--- id: "2026-03-24-harness-engineering-analysis" title: "Harness Engineering 分析 — learn-claude-code 仓库逆向解读" slug: "harness-engineering-analysis" status: "inbox" content_type: "article" channels: ["wechat", "x"] language: "zh-CN" source_urls: - "https://github.com/shareAI-lab/learn-claude-code" assets: [] cover_image: "" template: "article" owner: "content-forge" created_at: "2026-03-24T00:00:00+08:00" updated_at: "2026-03-24T00:00:00+08:00" published_at: null tags: ["harness-engineering", "agent-friendly", "claude-code", "agent-loop", "MCP"] --- # Harness Engineering 分析 > 来源仓库：[shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) > 定位：将 Claude Code 架构逆向工程为 12 课的 Harness Engineering 教程 --- ## 一、核心论点 ### 1.1 Agent = Model，不是代码 ``` Agent 的历史证据链： 2013 DeepMind DQN → 一个神经网络学会玩 49 款 Atari 游戏 2019 OpenAI Five → 五个网络打败 Dota 2 世界冠军 OG 2019 AlphaStar → 星际争霸 II 登顶 Grandmaster（前 0.15%） 2019 腾讯绝悟 → 王者荣耀 5v5 击败 KPL 职业选手 2024 LLM Coding Agents → 读代码库、写实现、调试、团队协作 共同真相：Agent 从来不是代码，Agent 始终是模型。 ``` ### 1.2 Harness = 驾驶舱，不是司机 ``` Harness = Tools + Knowledge + Observation + Action + Permissions 模型决定。Harness 执行。 模型推理。Harness 提供上下文。 模型是司机。Harness 是车辆。 ``` ### 1.3 对 "Prompt Plumbing" 的批判 仓库明确批判了一整个行业：拖拽工作流构建器、无代码 "AI Agent" 平台、Prompt 链编排库——它们不是 Agent，是"带有幻想的 shell 脚本"。 > "You cannot engineer your way to agency. Agency is learned, not programmed." --- ## 二、12 课架构 ### 2.1 全景层级图 ``` Phase 1: 循环 Phase 2: 规划与知识 ┌───────────────────┐ ┌───────────────────┐ │ s01 Agent Loop │ │ s03 TodoWrite │ │ 30 行 Python │ │ 模型自管计划 │ │ = 完整 Agent │ │ 一次一个 in_prog. │ │ │ │ │ │ s02 Tool Use │ │ s04 Subagent │ │ 调度映射表 │ │ 上下文隔离 │ │ 路径沙箱 │ │ 子任务清洁上下文 │ │ │ │ │ │ │ │ s05 Skills │ │ │ │ 两层按需加载 │ │ │ │ │ │ │ │ s06 Compact │ │ │ │ 三层上下文压缩 │ └───────────────────┘ └───────────────────┘ Phase 3: 持久化 Phase 4: 团队 ┌───────────────────┐ ┌───────────────────┐ │ s07 Task System │ │ s09 Agent Teams │ │ 任务 DAG 磁盘持久 │ │ 持久化队友 + 邮箱 │ │ 依赖自动解锁 │ │ │ │ │ │ s10 Protocols │ │ s08 Background │ │ 结构化握手协议 │ │ 后台线程异步执行 │ │ shutdown/plan │ │ 通知队列注入 │ │ │ │ │ │ s11 Autonomous │ │ │ │ 自组织领取任务 │ │ │ │ 60s 空闲自动退出 │ │ │ │ │ │ │ │ s12 Worktree │ │ │ │ Git worktree 隔离│ │ │ │ 控制面 + 执行面 │ └───────────────────┘ └───────────────────┘ ``` ### 2.2 每课核心机制 | 课 | Harness 层 | 核心机制 | 代码量 | |---|-----------|---------|--------| | s01 | Loop | `while True` + `stop_reason != "tool_use"` 退出 | 3.6KB | | s02 | Tool dispatch | `{tool_name: handler}` 调度映射 + `safe_path()` 沙箱 | ~5KB | | s03 | Planning | TodoManager 状态机（pending→in_progress→completed），一次一个 | ~7KB | | s04 | Context isolation | 子 Agent 清空 messages，只返回摘要文本 | ~9KB | | s05 | Knowledge | 两层注入：系统提示含索引（~100 token/skill）+ load_skill 工具返回全文 | ~11KB | | s06 | Compression | 三层压缩：每轮微压 → 50K token 自动压 → 手动压缩工具 | ~14KB | | s07 | Persistence | JSON 文件 DAG，blockedBy/blocks 依赖，完成自动解锁 | ~17KB | | s08 | Async | 守护线程 + 通知队列，每次 LLM 调用前排空队列 | ~19KB | | s09 | Teams | 持久化队友 + JSONL 邮箱，WORKING↔IDLE↔SHUTDOWN 生命周期 | ~21KB | | s10 | Protocols | request_id FSM（pending→approved/rejected），一个状态机两种协议 | ~23KB | | s11 | Autonomy | IDLE 轮询（5s 间隔）+ 任务板自主领取 + 身份重注入 | ~25KB | | s12 | Isolation | Git worktree 绑定 Task ID，控制面(.tasks/) + 执行面(.worktrees/) | 25.9KB | ### 2.3 设计不变量 每一课都叠加在 s01 的循环之上，**循环本身从不改变**： ```python # s01: 永不改变的核心循环 while True: response = client.messages.create( model=model, system=system_prompt, messages=messages, tools=tools ) # 模型决定何时停止 if response.stop_reason != "tool_use": break # Harness 执行工具调用 for block in response.content: if block.type == "tool_use": result = dispatch[block.name](block.input) messages.append(tool_result(block.id, result)) ``` --- ## 三、Harness Engineering 七原则 ### P1: 循环永不改变（The Loop Never Changes） 每一课在循环**周围**添加机制，而非**修改**循环。Agent（模型）拥有循环；Harness 拥有机制。 ### P2: 工具是 Agent 的手（Tools Are Hands） 原子、可组合、描述清晰。调度映射模式（`{name: handler}`）意味着添加能力无需改变核心。 ### P3: 知识按需加载，不预加载（Knowledge On-Demand） 两层 Skill 加载——系统提示中的廉价索引（~100 token）+ tool_result 中的昂贵内容（~2000 token）——是标准模式。 ### P4: 上下文是珍贵资源（Context Is Precious） 三种策略保护上下文：子 Agent 隔离（s04）、三层压缩（s06）、磁盘持久化（s07）。 ### P5: 约束聚焦，非限制（Constraints Focus, Not Limit） "一次一个 in_progress"（s03）、"只读子 Agent"（s04）、"路径沙箱"（s02）——都是让模型性能**更好**的护栏。 ### P6: 持久化跨越会话（Persistence Outlives Sessions） 磁盘任务（s07）、团队配置 JSON（s09）、事件 JSONL（s12）——Harness 维护模型上下文窗口无法持有的状态。 ### P7: 信任模型（Trust the Model） 最强主题。不预设工作流。不构建决策树。给工具和知识，让模型推理。 > "You are not writing intelligence. You are building the world intelligence inhabits." --- ## 四、附带 Skills ### agent-builder 核心哲学："模型已经知道如何做 Agent。你的工作是让开。" 三要素：Capabilities（能做什么）+ Knowledge（知道什么）+ Context（发生了什么） 渐进复杂度：从 3-5 个能力起步。大多数 Agent 不需要超过 Level 2（规划）。 反模式清单：过度工程、工具太多、刚性工作流、预加载知识、微管理。 ### mcp-builder MCP Server 构建模板（Python + TypeScript）。最佳实践：清晰工具描述、输入验证、错误处理、默认异步、安全、幂等。 ### code-review 五维审查：安全（Critical）→ 正确性 → 性能 → 可维护性 → 测试。结构化输出：摘要 + 关键问题 + 改进 + 亮点 + 结论。 ### pdf PDF 读取（pdftotext/PyMuPDF）、创建（pandoc/reportlab）、合并/拆分。实用工具检测 + 大文件逐页处理。 --- ## 五、与 Agent Friendly 开发规约的对照 ### 5.1 同一枚硬币的两面 ``` ┌──────────────────────────────────────────────────────────┐ │ │ │ Agent Friendly 规约 Harness Engineering │ │ (被调用方视角) (构建方视角) │ │ │ │ "怎么让 Agent 用好 "怎么给 Agent 建好 │ │ 你的系统" 运行环境" │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ 你的 API │◀── MCP ──────────▶│ Agent │ │ │ │ 你的工具 │ A2A │ Harness │ │ │ │ 你的文档 │ │ 循环+工具 │ │ │ └──────────┘ └──────────┘ │ │ │ │ 规约约束: Harness 约束: │ │ - Schema-First - 循环永不改变 │ │ - 工具设计 7 子规约 - 工具原子可组合 │ │ - 10 条安全约束 - 路径沙箱 │ │ - 25 条 NEVER - 信任模型 │ │ │ └──────────────────────────────────────────────────────────┘ ``` ### 5.2 概念映射表 | Harness Engineering 概念 | Agent Friendly 规约对应 | 关系 | |---|---|---| | **Agent Loop**（s01）| — | Harness 独有概念，规约不涉及 Agent 内部循环 | | **Tool dispatch map**（s02）| §2 Tool Design 7 子规约 | 构建方的调度 = 被调用方的 Schema | | **safe_path() 沙箱**（s02）| §4.1 Least Agency | 同一约束的两侧实现 | | **TodoWrite 一次一个**（s03）| P2 约束>能力 | 约束聚焦的典型实例 | | **Subagent 上下文隔离**（s04）| §4 安全 / Sandbox | 隔离是双方共识 | | **Skill 两层加载**（s05）| §5 文档发现层 (llms.txt) | 索引层+内容层 = 同一模式 | | **Context Compact**（s06）| — | Harness 独有（管理 Agent 内部记忆） | | **Task DAG 磁盘持久**（s07）| Agent Skills 标准 | 持久化知识的不同形式 | | **Background tasks**（s08）| — | Harness 独有（异步执行管理） | | **Team mailbox**（s09）| A2A 协议 | 邮箱 = 简化版 A2A | | **Shutdown/Plan protocols**（s10）| HITL + Agent 协商 | 结构化握手 = Agent 间礼仪 | | **Autonomous task claiming**（s11）| Agent Card 发现 | 自组织 = 去中心化发现 | | **Worktree isolation**（s12）| §4 Sandbox / MicroVM | 目录隔离 ≈ 轻量级沙箱 | | **"Trust the model"**（全局）| P2 约束>能力 | 同一哲学的不同表达 | | **mcp-builder skill** | §2 + §3 全部 | MCP Server 构建 = 规约的执行 | ### 5.3 互补关系全景 ``` Agent Friendly 完整画面 ──────────────────────── 被调用方（你的系统） 构建方（Agent Harness） ════════════════ ═══════════════════ §5 发现层 s05 Skill 两层加载 llms.txt / Agent Card 系统提示索引 + 按需加载 │ │ │ Agent 找到你 │ Agent 获取知识 ▼ ▼ §2 工具设计 s02 Tool dispatch Schema / 描述 / 注解 调度映射 + 沙箱 │ │ │ Agent 理解你 │ Agent 执行工具 ▼ ▼ §3 API 设计 s01 Agent Loop 10 条 AX 原则 while True 核心循环 │ │ │ Agent 调用你 │ Agent 决策 ▼ ▼ §4 安全规约 s04/s12 隔离 10 条安全约束 子 Agent + Worktree │ │ │ Agent 安全运行 │ Agent 安全执行 ▼ ▼ §6 评估规约 agent-builder skill Postman 48 / 10 项评分 渐进复杂度 + 反模式 │ │ └───────────┬───────────────┘ │ ▼ ┌────────────────┐ │ Agent 成功完成 │ │ 用户的任务 │ └────────────────┘ ``` ### 5.4 核心差异 | 维度 | Agent Friendly 规约 | Harness Engineering | |------|-------------------|-------------------| | **视角** | 被调用方（API/工具提供者） | 构建方（Agent 运行环境） | | **关注点** | 接口契约、发现性、安全 | 循环、上下文、持久化 | | **不涉及** | Agent 内部循环和记忆管理 | API/工具的 Schema 设计 | | **核心动词** | "暴露"、"描述"、"约束" | "加载"、"隔离"、"持久化" | | **评估方式** | 量化评分（48 Checks） | 12 课渐进验证 | | **共识** | 约束 > 能力；信任模型；Schema-First | 约束聚焦；信任模型；循环不变 | --- ## 六、整合洞察 ### 6.1 Agent Friendly 的完整定义（整合后） ``` Agent Friendly = 被调用方友好 + 构建方友好 被调用方友好（规约）： 让 Agent 能发现、理解、调用、验证你的系统 构建方友好（Harness）： 让 Agent 有清晰的感知、精准的行动、丰富的知识、安全的边界 两者的交汇点： 工具设计 ←→ 工具调度 文档发现 ←→ 知识加载 安全约束 ←→ 沙箱隔离 Agent 协议 ←→ 团队通信 ``` ### 6.2 为什么两个视角都需要 ``` 只有规约（被调用方）： → Agent 能找到你的 API，但不知道怎么高效使用 → 好的菜单，但没有好的厨房 只有 Harness（构建方）： → Agent 有好的运行环境，但外部工具难以对接 → 好的厨房，但食材（API）质量参差不齐 两者结合： → Agent 能发现好的工具 + 在好的环境中高效使用它们 → 好的厨房 + 好的食材 = 好的菜 ``` ### 6.3 共享的哲学根基 两个视角共享三条根本信念： **信念 1：模型比你想的更聪明** - 规约：不要猜测 Agent 的意图，给它好的 Schema 它会自己搞定 - Harness：不要预设工作流，给它工具和知识让它推理 **信念 2：约束是最好的礼物** - 规约：NEVER 清单比功能列表更重要（§10.7 约束>能力） - Harness：一次一个 in_progress 让模型更专注（s03） **信念 3：好设计是透明的** - 规约：好的工具描述让 Agent 像读文档一样理解接口 - Harness：好的循环设计让你几乎忘记它的存在