agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/hooks/check-notify-guard.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// check-notify-guard: 前端提示守卫门禁（intent 2026-09-19-auth-expiry-explicit-guard）
+// 红线：frontend/src 下禁止直接调用 antd 的 message.error / warning / warn / info——
+//       认证失效跳转期间这些提示必须能被静默，页面层发坏消息一律经 utils/notify.ts 的 notify.*。
+//       message.success / loading / open 不在守卫范围（正常提示），不拦。
+// 扫描面：全仓 frontend/src（非仅暂存区新增行，与 check-audit-fields 的渐进收口不同）——
+//         存量调用点已于 2026-09-19 一次性清零，故可直接全量扫描：既拦新增调用点，也暴露迁移遗漏。
+// 豁免：frontend/src/utils/notify.ts（守卫自身的实现，只有它允许直接调 message.error/warning/info）
+// 约定：违例输出到 stderr 并 exit 1；参数错误 exit 2；干净无输出 exit 0（对齐 check-architecture）
+// 自 check-notify-guard.sh 移植 node（2026-10-08 门禁去 sh 化第二批）——语义逐条对齐。
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+if (process.argv.length > 2) {
+  console.error(`用法: ${path.basename(process.argv[1])}（无参数；扫描面为全仓 frontend/src，不区分暂存区）`);
+  process.exit(2);
+}
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (gitRoot.error || gitRoot.status !== 0) {
+  console.error('check-notify-guard: 不在 git 仓库内,门禁 fail-closed,不静默放行');
+  process.exit(1);
+}
+process.chdir(gitRoot.stdout.trim());
+if (!fs.existsSync('frontend/src')) process.exit(0);
+
+const HIT = /message\.(error|warning|warn|info)\s*\(/;
+const hits = [];
+const walk = (dir) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (/\.(vue|ts)$/.test(e.name)) hits.push(p);
+  }
+};
+walk('frontend/src');
+
+const viol = [];
+for (const f of hits) {
+  const rel = f.replace(/\\/g, '/');
+  if (rel === 'frontend/src/utils/notify.ts') continue; // 守卫自身实现豁免
+  const lines = fs.readFileSync(f, 'utf8').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (!HIT.test(lines[i])) continue;
+    if (/^\s*(\/\/|\*|\/\*)/.test(lines[i])) continue; // 注释行不算违例
+    viol.push(`${rel}:${i + 1}:${lines[i]}`);
+  }
+}
+if (viol.length > 0) {
+  console.error('提示守卫违例：frontend/src 下直接调用 message.error/warning/info（应改经 notify.*，见 utils/notify.ts）：');
+  console.error(viol.join('\n'));
+  process.exit(1);
+}
+process.exit(0);

package/templates/engine/.agents/hooks/commit-check.cjs

@@ -0,0 +1,208 @@
+// commit-check: git commit 前置验证（本仓自有维护——decouple-flow-kit 起，原 agentic-flow-kit 通用版）
+// 1) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 不做 ext/prefix 裁剪，仍尊重 when）
+// 2) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 不做 ext/prefix 裁剪，仍尊重 when）
+// （敏感信息扫描段已退役——2026-10-21 owner 指令「密钥本地不扫」：本地双腿（本段正则 + pre-commit gitleaks
+//   protect 门）同批撤除，误报 papercut ×4 消债；执法收敛 verify 安全段 secrets-scan 关单/CI）
+// 旗标（2026-10-15 构建门后移 pre-push）：
+//   --no-build：跳过段 1 条件构建——pre-commit 常规提交用（提交内环提速）；构建在 pre-push 按推送范围
+//               执法，合并提交仍走 --full 全量构建（合并结果是没人验证过的新状态）。
+//   --range <old> <new>：推送范围模式（pre-push 用）——文件面取 git diff --name-only old new；
+//               old 为全零 sha（新分支首推）= 全量匹配语义（等价 --full 的构建面）。默认（无旗标）暂存区模式行为不变。
+// config（.agents/hooks/commit-check.config.json）为本仓自有件（engine 面豁免三件套）；缺失或无 builds/checks 时跳过对应段。
+// 配置示例（.agents/hooks/commit-check.config.json）：
+//   {
+//     "builds": [
+//       { "name": "backend",  "command": "dotnet build", "ext": [".cs", ".sln", ".csproj"] },
+//       { "name": "frontend", "command": "npm run build", "ext": [".ts", ".tsx", ".vue", ".js", ".jsx"],
+//         "cwd": "frontend",
+//         "lockPattern": "MSB3026|MSB3027",                        // 可选：命中时按 lockHint 提示（文件锁类「与代码无关」失败）
+//         "lockHint": "构建被文件锁拦下——本地运行中的进程正占用产物，停进程后重试" },
+//       { "name": "docs-site", "command": "npm run build", "prefix": "docs/", "cwd": "docs" }   // prefix 可选：路径前缀触发
+//     ],
+//     "checks": [
+//       { "name": "typecheck", "command": "npx tsc --noEmit", "ext": [".ts", ".tsx"], "when": ["tsconfig.json"] },
+//       { "name": "lint",      "command": "npx eslint .", "ext": [".ts", ".js"], "when": ["eslint.config.js", ".eslintrc.json"] }
+//     ]
+//   }
+// builds/checks 触发判定（对暂存文件；builds 不计 .agents/ 与 .githooks/ 自身变更，checks 不计 .githooks/——引擎脚本变更照跑秒级检查）：`ext 任一匹配 OR prefix 前缀命中`。
+//   - 只有 ext：按扩展名全局触发（跨目录，适合语言型触发——仓库里该扩展名基本只属于该构建）；
+//   - 只有 prefix：该前缀下任何文件触发（目录型触发——如 monorepo 子包，仓库其他位置的相同扩展名不触发）；
+//   - 两者同配为 OR 并集而非 AND 交集——要「前缀内的特定扩展名」请只配 prefix（目录内文档变更多跑一次构建，方向安全）。
+// when（builds 与 checks 共用）：数组任一满足才启用，无 when 字段 = 无条件启用。
+//   - 路径或尾部 * 一层通配（如 "*.sln"）：相对仓库根做存在性判断；
+//   - pkg:<点分路径>（如 pkg:scripts.build）：读该项 cwd（缺省仓库根）的 package.json，
+//     沿路径取值，非空字符串才算满足。
+//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦。--full 同样尊重 when。
+// 条件构建执行器（2026-10-07 L31：execSync → spawnSync + 显式 timeout）
+// 症状：托管 Node 22 下 execSync('cd frontend && npm run build') **永不返回**——
+//   vite 8 / rolldown 在 Windows 泄漏 stdout 管道句柄，构建产物实际已写完，但父进程
+//   的读端等不到 EOF → pre-commit 永久挂起，任何含 frontend/ 的提交都卡死
+//   （实测换系统 Node 24 后同一命令 12.6s 正常返回）。
+// 修法：spawnSync 传 timeout，到点判失败而非无限等；spawnSync.error 的 ETIMEDOUT
+//   即超时信号。stdio 沿用 'pipe'（须收 stdout 供失败时打错误行），但 spawnSync 的
+//   pipe 不依赖子进程主动关闭——父进程按固定长度读，泄漏句柄不再导致挂死。
+// 契约不变：返回 { ok, out }，调用方（128/155 行）按字符串消费 out。
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// 构建类命令的墙钟上限（毫秒）。npm run build 实测 12.6s / dotnet build 数十秒，
+// 取 10 分钟兼顾慢机与「本该 90 秒内结束」的挂起场景——远小于原来的永不返回。
+const BUILD_TIMEOUT_MS = 10 * 60 * 1000;
+
+process.chdir(path.resolve(__dirname, '../..'));
+
+function sh(cmd, cwd) {
+  try {
+    const r = spawnSync(cmd, {
+      shell: true,                       // 命令串含 && 与路径空格，沿用原 shell 语义
+      encoding: 'utf8',
+      cwd: cwd || undefined,
+      timeout: BUILD_TIMEOUT_MS,         // 到点 kill，判失败（不再无限等待）
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    if (r.error) {
+      const timedOut = r.error.code === 'ETIMEDOUT';
+      return {
+        ok: false,
+        out: (timedOut ? `[超时] 命令超过 ${BUILD_TIMEOUT_MS / 1000}s 未结束，已终止（kill 直接子进程，孙进程可能残留）：${cmd}\n` : `[spawn 失败] ${r.error.code || r.error.message}\n`)
+          + String((r.stdout || '') + (r.stderr || '')),
+      };
+    }
+    if (r.status !== 0) {
+      return { ok: false, out: String((r.stdout || '') + (r.stderr || '')) };
+    }
+    return { ok: true, out: String(r.stdout || '') };
+  } catch (e) {
+    return { ok: false, out: String(e.stdout || '') + String(e.stderr || '') + String(e.message || '') };
+  }
+}
+
+// --- 模式旗标（2026-10-15 构建门后移 pre-push；sha 经 git 管道来仍做白名单校验——信任边界） ---
+const NO_BUILD = process.argv.includes('--no-build');
+const rangeIdx = process.argv.indexOf('--range');
+const RANGE = rangeIdx >= 0 ? process.argv.slice(rangeIdx + 1, rangeIdx + 3) : null;
+if (RANGE && (RANGE.length < 2 || !/^[0-9a-f]{4,40}$/i.test(RANGE[0]) || !/^[0-9a-f]{4,40}$/i.test(RANGE[1]))) {
+  console.log(`BLOCK: --range 参数须为两个 git sha（现「${(RANGE || []).join(' ')}」）`);
+  process.exit(1);
+}
+// 全零 old = 新分支首推：git diff 对全零 sha 无从执行，且本就取全量匹配语义——文件面置空即可
+const RANGE_ZERO_OLD = RANGE !== null && /^0+$/.test(RANGE[0]);
+
+let staged = [];
+try {
+  // 2026-11-06（P1-4 同族）：变更面读取统一带 `-c core.quotepath=off`——默认 quotepath=true 下
+  // 非 ASCII 路径被转义（`"frontend/\346\226..."`），下游按路径前缀匹配的门会静默漏判。
+  // （当前 frontend/ 下无中文路径，影响面暂为 0；口径与 pre-commit/pre-push/test-impact-lib 对齐。）
+  const listCmd = !RANGE ? 'git -c core.quotepath=off diff --cached --name-only'
+    : RANGE_ZERO_OLD ? null
+    : `git -c core.quotepath=off diff --name-only ${RANGE[0]} ${RANGE[1]}`;
+  staged = listCmd === null ? []
+    : execSync(listCmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split('\n').map(s => s.trim()).filter(Boolean);
+} catch (e) {
+  console.log('BLOCK: 无法读取变更文件面（git diff 失败）');
+  process.exit(1);
+}
+
+// --- 0) 项目配置（可选） ---
+let config = { builds: [] };
+try {
+  const raw = JSON.parse(fs.readFileSync('.agents/hooks/commit-check.config.json', 'utf8'));
+  config = { ...config, ...raw };
+} catch (e) { /* 无配置 = 跳过构建验证 */ }
+
+// --- 1) 条件构建验证 ---
+// --full：合并提交（pre-merge-commit / 冲突解决后手动 commit）使用——合并结果是没人验证过的新状态，
+// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做路径裁剪。when 仍生效：没有对应能力就不跑。
+// --range 全零 old sha（新分支首推）同取全量匹配语义。
+// 引擎自身文件（.agents/、.githooks/）不参与构建匹配——工作流引擎不是项目构建产物。
+const FULL = process.argv.includes('--full') || RANGE_ZERO_OLD;
+const stagedForBuild = staged.filter(f => !f.startsWith('.agents/') && !f.startsWith('.githooks/'));
+// 质量检测面（2026-11-10 dev-tour 测试门接线）：checks 是秒级确定性检查，引擎脚本（.agents/）变更同样要过；
+// builds 面维持排除引擎（工作流引擎不是项目构建产物），.githooks/ 对两者都不计。
+const stagedForChecks = staged.filter(f => !f.startsWith('.githooks/'));
+
+// whenSatisfied：任一谓词满足即启用。pkg: 读 cwd 下的 package.json；其余谓词相对仓库根。
+function whenItem(w, cwd) {
+  if (typeof w === 'string' && w.startsWith('pkg:')) {
+    const keys = w.slice(4).split('.').filter(Boolean);
+    if (!keys.length) return false;
+    const pkgPath = path.join(cwd || '.', 'package.json');
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch (e) { return false; }
+    let cur = pkg;
+    for (const k of keys) {
+      if (cur == null || typeof cur !== 'object' || !Object.prototype.hasOwnProperty.call(cur, k)) return false;
+      cur = cur[k];
+    }
+    return typeof cur === 'string' && cur.trim() !== '';
+  }
+  const star = String(w).indexOf('*');
+  if (star < 0) return fs.existsSync(w);
+  const suffix = w.slice(star + 1);
+  const dir = path.dirname(w.slice(0, star)) || '.';
+  try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
+}
+function whenSatisfied(when, cwd) {
+  if (!when) return true;
+  const list = Array.isArray(when) ? when : [when];
+  return list.some((w) => whenItem(w, cwd));
+}
+function skipWhen(kind, item) {
+  const shown = Array.isArray(item.when) ? item.when.join(' / ') : item.when;
+  console.log(`SKIP: ${item.name}（未找到 ${shown}，跳过${kind}——配置好后自动启用）`);
+}
+
+if (NO_BUILD) {
+  console.log('SKIP: --no-build（2026-10-15 构建门后移 pre-push——常规提交不再构建，推送时按范围执法）');
+} else {
+  let consideredBuild = false;
+  for (const b of (config.builds || [])) {
+    if (!b || !b.command) continue;
+    const exts = Array.isArray(b.ext) ? b.ext : [];
+    const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (b.prefix ? f.startsWith(b.prefix) : false));
+    if (!match) continue;
+    consideredBuild = true;
+    if (!whenSatisfied(b.when, b.cwd)) { skipWhen('构建', b); continue; }
+    const r = sh(b.command, b.cwd);
+    if (!r.ok) {
+      if (b.lockPattern && new RegExp(b.lockPattern).test(r.out)) {
+        console.log(`BLOCK: ${b.name} 构建被文件锁拦下（与代码无关）。${b.lockHint || '停掉占用进程后原路重试'}\n` +
+          '锁冲突行：\n' + r.out.split(/\r?\n/).filter(l => new RegExp(b.lockPattern).test(l)).slice(0, 3).join('\n'));
+      } else {
+        console.log(`BLOCK: ${b.name} 构建失败（${b.command}）\n` + r.out.slice(0, 1500));
+      }
+      process.exit(1);
+    }
+    console.log(`OK: ${b.name} 构建通过（${b.command}）`);
+  }
+  if (!consideredBuild) {
+    console.log(config.builds && config.builds.length
+      ? 'SKIP: 无匹配的源码变更，跳过构建验证'
+      : 'SKIP: 未配置 builds（.agents/hooks/commit-check.config.json），跳过构建验证');
+  }
+}
+
+// --- 2) 质量检测（checks：lint / 类型检查 / vet 等秒级确定性检查；测试不放这里——关单在 stages.md Test 章阶段门） ---
+let ranCheck = false;
+for (const c of (config.checks || [])) {
+  if (!c || !c.command) continue;
+  const exts = Array.isArray(c.ext) ? c.ext : [];
+  const match = FULL || stagedForChecks.some(f => exts.some(e => f.endsWith(e)) || (c.prefix ? f.startsWith(c.prefix) : false));
+  if (!match) continue;
+  ranCheck = true;
+  if (!whenSatisfied(c.when, c.cwd)) { skipWhen('质量检查', c); continue; }
+  const r = sh(c.command, c.cwd);
+  if (!r.ok) {
+    console.log(`BLOCK: ${c.name} 质量检查未通过（${c.command}）\n` + r.out.slice(0, 1200));
+    process.exit(1);
+  }
+  console.log(`OK: ${c.name} 质量检查通过（${c.command}）`);
+}
+if (!ranCheck && config.checks && config.checks.length) {
+  console.log('SKIP: 无匹配的源码变更，跳过质量检测');
+}
+
+console.log('COMMIT_CHECK_OK');

package/templates/engine/.agents/hooks/gates.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "PreToolUse 命令门禁清单（单源）。mirrorOf 指向项目安全下限；exempt 为刻意缺省项，须写明原因，防静默漂移。宿主壳（.trae/hooks.json / .zcode/config.json / .codebuddy/settings.json）只接线指向 .agents/hooks/pre-shell-check.cjs，不复制脚本（2026-10-29 owner 单源指示）。",
+  "mirrorOf": ".agents/settings.json#/permissions",
+  "exempt": [
+    {
+      "item": "dotnet ef",
+      "reason": "EF Migrations 禁令属 dotnet-ca 门禁域（提交时拦截）；此处重复会形成双源漂移"
+    },
+    {
+      "item": "git push --force",
+      "reason": "由 pre-shell-check.cjs 的 isForcePush() 做 token 化判定，覆盖面强于子串匹配（含 -f、+refspec、参数换序）"
+    },
+    {
+      "item": "git push -f",
+      "reason": "同上，并入 isForcePush() token 化判定"
+    },
+    {
+      "item": "commit 短旗标簇 / shell 展开（$、反引号）/ hooksPath 配置注入 / 一次性别名 / 大括号展开",
+      "reason": "由 pre-shell-check.cjs isNoVerify 与 1b 块代码层执法（2026-11-09 评审多轮收敛：扁平域/物化/闭集枚举，子串清单不可表达；长旗标已另列 deny 行作子串面镜像）"
+    }
+  ],
+  "deny": [
+    { "pat": "git reset --hard", "reason": "禁破坏性重置" },
+    { "pat": "drop database", "reason": "禁删库" },
+    { "pat": "--no-verify", "reason": "禁绕过 git 钩子（commit/merge/push 三处一律禁，AGENTS.md §2；与 isNoVerify 代码层互补：此行覆盖子串面兜底，代码层覆盖短旗标/展开/注入闭集）" }
+  ],
+  "ask": [
+    { "pat": "git checkout", "reason": "可能切换/丢弃工作区改动" },
+    { "pat": "git clean", "reason": "可能删除未跟踪文件" },
+    { "pat": "git branch -D", "reason": "可能删除未合并分支" },
+    { "pat": "rm -rf", "reason": "可能递归删除文件" }
+  ]
+}

package/templates/engine/.agents/hooks/local-pre-commit.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// 项目门禁挂载点（.githooks/pre-commit 在通用门禁之后执行本文件；返回非零即阻断提交）
+// 回流迁移（2026-09-24）：原 pre-commit 直连的 4 个项目门禁改经本挂载点接线，行为等价
+// 任一门禁非零即透传其退出码（沿 sh 版 set -e 语义）——不要在末尾无条件 exit 0
+// 自 local-pre-commit(sh) 移植 node（2026-10-08 门禁去 sh 化第二批）
+// gate-diet 轻量化：四门并行起跑（实测串行 0.71s → 并行 ≈最慢一门），输出管道捕获后
+//   按原顺序重放——四门均为只读扫描器、无共享写状态，并行安全；退出码语义不变（首个非零即透传）
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+
+const HERE = path.dirname(process.argv[1]);
+const GATES = ['check-architecture.mjs', 'check-audit-fields.mjs', 'check-delete-guard.mjs', 'check-notify-guard.mjs'];
+const results = await Promise.all(GATES.map((gate) => new Promise((resolve) => {
+  const child = spawn(process.execPath, [path.join(HERE, gate)], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { out += d; });
+  child.on('error', (err) => resolve({ status: 1, out: `${gate} 启动失败: ${err}` }));
+  child.on('close', (code) => resolve({ status: code === null ? 1 : code, out }));
+})));
+let rc = 0;
+for (const r of results) {
+  if (r.out) process.stdout.write(r.out);
+  if (r.status !== 0 && rc === 0) rc = r.status;
+}
+process.exit(rc);