02 · 如何选择 Agent Platform 的技术框架？ - Technology Selection
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：04 · 如何开发、部署和维护 Agent Platform？ - Engineering & Practice
文档类型：专题研究 / 技术选型 / 架构决策参考
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何从产品需求、执行语义、工程可靠性、团队能力和总拥有成本出发，为 Agent Platform 选择前后端、Agent Runtime、Workflow Engine、数据与基础设施，并通过可复现实验形成可调整的技术决策？
专题导读
本篇属 Engineering & Practice。技术选型不是寻找“最先进”的框架，而是将产品所需的行为、工程约束、团队能力与候选方案逐项匹配。本文承接上一专题 Platform Case Studies 的产品分类与证据约定，进一步把比较转化为可执行的选型流程。研究对象是完整 Agent Platform，而非单个 Agent SDK；重点关注运行状态的持久化、人工审批、可恢复任务、权限隔离、产物版本、观测、成本和持续演进。
证据说明：[规范/官方] 表示可由列出的官方规范或文档支持的能力定义；[架构推论] 表示基于约束形成的建议；[待实验] 表示尚未在 Studio 项目代码与生产环境验证的命题。下文的评分、示例负载、技术组合均为参考设计，不是已完成的基准测试或对现有代码的审计。各项目 API、授权、商业条件与版本可能变化，正式采用前需重新核验。
研究结论
- 先确定不可妥协的系统行为，再比较工具：任务恢复、人工审批、执行幂等、权限与租户隔离、可追溯产物、成本上限，比编程语言偏好更具决定性。[架构推论]
- 将 Platform Control Plane、Workflow Orchestrator、Agent Runtime、Worker、Data Plane、Observability 分开选型；一个框架不应被默认视为所有层的解决方案。[架构推论]
- 对 Studio，建议将 Next.js/TypeScript 前端与平台 API、PostgreSQL 业务真相源、独立后台 Worker、对象存储作为候选基线；在此基础上比较 Python/LangGraph、TypeScript/Agents SDK 或自建轻量编排。此为待验证方案，非已确认技术栈。[架构推论]
- 对“暂停等待人工审批数小时、审核失败后返工、进程重启继续执行”的场景，必须以状态恢复实验而非 Demo 是否跑通判断工作流引擎。[待实验]
- Agent 的输出质量与平台执行可靠性分开测量。更换模型或提示词可能改变质量，却不能代替事务、重试和权限控制。[架构推论]
- 以 ADR（Architecture Decision Record）+ 证据矩阵 + 可复现 PoC 记录每项决策，并为未来迁移保留接口边界。[架构推论]
01 · 选型的对象、边界与决策顺序
1.1 技术栈分层
| 层次 | 核心职责 | 典型候选 | 不应由其独自承担 |
|---|---|---|---|
| Web/UI | Studio 工作台、可视化流程、审批、产物预览 | Next.js、React、Vue | 持久化后台任务执行 |
| Platform API / Control Plane | 身份、权限、项目、Agent 定义、Run API | Next.js API、NestJS、FastAPI | 长时间阻塞执行 |
| Workflow Orchestrator | 状态迁移、依赖、检查点、等待、重试 | LangGraph、Temporal、DB-backed orchestration | 模型输出事实核验 |
| Agent Runtime | 模型调用、工具、上下文、Agent 交接 | OpenAI Agents SDK、Google ADK、LangGraph、CrewAI | 全平台租户治理 |
| Worker / Queue | 后台执行、调度、租约、限流 | BullMQ、Celery、Temporal Workers、托管队列 | 单独作为业务状态真相源 |
| Transactional DB | Run、审核、配置、版本、审计、幂等 | PostgreSQL | 大型二进制文件主体存储 |
| Artifact Storage | 文件、版本、交付包 | S3 兼容对象存储 | 权限决策的唯一来源 |
| Retrieval | 文档检索、向量索引 | PostgreSQL + pgvector、专用检索引擎 | 事实正确性的最终判定 |
| Telemetry | Trace、Metric、Log、告警 | OpenTelemetry、Prometheus、Grafana、Langfuse | 替代业务事件账本 |
| Infrastructure | 部署、密钥、备份、网络 | Docker、Kubernetes、托管 PaaS | 自动满足业务可靠性 |
1.2 依赖关系
flowchart TD
R[业务需求与风险等级] --> C[关键行为与验收条件]
C --> B[架构边界和状态模型]
B --> P[候选技术与排除条件]
P --> E[同负载 PoC 与证据记录]
E --> A[ADR 决策与回退计划]
A --> O[上线观测与复审]
O -->|新证据| P1.3 非目标
本文不对“全球最佳 Agent 框架”排名，不承诺单一框架覆盖全部能力，不推断未公开的服务端架构，也不在缺少项目仓库与负载数据时宣称某组合已满足 Studio 生产需求。
02 · 从 Studio 的业务场景反推非功能需求
2.1 代表性业务流程
研究报告 Studio：用户创建研究项目 → 选题 Agent 提案 → 审核 Agent 给出修改意见 → 返工至通过或达到次数上限 → 人工确认 → 深度调研 → 分析 → 引用核验 → 成果版本化 → 导出与交付。运行可持续数分钟至数小时，可能需要等待用户隔天批准。[用户项目场景；负载时长为假设]
2.2 约束分级
| 级别 | 要求 | 验证方法 | 不满足时后果 |
|---|---|---|---|
| P0 | 重启后 Run 不丢失、不误标成功 | Kill/restart + 状态核对 | 数据丢失或重复执行 |
| P0 | 人工审批不阻塞进程且可恢复 | 跨进程/跨天恢复实验 | 工作流无法长期运行 |
| P0 | 关键写操作具备幂等语义 | 重复请求与重投递测试 | 重复扣费、重复产物 |
| P0 | 租户、项目、产物访问隔离 | 越权矩阵测试 | 数据泄露 |
| P0 | 外部工具执行有权限边界 | 拒绝未授权工具调用 | 越权副作用 |
| P1 | Run/Step/Attempt 可追踪 | Trace 与业务记录对账 | 无法定位失败 |
| P1 | 模型与工具成本可归因 | 用量记录与账单对账 | 成本不可控 |
| P1 | 成果版本与审核绑定 | 变更后审批失效测试 | 未审核内容被交付 |
| P1 | 可限流、超时、取消和重试 | 故障注入 | 资源耗尽 |
| P2 | 可视化工作流编辑 | 用户任务测试 | 配置效率较低 |
| P2 | 多模型动态路由 | 兼容性与质量对照 | 供应商切换困难 |
P0/P1/P2 为本研究建议优先级，不是项目已确认的产品需求。上线前需由项目负责人根据用户规模、预算、数据敏感度重新批准。
2.3 先收集的实际数据
必须盘点：代码语言与框架版本、现有运行入口、部署方式、团队技能、预计日 Run 数、同时活跃 Run 数、单 Run 平均步骤数、最长审批等待、单 Run Token、文件体积、用户与租户数量、数据驻留要求、预算、RTO/RPO 目标。没有这些数据时，性能和成本评分只可使用假设值。
03 · 选型标准与评分模型
3.1 硬门槛优先于加权评分
候选方案首先必须满足 P0：可靠状态恢复、审批等待、可审计操作、访问隔离、数据可导出。任何硬门槛未通过，即使生态或开发体验评分高，也不得直接用于对应生产路径。
3.2 评分维度（示例权重）
| 维度 | 权重 | 评分证据 |
|---|---|---|
| 执行语义与恢复 | 25% | 故障注入、持久化状态、恢复一致性 |
| 工程集成与复杂度 | 15% | PoC 开发工时、运维组件数量 |
| 安全与权限 | 15% | 租户隔离、凭证管理、审计 |
| 可观测与调试 | 10% | Run/Step/Trace 对账、错误定位 |
| 成本与可运营性 | 15% | 同负载基础设施与模型费用 |
| 可扩展与可迁移性 | 10% | 接口解耦、数据导出、迁移实验 |
| 团队能力与文档 | 10% | 学习时间、文档完整度、人才可得性 |
分数 = Σ(维度权重 × 1 - 5 分)；先过硬门槛，再算加权分。每个分数须附证据编号、测试版本、环境和复现步骤；不得以主观印象替代实验。评分权重为示例，不能据此声称某产品客观优于其他产品。
3.3 决策记录模板
adr_id: ADR-004
status: proposed
question: "Studio 工作流状态由谁持久化？"
context:
- "存在跨天人工审批"
- "审核失败后需返回指定步骤"
options:
- "LangGraph checkpoints + 平台业务状态"
- "Temporal workflow + 平台业务状态"
- "自建 PostgreSQL 状态机 + 队列"
hard_gates: [restart_recovery, idempotency, tenant_isolation]
evidence: [POC-01, POC-02, SEC-03]
chosen: null
tradeoffs: []
rollback_plan: "保留 workflow_run 与 step_run 的中立数据契约"
review_trigger: "并发、失败率或团队规模达到重新评估阈值"04 · 前端与产品交互技术选型
4.1 关键决策
Studio 的界面涉及工作空间、Agent 列表、研究流程图、多人协作、流式消息、产物预览、版本比较和管理后台。评估前端框架时应重点比较：组件生态、TypeScript 类型共享、长连接支持、权限呈现、复杂状态同步、Markdown/代码编辑、可视化节点编辑和无障碍能力，而不是只比较首屏速度。
| 候选 | 优势场景 | 风险/边界 | 验证点 |
|---|---|---|---|
| Next.js + React + TypeScript | 与已有 React/Next.js 项目衔接、服务端渲染与路由 | API 与后台 Worker 的职责易混淆 | SSE 重连、鉴权、构建部署 |
| React SPA + 独立 API | 前后端职责清晰、部署独立 | 认证、SEO、路由与构建需自行组合 | 复杂工作台性能与发布流程 |
| Vue + Nuxt | 团队熟悉 Vue、希望完整框架 | 若既有组件为 React 则迁移成本较高 | 组件迁移与维护成本 |
Studio 候选：保留既有 Next.js/TypeScript 前端，避免为技术统一而重写已完成的交互页面。[架构推论；未审计现有仓库]
4.2 状态管理建议
将服务器权威状态（Run 状态、审批结果、产物版本）与临时界面状态（面板展开、筛选条件、草稿编辑）分开。客户端乐观更新必须在服务端拒绝时回滚；SSE 只负责通知与增量刷新，断线后通过权威查询补齐事件，不应以浏览器内存作为唯一执行记录。
4.3 工作流编辑器
React Flow 等节点库适合构建可视化编辑器，但画布图不等于可执行工作流。需要图结构校验、节点类型版本、输入输出 Schema、权限校验、循环终止策略和发布快照。初期可先以受控表单与固定流程实现，再评估通用画布的必要性。
05 · 平台后端语言与服务框架
5.1 三种常见组合
| 方案 | 适用条件 | 主要代价 |
|---|---|---|
| TypeScript 全栈（Next.js/NestJS + TS Worker） | 团队 TS 熟练、API/类型共享优先 | Python AI 工具生态可能需要服务桥接 |
| TypeScript Web + Python Agent Worker | Web 侧 TS、AI/数据处理侧 Python | 双语言部署、契约与追踪治理 |
| Python 为主（FastAPI + Python Worker） | 数据科学/模型工程为主、Python 技能强 | 与既有 TS 产品界面需清晰分层 |
语言不决定可靠性；数据库事务、任务语义、异常恢复和工程流程才决定系统行为。[架构推论]
5.2 Studio 的参考接口边界
flowchart LR
UI[Next.js Studio UI] --> API[Platform API]
API --> DB[(PostgreSQL)]
API --> Q[Durable Queue / Scheduler]
Q --> W[Agent / Workflow Workers]
W --> DB
W --> OS[(Object Storage)]
W --> M[Model & Tool Adapters]
W --> T[Telemetry]
UI -->|SSE / Polling| APIPlatform API 持有用户授权、任务创建、审批、产物引用与管理操作；Worker 持有长任务执行。无论选择 Python 或 TS，二者通过版本化命令、事件和持久化状态交互，避免依赖同一进程内的对象引用。
06 · Agent Runtime 选型
6.1 需要比较的能力
模型与供应商适配、工具调用、结构化输出、Agent handoff、会话上下文、运行钩子、流式事件、错误传播、取消、工具权限、追踪、运行成本，以及在框架升级时迁移状态的难度。
| 候选 | 研究价值 | 必须验证的边界 |
|---|---|---|
| OpenAI Agents SDK | Agent、工具、handoff、tracing 的代码优先设计 | 供应商适配、外部业务持久化、审批语义 |
| LangGraph | 图式状态流、检查点、中断与恢复 | 检查点存储与平台业务状态的一致性 |
| Google ADK | Agent 组合、工具和多模型开发模式 | 部署与生态约束、迁移成本 |
| CrewAI | 角色化 Agent、任务与 Flow 的组织方式 | 跨天等待、失败恢复、审计对账 |
| 自建最小 Runtime | 最大化行为控制、抽象较薄 | 工具调用、上下文、追踪与安全维护成本 |
选型原则：Agent Runtime 可以替换，但平台的 agent_version_id、run_id、step_run_id、artifact_version_id 不应依赖某个 SDK 的内部标识。适配器应把 SDK 事件转换为平台的中立事件协议。
6.2 避免双重编排
若 Workflow Engine 已控制任务依赖、重试与审批，Agent Runtime 应聚焦单步内的推理、工具调用与有限 handoff。两层都自动重试可能造成指数级重复调用。需为每层明确重试次数、超时和幂等键。
07 · Workflow Engine 与长任务执行
7.1 三条路线
| 路线 | 优势 | 风险 | 优先 PoC |
|---|---|---|---|
| LangGraph + Checkpointer | 适合图式 Agent 状态与中断 | 业务状态与图状态需同步 | 审核返工 + 恢复 |
| Temporal + Workers | 强调持久化工作流与任务执行语义 | 引入独立基础设施和概念成本 | 长等待 + 重放约束 |
| PostgreSQL 状态机 + 队列 | 边界可控、MVP 组件少 | 自行实现租约、超时、恢复、补偿 | Worker 崩溃 + 重投递 |
不要把“队列保证消息送达”理解为“外部副作用只执行一次”。现实系统通常需要至少一次投递 + 幂等执行/去重 + 补偿；对于外部邮件发送、支付、文件写入等不可逆操作，必须单独设计业务去重和人工确认。
7.2 参考状态机
stateDiagram-v2
[*] --> queued
queued --> running
running --> waiting_approval
waiting_approval --> queued: approved / revised
running --> retry_wait
retry_wait --> queued
running --> succeeded
running --> failed
queued --> canceled
waiting_approval --> canceled
running --> cancel_requested
cancel_requested --> canceled
cancel_requested --> failed: cleanup failed状态机是平台建议，不代表任一框架原生提供完全相同的状态。状态更新需带版本号或事务条件，避免并发审批、重复取消和迟到 Worker 写回覆盖新状态。
7.3 崩溃一致性
典型竞态：Worker 已调用外部工具，但尚未写入成功事件便崩溃；重试时可能重复调用。应为工具调用建立 operation_id、幂等键、外部结果回查机制；对无法幂等的动作使用审批或补偿。数据库事务不能跨越所有外部 API 实现真正的原子性。
08 · 队列、调度与 Worker
8.1 队列选项
BullMQ/Redis 适用于 TypeScript 生态后台作业；Celery 适用于 Python 生态；托管消息队列可降低部分基础设施维护；Temporal Workers 适合采用 Temporal 作为工作流基础设施的方案。它们的投递保证、任务保留、延迟调度和失败处理各有不同，应按特定版本官方文档核验。[官方文档＋架构推论]
8.2 关键语义
任务应包含 job_id、run_id、step_run_id、attempt、tenant_id、idempotency_key、deadline_at、schema_version。Worker 应执行租约/心跳、最大尝试次数、指数退避和随机抖动；重试必须区分暂时性故障、永久性输入错误、授权错误和预算拒绝。
8.3 资源隔离
按租户与项目限制并发数、Token 预算、工具调用数、队列长度和文件大小。公平调度避免单个大型研究项目耗尽所有 Worker。GPU 并非调用远程模型 API 的默认必要条件；只有自托管模型或本地推理场景才需评估 GPU 资源。
09 · 数据库、缓存与对象存储
9.1 事务数据库
PostgreSQL 作为候选业务真相源，适合存储用户、组织、Agent 定义、不可变版本、Run、Step、审批、事件索引、产物元数据和审计记录。关系约束、事务、唯一键和行级权限策略均需要结合实际应用实现；启用 RLS 不等于所有查询自动安全。[官方文档＋架构推论]
CREATE TABLE workflow_runs (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
workflow_version_id UUID NOT NULL,
status TEXT NOT NULL,
state_version BIGINT NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE step_runs (
id UUID PRIMARY KEY,
run_id UUID NOT NULL REFERENCES workflow_runs(id),
step_key TEXT NOT NULL,
attempt_no INT NOT NULL DEFAULT 1,
status TEXT NOT NULL,
UNIQUE (run_id, step_key, attempt_no)
);
CREATE TABLE run_commands (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
run_id UUID NOT NULL REFERENCES workflow_runs(id),
idempotency_key TEXT NOT NULL,
command_type TEXT NOT NULL,
payload JSONB NOT NULL,
UNIQUE (tenant_id, idempotency_key)
);上述仅为概念性最小示例，未包含所有索引、外键、RLS 策略、分区、审计、迁移及事务逻辑，不可直接视为生产 Schema。
9.2 对象存储
原始资料、生成报告、图片、PDF 和导出包适合存放对象存储；数据库保存 object_key、内容哈希、版本、所有者、保留期限和访问策略。使用短时签名 URL 时须校验对象权限和过期时间，避免将存储桶公开作为交付捷径。
9.3 缓存
Redis 可用于缓存、限流和部分队列；但缓存失效、驱逐与重启不可导致审批或 Run 权威状态丢失。明确“可重建缓存”与“必须持久化的业务事实”的边界。
10 · 检索、知识库与向量数据库
研究报告平台可能需要文档切分、元数据过滤、全文检索、语义检索、引用定位和去重。初期可以评估 PostgreSQL 全文检索 + pgvector 的组合；当语料规模、召回率、过滤复杂度或查询性能超出阈值时，再考虑专用检索服务。具体阈值需实测确定。[架构推论]
评估必须包含：有答案召回率、无答案拒答表现、引用片段精确性、权限过滤正确率、索引更新延迟、查询 P95、每千次查询成本。向量相似度不能代替来源真实性核验，检索结果也不能直接获得执行工具的权限。
11 · 模型服务与供应商接入
11.1 供应商中立的调用契约
建议抽象 ModelRequest、ModelResponse、UsageRecord、ProviderError、ToolCall，记录模型标识、实际路由、提示词版本、超时、Token、缓存命中、估算成本和响应 ID。不要假定所有模型具有一致的结构化输出、工具调用、上下文窗口或 Token 统计语义。
11.2 路由策略
模型选择应结合任务类型、质量门槛、价格、延迟、数据策略和可用性。主备模型切换需要重新验证输出格式与质量，不应只根据 API 成功率自动认为结果等价。高风险任务的模型降级需允许人工批准。
11.3 成本
总成本包括模型输入/输出 Token、缓存、检索、存储、网络、后台 Worker、追踪保留、人工审核与工程维护。记录估算成本与实际账单成本的区别；按项目、Run、Agent Version 归因，避免多 Agent 重试被重复或遗漏计费。
12 · 身份、权限、安全与合规
| 风险 | 设计要求 | 验证方式 |
|---|---|---|
| 跨租户读取 | 所有业务查询带租户上下文，数据库与 API 双层校验 | 越权测试 |
| 工具权限升级 | 工具能力白名单、运行时作用域授权 | 恶意输入测试 |
| Prompt Injection | 将外部资料视为不可信数据，隔离工具授权 | 对抗测试 |
| 凭证泄露 | 密钥管理、轮换、最小权限、日志脱敏 | 泄露扫描 |
| Trace 泄密 | 采样、字段脱敏、保留期、访问审计 | Trace 访问矩阵 |
| 文件上传 | 类型/大小校验、恶意文件扫描、隔离处理 | 文件安全测试 |
| 供应链风险 | 锁定依赖、SBOM、漏洞监测、升级策略 | CI 检查 |
| 数据删除 | 对象、索引、缓存、备份保留策略 | 删除演练 |
用户可见的 Agent 推理摘要与内部模型隐藏推理应区分；监控和审计只应收集为完成业务目标所必需的内容。引用 OWASP LLM Top 10 和 NIST AI RMF 作为风险研究框架，不意味着遵循某项清单即可自动获得合规认证。
13 · 可观测、评估与质量门禁
建议建立三条彼此关联但不能互相替代的数据链：业务事件链（状态与审计事实）、Telemetry 链（Trace/Metric/Log 诊断）、Evaluation 链（内容质量、事实性、引用与人工审核）。三者以 run_id、step_run_id、agent_version_id 关联。
指标至少包括：Run 完成率、失败率、P50/P95 耗时、队列等待、重试率、工具错误率、每个合格交付的总成本、审核返工次数、引用核验通过率。每个指标须定义分母、时间窗口、排除条件及缺失数据处理方式。OpenTelemetry GenAI 语义约定仍存在版本演进，具体字段应按所用版本锁定。[规范/官方]
14 · 部署与基础设施选型
| 阶段 | 候选部署形态 | 适用判断 | 注意事项 |
|---|---|---|---|
| 开发/PoC | 本地 Docker Compose | 单人开发、快速复现 | 不代表生产高可用 |
| MVP | 托管 Web + 独立 Worker + 托管 PostgreSQL/对象存储 | 运维能力有限、负载中小 | 后台执行时限、网络、备份 |
| 增长期 | 容器服务 + 多 Worker + 独立队列 | 并发与隔离需求增长 | 调度、自动扩缩、故障域 |
| 复杂平台 | Kubernetes 或类似编排平台 | 多团队、多服务、复杂治理 | 平台维护与安全成本高 |
部署选型需对照服务地区、网络延迟、模型 API 可达性、数据驻留、灾备、服务条款和预算。不要因为未来可能扩张而提前引入 Kubernetes；也不要因为 PaaS 简单就忽略 Worker 持久运行与长审批场景的限制。[架构推论]
15 · Studio 三组候选架构与权衡
15.1 方案 A：TS 平台 + Python Agent Worker + 状态化编排
构成：Next.js/TS UI、Platform API、PostgreSQL、队列、Python Worker、LangGraph 或同类图式编排、对象存储、OTel。优势是保留 Web 开发栈并利用 Python AI 生态；代价是双语言、跨服务协议与部署复杂度。适合调研与分析工具依赖 Python 较多的场景。[待实验]
15.2 方案 B：TS 全栈 + Agent SDK + 自建业务工作流
构成：Next.js/TS UI、TS API、TS Worker、Agents SDK 或同类运行时、PostgreSQL 状态机、队列、对象存储。优势是类型共享和初期运维较简单；代价是长任务恢复、审批、补偿与状态迁移由团队实现。适合流程可控且团队 TS 技能占优的场景。[待实验]
15.3 方案 C：TS Web + Temporal + Agent Worker
构成：Next.js/TS UI、Platform API、Temporal Workflow/Worker、Agent Runtime、PostgreSQL 业务库、对象存储。优势是把长流程调度与恢复交给专门工作流系统；代价是额外基础设施、开发模型和运维负担。适合长等待、复杂依赖和更高可靠性要求得到验证的阶段。[待实验]
15.4 决策建议
目前不宜直接宣布 A/B/C 的最终胜者。先基于 Studio 的同一研究工作流实现薄 PoC：固定输入、模型、工具 Mock、失败注入和验收条件；比较恢复正确性、工程工时、运维负担与成本，再签署 ADR。若现有仓库已实现部分能力，应优先评估复用而非重写。
16 · PoC 设计：以相同任务进行公平对照
16.1 标准任务集
| PoC | 场景 | 注入条件 | 必须观察 |
|---|---|---|---|
| POC-01 | 选题→审核→返工 | 审核连续两次拒绝 | 状态图与终止条件 |
| POC-02 | 人工审批等待 | 暂停后重启 Worker | 审批令牌、恢复一致性 |
| POC-03 | 工具执行 | 调用后响应丢失 | 幂等、去重或补偿 |
| POC-04 | 产物生成 | 上传成功但数据库提交失败 | 孤儿文件与恢复 |
| POC-05 | 任务取消 | 取消与成功同时发生 | 状态冲突处理 |
| POC-06 | 供应商限流 | 429 与超时混合 | 退避、预算与最大重试 |
| POC-07 | 跨租户访问 | 用户读取他人 Run | 全链路拒绝与审计 |
| POC-08 | 追踪对账 | 丢失一段 Telemetry | 业务状态不受影响 |
| POC-09 | 版本切换 | 运行中发布新 Agent | 旧 Run 固定版本 |
| POC-10 | 导出交付 | 审核后修改报告 | 旧批准不自动覆盖新版本 |
16.2 固定实验条件
使用相同机器规格、数据库版本、测试数据、并发模式、模型 Mock、网络延迟模拟与随机种子。若需测试真实模型质量，另设质量实验；避免模型随机性污染工作流可靠性比较。记录 CPU/内存、数据库连接、失败率、P95、模型 Token、运行费用、部署时间与代码维护复杂度。
16.3 可复现报告模板
experiment_id: POC-02
candidate: "方案 A / 方案 B / 方案 C"
commit: "<git-sha>"
framework_versions: {}
environment: "<OS/CPU/RAM/DB>"
scenario: "等待人工审批时重启 Worker"
expected: "重启后同一 Run 可继续且不会重复执行已完成步骤"
observed: null
result: not_tested
artifacts: ["logs", "db_snapshot", "trace", "cost_record"]
reviewer: null17 · 参考开发路线与技术冻结策略
阶段 T0（基线）：盘点现有仓库、部署与数据库；形成 P0 验收清单、ADR 模板和实验环境。阶段 T1（单 Run）：完成 Agent 定义、Run、Step、事件与产物闭环。阶段 T2（工作流）：加入审核返工、人工等待、恢复、取消与幂等。阶段 T3（运营）：加入权限、成本、追踪、告警、备份和故障演练。阶段 T4（平台化）：按实际需求引入多租户、开发者 API、版本治理与扩容。阶段是建议顺序，不代表现有开发进度。
冻结策略：在 T1/T2 PoC 结束后暂时冻结核心状态契约与 API 版本；允许替换内部 Agent SDK，但任何替换必须通过回归测试。只有出现明确的性能、成本、可靠性或维护瓶颈时，才重审架构。
18 · 常见选型误区与反例
| 误区 | 失败机理 | 更合理的做法 |
|---|---|---|
| 先选热门框架再定义需求 | 演示路径掩盖业务约束 | 先列 P0 行为 |
| 把 Agent SDK 当完整平台 | 缺少权限、产物、审计与治理 | 明确分层 |
| 以“支持暂停”推断可靠恢复 | 未验证重启和版本迁移 | 故障注入 |
| 用 Redis 缓存作为唯一业务状态 | 驱逐/恢复影响事实完整性 | 事务数据库真相源 |
| 认为消息队列保证恰好一次副作用 | 重投递导致外部重复动作 | 幂等与补偿 |
| 为避免双语言而重写全部工具 | 迁移成本与风险过高 | 清晰服务契约 |
| 直接上微服务/Kubernetes | 运维复杂度先于业务价值 | 模块化单体优先评估 |
| 只按模型 Token 单价选型 | 忽略重试、审核与运营成本 | 总拥有成本 |
| 将 Trace 视为审计日志 | 采样/保留/脱敏破坏完整性 | 独立业务事件账本 |
| 仅测成功路径 | 崩溃与权限问题上线暴露 | 失败矩阵 |
| 过早引入向量数据库 | 增加同步与运维负担 | 先测检索质量与规模 |
| 依赖自动生成代码而不验收 | 复杂状态机隐藏竞态 | 测试与代码审查 |
19 · 验收矩阵（设计用例，未执行）
下列用例均为待实施的参考测试，并非已通过的测试结果。
| ID | 验收项 | 通过标准 |
|---|
| REQ-01 | 需求追溯 | 每个 P0 有对应测试与责任人 |
| REQ-02 | 候选清单 | 每个候选标注版本与许可 |
| REQ-03 | 硬门槛 | 未通过 P0 的候选不进入生产 |
| ADR-01 | 架构决策 | 保留证据与回退条件 |
| ADR-02 | 复审机制 | 触发条件可量化 |
| UI-01 | 运行刷新 | 断线后状态与服务端一致 |
| UI-02 | 审批冲突 | 并发审批不产生双重决定 |
| API-01 | 请求幂等 | 相同键重复提交不重复创建 |
| API-02 | 版本契约 | 旧客户端收到明确兼容错误 |
| API-03 | 分页 | 跨页无丢失与重复 |
| RUN-01 | 单步执行 | 事件和状态一致 |
| RUN-02 | 重启恢复 | 重启后无重复已完成步骤 |
| RUN-03 | 审批恢复 | 等待期间无常驻进程要求 |
| RUN-04 | 审核返工 | 次数上限可终止 |
| RUN-05 | 取消竞态 | 最终状态单调一致 |
| RUN-06 | 超时 | 任务超时可归因 |
| RUN-07 | 重试 | 永久错误不无限重试 |
| RUN-08 | 工具副作用 | 重复投递不重复外部动作 |
| RUN-09 | 版本固定 | 旧 Run 不随新发布改变 |
| RUN-10 | 并发 | 限制生效且公平调度 |
| DB-01 | 事务完整性 | 部分失败不产生错误成功态 |
| DB-02 | 索引 | 关键查询达到目标 P95 |
| DB-03 | 迁移 | 回滚/前向修复可执行 |
| DB-04 | 备份恢复 | 达到经批准的 RPO/RTO |
| ART-01 | 对象一致性 | 孤儿文件可清理 |
| ART-02 | 版本审核 | 内容变更需重新审核 |
| ART-03 | 访问控制 | 签名 URL 无越权 |
| SEC-01 | 租户隔离 | 跨租户读取被拒绝 |
| SEC-02 | 工具授权 | 未授权调用被拒绝 |
| SEC-03 | 注入防护 | 不可信内容不能升级权限 |
| SEC-04 | 密钥保护 | 日志与产物不暴露凭证 |
| OBS-01 | Trace 对账 | 可关联 Run/Step |
| OBS-02 | Telemetry 丢失 | 不影响业务状态 |
| OBS-03 | 成本归因 | 重试成本正确累计 |
| EVAL-01 | 质量评估 | 与执行成功独立记录 |
| EVAL-02 | 引用质量 | 证据可定位并核验 |
| OPS-01 | Worker 扩缩 | 不丢失任务 |
| OPS-02 | 限流降级 | 预算与并发阈值生效 |
| OPS-03 | 故障演练 | 依预案恢复 |
| COST-01 | 成本基线 | 记录同负载全量成本 |
| DOC-01 | 运行手册 | 新成员可复现实验 |
| DOC-02 | 退出策略 | 能导出数据并替换适配器 |
20 · 研究总结与后续衔接
技术选型的交付物不应仅是“选择某某框架”，而应包括：需求与硬门槛、候选清单、实验结果、权衡矩阵、ADR、风险清单、回退路径和复审阈值。对 Studio 最有价值的近期工作，是验证可恢复研究工作流的最小闭环，再据此确定编排、运行时与数据基础设施。本文提出的候选组合均有条件性，不能代替仓库审计和同负载实验。
下一篇：03 · 如何设计 Agent Platform 的系统架构？ - System Design。 下一专题将把选型结果转化为模块边界、领域对象、运行时序、数据一致性、部署拓扑与故障恢复设计。
第六轮跨章节契约核对（v1.3-r1；2026-11-01）
[平台设计决策 / 待测试] 本节是领域级一致性修订说明，优先于本篇不一致的历史局部示例；不表示已执行数据库迁移、API 合约或运行测试。统一参考：
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md。
本篇 Mermaid 中 waiting_approval、cancel_requested、canceled 是PoC 讨论用状态，并非可复制的统一 Run 枚举。正式契约建议使用 waiting + status_reason=approval、desired_action=cancel、cancelling 和终态 cancelled；审批恢复须遵守持久化与重调度规则。
上述映射不应机械替换其他对象（如 ManagementOperation、Deployment）的同名状态；正式实施应更新 OpenAPI/JSON Schema、SQL 约束、事件消费者、UI 映射及测试。
附录 A：参考文献与原始资料
以下以官方资料为优先，URL 供后续核验；具体 API 与功能应以采用时锁定版本的文档为准。
- Next.js, Documentation. nextjs.org/docs
- React, Documentation. react.dev
- TypeScript, Handbook. www.typescriptlang.org/docs/handbook/intro.html
- NestJS, Documentation. docs.nestjs.com
- FastAPI, Documentation. fastapi.tiangolo.com
- OpenAI, Agents SDK Documentation. openai.github.io/openai-agents-python
- LangGraph, Documentation. docs.langchain.com/oss/python/langgraph/overview
- Temporal, Documentation. docs.temporal.io
- Google Agent Development Kit, Documentation. google.github.io/adk-docs
- CrewAI, Documentation. docs.crewai.com
- BullMQ, Guide. docs.bullmq.io
- Celery, Documentation. docs.celeryq.dev
- PostgreSQL, Documentation. www.postgresql.org/docs
- pgvector, Repository and Documentation. github.com/pgvector/pgvector
- Redis, Documentation. redis.io/docs/latest
- Amazon S3, User Guide. docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html
- OpenTelemetry, Documentation. opentelemetry.io/docs
- OpenTelemetry, Semantic Conventions for Generative AI. opentelemetry.io/docs/specs/semconv/gen-ai
- Prometheus, Documentation. prometheus.io/docs/introduction/overview
- Grafana, Documentation. grafana.com/docs
- W3C, Trace Context. www.w3.org/TR/trace-context
- OWASP, Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10
- NIST, AI Risk Management Framework. www.nist.gov/itl/ai-risk-management-framework
- Kubernetes, Documentation. kubernetes.io/docs/home
- Docker, Documentation. docs.docker.com
- React Flow, Documentation. reactflow.dev
- CloudEvents, Specification. cloudevents.io
- Martin Fowler, Architecture Decision Records (contextual reading). martinfowler.com/articles/architecture-decision-records.html
附录 B：研究证据、验证声明与适用边界
已采用的证据类别：官方产品文档、公开规范与通用工程原则。本文未实施的事项：候选框架安装部署、Studio 仓库审计、性能基准、供应商价格核对、实际故障注入、隐私合规审查、最终架构签署。推论边界：Next.js/TypeScript、PostgreSQL、Worker、对象存储等是参考候选，不代表现有项目已经采用；A/B/C 无实测排名。变化风险：SDK API、许可证、托管限制、服务可用区和 GenAI 语义约定均可能更新。复核要求：正式选型需记录文档访问日期、版本、源码 commit、测试环境、失败日志、成本和审批结论。
与知识库其他章节的关系：P1 - P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 研究技术架构能力；F1 - F2 - F3 - F4 - F5 - F6 - F7 - F8 - F9 - F10 - F11 - F12 研究用户产品功能；本篇将其转换为工程选型条件，下一篇 System Design 将进一步落实系统模块、数据流与部署拓扑。