@customize-agent/server 4.59.2 → 4.60.0

package/scripts/half-built-scan.mjs

@@ -1,35 +1,9 @@
 #!/usr/bin/env node
-/**
- * 半成品扫描器（2026-09-28）。
- *
- * ## 为什么要有它
- * 用户口径：「每次问你都会遗漏很多东西，都会有很多都是半成品」。
- * 结构性原因不是"不够仔细"，而是：**仓库里已有九份缺口账本，散在九个文件里，没有一处汇总**——
- * 所以任何一次凭记忆回答都必然只覆盖一两份（见 `docs/half-built-inventory-2026-09-28.md` 第零节）。
- *
- * 本脚本负责的是**账本记不住的那一类**：**声明了、实现了，但生产代码里零调用点**。
- *
- * ## 判定口径（刻意保守）
- * 对每个导出符号分别统计：
- * - `inFile`：**本文件内**引用次数（扣掉声明行本身）——>0 说明它是模块内部实现的一部分（正常）；
- * - `otherProd`：**其它生产文件**引用次数——**这是唯一判定"接线与否"的量**；
- * - `tests`：测试目录引用次数——>0 且 otherProd=0 = **典型的"只在测试里活着"**。
- *
- * 三种分类：
- * | 分类 | 判据 | 含义 |
- * |---|---|---|
- * | 半成品嫌疑 | otherProd=0 且 tests>0 | 写好了、测过了，生产里没人用 |
- * | 谁都不用 | inFile=0 且 otherProd=0 且 tests=0 | 真死代码，或被取代的旧 API |
- * | 封装暴露 | otherProd=0 但 inFile>0 | 只是导出给测试用，**不是**半成品 |
- *
- * ## 已知局限（写在这里，免得被当成结论用）
- * - **动态引用识别不了**：`await import('...')`、字符串派发、计算属性访问都会漏判 ⇒ 会误报；
- * - 因此本脚本的输出是**候选清单**，逐条必须 grep 复核后才能写进账本；
- *   实测教训：本轮用它测"画布标签表"，头两版都测错（表其实是完整的），最后以读文件逐键核对为准。
- *
- * ## 用法
- *   node apps/server/scripts/half-built-scan.mjs                       # 全仓
- *   node apps/server/scripts/half-built-scan.mjs apps/server/src/services  # 指定目录
+/** 文本引用候选扫描，覆盖源码、测试和脚本，供实际调用闭包审查使用。
+ * 新增零引用导出、未处置的仅测试引用与星号转导出候选均阻断；其他增量显式报告。
+ * 转导出、动态派发、类型引用与副作用需独立核查，不能据文本数量删除实际入口。
+ * 基线只收紧已退休条目；登记仅允许有具体用途的观察/测试面，不能掩盖未接入业务。
+ * 用法：node apps/server/scripts/half-built-scan.mjs --full --gate --baseline <file>
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -38,10 +12,56 @@ import { fileURLToPath } from 'node:url';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(HERE, '../../..');           // 仓库根
 const DEFAULT_DIRS = ['apps/server/src', 'packages'];
-const DIRS = process.argv.slice(2).length > 0 ? process.argv.slice(2) : DEFAULT_DIRS;
+const ARGS = process.argv.slice(2);
+/**
+ * ★ D1（2026-09-28）：`--full` 打印**全量**清单（默认只列前 30 条）。
+ * 批量清理时要的是完整名单（"列前 30" 只够读一眼，不够动手）。
+ */
+const FULL = ARGS.includes('--full');
+/**
+ * ★ G2（2026-09-29）：**带值的开关必须把它的值一起从位置参数里摘掉**。
+ *
+ * 旧实现 `ARGS.filter(arg => !arg.startsWith('--'))` 只滤旗标 ⇒ `--baseline foo.json`
+ * 会把 `foo.json` 当成"扫描目录"传进 `DIRS`，于是报告范围变成"仓库根下的 foo.json"
+ * （**静默空扫**：所有计数归零，门禁恒绿）。这正是本脚本注释里反复出现的同一类错：
+ * 工具安静地给出错误结论比不给结论更糟。
+ */
+const VALUE_FLAGS = new Set(['--baseline', '--write-baseline']);
+const POSITIONAL = [];
+for (let i = 0; i < ARGS.length; i++) {
+  if (VALUE_FLAGS.has(ARGS[i])) {
+    // ★ 只吞"真像值"的下一个参数：`--write-baseline --gate` 里 `--gate` 是旗标，
+    // 吞掉它等于把这个开关静默吃掉（同"静默空扫"一类错）。
+    if (ARGS[i + 1] !== undefined && !ARGS[i + 1].startsWith('--')) i++;
+    continue;
+  }
+  if (ARGS[i].startsWith('--')) continue;
+  POSITIONAL.push(ARGS[i]);
+}
+const DIRS = POSITIONAL.length > 0 ? POSITIONAL : DEFAULT_DIRS;
+
+const GATE = ARGS.includes('--gate');
+const flagValue = name => {
+  const i = ARGS.indexOf(name);
+  return i >= 0 ? ARGS[i + 1] : undefined;
+};
+const BASELINE_ARG = flagValue('--baseline');
+const WRITE_BASELINE_ARG = flagValue('--write-baseline');
+/** 默认基线路径：与脚本同目录（CI 与本地同一条路径） */
+const DEFAULT_BASELINE = path.join(HERE, 'half-built-scan.baseline.json');
 
 const TEST_HINT = /(^|\/)(test|tests|__tests__|__mocks__)\//;
+/** 报告范围：只报 `.ts`/`.tsx` 的导出符号 */
 const isSource = file => /\.(ts|tsx)$/.test(file) && !/\.d\.ts$/.test(file);
+/**
+ * ★ 2026-09-29：**引用池要收 `.cjs`/`.mjs`/`.js`**（此前只收 `.ts/.tsx`，是最后一个已知假阳性源）。
+ *
+ * 实测代价：`searchKb`（`lib/api.ts`）只被 `scripts/upload-matrix.cjs` 用着，却因 `.cjs` 不在池里
+ * 被判成"谁都不用"——`gitignore` 级的工具盲区会让清理任务删掉在用的代码。
+ * 与"D1 把测试目录收进池子"是同一类修正：**引用池必须覆盖全部消费者**。
+ * （报告范围仍是 `.ts/.tsx`：`.cjs/.mjs` 不进清单，只当引用来源。）
+ */
+const isPoolFile = file => /\.(ts|tsx|cjs|mjs|js)$/.test(file) && !/\.d\.ts$/.test(file);
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.next', 'coverage']);
 
 function walk(dir, out = []) {
@@ -51,7 +71,7 @@ function walk(dir, out = []) {
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name)) continue;
       walk(full, out);
-    } else if (isSource(full)) out.push(full);
+    } else if (isPoolFile(full)) out.push(full);
   }
   return out;
 }
@@ -63,13 +83,68 @@ function walk(dir, out = []) {
  * `document-workflow` 的 `closePhaseNode` / `closeDanglingConnections` 被误报成"谁都不用"。
  * **工具撒谎比没有工具更糟**：这会让人去删正在用的代码。
  */
-const ALL_DIRS = DEFAULT_DIRS;
-const allFiles = ALL_DIRS.flatMap(dir => walk(path.resolve(ROOT, dir)));
+/**
+ * ★ D1（2026-09-28）修正：**引用池必须覆盖测试与脚本目录**。
+ *
+ * 原实现 `const ALL_DIRS = DEFAULT_DIRS`（= `['apps/server/src','packages']`）与下面那句
+ * 「报告范围 = 参数；**引用池 = 全仓**」的**注释意图相反**：测试目录与脚本不在池子里，
+ * 于是 `tests=0` 从来就不是"测试也不用"，而是"没查过测试"。
+ *
+ * 代价实测：一次清理任务按它的"谁都不用（140 条）"逐条真 grep 复核，**133 条被拦下**——
+ * 误报率 96%（`getKbTags` 这类"只在测试里活着"的根本没被算进去）。
+ * 一个 96% 误报的清单比没有清单更危险：照着它删就是成片删掉在用的东西。
+ */
+const REFERENCE_DIRS = ['apps/server/src', 'apps/server/test', 'apps/server/scripts', 'packages', 'scripts'];
+
+/**
+ * ★ 2026-09-29：**`export *` 再导出的文件不可判**（第二个已知盲区，与 `.cjs` 消费者同类）。
+ *
+ * `export * from './x'` 让 `x` 的每个符号都可达外部，但**没有任何地方提到那些符号名**——
+ * 于是它们会被三分类静默吞掉（既不在 otherProd，也不在 inFile/test），看起来像"封装暴露/谁都不用"。
+ * 实测本仓有 14 个这样的文件（`types/index.ts`、`constants/index.ts`、`chapterGeneration.ts` 等）。
+ * 后果与"照着 96% 误报清单删代码"同型：**工具撒谎比没有工具更糟**。
+ * 处置：这些文件里的符号**不进任何清单**，改为在报告末尾单独列出（人工判），
+ * 并在 `--csv` 里标 `verdict=不可判（星号再导出）`。
+ */
+function starReExportTargets() {
+  const targets = new Set();
+  for (const file of allFiles) {
+    const text = texts.get(file) ?? '';
+    for (const m of text.matchAll(/^\s*export \*\s*(?:as\s+\w+\s*)?from\s*'(\.[^']+)'/gm)) {
+      const base = path.resolve(path.dirname(file), m[1]);
+      for (const cand of [`${base}.ts`, `${base}.tsx`, path.join(base, 'index.ts')]) {
+        if (fs.existsSync(cand)) { targets.add(cand); break; }
+      }
+    }
+  }
+  return targets;
+}
+/**
+ * ⚠️ **不把 `docs/` 放进引用池**：文档是散文，而且本仓的文档里大量是**缺口清单**
+ * （"这条写好没接线"）——把清单算成"有引用"，会让真死代码因为它被记过一笔而永远不被清理。
+ * 文档命中的符号由**人**处置（要么接上、要么连同条目一起删），不交给扫描器自动判。
+ * 另一个已知盲区：`.cjs`/`.mjs`/`.js` 消费者（`isSource` 只认 .ts/.tsx）——
+ * 实测 `searchKb` 只被 `scripts/upload-matrix.cjs` 用着，曾因此被误判为死代码。
+ */
+const ALL_DIRS = REFERENCE_DIRS;
+/**
+ * ★ 2026-09-29：**引用池必须剔除本脚本自身**（第三个盲区，且是最隐蔽的一个）。
+ *
+ * 本脚本的注释里**点名**了一堆过去被判死的符号（`searchKb`、`getKbTags` 那批）——
+ * 收进 `.cjs/.mjs` 池之后，脚本读自己，**自己的散文成了"引用"**：`searchKb` 于是从"谁都不用"
+ * 消失（假阴性），而它其实真的零调用（`grep -rn searchKb --include=*.cjs` = 0）。
+ * **工具把自己算成消费者 = 用自己的注释证明自己没错**。剔除自身后结论才可核。
+ */
+const SELF = fileURLToPath(import.meta.url);
+const allFiles = ALL_DIRS.flatMap(dir => walk(path.resolve(ROOT, dir)))
+  .filter(file => path.resolve(file) !== path.resolve(SELF));
 const texts = new Map(allFiles.map(f => [f, fs.readFileSync(f, 'utf8')]));
 const prod = allFiles.filter(f => !TEST_HINT.test(f));
 const tests = allFiles.filter(f => TEST_HINT.test(f));
 const scopeRoots = DIRS.map(dir => path.resolve(ROOT, dir));
 const inScope = file => scopeRoots.some(root => file.startsWith(root + path.sep) || file === root);
+/** 被 `export *` 再导出的文件（其符号名不会被任何地方提到 ⇒ 不可判，见上文说明） */
+const STAR_REEXPORTED = starReExportTargets();
 
 const EXPORT_PATTERNS = [
   [/^export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm, 'fn'],
@@ -106,9 +181,10 @@ for (const file of prod) {
       if (otherProd > 0) continue;
       rows.push({
         rel, name, kind, inFile, testRefs,
-        verdict: inFile === 0 && testRefs === 0 ? '谁都不用'
-          : inFile === 0 && testRefs > 0 ? '半成品嫌疑'
-            : '封装暴露（只导出给测试）',
+        verdict: STAR_REEXPORTED.has(file) ? '不可判（星号再导出）'
+          : inFile === 0 && testRefs === 0 ? '谁都不用'
+            : inFile === 0 && testRefs > 0 ? '半成品嫌疑'
+              : '封装暴露（只导出给测试）',
       });
     }
   }
@@ -117,34 +193,178 @@ for (const file of prod) {
 const byVerdict = verdict => rows.filter(r => r.verdict === verdict);
 const suspect = byVerdict('半成品嫌疑');
 const unused = byVerdict('谁都不用');
+const undecidable = byVerdict('不可判（星号再导出）');
+
+/**
+ * ★ 2026-09-30（用户口径：**这类清单不许推给人**）：**登记表**把"设计如此的测试/观察/登记面"
+ * 从"半成品嫌疑"里分出来——登记条目**带理由**（`half-built-scan.allow.json`，改一项也要改理由），
+ * 不进"未登记"计数；新增的零引用导出会落进**未登记** ⇒ 当场判（接线 / 删除 / 登记）。
+ */
+const ALLOW_PATH = path.join(HERE, 'half-built-scan.allow.json');
+const allowed = (() => {
+  try {
+    const file = JSON.parse(fs.readFileSync(ALLOW_PATH, 'utf8'));
+    const map = new Map();
+    for (const entry of file.entries || []) map.set(`${entry.file}::${entry.symbol}`, entry.reason);
+    return map;
+  } catch {
+    return new Map();
+  }
+})();
+const registered = suspect.filter(row => allowed.has(`${row.rel}::${row.name}`));
+const unregistered = suspect.filter(row => !allowed.has(`${row.rel}::${row.name}`));
+/** ★ 2026-09-30：**"不可判"也进同一张登记表**（星号再导出里既有"本文件内自用"也有测试面——都登记，别留待判） */
+const undecidableRegistered = undecidable.filter(row => allowed.has(`${row.rel}::${row.name}`));
+const undecidableUnregistered = undecidable.filter(row => !allowed.has(`${row.rel}::${row.name}`));
 
 console.log('════════ 半成品扫描 ════════');
 console.log(`扫描范围：${DIRS.join(', ')}（引用池 = 全仓 ${prod.length} 个生产文件 / ${tests.length} 个测试文件）`);
 console.log(`导出符号在他处生产零引用：${rows.length}`);
-console.log(`  · 半成品嫌疑（仅测试引用）    ${suspect.length}`);
+console.log(`  · 半成品嫌疑（仅测试引用）    ${suspect.length}（**未登记 ${unregistered.length}** / 已登记 ${registered.length}）`);
 console.log(`  · 谁都不用（含自身文件）      ${unused.length}`);
 console.log(`  · 封装暴露（本文件内自用）    ${byVerdict('封装暴露（只导出给测试）').length}`);
+console.log(`  · 不可判（星号再导出）        ${undecidable.length}（**未登记 ${undecidableUnregistered.length}** / 已登记 ${undecidableRegistered.length}）`);
+
+/**
+ * ★ 2026-09-29：`--csv` 输出可处理名单（`rel,name,kind,inFile,testRefs,verdict`）。
+ * 批量清理要的是**能进表格/能过脚本**的名单，不是给人读的缩进文本。
+ */
+if (ARGS.includes('--csv')) {
+  console.log('file,name,kind,inFile,testRefs,verdict');
+  for (const row of rows) {
+    console.log([row.rel, row.name, row.kind, row.inFile, row.testRefs, row.verdict].join(','));
+  }
+  process.exit(0);
+}
 
 const print = (title, list, limit = 40) => {
   if (list.length === 0) return;
-  console.log(`\n── ${title}（${list.length} 条，列前 ${Math.min(limit, list.length)}）`);
-  for (const row of list.slice(0, limit)) {
+  console.log(`\n── ${title}（${list.length} 条${FULL ? '' : `，列前 ${Math.min(limit, list.length)}`}）`);
+  for (const row of (FULL ? list : list.slice(0, limit))) {
     console.log(`   ${row.rel}  ::  ${row.name}${row.testRefs ? `  (测试引用 ${row.testRefs})` : ''}`);
   }
 };
-print('半成品嫌疑', suspect);
+print('半成品嫌疑 未登记（**要当场判**：接线 / 删除 / 写进登记表并给理由）', unregistered);
+print('半成品嫌疑 已登记（测试/观察/登记面，理由见 half-built-scan.allow.json）', registered);
+if (registered.length > 0 && FULL) {
+  for (const row of registered) console.log(`   · ${row.rel} :: ${row.name} —— ${allowed.get(`${row.rel}::${row.name}`)}`);
+}
 print('谁都不用', unused, 30);
+print('不可判（星号再导出：符号可达但没有名字被提到，本脚本判不了）', undecidable, 10);
+
+console.log('\n完整整改与实际运行证据见 docs/project-improvements/2026-10-11-status-and-architecture.md。');
+console.log('本扫描仅提供文本引用候选；转导出、动态入口、内部可达依赖和副作用需按实际调用另行核查。');
+
+// ═══════════════════════════ 门禁（G2，2026-09-29）═══════════════════════════
+/**
+ * 口径全文在文件头「## 门禁口径（G2）」一节。这里只写实现锚点：
+ * - **四类计数 + 四类名录**都进基线（名录让"新增了什么"可以逐条打出来，而不是只给一个差值）；
+ * - **只有「谁都不用」红**；其余三类超基线只 `⚠`（理由：366 条"封装暴露"是刻意形态，
+ *   判红 = 每加一个测试用导出就挂 CI = 门禁当天就该被绕过）；
+ * - 基线文件缺失时「谁都不用」按 **0** 判（零容忍），其余三类不做棘轮比较（没有基线就没有差值）。
+ */
+const VERDICT_KEYS = ['谁都不用', '半成品嫌疑', '封装暴露（只导出给测试）', '不可判（星号再导出）'];
+const GATED_KEY = '谁都不用';
+const counts = Object.fromEntries(VERDICT_KEYS.map(key => [key, rows.filter(row => row.verdict === key).length]));
+const roster = Object.fromEntries(VERDICT_KEYS.map(key => [
+  key,
+  rows.filter(row => row.verdict === key).map(row => `${row.rel}::${row.name}`).sort(),
+]));
+
+/** 基线文件路径：`--baseline <file>` 显式给的优先；`--write-baseline [file]` 同理 */
+const writeBaselineTarget = WRITE_BASELINE_ARG !== undefined && !WRITE_BASELINE_ARG.startsWith('--')
+  ? WRITE_BASELINE_ARG
+  : DEFAULT_BASELINE;
+const baselinePath = BASELINE_ARG ? path.resolve(process.cwd(), BASELINE_ARG) : DEFAULT_BASELINE;
 
-console.log('\n════════ 另外九份账本（本脚本扫不到，必须一起看）════════');
-for (const line of [
-  'L1 A/B 接线缺口          test/services/agent/detailLayerWiring.test.ts 的 WIRING_GAPS',
-  'L2 N 类判据处置表        document-workflow/nClassJudges.ts 的 N_CLASS_JUDGE_DISPOSITIONS',
-  'L3 写作期处置欠账        detectorFixerRegistry.ts 的 PENDING_WRITING_TIME_DISPOSITION',
-  'L4 未锚定修复轮          agent/tools/repairRounds.ts 的 unanchoredRepairRounds()',
-  'L5 manual 检测器         detectorFixerRegistry 的 fixerDisposition==="manual"（54 条）',
-  'L6 工具面空壳（已删）    services/agent/toolRegistry.ts 的删除记录',
-  'L7 91 条对照表缺口       docs/closure-checklist-mapping-2026-09-28.md',
-  'L8 机制级缺口            docs/judgment-completeness-2026-09-28.md',
-  'L9 零生产者节点类型      docs/half-built-inventory-2026-09-28.md 第一节',
-]) console.log(`   ${line}`);
-console.log('\n完整口径与不确定性见 docs/half-built-inventory-2026-09-28.md。');
+if (ARGS.includes('--write-baseline')) {
+  const target = path.resolve(process.cwd(), writeBaselineTarget);
+  fs.writeFileSync(target, `${JSON.stringify({
+    note: '半成品扫描门禁基线（棘轮：数不许变多）。重新生成：node apps/server/scripts/half-built-scan.mjs --write-baseline',
+    generatedAt: new Date().toISOString().slice(0, 10),
+    scope: DIRS,
+    counts,
+    roster,
+  }, null, 2)}\n`, 'utf8');
+  console.log(`\n★ 已写入基线：${path.relative(ROOT, target)}（谁都不用 ${counts[GATED_KEY]} 条）`);
+  process.exit(0);
+}
+
+if (GATE) {
+  let baseline = { counts: {}, roster: {} };
+  let baselineNote = '未提供（「谁都不用」按 0 零容忍判；其余三类不做棘轮比较）';
+  if (fs.existsSync(baselinePath)) {
+    baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    baselineNote = `${path.relative(ROOT, baselinePath)}（生成于 ${baseline.generatedAt ?? '未知'}）`;
+  } else if (BASELINE_ARG) {
+    // 显式给了路径却不存在 = 大概率是路径写错。**不静默降级**：报出来，免得基线悄悄失效。
+    console.log(`\n⚠ 基线文件不存在：${baselinePath}（按「谁都不用 = 0」零容忍口径继续）`);
+  }
+
+  const baselineRoster = key => new Set(Array.isArray(baseline.roster?.[key]) ? baseline.roster[key] : []);
+  const currentRoster = key => new Set(roster[key]);
+  const grew = key => [...currentRoster(key)].filter(id => !baselineRoster(key).has(id));
+  const shrank = key => [...baselineRoster(key)].filter(id => !currentRoster(key).has(id));
+
+  console.log('\n════════ 门禁判定（--gate）════════');
+  console.log(`基线：${baselineNote}`);
+  const gatedBaseline = typeof baseline.counts?.[GATED_KEY] === 'number' ? baseline.counts[GATED_KEY] : 0;
+  console.log(`【硬红】${GATED_KEY}：${counts[GATED_KEY]} 条（基线允许 ≤ ${gatedBaseline}）`);
+  for (const key of VERDICT_KEYS) {
+    if (key === GATED_KEY) continue;
+    const base = baseline.counts?.[key];
+    console.log(`【只报】${key}：${counts[key]} 条${typeof base === 'number' ? `（基线 ${base}）` : ''}`);
+  }
+
+  const newDead = grew(GATED_KEY);
+  const vanishedDead = shrank(GATED_KEY);
+  /**
+   * ★ **扫描范围与基线不一致 ⇒ 直接红，不比较计数**。
+   *
+   * 计数只在"同一把尺子"下可比：拿 `apps/server/src/services`（局部）的计数去比全仓基线，
+   * 得到的差异全是噪音；反过来更糟——拿局部范围的 0 去"证明"全仓没有死符号。
+   * 这正是本脚本注释里那条纪律：**宁可红，不许静默给一个错误结论**。
+   */
+  const baselineScope = Array.isArray(baseline.scope) ? baseline.scope.join(',') : '';
+  const scopeMismatch = baselineScope !== '' && baselineScope !== DIRS.join(',');
+  /**
+   * ★ 2026-09-30：**未登记的"半成品嫌疑"同样硬红**——登记表（allow.json）之外新出现的零引用导出
+   * 必须当场判（接线 / 删除 / 写进登记表并给理由），否则这份清单又会退化成"堆给人看"的待办。
+   */
+  let failed = scopeMismatch || counts[GATED_KEY] > gatedBaseline || newDead.length > 0 || unregistered.length > 0 || undecidableUnregistered.length > 0;
+  if (scopeMismatch) {
+    console.log(`\n❌ 门禁红：扫描范围与基线不一致，计数不可比`);
+    console.log(`   基线：${baselineScope}`);
+    console.log(`   本次：${DIRS.join(',')}`);
+    console.log('   要门禁局部范围，请先用同一范围重跑 --write-baseline 另存一份基线。');
+  }
+
+  for (const key of VERDICT_KEYS) {
+    if (key === GATED_KEY) continue;
+    const delta = grew(key);
+    if (delta.length > 0) {
+      console.log(`⚠ 棘轮超基线（不红）：${key} 比基线多 ${delta.length} 条 —— 新增项：`);
+      for (const id of delta) console.log(`   ${id}`);
+      console.log('   （这一类**刻意不红**：它含大量"只导出给测试"的合法形态，判红等于焊死门禁。见文件头「门禁口径」）');
+    }
+  }
+
+  if (newDead.length > 0) {
+    console.log(`\n❌ 门禁红：新增 ${newDead.length} 个「谁都不用」的**真死符号**（生产零调用 ∧ 测试零引用 ∧ 本文件零自用）`);
+    for (const id of newDead) console.log(`   ${id}`);
+    console.log('   处置二选一（不许留着）：接到生产调用点，或按 P5 纪律连同它的路径一起删除。');
+  } else if (counts[GATED_KEY] > gatedBaseline) {
+    // ★ 只在**计数真的超基线**时打这一句。`failed` 为真还有第三种来源（范围不一致），
+    //   那一句已在上面单独报过——同一件事报两遍、且第二遍的措辞与事实不符（"0 > 0"），
+    //   正是本脚本反复在修的"输出与事实不一致"。
+    console.log(`\n❌ 门禁红：${GATED_KEY} ${counts[GATED_KEY]} 条 > 基线允许的 ${gatedBaseline} 条（名单与基线一致，是基线本身过宽）`);
+  }
+  if (vanishedDead.length > 0) {
+    console.log(`\n★ 棘轮可收紧：${GATED_KEY} 比基线少 ${vanishedDead.length} 条 —— 请重跑 --write-baseline 把它固化（棘轮只许往下走）`);
+    for (const id of vanishedDead) console.log(`   ${id}`);
+  }
+  if (!failed && newDead.length === 0) {
+    console.log(`\n✅ 门禁通过：${GATED_KEY} ${counts[GATED_KEY]} 条，无新增真死符号。`);
+  }
+  process.exit(failed ? 1 : 0);
+}

package/scripts/kb-fingerprint-worker.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// 只读本次明确选定的cache miss；复用原逐切片/逐实体SHA算法，禁止索引、模型或持久摘要。
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const identity = file => { const stat = fs.statSync(file); return JSON.stringify([fs.realpathSync(file), stat.dev, stat.ino]); };
+const scriptHash = createHash('sha256').update(fs.readFileSync(__filename)).digest('hex');
+process.once('message', async job => {
+  let store;
+  let response;
+  try {
+    if (!job || typeof job.requestId !== 'string' || job.scriptHash !== scriptHash || !path.isAbsolute(job.databasePath)
+      || !Array.isArray(job.paths) || !job.paths.length || job.paths.some(file => typeof file !== 'string' || !file)
+      || JSON.stringify([...new Set(job.paths)].sort()) !== JSON.stringify(job.paths)
+      || identity(job.databasePath) !== job.databaseIdentity) throw new Error('只读解析身份请求或数据库身份无效');
+    const { IndexStateStore } = await import('@customize-agent/knowledge');
+    store = new IndexStateStore(job.databasePath, { readonly: true });
+    const results = store.readSnapshot(() => Object.fromEntries(job.paths.map(file => [file, store.parsedFileFingerprint(file)])));
+    if (identity(job.databasePath) !== job.databaseIdentity) throw new Error('只读计算期间数据库被替换');
+    response = { results };
+  } catch (error) { response = { error: error instanceof Error ? error.message : String(error) }; }
+  finally { store?.close(); }
+  if (!process.send) process.exit(1);
+  process.send({ requestId: job?.requestId, pid: process.pid, scriptHash, databaseIdentity: job?.databaseIdentity, paths: job?.paths, ...response }, error => {
+    process.exit(error || response.error ? 1 : 0);
+  });
+});
+process.on('disconnect', () => process.exit(1));

package/scripts/kb-index-worker.cjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // 知识库后台索引子进程壳：索引主循环复用 @customize-agent/knowledge 的 runIndexLoop
-// （与主进程 runInProcess 共用同一实现），本文件只负责参数解析、进程壳与日志 IPC 转发。
+// 本文件负责参数解析、独立进程与日志 IPC 转发。
 // 操作日志单写者为主进程：worker 不再直接读写 kb-operations.jsonl，
 // 而是通过 process.send({ type: 'log', patch }) 把补丁交给主进程统一落盘，
 // 避免父子进程同时读改写日志文件造成记录丢失。
 const path = require('node:path');
+const { completeWorker } = require('./kb-worker-ipc.cjs');
 
 function upsert(_projectRoot, patch) {
   if (process.send) process.send({ type: 'log', patch });
@@ -12,7 +13,6 @@ function upsert(_projectRoot, patch) {
 
 function toStage(stage) {
   if (['parsing', 'chunking', 'vectorizing', 'done', 'error'].includes(stage)) return stage;
-  if (stage === 'indexing') return 'chunking';
   if (stage === 'scanning') return 'uploading';
   return 'vectorizing';
 }
@@ -42,33 +42,40 @@ async function main() {
     });
   };
 
-  const { vectorStatus } = await knowledge.runIndexLoop(project, job, onProgress);
+  const { vectorStatus, failedFiles } = await knowledge.runIndexLoop(project, job, onProgress);
+  if (failedFiles.length) {
+    const error = failedFiles.map(item => `${item.relativePath}：${item.reason}`).join('\n');
+    await completeWorker({ id: operationId, type: operationType, title: operationTitle, stage: 'error', status: 'error', percent: 100,
+      message: `索引结束，${failedFiles.length} 个文件解析失败；成功文件已保留`, error, filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined }, { shutdown: () => manager.shutdown() });
+    return;
+  }
   // 向量索引失败/降级不阻断上传：文本解析与切片已入库，操作以 warning 完成（主进程据 status='warning' 保留降级原因）
   if (vectorStatus.status === 'error' || vectorStatus.status === 'unavailable') {
     const error = vectorStatus.error || (vectorStatus.status === 'unavailable' ? 'hnswlib-node native 绑定不可用，向量索引已降级' : 'HNSWLib 向量入库失败');
-    upsert(projectRoot, { id: operationId, type: operationType, title: operationTitle, stage: 'done', status: 'warning', percent: 100, message: job.relativePaths?.length ? '文件夹重新解析完成（向量索引降级）' : job.relativePath ? '单文件重新解析完成（向量索引降级）' : '知识库后台索引完成（向量索引降级）', filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined, error });
-    try { await manager.shutdown(); } catch { /* 忽略关闭异常，不掩盖索引结果 */ }
-    setImmediate(() => process.kill(process.pid, 'SIGKILL'));
+    await completeWorker({ id: operationId, type: operationType, title: operationTitle, stage: 'done', status: 'warning', percent: 100, message: job.relativePaths?.length ? '文件夹重新解析完成（向量索引降级）' : job.relativePath ? '单文件重新解析完成（向量索引降级）' : '知识库后台索引完成（向量索引降级）', filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined, error }, { shutdown: () => manager.shutdown() });
     return;
   }
-  upsert(projectRoot, { id: operationId, type: operationType, title: operationTitle, stage: 'done', status: 'success', percent: 100, message: job.relativePaths?.length ? '文件夹重新解析完成' : job.relativePath ? '单文件重新解析完成' : '知识库后台索引完成', filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined });
-  // 索引完成后显式释放 native 资源并自然退出。
-  // 根因：直接 process.exit(0) 或未 shutdown 自然退出，都会在 native 模块
-  // （hnswlib-node 向量索引）析构阶段触发 SIGABRT（libc++abi: mutex lock failed），
-  // 主进程会误报“退出码 unknown”并把成功任务覆盖为失败。
-  // shutdown 后进程已无任何待完成工作（数据已落盘、IPC 已同步写入管道），
-  // 最后用 SIGKILL 自终结绕过 Node teardown（fork 场景实测 process.exit(0)、
-  // disconnect+自然退出均会 SIGABRT）；主进程据 receivedDone 防护把任务视为成功。
-  try { await manager.shutdown(); } catch { /* 忽略关闭异常，不掩盖索引成功结果 */ }
-  setImmediate(() => process.kill(process.pid, 'SIGKILL'));
+  // runIndexLoop 已完成持久化。等待终态 IPC 写入，再关闭资源和绕过 native teardown。
+  await completeWorker({ id: operationId, type: operationType, title: operationTitle, stage: 'done', status: 'success', percent: 100, message: job.relativePaths?.length ? '文件夹重新解析完成' : job.relativePath ? '单文件重新解析完成' : '知识库后台索引完成', filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined }, { shutdown: () => manager.shutdown() });
 }
 
-main().catch(error => {
+main().catch(async error => {
   const job = JSON.parse(process.argv[2] || '{}');
   const projectRoot = job.projectRoot ? path.resolve(job.projectRoot) : process.cwd();
   const operationId = job.operationId || job.id || `worker-error-${Date.now()}`;
   const message = error instanceof Error ? (error.stack || error.message) : String(error);
-  upsert(projectRoot, { id: operationId, type: job.uploadOperationId ? 'upload' : 'reindex', title: job.uploadOperationId ? `上传 ${job.uploadTitle || '文件'}` : job.relativePath ? `重新解析 ${job.relativePath}` : '知识库后台索引', stage: 'error', status: 'error', percent: 100, message, error: message, filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined });
-  // 同样避免 teardown 阶段的 SIGABRT 掩盖真实错误信息（主进程据 error 补丁已落盘）
-  setImmediate(() => process.kill(process.pid, 'SIGKILL'));
+  // 清理残留的进行中索引任务（解析抛错会停在 PARSING 等中间态），避免「假进行中」死任务让该文件无法删除
+  try {
+    const knowledge = await import('@customize-agent/knowledge');
+    const manager = new knowledge.MultiProjectManager();
+    const project = await manager.getProject(projectRoot);
+    project.failPendingIndexJobs(message);
+    await manager.shutdown();
+  } catch { /* 清理失败不掩盖原始错误 */ }
+  try {
+    await completeWorker({ id: operationId, type: job.uploadOperationId ? 'upload' : 'reindex', title: job.uploadOperationId ? `上传 ${job.uploadTitle || '文件'}` : job.relativePath ? `重新解析 ${job.relativePath}` : '知识库后台索引', stage: 'error', status: 'error', percent: 100, message, error: message, filePath: job.relativePath, fileName: job.relativePath ? path.basename(job.relativePath) : undefined }, { shutdown: async () => {} });
+  } catch (ipcError) {
+    console.error('[kb-worker] terminal IPC failed:', ipcError);
+    process.kill(process.pid, 'SIGKILL');
+  }
 });

package/scripts/kb-worker-ipc.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+/** 等 IPC 写入回调确认终态已送入管道后才释放资源/终结进程。 */
+function sendTerminalPatch(patch, channel = process, timeoutMs = 10000) {
+  if (patch.percent !== 100 || !((patch.stage === 'done' && ['success', 'warning'].includes(patch.status)) || (patch.stage === 'error' && patch.status === 'error'))) {
+    return Promise.reject(new Error('知识库 worker 终态补丁无效'));
+  }
+  return new Promise((resolve, reject) => {
+    if (typeof channel.send !== 'function' || channel.connected === false) {
+      reject(new Error('知识库 worker IPC 通道不可用'));
+      return;
+    }
+    const timer = setTimeout(() => reject(new Error('知识库 worker 终态 IPC 写入超时')), timeoutMs);
+    try {
+      channel.send({ type: 'log', patch }, error => {
+        clearTimeout(timer);
+        if (error) reject(error);
+        else resolve();
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      reject(error);
+    }
+  });
+}
+
+async function completeWorker(patch, { channel = process, shutdown, terminate = () => process.kill(process.pid, 'SIGKILL') }) {
+  await sendTerminalPatch(patch, channel);
+  // 数据写入在 runIndexLoop 内已 await 完成；这里释放 sqlite/native 句柄。
+  try { await shutdown(); } catch (error) { console.error('[kb-worker] shutdown:', error); }
+  terminate();
+}
+
+module.exports = { sendTerminalPatch, completeWorker };

package/scripts/purge-next-artifacts.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Next 产物清理：`dev` / `build` / `prepack` 三处共用的一条实现。
+ *
+ * 原先这三条 npm script 各自内联一份 `node -e "rmSync(...)"`（路径清单与重试魔数
+ * 复制三份，改一处得记得改三处），这里收成单一来源。
+ *
+ * ## 两种模式与理由
+ * - `full`：整体清空 `.next`，用在 `next dev` 启动前与 `next build` 前。
+ *   两种模式共用同一目录：dev 产物会污染生产构建（`verify-next-static` 把
+ *   `static/development`、`static/webpack` 明确判为污染），生产产物也会让 dev 状态错乱。
+ * - `publish`：只清 `cache` 与 `static/{development,webpack}`，用在构建后与 `prepack`。
+ *   `files` 把 `.next/static` 整目录打进发布包，dev 产物若不清会被 `verify-next-static`
+ *   当场拒绝；`cache` 是构建缓存，没有发布价值。
+ *
+ * ## 为什么带重试
+ * `rmSync` 遇 EBUSY/ENOTEMPTY 默认直接抛——之前出现过删除中途被占用（旧 next 进程 /
+ * 编辑器 / 杀软持有句柄）导致构建链中断。`maxRetries + retryDelay` 让它自己退避重试。
+ *
+ * 用法：
+ *   node scripts/purge-next-artifacts.cjs full     # 整个 .next
+ *   node scripts/purge-next-artifacts.cjs publish  # cache + static/{development,webpack}
+ * 退出码：0=已清（含本就干净的）；1=模式缺失/未知。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const nextDir = path.resolve(__dirname, '..', '.next');
+
+/** 占用重试：与两条 npm script 原先的内联参数保持一致 */
+const REMOVE_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 200 };
+
+const MODES = {
+  full: () => {
+    fs.rmSync(nextDir, REMOVE_OPTIONS);
+  },
+  publish: () => {
+    for (const target of [
+      path.join(nextDir, 'cache'),
+      path.join(nextDir, 'static', 'development'),
+      path.join(nextDir, 'static', 'webpack'),
+    ]) {
+      fs.rmSync(target, REMOVE_OPTIONS);
+    }
+  },
+};
+
+function usage() {
+  console.log(`Usage: node scripts/purge-next-artifacts.cjs <full|publish>
+
+  full     Remove the whole .next directory (before \`next dev\` / \`next build\`).
+  publish  Remove .next/cache and .next/static/{development,webpack} (after build / before pack).`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    usage();
+    return 0;
+  }
+  const run = args.length === 1 ? MODES[args[0]] : undefined;
+  if (!run) {
+    usage();
+    return 1;
+  }
+  run();
+  return 0;
+}
+
+if (require.main === module) process.exit(main());

package/scripts/verify-next-static.js

@@ -15,7 +15,7 @@ const required = [
 for (const item of required) {
   if (!fs.existsSync(item)) {
     console.error(`[server] Missing Next build artifact: ${path.relative(root, item)}`);
-    console.error('[server] Run `pnpm build` in apps/server before `pnpm start`.');
+    console.error('[server] Run `pnpm build` at the monorepo root (or in apps/server) before `pnpm start`.');
     process.exit(1);
   }
 }
@@ -54,7 +54,7 @@ for (const file of files) {
 const pagesManifestPath = path.join(nextDir, 'server', 'pages-manifest.json');
 if (!fs.existsSync(pagesManifestPath)) {
   console.error('[server] Missing Next pages manifest: .next/server/pages-manifest.json');
-  console.error('[server] Run `pnpm build` in apps/server before `pnpm start`.');
+  console.error('[server] Run `pnpm build` at the monorepo root (or in apps/server) before `pnpm start`.');
   process.exit(1);
 }
 const pagesManifest = JSON.parse(fs.readFileSync(pagesManifestPath, 'utf8'));