理解 Agent Harness，不能只看“它用了哪个模型”。真正决定体验的，是模型之外那一整套工程结构。
一个可用的编程 Agent，大致由五个部分组成：模型、上下文、工具、文件系统、终端。模型只是其中一个部件。没有后面四个，模型再强也只能给建议，不能完成任务。
一、模型：负责推理，不负责执行
模型的职责是理解目标、拆解任务、判断下一步该做什么。比如它会判断：这个 bug 应该先看登录模块，还是先跑测试；这个报错像类型问题，还是运行时问题；这个改动应该补单元测试，还是集成测试。
但模型不能直接读你的仓库，也不能自己运行 npm test。它需要 Harness 提供工具。
这也是为什么同一个模型，放在不同 Harness 里体验会差很多。聊天框里的模型只能回答；终端 Agent 里的模型可以读文件、改代码、跑命令、看错误输出，然后继续修。
二、上下文：决定 Agent 看见什么
上下文是 Agent 的工作台。
它可能包含：
- 用户当前任务；
- 当前对话历史；
- 相关文件内容；
- 搜索结果；
- Git diff；
- 终端输出；
- 项目规则；
- 历史记忆；
- 外部文档；
- 工具说明。
上下文不是越多越好。真正难的是选择。
比如你让 Agent 修支付回调问题，它应该优先看支付入口、订单服务、状态流转、队列消费者和测试，而不是整个前端目录。一个好的 Harness 会让模型逐步探索，而不是一次性吞下所有代码。
上下文管理的目标，是让模型在每一步拿到刚好够用的信息。
三、工具：让模型能行动
工具是 Harness 的手脚。
常见工具包括：
| 工具 | 作用 |
|---|---|
| Read | 读取文件 |
| Edit | 修改文件 |
| Search | 搜索文件名和内容 |
| Shell | 运行命令、测试、构建 |
| Git | 查看 diff、提交、分支 |
| Browser | 打开页面、截图、交互 |
| MCP | 连接外部系统 |
| Subagent | 分配子任务 |
工具调用的关键不是数量，而是反馈。每次工具返回结果，模型都要重新判断下一步。
例如：
运行测试 -> 发现失败 -> 读取失败文件 -> 修改实现 -> 再运行测试
这就是 Agentic Loop。
四、文件系统：真实世界的代码入口
编程 Agent 最重要的能力之一，是直接操作文件系统。
它能看到当前目录、子目录、配置文件、测试文件、构建脚本，也能创建新文件、修改已有文件。这个能力很强，也很危险。
一个成熟 Harness 必须处理好三个问题。
第一，作用范围。Agent 是否只能访问当前项目？能不能读上级目录？能不能访问用户主目录？
第二，改动可追踪。每次修改哪些文件、改了什么、能不能回滚。
第三，用户变更保护。用户已经改过但未提交的文件，Agent 不能随便覆盖。
这也是为什么 Git 状态和 diff 对 Agent 很重要。它不仅帮助模型理解当前工作，还保护人类开发者的现场。
五、终端：把验证闭环接起来
没有终端，Agent 写代码很容易停在“看起来对”。
有终端以后，它可以：
npm test
npm run lint
mvn test
cargo test
go test ./...
git diff
这让 Agent 从“生成代码”变成“验证代码”。
但终端也是风险最大的地方。读文件通常风险低，运行命令就复杂得多。npm test 可以允许，rm -rf 必须拦住，部署命令必须确认，数据库迁移要特别谨慎。
所以 Harness 一般会把命令分级：安全命令自动执行，普通命令询问确认，高危命令禁止或强制人工审批。
真实任务中的配合
假设任务是：
修复用户退出登录后仍能访问个人中心的问题。
Harness 的工作过程可能是：
- 模型理解目标；
- 搜索
logout、session、auth middleware； - 读取路由守卫和会话逻辑；
- 运行现有认证测试；
- 修改退出登录后的状态清理；
- 新增“退出后访问个人中心返回 401”的测试；
- 运行相关测试；
- 输出改动说明。
这里每一步都用到不同组件。模型负责判断，搜索和读取提供上下文，文件系统承载修改，终端完成验证。
容易被忽略的部分
很多人只关心模型能力，却忽略了 Harness 的细节。
比如搜索工具慢，Agent 就会浪费大量时间；上下文压缩差，长任务会丢关键指令；权限设计粗糙，用户会不敢让它自动执行；测试反馈不清晰，模型会反复修错方向。
因此，Agent Harness 的质量往往体现在小地方：文件搜索是否快、diff 是否清楚、命令输出是否截断合理、错误是否能被模型读懂、上下文是否能被稳定保留。
总结
Agent Harness 不是一个“AI 对话框”，而是一套工程执行系统。
它的核心组成可以归纳为：
模型负责推理
上下文负责提供信息
工具负责行动
文件系统负责落地
终端负责验证
权限负责边界
只有这些部分配合好，AI 编程才会从“生成一段代码”走向“完成一个任务”。
