agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/scripts/check-secrets-lite.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// check-secrets-lite：纯 Node 密钥兜底扫描（2026-10-29，CI 装不上 gitleaks 时的退路）
+// 动机：CI agent 无外网 / 二进制落不了盘时，secrets-scan 原为 loud-skip——门表看着绿、实际没扫。
+//   本脚本零二进制、零网络；check-secrets.mjs 在 gitleaks 不可用时自动接续（GITLEAKS_BIN/PATH/
+//   .agents/tools 三级全空），也可 SECRETS_SCAN_LITE=1 或 --lite 强制。
+// 规则分两档：
+//   ① 强特征（前缀/私钥块/JWT/连接串口令）：所有文件执法，误报极低。
+//   ② 宽泛 key=value（generic-api-key 同类）与连接串口令：只对「基线豁免清单之外」的文件执法，
+//      且要求值含数字/符号、熵达标、非代码表达式续写——实测本树 2811 文件命中 0 处。
+// 豁免口径（与 gitleaks 基线同源）：.gitleaks-baseline.json 出现过的 22 个文件按**文件级**豁免
+//   （owner 拍板的 1231 处存量，值在基线内已 redact，无法按值匹配）；另加 appsettings*.json 白名单
+//   （owner 2026-10-27 判定开发库凭据 / JWT Secret 非风险，gitleaks 亦不命中）。
+//   代价（明示）：上述文件内**新增**的弱特征密钥会漏，由可装机环境的 gitleaks 全量补。
+// 基线缺失 = exit 2（无豁免清单则全树必爆红，与 gitleaks detect 同口径 fail-closed）。
+// 行内豁免：同行含 `gitleaks:allow` 或 `secrets-lite:allow` 即跳过（与 gitleaks 同形）。
+// 用法：node .agents/scripts/check-secrets-lite.mjs [--staged | --range <a>..<b>] [--json]
+//   --staged 只扫暂存区新增行；--range 只扫给定范围新增行；缺省 = 全部 git 跟踪文件
+// 退出码：0 无泄漏；1 发现泄漏；2 配置/参数失守
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = path.resolve(SCRIPT_DIR, '..', '..');
+
+const STRONG_RULES = [
+  { id: 'private-key', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { id: 'aws-access-key-id', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { id: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+  { id: 'github-pat-fine-grained', re: /\bgithub_pat_[A-Za-z0-9_]{50,}\b/ },
+  { id: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { id: 'stripe-live-key', re: /\b(?:sk|rk)_live_[A-Za-z0-9]{20,}\b/ },
+  { id: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { id: 'square-access-token', re: /\bsq0atp-[0-9A-Za-z_-]{22}\b/ },
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+];
+
+const GENERIC_RULE = {
+  id: 'generic-api-key',
+  re: /(?:api[_-]?key|apikey|access[_-]?key|secret|token|passwd|password|pwd|_auth|authorization)["']?\s*[:=]\s*["']?([A-Za-z0-9+/=_-]{16,})["']?/i,
+};
+
+// 连接串口令：值与形态都强（`Password=xxx`），但 appsettings 属 owner 判定的非风险载体，
+// 故与 generic 同档——只对豁免清单外的文件执法。
+const CRED_RULE = {
+  id: 'connection-string-password',
+  // 值限定为「无空白/分号/引号、不含点号与括号」的字面量——含 `.`/`(` 的必是代码表达式（process.env.X 等）
+  re: /\b(?:password|pwd)\s*=\s*(?!\*|\$|<|\{)[A-Za-z0-9_\-+/=]{12,}(?![A-Za-z0-9_.])/i,
+};
+
+const PLACEHOLDER = /^(?:x{4,}|0{4,}|your|my|example|sample|changeme|placeholder|dummy|fake|redacted|todo|none|null|undefined|test)/i;
+const ALLOW_MARK = /(?:gitleaks|secrets-lite):allow/;
+// appsettings*.json：owner 2026-10-27 判定开发库凭据 / JWT Secret 非风险（详见本文件头注）
+const ACCEPTED_FILE = [/(?:^|\/)appsettings(?:\.[\w-]+)?\.json$/i];
+const SKIP_PATH = [
+  /^\.git\//, /(?:^|\/)node_modules\//, /^tmp\//, /(?:^|\/)dist\//, /^\.agents\/tools\//, /(?:^|\/)bin\//, /(?:^|\/)obj\//,
+  // pdf.js 发行版 worker（仅这两个具体文件）：内部把密码形参原样透传给 utf8StringToString()，
+  // 被 connection-string-password 规则误报（此处不复述原文字面量，否则本文件自身即命中）；
+  // `.map` 的 sourcesContent 为单行 JSON 无法加同行豁免标记
+  // （2026-11-03，commit 546eda16 引入 vendor 时起误报；不跳过整个目录，避免放过未来新增内容）
+  /(?:^|\/)frontend\/public\/pdfview\/build\/pdf\.worker\.mjs(?:\.map)?$/,
+];
+const MAX_BYTES = 2 * 1024 * 1024;
+
+const entropy = (s) => {
+  const m = new Map();
+  for (const ch of s) m.set(ch, (m.get(ch) || 0) + 1);
+  let h = 0;
+  for (const n of m.values()) h -= (n / s.length) * Math.log2(n / s.length);
+  return h;
+};
+
+const redact = (s) => (s.length <= 8 ? '***' : `${s.slice(0, 4)}***${s.slice(-2)}`);
+
+// 宽泛规则的残余误报过滤（实测口径见头注）
+const weakNoise = (line, m) => {
+  const v = m[1];
+  if (PLACEHOLDER.test(v)) return true;
+  if (entropy(v) < 3.5) return true;
+  if (!/\d/.test(v)) return true;                                  // 纯字母 = 标识符 / 常量名
+  if (/^[0-9a-f]{8,20}$/i.test(v)) return true;                    // 短 hex = assembly token / GUID 片段
+  if ((v.match(/-/g) || []).length >= 3) return true;              // 多连字符 = 描述性短语（如 integration-test-jwt-secret-2026-...）
+  if (/^[A-Za-z0-9_$]/.test(line.slice(m.index + m[0].length))) return true; // 值后续写 = 代码表达式
+  return false;
+};
+
+// 单行判定 → { rule, secret } 或 null
+export const matchLine = (line, { generic }) => {
+  if (ALLOW_MARK.test(line)) return null;
+  for (const r of STRONG_RULES) {
+    const m = r.re.exec(line);
+    if (m) return { rule: r.id, secret: redact(m[0]) };
+  }
+  if (!generic) return null;
+  const m = GENERIC_RULE.re.exec(line);
+  if (m && !weakNoise(line, m)) return { rule: GENERIC_RULE.id, secret: redact(m[1]) };
+  const c = CRED_RULE.re.exec(line);
+  if (c) {
+    const v = c[0].replace(/^[^=]*=/, '').trim();
+    // 口令须含数字或符号（纯大写/驼峰标识符如 process.env.SMOKE_ADMIN_PASSWORD 不算）
+    if ((/\d/.test(v) || /[^A-Za-z0-9_]/.test(v)) && !PLACEHOLDER.test(v)) {
+      return { rule: CRED_RULE.id, secret: redact(v) };
+    }
+  }
+  return null;
+};
+
+export const loadBaselineFiles = (file) => {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const set = new Set();
+  for (const e of Array.isArray(raw) ? raw : []) {
+    if (e && typeof e.File === 'string') set.add(e.File.replace(/\\/g, '/'));
+  }
+  return set;
+};
+
+const isExempt = (file, baselineFiles) => baselineFiles.has(file) || ACCEPTED_FILE.some((re) => re.test(file));
+const skipped = (p) => SKIP_PATH.some((re) => re.test(p));
+
+const readIfText = (abs) => {
+  try {
+    const st = fs.statSync(abs);
+    if (!st.isFile() || st.size > MAX_BYTES) return null;
+    const buf = fs.readFileSync(abs);
+    if (buf.subarray(0, 8000).includes(0)) return null; // 二进制
+    return buf.toString('utf8');
+  } catch { return null; }
+};
+
+const scanText = (file, text, baselineFiles, hits) => {
+  const generic = !isExempt(file, baselineFiles);
+  let ln = 0;
+  for (const line of text.split(/\r?\n/)) {
+    ln += 1;
+    const hit = matchLine(line, { generic });
+    if (hit) hits.push({ file, line: ln, rule: hit.rule, secret: hit.secret });
+  }
+};
+
+const scanWorkingTree = (root, baselineFiles) => {
+  // 根必须就是 git 顶层：CHECK_SECRETS_ROOT 指到子目录时 git 会回上层仓库，路径全 stat 失败 →
+  // scanned=0 的假绿。此处 fail-loud（下面对 scanned=0 也再兜一层）。
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8' });
+  if (top.status !== 0) throw new Error(`git rev-parse --show-toplevel 失败（${root} 不是 git 工作区？）：${top.stderr || top.status}`);
+  const topPath = path.resolve(String(top.stdout || '').trim());
+  if (topPath !== path.resolve(root)) throw new Error(`扫描根 ${root} 不是 git 顶层（顶层为 ${topPath}）——拒跑，避免扫空目录假绿`);
+  const r = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git ls-files 失败：${r.stderr || r.status}`);
+  const files = String(r.stdout || '').split('\0').map((s) => s.replace(/\\/g, '/')).filter(Boolean);
+  const hits = [];
+  let scanned = 0;
+  for (const f of files) {
+    if (skipped(f)) continue;
+    const text = readIfText(path.join(root, f));
+    if (text === null) continue;
+    scanned += 1;
+    scanText(f, text, baselineFiles, hits);
+  }
+  return { hits, scanned, unit: '文件' };
+};
+
+// 增量：只判 git diff 的新增行（-U0 下无上下文行，行号取新侧）
+const scanDiff = (root, range, baselineFiles) => {
+  const args = range === 'staged' ? ['diff', '--cached', '-U0', '--no-color'] : ['diff', '-U0', '--no-color', range];
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} 失败：${r.stderr || r.status}`);
+  const hits = [];
+  let file = null;
+  let ln = 0;
+  let scanned = 0;
+  for (const raw of String(r.stdout || '').split(/\r?\n/)) {
+    if (raw.startsWith('+++ ')) {
+      const p = raw.slice(4).trim();
+      file = p === '/dev/null' ? null : p.replace(/^b\//, '');
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+    if (hunk) { ln = Number(hunk[1]); continue; }
+    if (!file || !raw.startsWith('+')) continue;
+    const line = raw.slice(1);
+    if (!skipped(file)) {
+      scanned += 1;
+      const hit = matchLine(line, { generic: !isExempt(file, baselineFiles) });
+      if (hit) hits.push({ file, line: ln, rule: hit.rule, secret: hit.secret });
+    }
+    ln += 1;
+  }
+  return { hits, scanned, unit: '新增行' };
+};
+
+export const scan = ({ root = DEFAULT_ROOT, mode = 'all', range = null, baseline } = {}) => {
+  const baselinePath = baseline || path.join(root, '.gitleaks-baseline.json');
+  if (!fs.existsSync(baselinePath)) {
+    const err = new Error(`基线缺失 ${baselinePath}——无豁免清单则全树必爆红，拒跑（重建口径见 .agents/notes/runtime-env.md §6.3）`);
+    err.code = 'NO_BASELINE';
+    throw err;
+  }
+  const baselineFiles = loadBaselineFiles(baselinePath);
+  const res = mode === 'staged' ? scanDiff(root, 'staged', baselineFiles)
+    : mode === 'range' ? scanDiff(root, range, baselineFiles)
+      : scanWorkingTree(root, baselineFiles);
+  return { ...res, baselineFiles: baselineFiles.size };
+};
+
+export const main = (argv = process.argv.slice(2), root = process.env.CHECK_SECRETS_ROOT || DEFAULT_ROOT) => {
+  const rangeIdx = argv.indexOf('--range');
+  const range = rangeIdx >= 0 ? argv[rangeIdx + 1] : null;
+  const mode = argv.includes('--staged') ? 'staged' : range ? 'range' : 'all';
+  if (mode === 'range' && (!range || range.startsWith('-'))) {
+    console.error('[secrets-lite] ❌ --range 需要一个范围参数（<a>..<b>）');
+    return 2;
+  }
+  let res;
+  try {
+    res = scan({ root, mode, range });
+  } catch (e) {
+    console.error(`[secrets-lite] ❌ ${e.message}`);
+    return 2;
+  }
+  if (argv.includes('--json')) console.log(JSON.stringify(res.hits, null, 1));
+  const scopeNote = mode === 'all' ? '工作树全量' : mode === 'staged' ? '暂存增量' : `增量 ${range}`;
+  if (mode === 'all' && res.scanned === 0) {
+    console.error(`[secrets-lite] ❌ 扫描面为 0 ${res.unit}（根 ${root}）——空扫不算通过，按配置失守拒跑`);
+    return 2;
+  }
+  if (res.hits.length) {
+    for (const h of res.hits.slice(0, 50)) console.error(`[secrets-lite] ❌ ${h.file}:${h.line} ${h.rule} ${h.secret}`);
+    if (res.hits.length > 50) console.error(`[secrets-lite] …共 ${res.hits.length} 处，仅列前 50`);
+    console.error(`[secrets-lite] ❌ 发现 ${res.hits.length} 处疑似密钥（${scopeNote}｜${res.scanned} ${res.unit}）——删除该密钥或作废轮换；确属误报则同行加 secrets-lite:allow`);
+    return 1;
+  }
+  console.log(`[secrets-lite] ✅ 无泄漏（${scopeNote}｜${res.scanned} ${res.unit}｜基线豁免文件 ${res.baselineFiles}）`);
+  return 0;
+};
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  process.exit(main());
+}

package/templates/engine/.agents/scripts/check-secrets.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// check-secrets：密钥扫描门（2026-10-14 决定 4 / G5 安全插队；机制台账已登记）
+// 用法：node .agents/scripts/check-secrets.mjs [--staged] [--lite]
+//   默认     = 全量历史：gitleaks detect --baseline-path .gitleaks-baseline.json（基线外新泄漏 exit 1）
+//   --staged = 提交增量：gitleaks protect --staged（只看暂存内容，历史存量不触；原 pre-commit 消费——
+//              2026-10-21 owner 指令「密钥本地不扫」退役该腿，旗标保留供手动/测试）
+//   SECRETS_SCAN_BASE=<sha>（2026-10-29 secrets-incr，verify 默认档注入）= 范围增量：只扫 <sha>..HEAD
+//     新提交（锚点 = 最近绿行头，经 verify 的祖先校验——历史被 rebase 改写则锚失效回落全量）；
+//     覆盖链 = 每次绿行扫过锚..当刻，逐次滚动；全量兜底仍由 --full 本地档与 CI main 重档承担。
+//     基线（存量豁免）在两种模式下同样适用。sha 解析不出 → loud WARN + 回退全量（fail-safe）。
+// 二进制解析序（机理登记 = .agents/notes/runtime-env.md §6.3 gitleaks 条）：
+//   GITLEAKS_BIN 环境变量（.mjs/.js 结尾经本进程 node 直跑——测试注缝）→ PATH 上 gitleaks
+//   → .agents/tools/gitleaks(.exe)（git-ignore，机器本地）。
+// **2026-10-29 兜底（owner 口径「装不上也要扫」）**：三处皆缺（典型 = CI agent 无外网/无法落二进制），
+//   改走纯 Node 轻量扫描 check-secrets-lite.mjs（零二进制零网络，复用同一份基线做文件级豁免）——
+//   **不再 loud-skip**：密钥门从此恒执法，只是执法者按环境降级（gitleaks → lite）。
+//   强制指定：SECRETS_SCAN_LITE=1 或 --lite 跳过 gitleaks；SECRETS_SCAN_REQUIRE_GITLEAKS=1 则缺二进制即
+//   fail-closed（exit 2，供需要强执法面的场合）。降级事实在输出首行标明「执法者=lite」，绿行 envSkips 不再登记。
+// 基线：.gitleaks-baseline.json = 2026-10-14 历史全量 1221 处存量豁免（--redact 生成；用户拍板
+//   「豁免清单」，真实有效密钥的作废轮换另行处置，不因基线豁免）。2026-10-15 同口径重生成扩至 1227 处：
+//   追加 7bd06ebb（新大洋-物资需求提报原始动作脚本）6 处「权限Key」uuid——用户确认系旧系统权限条目
+//   标识符非凭证，与既有 wiki 产品需求采集物同类同处置。2026-10-24 再生成扩至 1230 处：追加
+//   e6f33915/919e7084 私有 npm 源 _auth 3 处（frontend/.npmrc ×2 + 文档抄录 ×1，同凭据家族）——
+//   用户拍板「公司私有 npm 源（101.101.118.58:8089）Basic 认证凭据豁免，不作废轮换，下次不再扫」。
+//   2026-10-31 再扩至 1236 处：追加 9ce8649e 的 5 处「rowKey」GUID（workflow/evidence/2026-10-31-username-caliber/probe.json
+//   ——前后端 UI 实测证据里人员表格的行 key = BasicConfig_Staff.ID）——**用户拍板「追加基线豁免 5 条（与 2026-10-15 先例同口径）」**，
+//   确认系人员标识符非凭证（同文件另有 177 个 GUID 因字段名不含 key 未被判，属规则按字段名启发式命中）。
+//   前向已把该字段值掩码为 <uuid> 并补 rowKeyKind 声明（5ace48f1）；本次豁免用于让范围基线 9b8bc5cd..HEAD 内的历史提交 9ce8649e 不再命中。
+//   detect 模式基线缺失 = exit 2
+//   （配置失守 fail-closed——静默无基线会让存量全量爆红，与拍板相反）。
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { main as liteMain } from './check-secrets-lite.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_SECRETS_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const STAGED = process.argv.includes('--staged');
+const FORCE_LITE = process.argv.includes('--lite') || process.env.SECRETS_SCAN_LITE === '1';
+const BASELINE = path.join(ROOT, '.gitleaks-baseline.json');
+
+function resolveBin() {
+  if (FORCE_LITE) return null;
+  const envBin = process.env.GITLEAKS_BIN;
+  if (envBin) {
+    if (!fs.existsSync(envBin)) return null;
+    return /\.(mjs|js)$/i.test(envBin) ? { node: envBin } : { raw: envBin };
+  }
+  const probe = spawnSync('gitleaks', ['version'], { encoding: 'utf8' });
+  if (probe.status === 0) return { raw: 'gitleaks' };
+  const local = path.join(ROOT, '.agents', 'tools', process.platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
+  if (fs.existsSync(local)) return { raw: local };
+  return null;
+}
+
+// 扫描范围（2026-10-29 secrets-incr）：SECRETS_SCAN_BASE 给定且可解析 → 只扫 base..HEAD；
+// 未给定 / 解析不出 → 全量（后者加 loud WARN，fail-safe 不静默）。
+let range = null;
+if (!STAGED && process.env.SECRETS_SCAN_BASE) {
+  const base = process.env.SECRETS_SCAN_BASE;
+  const probe = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd: ROOT, encoding: 'utf8' });
+  if (probe.status === 0) {
+    range = `${base.trim()}..HEAD`;
+  } else {
+    console.error(`[check-secrets] ⚠️ SECRETS_SCAN_BASE="${base}" 解析不出（非本仓提交/被改写？）——回退全量历史扫描`);
+  }
+}
+
+const scanRangeNote = STAGED ? '暂存增量' : range ? `增量范围 ${range}` : '全量';
+
+const bin = resolveBin();
+if (!bin) {
+  if (process.env.SECRETS_SCAN_REQUIRE_GITLEAKS === '1' && !FORCE_LITE) {
+    console.error('[check-secrets] ❌ SECRETS_SCAN_REQUIRE_GITLEAKS=1 但 gitleaks 三处解析皆缺——按配置 fail-closed 拦下（装机见 .agents/notes/runtime-env.md §6.3）');
+    process.exit(2);
+  }
+  if (!STAGED && !fs.existsSync(BASELINE)) {
+    console.error(`[check-secrets] ❌ 基线缺失 ${BASELINE}——轻量扫描同样依赖豁免清单，拒跑。重建：gitleaks detect --redact 全量报告存为该文件（口径见 runtime-env §6.3）`);
+    process.exit(2);
+  }
+  console.error(`[check-secrets] ℹ️ 执法者=lite（gitleaks 不可用${FORCE_LITE ? '／已强制 --lite' : '——未装或 CI 无外网'}）：纯 Node 轻量规则 + 同一基线文件级豁免；强执法面（全史逐行模式匹配）请装 gitleaks（runtime-env.md §6.3）`);
+  const liteArgs = STAGED ? ['--staged'] : range ? ['--range', range] : [];
+  process.exit(liteMain(liteArgs, ROOT));
+}
+
+if (!STAGED && !fs.existsSync(BASELINE)) {
+  console.error(`[check-secrets] ❌ 基线缺失 ${BASELINE}——detect 无基线 = 存量豁免失效全量爆红，拒跑。重建：gitleaks detect --redact 全量报告存为该文件（口径见 runtime-env §6.3）`);
+  process.exit(2);
+}
+console.log(`[check-secrets] 执法者=gitleaks（${bin.raw || bin.node}）`);
+const args = STAGED
+  ? ['protect', '--staged', '--redact', '--no-banner']
+  : ['detect', '--source', '.', '--baseline-path', BASELINE, '--redact', '--no-banner',
+    ...(range ? ['--log-opts', range] : [])];
+const r = bin.node
+  ? spawnSync(process.execPath, [bin.node, ...args], { stdio: 'inherit' })
+  : spawnSync(bin.raw, args, { stdio: 'inherit' });
+if (r.status !== 0) {
+  console.error(`[check-secrets] ❌ ${STAGED ? '暂存内容' : range ? `增量范围（${range}，基线外）` : '历史（基线外）'}发现密钥泄漏（gitleaks exit ${r.status}）——上方为 redacted 明细；新泄漏修法：删除该密钥或作废轮换，禁改基线豁免`);
+  process.exit(r.status ?? 1);
+}
+console.log(`[check-secrets] ✅ 执法者=gitleaks｜${scanRangeNote}（基线外）无泄漏`);

package/templates/engine/.agents/scripts/check-test-impact-map.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/* check-test-impact-map: 影响面映射完整性机检
+ *
+ * 目的：防止「新增测试类未登记 → 推送时被静默跳过」。
+ * 口径：tests/Shipyard.Material.IntegrationTests 下所有含 [Fact]/[Theory] 的文件，
+ *       其 public *Tests 类必须与 .agents/config/test-impact-map.json 的 areas 完全一致。
+ *       FullChain/ 默认不编译（#if FCLocal），不纳入。
+ *
+ * 何时硬红：run-backend-tests.mjs --full（CI 重档）先跑本检查，失败即退出 1。
+ * 何时软兜底：pre-push 选测时若发现未登记类，selector 自动回退全量（见 test-impact-lib.mjs）。
+ *
+ * 退出码：0 = 一致；1 = 缺失/陈旧/重复/测试类命名无法识别。
+ */
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT, loadMap } from './test-impact-lib.mjs';
+
+const TEST_DIR = path.join(ROOT, 'tests', 'Shipyard.Material.IntegrationTests');
+const SKIP_DIRS = new Set(['bin', 'obj', 'FullChain']);
+const CLASS_RE = /^public\s+(?:sealed\s+|abstract\s+|partial\s+)*class\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+
+const walk = (dir) => {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...walk(path.join(dir, entry.name)));
+    } else if (entry.isFile() && entry.name.endsWith('.cs')) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+  return out;
+};
+
+let map;
+try {
+  const mapIdx = process.argv.indexOf('--map');
+  const mapPath = mapIdx >= 0 ? process.argv[mapIdx + 1] : undefined;
+  if (mapIdx >= 0 && !mapPath) throw new Error('--map 缺少路径');
+  map = loadMap(mapPath);
+} catch (e) {
+  console.error(`check-test-impact-map: ${e.message}`);
+  process.exit(1);
+}
+
+const mapped = new Map();
+for (const [area, classes] of Object.entries(map.areas)) {
+  for (const cls of classes) {
+    if (!mapped.has(cls)) mapped.set(cls, new Set());
+    mapped.get(cls).add(area);
+  }
+}
+
+const source = new Map();
+const errors = [];
+for (const file of walk(TEST_DIR)) {
+  const src = fs.readFileSync(file, 'utf8');
+  const classes = [];
+  for (const m of src.matchAll(CLASS_RE)) {
+    if (m[1].endsWith('Tests')) classes.push(m[1]);
+  }
+  if (classes.length > 0) {
+    const ns = (src.match(/^namespace\s+([A-Za-z0-9_.]+)/m) || [])[1];
+    if (ns && ns !== map.namespace) {
+      errors.push(`测试命名空间与 manifest 不一致：${path.relative(ROOT, file)} → ${ns}（期望 ${map.namespace}）`);
+    }
+    for (const cls of classes) {
+      if (source.has(cls)) {
+        errors.push(`测试类重复声明：${cls}（${path.relative(ROOT, source.get(cls))} 与 ${path.relative(ROOT, file)}）`);
+      } else {
+        source.set(cls, file);
+      }
+    }
+    continue;
+  }
+  if (/\[(Fact|Theory)\b/.test(src)) {
+    errors.push(`无法识别的测试类（文件含 [Fact]/[Theory] 但没有 public *Tests 类）：${path.relative(ROOT, file)}`);
+  }
+}
+
+const missing = [...source.keys()].filter((cls) => !mapped.has(cls)).sort();
+const stale = [...mapped.keys()].filter((cls) => !source.has(cls)).sort();
+
+if (missing.length) {
+  errors.push(`未登记的测试类（${missing.length}）：\n  - ${missing.join('\n  - ')}`);
+}
+if (stale.length) {
+  errors.push(`manifest 中已不存在的测试类（${stale.length}）：\n  - ${stale.join('\n  - ')}`);
+}
+
+if (errors.length) {
+  console.error('check-test-impact-map: FAIL');
+  for (const err of errors) console.error(`- ${err}`);
+  console.error('修复：更新 .agents/config/test-impact-map.json 后重跑。');
+  process.exit(1);
+}
+
+const areaCounts = Object.entries(map.areas)
+  .map(([area, classes]) => `${area}=${classes.length}`)
+  .join(' ');
+console.log('check-test-impact-map: OK');
+console.log(`  classes: ${source.size}（source=${source.size}, mapped=${mapped.size}）`);
+console.log(`  areas: ${Object.keys(map.areas).length}（${areaCounts}）`);
+console.log(`  always: ${map.always.length}`);
+console.log(`  paths: ${map.paths.length}`);

package/templates/engine/.agents/scripts/ci-assert-frontend-deps.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// ci-assert-frontend-deps — CI「npm install 后 devDependencies 是否真落地」的前置断言（2026-10-29）
+// 动机：CI build 实跑红在三条门（frontend-lint / frontend-unit-test）都报
+//   `'vitest' is not recognized as an internal or external command` / `'eslint' is not ...`——
+//   npm install 退出码 0 却少装 devDependencies（agent 侧 NODE_ENV=production 或 omit=dev 常见）。
+//   让它在安装后一步当场失败，错误信息直指原因，而不是三条门各自重复报「命令不存在」。
+// 判据：frontend/node_modules/.bin 下 vitest 与 eslint 的可执行入口存在（跨平台判据看包目录）。
+// 退出码：0 齐全；1 缺失（打印可操作的修法）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const ROOT = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+const FE = path.join(ROOT, 'frontend');
+const REQUIRED = [
+  { pkg: 'vitest', cmd: 'vitest', why: 'frontend-unit-test（vitest run）' },
+  { pkg: 'eslint', cmd: 'eslint', why: 'frontend-lint（eslint .）' },
+  { pkg: 'vue-tsc', cmd: 'vue-tsc', why: 'frontend-build（vue-tsc -b）' },
+];
+
+const binDir = path.join(FE, 'node_modules', '.bin');
+if (!fs.existsSync(path.join(FE, 'node_modules'))) {
+  console.error(`[ci-assert-frontend-deps] ❌ frontend/node_modules 不存在——npm install 未执行或工作目录不对（${FE}）`);
+  process.exit(1);
+}
+
+const missing = [];
+for (const r of REQUIRED) {
+  const pkgJson = path.join(FE, 'node_modules', r.pkg, 'package.json');
+  const bin = path.join(binDir, process.platform === 'win32' ? `${r.cmd}.cmd` : r.cmd);
+  if (!fs.existsSync(pkgJson) || !fs.existsSync(bin)) missing.push(r);
+}
+
+if (missing.length) {
+  console.error('[ci-assert-frontend-deps] ❌ devDependencies 未落地（npm install 退出码 0 也可能少装）：');
+  for (const m of missing) console.error(`  · ${m.pkg}（${m.why}）：缺 node_modules/${m.pkg} 或 node_modules/.bin/${m.cmd}`);
+  console.error('[ci-assert-frontend-deps] 常见原因：agent 侧 NODE_ENV=production / npm config omit=dev / 私有源 .npmrc 认证失败导致整包跳过。');
+  console.error('[ci-assert-frontend-deps] 修法：npm install --legacy-peer-deps --include=dev（并确认 NODE_ENV=development、npm_config_omit 为空）。');
+  process.exit(1);
+}
+
+console.log(`[ci-assert-frontend-deps] ✅ devDependencies 齐全：${REQUIRED.map((r) => r.pkg).join(' / ')}（${path.relative(ROOT, binDir)}）`);

package/templates/engine/.agents/scripts/ci-commit-hygiene.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// CI 提交信息卫生检出（2026-11-05 复盘 P0 机器执法）：把「commit-msg 钩子未挂 / 被 --no-verify 跳过」
+// 变成 CI 可见失败——对推送区间内每个新提交（--no-merges，TFS PR 合并提交不校验）的 message 按
+// .githooks/commit-msg 同一份规则校验（枚举/正则单源 .agents/config/commit-msg-rules.json，禁双源）。
+// 检出边界：覆盖「钩子未挂 / --no-verify 且消息违规」；不覆盖「--no-verify 但消息恰好合法」（合法即无可报违规）。
+// 区间传递：三层基准
+//   ① --base 显式指定（本地复跑）；
+//   ② PR 构建（SYSTEM_PULLREQUEST_TARGETBRANCH 在场且 HEAD 是合并提交）：取合并提交的第一父（= 目标分支尖端）
+//      作基准，只判本 PR 引入的提交。原因（2026-11-05 实测 build 29054 假红）：PR 构建的 CI_PUSH_BEFORE 来自
+//      changes API「最老一笔的第一父」，该区间会拉入目标分支侧历史（main 上的「还原…」存量提交），
+//      把规则生效前的旧提交判红——规则只约束新提交，存量不该拦发布 PR。
+//   ③ 推送构建：CI_PUSH_BEFORE；取不到 advisory 退回 HEAD~1（同泳道门退回口径）。
+// 本地测试可 --base <revision> 显式指定。违规 exit 1 并逐条列出（hash + message + 违规原因）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const RULES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'commit-msg-rules.json');
+
+const fail = (msg) => { console.error(`ci-commit-hygiene: ${msg}`); process.exit(1); };
+
+let types = [];
+let exemptRe = null;
+let typeRe = null;
+try {
+  const rules = JSON.parse(fs.readFileSync(RULES, 'utf8'));
+  types = rules.types;
+  exemptRe = new RegExp(rules.exemptPrefix);
+  typeRe = new RegExp('^(' + rules.types.join('|') + ')' + rules.typeSuffix);
+} catch (e) { fail(`规则单源 ${RULES} 读取失败：${e.message}`); }
+
+const argOf = (k) => {
+  const i = process.argv.indexOf(k);
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : '';
+};
+
+const gitOut = (args) => {
+  // maxBuffer 抬到 64MB：spawnSync 缺省 1MB——区间覆盖整支历史（如 develop→main 同步直推）时
+  // %B 全量输出实测超 1MB 即 ENOBUFS（2026-11-05 实测假红）。64MB ≈ 本仓全历史输出的 50 倍余量。
+  const r = spawnSync('git', ['-c', 'core.quotepath=off', ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) fail(`git ${args.join(' ')} 失败：${String(r.stderr || r.error || '').trim()}`);
+  return String(r.stdout || '');
+};
+
+let base = argOf('--base');
+let baseSource = '--base';
+if (!base) {
+  const isPrBuild = Boolean((process.env.SYSTEM_PULLREQUEST_TARGETBRANCH || '').trim());
+  const parents = gitOut(['rev-list', '--parents', '-n', '1', 'HEAD']).trim().split(/\s+/).slice(1);
+  if (isPrBuild && parents.length > 1) {
+    base = parents[0];
+    baseSource = 'PR 目标侧第一父';
+  }
+}
+if (!base) {
+  base = (process.env.CI_PUSH_BEFORE || '').trim();
+  baseSource = 'CI_PUSH_BEFORE';
+}
+if (!base) {
+  base = 'HEAD~1';
+  baseSource = 'HEAD~1 回落';
+  console.error('ci-commit-hygiene: advisory: 无 --base / PR 合并检出 / CI_PUSH_BEFORE——退回 HEAD~1（同泳道门口径，多提交直推仅核末笔）');
+}
+base = gitOut(['rev-parse', base]).trim(); // 解析为 40 位 sha，顺带验证区间起点在本仓存在（不合法 loud fail）
+const head = gitOut(['rev-parse', 'HEAD']).trim();
+
+const log = gitOut(['log', '--no-merges', '--format=%H%x1f%B%x1e', `${base}..${head}`]);
+const violations = [];
+let total = 0;
+for (const rec of log.split('\u001e')) {
+  if (!rec.trim()) continue;
+  const [hash, body = ''] = rec.split('\u001f');
+  const first = body.split(/\r?\n/)[0] || '';
+  total++;
+  if (exemptRe.test(first) || typeRe.test(first)) continue;
+  violations.push({ hash, first });
+}
+
+const span = `${base.slice(0, 12)}..${head.slice(0, 12)}`;
+if (violations.length) {
+  console.error(`ci-commit-hygiene: 区间 ${span}（基准=${baseSource}）共 ${total} 笔（不含合并提交），${violations.length} 笔消息违规：`);
+  for (const v of violations) console.error(`  ${v.hash}  首行：${v.first || '（空首行）'}\n    原因：提交类型须为 ${types.join('/')}（AGENTS.md「git提交」）`);
+  process.exit(1);
+}
+console.log(`ci-commit-hygiene: 区间 ${span}（基准=${baseSource}）共 ${total} 笔（不含合并提交），0 违规`);

package/templates/engine/.agents/scripts/ci-install-gitleaks.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// ci-install-gitleaks — CI agent 尽力装机 gitleaks 至 .agents/tools/（2026-10-15 papercut 消债；
+//   2026-10-29 改「尽力而为」：装不上不再拦 build）。
+// 背景：verify 安全段 secrets-scan（check-secrets.mjs）解析序 = GITLEAKS_BIN → PATH → .agents/tools/。
+//   2026-10-29 起三处皆缺时不再 loud-skip，而是自动接续纯 Node 兜底扫描（check-secrets-lite.mjs）。
+//   故 CI 装机失败不再等于「密钥门不设防」——只等于「执法者降级为 lite」，不该拦整条流水线。
+// 行为：
+//   ① PATH 上已有匹配版本 → 幂等直过；② .agents/tools/ 已有匹配版本 → 幂等直过；
+//   ③ 否则从 GitHub releases 下 zip 解压（下载 20s 超时、解压/核验失败均不阻断）；
+//   ④ 任何失败 = exit 0 + 醒目告警（交由 check-secrets 的 lite 兜底），只有提示信息写日志。
+// 需要「装不上就红」的场合：设 SECRETS_SCAN_REQUIRE_GITLEAKS=1（check-secrets 会 fail-closed exit 2）。
+// 版本锚 8.30.1：与本机及基线生成口径一致（runtime-env §6.3）。agent = 自托管 Windows（池 JAMTC），
+//   解压走 PowerShell Expand-Archive；非 win32 回退 tar -xf（bsdtar 可解 zip），供他日换池。
+// checkout clean:true 每跑重装（.agents/tools/ 在工作区内随清）——~10MB/跑 换确定性，缓存化留待再登记。
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const VERSION = '8.30.1';
+const win = process.platform === 'win32';
+const plat = win ? 'windows_x64' : 'linux_x64';
+const URL = `https://github.com/gitleaks/gitleaks/releases/download/v${VERSION}/gitleaks_${VERSION}_${plat}.zip`;
+const ROOT = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+const toolsDir = process.env.GITLEAKS_TOOLS_DIR || path.join(ROOT, '.agents', 'tools');
+const bin = path.join(toolsDir, win ? 'gitleaks.exe' : 'gitleaks');
+
+const ok = (cmd) => spawnSync(cmd, ['version'], { encoding: 'utf8' });
+const skip = (why) => {
+  console.log(`[ci-install-gitleaks] ⏭️ ${why}——密钥门执法者降级为 lite（纯 Node 兜底扫描，仍执法）；需要强执法面请把 gitleaks 预装到 agent PATH（runtime-env §6.3）`);
+  process.exit(0);
+};
+
+// ① PATH 上已有（运维预装的退路）
+const onPath = ok('gitleaks');
+if (onPath.status === 0 && String(onPath.stdout).includes(VERSION)) {
+  console.log(`[ci-install-gitleaks] 已装于 PATH（${VERSION}）——幂等跳过下载`);
+  process.exit(0);
+}
+
+// ② 工作区工具目录已有
+if (fs.existsSync(bin)) {
+  const p = ok(bin);
+  if (p.status === 0 && String(p.stdout).includes(VERSION)) {
+    console.log(`[ci-install-gitleaks] 已装机 ${VERSION}（${bin}）——幂等跳过下载`);
+    process.exit(0);
+  }
+  console.error('[ci-install-gitleaks] 既有二进制版本核验异常，尝试重装覆盖');
+}
+
+fs.mkdirSync(toolsDir, { recursive: true });
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gitleaks-ci-'));
+const zip = path.join(tmp, 'gitleaks.zip');
+console.log(`[ci-install-gitleaks] 下载 ${URL}`);
+let res;
+try {
+  res = await fetch(URL, { signal: AbortSignal.timeout(20000) });
+} catch (e) {
+  skip(`下载失败（${e.name === 'TimeoutError' ? '20s 超时' : e.code || e.message}；agent 可能不通外网）`);
+}
+if (!res.ok) skip(`下载失败 HTTP ${res.status}`);
+fs.writeFileSync(zip, Buffer.from(await res.arrayBuffer()));
+
+const extract = win
+  ? spawnSync('powershell', ['-NoProfile', '-Command', 'Expand-Archive', '-Path', zip, '-DestinationPath', tmp, '-Force'], { encoding: 'utf8' })
+  : spawnSync('tar', ['-xf', zip, '-C', tmp], { encoding: 'utf8' });
+if (extract.status !== 0) skip(`解压失败：${extract.stderr || '(无 stderr)'}`);
+const inner = path.join(tmp, win ? 'gitleaks.exe' : 'gitleaks');
+if (!fs.existsSync(inner)) skip(`解压产物缺 ${inner}（zip 结构变更？）`);
+fs.copyFileSync(inner, bin);
+fs.rmSync(tmp, { recursive: true, force: true });
+
+const p = ok(bin);
+if (p.status !== 0 || !String(p.stdout).includes(VERSION)) skip(`装机后版本核验失败（exit ${p.status}，out：${p.stdout}）`);
+console.log(`[ci-install-gitleaks] ✅ gitleaks ${VERSION} 装机完成：${bin}——check-secrets 将用 gitleaks 强执法`);