@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -0,0 +1,419 @@
+/**
+ * v2/core.js —— fancy-story-builder 2.0 的共享基础
+ *
+ * 这里只放确定性能力：
+ *   - 阶段/目录/文件契约
+ *   - 统一 JSON 读写与内容哈希
+ *   - 阶段状态与 wiki 状态映射
+ *   - 项目内的相对路径
+ *
+ * 不在这里做 LLM 调用，也不做任何"猜依赖"的判断。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const SCHEMA_VERSION = '2.1';
+export const CONTRACT_VERSION = '2026-11-06';
+
+export const V2_STAGES = [
+  {
+    id: '00-baseline',
+    label: '输入基线',
+    dir: '00-baseline',
+    upstream: [],
+    requiredFiles: ['input.json', 'references.json', 'formulas.json'],
+  },
+  {
+    id: '10-scale',
+    label: '数量',
+    dir: '10-scale',
+    upstream: ['00-baseline'],
+    requiredFiles: ['scale.json'],
+  },
+  {
+    id: '20-macro',
+    label: '宏观',
+    dir: '20-macro',
+    upstream: ['10-scale'],
+    requiredFiles: ['world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'],
+  },
+  {
+    id: '30-cast',
+    label: '实体',
+    dir: '30-cast',
+    upstream: ['10-scale', '20-macro'],
+    requiredFiles: [
+      'characters.json', 'factions.json', 'locations.json', 'items.json',
+      'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json',
+      'relations.json', 'information.json',
+    ],
+  },
+  {
+    id: '40-rhythm',
+    label: '节奏',
+    dir: '40-rhythm',
+    upstream: ['10-scale', '20-macro', '30-cast'],
+    requiredFiles: ['chapter_map.json'],
+  },
+  {
+    id: '50-writing',
+    label: '正文',
+    dir: '50-writing',
+    upstream: ['40-rhythm'],
+    requiredFiles: ['ledger.json'],
+  },
+  {
+    id: '60-deslop',
+    label: '去味',
+    dir: '60-deslop',
+    upstream: ['50-writing'],
+    requiredFiles: [],
+  },
+];
+
+export const V2_STAGE_BY_ID = Object.fromEntries(V2_STAGES.map((s) => [s.id, s]));
+export const V2_STAGE_IDS = V2_STAGES.map((s) => s.id);
+
+export const STAGE_ORDER = V2_STAGE_IDS.slice();
+
+/** 旧命令/旧目录 → 新阶段。迁移与兼容都从这里取，避免两处写死。 */
+export const V1_TO_V2_STAGE = {
+  skeleton: '10-scale',
+  flesh: '30-cast',
+  rhythm: '40-rhythm',
+  writing: '50-writing',
+  deslop: '60-deslop',
+};
+
+export const V1_STAGE_DIR = {
+  skeleton: '骨架',
+  flesh: '血肉',
+  rhythm: '节奏',
+  writing: '写作',
+};
+
+/**
+ * 阶段目录：设定/<stage dir>。
+ * 注意：不是 设定/raw/sources/<旧目录>；2.0 的阶段目录是并列的。
+ */
+export function stageDir(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  if (!spec) throw new Error('未知阶段：' + stageId);
+  return path.join(projectRoot, '设定', spec.dir);
+}
+
+export function stageFile(projectRoot, stageId, name) {
+  return path.join(stageDir(projectRoot, stageId), name);
+}
+
+export function legacyStageDir(projectRoot, stageId) {
+  const name = V1_STAGE_DIR[stageId];
+  if (!name) return null;
+  return path.join(projectRoot, '设定', 'raw', 'sources', name);
+}
+
+export function isV2Project(projectRoot) {
+  if (!projectRoot) return false;
+  return ['10-scale', '20-macro', '30-cast', '40-rhythm'].some((id) =>
+    fs.existsSync(stageDir(projectRoot, id))
+  ) || fs.existsSync(path.join(projectRoot, '设定', 'manifest.json'));
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export function readText(file, fallback = null) {
+  try {
+    return fs.readFileSync(file, 'utf-8');
+  } catch {
+    return fallback;
+  }
+}
+
+export function fileExists(file) {
+  try {
+    return fs.existsSync(file) && fs.statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** 原子写 JSON：临时文件 → rename。 */
+export function writeJsonAtomic(file, value) {
+  ensureDir(path.dirname(file));
+  const tmp = file + '.tmp-' + process.pid + '-' + Date.now();
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, file);
+  } finally {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // 清理失败不掩盖主流程
+    }
+  }
+  return file;
+}
+
+/** 原子写文本。 */
+export function writeTextAtomic(file, text) {
+  ensureDir(path.dirname(file));
+  const tmp = file + '.tmp-' + process.pid + '-' + Date.now();
+  try {
+    fs.writeFileSync(tmp, text, 'utf-8');
+    fs.renameSync(tmp, file);
+  } finally {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // ignore
+    }
+  }
+  return file;
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+/** 去掉 _meta 后，对键名递归排序，得到稳定 JSON。 */
+export function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      if (key === '_meta') continue;
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function contentHash(value) {
+  const stable = JSON.stringify(canonicalize(value));
+  return 'sha256:' + crypto.createHash('sha256').update(stable, 'utf-8').digest('hex');
+}
+
+export function bytesHash(bytes) {
+  return 'sha256:' + crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+export function hashFile(file) {
+  const data = readJson(file, null);
+  if (data !== null) return contentHash(data);
+  try {
+    return bytesHash(fs.readFileSync(file));
+  } catch {
+    return null;
+  }
+}
+
+/** 阶段聚合哈希：所有业务 JSON 内容哈希再哈希，顺序固定。 */
+export function stageHash(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  if (!spec) return null;
+  const dir = stageDir(projectRoot, stageId);
+  const entries = [];
+  const walk = (current) => {
+    let names = [];
+    try {
+      names = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of names) {
+      if (entry.name.startsWith('.') || entry.name === '_context' || entry.name === 'bundle.json' || entry.name === 'README.md') continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (['outlines', 'chapters', 'timelines'].includes(entry.name)) walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.json') && !entry.name.endsWith('.md')) continue;
+      const rel = path.relative(dir, full).split(path.sep).join('/');
+      entries.push(rel + ':' + hashFile(full));
+    }
+  };
+  walk(dir);
+  entries.sort();
+  if (!entries.length) return null;
+  return 'sha256:' + crypto.createHash('sha256').update(entries.join('\n'), 'utf-8').digest('hex');
+}
+
+export function relProjectPath(projectRoot, file) {
+  return path.relative(projectRoot, file).split(path.sep).join('/');
+}
+
+export function wikiStatus(status) {
+  switch (status) {
+    case 'passed':
+      return 'done';
+    case 'revised':
+    case 'locked':
+      return 'revised';
+    case 'archived':
+    case 'deprecated':
+      return 'archived';
+    case 'stub':
+      return 'stub';
+    default:
+      return 'draft';
+  }
+}
+
+export function isTerminalStageStatus(status) {
+  return status === 'passed';
+}
+
+/**
+ * 读 v2 阶段状态。
+ * 兼容旧阶段：没有 v2 .stage-status.json 时，读旧骨架/血肉/节奏的 all_check。
+ */
+export function readStageStatus(projectRoot, stageId, opts = {}) {
+  const file = path.join(stageDir(projectRoot, stageId), '.stage-status.json');
+  const data = readJson(file, null);
+  if (data && typeof data === 'object') {
+    return {
+      stage: data.stage || stageId,
+      status: data.status || 'draft',
+      files: data.files || {},
+      checkedAt: data.checked_at || null,
+      errors: Array.isArray(data.errors) ? data.errors : [],
+      warnings: Array.isArray(data.warnings) ? data.warnings : [],
+      source: 'v2',
+    };
+  }
+  const legacy = opts.allowLegacy === false ? null : legacyStageDir(projectRoot, Object.keys(V1_STAGE_DIR).find((k) => V1_TO_V2_STAGE[k] === stageId));
+  if (legacy) {
+    const old = readJson(path.join(legacy, '.stage-status.json'), null);
+    const all = old && old.all_check && old.all_check.status;
+    if (all) {
+      return {
+        stage: stageId,
+        status: all === 'PASSED' ? 'passed' : (all === 'FAILED' ? 'stale' : 'draft'),
+        files: old.files || {},
+        checkedAt: old.all_check && old.all_check.last_check || null,
+        errors: [],
+        warnings: [],
+        source: 'v1',
+      };
+    }
+  }
+  return { stage: stageId, status: 'draft', files: {}, checkedAt: null, errors: [], warnings: [], source: null };
+}
+
+export function writeStageStatus(projectRoot, stageId, report) {
+  const file = path.join(stageDir(projectRoot, stageId), '.stage-status.json');
+  const payload = {
+    schema_version: SCHEMA_VERSION,
+    stage: stageId,
+    status: report && report.ok ? 'passed' : (report && report.status) || 'stale',
+    checked_at: nowIso(),
+    files: report && report.files || {},
+    errors: report && report.errors || [],
+    warnings: report && report.warnings || [],
+  };
+  writeJsonAtomic(file, payload);
+  return payload;
+}
+
+/**
+ * 统一错误对象。错误只允许指向项目内文件，不允许出现插件源码路径。
+ */
+export function v2Error(code, opts = {}) {
+  const out = {
+    code,
+    severity: opts.severity || 'error',
+    path: opts.path || '',
+    message: opts.message || '',
+  };
+  if (opts.expected !== undefined) out.expected = opts.expected;
+  if (opts.actual !== undefined) out.actual = opts.actual;
+  if (opts.hint) out.hint = String(opts.hint).replace(/node_modules|plugins\/fancy-story-builder|scripts\//g, '项目契约文件');
+  if (opts.contract) out.contract = opts.contract;
+  if (opts.reference) out.reference = opts.reference;
+  return out;
+}
+
+/** 读数组字段，永远返回数组。 */
+export function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+/** 从任意 JSON 值里取 id → 对象的映射。 */
+export function indexById(list) {
+  const map = new Map();
+  for (const row of asArray(list)) {
+    if (row && typeof row.id === 'string' && row.id) map.set(row.id, row);
+  }
+  return map;
+}
+
+/** 所有字符串里出现过的 id 集合（用于引用检查）。 */
+export function stringsOf(value, out = []) {
+  if (typeof value === 'string') out.push(value);
+  else if (Array.isArray(value)) for (const item of value) stringsOf(item, out);
+  else if (value && typeof value === 'object') for (const item of Object.values(value)) stringsOf(item, out);
+  return out;
+}
+
+/** 字段路径取值：a.b[0].c */
+export function getByPath(obj, dotted) {
+  let cur = obj;
+  for (const part of String(dotted || '').split('.')) {
+    if (!part) continue;
+    const m = /^([^\[\]]+)(?:\[(\d+)\])?$/.exec(part);
+    if (!m) return undefined;
+    if (cur === null || cur === undefined) return undefined;
+    cur = cur[m[1]];
+    if (m[2] !== undefined) {
+      if (!Array.isArray(cur)) return undefined;
+      cur = cur[Number(m[2])];
+    }
+  }
+  return cur;
+}
+
+export function setByPath(obj, dotted, value) {
+  const parts = String(dotted || '').split('.').filter(Boolean);
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (!cur[key] || typeof cur[key] !== 'object') cur[key] = {};
+    cur = cur[key];
+  }
+  if (parts.length) cur[parts[parts.length - 1]] = value;
+  return obj;
+}
+
+export function formatErrorLine(e) {
+  const code = e && e.code ? '[' + e.code + '] ' : '';
+  const p = e && e.path ? e.path + '：' : '';
+  const msg = e && (e.message || e.detail) ? (e.message || e.detail) : '';
+  const hint = e && e.hint ? '（' + e.hint + '）' : '';
+  return code + p + msg + hint;
+}
+
+export function summarizeReport(report, limit = 12) {
+  if (!report) return '未知错误';
+  const errors = Array.isArray(report.errors) ? report.errors : [];
+  const warnings = Array.isArray(report.warnings) ? report.warnings : [];
+  const lines = [];
+  for (const e of errors.slice(0, limit)) lines.push('- ' + formatErrorLine(e));
+  if (errors.length > limit) lines.push('- … 其余 ' + (errors.length - limit) + ' 个错误');
+  if (!errors.length && warnings.length) {
+    for (const w of warnings.slice(0, limit)) lines.push('- [warning] ' + formatErrorLine(w));
+  }
+  return lines.join('\n') || '无错误';
+}