P10 · 如何管理平台的数据、产物与共享资产？ - Platform Data & Assets

所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何对平台业务数据、执行数据、Agent 产物与可共享资产进行统一建模、持久化、索引、授权、追溯、交付和生命周期治理，同时保证多租户安全、成本可控与运行可靠？

专题导读

本篇属 Technical Architecture。Agent Platform 的价值不止于运行 Agent，还在于让运行过程中的输入、状态、输出、知识和可复用成果成为可识别、可追溯、可授权、可交付的平台资产。如果仅把所有内容存成聊天记录或对象存储文件，平台很快会遇到产物找不到、版本无法追踪、重复存储、跨项目误共享、删除不彻底、恢复不可复现等问题。

本篇研究平台级数据与资产治理：对象分类、元数据与存储分层、产物提交与发布、共享与权限、检索与血缘、保留与删除、备份恢复及成本治理。它不代替 P3 的 Agent 定义版本管理、P6 的工作流编排、P7 的外部资源接入、P11 的多租户隔离，也不把 Agent 的短期上下文和长期记忆全部等同于文件资产。本文给出参考设计、可运行方向的接口与 SQL 示例，并标注尚待验证的部分。

研究结论

数据与资产不是同一个层次。 数据是广义的记录与内容；资产是具有稳定身份、元数据、治理规则和生命周期、可被引用或交付的数据对象。
逻辑资产与物理内容必须分离。 asset_id 表示逻辑身份；asset_version_id 表示不可变内容版本；blob_id 或对象存储键表示底层字节。一个逻辑资产可以有多个版本，多个版本可以复用相同字节。
关系数据库管理事实与事务，对象存储管理大内容，索引系统提供发现能力。 搜索索引、向量索引和缓存都不应成为资产真实性的唯一来源。
执行结果必须通过受控提交转为正式资产。 Worker 的临时输出不能因为上传成功就自动成为已发布、可共享、可信任的交付物。
版本、来源、权限和保留策略应从创建时记录。 后补元数据无法可靠恢复所有来源与访问历史。
共享是受约束的授权关系，而非简单复制或公开 URL。 权限应在读取、下载、搜索结果展示和衍生交付时分别校验。
删除是跨系统的工作流。 数据库记录、对象存储、缓存、索引、备份、衍生文件与外部副本具有不同删除能力和时延；不能将“隐藏”称为“彻底删除”。
Studio 初期优先实现文件/报告资产、版本、运行关联、私有下载、基础检索与导出。 大规模知识图谱、跨组织市场和复杂自动分级可在需求明确后建设。

一、概念、分类与边界

1.1 五类平台数据

数据类别	典型对象	主要性质	推荐主要存储
平台控制数据	Tenant、Workspace、Project、成员、权限、配置	强一致的业务事实	关系数据库
定义与配置数据	Agent/Workflow 版本引用、Manifest、资源绑定	可版本化、可审计	关系数据库 + 对象存储
执行与事件数据	Run、Step Run、Attempt、事件、检查点	高频写入、保留分层	关系数据库 + 日志/事件存储
内容与产物数据	上传文件、检索快照、报告、图片、表格、导出包	字节量大、格式多样	对象存储 + 元数据表
发现与派生数据	全文索引、向量、缩略图、预览、统计	可重建、可能最终一致	搜索/向量系统 + 缓存

上述是治理分类，不是要求必须部署五种独立数据库。早期平台可采用 PostgreSQL、兼容 S3 的对象存储、PostgreSQL 全文检索和后台任务，待规模增长再拆分。

1.2 Data、Artifact、Asset、Knowledge、Memory

Data（数据）：平台存储或处理的全部结构化与非结构化信息。
Artifact（产物）：某个任务或流程产生的可识别输出，如报告 Markdown、引用清单、生成图、测试报告。产物可以尚未发布。
Asset（资产）：有稳定身份、所有者、版本、访问规则和管理生命周期的对象；上传文件、经过治理的产物及共享模板都可成为资产。
Knowledge（知识资源）：面向检索、推理或复用而组织的内容及索引；知识库可能引用多个资产，但不等同于所有文件。
Memory（记忆）：Agent 为连续交互保存的状态或长期事实；其生命周期、隐私边界和检索语义与通用资产不同，只有明确纳入资产治理的部分才进入本篇管理模型。

“Artifact”与“Asset”是不同维度：前者强调来源于执行，后者强调被平台治理。一个报告可同时属于两者。

1.3 与 P1 - P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 的职责边界

相邻组件	其主要职责	P10 提供什么
P1 Control Plane	准入、控制、策略决策	资产操作的事务接口、元数据与审计事件
P2 Execution Plane	执行任务、产生临时输出	上传暂存、正式提交、结果引用
P3 Agent Registry	Agent 定义与不可变版本	可复用底层内容存储，但 Agent 版本语义归 P3
P5 Runtime Management	Run/实例生命周期	Run 与资产的来源关联、检查点保留接口
P6 Workflow Management	工作流状态与节点依赖	节点输入输出引用、产物血缘
P7 Resource & Integration	外部资源连接、凭证与调用	平台内部资产与外部资源的受控引用
P8 Platform API & SDK	对外接口契约	资产查询、上传、下载、导出 API
P9 Extensibility	插件工件与扩展机制	插件生成产物的接收和治理
P11 Multi-tenancy	租户边界与隔离策略	租户标识、对象级过滤和数据隔离实施
P12 Governance	统一策略与治理	资产级策略执行点、保留与审计证据

边界原则： P10 定义数据与资产的存储及治理机制，不替代全平台的身份认证、策略制定、业务流程或安全组织架构。

二、对象模型：逻辑身份、版本与字节

2.1 核心对象

对象	主键	说明
`Asset`	`asset_id`	逻辑资产，稳定名称、类型、归属、可见性、当前版本指针
`AssetVersion`	`asset_version_id`	一次不可变内容快照、格式、大小、摘要、来源与创建时间
`Blob`	`blob_id`	物理字节对象及其存储位置、摘要、加密/校验状态
`Artifact`	`artifact_id`	Run/Step Run 产生的输出语义及其资产映射
`AssetRelation`	`relation_id`	引用、派生、包含、替代、输入/输出关系
`AssetGrant`	`grant_id`	对主体、范围和操作的授权关系
`Collection`	`collection_id`	工作空间内的逻辑分组或知识集合
`ExportJob`	`export_job_id`	从若干资产生成可下载交付包的异步任务
`RetentionPolicy`	`policy_id`	保留期、合法保全、到期动作等策略
`AssetEvent`	`event_id`	创建、提交、发布、共享、撤销、下载、删除等审计事件

2.2 关系示意

mermaid

 erDiagram
   WORKSPACE ||--o{ ASSET : owns
   ASSET ||--o{ ASSET_VERSION : has
   ASSET_VERSION }o--|| BLOB : stores_bytes_in
   RUN ||--o{ ARTIFACT : produces
   ARTIFACT }o--|| ASSET_VERSION : materializes_as
   ASSET_VERSION ||--o{ ASSET_RELATION : participates
   ASSET ||--o{ ASSET_GRANT : governed_by
   COLLECTION ||--o{ COLLECTION_ITEM : includes
   ASSET ||--o{ COLLECTION_ITEM : appears_in
   ASSET ||--o{ ASSET_EVENT : audited_by

一个 Blob 可以被多个版本引用，但去重范围必须与隔离策略匹配。跨租户物理去重可能泄漏内容存在性、影响加密密钥和删除承诺，不能默认启用。

2.3 不变式（Invariants）

asset_id 在所属命名空间内保持稳定；重命名不改变身份。
asset_version_id 的内容摘要、Blob 关联和内容类型在提交后不可修改。
当前版本指针可以更新，但应使用并发控制，避免覆盖其他人的修改。
Artifact 必须记录来源 Run；无 Run 的手动上传标记 origin=upload，不能伪造执行来源。
引用失效、版本撤销、访问权撤销是不同事件。
所有查询必须在服务端按租户和授权范围过滤；前端隐藏不是访问控制。
资产元数据和 Blob 的最终可用性必须通过提交协议协调，而非假设跨系统原子事务。

三、参考总体架构

mermaid

flowchart TB
  UI[Studio Web / CLI / SDK] --> API[Asset API]
  CP[Control Plane] --> API
  WK[Execution Workers] --> UP[Upload / Commit Service]
  API --> AUTH[Authorization / Policy Enforcement]
  UP --> AUTH
  API --> META[(PostgreSQL: Metadata & ACL)]
  UP --> META
  UP --> OBJ[(Object Storage: Blobs)]
  API --> OBJ
  META --> OUT[Transactional Outbox]
  OUT --> BUS[Event / Job Queue]
  BUS --> IDX[Search Indexer]
  BUS --> PRE[Preview / Extraction / Export Workers]
  IDX --> SEARCH[(Full-text / Vector Index)]
  PRE --> OBJ
  API --> SEARCH
  API --> AUDIT[Audit Log]

核心路径分成三类：元数据事务路径（数据库）、内容传输路径（对象存储）和异步派生路径（索引、预览、导出）。将大文件经 API 全量转发可简化安全控制但增大带宽成本；采用短时效预签名 URL 可减轻服务压力，但必须在签发前授权，并限定对象、操作、大小、类型与有效期。

3.1 分层职责

Metadata Service：逻辑资产、版本、关联、分类、状态和所有权。
Blob Service：对象键、上传会话、校验、加密、存储级别、删除和垃圾回收。
Artifact Service：Run 产物登记、暂存转正式、质量门禁与交付状态。
Index Service：全文、结构化过滤、向量索引和重建。
Access Service：授权决策、共享、下载凭据与撤销。
Lifecycle Service：保留、归档、法律保全、删除编排与成本策略。
Delivery Service：格式转换、导出包、交付清单与下载。

这些是逻辑模块，不要求一开始就拆成微服务。

四、数据模型与元数据契约

4.1 最小资产元数据

json

{
  "asset_id": "ast_01JEXAMPLE",
  "tenant_id": "ten_demo",
  "workspace_id": "ws_research",
  "project_id": "prj_agent_study",
  "kind": "report",
  "title": "Agent 平台架构研究",
  "description": "已审核的专题研究报告",
  "classification": "internal",
  "owner_id": "usr_editor",
  "status": "active",
  "current_version_id": "av_002",
  "tags": ["agent-platform", "architecture"],
  "created_at": "2026-10-31T10:00:00Z",
  "updated_at": "2026-10-31T10:30:00Z"
}

4.2 不可变版本元数据

json

{
  "asset_version_id": "av_002",
  "asset_id": "ast_01JEXAMPLE",
  "version_number": 2,
  "blob_id": "blob_sha256_...",
  "sha256": "<64-character-hex-digest>",
  "size_bytes": 183220,
  "media_type": "text/markdown",
  "filename": "report-v2.md",
  "origin": {
    "type": "workflow_run",
    "workflow_run_id": "wr_203",
    "step_run_id": "sr_reviewed",
    "agent_version_id": "agv_reviewer_4"
  },
  "created_by": "svc_studio",
  "created_at": "2026-10-31T10:30:00Z",
  "integrity_status": "verified",
  "review_status": "approved"
}

示例中的 ID、摘要占位符与时间仅说明契约，不是实际系统数据。review_status 是业务审核结果；integrity_status 是字节完整性状态，二者不能混为一谈。

4.3 元数据字段分组

分组	字段示例	设计要点
身份	ID、租户、工作空间、项目	稳定、唯一、不可跨租户碰撞
内容	MIME、大小、摘要、编码	由服务端核验，不信任上传者声明
归属	owner、creator、service principal	区分所有者和执行服务身份
来源	run、step、agent version、输入版本	追溯链必须能跨任务查询
治理	分类、可见性、保留、legal hold	权限与保留分开建模
生命周期	状态、版本、归档、删除时间	状态迁移可审计
检索	标题、摘要、标签、语言、索引状态	索引字段不等于授权依据
交付	格式、清单、审核、发布渠道	内部产物与外部交付分离

五、存储设计：数据库、对象存储与派生索引

5.1 关系数据库职责

关系数据库保存资产身份、版本元数据、权限关系、工作空间归属、来源关联、发布状态、保留规则和审计指针。核心查询应有明确索引，所有可被租户访问的表都应携带可验证的隔离键，或通过不可绕过的关联路径实施租户约束。

sql

-- 参考 DDL：展示约束方向，非可直接用于生产的完整迁移脚本。
CREATE TABLE assets (
  tenant_id uuid NOT NULL,
  asset_id uuid NOT NULL,
  workspace_id uuid NOT NULL,
  project_id uuid,
  kind text NOT NULL,
  title text NOT NULL,
  classification text NOT NULL DEFAULT 'internal',
  status text NOT NULL DEFAULT 'active',
  current_version_id uuid,
  revision bigint NOT NULL DEFAULT 0,
  created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, asset_id)
);

CREATE TABLE asset_versions (
  tenant_id uuid NOT NULL,
  asset_version_id uuid NOT NULL,
  asset_id uuid NOT NULL,
  version_number bigint NOT NULL,
  blob_id uuid NOT NULL,
  sha256 char(64) NOT NULL,
  media_type text NOT NULL,
  size_bytes bigint NOT NULL CHECK (size_bytes >= 0),
  created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, asset_version_id),
  UNIQUE (tenant_id, asset_id, version_number),
  FOREIGN KEY (tenant_id, asset_id)
    REFERENCES assets (tenant_id, asset_id)
);

CREATE INDEX idx_assets_workspace
  ON assets (tenant_id, workspace_id, created_at DESC);
CREATE INDEX idx_versions_asset
  ON asset_versions (tenant_id, asset_id, version_number DESC);

生产实现还需要：Blob 表、权限表、外键闭环、current_version_id 同租户且同资产校验、审计、迁移、备份、RLS 策略、并发冲突处理。仅凭上述 DDL 不能声称已实现租户隔离。

5.2 对象存储与对象键

对象键应由平台生成，例如 tenant/<opaque-id>/blobs/<random-id>；不要直接把用户文件名拼成路径，也不要在公开 URL 中暴露敏感项目名称。应校验服务端计算的内容摘要、实际字节数、文件头和 MIME 声明，并对危险文件类型实施隔离与扫描。

存储层需考虑：服务端加密、密钥轮换、分片上传、上传中断回收、版本化与生命周期策略、跨区域复制、灾难恢复和访问日志。对象存储“版本控制”是底层存储能力，不等同于业务资产版本。

5.3 索引与缓存

搜索索引属于派生视图：可能滞后、可重建，不可单独决定授权。检索结果应至少带回 asset_id/version_id，在服务端执行授权过滤或使用经过验证的安全过滤机制。向量索引也必须遵守租户、工作空间与可见性边界，不能因相似度搜索绕过 ACL。

缓存键应包含足够的授权上下文或只缓存与主体无关的数据；授权撤销后需定义失效机制。对于高敏感数据，优先牺牲缓存命中率而不是复用错误权限结果。

六、上传、提交与产物生成协议

6.1 两阶段内容提交

mermaid

sequenceDiagram
  participant W as Worker / Client
  participant A as Asset API
  participant D as Metadata DB
  participant O as Object Storage
  participant Q as Async Queue
  W->>A: 请求 upload session（身份/大小/类型）
  A->>D: 创建 pending_upload（过期时间）
  A-->>W: 限定范围的上传凭据
  W->>O: 上传临时对象
  W->>A: complete(session_id, checksum, idempotency_key)
  A->>O: 核验对象存在、大小与摘要
  A->>D: 事务：创建版本 + 更新资产指针 + outbox
  A-->>W: asset_version_id / committed
  D-->>Q: 异步分发提交事件
  Q->>O: 扫描/预览/索引/生命周期处理

此流程应定义临时对象超时清理、重复 complete 的幂等返回、DB 成功但事件未发出的 outbox 恢复，以及对象上传成功但 DB 提交失败的垃圾回收。数据库事务不能覆盖对象存储，因此应使用可恢复状态机和补偿处理实现最终一致。

6.2 产物状态机

mermaid

stateDiagram-v2
  [*] --> Temporary
  Temporary --> Validating: upload completed
  Validating --> Rejected: scan / contract failure
  Validating --> Committed: integrity verified
  Committed --> UnderReview: requires approval
  UnderReview --> Published: approved
  UnderReview --> Committed: revision requested
  Committed --> Published: auto-publish allowed
  Published --> Archived: retention transition
  Committed --> Deleted: deletion permitted
  Published --> Deleted: deletion permitted
  Archived --> Deleted: retention expired

这里的 Published 指可供授权对象消费，不意味着“互联网公开”。安全扫描、内容质量评审、版权与合规审批可能由不同服务负责，且存在不同的通过条件。

6.3 产物契约

一次 Agent 执行可以产生多种产物：primary_output、supporting_evidence、trace_export、intermediate_draft、final_delivery。应以类型和来源描述，而非仅凭文件名推断。建议在 Step Run 完成时提交产物清单；工作流完成时由交付服务选择最终交付集合。

json

{
  "workflow_run_id": "wr_203",
  "step_run_id": "sr_report",
  "artifacts": [
    {
      "role": "primary_output",
      "asset_version_id": "av_report_3",
      "media_type": "text/markdown"
    },
    {
      "role": "supporting_evidence",
      "asset_version_id": "av_sources_2",
      "media_type": "application/json"
    }
  ]
}

七、版本管理、引用与内容寻址

7.1 三种版本概念

逻辑资产版本：面向用户的报告 v1、v2、v3。
内容摘要：对字节计算的 SHA-256，用于校验完整性与判断内容相同。
交付版本：一次审核通过并对外提供的交付包，可包含多个资产版本。

这三者不能互相替代。相同字节可能有不同业务语义；同一交付包也可能包含多个不同版本的文件。

7.2 引用策略

引用方式	例子	优点	风险与适用
固定版本	`asset_version_id=av_002`	可追溯、适合 Run 输入	需要处理撤销与保留
当前版本	`asset_id=ast_01`	适合用户浏览	结果随时间变化
发布渠道	`channel=approved`	便于推广与回滚	运行时必须解析为固定版本
内容摘要	`sha256=...`	校验字节一致性	不表示授权或业务身份

在创建 Workflow Run 时，应解析所有关键输入的可变引用，生成输入资产版本清单。这使事后能够回答“这篇报告究竟依据了哪份资料”。但即使锁定资产版本，也不意味着外部 API、模型服务和随机采样都完全可复现。

7.3 并发更新

编辑者 A、B 同时提交新版本时，使用 revision/ETag 或事务锁防止无提示覆盖。典型策略是：内容版本可并存，但更新 current_version_id 必须进行条件写入；冲突时返回 409 Conflict 或 412 Precondition Failed，由客户端显式合并或重试。

八、来源、血缘与可追溯性

8.1 血缘图

mermaid

flowchart LR
  S1[Source Asset v1] --> R[Research Step Run]
  S2[Source Asset v2] --> R
  R --> D[Research Draft v1]
  D --> V[Review Step Run]
  V --> F[Approved Report v2]
  F --> E[PDF Export v1]
  F --> M[Delivery Manifest]
  E --> M

关系类型建议至少包括 derived_from、uses_as_input、produced_by、contains、supersedes、exported_from、cites。引用关系和事实支持关系必须分开：某报告引用某来源，不代表来源确实支持报告中的每项结论。

8.2 最小来源记录

执行主体：Run、Step Run、Agent Version、Workflow Version。
输入依据：Asset Version IDs、外部资源访问记录及抓取时间。
转换操作：生成、人工编辑、格式转换、审核批准。
输出结果：Asset Version、摘要、生成时间。
人工介入：审批人、时间、决策与修改记录。

外部网页内容可能更新或被删除。若合规与许可允许，可保存必要的引用元数据或授权快照；不得默认将受版权或合同限制的外部内容永久复制入库。

8.3 来源可信度与完整性

SHA-256 能验证字节未发生意外变化，但不能证明内容真实、合法或可靠。来源身份验证、签名、审计、人工审查和事实核验分别解决不同问题。对研究类产物建议同时保存“来源记录”和“证据核验状态”，避免把可追溯性误当作事实正确性。

九、资产发现、搜索与知识化

9.1 查询路径

资产发现包括：结构化过滤（项目、类型、标签、创建时间）、全文检索（标题/正文）、语义检索（嵌入向量）和血缘导航（查看输入、派生物、同一 Run 产物）。每种方式应有明确适用条件，不能只依赖向量相似度。

9.2 内容处理流水线

mermaid

flowchart LR
  A[Committed Asset Version] --> E[Extract Text / Metadata]
  E --> C[Chunk & Normalize]
  C --> I[Full-text Index]
  C --> V[Optional Embeddings]
  I --> Q[Authorized Search]
  V --> Q
  A --> P[Preview / Thumbnail]

文本抽取失败不能影响原始文件的持久化；派生任务应有重试、错误记录与人工重新索引入口。Chunk 必须关联 asset_version_id 和位置范围，版本更新后应使旧索引失效或显式标注历史版本。

9.3 检索授权与提示注入

外部文档、上传文件及其检索片段都应视为不可信内容，不能把其中的“系统指令”“请泄露密钥”等文本提升为平台指令。搜索索引应遵守租户和对象级权限；向 Agent 提供检索内容时附来源标识、范围和可信度，不直接赋予其执行工具的权限。

十、共享、权限与交付边界

10.1 共享模型

共享可以是工作空间内协作、跨项目引用、跨工作空间授权、跨租户受控共享、公开发布或一次性交付。不同共享范围应使用不同授权策略，避免只有 is_public 一个布尔字段。

建议采用“主体 - 资源 - 动作 - 条件”的授权模型：主体可为用户、服务账户、角色或受控外部接收者；动作包括 read_metadata、read_content、write_version、share、export、delete；条件可包括租户、项目、时间、分类级别和审批状态。

10.2 下载安全

每次签发下载凭据前进行授权与资源状态校验。
短期下载 URL 不等于可撤销的强保证：已签发 URL 在过期前可能仍有效；对高敏感内容应采用代理下载或更短时效、额外令牌校验。
共享撤销应使后续 API 访问立即失败，并尽快失效相关缓存；已下载到外部设备的副本通常无法由平台强制删除。
预览、缩略图、搜索摘要和导出文件可能泄露与原文相同的信息，必须纳入权限治理。

10.3 复制与引用

跨工作空间共享优先采用授权引用还是物理复制，取决于隔离要求、所有权、保留期和撤销语义。引用便于集中治理，但依赖源资产持续存在；复制提高独立性，却增加存储、同步和删除负担。应明确共享后由谁承担成本、谁可以撤销、谁有权保留历史版本。

十一、生命周期：保留、归档、删除与恢复

11.1 参考生命周期

Created → Committed → Active → Archived → Deletion Requested → Purging → Purged。

Revoked、Under Legal Hold、Quarantined 等可作为独立治理状态，不宜强行挤入单一线性状态机。对于被其他产物引用的版本，删除前应检查依赖、保留政策和合法保全约束。

11.2 保留策略

对象	参考策略	说明
上传暂存对象	短期自动过期	避免孤儿上传累积
Run 中间草稿	项目可配置的有限保留	可与最终交付分离
正式报告版本	按项目或合同政策保留	保证引用与审计可追溯
日志与追踪	最小必要保留	注意敏感内容脱敏
导出缓存	短期保留、可重建	不应无限期复制
备份	独立保留周期	恢复后仍需重放删除要求

表中不设统一天数，因为不同业务、地区、合同及法规要求不同。保留期应由治理政策和法律评估决定，而非直接照搬示例值。

11.3 删除的实际语义

删除请求可能经历：冻结共享、取消索引、标记墓碑、阻止新读取、检查引用/合法保全、删除物理对象、清理派生数据、记录结果、按备份策略完成到期清除。若 Blob 被多个合法版本引用，不能直接删除其物理字节。

需要明确告知用户：平台能控制自己的在线存储与服务访问，但不能保证撤回外部下载副本，也不能把备份中尚未过期的数据描述为已经物理清除。

11.4 灾难恢复

备份必须覆盖数据库与对象存储的一致性关系。只恢复数据库可能留下失踪 Blob；只恢复 Blob 可能缺失资产索引和授权。应定期验证恢复演练、校验随机样本的摘要、检测孤儿记录，并定义 RPO/RTO。任何具体恢复目标都需要基于业务需求和实测能力设定。

十二、交付物管理与导出流水线

12.1 交付包不是普通 ZIP

一个交付包至少应记录：交付 ID、接收方或访问范围、包含的固定 Asset Version、文件清单、各文件摘要、生成时间、格式转换版本、审批状态和有效期。可以使用 ZIP、PDF、Markdown 或网页发布，但必须有独立交付记录。

json

{
  "delivery_id": "del_1001",
  "workflow_run_id": "wr_203",
  "status": "ready",
  "manifest_version": 1,
  "items": [
    {"name": "report.md", "asset_version_id": "av_report_3"},
    {"name": "references.json", "asset_version_id": "av_sources_2"},
    {"name": "report.pdf", "asset_version_id": "av_pdf_1"}
  ],
  "review_status": "approved"
}

12.2 转换与再生成

PDF/HTML/图片预览等是从源资产派生的新版本化产物，应记录源版本、转换器版本、参数与输出摘要。源文件更新后，旧 PDF 不会自动变成新 PDF；应明确重新生成或保持历史交付不变。

12.3 发布与撤回

发布操作需要满足审核、权限、内容安全和交付完整性要求。撤回应停止新访问和新分发，但无法撤销已经下载的副本。若公开站点存在 CDN 缓存，需要单独的失效流程与可观测结果。

十三、API 与事件契约

13.1 参考 API

方法	路径	语义
`POST`	`/v1/assets`	创建逻辑资产
`GET`	`/v1/assets/{asset_id}`	查询元数据与当前版本
`GET`	`/v1/assets/{asset_id}/versions`	分页查询历史版本
`POST`	`/v1/assets/{asset_id}/uploads`	创建受限上传会话
`POST`	`/v1/uploads/{upload_id}:complete`	校验并提交版本
`GET`	`/v1/asset-versions/{version_id}`	查询固定版本
`POST`	`/v1/asset-versions/{version_id}:download`	授权后获取下载凭据
`POST`	`/v1/assets/{asset_id}/grants`	建立共享授权
`DELETE`	`/v1/assets/{asset_id}/grants/{grant_id}`	撤销共享授权
`GET`	`/v1/assets:search`	受权限约束的资产搜索
`GET`	`/v1/assets/{asset_id}/lineage`	查询来源与派生关系
`POST`	`/v1/exports`	创建异步导出任务
`GET`	`/v1/exports/{export_id}`	查询导出状态
`POST`	`/v1/assets/{asset_id}:requestDeletion`	发起删除工作流

上述路径是参考设计，不是已有标准或真实产品接口。批量导出和删除等耗时操作宜返回异步 Job ID；上传完成接口应支持幂等键，列表查询应支持游标分页。

13.2 错误契约

json

{
  "error": {
    "code": "ASSET_VERSION_CONFLICT",
    "message": "Current version changed since your last read.",
    "request_id": "req_example",
    "retryable": false
  }
}

典型错误包括：ASSET_NOT_FOUND（可对未授权对象隐藏其存在）、PERMISSION_DENIED、UPLOAD_EXPIRED、CHECKSUM_MISMATCH、QUARANTINED、RETENTION_BLOCKED、ASSET_VERSION_CONFLICT、QUOTA_EXCEEDED、EXPORT_FAILED。HTTP 状态码与业务错误码应形成稳定映射。

13.3 领域事件

建议事件包括 asset.created、asset.version.committed、asset.version.published、asset.grant.revoked、asset.indexing.failed、asset.deletion.requested、asset.purged、export.completed。事件至少携带 event_id、tenant_id、asset_id、version_id（如适用）、时间、因果请求 ID 和 Schema 版本。

消费者应按至少一次投递设计，处理重复事件和乱序；不能把事件到达顺序当作数据库最终状态。

十四、安全、隐私与治理

14.1 威胁模型

威胁	可能路径	关键控制
跨租户数据泄漏	查询遗漏租户过滤	服务端对象级授权、数据库约束/RLS、越权测试
不安全直接对象引用	猜测资产 ID	不依赖 ID 保密，逐次授权
上传恶意文件	文件伪装、宏、解析漏洞	类型核验、隔离扫描、沙箱转换
提示注入	检索文档包含恶意指令	将文档视为数据，工具权限独立校验
URL 泄漏	长期预签名链接、日志记录	短时效、日志脱敏、下载代理
内容篡改	上传替换或存储错误	内容摘要、不可变版本、审计
越权共享	共享者权限过大	`share` 独立权限、审批、作用域限制
隐私泄露	索引、预览、Trace 含敏感数据	数据分类、脱敏、最小保留
不当删除	误删或合法保全冲突	双阶段删除、保全检查、审计
存储滥用	巨型上传、压缩炸弹	配额、解压限制、超时与计费

14.2 数据分类

可以从 public / internal / confidential / restricted 起步，但这些等级必须配套实际权限和处理要求。敏感等级应支持向派生产物传播，不能因转换为 PDF、摘要或向量就自动降低保护级别。自动分类只能作为辅助，关键对象应允许人工复核。

14.3 数据驻留与合规

涉及个人信息、跨境传输、著作权、行业监管和数据保留时，应根据服务地区、用户所在地、数据性质及合同义务确定具体要求。本文不将某一种存储区域或固定保留期视为普遍合规方案。日志与向量也可能包含个人信息，不能排除在数据治理之外。

十五、可靠性、性能与成本

15.1 关键 SLI

指标	定义建议	观察目的
Commit success rate	成功提交版本数 / 有效提交请求数	写入可靠性
Blob availability	可成功读取且摘要匹配的对象比例	内容可用性
Index lag	提交到可搜索的延迟分布	搜索新鲜度
Download latency	授权后获取内容的耗时分布	用户体验
Orphan blob count	无有效引用的物理对象数	存储清理
Authorization denial anomalies	异常授权拒绝/放行模式	安全监测
Export completion rate	导出成功任务 / 已完成任务	交付可靠性
Cost per workspace	存储、流量、索引、转换费用归因	成本治理

目标阈值必须结合业务负载与实际测试确定。监控指标本身也应避免包含原始敏感文档内容。

15.2 成本来源

成本不仅是对象存储容量，还包括请求次数、跨区域传输、下载带宽、搜索索引、向量嵌入、格式转换、预览生成、备份和长期日志。对 Studio 可先按 workspace_id / project_id / workflow_run_id 归因，并区分原始资产、版本历史、派生文件和临时缓存。

15.3 扩展策略

初期：单 PostgreSQL + 对象存储 + 异步任务 + 简单全文搜索。增长期：分离索引服务、冷热存储、导出 Worker 池、分层缓存。大规模阶段：跨区域数据策略、分区表、独立搜索集群、审计归档与配额调度。不要把技术复杂度当成平台成熟度；优先依据真实瓶颈演进。

十六、Studio 贯穿案例：研究报告的资产全生命周期

16.1 业务场景

Studio 创建一项“Agent 平台技术架构”研究任务，选题 Agent 输出候选题目，调研 Agent 产生资料与引用清单，分析 Agent 生成结构化结论，审核 Agent 给出修改意见，用户确认后发布 Markdown 报告并导出 PDF。

16.2 对象与流程映射

阶段	产生的数据	P10 管理方式
创建任务	项目、Workflow Run、输入资料	保存固定输入资产版本
选题	候选题目、选择理由	中间 Artifact，关联 Step Run
深度调研	来源清单、摘录、网页元数据	分开保存来源记录与正文资产
分析写作	报告 Draft v1	新资产或新版本，记录输入血缘
审核返工	评审结果、Draft v2	保留审核记录及版本差异
人工确认	审批决策	审计事件，允许发布指定版本
发布	Report vFinal	固定发布版本、权限与分类
导出	PDF、ZIP、清单	派生资产与交付记录
后续更新	Report vNext	新版本，不覆盖旧交付包

16.3 一次运行的参考时序

mermaid

sequenceDiagram
  participant U as User
  participant S as Studio Control
  participant W as Workflow Engine
  participant A as Asset Service
  participant R as Reviewer
  U->>S: 创建研究任务（输入资产）
  S->>A: 解析并固定输入版本
  S->>W: 启动 Workflow Run
  W->>A: 提交调研产物与来源清单
  W->>A: 提交报告 Draft v1
  W->>R: 发起审核
  R-->>W: 返工意见
  W->>A: 提交报告 Draft v2
  W-->>U: 请求最终确认
  U->>S: 批准固定版本
  S->>A: 发布 Report v2
  S->>A: 创建 PDF/ZIP 导出任务
  A-->>U: 返回交付包与受控下载链接

16.4 初期最小数据表

优先建立 assets、asset_versions、blobs、artifacts、asset_relations、asset_grants、upload_sessions、export_jobs、asset_events 九类逻辑表；若现有系统已具备通用权限、审计或文件服务，可复用而非重复造轮子。第一阶段不要求复杂知识图谱或专门向量数据库。

16.5 分阶段交付路线

MVP： 私有上传、资产元数据、不可变版本、Run 关联、Markdown 下载、基础导出、删除请求。
Phase 2： 审核发布、版本比较、全文搜索、权限共享、来源血缘、异步 PDF/ZIP 导出。
Phase 3： 跨项目共享、知识集合、语义检索、分层保留、成本归因、合规治理与跨组织交付。

每个阶段都应先验证授权、可恢复性和数据一致性，再扩展用户可见功能。

十七、工程验证计划

以下是待执行的参考测试设计，不表示已经部署或测试通过。验收标准应进一步细化为自动化断言、数据集与性能阈值。

ID	测试场景	预期结果
T01	创建资产后重命名	`asset_id` 不变，版本历史可查询
T02	同一资产提交两个版本	版本均可按 ID 获取，旧内容不变
T03	两个客户端并发更新当前版本	条件更新检测冲突，不静默覆盖
T04	上传文件实际摘要与声明不符	拒绝提交并记录原因
T05	上传成功、数据库提交失败	临时对象可回收，正式资产不伪造成功
T06	数据库提交成功、事件投递失败	Outbox 可重试，最终建立索引
T07	重复提交相同幂等键	返回同一提交结果，不重复创建版本
T08	上传会话过期后继续提交	拒绝并回收暂存资源
T09	Worker 崩溃于产物提交中	状态可恢复，无半提交可见版本
T10	未授权用户猜测 Asset ID	无法读取元数据或内容
T11	跨租户全文检索	结果不包含其他租户内容
T12	跨租户向量检索	不泄露其他租户内容与摘要
T13	撤销共享授权后访问	后续受控 API 请求被拒绝
T14	已签发预签名 URL 后撤销	记录并验证剩余有效期风险
T15	搜索索引延迟	元数据仍正确，索引可重建
T16	源版本更新	历史 Run 仍指向原固定版本
T17	删除仍被合法保全的资产	阻止物理删除并说明原因
T18	删除共享 Blob 的一个引用	其他合法引用仍可读取
T19	清理最后一个引用	按策略安全回收 Blob
T20	导出 Markdown → PDF	记录来源版本、转换参数及输出摘要
T21	重复导出请求	幂等或明确生成独立 Job，不混淆结果
T22	导出任务超时	任务可重试，残留临时文件可回收
T23	恶意文件或伪装 MIME 上传	隔离/拒绝，无法通过预览执行恶意内容
T24	文档中包含提示注入文本	检索内容不改变工具权限或系统指令
T25	备份恢复后抽样校验	DB 元数据与 Blob 内容一致
T26	删除后恢复旧备份	删除墓碑/策略可重放，不意外重新公开
T27	工作空间存储配额耗尽	拒绝新增写入，已有资产可按策略读取
T28	大文件分片上传中断恢复	分片校验、过期回收及状态正确
T29	来源图出现循环或错误关联	关系校验阻止不合法血缘或标记异常
T30	敏感文档生成预览与摘要	衍生资产继承适当权限与分类

17.1 验收证据

建议保留测试用例版本、执行时间、测试环境、输入数据、实际输出、数据库断言、对象存储校验、审计记录与缺陷编号。安全测试应包含负面用例；恢复能力必须通过实际恢复演练而不是仅查看备份任务状态来证明。

17.2 尚待回答的工程问题

Studio 是否需要跨工作空间共享同一资产，还是只需同项目内复用？
是否有必须长期保留的引用快照？其许可边界如何确定？
产物审核与人工批准由哪一层持有最终决策权？
用户删除项目后，历史 Run 的审计需求与数据删除请求如何协调？
是否需要在多区域部署，以及哪些数据必须限定驻留区域？
下载流量、索引规模和导出任务量达到什么阈值才值得拆分服务？

附录 A：参考文献与原始资料

以下主要为规范和官方技术文档，提供可核验的实现依据。这些资料不共同定义某个统一的“Agent Platform Data & Assets 标准”；本文对象模型和分层架构属于在其基础上的工程综合与参考设计。

PostgreSQL Documentation - Transactions. www.postgresql.org/docs/current/tutorial-transactions.html （数据库事务与原子性）
PostgreSQL Documentation - Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html （行级访问控制的机制及边界）
PostgreSQL Documentation - Full Text Search. www.postgresql.org/docs/current/textsearch.html （全文检索）
Amazon S3 User Guide - Presigned URLs. docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html （临时对象访问凭据及风险）
Amazon S3 User Guide - Object Versioning. docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html （存储级对象版本）
Amazon S3 User Guide - Lifecycle Management. docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html （对象保留与生命周期操作）
OpenAPI Specification 3.1. spec.openapis.org/oas/v3.1.0.html （HTTP API 契约表达）
JSON Schema - Core Specification. json-schema.org/draft/2020-12/json-schema-core （结构化元数据校验）
RFC 9110 - HTTP Semantics. www.rfc-editor.org/rfc/rfc9110 （HTTP 方法、条件请求、缓存语义）
RFC 7232 - HTTP Conditional Requests. www.rfc-editor.org/rfc/rfc7232 （ETag/条件请求的历史规范；现行语义见 RFC 9110）
NIST SP 800-53 Rev. 5 - Security and Privacy Controls. csrc.nist.gov/pubs/sp/800/53/r5/upd1/final （访问控制、审计、数据保护的控制框架）
NIST SP 800-88 Rev. 1 - Guidelines for Media Sanitization. csrc.nist.gov/pubs/sp/800/88/r1/final （介质清理背景；需核对适用版本与实际存储服务能力）
OWASP API Security Top 10 (2023). owasp.org/API-Security/editions/2023/en/0x11-t10 （对象级授权等 API 风险）
OWASP Top 10 for LLM Applications. genai.owasp.org/llm-top-10 （检索内容提示注入等风险）
W3C PROV-O: The PROV Ontology. www.w3.org/TR/prov-o （实体、活动与主体的来源关系表达）
W3C PROV-DM: The PROV Data Model. www.w3.org/TR/prov-dm （数据血缘与来源概念）
OpenTelemetry Specification. opentelemetry.io/docs/specs/otel （追踪、指标与日志的关联）
SLSA - Supply-chain Levels for Software Artifacts. slsa.dev/spec/v1.0 （工件来源与完整性思路；软件供应链规范不能直接等同于研究报告真实性验证）

参考文献使用说明

PostgreSQL、S3 和 HTTP 文档支持特定底层机制，不意味着 Studio 必须使用这些产品或已完成部署。
W3C PROV 提供来源建模概念；本文简化的 AssetRelation 并非完整 PROV-O 实现。
OWASP 与 NIST 资料用于风险识别与控制设计，不能单凭引用这些资料证明平台符合任何认证或法规。
部分官方文档持续更新，正式工程实施时应固定所依据的文档版本、发布日期与访问日期。

附录 B：研究证据、验证声明与适用边界

B.1 证据分级

类型	本篇内容	证据状态
标准或官方机制	PostgreSQL 事务、HTTP 条件请求、S3 对象生命周期、W3C PROV 概念	有官方资料可核验；具体实现仍需按选型复核
工程综合与设计推论	Asset/Version/Blob 三层模型、模块化架构、上传提交协议、Studio 路线图	参考设计，不是统一行业标准
示例契约	JSON、SQL、API、事件、Mermaid 图	用于说明，不是生产就绪实现
待验证假设	性能、扩展能力、恢复目标、成本、扫描有效性	未开展部署或测试，不作成功声明

B.2 本篇未完成的验证

本文未进行实际平台部署、数据库迁移执行、对象存储上传、跨租户渗透测试、故障注入、备份恢复、压力测试或外部合规审查。测试矩阵为后续工程验收计划，不是已通过的测试报告。

B.3 适用范围

适用于以 Agent、Workflow、Run 和 Artifact 为核心对象的多项目 Agent Platform，尤其适用于研究报告 Studio、企业内部 Agent 工作台和可扩展的协作平台。对于高监管行业、极端规模、实时媒体流、超大规模知识检索或严格跨境数据驻留场景，需要进一步专项设计。

B.4 与后续专题的衔接

P10 解决“平台的数据与成果如何成为受治理的资产”。下一篇 P11 · 如何管理多租户、组织与工作空间隔离？ - Multi-tenancy & Isolation 将重点研究租户模型、组织层级、命名空间、资源隔离、数据隔离、身份边界与跨租户协作，并进一步严格化本篇的 tenant_id、共享授权和存储隔离设计。

P10 · 如何管理平台的数据、产物与共享资产？ - Platform Data & Assets ​

专题导读 ​

研究结论 ​

一、概念、分类与边界 ​

1.1 五类平台数据 ​

1.2 Data、Artifact、Asset、Knowledge、Memory ​

1.3 与 P1 - P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 的职责边界 ​

二、对象模型：逻辑身份、版本与字节 ​

2.1 核心对象 ​

2.2 关系示意 ​

2.3 不变式（Invariants） ​

三、参考总体架构 ​

3.1 分层职责 ​

四、数据模型与元数据契约 ​

4.1 最小资产元数据 ​

4.2 不可变版本元数据 ​

4.3 元数据字段分组 ​

五、存储设计：数据库、对象存储与派生索引 ​

5.1 关系数据库职责 ​

5.2 对象存储与对象键 ​

5.3 索引与缓存 ​

六、上传、提交与产物生成协议 ​

6.1 两阶段内容提交 ​

6.2 产物状态机 ​

6.3 产物契约 ​

七、版本管理、引用与内容寻址 ​

7.1 三种版本概念 ​

7.2 引用策略 ​

7.3 并发更新 ​

八、来源、血缘与可追溯性 ​

8.1 血缘图 ​

8.2 最小来源记录 ​

8.3 来源可信度与完整性 ​

九、资产发现、搜索与知识化 ​

9.1 查询路径 ​

9.2 内容处理流水线 ​

9.3 检索授权与提示注入 ​

十、共享、权限与交付边界 ​

10.1 共享模型 ​

10.2 下载安全 ​

10.3 复制与引用 ​

十一、生命周期：保留、归档、删除与恢复 ​

11.1 参考生命周期 ​

11.2 保留策略 ​

11.3 删除的实际语义 ​

11.4 灾难恢复 ​

十二、交付物管理与导出流水线 ​

12.1 交付包不是普通 ZIP ​

12.2 转换与再生成 ​

12.3 发布与撤回 ​

十三、API 与事件契约 ​

13.1 参考 API ​

13.2 错误契约 ​

13.3 领域事件 ​

十四、安全、隐私与治理 ​

14.1 威胁模型 ​

14.2 数据分类 ​

14.3 数据驻留与合规 ​

十五、可靠性、性能与成本 ​

15.1 关键 SLI ​

15.2 成本来源 ​

15.3 扩展策略 ​

十六、Studio 贯穿案例：研究报告的资产全生命周期 ​

16.1 业务场景 ​

16.2 对象与流程映射 ​

16.3 一次运行的参考时序 ​

16.4 初期最小数据表 ​

16.5 分阶段交付路线 ​

十七、工程验证计划 ​

17.1 验收证据 ​

17.2 尚待回答的工程问题 ​

附录 A：参考文献与原始资料 ​

参考文献使用说明 ​

附录 B：研究证据、验证声明与适用边界 ​

B.1 证据分级 ​

B.2 本篇未完成的验证 ​

B.3 适用范围 ​

B.4 与后续专题的衔接 ​

P10 · 如何管理平台的数据、产物与共享资产？ - Platform Data & Assets

专题导读

研究结论

一、概念、分类与边界

1.1 五类平台数据

1.2 Data、Artifact、Asset、Knowledge、Memory

1.3 与 P1 - P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 的职责边界

二、对象模型：逻辑身份、版本与字节

2.1 核心对象

2.2 关系示意

2.3 不变式（Invariants）

三、参考总体架构

3.1 分层职责

四、数据模型与元数据契约

4.1 最小资产元数据

4.2 不可变版本元数据

4.3 元数据字段分组

五、存储设计：数据库、对象存储与派生索引

5.1 关系数据库职责

5.2 对象存储与对象键

5.3 索引与缓存

六、上传、提交与产物生成协议

6.1 两阶段内容提交

6.2 产物状态机

6.3 产物契约

七、版本管理、引用与内容寻址

7.1 三种版本概念

7.2 引用策略

7.3 并发更新

八、来源、血缘与可追溯性

8.1 血缘图

8.2 最小来源记录

8.3 来源可信度与完整性

九、资产发现、搜索与知识化

9.1 查询路径

9.2 内容处理流水线

9.3 检索授权与提示注入

十、共享、权限与交付边界

10.1 共享模型

10.2 下载安全

10.3 复制与引用

十一、生命周期：保留、归档、删除与恢复

11.1 参考生命周期

11.2 保留策略

11.3 删除的实际语义

11.4 灾难恢复

十二、交付物管理与导出流水线

12.1 交付包不是普通 ZIP

12.2 转换与再生成

12.3 发布与撤回

十三、API 与事件契约

13.1 参考 API

13.2 错误契约

13.3 领域事件

十四、安全、隐私与治理

14.1 威胁模型

14.2 数据分类

14.3 数据驻留与合规

十五、可靠性、性能与成本

15.1 关键 SLI

15.2 成本来源

15.3 扩展策略

十六、Studio 贯穿案例：研究报告的资产全生命周期

16.1 业务场景

16.2 对象与流程映射

16.3 一次运行的参考时序

16.4 初期最小数据表

16.5 分阶段交付路线

十七、工程验证计划

17.1 验收证据

17.2 尚待回答的工程问题

附录 A：参考文献与原始资料

参考文献使用说明

附录 B：研究证据、验证声明与适用边界

B.1 证据分级

B.2 本篇未完成的验证

B.3 适用范围

B.4 与后续专题的衔接