harness-tool

把 agent-first 工程层一键装进新项目的 CLI —— init 在任意目录铺好 AGENTS / 系统地图 / 治理文档骨架，upgrade 给老项目补齐模板后来新增的机制，doctor 负责确认它真的就绪；技能等能力按需从评测仓库安装。

v0.1.0 · Node ≥ 20 · MIT · 零运行时依赖 · 工具中立（DSH / Claude Code / Cursor / Codex 通用）

✨ 特性

| | 特性 | 说明 | |---|---|---| | ⚡ | 一条命令铺层 | harness-tool init my-app：模板快照合并进目标目录；配合 --stack 可先搭代码脚手架 | | 🏗 | 代码脚手架可选 | --stack react-ts：先用 create-vite 搭好 app，再合并 harness 层（两者不冲突） | | 🧩 | 能力按需安装 | harness-tool add <name>：默认从 harness-lab 的 adopted/ 按名字找（类型自动识别），装进项目；也可用 skills install / agents install / mcp add 从任意源装 | | 🛡 | 绝不覆盖 | 只新增；已存在文件一律跳过并列出冲突，你的文件永远安全 | | ♻️ | 老项目能补机制 | harness-tool upgrade：把模板后来新增的自进化机制（lessons 台账 / verify 守卫 / CI 门禁）补进已有项目——同样只新增，改过的文件只报告不覆盖 | | 🤖 | AI 交接 | 装完直接输出一段可复制的提示语，交给编码 agent 照仓库内文档继续落地 | | 🩺 | 就绪自检 | harness-tool doctor：关键文件 / 占位符 / 机械配置 / active plan / git，外加自进化健康度（台账用没用起来、门禁在不在） | | 🔧 | 零运行时依赖 | 纯 Node 实现；TypeScript + Vitest + ESLint 仅用于开发与测试 | | 🔄 | 模板源可同步 | 内置 template/ 快照源自 harness-template，发版前随源更新 |

🚀 快速开始

# 纯 harness 层
npx harness-tool init my-app
# 直接带前端脚手架（先 create-vite 再合并 harness 层）
npx harness-tool init my-app --stack react-ts
cd my-app
harness-tool doctor              # 自检（会提示还缺哪些文档/配置）
harness-tool add frontend-design # 按需装一个能力（默认从 harness-lab 拿）

已有项目（模板更新之前建的）想拿到新机制：

harness-tool upgrade .           # 补齐缺失的机制文件（只增不改）
harness-tool upgrade . --dry-run # 先看看会补什么
harness-tool upgrade . --diff    # 规则类文件（AGENTS.md 等）行级差异：照抄这几行完成合并

新建的机制文件会自动装上；AGENTS.md / docs/*.md 这类已存在且你改过的文件永不覆盖—— --diff 把"模板新增了哪几行"和"你独有哪几行"列出来，合并这几行即可（工具分不清哪句是你写的，所以不替你改）。

然后把 init 输出里那段话发给你的编码 agent（DSH / Claude Code / Cursor / Codex）， 它会按仓库内 AGENTS.md 与 docs/BOOTSTRAP.md 完成落地——你不需要手把手教它。

想叠前端栈？直接用 --stack（自动执行 npm create vite@latest 后再合并），或手动 npm create vite@latest . -- --template react-ts 后再 harness-tool init。 能力（技能 / 子代理 / MCP）不在模板里，用到什么按名字装什么——在项目目录里执行：

harness-tool add frontend-design            # 默认从 harness-lab 的 adopted/ 找
harness-tool add frontend-design --from .   # 换源时才需要 --from（本地路径 / owner/repo）

类型自动识别（SKILL.md → 技能，AGENT.md → 子代理，server.json → MCP 预设）；已采纳能力与试用证据都在 harness-lab。

📖 命令参考

| 命令 | 作用 | 退出码 | |------|------|--------| | harness-tool init [dir] [--git] [--stack <tpl>] | ①（--stack 时）先用 create-vite 搭脚手架 → ② 把模板快照合并进 dir（默认 .）：只新增不覆盖、冲突列出；--git 额外执行 git init -b main | 0=成功，1=错误 | | harness-tool upgrade [dir] [--dry-run] [--diff] | 给已有项目补机制：把模板里缺失的文件补进来（docs/lessons/、docs/EVALS.md、scripts/verify.mjs、.github/workflows/verify.yml 等）；只新增、绝不覆盖；内容与模板不同的文件只列出来等人工合并；--dry-run 只报告不写盘，--diff 打印行级差异（模板新增了哪几行 / 你独有哪几行），规则类文件照抄即可完成合并 | 0=成功，1=错误 | | harness-tool doctor [dir] | 自检目录是否具备可开工的 harness 工程层 | 0=可开工（无关键缺失），1=存在关键缺失 | | harness-tool add <name> [dir] [--from <源>] [--update] [--force] | 按名字装能力：默认从 harness-lab 找（先 adopted/ 再 candidates/），类型自动识别；技能 → .claude/skills/<name>/ 与 .cursor/skills/<name>/，子代理 → .claude/agents/<name>.md，MCP → 项目 .mcp.json | 0=成功，1=错误 | | harness-tool skills install <source> [dir] [--agents <list>] [--update] | 从源（本地路径 / owner/repo[:sub] / https URL）安装技能 → .claude/skills/<name>/（默认 claude,cursor）；--update 重拉覆盖 | 0=成功，1=错误 | | harness-tool agents install <source> [dir] [--tools <list>] [--update] | 从源安装子代理规格（AGENT.md）→ <tool>/agents/<name>.md；默认 claude | 0=成功，1=错误 | | harness-tool mcp add <name\|preset> [dir] [--command <cmd>] [--args "…"] [--url <url>] [--force] | 写入项目 .mcp.json；preset = 含 server.json 的目录/仓库路径；同名需 --force；不写真实密钥 | 0=成功，1=错误 | | harness-tool mcp list [dir] / mcp remove <name> [dir] | 列出 / 移除已配置的 MCP server | 0=成功，1=错误/未找到 |

doctor 检查维度：关键文件（critical）· 占位符是否已填 · 五件套 scripts / tsconfig · active plan · git · 自进化健康度（机制文件在不在位 / lessons 台账用没用起来 / 技术债清不清 / CI 门禁在不在）。 后四项都是警告，不影响退出码；机制文件缺失时会直接提示用 harness-tool upgrade 补。

🧩 它往项目里放了什么

my-app/
├── AGENTS.md          # Agent 开工流程 + 路由地图（含"规则要能被弄坏"的准入标准）
├── ARCHITECTURE.md    # 系统形态 / 领域地图 / 分层规则 / 工程约定
├── scripts/
│   └── verify.mjs     # 零成本验证回路：无 BOM / 文档引用落地 / 五件套
├── .github/workflows/
│   └── verify.yml     # 门禁：跑的就是 node scripts/verify.mjs
└── docs/              # 治理骨架 + 工程规范基线
    ├── BOOTSTRAP.md PLANS.md QUALITY_SCORE.md        # 落地清单 / 计划 / 质量
    ├── CODE_STANDARDS.md TESTING.md SECURITY.md CI_CD.md   # 规范基线（按实际栈改写）
    ├── FRONTEND.md MODULE_STRUCTURE.md DESIGN.md           # 前端栈契约 / 模块边界 / 界面约定
    ├── RELIABILITY.md REVIEW.md PRODUCT_SENSE.md MEMORY.md AGENT_TOOLING.md
    ├── EVALS.md                     # 轻量评测方法学（争议件的一次 A/B 判决）
    ├── HISTORY.md                   # 历史索引（空表起步）
    ├── lessons/                     # 教训台账：自进化的记忆（症状→诊断→验证→棘轮）
    ├── generated/                   # 机器产物与归档（不是事实来源）
    ├── design-docs/                 # 设计决策（含 core-beliefs.md 根信念）
    └── product-specs/ exec-plans/ references/

装的是"规则与治理骨架"，不是代码脚手架——package.json、src/ 等由你的技术栈脚手架负责，两者不冲突、互不覆盖。 模板也不带能力内容（技能 / 子代理 / MCP）：那些按需从 harness-lab 装，项目里只留安装副本。

🛠 工作原理

• 模板快照：template/ 是 harness-template 的版本化快照；init 递归合并、逐文件判断"已存在则跳过"。
• 补齐通道：快照式的 init 天然拿不到模板后来新增的文件，upgrade 负责这条路径——逐文件对比快照，缺的补、内容不同的一个字节都不动（那是项目自己的内容），只报告出来等人工合并。
• 验证闭环：doctor 把模板的纪律（文档填了没、机械配置装没装、计划建没建、自进化机制在不在）转成可执行检查——AI 干完活能自证"就绪"。
• 零成本自进化：模板带的 scripts/verify.mjs + docs/lessons/ + AGENTS.md 准入标准，构成"观测→诊断→验证→固化"的棘轮；重量级 A/B 评测仍然只在 harness-lab 做。

🔗 相关项目

| 仓库 | 关系 | |------|------| | harness-template（npm 模板源） | 本 CLI 内置快照的上游；模板与工具"同源、各自迭代" | | harness-lab（能力评测仓库） | 能力的唯一来源：已采纳的 adopted/、候选 candidates/，带来源与试用证据；用本 CLI 装进项目 |

本项目自身也用它自己的方法论治理（dogfood）：AGENTS 路由、BOOTSTRAP 清单、active plan 驱动。

🔄 模板自动同步与发布（GitHub Actions）

内置 template/ 是 harness-template 的版本化快照。为让模板更新尽快到达用户，本仓库配了自动流水线：

• 触发：每天 02:00 UTC 定时检查；也可在仓库 Actions → Run workflow 手动触发；
• 逻辑：对比上游 harness-template@main 最新 commit 与 template/.template-version；有更新则同步快照 → npm version patch → 过 typecheck / lint / test / build → 发布 npm → 打 vX.Y.Z tag；
• 前置：仓库需配置 npm 发布密钥（Actions secret NPM_TOKEN：npmjs 上 auki-zy 的 granular token，勾选 Read and write 与 Bypass 2FA）；
• 用户侧：新版本发布后，npx harness-tool / npm i -g harness-tool@latest 即拿到含最新模板的快照；已初始化项目不会被自动覆盖——想让老项目也拿到新机制，跑一次 harness-tool upgrade；
• 手动：本地 npm run sync:template 可随时同步（写入 template/.template-version）。

harness-template 更新
   ↓（Actions 每日/手动检查）
harness-tool 同步快照 + bump + 发布 npm vX.Y.Z
   ↓（用户 npx / npm i -g @latest）
新项目 init 时拿到最新模板；老项目 harness-tool upgrade 补齐机制

🧑‍💻 开发

git clone https://github.com/auki-zy/harness-tool.git
cd harness-tool
npm install            # 开发依赖（TypeScript/Vitest/ESLint）
npm run build          # 产出 dist/
npm run lint && npm test   # 质量门禁
npm link               # 本地体验：任意目录执行 harness-tool

| script | 作用 | |--------|------| | dev / start | 运行 CLI（需先 build） | | build / typecheck | tsc 产出 / 类型检查 | | lint / test | ESLint / Vitest（threads 池） |

🗺 仓库治理入口

• AGENTS.md：开工流程 + 路由地图（canonical 入口）
• ARCHITECTURE.md：系统形态与分层
• docs/BOOTSTRAP.md：开新项目落地清单
• 当前计划：docs/exec-plans/active/

反馈与想法：欢迎在 issues 提出。