@erzhe/harness-kit 0.1.1 → 0.1.2

package/README.md

@@ -1,81 +1,131 @@
 # @erzhe/harness-kit
 
-> AI-friendly repo harness —— 把工程知识变成 agent 可消费的**契约层**。
+> 给 Agent 发一句话，让它帮你把仓库变成 AI 友好的。
 
-一份 `.agents/manifest.yaml` 作为单一事实源，生成各家 agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用**门禁**保证不变量、对外契约和文档不漂移。让不同的人、不同的机器上的 agent，构建出**一模一样的范式**。
+harness-kit 把仓库的工程知识（这是什么、怎么跑、什么不能破、改东西看哪）沉淀成一份 `.agents/manifest.yaml`，然后自动生成各家 Agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用门禁保证它们始终一致。
 
-> 包名 `@erzhe/harness-kit`，安装后命令行工具叫 **`harness-kit`**。
+---
 
-## 最快上手（推荐，零安装）
+## 最快上手
 
-在**任意仓库**里，把这句丢给你的 agent（Cursor / Claude Code / Codex 通用）：
+在**任意仓库**里，把这句话丢给你的 Agent（Cursor / Claude Code / Codex 通用）：
 
-> Onboard 本仓库到 harness-kit：跑 `npx -y @erzhe/harness-kit@latest onboard`，然后严格按输出执行。
+```
+Onboard 本仓库到 harness-kit：跑 npx -y @erzhe/harness-kit@latest onboard，然后严格按输出执行。
+```
 
-agent 会拉取**最新版**的 onboard skill 并照着做：仓库考古 → 逐块跟你确认着填 `.agents/manifest.yaml` → `sync` / `doctor` / `verify` 到绿。全程走 `npx`，不往机器上装任何全局东西；你一发新版，所有人下次执行就用上了。
+就这一句。Agent 会：
 
-## 为什么
+1. 拉取最新版的 onboard skill
+2. 扫描你的仓库（读 README、package.json、目录结构…）
+3. 逐块跟你确认着填 `.agents/manifest.yaml`
+4. 跑 `sync` / `doctor` / `verify` 直到全绿
 
-传统工程化（脚手架 / lint / CI）是**面向过去、面向人**的。Agent 需要的是显式、结构化、可机器消费的知识：这个仓库是什么、能跑什么、什么绝不能破、改动该看哪、哪些验证不了。`harness-kit` 把这些沉淀进 manifest，再确定性地生成与校验。
+全程走 `npx`，不往机器上装任何全局东西；你一发新版，所有人下次执行就用上了。
 
-## 安装
+---
 
-```bash
-npm i -g @erzhe/harness-kit      # 或 pnpm add -g / 直接 npx @erzhe/harness-kit
-harness-kit --help
+## 初始化后你得到什么
+
+```
+你的仓库/
+  AGENTS.md                    ← [生成] 跨工具入口，Agent 每次会话必读
+  CLAUDE.md                    ← [生成] Claude Code 入口
+  .cursor/rules/               ← [生成] Cursor 规则
+  .agents/
+    manifest.yaml              ← 你维护的唯一真相源
+    knowledge/                 ← Agent 从代码推不出来的知识（领域、约定、决策）
+    contracts/                 ← 对外接口的契约基线
+    playbooks/                 ← 可复用的工作流（SKILL.md）
+    routing.md                 ← [生成] 按改动类型导航：改 UI 看哪、加接口看哪
+    modules.md                 ← [生成] 模块卡：每个子系统的职责/入口/坑
 ```
 
+以后改工程知识 → 编辑 `manifest.yaml` → `harness-kit sync`。别手改生成物。
+
+---
+
 ## 命令
 
-```
-harness-kit onboard          # 打印 onboard skill 给 agent（配合 npx，永远最新、零安装）
-harness-kit init             # 铺 .agents/ 骨架 + starter manifest
-harness-kit sync             # manifest -> AGENTS.md / CLAUDE.md / Cursor rules / routing / modules
-harness-kit doctor           # 开发态体检：补全度 / 引用路径 / 漂移 / 新鲜度 / 体量预算
-harness-kit verify           # 门禁（CI）：跑不变量 + 契约 + 漂移，列出 GAPS，失败非 0 退出
-harness-kit accept-contract  # 一次预期的接口变更后，记录新的契约指纹为基线
-```
+| 命令 | 作用 |
+| --- | --- |
+| `harness-kit onboard` | 打印 onboard skill 给 Agent（配合 npx，永远最新、零安装） |
+| `harness-kit init` | 铺 `.agents/` 骨架 + 空白 manifest |
+| `harness-kit sync` | manifest → 生成 AGENTS.md / CLAUDE.md / Cursor rules / routing / modules |
+| `harness-kit doctor` | 体检：完整性 / 路径引用 / 漂移 / 新鲜度 / 体量预算 |
+| `harness-kit verify` | 门禁：跑不变量 + 契约 + 漂移，列出 GAPS，失败非 0 退出 |
+| `harness-kit accept-contract` | 有意变更接口后，记录新的契约指纹为基线 |
+| `harness-kit install-hooks` | 装 git 钩子：pre-commit 自动 sync + pre-push verify 拦漂移 |
+
+所有命令都支持 `-C <dir>` 指定目标仓库（默认当前目录）。
+
+---
+
+## 它解决什么问题
 
-## 心智模型
+传统工程化（脚手架 / lint / CI）是**面向人、面向过去**的。Agent 需要的是显式、结构化、可机器消费的知识：
+
+- **这是什么** → `identity`（name / summary / scope）
+- **怎么跑** → `capabilities`（setup / build / test / dev…）
+- **什么绝不能破** → `invariants`（声明式正则门禁）+ `contracts`（接口指纹基线）
+- **改东西看哪** → `routing`（按改动类型导航）+ `modules`（模块卡）
+- **哪些验证不了** → `GAPS`（诚实标注，绝不谎报）
+
+harness-kit 把这些沉淀进 manifest，再确定性地生成与校验。
+
+---
+
+## 工作原理
 
 ```
-.agents/manifest.yaml   (你 + agent 维护的唯一源)
-        |
+.agents/manifest.yaml   (你 + Agent 维护的唯一源)
+        │
    harness-kit sync     (确定性生成，勿手改产物)
-        v
+        ▼
 AGENTS.md / CLAUDE.md / .cursor/rules / .agents/routing.md / .agents/modules.md
-        |
-   harness-kit verify   (门禁：不变量 enforcement + 契约 snapshot + 生成物/知识漂移)
-        v
-   exit 0 / 非 0  +  诚实的 GAPS 清单（查不了的东西绝不谎报）
+        │
+   harness-kit verify   (门禁：不变量 + 契约 + 漂移)
+        ▼
+   exit 0 / 非 0  +  诚实的 GAPS 清单
 ```
 
-- **不变量**：声明式正则 `enforcement`（确定性、无 LLM），或标 `manual`。
-- **契约**：协议无关——`check`（跑仓库自带工具看退出码）或 `snapshot`（打印接口指纹 → CLI 存基线并 diff）。
-- **新鲜度**：知识条目 / 模块卡 `binds` 源文件哈希，代码一动就告警，无需人肉维护日期。
-- **GAPS**：打包 / 真网络 / 生产上传等本地验证不了的，`verify` 显式列出，绝不假装通过。
+- **不变量**：声明式正则 `enforcement`（确定性、无 LLM），或标 `manual`
+- **契约**：`snapshot` 打印接口指纹 → CLI 存基线并 diff（协议无关）
+- **新鲜度**：知识条目 `binds` 源文件哈希，代码一动就告警
+- **GAPS**：打包 / 真网络 / 生产上传等本地验证不了的，显式列出
 
-## 让 agent 来配置：onboard skill
+---
 
-手写 manifest 门槛高，但对 agent 是绝配。随包附带的 [`skills/erzhe-harness-init`](skills/erzhe-harness-init/SKILL.md) 引导 agent 做仓库考古、逐块跟你确认着填 manifest、再跑 `sync/doctor/verify` 到绿。
+## 让 Agent 自动触发（可选）
 
-最省事的用法就是上面的 [最快上手](#最快上手推荐零安装)——`npx ... onboard` 把 skill 打印给 agent，零安装、永远最新。若想让某个 agent **自动触发**（不用每次点名），可选地把 skill 软链进它的 skill 目录：`ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.cursor/skills/`。
+上面的"最快上手"是**显式调用**——你每次说"onboard 本仓库"，Agent 才会做。如果你想让某个 Agent **自动识别**"该给仓库接 harness-kit"，可以把 skill 软链进它的 skill 目录：
 
-## 文档
+```bash
+# Cursor
+ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.cursor/skills/
 
-- [`SPEC-v0.md`](SPEC-v0.md) —— manifest schema + 生成/校验契约（当前 v0.2）
-- [`DESIGN.md`](DESIGN.md) —— 设计决策、调研与决策日志
+# Claude Code
+ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.claude/skills/
+```
+
+这样当用户说"给这个仓库配置 harness"时，Agent 会自动找到并执行这个 skill。
+
+---
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm typecheck
-pnpm test        # node:test + tsx，核心逻辑单测
-pnpm build       # esbuild 打包成 dist/harness-kit.cjs 单文件可执行
-pnpm exec tsx src/cli.ts verify --repo .   # 开发态直接跑，且自托管验证本仓
+pnpm typecheck          # tsc --noEmit
+pnpm test               # node:test + tsx
+pnpm build              # esbuild → dist/harness-kit.cjs
+pnpm exec tsx src/cli.ts verify --repo .   # 自托管验证
 ```
 
+## 文档
+
+- [`SPEC-v0.md`](SPEC-v0.md) — manifest schema + 生成/校验契约
+
 ## License
 
 MIT © [MeCKodo (二哲)](https://erzhe.me/)

package/dist/harness-kit.cjs

@@ -11883,41 +11883,41 @@ var require_queue = __commonJS({
       queue.drained = drained;
       return queue;
       function push(value) {
-        var p = new Promise(function(resolve2, reject) {
+        var p = new Promise(function(resolve3, reject) {
           pushCb(value, function(err2, result) {
             if (err2) {
               reject(err2);
               return;
             }
-            resolve2(result);
+            resolve3(result);
           });
         });
         p.catch(noop);
         return p;
       }
       function unshift(value) {
-        var p = new Promise(function(resolve2, reject) {
+        var p = new Promise(function(resolve3, reject) {
           unshiftCb(value, function(err2, result) {
             if (err2) {
               reject(err2);
               return;
             }
-            resolve2(result);
+            resolve3(result);
           });
         });
         p.catch(noop);
         return p;
       }
       function drained() {
-        var p = new Promise(function(resolve2) {
+        var p = new Promise(function(resolve3) {
           process.nextTick(function() {
             if (queue.idle()) {
-              resolve2();
+              resolve3();
             } else {
               var previousDrain = queue.drain;
               queue.drain = function() {
                 if (typeof previousDrain === "function") previousDrain();
-                resolve2();
+                resolve3();
                 queue.drain = previousDrain;
               };
             }
@@ -12403,9 +12403,9 @@ var require_stream3 = __commonJS({
         });
       }
       _getStat(filepath) {
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           this._stat(filepath, this._fsStatSettings, (error, stats) => {
-            return error === null ? resolve2(stats) : reject(error);
+            return error === null ? resolve3(stats) : reject(error);
           });
         });
       }
@@ -12429,10 +12429,10 @@ var require_async5 = __commonJS({
         this._readerStream = new stream_1.default(this._settings);
       }
       dynamic(root, options) {
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           this._walkAsync(root, options, (error, entries) => {
             if (error === null) {
-              resolve2(entries);
+              resolve3(entries);
             } else {
               reject(error);
             }
@@ -12442,10 +12442,10 @@ var require_async5 = __commonJS({
       async static(patterns, options) {
         const entries = [];
         const stream = this._readerStream.static(patterns, options);
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           stream.once("error", reject);
           stream.on("data", (entry) => entries.push(entry));
-          stream.once("end", () => resolve2(entries));
+          stream.once("end", () => resolve3(entries));
         });
       }
     };
@@ -16471,7 +16471,7 @@ function useColor() {
 var program = new Command();
 
 // src/cli.ts
-var import_node_path12 = require("node:path");
+var import_node_path13 = require("node:path");
 
 // src/commands/init.ts
 var import_node_fs3 = require("node:fs");
@@ -17164,14 +17164,87 @@ function acceptContractCmd(repo, id) {
   return problems ? 1 : 0;
 }
 
-// src/commands/onboard.ts
+// src/commands/install-hooks.ts
+var import_node_child_process4 = require("node:child_process");
 var import_node_fs7 = require("node:fs");
 var import_node_path11 = require("node:path");
+var MARK = "harness-kit-managed-hook";
+function hooksDir(repo) {
+  const out = (0, import_node_child_process4.execSync)("git rev-parse --git-path hooks", { cwd: repo, encoding: "utf8" }).trim();
+  return (0, import_node_path11.resolve)(repo, out);
+}
+function preCommit() {
+  return `#!/bin/sh
+# ${MARK} (pre-commit): regenerate agent files from the manifest and stage them,
+# so generated docs never drift from .agents/manifest.yaml.
+# Reset with \`harness-kit install-hooks --force\`; delete this file to remove.
+[ -f .agents/manifest.yaml ] || exit 0
+HK="\${HARNESS_KIT_CMD:-npx -y @erzhe/harness-kit@latest}"
+if ! $HK sync --repo . >/dev/null; then
+  echo "harness-kit: sync failed (run \\\`$HK sync\\\` to see why)" >&2
+  exit 1
+fi
+git add AGENTS.md CLAUDE.md .cursor/rules .agents >/dev/null 2>&1 || true
+exit 0
+`;
+}
+function prePush() {
+  return `#!/bin/sh
+# ${MARK} (pre-push): block the push when the agent context has drifted from code.
+# Bypass once with \`git push --no-verify\`.
+[ -f .agents/manifest.yaml ] || exit 0
+HK="\${HARNESS_KIT_CMD:-npx -y @erzhe/harness-kit@latest}"
+if ! $HK verify --repo .; then
+  echo "" >&2
+  echo "harness-kit: verify failed \u2014 agent context drifted from code." >&2
+  echo "  self-heal: run an agent with \\\`$HK onboard\\\` and follow its Maintenance section," >&2
+  echo "  then review the diff. Bypass once with \\\`git push --no-verify\\\`." >&2
+  exit 1
+fi
+exit 0
+`;
+}
+function installHooksCmd(repo, force = false) {
+  let dir;
+  try {
+    dir = hooksDir(repo);
+  } catch {
+    err("not a git repo (git rev-parse failed) \u2014 run inside a git working tree");
+    return 1;
+  }
+  const targets = [
+    ["pre-commit", preCommit()],
+    ["pre-push", prePush()]
+  ];
+  for (const [name, body] of targets) {
+    const p = (0, import_node_path11.join)(dir, name);
+    if ((0, import_node_fs7.existsSync)(p) && !force) {
+      const cur = (0, import_node_fs7.readFileSync)(p, "utf8");
+      if (!cur.includes(MARK)) {
+        warn(`${name} exists and isn't harness-kit-managed \u2014 skipped (use --force to overwrite)`);
+        continue;
+      }
+    }
+    writeText(p, body);
+    (0, import_node_fs7.chmodSync)(p, 493);
+    ok(`installed ${name}`);
+  }
+  info(`
+Hooks written to ${dir}`);
+  info("pre-commit: regenerates agent files from the manifest and stages them.");
+  info("pre-push:   runs `harness-kit verify` and blocks on drift (bypass: git push --no-verify).");
+  info("override the CLI it calls with env HARNESS_KIT_CMD (e.g. for local dev).");
+  return 0;
+}
+
+// src/commands/onboard.ts
+var import_node_fs8 = require("node:fs");
+var import_node_path12 = require("node:path");
 var import_node_url = require("node:url");
 var import_meta = {};
 function moduleDir() {
   if (typeof __dirname !== "undefined" && __dirname) return __dirname;
-  return (0, import_node_path11.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+  return (0, import_node_path12.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
 }
 var HERE = moduleDir();
 var SKILL_REL = "skills/erzhe-harness-init/SKILL.md";
@@ -17185,9 +17258,9 @@ Do not fabricate: confirm uncertain fields with the user, and report honest GAPS
 
 `;
 function resolveSkill() {
-  for (const up of ["..", (0, import_node_path11.join)("..", "..")]) {
-    const p = (0, import_node_path11.join)(HERE, up, SKILL_REL);
-    if ((0, import_node_fs7.existsSync)(p)) return p;
+  for (const up of ["..", (0, import_node_path12.join)("..", "..")]) {
+    const p = (0, import_node_path12.join)(HERE, up, SKILL_REL);
+    if ((0, import_node_fs8.existsSync)(p)) return p;
   }
   return null;
 }
@@ -17198,7 +17271,7 @@ function onboardCmd() {
     return 1;
   }
   process.stdout.write(META);
-  process.stdout.write((0, import_node_fs7.readFileSync)(p, "utf8"));
+  process.stdout.write((0, import_node_fs8.readFileSync)(p, "utf8"));
   return 0;
 }
 
@@ -17213,13 +17286,14 @@ function guard(fn) {
   }
 }
 var program2 = new Command();
-program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.1");
-var repoOf = (o) => (0, import_node_path12.resolve)(o.repo);
+program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.2");
+var repoOf = (o) => (0, import_node_path13.resolve)(o.repo);
 program2.command("init").description("scaffold .agents/ skeleton + starter manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--name <name>", "project name", "my-project").option("--force", "overwrite existing manifest", false).action((o) => guard(() => initCmd(repoOf(o), o.name, o.force)));
 program2.command("sync").description("generate tool files (AGENTS.md, CLAUDE.md, .cursor rules) from manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => syncCmd(repoOf(o))));
 program2.command("doctor").description("dev-time health check: completeness, drift, freshness, tech debt").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => doctorCmd(repoOf(o))));
 program2.command("verify").description("CI gate: run enforceable invariants + contracts + drift; nonzero on failure").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => verifyCmd(repoOf(o))));
 program2.command("accept-contract").description("record current contract fingerprint(s) as the accepted baseline (after an intended change)").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--id <id>", "only this contract (default: all with a snapshot command)").action((o) => guard(() => acceptContractCmd(repoOf(o), o.id)));
+program2.command("install-hooks").description("install git hooks: pre-commit auto-sync + pre-push verify (drift gate)").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--force", "overwrite existing hooks", false).action((o) => guard(() => installHooksCmd(repoOf(o), o.force)));
 program2.command("onboard").description("print the erzhe-harness-init skill for an agent to follow (use via npx, always latest)").action(() => guard(() => onboardCmd()));
 program2.parseAsync();
 /*! Bundled license information:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erzhe/harness-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "AI-friendly repo harness: a manifest.yaml single source of truth that generates AGENTS.md / CLAUDE.md / Cursor rules and enforces invariants, contracts and drift via `harness-kit verify`.",
   "keywords": [

package/skills/erzhe-harness-init/SKILL.md

@@ -66,7 +66,36 @@ harness-kit verify          # 门禁：跑不变量 + 契约 + 漂移，并列
 
 - `harness-kit verify` 退出码 0；`GAPS` 段里每一条都是**真的没法自动查**（打包 / 真网络 / 生产上传 / 人肉不变量），不是偷懒。
 - `AGENTS.md` 在体量预算内（`doctor` 第 6 项会报行数/词数）。
-- 把生成物 + `.agents/` + 契约基线一起提交；告诉用户：**以后改 manifest → `harness-kit sync`，别手改生成物**；把 `harness-kit verify` 挂进 CI / pre-commit 才能真正兑现"跨人跨机一致"。
+- 把生成物 + `.agents/` + 契约基线一起提交；告诉用户：**以后改 manifest → `harness-kit sync`，别手改生成物**。
+- 装上自动化门禁，让防腐烂不靠人自律：
+  ```
+  harness-kit install-hooks --repo .
+  ```
+  pre-commit 自动 sync 并暂存生成物、pre-push 跑 `verify` 拦漂移；团队再把 `harness-kit verify` 放进 CI，才能真正兑现"跨人跨机一致"。
+
+## 5. 日常维护 / 自愈（接入之后，长期靠这个防腐烂）
+
+harness-kit 的持续价值不在首次接入，而在**代码演进时上下文不腐烂**。机制是：门禁发现漂移 → agent 自动修 → 人只 review。**别把维护活丢回给人**——你（agent）来修，人只做最后一次审查。
+
+**触发**：`harness-kit verify` 非零，或 `doctor` 报 drift / 新鲜度告警（装了 pre-push hook 会在 push 时自动拦）。
+
+**自愈流程（你就是那个 agent，按此做）：**
+1. 跑 `harness-kit verify`，逐条读红灯——它已把"哪块过期 / 哪个契约变了 / 该 sync 还是该 accept"写清楚了。
+2. 逐条处理：
+   - **生成物 drift**（"AGENTS.md drifted, run sync"）→ 直接 `harness-kit sync`。
+   - **knowledge 新鲜度告警**（绑定的源文件变了）→ 重新读那个源文件，判断知识是否真过时；过时就改 `.agents/knowledge/*` 或对应 manifest 字段再 sync。**没实质变化就别乱改**。
+   - **契约 drift**（snapshot 变了）→ 看对应代码改动：确属**有意**改接口（有需求 / commit 佐证）才 `harness-kit accept-contract --id <id>`；拿不准是否 breaking 就**别 accept**，标给人。
+   - **invariant 违规** → 按规则修代码；确认该规则已过时才动 manifest。
+3. 全部处理完再 `verify` 到退出码 0。
+4. **产出一份变更清单交给人 review（这是唯一的人工动作）**，至少含：
+   - 改了哪些 manifest 字段 / knowledge 文件，为什么；
+   - accept 了哪些契约、对应什么代码改动、是否 breaking；
+   - 哪些**没动**及原因。
+
+**红线**：
+- 契约 accept 必须有据可依且**必写进给人的清单**——绝不静默 auto-accept 对外接口变更。
+- 拿不准就标 GAP 交人，别用幻觉填。
+- 只修真漂移，别为了凑绿去改无关内容。
 
 ## 反模式（别做）