@customize-agent/server 4.60.31 → 4.60.32

package/scripts/capture-baseline.mjs

@@ -1,353 +0,0 @@
-#!/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. 基线与被评的那份文档**逐字段同源**（不会出现「基线是另一轮跑的」这种不可比）；
- *
- * ## 用法
- *
- * ```bash
- * # 采集一份既有归档（docId 见 generatedDocuments/index.json）
- * node apps/server/scripts/capture-baseline.mjs --project-root . --doc doc-1790407778481-d7a36837
- * # 采集最近 N 份
- * node apps/server/scripts/capture-baseline.mjs --project-root . --latest 2
- * ```
- *
- * 落盘：`~/.customize-agent/baselines/<时间戳>-<label>.baseline.json`（**append-only**，
- * 不覆盖历史基线——「同代码重跑波动 ±7」这件事只能靠多份基线看出来）。
- *
- */
-
-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: [], corpora: [], latest: 0, label: '', baseUrl: DEFAULT_BASE_URL, timeoutMinutes: 90 };
-  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 === '--corpus') args.corpora.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 === '--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 份已完成文档',
-    '  --corpus <关键词>      **按既有归档的输入原样重跑一份**再采集（可重复）：从归档里找最近一份',
-    '                         匹配该关键词（材料组名/要求文本）的记录，用它的 promptIds/requirement/',
-    '                         title/materialRoot 重跑——这是"改了代码之后同一份语料还能不能达到同样质量"',
-    '                         的取数方式（含巢湖/合工大这类真实语料）',
-    '  --label <name>         基线标签（默认 baseline）',
-    '  --base-url <url>       服务地址（默认 http://localhost:17321）',
-    '  --timeout-minutes <N>  单份生成等待上限（默认 90）',
-    '',
-    '',
-  ].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?.contractQuality;
-  const score = report?.score;
-  return {
-    contractId: report?.contractId ?? null,
-    documentHash: report?.documentHash ?? null,
-    dimensions: score?.dimensions ?? null,
-    deliveryReady: score?.deliveryReady ?? null,
-    verificationComplete: score?.verificationComplete ?? null,
-    qualityRated: score?.qualityRated ?? null,
-    qualityGaps: score?.qualityGaps ?? null,
-    measuredCriteria: Array.isArray(report?.findings) ? report.findings.length : null,
-    // 导出门禁保留实际阻断数；缺少评价回执不能当作零分或通过。
-    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 || {};
-  const startedAt = num(record.createdAt);
-  const endedAt = num(record.completedAt);
-  const elapsedMs = num(record.elapsedMs) ?? (startedAt !== null && endedAt !== null && endedAt >= startedAt ? endedAt - startedAt : null);
-  return {
-    schema: 'capture-baseline/v1',
-    capturedAt: new Date().toISOString(),
-    recordContentHash: crypto.createHash('sha256').update(JSON.stringify(record)).digest('hex'),
-    runId: record.runId ?? null,
-    workflowVersion: record.workflowVersion ?? null,
-    // 阶段墙钟不能相加当成等待时间；并发阶段与调用耗时可能重叠。
-    metrics: diagnostics.metrics ?? record.reviewMetadata?.metrics ?? record.draft?.reviewMetadata?.diagnostics?.metrics ?? null,
-    doc: {
-      id: record.id, title: record.title, templateId: record.templateId, templateName: record.templateName,
-      status: record.status, 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 || '',
-  };
-}
-
-function baselinesDir() { return path.join(os.homedir(), '.customize-agent', 'baselines'); }
-
-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 };
-}
-
-/**
- * ★ 实测修正（2026-09-30，A3 腿）：轮询超时 60s → **180s**，且**轮询失败不再终止采集**。
- *
- * 现场：生成中的服务端被 LLM 调用打满时，列表端点可能 >60s 才回答，`AbortSignal.timeout(60000)`
- * 直接抛 `The operation was aborted due to timeout` ⇒ **采集脚本死在轮询上，而生成还在跑**
- * （本轮 A3 腿就是这么丢的：脚本 05:29 报失败、文档仍在 generating）。
- * 采集器的职责是"等"，不是"因为服务忙就放弃"——超时只该由 `deadline`（`--timeout-minutes`）决定。
- */
-async function getJson(url, timeoutMs = 180000) {
-  try {
-    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 }; }
-  } catch (error) {
-    // 轮询失败 ⇒ 返回空体（调用方继续等）；**不 throw**（服务忙不等于生成失败）
-    process.stdout.write(`[baseline] 轮询失败（继续等，不影响生成）：${error instanceof Error ? error.message : String(error)}\n`);
-    return { status: 0, body: undefined };
-  }
-}
-
-const TERMINAL = new Set(['completed', 'completed_with_issues', 'warning', 'failed', 'aborted']);
-
-/**
- * ★ 2026-09-28：触发入参改成 **§12.1 三字段 + 语料四件套**（原实现传的是已退役的 `templateId` 单字段）。
- * `corpus` 给出时，用它的 `promptIds/requirement/title/materialRoot` **原样重跑**——
- * 语料可复现是基线可比的前提（换了提示词或材料组就不是同一份文档了）。
- */
-async function triggerAndWait({ baseUrl, projectRoot, corpus, timeoutMinutes }) {
-  const started = await postJson(`${baseUrl}/api/documents/generate`,
-    { promptIds: corpus.promptIds, requirement: corpus.requirement || '', title: corpus.title, materialRoot: corpus.materialRoot, 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] 已触发 ${corpus.title}（语料：${corpus.materialRoot}） → ${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'));
-}
-
-/**
- * ★ 2026-09-28：按关键词找**最近的语料记录**并抽出重跑所需的输入（四件套 + 项目根）。
- * 匹配面：`materialRoot`（材料组名）与 `requirement`（要求文本）——真实语料通常两者都带关键词。
- */
-function findCorpus({ projectRoot, keyword }) {
-  const dir = path.join(archiveDir(projectRoot), 'drafts');
-  if (!fs.existsSync(dir)) throw new Error(`归档目录不存在：${dir}`);
-  const candidates = fs.readdirSync(dir)
-    .filter(name => name.endsWith('.json') && !name.endsWith('.meta.json'))
-    .map(name => {
-      const full = path.join(dir, name);
-      try { return { full, stat: fs.statSync(full), record: JSON.parse(fs.readFileSync(full, 'utf8')) }; } catch { return undefined; }
-    })
-    .filter(Boolean)
-    .filter(item => `${item.record.materialRoot || ''} ${item.record.requirement || ''} ${item.record.title || ''}`.includes(keyword))
-    .sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs);
-  if (candidates.length === 0) throw new Error(`归档里找不到含「${keyword}」的记录（材料组名/要求文本/标题都没命中）：${dir}`);
-  const newest = candidates[0].record;
-  if (!newest.promptIds?.length) throw new Error(`「${keyword}」最近一份记录没有 promptIds（旧记录），无法原样重跑`);
-  return {
-    sourceDocId: newest.id,
-    promptIds: newest.promptIds,
-    requirement: newest.requirement || '',
-    title: newest.templateName || newest.title || '',
-    materialRoot: newest.materialRoot || '',
-    projectRoot: newest.projectRoot || projectRoot,
-  };
-}
-
-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));
-  const records = [];
-
-  /**
-   * ★ 2026-09-28：**按既有归档的输入原样重跑**（真实语料基线：巢湖 / 合工大这类）。
-   * 每个关键词解析出一份语料四件套，逐份触发 + 等待 + 采集——同一份语料在改动前后各跑一次，
-   * 两次的 `*.baseline.json` 可直接 diff（脚本的产物是可 diff 的基线，判定仍不在这里）。
-   */
-  for (const keyword of args.corpora) {
-    const corpus = findCorpus({ projectRoot: args.projectRoot, keyword });
-    process.stdout.write(`[baseline] 语料「${keyword}」命中 ${corpus.sourceDocId}：标题「${corpus.title}」材料组「${corpus.materialRoot}」\n`);
-    records.push(await triggerAndWait({ baseUrl: args.baseUrl, projectRoot: args.projectRoot, corpus, 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, '-');
-  const label = args.label || 'baseline';
-  const outDir = baselinesDir();
-  fs.mkdirSync(outDir, { recursive: true });
-  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}  ${item.doc.elapsedMs === null ? '耗时未知' : Math.round(item.doc.elapsedMs / 60000) + 'min'}\n`
-      + `    综合区间=${item.scores.overallInterval.lower ?? '?'}～${item.scores.overallInterval.upper ?? '?'}  阻断=${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) + '%' : '?'}）\n`,
-    );
-  }
-  process.stdout.write(`[baseline] 落盘：${outFile}\n`);
-  process.stdout.write('[baseline] 基线只抄写归档已有值，未测项保留为空。\n');
-
-}
-
-main().catch(error => {
-  process.stderr.write(`[baseline] 失败：${error instanceof Error ? error.message : String(error)}\n`);
-  process.exit(1);
-});