端到端架构与价值取舍
架构的要点，是只在能改变结果的地方引入复杂度。
类型： 参考 语言： Python 前置要求： 业务发现、需求与 SLA；阶段 14，第 01、12 和 28 课 预计时间： 约 135 分钟
学习目标
- 绘制从输入到反馈和运维的完整 Claude 系统
- 在增强模型调用、工作流、agent 和多 agent 系统之间做出选择
- 围绕证据、权限和验证边界拆解复杂工作
- 为成本、延迟、质量、安全性和可维护性之间的取舍给出依据
- 识别模型能力增强也无法修复结构性设计缺陷的场景
问题所在
一个团队上线了合同审查助手。单个 prompt 中塞进了合同、政策库、提取 schema、谈判规则， 还要求输出最终修订稿。演示跑通了，生产环境却不行。
大合同超出了实际可用的上下文预算。政策版本彼此冲突。模型返回了有效 JSON，其中却包含 没有依据的法律结论。审核人看不出每项修改由哪个来源支撑。重试只会增加成本，并不能改变 故障。更大的模型改善了文风，却没有解决可追溯性、权限和生命周期责任问题。
故障根源在于系统把几种不同的职责压进了一个概率性步骤。再给 prompt 加一句话也解决不了。
核心概念
画出完整闭环
端到端架构不只有模型调用。
flowchart LR
I["Input and identity"] --> V["Validate and classify"]
V --> C["Assemble trusted context"]
C --> R["Reason or generate"]
R --> T["Tools and external systems"]
T --> O["Validate output"]
O --> H{"Approval needed?"}
H -->|"yes"| P["Human review"]
H -->|"no"| A["Apply bounded action"]
P --> A
A --> E["Evidence, logs, and outcome"]
E --> F["Evaluation and feedback"]
F --> C针对每条边，问清楚：
- 哪些数据会跨越边界？
- 使用哪个身份和哪些权限？
- 强制执行什么 schema 或契约？
- 超时、含义模糊或部分失败时怎么办？
- 留存哪些证据？
- 谁负责下一项决策？
没有故障路径的架构图，只是一张营销图。
选择能满足需求的最小模式
可以从四种实用模式开始。
增强模型调用
单个请求使用选定的上下文、检索结果或工具，并返回有边界的输出。当步骤已知，而且单轮对话 能够容纳必要证据时，适合用来做分类、提取、起草或评分。
优点：
- 编排开销最低
- 最容易评估
- 延迟和成本可预测
局限：
- 不适合有分支的工作
- 对跨多个外部操作的故障恢复能力有限
确定性工作流
代码控制执行顺序，并在指定步骤调用 Claude。如果业务流程稳定、可审计性很重要，或每次状态 转换都需要明确契约，就使用这种模式。
优点：
- 状态和重试显式可见
- 每个步骤的权限范围更窄
- 测试可以复现
局限：
- 无法预先知道执行路径时会变得脆弱
- 出现新的例外类别就需要修改工作流
自适应 agent
Claude 根据观察结果选择下一项操作，直到满足停止条件。当证据发现过程决定执行路径，而且 逐一列举所有分支并不现实，就使用这种模式。
优点：
- 规划灵活
- 适合开放式研究和修复
局限：
- 延迟和成本不固定
- 权限面和评估面更大
- 存在循环、偏离目标和工具错误风险
多 agent 系统
协调器把相互独立的关注点交给专家或独立审核人。当工作可以拆分、上下文隔离能提高质量， 或验证要求相互独立时，使用这种模式。
优点：
- 并行执行
- 每个角色的上下文更小
- 独立审核
局限：
- 交接损耗和重复工作
- 调用次数更多，追踪分析更困难
- 协调成本可能高于节省的成本
不要因为架构图看起来成熟就选择多 agent。只有具体的上下文、独立性、并行性或专业化需求 足以抵消协调成本时，才应该选它。
围绕契约拆解
糟糕的拆解只遵循文档章节或团队边界，却不考虑如何检查正确性。好的拆解会在每次交接处建立 契约。
对于合同审查系统：
- 受理环节验证文件类型、身份和司法管辖区元数据。
- 条款切分返回稳定标识符和来源范围。
- 政策检索返回带可追溯信息的版本化证据。
- 条款分析按照 schema 返回发现项。
- 独立审核人检查证据覆盖情况和矛盾。
- 仅使用已接受的发现项生成修订稿。
- 重大变更由法务人员批准。
- 系统记录决策证据和后续结果。
每个步骤的任务都比“审查这份合同”更窄。故障可以被定位。系统可以重新尝试检索，而不用 重新生成已被接受的条款分析；审核人也可以只驳回一项发现，而不必丢弃全部工作。
分开语义控制和确定性控制
Claude 适合处理含义模糊的判断，例如某项条款是否实质改变了责任。代码更适合处理不变量， 例如必填字段、权限检查、最高退款金额、允许的司法管辖区和文档版本。
使用下面这条规则：
If a condition can be expressed as a stable predicate over trusted data,
enforce it outside the model.prompt 指令可以引导行为，但无法建立安全边界。
为整条执行轨迹编制预算
成本不只是单次调用的输入和输出 token。一次系统执行轨迹可能包括检索、多次模型调用、工具 执行、重试、审核和人工劳动。
估算：
expected task cost =
model calls
+ retrieval and tool cost
+ retry probability times retry cost
+ human review minutes times labor rate
+ expected incident and correction cost更小的模型如果导致更多重试，每个成功任务的成本反而可能更高。如果更大的模型可以省掉昂贵 的审核步骤，它也可能更便宜，但只有评估才能证明这一点。
把延迟视为一种分布
平均延迟会掩盖用户实际遇到的长尾。模型时间、工具时间、排队、重试和人工审批会叠加在一起。
至少要使用 P50、P95 和超时率。对于交互式工作，既要跟踪首次产生有用输出的时间，也要跟踪 总完成时间。对于后台工作，吞吐量和完成时限可能比首 token 延迟更重要。
并行执行只对相互独立的工作有帮助。如果并行调用争抢同一个速率限制，或输出结果还需要串行 协调，成本可能增加，端到端耗时却不会减少。
把反馈设计成产品界面
零散的点赞事件构不成反馈。每条反馈都要关联结果、输入、版本、执行轨迹和决策。
存储：
- 输入类别和风险等级
- prompt、模型、工具和知识版本
- 检索到的证据标识符
- 工具调用和结构化错误
- 输出和验证器结果
- 人工编辑和原因代码
- 下游结果
反馈闭环由此可以支持具体决策：修改 prompt、修复检索、调整路由、改进工具或缩小范围。
动手构建
交互实验
23-architecture-tradeoff使用架构取舍探索器，按照有权重的质量、延迟、成本、安全性、可审计性和变更成本证据，比较 增强调用、工作流、agent 与多 agent 设计。总分再高，也不能抵消硬性约束。
实践实验
从决策副本中删除一个被否决的备选方案或硬性安全门禁，观察就绪检查失败，再修复架构理由。
交付产物
填写完成的 outputs/architecture-decision.md 选择了确定性的 合同审查工作流，并记录了故障路径和回退条件。
验证
运行确定性决策包校验器：
cd certifications/claude/lessons/23-end-to-end-architecture-and-value-tradeoffs
python3 code/main.py
python3 -m unittest discover -s code/tests -v测验会检查相同的模式和控制决策。
综合项目关联
把 ADR 放入 Architect Professional 综合项目的架构方案部分。
为一个业务工作流创建架构包。
第 1 步：绘制三个候选方案
分别绘制增强调用、确定性工作流和自适应 agent 设计。使用相同的输入、输出和约束，保证比较 公平。
第 2 步：为明确的取舍评分
采用一到五分制，并写出证据。
| 评估标准 | 权重 | 增强调用 | 工作流 | Agent |
|---|---|---|---|---|
| 任务质量 | 25 | |||
| P95 延迟 | 15 | |||
| 每次成功的成本 | 15 | |||
| 安全性和权限 | 20 | |||
| 可审计性 | 15 | |||
| 变更成本 | 10 |
权重来自发现阶段，而不是习惯。如果受监管的操作使安全性成为硬性约束，就不能为了便利而用 平均分抵消它。
第 3 步：编写故障路径
为每个外部依赖项明确超时、重试、熔断行为、部分结果、用户消息和运维证据。对于 agent， 还要设定每轮总时长和成本预算。
第 4 步：定义评估
构建一个有代表性的集合，覆盖正常、含义模糊、对抗性和依赖故障场景。衡量最终质量、执行 轨迹质量、成本、延迟和安全性。
第 5 步：记录回退条件
明确哪些证据会促使团队切换模式。架构记录的是当前决策，可以随证据变化而调整。
上手使用
假设有一个研究系统，必须回答跨多家公司申报文件的问题。
如果一次检索查询就能稳定返回足够的证据，单次增强调用很合适。如果每项任务都遵循查询、 检索、排序、回答和引用的固定流程，工作流很合适。如果系统必须发现缺失的实体、改写查询， 并判断证据是否充足，agent 很合适。只有在并行研究来源或独立验证对目标指标的改善足以抵消 协调成本时，才应该采用多 agent 设计。
现在再加入一小时的答复时限和严格的成本预算。最优设计可能随之改变。架构选择始终受约束条件 影响。
考试决策模式
当各个选项的复杂度不同时，选择满足既定需求的最简单架构。先寻找结构性修复，再考虑修改 prompt。
有力的答案通常会：
- 在代码中强制执行确定性规则
- 隔离高风险工具和权限
- 对已知路径使用工作流，对真正需要自适应的路径使用 agent
- 在独立性属于需求时增加独立审核人
- 在每次转换中保留可追溯信息
- 定义停止、重试、部分结果和升级行为
- 优化每个成功结果的成本，而不是每次调用的成本
薄弱的答案往往只是添加更大的模型、更长的 prompt、更多 agent 或更多工具，却没有处理真正的 故障边界。
常见陷阱
能力膨胀
每个不必要的工具都会扩大 prompt 长度、选择歧义、攻击面和授权风险。只暴露当前角色所需的 最小工具集。
用 prompt 掩盖缺失的契约
如果两个步骤在标识符、schema 或错误行为上无法达成一致，更清晰的自然语言指令也无法建立 可靠接口。应该定义契约。
把自我审核当成独立审核
让同一个上下文“再检查一遍”，可能只会重复同一个假设。如果独立性很重要，应使用独立的 审核人、明确的评分规则和隔离的证据。
只优化演示路径
要判断系统能否用于生产，就看它如何处理含义模糊、数据过期、权限错误、超时和部分失败。 批准架构前必须覆盖这些场景。
练习
- 为发票争议处理流程设计增强调用、工作流和 agent 三个候选方案。选择一个，并说明回退条件。
- 找出 AI 工作流中应该用确定性代码实现的三个不变量。
- 计算两个模型在重试率和审核率不同时，每个成功任务的成本。
- 在多 agent 研究设计中加入一次工具中断，并明确部分结果的处理方式。
- 编写一项评估，用于发现最终文案不错、执行轨迹却浪费资源或不安全的系统。
关键术语
| 术语 | 人们常说的意思 | 实际含义 |
|---|---|---|
| 增强调用 | 一个能力较弱的 agent | 使用选定上下文或工具的有边界模型调用 |
| 工作流 | 步骤固定的 agent | 由代码负责、具有明确状态转换的编排 |
| Agent | 任意 LLM 应用 | 由模型主导、根据观察结果选择操作的循环 |
| 多 agent | 更高的智能 | 为隔离、并行或独立审核而协调多个模型上下文 |
| 契约 | 一条 prompt 指令 | 针对数据、错误和责任的机器可检查边界 |
| 每次成功的成本 | Token 价格 | 每个被接受结果预期承担的模型、工具、重试、审核和纠错总成本 |
延伸阅读
- 构建高效的 agent，了解工作流和 agent 模式
- Claude Agent SDK 文档，了解当前 agent 框架的能力
- 阶段 14，第 01 课：从第一性原理理解 agent 循环
- 阶段 14，第 28 课：编排取舍
- 阶段 17，第 08 课：有效吞吐量和延迟测量