@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-story-builder/scripts/story-artifacts.js

@@ -0,0 +1,933 @@
+/**
+ * story-artifacts.js —— 把聚合 JSON 拆成“可按对象阅读”的档案 + 每章一份细纲
+ *
+ * 为什么需要这一层：
+ *   - 现有阶段产物是聚合 JSON（实体.json / 冲突.json / 时序映射.json / 章节细纲.json），
+ *     人和别的 LLM 很难“只读一个伏笔/一个爽点/一章细纲”。
+ *   - llm_wiki 的 lint 需要页面级对象与链接，聚合 JSON 只能整文件 ingest，检查粒度太粗。
+ *   - 写作阶段需要每章一份硬约束：本章时间线、必须埋/收的伏笔、必须兑现的爽点/高潮、
+ *     必须出场的人、以及“谁还不知道什么，所以本章绝对不能提”。
+ *
+ * 设计原则：
+ *   - 聚合 JSON 仍是校验器的事实源；这里生成的是**确定性投影**，不引入 LLM 判断。
+ *   - 每个对象一个文件，每章一个细纲文件；写入保持幂等。
+ *   - 信息差只从已有数据推导（角色 information_state + 冲突 information_gaps + 时序 info_gaps），
+ *     不凭空编造“谁知道什么”。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SRC = ['设定', 'raw', 'sources'];
+const ARTIFACT_DIR = ['设定', 'raw', 'sources', '档案'];
+const BRIEF_DIR = ['设定', 'raw', 'sources', '节奏', '细纲'];
+
+function pad3(n) {
+  return String(n).padStart(3, '0');
+}
+
+function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmp, file);
+}
+
+function chapterLink(ch) {
+  return 'CH' + pad3(ch);
+}
+
+function uniqBy(items, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items || []) {
+    if (!item) continue;
+    const key = keyFn(item);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function flattenParticipants(row) {
+  const out = [];
+  if (!row) return out;
+  for (const value of [row.protagonist_side, row.main_antagonist, row.secondary_antagonist, row.third_party]) {
+    if (Array.isArray(value)) out.push(...value);
+    else if (value) out.push(value);
+  }
+  return out.filter(Boolean);
+}
+
+function namesToIds(names, byName) {
+  const ids = [];
+  for (const name of names || []) {
+    const id = byName.get(String(name).trim());
+    if (id) ids.push(id);
+  }
+  return [...new Set(ids)];
+}
+
+
+/** 章首钩子的写法提示（来自 glossary 的 7 式）。 */
+const HEAD_TECHNIQUES = {
+  '悬念对话': '用一句信息不完整的对话开场，让读者先感到“话里有话”；先不解释说话人真正知道什么。',
+  '闪前碎片': '先给未来结果的一个碎片，再回到当前时间线；碎片要具体，但不能把结果解释完。',
+  '倒计时': '在前 100 字内给出明确时限或剩余量，并让读者知道失败会付出什么代价。',
+  '神秘独白': '用第一人称内心独白制造诡异感或不可靠感；独白里要有具体细节，不能只写情绪。',
+  '反差场景': '把两个反差极大的场景并置，用断裂感制造问题；不要先解释为什么反差。',
+  '未完成动作': '让一个动作进行到一半被截断，停在“接下来会怎样”的悬念上。',
+  '意象预示': '用环境意象反复暗示后文；意象要具体可复现，不要写成抽象抒情。',
+};
+
+/** 章尾钩子的写法提示（来自 glossary 的 13 式）。 */
+const TAIL_TECHNIQUES = {
+  '突然揭示': '抛出改变全局的信息，但只给证据和反应，不把结论解释完。',
+  '紧急危机': '在章尾抛出下章必须回应的威胁，停在动作或决定之前。',
+  '未完成动作': '让动作被一个新变量打断，读者必须追下一章才知道结果。',
+  '身份反转': '让身份真相偏离读者预期；只给一个可验证的证据，不要当场解释全部。',
+  '两难抉择': '把角色逼到两个坏选项之间，停在选择之前。',
+  '神秘物品': '让一个重要但含义未知的物件出现；写清它被谁拿到、改变了什么，不解释它是什么。',
+  '倒计时': '把剩余时间压到读者能算出来的程度，停在时限即将到点的一刻。',
+  '承诺/威胁': '让某个人物公开宣布行动意图，停在“他真的要这么做”的瞬间。',
+  '离奇消失': '让一个人或物在不可能的条件下消失；只写见证者的反应，不给解释。',
+  '隐藏含义': '让表面正常的对话或动作暗藏第二层信息；用双关、停顿或异常细节收尾。',
+  '意象钩子': '让前文反复出现的意象发生变化；变化本身就是信息，不要解释。',
+  '回声钩子': '让章尾句呼应开头，但关键细节已经变了；读者能感到“同一句话，意义不同”。',
+  '留白钩子': '只展示人物反应，不揭示发生了什么；留白要具体到读者能追问“到底怎么了”。',
+};
+
+function headTechnique(type) {
+  return HEAD_TECHNIQUES[type] || '在前 100 字内抛出一个具体问题或异常，让读者带着问题进入本章。';
+}
+
+function tailTechnique(type) {
+  return TAIL_TECHNIQUES[type] || '在章尾留下一个具体、可追问的未解问题，不要把所有信息解释完。';
+}
+
+function renderEvent(event) {
+  return {
+    type: event.type,
+    ref: event.ref || '',
+    description: event.description || '',
+  };
+}
+
+/**
+ * 读取一次生成所需的全部上游数据。
+ */
+export function loadArtifactInputs(projectRoot) {
+  const skeletonDir = path.join(projectRoot, ...SRC, '骨架');
+  const fleshDir = path.join(projectRoot, ...SRC, '血肉');
+  const rhythmDir = path.join(projectRoot, ...SRC, '节奏');
+  const framework = readJson(path.join(skeletonDir, '框架.json'), {}) || {};
+  const entities = readJson(path.join(skeletonDir, '实体.json'), {}) || {};
+  const relations = readJson(path.join(skeletonDir, '关系.json'), {}) || {};
+  const fleshConflicts = readJson(path.join(fleshDir, '冲突.json'), {}) || {};
+  const fleshChars = readJson(path.join(fleshDir, '角色.json'), {}) || {};
+  const plan = readJson(path.join(rhythmDir, '章节规划.json'), {}) || {};
+  const timeline = readJson(path.join(rhythmDir, '时序映射.json'), {}) || {};
+  const outlines = readJson(path.join(rhythmDir, '章节细纲.json'), {}) || {};
+
+  const characterById = new Map();
+  const characterByName = new Map();
+  for (const c of (entities.characters || [])) {
+    if (!c || !c.id) continue;
+    characterById.set(c.id, c);
+    if (c.name) characterByName.set(String(c.name), c.id);
+  }
+  const factionById = new Map((entities.factions || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const locationById = new Map((entities.locations || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const itemById = new Map((entities.items || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const conflictById = new Map((entities.conflicts || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const foreshadowById = new Map((entities.foreshadows || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const climaxById = new Map((entities.climaxes || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const pleasureById = new Map((entities.pleasures || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const endingById = new Map((entities.endings || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+
+  const fleshConflictById = new Map();
+  for (const c of (fleshConflicts.conflicts || [])) {
+    if (c && c.id) fleshConflictById.set(c.id, c);
+  }
+  const fleshCharacterById = new Map();
+  for (const c of (fleshChars.characters || [])) {
+    if (c && c.id) fleshCharacterById.set(c.id, c);
+  }
+
+  const participantsByConflict = new Map();
+  for (const row of (relations.conflict_participants || [])) {
+    if (row && row.conflict) participantsByConflict.set(row.conflict, flattenParticipants(row));
+  }
+
+  const outlineByCh = new Map();
+  for (const o of (outlines.outlines || [])) {
+    if (o && typeof o.ch === 'number') outlineByCh.set(o.ch, o);
+  }
+
+  const timelineByCh = new Map();
+  const ensureCh = (ch) => {
+    if (!timelineByCh.has(ch)) {
+      timelineByCh.set(ch, {
+        events: [],
+        foreshadowActions: [],
+        climax: null,
+        pleasure: null,
+        ending: null,
+        conflicts: [],
+        infoGaps: [],
+        hooks: null,
+        arcStages: [],
+        relationshipChanges: [],
+      });
+    }
+    return timelineByCh.get(ch);
+  };
+
+  const mainLineById = new Map((entities.main_lines || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const branchById = new Map((entities.branches || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+
+  for (const row of (timeline.main_line_timeline || [])) {
+    if (!row || !Array.isArray(row.key_nodes)) continue;
+    for (const node of row.key_nodes) {
+      if (!node || typeof node.chapter !== 'number') continue;
+      ensureCh(node.chapter).events.push(renderEvent({
+        type: '主线节点',
+        ref: row.main_id + (mainLineById.get(row.main_id) ? '（' + mainLineById.get(row.main_id).name + '）' : ''),
+        description: node.event_ref || '',
+      }));
+    }
+  }
+  for (const row of (timeline.conflict_timeline || [])) {
+    if (!row || !row.conflict_id) continue;
+    for (const node of (row.escalation_nodes || [])) {
+      if (!node || typeof node.chapter !== 'number') continue;
+      const e = ensureCh(node.chapter);
+      const name = conflictById.get(row.conflict_id)?.name || row.conflict_id;
+      e.events.push(renderEvent({ type: '冲突升级', ref: row.conflict_id + '（' + name + '）', description: node.node_type || '' }));
+      e.conflicts.push({ id: row.conflict_id, name, node_type: node.node_type || '' });
+    }
+    if (typeof row.resolution_chapter === 'number') {
+      const e = ensureCh(row.resolution_chapter);
+      const name = conflictById.get(row.conflict_id)?.name || row.conflict_id;
+      e.events.push(renderEvent({ type: '冲突收束', ref: row.conflict_id + '（' + name + '）', description: 'resolution' }));
+    }
+    for (const gap of (row.info_gaps || [])) {
+      if (!gap || typeof gap.created !== 'number') continue;
+      const statusAt = (ch) => {
+        if (gap.created === ch) return 'created';
+        if (gap.resolved === ch) return 'resolved';
+        if (gap.created < ch && (typeof gap.resolved !== 'number' || gap.resolved > ch)) return 'open';
+        return null;
+      };
+      for (const ch of [gap.created, gap.resolved]) {
+        if (typeof ch !== 'number') continue;
+        const e = ensureCh(ch);
+        e.infoGaps.push({ conflict_id: row.conflict_id, info_name: gap.info_name, status: statusAt(ch) });
+      }
+    }
+  }
+  for (const row of (timeline.branch_timeline || [])) {
+    if (!row || !row.branch_id || !Array.isArray(row.interweaves)) continue;
+    for (const node of row.interweaves) {
+      if (!node || typeof node.chapter !== 'number') continue;
+      ensureCh(node.chapter).events.push(renderEvent({
+        type: '支线交织',
+        ref: row.branch_id + (branchById.get(row.branch_id) ? '（' + branchById.get(row.branch_id).name + '）' : ''),
+        description: node.description || '',
+      }));
+    }
+  }
+  for (const row of (timeline.relationship_timeline || [])) {
+    if (!row || typeof row !== 'object') continue;
+    const fromId = row.from;
+    const toId = row.to;
+    if (!fromId || !toId) continue;
+    const fromName = characterById.get(fromId)?.name || fromId;
+    const toName = characterById.get(toId)?.name || toId;
+    const ch = typeof row.start_chapter === 'number' ? row.start_chapter : null;
+    if (ch === null) continue;
+    const entry = {
+      from: fromId,
+      to: toId,
+      from_name: fromName,
+      to_name: toName,
+      stage: row.stage || '',
+      state: row.state || '',
+      start_chapter: ch,
+      end_chapter: typeof row.end_chapter === 'number' ? row.end_chapter : null,
+      trigger_event: row.trigger_event || '',
+      description: row.description || '',
+    };
+    ensureCh(ch).relationshipChanges.push(entry);
+    ensureCh(ch).events.push(renderEvent({
+      type: '关系变化',
+      ref: fromName + ' → ' + toName,
+      description: (row.stage ? row.stage + '：' : '') + (row.state || '') +
+        (row.trigger_event ? '（触发：' + row.trigger_event + '）' : ''),
+    }));
+  }
+
+  for (const row of (timeline.foreshadow_timeline || [])) {
+    if (!row || !row.fs_id) continue;
+    const fsRow = foreshadowById.get(row.fs_id) || { id: row.fs_id, name: row.fs_id };
+    if (typeof row.buried_chapter === 'number') {
+      ensureCh(row.buried_chapter).foreshadowActions.push({ id: row.fs_id, name: fsRow.name, action: '埋设' });
+    }
+    if (typeof row.recovered_chapter === 'number') {
+      ensureCh(row.recovered_chapter).foreshadowActions.push({ id: row.fs_id, name: fsRow.name, action: '回收' });
+    }
+  }
+  for (const row of (timeline.climax_timeline || [])) {
+    if (!row || typeof row.chapter !== 'number') continue;
+    const x = climaxById.get(row.climax_id) || { id: row.climax_id, name: row.climax_id };
+    ensureCh(row.chapter).climax = { id: x.id, name: x.name };
+  }
+  for (const row of (timeline.pleasure_timeline || [])) {
+    if (!row || typeof row.chapter !== 'number') continue;
+    const x = pleasureById.get(row.pleasure_id) || { id: row.pleasure_id, name: row.pleasure_id };
+    ensureCh(row.chapter).pleasure = { id: x.id, name: x.name };
+  }
+  for (const row of (timeline.ending_timeline || [])) {
+    if (!row || typeof row.chapter !== 'number') continue;
+    const x = endingById.get(row.ending_id) || { id: row.ending_id, name: row.ending_id };
+    ensureCh(row.chapter).ending = { id: x.id, name: x.name };
+  }
+  for (const row of (timeline.hook_timeline || [])) {
+    if (!row || typeof row.ch !== 'number') continue;
+    ensureCh(row.ch).hooks = {
+      head: row.hook_head || '',
+      tail: row.hook_tail || '',
+      strength: row.hook_strength || '',
+    };
+  }
+  for (const row of (timeline.character_timeline || [])) {
+    if (!row || !row.char_id) continue;
+    for (const stage of (row.arc_stages || [])) {
+      if (!stage || typeof stage.chapter !== 'number') continue;
+      ensureCh(stage.chapter).arcStages.push({ id: row.char_id, name: characterById.get(row.char_id)?.name || row.char_id, stage: stage.stage_name || '' });
+    }
+  }
+
+  return {
+    projectRoot,
+    skeletonDir,
+    fleshDir,
+    rhythmDir,
+    framework,
+    entities,
+    relations,
+    plan,
+    timeline,
+    outlines,
+    characterById,
+    characterByName,
+    factionById,
+    locationById,
+    itemById,
+    conflictById,
+    foreshadowById,
+    climaxById,
+    pleasureById,
+    endingById,
+    fleshConflictById,
+    fleshCharacterById,
+    participantsByConflict,
+    outlineByCh,
+    timelineByCh,
+  };
+}
+
+/** 把冲突的 info_gaps 与时序映射里的 created/resolved 合并。 */
+export function collectInfoGaps(inputs) {
+  const out = [];
+  const conflictTimeline = new Map();
+  for (const row of (inputs.timeline.conflict_timeline || [])) {
+    if (row && row.conflict_id) conflictTimeline.set(row.conflict_id, row);
+  }
+  // 没有节奏阶段时也要能从血肉冲突里拆出信息差；节奏只负责补 created/resolved。
+  const conflictIds = new Set([
+    ...inputs.fleshConflictById.keys(),
+    ...conflictTimeline.keys(),
+  ]);
+  for (const conflictId of conflictIds) {
+    const row = conflictTimeline.get(conflictId) || {};
+    const flesh = inputs.fleshConflictById.get(conflictId) || {};
+    const baseGaps = Array.isArray(flesh.information_gaps) ? flesh.information_gaps : [];
+    const timelineGaps = Array.isArray(row.info_gaps) ? row.info_gaps : [];
+    const count = Math.max(baseGaps.length, timelineGaps.length);
+    for (let i = 0; i < count; i += 1) {
+      const base = baseGaps[i] || {};
+      const tl = timelineGaps[i] || {};
+      const infoName = tl.info_name || base.info_name;
+      if (!infoName) continue;
+      const id = 'IG-' + conflictId + '-' + pad2(i + 1);
+      const whoKnows = base.who_knows || [];
+      const whoDoesNot = base.who_does_not_know || [];
+      out.push({
+        id,
+        conflict_id: conflictId,
+        info_name: infoName,
+        who_knows: whoKnows,
+        who_does_not_know: whoDoesNot,
+        who_knows_ids: namesToIds(whoKnows, inputs.characterByName),
+        who_does_not_know_ids: namesToIds(whoDoesNot, inputs.characterByName),
+        forbidden_mentions: whoDoesNot.map((name) => name + ' 尚不知道「' + infoName + '」，不得让其提及、知情或据此行动。'),
+        resolution_method: base.resolution_method || '',
+        created: typeof tl.created === 'number' ? tl.created : null,
+        resolved: typeof tl.resolved === 'number' ? tl.resolved : null,
+        status: (typeof tl.created === 'number' && typeof tl.resolved === 'number')
+          ? (tl.resolved <= tl.created ? 'invalid' : 'planned')
+          : 'planned',
+      });
+    }
+  }
+  return out;
+}
+
+/** 生成一个“章节时间线”文件的内容。 */
+function buildTimelineFile(inputs, ch) {
+  const e = inputs.timelineByCh.get(ch) || {
+    events: [], foreshadowActions: [], climax: null, pleasure: null,
+    ending: null, conflicts: [], infoGaps: [], hooks: null, arcStages: [],
+  };
+  return {
+    ch,
+    chapter: chapterLink(ch),
+    events: e.events,
+    foreshadow_actions: e.foreshadowActions,
+    climax: e.climax,
+    pleasure: e.pleasure,
+    ending: e.ending,
+    conflicts: e.conflicts,
+    information_gaps: e.infoGaps,
+    hooks: e.hooks,
+    arc_stages: e.arcStages,
+  };
+}
+
+/** 选出本章真正需要出场的角色（不再把“全书都存在”的人全塞进来）。 */
+function selectCast(inputs, ch, activeConflicts) {
+  const out = [];
+  const firstAppear = [];
+  const push = (id, reason) => {
+    if (!id || !inputs.characterById.has(id)) return;
+    out.push({ id, reason });
+  };
+  for (const c of (inputs.entities.characters || [])) {
+    if (c && c.type === '主角') push(c.id, '主角');
+  }
+  for (const row of (inputs.timeline.character_timeline || [])) {
+    if (!row || !row.char_id) continue;
+    if (row.appear_start === ch) firstAppear.push(row.char_id);
+    if (row.exit_chapter === ch) push(row.char_id, '退场');
+    for (const stage of (row.arc_stages || [])) {
+      if (stage && stage.chapter === ch) push(row.char_id, '弧光节点');
+    }
+  }
+  for (const conflict of activeConflicts) {
+    for (const id of (inputs.participantsByConflict.get(conflict.id) || [])) push(id, '冲突参与');
+  }
+  // 首次出场只补到能支撑一场戏的最小规模；不再把“全书都存在”的人全塞进来。
+  for (const id of firstAppear) {
+    if (out.length >= 6) break;
+    if (!out.some((x) => x.id === id)) push(id, '首次出场');
+  }
+  const unique = uniqBy(out, (x) => x.id).slice(0, 6);
+  return unique.map((x) => {
+    const c = inputs.characterById.get(x.id) || {};
+    return {
+      id: x.id,
+      name: c.name || x.id,
+      role: c.type || '',
+      reason: x.reason,
+    };
+  });
+}
+
+/** 找本章的地点/道具：优先匹配 scene_focus 里的名字，其次首次出场。 */
+function selectLocation(inputs, ch, sceneFocus) {
+  const focus = String(sceneFocus || '');
+  for (const l of (inputs.entities.locations || [])) {
+    if (!l || !l.name) continue;
+    if (focus.includes(String(l.name))) return { id: l.id, name: l.name };
+  }
+  for (const row of (inputs.timeline.location_timeline || [])) {
+    if (row && row.appear_start === ch && inputs.locationById.has(row.loc_id)) {
+      const l = inputs.locationById.get(row.loc_id);
+      return { id: l.id, name: l.name };
+    }
+  }
+  return null;
+}
+
+function selectItems(inputs, ch, sceneFocus) {
+  const focus = String(sceneFocus || '');
+  const out = [];
+  for (const item of (inputs.entities.items || [])) {
+    if (item && item.name && focus.includes(String(item.name))) out.push({ id: item.id, name: item.name });
+  }
+  for (const row of (inputs.timeline.item_timeline || [])) {
+    if (out.length >= 3) break;
+    if (row && row.appear_start === ch && inputs.itemById.has(row.item_id)) {
+      const item = inputs.itemById.get(row.item_id);
+      out.push({ id: item.id, name: item.name });
+    }
+  }
+  return uniqBy(out, (x) => x.id).slice(0, 3);
+}
+
+/** 本章的信息差：created/open/resolved 三种状态。 */
+function selectInfoGaps(inputs, ch, allInfoGaps, cast, activeConflicts) {
+  const castIds = new Set((cast || []).map((x) => x.id));
+  const relevantConflicts = new Set((activeConflicts || []).map((x) => x.id));
+  const out = [];
+  for (const gap of allInfoGaps) {
+    if (typeof gap.created !== 'number') continue;
+    let status = null;
+    if (gap.created === ch) status = 'created';
+    else if (gap.resolved === ch) status = 'resolved';
+    else if (gap.created < ch && (typeof gap.resolved !== 'number' || gap.resolved > ch)) status = 'open';
+    if (!status) continue;
+    // 只保留本章真正相关的信息差：本章创建/解决，或所属冲突在本章有升级节点。
+    if (status === 'open' && !relevantConflicts.has(gap.conflict_id)) continue;
+    const forbidden = [];
+    if (status !== 'resolved') {
+      for (const id of gap.who_does_not_know_ids || []) {
+        if (!castIds.has(id)) continue;
+        const c = inputs.characterById.get(id) || {};
+        forbidden.push(
+          (c.name || id) + '（' + id + '）尚不知道「' + gap.info_name + '」，' +
+          '本章不得让其提及、知情、据此行动，也不得用旁白提前揭示。'
+        );
+      }
+    }
+    out.push({
+      id: gap.id,
+      conflict_id: gap.conflict_id,
+      info_name: gap.info_name,
+      status,
+      who_knows: gap.who_knows,
+      who_does_not_know: gap.who_does_not_know,
+      who_knows_ids: gap.who_knows_ids,
+      who_does_not_know_ids: gap.who_does_not_know_ids,
+      resolution_method: gap.resolution_method,
+      created: gap.created,
+      resolved: gap.resolved,
+      forbidden_mentions: forbidden,
+    });
+  }
+  return out;
+}
+
+/** 生成每章细纲。 */
+export function buildChapterBriefs(inputs) {
+  const chapters = Array.isArray(inputs.plan.chapters) ? inputs.plan.chapters : [];
+  if (!chapters.length) return { count: 0, files: [] };
+  const allInfoGaps = collectInfoGaps(inputs);
+  const byCh = new Map();
+  const avgWords = Number(inputs.framework?.capacity?.avg_words_per_chapter) || 0;
+  const files = [];
+
+  for (const plan of chapters) {
+    if (!plan || typeof plan.ch !== 'number') continue;
+    const ch = plan.ch;
+    const tl = inputs.timelineByCh.get(ch) || {
+      events: [], foreshadowActions: [], climax: null, pleasure: null,
+      ending: null, conflicts: [], infoGaps: [], hooks: null, arcStages: [],
+      relationshipChanges: [],
+    };
+    const outline = inputs.outlineByCh.get(ch) || {};
+    const activeConflicts = uniqBy(tl.conflicts, (x) => x.id);
+    const cast = selectCast(inputs, ch, activeConflicts);
+    const location = selectLocation(inputs, ch, plan.scene_focus || '');
+    const items = selectItems(inputs, ch, plan.scene_focus || '');
+    const infoGaps = selectInfoGaps(inputs, ch, allInfoGaps, cast, activeConflicts);
+    const foreshadowActions = tl.foreshadowActions || [];
+    const hooks = tl.hooks || {
+      head: outline.hook_head || '',
+      tail: outline.hook_tail || '',
+      strength: outline.hook_strength || '',
+    };
+
+    const wordTarget = typeof outline.word_target === 'number' ? outline.word_target : avgWords;
+    const pov = cast.find((x) => x.reason === '主角')?.id || cast[0]?.id || '';
+    const povName = cast.find((x) => x.id === pov)?.name || pov;
+    const locationName = location ? location.name : '（本章未指定地点）';
+    const headType = hooks.head || '';
+    const tailType = hooks.tail || '';
+    const strength = hooks.strength || '';
+
+    const mustWrite = [];
+    if (outline.function_main) mustWrite.push('主功能：' + outline.function_main);
+    if (outline.function_aux) mustWrite.push('辅助功能：' + outline.function_aux);
+    if (plan.scene_focus) mustWrite.push('场景焦点：' + plan.scene_focus);
+    if (headType) mustWrite.push('章首钩子：' + headType + '（前 100 字内兑现）');
+    if (tailType) mustWrite.push('章尾钩子：' + tailType + '（章尾后 100 字内兑现）');
+    if (strength) mustWrite.push('钩子强度：' + strength);
+    if (cast.length) mustWrite.push('必须出场：' + cast.map((x) => x.id + '（' + x.name + '）').join('、'));
+    if (activeConflicts.length) {
+      mustWrite.push('必须推进冲突：' + activeConflicts.map((x) => x.id + '（' + x.name + '） · ' + (x.node_type || '推进')).join('、'));
+    }
+    const relationshipChanges = tl.relationshipChanges || [];
+    if (relationshipChanges.length) {
+      mustWrite.push('必须发生的关系变化：' + relationshipChanges.map((x) =>
+        x.from_name + '→' + x.to_name + ' 进入「' + x.stage + ' / ' + x.state + '」' +
+        (x.trigger_event ? '（触发：' + x.trigger_event + '）' : '')
+      ).join('、'));
+    }
+    if (foreshadowActions.length) {
+      mustWrite.push('必须完成的伏笔动作：' + foreshadowActions.map((x) => x.action + ' ' + x.id + '（' + x.name + '）').join('、'));
+    }
+    if (tl.climax) mustWrite.push('必须兑现高潮：' + tl.climax.id + '（' + tl.climax.name + '）');
+    if (tl.pleasure) mustWrite.push('必须兑现爽点：' + tl.pleasure.id + '（' + tl.pleasure.name + '）');
+    if (tl.ending) mustWrite.push('必须抵达结局节点：' + tl.ending.id + '（' + tl.ending.name + '）');
+    if (infoGaps.length) {
+      mustWrite.push('必须处理的信息差：' + infoGaps.map((x) => x.status + '「' + x.info_name + '」').join('、'));
+    }
+    if (wordTarget) mustWrite.push('字数目标：约 ' + wordTarget + ' 字');
+
+    const mustNotWrite = [];
+    for (const gap of infoGaps) {
+      for (const line of gap.forbidden_mentions) mustNotWrite.push(line);
+    }
+    const openForeshadows = [];
+    let futureForeshadowCount = 0;
+    for (const row of (inputs.timeline.foreshadow_timeline || [])) {
+      if (!row || !row.fs_id) continue;
+      if (typeof row.recovered_chapter !== 'number' || row.recovered_chapter <= ch) continue;
+      const fs = inputs.foreshadowById.get(row.fs_id) || { id: row.fs_id, name: row.fs_id };
+      if (typeof row.buried_chapter === 'number' && row.buried_chapter > ch) {
+        futureForeshadowCount += 1;
+        continue;
+      }
+      openForeshadows.push(row.fs_id + '（' + fs.name + '，第 ' + row.recovered_chapter + ' 章回收）');
+    }
+    for (const line of openForeshadows.slice(0, 8)) {
+      mustNotWrite.push('不得提前揭示伏笔 ' + line + ' 的真相。');
+    }
+    if (openForeshadows.length > 8) {
+      mustNotWrite.push('另有 ' + (openForeshadows.length - 8) + ' 条已埋未收伏笔：本章不得提前揭示它们的真相。');
+    }
+    if (futureForeshadowCount > 0) {
+      mustNotWrite.push('不得提前埋设/提及任何尚未到埋设章的伏笔；本章只允许执行 foreshadow_actions 中列出的动作。');
+    }
+    if (cast.length) {
+      mustNotWrite.push('不得让未列入本章 cast 的角色成为视角中心或关键行动人；需要新角色时必须先登记。');
+    }
+    if (relationshipChanges.length) {
+      mustNotWrite.push('不得把本章已经变化的关系写回变化前的状态；除非本章明确写了回退事件。');
+    }
+    mustNotWrite.push('不得提及未在本章时间线/信息差/伏笔动作中出现的冲突、伏笔、结局。');
+    mustNotWrite.push('不得改写已建立的世界观规则、角色信息状态与已知事实。');
+
+    const informationState = {};
+    const informationBoundaries = [];
+    for (const c of cast) {
+      const profile = inputs.fleshCharacterById.get(c.id);
+      if (!profile || !profile.information_state) continue;
+      informationState[c.id] = profile.information_state;
+      const info = profile.information_state;
+      if (info.unknown_secrets || info.false_beliefs) {
+        informationBoundaries.push({
+          id: c.id,
+          name: c.name,
+          unknown_secrets: info.unknown_secrets || '',
+          false_beliefs: info.false_beliefs || '',
+        });
+      }
+    }
+
+    const opening = {
+      hook_type: headType,
+      strength,
+      technique: headTechnique(headType),
+      must: [
+        '前 100 字内让读者看见一个具体异常、问题或时限。',
+        '让读者知道本章要追的具体问题是什么。',
+        headType ? '章首钩子类型必须是「' + headType + '」。' : '',
+      ].filter(Boolean),
+      avoid: [
+        '不要先写大段环境、背景或人物履历再进入钩子。',
+        '不要把章首钩子拖到场景中段才出现。',
+        '不要用旁白直接解释钩子的答案。',
+      ],
+    };
+
+    const ending = {
+      hook_type: tailType,
+      strength,
+      technique: tailTechnique(tailType),
+      must: [
+        '章尾后 100 字内留下一个具体、可追问的未解问题。',
+        '章尾必须让读者明确知道“下一章要追什么”。',
+        tailType ? '章尾钩子类型必须是「' + tailType + '」。' : '',
+      ].filter(Boolean),
+      avoid: [
+        '不要把本章所有问题解释完再收尾。',
+        '不要用总结式旁白代替钩子。',
+        '不要连续使用同一种章尾钩子（高潮期例外需注明）。',
+      ],
+    };
+
+    const timelineSummary = (tl.events || []).map((e) => (e.type || '事件') + '：' + (e.description || e.ref || '')).join('；');
+    const sceneBeats = [
+      {
+        name: '开场',
+        goal: '在' + locationName + '用「' + (headType || '具体异常') + '」开场，前 100 字兑现场景焦点：' + (plan.scene_focus || '让读者知道本章要追什么'),
+        must: [headType ? '章首钩子：' + headType : '给出具体异常/问题', cast.length ? '至少让 ' + cast.slice(0, 3).map((x) => x.name).join('、') + ' 中的一人进入场景' : ''],
+        avoid: ['不要先讲背景设定', '不要让人物只站着说话'],
+      },
+      {
+        name: '推进',
+        goal: '按「' + (outline.function_main || '推进主线') + '」推进' + (timelineSummary ? '，必须覆盖：' + timelineSummary : '') + (activeConflicts.length ? '；让冲突 ' + activeConflicts.map((x) => x.id).join('、') + ' 的实际压力落到角色身上' : ''),
+        must: [activeConflicts.length ? '推进 ' + activeConflicts.map((x) => x.id + '（' + x.name + '）').join('、') : '推进本章主功能', timelineSummary ? '时间线：' + timelineSummary : ''].filter(Boolean),
+        avoid: ['不要用说明代替行动', '不要同时开三条以上新线'],
+      },
+      {
+        name: '转折/兑现',
+        goal: (tl.climax ? '兑现高潮 ' + tl.climax.id + '；' : '') + (tl.pleasure ? '兑现爽点 ' + tl.pleasure.id + '；' : '') + (infoGaps.length ? '让信息差发生作用：' + infoGaps.map((x) => x.info_name).join('、') : '让角色做出不可逆选择'),
+        must: [
+          tl.climax ? '高潮：' + tl.climax.id : '',
+          tl.pleasure ? '爽点：' + tl.pleasure.id : '',
+          foreshadowActions.length ? '伏笔动作：' + foreshadowActions.map((x) => x.action + ' ' + x.id).join('、') : '',
+        ].filter(Boolean),
+        avoid: ['不要把高潮/爽点写成旁白总结', '不要提前揭示未到回收章的伏笔'],
+      },
+      {
+        name: '收束',
+        goal: '用「' + (tailType || '未解问题') + '」收束，并留下下一章必须回应的具体问题',
+        must: [tailType ? '章尾钩子：' + tailType : '留下具体未解问题', tl.ending ? '抵达结局节点：' + tl.ending.id : ''].filter(Boolean),
+        avoid: ['不要解释完所有问题', '不要用“欲知后事如何”式空钩子'],
+      },
+    ];
+
+    const elements = {
+      characters: cast,
+      location,
+      items,
+      conflicts: activeConflicts,
+      foreshadows: foreshadowActions,
+      climax: tl.climax,
+      pleasure: tl.pleasure,
+      ending: tl.ending,
+      timeline: tl.events || [],
+      relationship_changes: tl.relationshipChanges || [],
+      information_gaps: infoGaps,
+    };
+
+    const brief = {
+      id: 'OB-' + chapterLink(ch),
+      ch,
+      title: '第' + ch + '章',
+      volume: plan.volume || '',
+      act: plan.act || 0,
+      pov,
+      pov_name: povName,
+      scene_focus: plan.scene_focus || '',
+      function_main: outline.function_main || '',
+      function_aux: outline.function_aux || '',
+      emotion: {
+        value: typeof outline.emotion_value === 'number' ? outline.emotion_value : null,
+        phase: outline.emotion_phase || '',
+      },
+      word_target: wordTarget,
+      faction_appearance: outline.faction_appearance || '',
+      elements,
+      cast,
+      location,
+      items,
+      conflicts: activeConflicts,
+      timeline_events: tl.events || [],
+      relationship_changes: tl.relationshipChanges || [],
+      foreshadow_actions: foreshadowActions,
+      climax: tl.climax,
+      pleasure: tl.pleasure,
+      ending: tl.ending,
+      hooks,
+      information_gaps: infoGaps,
+      information_state: informationState,
+      information_boundaries: informationBoundaries,
+      how_to_write: {
+        pov: povName + '（' + (pov || '未指定') + '）',
+        pov_rule: '保持' + (povName || '视角人物') + '的限知视角；他不知道的信息不得写成已知。',
+        opening,
+        development: sceneBeats[1],
+        turn: sceneBeats[2],
+        ending,
+        scene_beats: sceneBeats,
+        technique_refs: [
+          '对标/wiki/开头钩子/开头钩子-总结.md',
+          '对标/wiki/结尾收束/结尾收束-总结.md',
+          '对标/wiki/叙事视角/叙事视角-总结.md',
+          '对标/wiki/节奏韵律/节奏韵律-总结.md',
+          '对标/wiki/章节结构/章节结构-总结.md',
+          '对标/wiki/对话技巧/对话技巧-总结.md',
+          '对标/wiki/描写技法/描写技法-总结.md',
+        ],
+      },
+      must_write: mustWrite,
+      must_not_write: mustNotWrite,
+      source: {
+        plan: '设定/raw/sources/节奏/章节规划.json',
+        timeline: '设定/raw/sources/节奏/时序映射.json',
+        outline: '设定/raw/sources/节奏/章节细纲.json',
+        flesh_conflicts: '设定/raw/sources/血肉/冲突.json',
+        flesh_characters: '设定/raw/sources/血肉/角色.json',
+      },
+    };
+
+    const file = path.join(inputs.projectRoot, ...BRIEF_DIR, '第' + pad3(ch) + '章.json');
+    writeJson(file, brief);
+    byCh.set(ch, brief);
+    files.push(file);
+  }
+
+  // 索引：让别的 LLM 一眼知道 600 章细纲在哪、有哪些文件。
+  const index = {
+    generated_at: new Date().toISOString(),
+    chapter_count: files.length,
+    dir: '设定/raw/sources/节奏/细纲',
+    files: files.map((file) => path.basename(file)),
+  };
+  writeJson(path.join(inputs.projectRoot, ...BRIEF_DIR, 'index.json'), index);
+  return { count: files.length, files, byCh };
+}
+
+/** 生成伏笔/爽点/冲突/信息差/时间线的独立档案文件。 */
+export function buildObjectArtifacts(inputs, infoGaps) {
+  const root = path.join(inputs.projectRoot, ...ARTIFACT_DIR);
+  const counts = {
+    foreshadows: 0,
+    pleasures: 0,
+    conflicts: 0,
+    info_gaps: 0,
+    timeline_chapters: 0,
+  };
+  const index = {
+    generated_at: new Date().toISOString(),
+    dir: '设定/raw/sources/档案',
+    foreshadows: [],
+    pleasures: [],
+    conflicts: [],
+    info_gaps: [],
+    timeline: [],
+  };
+
+  for (const row of (inputs.entities.foreshadows || [])) {
+    if (!row || !row.id) continue;
+    const tl = (inputs.timeline.foreshadow_timeline || []).find((x) => x && x.fs_id === row.id) || {};
+    const obj = {
+      id: row.id,
+      name: row.name || row.id,
+      type: row.type || '',
+      description: row.name || row.id,
+      buried_chapter: typeof tl.buried_chapter === 'number' ? tl.buried_chapter : null,
+      recovered_chapter: typeof tl.recovered_chapter === 'number' ? tl.recovered_chapter : null,
+      status: typeof tl.recovered_chapter === 'number' ? 'planned' : 'open',
+    };
+    writeJson(path.join(root, '伏笔', row.id + '.json'), obj);
+    index.foreshadows.push(obj.id);
+    counts.foreshadows += 1;
+  }
+
+  for (const row of (inputs.entities.pleasures || [])) {
+    if (!row || !row.id) continue;
+    const tl = (inputs.timeline.pleasure_timeline || []).find((x) => x && x.pleasure_id === row.id) || {};
+    const obj = {
+      id: row.id,
+      name: row.name || row.id,
+      scale: row.scale || '',
+      kind: row.kind || '',
+      chapter: typeof tl.chapter === 'number' ? tl.chapter : null,
+      description: row.name || row.id,
+    };
+    writeJson(path.join(root, '爽点', row.id + '.json'), obj);
+    index.pleasures.push(obj.id);
+    counts.pleasures += 1;
+  }
+
+  for (const row of (inputs.entities.conflicts || [])) {
+    if (!row || !row.id) continue;
+    const flesh = inputs.fleshConflictById.get(row.id) || {};
+    const tl = (inputs.timeline.conflict_timeline || []).find((x) => x && x.conflict_id === row.id) || {};
+    const obj = {
+      id: row.id,
+      name: row.name || row.id,
+      type: row.type || '',
+      scale: row.scale || '',
+      description: flesh.description || row.name || row.id,
+      core_goal: flesh.core_goal || '',
+      influence_scope: flesh.influence_scope || '',
+      focus_points: flesh.focus_points || [],
+      surface_contradiction: flesh.surface_contradiction || '',
+      deep_contradiction: flesh.deep_contradiction || '',
+      ultimate_contradiction: flesh.ultimate_contradiction || '',
+      // 血肉阶段的内容字段必须原样保留。档案是“合并视图”，不是有损投影。
+      escalation_path: Array.isArray(flesh.escalation_path) ? flesh.escalation_path : [],
+      resolution_plan: flesh.resolution_plan || null,
+      // 节奏阶段只补“发生在第几章”，没有节奏时保留空数组/null，不覆盖血肉内容。
+      escalation_nodes: Array.isArray(tl.escalation_nodes) ? tl.escalation_nodes : [],
+      resolution_chapter: typeof tl.resolution_chapter === 'number' ? tl.resolution_chapter : null,
+      information_gaps: infoGaps.filter((x) => x.conflict_id === row.id),
+      // 参与方是关系数据，来自骨架 关系.json 的 conflict_participants；
+      // 不在血肉冲突里重复存，但档案要把它并入。
+      participants: inputs.participantsByConflict.get(row.id) || [],
+      participant_names: (inputs.participantsByConflict.get(row.id) || [])
+        .map((id) => inputs.characterById.get(id)?.name || id),
+    };
+    writeJson(path.join(root, '冲突', row.id + '.json'), obj);
+    index.conflicts.push(obj.id);
+    counts.conflicts += 1;
+  }
+
+  for (const gap of infoGaps) {
+    writeJson(path.join(root, '信息差', gap.id + '.json'), gap);
+    index.info_gaps.push(gap.id);
+    counts.info_gaps += 1;
+  }
+
+  // 每章一份时间线，方便别的 LLM 按章阅读，也方便 lint 检查“本章事件是否完整”。
+  for (const plan of (inputs.plan.chapters || [])) {
+    if (!plan || typeof plan.ch !== 'number') continue;
+    const obj = buildTimelineFile(inputs, plan.ch);
+    writeJson(path.join(root, '时间线', 'CH' + pad3(plan.ch) + '.json'), obj);
+    index.timeline.push(obj.chapter);
+    counts.timeline_chapters += 1;
+  }
+
+  index.counts = counts;
+  writeJson(path.join(root, 'index.json'), index);
+  return { counts, index };
+}
+
+/**
+ * 生成全部独立档案与每章细纲。
+ *
+ * 幂等：重复执行只会覆盖同名文件；不会删除用户新增的文件。
+ *
+ * @param {string} projectRoot
+ * @returns {{counts: object, briefCount: number, briefs: Map<number, object>}}
+ */
+export function buildStoryArtifacts(projectRoot) {
+  const inputs = loadArtifactInputs(projectRoot);
+  const infoGaps = collectInfoGaps(inputs);
+  const objects = buildObjectArtifacts(inputs, infoGaps);
+  const briefs = buildChapterBriefs(inputs);
+  return {
+    counts: objects.counts,
+    briefCount: briefs.count,
+    briefs: briefs.byCh || new Map(),
+  };
+}