1. 什么是 Agent Harness

这是什么：Harness（脚手架） = 跑在模型外面的一层运行时，负责拼上下文、给工具、管权限、验结果、兜故障。

为什么用：同一套模型换个框架，编码评测能差出十倍。Agent 的水平不只由模型决定，很大一块由外面这层壳决定。

如何用：本章把「模型做不到什么」逐条列出来当检查表，再给出六层架构和成熟度分级，让你知道自己缺哪块。

1.1 模型做不到的那几件事

想知道 Harness 里该放什么，反过来问：模型做不到什么？

大模型看起来能写代码、能推理、能聊，但从系统角度看它主要是个输入输出函数。它不记历史、不跑命令、不知道自己干得对不对。

这张表就是 Harness 的组件清单。 排查问题时也用它：先列模型能做的事，再逐项补它做不到的部分，问题会落到具体缺口上——工具结果是否可读、任务状态是否持久化、失败后是否给出了可执行的修复信息。

1.2 Agent = Model + Harness

工程上常用的切分是 Agent = Model + Harness：

用户请求
   │
   ▼
┌──────────────────────────────────────────────┐
│  Harness                                     │
│  ├─ 组装上下文（系统提示 + 历史 + 资料 + 状态）│
│  ├─ 暴露工具（读文件 / 跑命令 / 调 API）        │
│  ├─ 执行工具，收集结果                        │
│  ├─ 管权限与沙箱                             │
│  └─ 验证结果、失败恢复、循环直到收敛           │
└──────────────────┬───────────────────────────┘
                   │  一次请求 = 上下文 + 工具清单
                   ▼
              ┌─────────┐
              │  模型    │ → 文本 或 工具调用
              └─────────┘

模型的输出分两种：文本（直接回给用户）和工具调用（交给 Harness 执行）。Harness 负责把工具调用的结果塞回上下文，让模型看到自己刚做了什么。

一个最小 Harness 长这样（Python，沿用 LLM 教程 的 SDK 写法）：

messages = [{"role": "system", "content": SYSTEM_PROMPT}]

while True:
    resp = client.chat.completions.create(
        model=MODEL, messages=messages, tools=TOOL_SCHEMAS
    )
    msg = resp.choices[0].message
    messages.append(msg)

    if not msg.tool_calls:          # 模型不再要工具 → 收敛
        print(msg.content)
        break

    for call in msg.tool_calls:     # 执行工具，把结果塞回上下文
        result = run_tool(call.function.name, json.loads(call.function.arguments))
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": result,      # ← 关键：结果要可读
        })

这三十行就是 Harness 的最小内核。它比模型简单，但决定了模型能干成什么样。

1.3 Prompt / Context / Harness Engineering

这三者不是并列关系，而是一层套一层，处理的问题范围越来越大：

简单任务里，Prompt 可能就够了——改一句文案，提示词说清楚，效果通常不差。

需要外部知识时，Context 更重要：你得把资料、检索结果、历史状态放到合适位置。

到了长链路、可执行、低容错的场景，Harness 才成为主要矛盾——Agent 需要的不只是「会回答」，还要能执行、验证、回滚、继续推进。

一句话：Prompt 能澄清局部指令，但提供不了文件访问、测试执行、状态保存和失败恢复。这些执行问题只能由 Harness 承担。

1.4 六层架构

从系统设计视角看，成熟的 Harness 通常有清晰分层。这是分析框架，不是业界统一协议，但拿来查缺项很好用：

可以想成给新员工搭工作环境：L1 是岗位说明，L2 是办公工具，L3 是标准操作流程，L4 是项目管理系统，L6 是红线规则和应急预案。

起步不需要一次建齐六层。先补 L1 和 L6：前者明确任务边界与输入，后者在越权、失败或结果不合格时拦截并恢复。等任务进入多步骤执行、需要保存中间产物或反复验证时，再补 L2~L5。

1.5 瓶颈常常不在模型

两个公开实验说明问题：

模型参数没变，差别出在：接口提供了什么操作、结果怎么返回、错误能不能被下一步利用。

这解释了常见的 Agent 故障：重复调工具、忽略约束、长任务里丢状态——往往不能靠换模型或补一句提示词解决。

还要注意 model-harness 耦合：Claude Code、Codex 这类产品会同时调优模型和工具逻辑，模型熟悉某套工具后，换到另一套 Harness 效果可能下降。最适合当前任务的 Harness，不一定是模型后训练时用的那一套——选型应该看任务的工具、约束和验证需求。

1.6 成熟度分级

拿来自检用的阶梯：

别从 Level 4 起步。 Level 0 升到 Level 1 之后，AGENTS.md、基础 Linter 和手动测试就已经能覆盖一大半高频错误了。

🤝 记忆口诀：模型负责想，Harness 负责让它做得到。

动手改

1. 拿你现在用的 AI 编码工具，在纸上列出「模型做不到但工具替它做到了」的五件事，对照第 1.1 节那张表
2. 找出你的项目里 Agent 最容易翻车的三次经历，判断分别缺的是六层里的哪一层
3. 给项目写一句定位：现在处于 Level 0 还是 Level 1？下一个要补的那一块是什么

小结

• Agent = Model + Harness：模型是输入输出函数，Harness 补齐它做不到的部分
• Harness 的组件清单可以反推：列模型做不到的事，逐项补上
• Prompt → Context → Harness 是三层递进，不是并列
• 六层架构：信息边界、工具系统、执行编排、记忆与状态、评估观测、约束与恢复
• 瓶颈常常不在模型——换 Harness 就能让同一模型分数翻几倍
• 成熟度 Level 0~4，从 Level 1 起步最划算

下一章：信息边界与上下文，先管住「它到底该看到什么」 🐸