Harness 的组件
工具调度、上下文管理、权限、会话、错误恢复与生命周期。
一句话理解：Harness 可以拆成十个模块：循环控制、上下文装配、工具注册与调度、权限策略、执行环境、会话与状态、错误恢复、生命周期事件、预算限制和可观测性；每个模块背后都藏着一个需要产品来拍板的决策。
上一课我们知道了 Harness 是模型外面的整套运行系统。但“运行系统”太抽象，没法拿去评审。和研发讨论时，更有效的做法是画一张组件图，然后逐个模块问：“这里的默认行为是什么？谁来决定？出错了会怎样？”
这一课给你这张图，并用「订单售后诊断 Agent」把每个模块落到具体设计上。
一张架构图
读图顺序：请求进入后，循环控制器反复执行“装配上下文 → 调模型 → 解析输出 → 调度工具 → 权限检查 → 执行 → 整形结果 → 回到装配”，直到模型给出不含工具调用的最终回答，或触发停止条件。
十个模块逐个看
1. 循环控制器
负责“继续还是停”。停止的原因包括：模型给出最终回答、达到最大轮数、超出预算、被用户中断、遇到需要人工的节点。停止条件的设计细节见 停止条件。
产品决策：上限设多少？达到上限时是直接失败、返回部分结果，还是允许用户“加额度继续”？
2. 上下文装配器
每次调用模型前，把系统指令、项目说明、工具定义、历史消息、工具结果、记忆拼成一次请求。长任务里它还要负责压缩和清理（见 长任务的上下文管理）。
产品决策：哪些信息每步都给（例如业务规则），哪些按需加载（例如某类商品的退款政策）？
3. 工具注册与调度器
维护“有哪些工具、参数长什么样、实际调用哪个函数”，并决定多个工具调用是并行还是串行。一个值得借鉴的默认策略：Claude Agent SDK 会让只读工具并发执行，而会修改状态的工具（编辑文件、执行命令）按顺序执行，避免互相冲突。
这个分流策略可以画成下图：
产品决策：给模型暴露多少工具？是一次全部暴露，还是按场景动态加载？
4. 权限与策略引擎
在工具真正执行前判断“允许、拒绝还是问人”。常见的配置维度有三个：允许清单（自动放行）、拒绝清单（无论如何都不执行）、权限模式（整体上有多信任 Agent）。以 Claude Agent SDK 为例，权限模式包括默认模式、自动接受文件编辑、只规划不修改、以分类模型自动审批等多档，并明确建议“跳过所有权限检查”的模式只在隔离环境中使用。
产品决策：操作如何分级？详见 操作分级 与 Human-in-the-loop。
5. 执行环境
工具在哪里执行：调用远程 API、在本地终端、在容器沙箱、在浏览器里。执行环境决定了“最坏情况下能造成多大破坏”，详见 沙箱。
6. 会话与状态存储
保存对话历史、任务进度、中间产物，支持恢复与分叉。注意一个容易忽略的边界：Claude Agent SDK 的文档明确指出，会话保存的是 对话，不是文件系统；要回滚 Agent 改过的文件需要单独的文件检查点机制。这类边界在 会话与持久化 中展开。
7. 错误恢复
处理模型 API 限流、工具超时、参数错误、做到一半中断等情况。详见本模块的 错误恢复与重试。
8. 生命周期事件（Hooks）
在“工具调用前后、会话开始结束、上下文压缩前”等时刻插入确定性代码，用于审计、拦截、改写参数、注入上下文。详见 Hooks 与生命周期。
9. 预算与限制
轮数、Token、金额、时长、并发数。Claude Agent SDK 提供了按轮数（max_turns）和按金额（max_budget_usd）两种上限，触发时返回对应的错误类型；OpenAI Agents SDK 的 Runner 同样有 max_turns，超过时抛出 MaxTurnsExceeded。
10. 可观测性
记录每一次模型调用与工具调用的输入、输出、耗时、Token 与成本，支撑调试、评估和计费。详见 Tracing。
把组件落到订单售后诊断 Agent 上
| 模块 | 设计决策 | 默认值 | 谁拍板 |
|---|---|---|---|
| 循环控制 | 最大轮数；打转检测 | 15 轮；同一工具同一参数连续 3 次即停 | 产品 + 研发 |
| 上下文装配 | 订单操作记录保留条数；规则文档加载方式 | 最近 20 条；退款规则按商品类目按需加载 | 产品 |
| 工具调度 | 并行策略 | 查询类并行；创建工单串行 | 研发 |
| 权限策略 | 操作分级 | 查询自动；发通知需确认；改订单状态需主管审批 | 产品 + 业务 |
| 执行环境 | 数据分析脚本在哪跑 | 无外网的隔离容器 | 研发 + 安全 |
| 会话与状态 | 会话保留多久；批量任务进度存哪 | 会话 30 天；进度存业务库 | 产品 + 合规 |
| 错误恢复 | 重试与降级 | 超时重试 2 次；仍失败标记“待人工” | 产品 |
| Hooks | 需要强制执行的规则 | 写操作前校验订单归属；所有调用写审计日志 | 产品 + 安全 |
| 预算 | 单任务成本上限 | 单个订单诊断不超过设定金额 | 产品 |
| 可观测性 | 记录粒度与脱敏 | 全量记录；手机号脱敏 | 研发 + 合规 |
这张表本身就是一份很好的评审材料：每一行都对应一个“如果不定，研发就会自己拍一个默认值”的决策点。
框架里的组件对应关系
不同框架把这些组件叫不同的名字。下表只列出已在官方文档核实过的对应项，便于你看文档时快速定位：
| 模块 | Claude Agent SDK | OpenAI Agents SDK | LangGraph |
|---|---|---|---|
| 循环控制 | 内置 Agent Loop，max_turns |
Runner，max_turns |
由你定义的图（节点与边） |
| 权限 | allowed_tools、disallowed_tools、permission_mode |
工具级审批（needs_approval）、Guardrails |
在节点中用 interrupt() 暂停等待人工 |
| 生命周期 | Hooks（如 PreToolUse、PostToolUse） |
RunHooks / AgentHooks |
图中的节点本身 |
| 会话与状态 | Sessions（resume / fork） | Sessions（如 SQLiteSession） |
Checkpointer + thread_id |
| 可观测性 | 结果消息中的用量与成本 | 内置 Tracing | 需结合配套工具 |
常见误区
- “这些组件第一版都要做全。” 第一版至少要有：最大轮数、工具错误处理、写操作确认、完整日志。其余可以随规模补齐。
- “权限写在 Prompt 里就行。” Prompt 是建议，不是强制。必须保证的规则要放进权限引擎或 Hooks，见 程序校验优先。
- “状态就是聊天记录。” 聊天记录很难被程序可靠解析。批量任务的进度应该是结构化数据，见 任务状态与 Checkpoint。
设计要点
- 为每个模块写下“默认行为”和“失败行为”，缺一不可。
- 把“必须遵守”的规则从 Prompt 中挑出来，下沉到权限引擎、Hooks 或工具实现里。
- 每个工具调用都要有唯一 ID，贯穿权限判断、执行、日志与结果，方便追查。
- 预算至少设两道：轮数上限和金额上限，并决定触发后的用户体验。
- 会话、任务状态、业务数据分开存，不要让聊天记录充当数据库。
练习
拿出你正在设计（或正在使用）的一个 Agent，照着本课的“订单售后诊断 Agent”表格，填写十个模块的设计决策、默认值和拍板人。标出其中 还没有人想过 的格子，这些就是下一次评审会要讨论的议题。预计用时 40 分钟。
延伸阅读
- How the agent loop works：Claude Agent SDK 对循环、消息类型、权限模式、预算与自动压缩的完整说明。
- OpenAI Agents SDK：Agents、Handoffs、Guardrails、Sessions、Tracing 等核心原语。
下一步
接下来几课逐个拆开这些模块，先从最基础的一环讲起：下一课「上下文装配：每一轮请求怎么拼出来」，看 Harness 每一轮到底把哪些东西、按什么顺序交给模型。