Files

T

phptits b1f17cf637 v2 platform foundation (docs 01/02/03): Action Runtime + Registry + unified API

- v2 foundation: ActionResult/DevError/ActorContext/ResourceRef/Execution types
- ActionRegistry + ResourceRegistry (namespaced types, FAIL FAST on duplicates)
- ActionRuntime pipeline: validate -> authorize -> middleware -> handler ->
  output validation -> audit -> event -> execution persisted (devos_action_executions)
- Legacy bridge: v1 services registered as devops.*/core.* resources & actions (47 actions, 9 resources)
- Unified Action API: POST /api/v2/actions/:actionId, GET discovery (actions/resources)
- 10 v2 unit tests (registry fail-fast, validation, authz, failure audit, events)

2026-09-10 21:09:44 +00:00

47 KiB

Raw Permalink Blame History

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 自己处理：

上传
下载
对象存储
文件权限
文件版本
临时 URL
文件预览
Hash
病毒扫描
生命周期
删除
备份

必须统一成为：

DevOS Storage Runtime

2. Core Principle

DevOS 必须区分：

File
Blob
Artifact
Attachment
Storage Object

3. File

File 表示：

用户或系统可识别的文件对象。

例如：

logo.png
article.md
report.pdf
backup.zip

File 是：

Metadata
+
Storage Reference

而不是直接保存文件二进制。

4. Blob

Blob 表示：

实际二进制数据。

例如：

image bytes
zip bytes
pdf bytes

Blob 可以存在：

Local Disk
S3
MinIO
Cloudflare R2
Azure Blob
GCS

5. Artifact

Artifact 表示：

某个 Task / Job / Action / Build / Deployment 产生的可追踪输出。

例如：

Task
 └── Artifact
      ├── report.pdf
      ├── data.csv
      └── result.json

Artifact 比 File 更强调：

来源
版本
执行过程
生命周期

6. Attachment

Attachment 表示：

一个 Resource / Task / Message / Agent Run 等对象关联的 File。

例如：

Task
 └── attachments
      ├── input.csv
      └── output.xlsx

7. Storage Object

Storage Object 是底层存储抽象：

bucket
key
size
etag
contentType
checksum

8. Architecture

                    DevOS File System
                           │
              ┌────────────┴────────────┐
              │                         │
             File                    Artifact
              │                         │
              └────────────┬────────────┘
                           │
                     Storage Runtime
                           │
                    Storage Provider
                           │
          ┌────────────────┼────────────────┐
          │                │                │
        Local             S3              R2
        Disk            Compatible

9. Storage Runtime

统一接口：

export interface StorageRuntime {
  put(
    input: PutObjectInput,
    context: StorageContext
  ): Promise<StorageObject>

  get(
    input: GetObjectInput,
    context: StorageContext
  ): Promise<StorageObject>

  delete(
    input: DeleteObjectInput,
    context: StorageContext
  ): Promise<void>

  exists(
    input: ExistsObjectInput,
    context: StorageContext
  ): Promise<boolean>

  stat(
    input: StatObjectInput,
    context: StorageContext
  ): Promise<StorageObjectMetadata>
}

10. Storage Provider

export interface StorageProvider {
  name: string

  put(
    input: PutObjectInput
  ): Promise<StorageObjectMetadata>

  get(
    input: GetObjectInput
  ): Promise<ReadableStream | Buffer>

  delete(
    input: DeleteObjectInput
  ): Promise<void>

  exists(
    input: ExistsObjectInput
  ): Promise<boolean>

  stat(
    input: StatObjectInput
  ): Promise<StorageObjectMetadata>

  createPresignedUrl?(
    input: PresignedUrlInput
  ): Promise<string>

  health(): Promise<HealthResult>
}

11. StorageContext

所有 Storage 操作必须有：

export interface StorageContext {
  requestId: string

  actor: Actor

  organizationId?: string

  projectId?: string

  environmentId?: string

  permissions: string[]

  metadata?: Record<string, unknown>
}

不能：

Plugin
 ↓
Storage Provider

直接访问。

必须：

Plugin
 ↓
Storage Runtime
 ↓
Permission
 ↓
Storage Provider

12. File Resource

File 是 DevOS Resource：

core.file

建议字段：

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

pending
uploading
processing
ready
quarantined
failed
deleting
deleted

14. File Lifecycle

Upload
  ↓
Pending
  ↓
Uploading
  ↓
Processing
  ↓
Security Scan
  ↓
Ready

失败：

Processing
  ↓
Failed

危险：

Processing
  ↓
Quarantined

15. Storage Key

禁止直接使用：

uploads/logo.png

避免：

filename collision
organization collision
path traversal

16. Never Trust Filename

用户上传：

../../etc/passwd

必须安全转换。

Storage Key 绝不能直接使用：

originalName

17. Original Filename

Original filename 只作为：

metadata

保存：

originalName

真正 Storage Key：

UUID

18. MIME Type

客户端提供的：

Content-Type

不能完全信任。

系统应：

extension check
+
content sniffing

必要时验证：

magic bytes

19. File Validation

上传时必须验证：

mimeType
extension
size
checksum
filename

可选：

image dimensions
video duration
PDF validity
archive contents

20. Upload Policy

每个 Resource / Plugin 可以定义：

export interface UploadPolicy {
  maxSizeBytes: number

  allowedMimeTypes?: string[]

  allowedExtensions?: string[]

  maxFiles?: number

  requireScan?: boolean

  requireChecksum?: boolean
}

21. Default Limits

必须提供全局：

storage.maxFileSize
storage.maxTotalUploadSize
storage.maxFilesPerRequest

不能无限制上传。

22. Chunked Upload

大文件必须支持：

Multipart Upload

流程：

Create Upload
 ↓
Upload Parts
 ↓
Complete Upload
 ↓
Verify
 ↓
Process

23. Upload Session

Resource：

core.uploadSession

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

如果网络断开：

Upload Part 1
Upload Part 2
Upload Part 3
↓
Network Failure
↓
Resume
↓
Upload Part 4

不能重新上传整个文件。

25. Presigned URL

大文件：

Browser
 ↓
Presigned URL
 ↓
Object Storage

不要：

Browser
 ↓
DevOS Backend
 ↓
Object Storage

把所有大文件流量经过 API。

26. Presigned URL Security

URL 必须：

short-lived
scoped
permission checked

例如：

expires = 5 minutes

不能生成：

permanent public URL

除非明确配置。

27. Download Action

统一：

core.file.download

执行：

Permission
 ↓
Scope
 ↓
File status
 ↓
Generate URL

28. Preview Action

core.file.preview

支持：

image
PDF
text
JSON
CSV
Markdown
video
audio

具体能力由 Preview Provider 决定。

29. Preview Provider

export interface PreviewProvider {
  supports(
    mimeType: string
  ): boolean

  preview(
    file: FileRecord
  ): Promise<PreviewResult>
}

30. Preview Result

export interface PreviewResult {
  type:
    | 'inline'
    | 'redirect'
    | 'generated'

  mimeType?: string

  url?: string

  content?: string

  pages?: number

  metadata?: Record<string, unknown>
}

31. Image Metadata

图片可提取：

width
height
format
orientation

可选：

EXIF

但：

GPS

等敏感元数据默认应该：

not exposed

32. File Processing

上传后：

File
 ↓
Processing Task
 ↓
Jobs

处理：

Virus Scan
Metadata
Thumbnail
Text Extraction
OCR
Embedding
Indexing

33. File Processing Pipeline

Upload
 ↓
Verify
 ↓
Scan
 ↓
Metadata
 ↓
Preview
 ↓
Text Extraction
 ↓
Embedding
 ↓
Search Index

不是所有文件都需要执行全部步骤。

34. Processing Capability

export interface FileProcessor {
  id: string

  supports(
    file: FileRecord
  ): boolean

  process(
    file: FileRecord,
    context: ProcessingContext
  ): Promise<ProcessingResult>
}

35. Processor Types

security.scan
metadata.extract
thumbnail.generate
text.extract
ocr
embedding.generate
search.index

36. Virus Scanning

如果启用：

Upload
 ↓
Quarantine
 ↓
Security Scanner
 ↓
Clean / Infected

Infected：

quarantined

禁止：

download
preview
agent access

直到人工/系统处理。

37. Security Scanner Provider

export interface SecurityScanner {
  scan(
    input: ScanInput
  ): Promise<ScanResult>
}

可接：

ClamAV
External Security Service

但 Storage Runtime 不应该绑定具体实现。

38. Text Extraction

支持：

PDF
DOCX
TXT
Markdown
HTML
CSV
JSON

输出：

ExtractedText

39. Extracted Text

Resource：

core.fileText

export interface FileText {
  fileId: string

  text: string

  language?: string

  extractedAt: Date

  extractor: string

  version: string
}

40. File Search

结合：

14_DATA_QUERY_SEARCH_INDEX_RUNTIME.md

文件内容可以进入：

Search Runtime

例如：

搜索：
“Cloudflare production deployment”

可以搜索：

PDF
Markdown
DOCX
Task Output
Reports

41. File Embedding

支持：

File
 ↓
Text Extraction
 ↓
Chunk
 ↓
Embedding
 ↓
Vector Index

用于：

RAG
Agent
Knowledge Base
Semantic Search

42. File Chunk

export interface FileChunk {
  id: string

  fileId: string

  index: number

  text: string

  startOffset?: number

  endOffset?: number

  embedding?: number[]

  metadata?: Record<string, unknown>
}

43. Chunk Strategy

不要固定一种 Chunk。

支持：

token based
character based
paragraph based
heading based
semantic

默认优先：

paragraph / heading aware

44. RAG Integration

最终：

User Question
 ↓
Search Runtime
 ↓
File Search
 ↓
Vector Search
 ↓
Top K Chunks
 ↓
Agent Context

而不是：

Agent
 ↓
读取整个 PDF

45. Artifact Resource

core.artifact

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<string, unknown>

  createdAt: Date
}

46. Artifact Examples

Task：

Generate SEO Report

Artifacts：

report.pdf
websites.csv
summary.json

47. Artifact Version

如果 Task 重新执行：

Artifact v1
Artifact v2
Artifact v3

而不是：

overwrite

默认保留版本。

48. Artifact Versioning

export interface ArtifactVersion {
  id: string

  artifactId: string

  version: number

  fileId: string

  executionId?: string

  checksum: string

  createdAt: Date
}

49. Reproducibility

Artifact 必须关联：

Task
Job
Execution
Action Version
Plugin Version
Runtime Version

结合：

12_MIGRATION_VERSIONING_COMPATIBILITY.md

这样：

Artifact

可以回答：

这个文件是谁生成的？
用什么版本生成？
什么时候生成？
为什么生成？

50. Artifact Provenance

export interface ArtifactProvenance {
  sourceType: string

  sourceId: string

  executionId?: string

  actorId: string

  runtimeVersion: string

  pluginVersions?: Record<string, string>

  actionVersion?: string

  createdAt: Date
}

51. Artifact Lineage

例如：

Input CSV
   ↓
Import Task
   ↓
Normalized Data
   ↓
Analysis Task
   ↓
Report PDF

系统应保存：

Artifact A
 ↓
Task
 ↓
Artifact B

52. Artifact Relation

export interface ArtifactRelation {
  sourceArtifactId: string

  targetArtifactId: string

  relation:
    | 'derived_from'
    | 'generated_from'
    | 'converted_from'
    | 'aggregated_from'
}

53. Agent Artifact

Agent 产生文件：

Agent
 ↓
Task
 ↓
Action
 ↓
Artifact

Agent 不直接：

write /tmp/output.pdf

然后告诉系统：

done

必须注册：

Artifact

54. Agent File Access

Agent 只能访问：

authorized File

必须经过：

File Capability

55. Agent File Capabilities

core.file.list
core.file.get
core.file.search
core.file.preview
core.file.download
core.artifact.list
core.artifact.get

写：

core.file.create
core.artifact.create

必须仍然经过：

Action Runtime

56. MCP File Access

MCP：

MCP
 ↓
Capability
 ↓
File Runtime

禁止：

MCP
 ↓
filesystem.readFile()

57. Local Filesystem

DevOS 可以使用：

Local Storage Provider

但 Local Provider 只能访问：

configured storage root

例如：

/var/lib/devos/storage

禁止：

作为 Storage Root。

58. Path Traversal

必须防御：

../
..\ 
absolute paths
symlink escape
null bytes

Storage Key 必须规范化。

59. Storage Bucket

Storage Provider 可以定义：

system
private
public
temporary
artifact
backup

例如：

devos-private
devos-artifacts
devos-temp

60. Bucket Policy

export interface BucketPolicy {
  name: string

  public: boolean

  maxObjectSize?: number

  retentionDays?: number

  encryptionRequired?: boolean
}

默认：

private

61. Encryption

敏感文件支持：

Encryption At Rest

推荐依赖：

Object Storage Encryption

不要自己实现密码学。

62. Secret Files

Secret 不应该使用普通：

core.file

保存。

例如：

API Key
Private Key
Cloud Credential

必须使用：

Secret Runtime

见：

13_DEPLOYMENT_ENVIRONMENT_CONFIG_RUNTIME.md

File Runtime 只保存：

reference

如果必须上传：

encrypt
+
strict ACL
+
no preview
+
no indexing

63. Temporary Files

Resource：

core.temporaryFile

或内部 Storage Namespace：

temporary

生命周期：

TTL

例如：

1 hour
24 hours
7 days

64. Temp File Cleanup

Scheduler：

Scheduler
 ↓
Cleanup Task
 ↓
Job
 ↓
Worker
 ↓
Delete expired files

65. Artifact Retention

不同 Artifact 类型不同策略：

Build Artifact
30 days

Deployment Artifact
90 days

Task Report
180 days

User Upload
indefinite

具体由：

Retention Policy

决定。

66. Retention Policy

export interface StorageRetentionPolicy {
  resource: string

  retentionDays?: number

  archiveAfterDays?: number

  deleteAfterDays?: number

  preserveIfReferenced?: boolean
}

67. Reference Protection

如果：

Artifact

仍被：

Task
Document
Deployment

引用：

不能因为普通 TTL：

delete

除非：

force

且具备权限。

68. Garbage Collection

Storage 中可能存在：

orphaned objects

例如：

Upload failed
DB transaction rollback

需要：

Storage GC

流程：

Scan Storage
 ↓
Compare DB
 ↓
Find Orphans
 ↓
Grace Period
 ↓
Delete

69. Garbage Collection Safety

发现 orphan 后：

不要立即删除

默认：

grace period = 24h

避免：

temporary inconsistency

70. Checksum

默认：

SHA-256

保存：

checksum
checksumAlgorithm

用途：

duplicate detection
integrity
upload verification
artifact reproducibility

71. Deduplication

相同：

checksum

可以复用 Storage Object。

但是：

File

仍然可以有不同 metadata。

即：

File A ─┐
        ├── Blob X
File B ─┘

72. Deduplication Security

Deduplication 不能导致：

Org A

推断：

Org B

存在相同文件。

因此：

cross-tenant dedup

默认关闭。

73. File Copy

支持：

core.file.copy

逻辑：

File A
 ↓
New File
 ↓
same Blob

如果权限允许。

74. File Move

逻辑上：

File
 ↓
change logical namespace

而不是：

download
upload
delete

75. File Rename

core.file.rename

只修改：

name

不需要重新上传 Blob。

76. File Delete

删除流程：

Action
 ↓
Permission
 ↓
Reference Check
 ↓
Soft Delete
 ↓
Async Physical Delete

不要：

HTTP request
 ↓
delete object

同步阻塞。

77. Hard Delete

必须是：

dangerous action

需要：

requiresApproval

的场景由 Resource Policy 决定。

78. File Events

core.file.created
core.file.updated
core.file.ready
core.file.quarantined
core.file.deleted
core.file.restored

Artifact：

core.artifact.created
core.artifact.version.created

79. Event Payload

export interface FileEvent {
  fileId: string

  organizationId?: string

  operation: string

  version: number

  actorId: string

  timestamp: Date
}

不要在 Event 中：

embed binary

80. Storage Metrics

必须提供：

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

export interface StorageHealth {
  provider: string

  status:
    | 'healthy'
    | 'degraded'
    | 'unavailable'

  latencyMs?: number

  availableBytes?: number

  error?: string
}

82. Storage Provider Registry

export interface StorageProviderRegistry {
  register(
    provider: StorageProvider
  ): void

  get(
    name: string
  ): StorageProvider

  list(): StorageProvider[]
}

83. Default Provider

开发：

local

生产：

S3-compatible

例如：

AWS S3
MinIO
Cloudflare R2

但上层：

Storage Runtime

不依赖具体厂商。

84. Provider Selection

可以按：

environment
organization
resource
file type

选择 Storage Provider。

例如：

production
 → S3

development
 → local

85. Storage Policy

export interface StoragePolicy {
  defaultProvider: string

  providerByEnvironment?: Record<string, string>

  maxFileSize: number

  allowedProviders?: string[]

  publicAccess: boolean
}

86. Public Files

如果允许 Public：

File
 ↓
Public Policy
 ↓
Public URL

必须明确：

public = true

默认：

false

87. CDN

大文件 / Public Asset：

Browser
 ↓
CDN
 ↓
Object Storage

DevOS 只负责：

authorization
metadata
URL generation

88. Attachment API

统一：

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

GET /api/artifacts
GET /api/artifacts/:id
GET /api/artifacts/:id/versions
GET /api/artifacts/:id/download

90. Upload API

91. Upload Flow

Client
 ↓
Create Upload Session
 ↓
DevOS Authorization
 ↓
Presigned URL
 ↓
Object Storage
 ↓
Complete
 ↓
DevOS Verify
 ↓
Processing Task
 ↓
File Ready

92. UI Upload Component

DevOS 提供：

<DevosUpload />

支持：

drag & drop
multiple
progress
pause
resume
cancel
retry
preview
validation

93. Artifact UI

Task 页面：

Task
 ├── Overview
 ├── Jobs
 ├── Logs
 ├── Artifacts
 │    ├── report.pdf
 │    ├── data.csv
 │    └── result.json
 └── Timeline

94. File Detail UI

File
 ├── Preview
 ├── Metadata
 ├── Versions
 ├── Relations
 ├── Activity
 └── Download

95. File Permissions

建议：

file.read
file.create
file.update
file.delete
file.download
file.preview
file.export

Artifact：

artifact.read
artifact.create
artifact.delete
artifact.download

96. Resource Scope

File 默认继承：

Organization
Project
Resource Owner

例如：

Task
 └── Artifact

Artifact 默认继承：

Task Scope

不能因为拿到了：

artifactId

就访问。

97. Signed URL Authorization

生成 URL 时：

Permission
+
Scope
+
File Status

必须全部通过。

URL 生成后：

短时间有效

98. Artifact Download From Agent

Agent：

Task
 ↓
Artifact
 ↓
Capability
 ↓
Temporary URL

不要把：

permanent public URL

放进 Agent Context。

99. File Search Integration

File
 ↓
Text Extraction
 ↓
Search Runtime
 ↓
Global Search

Global Search 可以显示：

PDF
Article
Task
Deployment

统一结果。

100. File to Resource Relation

例如：

seo.article
 └── coverImage → core.file

core.task
 └── artifacts → core.artifact

core.deployment
 └── package → core.artifact

101. Plugin File Extension

Plugin 可以注册：

export interface FileExtension {
  resource: string

  uploadPolicy?: UploadPolicy

  processors?: string[]

  previewProviders?: string[]

  metadata?: Record<string, unknown>
}

102. SEO Plugin Example

SEO Plugin：

seo.article
 ├── coverImage
 ├── attachments
 └── generatedReport

系统自动使用：

File Runtime
Artifact Runtime
Search Runtime

无需 SEO Plugin 自己实现文件系统。

103. Deployment Example

Deployment：

Build
 ↓
Artifact
 ↓
deployment.package
 ↓
Server

Artifact：

app.tar.gz

必须记录：

commit
build
runtime
plugin
checksum

这样可以：

rollback

104. Backup Example

Backup：

Backup Task
 ↓
Job
 ↓
Artifact

Artifact：

backup-2026-09-11.tar.zst

保留：

provenance
checksum
retention

105. Import Example

结合 Document 14：

User
 ↓
Upload CSV
 ↓
File
 ↓
Import Task
 ↓
Jobs
 ↓
Validate
 ↓
Import

错误：

import-errors.csv

作为：

Artifact

返回给用户。

106. Export Example

Resource Query
 ↓
Export Task
 ↓
Cursor
 ↓
Worker
 ↓
CSV
 ↓
Artifact

用户看到：

Export completed
 ↓
Download

107. AI Generated Content

Agent：

Goal
 ↓
Generate Article
 ↓
Action
 ↓
Artifact

例如：

article.md
article.html
seo-report.json

这些必须是：

Artifacts

而不是：

/tmp/xxx

108. Agent Working Files

Agent 可以有：

Working Files

但生命周期必须绑定：

AgentRun

例如：

AgentRun
 └── workspace

Agent Run 结束后：

cleanup

除非：

promoted to Artifact

109. Workspace

可以定义：

core.workspace

用于：

Agent
Build
Task
Plugin

但 Workspace 仍然必须经过：

Storage Runtime

110. Workspace Lifecycle

created
 ↓
active
 ↓
idle
 ↓
expired
 ↓
cleanup

111. Workspace Quota

每个：

AgentRun
Task
Organization

可以有：

storage quota

例如：

interface StorageQuota {
  maxBytes: number

  maxFiles: number

  maxSingleFileBytes: number
}

112. Agent Budget Integration

Agent Budget 增加：

storageBytes?: number

fileCount?: number

uploadBytes?: number

因此：

Agent

不能无限产生：

10GB

文件。

113. Task Budget Integration

Task 可以：

maxArtifactBytes
maxArtifactCount

超过：

budget_exceeded

Task 可以：

failed

或：

partially_completed

114. File Concurrency

Storage Provider 需要：

upload concurrency
download concurrency
processing concurrency

特别是：

large files

避免 Worker 被单个任务占满。

115. Large File Streaming

禁止：

const buffer = await file.arrayBuffer()

处理巨大文件。

必须支持：

stream

例如：

interface StreamSource {
  stream(): ReadableStream
}

116. Streaming Copy

例如：

S3
 ↓
S3

可以：

stream

不必：

S3
 ↓
RAM
 ↓
S3

117. Memory Limits

File processor 必须有：

maxMemory
maxDuration
maxOutputSize

避免：

malicious archive
huge decompression

导致 Worker OOM。

118. Archive Safety

ZIP/TAR 等处理必须防御：

Zip Bomb
Path Traversal
Symlink Escape
Huge File Count
Huge Uncompressed Size

119. Archive Extraction

默认：

disabled

需要明确：

processor capability

并且：

sandbox
resource limit

120. File Conversion

支持：

PDF → Text
DOCX → Text
Markdown → HTML
Image → Thumbnail
CSV → JSON

通过：

File Processor

执行。

121. Conversion Artifact

转换后的结果：

source.pdf
 ↓
conversion
 ↓
source.txt

必须：

new Artifact

并记录：

derived_from

122. File Version vs Artifact Version

区别：

File Version

表示：

同一个逻辑文件的更新

而：

Artifact Version

表示：

同一个输出对象的不同生成版本

不能混为一谈。

123. File Version Example

article.md
v1
v2
v3

用户编辑：

v3

Artifact：

SEO Report
v1
v2

每次 Task 重新生成。

124. Immutable Artifact

默认：

Artifact immutable

如果需要修改：

create new version

而不是：

overwrite

125. Immutable Deployment Artifact

Deployment package：

app-build-123.tar.gz

必须：

immutable

这样：

Deployment

才能可靠 rollback。

126. Artifact Promotion

Artifact 可以：

temporary
 ↓
validated
 ↓
promoted
 ↓
production

例如：

Build Artifact
 ↓
Test
 ↓
Production Artifact

Promotion 必须记录：

who
when
from
to

127. Artifact Signature

未来支持：

artifact signature

用于：

deployment
supply chain
verification

接口预留：

interface ArtifactSignature {
  algorithm: string

  keyId: string

  signature: string

  signedAt: Date
}

第一阶段不需要自行实现密码学。

128. Storage Audit

记录：

file.created
file.read
file.downloaded
file.deleted
artifact.created
artifact.downloaded

对于敏感文件：

read audit

必须开启。

129. Data / File Separation

Document 14：

Data Runtime

负责：

metadata
query
search
relations

Document 15：

Storage Runtime

负责：

binary
blob
upload
download
artifact

不要把 Blob：

直接塞 PostgreSQL

除非明确的小文件场景。

130. Database Storage

默认：

PostgreSQL

保存：

File Metadata
Artifact Metadata
Upload Session
File Relations
Retention Policy

对象存储保存：

Blob

131. Recommended Architecture

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

建议至少：

files
artifacts
artifact_versions
upload_sessions
file_relations
file_processing_jobs
storage_objects

133. storage_objects

interface StorageObjectRecord {
  id: string

  provider: string

  bucket: string

  key: string

  size: number

  checksum?: string

  etag?: string

  contentType?: string

  createdAt: Date
}

134. File → Storage Object

File
 ↓
StorageObject
 ↓
Provider
 ↓
Blob

允许未来：

File

重新绑定新的：

StorageObject

而不修改 File ID。

135. Storage Migration

Provider 切换：

S3
 ↓
R2

流程：

Migration Task
 ↓
Read Storage Object
 ↓
Copy
 ↓
Verify checksum
 ↓
Update metadata
 ↓
Delete old object

必须支持：

resume
retry
checkpoint

136. Storage Replication

未来支持：

Primary
 +
Replica

例如：

S3
 ↓
Backup S3

Artifact 可以配置：

replication policy

137. Storage Disaster Recovery

必须考虑：

DB lost
Object Storage lost
DB/Object inconsistent

恢复顺序：

Database
 ↓
Storage
 ↓
Reconcile
 ↓
Index

138. Reconciliation

提供：

core.storage.reconcile

检查：

DB File exists
Storage Object exists
Checksum matches
Artifact reference valid

发现异常：

orphan
missing
corrupt

139. Reconciliation Task

Storage Reconcile
 ↓
Task
 ↓
Jobs
 ↓
Worker
 ↓
Report Artifact

例如：

100000 objects
99000 valid
800 orphan
200 missing

输出：

reconcile-report.json

140. Storage CLI

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：

devos artifact list

devos artifact get <id>

devos artifact versions <id>

141. Storage UI

Settings：

System
 └── Storage
      ├── Providers
      ├── Buckets
      ├── Usage
      ├── Health
      ├── Policies
      └── Cleanup

142. Organization Storage Usage

Dashboard：

Storage
 ├── Files
 ├── Artifacts
 ├── Temporary
 ├── Backups
 └── Total

按：

Organization
Project
Plugin
Resource

统计。

143. Plugin Storage Usage

Plugin 可以查看：

SEO Plugin
 ├── 20GB
 ├── 12000 files
 └── 800 artifacts

但必须只能看到：

plugin-owned data

144. Storage Capability Registry

Storage 相关能力：

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

全部进入：

Capability Registry

145. MCP Exposure

MCP 可以使用：

file.search
file.get
artifact.list
artifact.get

但：

file.download
file.delete

属于更高风险 Capability。

必须经过：

Policy
Permission
Budget
Approval

146. Agent File Search Example

Goal：

“找到之前生成的 SEO 报告”

Agent：

Goal
 ↓
Capability Discovery
 ↓
core.file.search
 ↓
Search Runtime
 ↓
Permission
 ↓
Results
 ↓
core.artifact.get

而不是：

Agent
 ↓
filesystem scan

147. Agent Artifact Example

Goal：

“把本次分析结果导出为 PDF”

流程：

Agent
 ↓
Plan
 ↓
Task
 ↓
Generate Report Action
 ↓
Artifact
 ↓
Task Completed

最终：

Artifact ID

进入：

Agent Result

148. Plugin Example

Plugin 只需要：

defineResource({
  resource: 'seo.report'
})

并声明：

attachment field

DevOS 自动提供：

upload
preview
download
search
artifact
retention
permission

149. UI Extension

Plugin 可以声明：

interface FileWidgetExtension {
  resource: string

  placement:
    | 'overview'
    | 'attachments'
    | 'artifacts'

  component: string
}

例如：

SEO Article
 └── Attachments
      ├── Cover
      ├── Images
      └── Research PDF

150. Package Structure

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

packages/file/
├── file-service.ts
├── file-resource.ts
├── upload/
├── download/
├── preview/
├── processing/
├── lifecycle/
├── permissions/
└── index.ts

152. Artifact Package

packages/artifact/
├── artifact-service.ts
├── artifact-resource.ts
├── versioning.ts
├── provenance.ts
├── lineage.ts
├── retention.ts
└── index.ts

153. Processing Package

packages/file-processing/
├── processor.ts
├── processor-registry.ts
├── pipeline.ts
├── security/
├── metadata/
├── preview/
├── extraction/
├── embedding/
└── index.ts

154. Workspace Package

packages/workspace/
├── workspace-runtime.ts
├── workspace-policy.ts
├── quota.ts
├── lifecycle.ts
└── index.ts

155. Acceptance Criteria

Storage

[ ] Storage Runtime
[ ] Storage Provider
[ ] Local Provider
[ ] S3-compatible Provider
[ ] Provider Registry
[ ] Presigned URL
[ ] Streaming
[ ] Checksum

File

[ ] File Resource
[ ] Upload
[ ] Chunked Upload
[ ] Resume
[ ] Download
[ ] Preview
[ ] File Permissions
[ ] File Lifecycle
[ ] File Search

Artifact

[ ] Artifact Resource
[ ] Artifact Version
[ ] Provenance
[ ] Lineage
[ ] Immutable Artifact
[ ] Artifact Download
[ ] Artifact Retention

Processing

[ ] Processing Pipeline
[ ] Metadata
[ ] Text Extraction
[ ] Thumbnail
[ ] Security Scan
[ ] Embedding
[ ] Search Index

Reliability

[ ] Retry
[ ] Checkpoint
[ ] Reconciliation
[ ] Garbage Collection
[ ] Storage Migration
[ ] Health Check

156. Security Tests

必须测试：

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

测试：

small file upload
large file upload
multipart upload
resume
cancel
retry
checksum mismatch
duplicate upload
provider failure
network interruption

158. Artifact Tests

测试：

artifact creation
artifact version
artifact provenance
artifact lineage
artifact immutability
artifact retention
artifact download
artifact permission
artifact rollback

159. Agent Tests

测试：

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

测试：

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：

Plugin
 ↓
Resource
 ↓
File Attachment
 ↓
Upload
 ↓
Preview
 ↓
Search
 ↓
Artifact

全部应该自动进入：

DevOS Runtime

162. Performance Tests

必须测试：

100MB upload
1GB upload
10GB artifact
100k files
1M files
large directory
large search index
large artifact list

重点：

RAM usage
CPU
network
database query
provider latency

163. Zcode Implementation Rules

Rule 1

所有文件二进制操作：

必须经过 Storage Runtime

Rule 2

禁止：

UI
Plugin
Agent
MCP
Action Controller

直接：

fs.readFile
fs.writeFile
S3 SDK

访问业务文件。

Rule 3

业务文件 Metadata：

PostgreSQL

文件 Blob：

Object Storage

默认分离。

Rule 4

Artifact 必须可追踪：

Task
Job
Execution
Action Version
Plugin Version
Runtime Version

Rule 5

Artifact 默认：

Immutable

修改必须产生：

New Version

Rule 6

大文件必须：

Streaming
Multipart
Presigned URL

Rule 7

文件权限必须在：

URL Generation
Preview
Download
Search
MCP
Agent

全部生效。

Rule 8

Storage Index / Cache / Metadata：

都不是 Blob Source of Truth

Rule 9

文件生命周期必须：

Task
+
Job
+
Worker
+
Scheduler

执行。

Rule 10

Storage Provider 必须可替换。

禁止业务代码依赖：

S3 SDK
MinIO SDK
R2 SDK

164. Golden Rule

DevOS 文件体系必须遵循：

File
   ↓
File Metadata
   ↓
Storage Runtime
   ↓
Storage Provider
   ↓
Blob

Task 产物：

Task
   ↓
Job
   ↓
Execution
   ↓
Artifact
   ↓
Artifact Version
   ↓
File
   ↓
Storage Object
   ↓
Blob

文件处理：

File
   ↓
Processing Task
   ↓
Processor
   ├── Security Scan
   ├── Metadata
   ├── Preview
   ├── Text Extraction
   ├── Embedding
   └── Search Index

最终形成：

                         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 自己实现：

Upload
Download
File Storage
S3
Preview
Artifact
File Search
File Permission
File Lifecycle

而应该：

DevOS Core
 └── Storage Runtime
      ├── File
      ├── Artifact
      ├── Workspace
      ├── Upload
      ├── Preview
      ├── Processing
      ├── Search
      └── Lifecycle

Plugin 只定义：

Resource
+
Attachment
+
Artifact Type
+
Processing Requirement

DevOS 自动提供基础设施。

最终目标：

Plugin = Business Capability

DevOS = Data + Action + Agent + Task + Storage + Runtime

而不是：

Plugin = 一个自己带数据库、文件系统、队列、Agent、搜索系统的小型应用

这才是 DevOS 可以长期复用、扩展和 Fork 的基础。

47 KiB Raw Permalink Blame History Unescape Escape

DevOS File / Artifact / Storage Runtime

1. Goals

2. Core Principle

3. File

4. Blob

5. Artifact

6. Attachment

7. Storage Object

8. Architecture

9. Storage Runtime

10. Storage Provider

11. StorageContext

12. File Resource

13. File Status

14. File Lifecycle

15. Storage Key

16. Never Trust Filename

17. Original Filename

18. MIME Type

19. File Validation

20. Upload Policy

21. Default Limits

22. Chunked Upload

23. Upload Session

24. Resumable Upload

25. Presigned URL

26. Presigned URL Security

27. Download Action

28. Preview Action

29. Preview Provider

30. Preview Result

31. Image Metadata

32. File Processing

33. File Processing Pipeline

34. Processing Capability

35. Processor Types

36. Virus Scanning

37. Security Scanner Provider

38. Text Extraction

39. Extracted Text

40. File Search

41. File Embedding

42. File Chunk

43. Chunk Strategy

44. RAG Integration

45. Artifact Resource

46. Artifact Examples

47. Artifact Version

48. Artifact Versioning

49. Reproducibility

50. Artifact Provenance

51. Artifact Lineage

52. Artifact Relation

53. Agent Artifact

54. Agent File Access

55. Agent File Capabilities

56. MCP File Access

57. Local Filesystem

58. Path Traversal

59. Storage Bucket

60. Bucket Policy

61. Encryption

62. Secret Files

63. Temporary Files

64. Temp File Cleanup

65. Artifact Retention

66. Retention Policy

67. Reference Protection

68. Garbage Collection

69. Garbage Collection Safety

70. Checksum

71. Deduplication

72. Deduplication Security

73. File Copy

74. File Move

75. File Rename

76. File Delete

77. Hard Delete

78. File Events

47 KiB

Raw Permalink Blame History