Harness Engineering

什么是 Harness：Agent 的运行时与边界

背景与原理

一次 messages.create() 是无状态的 inference：你给它 input，它给你 output，模型并不知道也不在意你之前/之后做了什么。把这一次 inference 包装成一个能自主完成多步任务的实体，中间发生的所有事情合起来叫 harness：

• Tool dispatch：解析 model 返回的 tool_use block，路由到本地函数，执行后把 tool_result 塞回下一轮 messages。
• Loop control：判断停下还是继续——按 stop_reason == "end_turn"、max_iters、token budget、或人为 checkpoint。
• State / memory：messages 数组本身、scratch 文件、向量库、外部 DB——所有跨 turn 的状态都不是模型记住的，是 harness 记住的。
• Permission gate：tool 执行前的允许 / 拒绝 / 询问决策（Claude Code 的 ask / accept-edit / plan 三档就是这个）。
• Recovery：tool 失败、网络抖、模型乱说时的 retry / fallback / 人工接管。

真实使用体验 90% 取决于这几条的工程实现，而不是模型的 reasoning 强弱。Cognition 在 2025 年的 Don't Build Multi-Agents 里说得很直接：他们的核心壁垒是 harness 设计，而不是更聪明的 prompt。Claude Code 的 plan mode、Cursor 的 composer、Aider 的 git auto-commit，都是把同一个 base model 「装」进不同 OS 的结果。

实战示例

分清哪些是 prompt 的事、哪些是 harness 的事，从一个 30 秒诊断开始——当你的 agent 不 work，先问：

# —— 这是 PROMPT 的锅 ——
- 模型选错工具
- 输出格式不稳
- 推理跳步
- 没遵守约束

# —— 这是 HARNESS 的锅 ——
- 跑 10 轮就死循环（loop control 缺）
- tool 报错后 agent 就崩了（recovery 缺）
- 上下文越长越笨（compaction 缺）
- 工具调用没有人工干预的机会（permission 缺）
- 同一个 prompt 在 Claude Code 里好，在你脚本里不行（harness 不同）

把这张分类表贴在自己写 agent 的项目根目录——下次 debug 前先归因，能省一半时间。

Claude Code 的 Harness 拆解：你每天用的东西到底在做什么

背景与原理

Claude Code 是目前公开 SOTA 的 coding harness。把它拆开看，能直接抄到自己的 agent 项目里。核心抽象有六层：

• Tool registry：Read / Edit / Write / Bash / Grep / Glob 等少量正交工具。注意是少而正交，不是多而花哨——Anthropic 工程团队在博客里反复强调：tool 越多，模型 selection 失败率越高。
• Permission gate：三档（ask / accept-edit / plan）。plan mode 物理禁止 Write/Edit/Bash，强制模型只能读、只能想。这不是 prompt 约束，是 harness 物理拦截。
• Hooks 系统：UserPromptSubmit / PreToolUse / PostToolUse / SessionStart / Stop 等事件钩子，让你能在 harness 边界插入自定义 shell 命令（lint、tests、logging）。这是把 harness 暴露成可编程平台。
• Subagents：每个 subagent 是一个独立 context window 的子进程——用来执行能被「黑盒化」的子任务（搜索、研究、跑测试），结果摘要回主 agent。本质是 context isolation。
• Slash commands / Skills：把常用的 prompt + tool 组合封装成可触发指令。harness 把它编译进 system prompt 的注册表里。
• Auto compaction：context 接近上限时自动压缩历史（Day 2 讲过的 structured summary 路线）。

这些不是「锦上添花」，每一个都对应一个具体失败模式：没有 plan mode，模型会先动手再想；没有 hooks，每个 commit 都得手动跑 lint；没有 subagent，一次大搜索把主 context 污染到不可用。harness 设计就是把这些「为了不踩坑该做的事」固化成系统。

实战示例

读 Claude Code 自己的 .claude/settings.json 是最快的 harness 入门——直接看 SOTA harness 怎么暴露配置面：

{
  "permissions": {
    "allow": ["Read", "Grep", "Bash(git status:*)", "Bash(npm test:*)"],
    "ask":   ["Edit", "Write", "Bash(git push:*)"],
    "deny":  ["Bash(rm -rf:*)", "Bash(*--no-verify*)"]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type":"command", "command":"pnpm lint --fix $CLAUDE_FILE_PATHS"}]
    }],
    "Stop": [{"hooks":[{"type":"command","command":"pnpm test --silent"}]}]
  },
  "env": { "BASH_DEFAULT_TIMEOUT_MS": "120000" }
}

这一份 30 行配置干了四件原本要写代码的事：分级权限（allow / ask / deny 用 glob pattern 精确控制）、强制保存即 lint、每次会话结束跑测试、Bash 超时兜底。这就是 harness 提供的「可声明式编程」面——你不需要分叉 Claude Code，就能让它的运行时按你的工程纪律跑。

自建最小 Harness：100 行 Python 跑通一个 Agent

背景与原理

一个 harness 的最小骨架其实就五个组件：tool registry · loop controller · message buffer · permission gate · recovery。剩下都是这五个的变体。下面这段 100 行 Python 跑得起来、能处理 multi-turn tool calls、能拦截危险命令、能在 token 超阈值时 compact——它不漂亮，但每一行你都看得懂、改得动。

实战示例

import anthropic, json, subprocess
from pathlib import Path

client = anthropic.Anthropic()
MODEL  = "claude-sonnet-4-6"

# 1) TOOL REGISTRY：schema 给模型，handler 留本地
TOOLS = {
  "read_file": {
    "schema": {"name":"read_file","description":"Read a file",
      "input_schema":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}},
    "handler": lambda p: Path(p["path"]).read_text()[:8000]
  },
  "run_bash": {
    "schema": {"name":"run_bash","description":"Run a shell command (read-only)",
      "input_schema":{"type":"object","properties":{"cmd":{"type":"string"}},"required":["cmd"]}},
    "handler": lambda p: subprocess.run(p["cmd"],shell=True,capture_output=True,text=True,timeout=30).stdout[:8000]
  }
}

# 2) PERMISSION GATE：物理拦截，不靠模型自律
DENY = ["rm -rf", "--no-verify", "sudo", "curl ", "> /"]
def permit(tool, args):
    if tool == "run_bash":
        cmd = args.get("cmd","")
        if any(d in cmd for d in DENY): return False, f"denied: {cmd}"
    return True, None

# 3) LOOP CONTROLLER + 4) MESSAGE BUFFER + 5) RECOVERY
def agent(task, max_iters=20):
    msgs = [{"role":"user", "content": task}]
    schemas = [t["schema"] for t in TOOLS.values()]
    for i in range(max_iters):
        r = client.messages.create(model=MODEL, max_tokens=4096, tools=schemas, messages=msgs,
            system="You are a careful research agent. Use tools step by step.")
        msgs.append({"role":"assistant", "content": r.content})
        if r.stop_reason == "end_turn":
            return next((b.text for b in r.content if b.type=="text"), "")
        results = []
        for b in r.content:
            if b.type != "tool_use": continue
            ok, reason = permit(b.name, b.input)
            if not ok:
                out = reason
            else:
                try:
                    out = TOOLS[b.name]["handler"](b.input)
                except Exception as e:
                    out = f"ERROR: {type(e).__name__}: {e}"   # 关键：错误也回给模型
            results.append({"type":"tool_result","tool_use_id":b.id,"content":str(out)})
        msgs.append({"role":"user", "content": results})
    return "hit max_iters"

四个关键决策：（1）schema 和 handler 解耦——schema 是给模型的契约，handler 是你的本地代码，永远别让模型直接 eval。（2）permission 是物理拦截而非 prompt 约束——deny list 在 harness 层判，模型说服不了。（3）错误回给模型而不是抛异常——这是 agent 能自我修复的根因，error message 是它最重要的输入之一。（4）max_iters 默认 20，必须有上限，不然 tool selection 抖动会导致死循环。

《Building Effective Agents》精读：什么时候根本不该写 Agent

背景与原理

Anthropic 2024 年底那篇 Building Effective Agents（Erik Schluntz & Barry Zhang）是过去两年最重要的 agent 工程文献。最被引用的不是它给的代码示例，而是它给的分类——它强行把所有「agentic」应用切成两类：

• Workflow（工作流）：LLM 和 tool 通过预定义的代码路径编排。开发者完全控制控制流，LLM 只在节点上做内容生成 / 路由判断。
• Agent（代理）：LLM 动态决定要调什么工具、按什么顺序、什么时候停。控制流由模型掌握。

这个分类的杀伤力在于：大多数生产系统应该是 workflow，不是 agent。Workflow 更可预测、更便宜、更容易 eval、更容易 debug。Agent 用在任务开放、步数无法预先规划、需要根据中间结果决策的场景才合理（如自主调试、深度研究、复杂代码任务）。

博客列了 5 个 workflow pattern，可以直接背下来作为架构清单：

1. Prompt chaining：把任务切成几步，每步用一个 prompt，前一步输出做下一步输入。可以在中间插 gate（不通过就回退）。
2. Routing：先用一个分类 prompt 把请求分类，路由到不同的下游 prompt / 模型。
3. Parallelization：把任务切成可并行子任务（sectioning），或者跑多个 voter 投票（voting）。
4. Orchestrator-workers：一个 orchestrator 动态切分子任务、派给 worker、收集结果——Claude Code 的 subagent 就是这种。
5. Evaluator-optimizer：一个 LLM 生成，另一个 LLM 评估并给反馈，迭代直到达标。写作 / 翻译 / 复杂代码很合适。

真正的 agent 是这 5 个的「上层」——当任务复杂到无法预先写出 workflow 时才升级。博客原文："When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed."

实战示例

一个常被误造成 agent 的需求：「读用户上传的 PDF，提取要点，生成 1 页摘要」。看起来很 agentic？其实是 prompt chain：

# BAD：上来就写 agent，给它 read_pdf / summarize / save 三个 tool
agent("读 report.pdf 然后给我一页摘要")
#  → 模型可能跳过提取直接编 / 偶尔忘 save / debug 困难

# GOOD：prompt chain workflow，每步代码层控制
def summarize_pdf(path):
    text   = extract_pdf(path)                        # 代码做，不用 LLM
    if len(text) > 50_000:
        chunks = chunk_by_heading(text)
        partials = [summarize_chunk(c) for c in chunks]  # 并行 LLM call
        return synthesize(partials)                   # 第二步 LLM
    return summarize_short(text)

什么时候才升级到真正的 agent？三个信号同时出现：（1）步骤数无法预先知道；（2）每步的下一步取决于上一步的结果；（3）能验证最终输出对错（不然 agent 会跑飞还不知道）。Coding / 研究 / 复杂数据分析符合，写邮件 / 翻译 / 报告生成基本不符合。