04 · 如何分阶段开发 Agent Platform？ - Development Roadmap
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：04 · 如何开发、部署和维护 Agent Platform？ - Engineering & Practice
文档类型：专题研究 / 开发路线 / 工程实施参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何将 Agent Platform 的系统架构拆解为有依赖关系、可交付、可验收、可回退的开发阶段，在有限资源下从现有原型逐步实现可靠的 Agent 运行闭环、研究工作流和可运营平台？
专题导读
本篇属 Engineering & Practice。本篇承接 04/04/01 Platform Case Studies、04/04/02 Technology Selection、04/04/03 System Design，将技术研究与架构方案转化为实施路线。研究重点是：怎样定义阶段目标，怎样拆分工作包，怎样处理依赖与风险，怎样设置可执行的验收门禁，以及如何在开发中根据证据调整路线。本文以研究报告 Studio 为贯穿案例，但不宣称已审计 Studio 代码；此前对 Phase 1 交互原型的描述只作为用户已陈述的背景，不代表后端工程已经完成。
证据标记：[规范/官方] 为所列标准或项目官方资料所支持的原则；[工程推论] 为本研究提出的参考方案；[待验证] 为必须通过代码审计、PoC、集成测试或生产观测确认的结论。本文所有排期、验收阈值、接口和架构均为建议，不能视作已执行结果。
研究结论
- 按可验证的业务闭环划分阶段，而不是按前端、后端、数据库分别“做完”。 每阶段应交付一条可实际运行、可追踪、可失败恢复的垂直切片。[工程推论]
- Studio 的首个关键门槛是单 Run 真实闭环：定义 → 发起 → 持久化 → 排队 → 执行 → 记录 → 产物 → 查询 → 失败处理。[工程推论]
- 第二个关键门槛是多 Agent 研究工作流闭环：选题 → 审核 → 返工 → 调研 → 分析 → 人工批准 → 固定产物版本；它需要状态机与持久化，不等于简单串行调用。[工程推论]
- 运行成功、质量通过、人工批准、交付成功是四类不同事实，必须由数据模型和验收用例分别验证。[工程推论]
- 每阶段建立进入条件、退出标准、不可妥协的质量门禁、回滚办法；不以“页面能点通”作为工程完成标准。[工程推论]
- 技术选型遵循先做最小风险 PoC，再记录 ADR，再冻结一个阶段，避免在未验证恢复语义前绑定复杂框架。[工程推论]
- 工期采用相对规模和能力门槛表示；没有团队人数、代码质量、预算、环境数据时，不给出伪精确的周数。[待验证]
01 · 开发路线研究的对象与边界
1.1 四个不同层次
| 层次 | 回答的问题 | 主要交付物 | 典型误区 |
|---|---|---|---|
| 产品路线 Product Roadmap | 用户何时得到什么价值 | 场景、功能、价值指标 | 以功能数量代替价值 |
| 工程路线 Engineering Roadmap | 系统怎样逐步实现 | 工作包、依赖、里程碑 | 只列任务，不列验收 |
| 技术演进 Architecture Evolution | 系统何时改变结构 | ADR、迁移计划、接口边界 | 过早微服务化 |
| 运营就绪 Operational Readiness | 何时可承载真实用户 | SLO、值班、备份、成本、安全 | 上线即完成 |
本篇主要研究工程路线，同时使其与产品路线、架构演进和运营就绪相互约束。它不替代项目管理系统、迭代计划或某一框架的教程。
1.2 阶段划分的依据
阶段边界应优先由风险降低与可独立验收的能力决定，而非仅由模块名称决定。可采用四类依赖：数据依赖（例如 Run 必须先有版本引用）、控制依赖（例如审批前必须有暂停机制）、安全依赖（例如多租户开放前必须有授权检查）、运维依赖（例如上线前必须能恢复失败任务）。
1.3 明确非目标
初期非目标包括：通用低代码 Agent Marketplace、任意规模微服务、复杂计费清结算、全自动无人监督发布、跨地域多活、为每个 Agent 单独部署容器。这些能力可在有明确需求与证据后进入后续阶段。[工程推论]
02 · 开始开发前，怎样建立现状基线？
2.1 代码与运行环境审计
实际启动下一阶段前，应获取仓库只读快照，检查项目结构、运行脚本、环境变量模板、数据库迁移、测试、部署配置、依赖锁文件和 CI。重点区分：界面模拟、API Mock、真实 API、真实 Worker、持久化状态、真实模型/工具调用、可恢复工作流。不能从 UI 看起来完整推断服务端能力存在。
| 核查对象 | 核查问题 | 证据形式 | 未确认时的处理 |
|---|---|---|---|
| Web | 真实路由、鉴权和错误态是否存在 | 路由清单、演示、测试 | 标记未知 |
| API | 是否有稳定契约和统一错误码 | OpenAPI、请求记录 | 先建最小契约 |
| 数据库 | 迁移、约束、备份是否存在 | Schema、迁移日志 | 禁止假定持久化 |
| 队列与 Worker | 崩溃、重试、幂等怎样处理 | 代码、故障演练 | 先做故障 PoC |
| Agent Runtime | 模型、工具、超时、取消怎样实现 | Trace、适配器接口 | 建最小适配器 |
| Workflow | 暂停、审批、恢复和返工是否可靠 | 端到端测试 | 不视作完成 |
| 产物 | 版本、哈希、权限、存储是否可靠 | 对象记录、下载测试 | 暂不对外发布 |
| 安全 | 密钥、权限、租户隔离 | 威胁建模、测试 | 不开放第三方 |
| 运维 | 日志、备份、监控、成本 | Dashboard、恢复演练 | 不称生产就绪 |
2.2 建立需求与证据登记表
每条需求至少记录 requirement_id / user_value / priority / dependency / acceptance_evidence / owner / status / risk。status 建议取 proposed / validated / in_progress / verified / deferred，不要用“已做”掩盖是否通过验收。对 Studio 的已知情况，前端 Phase 1 曾完成假数据链路验收；其余工程能力必须重新核实。[待验证]
2.3 产出工程基线包
基线包应包括：当前架构图、功能真值表、环境与部署清单、数据流图、风险登记、技术 ADR、测试基线、成本基线和首阶段 backlog。任何缺项均显式写“未确认”，不得猜测。
03 · 如何定义平台的最小可运行闭环？
3.1 垂直切片
flowchart LR
U[用户创建研究任务] --> API[Platform API]
API --> DB[(PostgreSQL: Run/Outbox)]
DB --> Q[任务投递]
Q --> W[Worker]
W --> AR[Agent Runtime]
AR --> MT[模型与工具]
W --> EV[状态事件与结果]
EV --> DB
W --> OS[(对象存储)]
DB --> UI[运行详情与审核界面]
OS --> UI一个最小闭环需要在成功、失败、超时、重试、重复投递五类条件下均能解释状态；不能只演示成功路径。UI 需要展示来自数据库的真实 Run，而非前端自造状态。[工程推论]
3.2 最小对象集合
| 对象 | 最小字段 | 不可缺少的约束 |
|---|---|---|
| Agent Definition | id、owner、name | 所有者/工作空间隔离 |
| Agent Version | id、agent_id、config_hash | 版本不可变 |
| Run | id、agent_version_id、status、created_at | 幂等创建、状态合法转移 |
| Run Attempt | id、run_id、attempt_no | 同一 Run 可多次尝试 |
| Event | id、run_id、type、sequence | 可重放/可追溯，去重 |
| Artifact Version | id、run_id、storage_key、sha256 | 内容固定，权限检查 |
| Approval | id、run_id、artifact_version_id、status | 审批绑定具体版本 |
| Audit Record | id、actor、action、target、timestamp | 重要变更可审计 |
上表是参考领域模型，不要求 MVP 一次建齐所有高级字段；但不能用一个混合 status 表示运行、审核和交付的全部事实。
3.3 最小 API 契约（示例）
POST /v1/runs
Idempotency-Key: 8d9f...client-generated
Content-Type: application/json
{"agent_version_id":"av_123","input":{"topic":"非遗数字化"}}{
"id": "run_123",
"execution_status": "queued",
"evaluation_status": "not_evaluated",
"review_status": "not_requested",
"delivery_status": "not_delivered",
"created_at": "2026-11-01T00:00:00Z"
}此为建议契约，不是现有 Studio API；字段命名应在实现时与此前 P8/F6/F10 的统一协议对齐。
04 · 阶段总览：从原型到可运营平台
| 阶段 | 核心目标 | 用户可见结果 | 工程交付 | 退出条件 |
|---|---|---|---|---|
| S0 · Baseline & Decisions | 确认真实现状与关键选型 | 可解释的开发范围 | 审计、ADR、PoC、CI 基线 | 关键未知有负责人和验证路径 |
| S1 · Single-Run MVP | 真实单 Agent 闭环 | 可启动、查看、下载一次任务 | API、DB、Queue、Worker、Artifact | 故障场景可重复通过 |
| S2 · Workflow MVP | 多 Agent 研究流程 | 选题、审核、返工、人工确认 | 持久化状态机、审批、恢复 | 审核/恢复/重试端到端通过 |
| S3 · Operable MVP | 真实用户可持续使用 | 项目、监控、成本、受控交付 | 权限、备份、告警、审计 | 运营就绪门禁通过 |
| S4 · Platform Expansion | 平台化复用与开放 | Agent 管理、API/SDK、扩展 | 版本、治理、多工作空间 | 真实集成与隔离测试通过 |
| S5 · Scale & Optimization | 按证据优化 | 更稳定、更低成本、更高质量 | 性能、容量、质量评估 | 基于测量满足目标 |
顺序不是绝对串行：安全、日志、测试、文档、成本观测必须从 S0/S1 开始，不能等 S3 才补。S4/S5 仅在需求与负载出现时启动。[工程推论]
05 · S0：工程基线与技术决策
目标：以最少代码识别最大的不确定性。进入条件：取得当前仓库、运行方式、核心产品场景与必要环境访问权限。核心工作：现状审计、核心领域对象草图、候选技术 PoC、CI/格式检查、开发与测试环境隔离、秘密管理方案、风险登记与 ADR。
5.1 最小 PoC 组合
| PoC | 需回答的问题 | 验证方法 | 通过证据 |
|---|---|---|---|
| POC-01 | Worker 崩溃后能否恢复？ | 执行中 kill Worker 后重启 | Run 不丢、状态可解释 |
| POC-02 | 审批能否跨进程等待？ | 暂停、重启服务、批准 | 同一流程继续 |
| POC-03 | 重试会否重复写产物？ | 重复投递同一任务 | 只有预期版本/幂等记录 |
| POC-04 | 模型调用可否替换？ | 切换模拟与真实适配器 | 业务 API 不变 |
| POC-05 | Trace 与业务状态如何关联？ | 故意触发工具失败 | 可按 run_id 找到证据 |
| POC-06 | 成本能否归因？ | 记录用量与估算价格版本 | 可追踪来源及不确定性 |
PoC 应包含失败样本、运行日志、复现脚本与结论。若失败，应记录替代方案和新增风险，不要将“能运行一次”当成通过。
5.2 S0 退出门禁
- 当前能力清单明确区分已验证与未知；关键技术 ADR 有备选项和否决理由。
- 可以从干净环境复现开发启动、数据库迁移和基本测试。
- 关键路径的失败/恢复方案至少有一个经过 PoC 证据支持。
- S1 backlog 已拆成可独立验收的垂直切片；敏感凭证不入仓库。
回退策略：若编排器 PoC 未通过，保留平台接口与领域模型，切换候选引擎；不迁移真实用户数据。[工程推论]
06 · S1：单 Agent 真实运行闭环
6.1 推荐工作包与依赖
| 工作包 | 输入依赖 | 交付物 | 验收重点 |
|---|---|---|---|
| S1-01 身份与项目最小模型 | S0 | 用户/项目隔离 | 越权访问拒绝 |
| S1-02 Agent 定义与版本 | S1-01 | 不可变 AgentVersion | 运行固定版本 |
| S1-03 Run API 与状态机 | S1-02 | 创建、查询、取消接口 | 幂等、合法状态迁移 |
| S1-04 Outbox/Queue/Worker | S1-03 | 异步执行闭环 | 至少一次投递、幂等消费 |
| S1-05 Runtime Adapter | S1-04 | 模型/工具调用适配 | 超时、错误分类 |
| S1-06 Event/Trace | S1-03 - 05 | 时间轴、调用关联 | 不泄露敏感输入 |
| S1-07 Artifact Store | S1-05 | 固定版本与下载 | 哈希、授权、重复写保护 |
| S1-08 Run UI | S1-03、06、07 | 列表、详情、失败态 | 真数据、刷新后保留 |
| S1-09 故障与回归测试 | 全部 | 自动化验收报告 | 失败恢复可重复 |
6.2 核心执行契约
建议 Run 执行状态采用 queued / running / waiting / succeeded / failed / cancelled / timed_out，实际迁移应有白名单；waiting 可在 S2 细分为审批等待等原因。Worker 需要租约或心跳机制以发现失联；失败后通过重试策略或人工处理，不可默默卡死。[工程推论]
6.3 S1 必测场景
- 同一 Idempotency-Key 重复创建不生成两个 Run；不同请求体复用相同键应明确冲突语义。
- Worker 在模型响应前后崩溃，Run 不丢失，重复执行行为可解释。
- 模型超时、工具失败、队列积压均有可查询状态和错误分类。
- 用户取消请求不等于外部副作用被撤销；UI 显示实际终止状态。
- AgentVersion 在 Run 开始后更新，历史 Run 仍引用原版本。
- 产物下载必须校验用户权限；被撤销的链接不能继续访问。
S1 完成定义：一名测试用户能在全新环境创建任务，观察真实执行，下载真实产物；系统在受控故障后仍能解释或恢复任务。没有达到此门槛，不进入“多 Agent 平台已完成”的表述。
07 · S2：多 Agent 研究工作流闭环
7.1 参考流程与控制点
flowchart TD
A[创建研究任务] --> T[选题 Agent]
T --> R1[选题审核 Agent]
R1 -->|返工| T
R1 -->|通过| H1{用户确认选题}
H1 -->|修改| T
H1 -->|批准| D[深度调研 Agent]
D --> AN[分析 Agent]
AN --> R2[内容审核 Agent]
R2 -->|返工| D
R2 -->|通过| H2{人工批准成果版本}
H2 -->|退回| AN
H2 -->|批准| F[固定版本与交付]这只是产品参考工作流，真实流程是否需要每一步、是否允许跳过审批，需由业务需求确认。图中返工环路必须有次数/预算/时间上限，避免无限循环。[工程推论]
7.2 工作包
| 工作包 | 关键约束 | 验收证据 |
|---|---|---|
| Workflow Definition | 定义版本不可变 | Run 固定定义版本 |
| Step Run 与依赖 | 前置条件显式化 | 非法步骤不能启动 |
| Orchestrator | 状态持久化 | 进程重启后恢复 |
| Agent 协作协议 | 输入输出契约、超时 | 跨 Agent 可追踪 |
| Reviewer Loop | 定向返工、次数上限 | 不重复已通过的无关步骤 |
| Human Approval | 审批绑定对象/版本 | 重复审批、超时、拒绝可处理 |
| Artifact Review | 产物版本与审核分离 | 修改后需重新审核 |
| Workflow UI | 阶段状态与待办 | 刷新/重登录后状态一致 |
| E2E Fault Tests | 崩溃、重复投递、过期审批 | 可复现的测试结果 |
7.3 长任务恢复设计
在 waiting_for_approval 时应持久化 checkpoint、审批目标版本、待办权限、超时策略与恢复令牌。恢复操作必须校验审批主体和目标版本，并防止重复提交。对于外部邮件、支付、发布等不可逆副作用，采用幂等键或补偿机制，不能假定重放一定安全。[工程推论]
7.4 S2 退出门禁
完整工作流至少完成一次通过、一次返工、一次审批拒绝、一次超时和一次中途服务重启的自动化演练；审核历史与最终 Artifact Version 可反向追踪。质量评估应另设指标，不能只凭工作流执行成功判定研究报告可信。
08 · S3：可运营 MVP
S3 的重点不是增加 Agent 数量，而是让已有闭环能够服务真实用户，并在错误、资源限制和人员操作下保持可控。
| 能力 | 最小交付 | 上线门禁 |
|---|---|---|
| 身份与授权 | 用户/项目角色、服务端权限检查 | 越权测试通过 |
| 密钥管理 | 服务端保管、轮换、访问审计 | 客户端不暴露密钥 |
| 运行监控 | Run、失败率、延迟、队列、告警 | 能定位并处理卡死任务 |
| 成本控制 | Token、估算成本、预算阈值 | 预算越界有预期处理 |
| 产物管理 | 版本、审核、导出、下载 | 交付版本固定 |
| 备份与恢复 | DB/对象存储备份与恢复演练 | 实测 RPO/RTO，非口头承诺 |
| 事件与审计 | 操作日志、关键变更 | 管理行为可追踪 |
| 运维手册 | 故障分级、恢复流程、责任人 | 非开发者可按手册操作 |
| 质量评估 | 样本集、人工评分、引用核查 | 能区分系统成功与内容质量 |
8.1 上线准入审查
至少回答：谁可以访问？谁可以看到原始 Prompt 和资料？数据保留多久？模型供应商接收哪些内容？怎样撤销共享？任务失控如何停止？备份是否实际恢复成功？谁接收告警？预算用完怎样降级？出现敏感数据泄漏怎样处置？[工程推论]
8.2 建议的运营指标
运行完成率、P50/P95 执行时间、队列等待时间、审批等待时间、每份通过审核报告的成本、人工返工率、引用核验通过率、故障恢复时间。必须定义分母、时间窗、排除项和数据来源；指标初期先建立基线，再根据真实数据确定目标，不凭空承诺 99.9% 等 SLA。[工程推论]
09 · S4：平台化复用与对外集成
在 S1 - S3 已经可靠运行、出现复用需求后，再逐步开放 Agent Registry、工作空间模板、版本发布、API/SDK、Webhook、配额与多租户治理。不要把“支持多个项目”直接等同于已经具备多租户安全隔离。[工程推论]
| 扩展能力 | 进入条件 | 必须验证 |
|---|---|---|
| Agent Registry | 多项目需要复用 Agent | 版本固定、权限、依赖影响 |
| 发布渠道 | 需要灰度/回滚 | 旧 Run 不受切换影响 |
| Developer API/SDK | 有真实第三方集成 | 契约、幂等、兼容性 |
| Webhook | 外部系统需要异步通知 | 签名、重放保护、重试去重 |
| 多工作空间 | 团队与项目分离需求 | 查询/存储/缓存隔离 |
| 配额/治理 | 资源争用或预算约束 | 并发、公平性、成本归因 |
| 插件生态 | 第三方工具接入频繁 | 沙箱、凭证、权限审查 |
10 · S5：基于证据的扩容与优化
只有在负载数据、故障记录或成本曲线表明必要时，才评估更复杂的架构。候选措施包括：独立队列分区、Worker 水平扩展、冷热数据分层、模型路由、缓存、长任务分片、工作流引擎替换、读写分离、租户资源池隔离。每项优化必须先建立基线、提出可证伪假设、进行受控实验，并设置回滚条件。[工程推论]
11 · 如何拆分可执行的开发工作包？
11.1 工作包模板
id: S2-APPROVAL-03
title: 人工审批后恢复工作流
user_value: 审核者可以跨会话批准研究结果
prerequisites: [S1-RUN-03, S2-WORKFLOW-01]
owner: TBD
priority: critical
scope:
included: [审批对象, 授权校验, 状态持久化, 恢复事件]
excluded: [复杂多级审批]
acceptance:
- 服务重启后审批仍可完成
- 非授权用户不能审批
- 重复请求不会重复推进工作流
- 过期审批有明确错误和处理方式
failure_tests:
- 重复投递
- 并发审批
- checkpoint 丢失模拟
observability: [run_id, approval_id, trace_id]
rollback: 禁用新审批入口并保留待办状态
status: proposed11.2 工作包的大小与 Definition of Done
一个工作包应足以在单次迭代内完成并演示，过大则按 API、数据、执行、UI、故障验证拆成可验收子切片。完成定义应同时包含：代码、迁移、测试、文档、日志、权限、异常处理、回滚/恢复路径和验收证据。测试失败时状态仍是 in_progress 或 blocked，不是 done。[工程推论]
12 · 依赖关系与关键路径
flowchart LR
B[S0 基线与 ADR] --> M[领域模型/DB]
M --> R[Run API]
R --> W[Queue/Worker]
W --> A[Agent Runtime]
A --> P[Artifact]
R --> E[事件/Trace]
P --> F[单 Run 验收 S1]
E --> F
F --> WF[Workflow/Checkpoint]
WF --> H[Human Approval]
H --> REV[审核返工/版本]
REV --> G[多 Agent 验收 S2]
G --> O[权限/监控/备份/运营 S3]
O --> X[API/SDK/多租户 S4]关键路径需要由实际任务估算与人员分配计算，上图仅表示逻辑依赖，不是测算后的项目关键路径。并行开展 UI 组件、测试基建、文档和基础安全，但必须避免依赖未稳定的领域契约产生大量返工。
13 · 怎样进行排期与资源估算？
13.1 三点估算
对高不确定性工作包记录乐观 O、最可能 M、悲观 P，可用 PERT 期望 (O+4M+P)/6 作为粗略辅助，不能把其结果当作确定工期。应记录团队熟练度、外部依赖、测试环境、模型费用和审核等待等变量。估算单位可以是相对点数，避免没有基线就承诺具体周数。
13.2 容量与预算
总成本至少包括：工程时间、云计算、数据库/对象存储、模型 Token、第三方工具、日志存储、CI、域名、备份和故障处理。模型预算应按每次运行、每个合格交付、每个租户三个视角测算。研发成本和运行成本分开统计。
13.3 资源不足时的裁剪顺序
优先保留：真实运行、持久化状态、失败处理、审批、产物、基本权限与日志。可延后：拖拽式复杂编辑器、Marketplace、高级分析仪表盘、全语言 SDK、复杂组织结构、自动弹性伸缩。不要裁掉数据隔离、秘密保护和关键恢复测试。[工程推论]
14 · 怎样管理需求变更与技术债？
建议采用轻量 ADR 和阶段冻结：每个阶段开始前冻结核心 API/对象模型的变更流程；允许修复安全与正确性问题；其他新增需求进入下一阶段评估。每条技术债记录产生原因、影响范围、风险等级、偿还触发条件和责任人。将“临时内存状态”“跳过鉴权”“同步执行长任务”“前端模拟成功”等列为高风险债务，不能在真实用户上线前遗留。[工程推论]
15 · 如何设计工程交付与发布流程？
推荐开发环境 local → test/staging → production，数据库迁移采取向后兼容优先策略。发布应包含构建、静态检查、单元测试、集成测试、端到端测试、迁移预检查、灰度/小流量验证、监控观察与回退预案。对于不可逆数据库迁移，回退可能需要前向修复而非简单恢复旧代码；必须预先演练。[工程推论]
flowchart LR
PR[Pull Request] --> CI[Lint/Type/Unit]
CI --> IT[Integration + Migration]
IT --> ST[Staging E2E + Fault]
ST --> AP[发布批准]
AP --> PD[生产小流量]
PD --> OBS[观察指标]
OBS -->|通过| FULL[扩大流量]
OBS -->|失败| RB[停止发布/回退或前向修复]16 · Studio 贯穿案例：从 Phase 1 原型到真实研究系统
16.1 参考用户旅程
用户创建一个研究 Studio，指定研究主题，选择选题 Agent、审核 Agent、调研 Agent、分析 Agent，启动流程。选题审核失败则返工，审核通过后由用户确认。调研与分析完成后生成报告草稿，用户对固定版本批准，系统导出 Markdown/PDF 并保存交付记录。整个过程中用户能查看真实 Run、待办、错误、引用与产物版本。
16.2 分阶段产品演示脚本
| 阶段 | 可演示的真实行为 | 不应冒充已完成的能力 |
|---|---|---|
| S0 | 从干净环境启动项目，查看审计/ADR | 真实 Agent 执行 |
| S1 | 单 Agent 执行、失败重试、下载产物 | 多 Agent 恢复 |
| S2 | 审核返工、人工批准、服务重启恢复 | 生产安全/多租户 |
| S3 | 权限隔离、成本监控、备份恢复、受控交付 | 任意规模扩容 |
| S4 | SDK 集成、Agent 版本复用、工作空间隔离 | 完整生态成熟度 |
| S5 | 用实测数据说明性能/成本改善 | 未测量的性能宣称 |
16.3 Studio 首期推荐 backlog（优先级，不代表已实施）
| 优先级 | 任务 | 理由 |
|---|---|---|
| P0 | 审计现有 Next.js 项目、数据流和假数据位置 | 先确认真实基线 |
| P0 | 定义 AgentVersion、Run、Event、ArtifactVersion | 建立统一语义 |
| P0 | PostgreSQL 迁移与最小 API | 持久化业务真相源 |
| P0 | Worker + Agent Runtime Adapter | 真正执行任务 |
| P0 | Run 状态与事件时间轴 | 用户可理解、可诊断 |
| P0 | 幂等/超时/崩溃恢复 | 避免伪成功 |
| P1 | Workflow Definition 与 Step Run | 多 Agent 基础 |
| P1 | 审核返工与人工审批 | Studio 核心价值 |
| P1 | 产物版本与审核绑定 | 防止错误交付 |
| P1 | 引用核查与质量评估 | 区分生成和可信 |
| P1 | 成本、权限、备份、告警 | 运营准备 |
| P2 | Agent 发布、SDK、插件、租户治理 | 复用和扩展 |
17 · 风险登记与应对策略
| 风险 | 早期信号 | 缓解措施 | 触发动作 |
|---|---|---|---|
| UI 原型被当作后端完成 | 只有 Mock，无真实持久化 | 功能真值表与 E2E | 暂停扩展 UI |
| 工作流状态丢失 | 重启后无法恢复 | checkpoint + 恢复测试 | 阻止 S2 验收 |
| 重复工具副作用 | 重试后重复发送/写入 | 幂等键、Outbox、补偿 | 隔离有风险工具 |
| 无限审核返工 | 循环次数无上限 | 最大次数/预算/人工介入 | 自动暂停 |
| 模型成本失控 | 单任务 Token 异常 | 预算阈值、调用上限 | 降级/停止新任务 |
| 产物审核错配 | 审核未绑定版本 | 版本外键、不可变记录 | 阻止发布 |
| 敏感数据泄漏 | Trace 记录完整 Prompt | 最小化、脱敏、权限 | 停止外部访问 |
| 多租户串读 | 查询缺少租户过滤 | 服务端授权、隔离测试 | 阻止开放 |
| 框架绑定 | 业务直接调用 SDK 细节 | Adapter、契约测试 | 启动重构 ADR |
| 过早微服务化 | 运维复杂度高于业务需求 | 模块化单体优先 | 合并部署边界 |
| 发布无法回退 | 不可逆迁移无预案 | Expand/Contract、演练 | 暂停上线 |
| 研究质量不稳定 | 引用不实、审核差异大 | 数据集、人工核验 | 降低自动发布权限 |
18 · 阶段验收测试矩阵（建议，未执行）
以下用例均为待执行验收项。实际项目应为每项补充测试环境、操作步骤、预期输出、日志证据、责任人与执行日期。
| ID | 阶段 | 测试主题 | 预期结果 |
|---|---|---|---|
| T-01 | S0 | 干净环境安装 | 依赖可重现安装 |
| T-02 | S0 | 数据库迁移 | 空库可迁移 |
| T-03 | S0 | 配置校验 | 缺少必需配置明确失败 |
| T-04 | S0 | 秘密扫描 | 仓库无真实密钥 |
| T-05 | S0 | 框架 PoC 复现 | 有脚本与日志 |
| T-06 | S0 | ADR 审核 | 关键决策有替代方案 |
| T-07 | S1 | 重复创建 Run | 幂等键防重 |
| T-08 | S1 | 幂等键请求体冲突 | 返回确定性冲突 |
| T-09 | S1 | 非法状态迁移 | 拒绝并记录 |
| T-10 | S1 | 队列重复投递 | 不会产生重复业务结果 |
| T-11 | S1 | Worker 中途崩溃 | 可恢复或明确失败 |
| T-12 | S1 | Worker 心跳超时 | 识别失联任务 |
| T-13 | S1 | 模型超时 | 记录超时和重试策略 |
| T-14 | S1 | 工具异常 | 分类错误并展示 |
| T-15 | S1 | Run 取消 | 状态与副作用说明一致 |
| T-16 | S1 | 版本固定 | 旧 Run 引用不变 |
| T-17 | S1 | 产物哈希 | 下载内容可核验 |
| T-18 | S1 | 产物越权下载 | 拒绝访问 |
| T-19 | S1 | 事件顺序 | 可重放且去重 |
| T-20 | S1 | 刷新页面 | 真实状态不丢失 |
| T-21 | S2 | 审核失败返工 | 返回指定步骤 |
| T-22 | S2 | 返工上限 | 超过阈值暂停 |
| T-23 | S2 | 审批等待重启 | 重启后可恢复 |
| T-24 | S2 | 非授权审批 | 拒绝并审计 |
| T-25 | S2 | 重复审批 | 只推进一次 |
| T-26 | S2 | 过期审批 | 不推进工作流 |
| T-27 | S2 | 并发审批 | 结果确定且无双重提交 |
| T-28 | S2 | 版本修改后审核 | 旧审核不自动继承 |
| T-29 | S2 | 中途 Agent 失败 | 局部重试/恢复可解释 |
| T-30 | S2 | Workflow 版本切换 | 运行中版本不漂移 |
| T-31 | S2 | 工作流终止 | 后续步骤不再启动 |
| T-32 | S2 | 引用质量检查 | 结果独立于执行成功 |
| T-33 | S3 | 角色权限 | 不同角色权限正确 |
| T-34 | S3 | 跨项目访问 | 无权限数据不可见 |
| T-35 | S3 | 备份恢复 | 实际恢复数据完整 |
| T-36 | S3 | 告警通知 | 故障可触发且去重 |
| T-37 | S3 | 预算阈值 | 按策略阻止/降级 |
| T-38 | S3 | 审计记录 | 关键管理操作可追踪 |
| T-39 | S3 | 导出与交付 | 固定已批准版本 |
| T-40 | S3 | 共享撤销 | 撤销后不可访问 |
| T-41 | S3 | 敏感日志脱敏 | 敏感字段不可泄漏 |
| T-42 | S3 | 故障演练 | 按手册恢复服务 |
| T-43 | S4 | SDK 契约 | 示例应用可完成闭环 |
| T-44 | S4 | Webhook 签名 | 伪造请求被拒绝 |
| T-45 | S4 | Webhook 重放 | 重复事件安全处理 |
| T-46 | S4 | 多租户隔离 | 存储和查询均隔离 |
| T-47 | S4 | 发布渠道回滚 | 新旧 Run 版本一致性 |
| T-48 | S4 | API 兼容性 | 既有客户端无意外破坏 |
| T-49 | S5 | 负载基线 | 有可重复的负载数据 |
| T-50 | S5 | 扩容验证 | 吞吐与成本变化可量化 |
| T-51 | S5 | 模型路由比较 | 质量成本权衡有证据 |
| T-52 | S5 | 恢复目标 | 实测满足约定 RPO/RTO |
19 · 决策检查表与复盘机制
每次阶段评审应回答六个问题：①目标用户价值是否得到真实验证？②关键失败场景是否通过？③权限与敏感数据是否满足最低门槛？④实际运行成本是否可解释？⑤技术债是否在可接受范围？⑥下一阶段是否依赖尚未验证的假设？若任一关键项未通过，应明确记录 blocked / defer / redesign，而不是默认进入下一阶段。
建议每个阶段保留一份简短的工程复盘：原计划、实际证据、偏差、故障、成本、未完成风险、下一阶段假设。将研究结论和真实执行结果分开存档。
20 · 局限与适用边界
本文路线适用于以 Web 为主要入口、以异步长任务和多 Agent 工作流为核心、团队规模较小的 Agent Platform 初期开发。它不直接适用于需要严格实时控制、医疗/金融高风险自动决策、海量多租户 SLA 或强监管部署的场景；这些情况需要额外的领域合规、安全与可靠性设计。Studio 当前代码、团队人数、运行预算、用户规模、实际性能均未在本篇审计，因此不能将阶段建议当作确定实施计划。[待验证]
附录 A：参考文献与原始资料
以下资料用于支持工程机制、交付方法和可靠性原则；其中各阶段划分、Studio 工作包与验收矩阵是本文的设计推论，不是引用资料规定的标准流程。链接为官方规范或项目文档入口，实际落地时应核对所采用版本。
- Google, Site Reliability Engineering（服务可靠性、SLO 与运维实践）：sre.google/sre-book/table-of-contents
- Google, The Site Reliability Workbook（监控、告警、发布与可靠性）：sre.google/workbook/table-of-contents
- OpenTelemetry, Documentation（Trace、Metrics、Logs 与上下文传播）：opentelemetry.io/docs
- OpenTelemetry, Semantic Conventions（语义约定；GenAI 字段具有版本演进）：opentelemetry.io/docs/specs/semconv
- W3C, Trace Context（跨服务追踪上下文）：www.w3.org/TR/trace-context
- CloudEvents, Specification（事件元数据标准）：github.com/cloudevents/spec
- PostgreSQL, Documentation（事务、锁、约束、备份）：www.postgresql.org/docs/current
- Temporal, Documentation（持久化工作流及恢复语义，候选技术而非唯一方案）：docs.temporal.io
- LangGraph, Persistence（图状态与检查点，候选技术）：docs.langchain.com/oss/python/langgraph/persistence
- OpenAI, Agents SDK Documentation（Agent Runtime、工具和追踪的候选参考）：openai.github.io/openai-agents-python
- OWASP, Top 10 for Large Language Model Applications（LLM 应用风险）：genai.owasp.org/llm-top-10
- NIST, AI Risk Management Framework（AI 风险治理）：www.nist.gov/itl/ai-risk-management-framework
- OpenAPI Initiative, OpenAPI Specification（HTTP API 契约）：spec.openapis.org/oas/latest.html
- The Twelve-Factor App（应用配置与部署原则）：12factor.net
- GitHub Docs, Understanding GitHub Actions（CI/CD 参考实现）：docs.github.com/en/actions/about-github-actions/understanding-github-actions
- Martin Fowler, Strangler Fig Application（渐进替换策略）：martinfowler.com/bliki/StranglerFigApplication.html
- Martin Fowler, Feature Toggles（功能开关与发布控制）：martinfowler.com/articles/feature-toggles.html
- Kubernetes, Documentation（后期容器编排候选，并非 MVP 必需）：kubernetes.io/docs
附录 B：研究证据、验证声明与适用边界
| 内容 | 证据等级 | 声明 |
|---|---|---|
| 事务、约束、备份、API 契约、追踪等基础机制 | [规范/官方] | 有官方文档支持；具体实现取决于所选版本 |
| S0 - S5 阶段划分及优先级 | [工程推论] | 本文建议，非行业统一标准 |
| Studio 技术栈、接口、数据模型与工作包 | [工程推论] | 参考设计，需与实际代码核对 |
| 故障恢复、审批、成本、性能与质量目标 | [待验证] | 必须经实验和真实运行测量 |
| 52 项测试矩阵 | [待验证] | 仅为验收设计，未执行 |
验证声明：本文未连接或审计 Studio 源码，未部署候选技术栈，未运行测试矩阵，未测量开发工期、性能、模型费用或用户行为。所有示例仅用于解释可实施的工程契约。任何正式上线决策都应基于实测证据、明确的安全评审和组织批准。
与相邻专题的边界：本篇负责“开发顺序与阶段门禁”；04/04/02 负责“技术选型”；04/04/03 负责“系统设计”；下一篇 04/04/05 Deployment & Operations 进一步研究环境部署、运行保障、备份恢复和运维流程；04/04/06 Testing & Optimization 研究测试体系、评估方法与持续优化。