要深入理解 Agent Harness，不能只盯着“它用了哪个模型”。真正决定使用体验的，是模型之外那一整套工程架构——这才是让 AI 从一个“对话窗口”进化为“线上协作者”的关键所在。
一个可用的编程 Agent，大致由五个核心模块构成：模型、上下文、工具、文件系统、终端。模型只是其中一环。缺少后四个模块，哪怕模型再强大，也只能给出建议，无法真正完成任务。这就像一位顶尖医生没有手术刀和监护仪，光靠大脑无法进行手术。
一、模型：负责推理，不负责执行
模型的职责是理解目标、拆解任务、判断下一步该做什么。例如，它会判断：这个 bug 应该先排查登录模块，还是先运行测试；这个报错更像类型问题还是运行时异常；这个修改应该补充单元测试还是集成测试。但是模型不能直接读取你的代码仓库，也不能自行执行 npm test。它需要 Harness 提供工具支持。
这也是为什么同一款模型，放在不同的 Agent Harness 里，体验差距会非常大。聊天窗口中的模型只能回答问题；终端 Agent 里的模型能读取文件、修改代码、执行命令、查看错误输出，然后继续修复。模型的能力上限并不低，但实际体验的瓶颈往往在 Harness 的工程设计上。
二、上下文：决定 Agent 能感知到什么
上下文是 Agent 的工作台，它可能包含：
- 用户当前任务；
- 当前对话历史；
- 相关文件内容；
- 搜索结果；
- Git diff；
- 终端输出；
- 项目规则；
- 历史记忆；
- 外部文档；
- 工具说明。
上下文并非越多越好。真正的难点在于“选择”。如果让 Agent 修复支付回调问题，它应该优先关注支付入口、订单服务、状态流转、队列消费者和相应测试，而不是整个前端目录。一个优秀的 Agent Harness 会让模型逐步探索，而不是一次性吞噬全部代码。
::: center  :::上下文管理的核心目标，是让模型在每一步都能获取刚好够用的信息——信息太少看不清全局，信息太多反而被噪声淹没。
三、工具：让模型具备行动能力
工具是 Harness 的“双手和双脚”。常见工具有：
| 工具 | 作用 |
|---|---|
| Read | 读取文件 |
| Edit | 修改文件 |
| Search | 搜索文件名与内容 |
| Shell | 运行命令、测试、构建 |
| Git | 查看 diff、提交、分支 |
| Browser | 打开页面、截图、交互 |
| MCP | 连接外部系统 |
| Subagent | 分配子任务 |
工具调用的关键不在于数量，而在于反馈质量。每次工具返回结果后，模型都需要重新判断下一步操作。
例如：
运行测试 -> 发现失败 -> 读取失败文件 -> 修改实现 -> 再运行测试这就是 Agentic Loop —— 模型的每一次行动都依赖工具返回的结果来修正方向，循环往复直到任务完成。
四、文件系统：真实世界的代码入口
对于编程 Agent 而言，最重要的能力之一就是直接操作文件系统。它能查看当前目录、子目录、配置文件、测试文件、构建脚本，也能新建文件、修改已有文件。这个能力非常强大，但同时也伴随着风险。
一个成熟的 Agent Harness 必须妥善处理三个问题。
第一，作用范围。Agent 是否只能访问当前项目？能否读取上级目录？能否访问用户主目录？
第二，改动可追溯。每次修改了哪些文件、改了什么内容、能否回滚——这直接决定了开发者是否敢于让它动代码。
第三，保护用户未提交的变更。用户已经修改但尚未提交的文件，Agent 不能随意覆盖。
这也是为什么 Git 状态和 diff 对 Agent 至关重要。它不仅帮助模型理解当前工作进度，还能保护人类开发者的现场——谁都不希望写到一半的代码被 AI 一键覆盖。
五、终端：将验证闭环完整连接
没有终端，Agent 写代码很容易停留在“看上去正确”。有了终端之后，它可以：
npm test
npm run lint
mvn test
cargo test
go test ./...
git diff这让 Agent 从“生成代码”升级为“验证代码”——修改完后运行一遍测试，通过才算完成。
但终端也是风险最高的地方。读取文件通常风险较低，运行命令则复杂得多。npm test 可以允许，rm -rf 必须拦截，部署命令需要确认，数据库迁移操作尤其要谨慎。
因此，Agent Harness 一般会将命令分级：安全命令自动执行，普通命令需询问确认，高危命令禁止或强制人工审批。这并非保守，而是对生产环境应有的敬畏。
真实任务中的协同配合
假设任务是：
修复用户退出登录后仍能访问个人中心的问题。Agent Harness 的工作流程可能是：
- 模型理解目标；
- 搜索
logout、session、auth middleware； - 读取路由守卫和会话逻辑；
- 运行现有认证测试；
- 修改退出登录后的状态清理逻辑；
- 新增“退出后访问个人中心返回 401”的测试用例；
- 运行相关测试；
- 输出改动说明。
这里每一步都依赖不同组件。模型负责判断，搜索和读取提供上下文，文件系统承载修改，终端完成验证。每个环节都不可或缺，配合的好坏直接决定这个任务是一次通过还是反复折腾。
容易被忽略的细节
很多人只关注模型能力，却忽视了 Agent Harness 的工程细节。
比如，搜索工具速度慢，Agent 就会浪费大量时间；上下文压缩质量差，长任务会丢失关键指令；权限设计粗糙，用户会不敢让它自动执行；测试反馈不清晰，模型会反复修错方向。
因此，Agent Harness 的品质往往体现在小地方：文件搜索是否快速、diff 是否清晰、命令输出是否截断合理、错误信息能否被模型正确理解、上下文是否能稳定保留。这些细节才是区分“能用”与“好用”的分水岭。
总结
Agent Harness 不是一个“AI 对话框”，而是一套工程执行系统。
它的核心组成可以归纳为：
模型负责推理
上下文负责提供信息
工具负责行动
文件系统负责落地
终端负责验证
权限负责边界只有这些部分协同配合，AI 编程才能从“生成一段代码”真正走向“完成一个任务”。如果你正在调研或搭建自己的 Agent 系统，建议多花精力在模型之外的工程细节上——那才是真正拉开体验差距的关键所在。
