16 KiB
16 KiB
| id | title | slug | status | content_type | channels | language | source_urls | assets | cover_image | template | owner | created_at | updated_at | published_at | tags | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2026-03-24-harness-engineering-analysis | Harness Engineering 分析 — learn-claude-code 仓库逆向解读 | harness-engineering-analysis | inbox | article |
|
zh-CN |
|
article | content-forge | 2026-03-24T00:00:00+08:00 | 2026-03-24T00:00:00+08:00 | null |
|
Harness Engineering 分析
来源仓库：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 的循环之上，循环本身从不改变：
# 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 读取（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：好的循环设计让你几乎忘记它的存在