@brightliu/ai-control 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrightLiu4917
+
+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,126 @@
+# ai-control
+
+**让 AI 编程助手在你的项目里守规矩的工具。**
+
+你在用 Cursor、Claude Code、Codex、通义 Qoder 这些 AI 写代码时，是不是遇到过：
+
+- AI **编造**了一个数据库里根本不存在的字段？
+- AI 说"测试通过了"，其实**根本没跑**测试？
+- AI **顺手执行**了一条危险 SQL，或者把不该动的表改了？
+- 想管住它，结果流程太重，改个文案也要走一堆步骤，最后**自己都不想守**？
+
+ai-control 就是治这四件事的：装进你的项目后，AI 会**先写变更单给你确认、动数据库前必须等你点头、测试结果以测试报告为准（说了不算）**——而改文案这类小事走 30 秒的快速通道，不折腾你。
+
+## 效果对比
+
+```text
+❌ 没装之前
+你：加个订单导出功能
+AI：好的！（编了个 status=5 的枚举值，顺手改了表结构，最后说"测试全部通过"）
+你：……上线炸了。
+
+✅ 装了之后
+你：加个订单导出功能
+AI：我先看了代码。这个需求要动 t_order 表，属于高风险变更。
+    这是变更单：改什么、动哪张表、验收标准是这 4 条测试用例。确认吗？
+你：确认
+AI：（实现 → 跑测试）测试报告 4 条全绿，ai ship 发布检查通过。表结构变更的回滚 SQL 在这里。
+```
+
+你全程只做两件事：**确认变更单、确认数据库改动**。其他检查（用例覆盖没覆盖、测试报告在不在、有没有失败）由内置的自动检查完成——它查的是测试框架生成的原始报告，AI 想蒙混就得伪造报告文件，成本高得多、也容易被发现。
+
+## 3 分钟上手
+
+```bash
+# 1. 装工具（一次性）
+npm install -g github:BrightLiu4917/ai-control
+
+# 2. 装进你的项目
+cd 你的项目
+ai init                  # 自动识别技术栈；也可指定 --stack java|go|php|vue|react|node|mixed
+ai sync                  # 只有用 Claude Code / WorkBuddy 才需要：为它们生成各自格式的配置文件
+
+# 3. 开始干活——两种用法任选
+```
+
+**用法 A（推荐）：在 AI 工具里说人话。** 直接提需求，AI 会自己执行下面这 5 个命令并替你补全变更单——你只负责在确认点点头。用法 B 是同一套流程的手动入口，两者随时混用。
+
+**用法 B：终端命令。** 一共 5 个：
+
+| 命令 | 干什么 | 人话 |
+|---|---|---|
+| `ai new 名字` | 生成变更单骨架（需求说明 + 验收用例两个文件，由 AI 补全内容、你来确认） | "我要开工了"（小事加 `--lite`） |
+| `ai check 名字` | 检查变更单写全没有 | "能给用户确认了吗" |
+| `ai confirm 名字` | **由你本人运行**，留下确认记录（谁、何时、哪个提交）；AI 代跑会被钩子拦下 | "我确认了"（ship 的前置） |
+| `ai test 名字` | 跑你项目自己的测试，报告自动按变更隔离存放 | "跑测试" |
+| `ai ship 名字` | 核对测试报告：确认过没有、报告新不新、全绿没有 | "能交付了吗"（秒级出结果） |
+
+## 它靠什么管住 AI（三层，由软到硬）
+
+1. **规矩**（`AGENTS.md` + `.ai/rules/`）：63 行契约每次对话自动生效 + 20 份中文工程规则按需加载——禁止编造字段、SQL 必须带 WHERE、枚举必须 code+desc 禁止魔法值、JOIN 不许先连后分页……**这些是踩过生产事故总结的具体规则，不是"请写好代码"式的空话**。
+2. **确认点**（必须等你点头的两处）：变更单确认之前 AI 不许写码——你点头后 `ai confirm` 会记下确认人/时间/提交号，之后变更单再被改动确认即失效；数据库改动确认之前 AI 不许执行 SQL。
+3. **自动检查**（内置在 check/confirm/ship 命令里的程序）：变更单声明动表却想走快速通道？拦。碰表/接口却全是手动用例？拦。没确认就想交付、或确认后偷改了变更单？拦。测试报告缺失、有失败、或比确认时间还旧（拿旧报告顶包）？拦。（数据库确认属于第 2 层——靠契约约束 AI 停下等你，ship 时会提示做独立审查，不是机械拦截。）
+
+## 支持哪些 AI 工具
+
+| 工具 | 需要做什么 |
+|---|---|
+| Codex / Cursor / Kimi Code / Qoder | **装完即用**（它们自动读 AGENTS.md） |
+| Claude Code | `ai sync` 一次——生成它专用的 CLAUDE.md、角色配置，以及 **PreToolUse 钩子**：未确认就写业务代码、写影响范围外的文件、执行危险 SQL，会在动手的一瞬间被拦下（其他工具是事后检查，Claude Code 是当场按住手） |
+| WorkBuddy（腾讯 AI 办公助手） | `ai sync` 写入项目级 `.workbuddy/skills/`，重启 WorkBuddy 即生效（无需复制）；不用它可忽略 |
+
+多语言混合项目（如 Java 后端 + Vue 前端）装一次即可：AI 按任务碰到的文件自动选对应规则；测试命令在 `.ai/config.json` 里配一条串联命令。
+
+## 装进项目后长什么样
+
+```text
+你的项目/
+├── AGENTS.md        规矩总纲——AI 工具自动读取
+└── .ai/             规则库、角色手册 + changes/（变更单记录，每个需求一个文件夹）
+```
+
+已有 AGENTS.md 的项目不会被覆盖；升级用 `ai init --update`（只更新框架文件，先自动备份，绝不碰你的变更记录）。
+
+## 高风险变更想要第二意见？
+
+`ai ship` 检测到动数据库/支付/状态流时会提示：新开一个 AI 会话，用 `.ai/templates/review-prompt.md` + git diff 让它做一次独立审查（审查者不能是写代码的那个会话）。零配置、零 API 费用。
+
+## 常见问题
+
+**Q：改个错别字也要走流程吗？**
+不用。纯文档/注释/typo 直接改；小功能走 `--lite`（两个文件、30 秒确认）；只有动数据库、接口、权限才走完整流程。管控力度和风险成正比。
+
+**Q：AI 不守规矩怎么办？**
+说一句"按控制系统流程来"即可拽回；关键环节（越级偷渡、报告缺失或有失败）有自动检查兜底。诚实说明边界：AI 理论上可以伪造报告文件绕过检查，门禁的作用是把"张嘴谎报"变成"必须留下可查的假证据"——成本和暴露风险完全不是一个量级。
+
+**Q：测试报告是什么格式？**
+JUnit XML——`ai test` 会按栈自动搞定：Maven 自带；Go 的输出自动转成报告（零配置，无需 gotestsum）；Vitest 自动注入内置 junit reporter；PHPUnit 自动加 `--log-junit`；仅 Jest 需要 `npm i -D jest-junit`（会提示）。测试方法名里带上用例编号（如 `test_TC01_xxx`）即可被核对。多变更并行时把报告输出到 `test-results/<变更名>/` 可互相隔离；报告必须比确认时间新——旧报告顶包会被拦下。
+
+## 被脚本 / Agent 调用？机器契约在这
+
+所有命令遵守统一约定，无需解析人类文案：**退出码** 0=通过、1=用法或环境错误、2=门禁拦截；**结果信号**固定为输出中的单行大写标记：`CHECK_PASSED` / `CONFIRM_OK` / `TEST_PASSED` / `SHIP_GATES_PASSED` / `DOCTOR_OK`（失败时为 `[FAIL] ...` 行 + 非零退出码）。这两样是稳定接口，不会随文案调整而变。
+
+## 团队用？把门禁挂到 PR 上
+
+个人用时门禁跑在本地；团队用时加一个 GitHub Action，PR 不合规直接挂红叉合不了：
+
+```yaml
+# .github/workflows/ai-gates.yml
+name: ai-gates
+on: pull_request
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: BrightLiu4917/ai-control@main          # 契约门禁（check）
+      # 需要证据门禁时：先跑你的测试产出 JUnit 报告，再加一步
+      # - uses: BrightLiu4917/ai-control@main
+      #   with: { mode: ship }
+```
+
+## 工程质量
+
+零运行时依赖（只需 Node ≥18.17 + git）；22 个端到端验收测试 + 8 个单元测试 + 规则库引用自检（防悬空引用）；代码量硬预算写进 CI（内核 ≤1500 行、契约 ≤100 行、文档 1 份），超支即红——防止工具本身变臃肿。
+
+前身 [ai-coding-fun](https://github.com/BrightLiu4917/ai-coding-fun)（v1）经 15 批真实项目迭代后彻底重构：5000 行 bash → 600 行 JS，五份文档的流程 → 两份，学习成本压缩到本 README 一页。

package/addons/export-adapters.js

@@ -0,0 +1,132 @@
+// ai sync：导出多工具适配物（Claude Code + WorkBuddy）。
+// Codex / Cursor / Kimi / Qoder 原生读 AGENTS.md，无需导出。
+// 幂等：已存在跳过；--force 覆盖。WorkBuddy 技能自包含（内嵌被引用的规则快照）。
+const fs = require("fs");
+const path = require("path");
+
+function sync(root, args) {
+  const force = args.includes("--force");
+  const ai = path.join(root, ".ai");
+  const agentsDir = path.join(ai, "agents");
+  const written = [];
+  const skipped = [];
+
+  function write(p, content) {
+    if (fs.existsSync(p) && !force) { skipped.push(path.relative(root, p)); return; }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    written.push(path.relative(root, p));
+  }
+
+  const sec = (s, title) => (s.match(new RegExp(`^## ${title}\\n([\\s\\S]*?)(?=^## |$(?![\\s\\S]))`, "m")) || [])[1]?.trim() || "";
+  const firstLine = (s) => (s.trim().split("\n")[0] || "").replace(/。$/, "") + "。";
+
+  const agentFiles = fs.readdirSync(agentsDir).filter((f) => f.startsWith("agent-") && f.endsWith(".md"));
+
+  // 1. .claude/settings.json：PreToolUse 钩子。项目可能已有自己的 settings.json——
+  // 只做 JSON 合并（缺哪条补哪条），绝不整文件覆盖用户的 permissions/其他 hooks；写后读回校验。
+  const hooksOk = mergeClaudeSettings(root, written, skipped);
+
+  // 2. CLAUDE.md（钩子状态按合并的实际结果措辞，不许说大话）
+  write(path.join(root, "CLAUDE.md"),
+`# 项目契约入口（Claude Code）
+
+@AGENTS.md
+
+- 角色手册已导出为 \`.claude/agents/\` 原生 subagent，匹配任务自动委派。
+- 变更流程可通过 \`.claude/skills/\` 技能触发。
+${hooksOk
+    ? "- PreToolUse 钩子已启用：未确认变更时写业务代码、写影响范围外文件、执行危险 SQL、代跑 ai confirm 会被当场拦截（临时停用：AI_CONTROL_HOOKS=off）。"
+    : "- 注意：PreToolUse 钩子未安装（.claude/settings.json 无法合并）；上述拦截不生效，仅靠契约约束。"}
+`);
+
+  // 2. .claude/agents/
+  for (const f of agentFiles) {
+    const content = fs.readFileSync(path.join(agentsDir, f), "utf8");
+    const id = f.replace(/\.md$/, "");
+    const role = (content.match(/^# ([^（\n]+)/) || [, id])[1].trim();
+    const duty = firstLine(sec(content, "职责"));
+    const desc = `${role}。${duty}涉及对应场景时必须主动使用（use proactively）。`.replace(/\n/g, " ");
+    write(path.join(root, ".claude", "agents", f), `---\nname: ${id}\ndescription: ${desc}\n---\n\n${content}`);
+  }
+
+  // 3. .claude/skills/
+  const skills = {
+    "new-feature": ["为新功能创建 change 骨架。用户说“加个XX”“帮我做XX”“改一下XX”等提出需求时使用；先影响探测判级（lite/完整）。",
+      "# 新功能流程\n\n1. 与用户确认 change-id（小写中横线）。\n2. 运行 `ai new <id>`（小需求 `--lite`）。\n3. 按产品规格工程师手册补全 proposal 与验收用例，答掉待确认问题。\n4. `ai check <id>` 通过后，输出带级别与判级理由的确认单，等用户确认。\n5. 把 `ai confirm <id>` 交给用户本人运行（AI 禁止代跑；ship 的前置）。\n"],
+    "ready-check": ["校验 change 是否可请求确认。用户说“检查一下”“可以确认了吗”时使用。",
+      "# 就绪校验\n\n运行 `ai check <id>`；失败逐项修复后重跑，通过后向用户输出确认单；把 `ai confirm <id>` 交给用户本人运行。\n"],
+    "release-ship": ["发布门禁。用户说“测一下”“能上线吗”“发布”时使用。",
+      "# 发布流程\n\n1. `ai test <change-id>` 跑测试（报告自动写入 test-results/<change-id>/，与其他变更隔离）。\n2. `ai ship <id>` 过证据门禁。\n3. 按 `.ai/rules/53-release.md` 清单过与本次变更相关的项。\n4. 高风险变更建议在新会话用 `.ai/templates/review-prompt.md` 做独立审查。\n"],
+  };
+  for (const [name, [desc, body]] of Object.entries(skills)) {
+    write(path.join(root, ".claude", "skills", name, "SKILL.md"), `---\nname: ${name}\ndescription: ${desc}\n---\n\n${body}`);
+  }
+
+  // 4. workbuddy-skills/（自包含：内嵌被引用的 rules 与 dev 栈手册快照）
+  const NOTE = "\n\n---\n\n# 附录：内嵌快照\n\n> 本技能自包含；框架更新后需重跑 `ai sync --force` （项目级技能就地生效）。\n> 正文中的命令仅在安装了控制系统的项目内可执行。\n\n";
+  const embed = (content) => {
+    const refs = [...new Set([...content.matchAll(/\.ai\/(rules\/[0-9A-Za-z._-]+\.md|agents\/dev\/[a-z]+\.md)/g)].map((m) => m[1]))];
+    const parts = refs
+      .map((r) => path.join(ai, r))
+      .filter((p) => fs.existsSync(p))
+      .map((p) => `## 规则快照：${path.relative(ai, p)}\n\n${fs.readFileSync(p, "utf8").trim()}\n`);
+    return parts.length ? content + NOTE + parts.join("\n") : content;
+  };
+
+  const contract = fs.readFileSync(path.join(root, "AGENTS.md"), "utf8");
+  write(path.join(root, ".workbuddy", "skills", "ai-control-contract", "SKILL.md"),
+    `---\nname: ai-control-contract\ndescription: AI 全栈控制系统总契约：红线、两个确认点、任务分级、验收契约。在装有本控制系统的项目内开发时必须先应用。\nversion: 2.0.0\ntags: contract, workflow, gates\n---\n\n${embed(contract)}`);
+  for (const f of agentFiles) {
+    const content = fs.readFileSync(path.join(agentsDir, f), "utf8");
+    const id = f.replace(/\.md$/, "");
+    const role = (content.match(/^# ([^（\n]+)/) || [, id])[1].trim();
+    const duty = firstLine(sec(content, "职责"));
+    write(path.join(root, ".workbuddy", "skills", id, "SKILL.md"),
+      `---\nname: ${id}\ndescription: ${role}。${duty}\nversion: 2.0.0\ntags: ai-control, ${id.replace("agent-", "")}\n---\n\n${embed(content)}`);
+  }
+
+  console.log(`SYNC_OK written=${written.length} skipped=${skipped.length}`);
+  written.forEach((p) => console.log(`  + ${p}`));
+  console.log("WorkBuddy：项目级技能已写入 .workbuddy/skills/，重启 WorkBuddy 生效（无需复制；若曾装过 v1 全局技能，请从 ~/.workbuddy/skills/ 删除 agent-architect/agent-release 等残留）。Codex/Cursor/Kimi/Qoder 原生读 AGENTS.md 无需操作。");
+}
+
+// 合并 PreToolUse 钩子进 .claude/settings.json：只追加缺失项，保留用户已有内容。
+// 返回“钩子确实已就位”（写后读回校验）；settings.json 非法 JSON 时不动它并返回 false。
+function mergeClaudeSettings(root, written, skipped) {
+  const p = path.join(root, ".claude", "settings.json");
+  const OURS = [
+    { matcher: "Write|Edit|MultiEdit|NotebookEdit",
+      hooks: [{ type: "command", command: "node .ai/hooks/guard-write.js" }] },
+    { matcher: "Bash",
+      hooks: [{ type: "command", command: "node .ai/hooks/guard-bash.js" }] },
+  ];
+  let obj = {};
+  if (fs.existsSync(p)) {
+    try { obj = JSON.parse(fs.readFileSync(p, "utf8")); }
+    catch {
+      console.error("警告：.claude/settings.json 不是合法 JSON，已跳过 hooks 注入（未改动该文件）。");
+      return false;
+    }
+  }
+  obj.hooks = obj.hooks || {};
+  obj.hooks.PreToolUse = obj.hooks.PreToolUse || [];
+  const have = JSON.stringify(obj.hooks.PreToolUse);
+  let added = 0;
+  for (const entry of OURS) {
+    if (!have.includes(entry.hooks[0].command)) { obj.hooks.PreToolUse.push(entry); added++; }
+  }
+  if (added) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
+    written.push(path.relative(root, p) + `（合并 ${added} 条钩子，用户配置保留）`);
+  } else {
+    skipped.push(path.relative(root, p) + "（钩子已在）");
+  }
+  // 写后读回校验
+  try {
+    return JSON.stringify(JSON.parse(fs.readFileSync(p, "utf8"))).includes("guard-write.js");
+  } catch { return false; }
+}
+
+module.exports = { sync };

package/bin/ai.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// ai —— 控制系统统一入口（npm 全局命令）
+//
+//   ai init [--stack <java|go|php|vue|react|node|mixed>] [--update|--force]   安装/更新到当前项目
+//   ai new <id> [--lite|--upgrade]                          建变更骨架（lite 两件套）
+//   ai check <id>                                           契约门禁：影响范围/lite越界/用例覆盖/待确认
+//   ai confirm <id>                                         用户确认后留痕（by/at/sha），ship 的前置
+//   ai test [<id>]                                          跑项目测试（带 id 时报告按变更隔离）
+//   ai ship <id> [报告目录...]                               证据门禁：报告直查 + 高风险提示
+//   ai sync [--force]                                       导出 Claude/WorkBuddy 适配物
+//   ai doctor                                               环境体检
+
+const { die, requireProjectRoot, PKG_ROOT } = require("../lib/core");
+
+const [cmd, ...args] = process.argv.slice(2);
+
+switch (cmd) {
+  case "init":
+    require("../lib/init").init(args);
+    break;
+  case "new":
+    require("../lib/change").cmdNew(args);
+    break;
+  case "confirm":
+    require("../lib/gate").cmdConfirm(args);
+    break;
+  case "check":
+    require("../lib/gate").cmdCheck(args);
+    break;
+  case "test":
+    require("../lib/testrun").cmdTest(args);
+    break;
+  case "ship":
+    require("../lib/gate").cmdShip(args);
+    break;
+  case "sync":
+    require("../addons/export-adapters").sync(requireProjectRoot(), args);
+    break;
+  case "doctor":
+    require("../lib/doctor").cmdDoctor();
+    break;
+  case "version":
+  case "--version":
+  case "-v":
+    console.log(require(`${PKG_ROOT}/package.json`).version);
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined: {
+    const fs = require("fs");
+    const self = fs.readFileSync(__filename, "utf8");
+    console.log(self.split("\n").slice(1, 11).map((l) => l.replace(/^\/\/ ?/, "")).join("\n"));
+    break;
+  }
+  default:
+    die(`未知命令: ${cmd}（ai help 查看用法）`);
+}

package/lib/change.js

@@ -0,0 +1,62 @@
+// ai new：建变更骨架（lite 两件套 / 完整三件；--upgrade 平滑升级保留内容）
+const fs = require("fs");
+const path = require("path");
+const { requireProjectRoot, changeDir, die, exists, read, renderTemplate } = require("./core");
+
+function writeIfAbsent(p, content) {
+  if (exists(p)) {
+    console.log(`已存在，跳过: ${p}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+  console.log(`[WRITE] ${p}`);
+}
+
+function cmdNew(args) {
+  const id = args.find((a) => !a.startsWith("--"));
+  if (!id || !/^[a-z0-9][a-z0-9-]*$/.test(id)) die("用法: ai new <change-id>（小写中横线）[--lite|--upgrade]");
+  const root = requireProjectRoot();
+  const dir = changeDir(root, id);
+  const vars = { CHANGE_ID: id };
+
+  const lite = args.includes("--lite");
+  if (args.includes("--upgrade")) return upgrade(root, dir, id, vars);
+  writeIfAbsent(path.join(dir, "proposal.md"), renderTemplate(lite ? "proposal-lite.md" : "proposal.md", vars));
+  let casesTpl = renderTemplate("test-cases.md", vars);
+  if (lite) casesTpl = casesTpl.replace("| 单测 |", "| 手动 |"); // lite 常态是无自动化测试的小改动
+  writeIfAbsent(path.join(dir, "test-cases.md"), casesTpl);
+  if (!lite) {
+    writeIfAbsent(path.join(dir, "specs", id, "spec.md"), renderTemplate("spec.md", vars));
+  }
+
+  console.log("");
+  console.log("复制给 AI 助手：");
+  console.log(`请读取 .ai/changes/${id}${lite ? "（lite 变更）" : ""}。`);
+  if (lite) {
+    console.log("补全需求说明、影响文件和验收用例，答掉待确认问题。");
+    console.log(`本变更不涉及数据库和 API 契约；如发现需要涉及，停止并运行 ai new ${id} --upgrade 升级（保留已写内容），升级后重新请求确认。`);
+  } else {
+    console.log("先做影响探测（检索代码列出触碰的文件/表/接口），据此补全影响范围、规格场景和验收用例，答掉待确认问题。");
+    console.log("涉及数据库先走数据库工程师两阶段确认（.ai/agents/agent-dba.md）；涉及跨模块/接口兼容按模板补建 design.md。");
+  }
+  console.log("不要直接写代码；确认单需标注级别与判级理由，请用户确认后由用户本人运行 ai confirm " + id + "（AI 不代跑）。");
+}
+
+function upgrade(root, dir, id, vars) {
+  if (!exists(dir)) die(`change 不存在，无法升级: ${id}`);
+  const proposalPath = path.join(dir, "proposal.md");
+  if (exists(proposalPath)) {
+    const s = read(proposalPath);
+    if (/^变更级别:\s*lite\s*\n?/m.test(s)) {
+      fs.writeFileSync(proposalPath, s.replace(/^变更级别:\s*lite\s*\n?/m, ""));
+      console.log("已移除 lite 标记。");
+    }
+  }
+  writeIfAbsent(path.join(dir, "specs", id, "spec.md"), renderTemplate("spec.md", vars));
+  console.log("已升级为完整流程：既有 proposal/test-cases 全部保留。");
+  console.log("注意：影响范围已变化，必须重新经用户确认（ai confirm）；涉及数据库先走两阶段确认。");
+  console.log("升级即意味着涉及数据库/API：请把关键用例改为自动化（非手动），否则 check 会拦——全手动会让证据门禁失效。");
+}
+
+module.exports = { cmdNew };

package/lib/core.js

@@ -0,0 +1,94 @@
+// 公共函数：项目根定位、change 目录、YAML 段解析
+const fs = require("fs");
+const path = require("path");
+
+const PKG_ROOT = path.join(__dirname, "..");
+const PAYLOAD = path.join(PKG_ROOT, "payload");
+
+// 从 cwd 向上找 .ai/ 定位项目根
+function findProjectRoot(from = process.cwd()) {
+  let dir = from;
+  while (true) {
+    if (fs.existsSync(path.join(dir, ".ai"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function requireProjectRoot() {
+  const root = findProjectRoot();
+  if (!root) die("当前目录不在已安装项目内（未找到 .ai/）。先运行: ai init --stack <java|vue|react|go|php>");
+  return root;
+}
+
+function changeDir(root, id) {
+  return path.join(root, ".ai", "changes", id);
+}
+
+// 读取 .ai/config.json（缺失或解析失败返回空对象）
+function loadConfig(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, ".ai", "config.json"), "utf8"));
+  } catch { return {}; }
+}
+
+function die(msg, code = 1) {
+  console.error(`[FAIL] ${msg}`);
+  process.exit(code);
+}
+
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function exists(p) {
+  return fs.existsSync(p);
+}
+
+// 解析 proposal 影响范围里某个 key 的条目；返回非 none 的条目数组。
+// 兼容两种 YAML 写法：行内标量（key: none / key: t_order）与块列表（key:\n  - xxx）。
+// "无内容"的写法宽容匹配：none/None/无/暂无/N/A（P1-1：格式误伤会不断制造假失败）
+const NONE_RE = /^[-~]?$|^(none|无|暂无|n\/a)$/i;
+function scopeItems(proposalText, key) {
+  const re = new RegExp(`^[ \\t]*${key}:[ \\t]*([^\\n]*)\\n?((?:[ \\t]*-[ \\t]*[^\\n]*\\n?)*)`, "m");
+  const m = proposalText.match(re);
+  if (!m) return null; // 字段缺失
+  const items = [];
+  if (m[1] && m[1].trim()) items.push(m[1].trim());
+  for (const l of (m[2] || "").split("\n")) {
+    const v = l.replace(/^[ \t]*-[ \t]*/, "").trim();
+    if (v) items.push(v);
+  }
+  return items.filter((v) => !NONE_RE.test(v.replace(/[`'"]/g, "").trim()));
+}
+
+function isLite(proposalText) {
+  return /^变更级别:\s*lite/m.test(proposalText);
+}
+
+// 渲染模板：{{KEY}} 替换
+function renderTemplate(name, vars) {
+  let s = read(path.join(PAYLOAD, "templates", name));
+  for (const [k, v] of Object.entries(vars)) {
+    s = s.split(`{{${k}}}`).join(v);
+  }
+  return s;
+}
+
+// 递归拷贝目录
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+module.exports = {
+  PKG_ROOT, PAYLOAD,
+  findProjectRoot, requireProjectRoot, changeDir, loadConfig,
+  die, read, exists, scopeItems, isLite, renderTemplate, copyDir,
+};

package/lib/doctor.js

@@ -0,0 +1,68 @@
+// ai doctor：环境与安装体检。原则"信任但验证"——sync 说装好了不算数，逐项实测。
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { findProjectRoot, loadConfig, exists } = require("./core");
+
+function cmdDoctor() {
+  const ok = (b, label, fix) => console.log(`${b ? "OK  " : "FAIL"} ${label}${b || !fix ? "" : `——${fix}`}`);
+  let bad = 0;
+  const check = (b, label, fix) => { ok(b, label, fix); if (!b) bad++; };
+
+  // 环境
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  check(maj > 18 || (maj === 18 && min >= 17), `node ${process.version}（需 ≥18.17）`, "升级 Node");
+  let hasGit = true;
+  try { execSync("command -v git", { stdio: "ignore", shell: true }); } catch { hasGit = false; }
+  check(hasGit, "git", "安装 git（confirm 留痕与独立审查需要）");
+
+  // 安装
+  const root = findProjectRoot();
+  if (!root) {
+    console.log("FAIL 未安装（未找到 .ai/）——运行 ai init");
+    process.exit(1);
+  }
+  console.log(`OK   项目根: ${root}`);
+  const cfg = loadConfig(root);
+  check(exists(path.join(root, "AGENTS.md")), "AGENTS.md 契约", "ai init --update 恢复");
+  console.log(`OK   stack=${cfg.stack || "unknown"}  testCommand=${cfg.testCommand || "（自动探测）"}`);
+
+  // 钩子体检：文件在不在、settings.json 里是不是真挂上了（防"文案说启用、实际没装"）
+  const hookFiles = ["guard-write.js", "guard-bash.js"].every((f) => exists(path.join(root, ".ai", "hooks", f)));
+  check(hookFiles, ".ai/hooks/ 守卫脚本", "ai init --update 恢复");
+  const settingsPath = path.join(root, ".claude", "settings.json");
+  if (exists(settingsPath)) {
+    let wired = false, legal = true;
+    try { wired = JSON.stringify(JSON.parse(fs.readFileSync(settingsPath, "utf8"))).includes("guard-write.js"); }
+    catch { legal = false; }
+    check(legal, ".claude/settings.json 是合法 JSON", "修复语法后重跑 ai sync");
+    if (legal) check(wired, "PreToolUse 钩子已挂载（Claude Code 写入/执行瞬间拦截）", "运行 ai sync 合并钩子");
+  } else {
+    console.log("提示  未生成 Claude Code 适配（不用 Claude Code 可忽略；否则运行 ai sync）");
+  }
+
+  // 变更概览：确认状态与失效检测
+  const changesDir = path.join(root, ".ai", "changes");
+  const ids = exists(changesDir)
+    ? fs.readdirSync(changesDir).filter((d) => { try { return fs.statSync(path.join(changesDir, d)).isDirectory(); } catch { return false; } })
+    : [];
+  let confirmed = 0, stale = 0;
+  for (const id of ids) {
+    const cp = path.join(changesDir, id, "confirmed.json");
+    if (!exists(cp)) continue;
+    confirmed++;
+    try {
+      const at = Date.parse(JSON.parse(fs.readFileSync(cp, "utf8")).at) || 0;
+      for (const f of ["proposal.md", "test-cases.md"]) {
+        const p = path.join(changesDir, id, f);
+        if (exists(p) && fs.statSync(p).mtimeMs > at) { stale++; console.log(`FAIL 变更 ${id}: 确认后 ${f} 被修改——确认已失效，需重新 ai confirm`); bad++; break; }
+      }
+    } catch { console.log(`FAIL 变更 ${id}: confirmed.json 无效`); bad++; }
+  }
+  console.log(`OK   变更: ${ids.length} 个（已确认 ${confirmed}，确认失效 ${stale}）`);
+
+  console.log(bad ? `\nDOCTOR_FAIL：${bad} 项需处理。` : "\nDOCTOR_OK：全部体检通过。");
+  if (bad) process.exit(1);
+}
+
+module.exports = { cmdDoctor };