插章：AI Agent 与编程工具的结构

插章：AI Agent 与编程工具的结构#

你没法驾驭一个你没有拆开看过的东西。

第 03 章给 Harness Engineering 下了定义：它不是造智能体，而是造智能体周围的环境。本插章补上中间那块剖面图：现代 AI Agent 与 AI 编程工具，到底由哪些层组成？它为什么会跑偏？又该把马具接在哪些位置，才能让它更接近"按照我的想法、规则和习惯，从头到尾完成一个项目"？

先给结论：不要把智能体想成"一个会写代码的大模型"。 更准确的模型是：

用户输入 → 上下文装配 → 大模型决策 → 工具调用 → 观察结果
       ↖          记忆更新 ← 状态更新 ← 结果解释 ←

也就是说，真正需要被驾驭的不是模型权重本身，而是这条循环里的 输入、上下文、工具、记忆、停止条件、反馈信号。一具好马具不是让模型"更聪明"，而是让这条循环每一步都更难偏离你的意图。

05.1 Agent Loop：最小心智模型#

现代编码智能体的核心，是一个 observe → decide → act 的循环。ReAct 把"推理（Reasoning）"与"行动（Acting）"放进同一条轨道 [Yao et al., 2022]；Toolformer 则把工具使用推进为语言模型行动面的第一等公民 [Schick et al., 2023]。落到编码工具里，这条循环通常长这样：

        flowchart LR
  U["用户输入<br/>task / intent / constraints"] --> C["上下文装配<br/>repo files / docs / memory / rules"]
  C --> M["大模型决策<br/>plan / next action / tool choice"]
  M --> T["工具调用<br/>edit / shell / test / search / MCP"]
  T --> O["观察结果<br/>stdout / diff / error / test result"]
  O --> S["状态与记忆更新<br/>short-term / long-term"]
  S --> M
  M --> F["最终输出<br/>patch / explanation / PR / handoff"]

每一圈 loop 都可能变好，也可能变坏。智能体第一次读错意图，第二圈就会把错误当成上下文继续使用；一次工具输出被误解，下一圈就可能在错误前提上继续施工；一段过时的长期记忆被召回，整个项目会沿着旧架构走。Harness Engineering 的切入点，就是让这些错误尽早暴露、尽早被拒绝、尽早被回灌。

05.2 七个承重点#

用户输入：目标不是 prompt，而是任务契约#

用户输入不是"请帮我做 X"这么一句话。对编码智能体来说，真正有用的输入至少包含四项：

  • 目标：要交付什么行为。

  • 边界：哪些目录、接口、依赖不能碰。

  • 验收：什么测试、截图、命令或指标算完成。

  • 偏好：团队的命名、错误处理、日志、提交风格。

如果这些没有写清，智能体不会停下来等待澄清；它会选一个看似合理的解释，然后自信地写下去。第 07 章把这种失败叫 歧义放大。

对应马具：AGENTS.md、issue 模板、验收表、设计草案、任务拆分 skill。

上下文窗口：长不等于准#

Context window 是智能体当下能看到的那一卷材料。它可能包括当前对话、打开的文件、检索片段、错误日志、测试结果、规则文件和工具 schema。Karpathy 所谓 context engineering，讲的正是如何组合这份输入窗口 [Karpathy, 2025]。

上下文越长，召回越多，但污染也越多。三段"差不多相关"的旧实现，可能比没有上下文更糟：模型会把它们取平均，生成第四种同样平庸的实现。RAG 的价值不是"把更多东西塞进来"，而是把 该看的东西 放进来，把 不该看的东西 拦在外面 [Lewis et al., 2020]。

对应马具：sources-of-truth 索引、上下文白名单、弃用路径黑名单、检索质量评审、坏链扫描。

记忆：短期记忆负责连贯，长期记忆负责惯性#

短期记忆通常是本轮对话、scratchpad、计划列表、最近工具输出。它让智能体能连续工作，也会让一次错误解释在后续 loop 中反复扩散。

长期记忆通常是知识库、向量索引、规则文件、历史总结、项目 wiki。它让智能体继承团队习惯，也会让过时架构继续阴魂不散。对长期记忆来说，最危险的状态不是"没有"，而是"有，但没人知道它已经旧了"。

对应马具：verified: 日期、Groom job、过期记忆清单、ADR 状态、memory reset 规则。

工具：智能体真正改变世界的手#

模型只生成 token；工具才改变世界。编辑文件、运行 shell、调用浏览器、访问 MCP server、发 PR、查日志、跑部署，都是工具面的一部分。MCP 把工具契约做成可声明、可发现、可组合的协议面 [Anthropic, 2024]。

工具面有三类典型风险：

  • 工具幻觉：模型以为有某个工具或参数，但实际没有。

  • 权限过宽：工具能做的事超过当前任务需要。

  • 观察误读：工具返回错误，模型却把它当成功继续推进。

对应马具：工具 schema 检查、权限白名单、危险工具审批、命令输出解析、失败码硬拒绝。

Prompt、rule、skill：过程被写成制品#

Prompt 是一次性的说法；rule 是仓库里的家规；skill 是可复用的流程。它们都在塑造智能体"下一步该怎么做"，但承重能力不同。

一条 prompt 能解决一次任务；一条 skill 能解决一类任务；一条被 hook 约束的 skill，才能成为团队纪律。没有护栏的 skill，容易退化为"我会按照 TDD 技能来做"这种合规口号。

对应马具：SKILL.md、.cursor/rules、Claude Code commands、AGENTS.md、skill 前置条件检查。

Controller：循环预算、停止条件与升级路径#

Agent Loop 需要一个 controller：决定下一步是否继续、调用哪个工具、何时停止、何时向人类升级。很多"跑偏"不是模型第一步错了，而是 controller 没有及时刹车。

常见失控模式：

  • 连续三次测试失败仍继续乱改。

  • 成本超过阈值仍继续请求模型。

  • diff 变得过大仍不切小任务。

  • 任务目标变化后仍沿着旧 plan 前进。

对应马具：turn budget、cost cap、diff size cap、失败重试上限、升级规则、SessionEnd 总结。

输出：最终答案不是终点，证据才是终点#

编码智能体的最终输出不应只是"我完成了"。工程上有用的输出至少包含：

  • 改了哪些文件。

  • 跑了哪些命令。

  • 哪些检查通过。

  • 哪些风险仍未处理。

  • 哪个证据能证明需求被满足。

对应马具：PR 模板、Verification Table、HarnessCard delta、release note、可复现脚本。

05.3 跑偏的七种原因#

跑偏原因

表面症状

真正问题

对应马具

目标含糊

代码能跑，但不是你要的

用户输入没有验收条件

SDD × 缰绳

上下文污染

生成了混合风格实现

检索召回了旧路径或坏例子

SDD × 梳理

工具幻觉

调了不存在的命令或参数

工具 schema 不被验证

SDD × 护栏

权限过宽

改了不该改的目录

工具面没有边界

TDD × 护栏 / 牧场

红树继续写

测试失败后越改越多

没有及时拒绝

TDD × 护栏

成本失控

结果一样，账单变大

loop 缺少成本信号

MDD × 护栏

记忆漂移

按旧架构写新代码

长期记忆无人维护

SDD × 梳理

这张表的重点是：跑偏很少只有一个原因。一次"智能体不听话"，往往同时包含含糊任务、污染上下文、过宽工具和缺失反馈。Harness Engineering 的价值，是把这些原因拆开，让每个原因都能落到一件可改的制品上。

05.4 针对性驾驭：把马具接到正确层#

Agent 层

缰绳

护栏

牧场

梳理

用户输入

issue 模板、任务契约

prompt schema

PO / reviewer 验收

复盘含糊需求

上下文

sources-of-truth 索引

禁用路径检查

上下文包评审

坏链与过期文档扫描

记忆

verified: 日期

过期记忆拒绝

ADR 状态机

定期 memory prune

工具

工具说明与示例

schema / permission gate

沙箱与审批

工具清单审计

Skill / rule

AGENTS.md / SKILL.md

skill 前置条件检查

角色化 review

skill drift review

Controller

plan / budget

turn cap / cost cap

分阶段验收

失败模式复盘

输出

完成定义

PR 模板检查

Verification Table

HarnessCard delta

一旦你用这张表看 AI 编程工具，就会发现"让它不要跑偏"不是一句愿望，而是一组具体工程选择：上下文要筛，工具要限权，loop 要有预算，输出要带证据，长期记忆要有人梳理。

05.5 Autonomy Envelope：什么时候可以少人工纠正#

"从头到尾不需要人工纠正"不是一个绝对承诺，而是一条 autonomy envelope（自主工作包络）。任务落在包络内，智能体可以高度自主；任务跑出包络，智能体必须停下来、请求澄清或升级给人。

一项任务落在包络内，至少满足八个条件：

  1. 目标可验收。 有测试、截图、命令、指标或人工验收表。

  2. 边界清楚。 允许改哪些目录、禁止改哪些目录写在 AGENTS.md 或任务契约里。

  3. 上下文可信。 sources-of-truth 明确，过期文档有标记。

  4. 工具够用但不过宽。 能运行测试、编辑文件、查文档；不能随手碰生产、密钥、部署。

  5. 失败会被拒绝。 红测试、密钥扫描、schema mismatch、成本超限都会停住 loop。

  6. 记忆可刷新。 长期规则有 owner 和 Groom 节奏。

  7. 输出带证据。 最终回答必须列出 diff、命令、结果和剩余风险。

  8. 有升级路径。 需求冲突、权限不足、连续失败、超预算时必须停下来问。

这八条都满足时，"少人工纠正"才是工程目标；少一半时，它就只是把人类 review 推迟到更痛的时刻。

05.6 一条实用调试法：看 trace，不看态度#

当智能体跑偏时，不要问"它为什么不听话"。问这七个 trace 问题：

  1. 用户输入里有没有完成定义？

  2. 它实际看到了哪些文件和规则？

  3. 它召回了哪些长期记忆？

  4. 它为什么选择这个工具？

  5. 工具返回了什么观察结果？

  6. 它如何解释这个结果？

  7. 哪一条护栏本该挡住它，却没有挡住？

这就是 Agent Loop 版的事故复盘。你不是在评价模型人格，而是在检查一条工程流水线：输入、上下文、工具、记忆、决策、观察、输出，哪一段缺了马具。

研究脉络#

  • ReAct [Yao et al., 2022] —— 把 reasoning 与 acting 放进同一条循环，是本章 Agent Loop 图的学术底座。

  • Toolformer [Schick et al., 2023] —— 工具不是附属品，而是语言模型行动面的核心组成。

  • RAG 与 Context Engineering [Karpathy, 2025, Lewis et al., 2020] —— 上下文不是越多越好，而是一件需要工程化选择、过滤和维护的输入制品。

  • MCP [Anthropic, 2024] —— 现代工具面正在从 ad hoc 函数调用，走向可声明、可检查、可组合的协议。

  • Agent Engineering 经验框架 [Anthropic, 2024, LangChain, 2026] —— 业界已经把 prompts、tools、memory、orchestration、runtime 当作智能体产品的主要剖面；本章把这些剖面翻译成 Harness Engineering 的接点。

动手环节#

本章的两份 hands-on 制品住在 source/_handson/05-agent-loop-anatomy/：

  • agent-loop-harness-map.yaml —— 把 Agent Loop 的七层映射到缰绳、护栏、牧场、梳理。

  • autonomy-envelope-checklist.md —— 一份 8 条检查表，用来判断某个任务能否交给智能体高度自主完成。

# verified: 2026-04-24 · Ch.03B hands-on · Agent Loop to harness map
agent_loop_layers:
  user_input:
    bridle: ["issue template", "acceptance criteria", "task contract"]
    fence: ["prompt schema", "required fields check"]
    paddock: ["PO/reviewer acceptance table"]
    groom: ["ambiguous requirement retro"]
  context_window:
    bridle: ["sources-of-truth index", "context pack"]
    fence: ["deprecated-path denylist", "broken-link check"]
    paddock: ["context package review"]
    groom: ["weekly docs freshness scan"]
  memory:
    bridle: ["verified headers", "ADR status"]
    fence: ["reject stale memory beyond max_age_days"]
    paddock: ["architecture review"]
    groom: ["memory prune schedule"]
  tools:
    bridle: ["tool examples", "MCP manifest"]
    fence: ["schema check", "permission allowlist"]
    paddock: ["sandbox", "approval for dangerous tools"]
    groom: ["tool inventory audit"]
  skills_and_rules:
    bridle: ["AGENTS.md", "SKILL.md", ".cursor/rules"]
    fence: ["skill precondition hook"]
    paddock: ["role-scoped review"]
    groom: ["skill drift review"]
  controller:
    bridle: ["plan", "turn budget", "cost budget"]
    fence: ["turn cap", "cost cap", "diff size cap"]
    paddock: ["phase gate"]
    groom: ["failure-mode retro"]
  output:
    bridle: ["definition of done"]
    fence: ["PR template check"]
    paddock: ["Verification Table"]
    groom: ["HarnessCard delta"]

<!-- verified: 2026-04-24 · Ch.03B hands-on · autonomy envelope checklist -->

# Autonomy Envelope Checklist

Use this before asking an AI coding agent to complete a task with minimal
human correction.

- [ ] **Goal is testable.** The task has tests, screenshots, commands,
      metrics, or a review table that can decide done vs not done.
- [ ] **Boundaries are explicit.** Allowed and forbidden paths are listed in
      `AGENTS.md`, the issue, or the task contract.
- [ ] **Context is trustworthy.** Sources of truth are named; stale docs and
      deprecated paths are marked or blocked.
- [ ] **Tools are sufficient.** The agent can edit, inspect, test, and search
      what it needs.
- [ ] **Tools are not overpowered.** Production, secrets, deploys, and
      destructive commands require approval or are unavailable.
- [ ] **Failures stop the loop.** Red tests, schema mismatches, secret scans,
      and cost caps block further work.
- [ ] **Memory can be refreshed.** Long-term rules have an owner and a Groom
      cadence.
- [ ] **Final output includes evidence.** The agent must report changed files,
      commands run, results, and remaining risks.

If fewer than six boxes are checked, keep a human in the loop. If all eight
are checked, the task is inside the autonomy envelope.