Agent Harness 是什么？
在 AI 编程工具飞速发展的今天，一个概念正在成为 Agent 工程领域最核心的共识——Agent = Model + Harness。
模型提供智能，Harness 让智能变得有用。如果你不是模型本身，那你就是 Harness 的一部分。
从一副"挽具"讲起
Harness 这个词的英文原意是"马具、挽具"，就是套在马身上、让马的力量转化为拉车动力的那套装备。类比非常精准：模型是马，Harness 是挽具，Agent 是马+挽具+车的整体系统。
马本身有力量，但如果没有缰绳、鞍具、车厢来转化这股力量，它什么也拉不动。大模型也是一样——一个裸模型（无论 GPT-4 还是 Claude Opus）放在服务器上，它不能读写文件，不能执行命令，不能联网搜索，也不能记住昨天和你说过什么。
更技术化地说，Harness 是模型之外的一切工程基础设施。它决定了一个 Agent 能不能真正地"干活"。
为什么需要 Harness？
一个裸大模型有四大硬伤：
第一，没有文件系统 — 看不见项目代码，读不了文档。Agent File I/O（读写文件、编辑代码）是 Harness 最基本的能力。
第二，不能执行代码 — 只能"说"不能"做"。Bash 沙箱赋予了 Agent 编写代码并自主运行的能力，这是从聊天机器人到编程助手的关键一跃。
第三，知识过时 — 训练数据截止于某个时间点。Web Search + MCP 突破了知识的"时间牢笼"，让 Agent 能实时获取最新信息。
第四，没有记忆 — 每次对话从零开始。AGENTS.md / MEMORY.md 提供了持久记忆机制，让 Agent 能在会话间持续学习。
简单来说：裸模型只能告诉你它"想怎么做"，配有 Harness 的 Agent 直接动手做给你看。
Harness 的六大核心组件
1. 文件系统（Agent 的感官）
Agent 有了文件系统，就能读取项目代码、写入修改、查看日志。文件系统也是天然的协作面——人和 Agent 可以通过共享文件来协调工作。Agent 可以增量地读取和写入文件，而不是将所有内容都塞在上下文里。
2. Bash + 沙箱（Agent 的四肢）
这是让 Agent 从"想"到"做"的关键一步。Agent 可以自主编写和执行代码、安装依赖、运行测试，而不是被限制在一组固定的预配置工具中。沙箱提供了安全隔离的执行环境，可以允许命令列表、强制执行网络隔离。
3. 记忆系统（Agent 的大脑皮层）
通过 AGENTS.md、MEMORY.md 等标准文件，Agent 在启动时自动注入项目知识。Agent 可以持续更新这些文件，实现跨会话的持续学习——这是一套"不改权重也能给模型加知识"的优雅方案。
4. 联网搜索 + MCP（Agent 的五感延伸）
突破知识的"时间牢笼"。Agent 可以实时搜索互联网、调用第三方 API、接入数据库、通过 MCP 协议使用外部工具，获取训练数据截止日期之后的信息。
5. 上下文工程（Agent 的注意力管理）
对抗 AI 系统的"熵增"。包括自动压缩历史记录、智能摘要、只注入必要知识等策略。优秀的 Harness 会让 AGENTS.md 保持在 50 行以内作为"地图"，指向项目中更深层的事实来源。
6. 编排 + Hooks（Agent 的指挥系统）
让 Agent 从单兵作战变成集团军协同。子 Agent 生成、任务交接、模型路由、质量检查——这些都是编排层的职责。Hooks 则提供了安全底线：路径白名单、命令黑名单、交互式审批。这是 Harness 中最容易被低估但最关键的组件。System Prompt 不是第七个组件，但它是贯穿所有六个组件的神经系统。
Harness 在 OpenCode 生态中的实践：harness-opencode
在 OpenCode 生态中，有一个成熟的开源 Harness 实现——由 @iceglober 开发的 harness-opencode 项目（MIT 协议）。它提供了 14 个 Agent、7 个斜杠命令、5 个自定义工具、5 个 MCP 集成、5 个技能包和 4 个子插件，一个包搞定所有。
核心理念：五阶段 PRIME 工作流
Harness-opencode 的默认 Agent prime 运行一个完整的五阶段端到端工作流：
- Phase 1：研究 — 理解需求、探索代码库
- Phase 2：规划 — 生成经过对抗性审查的计划（含缺口分析）
- Phase 3：构建 — 执行计划（由 mid-tier 模型处理以节省成本）
- Phase 4：QA — 全面审查和测试
- Phase 5：验证 — 检查完成标准，生成最终输出
14 个专业 Agent 分工
| 层级 | Agent | 能力等级 | 职责 |
|---|---|---|---|
| 核心 | prime | deep | 五阶段端到端工作流，默认 Agent |
| 规划 | plan | deep | 交互式规划 + 缺口分析 + 对抗性审查 |
| plan-reviewer | deep | 专攻计划审查 | |
| gap-analyzer | deep | 识别计划中的缺口 | |
| 构建 | build | mid | 计划执行者 |
| 审查 | qa-reviewer | mid | 快速对抗性代码审查 |
| qa-thorough | deep | 全量对抗性审查 | |
| 搜索 | code-searcher | fast | 代码库快速搜索 |
| lib-reader | mid | 库和依赖分析 | |
| 文档 | docs-maintainer | mid | 文档更新维护 |
| agents-md-writer | mid | AGENTS.md 生成 | |
| 架构 | architecture-advisor | deep | 架构设计指导 |
| 无人值守 | pilot-planner | deep | 将工作分解为 DAG 任务 |
| pilot-builder | mid | 无人值守任务执行器 |
7 个斜杠命令
| 命令 | 功能 |
|---|---|
/fresh <ticket> |
清空工作树 → 创建分支 → 启动五阶段工作流 |
/autopilot <ticket> |
全自动 PRIME，直到验收标准通过才停止 |
/ship <plan> |
Squash 提交、推送、自动开 PR |
/review <ref> |
只读对抗性审查（PR 号、SHA、分支或文件） |
/research <query> |
并行代码库搜索，返回精确的文件:行号引用 |
/init-deep |
生成层级化的 AGENTS.md 文件 |
/costs |
查看当前会话的 LLM 累计花费 |
如何在 OpenCode 中安装 Harness
方式一：全局 CLI 安装（推荐）
# 一步安装
bun add -g @glrs-dev/harness-opencode
glrs-oc install-plugin
opencode
# 进入 OpenCode 后，/fresh /autopilot /ship 等命令自动可用
方式二：仅插件安装（适合临时使用）
bunx @glrs-dev/harness-opencode install
opencode
无需全局安装，所有插件功能自动加载。
配置模型覆盖
可以在 opencode.json 中配置不同层级使用的模型：
{
"harness": {
"models": {
"deep": ["anthropic/claude-opus-4"],
"mid": ["anthropic/claude-sonnet-4"],
"fast": ["anthropic/claude-haiku-4"]
}
}
}
配置优先级：per-agent 覆盖 > tier 默认 > 插件内置默认。
无人值守 Pilot 模式
对于大型任务，Harness 支持将工作分解为 DAG（有向无环图）任务计划，完全无人值守运行。每个任务运行在隔离的 Git Worktree 中，自带验证命令。
# 规划阶段
glrs-oc pilot plan "实现用户认证模块"
# 验证计划（schema + DAG + glob 完整性）
glrs-oc pilot validate
# 无人值守执行
glrs-oc pilot build
# 检查任务状态
glrs-oc pilot status
# 恢复中断的运行
glrs-oc pilot resume
# 查看任务开销
glrs-oc pilot cost --json
Pilot 模式的背后是每个任务的严格沙盒化和失败隔离——一个任务失败不会影响其他任务的执行状态，故障恢复非常清晰。
使用 Harness 前后的对比
| 维度 | 裸 OpenCode | 配有 Harness |
|---|---|---|
| 工作流 | 直接聊天改代码 | 研究→规划→构建→QA→验证 五阶段 |
| 知识连贯性 | 每次对话从零开始 | AGENTS.md 注入 + 跨会话持久记忆 |
| 代码质量 | 改完就看，缺乏把关 | 对抗性审查 + QA 门禁 + 自动化验证 |
| 复杂任务 | 需要手动分段、人工跟踪 | DAG 自动编排 + 无人值守执行 |
| 模型成本 | 无感使用，难以控制 | 分层分级：deep/mid/fast 按需分配 |
| 团队协作 | 个人工具 | 标准化的 AGENTS.md + 共享计划文件 |
| 可观测性 | 不太清楚 LLM 花了多少钱 | /costs + pilot cost --json 全程追踪 |
更直观的场景对比
场景：在一个已有的 Spring Boot 项目中添加用户认证模块
没有 Harness：
- 你在 OpenCode 中说"帮我加个 JWT 认证"
- Agent 直接开始修改代码（可能改错层、破坏现有架构）
- 你可能需要在过程中多次纠正
- 改完后手动 review、手动测试
- 完全依赖你自己的架构判断力
有 Harness 之后：
- 你输入
/fresh "为项目添加 JWT 用户认证" - Agent 先研究整个项目的目录结构和现有认证逻辑
- 然后生成详细计划，经过 gap-analyzer 和 plan-reviewer 的对抗性审查
- 通过后才交给 build Agent 执行（使用便宜的中端模型）
- 执行完后 qa-reviewer 做全量审查
- 最后验证是否满足验收标准
- 你也可以直接说
/autopilot "..."，然后去泡杯咖啡
关于 Agent Harness 的常见误区
误区一：Harness = Prompt 工程
不对。Prompt 只是 Harness 的神经系统的一部分，完整的 Harness 包括文件系统、工具执行、记忆、沙箱、编排等整套工程基础设施。
误区二：有了好模型就不需要 Harness
恰恰相反——模型越好，Harness 越重要。强大的模型在优秀 Harness 的引导下能释放数倍的价值，但在糟糕的 Harness 中同样会产生灾难性的后果。
误区三：Harness 是锦上添花
对于生产级 Agent 来说，Harness 是必需品。一个没有记忆、不能执行代码、没有安全边界的 Agent，本质上就是个高级聊天机器人。
误区四：小项目不需要 Harness
即使是个人项目，Harness 的收益也是立竿见影的——自动的代码审查、成本追踪、跨会话记忆，这些功能在第一天就能节省时间。
总结
Agent Harness 不是一个锦上添花的概念，它是 Agent 从原型走向生产的必经之路。
回顾这个领域的发展，能清晰地看到一个趋势：
- 2023年：大家比的是哪个模型的参数更大
- 2024年：大家比的是哪个模型的推理能力更强
- 2025年：模型能力的差距在缩小，竞争转向了工程层
- 2026年：Agent = Model + Harness 成为行业共识，Harness Engineering 正式成为一门工程学科
模型不再是差异化因素，围绕模型构建的 Harness 系统才是。
从 OpenAI 的 Codex、Anthropic 的 Claude Code，到开源的 OpenCode，所有主流的 AI 编程工具都在朝这个方向演进。
如果你正在使用 OpenCode，安装 harness-opencode 可能是今天能做的最有价值的一件事——它让一个会聊天的 AI 变成了真正能帮你干活的编程搭档。