@erzhe/harness-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MeCKodo (二哲)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @erzhe/harness-kit
+
+> AI-friendly repo harness —— 把工程知识变成 agent 可消费的**契约层**。
+
+一份 `.agents/manifest.yaml` 作为单一事实源，生成各家 agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用**门禁**保证不变量、对外契约和文档不漂移。让不同的人、不同的机器上的 agent，构建出**一模一样的范式**。
+
+> 包名 `@erzhe/harness-kit`，安装后命令行工具叫 **`harness-kit`**。
+
+## 为什么
+
+传统工程化（脚手架 / lint / CI）是**面向过去、面向人**的。Agent 需要的是显式、结构化、可机器消费的知识：这个仓库是什么、能跑什么、什么绝不能破、改动该看哪、哪些验证不了。`harness-kit` 把这些沉淀进 manifest，再确定性地生成与校验。
+
+## 安装
+
+```bash
+npm i -g @erzhe/harness-kit      # 或 pnpm add -g / 直接 npx @erzhe/harness-kit
+harness-kit --help
+```
+
+## 命令
+
+```
+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  # 一次预期的接口变更后，记录新的契约指纹为基线
+```
+
+## 心智模型
+
+```
+.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 清单（查不了的东西绝不谎报）
+```
+
+- **不变量**：声明式正则 `enforcement`（确定性、无 LLM），或标 `manual`。
+- **契约**：协议无关——`check`（跑仓库自带工具看退出码）或 `snapshot`（打印接口指纹 → CLI 存基线并 diff）。
+- **新鲜度**：知识条目 / 模块卡 `binds` 源文件哈希，代码一动就告警，无需人肉维护日期。
+- **GAPS**：打包 / 真网络 / 生产上传等本地验证不了的，`verify` 显式列出，绝不假装通过。
+
+## 让 agent 来配置：onboard skill
+
+手写 manifest 门槛高，但对 agent 是绝配。随包附带的 [`skills/erzhe-harness-init`](skills/erzhe-harness-init/SKILL.md) 引导 agent 做仓库考古、逐块跟你确认着填 manifest、再跑 `sync/doctor/verify` 到绿。把它软链到 `~/.cursor/skills/` 或 `~/.claude/skills/` 即可被发现。
+
+## 文档
+
+- [`SPEC-v0.md`](SPEC-v0.md) —— manifest schema + 生成/校验契约（当前 v0.2）
+- [`DESIGN.md`](DESIGN.md) —— 设计决策、调研与决策日志
+
+## 开发
+
+```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 .   # 开发态直接跑，且自托管验证本仓
+```
+
+## License
+
+MIT © [MeCKodo (二哲)](https://erzhe.me/)

package/SPEC-v0.md

@@ -0,0 +1,206 @@
+# AI-Harness SPEC v0.2
+
+> 一套 AI-friendly 的仓库规范。定义"任何仓库要让 Agent 冷启动即可高效工作、且人人构建出一致范式，必须声明什么、怎么声明、怎么防过期"。
+> 配套 CLI：`ai-harness`（`init` / `sync` / `doctor` / `verify`）。manifest 标签仍为 `ai-harness/v0`（v0 主线）。
+>
+> 设计背景与调研见 `DESIGN.md`。本文件是规范正文。
+>
+> **v0.2 相比 v0**：在"可执行内核"（生成 + 门禁 + 派生防腐烂）之上，叠加一层从竞品吸收来的**行为协议**——
+> Task Brief、按改动类型路由（§8）、模块卡（§9）、验证缺口 GAPS（§5）、知识沉淀触发与 adoption 节奏。
+> 切分原则：**能机器校验的做成数据驱动**（routing/modules/GAPS 都由 manifest 生成并被 `doctor`/`verify` 检查），
+> **纯 agent 运行时行为的留 prose**（写进生成的 `AGENTS.md` Working agreement）。
+
+---
+
+## 1. 目的与非目标
+
+**目的**：让一份 `.agents/manifest.yaml`（+ 少量叙述文件）成为"人和 Agent 共享的单一真相源"，由 CLI 派生出各家工具文件、并用可执行门禁保证一致性。
+
+**非目标（明确不做，避免变成又一个重工具）**：
+- **不是 spec-driven 工作流引擎**（不做 specify→plan→tasks 那套 per-feature 流程；那是 Spec Kit/Kiro 的活，可以骑在我们之上）。
+- **不是文档生成器**：只沉淀"Agent 无法自行发现"的信息；能被工具从代码里算出来的（模块列表、调用图），一律**生成**，不手写。
+- **反仪式**：宁可字段少、宁可留空，也不制造需要人肉长期维护的负担。
+
+---
+
+## 2. 目录布局
+
+```
+<repo>/
+  AGENTS.md                          # [生成] 跨工具入口，<100 行，指路
+  CLAUDE.md                          # [生成] 首行 @AGENTS.md
+  .cursor/rules/00-follow-agents.mdc # [生成] 薄适配器
+  .agents/                           # canonical 命名空间（唯一手写源）
+    manifest.yaml                    # 脊椎（本规范核心，见 §3）
+    knowledge/                       # 手写叙述：domain / conventions / journal
+      domain.md
+      conventions.md
+      journal/0001-*.md              # ADR：一决策一文件
+    routing.md                       # [生成] 按改动类型导航（见 §8）
+    modules.md                       # [生成] 模块卡（见 §9）
+    adoption.md                      # 手写：挣工具节奏账本（见 §5）
+    contracts/<id>.snapshot          # 已接受的契约基线，随仓入库（见 §5）
+    playbooks/                       # SKILL.md（可选，复用社区标准）
+    checks/                          # invariant 的可执行脚本（可选）
+    map/                             # [生成·暂缓/可选] 全量代码地图；核心地图需求已由 modules/routing 覆盖（见 §6）
+```
+
+所有 `[生成]` 文件顶部带 `# GENERATED by ai-harness — DO NOT EDIT`。
+
+---
+
+## 3. `manifest.yaml` Schema
+
+```yaml
+spec: ai-harness/v0                  # 规范版本
+
+# ── 1. Identity：这是什么 / 边界 / 上下游 ────────────────────
+identity:
+  name: string
+  summary: string                    # 一句话
+  scope_in:  [string]                # 明确"管什么"
+  scope_out: [string]                # 明确"不管什么"（防越界瞎改）
+  upstream:   [string]               # 依赖谁（服务 / 库 / 设计系统…）
+  downstream: [string]               # 谁依赖我
+
+# ── 2. Capabilities：机器可读、自描述命令 ───────────────────
+#   保留动词（可选、按需声明）：setup build test lint typecheck run verify
+#   也允许自定义键（e2e / release / docs / smoke …）
+capabilities:
+  <verb>:
+    run: string                      # 要执行的命令
+    desc?: string
+    example?: string                 # 特别用于 CLI：一个真实调用示例
+    background?: bool                # dev server 等长驻进程 = true
+    mutating?: bool                  # release/publish/deploy 等有副作用 → Agent 须先确认
+
+# ── 3. Environment：跑起来需要的配置（每个可运行仓库都要） ────
+environment:
+  - name: string                     # 如 API_BASE_URL / DATABASE_URL
+    desc?: string
+    required?: bool                  # 缺了跑不起来
+    secret?: bool                    # 密钥类，勿硬编码/勿入库
+
+# ── 4. Contracts：对外接口 = 契约（破坏需显式版本升级） ──────
+#   涵盖：库的 public API、CLI 的命令/flag、前后端 API schema…
+contracts:
+  - id: string
+    kind: public-api | cli-interface | http-api | event | other
+    desc: string
+    breaking_needs?: major | minor   # 破坏它至少需要哪级版本变更
+    check?: string                   # 能自动校验兼容性的命令（仓库自带工具，如 buf breaking / oasdiff / api-extractor），exit 0 = 兼容
+    snapshot?: string                # 打印契约当前指纹到 stdout 的命令；CLI 存基线并 diff（协议无关，见 §5）
+    manual_verify?: string           # 既无 check 也无 snapshot 时的人肉验证说明（进 GAPS，见 §5）
+
+# ── 5. Invariants：硬约束，优先声明式、可门禁 ────────────────
+invariants:
+  - id: string
+    rule: string                     # 人类可读约束
+    # 三选一执行方式（按此优先级）：
+    enforcement?:                     # (a) 声明式，确定性、无 LLM（借鉴 adr-kit）
+      forbid_pattern?: [string]
+      forbid_import?:  [string]
+      require_pattern?:[string]
+      path_glob?:      [string]      # 限定作用范围
+    check?: string                    # (b) 任意命令，exit 0 = pass
+    manual?: bool                     # (c) 无法机器验证 → 软约定，计入技术债
+    llm_judge?: bool                  # 复杂语义可 opt-in 让模型判
+
+# ── 6. Knowledge：指向叙述文件；新鲜度"派生"，不手写日期 ─────
+knowledge:
+  - path: string                     # .agents/knowledge/... 下的文件/目录
+    role: domain | conventions | journal | other
+    binds?: [string]                 # 它描述的源文件（用于算 drift）
+    #  freshness 由 CLI 从 git 与 binds 的 hash 派生，不要求人肉填 verified 日期
+
+# ── 8. Routing：按"改动类型"导航（生成 .agents/routing.md，v0.2） ──
+#   不列举需求，而是按"改动类型"告诉 Agent：先读哪、入口在哪、别假设什么、最少跑什么验证。
+routing:
+  - when: string                     # 改动类型，如 "修 bug" / "加 HTTP 接口" / "动数据源"
+    read?:        [string]           # 先读哪些文件/目录（repo-relative）
+    entry?:       [string]           # 入口点
+    dont_assume?: [string]           # 别假设什么（gotchas）
+    verify?:      [string]           # 最少验证：capability 动词，或带空格的原始命令
+    #  doctor 校验 read/entry 路径存在、verify 动词已在 capabilities 声明
+
+# ── 9. Modules：模块卡（生成 .agents/modules.md，v0.2） ──────────
+#   每模块固定：职责 / 入口 / 上下游 / 必须知道 / 常见错误。entry 自动参与新鲜度绑定。
+modules:
+  - name: string
+    role: string                     # 职责
+    entry: [string]                  # 入口文件（也用于 freshness：改了 → 模块卡告警）
+    upstream?:   [string]
+    downstream?: [string]
+    must_know?:  [string]            # Agent 必须知道
+    pitfalls?:   [string]            # 常见错误（最高价值的一栏）
+
+# ── 7. Playbooks：复用 SKILL.md（可选） ──────────────────────
+playbooks:
+  dir?: string                       # 默认 .agents/playbooks/
+
+# ── 生成映射：canonical → 各工具文件 ─────────────────────────
+generate:
+  - to: "AGENTS.md"                       render: "identity+capabilities+environment+invariants"
+  - to: "CLAUDE.md"                       content: "@AGENTS.md"
+  - to: ".cursor/rules/00-follow-agents.mdc"  template: "adapter"
+```
+
+**保留动词说明**：`capabilities` 的保留动词全部**可选**——它是一套"共享词汇表"，仓库只声明适用的子集（库通常没有 `run`；前端 `run` 是 dev server 且 `background: true`）。Agent 冷启动时能预期这些词的语义。
+
+---
+
+## 4. 生成契约（`sync`）
+
+- `manifest.yaml` + `.agents/**` 是唯一手写源。
+- `harness sync` 幂等地渲染出 `generate` 列出的所有工具文件，顶部写 DO-NOT-EDIT 头。
+- 生成文件不进人工编辑；要改就改 manifest 再 sync。
+
+## 5. 校验契约（`doctor` / `verify`）
+
+`harness doctor`（开发期体检，尽量确定性）：
+1. manifest 结构合法（对 schema）。
+2. 所有引用的 path / check 脚本 / binds 源文件**存在**。
+3. `capabilities` 命令可解析（可选 dry-run）。
+4. 生成物**无漂移**（re-render 到内存 vs 磁盘 diff）。
+5. 新鲜度：`knowledge.binds` 的源文件 hash 变了 → 报 drift；`invariants` 里 `manual:true` 的计入"待补门禁"技术债并给出数量。
+6. **AGENTS.md 体量预算**：生成的 `AGENTS.md` 超过 ~150 行 / ~700 词告警。渐进式披露——入口只指路，细节放 `.agents/` 按需加载，绝不让 Agent 读不完。
+
+`harness verify`（CI 门禁，全确定性）= 所有 `invariants` 的 `enforcement`/`check` + `contracts.check` + `capabilities.verify` + "生成物无漂移"。任一失败即 fail。
+
+**契约校验（v0.2，协议无关）**：契约的破坏检测有两条互补路径，CLI **不理解任何协议语义**，只当调度器 + 基线框架：
+- `check`：仓库自带的破坏检测工具（HTTP → `oasdiff`；gRPC/protobuf → `buf breaking`；库 → `api-extractor`；CLI → 自写脚本），exit 0 = 兼容。CLI 只 `execSync` 看退出码。
+- `snapshot`：仓库给一条**打印契约当前指纹到 stdout** 的命令（HTTP 打印 openapi / 抓路由；库打印 API 报告；CLI 打印 `--help`）。CLI 把 stdout 存成基线 `.agents/contracts/<id>.snapshot`，`verify` 时重新打印再 diff：一致=过，**漂移=fail**，无基线=提示先 `accept-contract`。这套 snapshot+baseline 与"生成物漂移检测"同一心智，复用于任何形态。
+- 有意变更契约时，显式跑 `harness accept-contract [--id <id>]` 更新基线——**与 `sync` 分开**，杜绝破坏被悄悄盖章。
+
+**GAPS 报告（v0.2）**：`verify` 末尾输出一段"这里查不了"的显式清单，把以下三类**从散落的 WARN 收拢成一等公民**：
+- `manual: true` 的 invariant（软约定，计技术债）；
+- 没有 `check` 的 contract（附 `manual_verify` 人肉验证说明）；
+- `mutating` / `background` 的 capability（有副作用/长驻，纯 CI 跑不了）。
+
+GAPS 不计入失败，但会打印数量（`verify: OK (N gap(s))`）。配套**铁律**（写进 `AGENTS.md` Working agreement）：**Agent 绝不许把 GAPS 里的项谎报成"已验证通过"**——查不了就如实说查不了。这直接治"把没跑的验证说成跑过了"。
+
+**行为协议（v0.2，纯 prose，生成进 `AGENTS.md`）**：
+- **Task Brief**：动手前先在对话里声明"改什么/属哪类/碰哪些层/怎么验证"，治"上来就全仓 grep + 瞎猜"。
+- **先路由后编辑**：改代码前先在 `routing.md` 里找到对应改动类型、按它指的文件读，别全仓搜。
+- **知识沉淀触发 + 反沉淀**：学到"代码里推不出来的"（坑/决策/修复）才沉淀到 `knowledge/`（决策走 journal ADR）；一次性噪音、代码里显而易见的，**不要沉淀**。
+- **adoption 节奏**（`.agents/adoption.md`，手写账本）：默认用最轻的方案；同一错误漏 3 次以上、或一个软约定用满一周确实值得，才把它升级成 `verify` 的机器门禁。反仪式，"挣来"更重的工具。
+
+## 6. 防腐烂（anti-rot）
+
+- **结构地图（暂缓 / 可选）**：核心"该看哪、别假设什么"已由 `modules`（模块卡，§9）+ `routing`（§8）用**高信噪比精选**覆盖。全量代码 dump（repomix `--compress`）不是必做项——它面向"喂给无文件访问的外部 LLM"，与 IDE agent 场景 + 渐进式披露原则不对口，且腐烂最快。真需要时**按需生成、不入库**（放 .gitignore），不当 CI/hook 固定产物。见 DESIGN 决策日志（2026-07-03）。
+- **新鲜度派生、不手写**：知识条目通过 `binds` 绑定源文件，CLI 存其内容 hash；源文件变化 → reliability 下降 → drift 告警。**不要求人肉维护 `verified` 日期**（那是 ceremony）。
+- **两档 guardian**：
+  - 便宜档（`doctor`，可每日/每次会话跑，确定性）：drift、过期候选、`manual` 技术债。
+  - LLM 档（可选、偶发、须先确认花费）：找缺失的知识/ADR、语义审计。
+
+## 7. CLI 命令面
+
+| 命令 | 作用 |
+| --- | --- |
+| `harness init` | 往当前 repo 注入 `.agents/` 骨架 + 交互式填 manifest 关键字段 |
+| `harness sync` | manifest → 生成各工具文件（幂等，带 DO-NOT-EDIT 头） |
+| `harness doctor` | 开发期体检：完整性 + 漂移 + 新鲜度 + 技术债 |
+| `harness verify` | CI 门禁：跑全部可执行 checks，任一失败即 fail |
+| `harness accept-contract [--id]` | 把当前契约指纹记为已接受基线（有意变更后显式跑，与 sync 分开） |
+
+（未来：`harness map` 生成代码地图、`harness new-adr` 起草决策记录。）