uni-harness

🇺🇸 English | 🇰🇷 한국어 | 🇨🇳 简体中文 | 🇯🇵 日本語

一个面向 Claude Code 的智能体挽具（harness）套件。它为编码智能体包上 自动验证（传感器）、破坏性命令拦截（守卫）、基于检查点的会话恢复、 带绊线告警的全量工具调用日志，以及把每次失败都转化为永久结构的 棘轮（ratchet）工作流。

公式：Agent = Model + Harness。 模型带来推理能力； 其余的一切 — 规则、传感器、循环上限、记忆、可观测性 — 由这个套件提供。

安装

npx uni-harness init            # 在项目根目录执行（或：init <路径>）

然后在项目中打开 Claude Code — Claude 会发现挽具尚未配置，并 主动提议运行 /harness-init（也可以自己运行）。它会扫描仓库、 检测构建/测试/lint 命令、通过实际运行来验证它们，并在你批准后 填入 CLAUDE.md 和 .harness/commands.env。在此步骤完成前， 验证传感器保持待机。

其他安装器命令：

npx uni-harness update          # 刷新套件机件（绝不触碰你的文件）
npx uni-harness doctor          # 诊断安装状态
npx uni-harness uninstall --yes # 移除套件机件，保留你的文件

依赖要求：bash、python3（仅标准库 — 无需任何包）、安装器本身需要 node ≥16。

对进行中的项目同样安全。 init 绝不覆盖你拥有的任何东西： 已有的 CLAUDE.md 会被保留（运行 /harness-init 后它会以追加方式 提议补充挽具章节），已有 settings.json 中的钩子和权限会被保留 （套件钩子以合并方式加入），你的 .gitignore 只会被追加而不是替换。 update 只刷新未被修改的套件文件 — 你自定义过的一律跳过 （会列出，可用 --force 覆盖）。

内含组件

| 文件 | 作用 | |---|---| | CLAUDE.md | 项目命令、规则、反模式、工作循环与检查点协议 | | AGENTS.md | 规则的跨工具镜像 — Codex、Cursor、Aider、Gemini CLI 等 20+ 工具都会读取 | | .claude/settings.json | 钩子注册 | | .claude/hooks/sensor-post-edit.sh | 每次代码编辑立即运行 lint，将失败反馈回去 | | .claude/hooks/stop-gate.sh | 回合结束时批量运行测试；失败状态下阻止收工（每会话 3 次上限，超过则强制升级上报）；执行可选的轨迹规则（.harness/trace.rules："回合结束前必须发生过 X"） | | .claude/hooks/guard-pre-bash.sh | 在执行前拦截破坏性命令与验证绕过（--no-verify）；当要提交从未通过测试的编辑时先向用户确认 | | .claude/hooks/guard-pre-edit.sh | 反作弊关卡：削弱测试的编辑（skip/only 标记、删除测试、掏空断言）以及配置/挽具文件的更改都需要用户批准 | | .claude/hooks/pre-compact.sh | 在上下文压缩前对检查点做快照；恢复时的检查点刷新指令由 session-start.sh 负责 | | .claude/hooks/session-start.sh | 会话启动/恢复/压缩时重新注入进行中的检查点；失败堆积时提示 /ratchet | | .claude/hooks/session-end.sh | 每个会话写入一行台账（时长、调用/失败/编辑数、收工拦截次数、测试状态）→ sessions.jsonl | | .claude/hooks/observe-log.sh | 以 JSONL 记录每次工具调用 + 绊线（同一失败 3 次、调用激增） | | harness/harness_report.py | 基于日志的健康记分卡 | | harness/tests/ | 钩子与安装器的自测 | | bin/cli.js | 安装器（init / update / doctor / uninstall） |

技能：

| 技能 | 作用 | |---|---| | /harness-init | 扫描仓库 → 填写 PROJECT 章节 & commands.env（安装时一次） | | /checkpoint | 将状态保存到 .harness/state/（plan.md / decisions.jsonl / progress.json） | | /ratchet [失误] | 复现 → 归类 → 提议规则/传感器/权限 → 验证（无参数：诊断日志）。每个提议附带可证伪的预测（predictions.jsonl） | | /guide-audit | 审计 CLAUDE.md 规则 — 保留 / 删除 / 转为传感器（每月）；将过往预测与日志比对验证，没起作用的规则凭证据删除 | | /distill [成功] | 成功侧的棘轮：从日志中挖掘已完成的任务，提议为可复用的项目技能 |

推荐权限配置（可选）

套件不强加权限策略。若用于无人值守或高自治场景，可考虑在项目的 .claude/settings.json 中加入类似配置 — 尤其是阻止智能体修改 自身挽具的那些条目：

{
  "permissions": {
    "ask": [
      "Edit(.claude/**)", "Write(.claude/**)",
      "Edit(.harness/**)", "Write(.harness/**)",
      "Edit(.env*)", "Edit(*.config.*)", "Edit(.github/**)"
    ],
    "deny": [
      "Read(.env)", "Read(.env.*)", "Read(**/secrets/**)",
      "Read(**/*.pem)", "Bash(sudo*)"
    ]
  }
}

运营例程

• 每天 / 每个任务： 正常干活即可。传感器和守卫是自动的。 长任务用 /checkpoint 保存状态。
• 发现失误时： 不要只在对话里修掉 — 运行 /ratchet [发生了什么] 把它结构化。同一审查意见出现 3 次 → 变成规则；同一规则被违反 3 次 → 升级为守卫/权限。
• 每周： 用 python3 harness/harness_report.py 查看记分卡； 出现重复失败就运行 /ratchet。
• 一次有意义的成功之后： 若流程还会重复，用 /distill 把它 变成项目技能。
• 每月： 用 /guide-audit 审计 CLAUDE.md — 删除传感器已自动 强制执行的规则，合并互相矛盾的规则，并将每条规则的预测与日志 比对（同一失败仍在发生的规则，凭数字而非感觉删除或升级）。

自定义

• 危险命令模式：guard-pre-bash.sh 中的 DENY_PATTERNS
• 绊线阈值：observe-log.sh（默认：同一失败 3 次、300 次调用）
• 传感器文件扩展名：sensor-post-edit.sh 中的 case 语句
• 收工拦截上限：stop-gate.sh（默认：每会话 3 次）
• 修改了钩子就在 harness/tests/test_hooks.sh 加一个用例并运行

什么时候不该用

对一次性提问、探索性头脑风暴、无法验证的创意工作来说它是杀鸡用牛刀。 它的价值体现在：反复运行的工作、失败有真实代价的工作、无人值守运行 的工作、以及必须跨会话保持状态的工作。

设计背景

本套件是两份材料的可运行实现。完整分析在 docs/ 中 — 它们不随 npm 包分发（运行中的智能体不需要理论），但解释了这里的 每一个设计决策。

📄 EnvHarness: Awakening Static Worlds for Agent Learning

arXiv:2608.19880 · Chengsong Huang, Zifeng Wang, Rujun Han, Chen-Yu Lee 等 (2026) 深度解读：docs/analysis-01-envharness.md

论文主张。 正如给智能体装上挽具（工具、记忆、技能）可以在不动 权重的情况下扩展它，你也可以给环境装上挽具，在不动其代码的情况下 定制学习信号：Static Env + EnvHarness = Customized Env。环境只在 接口层通过三个可组合的组件被变换 — Stage（重塑初始状态）、 Contract（过滤动作、变换观测、包装转移）、Chain（组合环境）— 因此原始的真值验证器始终得到保留，这正是它相对 LLM 生成环境的核心 优势。一个名为 EnvRigger 的自动化循环驱动设计：观察失败轨迹 → 诊断根因 → 编写变换 → 对原始失败进行验证。在五个基准上， 包装后的环境提升了智能体表现（如 ALFWorld 分布外 +9.0 分、SWE-bench Verified +2.7 且步数减少 9.8%）— 分布外增益最大，是迁移而非记忆的 证据。

本套件从中借鉴的：

| 论文概念 | 此处的实现 | |---|---| | EnvRigger 循环（观察 → 诊断 → 编写 → 验证） | /ratchet 技能 — 自动接受被替换为用户批准 | | Contract：动作过滤 | guard-pre-bash.sh（破坏性命令执行前拦截） | | Contract：结构化反馈 | sensor-post-edit.sh / stop-gate.sh（验证结果反馈） | | Stage：备妥的初始状态 | 会话启动时的检查点恢复 | | 保留原始验证器 | 不变量：挽具包装你的测试套件，但绝不修改或绕过它 |

📘 挽具工程：6 层生产实战手册

公开实践者材料的综合 — Mitchell Hashimoto 的棘轮方法论、OpenAI Codex 实战报告、 Martin Fowler 的向导与传感器分类法，以及 Anthropic / LangChain / Cursor 的资料。 深度解读：docs/analysis-02-harness-engineering.md

手册主张。 提示词工程（模型说什么）和上下文工程（模型看到 什么）都被挽具工程所涵盖：模型能做什么、什么能在失败中幸存、什么被 允许、什么算完成。Agent = Model + Harness 这一主张有自报但一致的 证据支撑 — 同一个模型仅靠更换挽具在 GAIA 上从 30.91% 跃升至 74.55%， 固定模型仅靠挽具优化在 Terminal Bench 上从第 30 名爬到第 5 名。 架构分为六层，与本套件一一对应：

| # | 层 | 原则 | 在本套件中 | |---|---|---|---| | 1 | 向导 | 每一行 = 对一次过往失败的永久预防 | CLAUDE.md | | 2 | 传感器 | 外部确定性检查，绝不自我评判 | sensor-post-edit.sh、stop-gate.sh | | 3 | 智能体循环 | 每项预算都有上限，耗尽即升级上报 | 工作循环协议 + 绊线 + 3 次收工拦截上限 | | 4 | 记忆 | 文件系统即记忆；必须通过恢复测试 | /checkpoint + session-start.sh | | 5 | 权限 | 模型无法限制它自己 | guard-pre-bash.sh + 推荐权限 | | 6 | 可观测性 | 记录一切，对漂移告警 | observe-log.sh + harness_report.py |

运营规则也来自于此 — Hashimoto 的棘轮原则（"智能体每犯一次错， 就工程化一个让该错误不可能重演的方案"）以及 Cursor 的晋升阶梯：

flowchart LR
    F[观察到失败] --> R["/ratchet: 复现 + 诊断"]
    R --> P{最强的层}
    P -->|缺的是上下文| G["向导规则 (CLAUDE.md)"]
    P -->|检查可以捕获| S[传感器 / lint 规则]
    P -->|应当彻底不可能| H[守卫 / 权限]
    G & S & H --> V[针对原始失败验证]
    V --> N[同一失败无法重演]

同一审查意见出现 3 次 → 变成规则。同一规则被违反 3 次 → 变成关卡。而成熟的信号是规则增速的下降 — 只会堆积的挽具就是债务， 这正是 /guide-audit 存在的意义。

想扩展套件本身？从 docs/AGENT_BRIEFING.md 开始 — 那里有 不变量（不得削弱验证、未经批准不得自动应用、最小基础设施）和经过 审核的待办清单。