F10 · 用户如何管理任务产物与交付成果？ - Artifact & Delivery Management
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 资产与交付参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：用户如何在 Agent Platform 中发现、预览、审核、整理、编辑、版本化、共享、导出并交付任务产物，同时保证来源可追溯、权限可控、交付结果可验证？
专题导读
本篇属 Product Architecture。Agent Platform 的价值不仅体现在 Agent 是否完成一次 Run，更体现在用户能否将执行结果转化为可理解、可审核、可继续编辑、可复用、可交付的成果。一次研究任务可能产生检索记录、原始网页摘录、结构化分析、报告草稿、审稿意见、最终 Markdown、PDF 和交付包。这些内容在业务含义、质量状态、保留期限与访问权限上并不相同。
F10 从用户可见的产品功能研究 Artifact & Delivery Management。底层存储、Blob 去重、元数据与数据血缘属于 P10 Platform Data & Assets；F10 重点回答用户看到什么、怎样操作、何时可以交付、如何确认交付成功，以及错误发生后如何恢复。
证据边界：文中关于 HTTP、对象存储、内容摘要、安全与可访问性的原理依据公开规范；具体页面布局、状态机、接口和数据模型是面向 Studio 的参考设计，不代表既有平台标准，也未进行生产验证。
研究结论
- 应明确区分 Execution Output（执行输出）→ Artifact（受管理的任务产物）→ Deliverable（明确面向接收方的交付成果）→ Delivery（一次实际交付行为）；这些对象可以关联但不应混同。
- 产品功能至少覆盖 产物发现、预览、审核、编辑与修订、版本比较、集合整理、导出、交付、追溯、权限与保留 十项能力。
- 产物的执行状态、内容质量状态、审核状态、发布状态、交付状态必须独立展示。Run 成功不能自动推断报告可信或已交付。
- 正式交付必须固定不可变的产物版本及其文件摘要；任何交付后编辑应生成新版本或新交付记录，不能静默覆盖已交付内容。
- 用户应能从成果反向追踪到 Run、Step Run、Agent Version、Workflow Version、输入资料与审核证据；但记录来源并不自动证明事实正确。
- Studio 初期优先实现 Run 产物列表、Markdown 预览、草稿修订、审核状态、不可变版本、Markdown/PDF 导出、受控下载与交付记录。
01 · 定义、对象与职责边界
1.1 关键术语
| 对象 | 定义 | 典型示例 | 用户操作 |
|---|---|---|---|
| Execution Output | Agent 或工具执行时产生的原始输出 | 模型文本、工具 JSON、临时日志 | 查看、诊断、筛选保留 |
| Artifact | 具有身份、元数据和访问控制的任务产物 | 调研笔记、报告草稿、图表文件 | 预览、整理、修订、审核 |
| Asset | 具有独立生命周期、可被复用的受管理资产 | 正式研究报告、共享数据集 | 收藏、引用、共享、归档 |
| Artifact Version | 产物在某时点固定的内容与元数据快照 | report@v3 | 对比、回溯、引用 |
| Deliverable | 为某个接收方或交付目的选定的成果版本集合 | 报告 PDF + 附件 ZIP | 组包、确认、批准 |
| Delivery | 将特定 Deliverable 提供给接收方的动作与记录 | 私有下载、发送受控链接 | 查看状态、撤销访问、重试 |
| Export Job | 将源产物转换为指定格式的异步作业 | Markdown → PDF | 配置、运行、查看错误 |
约束：临时执行输出并不都需要长期保存；Artifact 也不一定成为共享 Asset；Deliverable 是业务语义，不能简单等同于某个 Blob。
1.2 与相邻专题的分工
| 专题 | 主要职责 | F10 产品衔接 |
|---|---|---|
| F6 Agent Execution | 启动、控制 Run | 从运行详情打开产物、查看生成进度 |
| F7 Agent Collaboration | 多 Agent 交接与审核 | 汇总不同节点的产物和审核意见 |
| F8 Agent Monitoring | 运行、质量与成本监控 | 从质量告警跳转到具体产物版本 |
| F5 Workspace & Project Management | 项目组织与归属 | 按项目管理成果、文件夹和交付记录 |
| F4 Agent Publishing & Sharing | Agent 本身的发布与共享 | 不替代研究成果的发布 |
| P10 Platform Data & Assets | 存储、索引、版本、数据血缘 | 提供元数据、内容、索引、权限和下载能力 |
| P12 Platform Governance | 策略、审批、审计 | 执行交付门禁、权限与敏感内容策略 |
02 · 用户角色、任务与核心场景
| 角色 | 主要目标 | 关键疑问 | 关键动作 |
|---|---|---|---|
| 业务用户 | 取得可用成果 | 哪个文件是最终版？ | 预览、下载、确认接收 |
| 研究作者 | 迭代报告内容 | 哪些段落需要修改？ | 编辑、保存修订、比较版本 |
| 审核者 | 判断能否发布 | 引用是否核验、结论是否充分？ | 评论、批准、驳回、要求返工 |
| 项目负责人 | 组织交付 | 哪些成果齐备、谁负责？ | 组包、指派、批准交付 |
| 平台开发者 | 追查生成与导出故障 | 文件从哪一步产生？ | 查看血缘、导出日志、错误代码 |
| 管理员 | 保护数据与审计 | 是否越权共享或超期保留？ | 配置策略、撤销链接、审计 |
典型任务包括：研究报告生成后审核并导出；多 Agent 分别生成数据表、图表和正文后汇总；同一成果以多种格式交付；客户要求更正已交付版本；分享链接到期或接收方权限被撤销；导出任务失败后安全重试。
03 · 产品功能与信息架构
3.1 功能域
| 功能域 | 用户界面 | MVP 必要能力 | 后续增强 |
|---|---|---|---|
| 产物中心 | Project / Artifacts | 列表、搜索、类型筛选、归属 | 语义检索、智能分组 |
| 产物详情 | Artifact Detail | 预览、元数据、来源、状态 | 多格式并排、质量趋势 |
| 版本历史 | Versions | 查看版本、差异、恢复为新草稿 | 多分支编辑、合并 |
| 审核工作台 | Review | 评论、通过、驳回、返工 | 多级审批、规则化门禁 |
| 导出中心 | Exports | 选择格式、发起导出、下载 | 模板市场、批量转换 |
| 交付中心 | Deliveries | 组包、接收方、记录、状态 | 外部客户门户、签收 |
| 权限与共享 | Share | 受控链接、到期时间、撤销 | 水印、数据分级策略 |
| 审计与追溯 | Provenance / Activity | Run、Agent、输入引用 | 证据图谱、差异影响分析 |
3.2 推荐导航
flowchart TD
W[Workspace] --> P[Project]
P --> R[Runs]
P --> A[Artifacts]
P --> D[Deliveries]
R --> RD[Run Detail]
RD --> A
A --> AD[Artifact Detail]
AD --> V[Versions]
AD --> Q[Review]
AD --> E[Export]
AD --> S[Share]
D --> DD[Delivery Detail]
DD --> AD产品应提供两个互补入口：从 Run 找产物，适合追踪某次执行；从 Project 找成果，适合日常管理与交付。避免将全部输出埋在聊天消息或 Trace 中。
3.3 产物列表的最小字段
名称、类型、当前版本、所属项目、创建来源、创建时间、最近修改、审核状态、交付状态、负责人。支持按项目、Run、类型、审核状态、时间和关键词筛选；用户没有权限的产物不应通过搜索结果泄露名称或摘要。
04 · 核心对象模型与关系
erDiagram
PROJECT ||--o{ RUN : contains
RUN ||--o{ STEP_RUN : contains
STEP_RUN ||--o{ ARTIFACT : produces
ARTIFACT ||--o{ ARTIFACT_VERSION : has
ARTIFACT_VERSION ||--o{ REVIEW : receives
ARTIFACT_VERSION ||--o{ EXPORT_JOB : source
EXPORT_JOB ||--o| EXPORT_FILE : creates
PROJECT ||--o{ DELIVERABLE : owns
DELIVERABLE ||--|{ DELIVERABLE_ITEM : includes
ARTIFACT_VERSION ||--o{ DELIVERABLE_ITEM : selected
EXPORT_FILE ||--o{ DELIVERABLE_ITEM : selected
DELIVERABLE ||--o{ DELIVERY : sent_as
DELIVERY ||--o{ DELIVERY_EVENT : records推荐的稳定标识：artifact_id 标识长期逻辑产物；artifact_version_id 标识不可变内容版本；deliverable_id 标识一次交付集合；delivery_id 标识交付行为。展示用 v1/v2 可递增，但内部引用应使用稳定 ID。
4.1 来源与归属
每个 Artifact 至少关联 tenant_id、workspace_id、project_id、created_by、source_run_id（如由 Run 生成）、media_type、classification 和 current_version_id。允许用户手动上传产物，此时 source_run_id 可以为空，但应记录上传者与来源声明。
4.2 版本不可变与编辑
编辑器修改的是可变 Draft；保存并提交形成新的不可变 Artifact Version。若要“恢复旧版”，应创建基于旧版内容的新版本，而不是改写历史版本。版本记录至少包含 content_hash、blob_ref、parent_version_id、created_at、created_by、change_summary。
05 · 产物生命周期与状态机
5.1 分离的状态维度
| 维度 | 示例状态 | 由谁负责 |
|---|---|---|
| 生成状态 | GENERATING / READY / GENERATION_FAILED | Run / Artifact Service |
| 内容修订状态 | DRAFT / FROZEN | 编辑器与版本服务 |
| 质量评估状态 | NOT_EVALUATED / PASSED / FAILED / INCONCLUSIVE | Evaluation Service |
| 审核状态 | NOT_SUBMITTED / IN_REVIEW / CHANGES_REQUESTED / APPROVED / REJECTED | Review Service |
| 发布状态 | PRIVATE / RELEASED / WITHDRAWN | Asset / Publication Service |
| 交付状态 | NOT_DELIVERED / PREPARING / AVAILABLE / EXPIRED / REVOKED / FAILED | Delivery Service |
不同产品可采用其他枚举，但必须有明确语义。尤其不能把 APPROVED 等同于 DELIVERED。
5.2 审核流程
stateDiagram-v2
[*] --> DRAFT
DRAFT --> IN_REVIEW: 提交审核
IN_REVIEW --> CHANGES_REQUESTED: 要求修改
CHANGES_REQUESTED --> DRAFT: 创建新草稿修订
IN_REVIEW --> APPROVED: 审核通过
IN_REVIEW --> REJECTED: 拒绝
APPROVED --> [*]
REJECTED --> DRAFT: 重写并重新提交审核决策必须绑定 artifact_version_id，而不是仅绑定 artifact_id。一旦内容发生修改，旧版的审核通过不能自动继承给新版。若确需轻微修改豁免，应建立显式规则、审批和审计记录。
06 · 产物发现、预览与阅读体验
6.1 类型化预览
- Markdown：渲染阅读与原文切换；代码块、表格、脚注和引用链接可访问。
- PDF：分页阅读、页码、文件大小和版本标识；不得仅凭 PDF 生成成功断言排版正确。
- 图片：尺寸、格式、缩放和替代文本；预览与原文件下载分离。
- CSV / 表格：限制行数的安全预览、列类型提示、下载完整文件。
- JSON：折叠结构、Schema 提示、敏感字段遮蔽。
- ZIP：显示包内清单和总大小；不应在未经安全处理的情况下自动解压或执行内容。
所有用户上传和模型生成内容都应作为不可信内容处理。Markdown 中的 HTML、外链资源、脚本、公式渲染等应遵循明确的净化与内容安全策略。文件预览不能获得宿主应用的高权限执行上下文。
6.2 阅读中的证据提示
研究类成果应支持段落级或章节级来源标记、参考文献跳转、证据状态（已核验 / 推论 / 未验证）和来源失效提示。产品应避免用“有引用链接”代替“事实已核验”。对外部网页、模型生成摘要和用户上传文档，应显示来源类型和采集时间。
07 · 编辑、修订与版本比较
7.1 编辑方式
提供 Markdown 原文编辑、富文本编辑（可选）和外部编辑后重新导入三种模式。对于结构复杂的研究文档，优先保证 Markdown 的无损往返，避免表格、代码块、引用和脚注在格式转换时丢失。
7.2 并发控制
编辑提交应携带 Draft Revision 或 If-Match / ETag。发生冲突时提示“他人已更新”，允许查看差异、另存草稿或人工合并，禁止最后写入者无提示覆盖。自动保存成功与“正式提交版本”必须有不同反馈。
7.3 版本比较
用户至少能比较：正文差异、文件摘要、作者与修改时间、来源 Run、审核状态、交付使用情况。版本差异属于文本比较，不等同于语义或事实质量评估；重要结论的修改需要重新审核。
08 · 审核、评论与质量门禁
8.1 审核对象与意见结构
审核请求包含产物版本、审核人、审核规则、截止时间和状态。审核意见建议包括 section_anchor、category、severity、comment、evidence_refs 和 resolution_status。锚点在版本变化后可能失效，系统应保留原始版本引用并提示重新定位。
8.2 研究报告质量维度
| 维度 | 检查问题 | 证据 |
|---|---|---|
| 完整性 | 是否覆盖约定章节与交付范围？ | 章节检查清单 |
| 事实性 | 关键结论是否有可核验依据？ | 来源与核验记录 |
| 引用质量 | 引用是否支持相应断言？ | 逐条证据映射 |
| 一致性 | 术语、编号、图表是否一致？ | 结构校验报告 |
| 安全与合规 | 是否包含不应外发的信息？ | 数据分级、脱敏检查 |
| 可读性 | 目标读者能否理解并使用？ | 人工审阅与可用性反馈 |
| 格式 | PDF、Markdown 是否正确？ | 渲染检查、文件验证 |
自动检查可作为辅助门禁；关键事实性与高风险外发仍可能需要人工复核。LLM-as-a-judge 的结果应保留评估器版本、提示词、输入范围和不确定性。
09 · 交付物组包与格式导出
9.1 Deliverable 构成
一个 Deliverable 可以包含：主报告、数据附件、图片图表、参考文献清单、变更说明和交付清单。每个条目绑定具体 artifact_version_id 或 export_file_id，记录文件名、内容摘要、大小、格式和展示顺序。
9.2 导出作业
flowchart LR
A[选定 Artifact Version] --> B[选择导出模板/格式]
B --> C[预检权限与依赖]
C --> D[创建 Export Job]
D --> E[隔离转换 Worker]
E --> F[验证文件/计算摘要]
F --> G[保存 Export File]
G --> H[预览/加入 Deliverable]
E --> I[失败日志与重试]建议将转换设为异步任务，支持 QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELED。转换输入必须固定版本，不能在任务排队期间自动跟随“最新草稿”。
9.3 导出格式与限制
| 格式 | 用途 | 主要风险 |
|---|---|---|
| Markdown | 可继续编辑、纳入知识库 | 相对路径、图片依赖、扩展语法差异 |
| 固定版式阅读与提交 | 字体替换、分页、链接、可访问性 | |
| HTML | 在线阅读、嵌入网站 | 脚本注入、外部资源与 CSP |
| DOCX | 协作编辑与正式文档 | 样式映射、复杂表格与修订语义 |
| CSV/XLSX | 结构化数据交付 | 公式注入、编码、类型误判 |
| ZIP | 多文件交付 | 路径穿越、压缩炸弹、缺失文件 |
PDF 转换成功后，至少检查文件存在、可打开、页数非零、主要标题可见及预期附件/链接情况。生产场景可增加自动化渲染对比与抽样人工验收。
10 · 交付流程、接收与撤销
10.1 标准流程
选择成果版本 → 检查审核与权限 → 创建 Deliverable → 生成交付文件 → 审核交付清单 → 确认接收方 → 发起 Delivery → 记录状态与证据。
交付前界面应明确显示版本、格式、文件数量、数据分类、接收方、访问有效期和审批状态。对外发出后，系统记录交付时间、操作者、文件摘要和链接状态。
10.2 交付状态
stateDiagram-v2
[*] --> PREPARING
PREPARING --> READY: 文件与门禁通过
PREPARING --> FAILED: 生成或校验失败
READY --> AVAILABLE: 创建受控访问
AVAILABLE --> EXPIRED: 到期
AVAILABLE --> REVOKED: 撤销访问
AVAILABLE --> ACKNOWLEDGED: 接收方确认
FAILED --> PREPARING: 修复后重试AVAILABLE 仅表示访问渠道已建立，不代表接收方已下载或阅读。ACKNOWLEDGED 必须有明确的接收确认机制，不能根据页面访问量推断。
10.3 撤销边界
撤销受控链接可以阻止后续授权访问，但不能删除接收方此前下载的副本。已交付内容发现错误时，应采用更正通知 + 新交付版本 + 旧交付标记被替代的机制，保留审计记录。
11 · 权限、安全与数据治理
11.1 权限矩阵（示例）
| 操作 | 作者 | 审核人 | 项目负责人 | 外部接收方 |
|---|---|---|---|---|
| 查看项目内产物 | 依授权 | 依授权 | 依授权 | 否 |
| 编辑草稿 | 是 | 通常否 | 依授权 | 否 |
| 提交审核 | 是 | 依授权 | 是 | 否 |
| 批准版本 | 通常否（职责分离） | 是 | 依策略 | 否 |
| 创建对外交付 | 依策略 | 通常否 | 是 | 否 |
| 下载指定交付文件 | 依授权 | 依授权 | 是 | 仅被授权版本 |
| 撤销共享 | 依授权 | 依授权 | 是 | 否 |
这是参考角色矩阵；实际授权需结合 Tenant、Workspace、Project、数据分类和组织策略。禁止只在前端隐藏按钮而不在服务端校验。
11.2 安全控制
- 上传：限制大小和类型，进行内容检测与恶意文件扫描；不能仅信任文件扩展名。
- 预览：隔离不可信 HTML/Markdown，避免 XSS、外链泄漏与自动执行。
- 导出：沙箱化转换器，限制 CPU、内存、网络和文件系统权限。
- 下载：私有对象存储、短时签名 URL 或代理下载、对象级授权。
- 分享：到期、撤销、最小访问范围、必要时接收方身份验证。
- 审计：记录查看、下载、导出、批准、共享、撤销等敏感操作；日志中不写入密钥和完整敏感内容。
- 数据保留：按策略设置保留、归档、删除；遵守合法保留要求和备份删除延迟。
- 搜索：索引和向量检索应执行与源资产一致的权限过滤。
12 · 来源追溯、可重复性与证据链
12.1 最小血缘链
flowchart TD
I[Input Asset Versions] --> W[Workflow Version / Run]
W --> S[Step Run / Attempt]
AG[Agent Version] --> S
S --> AV[Artifact Version]
AV --> RV[Review Decision]
AV --> EJ[Export Job]
EJ --> EF[Export File]
EF --> DV[Deliverable]
RV --> DV
DV --> DL[Delivery]产物详情应能回答：谁创建了它？由哪个 Agent 和 Workflow 版本产生？使用了哪些输入版本？是否经过人工编辑？谁审核了哪个版本？导出了哪些格式？交付给谁？
12.2 可追溯不等于可完全复现
即使固定了 Agent Version 和输入资料，外部模型、搜索结果、第三方 API、时间依赖与非确定性采样仍可能导致结果不同。产品应区分“有完整来源记录”“可重新执行”“能得到字节级相同输出”三种保证，不应作无依据的可重复性承诺。
13 · 平台技术架构映射
flowchart TB
UI[Artifact / Review / Delivery UI] --> API[Platform API]
API --> AUTH[Governance / Authorization]
API --> AS[Artifact Service]
API --> RS[Review Service]
API --> DS[Delivery Service]
API --> ES[Export Service]
AS --> DB[(PostgreSQL Metadata)]
AS --> OBJ[(Private Object Storage)]
RS --> DB
DS --> DB
ES --> Q[(Job Queue)]
Q --> WK[Sandboxed Export Worker]
WK --> OBJ
API --> AUD[Audit Events]
AS --> IDX[Search Index]初期可以采用模块化单体服务实现 Artifact、Review、Export、Delivery 四个模块，避免为每个功能建立独立微服务。导出 Worker 应与 Web/API 进程隔离，以控制文件转换的资源与安全风险。
13.1 一致性策略
元数据写入与对象存储操作无法天然构成一个跨系统数据库事务。建议采用 PENDING_UPLOAD → VERIFIED → AVAILABLE 的显式状态、内容摘要校验、幂等提交与后台对账。交付记录应先冻结条目清单，再创建下载权限；避免“交付已成功但文件仍未就绪”。
14 · API 与数据契约（参考设计）
14.1 核心 API
| 方法 | 路径 | 功能 |
|---|---|---|
| GET | /v1/projects/{project_id}/artifacts | 查询产物列表 |
| GET | /v1/artifacts/{artifact_id} | 产物详情与权限信息 |
| GET | /v1/artifacts/{artifact_id}/versions | 版本历史 |
| POST | /v1/artifacts/{artifact_id}/versions | 提交新不可变版本 |
| POST | /v1/artifact-versions/{version_id}/reviews | 发起审核 |
| POST | /v1/reviews/{review_id}/decisions | 提交审核决定 |
| POST | /v1/exports | 创建导出作业 |
| GET | /v1/exports/{export_id} | 查询导出状态 |
| POST | /v1/deliverables | 创建交付集合 |
| POST | /v1/deliverables/{id}/items | 固定交付条目 |
| POST | /v1/deliveries | 发起交付 |
| POST | /v1/deliveries/{id}/revoke | 撤销后续访问 |
| GET | /v1/deliveries/{id}/events | 查询交付事件 |
以上路径仅是参考设计，不是公开标准。所有写操作应校验主体、租户、项目、资源版本及策略；对可能重复提交的操作支持幂等键。
14.2 Artifact Version 示例
{
"artifact_id": "art_report_001",
"artifact_version_id": "av_003",
"version_label": "v3",
"project_id": "project_agent_map",
"media_type": "text/markdown",
"content_hash": "sha256:<64-hex-digest>",
"blob_ref": "private://tenant-a/artifacts/art_report_001/v3.md",
"source": {
"workflow_run_id": "wr_102",
"step_run_id": "sr_write_08",
"agent_version_id": "agent_writer_v7",
"input_artifact_version_ids": ["av_research_009", "av_analysis_005"]
},
"review_status": "APPROVED",
"classification": "INTERNAL",
"created_at": "2026-11-01T08:00:00Z"
}blob_ref 应为内部引用，不应作为未经授权即可访问的公开 URL。摘要示例是占位符，不代表实际计算结果。
14.3 创建交付示例
{
"project_id": "project_agent_map",
"deliverable_name": "Agent Platform 研究报告交付包",
"items": [
{"artifact_version_id": "av_003", "role": "primary_report"},
{"export_file_id": "ef_pdf_003", "role": "pdf_copy"}
],
"recipient": {"type": "workspace_member", "id": "member_42"},
"access": {"mode": "authenticated", "expires_at": "2026-11-15T00:00:00Z"}
}交付接口应拒绝未就绪的导出文件、未授权接收方、被撤销版本和不满足审核门禁的条目，并返回可解释的错误原因。
15 · PostgreSQL 参考数据模型
下述 SQL 是说明性骨架，省略完整的租户 RLS、所有外键、迁移策略和索引；不得直接视为可上线的完整 Schema。
CREATE TABLE artifacts (
tenant_id UUID NOT NULL,
artifact_id UUID PRIMARY KEY,
project_id UUID NOT NULL,
name TEXT NOT NULL,
media_type TEXT NOT NULL,
classification TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE artifact_versions (
tenant_id UUID NOT NULL,
artifact_version_id UUID PRIMARY KEY,
artifact_id UUID NOT NULL REFERENCES artifacts(artifact_id),
version_no INTEGER NOT NULL,
blob_key TEXT NOT NULL,
sha256 CHAR(64) NOT NULL,
source_run_id UUID,
created_by UUID NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (artifact_id, version_no)
);
CREATE TABLE artifact_reviews (
tenant_id UUID NOT NULL,
review_id UUID PRIMARY KEY,
artifact_version_id UUID NOT NULL REFERENCES artifact_versions(artifact_version_id),
reviewer_id UUID NOT NULL,
decision TEXT NOT NULL,
comment TEXT,
decided_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE export_jobs (
tenant_id UUID NOT NULL,
export_job_id UUID PRIMARY KEY,
artifact_version_id UUID NOT NULL REFERENCES artifact_versions(artifact_version_id),
target_format TEXT NOT NULL,
status TEXT NOT NULL,
result_blob_key TEXT,
error_code TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE deliverables (
tenant_id UUID NOT NULL,
deliverable_id UUID PRIMARY KEY,
project_id UUID NOT NULL,
name TEXT NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE deliverable_items (
tenant_id UUID NOT NULL,
deliverable_id UUID NOT NULL REFERENCES deliverables(deliverable_id),
item_no INTEGER NOT NULL,
artifact_version_id UUID REFERENCES artifact_versions(artifact_version_id),
export_job_id UUID REFERENCES export_jobs(export_job_id),
PRIMARY KEY (deliverable_id, item_no),
CHECK ((artifact_version_id IS NOT NULL) <> (export_job_id IS NOT NULL))
);
CREATE TABLE deliveries (
tenant_id UUID NOT NULL,
delivery_id UUID PRIMARY KEY,
deliverable_id UUID NOT NULL REFERENCES deliverables(deliverable_id),
recipient_ref TEXT NOT NULL,
status TEXT NOT NULL,
expires_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);工程补充：生产实现应使用复合外键或等价约束保证所有关联对象属于同一租户；仅添加 tenant_id 列不能阻止跨租户关联。已发布版本的不可变性需通过权限、数据库约束或受控写入流程保障；单纯的 UNIQUE 约束并不能阻止 UPDATE。对交付条目还需冻结导出结果摘要，防止引用可变导出作业记录。
16 · Studio 贯穿案例：从研究草稿到正式交付
16.1 业务设定
Studio 的 Agent 技术地图研究项目使用选题 Agent、调研 Agent、分析 Agent、审核 Agent 和写作 Agent 协作。每个节点可以生成多个产物，用户最终需要一份 Markdown 研究文章、可阅读 PDF 和可追溯的参考文献清单。
16.2 完整用户旅程
- 研究执行：调研 Agent 输出检索摘要与来源清单；写作 Agent 输出
draft.md。Run 详情显示对应产物。 - 产物登记：平台将需要保留的输出登记为 Artifact，关联 Agent Version、Step Run 和输入资料版本。
- 作者修订：用户在产物详情打开 Markdown，修订术语、结构和证据，提交
v2，并填写修改摘要。 - 审核返工：审核 Agent 或人工审核者针对
v2提出“引用无法支持结论”的问题；系统保留意见并将任务返回作者。 - 重新提交：作者生成
v3，修复引用并提交审核。v2的审核状态不自动迁移至v3。 - 批准：审核者批准
v3，平台记录审核身份、时间、版本和检查清单。 - 导出：用户选择
v3导出 PDF；转换 Worker 输出 PDF 文件、摘要和验证结果。 - 组包：创建 Deliverable，固定
v3Markdown、对应 PDF 和参考资料清单。 - 交付：负责人选择受控共享链接和接收方，平台验证权限、分类、审批与有效期后创建 Delivery。
- 追踪与更正：交付记录显示文件版本和访问状态；若发现错误，发布
v4和新的交付记录，并标记旧交付被替代。
16.3 Studio 页面建议
Project / Agent 技术地图
├── Overview
├── Runs
│ └── Run Detail → Outputs
├── Artifacts
│ ├── All Artifacts
│ └── Artifact Detail
│ ├── Preview / Edit
│ ├── Versions / Diff
│ ├── Review / Comments
│ └── Provenance
└── Deliveries
├── Export Jobs
├── Deliverable Builder
└── Delivery History交互重点：用户进入报告详情时，首先看到清晰的“当前工作草稿”“最新审核通过版本”“最近交付版本”，而不是只有一个模糊的“最新版”。
16.4 Studio MVP 的优先级
| 优先级 | 功能 | 最小验收标准 |
|---|---|---|
| P0 | Run 产物关联 | 从 Run 能定位其生成的文件 |
| P0 | Markdown 预览与下载 | 内容完整，权限正确 |
| P0 | 不可变版本 | 历史版本不可被静默覆盖 |
| P0 | 审核状态 | 审核决定绑定具体版本 |
| P0 | PDF 异步导出 | 可查询状态、下载、查看失败原因 |
| P0 | 交付记录 | 固定文件版本、接收方和时间 |
| P1 | 版本 Diff | 可比较正文差异 |
| P1 | 评论与返工 | 版本化审核意见与闭环 |
| P1 | 受控分享 | 过期与撤销后不可继续访问 |
| P1 | 来源追溯 | 展示 Agent、Run、输入版本 |
| P2 | 多人协作编辑 | 并发冲突可见且可恢复 |
| P2 | 批量导出与模板 | 复杂格式及品牌模板 |
17 · 异常场景与失败恢复
| 场景 | 用户可见反馈 | 系统处理原则 |
|---|---|---|
| Run 成功但没有可保留产物 | 显示“执行完成，无正式产物” | 不凭空创建文件 |
| 上传成功但摘要校验失败 | 显示“文件校验失败” | 不发布为可下载版本 |
| 审核期间草稿被修改 | 提示“审核版本已变化” | 审核固定版本，要求重新提交 |
| 导出 PDF 失败 | 错误类型、重试入口 | 保留源版本，隔离重试 |
| 导出任务重复提交 | 返回已有作业或去重结果 | 幂等键 + 唯一约束 |
| 交付包中某文件不可用 | 禁止完成交付并列出问题 | 交付前逐项预检 |
| 分享链接已过期 | 显示过期及重新申请方式 | 服务端拒绝下载 |
| 用户失去项目权限 | 访问被拒绝 | 即时授权检查、缓存失效 |
| 已交付报告需要更正 | 提示发布更正版 | 保留旧交付证据，不覆盖 |
| 对象存储短暂不可用 | “暂时无法下载” | 有界重试、告警与对账 |
| 预览内容含恶意脚本 | 安全预览或禁止预览 | 不可信内容隔离 |
| 文件被删除但仍受保留策略约束 | 显示“不可删除”及原因 | 策略优先、审计记录 |
18 · 产品指标、研究方法与开发路线
18.1 指标体系
- 成果可达性：用户从 Run 完成到找到正式产物的时间；产物检索成功率。
- 审核效率：从提交审核到决定的时间、返工轮次、审核积压量。
- 导出可靠性：导出成功率、失败原因分布、平均耗时、重复任务比例。
- 交付可靠性：交付预检失败率、不可访问链接比例、交付更正率。
- 质量可追溯性：可关联来源 Run 的版本比例、审核版本绑定完整率。
- 安全性：越权下载拦截、过期链接访问拒绝、敏感文件外发审批覆盖。
这些指标需要按项目规模、格式复杂度和用户场景分层观察；不应在未采集基线数据前随意规定统一的“行业标准阈值”。
18.2 用户研究方法
邀请研究作者、审核者、项目负责人和成果接收方完成典型任务：找到最新批准版本、对比两个版本、提出审核意见、导出 PDF、撤销共享、定位某段结论的来源。观察任务完成率、错误、耗时和对状态的误解，再迭代信息架构。
18.3 分阶段路线
| 阶段 | 目标 | 交付 |
|---|---|---|
| Phase 1 | 产物可见、可下载 | Artifact 列表、详情、Run 关联 |
| Phase 2 | 可修订、可审核 | Draft、不可变版本、审核状态 |
| Phase 3 | 可导出、可交付 | 异步转换、交付包、受控链接 |
| Phase 4 | 可协作、可追溯 | 评论、Diff、血缘、审计 |
| Phase 5 | 可规模化治理 | 批量操作、复杂策略、外部交付门户 |
19 · 工程验证矩阵（待执行）
以下均为拟议验收测试，不是已执行测试结果。
| 编号 | 测试场景 | 预期结果 |
|---|---|---|
| T01 | Run 生成 Markdown | 产物关联正确 Run/Step Run |
| T02 | Run 生成多个文件 | 列表展示全部受管理产物 |
| T03 | Run 无正式产物 | 不显示虚构文件 |
| T04 | 手动上传文件 | 来源类型为用户上传 |
| T05 | 非法 MIME / 超限文件 | 拒绝并说明原因 |
| T06 | 文件摘要不匹配 | 不进入可用状态 |
| T07 | 未授权项目访问列表 | 不返回受限产物 |
| T08 | 未授权直接访问下载 URL | 服务端拒绝 |
| T09 | Markdown 含恶意 HTML | 不执行脚本 |
| T10 | JSON 含敏感字段 | 按策略遮蔽 |
| T11 | 保存新草稿修订 | 不修改已发布版本 |
| T12 | 并发修改同一草稿 | 发生冲突并提示 |
| T13 | 查看两个版本 Diff | 展示对应版本差异 |
| T14 | 恢复旧版内容 | 创建新版本，不覆盖历史 |
| T15 | 审核绑定版本 v2 | 仅 v2 获得审核决定 |
| T16 | v2 通过后修改为 v3 | v3 不自动继承批准 |
| T17 | 无权限用户审批 | 审批被拒绝并审计 |
| T18 | 导出源版本在排队时更新 | 作业仍使用固定源版本 |
| T19 | PDF 导出成功 | 文件可打开且摘要存在 |
| T20 | PDF 转换器失败 | 作业 FAILED 且保留诊断信息 |
| T21 | 同一导出请求重复提交 | 按幂等语义处理 |
| T22 | 导出包含恶意外链 | 按网络与内容策略阻断 |
| T23 | 交付包包含未就绪文件 | 禁止交付 |
| T24 | 交付包包含未经批准版本 | 按策略拒绝 |
| T25 | 交付创建成功 | 固定清单、摘要和接收方 |
| T26 | 接收方无授权 | 无法下载 |
| T27 | 分享链接到期 | 下载被拒绝 |
| T28 | 分享链接被撤销 | 后续下载被拒绝 |
| T29 | 已下载文件后撤销 | 系统不虚称远端副本删除 |
| T30 | 交付后更正报告 | 产生新版本与交付记录 |
| T31 | 数据保留期未结束请求删除 | 按策略拒绝 |
| T32 | 对象存储暂时不可用 | 可恢复错误与有界重试 |
| T33 | 搜索受限文件 | 不泄露名称与摘要 |
| T34 | 跨租户交付条目关联 | 数据层与服务层拒绝 |
| T35 | 审核与交付操作 | 审计记录主体、时间、对象 |
| T36 | 多次重试交付 | 不产生重复不可控外发 |
| T37 | 大型 ZIP / 解压炸弹 | 限制资源并拒绝危险处理 |
| T38 | 版本血缘查询 | 能追溯 Agent、Run、输入版本 |
| T39 | 导出结果被意外覆盖 | 摘要/不可变约束阻断 |
| T40 | 交付包缺少主报告 | 按交付规则提示缺失 |
20 · 局限、开放问题与研究反思
- 编辑器边界：Markdown 原文编辑可保证技术可控，但复杂富文本、批注和实时协作会显著增加版本与格式转换复杂度。
- 审核可信度：模型自动评估可降低重复劳动，但不能替代关键事实的独立核验；审查规则也需要随研究任务变化。
- 多格式一致性：PDF、DOCX、HTML 之间无法天然保证完全一致；应定义“内容一致”和“版式一致”的不同验收标准。
- 数据生命周期：删除和撤销共享涉及对象存储副本、备份、缓存和接收方已下载文件；产品需准确说明保证边界。
- 资产颗粒度：每个中间模型输出是否都要成为 Artifact，取决于追溯价值、成本和数据保留要求；不宜无差别永久保存。
- 交付责任：平台可以证明交付文件的版本、摘要和访问事件，但不能仅凭系统日志证明接收方已理解内容。
- 后续研究：可继续研究内容级证据图谱、协作式版本合并、客户签收、电子签名、结构化交付模板与跨平台互操作。
跨章节契约修订说明（v1.3-r1，2026-11-01）
本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。
不可变版本与审核： [平台设计决策] 审核绑定 artifact_version_id 和内容摘要；新版本不自动继承旧版本的审核通过结果。交付 Manifest 固定一组不可变版本；交付成功与接收方阅读/认可分开。
跨存储一致性： [架构推论/待测试] 对象存储与 PostgreSQL 不应假定单事务原子提交；建议 PENDING_UPLOAD → VERIFIED → AVAILABLE，验证摘要、过期临时文件清理、孤儿对象对账和并发更新。未经对象存储故障注入、租户权限及版本竞争测试，不得宣称安全交付已通过工程验证。
附录 A：参考文献与原始资料
以下优先列出规范、官方文档与安全指南。引用支撑相关技术原则；本篇提出的产品分类、页面方案、字段和状态机为综合设计，不是这些资料直接规定的 Agent Platform 产品标准。
- RFC 9110 - HTTP Semantics. IETF. HTTP 状态、资源语义、条件请求等。www.rfc-editor.org/rfc/rfc9110
- RFC 9111 - HTTP Caching. IETF. 缓存与验证器相关语义。www.rfc-editor.org/rfc/rfc9111
- RFC 6902 - JSON Patch. IETF. 结构化 JSON 文档的补丁表达。www.rfc-editor.org/rfc/rfc6902
- RFC 9457 - Problem Details for HTTP APIs. IETF. 标准化 API 错误响应。www.rfc-editor.org/rfc/rfc9457
- OpenAPI Specification 3.1. OpenAPI Initiative. HTTP API 契约描述。spec.openapis.org/oas/v3.1.0
- JSON Schema - Specification. JSON Schema. 结构化对象校验。json-schema.org/specification
- PostgreSQL Documentation - Transaction Isolation. PostgreSQL Global Development Group. www.postgresql.org/docs/current/transaction-iso.html
- PostgreSQL Documentation - Row Security Policies. PostgreSQL Global Development Group. www.postgresql.org/docs/current/ddl-rowsecurity.html
- Amazon S3 User Guide - Using presigned URLs. AWS. 临时授权访问对象的实现参考。docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
- OWASP File Upload Cheat Sheet. OWASP. 文件上传安全控制。cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
- OWASP Cross Site Scripting Prevention Cheat Sheet. OWASP. 不可信内容安全呈现。cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
- OWASP Authorization Cheat Sheet. OWASP. 授权与最小权限原则。cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
- W3C Web Content Accessibility Guidelines (WCAG) 2.2. W3C. 文件预览与交互可访问性参考。www.w3.org/TR/WCAG22
- W3C PROV-O: The PROV Ontology. W3C. 来源与数据血缘的表达模型。www.w3.org/TR/prov-o
- NIST Secure Software Development Framework (SP 800-218). NIST. 软件工件完整性和安全开发参考。csrc.nist.gov/pubs/sp/800/218/final
- OpenTelemetry Documentation - Traces. OpenTelemetry. 运行追踪和上下文关联。opentelemetry.io/docs/concepts/signals/traces
- Git Documentation - git-diff. Git. 文本版本差异的工程参考。git-scm.com/docs/git-diff
- CommonMark Specification. CommonMark. Markdown 解析兼容性参考。spec.commonmark.org
附录 B：研究证据、验证声明与适用边界
B.1 证据等级
| 类型 | 内容 | 使用方式 |
|---|---|---|
| 已有规范 | HTTP、OpenAPI、JSON Schema、W3C PROV、WCAG | 支撑协议与互操作原则 |
| 官方工程文档 | PostgreSQL、S3、OpenTelemetry、Git | 支撑可行实现机制 |
| 安全指南 | OWASP、NIST | 支撑风险识别与防护方向 |
| 设计推论 | Artifact / Deliverable / Delivery 的产品划分、状态模型 | 作为可讨论的参考架构 |
| 未测试设想 | Studio 页面、API、数据库骨架、40 项测试 | 需工程实现与用户验证 |
B.2 尚未完成的验证
本篇未运行真实 PostgreSQL 迁移、文件上传、PDF 转换、权限渗透测试、对象存储故障注入、用户可用性测试或多租户隔离测试。SQL、JSON、Mermaid 与 API 仅为参考设计，不能据此宣称系统已具备对应能力。
B.3 适用范围
适用于需要管理 Agent 输出与业务交付的研究、内容生产、数据分析及企业自动化平台。对于受监管行业、包含个人敏感数据的系统或具有合同效力的正式交付，必须补充行业合规、记录保留、电子签名、证据固定和组织授权要求。
B.4 与后续专题的关系
F10 完成用户侧的成果管理闭环；下一篇 F11 · 开发者如何通过 API 与 SDK 集成平台能力？ - Developer Experience 将研究开发者如何通过接口、SDK、示例、文档、沙箱和开发者工具调用这些平台能力。F12 则从管理员视角研究平台级管理。