@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -0,0 +1,538 @@
+/**
+ * v2/manifest.js —— 项目级依赖图与实体索引。
+ *
+ * 设计原则：
+ *   - 业务 JSON 只声明 _meta.upstream（我来自哪里）；
+ *   - 下游关系全部由 manifest 计算（谁引用了我）；
+ *   - patch 只按图遍历，不靠 LLM 猜依赖。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  SCHEMA_VERSION,
+  V2_STAGES,
+  V2_STAGE_BY_ID,
+  STAGE_ORDER,
+  asArray,
+  bytesHash,
+  contentHash,
+  hashFile,
+  nowIso,
+  readJson,
+  readStageStatus,
+  relProjectPath,
+  stageDir,
+  stageHash,
+  writeJsonAtomic,
+} from './core.js';
+
+export const MANIFEST_PATH = ['设定', 'manifest.json'];
+
+const STAGE_UPSTREAM = {
+  '00-baseline': [],
+  '10-scale': ['00-baseline'],
+  '20-macro': ['10-scale'],
+  '30-cast': ['10-scale', '20-macro'],
+  '40-rhythm': ['10-scale', '20-macro', '30-cast'],
+  '50-writing': ['40-rhythm'],
+  '60-deslop': ['50-writing'],
+};
+
+const ENTITY_TYPE_BY_KEY = {
+  characters: '人物',
+  factions: '势力',
+  locations: '地点',
+  items: '道具',
+  conflicts: '冲突',
+  foreshadows: '伏笔',
+  climaxes: '高潮',
+  payoffs: '爽点',
+  endings: '结局',
+  world_rules: '世界观',
+  main_line: '主线',
+  branches: '支线',
+  roles: '角色功能位',
+  character_relations: '关系',
+  faction_relations: '势力关系',
+  memberships: '势力成员',
+  information_gaps: '信息差',
+  chapters: '章',
+  chapters_map: '章',
+};
+
+const ENTITY_PREFIX = {
+  C: '人物',
+  F: '势力',
+  L: '地点',
+  P: '道具',
+  X: '冲突',
+  FS: '伏笔',
+  CL: '高潮',
+  PL: '爽点',
+  E: '结局',
+  R: '世界观',
+  M: '主线',
+  B: '支线',
+  REL: '关系',
+  FREL: '势力关系',
+  MEM: '势力成员',
+  IG: '信息差',
+  CH: '章',
+  ROLE: '角色功能位',
+};
+
+function stageFiles(projectRoot, stageId) {
+  const dir = stageDir(projectRoot, stageId);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (current) => {
+    let names = [];
+    try {
+      names = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of names) {
+      const name = entry.name;
+      if (name.startsWith('.')) continue;
+      if (name === '_context' || name === 'bundle.json' || name === 'README.md') continue;
+      const full = path.join(current, name);
+      if (entry.isDirectory()) {
+        if (name === 'outlines' || name === 'chapters' || name === 'timelines') walk(full);
+        continue;
+      }
+      if (name.endsWith('.json') || name.endsWith('.md')) out.push(full);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+function fileNodeId(projectRoot, stageId, file) {
+  const rel = path.relative(stageDir(projectRoot, stageId), file).split(path.sep).join('/');
+  if (stageId === '40-rhythm' && rel.startsWith('outlines/')) {
+    return '40-rhythm.outline.' + rel.replace(/^outlines\//, '').replace(/\.json$/, '');
+  }
+  if (stageId === '50-writing' && rel.startsWith('chapters/')) {
+    return '50-writing.chapter.' + rel.replace(/^chapters\//, '').replace(/\.md$/, '');
+  }
+  return stageId + '.' + rel.replace(/\.(json|md)$/, '').replace(/\//g, '.');
+}
+
+function expectedUpstream(stageId, rel) {
+  if (stageId === '00-baseline') return [];
+  if (stageId === '10-scale') return ['00-baseline'];
+  if (stageId === '20-macro') return ['10-scale'];
+  if (stageId === '30-cast') return ['10-scale', '20-macro'];
+  if (stageId === '40-rhythm') {
+    if (rel.startsWith('outlines/')) return ['40-rhythm.chapter_map', '10-scale', '20-macro', '30-cast'];
+    if (rel.startsWith('timelines/') || rel === 'index.json') return ['40-rhythm.chapter_map'];
+    return ['10-scale', '20-macro', '30-cast'];
+  }
+  if (stageId === '50-writing') return ['40-rhythm'];
+  if (stageId === '60-deslop') return ['50-writing'];
+  return [];
+}
+
+function metaUpstream(data) {
+  const raw = data && data._meta && data._meta.upstream;
+  if (!Array.isArray(raw)) return null;
+  return raw.map((x) => (typeof x === 'string' ? x : x && x.node_id)).filter(Boolean);
+}
+
+function entityTypeOf(key, id) {
+  if (key && ENTITY_TYPE_BY_KEY[key]) return ENTITY_TYPE_BY_KEY[key];
+  const prefix = String(id || '').match(/^(FREL|REL|MEM|ROLE|FS|CL|PL|IG|CH|[CFLPXEMRB])/);
+  if (prefix) return ENTITY_PREFIX[prefix[1]] || '';
+  return '';
+}
+
+function scanEntities(value, out, keyHint) {
+  if (Array.isArray(value)) {
+    for (const item of value) scanEntities(item, out, keyHint);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  const entityId = typeof value.id === 'string' && value.id
+    ? value.id
+    : (typeof value.chapter_id === 'string' && value.chapter_id ? value.chapter_id : null);
+  if (entityId) {
+    const type = entityTypeOf(keyHint, entityId);
+    if (type) {
+      out.push({
+        id: entityId,
+        type,
+        name: value.name || value.title || '',
+        key: keyHint || '',
+        display_no: value.display_no,
+      });
+    }
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (key === '_meta') continue;
+    scanEntities(child, out, key);
+  }
+}
+
+function tokensIn(text) {
+  const set = new Set();
+  const re = /\b(?:ROLE-[A-Z0-9-]+|IG-[A-Za-z0-9-]+|[A-Z]{1,3}-?\d{3,})\b/g;
+  let m;
+  while ((m = re.exec(text)) !== null) set.add(m[0]);
+  return set;
+}
+
+function stageNode(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  const status = readStageStatus(projectRoot, stageId, { allowLegacy: false });
+  return {
+    kind: 'stage',
+    stage: stageId,
+    label: spec.label,
+    path: path.join('设定', spec.dir).split(path.sep).join('/'),
+    status: status.status,
+    hash: stageHash(projectRoot, stageId),
+    upstream: STAGE_UPSTREAM[stageId] || [],
+    files: [],
+    updated_at: nowIso(),
+  };
+}
+
+/**
+ * 构建 manifest。write=true 时写回 设定/manifest.json。
+ */
+export function buildManifest(projectRoot, opts = {}) {
+  const nodes = {};
+  const edges = [];
+  const entities = {};
+  const allFiles = [];
+  const textCache = new Map();
+
+  for (const stage of V2_STAGES) {
+    if (!fs.existsSync(stageDir(projectRoot, stage.id))) continue;
+    nodes[stage.id] = stageNode(projectRoot, stage.id);
+  }
+
+  // 阶段边
+  for (const [to, ups] of Object.entries(STAGE_UPSTREAM)) {
+    if (!nodes[to]) continue;
+    for (const from of ups) {
+      if (!nodes[from]) continue;
+      edges.push({ from, to, kind: from === '10-scale' ? 'quantity' : (from === '40-rhythm' ? 'outline' : 'content') });
+    }
+  }
+
+  // 文件节点
+  const fileNodeByPath = new Map();
+  for (const stage of V2_STAGES) {
+    if (!nodes[stage.id]) continue;
+    for (const file of stageFiles(projectRoot, stage.id)) {
+      const rel = path.relative(stageDir(projectRoot, stage.id), file).split(path.sep).join('/');
+      const nodeId = fileNodeId(projectRoot, stage.id, file);
+      const data = file.endsWith('.json') ? readJson(file, null) : null;
+      const upstream = data ? (metaUpstream(data) || expectedUpstream(stage.id, rel)) : [];
+      const node = {
+        kind: 'file',
+        stage: stage.id,
+        path: relProjectPath(projectRoot, file),
+        status: (() => {
+          const s = readStageStatus(projectRoot, stage.id);
+          return s.status;
+        })(),
+        hash: file.endsWith('.json') ? hashFile(file) : bytesHash(fs.readFileSync(file)),
+        upstream,
+        downstream: [],
+        file: rel,
+        updated_at: nowIso(),
+      };
+      nodes[nodeId] = node;
+      nodes[stage.id].files.push(nodeId);
+      fileNodeByPath.set(file, nodeId);
+      allFiles.push({ file, nodeId, stage: stage.id, rel, data });
+      for (const up of upstream) {
+        edges.push({ from: up, to: nodeId, kind: 'file' });
+      }
+    }
+  }
+
+  // 文件节点的 upstream 若指向阶段节点，补阶段节点文件列表（manifest 自身可追）
+  // 反向边：所有节点
+  const downstream = new Map();
+  for (const [id, node] of Object.entries(nodes)) downstream.set(id, new Set());
+  for (const e of edges) {
+    if (!downstream.has(e.from)) downstream.set(e.from, new Set());
+    downstream.get(e.from).add(e.to);
+  }
+  for (const [id, set] of downstream.entries()) {
+    if (nodes[id]) nodes[id].downstream = [...set].sort();
+  }
+
+  // 实体索引
+  const entityRows = [];
+  for (const entry of allFiles) {
+    if (!entry.data) continue;
+    const rows = [];
+    scanEntities(entry.data, rows, '');
+    for (const row of rows) {
+      if (!entities[row.id]) {
+        entities[row.id] = {
+          type: row.type,
+          name: row.name || '',
+          display_no: row.display_no,
+          source: entry.nodeId,
+          source_path: nodes[entry.nodeId].path,
+          downstream: [],
+        };
+        entityRows.push(row.id);
+      }
+    }
+  }
+
+  // 文本引用索引：一次扫描每个文件，用 token 正则匹配实体 ID。
+  for (const entry of allFiles) {
+    let text = textCache.get(entry.file);
+    if (text === undefined) {
+      try {
+        text = fs.readFileSync(entry.file, 'utf-8');
+      } catch {
+        text = '';
+      }
+      textCache.set(entry.file, text);
+    }
+    const tokens = tokensIn(text);
+    for (const token of tokens) {
+      const row = entities[token];
+      if (!row) continue;
+      if (row.source === entry.nodeId) continue;
+      if (!row.downstream.includes(entry.nodeId)) row.downstream.push(entry.nodeId);
+    }
+  }
+  // 章实体额外关联已写正文：正文文件标题只有“第N章”，文本里没有 CH001 字样，
+  // 单靠 ID 扫描会漏掉它。
+  for (const [id, row] of Object.entries(entities)) {
+    if (row.type !== '章' || !row.display_no) continue;
+    const manuscriptNode = '50-writing.chapter.第' + String(row.display_no).padStart(3, '0') + '章';
+    if (nodes[manuscriptNode] && manuscriptNode !== row.source && !row.downstream.includes(manuscriptNode)) {
+      row.downstream.push(manuscriptNode);
+    }
+  }
+  for (const row of Object.values(entities)) row.downstream.sort();
+
+  const stageStatus = {};
+  for (const stage of V2_STAGES) {
+    if (nodes[stage.id]) stageStatus[stage.id] = nodes[stage.id].status;
+  }
+  const project = readJson(path.join(stageDir(projectRoot, '00-baseline'), 'input.json'), {}) || {};
+  const manifest = {
+    schema_version: SCHEMA_VERSION,
+    generated_at: nowIso(),
+    project: {
+      book_name: project.book_name || project.name || '',
+      target_chapters: Number(project.target_chapters || 0) || null,
+      target_words: Number(project.target_words || 0) || null,
+    },
+    stages: stageStatus,
+    nodes,
+    edges,
+    entities,
+  };
+
+  if (opts.write !== false) {
+    writeJsonAtomic(path.join(projectRoot, ...MANIFEST_PATH), manifest);
+  }
+  return manifest;
+}
+
+export function readManifest(projectRoot) {
+  return readJson(path.join(projectRoot, ...MANIFEST_PATH), null);
+}
+
+/** 规划/校验用：相对路径 → 文件节点。 */
+export function fileNodeByProjectPath(manifest, rel) {
+  for (const [id, node] of Object.entries(manifest.nodes || {})) {
+    if (node.kind === 'file' && node.path === rel) return { id, ...node };
+  }
+  return null;
+}
+
+/** 反向依赖闭包：传入节点 ID，返回所有下游节点（含自身）。 */
+export function reverseClosure(manifest, nodeIds) {
+  const nodes = manifest.nodes || {};
+  const result = new Set();
+  const queue = [...nodeIds];
+  while (queue.length) {
+    const id = queue.shift();
+    if (!id || result.has(id)) continue;
+    result.add(id);
+    const node = nodes[id];
+    if (!node) continue;
+    for (const next of asArray(node.downstream)) queue.push(next);
+  }
+  return result;
+}
+
+/** 找一条请求里点名到的实体（按 ID 或名称）。 */
+export function findEntities(manifest, text) {
+  const request = String(text || '');
+  const found = [];
+  for (const [id, entity] of Object.entries(manifest.entities || {})) {
+    if (request.includes(id) || (entity.name && entity.name.length >= 2 && request.includes(entity.name))) {
+      found.push({ id, ...entity });
+    }
+  }
+  return found;
+}
+
+/**
+ * 生成 patch 影响计划。
+ * 优先级：请求中明确点名的实体 → 字段/阶段关键词 → 全下游。
+ */
+export function buildPatchPlan(projectRoot, userRequest, manifest) {
+  const m = manifest || readManifest(projectRoot) || buildManifest(projectRoot, { write: false });
+  const requested = findEntities(m, userRequest);
+  const affectedNodes = new Set();
+  const reasons = [];
+
+  for (const entity of requested) {
+    affectedNodes.add(entity.source);
+    affectedNodes.add(entity.id);
+    for (const id of asArray(entity.downstream)) affectedNodes.add(id);
+    // 关系/成员关系不是章节地图里直接引用的 ID，但它们的语义会进入每章的关系呈现。
+    // 依赖图无法从文本反查“这条关系被哪些章节写到”，所以按保守规则把节奏与正文纳入。
+    if (['关系', '势力关系', '势力成员'].includes(entity.type)) {
+      affectedNodes.add('40-rhythm');
+      affectedNodes.add('50-writing');
+    }
+    reasons.push('实体 ' + entity.id + (entity.name ? '（' + entity.name + '）' : ''));
+  }
+
+  // 字段/阶段关键词兜底：不点名实体时，至少把相关阶段及其下游拉进来。
+  const stageHints = [];
+  if (/数量|配额|章节数|卷数|幕数|字数|规模|quota|scale/i.test(userRequest)) stageHints.push('10-scale');
+  if (/世界观|主题|主线|支线|结局|卷纲|幕纲|情绪|角色功能|macro/i.test(userRequest)) stageHints.push('20-macro');
+  if (/人物|角色|势力|地点|道具|冲突|伏笔|高潮|爽点|关系|信息差|cast/i.test(userRequest)) stageHints.push('30-cast');
+  if (/关系|成员|立场|态度/i.test(userRequest)) stageHints.push('40-rhythm', '50-writing');
+  if (/章节|细纲|节奏|钩子|时间线|rhythm/i.test(userRequest)) stageHints.push('40-rhythm');
+  if (/正文|章节内容|writing/i.test(userRequest)) stageHints.push('50-writing');
+  for (const stageId of stageHints) {
+    if (m.nodes && m.nodes[stageId]) {
+      affectedNodes.add(stageId);
+      for (const id of asArray(m.nodes[stageId].downstream)) affectedNodes.add(id);
+      reasons.push('阶段 ' + stageId);
+    }
+  }
+
+  // 没识别出任何范围：全部已生成阶段（保守处理，要求确认）。
+  if (!affectedNodes.size) {
+    for (const [id, node] of Object.entries(m.nodes || {})) {
+      if (node.kind === 'stage') affectedNodes.add(id);
+    }
+    reasons.push('未识别到具体实体，按全量下游处理');
+  }
+
+  const closure = reverseClosure(m, [...affectedNodes]);
+  const files = [];
+  const stages = new Set();
+  for (const id of closure) {
+    const node = m.nodes && m.nodes[id];
+    if (!node) continue;
+    if (node.kind === 'stage') {
+      stages.add(node.stage || id);
+      for (const fileId of asArray(node.files)) {
+        const f = m.nodes[fileId];
+        if (f && f.kind === 'file') files.push(f.path);
+      }
+    } else if (node.kind === 'file') {
+      stages.add(node.stage);
+      files.push(node.path);
+    }
+  }
+  const uniqFiles = [...new Set(files)].sort();
+  const stageList = STAGE_ORDER.filter((s) => stages.has(s));
+  const writingAffected = stageList.includes('50-writing') || uniqFiles.some((f) => f.includes('50-writing'));
+
+  return {
+    request: userRequest,
+    reasons: [...new Set(reasons)],
+    entities: requested.map((e) => ({ id: e.id, type: e.type, name: e.name, source: e.source_path || e.source })),
+    stages: stageList,
+    files: uniqFiles,
+    requires_confirmation: writingAffected || requested.length === 0,
+    writing_affected: writingAffected,
+    manifest_generated_at: m.generated_at || null,
+  };
+}
+
+/** 校验 manifest 自身与磁盘是否一致。 */
+export function verifyManifest(projectRoot, manifest) {
+  const m = manifest || readManifest(projectRoot);
+  const errors = [];
+  const warnings = [];
+  if (!m) {
+    return { ok: false, errors: [{ code: 'MANIFEST_MISSING', message: '设定/manifest.json 不存在' }], warnings };
+  }
+  const current = buildManifest(projectRoot, { write: false });
+  const nodeIds = new Set([...Object.keys(m.nodes || {}), ...Object.keys(current.nodes || {})]);
+  for (const id of nodeIds) {
+    const oldNode = (m.nodes || {})[id];
+    const newNode = (current.nodes || {})[id];
+    if (!oldNode && newNode) {
+      errors.push({ code: 'MANIFEST_NODE_ADDED', path: newNode.path, message: '新增节点未写入 manifest：' + id });
+      continue;
+    }
+    if (oldNode && !newNode) {
+      errors.push({ code: 'MANIFEST_NODE_REMOVED', path: oldNode.path, message: '节点已从磁盘删除但 manifest 未更新：' + id });
+      continue;
+    }
+    if (oldNode && newNode && oldNode.hash !== newNode.hash) {
+      errors.push({ code: 'MANIFEST_HASH_MISMATCH', path: newNode.path, message: '文件内容变化但 manifest 未更新：' + id });
+    }
+  }
+  // 上游哈希是否与 _meta 声明一致（stale 检测）
+  for (const [id, node] of Object.entries(current.nodes || {})) {
+    if (node.kind !== 'file') continue;
+    const entry = current.nodes[id];
+    const data = readJson(path.join(projectRoot, entry.path), null);
+    const ups = metaUpstream(data);
+    if (!ups) continue;
+    for (const upId of ups) {
+      const up = current.nodes[upId];
+      if (!up) {
+        warnings.push({ code: 'MANIFEST_UPSTREAM_UNKNOWN', path: entry.path, message: '上游节点不存在：' + upId });
+        continue;
+      }
+      const declared = asArray(data._meta.upstream).find((x) => x && x.node_id === upId);
+      if (declared && declared.hash && up.hash && declared.hash !== up.hash) {
+        errors.push({
+          code: 'MANIFEST_UPSTREAM_STALE',
+          path: entry.path,
+          message: '上游已变化，本文件标记 stale：' + upId,
+          expected: up.hash,
+          actual: declared.hash,
+          hint: '重新运行当前阶段，或运行 patch 让依赖图逐层更新',
+        });
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, manifest: current };
+}
+
+/**
+ * 给业务 JSON 填 _meta.upstream。读取上游文件当前哈希。
+ * 返回 meta 对象（不含 content_hash；content_hash 由写盘方补）。
+ */
+export function makeUpstreamMeta(projectRoot, nodeIds) {
+  const current = buildManifest(projectRoot, { write: false });
+  const out = [];
+  for (const nodeId of asArray(nodeIds)) {
+    const node = current.nodes && current.nodes[nodeId];
+    if (!node) continue;
+    out.push({
+      node_id: nodeId,
+      path: node.path,
+      hash: node.hash,
+      snapshot: node.kind === 'stage' ? '_context/' + nodeId.split('-').pop() + '.json' : undefined,
+    });
+  }
+  return out;
+}

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

@@ -0,0 +1,137 @@
+/**
+ * v2/migrate.js —— 旧 1.x 项目迁移。
+ *
+ * 迁移原则：
+ *   - 旧数据不删除，复制到 设定/legacy/v1/ 只读保留；
+ *   - 能确定性复现的数量先迁移（容量、配额、卷/幕区间）；
+ *   - 宏观/实体/节奏不伪造：缺少新契约字段的内容不硬塞，交给用户确认后重新生成或 patch。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  V1_STAGE_DIR,
+  ensureDir,
+  fileExists,
+  readJson,
+  stageDir,
+  stageFile,
+  writeJsonAtomic,
+  writeTextAtomic,
+} from './core.js';
+import { buildScale, finalizeScale, renderScaleMd, validateScale } from './scale.js';
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  ensureDir(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+  return true;
+}
+
+function oldFramework(projectRoot) {
+  return readJson(path.join(projectRoot, '设定', 'raw', 'sources', '骨架', '框架.json'), null);
+}
+
+function oldHierarchy(projectRoot) {
+  return readJson(path.join(projectRoot, '设定', 'raw', 'sources', '骨架', '层级.json'), null);
+}
+
+/**
+ * 生成 scale：优先沿用旧框架的 capacity / quota / volume_ratio。
+ */
+export function migrateScale(projectRoot, topicData, formulasDoc, opts = {}) {
+  const framework = oldFramework(projectRoot) || {};
+  const cap = framework.capacity || {};
+  const topic = {
+    ...topicData,
+    target_chapters: Number(cap.target_chapters) || topicData.target_chapters,
+    target_words: Number(cap.target_words) || topicData.target_words,
+  };
+  const scale = buildScale(topic, formulasDoc, opts);
+  const oldQuota = framework.quota || {};
+  const q = scale.quotas;
+  const set = (obj, key, value) => {
+    if (value === undefined || value === null) return;
+    const n = Number(value);
+    if (Number.isFinite(n)) obj[key] = n;
+  };
+  set(q.characters, 'protagonist', oldQuota.character_counts && oldQuota.character_counts.protagonist);
+  set(q.characters, 'core_supporting', oldQuota.character_counts && oldQuota.character_counts.core_supporting);
+  set(q.characters, 'volume_supporting', oldQuota.character_counts && oldQuota.character_counts.volume_supporting);
+  set(q.characters, 'core_antagonist', oldQuota.character_counts && oldQuota.character_counts.core_antagonist);
+  set(q.characters, 'volume_antagonist', oldQuota.character_counts && oldQuota.character_counts.volume_antagonist);
+  set(q, 'factions', oldQuota.faction_count);
+  set(q, 'faction_relations', oldQuota.faction_relation_count);
+  set(q, 'locations', oldQuota.location_count);
+  set(q.items, 'core', oldQuota.item_counts && oldQuota.item_counts.core);
+  set(q.items, 'branch', oldQuota.item_counts && oldQuota.item_counts.branch);
+  set(q.items, 'symbolic', oldQuota.item_counts && oldQuota.item_counts.symbolic);
+  set(q.conflicts, 'core', oldQuota.conflict_counts && oldQuota.conflict_counts.core);
+  set(q.conflicts, 'phase', oldQuota.conflict_counts && oldQuota.conflict_counts.phase);
+  set(q.conflicts, 'branch', oldQuota.conflict_counts && oldQuota.conflict_counts.branch);
+  set(q.foreshadows, 'small', oldQuota.foreshadow_counts && oldQuota.foreshadow_counts.small);
+  set(q.foreshadows, 'medium', oldQuota.foreshadow_counts && oldQuota.foreshadow_counts.medium);
+  set(q.foreshadows, 'large', oldQuota.foreshadow_counts && oldQuota.foreshadow_counts.large);
+  set(q.climaxes, 'small', oldQuota.climax_counts && oldQuota.climax_counts.small);
+  set(q.climaxes, 'medium', oldQuota.climax_counts && oldQuota.climax_counts.medium);
+  set(q.climaxes, 'large', oldQuota.climax_counts && oldQuota.climax_counts.large);
+  set(q.pleasures, 'small', oldQuota.pleasure_counts && oldQuota.pleasure_counts.small);
+  set(q.pleasures, 'medium', oldQuota.pleasure_counts && oldQuota.pleasure_counts.medium);
+  set(q.pleasures, 'large', oldQuota.pleasure_counts && oldQuota.pleasure_counts.large);
+  set(q.world_rules, 'core', oldQuota.world_rule_counts && oldQuota.world_rule_counts.core);
+  set(q.world_rules, 'information', oldQuota.world_rule_counts && oldQuota.world_rule_counts.information);
+  set(q.world_rules, 'social', oldQuota.world_rule_counts && oldQuota.world_rule_counts.social);
+  set(q, 'endings', oldQuota.ending_count);
+  set(q, 'branches', oldQuota.branch_count);
+  set(q, 'main_lines', oldQuota.main_line_count);
+  if (oldQuota.relations && typeof oldQuota.relations === 'object') {
+    set(q.relations, 'character', oldQuota.relations.character);
+    set(q.relations, 'faction', oldQuota.relations.faction);
+    set(q.relations, 'membership', oldQuota.relations.membership);
+  }
+  finalizeScale(scale, formulasDoc, opts);
+  return scale;
+}
+
+export function migrateV1(projectRoot, topicData, formulasDoc, opts = {}) {
+  const legacyRoot = path.join(projectRoot, '设定', 'legacy', 'v1');
+  ensureDir(legacyRoot);
+  const copied = [];
+  for (const name of Object.values(V1_STAGE_DIR)) {
+    const src = path.join(projectRoot, '设定', 'raw', 'sources', name);
+    if (!fs.existsSync(src)) continue;
+    copyDir(src, path.join(legacyRoot, name));
+    copied.push(name);
+  }
+
+  const scale = migrateScale(projectRoot, topicData, formulasDoc, opts);
+  const validation = validateScale(scale, formulasDoc, opts);
+  if (validation.ok) {
+    writeJsonAtomic(stageFile(projectRoot, '10-scale', 'scale.json'), scale);
+    writeTextAtomic(stageFile(projectRoot, '10-scale', 'scale.md'), renderScaleMd(scale));
+  }
+
+  // 迁移报告：明确哪些东西没有伪造。
+  const hierarchy = oldHierarchy(projectRoot);
+  const report = {
+    schema_version: '2.1',
+    migrated_at: new Date().toISOString(),
+    status: validation.ok ? 'MIGRATED_PARTIAL' : 'MIGRATED_SCALE_INVALID',
+    legacy_dirs_copied: copied,
+    scale_ok: validation.ok,
+    scale_errors: validation.errors,
+    volumes_in_legacy: Array.isArray(hierarchy && hierarchy.volumes) ? hierarchy.volumes.length : 0,
+    notes: [
+      '旧 骨架/血肉/节奏 已复制到 设定/legacy/v1/，只读保留。',
+      '10-scale 已按旧框架的 capacity/quota 迁移。',
+      '20-macro / 30-cast / 40-rhythm 不自动伪造：旧数据缺少新契约字段时，硬转换会产出看似完整但不可校验的内容。',
+      '下一步：检查 10-scale/scale.json，然后依次运行 /fancy-story-builder macro、cast、rhythm。',
+    ],
+  };
+  writeJsonAtomic(path.join(projectRoot, '设定', 'legacy', 'v1', 'migration-report.json'), report);
+  return report;
+}