到目前为止，我们都是徒手实现 Agent 的循环。但真实的"Agent 工具"——Claude Code / Codex / OpenCode——是把 30 行的 ReAct 拆成几万行，里面装着计划、记忆、skill、子 agent、可观测性、权限。本章把这些"上层建筑"通称叫 Harness，让你从工具使用者升级到工具理解者。

12.1 Harness 是什么

Harness 这一词来自骑马——给马套上挽具，让人能驾驭马的能力，但不替代马。Agent Harness 同义：把 LLM 的"思考与产码"能力放到一个可控制的执行壳里，加 UI、加权限、加 memory、加 tool registry，但不替代 LLM 在循环中的主角身份。

┌────────────────────────────────────────────────────────────────┐
│                       USER (intent)                            │
├────────────────────────────────────────────────────────────────┤
│ Harness Layer                                                  │
│ ┌───────────┐ ┌─────────────┐ ┌───────────┐ ┌──────────────┐  │
│ │ UI / CLI  │ │ Permission  │ │ Memory    │ │ Skill Loader │  │
│ └───────────┘ └─────────────┘ └───────────┘ └──────────────┘  │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │                 Agent Loop (ReAct)                       │ │
│ │  Thought → Action → Observation → ... → DONE            │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │     Tool Registry (Bash / Edit / Grep / MCP / …)         │ │
│ └──────────────────────────────────────────────────────────┘ │
│                          Model Provider                        │
│              (Anthropic / OpenAI / local ollama)               │
└────────────────────────────────────────────────────────────────┘

12.2 OpenCode 的六层架构

OpenCode 是开源 harness 的代表，把上面那块抽象拆成六层：

层 职责 你撞见
Shell / TUI 你的 REPL 接口 opencode 命令
Session & Memory 持久化对话、压缩、跨重启 .opencode/ 目录
Skill 系统 把 prompt 沉淀成可加载单元 slash commands / references
Plan / Subagent 拆任务、并行执行 task 内置
Tool Registry bash / edit / grep / glob / MCP / webfetch 工具调用
Provider 抽象 OpenAI / Anthropic / DeepSeek / local provider.anthropic

12.3 Skill：Harness 内的"沉淀原力"

我们 22 章 才会正式展开 Skill，但 Harness 视角下把它放：

Skill = 一个 Slash Command + 一段 SKILL.md 系统提示 + 可能附带的 references

在 OpenCode 里，按"作用域"分四类 Skill：

project skill    → <repo>/.opencode/skills/foo/SKILL.md      你项目的专属
user    skill    → ~/.config/opencode/skills/foo/SKILL.md    你个人跨项目
plugin  skill    → plugin 包随装展开                       社区/团队共享
builtin  skill   → OpenCode 自带 (playwright, security-research)

Harness 的"复利价值"——这就是为什么 Claude Code / OpenCode 比纯 connect-Claude-API 玩得溜：你每次干活，沉淀不只是脑里的，还有磁盘上的。

12.4 superpowers：用户联网 benchmark 的 skill 集

2025 年 Robert Obryk 写了一个开源 Skill 集合 superpowers（GitHub obra/superpowers），其亮点是把 “Brainstorming → TDD → Debugging → Review → Verification” 五个软件任务做成 trigger-based skills，不抢占默认行为，只在该出现时摆放。

一个学会还会自动"召回"前面的 skill：

新会话起头 → using-superpowers 强制你跳过重复探索 ↓
要做功能设计 → brainstorming                  ↓
要做实现 → tdd / subagent-driven-development   ↓
要做审查 → requesting-code-review / review-work
注：以上是 OpenCode 的 superpowers 插件提供的 skill tree

学完本系列五篇 Agent 篇，你会看到实际的 skill 在上一章就 trigger 出来——那就是"内置 superpowers"在你 doing。

12.5 OpenCode 的 Plan / Oracle / Subagent 协作

接下来三章都是在讲"多 Agent 协作"——这里先看一张总览：

[USER GOAL]
       │
┌──────▼───────┐
│ Metis Plan   │ ← 分析意图、发现约束、产出 work plan
└──────────────┘
       │
┌──────▼───────┐
│ Momus Review │ ← 评 plan 是否清晰、可验证
└──────────────┘
       │ (loop clear)
┌──────▼───────┐
│ Build / Sisyphus │ ← 主执行线程
└──────────────┘
       │   │   │ (并发 dispatch)
       ▼   ▼   ▼
   explore librarian oracle     ← 5 类 subagent
       │       │       │
       └───────┴───────┘
              │
        (合成) done

关键洞察：你看到的不是一个超能 Agent，而是角色分化：Metis 想、Momus 挑剔、Build 干、explore 找文件、librarian 查文档、oracle 推理。每一类角色都被 system prompt 约束在特定范围内。

这是从 Agent 级到 Swarm 级的过渡：你不再追求"一个超大模型搞定一切"，而是让"几个细化的 subagent 协作"。13 章细拆。

12.6 Harness 跟 LLM 协议

不同 harness 默认的 LLM API 是不一样的：

Harness 默认 API 可插后端
Claude Code Anthropic Messages 不开
Codex CLI OpenAI Responses 不开
OpenCode 上述皆可 ✅ 开放
Aider OpenAI / Anthropic ✅
Continue 自托管 + Edge ✅

OpenCode 通过 provider 抽象允许任何提供商：

{
  "provider": {
    "anthropic": { "models": { "claude-opus-4-5": {} } },
    "openai":    { "models": { "gpt-5": {}, "o3-pro": {} } },
    "deepseek":  { "models": { "deepseek-v3-r1": {} } },
    "ollama":    { "models": { "qwen2.5-coder:32b": {} } }
  },
  "model": "anthropic/claude-opus-4-5"
}

这意味着 OpenCode 可达"本地小模型 + 大模型 mix"——一种未来 download skill 在本地运行的 cost-saving 路径。

12.7 实战：把 OpenCode 嵌进你的工作流

不必全包替换。渐进式装 5 步：

  1. 留你的 IDE（VS Code / Cursor），保留 L1 补全舒适感
  2. 在终端开 OpenCode / Claude Code 一个 Window 当 “L3 大锤”
  3. 在项目根写 AGENTS.md + SECURITY.md（08 章 模板）
  4. 把 3 个反复要用的 prompt 改写为 .opencode/skills/<name>/SKILL.md
  5. 跨项目用一个 user-level skill

5 周之类，你会发现自己主动用 Skill 开发 Skill——那是 Skill 篇 的开篇场景。

12.8 找不到合适的 harness 时

写自己的 harness 框架是 2025-2026 几个大公司都做了的事（Linear、Figma 的内部 agent 框架）。但写之前问三问：

  • 你的团队 / 业务有 harness 不能复用的强约束么？（合规 / 离线 / 性能）
  • 有时间维护吗？Harness 自己写 datasource 节奏比想象多
  • 有动力加 Skill / MCP 兼容？不开这两人气接口，团队用一周就跑光

如果三问有两条"否" → 在 OpenCode / Claude Code 上 fork 改造；都"是"→ 再写。这个判断在第 28 章：多 Agent 协作系统 讲实战细节。

12.9 小结

  • Harness = UI + Loop + Tool + Skill + Provider 六层
  • OpenCode / Claude Code 是开源 / 闭源 harness 的代表
  • 角色：Metis / Momus / Build / explore / librarian / oracle 多种 subagent 各司其职
  • 渐进嵌入：IDE 留 L1，Terminal 开 L3 备用，沉淀三技能起步

下一篇：《13 任务委派：Subagent 与并行执行》——本系列第一次见识多 Agent 写到一个工程里。

Summary: Harness 把 Loop 装上 UI / 权限 / Memory / Skill / Subagent 六层，理解架构后做 OpenCode 的二开/嵌入有谱。