@customize-agent/server 4.57.0 → 4.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/server",
-  "version": "4.57.0",
+  "version": "4.59.0",
   "description": "Customize Agent Web 管理控制台",
   "exports": {
     "./package.json": "./package.json"
@@ -36,9 +36,9 @@
   },
   "dependencies": {
     "@ant-design/icons": "^6.3.2",
-    "@customize-agent/knowledge": "^4.15.2",
-    "@customize-agent/llm": "^3.1.2",
-    "@customize-agent/runtime": "^3.1.0",
+    "@customize-agent/knowledge": "^4.16.0",
+    "@customize-agent/llm": "^3.1.3",
+    "@customize-agent/runtime": "^3.1.2",
     "@napi-rs/canvas": "^0.1.82",
     "@types/nprogress": "^0.2.3",
     "antd": "^6.5.0",
@@ -76,6 +76,7 @@
     "build": "node -e \"require('fs').rmSync('.next', { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })\" && next build && node -e \"const fs=require('fs'); for (const p of ['.next/cache','.next/static/development','.next/static/webpack']) fs.rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })\" && node scripts/verify-next-static.js",
     "prestart": "node scripts/verify-next-static.js",
     "start": "next start -p 17321",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
   }
 }

package/scripts/capture-baseline.mjs

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+/**
+ * capture-baseline：验收基线采集（方案 P8.5 / Z5 的 A 组）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ## 为什么需要这个脚本（方案 14.2 的原话：归档作为评估基线的成色）
+ *
+ * `~/.customize-agent/projects/<id>/generatedDocuments/` 里有 288 份 draft、281 份 assets、
+ * 46 份交付报告。**够**判据行为回归；**不够**做「改造是否让文档更好」的判定，因为归档里缺两样：
+ *
+ * - ❌ **无 `blockLedger`**（块级目标/实际/失败类别）——没有它就答不出「篇幅失守是写作侧还是修复侧」；
+ * - ❌ **无逐调用 token/缓存遥测**——成本与缓存命中率**当前不可重建**。
+ *
+ * 于是「改了之后是不是退化了」在数据上无从判断（S4.2）。本脚本把这两样**在生成结束的那一刻**
+ * 抄下来，与六维分一起冻结成一份可 diff 的基线。
+ *
+ * ## 为什么是「采集归档」而不是「另跑一遍管线」
+ *
+ * 生成只发生一次，**产物就是归档**。脚本不重跑任何东西——它读归档、按 baseline schema 抽取、
+ * 落成一份 `*.baseline.json`。这样：
+ * 1. 采集本身**零 LLM 成本**（跑一次真实文档 ~50 分钟，重跑一遍纯属浪费）；
+ * 2. 基线与被评的那份文档**逐字段同源**（不会出现「基线是另一轮跑的」这种不可比）；
+ * 3. A/B 两组的差异**只来自开关**（`REPAIR_CHAIN=off` / `AGENT_TOOLS=on`），不是两套采集代码。
+ *
+ * ## 用法
+ *
+ * ```bash
+ * # 采集一份既有归档（docId 见 generatedDocuments/index.json）
+ * node apps/server/scripts/capture-baseline.mjs --project-root . --doc doc-1790407778481-d7a36837
+ * # 采集最近 N 份（自带 --run 时先触发一次生成再采集）
+ * node apps/server/scripts/capture-baseline.mjs --project-root . --latest 2
+ * node apps/server/scripts/capture-baseline.mjs --project-root . --run tpl-1790019955043 --run tpl-1790187804600
+ * ```
+ *
+ * 落盘：`~/.customize-agent/baselines/<时间戳>-<label>.baseline.json`（**append-only**，
+ * 不覆盖历史基线——「同代码重跑波动 ±7」这件事只能靠多份基线看出来）。
+ *
+ * ## A/B 模式（S11.2：**同一组 N 份归档，开关开/关各跑一次**）
+ *
+ * ```bash
+ * # 腿 1（off）——需要**服务端以 REPAIR_CHAIN=off 启动**（开关读的是服务端进程的 env，脚本设不了）
+ * node apps/server/scripts/capture-baseline.mjs --project-root . --latest 8 --ab REPAIR_CHAIN --ab-leg off
+ * # 腿 2（on）——服务端以默认 env 重启后再跑；配对文件由腿 1 打印，无需手抄
+ * node apps/server/scripts/capture-baseline.mjs --project-root . --latest 8 --ab REPAIR_CHAIN --ab-leg on
+ * # 判定（**不在本脚本里**）：两腿各跑完后由 TS 侧 `services/agent/abExecution.ts` 出结论
+ * ```
+ *
+ * 分工（这是本模式最重要的一条）：**脚本只做机制 + 抄写原始证据，绝不下结论**。
+ * | 环节 | 谁 |
+ * |---|---|
+ * | 拒绝"这场 A/B 根本不成立"（腿值非法 / 同一腿跑两次 / 两腿输入不同 / 标签与历史基线撞车） | **本脚本**（全部在任何网络调用**之前**或落盘**之前**） |
+ * | 从归档里抄 `repairChainMode` 等**原始**证据 | 本脚本（抄写，不判定） |
+ * | 「这一腿的开关真的切了吗」+「on 腿是否退化」 | TS 侧 `services/agent/abExecution.ts`（复用 S4.2 的 `costModel`） |
+ *
+ * 为什么判定不放这儿：脚本的产物是**文件**，它不会拒绝给结论——而"标签写错的一腿"这种错
+ * 只能靠"声明值 vs 归档证据"的对账抓出来，那需要两腿的归档同时在手，且必须**宁可不出结论**。
+ * 脚本在此处的克制是刻意的：它连"declare=on 且归档无标记 ⇒ 视为 on"这种推断都不做。
+ *
+ * ★ 未核实：`AGENT_TOOLS` 这条腿今天**采集得出、判定不出**——写手循环的 `onTurn`
+ * （`writerLoop.ts:134` 的 `turn.*` 载荷）在生产路径上零消费点，节点日志里没有 `turn` 节点，
+ * 归档里也没有任何字段记录这个开关。脚本会对这种腿打出显式警告（跑完 8+8 份仍会拒判），
+ * 免得白跑 16 次真实生成。
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_BASE_URL = process.env.BASELINE_BASE_URL || 'http://localhost:17321';
+
+function parseArgs(argv) {
+  const args = { projectRoot: process.cwd(), docs: [], runs: [], latest: 0, label: '', baseUrl: DEFAULT_BASE_URL, timeoutMinutes: 90, ab: '', abLeg: '', abPair: '', abSize: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = () => argv[++index];
+    if (token === '--project-root') args.projectRoot = path.resolve(next());
+    else if (token === '--doc') args.docs.push(next());
+    else if (token === '--run') args.runs.push(next());
+    else if (token === '--latest') args.latest = Number(next());
+    else if (token === '--label') args.label = next();
+    else if (token === '--base-url') args.baseUrl = next();
+    else if (token === '--timeout-minutes') args.timeoutMinutes = Number(next());
+    else if (token === '--ab') args.ab = next();
+    else if (token === '--ab-leg') args.abLeg = next();
+    else if (token === '--ab-pair') args.abPair = next();
+    else if (token === '--ab-size') args.abSize = Number(next());
+    else if (token === '--help' || token === '-h') { printHelp(); process.exit(0); }
+    else throw new Error(`未知参数：${token}（--help 看用法）`);
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write([
+    'capture-baseline：把既有归档抽成可 diff 的验收基线（方案 P8.5）。',
+    '',
+    '  --project-root <dir>   文档所属项目根（默认当前目录；决定归档目录）',
+    '  --doc <docId>          采集指定文档（可重复）',
+    '  --latest <N>           采集最近 N 份已完成文档',
+    '  --run <templateId>     先触发一次生成再采集（可重复；需要服务在跑）',
+    '  --label <name>         基线标签（默认按开关自动命名 a-on / b-off）',
+    '  --base-url <url>       服务地址（默认 http://localhost:17321）',
+    '  --timeout-minutes <N>  单份生成等待上限（默认 90）',
+    '',
+    'A/B（S11.2：同 N 份归档，开/关各跑一次；判定在 TS 侧 abExecution.ts）：',
+    '  --ab <SWITCH>          开关名（本工具支持 REPAIR_CHAIN / AGENT_TOOLS）',
+    '  --ab-leg <on|off>      本腿的开关取值（同一腿只能采一次）',
+    '  --ab-pair <file>       配对文件（默认按 开关+项目 定形，腿 1 打印出来供腿 2 复用）',
+    '  --ab-size <N>          本场 A/B 的归档份数（腿 1 默认 8；腿 2 缺省沿用本场已声明的份数）',
+    '',
+  ].join('\n'));
+}
+
+// ── 归档读取（与 generatedDocumentService 的落盘布局同源：~/.customize-agent/projects/<projectId>/generatedDocuments）──
+
+/**
+ * 项目 id（`sha256(绝对路径)` 前 12 位，与 `@customize-agent/knowledge` 的 `computeProjectId` 逐字同构）。
+ * **只用于定位归档目录**，不参与任何评分口径——口径单源在服务端，本脚本只读。
+ *
+ * ⚠️ 刻意不 import 那个包：脚本要在**服务未启动 / 依赖未构建**时也能跑（验收现场最需要它的时候，
+ * 往往正是服务刚崩的时候）。同构关系由下面这条自检守住——算法一旦漂移，脚本会立刻找不到归档，
+ * 而不是悄悄采到空基线。
+ */
+function projectIdOf(projectRoot) {
+  return crypto.createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 12);
+}
+
+function archiveDir(projectRoot) {
+  return path.join(os.homedir(), '.customize-agent', 'projects', projectIdOf(projectRoot), 'generatedDocuments');
+}
+
+// ── 抽取：只抽「归档里已有、但没被结构化保存」的那些量 ─────────────────────
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * 六维 + 专业分 + 阻断数（评分口径单源在服务端；脚本只做**抄写**，不做换算）。
+ * 换算会让基线与被评文档的差异混入「脚本口径」这个第三变量。
+ */
+function scoresOf(record) {
+  const report = record?.reviewMetadata?.qualityReport || {};
+  const dims = report.dimensions || report.dimensionScores || null;
+  return {
+    overall: num(report.overall ?? report.overallScore),
+    dimensions: dims,
+    requirementChecklist: Array.isArray(report.requirementChecklist) ? report.requirementChecklist.length : null,
+    // 阻断数：导出闸门里的 blockingIssues（**不是**六维分——两套口径，方案 §六 顺带发现）
+    blockingCount: Array.isArray(record?.draft?.exportGate?.blockingIssues) ? record.draft.exportGate.blockingIssues.length : null,
+    exportGatePassed: record?.draft?.exportGate?.passed ?? null,
+  };
+}
+
+/** 块级篇幅账（方案 14.2 点名的缺口之一） */
+function blockLedgerOf(record) {
+  const ledger = record?.reviewMetadata?.diagnostics?.blockLedger || record?.draft?.reviewMetadata?.diagnostics?.blockLedger || [];
+  const rows = Array.isArray(ledger) ? ledger : [];
+  const primary = rows.filter(row => !row.isolatedRetry);
+  return {
+    rows: primary.length,
+    targetChars: primary.reduce((sum, row) => sum + (num(row.target) || 0), 0),
+    actualChars: primary.reduce((sum, row) => sum + (num(row.actual) || 0), 0),
+    firstPassRate: primary.length > 0 ? primary.filter(row => row.passed && (num(row.attempt) || 0) === 0).length / primary.length : null,
+    failureKinds: primary.flatMap(row => row.failureKinds || []).reduce((acc, kind) => { acc[kind] = (acc[kind] || 0) + 1; return acc; }, {}),
+    ledger, // 明细整段落盘：缺口归因要靠它，不要在脚本里预先聚合掉信息
+  };
+}
+
+/** 逐调用 token/缓存遥测（方案 14.2 点名的缺口之二） */
+function llmTelemetryOf(record) {
+  const diagnostics = record?.reviewMetadata?.diagnostics || record?.draft?.reviewMetadata?.diagnostics || {};
+  const llm = diagnostics.llm || {};
+  return {
+    calls: num(llm.calls), failures: num(llm.failures), retries: num(llm.retries), schemaFailures: num(llm.schemaFailures),
+    maxActive: num(llm.maxActive),
+    inputTokens: num(llm.inputTokens), outputTokens: num(llm.outputTokens),
+    promptCacheHitTokens: num(llm.promptCacheHitTokens), promptCacheMissTokens: num(llm.promptCacheMissTokens),
+    inputChars: num(llm.inputChars),
+  };
+}
+
+/** 修复链净增 + 逐轮明细（Z7 R1：退役决策的输入）与关链状态（Z5） */
+function repairChainOf(record) {
+  const diagnostics = record?.reviewMetadata?.diagnostics || record?.draft?.reviewMetadata?.diagnostics || {};
+  const telemetry = record?.reviewMetadata?.telemetry || {};
+  return {
+    netChars: diagnostics.repairChainNetChars || telemetry.repairChainNetChars || null,
+    switchState: diagnostics.repairChain || null,
+    repairHeat: telemetry.repairHeat || null,
+  };
+}
+
+function baselineOf(record, options) {
+  const diagnostics = record?.reviewMetadata?.diagnostics || {};
+  return {
+    schema: 'capture-baseline/v1',
+    capturedAt: new Date().toISOString(),
+    // ★ 开关状态必须进基线：A/B 两组**只差开关**，基线里没有开关就分不清这份是哪一组
+    switches: {
+      repairChain: diagnostics.repairChain?.mode || 'on',
+      agentTools: process.env.AGENT_TOOLS || 'off',
+      agendEmitNodeStageMirror: process.env.AGENT_EMIT_NODE_STAGE_MIRROR || 'default',
+    },
+    doc: {
+      id: record.id, title: record.title, templateId: record.templateId, templateName: record.templateName,
+      status: record.status, elapsedMs: num(record.elapsedMs), wordCount: num(record.wordCount),
+      markdownChars: typeof record.markdown === 'string' ? record.markdown.length : null,
+      completedAt: record.completedAt ?? null,
+    },
+    scores: scoresOf(record),
+    blockLedger: blockLedgerOf(record),
+    llm: llmTelemetryOf(record),
+    repairChain: repairChainOf(record),
+    note: options.note || '',
+  };
+}
+
+// ── A/B 配对（S11.2：同 N 份归档，开/关各跑一次） ─────────────────────────
+
+/**
+ * 本工具认识的 A/B 开关（与 TS 侧 `services/agent/abExecution.ts` 的 `abSwitchEvidence()` 逐条同集合）。
+ *
+ * ★ 刻意**不**接受 `SKILLS`/`PAUSE`：它们的关闭效果在归档里没有可对账的痕迹
+ * （技能不参与 ≠ 模板缺字段，暂停被忽略 ≠ 终态不是 paused，两者都可能由别的原因造成）。
+ * 在这里放行会让操作者以为"A/B 做过了"，而判定侧只会拒判——把"跑过"当成"验过"是本仓红线。
+ */
+const AB_SWITCHES = ['REPAIR_CHAIN', 'AGENT_TOOLS'];
+const AB_LEGS = ['on', 'off'];
+/** 归档证据**当前不可用**的开关（跑完仍会拒判）——采集不拦，但必须**事先**说清 */
+const AB_UNVERIFIABLE = { AGENT_TOOLS: '归档里没有任何字段记录这个开关：写手循环的 onTurn（writerLoop.ts:134 的 turn.* 载荷）在生产路径上零消费点，节点日志里没有 turn 节点' };
+
+function baselinesDir() {
+  return path.join(os.homedir(), '.customize-agent', 'baselines');
+}
+
+/** 配对文件：显式 `--ab-pair` 优先；否则按「开关 + 项目」定形（腿 2 无需手抄路径） */
+function abPairPathOf(args) {
+  if (args.abPair) return path.resolve(args.abPair);
+  return path.join(baselinesDir(), `ab-${args.ab.toLowerCase()}-${projectIdOf(args.projectRoot)}.abpair.json`);
+}
+
+function loadPairOrNull(file) {
+  if (!fs.existsSync(file)) return null;
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (parsed?.schema !== 'ab-pair/v1' || !Array.isArray(parsed.legs)) {
+    throw new Error(`配对文件形状不对（期望 schema=ab-pair/v1）：${file}`);
+  }
+  return parsed;
+}
+
+/**
+ * A/B 的全部「这场实验不成立」判定——**在任何网络调用之前**跑完。
+ *
+ * 为什么必须前置：`--run` 会触发真实生成（一份 40–60 分钟、真金白银）。等到采完 8+8 份
+ * 才发现"同一腿采了两次"，代价是十几小时机时与一份**没法用**的数据——而那种数据最危险的地方
+ * 是它看起来能用。故这里宁可多拦。
+ */
+function abPreflight(args) {
+  const touched = args.ab !== '' || args.abLeg !== '' || args.abPair !== '' || args.abSize !== null;
+  if (!touched) return null;
+  if (!args.ab) throw new Error('--ab-leg / --ab-pair / --ab-size 需要同时给 --ab <SWITCH>（否则参数会被静默忽略）');
+  if (!AB_SWITCHES.includes(args.ab)) {
+    throw new Error(`--ab 不支持 ${args.ab}：本工具只做 ${AB_SWITCHES.join(' / ')}（判定侧同集合；其它开关在归档里没有可对账的痕迹）`);
+  }
+  const leg = args.abLeg;
+  if (leg === '') throw new Error(`--ab ${args.ab} 必须给 --ab-leg <${AB_LEGS.join('|')}>：不给就分不清这份归档属于哪一腿，而两腿的归档**除开关外必须一致**`);
+  if (!AB_LEGS.includes(leg)) throw new Error(`--ab-leg 只认 ${AB_LEGS.join('|')}，收到「${args.abLeg}」（含糊取值在 A/B 里是结论级差错：'true'/'1' 到底算哪一腿没有唯一答案）`);
+  if (args.abSize !== null && (!Number.isInteger(args.abSize) || args.abSize <= 0)) {
+    throw new Error(`--ab-size 需要正整数，收到「${args.abSize}」（0 / 负数 / 小数都不收：含糊值一律拒绝，不静默取默认）`);
+  }
+  // 两腿必须各有自己的标签：判定侧**按标签配对**，两腿同标签会让 on/off 指到同一份基线文件
+  if (args.label !== '') {
+    throw new Error('A/B 模式下不允许 --label：两腿必须各有自己的标签（本模式自动命名为 ab-<开关>-<腿>-<时刻>），同标签会让判定侧把两腿指到同一份基线');
+  }
+
+  const pairFile = abPairPathOf(args);
+  const pair = loadPairOrNull(pairFile);
+  // 份数缺省取**本场已声明的**（腿 2 不必重抄 --ab-size；显式给了不一致的值仍然拒）
+  const size = args.abSize === null ? (pair?.size ?? 8) : args.abSize;
+  if (pair) {
+    if (pair.switchName !== args.ab) throw new Error(`配对文件是给 ${pair.switchName} 的，本次是 ${args.ab}：${pairFile}`);
+    const existing = pair.legs.map(item => item.leg);
+    if (existing.includes(leg)) {
+      throw new Error(`「${leg}」腿已经采过了（${pairFile}）：A/B 是**开/关各一次**，同一腿采两次只会让配对无法收敛到"两腿只差开关"（已采：${existing.join('、')}）`);
+    }
+    if (pair.size !== size) throw new Error(`配对文件的份数是 ${pair.size}，本次 --ab-size ${size}：两腿必须同份数，改份数等于换了一场实验（请新建一场）`);
+  }
+
+  // 事前把"这条腿的证据不存在"说清——免得白跑 8 份真实生成
+  if (AB_UNVERIFIABLE[args.ab]) {
+    process.stdout.write(`[baseline] ⚠ 本腿（${args.ab}=${leg}）可采集但**判定会拒绝出结论**：${AB_UNVERIFIABLE[args.ab]}\n`);
+    process.stdout.write('[baseline] ⚠ 若目的是"建立"该证据通道，先把写入接上再跑；否则这 8 份归档只能当原始素材，不能当 A/B 证据。\n');
+  }
+  // 开关读的是**服务端进程**的 env（生成跑在服务端，本脚本设不了）——本地 env 只是提示，不是证据
+  const localEnv = process.env[args.ab] || '(未设)';
+  if (args.runs.length > 0) {
+    process.stdout.write(`[baseline] ⚠ 本腿要求服务端 env：${args.ab}=${leg}（脚本设不了它；本地 env=${localEnv}）——请**重启服务**后再跑 --run，否则采到的是另一腿。\n`);
+  }
+
+  return { switchName: args.ab, leg, size, pairFile, pair, legCount: (pair?.legs.length ?? 0) + 1 };
+}
+
+/** 归档证据：关链标记（`documentPipeline.ts:160` 只在**关**时写）+ 节点日志里 turn 节点条数（今天恒 0） */
+function abObserveLeg({ projectRoot, records }) {
+  const modes = [];
+  const turnCounts = [];
+  const notes = [];
+  for (const record of records) {
+    const mode = record?.reviewMetadata?.diagnostics?.repairChain?.mode ?? record?.draft?.reviewMetadata?.diagnostics?.repairChain?.mode ?? null;
+    modes.push(mode);
+    const count = turnNodeCountOf({ projectRoot, docId: record.id });
+    turnCounts.push(count);
+    if (count === null) notes.push(`${record.id}：无节点日志（turn 条数记为「未知」，不是 0）`);
+  }
+  const distinct = [...new Set(modes.map(mode => mode ?? '(缺)'))].sort();
+  return {
+    // 关腿应全体带标记；混着来（如 'off+(缺)'）在判定侧会被判为"标签对不上"并给出这段原文
+    repairChainMode: modes.length > 0 && distinct.length === 1 && distinct[0] === '(缺)' ? null : distinct.join('+'),
+    turnNodeCount: turnCounts.some(count => count !== null) ? turnCounts.reduce((sum, count) => sum + (count ?? 0), 0) : null,
+    notes,
+    perDoc: records.map((record, index) => ({ docId: record.id, repairChainMode: modes[index], turnNodeCount: turnCounts[index] })),
+  };
+}
+
+/** 节点日志里 `turn.*` 节点条数；**日志不存在 ⇒ null（未知）**，绝不写成 0（0 是"查过了，没有"） */
+function turnNodeCountOf({ projectRoot, docId }) {
+  const file = path.join(archiveDir(projectRoot), 'drafts', `${docId}.nodes.jsonl`);
+  if (!fs.existsSync(file)) return null;
+  let count = 0;
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (String(parsed?.type || '').startsWith('turn.')) count += 1;
+    } catch { /* 撕裂尾行：不计入（也不当成 0——上面的 existsSync 已经区分了"没有日志"） */ }
+  }
+  return count;
+}
+
+/**
+ * 落盘**之前**的输入集校验：两腿必须跑同一组输入。
+ *
+ * 为什么这条值钱：`--latest 8` 的选片随"最近完成"变化。若两腿之间又完成了一份文档，
+ * 腿 2 采到的就是另一组——而**分数差异会被读成开关的效果**。这种错在结果里看不出来
+ * （两组分数都"正常"），只能靠这次集合比对拦住。
+ */
+function abAssertInputs(ab, baselines) {
+  if (baselines.length !== ab.size) {
+    throw new Error(`本腿采到 ${baselines.length} 份，与 --ab-size ${ab.size} 不符：A/B 的前提是两腿同份数（拒绝落盘）`);
+  }
+  const templates = baselines.map(item => item.doc.templateId || item.doc.templateName || '(未知模板)');
+  const docs = baselines.map(item => item.doc.id);
+  const other = ab.pair?.legs?.[0];
+  if (other) {
+    const mine = [...templates].sort().join('\u0000');
+    const theirs = [...other.templates].sort().join('\u0000');
+    if (mine !== theirs) {
+      throw new Error(`两腿输入不是同一组模板（本腿 ${templates.join('、')} vs 另一腿 ${other.templates.join('、')}）：差的就不是开关了（拒绝落盘）`);
+    }
+    const overlap = docs.filter(id => other.docIds.includes(id));
+    if (overlap.length > 0) {
+      throw new Error(`两腿归档重合 ${overlap.length} 份（${overlap.slice(0, 3).join('、')}…）：同一份归档不能同时代表"开"与"关"（拒绝落盘）`);
+    }
+  }
+  return { templates, docs };
+}
+
+/** A/B 模式下拒绝与历史基线**撞标签**：标签是判定侧的配对键，撞了就会把两场会话混成一场 */
+function abAssertLabelFree(label) {
+  const dir = baselinesDir();
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.baseline.json')) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+      if (parsed?.label === label) {
+        throw new Error(`标签「${label}」已被 ${name} 占用：A/B 的判定按标签配对，撞标签会把两场会话混成一场（A/B 模式下 --label 不可用，把旧基线移出目录或删掉即可；正常情况不会撞——标签里带采集时刻）`);
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('已被')) throw error; // 上面的拒绝照原样抛出
+      /* 解析失败的历史文件不参与撞标签判定（`loadBaselines` 侧同样跳过并告警） */
+    }
+  }
+}
+
+/** 写配对状态（腿记录**只追加不删**；文件本身重写是因为它是状态不是产物） */
+function abWriteLeg({ ab, label, outFile, records }) {
+  const observed = abObserveLeg({ projectRoot: ab.projectRoot, records });
+  const leg = {
+    leg: ab.leg,
+    label,
+    baselineFile: path.basename(outFile),
+    declared: ab.leg,
+    capturedAt: new Date().toISOString(),
+    templates: ab.observed.templates,
+    docIds: ab.observed.docs,
+    observed,
+  };
+  const pair = {
+    schema: 'ab-pair/v1',
+    switchName: ab.switchName,
+    pairId: `ab-${ab.switchName.toLowerCase()}-${projectIdOf(ab.projectRoot)}`,
+    projectRoot: path.resolve(ab.projectRoot),
+    size: ab.size,
+    legs: [...(ab.pair?.legs ?? []), leg],
+  };
+  fs.writeFileSync(ab.pairFile, `${JSON.stringify(pair, null, 2)}\n`);
+  return { pair, openLeg: AB_LEGS.filter(item => !pair.legs.some(entry => entry.leg === item)) };
+}
+
+// ── 服务交互：触发与轮询 ────────────────────────────────────────────────
+
+async function postJson(url, body, timeoutMs = 60000) {
+  const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
+  const text = await response.text();
+  let parsed = null;
+  try { parsed = JSON.parse(text); } catch { /* 非 JSON 响应原样带出 */ }
+  return { status: response.status, body: parsed ?? text };
+}
+
+async function getJson(url, timeoutMs = 60000) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  const text = await response.text();
+  try { return { status: response.status, body: JSON.parse(text) }; } catch { return { status: response.status, body: text }; }
+}
+
+const TERMINAL = new Set(['completed', 'completed_with_issues', 'warning', 'failed', 'aborted']);
+
+async function triggerAndWait({ baseUrl, projectRoot, templateId, timeoutMinutes }) {
+  const started = await postJson(`${baseUrl}/api/documents/generate`, { templateId, requirement: '', projectRoot }, 120000);
+  if (started.status !== 202 && started.status !== 200) {
+    throw new Error(`触发失败（HTTP ${started.status}）：${typeof started.body === 'string' ? started.body : JSON.stringify(started.body)}`);
+  }
+  const documentId = started.body?.documentId || started.body?.record?.id || started.body?.id;
+  if (!documentId) throw new Error(`触发返回里没有 documentId：${JSON.stringify(started.body).slice(0, 400)}`);
+  process.stdout.write(`[baseline] 已触发 ${templateId} → ${documentId}（等待生成，通常 40–60 分钟）\n`);
+  const deadline = Date.now() + timeoutMinutes * 60000;
+  let lastLog = 0;
+  for (;;) {
+    if (Date.now() > deadline) throw new Error(`等待超时（${timeoutMinutes} 分钟）：${documentId}`);
+    await new Promise(resolve => setTimeout(resolve, 20000));
+    const { body } = await getJson(`${baseUrl}/api/documents/generated?id=${encodeURIComponent(documentId)}&projectRoot=${encodeURIComponent(projectRoot)}`);
+    const record = body?.document;
+    if (!record) continue;
+    if (Date.now() - lastLog > 300000) {
+      lastLog = Date.now();
+      process.stdout.write(`[baseline] ${documentId} 状态=${record.status} 字数=${record.wordCount ?? '?'}\n`);
+    }
+    if (TERMINAL.has(record.status)) return record;
+  }
+}
+
+function loadArchivedRecord({ projectRoot, docId }) {
+  const file = path.join(archiveDir(projectRoot), 'drafts', `${docId}.json`);
+  if (!fs.existsSync(file)) throw new Error(`归档不存在：${file}`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function latestDocIds({ projectRoot, count }) {
+  const indexFile = path.join(archiveDir(projectRoot), 'index.json');
+  if (!fs.existsSync(indexFile)) throw new Error(`索引不存在：${indexFile}`);
+  const entries = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
+  return entries
+    .filter(entry => entry.completedAt && String(entry.status).startsWith('completed'))
+    .sort((left, right) => (right.completedAt || 0) - (left.completedAt || 0))
+    .slice(0, count)
+    .map(entry => entry.id);
+}
+
+// ── 主流程 ─────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // ★ A/B 的拒绝**全部**在这里（任何网络调用之前）：腿值非法 / 同一腿采两次 / 份数不一致…
+  const ab = abPreflight(args);
+  if (ab) {
+    ab.projectRoot = args.projectRoot;
+    process.stdout.write(`[baseline] A/B：${ab.switchName}=${ab.leg}（第 ${ab.legCount}/2 腿，共 ${ab.size} 份）配对文件 ${ab.pairFile}\n`);
+  }
+  const records = [];
+
+  for (const templateId of args.runs) {
+    records.push(await triggerAndWait({ baseUrl: args.baseUrl, projectRoot: args.projectRoot, templateId, timeoutMinutes: args.timeoutMinutes }));
+  }
+  if (args.latest > 0) {
+    for (const docId of latestDocIds({ projectRoot: args.projectRoot, count: args.latest })) {
+      records.push(loadArchivedRecord({ projectRoot: args.projectRoot, docId }));
+    }
+  }
+  for (const docId of args.docs) records.push(loadArchivedRecord({ projectRoot: args.projectRoot, docId }));
+  if (records.length === 0) { printHelp(); process.exit(1); }
+
+  const baselines = records.map(record => baselineOf(record, args));
+  const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+  // A/B 的标签带**时刻**：判定侧按标签配对，两场会话天然可分（同开关可重复做 A/B，不必先归档旧基线）
+  const label = args.label || (ab ? `ab-${ab.switchName.toLowerCase()}-${ab.leg}-${stamp}` : (baselines[0].switches.repairChain === 'off' ? 'b-off' : 'a-on'));
+  const outDir = baselinesDir();
+  fs.mkdirSync(outDir, { recursive: true });
+  if (ab) {
+    // ★ 落盘前的最后两道拒绝：两腿输入不同 / 标签与历史基线撞车。
+    //   抛在这里 ⇒ 本腿**一份文件都不写**（不留"半套配对"这种看起来能用的状态）
+    ab.observed = abAssertInputs(ab, baselines);
+    abAssertLabelFree(label);
+  }
+  const outFile = path.join(outDir, `${stamp}-${label}.baseline.json`);
+  fs.writeFileSync(outFile, `${JSON.stringify({ capturedAt: new Date().toISOString(), label, projectRoot: path.resolve(args.projectRoot), baselines }, null, 2)}\n`);
+
+  process.stdout.write('\n[baseline] 采集完成\n');
+  for (const item of baselines) {
+    const dims = item.scores.dimensions ? JSON.stringify(item.scores.dimensions) : '(无 dimensions)';
+    process.stdout.write(
+      `  ${item.doc.id}  ${item.doc.title}  状态=${item.doc.status}  ${Math.round((item.doc.elapsedMs || 0) / 60000)}min\n`
+      + `    综合=${item.scores.overall ?? '?'}  阻断=${item.scores.blockingCount ?? '?'}  六维=${dims}\n`
+      + `    块账=${item.blockLedger.rows} 块 Σ目标=${item.blockLedger.targetChars} Σ实际=${item.blockLedger.actualChars}\n`
+      + `    LLM 调用=${item.llm.calls ?? '?'} 缓存命中/未命中=${item.llm.promptCacheHitTokens ?? '?'}/${item.llm.promptCacheMissTokens ?? '?'}\n`
+      + `    修复链净增=${item.repairChain.netChars?.delta ?? '?'}（${item.repairChain.netChars ? (item.repairChain.netChars.ratio * 100).toFixed(1) + '%' : '?'}）开关=${item.switches.repairChain}\n`,
+    );
+  }
+  process.stdout.write(`[baseline] 落盘：${outFile}\n`);
+  if (ab) {
+    const { pair, openLeg } = abWriteLeg({ ab, label, outFile, records });
+    process.stdout.write(`[baseline] A/B 状态：${ab.pairFile}（已采 ${pair.legs.map(item => item.leg).join('、')}）\n`);
+    if (openLeg.length > 0) {
+      process.stdout.write(`[baseline] 还差「${openLeg.join('、')}」腿：服务端 env 切到 ${ab.switchName}=${openLeg[0]} 并重启后，用**同一批输入**再跑一次\n`);
+      process.stdout.write(`[baseline]   （--ab ${ab.switchName} --ab-leg ${openLeg[0]} --ab-pair ${ab.pairFile}；--latest/--doc 的选片必须与上一腿同组）\n`);
+    } else {
+      process.stdout.write('[baseline] 两腿齐了。判定（**不在本脚本里**，跑 TS 侧车道）：\n');
+      process.stdout.write(`[baseline]   AB_PAIR=${ab.pairFile} npx vitest run --config vitest.manual.config.ts apps/server/test/services/agent/abExecution.manual.ts\n`);
+    }
+    process.stdout.write('[baseline] ★ 本脚本只采集与抄写证据，**不下结论**：标签对不对、是否退化，由 TS 侧 abExecution（复用 S4.2）判。\n');
+  }
+  process.stdout.write('[baseline] ★ 同代码重跑波动 ±7（方案 14.5 族 6 实测）——单点差值不足以归因，A/B 要比的是**维度构成**。\n');
+}
+
+main().catch(error => {
+  process.stderr.write(`[baseline] 失败：${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});