Harness Engineering（智能体控制框架工程）
Harness Engineering 负责设计智能体周围的控制系统：智能体可以编辑什么、如何接收反馈、将状态写入哪里、故障如何恢复，以及谁可以批准不可撤销的操作。Harness 是区分一次有用的智能体会话与一个可运行数天而不破坏目标的自主循环的关键。
何时激活
在以下情况下激活此技能：
- 构建自主研究或实验循环
- 设计具有锁定指标和可编辑代码/内容的智能体环境
- 创建生成 PR 或后台运行的智能体
- 评估智能体在无需频繁人工提示的情况下能否安全运行
- 为智能体工作流添加新颖性检测、消融、剪枝、回滚或持久化日志
- 防止智能体对基准测试作弊、削弱规则或跨上下文压缩丢失状态
不要将此技能用于其他技能负责的相关工作：
- 通用的质量门禁、回归套件或没有自主控制面的结果指标：请使用
evaluation。 - Harness 工具的工具架构、响应格式和恢复错误：请使用
tool-design。 - 项目级别的任务-模型拟合、流水线形状和成本规划：请使用
project-development。 - 远程沙箱、热池和托管会话基础设施：请使用
hosted-agents。
核心概念
Harness 边界
将智能体与其操作的环境分开。智能体提出行动；harness 定义允许的表面、反馈、持久化和升级规则。
使用四个表面类别：
| 表面 | 示例 | 规则 |
|---|---|---|
| 锁定 | 评估指标、规则、验证脚本、合并策略 | 智能体可以读取并提议修改，但不能使用修改后的规则为自己评分 |
| 可编辑 | 技能草稿、实验文件、提示、待测试配置 | 智能体可在循环中修改 |
| 仅追加 | 结果日志、研究线程、被拒绝的想法 | 智能体只能追加，不能重写 |
| 人工控制 | 合并、生产部署、凭据、破坏性操作 | 需要明确的人工批准 |
紧密反馈循环
自主性在反馈快速、明确且难以作弊时才能发挥作用。Karpathy 的 autoresearch 是最小模式：一个可编辑文件、一个锁定评估文件、固定的挂钟预算、一个标量指标、git 回滚和一个持久化结果日志。这里的教训并不是每个 harness 都需要一个指标，而是模糊的反馈会导致模糊的自主性。
对于开放式的研究到技能工作，请将标量指标替换为锁定的规则、确定性结构检查、源可追溯性和人工审查阈值。
持久化状态
长时间运行的智能体必须外部化状态。将计划、源队列、结果、失败和交接存储在文件中，以便未来的智能体可以恢复而无需依赖聊天历史。Prime Intellect 的自主 nanoGPT 工作展示了持久化便签本（scratchpads）和 THREAD.md 风格日志在恢复、监控和审计中的价值。
使用仅追加日志记录：
- 尝试过什么
- 什么改进了或失败了
- 为什么保留了、丢弃了或路由到了审查的候选
- 检查了哪些上游源
- 下一个智能体应该做什么
搜索纪律
智能体倾向于利用最近的表面、累积复杂性并且很少进行剪枝。添加明确的搜索规则：
- 定期刷新上游源。
- 在花费大预算之前要求进行新颖性检查。
- 保留被拒绝的尝试以避免重复发现。
- 当堆栈中有多个添加时，运行留一法剪枝。
- 在质量相同时奖励简化。
- 在提升之前使用单独的验证。
机制注册表
对于研究到技能系统，将接受的机制与散文分开跟踪。机制记录应包括稳定的 mechanism_id、owning_skill、status、激活场景、行为变更、证据和失败模式。新颖性门禁应首先与此注册表进行比较，然后再使用更广泛的语料库重叠，因为关键字重叠会捕获过时的措辞，而机制比较会捕获真正的重复。
治理
自主智能体可以准备 PR，但治理必须明确。它们可以起草更改、运行检查并编写 PR 摘要。在用户明确授予特定操作的权限之前，它们不应合并、部署或推送。
详细主题
Autoresearch 风格循环
在针对稳定评估器优化工件时使用此模式：
读取锁定上下文 -> 选择假设 -> 编辑允许的表面 -> 提交/设置检查点
-> 运行评估器 -> 记录结果 -> 如果更好则保留 -> 如果更差则丢弃或回滚
-> 重复
必需的属性：
- 评估器位于可编辑表面之外。
- 反馈节奏足够固定以比较尝试。
- 失败的尝试留下审计跟踪。
- 回滚成本低。
- 智能体具有针对崩溃和超时的策略。
研究到技能循环
当源变为技能变更时使用此模式：
发现 -> 检索 -> 门禁 -> 评分 -> 提取机制
-> 映射到现有或新技能 -> 起草提案 -> 验证结构
-> 准备 PR -> 人工审查
锁定评估器是源规则、技能变更规则、结构检查和审查者批准的组合。可编辑工件是提议的技能增量。
指标作弊抵抗
假设一个优化型智能体会学习 harness。防范：
- 编辑评估代码或规则，然后使用新版本进行自我批准
- 添加能取悦评判者但损害技能激活的冗长内容
- 引用未检索的源
- 优化聚合分数但关键维度失败
- 在日志中避免失败的记录
缓解措施：每次运行锁定规则，报告每个维度的分数，要求源检索证据，保留被拒绝的尝试，并将治理变更路由到人工审查。
监控智能体
对长时间运行使用监控智能体，但将其限制为只读报告，除非明确指定其他任务。监控输出应报告：
- 当前最佳候选
- 活跃的任务或草稿
- 上次上游刷新
- 失败或停滞的循环
- 日志与声称状态之间的分歧
- 下一步行动和阻塞项
实用指南
Harness 设计清单
- 用一句话定义目标。
- 识别锁定、可编辑、仅追加和人工控制的表面。
- 选择反馈机制：标量指标、规则、确定性测试、人工审查或组合。
- 定义保留、丢弃、崩溃、超时和审查状态。
- 在循环开始前创建持久化线程日志。
- 为长时间运行的循环添加源刷新、机制注册表新颖性和剪枝规则。
- 定义智能体在不询问的情况下可以做什么以及什么需要批准。
- 在一个已知好的工件和一个已知坏的工件上验证 harness。
文件布局
research-run/
THREAD.md
sources/
queue.md
evaluations/
proposals/
logs/
results.tsv
rejected.md
drafts/
对于仅追加、机器可读的日志使用 TSV 或 JSONL。对于交接和面向审查者的摘要使用 Markdown。
示例
示例 1：锁定指标
智能体优化 train.py，但 prepare.py 负责数据加载和评估。智能体可以编辑模型但不能更改指标。失败的实验被记录并回滚。
示例 2：锁定规则
智能体评估 Anthropic 或 OpenAI 的新工程文章，但源策展规则在运行中被锁定。如果源通过，智能体起草技能提案。它不能降低规则阈值以允许源通过。
示例 3：自动 PR 但不自动合并
智能体在通过源、技能和结构检查后准备分支和 PR 正文。PR 说明未解决的风险，并等待人工合并批准。
指南
- 在开始循环前锁定评估器。
- 保持可编辑表面足够窄以获取可靠的差异。
- 在上下文压缩可能擦除状态之前写入持久化日志。
- 报告每个维度的分数，而不仅仅是聚合分数。
- 在引用之前要求源检索。
- 为广泛搜索添加新颖性门禁，为复杂堆栈添加剪枝门禁。
- 在质量相同时优先简化。
- 将 PR 准备与合并权限分开。
- 使用旧的评估器和新的评估器重新验证 harness 更改。
- 将停止的自主循环视为 harness 故障，而不是智能体个性怪癖。
陷阱
- 可变的评估器：如果智能体可以编辑指标，它可能会优化基准测试而不是任务。在运行期间保持规则和评估代码锁定。
- 仅聊天记忆：当计划仅存在于对话历史中时，长时间运行会在压缩后失败。从一开始就编写线程日志和结果文件。
- 没有丢弃记录：没有被拒绝尝试的日志，智能体会重复失败的想法。保留足够详细信息的失败记录以避免重复发现。
- 复杂性累积：智能体堆叠更改并且很少删除它们。要求剪枝轮次并奖励同等质量的简化。
- 过早的新颖性声称：智能体将重新组合标记为新颖。在声称新颖性之前，与现有仓库技能、源队列和被拒绝日志进行比较。
- 监控误报：监控智能体可能会总结过时或不一致的状态。要求它们引用声称背后的文件或日志。
- 人工批准歧义：“准备 PR”不是“合并 PR”。在 harness 中明确指定批准边界。
- 易变的源漂移：快速变化的实验室声明会迅速过时。在参考资料中放置带有日期的证据并安排重新验证。
集成
此技能连接到：
- evaluation - 规则和质量门禁提供锁定的反馈表面
- advanced-evaluation - 成对比较和偏差缓解改进提案审查
- filesystem-context - 持久化日志、便签本和线程文件保留状态
- multi-agent-patterns - 研究者、验证者、监控者和写作者智能体需要隔离的上下文
- tool-design - Harness 工具必须公开清晰的契约和恢复错误
- project-development - 基于文件的流水线和任务-模型拟合分析保持循环简单
- hosted-agents - 后台执行需要沙箱、快照和批准边界
参考
内部参考：
researcher/README.md- 在实现仓库原生的研究到技能操作系统时阅读researcher/rubrics/harness-change.md- 在评估智能体 harness 的更改时阅读researcher/runbooks/autonomous-research-loop.md- 在运行源到技能循环时阅读
外部资源：
- Karpathy
autoresearch- 具有锁定评估的约束自主实验循环 - Prime Intellect 自主 nanoGPT 速度跑 - 持久化便签本、交接、监控和自主性故障模式
- AlphaEvolve 和 FunSearch - 由系统评估器配对的 LLM 生成候选
- HELM 和 LM Evaluation Harness - 透明、可重复的评估基础设施
技能元数据
创建日期：2026-05-14 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.1.0