AI Coding Harness

它是什么

AI coding harness（AI 编码框架）是你在编码 agent 周围搭建的强制执行与验证脚手架，让它能够自主运行而不至于把事情搞砸。如果说护栏（guardrail）是一种你必须靠记忆去遵守的习惯（跑测试、看 diff），那么 harness 就是一台替你记住这些的机器：它位于 agent 的意图与真实世界之间，在每一个危险步骤上进行记录、警告或拦截。dancinlab/harness 是一个与具体项目无关的参考引擎——一个共享的 TypeScript 核心，每个仓库的差异仅在于一份 harness.config.json 加上几个 .harness/*.json 数据文件。

优势

把你的护栏从可有可无的习惯变成由代码强制执行的规则——agent 无法跳过它们。
对整个工具生命周期进行把关：命令运行之前、文件写入之前、在 prompt 上、在 commit 时、在 push 时。
仅追加（append-only）的 JSONL 账本提供了 agent 一切行为的防篡改记录——写入成本极低，审计也轻而易举。
可嵌入任何仓库：行为由配置和数据决定，而非分叉的代码。
设计上在一切正常时保持安静，因此警告出现时仍然有分量。

取舍

它是管道工程，不是魔法：harness 让错误易于被廉价地捕获，但它并不能让 AI 变得正确。
需要初始设置，以及一份针对你项目危险区调校过的配置。
过于严格的规则会带来摩擦；"bitter-gate"（苦闸）纪律——在新增规则之前先退役一条休眠规则——正是为了对抗这一点而存在。
在有真实用户的真实项目上最有价值——对于一次性的原型来说则是杀鸡用牛刀。

最适合

认真的 vibe coding：你让一个 agent 在基本无人监督的情况下进行多文件改动并运行命令，同时你需要把一次糟糕操作的代价维持在接近于零。

五项原则（H1–H5）

H1 成功安静、失败响亮——不制造你迟早会学会忽略的噪音。
H2 永不自动修复——提出建议、拦截或警告；由人类或知情的 agent 来决定。
H3 Bitter-gate——在新增规则之前先退役一条休眠规则。
H4 配置驱动——一个引擎，每个项目一份 harness.config.json。
H5 AI 原生——仅追加的 JSONL 账本，无法被悄然改写。

它长什么样

一份最简配置草图：

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

以及围绕单次 agent 操作的前置/后置钩子（hook）流程：

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

agent 永远无法绕过这道闸门——这正是整件事的关键所在。