# DevOS File / Artifact / Storage Runtime > Document: 15 > Status: Required > Audience: Zcode / DevOS Core Team > Depends On: > - 03_RESOURCE_ACTION_MODEL.md > - 06_MCP_SKILL_AGENT_RUNTIME.md > - 09_TASK_JOB_QUEUE_RUNTIME.md > - 12_MIGRATION_VERSIONING_COMPATIBILITY.md > - 13_DEPLOYMENT_ENVIRONMENT_CONFIG_RUNTIME.md > - 14_DATA_QUERY_SEARCH_INDEX_RUNTIME.md --- # 1. Goals DevOS 中会出现大量文件： - 用户上传文件 - 图片 - 视频 - PDF - CSV - Excel - Markdown - AI 生成内容 - SEO 文章 - Agent 输出 - Task 输出 - Job 日志 - Deployment 包 - Build 产物 - Backup - Import 文件 - Export 文件 - MCP 下载内容 - Plugin 资源 不能让每个 Plugin 自己处理： ```text 上传 下载 对象存储 文件权限 文件版本 临时 URL 文件预览 Hash 病毒扫描 生命周期 删除 备份 ```` 必须统一成为： ```text DevOS Storage Runtime ``` --- # 2. Core Principle DevOS 必须区分： ```text File Blob Artifact Attachment Storage Object ``` --- # 3. File File 表示： > 用户或系统可识别的文件对象。 例如： ```text logo.png article.md report.pdf backup.zip ``` File 是： ```text Metadata + Storage Reference ``` 而不是直接保存文件二进制。 --- # 4. Blob Blob 表示： > 实际二进制数据。 例如： ```text image bytes zip bytes pdf bytes ``` Blob 可以存在： ```text Local Disk S3 MinIO Cloudflare R2 Azure Blob GCS ``` --- # 5. Artifact Artifact 表示： > 某个 Task / Job / Action / Build / Deployment 产生的可追踪输出。 例如： ```text Task └── Artifact ├── report.pdf ├── data.csv └── result.json ``` Artifact 比 File 更强调： ```text 来源 版本 执行过程 生命周期 ``` --- # 6. Attachment Attachment 表示： > 一个 Resource / Task / Message / Agent Run 等对象关联的 File。 例如： ```text Task └── attachments ├── input.csv └── output.xlsx ``` --- # 7. Storage Object Storage Object 是底层存储抽象： ```text bucket key size etag contentType checksum ``` --- # 8. Architecture ```text DevOS File System │ ┌────────────┴────────────┐ │ │ File Artifact │ │ └────────────┬────────────┘ │ Storage Runtime │ Storage Provider │ ┌────────────────┼────────────────┐ │ │ │ Local S3 R2 Disk Compatible ``` --- # 9. Storage Runtime 统一接口： ```ts export interface StorageRuntime { put( input: PutObjectInput, context: StorageContext ): Promise get( input: GetObjectInput, context: StorageContext ): Promise delete( input: DeleteObjectInput, context: StorageContext ): Promise exists( input: ExistsObjectInput, context: StorageContext ): Promise stat( input: StatObjectInput, context: StorageContext ): Promise } ``` --- # 10. Storage Provider ```ts export interface StorageProvider { name: string put( input: PutObjectInput ): Promise get( input: GetObjectInput ): Promise delete( input: DeleteObjectInput ): Promise exists( input: ExistsObjectInput ): Promise stat( input: StatObjectInput ): Promise createPresignedUrl?( input: PresignedUrlInput ): Promise health(): Promise } ``` --- # 11. StorageContext 所有 Storage 操作必须有： ```ts export interface StorageContext { requestId: string actor: Actor organizationId?: string projectId?: string environmentId?: string permissions: string[] metadata?: Record } ``` 不能： ```text Plugin ↓ Storage Provider ``` 直接访问。 必须： ```text Plugin ↓ Storage Runtime ↓ Permission ↓ Storage Provider ``` --- # 12. File Resource File 是 DevOS Resource： ```text core.file ``` 建议字段： ```ts export interface FileRecord { id: string name: string originalName?: string mimeType: string extension?: string size: number checksum?: string checksumAlgorithm?: string storageProvider: string storageBucket?: string storageKey: string status: FileStatus ownerId?: string organizationId?: string projectId?: string createdAt: Date updatedAt: Date deletedAt?: Date } ``` --- # 13. File Status ```text pending uploading processing ready quarantined failed deleting deleted ``` --- # 14. File Lifecycle ```text Upload ↓ Pending ↓ Uploading ↓ Processing ↓ Security Scan ↓ Ready ``` 失败： ```text Processing ↓ Failed ``` 危险： ```text Processing ↓ Quarantined ``` --- # 15. Storage Key 禁止直接使用： ```text uploads/logo.png ``` 避免： ```text filename collision organization collision path traversal ``` 推荐： ```text {organizationId}/{resource}/{year}/{month}/{uuid} ``` 例如： ```text org_123/ core.file/ 2026/ 09/ file_abc123 ``` --- # 16. Never Trust Filename 用户上传： ```text ../../etc/passwd ``` 必须安全转换。 Storage Key 绝不能直接使用： ```text originalName ``` --- # 17. Original Filename Original filename 只作为： ```text metadata ``` 保存： ```text originalName ``` 真正 Storage Key： ```text UUID ``` --- # 18. MIME Type 客户端提供的： ```text Content-Type ``` 不能完全信任。 系统应： ```text extension check + content sniffing ``` 必要时验证： ```text magic bytes ``` --- # 19. File Validation 上传时必须验证： ```text mimeType extension size checksum filename ``` 可选： ```text image dimensions video duration PDF validity archive contents ``` --- # 20. Upload Policy 每个 Resource / Plugin 可以定义： ```ts export interface UploadPolicy { maxSizeBytes: number allowedMimeTypes?: string[] allowedExtensions?: string[] maxFiles?: number requireScan?: boolean requireChecksum?: boolean } ``` --- # 21. Default Limits 必须提供全局： ```text storage.maxFileSize storage.maxTotalUploadSize storage.maxFilesPerRequest ``` 不能无限制上传。 --- # 22. Chunked Upload 大文件必须支持： ```text Multipart Upload ``` 流程： ```text Create Upload ↓ Upload Parts ↓ Complete Upload ↓ Verify ↓ Process ``` --- # 23. Upload Session Resource： ```text core.uploadSession ``` ```ts export interface UploadSession { id: string filename: string size: number mimeType: string totalParts?: number uploadedParts: number status: | 'created' | 'uploading' | 'completed' | 'failed' | 'cancelled' expiresAt: Date } ``` --- # 24. Resumable Upload 如果网络断开： ```text Upload Part 1 Upload Part 2 Upload Part 3 ↓ Network Failure ↓ Resume ↓ Upload Part 4 ``` 不能重新上传整个文件。 --- # 25. Presigned URL 大文件： ```text Browser ↓ Presigned URL ↓ Object Storage ``` 不要： ```text Browser ↓ DevOS Backend ↓ Object Storage ``` 把所有大文件流量经过 API。 --- # 26. Presigned URL Security URL 必须： ```text short-lived scoped permission checked ``` 例如： ```text expires = 5 minutes ``` 不能生成： ```text permanent public URL ``` 除非明确配置。 --- # 27. Download Action 统一： ```text core.file.download ``` 执行： ```text Permission ↓ Scope ↓ File status ↓ Generate URL ``` --- # 28. Preview Action ```text core.file.preview ``` 支持： ```text image PDF text JSON CSV Markdown video audio ``` 具体能力由 Preview Provider 决定。 --- # 29. Preview Provider ```ts export interface PreviewProvider { supports( mimeType: string ): boolean preview( file: FileRecord ): Promise } ``` --- # 30. Preview Result ```ts export interface PreviewResult { type: | 'inline' | 'redirect' | 'generated' mimeType?: string url?: string content?: string pages?: number metadata?: Record } ``` --- # 31. Image Metadata 图片可提取： ```text width height format orientation ``` 可选： ```text EXIF ``` 但： ```text GPS ``` 等敏感元数据默认应该： ```text not exposed ``` --- # 32. File Processing 上传后： ```text File ↓ Processing Task ↓ Jobs ``` 处理： ```text Virus Scan Metadata Thumbnail Text Extraction OCR Embedding Indexing ``` --- # 33. File Processing Pipeline ```text Upload ↓ Verify ↓ Scan ↓ Metadata ↓ Preview ↓ Text Extraction ↓ Embedding ↓ Search Index ``` 不是所有文件都需要执行全部步骤。 --- # 34. Processing Capability ```ts export interface FileProcessor { id: string supports( file: FileRecord ): boolean process( file: FileRecord, context: ProcessingContext ): Promise } ``` --- # 35. Processor Types ```text security.scan metadata.extract thumbnail.generate text.extract ocr embedding.generate search.index ``` --- # 36. Virus Scanning 如果启用： ```text Upload ↓ Quarantine ↓ Security Scanner ↓ Clean / Infected ``` Infected： ```text quarantined ``` 禁止： ```text download preview agent access ``` 直到人工/系统处理。 --- # 37. Security Scanner Provider ```ts export interface SecurityScanner { scan( input: ScanInput ): Promise } ``` 可接： ```text ClamAV External Security Service ``` 但 Storage Runtime 不应该绑定具体实现。 --- # 38. Text Extraction 支持： ```text PDF DOCX TXT Markdown HTML CSV JSON ``` 输出： ```text ExtractedText ``` --- # 39. Extracted Text Resource： ```text core.fileText ``` ```ts export interface FileText { fileId: string text: string language?: string extractedAt: Date extractor: string version: string } ``` --- # 40. File Search 结合： ```text 14_DATA_QUERY_SEARCH_INDEX_RUNTIME.md ``` 文件内容可以进入： ```text Search Runtime ``` 例如： ```text 搜索： “Cloudflare production deployment” ``` 可以搜索： ```text PDF Markdown DOCX Task Output Reports ``` --- # 41. File Embedding 支持： ```text File ↓ Text Extraction ↓ Chunk ↓ Embedding ↓ Vector Index ``` 用于： ```text RAG Agent Knowledge Base Semantic Search ``` --- # 42. File Chunk ```ts export interface FileChunk { id: string fileId: string index: number text: string startOffset?: number endOffset?: number embedding?: number[] metadata?: Record } ``` --- # 43. Chunk Strategy 不要固定一种 Chunk。 支持： ```text token based character based paragraph based heading based semantic ``` 默认优先： ```text paragraph / heading aware ``` --- # 44. RAG Integration 最终： ```text User Question ↓ Search Runtime ↓ File Search ↓ Vector Search ↓ Top K Chunks ↓ Agent Context ``` 而不是： ```text Agent ↓ 读取整个 PDF ``` --- # 45. Artifact Resource ```text core.artifact ``` ```ts export interface Artifact { id: string name: string type: string fileId: string sourceType: | 'task' | 'job' | 'execution' | 'action' | 'agent' | 'build' | 'deployment' | 'plugin' | 'system' sourceId: string version: number metadata?: Record createdAt: Date } ``` --- # 46. Artifact Examples Task： ```text Generate SEO Report ``` Artifacts： ```text report.pdf websites.csv summary.json ``` --- # 47. Artifact Version 如果 Task 重新执行： ```text Artifact v1 Artifact v2 Artifact v3 ``` 而不是： ```text overwrite ``` 默认保留版本。 --- # 48. Artifact Versioning ```ts export interface ArtifactVersion { id: string artifactId: string version: number fileId: string executionId?: string checksum: string createdAt: Date } ``` --- # 49. Reproducibility Artifact 必须关联： ```text Task Job Execution Action Version Plugin Version Runtime Version ``` 结合： ```text 12_MIGRATION_VERSIONING_COMPATIBILITY.md ``` 这样： ```text Artifact ``` 可以回答： ```text 这个文件是谁生成的？ 用什么版本生成？ 什么时候生成？ 为什么生成？ ``` --- # 50. Artifact Provenance ```ts export interface ArtifactProvenance { sourceType: string sourceId: string executionId?: string actorId: string runtimeVersion: string pluginVersions?: Record actionVersion?: string createdAt: Date } ``` --- # 51. Artifact Lineage 例如： ```text Input CSV ↓ Import Task ↓ Normalized Data ↓ Analysis Task ↓ Report PDF ``` 系统应保存： ```text Artifact A ↓ Task ↓ Artifact B ``` --- # 52. Artifact Relation ```ts export interface ArtifactRelation { sourceArtifactId: string targetArtifactId: string relation: | 'derived_from' | 'generated_from' | 'converted_from' | 'aggregated_from' } ``` --- # 53. Agent Artifact Agent 产生文件： ```text Agent ↓ Task ↓ Action ↓ Artifact ``` Agent 不直接： ```text write /tmp/output.pdf ``` 然后告诉系统： ```text done ``` 必须注册： ```text Artifact ``` --- # 54. Agent File Access Agent 只能访问： ```text authorized File ``` 必须经过： ```text File Capability ``` --- # 55. Agent File Capabilities ```text core.file.list core.file.get core.file.search core.file.preview core.file.download core.artifact.list core.artifact.get ``` 写： ```text core.file.create core.artifact.create ``` 必须仍然经过： ```text Action Runtime ``` --- # 56. MCP File Access MCP： ```text MCP ↓ Capability ↓ File Runtime ``` 禁止： ```text MCP ↓ filesystem.readFile() ``` --- # 57. Local Filesystem DevOS 可以使用： ```text Local Storage Provider ``` 但 Local Provider 只能访问： ```text configured storage root ``` 例如： ```text /var/lib/devos/storage ``` 禁止： ```text / ``` 作为 Storage Root。 --- # 58. Path Traversal 必须防御： ```text ../ ..\ absolute paths symlink escape null bytes ``` Storage Key 必须规范化。 --- # 59. Storage Bucket Storage Provider 可以定义： ```text system private public temporary artifact backup ``` 例如： ```text devos-private devos-artifacts devos-temp ``` --- # 60. Bucket Policy ```ts export interface BucketPolicy { name: string public: boolean maxObjectSize?: number retentionDays?: number encryptionRequired?: boolean } ``` 默认： ```text private ``` --- # 61. Encryption 敏感文件支持： ```text Encryption At Rest ``` 推荐依赖： ```text Object Storage Encryption ``` 不要自己实现密码学。 --- # 62. Secret Files Secret 不应该使用普通： ```text core.file ``` 保存。 例如： ```text API Key Private Key Cloud Credential ``` 必须使用： ```text Secret Runtime ``` 见： ```text 13_DEPLOYMENT_ENVIRONMENT_CONFIG_RUNTIME.md ``` File Runtime 只保存： ```text reference ``` 如果必须上传： ```text encrypt + strict ACL + no preview + no indexing ``` --- # 63. Temporary Files Resource： ```text core.temporaryFile ``` 或内部 Storage Namespace： ```text temporary ``` 生命周期： ```text TTL ``` 例如： ```text 1 hour 24 hours 7 days ``` --- # 64. Temp File Cleanup Scheduler： ```text Scheduler ↓ Cleanup Task ↓ Job ↓ Worker ↓ Delete expired files ``` --- # 65. Artifact Retention 不同 Artifact 类型不同策略： ```text Build Artifact 30 days Deployment Artifact 90 days Task Report 180 days User Upload indefinite ``` 具体由： ```text Retention Policy ``` 决定。 --- # 66. Retention Policy ```ts export interface StorageRetentionPolicy { resource: string retentionDays?: number archiveAfterDays?: number deleteAfterDays?: number preserveIfReferenced?: boolean } ``` --- # 67. Reference Protection 如果： ```text Artifact ``` 仍被： ```text Task Document Deployment ``` 引用： 不能因为普通 TTL： ```text delete ``` 除非： ```text force ``` 且具备权限。 --- # 68. Garbage Collection Storage 中可能存在： ```text orphaned objects ``` 例如： ```text Upload failed DB transaction rollback ``` 需要： ```text Storage GC ``` 流程： ```text Scan Storage ↓ Compare DB ↓ Find Orphans ↓ Grace Period ↓ Delete ``` --- # 69. Garbage Collection Safety 发现 orphan 后： ```text 不要立即删除 ``` 默认： ```text grace period = 24h ``` 避免： ```text temporary inconsistency ``` --- # 70. Checksum 默认： ```text SHA-256 ``` 保存： ```ts checksum checksumAlgorithm ``` 用途： ```text duplicate detection integrity upload verification artifact reproducibility ``` --- # 71. Deduplication 相同： ```text checksum ``` 可以复用 Storage Object。 但是： ```text File ``` 仍然可以有不同 metadata。 即： ```text File A ─┐ ├── Blob X File B ─┘ ``` --- # 72. Deduplication Security Deduplication 不能导致： ```text Org A ``` 推断： ```text Org B ``` 存在相同文件。 因此： ```text cross-tenant dedup ``` 默认关闭。 --- # 73. File Copy 支持： ```text core.file.copy ``` 逻辑： ```text File A ↓ New File ↓ same Blob ``` 如果权限允许。 --- # 74. File Move 逻辑上： ```text File ↓ change logical namespace ``` 而不是： ```text download upload delete ``` --- # 75. File Rename ```text core.file.rename ``` 只修改： ```text name ``` 不需要重新上传 Blob。 --- # 76. File Delete 删除流程： ```text Action ↓ Permission ↓ Reference Check ↓ Soft Delete ↓ Async Physical Delete ``` 不要： ```text HTTP request ↓ delete object ``` 同步阻塞。 --- # 77. Hard Delete 必须是： ```text dangerous action ``` 需要： ```text requiresApproval ``` 的场景由 Resource Policy 决定。 --- # 78. File Events ```text core.file.created core.file.updated core.file.ready core.file.quarantined core.file.deleted core.file.restored ``` Artifact： ```text core.artifact.created core.artifact.version.created ``` --- # 79. Event Payload ```ts export interface FileEvent { fileId: string organizationId?: string operation: string version: number actorId: string timestamp: Date } ``` 不要在 Event 中： ```text embed binary ``` --- # 80. Storage Metrics 必须提供： ```text storage_bytes_total storage_files_total storage_upload_total storage_download_total storage_upload_bytes storage_download_bytes storage_errors_total storage_processing_total storage_quarantine_total storage_gc_total ``` --- # 81. Storage Health ```ts export interface StorageHealth { provider: string status: | 'healthy' | 'degraded' | 'unavailable' latencyMs?: number availableBytes?: number error?: string } ``` --- # 82. Storage Provider Registry ```ts export interface StorageProviderRegistry { register( provider: StorageProvider ): void get( name: string ): StorageProvider list(): StorageProvider[] } ``` --- # 83. Default Provider 开发： ```text local ``` 生产： ```text S3-compatible ``` 例如： ```text AWS S3 MinIO Cloudflare R2 ``` 但上层： ```text Storage Runtime ``` 不依赖具体厂商。 --- # 84. Provider Selection 可以按： ```text environment organization resource file type ``` 选择 Storage Provider。 例如： ```text production → S3 development → local ``` --- # 85. Storage Policy ```ts export interface StoragePolicy { defaultProvider: string providerByEnvironment?: Record maxFileSize: number allowedProviders?: string[] publicAccess: boolean } ``` --- # 86. Public Files 如果允许 Public： ```text File ↓ Public Policy ↓ Public URL ``` 必须明确： ```text public = true ``` 默认： ```text false ``` --- # 87. CDN 大文件 / Public Asset： ```text Browser ↓ CDN ↓ Object Storage ``` DevOS 只负责： ```text authorization metadata URL generation ``` --- # 88. Attachment API 统一： ```text POST /api/files/upload GET /api/files/:id GET /api/files/:id/download GET /api/files/:id/preview DELETE /api/files/:id ``` --- # 89. Artifact API ```text GET /api/artifacts GET /api/artifacts/:id GET /api/artifacts/:id/versions GET /api/artifacts/:id/download ``` --- # 90. Upload API 推荐： ```text POST /api/uploads POST /api/uploads/:id/parts POST /api/uploads/:id/complete POST /api/uploads/:id/cancel ``` 大文件优先： ```text Presigned Upload ``` --- # 91. Upload Flow ```text Client ↓ Create Upload Session ↓ DevOS Authorization ↓ Presigned URL ↓ Object Storage ↓ Complete ↓ DevOS Verify ↓ Processing Task ↓ File Ready ``` --- # 92. UI Upload Component DevOS 提供： ```text ``` 支持： ```text drag & drop multiple progress pause resume cancel retry preview validation ``` --- # 93. Artifact UI Task 页面： ```text Task ├── Overview ├── Jobs ├── Logs ├── Artifacts │ ├── report.pdf │ ├── data.csv │ └── result.json └── Timeline ``` --- # 94. File Detail UI ```text File ├── Preview ├── Metadata ├── Versions ├── Relations ├── Activity └── Download ``` --- # 95. File Permissions 建议： ```text file.read file.create file.update file.delete file.download file.preview file.export ``` Artifact： ```text artifact.read artifact.create artifact.delete artifact.download ``` --- # 96. Resource Scope File 默认继承： ```text Organization Project Resource Owner ``` 例如： ```text Task └── Artifact ``` Artifact 默认继承： ```text Task Scope ``` 不能因为拿到了： ```text artifactId ``` 就访问。 --- # 97. Signed URL Authorization 生成 URL 时： ```text Permission + Scope + File Status ``` 必须全部通过。 URL 生成后： ```text 短时间有效 ``` --- # 98. Artifact Download From Agent Agent： ```text Task ↓ Artifact ↓ Capability ↓ Temporary URL ``` 不要把： ```text permanent public URL ``` 放进 Agent Context。 --- # 99. File Search Integration ```text File ↓ Text Extraction ↓ Search Runtime ↓ Global Search ``` Global Search 可以显示： ```text PDF Article Task Deployment ``` 统一结果。 --- # 100. File to Resource Relation 例如： ```text seo.article └── coverImage → core.file ``` ```text core.task └── artifacts → core.artifact ``` ```text core.deployment └── package → core.artifact ``` --- # 101. Plugin File Extension Plugin 可以注册： ```ts export interface FileExtension { resource: string uploadPolicy?: UploadPolicy processors?: string[] previewProviders?: string[] metadata?: Record } ``` --- # 102. SEO Plugin Example SEO Plugin： ```text seo.article ├── coverImage ├── attachments └── generatedReport ``` 系统自动使用： ```text File Runtime Artifact Runtime Search Runtime ``` 无需 SEO Plugin 自己实现文件系统。 --- # 103. Deployment Example Deployment： ```text Build ↓ Artifact ↓ deployment.package ↓ Server ``` Artifact： ```text app.tar.gz ``` 必须记录： ```text commit build runtime plugin checksum ``` 这样可以： ```text rollback ``` --- # 104. Backup Example Backup： ```text Backup Task ↓ Job ↓ Artifact ``` Artifact： ```text backup-2026-09-11.tar.zst ``` 保留： ```text provenance checksum retention ``` --- # 105. Import Example 结合 Document 14： ```text User ↓ Upload CSV ↓ File ↓ Import Task ↓ Jobs ↓ Validate ↓ Import ``` 错误： ```text import-errors.csv ``` 作为： ```text Artifact ``` 返回给用户。 --- # 106. Export Example ```text Resource Query ↓ Export Task ↓ Cursor ↓ Worker ↓ CSV ↓ Artifact ``` 用户看到： ```text Export completed ↓ Download ``` --- # 107. AI Generated Content Agent： ```text Goal ↓ Generate Article ↓ Action ↓ Artifact ``` 例如： ```text article.md article.html seo-report.json ``` 这些必须是： ```text Artifacts ``` 而不是： ```text /tmp/xxx ``` --- # 108. Agent Working Files Agent 可以有： ```text Working Files ``` 但生命周期必须绑定： ```text AgentRun ``` 例如： ```text AgentRun └── workspace ``` Agent Run 结束后： ```text cleanup ``` 除非： ```text promoted to Artifact ``` --- # 109. Workspace 可以定义： ```text core.workspace ``` 用于： ```text Agent Build Task Plugin ``` 但 Workspace 仍然必须经过： ```text Storage Runtime ``` --- # 110. Workspace Lifecycle ```text created ↓ active ↓ idle ↓ expired ↓ cleanup ``` --- # 111. Workspace Quota 每个： ```text AgentRun Task Organization ``` 可以有： ```text storage quota ``` 例如： ```ts interface StorageQuota { maxBytes: number maxFiles: number maxSingleFileBytes: number } ``` --- # 112. Agent Budget Integration Agent Budget 增加： ```ts storageBytes?: number fileCount?: number uploadBytes?: number ``` 因此： ```text Agent ``` 不能无限产生： ```text 10GB ``` 文件。 --- # 113. Task Budget Integration Task 可以： ```text maxArtifactBytes maxArtifactCount ``` 超过： ```text budget_exceeded ``` Task 可以： ```text failed ``` 或： ```text partially_completed ``` --- # 114. File Concurrency Storage Provider 需要： ```text upload concurrency download concurrency processing concurrency ``` 特别是： ```text large files ``` 避免 Worker 被单个任务占满。 --- # 115. Large File Streaming 禁止： ```ts const buffer = await file.arrayBuffer() ``` 处理巨大文件。 必须支持： ```text stream ``` 例如： ```ts interface StreamSource { stream(): ReadableStream } ``` --- # 116. Streaming Copy 例如： ```text S3 ↓ S3 ``` 可以： ```text stream ``` 不必： ```text S3 ↓ RAM ↓ S3 ``` --- # 117. Memory Limits File processor 必须有： ```text maxMemory maxDuration maxOutputSize ``` 避免： ```text malicious archive huge decompression ``` 导致 Worker OOM。 --- # 118. Archive Safety ZIP/TAR 等处理必须防御： ```text Zip Bomb Path Traversal Symlink Escape Huge File Count Huge Uncompressed Size ``` --- # 119. Archive Extraction 默认： ```text disabled ``` 需要明确： ```text processor capability ``` 并且： ```text sandbox resource limit ``` --- # 120. File Conversion 支持： ```text PDF → Text DOCX → Text Markdown → HTML Image → Thumbnail CSV → JSON ``` 通过： ```text File Processor ``` 执行。 --- # 121. Conversion Artifact 转换后的结果： ```text source.pdf ↓ conversion ↓ source.txt ``` 必须： ```text new Artifact ``` 并记录： ```text derived_from ``` --- # 122. File Version vs Artifact Version 区别： ```text File Version ``` 表示： ```text 同一个逻辑文件的更新 ``` 而： ```text Artifact Version ``` 表示： ```text 同一个输出对象的不同生成版本 ``` 不能混为一谈。 --- # 123. File Version Example ```text article.md v1 v2 v3 ``` 用户编辑： ```text v3 ``` Artifact： ```text SEO Report v1 v2 ``` 每次 Task 重新生成。 --- # 124. Immutable Artifact 默认： ```text Artifact immutable ``` 如果需要修改： ```text create new version ``` 而不是： ```text overwrite ``` --- # 125. Immutable Deployment Artifact Deployment package： ```text app-build-123.tar.gz ``` 必须： ```text immutable ``` 这样： ```text Deployment ``` 才能可靠 rollback。 --- # 126. Artifact Promotion Artifact 可以： ```text temporary ↓ validated ↓ promoted ↓ production ``` 例如： ```text Build Artifact ↓ Test ↓ Production Artifact ``` Promotion 必须记录： ```text who when from to ``` --- # 127. Artifact Signature 未来支持： ```text artifact signature ``` 用于： ```text deployment supply chain verification ``` 接口预留： ```ts interface ArtifactSignature { algorithm: string keyId: string signature: string signedAt: Date } ``` 第一阶段不需要自行实现密码学。 --- # 128. Storage Audit 记录： ```text file.created file.read file.downloaded file.deleted artifact.created artifact.downloaded ``` 对于敏感文件： ```text read audit ``` 必须开启。 --- # 129. Data / File Separation Document 14： ```text Data Runtime ``` 负责： ```text metadata query search relations ``` Document 15： ```text Storage Runtime ``` 负责： ```text binary blob upload download artifact ``` 不要把 Blob： ```text 直接塞 PostgreSQL ``` 除非明确的小文件场景。 --- # 130. Database Storage 默认： ```text PostgreSQL ``` 保存： ```text File Metadata Artifact Metadata Upload Session File Relations Retention Policy ``` 对象存储保存： ```text Blob ``` --- # 131. Recommended Architecture ```text PostgreSQL ├── core.file ├── core.artifact ├── core.artifact_version ├── core.upload_session ├── core.file_text └── core.file_relation Object Storage ├── private ├── artifact ├── temporary └── backup ``` --- # 132. Storage Database Schema 建议至少： ```text files artifacts artifact_versions upload_sessions file_relations file_processing_jobs storage_objects ``` --- # 133. storage_objects ```ts interface StorageObjectRecord { id: string provider: string bucket: string key: string size: number checksum?: string etag?: string contentType?: string createdAt: Date } ``` --- # 134. File → Storage Object ```text File ↓ StorageObject ↓ Provider ↓ Blob ``` 允许未来： ```text File ``` 重新绑定新的： ```text StorageObject ``` 而不修改 File ID。 --- # 135. Storage Migration Provider 切换： ```text S3 ↓ R2 ``` 流程： ```text Migration Task ↓ Read Storage Object ↓ Copy ↓ Verify checksum ↓ Update metadata ↓ Delete old object ``` 必须支持： ```text resume retry checkpoint ``` --- # 136. Storage Replication 未来支持： ```text Primary + Replica ``` 例如： ```text S3 ↓ Backup S3 ``` Artifact 可以配置： ```text replication policy ``` --- # 137. Storage Disaster Recovery 必须考虑： ```text DB lost Object Storage lost DB/Object inconsistent ``` 恢复顺序： ```text Database ↓ Storage ↓ Reconcile ↓ Index ``` --- # 138. Reconciliation 提供： ```text core.storage.reconcile ``` 检查： ```text DB File exists Storage Object exists Checksum matches Artifact reference valid ``` 发现异常： ```text orphan missing corrupt ``` --- # 139. Reconciliation Task ```text Storage Reconcile ↓ Task ↓ Jobs ↓ Worker ↓ Report Artifact ``` 例如： ```text 100000 objects 99000 valid 800 orphan 200 missing ``` 输出： ```text reconcile-report.json ``` --- # 140. Storage CLI ```bash devos storage providers devos storage health devos storage files devos storage objects devos storage reconcile devos storage gc devos storage migrate devos storage usage ``` Artifact： ```bash devos artifact list devos artifact get devos artifact versions ``` --- # 141. Storage UI Settings： ```text System └── Storage ├── Providers ├── Buckets ├── Usage ├── Health ├── Policies └── Cleanup ``` --- # 142. Organization Storage Usage Dashboard： ```text Storage ├── Files ├── Artifacts ├── Temporary ├── Backups └── Total ``` 按： ```text Organization Project Plugin Resource ``` 统计。 --- # 143. Plugin Storage Usage Plugin 可以查看： ```text SEO Plugin ├── 20GB ├── 12000 files └── 800 artifacts ``` 但必须只能看到： ```text plugin-owned data ``` --- # 144. Storage Capability Registry Storage 相关能力： ```text core.file.upload core.file.download core.file.preview core.file.search core.file.delete core.artifact.create core.artifact.list core.artifact.download core.storage.health core.storage.reconcile core.storage.gc ``` 全部进入： ```text Capability Registry ``` --- # 145. MCP Exposure MCP 可以使用： ```text file.search file.get artifact.list artifact.get ``` 但： ```text file.download file.delete ``` 属于更高风险 Capability。 必须经过： ```text Policy Permission Budget Approval ``` --- # 146. Agent File Search Example Goal： ```text “找到之前生成的 SEO 报告” ``` Agent： ```text Goal ↓ Capability Discovery ↓ core.file.search ↓ Search Runtime ↓ Permission ↓ Results ↓ core.artifact.get ``` 而不是： ```text Agent ↓ filesystem scan ``` --- # 147. Agent Artifact Example Goal： ```text “把本次分析结果导出为 PDF” ``` 流程： ```text Agent ↓ Plan ↓ Task ↓ Generate Report Action ↓ Artifact ↓ Task Completed ``` 最终： ```text Artifact ID ``` 进入： ```text Agent Result ``` --- # 148. Plugin Example Plugin 只需要： ```ts defineResource({ resource: 'seo.report' }) ``` 并声明： ```text attachment field ``` DevOS 自动提供： ```text upload preview download search artifact retention permission ``` --- # 149. UI Extension Plugin 可以声明： ```ts interface FileWidgetExtension { resource: string placement: | 'overview' | 'attachments' | 'artifacts' component: string } ``` 例如： ```text SEO Article └── Attachments ├── Cover ├── Images └── Research PDF ``` --- # 150. Package Structure ```text packages/storage/ ├── storage-runtime.ts ├── storage-context.ts ├── storage-provider.ts ├── storage-policy.ts ├── storage-registry.ts ├── providers/ │ ├── local/ │ ├── s3/ │ └── r2/ └── index.ts ``` --- # 151. File Package ```text packages/file/ ├── file-service.ts ├── file-resource.ts ├── upload/ ├── download/ ├── preview/ ├── processing/ ├── lifecycle/ ├── permissions/ └── index.ts ``` --- # 152. Artifact Package ```text packages/artifact/ ├── artifact-service.ts ├── artifact-resource.ts ├── versioning.ts ├── provenance.ts ├── lineage.ts ├── retention.ts └── index.ts ``` --- # 153. Processing Package ```text packages/file-processing/ ├── processor.ts ├── processor-registry.ts ├── pipeline.ts ├── security/ ├── metadata/ ├── preview/ ├── extraction/ ├── embedding/ └── index.ts ``` --- # 154. Workspace Package ```text packages/workspace/ ├── workspace-runtime.ts ├── workspace-policy.ts ├── quota.ts ├── lifecycle.ts └── index.ts ``` --- # 155. Acceptance Criteria ## Storage ```text [ ] Storage Runtime [ ] Storage Provider [ ] Local Provider [ ] S3-compatible Provider [ ] Provider Registry [ ] Presigned URL [ ] Streaming [ ] Checksum ``` ## File ```text [ ] File Resource [ ] Upload [ ] Chunked Upload [ ] Resume [ ] Download [ ] Preview [ ] File Permissions [ ] File Lifecycle [ ] File Search ``` ## Artifact ```text [ ] Artifact Resource [ ] Artifact Version [ ] Provenance [ ] Lineage [ ] Immutable Artifact [ ] Artifact Download [ ] Artifact Retention ``` ## Processing ```text [ ] Processing Pipeline [ ] Metadata [ ] Text Extraction [ ] Thumbnail [ ] Security Scan [ ] Embedding [ ] Search Index ``` ## Reliability ```text [ ] Retry [ ] Checkpoint [ ] Reconciliation [ ] Garbage Collection [ ] Storage Migration [ ] Health Check ``` --- # 156. Security Tests 必须测试： ```text User A cannot access User B file Org A cannot access Org B file Expired signed URL fails Quarantined file cannot download Quarantined file cannot preview Forbidden file cannot search Forbidden file cannot be indexed into accessible scope Path traversal blocked Absolute path blocked Symlink escape blocked Oversized upload rejected Invalid MIME rejected Archive bomb rejected Expired temporary file cleaned ``` --- # 157. Upload Tests 测试： ```text small file upload large file upload multipart upload resume cancel retry checksum mismatch duplicate upload provider failure network interruption ``` --- # 158. Artifact Tests 测试： ```text artifact creation artifact version artifact provenance artifact lineage artifact immutability artifact retention artifact download artifact permission artifact rollback ``` --- # 159. Agent Tests 测试： ```text Agent can search authorized files Agent cannot access unauthorized files Agent cannot read quarantined files Agent can create Artifact Agent Artifact has provenance Agent respects storage budget Agent working files are cleaned Artifact survives AgentRun cleanup ``` --- # 160. MCP Tests 测试： ```text MCP file search MCP file get MCP artifact get MCP permission MCP scope MCP signed URL expiry MCP cannot access filesystem ``` --- # 161. Plugin Tests 安装 Plugin： ```text Plugin ↓ Resource ↓ File Attachment ↓ Upload ↓ Preview ↓ Search ↓ Artifact ``` 全部应该自动进入： ```text DevOS Runtime ``` --- # 162. Performance Tests 必须测试： ```text 100MB upload 1GB upload 10GB artifact 100k files 1M files large directory large search index large artifact list ``` 重点： ```text RAM usage CPU network database query provider latency ``` --- # 163. Zcode Implementation Rules ## Rule 1 所有文件二进制操作： ```text 必须经过 Storage Runtime ``` --- ## Rule 2 禁止： ```text UI Plugin Agent MCP Action Controller ``` 直接： ```text fs.readFile fs.writeFile S3 SDK ``` 访问业务文件。 --- ## Rule 3 业务文件 Metadata： ```text PostgreSQL ``` 文件 Blob： ```text Object Storage ``` 默认分离。 --- ## Rule 4 Artifact 必须可追踪： ```text Task Job Execution Action Version Plugin Version Runtime Version ``` --- ## Rule 5 Artifact 默认： ```text Immutable ``` 修改必须产生： ```text New Version ``` --- ## Rule 6 大文件必须： ```text Streaming Multipart Presigned URL ``` --- ## Rule 7 文件权限必须在： ```text URL Generation Preview Download Search MCP Agent ``` 全部生效。 --- ## Rule 8 Storage Index / Cache / Metadata： ```text 都不是 Blob Source of Truth ``` --- ## Rule 9 文件生命周期必须： ```text Task + Job + Worker + Scheduler ``` 执行。 --- ## Rule 10 Storage Provider 必须可替换。 禁止业务代码依赖： ```text S3 SDK MinIO SDK R2 SDK ``` --- # 164. Golden Rule DevOS 文件体系必须遵循： ```text File ↓ File Metadata ↓ Storage Runtime ↓ Storage Provider ↓ Blob ``` Task 产物： ```text Task ↓ Job ↓ Execution ↓ Artifact ↓ Artifact Version ↓ File ↓ Storage Object ↓ Blob ``` 文件处理： ```text File ↓ Processing Task ↓ Processor ├── Security Scan ├── Metadata ├── Preview ├── Text Extraction ├── Embedding └── Search Index ``` 最终形成： ```text DevOS File System │ ┌─────────────────┼─────────────────┐ │ │ │ File Artifact Workspace │ │ │ └─────────────────┼─────────────────┘ │ Storage Runtime │ ┌───────────┴───────────┐ │ │ Metadata Blob │ │ PostgreSQL Object Storage │ │ └───────────┬───────────┘ │ Processing Runtime │ ┌─────────────────┼─────────────────┐ │ │ │ Preview Extract Embedding │ │ │ └─────────────────┼─────────────────┘ │ Search Runtime │ Global Search │ ┌───────────┴───────────┐ │ │ User Agent │ │ MCP Plugin ``` --- # 165. Final Principle DevOS 不应该让 Plugin 自己实现： ```text Upload Download File Storage S3 Preview Artifact File Search File Permission File Lifecycle ``` 而应该： ```text DevOS Core └── Storage Runtime ├── File ├── Artifact ├── Workspace ├── Upload ├── Preview ├── Processing ├── Search └── Lifecycle ``` Plugin 只定义： ```text Resource + Attachment + Artifact Type + Processing Requirement ``` DevOS 自动提供基础设施。 最终目标： ```text Plugin = Business Capability DevOS = Data + Action + Agent + Task + Storage + Runtime ``` 而不是： ```text Plugin = 一个自己带数据库、文件系统、队列、Agent、搜索系统的小型应用 ``` 这才是 DevOS 可以长期复用、扩展和 Fork 的基础。