Harness 七层解剖：从 Instructions 到 Observability

系列第 3 篇 · 前置：第 1 篇 → 第 2 篇

前两篇讲了 Harness 是什么、Guides vs Sensors 怎么配合。这一篇把 Harness 拆成七层，逐个讲清楚：每层是什么、怎么落地、最容易踩什么坑。

这七层不是理论分类，是排查 Agent 问题时的检查清单------出了问题，从第一层往下问"这一层有没有做好"，通常能定位到根因。

一、第一层：Instructions（指令）

是什么： 告诉 AI "按什么规矩干"的所有文字。

objectivec 复制代码

包括：
  系统 Prompt
  CLAUDE.md / AGENTS.md
  Skill 定义（SKILL.md）
  编码规范文档
  架构决策记录（ADR）

怎么落地：

CLAUDE.md 放项目级规则（架构、风格、禁止事项）
SKILL.md 放领域级规则（登录模块怎么写、API 怎么调）
系统 Prompt 放角色设定（"你是一个 Android 专家，聚焦 Kotlin"）

最常见的坑：

objectivec 复制代码

坑 1：把所有规则塞进一个 CLAUDE.md
  → 上下文越长，模型越容易忽略后面的规则
  → 拆成 CLAUDE.md（项目级）+ Skills（领域级）+ 系统 Prompt（角色级）

坑 2：规则写成形容词
  → "写一个好的登录模块" → 什么是"好"？
  → 改成可验证的条款："编译通过 + token 持久化 + 状态驱动 UI"

坑 3：规则之间矛盾
  → CLAUDE.md 说"用 MVVM"，Skill 说"用 MVI"
  → AI 不知道听谁的，随机选一个
  → 维护规则时要全局一致性检查

关键认知： Instructions 是 Inferential Guides------模型读了、通常遵守，但不保证遵守。硬规则不能只靠这一层，需要第六层 Hooks 来强制。

二、第二层：Knowledge（知识）

是什么： AI 干活时需要参考的信息------之前干了什么、该参考什么、项目历史。

scss 复制代码

包括：
  记忆存储（长期记忆）
  上下文压缩 / 压缩（compaction）
  检索系统（RAG）
  进度文件（progress.md）
  对话历史

怎么落地：

短期：对话上下文（自动的，但会溢出）
中期：progress.md 记录当前进度（每轮更新）
长期：向量检索 / 知识库（项目文档、历史决策）

最常见的坑：

scss 复制代码

坑 1：靠对话历史当记忆
  → 上下文窗口一满，早期信息就没了
  → 长任务跑到第 10 轮，AI 忘了第 1 轮的决策
  → 必须有 progress.md 或其他持久化记忆

坑 2：检索不相关的信息
  → RAG 召回了一堆不相关的文档
  → AI 被干扰，反而做错
  → 检索质量 > 检索数量，精准召回比海量召回有用

坑 3：没有进度记录
  → 会话崩溃 → 全丢 → 从头再来
  → 每轮把关键决策和进度写进 progress.md
  → 这就是 Loop 系列里讲的"记忆持久化"

关键认知： Knowledge 层解决的是"AI 有没有足够的信息"。信息不够会瞎做，信息太多会被干扰。精准、持久、可检索是三个关键词。

三、第三层：Tools（工具）

是什么： AI 能调用的函数------让它从"只会说话"变成"能动手"。

复制代码

包括：
  文件读写（Read / Write / Edit）
  Shell 命令执行
  搜索（Web / 代码库）
  MCP 集成（GitHub / Slack / 数据库）
  浏览器控制
  自定义工具

怎么落地：

只给当前任务需要的工具（最小权限原则）
工具描述要精确（"读取文件内容"而不是"文件操作"）
危险工具需要权限确认（删除、发布、对外发送）

最常见的坑：

arduino 复制代码

坑 1：工具太多
  → 给 AI 20 个工具，它不知道该用哪个
  → 按需给工具，当前任务用不到的不要给

坑 2：工具描述模糊
  → 工具名叫 file_tool，描述是"处理文件"
  → AI 不知道它能读还是能写还是能删
  → 工具名+描述要精确到"读取指定路径的文本文件内容"

坑 3：工具没有错误处理
  → AI 调用工具失败 → 不知道为什么 → 反复重试
  → 工具返回值要包含明确的错误信息

关键认知： Tools 是 Harness 里最直接的"能力赋予"。工具的数量、描述、错误处理，直接决定 AI 能不能可靠地完成任务。

四、第四层：Infrastructure（基础设施）

是什么： AI 干活的物理环境------在哪跑、能碰什么、隔离程度。

复制代码

包括：
  文件系统（工作目录、权限范围）
  沙箱（Docker / 容器 / 虚拟环境）
  浏览器（受控的浏览器实例）
  执行环境（操作系统、依赖、网络）

怎么落地：

每个 Agent 任务在独立工作目录跑
危险操作在沙箱里执行（不碰宿主机）
网络访问按需开放（不是所有任务都需要联网）

最常见的坑：

bash 复制代码

坑 1：没有隔离
  → AI 直接在你的主目录干活
  → 一个 rm -rf 就能删掉你的项目
  → 必须有工作目录限制 + 沙箱

坑 2：环境不一致
  → 你本地能跑的命令，AI 的环境里跑不了
  → 依赖没装、版本不对、路径不同
  → 环境要可复现（Docker / 固定版本 / bootstrap 脚本）

坑 3：权限过大
  → AI 能读你的 SSH 密钥、能发邮件、能删仓库
  → 最小权限原则：只给当前任务需要的

关键认知： Infrastructure 是安全底线。这一层没做好，其他六层再完善也可能出大事。 AI 不是人，它不会"觉得这个操作可能有危险就停一下"------它会按指令执行。

五、第五层：Orchestration（编排）

是什么： 多 Agent / 多步骤之间的协调------谁干什么、谁能碰什么、怎么交接。

复制代码

包括：
  子 Agent 生成（spawn）
  模型路由（不同任务用不同模型）
  交接（handoff）
  上下文防火墙（子 Agent 看不到父 Agent 的全部上下文）
  权限门（危险操作需要审批）

怎么落地：

生成 Agent 和评审 Agent 分开（Loop 系列讲的独立评审）
子 Agent 只拿到完成任务需要的最小上下文
危险操作触发权限门，暂停等人确认

最常见的坑：

arduino 复制代码

坑 1：一个 Agent 干所有事
  → 又写代码又测代码又审代码
  → 自己评自己 → 假达标
  → 至少拆成生成 + 评审两个角色

坑 2：子 Agent 上下文泄漏
  → 把整个对话历史传给子 Agent
  → 子 Agent 被无关信息干扰，还可能泄漏敏感信息
  → 上下文防火墙：只传任务相关的

坑 3：没有交接协议
  → 生成 Agent 写完代码，评审 Agent 不知道从哪开始
  → 交接要结构化："修改了哪些文件、为什么改、还有什么没做"

关键认知： Orchestration 层解决的是"多角色怎么协作"。单 Agent 靠自觉，多 Agent 靠协议。 协议越清晰，协作越可靠。

六、第六层：Hooks / Middleware（钩子/中间件）

是什么： 在 Agent 生命周期的特定节点，由 Harness（不是模型）确定性执行的脚本。

vbnet 复制代码

包括：
  PreToolUse（工具调用前）
  PostToolUse（工具调用后）
  UserPromptSubmit（用户提交后）
  Stop（Agent 停止时）
  SubagentStart / SubagentStop（子 Agent 启停时）

怎么落地：

写 Shell 脚本，在 .claude/settings.json 里注册（matcher 声明触发哪个工具）
事件 JSON 从 stdin 传入（INPUT=$(cat)，用 jq 取值）
要阻止操作：向 stdout 输出 JSON 决策（permissionDecision: "deny"）
脚本可以修改输入、注入上下文、记录日志

最常见的坑：

objectivec 复制代码

坑 1：以为 CLAUDE.md 能强制规则
  → CLAUDE.md 是建议，模型可以忽略
  → Hook 是强制，模型无法绕过
  → 硬规则（禁止操作、合规检查）必须用 Hook

坑 2：Hook 脚本太复杂
  → Hook 应该轻量、快速、确定性
  → 一个 PreToolUse 跑 30 秒，每次工具调用都卡
  → Hook 做简单检查（路径白名单、命令黑名单），复杂逻辑放 Agent 里

坑 3：Hook 没有错误信息
  → Hook 阻止了操作，但只返回"拒绝"
  → AI 不知道为什么被拒，无法修正
  → 返回明确的原因："禁止删除 /Users/ 下的文件，请指定项目内路径"

关键认知： Hooks 是 Harness 里唯一能保证确定性执行的地方。CLAUDE.md 是"请你遵守"，Hook 是"你必须遵守"。下一篇专门讲这一层。

七、第七层：Observability（可观测性）

是什么： 让你能看见 Agent 干了什么、花了多少、哪里出了问题。

复制代码

包括：
  日志（每轮对话、每次工具调用）
  追踪（trace，端到端的执行链路）
  成本计量（token 消耗、API 调用次数、费用）
  事件总线（关键节点触发事件，供外部系统消费）

怎么落地：

至少记录：每轮的输入/输出、工具调用、耗时、token
成本监控：设置预算上限，超了告警
失败追踪：记录失败的步骤、错误信息、重试次数

最常见的坑：

javascript 复制代码

坑 1：没有日志
  → Agent 跑了一轮，出了错，你不知道它干了什么
  → "它好像删了个文件？删的哪个？"
  → 必须有完整的执行日志

坑 2：只看结果不看过程
  → 最终代码是对的，但中间跑了 50 轮、花了 $20
  → 没有成本意识，Agent 可以空转烧钱
  → 成本计量 + 步骤预算是必须的

坑 3：日志不可搜索
  → 日志写了，但几千轮里找不出"那次失败"
  → 结构化日志（JSON）+ 可查询（按时间/任务/错误类型筛选）

关键认知： Observability 是"你能不能 debug Agent"的前提。看不见就调不了，调不了就不可靠。 生产级 Agent 必须有这一层。

八、七层之间的关系

七层不是孤立的，它们有依赖关系：

markdown 复制代码

Infrastructure（在哪跑）是地基
  → Tools（能干什么）建在基础设施之上
    → Knowledge（知道什么）给工具调用提供上下文
      → Instructions（按什么规矩）指导怎么用工具
        → Orchestration（谁干什么）协调多个角色
          → Hooks（强制规则）在关键节点拦截
            → Observability（能看见什么）贯穿所有层

一个排查口诀：

复制代码

Agent 做了不该做的事 → 查 Hooks（第六层）有没有拦住
Agent 不会做该做的事 → 查 Tools（第三层）有没有给够
Agent 忘了之前的决策 → 查 Knowledge（第二层）有没有持久化
Agent 不遵守规矩 → 查 Instructions（第一层）写清楚了吗 + Hooks 强制了吗
Agent 多角色乱套 → 查 Orchestration（第五层）协议清晰吗
Agent 出错了你不知道 → 查 Observability（第七层）有没有日志
Agent 把环境搞坏了 → 查 Infrastructure（第四层）有没有隔离

九、这一篇总结

ini 复制代码

1. Harness 七层：Instructions / Knowledge / Tools / Infrastructure /
   Orchestration / Hooks / Observability
2. Instructions = 规矩（建议性，模型可忽略）
3. Knowledge = 信息（精准、持久、可检索）
4. Tools = 能力（最小权限、精确描述、错误处理）
5. Infrastructure = 环境（隔离、可复现、安全底线）
6. Orchestration = 协作（角色分离、上下文防火墙、交接协议）
7. Hooks = 强制（唯一确定性执行的地方，硬规则靠它）
8. Observability = 可见（日志、追踪、成本，debug 的前提）
9. 出问题从第一层往下查，每层问"这一层做好了吗"

下篇专门讲第六层 Hooks------为什么 CLAUDE.md 不够，Hook 才是 Harness 的底线，以及怎么写有效的 Hook。