agent-harness

Agent harness——Agent 收到的指令，以及如何审查别人给 Agent 的指令

agent-orchestrator 负责串联循环。agent-evals 用于验证其行为。agent-interop 负责让它与其他进程通信。**这项技能是它们与模型之间的那一层：提示词、工具和技术选择。**Harness 工程不仅包括指令，还包括上下文管理。其效果取决于任务、模型和评估；基准测试的提升并不能证明它普遍有效。

它有两个方向。构建和审查所用的是同一份清单，只不过一个正向阅读，一个反向阅读，因此它们在此合并介绍。

---

触发条件

“工具描述”、“Agent 循环不停”、“提示词工程”、“Harness 工程”、“ReAct 循环”、“React 模式”、“静态还是动态”、“嵌入 Agent”、“Agent SDK”、“Pi harness”、“встроить агента”。

从 0.31.3 的描述中移至此处：“Agent 选错工具”、“агент не вызывает тул”、“审查这个 Agent”。

规则零——先检查提示词（这是一项诊断启发式，存在例外）

对于工具选择或使用方面的问题，应先检查指令和描述，再添加架构。Anthropic 的工具指南（阅读日期：2026-10-09）支持评估描述变更；它并非缺陷占比的测量结果。这决定的是诊断顺序，而非最终结论。**例外是提示词无法触及的问题：**确定性的竞态、硬编码的密钥、连接到错误操作的超时——源代码层面的不变量违规属于代码错误，改写措辞无法解决。

添加重试机制、路由器或子 Agent 之前，请按以下顺序检查：

1. 工具描述是否说明了何时使用工具，而不仅仅是说明工具的功能？
2. **系统提示词是否明确列出词汇？**如果没有列出允许的值，被告知要跟踪状态的 Agent 在同一轮运行中就会自行创造出 pending、to-do、done 和 completed。
3. **Agent 是否知道今天的日期？**有训练截止日期的模型会依赖记忆作答，而不是搜索，除非注入当前日期。
4. 指令该灵活时是否灵活，该严格时是否严格？“以你认为最合理的顺序使用工具”适用于正在了解任务时；而在生产环境中，这种说法就不合适了，因为只有“你必须为每项任务执行网络搜索”才能防止跳过步骤。

只有完成这些检查后，才考虑采用架构。优先采用架构，正是让提示词缺陷变成永久结构性成本的原因。

---

工作流还是 Agent——先做决定

Agent会动态指导自己的流程。工作流会遵循预定义的代码路径。两者的选择并非取决于复杂程度，而是取决于步骤数能否预先确定。

构建工作流的情况	构建 Agent 的情况
需求清晰且稳定	任务开放或需要探索
可预测性和明确控制很重要	灵活性比可预测性更重要
优先考虑调试和成本控制	需要针对多个变量进行自适应推理
现在就能列出每个步骤	步骤数不可预测，无法硬编码

**从能解决问题的最简单方案开始，到此为止。**Agent 会增加延迟、成本，以及工作流不会遇到的一类故障——它需要相信自己的决策。只有在确实无法编写固定路径时，才值得承担这些代价。

在采用自主运行之前，先了解五种工作流模式

模式	结构	适用场景
提示词链式调用	顺序调用，每次基于上一步的输出，并在中间进行程序化检查	任务可拆解为固定步骤——先列提纲再起草，先起草再翻译
路由	对输入分类，然后交给专门处理的对象	类别彼此明确，且每个类别都需要专属提示词
并行化	分段（同时处理相互独立的子任务）或投票（将同一任务执行 N 次）	子任务相互独立，或需要多个样本来提高置信度
编排器–工作者	由一个中心模型拆解并分派任务，然后综合结果	子任务无法预先定义——这是它与路由的本质区别
评估器–优化器	一个模型生成结果，另一个模型提出批评，然后循环迭代	存在明确的评估标准，且迭代确实能带来可衡量的改进

**编排器–工作者与路由的区别，是人们最容易搞错的地方。**路由从已知集合中选择。编排会根据每个请求生成集合。如果你能列举出所有分支，那你需要的是路由，而且成本更低。

静态还是动态——第二个问题，而且它与前一个问题不同

选定工作流后，还有一点尚未确定：运行前能否确定其结构？ 静态图的所有节点和边都预先确定；动态图则会随着节点读取自身输出并决定下一步操作而不断扩展。

始终优先选择静态——只有当静态版本遇到可以明确指出的瓶颈时，才改用动态，因为动态能力更强，也更难控制。但可审计性与静态结构并非同一维度——把事先绘制的计划和事后保存的执行图混为一谈了。只有当运行的执行记录完整时，才具备可审计性：记录实际运行的每个节点、边和事件，当时生效的策略版本，以及带有来源信息的确定性限制（预算／深度／节点上限）。静态图是首选，因为其实际执行的结构通常与绘制的结构一致；动态图只要在这些限制范围内保留该记录，同样可审计。无论哪种模式，单凭设计示意图都不能作为证据——"这是我的计划"并不等于"这是实际发生的事"。

六行表格、模型的其余部分——虚假边测试、菱形结构、汇合前的检查节点——以及主机实际如何执行扇出，都集中在此处：agent-orchestrator/references/graph-engineering.md。此处不再重述，因为把决策表放在两个地方，只会让它们彼此矛盾。

参考资料

每份资料开头都有自己的 何时加载 行和修订标记——这些内容会变动，而且本工具包的仓库验证器会在参考资料未注明阅读时间时导致构建失败。

文件	何时阅读
references/context-lifecycle.md	上下文过时、检索到的笔记相互冲突，或研究成果被纳入技能指南时——了解当前指针、归档边界和来源准入
references/instruction-budget.md	指令文件超出限制、彼此重复，或需要拆分但又不能丢失要求时；包含用于测量显式输入的脚本
references/system-prompt.md	你正在编写或修复提示词时——高度、结构、词汇、动态上下文，以及推理模型需要做出的调整
references/tools.md	模型选错工具或一个也没选时——Agent 与计算机的接口：工具数量、命名方式、描述方式和返回内容
references/techniques.md	你正在从 ReAct、reflection、voting、planning 等方法中做选择时——每项都附有生产环境适用性结论，而非基准测试分数
references/workbench-contracts.md	围绕现有 Agent 组装框架时——安装所有权、受限钩子、交接、与产物绑定的证据和观测限制；以及选择性采用的 ECC 方法
references/layers.md	决定框架由你负责哪些部分时——内核、工作台和产品层，以及权限边界通常应由其他人负责的原因
references/audit.md	审查并非由你构建的 Agent 系统时——七条审查路线、证据等级和优先级计划
references/pi.md	你想了解上述原则的完整实现示例时——Pi 的会话、压缩、配置、技能、信任和容器化；每项都对应其实现的规则，并说明它刻意有所分歧的地方
references/pi-sdk.md	你正在嵌入或扩展框架时——SDK、RPC 协议、JSON 模式，以及权限门、上下文改写或成本钩子实际可接入的八个扩展点

scripts/audit_agent.py ——审计中的机械检查部分。它可以找出无需理解意图即可发现的问题（无界循环、没有描述的工具、被吞掉的工具错误、硬编码模型、缺失超时），并列出它无法发现的问题，因此它保持沉默绝不意味着通过检查。

**清理指令时的注意事项：**急于通过 @file 导入来重组文本，并不能节省其运行时上下文成本。保留必需规则处于加载状态，将可选细节放在明确的任务触发条件后，并单独验证宿主的新鲜加载情况，不要只测量文件大小（references/instruction-budget.md）。

审计 Agent 系统——简明版

完整版见 references/audit.md。大致流程如下：

1. 先运行扫描器。 这很省事，而且扫描器列出的盲点能告诉你，审计其余部分必须手动检查什么。
2. 逐一检查七个方面——提示词、工具、控制流、上下文、故障、权限、证据——只有附有观察依据时才记录发现。
3. 根据每条建议的依据进行分级： 在此测得、上游文档记载，或判断。
4. 输出按优先级排序的计划，而非分数。 一个数字无法告诉任何人周一该改什么。这也是 agent-evals 用于评估标准、seo-aeo-audit 用于网站的同一条规则。

大多数审计最先发现的问题： 系统没有评估。这是关于未知可靠性的发现——下游每项行为估计都无法证伪，包括本次审计的估计。但这不会抹去源代码中可证实的内容：可证明的重复扣费、硬编码密钥、确定性竞争条件，各自都保留其发现和优先级，并由具体危害决定——泛泛的“没有评估”绝不会掩盖已证实的具体危害。

---

边界

与 agent-orchestrator 的边界。 该技能负责循环的基础设施：迭代保护、裁剪、子 Agent 分派、提供方路由、记忆层、检查点。本技能负责模型接收到的指令。两者在四个接口处交汇，每个接口只在一处跨界：

1. 描述工具，让模型选对工具，由本技能的 references/tools.md 负责；根据能力标志为每个请求组装工具列表，由 orchestrator 的 §3 负责，其中会指向这里来获取措辞。
2. 提示词中写了什么——抽象层次、词汇、枚举状态——由本技能的 references/system-prompt.md 负责；每个请求重建提示词，并在同一轮处理中构建工具列表，则由 orchestrator 的 §10 负责。
3. 工作的形态——静态/动态表、伪边测试、收敛前的检查器——只有一个归属处，而且不在这里：agent-orchestrator/references/graph-engineering.md。本技能关于静态或动态的部分只讨论如何做出决策，并链接到该文档以供参考。
4. 上下文窗口： agent-orchestrator/references/context-engineering.md 讲解压缩——窗口填满时该丢弃什么；本技能的 system-prompt.md 则讲解一开始该放入什么。一个负责填入，一个负责清空，分属两个文件。

与 agent-evals 的边界。 该技能根据执行记录衡量 Agent 的行为；本技能则根据源代码和提示词审查 Agent 的构建方式。审计发现没有评估时，应转交给该技能；若评估套件在同一方面持续失败，则应反馈到这里。

与 agent-interop 的边界。 MCP、A2A、注册表、网关——这些是进程之间的通信线路。工具描述归这里；工具协议归那里。

未涵盖的内容： 模型选择和定价（Anthropic 的相关内容见 claude-api 技能）、转售场景下的资金账户（agent-orchestrator/references/llm-proxy-billing.md），以及 RAG 检索质量；后者属于搜索问题，本技能只涉及它进入提示词的部分。

---

清单 — 值得发布的 harness

• 明确指出是内核还是工作台 harness；区分已安装、已加载和已强制执行的能力
• 审慎决定采用工作流还是 Agent，并实际尝试过更简单的选项
• 同样要决定采用静态还是动态方案——优先选择静态方案以提高可预测性；必须可审计的运行要保留完整执行记录（而不只是静态结构）
• 系统提示词处于恰当的抽象层级——提供启发式指导，而非硬编码分支，也非含糊期待
• Agent 必须输出的每个状态、类别和枚举值都要在提示词中逐一列出
• 注入当天日期和其他易变上下文，而不是想当然地认为 Agent 知道
• 工具：少而精、影响力大，使用命名空间，并像向新同事介绍一样逐一说明
• 工具响应要传达含义，而非标识符，并默认分页或截断
• 工具错误要指导下一次尝试，而不是重复堆栈跟踪
• 每个问题选择一种技术，并说明理由——不要只因某篇论文提到过 ReAct 就采用它
• 子 Agent 返回提炼后的摘要，而不是对话记录
• 能够观察 Agent：使用了哪个工具、传入了哪些参数、观察到了什么、消耗了多少 token
• 先实现可观测性，再实现功能；先做评测，再调优提示词；否则调优就成了道听途说——只有语料库可以等到生产环境再准备