@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-story-builder/skeleton-output.js

@@ -0,0 +1,199 @@
+/**
+ * skeleton-output.js —— 骨架阶段的产出盘点
+ *
+ * 与 flesh-output.js / rhythm-output.js 同构，但对象是骨架阶段的 4 个产物文件。
+ *
+ * 盘点要回答两个问题（插件据此决定能不能报"完成"）：
+ *   1. 4 个产物文件是不是都落地了？
+ *   2. 全量校验（--all）过没过？
+ *
+ * 第 2 条对骨架尤其要紧：引用完整性（SKELETON_REF_MISSING）、
+ * 图连通性（G_ISOLATED）、配额一致性（QUOTA_MISMATCH）
+ * 全都是跨文件口径，单文件校验过不代表阶段过。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 骨架阶段的 4 个产出文件（顺序 = 生成依赖顺序）
+export const SKELETON_OUTPUT_FILES = [
+  '框架.json',
+  '实体.json',
+  '关系.json',
+  '层级.json'
+];
+
+/**
+ * 盘点骨架阶段的产出。
+ *
+ * @param {string} stageDir 骨架阶段目录
+ * @returns {Object} { present, missing, complete }
+ */
+export function inspectSkeletonOutput(stageDir) {
+  const present = [];
+  const missing = [];
+  for (const f of SKELETON_OUTPUT_FILES) {
+    const p = path.join(stageDir, f);
+    let ok = false;
+    try {
+      ok = fs.existsSync(p) && fs.statSync(p).size > 0;
+    } catch {
+      ok = false;
+    }
+    if (ok) present.push(f);
+    else missing.push(f);
+  }
+  return { present, missing, complete: missing.length === 0 };
+}
+
+/**
+ * 读骨架阶段的 .stage-status.json，看全量校验的状态。
+ *
+ * @returns {Object} { allCheck, rounds, files, error }
+ */
+export function readSkeletonStageStatus(stageDir) {
+  const p = path.join(stageDir, '.stage-status.json');
+  if (!fs.existsSync(p)) {
+    return { allCheck: null, rounds: 0, files: {}, error: '.stage-status.json 不存在（骨架阶段还没跑过校验）' };
+  }
+  let s;
+  try {
+    s = JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return { allCheck: null, rounds: 0, files: {}, error: '.stage-status.json 解析失败：' + e.message };
+  }
+  if (!s || typeof s !== 'object') {
+    return { allCheck: null, rounds: 0, files: {}, error: '.stage-status.json 内容不是对象' };
+  }
+  const all = s.all_check && typeof s.all_check === 'object' ? s.all_check : {};
+  return {
+    allCheck: all.status || null,
+    rounds: all.rounds || 0,
+    files: (s.files && typeof s.files === 'object') ? s.files : {},
+    error: null
+  };
+}
+
+/**
+ * 生成骨架阶段收尾的结论说明（人类可读、可执行）。
+ */
+/**
+ * 哪些产物文件已经定稿（单文件校验 PASSED，且校验之后没被外部改动）。
+ *
+ * 续跑用：重跑骨架阶段时，已定稿的文件不必再派活重做 ——
+ * 直接沿用磁盘上的产物（下游的批次规划要读它们：
+ * readTargetChapters 读 框架.json 的 capacity，关系批次要读 实体.json 的 id 表）。
+ *
+ * 为什么要续跑：tt5 实测（2026-10-25）骨架阶段一次要派 40+ 批，
+ * 中途任何一次失败（provider 报错 / 连接断开 / 用户 Ctrl-C）都会让
+ * 已定稿的文件被整段重做一遍 —— 框架 + 实体 13 个 turn 全部白烧额度。
+ *
+ * 判没被外部改动**看分片、不看产物**：
+ * 分片是真源（产物 = 分片合并出来的），插件会用分片覆盖被模型改坏的产物
+ * （makeSettledRestorer）—— 那是内容没变的重新落盘，只看产物的 mtime 会误判成
+ * "被改过"从而白白重做一遍（tt5 实测 2026-10-25 端到端验证时，
+ * 框架被重复派活就是这个原因）。
+ *
+ * @param {string} stageDir 骨架阶段目录
+ * @param {Object} [opts]
+ * @param {string} [opts.buildDir] 分片目录（默认 <stageDir>/.skeleton-build）
+ * @returns {Set<string>} 已定稿的文件名（形如 框架.json）
+ */
+export function readSkeletonSettledFiles(stageDir, opts = {}) {
+  const status = readSkeletonStageStatus(stageDir);
+  const buildDir = opts.buildDir || path.join(stageDir, '.skeleton-build');
+  const settled = new Set();
+  for (const file of SKELETON_OUTPUT_FILES) {
+    // .stage-status.json 里的键是**类型名**（校验脚本写的：s.files[fileType]，
+    // skeleton-validate.js:1445），不是带扩展名的文件名 —— 两种都认。
+    const rec = status.files[file.replace(/\.json$/, '')] || status.files[file];
+    if (!rec || rec.status !== 'PASSED') continue;
+    const checkedAt = Date.parse(rec.last_check || '');
+    if (!Number.isFinite(checkedAt)) continue;
+    // 产物要在位
+    const p = path.join(stageDir, file);
+    let st;
+    try {
+      st = fs.statSync(p);
+    } catch {
+      continue;
+    }
+    if (!st.size) continue;
+    // 分片是判据：分片在校验之后被改过 → 内容可能变了 → 得重做
+    const type = file.replace(/\.json$/, '');
+    const prefix = '骨架-' + type + '.b';
+    let names = [];
+    try {
+      names = fs.readdirSync(buildDir);
+    } catch {
+      names = [];
+    }
+    const mine = names.filter((n) => n.startsWith(prefix) && n.endsWith('.json'));
+    if (!mine.length) continue; // 分片没了 → 没法重建 → 重做
+    let touched = false;
+    for (const n of mine) {
+      try {
+        const s = fs.statSync(path.join(buildDir, n));
+        if (s.mtimeMs > checkedAt + 2000) {
+          touched = true;
+          break;
+        }
+      } catch {
+        touched = true;
+        break;
+      }
+    }
+    if (touched) continue;
+    settled.add(file);
+  }
+  return settled;
+}
+
+export function buildSkeletonCompletionNote(inspect, status) {
+  const lines = [];
+  const allCheck = status.allCheck;
+  const missing = inspect.missing;
+
+  if (inspect.complete && allCheck === 'PASSED') {
+    lines.push('骨架阶段产出检查：4 个 JSON 齐全，全量校验（--all）已通过。');
+    lines.push('');
+    lines.push('产出文件：');
+    for (const f of inspect.present) lines.push('- 设定/raw/sources/骨架/' + f);
+    return lines.join('\n');
+  }
+
+  lines.push('骨架阶段产出检查：**未通过**，当前状态如下。');
+  lines.push('');
+
+  if (!inspect.complete) {
+    lines.push('- 缺失文件（' + missing.length + '/' + SKELETON_OUTPUT_FILES.length + '）：' + missing.join('、'));
+    lines.push('  骨架阶段是逐批派活的，任一段没跑完，下游那一段就不会开工');
+    lines.push('  （框架 → 实体 → 关系+层级，段间有依赖门禁）。');
+  } else {
+    lines.push('- 4 个 JSON 都已产出。');
+  }
+
+  lines.push('');
+  if (allCheck === 'PASSED') {
+    lines.push('- 全量校验：PASSED（但文件集合与校验记录不一致，需要人工核对）。');
+  } else if (allCheck === 'FAILED') {
+    lines.push('- 全量校验：FAILED（跨文件一致性没通过：引用完整性 / 图连通性 / 配额一致性都在 --all 里查）。');
+  } else if (allCheck === 'STALE') {
+    lines.push('- 全量校验：**STALE**（单文件校验把已通过的全量结论作废了，必须重新跑一次 --all）。');
+  } else if (allCheck === 'PENDING') {
+    lines.push('- 全量校验：**PENDING**（从未跑过 --all，引用完整性、图连通性、配额一致性全都没验过）。');
+  } else {
+    lines.push('- 全量校验：**未运行**（' + (status.error || '状态不可读') + '）。');
+  }
+
+  lines.push('');
+  lines.push('下一步：');
+  if (!inspect.complete) {
+    lines.push('1. 重新运行骨架阶段，补齐缺失文件：' + missing.join('、'));
+    lines.push('2. 4 个文件齐了之后，必须再跑一次全量校验（--all），确认 all_check.status = PASSED。');
+  } else {
+    lines.push('1. 跑一次全量校验（--all），把 errors 逐条改掉；');
+    lines.push('2. 直到 all_check.status = PASSED 再进入血肉阶段。');
+  }
+
+  return lines.join('\n');
+}