@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/plugins/fancy-story-builder/index.js

@@ -0,0 +1,3152 @@
+/**
+ * fancy-story-builder plugin entry
+ *
+ * 触发命令:
+ *   /fancy-story-builder skeleton - 骨架阶段
+ *   /fancy-story-builder flesh   - 血肉阶段
+ *   /fancy-story-builder rhythm  - 节奏阶段
+ *   /fancy-story-builder analyze - 分析阶段
+ *
+ * 流程：
+ *   1. 检查 setup_id，不存在则调用 llm_wiki 创建"设定"项目
+ *   2. 读取 _novel_topic.json 获取选题信息
+ *   3. 读取 对标/wiki/ 获取对标参考
+ *   4. 根据子命令生成提示词
+ *
+ * 依赖：
+ *   - fancy-topic (选题)
+ *   - fancy-analyze (拆解对标)
+ */
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync, copyFileSync, renameSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { llmFollowup, notify, spawnScript } from '#infra';
+import { describeFetchError, readJsonSafe } from '#llm-wiki';
+import { storyBuilder } from './templates.js';
+import { readWikiReferences, renderBenchmarkGuidance } from './wiki-references.js';
+import { readInputSnapshot, readStageGate } from './scripts/graph-utils.js';
+import {
+  inspectFleshOutput,
+  readFleshStageStatus
+} from './flesh-output.js';
+import {
+  inspectRhythmOutput,
+  readRhythmStageStatus,
+  buildRhythmCompletionNote
+} from './rhythm-output.js';
+import {
+  planFleshBatches,
+  planRhythmBatches,
+  planSkeletonBatches,
+  mergeFleshShards,
+  cleanupPartialFiles,
+  attributeErrors,
+  computeKeyChapters,
+  buildClimaxTypes,
+  RHYTHM_CROSS_FILE_OWNERS,
+  SHARD_DIR_NAME,
+  RHYTHM_SHARD_DIR_NAME,
+  SKELETON_SHARD_DIR_NAME
+} from './scripts/stage-batches.js';
+import { quotaPathToArray } from './scripts/skeleton-quota.js';
+import {
+  inspectSkeletonOutput,
+  readSkeletonStageStatus,
+  readSkeletonSettledFiles,
+  buildSkeletonCompletionNote
+} from './skeleton-output.js';
+import {
+  collectRelevantRelations,
+  buildIdToName,
+  buildRhythmChapterRefs,
+  buildRhythmPrevTail,
+  buildRhythmSkeletonOutline
+} from './scripts/stage-contract.js';
+import { runStageBatches, createStageSession, makeShardAdopter } from './stage-driver.js';
+import { phaseScriptFiles } from './deploy-manifest.js';
+import { renderInfraBlock, classifyIssues } from './scripts/error-classes.js';
+import {
+  buildSemanticLintPrompt,
+  parseLintBlocks,
+  reviewLintFindings,
+  collectFleshEntities,
+  collectSkeletonRelations,
+  collectEntityKeys
+} from './scripts/semantic-lint.js';
+import {
+  loadWritingContext,
+  runWritingStage,
+  makeWaitForTurn,
+  shardContentChanged,
+  chapterFileName,
+  WRITING_BATCH_SIZE
+} from './writing-driver.js';
+import {
+  deslopDirs,
+  listChapterFiles,
+  runDeslopStage,
+  renderChapterReport,
+  renderOverviewReport,
+  writeReport
+} from './deslop-driver.js';
+
+export const inject = ['commands', 'userQuestions'];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// llm-wiki HTTP 调用超时（毫秒）
+const LLM_WIKI_TIMEOUT_MS = 30000;
+
+// 血肉阶段单批产物的目标字节上限。
+// 2026-10 tt5 实测：8 个文件一次性派活（真实规模 340KB）在写到最后一个文件时
+// 被 provider 中断（output new_sensitive 1027），且因为全量校验从没跑过，
+// 整个失败对用户完全不可见。改成逐批派活后，每批必须远小于单回合输出预算。
+const FLESH_BATCH_MAX_BYTES = 40 * 1024;
+
+// 骨架阶段单批产物的目标字节上限。
+// 骨架的实体条目很小（id + name + 枚举字段），关系条目也很小，
+// 唯一的大对象是框架.json（整文件型，含 30 条 derivations）。
+const SKELETON_BATCH_MAX_BYTES = 40 * 1024;
+
+// 骨架关系+层级段：每生成多少个批次做一次中途校验。
+//
+// 为什么需要（tt5 实测）：那一段有 27+4=31 个批次，阶段级校验要**全部写完**才跑。
+// 第 8 批（faction_relations）写错行数 → 要等 23 批都写完才发现 → 整段返工。
+// 而模型在没有反馈通道的那 31 轮里，自己造了 45 个检查脚本在猜校验器的判据
+// （_chk2.mjs … _chk46.mjs），还去读了校验器源码 14 次。
+//
+// 8 是折中：太密会反复合并+起进程（每次校验都是一次 node 启动），
+// 太稀又会把反馈推得太晚。tt5 的错在第 8 批，8 刚好当场抓住。
+const SKELETON_CHECKPOINT_EVERY = 8;
+
+// 节奏阶段单批产物的目标字节上限。
+// 节奏的真实体量比血肉还大（tt5 实测 T=800 时全量约 1.5MB：章节规划 20 批 +
+// 时序映射 34 批 + 章节细纲 32 批），逐批派活后单批仍必须远小于单回合输出预算。
+const RHYTHM_BATCH_MAX_BYTES = 40 * 1024;
+
+function getProjectRoot(session) {
+  // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
+  // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
+  // 此时返回 null，由调用方给出明确报错。
+  const cwd = session.header?.cwd;
+  return cwd || null;
+}
+
+/**
+ * 读取 .fancy-deployed 配置
+ *
+ * 返回 { ok, config, reason }：
+ *   ok=false 时 reason 区分"文件不存在"与"文件损坏"，
+ *   避免把损坏的配置文件报成"尚未初始化"（而 bootstrap 又因文件存在拒绝重复 init），
+ *   形成无自愈路径的死锁。
+ */
+/**
+ * 读 .fancy-deployed 配置。
+ *
+ * 导出给 fancy-import 用：导入阶段也要读同一份配置（llm-wiki 地址 / token），
+ * 各写一份解析的话，配置格式一变就会漏一处。
+ */
+export function readDeployedConfig(projectRoot) {
+  const deployedPath = join(projectRoot, '.fancy-deployed');
+  if (!existsSync(deployedPath)) {
+    return { ok: false, config: null, reason: 'not_found' };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(deployedPath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, config: null, reason: 'corrupt: 顶层不是对象' };
+    }
+    return { ok: true, config: parsed, reason: null };
+  } catch (e) {
+    return { ok: false, config: null, reason: 'corrupt: ' + e.message };
+  }
+}
+
+/**
+ * 更新 .fancy-deployed 中的指定字段
+ *
+ * 采用"临时文件 + rename"做原子写，避免进程被杀/磁盘满时留下半截 JSON。
+ */
+function updateDeployedField(projectRoot, key, value) {
+  const deployedPath = join(projectRoot, '.fancy-deployed');
+  const res = readDeployedConfig(projectRoot);
+  if (!res.ok) return false;
+  const config = res.config;
+  config[key] = value;
+  const tmpPath = deployedPath + '.tmp-' + process.pid;
+  try {
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2), 'utf-8');
+    renameSync(tmpPath, deployedPath);
+    return true;
+  } catch (e) {
+    console.error(`[fancy-story-builder] 更新 .fancy-deployed 失败: ${e.message}`);
+    try { if (existsSync(tmpPath)) unlinkSync(tmpPath); } catch { /* ignore */ }
+    return false;
+  }
+}
+
+/**
+ * 读取 _novel_topic.json
+ */
+
+/**
+ * 拷贝阶段对应的参考文件到项目根的 references/ 目录
+ *
+ * 新版设计：references/ 下含分类子目录（骨架指导/血肉指导/节奏指导/写作指导/）
+ * 和顶层文件（glossary.md / index.md / formulas-*.json）。
+ *
+ * 各阶段拷贝：阶段相关的指导分类目录 + 顶层文件（词表/公式）。
+ */
+function copyPhaseReferences(projectRoot, phase) {
+  const PLUGIN_REFERENCES_DIR = join(__dirname, 'references');
+  const PROJECT_REFERENCES_DIR = join(projectRoot, 'references');
+
+  // 各阶段对应的指导分类目录
+  const PHASE_GUIDE_DIRS = {
+    skeleton: ['骨架指导'],
+    flesh: ['血肉指导'],
+    rhythm: ['节奏指导'],
+    writing: ['写作指导'],
+    deslop: ['写作指导'],
+    analyze: ['骨架指导', '血肉指导', '节奏指导', '写作指导']
+  };
+  // 各阶段顶层文件（glossary.md 总是需要；formulas 各阶段不同）
+  const PHASE_TOP_FILES = {
+    skeleton: ['glossary.md', 'formulas-skeleton.json', 'index.md'],
+    flesh: ['glossary.md', 'index.md'],
+    rhythm: ['glossary.md', 'formulas-rhythm.json', 'index.md'],
+    writing: ['glossary.md', 'index.md'],
+    deslop: ['glossary.md', 'index.md'],
+    analyze: ['glossary.md', 'formulas-skeleton.json', 'formulas-rhythm.json', 'index.md']
+  };
+
+  const guideDirs = PHASE_GUIDE_DIRS[phase] || [];
+  const topFiles = PHASE_TOP_FILES[phase] || ['glossary.md'];
+
+  // 确保项目 references 目录存在
+  if (!existsSync(PROJECT_REFERENCES_DIR)) {
+    try {
+      mkdirSync(PROJECT_REFERENCES_DIR, { recursive: true });
+    } catch {
+      return false;
+    }
+  }
+
+  let allOk = true;
+
+  // 拷贝指导分类目录（递归）
+  for (const guideDir of guideDirs) {
+    const srcDir = join(PLUGIN_REFERENCES_DIR, guideDir);
+    const destDir = join(PROJECT_REFERENCES_DIR, guideDir);
+    if (!copyDirRecursive(srcDir, destDir)) allOk = false;
+  }
+
+  // 拷贝顶层文件
+  for (const f of topFiles) {
+    const src = join(PLUGIN_REFERENCES_DIR, f);
+    const dest = join(PROJECT_REFERENCES_DIR, f);
+    if (existsSync(src)) {
+      try {
+        copyFileSync(src, dest);
+      } catch {
+        allOk = false;
+      }
+    }
+  }
+
+  return allOk;
+}
+
+/**
+ * 递归拷贝目录（含子目录）
+ */
+function copyDirRecursive(srcDir, destDir) {
+  try {
+    if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  try {
+    mkdirSync(destDir, { recursive: true });
+  } catch {
+    return false;
+  }
+  let allOk = true;
+  let entries;
+  try {
+    entries = readdirSync(srcDir);
+  } catch {
+    return false;
+  }
+  for (const f of entries) {
+    const srcPath = join(srcDir, f);
+    const destPath = join(destDir, f);
+    let st;
+    try {
+      st = statSync(srcPath);
+    } catch {
+      // 断链符号链接 / 无权限 / readdir 与 stat 之间的竞态删除
+      allOk = false;
+      continue;
+    }
+    if (st.isDirectory()) {
+      if (!copyDirRecursive(srcPath, destPath)) allOk = false;
+    } else if (st.isFile()) {
+      try {
+        copyFileSync(srcPath, destPath);
+      } catch {
+        allOk = false;
+      }
+    }
+  }
+  return allOk;
+}
+
+/**
+ * 拷贝阶段对应的校验脚本到项目根的 references/ 目录
+ *
+ * 清单**不是手写的**：从该阶段的入口校验脚本出发，递归收集它的
+ * 同目录 import 闭包（graph-utils / content-quality / skeleton-quota …）。
+ *
+ * 手写清单的坑：清单里的文件都拷成功了，部署阶段看不出问题，
+ * 但少拷一个被 import 的文件，插件跑起来时校验脚本直接
+ * ERR_MODULE_NOT_FOUND（真实踩过：抽出 skeleton-quota.js 后
+ * 骨架阶段报 "references/skeleton-quota.js is missing"）。
+ */
+function copyPhaseScripts(projectRoot, phase) {
+  const PROJECT_REFERENCES_DIR = join(projectRoot, 'references');
+  const PLUGIN_SCRIPTS_DIR = join(__dirname, 'scripts');
+
+  // 该阶段不需要校验脚本（analyze / wiki）→ 无事可做，不算失败
+  const manifest = phaseScriptFiles(
+    phase,
+    PLUGIN_SCRIPTS_DIR,
+    join(__dirname, 'prompts'),
+    join(__dirname, 'references')
+  );
+  if (!manifest) return true;
+
+  // import 闭包里引了但磁盘上找不到的文件：这种清单不可能跑通，
+  // 直接判失败，别等运行时才炸。
+  if (manifest.missing.length) {
+    console.error(
+      `[fancy-story-builder] 阶段 ${phase} 的校验脚本依赖缺失：${manifest.missing.join('、')}`
+    );
+    return false;
+  }
+
+  // 确保 references 目录存在
+  if (!existsSync(PROJECT_REFERENCES_DIR)) {
+    try {
+      mkdirSync(PROJECT_REFERENCES_DIR, { recursive: true });
+    } catch {
+      return false;
+    }
+  }
+
+  let allOk = true;
+  for (const scriptFile of manifest.files) {
+    const src = join(PLUGIN_SCRIPTS_DIR, scriptFile);
+    if (!existsSync(src)) {
+      allOk = false;
+      continue;
+    }
+    const dest = join(PROJECT_REFERENCES_DIR, scriptFile);
+    try {
+      copyFileSync(src, dest);
+    } catch {
+      allOk = false;
+    }
+  }
+
+  return allOk;
+}
+
+/**
+ * 拷贝阶段对应的模板文件到项目根的 模板/ 目录
+ *
+ * 新版设计：templates/ 下含分类子目录（骨架/血肉/节奏/），每个子目录含阶段模板。
+ * 每个阶段拷贝对应分类目录的所有模板到项目的 模板/<分类>/。
+ */
+function copyPhaseTemplates(projectRoot, phase) {
+  const PLUGIN_TEMPLATES_DIR = join(__dirname, 'templates');
+  const PROJECT_TEMPLATES_DIR = join(projectRoot, '模板');
+
+  // 各阶段对应的模板分类目录
+  const PHASE_TEMPLATE_DIRS = {
+    skeleton: '骨架',
+    flesh: '血肉',
+    rhythm: '节奏'
+  };
+
+  const templateSubDir = PHASE_TEMPLATE_DIRS[phase];
+  // 该阶段不需要模板（writing / analyze / wiki）→ 无事可做，不算失败
+  if (!templateSubDir) return true;
+
+  const srcDir = join(PLUGIN_TEMPLATES_DIR, templateSubDir);
+  const destDir = join(PROJECT_TEMPLATES_DIR, templateSubDir);
+
+  if (!existsSync(srcDir)) return false;
+
+  // 确保项目模板分类目录存在
+  if (!existsSync(destDir)) {
+    try {
+      mkdirSync(destDir, { recursive: true });
+    } catch {
+      return false;
+    }
+  }
+
+  return copyDirRecursive(srcDir, destDir);
+}
+
+/**
+ * 把 schema-setting.md / purpose-template.md 拷进"设定"目录。
+ *
+ * "设定"目录本身**由 llm-wiki 创建**，不由插件创建。理由（llm-wiki 源码核实）：
+ *   - commands::project::create_project_impl 只在目录**不存在**时才会建
+ *     raw/sources、raw/assets，并写 schema.md、wiki/index.md、wiki/log.md；
+ *   - 目录若被抢先创建，handle_create_project 会走"目录已存在"分支，
+ *     以上全部不建 —— 项目就残缺了。
+ * 所以插件在调用 /projects/create 之前绝不能自己 mkdir 设定/。
+ *
+ * 本函数只做两件事：
+ *   1. 确保 设定/raw/sources 存在（这是三个阶段产物的落点；
+ *      llm-wiki 走"目录已存在"分支时不会建它）；
+ *   2. 拷 schema.md / purpose.md（覆盖 llm-wiki 写的默认 schema.md，这是有意的）。
+ *
+ * @param {string} projectRoot 项目根目录
+ * @param {{includePurpose?: boolean}} [opts] includePurpose=false 时只拷 schema.md
+ *        （wiki 阶段只认 schema.md，不需要 purpose.md）
+ * @returns {{ ok: boolean, reason: string|null, detail: string|null }}
+ */
+async function copySchemaToProject(projectRoot, opts = {}) {
+  const includePurpose = opts.includePurpose !== false;
+  const pluginDir = __dirname;
+  const schemaSrc = join(pluginDir, 'schema-setting.md');
+  const purposeSrc = join(pluginDir, 'purpose-template.md');
+
+  const schemaDestDir = join(projectRoot, '设定');
+  const schemaDest = join(schemaDestDir, 'schema.md');
+  const purposeDest = join(schemaDestDir, 'purpose.md');
+  const sourcesDir = join(schemaDestDir, 'raw', 'sources');
+
+  // "设定"目录应当已由 llm-wiki 建好。缺失说明 llm-wiki 那一步没走通，
+  // 此时插件自己补建会让 llm-wiki 的项目结构残缺，所以只报告不补建。
+  if (!existsSync(schemaDestDir)) {
+    return {
+      ok: false, reason: 'setting_dir_missing',
+      detail: '设定目录不存在（应由 llm-wiki 的 /projects/create 创建）'
+    };
+  }
+
+  // 产物落点必须存在
+  try {
+    mkdirSync(sourcesDir, { recursive: true });
+  } catch (e) {
+    return { ok: false, reason: 'mkdir_failed', detail: '创建 ' + sourcesDir + ' 失败：' + e.message };
+  }
+
+  // 拷贝 schema-setting.md
+  let copied = 0;
+  if (existsSync(schemaSrc)) {
+    try {
+      copyFileSync(schemaSrc, schemaDest);
+      copied++;
+    } catch (e) {
+      return { ok: false, reason: 'copy_failed', detail: '拷贝 schema.md 失败：' + e.message };
+    }
+  }
+
+  // 拷贝 purpose-template.md 并重命名为 purpose.md
+  if (includePurpose && existsSync(purposeSrc)) {
+    try {
+      copyFileSync(purposeSrc, purposeDest);
+      copied++;
+    } catch (e) {
+      return { ok: false, reason: 'copy_failed', detail: '拷贝 purpose.md 失败：' + e.message };
+    }
+  }
+
+  return { ok: true, reason: null, detail: copied > 0 ? null : '插件目录下没有 schema-setting.md / purpose-template.md' };
+}
+
+function readNovelTopic(projectRoot) {
+  const topicPath = join(projectRoot, '_novel_topic.json');
+  if (!existsSync(topicPath)) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(topicPath, 'utf-8'));
+  } catch (e) {
+    // 解析失败与"文件不存在"要能区分：前者是文件损坏，错误提示不能误导成"未选题"
+    console.error(`[fancy-story-builder] _novel_topic.json 解析失败: ${e.message}`);
+    return null;
+  }
+  // 必须是对象；数组/字符串/数字会让下游的字段解构拿到 undefined
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    console.error('[fancy-story-builder] _novel_topic.json 顶层必须是对象');
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * 调用 llm_wiki API
+ */
+async function callLlmWikiApi(baseUrl, token, path, method = 'POST', body = null, signal = null) {
+  const url = `${baseUrl}${path}`;
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`,
+  };
+  const options = { method, headers };
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+  // 超时保护：否则 llm-wiki 挂起时命令会一直挂到 Node fetch 的默认超时。
+  const timeout = AbortSignal.timeout(LLM_WIKI_TIMEOUT_MS);
+  options.signal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const response = await fetch(url, options);
+  // 响应体可能不是 JSON（例如网关返回 HTML 错误页）——
+  // 直接 response.json() 会抛 SyntaxError，把真正的 HTTP 状态盖掉，
+  // 用户看到的是 "Unexpected token '<'" 这种看不懂的东西。
+  const data = await readJsonSafe(response);
+  return { status: response.status, data };
+}
+
+/**
+ * 确保 setup_id 存在。
+ * 返回 { id, reused }：reused=true 表示从 llm-wiki 本地缓存复用（提示用户）
+ */
+function readExistingProjectId(projectRoot) {
+  const cachePaths = [
+    join(projectRoot, '设定', '.llm-wiki', 'project.json'),
+    join(projectRoot, '.llm-wiki', 'project.json')
+  ];
+  for (const p of cachePaths) {
+    if (existsSync(p)) {
+      try {
+        const data = JSON.parse(readFileSync(p, 'utf-8'));
+        if (data && typeof data.id === 'string' && data.id.length > 0) {
+          return data.id;
+        }
+      } catch { /* ignore */ }
+    }
+  }
+  return '';
+}
+
+/**
+ * 确保"设定"目录在 llm-wiki 侧是一个真实存在的项目。返回 { id, reused, source, reason, detail }：
+ * - id: setup_id；空字符串表示拿不到
+ * - reused: true 表示复用了已有的 id
+ * - source: 'cache'（llm-wiki 写的 设定/.llm-wiki/project.json）/ 'created'（本次新建）
+ * - reason/detail: 拿不到时的可诊断分类与具体原因
+ *
+ * 为什么这一步对四个阶段都是硬前提（骨架/血肉/节奏/写作）：
+ *   "设定"目录必须被 llm-wiki 登记成项目，llm-wiki 侧才认它。
+ *   核实依据（llm-wiki 源码 api_server.rs）：
+ *     - handle_create_project 会写 <root>/.llm-wiki/project.json（存 id）
+ *       并调 upsert_project_in_registry 登记进 app-state.json 的 projectRegistry；
+ *     - resolve_project → load_projects **只从 projectRegistry 枚举项目**，
+ *       没登记过的目录一律 "Unknown project"。
+ *   而三个阶段的全部产物都会被 llm-wiki ingest 纳管（实测对照项目：
+ *   骨架 7 个 + 血肉 13 个 + 节奏 55 个文件全部进了 ingest-cache）。
+ *   所以设定项目没建成 → 产物进不了 llm-wiki 知识库 → 后续 wiki / analyze 必然失败。
+ *   这种情况下"降级继续"是假成功，不做。
+ *
+ * 权威判据是 llm-wiki 自己写的 设定/.llm-wiki/project.json：
+ *   它存在 = llm-wiki 确实把这个目录建成了项目（且 id 与 llm-wiki 内部一致）。
+ *   .fancy-deployed 里的 setup_id 只是副本，可能指向已被删除/从未建成的项目
+ *   （实测用户项目 tt3 就是这样：setup_id 有，设定/ 目录整个不存在）。
+ *
+ * 本函数不抛异常：失败时返回可诊断的 reason/detail，由调用方报给用户。
+ */
+/**
+ * 确保 llm-wiki 里有"设定"项目（返回 setup_id）。
+ *
+ * 导出给 fancy-import 用：导入阶段也要往 `设定/raw/sources/` 里写产物，
+ * 那个目录必须先是 llm-wiki 的项目，产物才会被 ingest 纳管。
+ * 各写一份的话，llm-wiki 的建项目流程（"目录不存在时才建"）改一处就会漏一处。
+ */
+export async function ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal = null) {
+  // 1) llm-wiki 自己写的 project.json —— 权威判据
+  const cachedId = readExistingProjectId(projectRoot);
+  if (cachedId) {
+    // 与 .fancy-deployed 的记录保持一致（以 llm-wiki 的为准）
+    const storedId = deployedConfig && typeof deployedConfig.setup_id === 'string' ? deployedConfig.setup_id.trim() : '';
+    if (cachedId !== storedId) {
+      updateDeployedField(projectRoot, 'setup_id', cachedId);
+    }
+    return { id: cachedId, reused: true, source: 'cache', reason: null, detail: null };
+  }
+
+  // 2) 还没有 project.json —— 让 llm-wiki 建项目。
+  //    注意：调用前**不要**自己先建 设定/ 目录。
+  //    llm-wiki 的 create_project_impl 只在目录不存在时才会建
+  //    raw/sources、raw/assets 并写 wiki/index.md、wiki/log.md；
+  //    目录若已被抢先创建，它会走"目录已存在"分支，以上全部不建。
+  try {
+    const result = await callLlmWikiApi(
+      llmWikiUrl,
+      llmWikiToken,
+      '/projects/create',
+      'POST',
+      {
+        name: '设定',
+        path: projectRoot,
+      },
+      signal
+    );
+
+    if (result.status === 401 || result.status === 403) {
+      return {
+        id: '', reused: false, source: null, reason: 'unauthorized',
+        detail: 'llm-wiki 拒绝了请求（HTTP ' + result.status + '）：服务端没有配置 API token，或本项目 .fancy-deployed 里的 llm_wiki_token 与它不一致'
+      };
+    }
+
+    if (result.status >= 400) {
+      const msg = (result.data && (result.data.error || result.data.message)) || ('HTTP ' + result.status);
+      return { id: '', reused: false, source: null, reason: 'api_error', detail: String(msg) };
+    }
+
+    if (result.data && result.data.error) {
+      return { id: '', reused: false, source: null, reason: 'api_error', detail: String(result.data.error) };
+    }
+
+    if (result.data && result.data.ok === true && result.data.project && result.data.project.id) {
+      const setupId = result.data.project.id;
+      updateDeployedField(projectRoot, 'setup_id', setupId);
+      return { id: setupId, reused: false, source: 'created', reason: null, detail: null };
+    }
+
+    return {
+      id: '', reused: false, source: null, reason: 'unexpected_response',
+      detail: 'llm-wiki 返回了非预期结构（缺少 ok / project.id）'
+    };
+  } catch (err) {
+    return {
+      id: '', reused: false, source: null, reason: 'network',
+      // Node 的 fetch 失败只抛一句 "fetch failed"，真正的原因在 err.cause 里。
+      // 不翻译的话用户既不知道是服务没启动、地址写错，还是超时。
+      detail: describeFetchError(err, LLM_WIKI_TIMEOUT_MS)
+    };
+  }
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-story-builder',
+    description: '📖 故事构建 ( usage: /fancy-story-builder skeleton | flesh | rhythm | writing | deslop | wiki | analyze )',
+    input: {
+      hint: '.',
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      const projectRoot = getProjectRoot(session);
+      if (!projectRoot) {
+        return notify(session, 'error', storyBuilder.notify({
+          type: 'no_project_root',
+          err: '无法确定项目目录（会话未提供 cwd）。请在项目目录下运行该命令。'
+        }));
+      }
+
+      // 1. 检查 .fancy-deployed
+      if (!existsSync(join(projectRoot, '.fancy-deployed'))) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'not_initialized' }));
+      }
+
+      // 2. 读取配置
+      const deployedRes = readDeployedConfig(projectRoot);
+      if (!deployedRes.ok) {
+        if (deployedRes.reason === 'not_found') {
+          return notify(session, 'error', storyBuilder.notify({ type: 'not_initialized' }));
+        }
+        return notify(session, 'error', storyBuilder.notify({
+          type: 'config_corrupt',
+          err: '.fancy-deployed 解析失败（' + deployedRes.reason + '）。请手工修复或删除该文件后重新运行 /fancy-bootstrap。'
+        }));
+      }
+      const deployedConfig = deployedRes.config;
+      if (!deployedConfig) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'not_initialized' }));
+      }
+
+      // 3. 检查 llm_wiki 配置
+      const llmWikiUrl = (deployedConfig.llm_wiki_url || '').replace(/\/$/, '');
+      const llmWikiToken = deployedConfig.llm_wiki_token || '';
+
+      if (!llmWikiUrl || !llmWikiToken) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'llm_wiki_not_configured' }));
+      }
+
+      // 4. 读取选题信息
+      const topicData = readNovelTopic(projectRoot);
+      if (!topicData) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'no_topic' }));
+      }
+
+      // 5. 解析子命令
+      const rawInput = (invocation.rawInput || '').trim().toLowerCase();
+      const subcommand = rawInput.split(/\s+/)[0];
+
+      if (!subcommand) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'no_subcommand' }));
+      }
+
+      // 5.1 校验子命令合法性：非法子命令不应该往项目目录里写文件
+      const VALID_SUBCOMMANDS = ['wiki', 'skeleton', 'flesh', 'rhythm', 'analyze', 'writing', 'deslop'];
+      if (!VALID_SUBCOMMANDS.includes(subcommand)) {
+        return notify(session, 'error', storyBuilder.notify({ type: 'no_subcommand' }));
+      }
+
+      // 6. 拷贝阶段对应的参考文件到项目根的 references/ 目录
+      //    三个拷贝函数的返回值必须检查：失败时模板/参考文件没部署，
+      //    但 prompt 仍会指示 LLM 去读这些不存在的文件，产出垃圾内容。
+      const refsOk = copyPhaseReferences(projectRoot, subcommand);
+      const scriptsOk = copyPhaseScripts(projectRoot, subcommand);
+      const tplOk = copyPhaseTemplates(projectRoot, subcommand);
+      if (!refsOk || !scriptsOk || !tplOk) {
+        const failed = [];
+        if (!refsOk) failed.push('references/');
+        if (!scriptsOk) failed.push('校验脚本');
+        if (!tplOk) failed.push('模板/');
+        console.error(`[fancy-story-builder] 部署失败：${failed.join('、')}`);
+        return notify(session, 'error', storyBuilder.notify({
+          type: 'deploy_failed',
+          err: '以下文件部署失败：' + failed.join('、') + '（请检查磁盘空间与目录权限）'
+        }));
+      }
+
+      // 9. 获取 wiki 参考（根据阶段筛选目录）
+      const wikiReferences = readWikiReferences(projectRoot, subcommand);
+
+      // 9. 分发到对应处理函数
+      switch (subcommand) {
+        case 'wiki':
+          return handleWiki(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken);
+
+        case 'skeleton':
+          return handleSkeleton(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences);
+
+        case 'flesh':
+          // --semantic：血肉产出后再跑一次 LLM 语义检查（对应 llm_wiki 的 runSemanticLint）
+          return handleFlesh(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences, {
+            semantic: /\s--semantic(\s|$)/.test(rawInput)
+          });
+
+        case 'rhythm':
+          return handleRhythm(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences);
+
+        case 'analyze':
+          return handleAnalyze(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences);
+
+        case 'writing':
+          return handleWriting(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences);
+
+        case 'deslop':
+          return handleDeslop(ctx, session, invocation, projectRoot, deployedConfig, topicData);
+
+        default:
+          return notify(session, 'error', storyBuilder.notify({ type: 'no_subcommand' }));
+      }
+    },
+  });
+}
+
+/**
+ * 处理骨架阶段
+ */
+/**
+ * 处理骨架阶段（插件驱动版）
+ *
+ * 骨架是第一个阶段，没有上游可读，但**内部有硬依赖**：
+ *
+ *   1. 实体写几条，由框架的 quota 决定（校验器逐类核对，QUOTA_MISMATCH）
+ *   2. 关系里填的 id，只能来自实体清单（SKELETON_REF_MISSING）
+ *   3. 层级里填的卷 id / 主线 id / 支线 id，分别来自框架与实体清单
+ *
+ * 所以骨架分三段驱动：
+ *   段一 框架   —— 整文件型（1 批），定 quota / volume_ratio / derivations
+ *   段二 实体   —— 12 个数组，每类条数按段一的 quota 写
+ *   段三 关系+层级 —— 关系与层级引用段二的 id；用**全量校验**判
+ *                  （引用完整性、图连通性、配额一致性都要跨文件才能查）
+ *
+ * 校验粒度：前两段用单文件校验（模板结构 / 枚举 / id 唯一 / derivations 完整性），
+ * 最后一段用全量 --all。
+ */
+async function handleSkeleton(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences) {
+  // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+  const benchmarkRefs = renderBenchmarkGuidance(projectRoot, 'skeleton');
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在（幂等调用）
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  // 说明文字要并入最终返回的消息：notify 的中间返回值会被丢弃，
+  // 单独发一条 info 用户根本看不到。
+  let setupNote = '';
+  if (!setupId) {
+    // "设定"目录必须先是 llm-wiki 里的项目，本阶段的产物才会被 ingest 纳管
+    // （实测：骨架 7 + 血肉 13 + 节奏 55 个文件全部进了 llm-wiki 的 ingest-cache）。
+    // 拿不到 setup_id = 设定项目没建成 → 继续跑只会产出不被纳管的半成品，
+    // 而且后续 wiki / analyze 阶段必然失败。必须硬失败。
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+  if (setupResult.reused) {
+    setupNote = storyBuilder.notify({ type: 'setup_id_reused', id: setupId, source: setupResult.source });
+  }
+
+  // 准备"设定"目录并拷贝 schema 文件。
+  // 拷失败必须**硬失败**：设定目录不存在时，后面的分片目录（设定/raw/sources/…）
+  // 会把"设定"目录自己建出来 —— 而这个目录本该由 llm-wiki 的 /projects/create 建，
+  // 插件抢建会让 llm-wiki 以为项目已存在，不再补 raw/assets、wiki/index.md，
+  // 项目就残缺了（llm-wiki 侧 ingest 会缺文件）。
+  const schemaCopy = await copySchemaToProject(projectRoot);
+  if (!schemaCopy.ok) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'schema_copy_failed',
+      detail: schemaCopy.detail
+    }));
+  }
+
+  const stageDir = join(projectRoot, '设定', 'raw', 'sources', '骨架');
+  const buildDir = join(stageDir, SKELETON_SHARD_DIR_NAME);
+  try {
+    mkdirSync(buildDir, { recursive: true });
+  } catch (e) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '建分片目录失败：' + e.message }));
+  }
+
+  const validator = join(projectRoot, 'references', 'skeleton-validate.js');
+  const projectTemplateDir = join(projectRoot, '模板', '骨架');
+  const pluginTemplateDir = join(__dirname, 'templates', '骨架');
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: 60 * 60 * 1000,
+    idleGraceMs: 60000,
+    signal,
+    // 重投场景里分片文件还在（不能删 —— 删了模型 write 会被 DSH 的版本守卫拦死），
+    // 完成判据必须看内容有没有变。
+    changed: shardContentChanged
+  });
+  const canWait = invocation && invocation.agent && typeof invocation.agent.status === 'string';
+  const progressNotes = [];
+
+  // 目标章节：数量公式的输入 T（骨架阶段没有上游快照，直接用选题）
+  const targetChapters = Number(topicData && topicData.target_chapters) || 0;
+
+  // 批次规划：**分段规划**，因为规划本身也有依赖：
+  //   实体批次的规模来自框架的 quota（段一产出后才有）
+  //   关系批次的 id 表来自实体清单（段二产出后才有）
+  // 所以只先规划框架那一段，后两段等上一段落盘后再规划。
+  const planBase = {
+    skeletonDir: stageDir,
+    templateDir: pluginTemplateDir,
+    buildDir: buildDir,
+    chapters: targetChapters,
+    maxBytes: SKELETON_BATCH_MAX_BYTES
+  };
+  const planA = planSkeletonBatches(Object.assign({}, planBase, { only: ['框架'] }));
+  if (!planA.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '骨架批次规划失败：' + planA.error }));
+  }
+
+  // 批次 key -> 所属文件
+  const fileByBatchKey = new Map();
+  const knownShards = [];
+  const rememberPlan = (plan) => {
+    for (const f of plan.files) {
+      for (const b of f.batches) {
+        fileByBatchKey.set(b.key, f);
+        knownShards.push(b.shard);
+      }
+    }
+  };
+  rememberPlan(planA);
+
+  // ---- 提示词构建（三段共用） ----
+  const buildBatchPrompt = (batch, attempt, failures) => buildSkeletonBatchPrompt({
+    batch: batch,
+    attempt: attempt,
+    failures: failures,
+    stageDir: stageDir,
+    topicData: topicData,
+    benchmarkRefs: benchmarkRefs
+  });
+
+  // ---- 驱动（三段共用同一会话，批次状态跨段保留） ----
+  const stageSession = createStageSession();
+  const driverCommon = {
+    session: stageSession,
+    buildPrompt: buildBatchPrompt,
+    sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+    waitIdle: async (files, before) => waitForTurn(files, before),
+    readShard: (batch) => readShardFile(batch.shardPath),
+    adoptShard: makeShardAdopter(buildDir, knownShards),
+    // 模型这轮没动分片时（NO_CHANGE），由**脚本**判这个分片是不是本来就对：
+    // 局部口径只判这一批涉及的数组，不查跨文件一致性。
+    validateBatch: async (batch) => runSkeletonValidatorPartial({
+      validator: validator,
+      input: batch.shardPath,
+      template: join(projectTemplateDir, batch.template),
+      fileType: batch.type,
+      upstream: stageDir,
+      arrays: batch.arrays || [],
+      projectRoot: projectRoot
+    }),
+    applyFile: async (file) => mergeFleshShards({
+      stageDir: stageDir,
+      buildDir: buildDir,
+      batches: file.batches
+    }),
+    attribute: (errors, layout) => attributeErrors(errors, layout, {
+      pathKeys: skeletonPathKey
+    }),
+    onProgress: (msg) => { progressNotes.push(msg); }
+  };
+
+  const phaseReports = [];
+  // planB / planC 要提到外层：批次统计要用它们
+  // （而且它们是**分段规划**出来的 —— 段二要等框架落盘，段三要等实体落盘）
+  let planB = null;
+  let planC = null;
+
+  /**
+   * 造一个"用分片把已定稿产物覆盖回去"的恢复器。
+   *
+   * 分片是真源（产物 = 分片合并出来的），所以拿分片覆盖磁盘上的产物，
+   * 模型的越权修改就自动失效了。
+   *
+   * @param {Array} plans 已定稿的阶段规划（每个含 files）
+   * @returns {() => Promise<string[]>} 返回"确实被改动过、已覆盖回去"的文件名
+   */
+  const makeSettledRestorer = (plans) => async () => {
+    const restored = [];
+    for (const plan of plans || []) {
+      for (const f of (plan && plan.files) || []) {
+        if (!f || !f.batches || !f.batches.length) continue;
+        const target = join(stageDir, f.file);
+        let before = null;
+        try {
+          before = existsSync(target) ? readFileSync(target, 'utf-8') : null;
+        } catch (e) {
+          before = null;
+        }
+        const r = await mergeFleshShards({
+          stageDir: stageDir,
+          buildDir: buildDir,
+          batches: f.batches,
+          allowMissing: false,
+          outPath: target
+        });
+        if (!r || r.ok !== true) continue;
+        let after = null;
+        try {
+          after = existsSync(target) ? readFileSync(target, 'utf-8') : null;
+        } catch (e) {
+          after = null;
+        }
+        if (before !== null && after !== null && before !== after) restored.push(f.file);
+      }
+    }
+    return restored;
+  };
+  let report = { ok: false, error: null, files: [], failedFiles: [], errors: [], warnings: [] };
+
+  try {
+    if (!canWait) {
+      report = {
+        ok: false,
+        error: '当前运行时没有暴露 agent，无法逐批派活骨架阶段（派活需要能等待每一轮结束）',
+        files: [],
+        failedFiles: [],
+        errors: [],
+        warnings: []
+      };
+    } else {
+      // ---- 段一：框架 ----
+      // 已定稿的文件（单文件校验已通过、之后没被改过）不派活重做：
+      // 直接沿用磁盘上的产物 —— 段二的批次规划要读它的 quota。
+      // tt5 实测（2026-10-25）：骨架一次要派 40+ 批，中途任何一次失败都会
+      // 让框架 + 实体这 13 个 turn 白烧额度重做一遍。
+      const settledFiles = readSkeletonSettledFiles(stageDir, { buildDir: buildDir });
+      let rA;
+      if (settledFiles.has('框架.json')) {
+        rA = skippedFilesReport(['框架.json']);
+        progressNotes.push('框架.json 已定稿（单文件校验已通过、之后未改动），本轮跳过重做');
+      } else {
+        rA = await runStageBatches(Object.assign({}, driverCommon, {
+          files: planA.files,
+          validateScope: 'stage',
+          validateStage: (files) => validateSkeletonFiles(files, {
+            validator: validator,
+            templateDir: projectTemplateDir,
+            stageDir: stageDir,
+            projectRoot: projectRoot
+          })
+        }));
+      }
+      phaseReports.push(rA);
+
+      // ---- 段二：实体（条数按段一的 quota 写；规划也要等段一落盘） ----
+      let rB = null;
+      if (phaseFileOk(rA, '框架.json')) {
+        planB = planSkeletonBatches(Object.assign({}, planBase, { only: ['实体'] }));
+        if (!planB.ok) {
+          rB = {
+            ok: false,
+            error: '实体批次规划失败：' + planB.error,
+            files: [],
+            failedFiles: ['实体.json'],
+            errors: [],
+            warnings: []
+          };
+        } else {
+          rememberPlan(planB);
+          if (settledFiles.has('实体.json')) {
+            rB = skippedFilesReport(['实体.json']);
+            progressNotes.push('实体.json 已定稿（单文件校验已通过、之后未改动），本轮跳过重做');
+          } else {
+            rB = await runStageBatches(Object.assign({}, driverCommon, {
+              files: planB.files,
+              // 框架.json 在这一段开始前已经 PASSED：模型越权改它就用分片覆盖回去
+              restoreSettled: makeSettledRestorer([planA]),
+              validateScope: 'stage',
+              validateStage: (files) => validateSkeletonFiles(files, {
+                validator: validator,
+                templateDir: projectTemplateDir,
+                stageDir: stageDir,
+                projectRoot: projectRoot
+              })
+            }));
+          }
+          phaseReports.push(rB);
+        }
+      }
+
+      // ---- 段三：关系 + 层级（全量校验；规划要等段二落盘） ----
+      let rC = null;
+      if (rB && phaseFileOk(rB, '实体.json')) {
+        planC = planSkeletonBatches(Object.assign({}, planBase, { only: ['关系', '层级'] }));
+        if (!planC.ok) {
+          rC = {
+            ok: false,
+            error: '关系与层级批次规划失败：' + planC.error,
+            files: [],
+            failedFiles: ['关系.json', '层级.json'],
+            errors: [],
+            warnings: []
+          };
+        } else {
+          rememberPlan(planC);
+          // 关系 / 层级分开定稿：已定稿的不派活，只跑还没定稿的那个。
+          const pendingFiles = planC.files.filter((f) => !settledFiles.has(f.file));
+          const settledHere = planC.files
+            .filter((f) => settledFiles.has(f.file))
+            .map((f) => f.file);
+          if (settledHere.length) {
+            progressNotes.push(settledHere.join('、') +
+              ' 已定稿（单文件校验已通过、之后未改动），本轮跳过重做');
+          }
+          if (!pendingFiles.length) {
+            // 全都定稿：不派活，但仍然要确认跨文件口径（--all）还成立。
+            const all = await runSkeletonValidatorAll({
+              validator: validator,
+              stageDir: stageDir,
+              templateDir: projectTemplateDir,
+              projectRoot: projectRoot
+            });
+            const allOk = all.status === 0;
+            rC = {
+              ok: allOk,
+              error: allOk ? null : '全量校验（--all）没通过',
+              files: settledHere.map((f) => ({ file: f, ok: allOk })),
+              failedFiles: allOk ? [] : settledHere.slice(),
+              batches: [],
+              errors: all.errors || [],
+              warnings: all.warnings || [],
+              unattributed: [],
+              infraErrors: [],
+              totalBatches: 0,
+              totalRounds: 0
+            };
+          } else {
+            rC = await runStageBatches(Object.assign({}, driverCommon, {
+              files: pendingFiles,
+              // 框架.json / 实体.json 在这一段开始前都已 PASSED：
+              // 模型越权改它们就用分片覆盖回去（tt5 实测：模型改了 框架.json 的 quota）
+              restoreSettled: makeSettledRestorer([planA, planB]),
+              validateScope: 'stage',
+              // 中途校验：关系+层级段有 27+4=31 个批次（tt5 实测），
+              // 全写完才判一次的话，第 8 批写错要等 23 批都写完才发现。
+              // 每 8 批局部判一次（局部口径：只判已写完的数组，不误报"缺数组/图不连通"）。
+              checkpointEvery: SKELETON_CHECKPOINT_EVERY,
+              applyPartial: async (file) => mergeFleshShards({
+                stageDir: stageDir,
+                buildDir: buildDir,
+                batches: file.batches,
+                // 中途的半成品不能覆盖正式产物，也缺还没生成的分片
+                allowMissing: true,
+                outPath: join(stageDir, '.partial-' + file.file)
+              }),
+              validatePartial: async (file, part) => runSkeletonValidatorPartial({
+                validator: validator,
+                input: part.path,
+                template: join(projectTemplateDir, file.template),
+                fileType: file.type,
+                upstream: stageDir,
+                arrays: part.writtenArrays || [],
+                projectRoot: projectRoot
+              }),
+              // 跨文件口径（引用完整性 / 图连通性 / 配额一致性）只能全量判
+              validateStage: () => runSkeletonValidatorAll({
+                validator: validator,
+                stageDir: stageDir,
+                templateDir: projectTemplateDir,
+                projectRoot: projectRoot
+              })
+            }));
+            // 跳过的文件也要出现在段报告里（段与段之间靠它判依赖门禁）
+            if (settledHere.length) {
+              rC = Object.assign({}, rC, {
+                files: (rC.files || []).concat(settledHere.map((f) => ({ file: f, ok: true, skipped: true })))
+              });
+            }
+          }
+          phaseReports.push(rC);
+        }
+      }
+
+      report = mergePhaseReports(phaseReports);
+      // 清掉中途校验留下的半成品（点号开头，不会被 regenerateMd 渲染成 .md，
+      // 但留在产物目录里会让人以为那是产物的一部分）。
+      cleanupPartialFiles(stageDir);
+      if (!phaseFileOk(rA, '框架.json')) {
+        report.blocked = '框架没通过校验，实体的条数由框架的 quota 决定，本轮没有继续派活实体';
+      } else if (rB && !phaseFileOk(rB, '实体.json')) {
+        report.blocked = '实体没通过校验，关系与层级要引用实体清单里的 id，本轮没有继续派活关系与层级';
+      }
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg }));
+  }
+
+  // ---- 产出盘点 ----
+  const inspect = inspectSkeletonOutput(stageDir);
+  const status = readSkeletonStageStatus(stageDir);
+  const completionNote = buildSkeletonBatchNote({
+    report: report,
+    progressNotes: progressNotes,
+    plans: [planA, planB, planC].filter(Boolean)
+  });
+  const inspectNote = buildSkeletonCompletionNote(inspect, status);
+
+  const allPassed = report.ok && inspect.complete && status.allCheck === 'PASSED';
+  const payloadType = allPassed ? 'skeleton_complete' : 'skeleton_incomplete';
+
+  const parts = [setupNote, completionNote, inspectNote].filter(Boolean);
+  const extra = parts.join('\n\n');
+  return notify(session, 'success', storyBuilder.notify({ type: payloadType, phase: '骨架', extra }));
+}
+
+/**
+ * 骨架阶段的路径解析：quota.<字段> → 真正该改的批次。
+ *
+ * QUOTA_MISMATCH 的 path 形如 "quota.character_counts.protagonist"：
+ * 声明在框架里，但根因常在实体清单（少写了一个主角）。
+ * 按通用规则会归到框架批次，模型就会去改 quota —— 下一轮还是同样的错。
+ * 这里把它导向对应的实体数组批次。
+ *
+ * 两个特例：
+ *   quota.volume_count        → 层级.json 的 volumes（卷数对不上就补卷）
+ *   quota.faction_relation_count → 关系.json 的 faction_relations（补双向行）
+ */
+export function skeletonPathKey(p) {
+  if (typeof p !== 'string' || p.indexOf('quota.') !== 0) return null;
+  const rest = p.slice('quota.'.length);
+  if (rest === 'volume_count') return 'volumes';
+  if (rest === 'faction_relation_count') return 'faction_relations';
+  return quotaPathToArray(rest);
+}
+
+/**
+ * 骨架单批的提示词组装（驱动层与测试共用同一条路径）。
+ *
+ * 两块额外上下文都是**派活信息**，不属于产物契约：
+ *   idTables    —— 关系批次能引用的实体 id 表（从段二的实体清单读）
+ *   extraContext —— 框架批次算数量要用的 T（数量公式的输入）
+ *
+ * 注意框架批次的判据是 batch.type，不是 batch.groupKey：
+ * 框架那一批是整文件型（wholeObject），groupKey 是 null。
+ *
+ * @param {Object} opts
+ * @param {Object} opts.batch        批次描述
+ * @param {number} [opts.attempt]    第几次尝试
+ * @param {Array}  [opts.failures]   上一轮校验判出来的错误
+ * @param {string} opts.stageDir     骨架目录（绝对路径，读实体清单用）
+ * @param {Object} [opts.topicData]  选题数据（提供 T / 目标字数）
+ * @returns {string} 提示词全文
+ */
+export function buildSkeletonBatchPrompt(opts) {
+  const o = opts || {};
+  const batch = o.batch || {};
+  const topicData = o.topicData || {};
+  const attempt = o.attempt || 1;
+
+  let idTables = null;
+  let extraContext = null;
+
+  if (batch.refs && batch.refs.length) {
+    idTables = buildSkeletonIdTables(batch.refs, o.stageDir);
+  }
+  if (batch.type === '框架') {
+    // 框架那一批要把 T 摆出来（数量公式的输入）
+    extraContext = [
+      '目标章节 T = ' + (Number(topicData.target_chapters) || 0),
+      '目标字数 = ' + (topicData.target_words || '（任务输入里没有）'),
+      '数量公式读 references/formulas-skeleton.json，按 6.3 的拓扑顺序算区间。'
+    ];
+  }
+
+  return storyBuilder.generateSkeletonBatchPrompt({
+    batch: batch,
+    attempt: attempt,
+    failures: o.failures,
+    idTables: idTables,
+    extraContext: extraContext,
+    stageDir: o.stageDirRel || '设定/raw/sources/骨架',
+    buildDir: o.buildDirRel || ('设定/raw/sources/骨架/' + SKELETON_SHARD_DIR_NAME),
+    topicData: topicData
+  });
+}
+
+/**
+ * 渲染"可引用的 id 表"（关系批次用）。
+ *
+ * 模型填关系时要引用别的实体的 id；不给表它就凭空编，
+ * 编出来的 id 一个都不存在（SKELETON_REF_MISSING）。
+ */
+function buildSkeletonIdTables(refs, stageDir) {
+  const entities = readJsonFileSafe(join(stageDir, '实体.json'));
+  if (!entities || typeof entities !== 'object') return null;
+  const lines = [];
+  for (const key of refs || []) {
+    const list = Array.isArray(entities[key]) ? entities[key] : [];
+    if (!list.length) continue;
+    lines.push('### ' + key + '（' + list.length + ' 个）');
+    for (const e of list) {
+      const tag = e.type || e.category || e.scale || e.level || '';
+      lines.push('- ' + e.id + ' ' + e.name + (tag ? '（' + tag + '）' : ''));
+    }
+    lines.push('');
+  }
+  return lines.length ? lines : null;
+}
+
+/**
+ * 逐个文件跑骨架校验器的单文件模式，汇总成阶段级结果。
+ */
+async function validateSkeletonFiles(files, opts) {
+  const errors = [];
+  const warnings = [];
+  const fileStatus = {};
+  let status = 0;
+  for (const file of files || []) {
+    const r = await runSkeletonValidator({
+      validator: opts.validator,
+      input: join(opts.stageDir, file.file),
+      template: join(opts.templateDir, file.template),
+      fileType: file.type,
+      projectRoot: opts.projectRoot
+    });
+    for (const e of r.errors || []) errors.push(e);
+    for (const w of r.warnings || []) warnings.push(w);
+    fileStatus[file.file] = r.status;
+    if (r.status !== 0) {
+      status = Math.max(status, r.status === 2 ? 2 : 1);
+    }
+  }
+  return { status: status, errors: errors, warnings: warnings, fileStatus: fileStatus };
+}
+
+/**
+ * 调 skeleton-validate.js 的单文件模式（判定权在脚本，插件只读结果）。
+ */
+export async function runSkeletonValidator(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--input=' + opts.input,
+      '--template=' + opts.template,
+      '--file=' + opts.fileType
+    ],
+    timeout: 120000,
+    projectRoot: opts.projectRoot,
+    label: opts.fileType,
+    crashMessage: '校验脚本异常',
+    invalidMessage: '校验脚本输出'
+  });
+}
+
+/**
+ * 调 skeleton-validate.js 的全量模式（--all）。
+ */
+export async function runSkeletonValidatorAll(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--stage-dir=' + opts.stageDir,
+      '--template-dir=' + opts.templateDir,
+      '--all'
+    ],
+    timeout: 300000,
+    projectRoot: opts.projectRoot,
+    label: 'ALL',
+    crashMessage: '全量校验脚本异常',
+    invalidMessage: '全量校验输出'
+  });
+}
+
+/**
+ * 调 skeleton-validate.js 的**局部模式**（--arrays）。
+ *
+ * 中途校验用：文件还没写完，全量校验会误报（缺数组 → REQUIRED、图还不全 → G_ISOLATED），
+ * 所以只判指定数组上当场可判的错（模板子树 / 引用完整性 / 重复 / 自环 / 对称性 / 行数对账）。
+ */
+export async function runSkeletonValidatorPartial(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--input=' + opts.input,
+      '--template=' + opts.template,
+      '--file=' + opts.fileType,
+      '--upstream=' + opts.upstream,
+      '--arrays=' + (opts.arrays || []).join(',')
+    ],
+    timeout: 120000,
+    projectRoot: opts.projectRoot,
+    label: opts.fileType + '(局部)',
+    crashMessage: '局部校验脚本异常',
+    invalidMessage: '局部校验输出'
+  });
+}
+
+/**
+ * 骨架阶段结论：把"派了多少批、哪些文件没过、错在哪"讲清楚。
+ */
+function buildSkeletonBatchNote(opts) {
+  const o = opts || {};
+  const report = o.report || {};
+  const plans = o.plans || [];
+  const lines = [];
+
+  const totalKeys = new Set();
+  for (const p of plans) {
+    for (const b of (p.batches || [])) totalKeys.add(b.key);
+  }
+  const okKeys = new Set();
+  for (const b of (report.batches || [])) {
+    if (b.ok) okKeys.add(b.key);
+  }
+
+  if (report.error) {
+    lines.push('❌ 骨架阶段未完成：' + report.error);
+  } else if (report.ok) {
+    lines.push('✅ 骨架阶段逐批派活完成：' + okKeys.size + '/' + totalKeys.size + ' 批通过校验。');
+  } else {
+    lines.push('❌ 骨架阶段未完成：' + ((report.failedFiles || []).join('、') || '有批次没通过校验') + '。');
+    lines.push('（已通过 ' + okKeys.size + '/' + totalKeys.size + ' 批）');
+  }
+
+  if (report.blocked) {
+    lines.push('');
+    lines.push('⛔ ' + report.blocked);
+  }
+
+  const errs = report.errors || [];
+  if (errs.length) {
+    lines.push('');
+    lines.push('**校验错误（' + errs.length + ' 条）**');
+    for (const e of errs.slice(0, 15)) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || '') + (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    if (errs.length > 15) lines.push('- ……还有 ' + (errs.length - 15) + ' 条');
+  }
+
+  // 脚本/环境问题单独成段：它们没有重投给模型，混在错误列表里会误导
+  for (const l of renderInfraBlock(report.infraErrors)) lines.push(l);
+
+  const un = report.unattributed || [];
+  if (un.length) {
+    lines.push('');
+    lines.push('**归因不到具体批次的错误（' + un.length + ' 条，重投时不会自动修）**');
+    for (const e of un.slice(0, 8)) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || ''));
+    }
+    if (un.length > 8) lines.push('- ……还有 ' + (un.length - 8) + ' 条');
+  }
+
+  const notes = o.progressNotes || [];
+  if (notes.length) {
+    lines.push('');
+    lines.push('进度（共 ' + notes.length + ' 条）：' + notes.slice(-3).join('；'));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 处理血肉阶段
+ */
+async function handleFlesh(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences, opts) {
+  // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+  const benchmarkRefs = renderBenchmarkGuidance(projectRoot, 'flesh');
+  const options = opts || {};
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在（幂等调用）
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  // 说明文字要并入最终返回的消息：notify 的中间返回值会被丢弃，
+  // 单独发一条 info 用户根本看不到。
+  let setupNote = '';
+  if (!setupId) {
+    // "设定"目录必须先是 llm-wiki 里的项目，本阶段的产物才会被 ingest 纳管
+    // （实测：骨架 7 + 血肉 13 + 节奏 55 个文件全部进了 llm-wiki 的 ingest-cache）。
+    // 拿不到 setup_id = 设定项目没建成 → 继续跑只会产出不被纳管的半成品，
+    // 而且后续 wiki / analyze 阶段必然失败。必须硬失败。
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+  if (setupResult.reused) {
+    setupNote = storyBuilder.notify({ type: 'setup_id_reused', id: setupId, source: setupResult.source });
+  }
+
+  // 准备"设定"目录并拷贝 schema 文件。
+  // 拷失败必须**硬失败**：设定目录不存在时，后面的分片目录（设定/raw/sources/…）
+  // 会把"设定"目录自己建出来 —— 而这个目录本该由 llm-wiki 的 /projects/create 建，
+  // 插件抢建会让 llm-wiki 以为项目已存在，不再补 raw/assets、wiki/index.md，
+  // 项目就残缺了（llm-wiki 侧 ingest 会缺文件）。
+  const schemaCopy = await copySchemaToProject(projectRoot);
+  if (!schemaCopy.ok) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'schema_copy_failed',
+      detail: schemaCopy.detail
+    }));
+  }
+
+  // 骨架目录：任务输入快照与 id+name 摘要都从这儿取
+  const skeletonDir = join(projectRoot, '设定', 'raw', 'sources', '骨架');
+
+  // 任务输入快照：读骨架阶段的 框架.json（input_snapshot + capacity）。
+  // 骨架阶段已经把这次选题的完整输入固化成了可校验的快照，血肉阶段直接用它，
+  // 比在提示词里另拼一份（过去只有书名/题材/目标章节/一句话故事 4 项）更权威也更完整。
+  const inputSnapshot = readInputSnapshot(skeletonDir);
+
+  // 血肉目录 + 分片目录（分片是插件与 LLM 之间的中间态，不算最终产物）
+  const fleshStageDir = join(projectRoot, '设定', 'raw', 'sources', '血肉');
+  const buildDir = join(fleshStageDir, SHARD_DIR_NAME);
+
+  const canWait = invocation && invocation.agent && typeof invocation.agent.status === 'string';
+
+  // ---- 批次规划（先算出要写哪些批，再开始派活） ----
+  const plan = planFleshBatches({
+    skeletonDir: skeletonDir,
+    templateDir: join(__dirname, 'templates', '血肉'),
+    buildDir: buildDir,
+    maxBytes: FLESH_BATCH_MAX_BYTES
+  });
+  if (!plan.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '血肉批次规划失败：' + plan.error }));
+  }
+
+  // 分片目录：模型写分片、插件合并成最终产物
+  try {
+    mkdirSync(buildDir, { recursive: true });
+  } catch (e) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '建分片目录失败：' + e.message }));
+  }
+
+  // 骨架关系：批次提示词里要把"本批相关的骨架关系"原样给模型，
+  // 否则模型只能自己猜 relationship_type，REL_TYPE_MISMATCH 必炸。
+  const skeletonEntities = readJsonFileSafe(join(skeletonDir, '实体.json'));
+  const skeletonRelations = readJsonFileSafe(join(skeletonDir, '关系.json'));
+  const idToName = buildIdToName(skeletonEntities);
+
+  const validator = join(projectRoot, 'references', 'flesh-validate.js');
+  const projectTemplateDir = join(projectRoot, '模板', '血肉');
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: 60 * 60 * 1000,
+    idleGraceMs: 60000,
+    signal,
+    // 重投场景里分片文件还在（不能删 —— 删了模型 write 会被 DSH 的版本守卫拦死），
+    // 完成判据必须看内容有没有变。
+    changed: shardContentChanged
+  });
+  const knownShards = plan.batches.map((b) => b.shard);
+  const progressNotes = [];
+
+  // ---- 插件驱动：派活 -> 等 LLM -> 合并 -> 跑校验 -> 归因 -> 重投 ----
+  const driverOptions = {
+    files: plan.files,
+    buildPrompt: (batch, attempt, failures) => {
+      const ids = (batch.items || []).map((i) => i.id).filter(Boolean);
+      const rel = collectRelevantRelations(skeletonRelations, idToName, ids);
+      return storyBuilder.generateFleshBatchPrompt({
+        batch: batch,
+        attempt: attempt,
+        failures: failures,
+        relations: rel.lines,
+        stageDir: '设定/raw/sources/血肉',
+        buildDir: '设定/raw/sources/血肉/' + SHARD_DIR_NAME,
+        inputSnapshot: inputSnapshot,
+        topicData: topicData,
+        benchmarkRefs: benchmarkRefs
+      });
+    },
+    sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+    waitIdle: async (files, before) => waitForTurn(files, before),
+    readShard: (batch) => readShardFile(batch.shardPath),
+    adoptShard: makeShardAdopter(buildDir, knownShards),
+    applyFile: async (file) => mergeFleshShards({
+      stageDir: fleshStageDir,
+      buildDir: buildDir,
+      batches: file.batches
+    }),
+    validateFile: async (file) => runFleshValidator({
+      validator: validator,
+      input: join(fleshStageDir, file.file),
+      template: join(projectTemplateDir, file.template),
+      fileType: file.type,
+      upstream: skeletonDir,
+      projectRoot: projectRoot
+    }),
+    attribute: (errors, layout) => attributeErrors(errors, layout),
+    onProgress: (msg) => { progressNotes.push(msg); }
+  };
+
+  let report = { ok: false, error: null, files: [], failedFiles: [] };
+  try {
+    if (!canWait) {
+      // 运行时没暴露 agent：派活必须能等回合结束，没法等就只能明确报错，
+      // 不能装作驱动过了（2026-10 tt5 的教训就是"装作成功"最伤人）。
+      report = {
+        ok: false,
+        error: '当前运行时没有暴露 agent，无法逐批派活血肉阶段（派活需要能等待每一轮结束）',
+        files: [],
+        failedFiles: []
+      };
+    } else {
+      report = await runStageBatches(driverOptions);
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg }));
+  }
+
+  // ---- 全量校验（插件自己跑，判定权在脚本） ----
+  let allResult = null;
+  if (report.ok) {
+    allResult = await runFleshValidatorAll({
+      validator: validator,
+      stageDir: fleshStageDir,
+      templateDir: projectTemplateDir,
+      upstream: skeletonDir,
+      projectRoot: projectRoot
+    });
+  }
+
+  const inspect = inspectFleshOutput(fleshStageDir);
+  const status = readFleshStageStatus(fleshStageDir);
+  const completionNote = buildFleshBatchNote({
+    report: report,
+    allResult: allResult,
+    inspect: inspect,
+    status: status,
+    progressNotes: progressNotes,
+    plan: plan
+  });
+
+  const allPassed = !!(allResult && allResult.status === 0);
+  const payloadType = (report.ok && allPassed) ? 'flesh_complete' : 'flesh_incomplete';
+
+  // 语义检查（可选，--semantic）：确定性脚本查不了的内容矛盾，靠 LLM 查。
+  // 对照 llm_wiki 的 runSemanticLint：独立一轮、结果只提示不阻断。
+  let semanticNote = '';
+  if (options.semantic) {
+    semanticNote = await runSemanticLint({
+      invocation: invocation,
+      session: session,
+      projectRoot: projectRoot,
+      fleshStageDir: fleshStageDir,
+      skeletonDir: skeletonDir,
+      inspect: inspect,
+      signal: signal,
+      canWait: canWait
+    });
+  }
+
+  const parts = [setupNote, completionNote, semanticNote].filter(Boolean);
+  const extra = parts.join('\n\n');
+  return notify(session, 'success', storyBuilder.notify({ type: payloadType, phase: '血肉', extra }));
+}
+
+/**
+ * 读一个 JSON 文件，失败返回 null（不抛）。
+ */
+function readJsonFileSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 读一个分片文件，校验它是合法 JSON 且顶层是对象。
+ */
+function readShardFile(file) {
+  if (!file || !existsSync(file)) {
+    return { ok: false, error: '分片文件不存在：' + file };
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return { ok: false, error: '分片不是合法 JSON：' + e.message };
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, error: '分片顶层必须是对象' };
+  }
+  return { ok: true, data: data };
+}
+
+/**
+ * 跑一个校验脚本，把结果解析成结构化结论。
+ *
+ * 退出码语义（血肉 / 节奏 / 骨架 / 写作的校验器一致）：
+ *   0 = 通过    1 = 内容有错    2 = 脚本异常
+ *
+ * 关键：**不能只看退出码**。内容有错也是退出码 1，
+ * 而校验器已经把错误清单写在 stdout 的 JSON 里了 ——
+ * 必须先解析输出再判，否则错误清单会被整体丢掉。
+ * （早期版本把退出码非 0 当成"脚本异常"，每次校验失败都报 VALIDATOR_CRASH，
+ *  "哪里有问题、该怎么改"就完全看不到了。）
+ *
+ * 血肉与节奏的封装逻辑原本各写了一份，逐字节相同；
+ * 抽到这里以后，退出码语义只有一处定义。
+ */
+async function runValidatorScript(opts) {
+  const r = await spawnScript('node', [opts.validator].concat(opts.args || []), {
+    timeout: opts.timeout || 120000,
+    cwd: opts.projectRoot
+  });
+  let parsed = null;
+  try {
+    parsed = JSON.parse(r.output);
+  } catch (e) {
+    parsed = null;
+  }
+  if (parsed && typeof parsed.status === 'number') {
+    return { status: parsed.status, errors: parsed.errors || [], warnings: parsed.warnings || [] };
+  }
+  if (!r.ok) {
+    return {
+      status: 2,
+      errors: [{
+        code: 'VALIDATOR_CRASH',
+        path: opts.label || '',
+        message: (opts.crashMessage || '校验脚本异常') + '：' + (r.error || r.stderr || '未知错误'),
+        hint: null
+      }],
+      warnings: []
+    };
+  }
+  return {
+    status: 2,
+    errors: [{
+      code: 'VALIDATOR_OUTPUT_INVALID',
+      path: opts.label || '',
+      message: (opts.invalidMessage || '校验脚本输出') + '不是合法 JSON',
+      hint: null
+    }],
+    warnings: []
+  };
+}
+
+/**
+ * 调 flesh-validate.js 的单文件模式（判定权在脚本，插件只读结果）。
+ */
+export async function runFleshValidator(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--input=' + opts.input,
+      '--template=' + opts.template,
+      '--file=' + opts.fileType,
+      '--upstream=' + opts.upstream
+    ],
+    timeout: 120000,
+    projectRoot: opts.projectRoot,
+    label: opts.fileType,
+    crashMessage: '校验脚本异常',
+    invalidMessage: '校验脚本输出'
+  });
+}
+
+/**
+ * 调 flesh-validate.js 的全量模式（--all）。
+ */
+export async function runFleshValidatorAll(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--stage-dir=' + opts.stageDir,
+      '--template-dir=' + opts.templateDir,
+      '--upstream=' + opts.upstream,
+      '--all'
+    ],
+    timeout: 300000,
+    projectRoot: opts.projectRoot,
+    label: 'ALL',
+    crashMessage: '全量校验脚本异常',
+    invalidMessage: '全量校验输出'
+  });
+}
+
+/**
+ * 调 rhythm-validate.js 的单文件模式（判定权在脚本，插件只读结果）。
+ */
+export async function runRhythmValidator(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--input=' + opts.input,
+      '--template=' + opts.template,
+      '--file=' + opts.fileType,
+      '--upstream=' + opts.upstream
+    ],
+    timeout: 120000,
+    projectRoot: opts.projectRoot,
+    label: opts.fileType,
+    crashMessage: '校验脚本异常',
+    invalidMessage: '校验脚本输出'
+  });
+}
+
+/**
+ * 调 rhythm-validate.js 的全量模式（--all）。
+ */
+export async function runRhythmValidatorAll(opts) {
+  return runValidatorScript({
+    validator: opts.validator,
+    args: [
+      '--stage-dir=' + opts.stageDir,
+      '--template-dir=' + opts.templateDir,
+      '--upstream=' + opts.upstream,
+      '--all'
+    ],
+    timeout: 300000,
+    projectRoot: opts.projectRoot,
+    label: 'ALL',
+    crashMessage: '全量校验脚本异常',
+    invalidMessage: '全量校验输出'
+  });
+}
+
+/**
+ * 血肉阶段结论：把"派了多少批、哪些文件没过、错在哪"讲清楚。
+ *
+ * 2026-10 tt5 的教训：失败必须可见。插件驱动之后，
+ * "阶段开始"这种话只在真的开始时才能说，失败必须带清单。
+ */
+function buildFleshBatchNote(opts) {
+  const o = opts || {};
+  const report = o.report || {};
+  const allResult = o.allResult || null;
+  const plan = o.plan || { batches: [] };
+  const lines = [];
+
+  const totalBatches = (plan.batches || []).length;
+  const doneBatches = (report.files || []).reduce((n, f) => n + (f.batches || []).filter((b) => b.ok).length, 0);
+
+  if (report.error) {
+    lines.push('❌ 血肉阶段中断：' + report.error);
+  } else if (report.ok) {
+    lines.push('✅ 血肉阶段逐批派活完成：' + doneBatches + '/' + totalBatches + ' 批，8 个文件全部单检通过。');
+  } else {
+    lines.push('❌ 血肉阶段未完成：' + (report.failedFiles || []).join('、') + ' 没通过校验。');
+    lines.push('（已完成 ' + doneBatches + '/' + totalBatches + ' 批）');
+  }
+
+  for (const f of report.files || []) {
+    if (f.ok) continue;
+    lines.push('');
+    lines.push('**' + f.file + '**（' + f.rounds + ' 轮）');
+    const errs = f.errors || [];
+    if (!errs.length) {
+      lines.push('- ' + (f.error || '未通过校验，但没有拿到错误清单'));
+      continue;
+    }
+    for (const e of errs.slice(0, 12)) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || '') + (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    if (errs.length > 12) lines.push('- ……还有 ' + (errs.length - 12) + ' 条');
+  }
+
+  // 脚本/环境问题单独成段：它们没有重投给模型，混在错误列表里会误导
+  for (const l of renderInfraBlock(report.infraErrors)) lines.push(l);
+
+  if (allResult) {
+    lines.push('');
+    // 全量校验的错误也要分两类：脚本/环境问题不是产物内容的问题，
+    // 不能混在"未通过，N 条错误"里 —— 那会让人以为重跑一轮就能好。
+    const split = classifyIssues(allResult.errors || []);
+    if (allResult.status === 0) {
+      lines.push('全量校验（--all）：通过' + ((allResult.warnings || []).length ? '，warning ' + allResult.warnings.length + ' 条' : '') + '。');
+    } else if (allResult.status === 1) {
+      lines.push('全量校验（--all）：未通过，' + split.content.length + ' 条内容错误。');
+      for (const e of split.content.slice(0, 12)) {
+        lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || '') + (e.hint ? '（' + e.hint + '）' : ''));
+      }
+      if (split.content.length > 12) lines.push('- ……还有 ' + (split.content.length - 12) + ' 条');
+    } else {
+      lines.push('全量校验（--all）：脚本异常。');
+      for (const e of (allResult.errors || []).slice(0, 5)) {
+        lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.message || ''));
+      }
+    }
+    for (const l of renderInfraBlock(split.infra)) lines.push(l);
+  }
+
+  const notes = o.progressNotes || [];
+  if (notes.length) {
+    lines.push('');
+    lines.push('进度（共 ' + notes.length + ' 条）：' + notes.slice(-3).join('；'));
+  }
+
+  // 产出盘点：哪些文件压根没落地（批次生成失败时会缺）
+  const missing = (o.inspect && o.inspect.missing) || [];
+  if (missing.length) {
+    lines.push('');
+    lines.push('缺产物文件：' + missing.join('、'));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 血肉阶段的语义检查（LLM 层）
+ *
+ * 对照 llm_wiki 的 runSemanticLint（src/lib/lint.ts:205）：
+ *   - 独立一轮投递，不与血肉产出混在一起
+ *   - 结果只提示，不阻断阶段（血肉阶段的成败由确定性脚本说了算）
+ *   - LLM 的结果必须本地复核后才展示（semantic-lint.js reviewLintFindings）
+ *
+ * 为什么不直接在 flesh-validate.js 里做：校验器是纯 node 脚本，没有 LLM 通道。
+ */
+async function runSemanticLint(opts) {
+  const o = opts || {};
+  const fleshStageDir = o.fleshStageDir;
+  const skeletonDir = o.skeletonDir;
+
+  if (!o.canWait) {
+    return '语义检查未执行：当前运行时没有暴露 agent，无法等待 LLM 完成这一轮。';
+  }
+  if (!o.inspect || !o.inspect.complete) {
+    return '语义检查未执行：血肉 8 个 JSON 还没齐。先把血肉阶段补齐，再跑 `--semantic`。';
+  }
+
+  const fleshEntities = collectFleshEntities(fleshStageDir);
+  if (!fleshEntities.length) {
+    return '语义检查未执行：血肉目录里没读到实体。';
+  }
+  const skeletonRelations = collectSkeletonRelations(skeletonDir);
+  const keys = collectEntityKeys(skeletonDir);
+
+  const prompt = buildSemanticLintPrompt({
+    fleshEntities: fleshEntities,
+    skeletonRelations: skeletonRelations,
+    entityIds: keys.entityIds,
+    entityNames: keys.entityNames
+  });
+
+  const outFile = join(fleshStageDir, '.semantic-lint.txt');
+  // 旧结果先删掉：不然上一轮的残留会被当成本轮结果
+  try {
+    if (existsSync(outFile)) fs.unlinkSync(outFile);
+  } catch (e) {
+    // 删不掉就继续（下面的等待会超时并如实报告）
+  }
+
+  const fullPrompt = prompt + [
+    '',
+    '## 输出方式',
+    '',
+    '把上面的 LINT 块**原样**写进这个文件（不要加解释、不要用 markdown 代码块包住）：',
+    '',
+    outFile,
+    '',
+    '如果没有值得报的问题，就写一个空文件（0 字节）。'
+  ].join('\n');
+
+  let follow;
+  try {
+    follow = await llmFollowup(o.invocation, fullPrompt);
+  } catch (e) {
+    return '语义检查未执行：提示词投递失败（' + (e && e.message ? e.message : String(e)) + '）。';
+  }
+  if (!follow || follow.ok !== true) {
+    return '语义检查未执行：提示词投递失败（' + ((follow && follow.error) || '未知原因') + '）。';
+  }
+
+  const waitForTurn = makeWaitForTurn(o.invocation, { timeoutMs: 30 * 60 * 1000, idleGraceMs: 60000, signal: o.signal });
+  await waitForTurn([outFile]);
+
+  if (!existsSync(outFile)) {
+    return '语义检查未产出结果文件（' + outFile + '），这一轮没有拿到结论。';
+  }
+  let raw = '';
+  try {
+    raw = fs.readFileSync(outFile, 'utf-8');
+  } catch (e) {
+    return '语义检查结果文件读不出来：' + e.message;
+  }
+  if (!raw.trim()) {
+    return '语义检查：LLM 审校后没有发现值得报的问题。';
+  }
+
+  const findings = parseLintBlocks(raw);
+  if (!findings.length) {
+    return '语义检查：结果文件里没有可解析的 LINT 块（' + outFile + '），这一轮没有拿到结论。';
+  }
+  const reviewed = reviewLintFindings(findings, {
+    entityIds: keys.entityIds,
+    entityNames: keys.entityNames
+  });
+  return formatSemanticLintResult(reviewed.kept, reviewed.dropped, outFile);
+}
+
+/**
+ * 把语义检查结果渲染成给人看的说明。
+ *
+ * 分级（对应 llm_wiki 的 finding severity）：
+ *   error   —— 设定自相矛盾，必须改
+ *   warning —— 大概率要改
+ *   info    —— 可以斟酌
+ */
+function formatSemanticLintResult(kept, dropped, outFile) {
+  const lines = [];
+  const bySeverity = { error: [], warning: [], info: [] };
+  for (const f of kept) {
+    (bySeverity[f.severity] || bySeverity.warning).push(f);
+  }
+  lines.push('语义检查（LLM 审校）：' + kept.length + ' 条。');
+  lines.push('');
+  if (!kept.length) {
+    lines.push('- 复核后没有可信的发现。');
+  }
+  for (const sev of ['error', 'warning', 'info']) {
+    const list = bySeverity[sev];
+    if (!list.length) continue;
+    lines.push('### ' + (sev === 'error' ? '必须改' : sev === 'warning' ? '大概率要改' : '可以斟酌') + '（' + list.length + '）');
+    lines.push('');
+    for (const f of list) {
+      lines.push('- **' + f.title + '**（' + f.type + '）');
+      if (f.description) lines.push('  ' + f.description.replace(/\n+/g, ' '));
+      if (f.pages.length) lines.push('  涉及：' + f.pages.join('、'));
+    }
+    lines.push('');
+  }
+  if (dropped.length) {
+    lines.push('（另有 ' + dropped.length + ' 条经本地复核后丢弃：' + dropped.map((d) => d.reason).join('；') + '）');
+    lines.push('');
+  }
+  lines.push('原始结果：' + outFile);
+  lines.push('语义检查**不阻断**血肉阶段：上面这些是 LLM 的判断，要不要改、改哪条由你决定。');
+  return lines.join('\n');
+}
+
+/**
+ * 处理节奏阶段（插件驱动版）
+ *
+ * 与血肉阶段同构（插件当司机、脚本当裁判），但节奏多两条硬约束：
+ *
+ *   1. **生成顺序有依赖**：章节规划 → 节奏参数 → 时序映射 → 章节细纲。
+ *      时序映射受节奏参数约束（主线 key_nodes 数 = main_progress_chapter_count、
+ *      支线章数之和 = branch_chapter_total），先定参数再写映射才能一次填对。
+ *      所以节奏拆成三段驱动，每段生成完立刻合并，下一段的提示词才读得到。
+ *
+ *   2. **重点章集合是动态的**：章节细纲只写重点章，而重点章（大高潮章 / 结局章 /
+ *      钩子章）全都在时序映射里，必须等时序映射生成后才知道。
+ *      所以细纲那一段是"算完重点章再规划批次"，不能预先静态规划。
+ *
+ * 校验粒度：前两段用**单文件校验**（章节规划覆盖 1..T、时序映射引用完整性、
+ * 节奏参数可行性都能单文件判），最后一段用**全量校验 --all**
+ * （跨文件口径：主线/支线/参数三者吻合、结局覆盖、钩子下限）。
+ */
+async function handleRhythm(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences) {
+  // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+  const benchmarkRefs = renderBenchmarkGuidance(projectRoot, 'rhythm');
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在（幂等调用）
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  // 说明文字要并入最终返回的消息：notify 的中间返回值会被丢弃，
+  // 单独发一条 info 用户根本看不到。
+  let setupNote = '';
+  if (!setupId) {
+    // "设定"目录必须先是 llm-wiki 里的项目，本阶段的产物才会被 ingest 纳管
+    // （实测：骨架 7 + 血肉 13 + 节奏 55 个文件全部进了 llm-wiki 的 ingest-cache）。
+    // 拿不到 setup_id = 设定项目没建成 → 继续跑只会产出不被纳管的半成品，
+    // 而且后续 wiki / analyze 阶段必然失败。必须硬失败。
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+  if (setupResult.reused) {
+    setupNote = storyBuilder.notify({ type: 'setup_id_reused', id: setupId, source: setupResult.source });
+  }
+
+  // 准备"设定"目录并拷贝 schema 文件。
+  // 拷失败必须**硬失败**：设定目录不存在时，后面的分片目录（设定/raw/sources/…）
+  // 会把"设定"目录自己建出来 —— 而这个目录本该由 llm-wiki 的 /projects/create 建，
+  // 插件抢建会让 llm-wiki 以为项目已存在，不再补 raw/assets、wiki/index.md，
+  // 项目就残缺了（llm-wiki 侧 ingest 会缺文件）。
+  const schemaCopy = await copySchemaToProject(projectRoot);
+  if (!schemaCopy.ok) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'schema_copy_failed',
+      detail: schemaCopy.detail
+    }));
+  }
+
+  // 三个阶段目录
+  const skeletonDir = join(projectRoot, '设定', 'raw', 'sources', '骨架');
+  const fleshDir = join(projectRoot, '设定', 'raw', 'sources', '血肉');
+  const rhythmStageDir = join(projectRoot, '设定', 'raw', 'sources', '节奏');
+  // 分片目录（插件与 LLM 之间的中间态，不算最终产物）
+  const buildDir = join(rhythmStageDir, RHYTHM_SHARD_DIR_NAME);
+
+  // ---- 前置门禁：骨架 + 血肉两个上游都必须全量校验通过 ----
+  // 这个判定不能只写在提示词里（模型看不见 .stage-status.json 的真实状态，
+  // 上游没通过时照样会开写，产出全是废的）。
+  const gate = checkRhythmUpstreamGates(skeletonDir, fleshDir);
+  if (!gate.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'upstream_not_ready', err: gate.reason }));
+  }
+
+  // 分片目录：模型写分片、插件合并成最终产物
+  try {
+    mkdirSync(buildDir, { recursive: true });
+  } catch (e) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '建分片目录失败：' + e.message }));
+  }
+
+  // 任务输入快照：与血肉阶段同源（骨架 框架.json 的 input_snapshot + capacity）
+  const inputSnapshot = readInputSnapshot(skeletonDir);
+
+  // 骨架上下文：id->name（时序映射的 id 必须原样抄）、高潮类型、卷/幕/配额
+  const skeletonEntities = readJsonFileSafe(join(skeletonDir, '实体.json'));
+  const hierarchy = readJsonFileSafe(join(skeletonDir, '层级.json'));
+  const framework = readJsonFileSafe(join(skeletonDir, '框架.json'));
+  const idToName = buildIdToName(skeletonEntities);
+  const climaxTypes = buildClimaxTypes(skeletonEntities);
+  const skeletonOutline = buildRhythmSkeletonOutline({ hierarchy: hierarchy, framework: framework });
+
+  const validator = join(projectRoot, 'references', 'rhythm-validate.js');
+  const projectTemplateDir = join(projectRoot, '模板', '节奏');
+  const pluginTemplateDir = join(__dirname, 'templates', '节奏');
+  // 节奏校验器要求上游同时给骨架和血肉两个目录
+  const upstream = skeletonDir + ',' + fleshDir;
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: 60 * 60 * 1000,
+    idleGraceMs: 60000,
+    signal,
+    // 重投场景里分片文件还在（不能删 —— 删了模型 write 会被 DSH 的版本守卫拦死），
+    // 完成判据必须看内容有没有变。
+    changed: shardContentChanged
+  });
+  const canWait = invocation && invocation.agent && typeof invocation.agent.status === 'string';
+  const progressNotes = [];
+
+  // ---- 批次规划（三段） ----
+  const planBase = {
+    skeletonDir: skeletonDir,
+    templateDir: pluginTemplateDir,
+    buildDir: buildDir,
+    maxBytes: RHYTHM_BATCH_MAX_BYTES
+  };
+  // 第一段：章节规划 + 节奏参数（两者互相无依赖）
+  const planA = planRhythmBatches(Object.assign({}, planBase, { only: ['章节规划', '节奏参数'] }));
+  if (!planA.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '节奏批次规划失败：' + planA.error }));
+  }
+  // 第二段：时序映射（依赖第一段的节奏参数）
+  const planB = planRhythmBatches(Object.assign({}, planBase, { only: ['时序映射'] }));
+  if (!planB.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: '节奏批次规划失败：' + planB.error }));
+  }
+
+  // 批次 key -> 所属文件（提示词构建时要按批次找到所在文件，算上一批收尾）
+  const fileByBatchKey = new Map();
+  const knownShards = [];
+  for (const f of planA.files.concat(planB.files)) {
+    for (const b of f.batches) {
+      fileByBatchKey.set(b.key, f);
+      knownShards.push(b.shard);
+    }
+  }
+
+  // ---- 提示词构建（三段共用） ----
+  const buildBatchPrompt = (batch, attempt, failures) => {
+    const chapters = (batch.items || []).map((it) => it.ch).filter((c) => typeof c === 'number');
+    let chapterRefs = null;
+    let prevTail = null;
+    let extraContext = null;
+
+    if (batch.type === '章节规划') {
+      // 卷/幕/配额是受约束的枚举，模型看不到就只会瞎编
+      extraContext = skeletonOutline.lines;
+    } else if (batch.type === '时序映射') {
+      // 时序映射受节奏参数约束：必须让模型看到三个参数的真实值
+      extraContext = buildRhythmParamContext(rhythmStageDir);
+    } else if (batch.type === '章节细纲') {
+      // 本批章号在时序映射里的真源信息（钩子/高潮/结局/主线节点）
+      const timeline = readJsonFileSafe(join(rhythmStageDir, '时序映射.json'));
+      chapterRefs = buildRhythmChapterRefs({
+        timeline: timeline || {},
+        chapters: chapters,
+        idToName: idToName,
+        climaxTypes: climaxTypes
+      }).lines;
+      prevTail = buildRhythmPrevTailFor(fileByBatchKey.get(batch.key), batch, buildDir);
+    }
+
+    return storyBuilder.generateRhythmBatchPrompt({
+      batch: batch,
+      attempt: attempt,
+      failures: failures,
+      chapterRefs: chapterRefs,
+      prevTail: prevTail,
+      extraContext: extraContext,
+      stageDir: '设定/raw/sources/节奏',
+      buildDir: '设定/raw/sources/节奏/' + RHYTHM_SHARD_DIR_NAME,
+      inputSnapshot: inputSnapshot,
+      topicData: topicData,
+      benchmarkRefs: benchmarkRefs
+    });
+  };
+
+  // ---- 驱动（三段共用同一会话，批次状态跨段保留） ----
+  const stageSession = createStageSession();
+  const driverCommon = {
+    session: stageSession,
+    buildPrompt: buildBatchPrompt,
+    sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+    waitIdle: async (files, before) => waitForTurn(files, before),
+    readShard: (batch) => readShardFile(batch.shardPath),
+    adoptShard: makeShardAdopter(buildDir, knownShards),
+    applyFile: async (file) => mergeFleshShards({
+      stageDir: rhythmStageDir,
+      buildDir: buildDir,
+      batches: file.batches
+    }),
+    attribute: (errors, layout) => attributeErrors(errors, layout, { codeOwners: RHYTHM_CROSS_FILE_OWNERS }),
+    onProgress: (msg) => { progressNotes.push(msg); }
+  };
+
+  const phaseReports = [];
+  // 第三段的批次规划要提到外面：批次统计要用到它，
+  // 而且它的分片名也要在派活前登记进 knownShards。
+  let planC = null;
+  let keyChapters = null;
+  let report = { ok: false, error: null, files: [], failedFiles: [], errors: [], warnings: [] };
+
+  try {
+    if (!canWait) {
+      // 运行时没暴露 agent：派活必须能等回合结束，没法等就只能明确报错，
+      // 不能装作驱动过了（2026-10 tt5 的教训就是"装作成功"最伤人）。
+      report = {
+        ok: false,
+        error: '当前运行时没有暴露 agent，无法逐批派活节奏阶段（派活需要能等待每一轮结束）',
+        files: [],
+        failedFiles: [],
+        errors: [],
+        warnings: []
+      };
+    } else {
+      // ---- 第一段：章节规划 + 节奏参数（单文件校验） ----
+      const rA = await runStageBatches(Object.assign({}, driverCommon, {
+        files: planA.files,
+        validateScope: 'stage',
+        validateStage: (files) => validateRhythmFiles(files, {
+          validator: validator,
+          templateDir: projectTemplateDir,
+          stageDir: rhythmStageDir,
+          upstream: upstream,
+          projectRoot: projectRoot
+        })
+      }));
+      phaseReports.push(rA);
+
+      // 段间门禁只看**下游真正依赖**的文件：
+      //   时序映射依赖节奏参数 → 节奏参数没过就停（写出来的映射必然对不上）
+      //   章节细纲依赖时序映射 → 时序映射没过就停（重点章算不出来）
+      // 章节规划没过不拦下一段：它不影响时序映射，
+      // 而且最后一段的全量校验会把它的错误重新归因回它的批次再修。
+      let rB = null;
+      if (phaseFileOk(rA, '节奏参数.json')) {
+        rB = await runStageBatches(Object.assign({}, driverCommon, {
+          files: planB.files,
+          validateScope: 'stage',
+          validateStage: (files) => validateRhythmFiles(files, {
+            validator: validator,
+            templateDir: projectTemplateDir,
+            stageDir: rhythmStageDir,
+            upstream: upstream,
+            projectRoot: projectRoot
+          })
+        }));
+        phaseReports.push(rB);
+      }
+
+      // ---- 第三段：章节细纲（重点章动态规划 + 全量校验） ----
+      let rC = null;
+      if (rB && phaseFileOk(rB, '时序映射.json')) {
+        const chapterPlan = readJsonFileSafe(join(rhythmStageDir, '章节规划.json'));
+        const timeline = readJsonFileSafe(join(rhythmStageDir, '时序映射.json'));
+        keyChapters = computeKeyChapters({
+          chapters: (chapterPlan && chapterPlan.chapters) || [],
+          timeline: timeline || {},
+          climaxTypes: climaxTypes
+        });
+        if (!keyChapters.length) {
+          rC = {
+            ok: false,
+            error: '算不出重点章（章节规划或时序映射没产出有效章节号），章节细纲无法开工',
+            files: [],
+            failedFiles: ['章节细纲.json'],
+            errors: [],
+            warnings: []
+          };
+        } else {
+          planC = planRhythmBatches(Object.assign({}, planBase, {
+            only: ['章节细纲'],
+            keyChapters: keyChapters
+          }));
+          if (!planC.ok) {
+            rC = {
+              ok: false,
+              error: '章节细纲批次规划失败：' + planC.error,
+              files: [],
+              failedFiles: ['章节细纲.json'],
+              errors: [],
+              warnings: []
+            };
+          } else {
+            for (const f of planC.files) {
+              for (const b of f.batches) {
+                fileByBatchKey.set(b.key, f);
+                knownShards.push(b.shard);
+              }
+            }
+            rC = await runStageBatches(Object.assign({}, driverCommon, {
+              files: planC.files,
+              validateScope: 'stage',
+              // 最后一段只能全量判：跨文件口径的错误单文件查不出来
+              validateStage: () => runRhythmValidatorAll({
+                validator: validator,
+                stageDir: rhythmStageDir,
+                templateDir: projectTemplateDir,
+                upstream: upstream,
+                projectRoot: projectRoot
+              })
+            }));
+            phaseReports.push(rC);
+          }
+        }
+      }
+
+      report = mergePhaseReports(phaseReports);
+      if (keyChapters) report.keyChapters = keyChapters;
+      // 段间门禁挡住的原因要说清楚，不能只报"未完成"
+      if (!phaseFileOk(rA, '节奏参数.json')) {
+        report.blocked = '节奏参数没通过校验，时序映射的布局必须与它对齐，本轮没有继续派活时序映射';
+      } else if (rB && !phaseFileOk(rB, '时序映射.json')) {
+        report.blocked = '时序映射没通过校验，章节细纲的重点章依赖它，本轮没有继续派活章节细纲';
+      }
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg }));
+  }
+
+  // ---- 产出盘点 ----
+  const inspect = inspectRhythmOutput(rhythmStageDir);
+  const status = readRhythmStageStatus(rhythmStageDir);
+  const completionNote = buildRhythmBatchNote({
+    report: report,
+    inspect: inspect,
+    status: status,
+    progressNotes: progressNotes,
+    plans: [planA, planB, planC].filter(Boolean)
+  });
+  const inspectNote = buildRhythmCompletionNote(inspect, status);
+
+  const allPassed = report.ok && inspect.complete && status.allCheck === 'PASSED';
+  const payloadType = allPassed ? 'rhythm_complete' : 'rhythm_incomplete';
+
+  const parts = [setupNote, completionNote, inspectNote].filter(Boolean);
+  const extra = parts.join('\n\n');
+  return notify(session, 'success', storyBuilder.notify({ type: payloadType, phase: '节奏', extra }));
+}
+
+/**
+ * 节奏阶段的上游门禁：骨架 + 血肉两个上游都要全量校验通过。
+ *
+ * 判定口径与 rhythm-validate.js 的 checkUpstreamGates 一致
+ * （读上游 .stage-status.json 的 all_check.status）。
+ * 插件侧提前判是为了**不浪费**：上游没过时模型的每一轮产出都是废的。
+ */
+function checkRhythmUpstreamGates(skeletonDir, fleshDir) {
+  const dirs = [['骨架', skeletonDir], ['血肉', fleshDir]];
+  for (const pair of dirs) {
+    const name = pair[0];
+    const dir = pair[1];
+    if (!dir || !existsSync(dir)) {
+      return { ok: false, reason: name + '阶段目录不存在：' + (dir || '(未指定)') };
+    }
+    const g = readStageGate(dir);
+    if (!g.ok) {
+      return { ok: false, reason: name + '阶段还没通过全量校验：' + g.reason };
+    }
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * 逐个文件跑节奏校验器的单文件模式，把结果汇总成阶段级结果。
+ *
+ * 单文件模式能查出来的：章节规划覆盖 1..T / 卷存在 / 幕合法、
+ * 时序映射的 id 引用完整性 / 章节号区间 / 递增关系、
+ * 节奏参数的 7 条约束可行性 / derivations 键名。
+ * 这些都不依赖其它文件，所以前两段生成完就能立刻判，不用等全部产物齐。
+ */
+async function validateRhythmFiles(files, opts) {
+  const errors = [];
+  const warnings = [];
+  const fileStatus = {};
+  let status = 0;
+  for (const file of files || []) {
+    const r = await runRhythmValidator({
+      validator: opts.validator,
+      input: join(opts.stageDir, file.file),
+      template: join(opts.templateDir, file.template),
+      fileType: file.type,
+      upstream: opts.upstream,
+      projectRoot: opts.projectRoot
+    });
+    for (const e of r.errors || []) errors.push(e);
+    for (const w of r.warnings || []) warnings.push(w);
+    fileStatus[file.file] = r.status;
+    if (r.status !== 0) {
+      // 2 = 脚本异常（比内容错误更严重），取最大值
+      status = Math.max(status, r.status === 2 ? 2 : 1);
+    }
+  }
+  return { status: status, errors: errors, warnings: warnings, fileStatus: fileStatus };
+}
+
+/**
+ * 某个文件在一次驱动里过没过。
+ *
+ * 阶段级校验把多个文件的错误混在一起返回，但段间门禁只关心
+ * "下游依赖的那个文件"过没过——不能因为章节规划没过就把整条链掐断。
+ */
+/**
+ * 造一份"这一段的文件都已定稿，本轮没有派活"的段报告。
+ *
+ * 续跑用：已定稿的文件不派活重做，但它们必须出现在段报告里 ——
+ * 段与段之间的依赖门禁（phaseFileOk）靠它判断能不能继续往下走。
+ *
+ * @param {Array<string>} files 已定稿的文件名
+ * @returns {Object} 段报告
+ */
+function skippedFilesReport(files) {
+  return {
+    ok: true,
+    error: null,
+    files: (files || []).map((f) => ({ file: f, ok: true, skipped: true })),
+    failedFiles: [],
+    batches: [],
+    errors: [],
+    warnings: [],
+    unattributed: [],
+    infraErrors: [],
+    totalBatches: 0,
+    totalRounds: 0
+  };
+}
+
+function phaseFileOk(report, file) {
+  if (!report) return false;
+  const fr = (report.files || []).find((f) => f.file === file);
+  if (!fr) return false;
+  return !!fr.ok;
+}
+
+/**
+ * 把三段的驱动报告合成一份。
+ *
+ * 结论以**最后一段**为准：后面的段可能已经把前面的问题修掉了
+ * （比如第一段章节规划没过，第三段的全量校验又把它修好了）。
+ * 如果按"任一段没过就整体没过"来判，会出现"实际全过了却报未完成"。
+ */
+function mergePhaseReports(reports) {
+  const out = {
+    ok: true, error: null, files: [], failedFiles: [],
+    errors: [], warnings: [], unattributed: [], batches: [],
+    // 脚本/环境问题：跨段累积（不重投给模型，但必须一路带到最终报告）
+    infraErrors: []
+  };
+  for (const r of reports || []) {
+    if (!r) continue;
+    for (const f of r.files || []) {
+      const exist = out.files.find((x) => x.file === f.file);
+      if (!exist) {
+        out.files.push(Object.assign({}, f));
+        continue;
+      }
+      exist.rounds = (exist.rounds || 0) + (f.rounds || 0);
+      if (f.ok) {
+        exist.ok = true;
+        exist.error = null;
+      } else if (!exist.ok && f.error) {
+        exist.error = f.error;
+      }
+      if ((f.errors || []).length) exist.errors = f.errors;
+      if ((f.warnings || []).length) exist.warnings = f.warnings;
+      exist.batches = (exist.batches || []).concat(f.batches || []);
+    }
+    for (const b of r.batches || []) out.batches.push(b);
+    for (const e of r.errors || []) out.errors.push(e);
+    for (const w of r.warnings || []) out.warnings.push(w);
+    for (const e of r.unattributed || []) out.unattributed.push(e);
+    for (const e of r.infraErrors || []) out.infraErrors.push(e);
+
+    // 最后一段说了算
+    out.ok = !!r.ok;
+    out.failedFiles = (r.failedFiles || []).slice();
+    out.error = r.ok ? null : (r.error || null);
+  }
+  if (!out.ok && !out.error) {
+    out.error = '有阶段没通过校验：' + out.failedFiles.join('、');
+  }
+  return out;
+}
+
+/**
+ * 渲染"节奏参数"的真实值，给时序映射批次照抄。
+ * 节奏参数.json 是小对象（3 个整数 + 1 个比率 + 7 条 derivations），可以直接读。
+ */
+function buildRhythmParamContext(rhythmStageDir) {
+  const params = readJsonFileSafe(join(rhythmStageDir, '节奏参数.json'));
+  if (!params || typeof params !== 'object') return null;
+  const lines = ['节奏参数（已由上一段产出，下面是真实值，时序映射必须与它对齐）：'];
+  const keys = ['branch_chapter_total', 'overlap_chapter_count', 'main_progress_chapter_count'];
+  for (const k of keys) {
+    if (params[k] === undefined) continue;
+    lines.push('- ' + k + ' = ' + JSON.stringify(params[k]));
+  }
+  if (params.chapter_hook_rate && typeof params.chapter_hook_rate === 'object') {
+    lines.push('- chapter_hook_rate = ' + JSON.stringify(params.chapter_hook_rate));
+    lines.push('  hook_timeline 的章数下限 = ceil(T * rate)'
+      + (params.chapter_hook_rate.is_minimum ? '（is_minimum=true，是硬下限）' : '（is_minimum=false，只是参考）'));
+  }
+  return lines;
+}
+
+/**
+ * 找同一文件里上一批的收尾（章节按时间推进，本批要承接上一批）。
+ */
+function buildRhythmPrevTailFor(file, batch, buildDir) {
+  if (!file || !file.batches || !file.batches.length) return null;
+  const idx = file.batches.findIndex((b) => b.key === batch.key);
+  if (idx <= 0) return null;
+  const prev = file.batches[idx - 1];
+  const shard = readJsonFileSafe(join(buildDir, prev.shard));
+  return buildRhythmPrevTail({ shard: shard, arrayKeys: prev.arrays });
+}
+
+/**
+ * 节奏阶段结论：把"派了多少批、哪些文件没过、错在哪"讲清楚。
+ *
+ * 与血肉同款：失败必须可见，不能只报"阶段开始"。
+ */
+function buildRhythmBatchNote(opts) {
+  const o = opts || {};
+  const report = o.report || {};
+  const plans = o.plans || [];
+  const lines = [];
+
+  // 批次数按**去重后的批次**算：重投会让 report.batches 里出现同一批的多条记录，
+  // 直接 length 会算出 "18/13" 这种自相矛盾的数。
+  const totalKeys = new Set();
+  for (const p of plans) {
+    for (const b of (p.batches || [])) totalKeys.add(b.key);
+  }
+  const okKeys = new Set();
+  for (const b of (report.batches || [])) {
+    if (b.ok) okKeys.add(b.key);
+  }
+
+  if (report.error) {
+    lines.push('❌ 节奏阶段未完成：' + report.error);
+  } else if (report.ok) {
+    lines.push('✅ 节奏阶段逐批派活完成：' + okKeys.size + '/' + totalKeys.size + ' 批通过校验。');
+  } else {
+    lines.push('❌ 节奏阶段未完成：' + ((report.failedFiles || []).join('、') || '有批次没通过校验') + '。');
+    lines.push('（已通过 ' + okKeys.size + '/' + totalKeys.size + ' 批）');
+  }
+
+  if (report.blocked) {
+    lines.push('');
+    lines.push('⛔ ' + report.blocked);
+  }
+
+  const errs = report.errors || [];
+  if (errs.length) {
+    lines.push('');
+    lines.push('**校验错误（' + errs.length + ' 条）**');
+    for (const e of errs.slice(0, 15)) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || '') + (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    if (errs.length > 15) lines.push('- ……还有 ' + (errs.length - 15) + ' 条');
+  }
+
+  // 脚本/环境问题单独成段：它们没有重投给模型，混在错误列表里会误导
+  for (const l of renderInfraBlock(report.infraErrors)) lines.push(l);
+
+  const un = report.unattributed || [];
+  if (un.length) {
+    lines.push('');
+    lines.push('**归因不到具体批次的错误（' + un.length + ' 条，重投时不会自动修）**');
+    for (const e of un.slice(0, 8)) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.path || '(无路径)') + '：' + (e.message || ''));
+    }
+    if (un.length > 8) lines.push('- ……还有 ' + (un.length - 8) + ' 条');
+  }
+
+  const notes = o.progressNotes || [];
+  if (notes.length) {
+    lines.push('');
+    lines.push('进度（共 ' + notes.length + ' 条）：' + notes.slice(-3).join('；'));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 处理 wiki 命令 - 对 raw/sources 执行 ingest
+ */
+async function handleWiki(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken) {
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  if (!setupId) {
+    // 本阶段要真的拿 setup_id 去调 llm-wiki API，取不到就必须停，并说清怎么修
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+
+  // 准备"设定"目录并拷贝 schema.md（本阶段只认 schema.md，不需要 purpose.md）。
+  // 之前这里是手写的拷贝：不建目录（目录不存在时静默失败），
+  // 而且 catch 把错误吞掉，用户完全看不到。
+  const schemaCopy = await copySchemaToProject(projectRoot, { includePurpose: false });
+  const schemaNote = schemaCopy.ok
+    ? ''
+    : storyBuilder.notify({ type: 'schema_copy_failed', detail: schemaCopy.detail });
+
+  // 只读取 raw/sources/节奏 目录下的文件
+  const rhythmDir = join(projectRoot, '设定', 'raw', 'sources', '节奏');
+  if (!existsSync(rhythmDir)) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'no_sources_dir' }));
+  }
+
+  // 收集节奏目录下所有 .md 文件
+  const filesToIngest = [];
+  const collectErrors = [];
+  function collectFiles(dir, basePath = '') {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch (e) {
+      collectErrors.push(`读取目录失败 ${dir}: ${e.message}`);
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      const relativePath = basePath ? `${basePath}/${entry}` : entry;
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch (e) {
+        collectErrors.push(`读取条目失败 ${fullPath}: ${e.message}`);
+        continue;
+      }
+      if (stat.isDirectory()) {
+        collectFiles(fullPath, relativePath);
+      } else if (stat.isFile() && entry.endsWith('.md')) {
+        filesToIngest.push(`raw/sources/${relativePath}`);
+      }
+    }
+  }
+  collectFiles(rhythmDir, '节奏');
+
+  if (collectErrors.length > 0) {
+    console.error('[fancy-story-builder] 收集文件时出错：\n  ' + collectErrors.join('\n  '));
+  }
+
+  if (filesToIngest.length === 0) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'no_files_to_ingest' }));
+  }
+
+  // 清除 ingest-cache 中对应文件的 hash（强制重新解析）
+  const ingestCachePath = join(projectRoot, '设定', '.llm-wiki', 'ingest-cache.json');
+  if (existsSync(ingestCachePath)) {
+    try {
+      const cacheContent = readFileSync(ingestCachePath, 'utf-8');
+      const cacheData = JSON.parse(cacheContent);
+      let cleared = 0;
+      for (const filePath of filesToIngest) {
+        // llm-wiki 的缓存键是相对 raw/sources/ 的路径（如 "节奏/主线大纲.md"），
+        // 不是文件名。之前用 basename 查永远 miss，导致"强制重新解析"形同虚设。
+        const cacheKey = filePath.startsWith('raw/sources/')
+          ? filePath.slice('raw/sources/'.length)
+          : filePath;
+        if (cacheData.entries && cacheData.entries[cacheKey]) {
+          cacheData.entries[cacheKey].hash = '';
+          cleared++;
+        }
+      }
+      writeFileSync(ingestCachePath, JSON.stringify(cacheData, null, 2), 'utf-8');
+      console.error(`[fancy-story-builder] 已清除 ${cleared}/${filesToIngest.length} 个 ingest-cache 条目的 hash`);
+    } catch (e) {
+      console.error(`[fancy-story-builder] 更新 ingest-cache 失败：${e.message}`);
+    }
+  }
+
+  // 调用 ingest 接口
+  try {
+    const result = await callLlmWikiApi(
+      llmWikiUrl,
+      llmWikiToken,
+      `/projects/${setupId}/sources/ingest`,
+      'POST',
+      { paths: filesToIngest },
+      signal
+    );
+    // 必须检查响应体：llm-wiki 的错误约定是 HTTP 200 + { ok:false, error:"..." }，
+    // 不检查就会把失败当成"已启动 ingest"报给用户。
+    if (result.status >= 400) {
+      const msg = (result.data && (result.data.error || result.data.message)) || ('HTTP ' + result.status);
+      return notify(session, 'error', storyBuilder.notify({ type: 'ingest_failed', err: msg }));
+    }
+    if (result.data && result.data.ok === false) {
+      const msg = result.data.error || '接口返回 ok:false';
+      return notify(session, 'error', storyBuilder.notify({ type: 'ingest_failed', err: msg }));
+    }
+    return notify(session, 'success', storyBuilder.notify({ type: 'ingest_started', fileCount: filesToIngest.length, extra: schemaNote }));
+  } catch (err) {
+    const errMsg = describeFetchError(err, LLM_WIKI_TIMEOUT_MS);
+    return notify(session, 'error', storyBuilder.notify({ type: 'ingest_failed', err: errMsg }));
+  }
+}
+
+/**
+ * 查询 ingest 状态
+ */
+async function queryIngestStatus(llmWikiUrl, llmWikiToken, projectId, signal = null) {
+  return callLlmWikiApi(llmWikiUrl, llmWikiToken, `/projects/${projectId}/ingest/querystatus`, 'GET', null, signal);
+}
+
+/**
+ * 获取 reviews 列表
+ */
+async function getReviews(llmWikiUrl, llmWikiToken, projectId, signal = null) {
+  return callLlmWikiApi(llmWikiUrl, llmWikiToken, `/projects/${projectId}/reviews`, 'GET', null, signal);
+}
+
+/**
+ * 处理分析阶段
+ */
+async function handleAnalyze(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences) {
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在（幂等调用）
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  // 说明文字要并入最终返回的消息：notify 的中间返回值会被丢弃，
+  // 单独发一条 info 用户根本看不到。
+  let setupNote = '';
+  if (!setupId) {
+    // 本阶段要真的拿 setup_id 去调 llm-wiki API，取不到就必须停，并说清怎么修
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+  if (setupResult.reused) {
+    setupNote = storyBuilder.notify({ type: 'setup_id_reused', id: setupId, source: setupResult.source });
+  }
+
+  // 准备"设定"目录并拷贝 schema 文件（返回值必须检查：拷失败要能看见）
+  const schemaCopy = await copySchemaToProject(projectRoot);
+  if (!schemaCopy.ok) {
+    setupNote = (setupNote ? setupNote + '\n\n' : '') + storyBuilder.notify({
+      type: 'schema_copy_failed',
+      detail: schemaCopy.detail
+    });
+  }
+
+  // 1. 查询 ingest 状态
+  try {
+    const statusResult = await queryIngestStatus(llmWikiUrl, llmWikiToken, setupId, signal);
+    if (statusResult && statusResult.data) {
+      const { missingFiles, queue } = statusResult.data;
+
+      // 队列可能是数组，也可能是对象 { pending, processing, done, failed, cancelled }。
+      // 之前只按数组处理（queue.length），对象形式下 queue.length 恒为 undefined，
+      // 导致"还有任务在跑"这个判断永远不生效。
+      const queueCount = Array.isArray(queue)
+        ? queue.length
+        : (queue && typeof queue === 'object'
+          ? (queue.pending || 0) + (queue.processing || 0)
+          : 0);
+
+      // 检查是否有未 ingest 的文件或正在进行中的任务
+      if ((missingFiles && missingFiles.length > 0) || queueCount > 0) {
+        const missingCount = missingFiles ? missingFiles.length : 0;
+        return notify(session, 'error', storyBuilder.notify({
+          type: 'ingest_not_ready',
+          missingCount,
+          queueCount,
+        }));
+      }
+    }
+  } catch (err) {
+    // querystatus 失败不影响主流程，仅记录
+    console.error(`[fancy-story-builder] querystatus failed: ${describeFetchError(err, LLM_WIKI_TIMEOUT_MS)}`);
+  }
+
+  // 2. 获取 reviews
+  let reviewsContent = '';
+  try {
+    const reviewsResult = await getReviews(llmWikiUrl, llmWikiToken, setupId, signal);
+    if (reviewsResult && reviewsResult.data && reviewsResult.data.reviews) {
+      const reviews = reviewsResult.data.reviews;
+
+      // 分类整理 reviews
+      const contradiction = reviews.filter(r => r.type === 'contradiction');
+      const confirm = reviews.filter(r => r.type === 'confirm');
+      const suggestion = reviews.filter(r => r.type === 'suggestion');
+
+      reviewsContent = `\n\n## LLM Wiki 审查结果\n\n`;
+      reviewsContent += `共发现 ${reviews.length} 个审查项：\n\n`;
+
+      if (contradiction.length > 0) {
+        reviewsContent += `### ⚠️ 矛盾 (${contradiction.length}项)\n\n`;
+        for (const r of contradiction) {
+          reviewsContent += `- **${r.title}**\n  - 位置：${r.sourcePath || '未知'}\n  - 描述：${r.description || '无描述'}\n\n`;
+        }
+      }
+
+      if (confirm.length > 0) {
+        reviewsContent += `### ❓ 需要确认 (${confirm.length}项)\n\n`;
+        for (const r of confirm) {
+          reviewsContent += `- **${r.title}**\n  - 位置：${r.sourcePath || '未知'}\n  - 描述：${r.description || '无描述'}\n\n`;
+        }
+      }
+
+      if (suggestion.length > 0) {
+        reviewsContent += `### 💡 改进建议 (${suggestion.length}项)\n\n`;
+        for (const r of suggestion) {
+          reviewsContent += `- **${r.title}**\n  - 位置：${r.sourcePath || '未知'}\n  - 描述：${r.description || '无描述'}\n\n`;
+        }
+      }
+    }
+  } catch (err) {
+    // reviews 失败不影响主流程，仅记录
+    console.error(`[fancy-story-builder] getReviews failed: ${describeFetchError(err, LLM_WIKI_TIMEOUT_MS)}`);
+  }
+
+  // 3. 生成提示词（包含 reviews 内容）
+  const prompt = storyBuilder.generateAnalyzeSystemPrompt({ topicData, wikiReferences, reviewsContent });
+
+  try {
+    const follow = await llmFollowup(invocation, prompt);
+    // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
+    // 否则投递失败也会报"阶段开始"
+    if (!follow || follow.ok !== true) {
+      return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: (follow && follow.error) || '提示词投递失败' }));
+    }
+    return notify(session, 'success', storyBuilder.notify({ type: 'phase_started', phase: '分析', extra: setupNote }));
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg }));
+  }
+}
+
+/**
+ * 处理写作阶段（直接走 prompt 4 - 逐章生成 + 校验 + 台账）
+ */
+async function handleWriting(ctx, session, invocation, projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, topicData, wikiReferences) {
+  // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+  const benchmarkRefs = renderBenchmarkGuidance(projectRoot, 'writing');
+  // 用户中断时让底层 HTTP 请求一起取消（此前 signal 取了却没用）
+  const { signal } = invocation;
+  // 确保 setup_id 存在（幂等调用）
+  const setupResult = await ensureSetupId(projectRoot, deployedConfig, llmWikiUrl, llmWikiToken, signal);
+  const setupId = setupResult.id;
+  // 说明文字要并入最终返回的消息：notify 的中间返回值会被丢弃，
+  // 单独发一条 info 用户根本看不到。
+  let setupNote = '';
+  if (!setupId) {
+    // "设定"目录必须先是 llm-wiki 里的项目，本阶段的产物才会被 ingest 纳管
+    // （实测：骨架 7 + 血肉 13 + 节奏 55 个文件全部进了 llm-wiki 的 ingest-cache）。
+    // 拿不到 setup_id = 设定项目没建成 → 继续跑只会产出不被纳管的半成品，
+    // 而且后续 wiki / analyze 阶段必然失败。必须硬失败。
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'setup_id_unavailable',
+      err: setupResult.reason,
+      detail: setupResult.detail
+    }));
+  }
+  if (setupResult.reused) {
+    setupNote = storyBuilder.notify({ type: 'setup_id_reused', id: setupId, source: setupResult.source });
+  }
+
+  // 准备"设定"目录并拷贝 schema 文件（返回值必须检查：拷失败要能看见）
+  const schemaCopy = await copySchemaToProject(projectRoot);
+  if (!schemaCopy.ok) {
+    setupNote = (setupNote ? setupNote + '\n\n' : '') + storyBuilder.notify({
+      type: 'schema_copy_failed',
+      detail: schemaCopy.detail
+    });
+  }
+
+  // ============================================================
+  // 写作阶段：插件驱动、按批执行
+  // ============================================================
+  // 旧模式：投一次提示词就返回"写作阶段开始"，T 章全靠 LLM 自己 for 循环，
+  // 插件对写作流程零控制（漏章/跳章/校验失败不重试/台账不更新都发现不了）。
+  // 新模式：插件自己按批循环，每批注入细纲与上下文，**自己跑校验器**，
+  // 失败的章回喂重试，通过才推进。
+  const context = loadWritingContext(projectRoot);
+  if (context.error) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: context.error }));
+  }
+
+  const upstreamDirs = [
+    join(projectRoot, '设定', 'raw', 'sources', '骨架'),
+    join(projectRoot, '设定', 'raw', 'sources', '血肉'),
+    join(projectRoot, '设定', 'raw', 'sources', '节奏')
+  ];
+  const validator = join(projectRoot, 'references', 'writing-validate.js');
+
+  // 这条信息不能只 notify 出去：DSH 只有 handler 的返回值会经
+  // settleThrown → command/done → channel.notify()，中间调用丢弃 = 用户看不到。
+  // 并入最终返回消息。
+  const writingNote = '写作阶段：共 ' + context.T + ' 章，按每批 ' + WRITING_BATCH_SIZE + ' 章由插件逐批驱动。';
+  setupNote = setupNote ? setupNote + '\n\n' + writingNote : writingNote;
+
+  // 逐批进度同样只在最终消息里给摘要
+  const progressNotes = [];
+
+  // signal 必须传：用户按 Ctrl-C 之后不该还在等 45 分钟。
+  // idleGraceMs 与其余阶段对齐（60 秒）：15 秒的宽限期会把"排队稍慢"
+  // 误判成超时，整段写作直接中断。
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: 45 * 60 * 1000,
+    idleGraceMs: 60000,
+    signal: invocation.signal
+  });
+
+  // 写作执行须知（产物契约）：每批派活都带一遍
+  const contract = storyBuilder.generateWritingContract({ topicData, benchmarkRefs });
+
+  let report;
+  try {
+    report = await runWritingStage({
+      context,
+      projectRoot,
+      contract,
+      sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+      waitIdle: async (expectedFiles) => {
+        const r = await waitForTurn(expectedFiles);
+        if (!r.ok) {
+          const err = new Error(r.reason || '等待 LLM 失败');
+          err.__writingWaitFailed = true;
+          throw err;
+        }
+        return r;
+      },
+      validateChapter: async (ch) => {
+        const file = join(context.dirs.writing, chapterFileName(ch));
+        if (!existsSync(file)) {
+          return {
+            status: 2,
+            errors: [{ code: 'CHAPTER_MISSING', path: file, message: '第 ' + ch + ' 章文件没有生成：' + file, hint: 'LLM 本轮没有产出该章' }],
+            warnings: []
+          };
+        }
+        const r = await spawnScript('node', [
+          validator,
+          '--input=' + file,
+          '--chapter=' + ch,
+          '--upstream=' + upstreamDirs.join(',')
+        ], { timeout: 120000, cwd: projectRoot });
+        if (!r.ok) {
+          return {
+            status: 2,
+            errors: [{ code: 'VALIDATOR_CRASH', path: file, message: '校验脚本异常：' + (r.error || r.stderr || '未知错误'), hint: null }],
+            warnings: []
+          };
+        }
+        try {
+          const parsed = JSON.parse(r.output);
+          return { status: parsed.status, errors: parsed.errors || [], warnings: parsed.warnings || [] };
+        } catch (e) {
+          return {
+            status: 2,
+            errors: [{ code: 'VALIDATOR_OUTPUT_INVALID', path: file, message: '校验脚本输出不是合法 JSON：' + String(e.message), hint: null }],
+            warnings: []
+          };
+        }
+      },
+      // 进度消息不能直接 notify 出去：DSH 只有 handler 的返回值会被用户看到，
+      // 中间调用一律丢弃。改为收集起来，在最终消息里给摘要
+      // （T=500 有 50 批，全塞进去太长）。
+      onProgress: (msg) => { progressNotes.push(msg); }
+    });
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg, extra: setupNote }));
+  }
+
+  if (!report.ok) {
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: report.error || '写作阶段中断', extra: setupNote }));
+  }
+
+  // 逐批进度的摘要：写进最终消息，用户才看得到"跑到哪了"
+  const progressSummary = progressNotes.length
+    ? '写作进度（共 ' + progressNotes.length + ' 条）：' +
+      progressNotes.slice(-3).join('；')
+    : '';
+  const finalNote = progressSummary
+    ? (setupNote ? setupNote + '\n\n' + progressSummary : progressSummary)
+    : setupNote;
+
+  // 续跑复检没过的章（空文件/半截/标题错/校验不过）——要说明它们被重写了，
+  // 否则用户看到"复用 N 章"却不知道有几章被判定为不合格。
+  const recheckNote = (report.recheckFailed && report.recheckFailed.length)
+    ? '复检未通过、已重新写的有 ' + report.recheckFailed.length + ' 章（章号：' +
+      report.recheckFailed.map((r) => r.ch).join('、') + '）。'
+    : '';
+
+  if (report.failed.length > 0) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'writing_incomplete',
+      written: report.written.length,
+      reused: (report.reused || []).length,
+      failed: report.failed.map((f) => f.ch),
+      extra: [finalNote, recheckNote].filter(Boolean).join('\n\n')
+    }));
+  }
+
+  return notify(session, 'success', storyBuilder.notify({
+    type: 'writing_done',
+    count: report.written.length,
+    reused: (report.reused || []).length,
+    extra: [finalNote, recheckNote].filter(Boolean).join('\n\n')
+  }));
+}
+
+/**
+ * 处理去味阶段（插件驱动、逐章执行）
+ *
+ * 与写作阶段同一套骨架：插件派活 → 等回合 → 自己跑检测器 → 判结果 → 回喂重试。
+ * 去味特有的三件事：
+ *   - 改写**只改 AI 味**（模型改，插件不替模型做正则替换）；
+ *   - 改动比例超 35% 自动回滚（旧 SKILL.md 承诺了，代码里从来没实现）；
+ *   - 报告由插件按检测数据生成（不让模型自己总结，免得"装作成功"）。
+ *
+ * 不需要 setup_id：去味只改本地正文文件，不往"设定"目录新增设定产物。
+ */
+async function handleDeslop(ctx, session, invocation, projectRoot, deployedConfig, topicData) {
+  const dirs = deslopDirs(projectRoot);
+  const chapters = listChapterFiles(projectRoot);
+  if (chapters.length === 0) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'deslop_no_chapters',
+      extra: dirs.writing
+    }));
+  }
+
+  // 校验脚本必须部署到位（部署清单从 import 图推导，缺文件在部署阶段就该报错）
+  const validator = join(projectRoot, 'references', 'deslop-validate.js');
+  if (!existsSync(validator)) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'deploy_failed',
+      err: '校验脚本部署失败：references/deslop-validate.js 不存在'
+    }));
+  }
+
+  const contract = storyBuilder.generateDeslopContract({ topicData });
+  const progressNotes = [];
+
+  // 写作复检要用的上游目录（去味阶段自己的作用域，与写作阶段那份互不影响）
+  const upstreamDirs = [
+    join(projectRoot, '设定', 'raw', 'sources', '骨架'),
+    join(projectRoot, '设定', 'raw', 'sources', '血肉'),
+    join(projectRoot, '设定', 'raw', 'sources', '节奏')
+  ];
+
+  // 等回合的判据：改写场景里文件**本来就在**，"文件在不在"不能当完成判据，
+  // 必须看内容有没有变。baseline 由每次 waitIdle 调用设置。
+  let baseline = null;
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: 45 * 60 * 1000,
+    idleGraceMs: 60000,
+    signal: invocation.signal,
+    changed: (files) => {
+      if (baseline === null) return true;
+      return files.some((f) => {
+        try {
+          return readFileSync(f, 'utf-8') !== baseline;
+        } catch {
+          return true;
+        }
+      });
+    }
+  });
+
+  const waitIdle = async (files, before) => {
+    baseline = before;
+    try {
+      return await waitForTurn(files);
+    } finally {
+      baseline = null;
+    }
+  };
+
+  // 检测：跑**部署到项目里的那一份**（跑的就是部署下去的那份，缺文件立刻暴露）
+  const detect = async (file) => {
+    const r = await spawnScript('node', [validator, '--input=' + file], {
+      timeout: 120000,
+      cwd: projectRoot
+    });
+    if (!r.ok) {
+      return { ok: false, error: '检测脚本异常：' + (r.error || r.stderr || '未知错误') };
+    }
+    try {
+      return { ok: true, detection: JSON.parse(r.output) };
+    } catch (e) {
+      return { ok: false, error: '检测脚本输出不是合法 JSON：' + String(e.message) };
+    }
+  };
+
+  let report;
+  try {
+    report = await runDeslopStage({
+      projectRoot,
+      dirs,
+      chapters,
+      contract,
+      sendPrompt: async (prompt) => llmFollowup(invocation, prompt),
+      waitIdle,
+      detect,
+      // 去味后的写作复检（P1-3）：去味只查标题/字数/空文，
+      // 查不出占位符/字符集/禁用词/一级标题这些"改坏了"的情况。
+      // 这里补跑部署到项目里的 writing-validate.js。
+      validateWriting: async (chapter) => {
+        const script = join(projectRoot, 'references', 'writing-validate.js');
+        if (!existsSync(script)) return { ok: true, errors: [] };
+        const r = await spawnScript('node', [
+          script,
+          '--input=' + chapter.path,
+          '--chapter=' + chapter.ch,
+          '--upstream=' + upstreamDirs.join(',')
+        ], { timeout: 120000, cwd: projectRoot });
+        if (!r.ok) {
+          return { ok: false, errors: [{ code: 'VALIDATOR_CRASH', message: '写作校验脚本异常：' + (r.error || r.stderr || '未知错误') }] };
+        }
+        try {
+          const parsed = JSON.parse(r.output);
+          return { ok: parsed.status === 0, errors: parsed.errors || [] };
+        } catch (e) {
+          return { ok: false, errors: [{ code: 'VALIDATOR_OUTPUT_INVALID', message: '写作校验脚本输出不是合法 JSON：' + String(e.message) }] };
+        }
+      },
+      onProgress: (msg) => { progressNotes.push(msg); },
+      onChapter: (chapter) => {
+        const name = '第' + String(chapter.ch).padStart(3, '0') + '章_去AI味报告.md';
+        writeReport(dirs, name, renderChapterReport(chapter));
+      }
+    });
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return notify(session, 'error', storyBuilder.notify({ type: 'api_failed', err: errMsg }));
+  }
+
+  if (report.chapters.length) {
+    writeReport(dirs, '去AI味总览.md', renderOverviewReport(report.chapters));
+  }
+
+  // 进度摘要必须并进最终消息：DSH 只显示 handler 的返回值，中间 notify 会被丢弃
+  const progressSummary = progressNotes.length
+    ? '去味进度（共 ' + progressNotes.length + ' 条）：' + progressNotes.slice(-3).join('；')
+    : '';
+
+  const problems = report.failed.concat(report.errored);
+  if (problems.length > 0) {
+    return notify(session, 'error', storyBuilder.notify({
+      type: 'deslop_incomplete',
+      failed: problems,
+      rolledBack: report.rolledBack.length,
+      errored: report.errored.length,
+      extra: progressSummary
+    }));
+  }
+
+  return notify(session, 'success', storyBuilder.notify({
+    type: 'deslop_done',
+    count: report.chapters.length,
+    clean: report.clean,
+    passed: report.passed,
+    extra: progressSummary
+  }));
+}