coding-agent-harness

# Coding Agent 与 Harness 工程 ## 何时使用 - 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈） - 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段 - 评估一个任务是否适合交给 Agent 自主执行（四象限判断） - Agent "能跑但不可靠"：跑偏、走破坏性捷径、过早宣布完成 - 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型 ## 核心原则 **Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。** Harness 是"Agent 边界内、模型之外"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。 **Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）： | 组件 | 回答的问题 | 落地形态 | | --- | --- | --- | | 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 | | 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 | | 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 | | 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 | **任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向"目标明确 + 可自动验证"： - 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug） - 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度 - 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化"代码质量"） - 目标模糊 + 需人工验证 = **难以启动**（如"让 UI 更好看"） 代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。 **四条可迁移的设计原则**： 1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是"做不了"，系统提示词里"请遵循..."只是"建议别做"。 2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。 3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。 4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。 **约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建"修复"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。 **并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。 **业界经验**： - 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。 - LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。 - Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决"一次想做太多"和"过早声称完成"。 ## 实践模式 **建一个 Coding Agent 的最小清单**： 1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。 2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把"测试通过"而非"代码写完"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。 3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。 4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。 5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。 6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。 7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。 **上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。 ## 常见陷阱 - 把指导写进提示词而不落成代码约束——模型会忽略"请遵循..."式建议 - 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写） - 写完代码不跑测试就报告"任务完成" - 把整个代码库一股脑塞进上下文，既不经济也没必要 - 一个工具失败就中止整批并行调用甚至整个任务 - 只换模型不修 Harness：基准提升往往来自 Harness 而非模型 - 环境信息硬编码在静态系统提示词里 ## 配套代码 - `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径 - `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用 - `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示"模型即 Agent"的最小闭环 - `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排 - `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来 - `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主 ## 深度阅读 - `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」 - `book/chapter1.md`「Harness 工程：模型之外的竞争力」