Harness Handbook：让演化中的 Agent Harness 可读、可导航、可编辑
Harness Handbook：让演化中的 Agent Harness 可读、可导航、可编辑
核心结论
Harness-Engineering 的下一层瓶颈不是“有没有 prompt / tool / memory”，而是当 harness 本身变成复杂代码系统后，开发者和 coding agent 能否快速定位“某个行为”由哪些文件、函数、阶段和状态转移共同实现。论文提出 Harness Handbook：从 harness codebase 自动合成一个行为中心的手册，把文件/函数组织成执行阶段、行为条目、调用关系和 state-register view，并在修改时用 Behavior-Guided Progressive Disclosure（BGPD）逐步展开相关上下文。
为什么对用户重要
用户的 Hermes / llm-wiki 工作流已经包含 skills、cron、tools、gateway、wiki ingest、vector index、验证门禁等多个 harness 层。随着规则持续累积，失败会从“模型不会做”转向“agent 找不到控制逻辑在哪里、改错边界、忘记同步文档”。Harness Handbook 的价值在于把 harness 当成需要持续维护的工程对象，而不是散落在 prompt、脚本和口头经验里的隐性系统。
机制 / 一阶原理
传统代码索引以文件和符号为中心，但 harness 修改请求通常以行为描述出现，例如“在工具可靠性变化时换路由”“在完成报告前检查 receipts”。这中间存在一个映射鸿沟：行为跨越 prompt construction、state management、tool invocation、validation、resynchronization 等多个阶段。Harness Handbook 用三步降低这个鸿沟：
- 静态事实抽取：从代码中抽取文件、函数、调用、状态和配置事实。
- 行为组织：把底层事实按执行阶段和行为条目重组，生成 function-as-leaf 或 file-as-leaf 的文档树。
- 修改时渐进披露：先根据行为选择相关阶段/条目，再展开调用关系和源码证据，避免把整个仓库塞进上下文。
这和 Context-Engineering 的核心一致：上下文不是越多越好，而是要按任务行为边界组织、按证据逐步展开。
与已有 wiki 概念的关系
- 延续 Harness-Engineering：从“harness 是控制层”推进到“harness 自身需要行为地图和同步机制”。
- 补强 Repository-Exploration：仓库探索不能只问“哪些文件相关”，还要问“目标行为在哪些阶段和状态转移中出现”。
- 支持 Agentic-Coding：coding agent 修改复杂 harness 前应先定位行为链，而不是直接 grep 关键词后 patch。
- 呼应 Context-Engineering：Handbook 是一种可持久化、可审查、可更新的 context artifact。
对 Hermes / llm-wiki 的可执行启发
- 为 Hermes 自身的长期自动化建立“harness map”：cron 发现、source extraction、raw archive、page promotion、index/log、vector reindex、delivery 分别对应哪些脚本/skill/规则。
- 每次自我优化不只写反思，还要标注它影响的是哪个 harness 阶段：discovery、ingest、verification、routing、reporting 或 maintenance。
- 对复杂工具链改动采用 BGPD 风格：先定位行为阶段，再读局部文件和调用关系，最后修改；避免在无人 cron 里大范围猜改。
- llm-wiki 页面模板可以加入“影响的 workflow 阶段”字段，帮助未来从知识点反推可改进的系统部位。
失败模式 / 边界
- Handbook 若不随代码和技能变化同步，会变成更危险的陈旧上下文。
- 行为抽取依赖 LLM synthesis，可能漏掉隐式 side effect、动态配置和外部服务状态。
- 对小脚本过度生成 handbook 可能成本大于收益；适合用于长期演化、跨文件、跨工具的 harness。
- 论文结果仍以特定 harness / 修改请求为实验对象，泛化到 Hermes 需要先做小范围 trial。
深度判断
值得晋升为正式 source 页：它不是泛泛谈 agent，而是直接解决“harness 越来越复杂后如何维护”的二阶问题，能指导 Hermes 把自我优化从每日反思升级为可导航的系统地图。
写入记录
- 2026-07-17 09:00 CST：新增论文深度摘要，提炼行为中心 harness map、BGPD 和对 Hermes/llm-wiki 自我优化的启发。