@brightliu/ai-control 2.1.0

package/lib/gate.js

@@ -0,0 +1,193 @@
+// gate：check（结构与契约门禁）、confirm（确认留痕）与 ship（证据门禁）
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { requireProjectRoot, changeDir, loadConfig, die, read, exists, scopeItems, isLite } = require("./core");
+const { parseReports, findReportDirs } = require("./junit");
+
+const SCOPE_KEYS = ["affected_files", "affected_tables", "affected_apis", "affected_pages"];
+
+// 覆盖闭环关键词：内置中英双语，可在 .ai/config.json 的 gateKeywords 覆盖（P2-6）
+const DEFAULT_KEYWORDS = {
+  exception: ["异常流", "异常", "exception", "invalid"],
+  permission: ["权限", "permission", "unauthorized"],
+  emptyOrError: ["空态", "错误态", "empty", "error"],
+};
+const MANUAL_RE = /手动|manual/i;
+
+function collect(dir) {
+  const proposal = path.join(dir, "proposal.md");
+  const cases = path.join(dir, "test-cases.md");
+  if (!exists(proposal)) die("缺少 proposal.md");
+  if (!exists(cases)) die("缺少 test-cases.md；验收用例必须在设计阶段产出并随 change 确认");
+  return { proposalText: read(proposal), casesText: read(cases) };
+}
+
+function tcRows(casesText) {
+  return casesText.split("\n").filter((l) => /^\|\s*TC-/i.test(l));
+}
+
+function requireChange(args, usage) {
+  const id = args.find((a) => !a.startsWith("--"));
+  if (!id) die(usage);
+  const root = requireProjectRoot();
+  const dir = changeDir(root, id);
+  if (!exists(dir)) die(`change 不存在: ${id}`);
+  return { id, root, dir };
+}
+
+// ── check 核心（cmdCheck 与 cmdConfirm 共用）──────────────
+function runCheck(root, dir, id) {
+  const { proposalText, casesText } = collect(dir);
+  const cfg = loadConfig(root);
+  const kw = (name) => (cfg.gateKeywords && cfg.gateKeywords[name]) || DEFAULT_KEYWORDS[name];
+  const hasKw = (name) => kw(name).some((k) => casesText.toLowerCase().includes(k.toLowerCase()));
+  const errors = [];
+
+  // 影响范围字段齐全
+  for (const k of SCOPE_KEYS) {
+    if (scopeItems(proposalText, k) === null) errors.push(`影响范围缺少字段: ${k}`);
+  }
+  const tables = scopeItems(proposalText, "affected_tables") || [];
+  const apis = scopeItems(proposalText, "affected_apis") || [];
+  const pages = scopeItems(proposalText, "affected_pages") || [];
+
+  // lite 越界门禁
+  if (isLite(proposalText)) {
+    if (tables.length) errors.push(`lite 变更不允许涉及数据库表；运行 ai new ${id} --upgrade 升级为完整流程（保留已写内容）`);
+    if (apis.length) errors.push(`lite 变更不允许涉及 API 契约；运行 ai new ${id} --upgrade 升级为完整流程（保留已写内容）`);
+  }
+
+  // 用例存在与覆盖闭环
+  const rows = tcRows(casesText);
+  if (rows.length === 0) errors.push("test-cases.md 没有任何用例行（用例ID 须以 TC- 开头）");
+  if (apis.length && !hasKw("exception"))
+    errors.push("affected_apis 非 none：必须包含异常流用例（参数错误、数据不存在、状态不允许）");
+  if (pages.length) {
+    if (!hasKw("permission")) errors.push("affected_pages 非 none：必须包含权限用例");
+    if (!hasKw("emptyOrError")) errors.push("affected_pages 非 none：必须包含空态或错误态用例");
+  }
+  // P0-1：高风险变更（碰表/接口）必须有自动化用例，否则证据门禁会因"全手动豁免"而失效
+  if ((tables.length || apis.length) && rows.length && rows.every((r) => MANUAL_RE.test(r))) {
+    errors.push("涉及数据库/API 的变更必须至少 1 条非手动（自动化）用例——发布门禁凭 JUnit 报告验收，全手动会让证据链失效");
+  }
+
+  // 待确认门禁：只查"## 待确认问题"章节内的未答条目（不全文扫字样）
+  for (const f of fs.readdirSync(dir, { recursive: true })) {
+    const p = path.join(dir, String(f));
+    if (!p.endsWith(".md") || !fs.statSync(p).isFile()) continue;
+    for (const item of unresolvedItems(read(p))) {
+      errors.push(`待确认问题未答（${path.basename(p)}）: ${item}`);
+    }
+  }
+  return errors;
+}
+
+function unresolvedItems(text) {
+  const m = text.match(/^## 待确认问题\n([\s\S]*?)(?=^## |$(?![\s\S]))/m);
+  if (!m) return [];
+  return m[1]
+    .split("\n")
+    .filter((l) => /^\s*-\s*\S/.test(l))
+    .map((l) => l.replace(/^\s*-\s*/, "").trim())
+    .filter((v) => !/已确认|已解决|无待确认|暂无|（没有则写/.test(v));
+}
+
+function cmdCheck(args) {
+  const { id, root, dir } = requireChange(args, "用法: ai check <change-id>");
+  const errors = runCheck(root, dir, id);
+  if (errors.length) {
+    errors.forEach((e) => console.error(`[FAIL] ${e}`));
+    die(`check 未通过（${errors.length} 项）`, 2);
+  }
+  console.log("CHECK_PASSED：可向用户输出确认单（标注级别与判级理由）。");
+}
+
+// ── ai confirm：把"用户点头"变成可审计留痕（by/at/sha）────
+function cmdConfirm(args) {
+  const { id, root, dir } = requireChange(args, "用法: ai confirm <change-id>（用户确认变更单后执行）");
+  const errors = runCheck(root, dir, id);
+  if (errors.length) {
+    errors.forEach((e) => console.error(`[FAIL] ${e}`));
+    die("check 未通过，禁止确认；修复后重试", 2);
+  }
+  const git = (cmd) => { try { return execSync(cmd, { cwd: root, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; } };
+  const record = {
+    by: git("git config user.name") || process.env.USER || "unknown",
+    at: new Date().toISOString(),
+    sha: git("git rev-parse HEAD"),
+  };
+  fs.writeFileSync(path.join(dir, "confirmed.json"), JSON.stringify(record, null, 2) + "\n");
+  console.log(`CONFIRM_OK：已留痕（by=${record.by}）。开始实现；proposal/test-cases 再改动需重新确认。`);
+}
+
+// 读取确认留痕；proposal/test-cases/specs 在确认后被改动 → 确认失效
+function requireFreshConfirm(dir, id) {
+  const confPath = path.join(dir, "confirmed.json");
+  if (!exists(confPath)) die(`变更未确认：向用户输出确认单，用户点头后运行 ai confirm ${id}`, 2);
+  let confAt = 0;
+  try { confAt = Date.parse(JSON.parse(read(confPath)).at) || 0; } catch { /* 落入下方校验 */ }
+  if (!confAt) die("confirmed.json 无效；重新运行 ai confirm", 2);
+  for (const f of fs.readdirSync(dir, { recursive: true })) {
+    const rel = String(f);
+    const p = path.join(dir, rel);
+    const base = path.basename(rel);
+    const isContract = base === "proposal.md" || base === "test-cases.md" || rel.startsWith("specs");
+    if (!isContract || !p.endsWith(".md") || !fs.statSync(p).isFile()) continue;
+    if (fs.statSync(p).mtimeMs > confAt) {
+      die(`确认已过期：${rel} 在确认后被修改；重新向用户确认并运行 ai confirm ${id}`, 2);
+    }
+  }
+  return confAt;
+}
+
+// ── ai ship ──────────────────────────────────────────────
+function cmdShip(args) {
+  const { id, root, dir } = requireChange(args, "用法: ai ship <change-id> [junit-报告目录...]");
+  const { proposalText, casesText } = collect(dir);
+  const confAt = requireFreshConfirm(dir, id);
+  const rows = tcRows(casesText);
+  const autoRows = rows.filter((l) => !MANUAL_RE.test(l));
+
+  if (autoRows.length === 0) {
+    console.log("全部用例为手动验证：跳过 JUnit 报告核对，验收结果须逐条写入交付说明。");
+  } else {
+    const extraDirs = args.filter((a) => !a.startsWith("--") && a !== id);
+    // N-3 串号收口：存在多个变更时，全局报告目录无法证明"这是本变更的证据"——
+    // 必须用隔离目录（ai test <id> 自动生成）或显式传入报告路径
+    const scoped = path.join(root, "test-results", id);
+    const allChanges = fs.readdirSync(path.join(root, ".ai", "changes"))
+      .filter((d) => { try { return fs.statSync(path.join(root, ".ai", "changes", d)).isDirectory(); } catch { return false; } });
+    if (!extraDirs.length && !exists(scoped) && allChanges.length > 1) {
+      die(`存在多个变更（${allChanges.join(", ")}）：证据必须按变更隔离。运行 ai test ${id}（报告自动写入 test-results/${id}/），或显式传入报告目录`, 2);
+    }
+    const reportDirs = extraDirs.length ? extraDirs : findReportDirs(root, id);
+    if (!reportDirs.length) die(`未找到 JUnit 报告目录；请先运行 ai test ${id}`, 2);
+    const { parsed, failures, passedIds, newestMtime } = parseReports(reportDirs);
+    if (!parsed) die("报告目录中没有可解析的 JUnit XML", 2);
+    // P0-2：报告必须晚于确认时间——旧迭代/别的变更的残留报告不算证据
+    if (newestMtime < confAt) die("测试报告早于本变更的确认时间——疑似旧报告；重跑 ai test 后再 ship", 2);
+    const missing = autoRows
+      .map((l) => l.split("|")[1].trim())
+      .filter((tc) => {
+        const n = parseInt(tc.replace(/^TC[-_]?0*/i, ""), 10);
+        return !passedIds.has(n);
+      });
+    failures.forEach((f) => console.error(`FAILED_TEST: ${f}`));
+    missing.forEach((c) => console.error(`MISSING_CASE: ${c}`));
+    if (failures.length) die("存在失败的测试；修复后重跑（报告即证据）", 2);
+    if (missing.length) die("以上非手动用例在报告中没有通过记录（测试名须含 TC-ID）", 2);
+    console.log(`EVIDENCE_OK：报告 ${parsed} 份，非手动用例 ${autoRows.length} 条全部有通过记录。`);
+  }
+
+  // 高风险提示（结构化判定，防 v1 的 grep 越界误报）
+  if ((scopeItems(proposalText, "affected_tables") || []).length) {
+    console.log("提示：本变更涉及数据库，建议在新会话用 .ai/templates/review-prompt.md 做一次独立审查。");
+  } else if (/支付|状态流转/.test(proposalText.split("## 待确认问题")[0])) {
+    console.log("提示：本变更涉及支付/状态流，建议在新会话用 .ai/templates/review-prompt.md 做一次独立审查。");
+  }
+
+  console.log("SHIP_GATES_PASSED：门禁全部通过。手动用例结果与残余风险写入交付说明。");
+}
+
+module.exports = { cmdCheck, cmdConfirm, cmdShip };

package/lib/init.js

@@ -0,0 +1,88 @@
+// ai init：把 payload 资产装进目标项目；--update 只更新框架文件（先备份，不碰用户数据）
+const fs = require("fs");
+const path = require("path");
+const { PAYLOAD, die, exists, copyDir } = require("./core");
+
+const FRAMEWORK_DIRS = ["agents", "rules", "templates", "hooks"]; // .ai/ 下属于框架的部分
+const STACKS = ["java", "go", "php", "vue", "react", "node", "mixed"];
+
+function init(args) {
+  const root = process.cwd();
+  const update = args.includes("--update");
+  const force = args.includes("--force");
+  const stackIdx = args.indexOf("--stack");
+  const stack = stackIdx >= 0 ? args[stackIdx + 1] : detectStack(root);
+  if (stackIdx >= 0 && !STACKS.includes(stack)) {
+    die(`未知 stack "${stack || ""}"。可用值: ${STACKS.join(" | ")}（多语言混合项目用 mixed）`);
+  }
+
+  const agentsMd = path.join(root, "AGENTS.md");
+  const aiDir = path.join(root, ".ai");
+  const stampNow = () => new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+
+  if (!update) {
+    // 项目原有 AGENTS.md（未装过本系统）是常见情况：--force 备份后覆盖，避免与 --update 互踢死锁
+    if ((exists(agentsMd) || exists(aiDir)) && !force) {
+      if (exists(aiDir)) die("已安装（存在 .ai/）。升级框架用: ai init --update");
+      die("AGENTS.md 已存在（项目原有）。用 ai init --force 安装：原文件自动备份为 AGENTS.md.bak-<时间戳>，装完后请把原有内容手动合并回 AGENTS.md 尾部");
+    }
+    if (force && exists(agentsMd)) {
+      const bak = `AGENTS.md.bak-${stampNow()}`;
+      fs.copyFileSync(agentsMd, path.join(root, bak));
+      console.log(`原 AGENTS.md 已备份为 ${bak}，请安装后手动合并需要保留的内容。`);
+    }
+  } else {
+    if (!exists(aiDir)) die("未安装（缺 .ai/），--update 无从更新。全新安装用 ai init；项目已有自己的 AGENTS.md 时用 ai init --force（自动备份原文件）");
+    // 备份框架部分（用户数据 .ai/changes/、config.json 不动）
+    const stamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+    const backup = path.join(aiDir, "backup", `update-${stamp}`);
+    fs.mkdirSync(backup, { recursive: true });
+    for (const d of FRAMEWORK_DIRS) {
+      const src = path.join(aiDir, d);
+      if (exists(src)) copyDir(src, path.join(backup, d));
+    }
+    if (exists(agentsMd)) fs.copyFileSync(agentsMd, path.join(backup, "AGENTS.md"));
+    console.log(`已备份到 .ai/backup/update-${stamp}/`);
+  }
+
+  // 拷贝框架资产
+  for (const d of FRAMEWORK_DIRS) {
+    copyDir(path.join(PAYLOAD, d), path.join(aiDir, d));
+  }
+  fs.copyFileSync(path.join(PAYLOAD, "AGENTS.md"), agentsMd);
+
+  // config：首装写入；update 保留已有
+  const cfgPath = path.join(aiDir, "config.json");
+  if (!exists(cfgPath)) {
+    fs.writeFileSync(cfgPath, JSON.stringify({ stack: stack || "unknown", testCommand: "" }, null, 2) + "\n");
+  }
+  fs.mkdirSync(path.join(root, ".ai", "changes"), { recursive: true });
+
+  // .gitignore 补 .ai/backup
+  const gi = path.join(root, ".gitignore");
+  const line = ".ai/backup/";
+  if (!exists(gi) || !fs.readFileSync(gi, "utf8").includes(line)) {
+    fs.appendFileSync(gi, `${line}\n`);
+  }
+
+  console.log(update ? "UPDATE_OK：框架已更新，用户数据未触碰（.ai/changes/、config.json）。"
+                     : `INIT_OK：已安装（stack=${stack || "unknown"}）。日常命令: ai new / check / confirm / test / ship`);
+}
+
+function detectStack(root) {
+  if (exists(path.join(root, "pom.xml"))) return "java";
+  if (exists(path.join(root, "go.mod"))) return "go";
+  if (exists(path.join(root, "composer.json"))) return "php";
+  if (exists(path.join(root, "package.json"))) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps.vue) return "vue";
+      if (deps.react) return "react";
+    } catch { /* 忽略解析失败 */ }
+    return "node";
+  }
+  return "";
+}
+
+module.exports = { init, detectStack };

package/lib/junit.js

@@ -0,0 +1,76 @@
+// JUnit XML 解析（零依赖，正则级；JUnit testcase 结构足够规整）
+const fs = require("fs");
+const path = require("path");
+
+const TC_RE = /TC[-_]?0*(\d+)/gi;
+
+function findReportDirs(root, changeId) {
+  // 按变更隔离的报告目录优先：存在则只用它，避免别的变更/上次迭代的旧报告串号（P0-2）
+  if (changeId) {
+    const scoped = path.join(root, "test-results", changeId);
+    if (fs.existsSync(scoped)) return [scoped];
+  }
+  return [
+    "target/surefire-reports",
+    "target/failsafe-reports",
+    "build/test-results",
+    "test-results",
+    "reports/junit",
+  ]
+    .map((d) => path.join(root, d))
+    .filter((d) => fs.existsSync(d));
+}
+
+function xmlFiles(dirs) {
+  const out = [];
+  for (const d of dirs) {
+    const st = fs.statSync(d);
+    if (st.isFile() && d.endsWith(".xml")) { out.push(d); continue; }
+    if (!st.isDirectory()) continue;
+    for (const f of fs.readdirSync(d, { recursive: true })) {
+      const p = path.join(d, String(f));
+      if (p.endsWith(".xml") && fs.statSync(p).isFile()) out.push(p);
+    }
+  }
+  return out;
+}
+
+// 返回 { parsed, failures, passedIds, newestMtime: 最新报告的修改时间(ms) }
+function parseReports(dirs) {
+  let parsed = 0;
+  let newestMtime = 0;
+  const failures = [];
+  const passedIds = new Set();
+
+  for (const file of xmlFiles(dirs)) {
+    const xml = fs.readFileSync(file, "utf8");
+    // 匹配自闭合与含子元素两种 testcase
+    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    let m, found = false;
+    while ((m = caseRe.exec(xml)) !== null) {
+      found = true;
+      const attrs = m[1] || "";
+      const inner = m[2] || "";
+      // 边界防护：name= 不能匹配到 classname= 内部（v1 grep 越界的同类坑）
+      const name = (attrs.match(/(?:^|[^a-zA-Z])name="([^"]*)"/) || [])[1] || "";
+      const cls = (attrs.match(/classname="([^"]*)"/) || [])[1] || "";
+      const failed = /<(failure|error)\b/.test(inner);
+      const skipped = /<skipped\b/.test(inner);
+      if (failed) failures.push(name || "?");
+      if (skipped) continue;
+      let t;
+      TC_RE.lastIndex = 0;
+      const hay = `${name} ${cls}`;
+      while ((t = TC_RE.exec(hay)) !== null) {
+        if (!failed) passedIds.add(parseInt(t[1], 10));
+      }
+    }
+    if (found) {
+      parsed++;
+      newestMtime = Math.max(newestMtime, fs.statSync(file).mtimeMs);
+    }
+  }
+  return { parsed, failures, passedIds, newestMtime };
+}
+
+module.exports = { findReportDirs, parseReports };

package/lib/testrun.js

@@ -0,0 +1,136 @@
+// ai test：跑项目测试（config.testCommand 优先，否则按栈自动探测）
+// 多栈 JUnit 自动注入（P1-2）：证据门禁靠 JUnit 报告，但只有 Maven 自带——
+// 其余栈在此自动补齐报告输出，统一落到 test-results/，用户零配置。
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { requireProjectRoot, loadConfig, die, exists } = require("./core");
+
+const OUT_DIR = "test-results";
+
+function cmdTest(args = []) {
+  const root = requireProjectRoot();
+  // ai test <id>：报告写入 test-results/<id>/，与其他变更隔离（ship 优先只认它）
+  const id = (args || []).find((a) => !a.startsWith("--")) || "";
+  if (id && !exists(path.join(root, ".ai", "changes", id))) die(`change 不存在: ${id}`);
+  const out = id ? `${OUT_DIR}/${id}` : OUT_DIR;
+  const started = Date.now();
+  // maven/自定义命令无法定向输出——跑完后把本次新产生的报告收割进隔离目录
+  const after = id ? () => harvest(root, out, started) : null;
+
+  const custom = loadConfig(root).testCommand || "";
+  if (custom) return run(root, custom, "自定义命令不注入报告参数；请确保命令本身输出 JUnit XML", after);
+
+  if (exists(path.join(root, "pom.xml"))) return run(root, "mvn test", null, after); // surefire 自带报告
+  if (exists(path.join(root, "go.mod"))) return runGo(root, out);
+  if (exists(path.join(root, "package.json"))) return runNode(root, out);
+  if (exists(path.join(root, "composer.json")))
+    return run(root, `vendor/bin/phpunit --log-junit ${out}/phpunit.xml`);
+  die("无法确定测试命令；在 .ai/config.json 的 testCommand 中配置");
+}
+
+function run(root, cmd, note, after) {
+  console.log(`==> ${cmd}`);
+  if (note) console.log(`（${note}）`);
+  const r = spawnSync(cmd, { shell: true, stdio: "inherit", cwd: root });
+  if (r.status !== 0) die(`TEST_FAILED（exit=${r.status}）；修复后重跑。报告即验收证据`, r.status || 1);
+  if (after) after();
+  console.log("TEST_PASSED（JUnit 报告即验收证据，ai ship 时核对）");
+}
+
+// 把本次运行新产生的 JUnit XML 收进隔离目录（只收 mtime 晚于本次启动的）
+function harvest(root, outRel, started) {
+  const SOURCES = [
+    "target/surefire-reports", "target/failsafe-reports",
+    "build/test-results", "reports/junit",
+  ];
+  const outAbs = path.join(root, outRel);
+  fs.mkdirSync(outAbs, { recursive: true });
+  let n = 0;
+  const grab = (dir, recursive) => {
+    if (!exists(dir)) return;
+    for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, f.name);
+      if (f.isDirectory()) { if (recursive) grab(p, true); continue; }
+      if (!f.name.endsWith(".xml")) continue;
+      if (fs.statSync(p).mtimeMs >= started - 2000) {
+        fs.copyFileSync(p, path.join(outAbs, f.name));
+        n++;
+      }
+    }
+  };
+  SOURCES.forEach((d) => grab(path.join(root, d), true));
+  grab(path.join(root, OUT_DIR), false); // test-results 根层文件（不递归，避免收走别的变更的隔离目录）
+  if (n) console.log(`已把 ${n} 份新报告收入 ${outRel}/（按变更隔离）`);
+  else console.log(`提示：本次未检测到新报告；若测试框架输出位置特殊，请显式传给 ai ship`);
+}
+
+// ── Go：go test 原生不产 XML；捕获 -v 输出自转 JUnit（零依赖，无需 gotestsum）──
+function runGo(root, out) {
+  const cmd = "go test ./... -v";
+  console.log(`==> ${cmd}（输出将转为 JUnit 报告：${out}/go.xml）`);
+  const r = spawnSync(cmd, { shell: true, cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  const txt = (r.stdout || "") + (r.stderr || "");
+  process.stdout.write(txt);
+  const cases = parseGoTestOutput(txt);
+  if (cases.length) {
+    fs.mkdirSync(path.join(root, out), { recursive: true });
+    fs.writeFileSync(path.join(root, out, "go.xml"), buildJUnitXml("go", cases));
+    console.log(`已生成 ${out}/go.xml（${cases.length} 条用例）`);
+  }
+  if (r.status !== 0) die(`TEST_FAILED（exit=${r.status}）；修复后重跑。报告即验收证据`, r.status || 1);
+  console.log("TEST_PASSED（JUnit 报告即验收证据，ai ship 时核对）");
+}
+
+// 解析 `go test -v` 的 --- PASS/FAIL/SKIP 行（含子测试缩进）
+function parseGoTestOutput(out) {
+  const cases = [];
+  for (const line of out.split("\n")) {
+    const m = line.match(/^\s*--- (PASS|FAIL|SKIP): (\S+) \(([\d.]+)s\)/);
+    if (m) cases.push({ name: m[2], status: m[1], time: m[3] });
+  }
+  return cases;
+}
+
+function buildJUnitXml(suite, cases) {
+  const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
+  const failures = cases.filter((c) => c.status === "FAIL").length;
+  const body = cases
+    .map((c) => {
+      const inner = c.status === "FAIL" ? "<failure/>" : c.status === "SKIP" ? "<skipped/>" : "";
+      return inner
+        ? `  <testcase classname="${esc(suite)}" name="${esc(c.name)}" time="${c.time}">${inner}</testcase>`
+        : `  <testcase classname="${esc(suite)}" name="${esc(c.name)}" time="${c.time}"/>`;
+    })
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="${esc(suite)}" tests="${cases.length}" failures="${failures}">\n${body}\n</testsuite>\n`;
+}
+
+// ── Node：Vitest 用内置 junit reporter；Jest 需 jest-junit（缺则给一行安装指引）──
+function runNode(root, out) {
+  let deps = {};
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch { /* 按 npm test 兜底 */ }
+
+  if (deps.vitest) {
+    return run(root, `npx vitest run --reporter=default --reporter=junit --outputFile=${out}/vitest.xml`);
+  }
+  if (deps.jest) {
+    if (!deps["jest-junit"]) {
+      console.log("提示：Jest 无内置 JUnit 输出。运行 `npm i -D jest-junit` 后重跑 ai test，报告将自动生成。");
+      return run(root, "npm test", "本次无 JUnit 报告，ship 的证据门禁将无法通过");
+    }
+    console.log(`==> npx jest --reporters=default --reporters=jest-junit（报告：${out}/jest.xml）`);
+    const r = spawnSync("npx jest --reporters=default --reporters=jest-junit", {
+      shell: true, stdio: "inherit", cwd: root,
+      env: { ...process.env, JEST_JUNIT_OUTPUT_DIR: out, JEST_JUNIT_OUTPUT_NAME: "jest.xml" },
+    });
+    if (r.status !== 0) die(`TEST_FAILED（exit=${r.status}）；修复后重跑。报告即验收证据`, r.status || 1);
+    return console.log("TEST_PASSED（JUnit 报告即验收证据，ai ship 时核对）");
+  }
+  return run(root, "npm test", "未识别测试框架，无法自动注入 JUnit 输出；如需证据门禁请配置 junit reporter");
+}
+
+module.exports = { cmdTest, parseGoTestOutput, buildJUnitXml };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@brightliu/ai-control",
+  "version": "2.1.0",
+  "description": "AGENTS.md 标准之上的中文全栈 AI 工程控制层：规格先行、DB 两阶段确认、证据验收。支持 Codex / Claude Code / Cursor / Kimi / Qoder / WorkBuddy。",
+  "bin": {
+    "ai": "bin/ai.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "payload/",
+    "addons/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/unit.test.js && node tests/budget.js && node tests/refs.js && npx bats tests/"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BrightLiu4917/ai-control.git"
+  },
+  "keywords": [
+    "agents-md",
+    "ai-coding",
+    "spec-driven",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "bats": "^1.11.0"
+  }
+}

package/payload/AGENTS.md

@@ -0,0 +1,62 @@
+# 全局契约
+
+你是在严格约束下工作的全栈工程师。不确定时：停止并询问。禁止带着影响正确性的假设继续。
+
+## 绝对红线
+
+- 禁止发明业务事实：字段、枚举值、API 路径、权限、状态流转、响应格式必须来自已确认规格或用户确认。
+- 禁止伪实现：不写空方法、TODO 桩、假数据糊弄验证；禁止为通过验证降低测试或安全标准。
+- 禁止在代码、日志、配置、文档中出现密钥、密码、token、生产连接串。
+- 禁止修改无关文件、顺手重构、未经批准引入依赖或删除既有接口/字段/页面入口。
+
+## 两个必须等用户点头的确认点
+
+1. **change 确认**：proposal + test-cases 未经用户确认，禁止写任何业务代码；用户点头后**由用户本人**运行 `ai confirm <id>` 留痕（AI 禁止代跑，把命令交给用户）（ship 门禁的前置，确认后再改 proposal/test-cases 即失效须重确认）。
+2. **数据库确认**：涉及表结构/字段/索引/迁移时，先输出表结构设计审查，确认后再输出变更确认包（含目标 DDL、回滚 SQL、联动清单），再次确认后才能执行 SQL 或写 migration。DROP/TRUNCATE 前默认备份（`原表名_copy_yyyyMMdd`）。完整细则见 `.ai/rules/10-db-schema.md`。
+
+## 任务分级
+
+- **简单任务**（可跳过 change）：仅文档/注释/typo，单文件，不碰任何业务行为。
+- **lite**（`ai new <id> --lite`，两件套）：不碰数据库、API 契约、权限/租户/支付/状态流转；越界会被门禁拦下，用 `ai new <id> --upgrade` 升级（保留已写内容）。lite 减仪式不减纪律：同样要求原子提交和可验证用例。
+- **完整**（`ai new <id>`）：其余一切。涉及跨模块/数据库/接口兼容时按模板补建 design.md。
+
+## 工作流
+
+```text
+用户提需求 → 影响探测（检索代码，列出触碰的文件/表/接口）→ 判级（证据判级，拿不准判高一级）
+→ ai new 建骨架 → 补全 proposal + test-cases → ai check → 确认单标注级别与理由，等用户确认 → 用户运行 ai confirm
+→ 实现（最小切片）→ ai test <id> → ai ship（证据门禁秒级）→ 交付
+```
+
+- 用户说"测一下"→ `ai test <id>`（报告自动按变更隔离）；"能上线吗/发布"→ `ai ship <id>`；"表加字段"→ 走数据库确认。
+- 用户明说小/大需求时尊重其判级，门禁照常。
+
+## 验收契约
+
+- test-cases.md 随规格一起经用户确认；执行阶段禁止为迁就实现修改用例，改需重新确认。
+- 自动化测试方法名必须含用例ID（如 `test_TC01_xxx`）；验收以 JUnit 报告为证据（存在、无失败、TC-ID 覆盖非手动用例），不维护状态表格。
+- 手动用例的执行结果逐条写入交付说明；禁止谎报未执行的验证。
+- 验证尽量在独立上下文进行（Claude Code 用测试工程师 subagent，其他工具建议新会话）；用 goal-backward 提问："这个功能要成立，哪些行为必须可观察到？"
+
+## 角色路由（4 个）
+
+按任务读取对应手册，对用户使用中文角色名：
+
+- 产品规格工程师 `.ai/agents/agent-spec.md`：需求澄清、架构影响、变更规格、API 契约。非简单任务必先经过。
+- 数据库工程师 `.ai/agents/agent-dba.md`：表结构、SQL、迁移回滚、两阶段确认。碰 DB 必先经过。
+- 开发工程师 `.ai/agents/agent-dev.md`：全部实现；按栈读 `.ai/agents/dev/` 对应手册与 `.ai/rules/` 栈规则。
+- 测试工程师 `.ai/agents/agent-test.md`：设计期写验收用例，实现后按报告核对证据。
+- 发布检查按 `.ai/rules/53-release.md` 清单执行（只过与本次变更相关的项）；高风险变更建议用 `.ai/templates/review-prompt.md` 在新会话做一次独立审查。
+
+## 规则库
+
+`.ai/rules/` 单层编号，按需读取（索引见其 README）：10-db-schema、20-api、21-jwt、22-rbac、30-frontend、31-vue3、32-react、40-backend、41-spring-boot、42-go-gin、43-php、44-java-enum、50-testing、51-security、52-performance、53-release、01-code-change、02-product-ux。
+开工提示会注入本次必读清单；不读本次未涉及的规则。
+
+## 必须澄清（停止并询问）
+
+字段含义、枚举值、表结构、状态流转、权限/租户规则、删除行为、支付扣减、API 响应格式、页面入口与异常态、规格与现有代码冲突——任一不清即停。
+
+## 交付输出
+
+只列实际发生变化的项（有 SQL 必附回滚；有手动用例必逐条报告结果）；无变化的项不写"无"占位。大型功能建议归档已确认行为到 `.ai/specs/`，中小变更不强制。