02｜Agent Harness 的核心组成：模型、上下文、工具、文件系统和终端

理解 Agent Harness，不能只看“它用了哪个模型”。真正决定体验的，是模型之外那一整套工程结构。

一个可用的编程 Agent，大致由五个部分组成：模型、上下文、工具、文件系统、终端。模型只是其中一个部件。没有后面四个，模型再强也只能给建议，不能完成任务。

一、模型：负责推理，不负责执行

模型的职责是理解目标、拆解任务、判断下一步该做什么。比如它会判断：这个 bug 应该先看登录模块，还是先跑测试；这个报错像类型问题，还是运行时问题；这个改动应该补单元测试，还是集成测试。

但模型不能直接读你的仓库，也不能自己运行 npm test。它需要 Harness 提供工具。

这也是为什么同一个模型，放在不同 Harness 里体验会差很多。聊天框里的模型只能回答；终端 Agent 里的模型可以读文件、改代码、跑命令、看错误输出，然后继续修。

二、上下文：决定 Agent 看见什么

上下文是 Agent 的工作台。

它可能包含：

• 用户当前任务；
• 当前对话历史；
• 相关文件内容；
• 搜索结果；
• Git diff；
• 终端输出；
• 项目规则；
• 历史记忆；
• 外部文档；
• 工具说明。

上下文不是越多越好。真正难的是选择。

比如你让 Agent 修支付回调问题，它应该优先看支付入口、订单服务、状态流转、队列消费者和测试，而不是整个前端目录。一个好的 Harness 会让模型逐步探索，而不是一次性吞下所有代码。

上下文管理的目标，是让模型在每一步拿到刚好够用的信息。

三、工具：让模型能行动

工具是 Harness 的手脚。

常见工具包括：

工具调用的关键不是数量，而是反馈。每次工具返回结果，模型都要重新判断下一步。

例如：

运行测试 -> 发现失败 -> 读取失败文件 -> 修改实现 -> 再运行测试

这就是 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 的工作过程可能是：

1. 模型理解目标；
2. 搜索 logout、session、auth middleware；
3. 读取路由守卫和会话逻辑；
4. 运行现有认证测试；
5. 修改退出登录后的状态清理；
6. 新增“退出后访问个人中心返回 401”的测试；
7. 运行相关测试；
8. 输出改动说明。

这里每一步都用到不同组件。模型负责判断，搜索和读取提供上下文，文件系统承载修改，终端完成验证。

容易被忽略的部分

很多人只关心模型能力，却忽略了 Harness 的细节。

比如搜索工具慢，Agent 就会浪费大量时间；上下文压缩差，长任务会丢关键指令；权限设计粗糙，用户会不敢让它自动执行；测试反馈不清晰，模型会反复修错方向。

因此，Agent Harness 的质量往往体现在小地方：文件搜索是否快、diff 是否清楚、命令输出是否截断合理、错误是否能被模型读懂、上下文是否能被稳定保留。

总结

Agent Harness 不是一个“AI 对话框”，而是一套工程执行系统。

它的核心组成可以归纳为：

模型负责推理
上下文负责提供信息
工具负责行动
文件系统负责落地
终端负责验证
权限负责边界

只有这些部分配合好，AI 编程才会从“生成一段代码”走向“完成一个任务”。