@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/scripts/v2/context.js

@@ -0,0 +1,434 @@
+/**
+ * v2/context.js —— 阶段自包含：_context 快照、bundle.json、README、导出。
+ *
+ * 每个阶段目录都可以整体交给另一个 LLM：
+ *   - _context/ 是上游只读快照
+ *   - bundle.json 说明读法、数量快照和校验项
+ *   - README.md 是本阶段契约
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  V2_STAGE_BY_ID,
+  asArray,
+  contentHash,
+  ensureDir,
+  fileExists,
+  hashFile,
+  nowIso,
+  readJson,
+  readText,
+  relProjectPath,
+  stageDir,
+  stageFile,
+  stageHash,
+  writeJsonAtomic,
+  writeTextAtomic,
+} from './core.js';
+import { contractFor, renderContractMarkdown } from './contracts.js';
+import { renderOutlineMarkdown, renderStageMarkdown } from './export-markdown.js';
+
+/** 每个阶段需要哪些上游快照。 */
+export function contextSpecs(stageId) {
+  const base = {
+    file: 'baseline.json',
+    sources: ['00-baseline/input.json', '00-baseline/references.json'],
+    merge: 'baseline',
+  };
+  switch (stageId) {
+    case '10-scale':
+      return [
+        base,
+        { file: 'formulas.json', sources: ['00-baseline/formulas.json'], merge: 'single' },
+      ];
+    case '20-macro':
+      return [
+        base,
+        { file: 'scale.json', sources: ['10-scale/scale.json'], merge: 'single' },
+      ];
+    case '30-cast':
+      return [
+        base,
+        { file: 'scale.json', sources: ['10-scale/scale.json'], merge: 'single' },
+        {
+          file: 'macro.json',
+          sources: ['world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'].map((n) => '20-macro/' + n),
+          merge: 'macro',
+        },
+      ];
+    case '40-rhythm':
+      return [
+        base,
+        { file: 'scale.json', sources: ['10-scale/scale.json'], merge: 'single' },
+        {
+          file: 'macro.json',
+          sources: ['world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'].map((n) => '20-macro/' + n),
+          merge: 'macro',
+        },
+        {
+          file: 'cast.json',
+          sources: ['characters.json', 'factions.json', 'locations.json', 'items.json', 'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json', 'relations.json', 'information.json'].map((n) => '30-cast/' + n),
+          merge: 'cast',
+        },
+      ];
+    case '50-writing':
+      return [
+        base,
+        { file: 'scale.json', sources: ['10-scale/scale.json'], merge: 'single' },
+        {
+          file: 'macro.json',
+          sources: ['world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'].map((n) => '20-macro/' + n),
+          merge: 'macro',
+        },
+        {
+          file: 'cast.json',
+          sources: ['characters.json', 'factions.json', 'locations.json', 'items.json', 'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json', 'relations.json', 'information.json'].map((n) => '30-cast/' + n),
+          merge: 'cast',
+        },
+        { file: 'rhythm.json', sources: ['40-rhythm/chapter_map.json', '40-rhythm/index.json'], merge: 'rhythm' },
+      ];
+    case '60-deslop':
+      return [
+        base,
+        { file: 'scale.json', sources: ['10-scale/scale.json'], merge: 'single' },
+      ];
+    default:
+      return [];
+  }
+}
+
+function sourcePath(projectRoot, rel) {
+  return path.join(projectRoot, '设定', rel);
+}
+
+function withoutMeta(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === '_meta') continue;
+    out[key] = item;
+  }
+  return out;
+}
+
+function mergeSources(projectRoot, sources, merge) {
+  const files = sources.map((rel) => ({ rel, data: readJson(sourcePath(projectRoot, rel), null) }));
+  const present = files.filter((x) => x.data !== null);
+  if (!present.length) return null;
+  if (merge === 'single') return withoutMeta(present[0].data);
+  if (merge === 'baseline') {
+    const input = present.find((x) => x.rel.endsWith('input.json'));
+    const references = present.find((x) => x.rel.endsWith('references.json'));
+    return {
+      input: input ? input.data : {},
+      references: references ? references.data : [],
+      genre_profiles: withoutMeta(readJson(sourcePath(projectRoot, '00-baseline/genre-profiles.json'), null)),
+    };
+  }
+  if (merge === 'macro') {
+    return {
+      world: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/world.json'), {})),
+      story: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/story.json'), {})),
+      volumes: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/volumes.json'), {})),
+      lines: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/lines.json'), {})),
+      endings: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/endings.json'), {})),
+      emotion: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/emotion.json'), {})),
+      roles: withoutMeta(readJson(sourcePath(projectRoot, '20-macro/roles.json'), {})),
+    };
+  }
+  if (merge === 'cast') {
+    return {
+      characters: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/characters.json'), {})),
+      factions: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/factions.json'), {})),
+      locations: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/locations.json'), {})),
+      items: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/items.json'), {})),
+      conflicts: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/conflicts.json'), {})),
+      foreshadows: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/foreshadows.json'), {})),
+      climaxes: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/climaxes.json'), {})),
+      payoffs: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/payoffs.json'), {})),
+      relations: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/relations.json'), {})),
+      information: withoutMeta(readJson(sourcePath(projectRoot, '30-cast/information.json'), {})),
+    };
+  }
+  if (merge === 'rhythm') {
+    return {
+      chapter_map: withoutMeta(readJson(sourcePath(projectRoot, '40-rhythm/chapter_map.json'), {})),
+      index: withoutMeta(readJson(sourcePath(projectRoot, '40-rhythm/index.json'), {})),
+    };
+  }
+  return null;
+}
+
+function snapshotPayload(projectRoot, spec) {
+  const data = mergeSources(projectRoot, spec.sources, spec.merge);
+  if (data === null) return null;
+  return {
+    _meta: {
+      snapshot_of: spec.sources,
+      source_hash: contentHash(data),
+      snapshot_at: nowIso(),
+      read_only: true,
+    },
+    ...data,
+  };
+}
+
+/**
+ * 生成/刷新阶段的上游快照。
+ * @returns {{ok:boolean, files:string[], errors:Array}}
+ */
+export function ensureContext(projectRoot, stageId) {
+  const dir = path.join(stageDir(projectRoot, stageId), '_context');
+  ensureDir(dir);
+  const written = [];
+  const errors = [];
+  for (const spec of contextSpecs(stageId)) {
+    const payload = snapshotPayload(projectRoot, spec);
+    if (payload === null) {
+      errors.push({
+        code: 'BUNDLE_CONTEXT_SOURCE_MISSING',
+        path: '_context/' + spec.file,
+        message: '上游快照源文件不存在：' + spec.sources.join('、'),
+        hint: '先运行上游阶段，并确认阶段文件已落盘',
+        contract: stageId + '/README.md#self-contained',
+      });
+      continue;
+    }
+    writeJsonAtomic(path.join(dir, spec.file), payload);
+    written.push(spec.file);
+  }
+  return { ok: errors.length === 0, files: written, errors };
+}
+
+export function validateContext(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  const errors = [];
+  const dir = path.join(stageDir(projectRoot, stageId), '_context');
+  for (const item of contextSpecs(stageId)) {
+    const file = path.join(dir, item.file);
+    if (!fileExists(file)) {
+      errors.push({
+        code: 'BUNDLE_CONTEXT_MISSING',
+        path: '_context/' + item.file,
+        message: '缺少上游快照',
+        hint: '运行 /fancy-story-builder ' + stageId + '，插件会刷新快照',
+        contract: stageId + '/README.md#self-contained',
+      });
+      continue;
+    }
+    const snapshot = readJson(file, null);
+    if (!snapshot || !snapshot._meta) {
+      errors.push({ code: 'BUNDLE_CONTEXT_INVALID', path: '_context/' + item.file, message: '快照缺少 _meta', contract: stageId + '/README.md#self-contained' });
+      continue;
+    }
+    const current = snapshotPayload(projectRoot, item);
+    if (!current) {
+      errors.push({ code: 'BUNDLE_CONTEXT_SOURCE_MISSING', path: '_context/' + item.file, message: '上游源文件不存在，快照无法核对', contract: stageId + '/README.md#self-contained' });
+      continue;
+    }
+    if (snapshot._meta.source_hash !== current._meta.source_hash) {
+      errors.push({
+        code: 'BUNDLE_CONTEXT_STALE',
+        path: '_context/' + item.file,
+        message: '上游已变化，快照过期',
+        expected: current._meta.source_hash,
+        actual: snapshot._meta.source_hash,
+        hint: '重新运行本阶段以刷新 _context，或运行 patch 逐层更新',
+        contract: stageId + '/README.md#self-contained',
+      });
+    }
+  }
+  // 阶段目录不能引用项目外文件
+  const scan = (value, p) => {
+    if (typeof value === 'string') {
+      if (path.isAbsolute(value) || /node_modules|fancy-story-builder\/index\.js|plugins\/fancy-story-builder/.test(value)) {
+        errors.push({ code: 'BUNDLE_EXTERNAL_PATH', path: p, message: '阶段文件不能引用项目外或插件源码路径', actual: value, contract: stageId + '/README.md#self-contained' });
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((x, i) => scan(x, p + '[' + i + ']'));
+      return;
+    }
+    if (value && typeof value === 'object') {
+      for (const [k, v] of Object.entries(value)) {
+        if (k === '_meta') continue;
+        scan(v, p ? p + '.' + k : k);
+      }
+    }
+  };
+  for (const name of asArray(spec && spec.requiredFiles)) {
+    const file = path.join(stageDir(projectRoot, stageId), name);
+    if (!fileExists(file)) continue;
+    scan(readJson(file, null), name);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function quantitySnapshot(stageId, scale) {
+  const q = (scale && scale.quotas) || {};
+  const base = {
+    target_chapters: scale && scale.capacity && scale.capacity.target_chapters,
+    target_words: scale && scale.capacity && scale.capacity.target_words,
+    volume_count: scale && scale.structure && scale.structure.volume_count,
+  };
+  if (stageId === '30-cast' || stageId === '40-rhythm' || stageId === '50-writing') {
+    base.character_counts = q.characters || {};
+    base.conflict_counts = q.conflicts || {};
+  }
+  if (stageId === '40-rhythm' || stageId === '50-writing') {
+    base.foreshadow_counts = q.foreshadows || {};
+    base.payoff_counts = q.pleasures || {};
+  }
+  return base;
+}
+
+export function writeBundle(projectRoot, stageId, opts = {}) {
+  const contract = contractFor(stageId);
+  if (!contract) return null;
+  const scale = readJson(stageFile(projectRoot, '10-scale', 'scale.json'), null);
+  const bundle = {
+    schema_version: '2.1',
+    stage: stageId,
+    purpose: contract.purpose,
+    read_order: contract.readOrder,
+    upstream: (V2_STAGE_BY_ID[stageId] && V2_STAGE_BY_ID[stageId].upstream) || [],
+    quantity_snapshot: quantitySnapshot(stageId, scale),
+    checks: contract.checks,
+    forbidden: contract.forbidden,
+    self_contained: {
+      context_dir: '_context',
+      required_files: contextSpecs(stageId).map((x) => '_context/' + x.file),
+    },
+    generated_at: nowIso(),
+    ...opts,
+  };
+  writeJsonAtomic(path.join(stageDir(projectRoot, stageId), 'bundle.json'), bundle);
+  writeTextAtomic(path.join(stageDir(projectRoot, stageId), 'README.md'), renderContractMarkdown(stageId));
+  return bundle;
+}
+
+export function validateBundle(projectRoot, stageId) {
+  const errors = [];
+  const context = validateContext(projectRoot, stageId);
+  errors.push(...context.errors);
+  const bundleFile = path.join(stageDir(projectRoot, stageId), 'bundle.json');
+  const bundle = readJson(bundleFile, null);
+  if (!bundle) {
+    errors.push({ code: 'BUNDLE_MISSING', path: stageId + '/bundle.json', message: '缺少 bundle.json', hint: '运行本阶段会生成', contract: stageId + '/README.md#self-contained' });
+  } else {
+    const required = contextSpecs(stageId).map((x) => '_context/' + x.file);
+    for (const rel of required) {
+      if (!fileExists(path.join(stageDir(projectRoot, stageId), rel))) {
+        errors.push({ code: 'BUNDLE_CONTEXT_MISSING', path: stageId + '/bundle.json', message: 'bundle 要求的上下文文件不存在：' + rel, contract: stageId + '/README.md#self-contained' });
+      }
+    }
+    if (!bundle.quantity_snapshot || !bundle.quantity_snapshot.target_chapters) {
+      errors.push({ code: 'BUNDLE_QUANTITY_MISSING', path: stageId + '/bundle.json', message: 'bundle 缺少数量快照', contract: stageId + '/README.md#self-contained' });
+    }
+  }
+  const readme = path.join(stageDir(projectRoot, stageId), 'README.md');
+  if (!fileExists(readme)) {
+    errors.push({ code: 'BUNDLE_README_MISSING', path: stageId + '/README.md', message: '缺少阶段契约 README.md', contract: stageId + '/README.md#self-contained' });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 把阶段目录导出成一个 Markdown 汇总文件。
+ *
+ * 输出是 `设定/exports/<stageId>/<stageId>.md`；不再复制源 JSON，
+ * 因为导出对象是另一个 LLM，需要的是可读内容，而不是重复的 JSON。
+ */
+export function exportStage(projectRoot, stageId, opts = {}) {
+  const src = stageDir(projectRoot, stageId);
+  if (!fs.existsSync(src)) {
+    return { ok: false, error: '阶段目录不存在：' + stageId, path: null };
+  }
+  const bundle = writeBundle(projectRoot, stageId);
+  const validation = validateBundle(projectRoot, stageId);
+  let rendered;
+  try {
+    rendered = renderStageMarkdown(projectRoot, stageId);
+  } catch (err) {
+    return { ok: false, error: '生成 Markdown 失败：' + (err instanceof Error ? err.message : String(err)), path: null };
+  }
+  const dest = path.join(projectRoot, '设定', 'exports', stageId);
+  // 旧版导出会把整目录复制过来；这里清掉旧文件，避免 JSON 副本继续误导读者。
+  fs.rmSync(dest, { recursive: true, force: true });
+  ensureDir(dest);
+  const file = path.join(dest, stageId + '.md');
+  writeTextAtomic(file, rendered.markdown);
+  return {
+    ok: true,
+    path: relProjectPath(projectRoot, file),
+    markdown: file,
+    files: rendered.files,
+    title: rendered.title,
+    validation,
+    bundle,
+  };
+}
+
+/**
+ * 解析章节引用：稳定 chapter_id（大小写不敏感）、display_no 或文件名。
+ * 返回真实的 chapter_id；找不到返回 null。
+ */
+export function resolveOutlineChapterId(projectRoot, input) {
+  const raw = String(input || '').trim();
+  if (!raw) return null;
+  const rhythmDir = stageDir(projectRoot, '40-rhythm');
+  const outlinesDir = path.join(rhythmDir, 'outlines');
+  if (fileExists(path.join(outlinesDir, raw + '.json'))) return raw;
+
+  const map = readJson(stageFile(projectRoot, '40-rhythm', 'chapter_map.json'), { chapters: [] });
+  const chapters = asArray(map && map.chapters);
+  const byId = chapters.find((c) => String(c.chapter_id).toLowerCase() === raw.toLowerCase());
+  if (byId && fileExists(path.join(outlinesDir, byId.chapter_id + '.json'))) return byId.chapter_id;
+  if (/^\d+$/.test(raw)) {
+    const byNo = chapters.find((c) => Number(c.display_no) === Number(raw));
+    if (byNo && fileExists(path.join(outlinesDir, byNo.chapter_id + '.json'))) return byNo.chapter_id;
+  }
+
+  try {
+    const names = fs.readdirSync(outlinesDir).filter((n) => n.endsWith('.json'));
+    const hit = names.find((n) => n.slice(0, -5).toLowerCase() === raw.toLowerCase());
+    if (hit) return hit.slice(0, -5);
+  } catch {
+    /* outlines 还没生成 */
+  }
+  return null;
+}
+
+/** 导出单章细纲为一个 Markdown 文件。 */
+export function exportOutline(projectRoot, chapterRef) {
+  const chapterId = resolveOutlineChapterId(projectRoot, chapterRef);
+  if (!chapterId) {
+    return { ok: false, error: '细纲不存在：' + chapterRef, path: null, errors: [] };
+  }
+  let rendered;
+  try {
+    rendered = renderOutlineMarkdown(projectRoot, chapterId);
+  } catch (err) {
+    return { ok: false, error: '生成 Markdown 失败：' + (err instanceof Error ? err.message : String(err)), path: null, errors: [] };
+  }
+  if (!rendered) return { ok: false, error: '细纲不存在：' + chapterRef, path: null, errors: [] };
+  const dest = path.join(projectRoot, '设定', 'exports', '40-rhythm', chapterId);
+  fs.rmSync(dest, { recursive: true, force: true });
+  ensureDir(dest);
+  const file = path.join(dest, chapterId + '.md');
+  writeTextAtomic(file, rendered.markdown);
+  return {
+    ok: true,
+    path: relProjectPath(projectRoot, file),
+    markdown: file,
+    chapterId,
+    files: rendered.files,
+    outline: rendered.outline,
+  };
+}
+
+/** 读取导出目录里的 bundle（供测试/自包含检查）。 */
+export function readExportedBundle(projectRoot, stageId) {
+  return readJson(path.join(projectRoot, '设定', 'exports', stageId, 'bundle.json'), null);
+}