@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-story-builder/writing-driver.js

@@ -0,0 +1,1061 @@
+/**
+ * writing-driver.js
+ * 写作阶段：插件驱动、按批执行（默认每批 10 章）
+ *
+ * 为什么要改成插件驱动：
+ *   旧模式下插件只投一次提示词就返回"写作阶段开始"，剩下 T 章全靠 LLM 在自己
+ *   那一轮里 for 循环完成——自己读细纲、自己跑校验、自己更台账。插件对写作
+ *   流程零控制：少写一章、跳过一章、校验失败不重试、台账没更新，插件都不知道；
+ *   上下文一被压缩，几百章的进度状态就丢了。
+ *
+ * 改成插件驱动后：
+ *   插件自己按批循环 → 每批把细纲/前章尾/台账快照注入 prompt → 投给 LLM →
+ *   等 LLM 空闲 → **插件自己跑 writing-validate.js 逐章校验** →
+ *   通过就推进台账进下一批，有失败就把 errors[] 回喂重试该批。
+ *
+ * 对 LLM 的变化：提示词从"执行手册"瘦身成"怎么写好一章"的方法论，
+ * 流程（读什么、校验什么、写哪几个文件）由插件执行。
+ *
+ * 本模块不直接依赖 dsh 运行时：sendPrompt / waitIdle / validateChapter 都由
+ * 调用方注入，因此可以在没有 LLM 的情况下用测试夹具驱动。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+import { countEffectiveChars } from './scripts/content-quality.js';
+
+// 每批章数
+export const WRITING_BATCH_SIZE = 10;
+// 单批最大尝试次数（含首次）。超了就带着失败章继续下一批，并在最终报告里列出。
+export const WRITING_MAX_BATCH_ATTEMPTS = 3;
+// 前章正文注入长度（字）
+export const WRITING_PREV_TAIL_CHARS = 500;
+
+// ============================================================
+// 上下文读取
+// ============================================================
+
+function readJsonSafe(p) {
+  try {
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(p) {
+  try {
+    if (!existsSync(p)) return null;
+    return readFileSync(p, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/** 章文件路径：设定/raw/sources/写作/第NNN章.md */
+export function chapterFileName(ch) {
+  return '第' + String(ch).padStart(3, '0') + '章.md';
+}
+
+export function writingDirs(projectRoot) {
+  const src = join(projectRoot, '设定', 'raw', 'sources');
+  return {
+    sources: src,
+    skeleton: join(src, '骨架'),
+    flesh: join(src, '血肉'),
+    rhythm: join(src, '节奏'),
+    writing: join(src, '写作'),
+    ledger: join(src, '写作', '台账')
+  };
+}
+
+/**
+ * 读取写作阶段需要的全部上游数据。
+ *
+ * 返回 { T, outlines, existing, prevTail, ledgers, dirs, entityRoster }。
+ * 任何一项读不到都返回 null，交给调用方报错（不抛异常，方便统一成通知文案）。
+ */
+/**
+ * 读写作阶段的**可变状态**：已写章节、前情衔接、台账。
+ *
+ * 单独抽出来是因为它有两个调用点：
+ *   · loadWritingContext —— 开场读一次
+ *   · refreshWritingContext —— 每批写完后重读（否则第 2 批拿到的还是
+ *     第 1 批之前的"前情衔接"和台账快照，角色状态前后矛盾）
+ *
+ * @param {Object} dirs writingDirs() 的结果
+ * @param {number} T 全书章数
+ */
+/**
+ * 轻量复检一个已存在的章节文件。
+ *
+ * 为什么"文件存在"不等于"这章写完了"：
+ * 旧实现只按文件名 `第N章.md` 判断，于是
+ *   - 上次失败留下的 0 字节文件
+ *   - 上次中断留下的半截文件
+ *   - 标题写错的文件
+ * 都会被当成"已写完"而**永久跳过** —— 续跑多少遍都补不上，
+ * 而报告只说"0 章全部写完并通过逐章校验"，用户完全看不出来。
+ *
+ * 这里只做三项便宜且能抓住上述三类残留的检查（同步、不起子进程）：
+ *   1. 文件非空
+ *   2. 首行是 `# 第N章`（章号与文件名一致）
+ *   3. 有效字数 ≥ 50（写作校验器的 EMPTY_BODY 门槛）
+ *
+ * 更严的复检（占位符/字符集/台账…）由 runWritingStage 里的
+ * validateChapter 补上 —— 那是完整校验器，能起子进程。
+ *
+ * @param {string} filePath
+ * @param {number} ch 章号
+ * @returns {{ok:boolean, reason:string|null}}
+ */
+export function quickCheckChapterFile(filePath, ch) {
+  let text = null;
+  try {
+    text = readFileSync(filePath, 'utf-8');
+  } catch {
+    return { ok: false, reason: '文件读不出来' };
+  }
+  if (!text || !text.trim()) return { ok: false, reason: '文件是空的' };
+  const first = text.split('\n', 1)[0].trim();
+  const m = /^#\s*第\s*(\d+)\s*章(?:\s|$)/.exec(first);
+  if (!m) return { ok: false, reason: '首行不是 "# 第N章 标题"（实际：' + first.slice(0, 30) + '）' };
+  if (Number(m[1]) !== ch) {
+    return { ok: false, reason: '标题章号 ' + m[1] + ' 与文件名章号 ' + ch + ' 不一致' };
+  }
+  const eff = countEffectiveChars(text);
+  if (eff < 50) return { ok: false, reason: '正文太短（有效字数 ' + eff + ' < 50）' };
+  return { ok: true, reason: null };
+}
+
+export function readWritingState(dirs, T) {
+  // 已存在的章（用于续跑）
+  const existing = new Set();
+  // 章号 → 磁盘上的实际文件名。
+  // existing 用正则识别（`第(\d+)章.md`，位数不限），但 chapterFileName 拼的是
+  // 三位补零名（第001章.md）。模型要是写成 `第1章.md`，识别得到、却按补零名
+  // 读不到 —— 前情衔接就静默失效（prevTail 永远空）。这里记下实际文件名兜底。
+  const fileByChapter = new Map();
+  // 存在但没通过轻量复检的章：不算"已写完"，续跑时要重写。
+  const invalid = [];
+  let files = [];
+  try {
+    if (dirs.writing && existsSync(dirs.writing)) files = readdirSync(dirs.writing);
+  } catch {
+    files = [];
+  }
+  for (const f of files) {
+    const m = /^第(\d+)章\.md$/.exec(f);
+    if (!m) continue;
+    const ch = Number(m[1]);
+    if (!fileByChapter.has(ch)) fileByChapter.set(ch, f);
+    // 轻量复检：空文件/半截文件/标题错的**不算已写完**（2026-10-27 修）
+    const chk = quickCheckChapterFile(join(dirs.writing, f), ch);
+    if (!chk.ok) {
+      invalid.push({ ch, file: f, reason: chk.reason });
+      continue;
+    }
+    existing.add(ch);
+  }
+
+  // 台账
+  // 台账目录可能整个不存在（续跑时还没建），这时台账就是空的，不能抛错
+  const readLedger = (name) => {
+    if (!dirs.ledger) return null;
+    return readJsonSafe(join(dirs.ledger, name));
+  };
+  const ledgers = {
+    chapters: readLedger('章台账.json') || {},
+    characters: readLedger('人物台账.json') || {},
+    foreshadows: readLedger('伏笔台账.json') || {},
+    timeline: readLedger('时间线台账.json') || {}
+  };
+
+  // 前章尾部（衔接用）：取**最后写完的那一章**的尾部
+  let prevTail = '';
+  let prevChapter = T;
+  for (let ch = T; ch >= 1; ch--) {
+    if (!existing.has(ch)) continue;
+    let text = readTextSafe(join(dirs.writing, chapterFileName(ch)));
+    // 规范名（第001章.md）读不到时，用磁盘上的实际文件名再试一次
+    if (text === null) {
+      const actual = fileByChapter.get(ch);
+      if (actual) text = readTextSafe(join(dirs.writing, actual));
+    }
+    if (text === null) continue;
+    prevTail = text.slice(-WRITING_PREV_TAIL_CHARS);
+    prevChapter = ch;
+    break;
+  }
+
+  return { existing, ledgers, prevTail, prevChapter, invalid };
+}
+
+export function loadWritingContext(projectRoot) {
+  const dirs = writingDirs(projectRoot);
+  const framework = readJsonSafe(join(dirs.skeleton, '框架.json'));
+  const T = framework && framework.capacity ? Number(framework.capacity.target_chapters || 0) : 0;
+  if (!T || !Number.isFinite(T) || T <= 0) {
+    return { error: '读不到骨架 框架.json 的 capacity.target_chapters，无法确定要写多少章' };
+  }
+
+  // 章节细纲：节奏阶段的 章节细纲.json
+  const outlinesRaw = readJsonSafe(join(dirs.rhythm, '章节细纲.json'));
+  const outlines = new Map();
+  for (const o of ((outlinesRaw && outlinesRaw.outlines) || [])) {
+    if (o && typeof o.ch === 'number') outlines.set(o.ch, o);
+  }
+
+  // 章节规划 + 时序映射：用来算出"这一章该有谁、该在哪、该埋什么"
+  const planRaw = readJsonSafe(join(dirs.rhythm, '章节规划.json'));
+  const timelineRaw = readJsonSafe(join(dirs.rhythm, '时序映射.json'));
+  const entity = readJsonSafe(join(dirs.skeleton, '实体.json')) || {};
+  const fleshChars = readJsonSafe(join(dirs.flesh, '角色.json')) || {};
+  const roster = buildEntityRoster(dirs);
+  const chapterContext = buildChapterContext(planRaw, timelineRaw, entity, fleshChars, roster);
+
+  const state = readWritingState(dirs, T);
+
+  return {
+    T,
+    outlines,
+    chapterContext,
+    existing: state.existing,
+    prevTail: state.prevTail,
+    prevChapter: state.prevChapter,
+    ledgers: state.ledgers,
+    // 存在但没通过轻量复检的章（空文件/半截/标题错）——续跑要重写它们
+    invalid: state.invalid || [],
+    dirs,
+    roster,
+    error: null
+  };
+}
+
+/**
+ * 刷新写作 context 的可变部分（已写章节 / 前情衔接 / 台账）。
+ *
+ * 什么时候必须刷：每批写完之后。
+ * 不刷的后果（实测）：
+ *   · 第 2 批提示词里的"前情衔接"还是第 1 批**之前**的内容 → 承接断裂
+ *   · 台账快照是旧的 → 第 1 批把角色写成受伤，第 2 批看到的还是初始状态
+ *
+ * 静态部分（细纲 / 逐章上下文 / 花名册 / T）不动 —— 它们来自上游产物，
+ * 写作阶段不会改。
+ *
+ * @param {Object} context loadWritingContext() 的返回值
+ * @returns {Object} 同一个 context 对象（就地更新）
+ */
+export function refreshWritingContext(context) {
+  if (!context || context.error || !context.dirs) return context;
+  const state = readWritingState(context.dirs, context.T);
+  context.existing = state.existing;
+  context.prevTail = state.prevTail;
+  context.prevChapter = state.prevChapter;
+  context.ledgers = state.ledgers;
+  context.invalid = state.invalid || [];
+  return context;
+}
+
+/**
+ * 把节奏阶段的"章节规划 + 时序映射"折算成**逐章上下文**。
+ *
+ * 章节细纲本身只有功能、情绪、钩子、字数这些字段，不含"这一章该有谁、
+ * 在哪、该埋哪个伏笔"。这些信息散在 时序映射.json 的各个 *_timeline 里。
+ * 写作驱动按批派活时必须把它们逐章摊开——否则 LLM 只能靠前章结尾去猜
+ * 本章该出场谁、该推进哪条线。
+ */
+export function buildChapterContext(planRaw, timelineRaw, entity, fleshChars, roster) {
+  const nameById = new Map();
+  for (const c of (roster && roster.characters) || []) nameById.set(c.id, c.name);
+  for (const c of (roster && roster.fleshCharacters) || []) nameById.set(c.id, c.name);
+  for (const c of (entity && entity.characters) || []) if (c && c.id) nameById.set(c.id, c.name);
+  for (const c of ((fleshChars && fleshChars.characters) || [])) if (c && c.id) nameById.set(c.id, c.name);
+
+  const locName = new Map();
+  for (const l of (entity && entity.locations) || []) if (l && l.id) locName.set(l.id, l.name);
+  const itemName = new Map();
+  for (const it of (entity && entity.items) || []) if (it && it.id) itemName.set(it.id, it.name);
+  const conflictName = new Map();
+  for (const c of (entity && entity.conflicts) || []) if (c && c.id) conflictName.set(c.id, c.name);
+  const fsName = new Map();
+  for (const f of (entity && entity.foreshadows) || []) if (f && f.id) fsName.set(f.id, f.name);
+  const climaxName = new Map();
+  for (const c of (entity && entity.climaxes) || []) if (c && c.id) climaxName.set(c.id, c.name);
+  const pleasureName = new Map();
+  for (const p of (entity && entity.pleasures) || []) if (p && p.id) pleasureName.set(p.id, p.name);
+  const endingName = new Map();
+  for (const e of (entity && entity.endings) || []) if (e && e.id) endingName.set(e.id, e.name);
+
+  const ctx = new Map();
+  const get = (ch) => {
+    if (!ctx.has(ch)) {
+      ctx.set(ch, {
+        ch,
+        volume: null, act: null, sceneFocus: '',
+        characters: [], locations: [], items: [],
+        conflicts: [], foreshadows: [], climax: null, pleasure: null,
+        hook: null, ending: null
+      });
+    }
+    return ctx.get(ch);
+  };
+
+  // 章节规划：卷 / 幕 / 场景焦点
+  for (const c of ((planRaw && planRaw.chapters) || [])) {
+    if (!c || typeof c.ch !== 'number') continue;
+    const e = get(c.ch);
+    e.volume = c.volume || null;
+    e.act = typeof c.act === 'number' ? c.act : null;
+    e.sceneFocus = c.scene_focus || '';
+  }
+
+  const t = timelineRaw || {};
+
+  // 角色 / 地点 / 道具：按出场区间铺到每一章
+  const spread = (list, idKey, target, nameMap) => {
+    for (const it of (list || [])) {
+      if (!it) continue;
+      const id = it[idKey];
+      const from = typeof it.appear_start === 'number' ? it.appear_start : null;
+      const to = typeof it.appear_end === 'number' ? it.appear_end : null;
+      if (from === null || to === null) continue;
+      for (let ch = from; ch <= to; ch++) {
+        get(ch)[target].push({ id, name: nameMap.get(id) || id });
+      }
+    }
+  };
+  spread(t.character_timeline, 'char_id', 'characters', nameById);
+  spread(t.location_timeline, 'loc_id', 'locations', locName);
+  spread(t.item_timeline, 'item_id', 'items', itemName);
+
+  // 冲突：升级节点落在哪一章
+  for (const it of (t.conflict_timeline || [])) {
+    if (!it) continue;
+    const nodes = Array.isArray(it.escalation_nodes) ? it.escalation_nodes : [];
+    for (const n of nodes) {
+      // 契约字段是 chapter（templates/节奏/时序映射模板.json，
+      // rhythm-validate.js 读的也是 n.chapter）——原来这里读的是 n.ch，
+      // 字段名对不上 → 冲突升级章节永远进不了正文上下文（实测 conflicts 全空）。
+      const ch = typeof n === 'number'
+        ? n
+        : (n && typeof n.chapter === 'number' ? n.chapter
+          : (n && typeof n.ch === 'number' ? n.ch : null));
+      if (ch === null) continue;
+      get(ch).conflicts.push({ id: it.conflict_id, name: conflictName.get(it.conflict_id) || it.conflict_id });
+    }
+  }
+
+  // 伏笔：埋设章与回收章
+  for (const it of (t.foreshadow_timeline || [])) {
+    if (!it) continue;
+    const mark = (ch, kind) => {
+      if (typeof ch !== 'number') return;
+      get(ch).foreshadows.push({ id: it.fs_id, name: fsName.get(it.fs_id) || it.fs_id, kind });
+    };
+    mark(it.buried_chapter, '埋设');
+    mark(it.recovered_chapter, '回收');
+  }
+
+  // 高潮 / 爽点 / 结局
+  for (const it of (t.climax_timeline || [])) {
+    if (!it || typeof it.chapter !== 'number') continue;
+    get(it.chapter).climax = { id: it.climax_id, name: climaxName.get(it.climax_id) || it.climax_id };
+  }
+  for (const it of (t.pleasure_timeline || [])) {
+    if (!it || typeof it.chapter !== 'number') continue;
+    get(it.chapter).pleasure = { id: it.pleasure_id, name: pleasureName.get(it.pleasure_id) || it.pleasure_id };
+  }
+  for (const it of (t.ending_timeline || [])) {
+    if (!it || typeof it.chapter !== 'number') continue;
+    get(it.chapter).ending = { id: it.ending_id, name: endingName.get(it.ending_id) || it.ending_id };
+  }
+
+  // 钩子
+  for (const it of (t.hook_timeline || [])) {
+    if (!it || typeof it.ch !== 'number') continue;
+    get(it.ch).hook = { head: it.hook_head || '', tail: it.hook_tail || '', strength: it.hook_strength || '' };
+  }
+
+  return ctx;
+}
+
+function collectNamed(list) {
+  const out = [];
+  for (const it of (list || [])) {
+    if (it && it.id && it.name) out.push({ id: it.id, name: it.name });
+  }
+  return out;
+}
+
+/**
+ * 实体名册：角色 / 势力 / 地点 / 道具 / 冲突 的 id+name。
+ * 写作阶段引用实体时必须用这些 id 与 name，不能自创。
+ */
+export function buildEntityRoster(dirs) {
+  const entity = readJsonSafe(join(dirs.skeleton, '实体.json')) || {};
+  const flesh = readJsonSafe(join(dirs.flesh, '角色.json')) || {};
+  return {
+    characters: collectNamed(entity.characters),
+    conflicts: collectNamed(entity.conflicts),
+    factions: collectNamed(entity.factions),
+    locations: collectNamed(entity.locations),
+    items: collectNamed(entity.items),
+    endings: collectNamed(entity.endings),
+    fleshCharacters: collectNamed(flesh.characters)
+  };
+}
+
+// ============================================================
+// 分批
+// ============================================================
+
+/**
+ * 把 T 章切成若干批。
+ *
+ * 已经存在的章（续跑）不重复写：批次里跳过它们，
+ * 但仍然把整段章号范围交给 LLM，让它知道自己在写的是哪一段。
+ */
+export function planBatches(context, batchSize) {
+  const size = batchSize || WRITING_BATCH_SIZE;
+  const batches = [];
+  let start = 1;
+  while (start <= context.T) {
+    const end = Math.min(start + size - 1, context.T);
+    const chapters = [];
+    const skipped = [];
+    for (let ch = start; ch <= end; ch++) {
+      if (context.existing.has(ch)) skipped.push(ch);
+      else chapters.push(ch);
+    }
+    batches.push({ start, end, chapters, skipped });
+    start = end + 1;
+  }
+  return batches;
+}
+
+// ============================================================
+// Prompt 构建
+// ============================================================
+
+function formatOutline(o) {
+  if (!o) return '（本章无细纲）';
+  const lines = [];
+  const push = (k, v) => {
+    if (v === undefined || v === null || v === '') return;
+    if (Array.isArray(v)) {
+      if (v.length === 0) return;
+      lines.push('- ' + k + '：' + v.map((x) => (typeof x === 'object' ? JSON.stringify(x) : String(x))).join('；'));
+      return;
+    }
+    if (typeof v === 'object') {
+      lines.push('- ' + k + '：' + JSON.stringify(v));
+      return;
+    }
+    lines.push('- ' + k + '：' + String(v));
+  };
+  push('功能', o.function_main);
+  push('辅助功能', o.function_aux);
+  push('情绪阶段', o.emotion_phase);
+  push('爽点', o.satisfaction_type || o.satisfaction_audience);
+  push('伏笔动作', o.foreshadow_action);
+  push('势力出场', o.faction_appearance);
+  push('章首钩子', o.hook_head);
+  push('章尾钩子', o.hook_tail);
+  push('钩子强度', o.hook_strength);
+  push('出场角色', o.char_ids);
+  push('出场地点', o.loc_ids);
+  push('关联道具', o.item_ids);
+  push('关联冲突', o.conflict_ids);
+  push('字数目标', o.word_target);
+  push('所属卷', o.volume);
+  return lines.length ? lines.join('\n') : '（本章无细纲）';
+}
+
+function formatRoster(roster) {
+  const seg = (label, arr) => {
+    if (!arr || arr.length === 0) return '';
+    return label + '：' + arr.map((x) => x.id + '（' + x.name + '）').join('、');
+  };
+  const parts = [
+    seg('角色', roster.characters),
+    seg('势力', roster.factions),
+    seg('地点', roster.locations),
+    seg('道具', roster.items),
+    seg('冲突', roster.conflicts)
+  ].filter(Boolean);
+  return parts.join('\n');
+}
+
+function formatLedgerSnapshot(ledgers) {
+  const out = [];
+  // 人物台账：只要有人物（写作阶段需要人物当前状态）
+  const chars = ledgers.characters || {};
+  const charKeys = Object.keys(chars);
+  if (charKeys.length) {
+    out.push('【人物台账】');
+    for (const k of charKeys) {
+      const c = chars[k] || {};
+      out.push('- ' + k + '：位置=' + (c.current_location || '未记') +
+        '；目标=' + (c.current_goal || '未记') +
+        '；状态=' + (c.status || '未记') +
+        '；上次出场=' + (c.last_appear_chapter === undefined ? '未记' : c.last_appear_chapter));
+    }
+  }
+  // 伏笔台账：只要未回收的
+  const fs = ledgers.foreshadows || {};
+  const open = Object.entries(fs).filter(([, v]) => v && (v.status === 'open' || v.status === 'progressing'));
+  if (open.length) {
+    out.push('');
+    out.push('【未回收伏笔】');
+    for (const [k, v] of open) {
+      out.push('- ' + k + '：' + (v.content || '') + '（埋于第 ' + (v.buried_chapter === undefined ? '?' : v.buried_chapter) + ' 章，状态 ' + v.status + '）');
+    }
+  }
+  // 时间线
+  const tl = ledgers.timeline || {};
+  if (tl.current_time) {
+    out.push('');
+    out.push('【当前时间】' + tl.current_time + '（已过 ' + (tl.elapsed_days === undefined ? '?' : tl.elapsed_days) + ' 天）');
+  }
+  return out.join('\n');
+}
+
+/**
+ * 渲染"这一章该有谁、该在哪、该推进什么"。
+ * 数据来自节奏阶段的 章节规划 + 时序映射，由驱动算好后逐章摊开，
+ * LLM 不需要自己去翻上游 JSON。
+ */
+function formatChapterContext(context, ch) {
+  const c = (context.chapterContext && context.chapterContext.get(ch)) || null;
+  if (!c) return '';
+  const lines = [];
+  if (c.volume) lines.push('- 所属卷：' + c.volume + (c.act ? '（第 ' + c.act + ' 幕）' : ''));
+  if (c.sceneFocus) lines.push('- 场景焦点：' + c.sceneFocus);
+  if (c.characters.length) {
+    lines.push('- 出场角色：' + c.characters.map((x) => x.id + '（' + x.name + '）').join('、'));
+  }
+  if (c.locations.length) {
+    lines.push('- 出场地点：' + c.locations.map((x) => x.id + '（' + x.name + '）').join('、'));
+  }
+  if (c.items.length) {
+    lines.push('- 出场道具：' + c.items.map((x) => x.id + '（' + x.name + '）').join('、'));
+  }
+  if (c.conflicts.length) {
+    lines.push('- 涉及冲突：' + c.conflicts.map((x) => x.id + '（' + x.name + '）').join('、'));
+  }
+  if (c.foreshadows.length) {
+    lines.push('- 伏笔动作：' + c.foreshadows.map((x) => x.id + '（' + x.name + '）' + x.kind).join('、'));
+  }
+  if (c.climax) lines.push('- 本章高潮：' + c.climax.id + '（' + c.climax.name + '）');
+  if (c.pleasure) lines.push('- 本章爽点：' + c.pleasure.id + '（' + c.pleasure.name + '）');
+  if (c.ending) lines.push('- 本章结局：' + c.ending.id + '（' + c.ending.name + '）');
+  if (c.hook) {
+    lines.push('- 钩子：章首 ' + (c.hook.head || '未指定') + ' / 章尾 ' + (c.hook.tail || '未指定') +
+      (c.hook.strength ? '（强度 ' + c.hook.strength + '）' : ''));
+  }
+  if (lines.length === 0) return '';
+  return '**本章上下文**\n\n' + lines.join('\n') + '\n\n';
+}
+
+/**
+ * 构建一个批次的提示词。
+ *
+ * attempt > 1 时是重试提示词：只要求重写失败的章，并把校验错误原样带上。
+ *
+ * contract 是写作执行须知（产物契约），由调用方从 prompts/04-writing-prompt.md 读出，
+ * 每批带一遍；它只讲"写成什么样"，不讲流程——流程由驱动执行。
+ */
+export function buildBatchPrompt(context, batch, attempt, failures, contract) {
+  const isRetry = attempt > 1 && failures && failures.length > 0;
+  const targetChapters = isRetry ? failures.map((f) => f.ch) : batch.chapters;
+  const parts = [];
+
+  if (contract) {
+    parts.push(contract.trim());
+    parts.push('');
+    parts.push('---');
+    parts.push('');
+  }
+
+  parts.push('# 本轮派活：第 ' + batch.start + '-' + batch.end + ' 批' + (isRetry ? '（重试）' : ''));
+  parts.push('');
+  parts.push('本轮由写作驱动分批派活。请**严格按下面的章号顺序**完成本轮的每一章。');
+  parts.push('');
+
+  if (isRetry) {
+    parts.push('## 本轮需要重写的章（校验未通过）');
+    parts.push('');
+    for (const f of failures) {
+      parts.push('### 第 ' + f.ch + ' 章 —— 校验未通过');
+      parts.push('');
+      parts.push('错误清单：');
+      for (const e of (f.errors || [])) {
+        parts.push('- [' + e.code + '] ' + (e.path || '(无路径)') + '：' + e.message + (e.hint ? '（' + e.hint + '）' : ''));
+      }
+      parts.push('');
+      const cc = formatChapterContext(context, f.ch);
+      if (cc) parts.push(cc);
+      parts.push('该章细纲：');
+      parts.push(formatOutline(context.outlines.get(f.ch)));
+      parts.push('');
+    }
+    parts.push('**只重写上面列出的章**，其它已通过的章不要动，也不要重复写。');
+    parts.push('');
+    parts.push('**重写完要同步更新台账**：把章台账里这些章的同 `ch` 旧条目**替换**掉（不要留两条），' +
+      '并把本轮的 `hook_head_type` / `hook_tail_type` / `micro_payoffs` 登记对；' +
+      '人物台账、伏笔台账、时间线台账也要跟上。台账没更新，校验器读到的还是上一版，会一直报同一个错。');
+    parts.push('');
+  } else {
+    parts.push('## 本轮要写的章');
+    parts.push('');
+    for (const ch of batch.chapters) {
+      parts.push('### 第 ' + ch + ' 章');
+      parts.push('');
+      const cc = formatChapterContext(context, ch);
+      if (cc) parts.push(cc);
+      parts.push(formatOutline(context.outlines.get(ch)));
+      parts.push('');
+    }
+  }
+
+  parts.push('## 落盘路径');
+  parts.push('');
+  for (const ch of targetChapters) {
+    parts.push('- 第 ' + ch + ' 章 → `设定/raw/sources/写作/' + chapterFileName(ch) + '`');
+  }
+  parts.push('');
+
+  if (context.prevTail) {
+    parts.push('## 前情衔接（第 ' + context.prevChapter + ' 章结尾 ' + WRITING_PREV_TAIL_CHARS + ' 字）');
+    parts.push('');
+    parts.push('```');
+    parts.push(context.prevTail);
+    parts.push('```');
+    parts.push('');
+  }
+
+  const snapshot = formatLedgerSnapshot(context.ledgers);
+  if (snapshot) {
+    parts.push('## 当前台账快照');
+    parts.push('');
+    parts.push(snapshot);
+    parts.push('');
+  }
+
+  const roster = formatRoster(context.roster);
+  if (roster) {
+    parts.push('## 实体名册（引用实体时只能用这里的 id 与 name，不得自创）');
+    parts.push('');
+    parts.push(roster);
+    parts.push('');
+  }
+
+  parts.push('## 怎么写');
+  parts.push('');
+  parts.push('1. 逐章读 `references/写作指导/` 下的相关文件（`01-scene.md` 场景五要素、`02-chapter-workflow.md` 成章流程、' +
+    '`03-opening-chapter.md` 开篇、`04-dialogue-mastery.md` 对话、`06-tone-ensemble.md` 文风、`05-genre-formulas.md` 题材公式）。');
+  parts.push('2. 写完一章就把正文写进上面的落盘路径（正文第一行是 `# 第N章 <标题>`，N 与章号一致）。');
+  parts.push('3. 写完一章就更新台账：`设定/raw/sources/写作/台账/` 下的 `章台账.json`（追加本章）、' +
+    '`人物台账.json`（更新出场角色）、`伏笔台账.json`（更新 open/progressing 状态）、`时间线台账.json`（推进当前位置）。');
+  parts.push('   **重写某章时，要把章台账里同 `ch` 的旧条目替换掉，不要留两条** —— ' +
+    '校验器按 ch 取最后一条生效版本，留两条会让钩子类型、微兑现这些登记读不到。');
+  parts.push('   章台账每章要登记 `hook_head_type`（7 式章首引子之一）、`hook_tail_type`（13 式章末钩子之一）、' +
+    '`micro_payoffs`（7 种微兑现，至少 1 个）；有角色复生就登记 `revival_events`。取值见 `references/写作指导/09-reading-power.md`。');
+  parts.push('4. **不要自己跑校验脚本**——写完本轮所有章并更新完台账即可，驱动会逐章校验并把错误发回来。');
+  parts.push('5. 全部写完后，用一段话汇报：本轮写了哪几章、每章标题与字数、埋/收了哪些伏笔、哪些章没有细纲。');
+  parts.push('');
+
+  return parts.join('\n');
+}
+
+// ============================================================
+// 等待 LLM 跑完一轮
+// ============================================================
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * 造一个"等 LLM 把这一轮做完"的函数。
+ *
+ * 直接用 agent.whenIdle() 有竞态：send() 之后 agent 可能还没被唤醒，
+ * whenIdle() 立刻就 resolve 了。所以这里改成轮询 agent.status：
+ *   - 观察到 running → 说明这一轮已经启动；
+ *   - 从 running 变回 idle → 这一轮结束；
+ *   - 如果一直没观察到 running，但连续 idle 超过 idleGraceMs，
+ *     判定为"这一轮没跑起来或已经空转结束"。
+ *
+ * 同时用"预期产物是否都落盘"作为第二重判据：LLM 没写文件时能立刻判定失败，
+ * 不必干等到超时。
+ *
+ * 改写场景（去 AI 味）需要第三重判据：文件**本来就存在**，
+ * 光看"文件在不在"会立刻判定成功（模型其实什么都没改）。
+ * 这时传 options.changed(files, before) —— 返回 true 才算这轮真的改了东西。
+ * before 是本轮开始前的文件内容（基线），由调用方每次 waitIdle 时传入。
+ *
+ * 失败时返回 code（机器可读），调用方据此决定是重试还是放弃：
+ *   NO_CHANGE —— 模型跑了但没动目标文件（改写场景的可重试失败）
+ *   NO_OUTPUT —— 模型跑了但没产出预期文件
+ *   TIMEOUT / ABORTED / NO_AGENT —— 环境问题，重试也没用
+ *
+ * @param {Object} invocation
+ * @param {Object} [opts]
+ * @param {number} [opts.pollMs]
+ * @param {number} [opts.timeoutMs]
+ * @param {number} [opts.idleGraceMs]
+ * @param {AbortSignal} [opts.signal]
+ * @param {(files:string[], before?:string) => boolean} [opts.changed] 内容变化判据
+ * @returns {(expectedFiles?: string[], before?: string) => Promise<{ok:boolean, reason?:string, code?:string, missing?:string[]}>}
+ */
+/**
+ * 读最近一次「回合结束」的失败原因。
+ *
+ * 为什么需要它（2026-10-25 线上故障）：
+ * provider 报错（429 限流 / 400 / 401…）时，DSH 的 agent 会把这一轮以
+ * `turn/end {reason:{kind:'error', error:{code, message}}}` 收掉
+ * （dsh-agent-loop/lib/index.js:984-990），**模型一个字都没写**。
+ * 而等待逻辑只看"文件在不在"，于是把它报成
+ * "NO_OUTPUT：LLM 本轮结束但没有产出预期文件" ——
+ * 真因（限流/鉴权/上下文超限）被完全盖掉，用户只能猜。
+ *
+ * @param {object} session - DSH Session
+ * @param {number} sinceSeq - 只看这个 seq 之后的回合（避免拿到上一轮的错误）
+ * @returns {{code: string, reason: string} | null}
+ */
+export function lastTurnFailure(session, sinceSeq) {
+  const log = session && Array.isArray(session.log) ? session.log : null;
+  if (!log) return null;
+  for (let i = log.length - 1; i >= 0; i--) {
+    const event = log[i];
+    if (!event || event.type !== 'turn/end') continue;
+    if (typeof sinceSeq === 'number' && event.seq < sinceSeq) return null;
+    const reason = event.data && event.data.reason;
+    if (!reason || reason.kind === 'completed') return null;
+    if (reason.kind === 'error') {
+      const failure = reason.error || {};
+      const code = failure.code || 'UNKNOWN';
+      const message = failure.message || JSON.stringify(failure);
+      return { code: 'TURN_ERROR', providerCode: code, reason: '本轮对话出错（' + code + '）：' + message };
+    }
+    if (reason.kind === 'aborted') {
+      return { code: 'ABORTED', reason: '本轮对话被中断' };
+    }
+    return { code: 'TURN_' + String(reason.kind).toUpperCase(), reason: '本轮对话未完成（' + reason.kind + '）' };
+  }
+  return null;
+}
+
+export function makeWaitForTurn(invocation, opts) {
+  const options = opts || {};
+  const pollMs = options.pollMs || 300;
+  const timeoutMs = options.timeoutMs || 45 * 60 * 1000;
+  const idleGraceMs = options.idleGraceMs || 15000;
+  const signal = options.signal || null;
+  const changed = typeof options.changed === 'function' ? options.changed : null;
+
+  return async function waitForTurn(expectedFiles, before) {
+    const agent = invocation && invocation.agent;
+    // 守卫要检查实际使用的 API：下面轮询的是 agent.status（DSH 的 AgentStatus
+    // 只有 'idle' | 'running' 两个值），此前却检查 agent.whenIdle 是否存在，
+    // 守卫与被守卫的对象不是同一个。
+    if (!agent || typeof agent.status !== 'string') {
+      return { ok: false, code: 'NO_AGENT', reason: '当前运行时没有暴露 agent，无法等待 LLM 完成本轮' };
+    }
+    const deadline = Date.now() + timeoutMs;
+    const startedAt = Date.now();
+    let sawRunning = false;
+    // 本轮开始前的日志长度：只认这之后的 turn/end，
+    // 免得把上一轮的 provider 错误算到这一轮头上。
+    const session = agent.session || null;
+    const sinceSeq = session && Array.isArray(session.log) ? session.log.length : undefined;
+
+    while (Date.now() < deadline) {
+      // 用户中断时立刻放手：命令处理器不该在用户取消后还傻等 45 分钟
+      if (signal && signal.aborted) {
+        return { ok: false, code: 'ABORTED', reason: '已被用户中断', aborted: true };
+      }
+      const running = agent.status === 'running';
+      if (running) {
+        sawRunning = true;
+        await sleep(pollMs);
+        continue;
+      }
+      // idle
+      const files = expectedFiles || [];
+      const missing = files.filter((f) => !existsSync(f));
+      // changed 为空时行为与从前一致（文件在就算成功）。
+      // before 是本轮的基线内容：重投场景里文件**本来就在**，
+      // "文件在不在"不能当完成判据，必须看内容有没有变。
+      const changedOk = !changed || changed(files, before);
+      if (files.length > 0 && missing.length === 0 && changedOk) {
+        return { ok: true, sawRunning };
+      }
+      if (files.length > 0 && missing.length === 0) {
+        // 文件在，但内容没变（重投场景）：模型这轮等于什么都没做。
+        //
+        // 必须**立刻**判失败，不能继续等：继续等会一直等到 idleGraceMs
+        // （阶段驱动给的是 60 秒），几十个批次 × 3 轮 = 卡死十几分钟
+        // （实测 2026-10-24：全量回归挂在 apply-orchestration 上 11 分钟）。
+        // 有没有观察到 running 不影响这个结论：内容没变就是没变。
+        return { ok: false, code: 'NO_CHANGE', reason: 'LLM 本轮结束但目标文件内容没有变化', missing: [] };
+      }
+      if (sawRunning) {
+        // 这一轮跑完了，但产物没落盘。
+        //
+        // 先看这一轮是不是**带着错误**结束的（provider 限流 / 鉴权 / 上下文超限…）：
+        // 那种情况下模型是被打断的，本来就写不出文件 —— 报 NO_OUTPUT 会把真因盖掉，
+        // 用户只能猜（2026-10-25 线上：骨架报"NO_OUTPUT"，真因是 provider 报错）。
+        const failure = lastTurnFailure(session, sinceSeq);
+        if (failure) {
+          return {
+            ok: false,
+            code: failure.code,
+            ...(failure.providerCode ? { providerCode: failure.providerCode } : {}),
+            reason: failure.reason,
+            missing,
+          };
+        }
+        return { ok: false, code: 'NO_OUTPUT', reason: 'LLM 本轮结束但没有产出预期文件', missing };
+      }
+      if (Date.now() - startedAt > idleGraceMs) {
+        return { ok: false, code: 'TIMEOUT', reason: '等待 LLM 响应超时（未观察到本轮启动）' };
+      }
+      await sleep(pollMs);
+    }
+    return { ok: false, code: 'TIMEOUT', reason: '等待 LLM 响应超时' };
+  };
+}
+
+// ============================================================
+// 主循环
+// ============================================================
+
+/**
+ * 分片内容变化判定（阶段驱动用）。
+ *
+ * 为什么需要它：阶段驱动的重投**不能删旧分片** ——
+ * DSH 的 write 工具记着"本会话上次看到这个文件时的版本"，
+ * 文件被外部删掉后再写同一路径会报 FS_STALE_VERSION
+ * （"cannot write ...: file no longer exists — re-read the file, then retry"），
+ * 而 re-read 同样失败（文件已经没了），模型就此卡死。
+ * 所以旧分片留着，完成判据改成"内容相对基线有没有变"。
+ *
+ * before 为 null（首轮，文件本来就不存在）时不做判定，直接算变了。
+ *
+ * @param {string[]} files - 本轮预期产物的路径
+ * @param {string|null} before - 本轮开始前的内容基线
+ * @returns {boolean} 有任一文件的内容变了就算变了
+ */
+export function shardContentChanged(files, before) {
+  if (before === null || before === undefined) return true;
+  return (files || []).some((f) => {
+    try {
+      return readFileSync(f, 'utf-8') !== before;
+    } catch {
+      // 读不到 = 文件没了 = 算变了（交给上层按"没产出"处理）
+      return true;
+    }
+  });
+}
+
+/**
+ * 按批驱动写作阶段。
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {number} [opts.batchSize]
+ * @param {number} [opts.maxAttempts]
+ * @param {(prompt: string) => Promise<{ok: boolean, error?: string}>} opts.sendPrompt
+ * @param {() => Promise<void>} opts.waitIdle
+ * @param {(ch: number) => Promise<{status: number, errors: Array, warnings: Array}>} opts.validateChapter
+ * @param {(msg: string) => void} [opts.onProgress]
+ * @param {Array} [opts.outline] 预置的细纲（测试用；不传则从磁盘读）
+ * @returns {Promise<Object>} 汇总报告
+ */
+export async function runWritingStage(opts) {
+  const context = opts.context || loadWritingContext(opts.projectRoot);
+  if (context.error) {
+    return { ok: false, error: context.error, batches: [], written: [], failed: [] };
+  }
+  const batchSize = opts.batchSize || WRITING_BATCH_SIZE;
+  const maxAttempts = opts.maxAttempts || WRITING_MAX_BATCH_ATTEMPTS;
+
+  // ---- 续跑复检（P1-1）----
+  //
+  // 旧实现里"已存在的章"**从来没有被校验过**：文件在磁盘上就算"写完了"。
+  // 于是上次失败留下的空文件/半截文件会被永久跳过 —— 续跑多少遍都补不上，
+  // 而最终消息还写着"0 章全部写完并通过逐章校验"，用户完全看不出来。
+  //
+  // 现在对每个已存在的章跑一次完整校验：
+  //   通过 → 计入 reused（复用，不重写）
+  //   没过 → 移出 existing，当作待写章重新写
+  const reused = [];
+  const recheckFailed = [];
+  const existingBefore = [...(context.existing || [])].sort((a, b) => a - b);
+  for (const ch of existingBefore) {
+    if (!opts.validateChapter) {
+      reused.push(ch);
+      continue;
+    }
+    const r = await opts.validateChapter(ch);
+    if (r && r.status === 0) {
+      reused.push(ch);
+    } else {
+      context.existing.delete(ch);
+      recheckFailed.push({ ch, errors: (r && r.errors) || [] });
+    }
+  }
+
+  const batches = planBatches(context, batchSize);
+
+  const report = {
+    ok: true, error: null, batches: [], written: [], failed: [], skipped: [],
+    reused, recheckFailed
+  };
+
+  for (const batch of batches) {
+    if (batch.chapters.length === 0) {
+      report.skipped.push({ start: batch.start, end: batch.end, chapters: batch.skipped });
+      if (opts.onProgress) opts.onProgress('第 ' + batch.start + '-' + batch.end + ' 章已存在，跳过。');
+      continue;
+    }
+
+    let attempt = 1;
+    let failures = [];
+    let attemptLog = [];
+
+    while (attempt <= maxAttempts) {
+      const prompt = buildBatchPrompt(context, batch, attempt, failures, opts.contract);
+      const sent = await opts.sendPrompt(prompt);
+      if (!sent || sent.ok !== true) {
+        report.ok = false;
+        report.error = (sent && sent.error) || '提示词投递失败';
+        report.batches.push({ start: batch.start, end: batch.end, attempt, ok: false, error: report.error });
+        return report;
+      }
+      // waitIdle 的返回值必须检查：它失败时（例如某章没落盘 → NO_OUTPUT），
+      // 不检查就往下走"逐章校验"，会把没写的章当成"写完了"（实测：
+      // 30 章全被记成已写，报告还写着成功）。
+      const waited = await opts.waitIdle(batch.chapters.map((ch) => join(context.dirs.writing, chapterFileName(ch))));
+      if (!waited || waited.ok !== true) {
+        const code = (waited && waited.code) || '';
+        const reason = (waited && waited.reason) || '等待 LLM 结束失败';
+        attemptLog.push({ attempt, failed: batch.chapters.slice(), note: reason });
+        // 环境类失败重试没有意义（超时 / 用户中断 / 运行时缺失）
+        if (code === 'TIMEOUT' || code === 'ABORTED' || code === 'NO_AGENT') {
+          report.ok = false;
+          report.error = reason;
+          report.batches.push({ start: batch.start, end: batch.end, attempt, ok: false, error: reason });
+          return report;
+        }
+        // waitIdle 失败不代表整批都没写出来 —— 可能是最后一章超时，
+        // 前面的章已经落盘了。旧实现把**整批**列进 failures，
+        // 下一次 prompt 就要求重写 1~10 章，已经写好的 1~9 章会被覆盖。
+        // 现在先逐章看：真的没落盘的、或者落盘了但校验不过的，才要重写。
+        const missing = [];
+        const okChapters = [];
+        for (const ch of batch.chapters) {
+          const p = join(context.dirs.writing, chapterFileName(ch));
+          const text = readTextSafe(p);
+          if (text === null || !text.trim()) {
+            missing.push(ch);
+            continue;
+          }
+          if (!opts.validateChapter) {
+            okChapters.push(ch);
+            continue;
+          }
+          const r = await opts.validateChapter(ch);
+          if (r && r.status === 0) okChapters.push(ch);
+          else missing.push(ch);
+        }
+
+        if (!missing.length) {
+          // 整批其实都写好了（waitIdle 失败多半是最后一章超时）
+          failures = [];
+          refreshWritingContext(context);
+          report.batches.push({
+            start: batch.start, end: batch.end, attempt, ok: true,
+            results: okChapters.map((ch) => ({ ch, status: 0, errors: [], warnings: [] }))
+          });
+          report.written.push(...batch.chapters);
+          if (opts.onProgress) {
+            opts.onProgress('第 ' + batch.start + '-' + batch.end + ' 章已写完并通过校验（等待超时但内容已落盘）。');
+          }
+          break;
+        }
+
+        failures = missing.map((ch) => ({
+          ch,
+          status: 2,
+          errors: [{ code: code || 'WAIT_FAILED', path: chapterFileName(ch), message: reason, hint: null }],
+          warnings: []
+        }));
+        if (attempt < maxAttempts) {
+          attempt += 1;
+          continue;
+        }
+        report.ok = false;
+        report.error = reason;
+        report.batches.push({ start: batch.start, end: batch.end, attempt, ok: false, error: reason });
+        for (const f of failures) report.failed.push({ ch: f.ch, errors: f.errors });
+        return report;
+      }
+
+      // 逐章校验
+      const results = [];
+      for (const ch of batch.chapters) {
+        const r = await opts.validateChapter(ch);
+        results.push({ ch, status: r.status, errors: r.errors || [], warnings: r.warnings || [] });
+      }
+      const bad = results.filter((r) => r.status !== 0);
+      attemptLog.push({ attempt, failed: bad.map((b) => b.ch) });
+
+      if (bad.length === 0) {
+        // 本批通过：清掉上一轮遗留的失败清单，否则重试成功的批仍会被记成失败
+        failures = [];
+        // 刷新 context：下一批要用**本批写完之后**的前情衔接和台账快照，
+        // 否则第 2 批承接的还是第 1 批之前的内容（角色状态前后矛盾）。
+        // 注意只在"本批通过"时刷 —— 同批重试时前情衔接必须停在上一批末尾，
+        // 不能拿本批的半成品当衔接。
+        refreshWritingContext(context);
+        report.batches.push({ start: batch.start, end: batch.end, attempt, ok: true, results });
+        report.written.push(...batch.chapters);
+        if (opts.onProgress) {
+          opts.onProgress('第 ' + batch.start + '-' + batch.end + ' 章已写完并通过校验（' + batch.chapters.length + ' 章）。');
+        }
+        break;
+      }
+
+      failures = bad;
+      if (attempt < maxAttempts) {
+        if (opts.onProgress) {
+          opts.onProgress('第 ' + batch.start + '-' + batch.end + ' 批有 ' + bad.length + ' 章校验未通过，正在重写。');
+        }
+      }
+      attempt++;
+    }
+
+    if (failures.length > 0) {
+      // 报告不能说"成功"：有章没过校验，ok 必须是 false，error 要写清楚。
+      // （之前只把失败塞进 batches，report.ok 仍是 true、error 仍是 null ——
+      //   任何按 report.ok 判断的调用方都会被误导。）
+      report.ok = false;
+      if (!report.error) {
+        report.error = '有 ' + failures.length + ' 章没通过校验';
+      }
+      report.batches.push({ start: batch.start, end: batch.end, attempt: maxAttempts, ok: false, results: failures });
+      for (const f of failures) report.failed.push({ ch: f.ch, errors: f.errors });
+      // 本批没过，但可能已经把部分章写到磁盘上了。
+      // 下一批的"前情衔接"必须按**磁盘上的真实状态**来 ——
+      // 不刷新的话，失败批残留的章会被跳过，时间线/人物状态就错位了。
+      refreshWritingContext(context);
+      if (opts.onProgress) {
+        opts.onProgress('第 ' + batch.start + '-' + batch.end + ' 批仍有 ' + failures.length + ' 章未通过，已记入报告，继续下一批。');
+      }
+    }
+  }
+
+  return report;
+}