Harness 框架详解

Harness 是什么

Harness = Agent 的载具 / 脚手架，它为模型提供与外部世界交互的能力。

如果把 LLM 比作"大脑"，那 Harness 就是"身体"——眼睛、手、耳朵、权限徽章。没有 Harness，模型只能在纯文本的世界里自言自语；有了 Harness，模型才能读代码、写文件、执行命令、浏览网页、查询数据库。

核心洞察：

"最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。"

工程师不需要训练模型，而是要为模型搭建最好的脚手架，让它的智能充分发挥。

---

Harness 五大要素

1. 工具（Tools）

Agent 的"双手"，直接操作外部世界的能力：

工具类型	示例	说明
文件读写	read_file, write_file, edit_file	代码与配置的 CRUD
Shell 执行	bash, run_in_terminal	运行任意命令
API 调用	fetch, curl	与外部服务交互
浏览器控制	browser_navigate, browser_click	端到端 UI 测试、信息抓取
数据库查询	sql_query	数据检索与修改

2. 知识（Knowledge）

Agent 的"领域专长"，让它不仅聪明，还懂业务：

• 产品文档：功能规格、用户故事
• 架构决策记录（ADR）：为什么选这个方案、trade-off 是什么
• 风格指南：代码规范、命名约定、设计模式偏好
• 合规要求：安全策略、隐私规范、审计要求

关键原则：按需加载，不前置。 知识不是一股脑塞进 prompt，而是在 Agent 需要时动态检索注入。

3. 观察（Observation）

Agent 的"眼睛和耳朵"，感知环境变化：

• Git Diff：代码变更了什么
• 日志输出：命令执行的结果、错误信息
• 浏览器状态：页面截图、DOM 结构
• 环境反馈：测试通过/失败、构建状态、lint 结果

4. 行动（Action）

Agent 的"肌肉"，将决策转化为实际操作：

• CLI 命令：git commit, npm install, docker build
• API 调用：创建 PR、发送通知、触发部署
• UI 交互：点击按钮、填写表单、截图验证

5. 权限（Permission）

Agent 的"边界"，确保安全可控：

• 沙箱隔离：文件系统、网络访问的限制范围
• 审批流程：高危操作需人类确认（如 git push --force、删除文件）
• 信任边界：区分只读操作 vs 写操作、本地操作 vs 远程操作

---

Harness 工程师五大职责

作为 Harness 工程师，你的工作不是让模型更聪明，而是让模型的聪明有用武之地：

1. 实现工具 —— 给 Agent 一双手

• 设计清晰的 Tool Schema（输入/输出定义）
• 确保工具原子化、可组合
• 提供充分的工具描述，让模型知道何时使用

2. 策划知识 —— 给 Agent 领域专长

• 整理项目文档、规范、约定
• 构建 RAG 检索管道
• 维护知识的时效性和准确性

3. 管理上下文 —— 给 Agent 干净的记忆

• 实现上下文压缩策略
• 设计子 Agent 上下文隔离
• 确保关键信息不被截断

4. 控制权限 —— 给 Agent 边界

• 定义操作白名单/黑名单
• 实现审批流程（人在回路）
• 设计沙箱隔离机制

5. 收集任务过程数据 —— 为模型训练反馈

• 记录 Agent 的决策轨迹（trajectory）
• 收集成功/失败案例
• 为 RLHF / 微调提供高质量数据

---

我的理解与思考

（在此记录你对 Harness 框架的理解、疑问和延伸思考）