@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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

@@ -0,0 +1,1446 @@
+/**
+ * fancy-story-builder templates — 提示词模板
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { renderInputSnapshot } from './scripts/graph-utils.js';
+import { pickContractSections } from './scripts/stage-contract.js';
+import { readingPowerLegend } from './scripts/reading-power.js';
+import { referenceLogPromptBlock } from './scripts/reference-log.js';
+import { deslopLegend } from './scripts/ai-patterns.js';
+import { normalizeLegacyTopicData, TOPIC_REQUIRED_FIELDS } from '#topic-fields';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REFERENCES_DIR = join(__dirname, 'references');
+const PROMPTS_DIR = join(__dirname, 'prompts');
+
+// 读取内置参考文件
+// - skeleton-prompt.md 等 prompt 文件从 prompts/ 读
+// - 其他参考文件（glossary / formulas / index）从 references/ 读
+
+// 给 LLM 看时去掉 prompt 文件顶部维护者元数据（@meta-only sentinel 之前的内容）
+function cleanPromptForLLM(content) {
+  // 找到 '@meta-only' 行的索引，丢掉从开头到该行（含）的所有内容
+  const idx = content.indexOf('\n@meta-only\n');
+  if (idx === -1) return content; // 没有 sentinel，保持原样
+  // 取 sentinel 之后的内容；sentinel 之后的 --- 是 markdown 分隔，让 Markdown 渲染器有上下文
+  const after = content.slice(idx + '\n@meta-only\n'.length);
+  // 去掉紧跟的 --- 行（如果有），但保留后续章节正文
+  return after.replace(/^\s*---\s*\n/, '');
+}
+
+/**
+ * 模板里的类型 → 人话（提示词用）。
+ *
+ * 模板 JSON 是唯一真源：类型标签只能由它推出来，
+ * 不能在提示词里另写一份（手写的那份一定会漂移）。
+ *
+ * @param {Object} spec 模板里的字段定义
+ * @returns {string} 类型标签
+ */
+function skeletonTypeLabel(spec) {
+  if (!spec || typeof spec !== 'object') return '未定义';
+  const t = spec.type;
+  if (t === 'array') return skeletonTypeLabel(spec.items || {}) + '数组';
+  if (t === 'string') return '字符串';
+  if (t === 'number' || t === 'integer') return '数字';
+  if (t === 'boolean') return '布尔';
+  if (t === 'object') return '对象';
+  return String(t || '未定义');
+}
+
+function readBuiltInReference(filename) {
+  // 提示词文件：优先从 prompts/ 找，再 fallback 到 references/
+  if (/^\d{2}-.+\.md$/.test(filename) || /skeleton-prompt|flesh-prompt|rhythm-prompt|writing-prompt/.test(filename)) {
+    try {
+      return readFileSync(join(PROMPTS_DIR, filename), 'utf-8');
+    } catch {
+      try {
+        return readFileSync(join(REFERENCES_DIR, filename), 'utf-8');
+      } catch {
+        return '';
+      }
+    }
+  }
+  // 其他：从 references/ 读
+  try {
+    return readFileSync(join(REFERENCES_DIR, filename), 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 选题字段的安全取值：数组/字符串/其它都要能安全转成 prompt 里的文本。
+ * 之前用 `hard_constraints?.join('；')`，当该字段是字符串（用户手改/旧格式）时
+ * 会抛 TypeError 并逃出命令处理器。
+ */
+function joinField(v, sep = '；', fallback = '无') {
+  if (Array.isArray(v)) return v.length ? v.map(x => (x === null || x === undefined ? '' : String(x))).filter(Boolean).join(sep) : fallback;
+  if (v === undefined || v === null) return fallback;
+  if (typeof v === 'string') return v.trim() ? v : fallback;
+  return String(v);
+}
+
+/**
+ * 从选题参数兜底出一份任务输入快照。
+ *
+ * 正常路径是读骨架阶段的 框架.json（input_snapshot + capacity），
+ * 那份快照是骨架校验器验过的，更权威。这里只在"骨架产物还没落盘"时兜底。
+ */
+function snapshotFromTopicData(topicData) {
+  const t = normalizeLegacyTopicData(topicData || {});
+  const out = {};
+  for (const id of TOPIC_REQUIRED_FIELDS) {
+    if (id === 'hard_constraints' || id === 'anti_tropes') {
+      out[id] = Array.isArray(t[id]) ? t[id] : [];
+    } else {
+      out[id] = t[id];
+    }
+  }
+  return out;
+}
+
+/**
+ * 把提示词里**行内反引号**包着的项目内路径改成绝对路径。
+ *
+ * ## 为什么必须改
+ *
+ * 插件把参考文件（词表 / 公式 / 阶段指导 / 字段模板）拷到**项目根**的
+ * `references/` 与 `模板/` 下，但提示词里写的是相对路径
+ * （`references/formulas-skeleton.json`）。
+ *
+ * 相对路径的前提是"当前目录 = 项目根"。这个前提一旦不成立，
+ * 路径就会被拼到别的目录下 —— 典型的是拼成
+ * `<项目根>/设定/references/formulas-skeleton.json`：
+ * `设定/` 是 llm-wiki 的项目目录，插件**从没**往那里放过参考文件，
+ * 于是读不到，模型要么空手写、要么以为参考文件缺失。
+ *
+ * 插件知道项目根，所以在运行时把路径换成绝对的：基准被钉死，
+ * 模型不用猜，工具用哪种读法都对。
+ *
+ * ## 只改行内反引号里的
+ *
+ * - **代码块里的命令保持相对**：`node references/upstream-query.js …`
+ *   是在项目根下执行的命令，绝对化会与"在项目根运行"的语义打架；
+ * - **产物路径保持相对**（`设定/raw/sources/…`）：那是模型要写的地方，
+ *   相对项目根，和校验器读的路径一致；
+ * - **`对标/wiki/` 保持相对**：那是 llm-wiki 的项目，相对路径才是它要的形态。
+ *
+ * @param {string} text        提示词正文
+ * @param {string} projectRoot 项目根绝对路径（没有就原样返回）
+ * @returns {string} 绝对化后的正文
+ */
+export function absolutizeInlinePaths(text, projectRoot) {
+  if (!text || !projectRoot) return text;
+  const root = String(projectRoot).replace(/\/+$/, '');
+  if (!root) return text;
+  return text.replace(/`((?:references|模板)\/[^`\n]*)`/g, (m, p) => '`' + root + '/' + p + '`');
+}
+
+/** 标量字段的安全取值：undefined/null 会导致 prompt 里出现字面量 "undefined" */
+function textField(v, fallback = '') {
+  if (v === undefined || v === null) return fallback;
+  return String(v);
+}
+
+export const storyBuilder = {
+  /**
+   * 通知模板
+   */
+  /**
+   * 通知模板。
+   *
+   * 解构列表必须**覆盖每个分支里插值到的变量** —— 少一个就是
+   * ReferenceError（2026-10-27 实测：writing_done / writing_incomplete /
+   * deslop_done / deslop_incomplete 四个分支全部因为缺 count/failed/written/
+   * clean/passed/rolledBack/errored 而抛错，写作与去味阶段每次跑完都在
+   * 收尾处崩，而 993 个测试全绿 —— 这条路径零覆盖）。
+   *
+   * 数值给默认值，是为了让"调用方忘了传某个字段"退化成 0 而不是崩。
+   */
+  notify({ type, err, phase, id, fileCount, missingCount, queueCount, detail, source, extra, stage, missing, next,
+          count = 0, failed = [], written = 0, clean = 0, passed = 0, rolledBack = 0, errored = 0,
+          reused = 0 }) {
+    switch (type) {
+      case 'help':
+        return `📖 故事构建 用法
+
+/fancy-build scale    - 故事规模：总章数、总字数、卷、幕、配额
+/fancy-build macro    - 世界观、故事、主线/支线、结局、角色功能位
+/fancy-build cast     - 人物、势力、地点、道具、冲突、伏笔、爽点、高潮、信息差
+/fancy-build rhythm   - 章节地图：逐章写人物、地点、冲突、钩子、伏笔/爽点动作
+/fancy-build outline  - 细纲和场景；示例：outline CH001 / outline 1-10 / outline all
+/fancy-build write   - 正文和章末交接；示例：write CH001 / write 1-10 / write all
+/fancy-build deslop   - 去 AI 味；示例：deslop CH001 / deslop 1-10 / deslop all
+/fancy-build help    - 显示本帮助
+`;
+
+      case 'v2_done':
+        return err || extra || '✅ 阶段完成。';
+
+      case 'v2_failed': {
+        const text = err || extra || '阶段未完成';
+        return /^[❌⚠️]/.test(text) ? text : '❌ ' + text;
+      }
+
+      case 'v2_info':
+        return err || extra || '';
+
+      case 'cancelled':
+        return '🚫 操作已取消。';
+
+      case 'no_provider':
+        return '⚠️ 当前运行环境不支持交互式提问。请在 dsh-tui 中运行该命令，或确认 Web UI 已正确加载交互组件。';
+
+      case 'no_project_root':
+        return '❌ 无法确定当前项目：' + (err || '会话未提供当前工作目录') + '。请在项目目录下运行，或用 /fancy-project use <名字|UUID> 指定当前项目。';
+
+      case 'ask_failed':
+        return '❌ 交互提问失败：' + (err || '未知错误');
+
+      case 'not_initialized':
+        return '⚠️ 当前没有可用项目。请先运行 /fancy-bootstrap 初始化工作区，再运行 /fancy-topic setup 创建项目。';
+
+      case 'config_corrupt':
+        return '❌ ' + (err || '无法解析 .fancy-deployed 状态文件。') + ' 请检查文件内容，或重新运行 /fancy-bootstrap 初始化工作区。';
+
+      case 'no_project_root':
+        return '❌ ' + (err || '无法确定项目目录');
+
+      case 'no_topic':
+        return '⚠️ 未找到选题信息。请先运行 /fancy-topic 完成选题。';
+
+      case 'setup_id_unavailable': {
+        // 分类原因 → 人话 + **针对该原因**的排查步骤。
+        // 此前这里只有一句"未设置 setup_id，请先运行 /fancy-build skeleton"，
+        // 而用户正是运行着这条命令 —— 死胡同，且把真实原因（token 无效 / 服务没起）藏了。
+        // 注意：步骤必须按原因分流。给"连不上服务"的人列一堆 token 步骤，
+        // 比不给步骤更糟 —— 会把人引到错误的方向上去。
+        const reasonText = {
+          unauthorized: 'llm-wiki 拒绝了请求（token 无效或服务端未配置 token）',
+          network: '无法连接 llm-wiki 服务',
+          api_error: 'llm-wiki 返回了错误',
+          unexpected_response: 'llm-wiki 返回了非预期结构'
+        };
+        const stepsByReason = {
+          unauthorized: [
+            '1. 在 llm-wiki 的「设置 → API + MCP」里填「访问令牌」（可直接点「生成新 token」）',
+            '2. 保存设置后，把同一个 token 写进本项目 .fancy-deployed 的 llm_wiki_token 字段',
+            '3. 确认 llm-wiki 正在运行：curl -s -o /dev/null -w "%{http_code}" http://localhost:19828/api/v1/health'
+          ],
+          network: [
+            '1. 确认 llm-wiki 正在运行：curl -s -o /dev/null -w "%{http_code}" http://localhost:19828/api/v1/health',
+            '2. 确认 .fancy-deployed 里的 llm_wiki_url 指向正确地址（默认 http://localhost:19828/api/v1）',
+            '3. 启动 llm-wiki 后重试本命令'
+          ],
+          api_error: [
+            '1. 查看 llm-wiki 日志或控制台输出，确认服务端返回的具体错误',
+            '2. 确认 .fancy-deployed 里的 llm_wiki_url 与 llm_wiki_token 正确'
+          ],
+          unexpected_response: [
+            '1. 确认 llm-wiki 版本与本插件兼容（/api/v1/projects/create 应返回 {ok:true, project:{id}}）',
+            '2. 确认 .fancy-deployed 里的 llm_wiki_url 末尾就是 /api/v1'
+          ]
+        };
+        const steps = stepsByReason[err] || [
+          '1. 在 llm-wiki 的「设置 → API + MCP」里确认「访问令牌」已填写、「启用本地 HTTP API」已打开',
+          '2. 确认 .fancy-deployed 里的 llm_wiki_url 与 llm_wiki_token 正确'
+        ];
+        const head = '❌ 未能建立 llm-wiki 设定项目：' + (reasonText[err] || err || '未知原因');
+        const detailLine = detail ? '\n详情：' + detail : '';
+        const consequence =
+          '\n\n后果：llm-wiki 尚未识别本项目的「设定」目录，' +
+          '本阶段产物不会被 ingest 纳管，后续 /fancy-build maintain sync 与 maintain lint 也会失败。';
+        const tail = '\n' + (steps.length + 1) +
+          '. 处理完成后重新执行本命令，插件会自动将「设定」目录创建为 llm-wiki 项目。';
+        return head + detailLine + consequence + '\n处理办法：\n' + steps.join('\n') + tail;
+      }
+
+      case 'setup_id_reused': {
+        const sourceText = {
+          cache: 'llm-wiki 已建好的设定项目',
+          deployed: '本项目 .fancy-deployed 已记录',
+          remote: 'llm-wiki 项目列表'
+        };
+        return '✅ 复用 setup_id=' + (id || '?') + '（来源：' + (sourceText[source] || '已有记录') + '）';
+      }
+
+      case 'deploy_failed':
+        return '❌ 阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间和目录权限后重试。';
+
+      case 'schema_copy_failed':
+        return '❌ 设定目录准备失败：' + (detail || '未知原因') +
+          '。\n\n请确认 llm-wiki 正在运行，且 .fancy-deployed 里的 llm_wiki_url / llm_wiki_token 正确。' +
+          '插件会先通过 llm-wiki 重建“设定”项目；如果服务不可用，插件不会以空目录继续执行。';
+
+      case 'llm_wiki_not_configured':
+        return '⚠️ llm_wiki 未配置。请在 .fancy-deployed 中配置 llm_wiki_url 和 llm_wiki_token';
+
+      case 'api_failed':
+        return '❌ 调用 llm_wiki API 失败：' + (err || '未知错误') + (extra ? '\n\n' + extra : '');
+
+      case 'phase_started':
+        // 措辞必须准确：agent.send()/followup() 返回 void，只能知道"提示词已入队"，
+        // 真正的模型调用在后续 agent loop 里异步发生（DSH 对 whenIdle 的说明亦明确：
+        // "does not identify the settlement of any particular message"）。
+        // 说"阶段开始"会让用户以为模型已经在写；实际 DeepSeek 侧 401 / 限流 / 超时，
+        // 插件这一侧完全无感，错误只会出现在会话流里。
+        return `✅ ${phase}提示词已发送至会话模型，产物将由模型生成。` + (extra ? '\n\n' + extra : '');
+
+      case 'flesh_incomplete':
+        // 血肉阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
+        // 2026-10 tt5 实测过静默失败——少产出一个文件、全量校验从没跑过，
+        // 而插件早就返回了"阶段开始"。现在血肉阶段改成插件逐批派活，
+        // 没过的批次由插件用脚本判出来并回喂重试，仍没过就把清单摆出来。
+        return '❌ 血肉阶段未完成：部分文件未通过校验，或全量校验（--all）未通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'flesh_complete':
+        // 收尾自检确认跑完了：这时 LLM 那一轮已经结束，"已投递"的说法反而不准
+        return '✅ 血肉阶段完成：8 个 JSON 齐全，全量校验（--all）已通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'stage_dependency_missing':
+        return '❌ ' + (stage || '当前') + '阶段未启动：前置的' + (missing || '上游') + '阶段尚未生成。'
+          + (detail ? '（' + detail + '）' : '')
+          + '\n\n请先执行 `' + (next || '/fancy-build help') + '`，等该阶段完成并通过校验后，再执行当前命令。';
+
+      case 'upstream_not_ready':
+        // 节奏阶段的上游门禁没过：继续跑只会产出废数据，必须在这里挡住
+        return '❌ 节奏阶段未启动：' + (err || '上游阶段未通过全量校验')
+          + '\n\n节奏阶段依赖骨架和血肉两个上游，且两者的全量校验（--all）都必须已通过。'
+          + '请先完成上游阶段，并确认各自的 .stage-status.json 中 all_check.status = PASSED，再执行节奏阶段。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'rhythm_incomplete':
+        // 节奏阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
+        // 节奏的绝大多数校验是跨文件口径的，单文件过了不代表阶段过了。
+        return '❌ 节奏阶段未完成：部分批次未通过校验，或全量校验（--all）未通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'rhythm_complete':
+        return '✅ 节奏阶段完成：4 个 JSON 齐全，全量校验（--all）已通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'skeleton_incomplete':
+        // 骨架阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
+        // 引用完整性 / 图连通性 / 配额一致性都要全量校验才判得了。
+        return '❌ 骨架阶段未完成：部分批次未通过校验，或全量校验（--all）未通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'skeleton_complete':
+        return '✅ 骨架阶段完成：4 个 JSON 齐全，全量校验（--all）已通过。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'writing_done':
+        // 必须说清"新写"和"复用"各多少 —— 旧文案只写 count，
+        // 全章都已存在时 count=0，出来的是"0 章全部写完并通过逐章校验"，
+        // 用户会以为没有需要写的章，实际可能是全书都没写。
+        return '✅ 写作阶段完成：新写 ' + count + ' 章' +
+          (reused > 0 ? '，复用 ' + reused + ' 章（已复检通过）' : '') +
+          '；全部章节逐章校验通过。' + (extra ? '\n\n' + extra : '');
+
+      case 'writing_incomplete':
+        return '❌ 写作阶段结束，但有 ' + failed.length + ' 章未通过校验（已写 ' + written + ' 章' +
+          (reused > 0 ? '，复用 ' + reused + ' 章（已复检通过）' : '') +
+          '）。未通过章号：' + failed.join('、') +
+          '。请修复对应章节后重新执行本命令；已完成的章节将自动跳过。' + (extra ? '\n\n' + extra : '');
+
+      case 'deslop_no_chapters':
+        return '❌ 去味阶段没有可处理的章节：写作目录中未找到 `第NNN章.md` 文件。'
+          + '（目录：' + (extra || '未知') + '）请先运行 /fancy-build write all 生成正文。';
+
+      case 'deslop_done':
+        return `✅ 去味阶段完成：${count} 章已处理（${clean} 章原本已符合要求，${passed} 章改写后复扫通过）。`
+          + (extra ? '\n\n' + extra : '');
+
+      case 'deslop_incomplete':
+        return `❌ 去味阶段结束，但有 ${failed.length} 章未通过去味校验（其中 ${rolledBack} 章改动超 35% 已被回滚，${errored} 章执行出错）。`
+          + '问题章号：' + (failed.length ? failed.join('、') : '无') + '。'
+          + '原文已备份在 `设定/raw/sources/写作/.revisions/`，报告见 `审查报告/`。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'no_subcommand':
+        return `⚠️ 请指定阶段：
+
+/fancy-build scale
+/fancy-build macro
+/fancy-build cast
+/fancy-build rhythm
+/fancy-build outline [CH001 | 1-10 | all]
+/fancy-build write [CH001 | 1-10 | all]
+/fancy-build deslop [CH001 | 1-10 | all]
+/fancy-build help`;
+
+      case 'no_sources_dir':
+        return '⚠️ 未找到 raw/sources 目录。请先执行骨架、血肉或节奏阶段，生成设定文件。';
+
+      case 'no_files_to_ingest':
+        return '⚠️ raw/sources 目录中未找到可 ingest 的文件。';
+
+      case 'ingest_started':
+        return `✅ 已启动 ingest，共 ${fileCount} 个文件正在处理。稍后可执行 /fancy-build maintain lint 进行检查。` + (extra ? '\n\n' + extra : '');
+
+      case 'ingest_failed':
+        return '❌ ingest 失败：' + (err || '未知错误');
+
+      case 'ingest_not_ready':
+        return `⚠️ ingest 尚未完成。当前有 ${missingCount} 个文件未处理，${queueCount} 个任务进行中。请等待 ingest 结束后再执行分析。`;
+
+      case 'sync_done':
+        return '✅ 故事对象已同步到 llm_wiki。' + (extra ? '\n\n' + extra : '');
+
+      case 'sync_failed':
+        return '❌ 同步到 llm_wiki 失败。' + (extra ? '\n\n' + extra : '');
+
+      case 'query_done':
+        return extra || '💬 查询完成';
+
+      case 'lint_done':
+        return '❌ 检查发现问题' + (extra ? '\n\n' + extra : '') +
+          '\n\n💡 可执行 `/fancy-build fix`：插件会把问题归因到骨架/血肉/节奏，发给 LLM 修复、跑阶段校验并重新 sync。';
+
+      case 'lint_clean':
+        return '✅ 检查通过' + (extra ? '\n\n' + extra : '');
+
+      case 'stage_materialize_failed':
+        return '❌ ' + (phase || '当前') + '阶段数据已完成，但同步到 llm_wiki 失败。'
+          + (extra ? '\n\n' + extra : '');
+
+      case 'patch_done':
+        return extra || '✅ patch 完成';
+
+      case 'patch_cancelled':
+        return '已取消 patch，未修改任何文件。';
+
+      default:
+        return String(type);
+    }
+  },
+
+  /**
+   * 子命令询问
+   */
+  askSubcommand() {
+    return {
+      id: 'subcommand',
+      question: '请选择要执行的阶段：',
+      options: [
+        { label: 'scale', description: '10-scale：只算章/卷/幕/配额/节奏预算' },
+        { label: 'macro', description: '20-macro：世界观、卷纲、幕纲、主支线、结局、角色功能位' },
+        { label: 'cast', description: '30-cast：人物、势力、地点、冲突、伏笔、爽点、关系、信息差' },
+        { label: 'rhythm', description: '40-rhythm：章节地图；--full 同时生成全部细纲' },
+        { label: 'outline', description: '40-rhythm：单章细纲 outline CH001 / outline all' },
+        { label: 'writing', description: '50-writing：按单章细纲写正文' },
+        { label: 'sync', description: '同步阶段闭包到 llm_wiki（首次正式同步在 30-cast）' },
+        { label: 'query', description: '向 llm_wiki 提问：query <问题>' },
+        { label: 'lint', description: 'schema / link / 语义检查（30-cast 通过后）' },
+        { label: 'patch', description: '按 manifest 依赖图修订：patch <意见>' },
+        { label: 'help', description: '显示全部子命令说明' },
+      ],
+    };
+  },
+
+  /**
+   * 生成骨架阶段的系统提示词
+   */
+  generateSkeletonSystemPrompt({ topicData, wikiReferences }) {
+    const {
+      book_name,
+      genre,
+      target_words,
+      target_chapters,
+      positioning,
+      core_conflict,
+      hard_constraints,
+      anti_tropes,
+    } = topicData;
+
+    // 读取骨架阶段提示词模板（prompts/01-skeleton-prompt.md）
+    let prompt = cleanPromptForLLM(readBuiltInReference('01-skeleton-prompt.md'));
+
+    // 替换变量
+    prompt = prompt.replace(/\$\{genre\}/g, textField(genre));
+    prompt = prompt.replace(/\$\{book_name\}/g, textField(book_name));
+    prompt = prompt.replace(/\$\{target_words\}/g, textField(target_words));
+    prompt = prompt.replace(/\$\{target_chapters\}/g, textField(target_chapters));
+    prompt = prompt.replace(/\$\{positioning\}/g, textField(positioning));
+    prompt = prompt.replace(/\$\{core_conflict\}/g, textField(core_conflict));
+    prompt = prompt.replace(/\$\{hard_constraints\}/g, joinField(hard_constraints));
+    prompt = prompt.replace(/\$\{anti_tropes\}/g, joinField(anti_tropes));
+    prompt = prompt.replace(/\$\{wikiReferences\}/g, wikiReferences || '');
+
+    return prompt;
+  },
+
+  /**
+   * 生成血肉阶段的系统提示词
+   *
+   * inputSnapshot：骨架阶段 框架.json 里的任务输入快照（权威来源）。
+   * 缺省时退回 topicData 拼一份（骨架产物还没落盘的兜底）。
+   */
+  generateFleshSystemPrompt({ topicData, wikiReferences, inputSnapshot }) {
+    const { book_name, genre, target_chapters, positioning, hard_constraints, anti_tropes } = topicData;
+
+    // 读取血肉阶段提示词模板（prompts/02-flesh-prompt.md）
+    let prompt = cleanPromptForLLM(readBuiltInReference('02-flesh-prompt.md'));
+
+    // 替换变量
+    prompt = prompt.replace(/\$\{book_name\}/g, textField(book_name));
+    prompt = prompt.replace(/\$\{genre\}/g, textField(genre));
+    prompt = prompt.replace(/\$\{target_chapters\}/g, textField(target_chapters));
+    // 血肉 prompt 文件暂未引用，但保持幂等
+    prompt = prompt.replace(/\$\{hard_constraints\}/g, joinField(hard_constraints));
+    prompt = prompt.replace(/\$\{anti_tropes\}/g, joinField(anti_tropes));
+    prompt = prompt.replace(/\$\{wikiReferences\}/g, wikiReferences || '');
+
+    // 任务输入清单：优先用骨架阶段的 input_snapshot 快照
+    const snapshot = inputSnapshot || snapshotFromTopicData(topicData);
+    prompt = prompt.replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot));
+
+    // 移除残余的 ${...} 占位符
+    prompt = prompt.replace(/\$\{[a-z_]+\}/g, '');
+
+    return prompt;
+  },
+
+  /**
+   * 生成血肉阶段的**单轮派活提示词**。
+   *
+   * 血肉阶段改成插件驱动之后，提示词不再是"一次投喂、LLM 自己跑完 8 个文件"的
+   * 执行手册，而是"每批带一遍"的产物契约 + 本轮任务：
+   *   - 契约段：从 02-flesh-prompt.md 按小节抽取（总纲/铁律/本文件字段契约/质量正反例…）
+   *   - 本轮任务：写哪个文件、哪些条目、写成什么格式
+   *   - 重试轮：脚本判出来的错误清单 + 只改被点名字段的要求
+   *
+   * @param {Object} opts
+   * @param {Object} opts.batch        批次描述（stage-batches.js 产出）
+   * @param {number} [opts.attempt]    第几次尝试（1 = 首次，>1 = 重试）
+   * @param {Array}  [opts.failures]   上一轮校验判出来的错误
+   * @param {Array}  [opts.relations]  与本批相关的骨架关系（已渲染成文本行）
+   * @param {string} [opts.stageDir]   血肉目录（相对项目根）
+   * @param {string} [opts.buildDir]   分片目录（相对项目根）
+   * @param {Object} [opts.inputSnapshot] 骨架 input_snapshot
+   * @param {Object} [opts.topicData]
+   * @returns {string} 提示词全文
+   */
+  generateFleshBatchPrompt(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+
+    const contract = readBuiltInReference('02-flesh-prompt.md');
+    const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
+    const withSnapshot = absolutizeInlinePaths(
+      contract
+        .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
+        .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || ''),
+      o.projectRoot
+    );
+
+    // 首轮带全量契约；重试轮只带"本文件字段契约 + 质量 + 错误码速查"，
+    // 任务输入在首轮已经建立，后续轮不必重复。
+    const names = isRetry
+      ? ['overview', 'file:' + batch.type, 'quality', 'errors', 'forbidden']
+      : ['overview', 'input', 'rules', 'refs', 'file:' + batch.type, 'quality', 'forbidden'];
+    const picked = pickContractSections(withSnapshot, names);
+    if (picked.missing.length) {
+      // 契约小节缺失是提示词文件的结构问题，必须让调用方知道
+      throw new Error('血肉契约缺少小节：' + picked.missing.join('、'));
+    }
+
+    const parts = [picked.text];
+    parts.push('');
+    parts.push('---');
+    parts.push('');
+    if (o.benchmarkDigest) {
+      // 摘要正文必须每轮都在：重试轮不抽 refs 小节，但参考不能跟着消失。
+      parts.push(String(o.benchmarkDigest).trim());
+      parts.push('');
+      parts.push('---');
+      parts.push('');
+    }
+    parts.push(this.buildFleshBatchTask({ batch, attempt, failures: o.failures, relations: o.relations, stageDir: o.stageDir, buildDir: o.buildDir }));
+
+    return parts.join('\n');
+  },
+
+  /**
+   * 生成节奏阶段的**单轮派活提示词**。
+   *
+   * 与血肉同构（契约 + 本轮任务），但多两样：
+   *   - 本轮涉及的章号在**时序映射**里的对应信息（章节号唯一真源在时序映射，
+   *     细纲/规划的章号必须跟它对齐）
+   *   - 上一批的收尾（章节按时间推进，第 N 章要承接第 N-1 章）
+   *
+   * @param {Object} opts
+   * @param {Object} opts.batch        批次描述
+   * @param {number} [opts.attempt]    第几次尝试
+   * @param {Array}  [opts.failures]   上一轮校验判出来的错误
+   * @param {Array}  [opts.chapterRefs] 本批章号在时序映射里的对应信息（文本行）
+   * @param {string} [opts.prevTail]   上一批收尾（文本）
+   * @param {string} [opts.stageDir]
+   * @param {string} [opts.buildDir]
+   * @param {Object} [opts.inputSnapshot]
+   * @param {Object} [opts.topicData]
+   * @returns {string} 提示词全文
+   */
+  generateRhythmBatchPrompt(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+
+    const contract = readBuiltInReference('03-rhythm-prompt.md');
+    const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
+    const withSnapshot = absolutizeInlinePaths(
+      contract
+        .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
+        .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || ''),
+      o.projectRoot
+    );
+
+    const names = isRetry
+      ? ['overview', 'file:' + batch.type, 'consistency', 'errors', 'forbidden']
+      : ['overview', 'input', 'rules', 'refs', 'file:' + batch.type, 'consistency', 'forbidden'];
+    const picked = pickContractSections(withSnapshot, names);
+    if (picked.missing.length) {
+      throw new Error('节奏契约缺少小节：' + picked.missing.join('、'));
+    }
+
+    const parts = [picked.text, '', '---', ''];
+    if (o.benchmarkDigest) {
+      // 摘要正文必须每轮都在：重试轮不抽 refs 小节，但参考不能跟着消失。
+      parts.push(String(o.benchmarkDigest).trim());
+      parts.push('', '---', '');
+    }
+    parts.push(this.buildRhythmBatchTask({
+      batch: batch,
+      attempt: attempt,
+      failures: o.failures,
+      chapterRefs: o.chapterRefs,
+      prevTail: o.prevTail,
+      extraContext: o.extraContext,
+      stageDir: o.stageDir,
+      buildDir: o.buildDir
+    }));
+    return parts.join('\n');
+  },
+
+  /**
+   * 节奏单轮任务区块：写哪个文件、写哪几章/哪些条目、写成什么格式。
+   */
+  buildRhythmBatchTask(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+    const stageDir = o.stageDir || '设定/raw/sources/节奏';
+    const buildDir = o.buildDir || stageDir + '/.rhythm-build';
+    const shardPath = buildDir + '/' + batch.shard;
+    const targetPath = stageDir + '/' + batch.file;
+
+    const lines = [];
+    lines.push('# 本轮派活：' + batch.file + ' / ' + (batch.groupKey || 'whole'));
+    lines.push('');
+    lines.push('这是第 ' + attempt + ' 次写这一批。**只写下面列出的内容**，写到指定文件，写完就停。');
+    lines.push('');
+
+    if (isRetry) {
+      lines.push('## 上一轮校验没通过（脚本判出来的错误）');
+      lines.push('');
+      const failures = o.failures || [];
+      if (!failures.length) {
+        lines.push('（错误清单为空，按上一轮的字段要求重写这一批。）');
+      } else {
+        for (const f of failures) {
+          lines.push('- [' + (f.code || 'ERROR') + '] ' + (f.path || '(无路径)') + '：' + (f.message || '') + (f.hint ? '（' + f.hint + '）' : ''));
+        }
+      }
+      lines.push('');
+      lines.push('**只修上面点名的字段**，其余内容保持原样。');
+      lines.push('');
+    }
+
+    lines.push('## 要写到哪里');
+    lines.push('');
+    lines.push('- 文件路径：`' + shardPath + '`');
+    lines.push('- 这是一个**分片**文件：只包含本批内容，不要包含别的，也不要动 `' + targetPath + '`。');
+    lines.push('- 如果需要看已产出的内容（保持一致用），可以读 `' + targetPath + '`，但**不要修改它**。');
+    lines.push('');
+
+    lines.push('## 文件格式');
+    lines.push('');
+    if (batch.wholeObject) {
+      lines.push('这个文件是一个 JSON 对象（没有顶层数组）。顶层键固定为：');
+      lines.push('');
+      lines.push('```');
+      lines.push('{');
+      lines.push('  "branch_chapter_total": <整数>,');
+      lines.push('  "overlap_chapter_count": <整数>,');
+      lines.push('  "main_progress_chapter_count": <整数>,');
+      lines.push('  "chapter_hook_rate": { "rate": <小数>, "is_minimum": <true|false> },');
+      lines.push('  "derivations": { ...7 条约束名... }');
+      lines.push('}');
+      lines.push('```');
+      lines.push('');
+      lines.push('**先算参数再填**：按「节奏参数」那一节的步骤 1-7 反推可行区间，不要试错。');
+    } else {
+      const arrays = batch.arrays || [batch.groupKey];
+      const shape = arrays.map((a) => '  "' + a + '": [ ... ]').join(',\n');
+      lines.push('文件内容是一个 JSON 对象，顶层键固定为：');
+      lines.push('');
+      lines.push('```');
+      lines.push('{');
+      lines.push(shape);
+      lines.push('}');
+      lines.push('```');
+      lines.push('');
+      lines.push('键的顺序、缩进不重要，但**顶层键名不能改**，数组里只能有本批条目。');
+    }
+    lines.push('');
+
+    if (batch.byChapter) {
+      const chapters = (batch.items || []).map((it) => it.ch);
+      lines.push('## 本批要写的章（' + chapters.length + ' 章）');
+      lines.push('');
+      lines.push(chapters.join(', '));
+      lines.push('');
+      lines.push('**只写这些章，章号原样抄。**');
+      lines.push('');
+    } else if (batch.rowsMode === 'optional') {
+      lines.push('## 本批负责的关系阶段（可 0 行）');
+      lines.push('');
+      lines.push('本批写 `' + batch.groupKey + '` 里 `' + (batch.ownerField || 'from') + '` 属于下表这些角色的行：');
+      lines.push('');
+      lines.push('| id | name |');
+      lines.push('|---|---|');
+      for (const item of batch.items || []) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**没有关系变化就写空数组 `[]`**；有关系变化才写行，不要为了凑数硬编。');
+      lines.push('每行只写一个阶段：`from` / `to` / `stage` / `state` / `start_chapter`，可选 `end_chapter` / `trigger_event` / `description`。');
+      lines.push('同一对角色按 `start_chapter` 严格递增；`from` 必须是上表里的角色 id。');
+      lines.push('');
+    } else if (!batch.wholeObject) {
+      lines.push('## 本批要写的条目（' + batch.count + ' 条）');
+      lines.push('');
+      lines.push('| id | name |');
+      lines.push('|---|---|');
+      for (const item of batch.items || []) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**id 和 name 原样抄，不要改一个字符。**');
+      lines.push('');
+    }
+
+    if (o.chapterRefs && o.chapterRefs.length) {
+      lines.push('## 本批章号在时序映射里的对应信息（章节号唯一真源）');
+      lines.push('');
+      for (const line of o.chapterRefs) lines.push(line);
+      lines.push('');
+      lines.push('**本批的章号、钩子、高潮、结局必须与上面一致**；不一致会被全量校验拦下。');
+      lines.push('');
+    }
+
+    if (o.prevTail) {
+      lines.push('## 上一批收尾（承接用）');
+      lines.push('');
+      lines.push(o.prevTail);
+      lines.push('');
+    }
+
+    if (o.extraContext && o.extraContext.length) {
+      lines.push('## 本批需要的对照数据（插件从上游读出，原样照抄）');
+      lines.push('');
+      for (const line of o.extraContext) lines.push(line);
+      lines.push('');
+    }
+
+    lines.push(referenceLogPromptBlock('节奏', batch));
+    lines.push('## 交付');
+    lines.push('');
+    lines.push('写完 `' + shardPath + '` 就结束本轮。');
+    lines.push('');
+    lines.push('**只回一句话**（例：`已写入 骨架-层级.b24.branch_span.json，10 条`），然后停下：');
+    lines.push('');
+    lines.push('- 不要解释设计思路、不要罗列自己检查过哪些项');
+    lines.push('- **不要引用错误码说"满足 XXX 要求"** —— 通过与否由插件的校验脚本判定，不是你说了算');
+    lines.push('- 不要宣布完成、不要运行任何校验脚本');
+    lines.push('');
+
+    return lines.join('\n');
+  },
+
+  /**
+   * 血肉单轮任务区块：写哪个文件、写哪几条、写成什么格式。
+   */
+  buildFleshBatchTask(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+    const stageDir = o.stageDir || '设定/raw/sources/血肉';
+    const buildDir = o.buildDir || stageDir + '/.flesh-build';
+    const shardPath = buildDir + '/' + batch.shard;
+    const targetPath = stageDir + '/' + batch.file;
+
+    const lines = [];
+    lines.push('# 本轮派活：' + batch.file + ' / ' + batch.groupKey);
+    lines.push('');
+    lines.push('这是第 ' + attempt + ' 次写这一批。**只写下面列出的条目**，写到指定文件，写完就停。');
+    lines.push('');
+
+    if (isRetry) {
+      lines.push('## 上一轮校验没通过（脚本判出来的错误）');
+      lines.push('');
+      const failures = o.failures || [];
+      if (!failures.length) {
+        lines.push('（错误清单为空，按上一轮的字段要求重写这一批。）');
+      } else {
+        for (const f of failures) {
+          lines.push('- [' + (f.code || 'ERROR') + '] ' + (f.path || '(无路径)') + '：' + (f.message || '') + (f.hint ? '（' + f.hint + '）' : ''));
+        }
+      }
+      lines.push('');
+      lines.push('**只修上面点名的字段**，其余内容保持原样（包括已经写对的条目）。');
+      lines.push('');
+    }
+
+    lines.push('## 要写到哪里');
+    lines.push('');
+    lines.push('- 文件路径：`' + shardPath + '`');
+    lines.push('- 这是一个**分片**文件：只包含本批条目，不要包含别的条目，也不要动 `' + targetPath + '`。');
+    lines.push('- 如果需要看本文件已经写了什么（保持一致用），可以读 `' + targetPath + '`，但**不要修改它**。');
+    lines.push('');
+
+    lines.push('## 文件格式');
+    lines.push('');
+    const arrays = batch.arrays || [batch.groupKey];
+    const shape = arrays.map((a) => '  "' + a + '": [ ... ]').join(',\n');
+    lines.push('文件内容是一个 JSON 对象，顶层键固定为：');
+    lines.push('');
+    lines.push('```');
+    lines.push('{');
+    lines.push(shape);
+    lines.push('}');
+    lines.push('```');
+    lines.push('');
+    lines.push('键的顺序、缩进不重要，但**顶层键名不能改**，数组里只能有本批条目。');
+    lines.push('');
+
+    lines.push('## 本批要写的条目（' + batch.count + ' 条）');
+    lines.push('');
+    if (batch.free) {
+      lines.push('这一组没有骨架条目，需要你自己写 **' + batch.count + ' 条**。');
+      if (batch.groupKey === 'rule_conflict_plan') {
+        lines.push('写规则之间的冲突预案：每条两句话——`contradiction` 是哪两条规则（或规则与核心冲突）打架，`solution` 是怎么化解。');
+      }
+    } else {
+      lines.push('| id | name | 类型 |');
+      lines.push('|---|---|---|');
+      for (const item of batch.items || []) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' | ' + (item.type || item.category || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**id 和 name 原样抄，不要改一个字符。**');
+    }
+    lines.push('');
+
+    if (batch.detailArray) {
+      lines.push('## 道具详情必须同时写');
+      lines.push('');
+      lines.push('本批每个条目都要在 `' + batch.detailArray + '` 数组里写一条**同 id 同 name** 的详情（模板字段：id/name/type/appearance/origin/function_detail/limit/related_characters/related_conflicts）。');
+      lines.push('`related_characters` 写角色**名字**，`related_conflicts` 写冲突**名字**。');
+      lines.push('');
+    }
+
+    if (o.relations && o.relations.length) {
+      lines.push('## 骨架里与本批相关的关系（必须照抄）');
+      lines.push('');
+      for (const line of o.relations) lines.push(line);
+      lines.push('');
+    }
+
+    lines.push(referenceLogPromptBlock('血肉', batch));
+    lines.push('## 交付');
+    lines.push('');
+    lines.push('写完 `' + shardPath + '` 就结束本轮。');
+    lines.push('');
+    lines.push('**只回一句话**（例：`已写入 骨架-层级.b24.branch_span.json，10 条`），然后停下：');
+    lines.push('');
+    lines.push('- 不要解释设计思路、不要罗列自己检查过哪些项');
+    lines.push('- **不要引用错误码说"满足 XXX 要求"** —— 通过与否由插件的校验脚本判定，不是你说了算');
+    lines.push('- 不要宣布完成、不要运行任何校验脚本');
+    lines.push('');
+
+    return lines.join('\n');
+  },
+
+  /**
+   * 生成节奏阶段的系统提示词
+   *
+   * inputSnapshot：骨架阶段 框架.json 里的任务输入快照（权威来源）。
+   *
+   * @deprecated 节奏阶段已改成插件逐批派活（2026-10），
+   *   实际用的是 generateRhythmBatchPrompt —— 它按批次从契约里抽小节，
+   *   单轮提示词只有十几 KB。这里保留整份提示词的拼装逻辑，
+   *   供骨架阶段迁移到同一 driver 之后做对照与回归。
+   */
+  /**
+   * 生成骨架阶段的单轮提示词。
+   *
+   * 骨架是第一个阶段：没有上游可读，任务输入直接来自选题。
+   * 契约按批次抽小节 —— 框架那一批带公式拓扑，实体/关系/层级那几批
+   * 只带自己那个文件的字段契约，不带公式（公式只有框架用得上）。
+   *
+   * @param {Object} opts
+   * @param {Object} opts.batch        批次描述
+   * @param {number} [opts.attempt]    第几次尝试
+   * @param {Array}  [opts.failures]   上一轮校验判出来的错误
+   * @param {Array}  [opts.idTables]   可引用的 id 表（文本行，关系批次用）
+   * @param {Array}  [opts.extraContext] 本批需要的对照数据（文本行）
+   * @param {string} [opts.stageDir]
+   * @param {string} [opts.buildDir]
+   * @param {Object} [opts.inputSnapshot]
+   * @param {Object} [opts.topicData]
+   * @returns {string} 提示词全文
+   */
+  generateSkeletonBatchPrompt(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+
+    const contract = readBuiltInReference('01-skeleton-prompt.md');
+    const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
+    const withSnapshot = absolutizeInlinePaths(
+      contract
+        .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
+        // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+        .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || ''),
+      o.projectRoot
+    );
+
+    const names = isRetry
+      ? ['overview', 'file:' + batch.type, 'consistency', 'errors', 'forbidden']
+      : ['overview', 'input', 'rules', 'refs', 'file:' + batch.type, 'consistency', 'forbidden'];
+    const picked = pickContractSections(withSnapshot, names);
+    if (picked.missing.length) {
+      throw new Error('骨架契约缺少小节：' + picked.missing.join('、'));
+    }
+
+    const parts = [picked.text, '', '---', ''];
+    if (o.benchmarkDigest) {
+      // 摘要正文必须每轮都在：重试轮不抽 refs 小节，但参考不能跟着消失。
+      parts.push(String(o.benchmarkDigest).trim());
+      parts.push('', '---', '');
+    }
+    parts.push(this.buildSkeletonBatchTask({
+      batch: batch,
+      attempt: attempt,
+      failures: o.failures,
+      idTables: o.idTables,
+      extraContext: o.extraContext,
+      existingEntities: o.existingEntities,
+      stageDir: o.stageDir,
+      buildDir: o.buildDir
+    }));
+    return parts.join('\n');
+  },
+
+  /**
+   * 从模板 JSON 生成"本批字段的类型契约"（**动态注入，不手写**）。
+   *
+   * 为什么要动态生成：模板 JSON 是校验器和提示词的**共同真源**，
+   * 手写类型表一定会漂移。
+   *
+   * 线上实测（tt5 2026-10-25）：关系模板里 protagonist_side /
+   * secondary_antagonist / third_party 是**字符串数组**，
+   * 而提示词只列了字段名、没说是数组（prompts/01-skeleton-prompt.md:346-356），
+   * 模型就写成了字符串 → 525 条 TYPE 错误 →
+   * 中途校验反复点名 conflict_participants 这批 →
+   * 3 次重启上限 → 关系段停摆 → 层级段没开工 → 骨架阶段未完成。
+   *
+   * @param {Object} batch 批次描述
+   * @returns {string[]} 提示词行（空数组 = 本批没有可说明的字段）
+   */
+  renderSkeletonFieldTypes(batch) {
+    const templateFile = batch && batch.template;
+    if (!templateFile) return [];
+    let tpl;
+    try {
+      tpl = JSON.parse(readFileSync(join(__dirname, 'templates', '骨架', templateFile), 'utf-8'));
+    } catch {
+      return [];
+    }
+    const props = (tpl && tpl.structure && tpl.structure.properties) || null;
+    if (!props || typeof props !== 'object') return [];
+
+    const lines = [];
+    lines.push('## 字段类型（**照这张表写，不要猜**）');
+    lines.push('');
+    lines.push('下面每个字段的类型都是**硬要求**：类型写错校验器会直接报 TYPE 错误，' +
+      '同一个批次反复报同类错误就会触发中途校验的重启上限，整段停摆。');
+    lines.push('');
+
+    const wanted = [];
+    for (const a of (batch.arrays || [])) {
+      if (a && wanted.indexOf(a) < 0) wanted.push(a);
+    }
+
+    // 整文件型产物（框架）：顶层键不是数组，说明它们各自的类型
+    if (!wanted.length) {
+      for (const k of Object.keys(props)) {
+        const spec = props[k];
+        if (!spec || spec.type === 'array') continue;
+        lines.push('- ' + k + '：' + skeletonTypeLabel(spec));
+      }
+      lines.push('');
+      return lines.length > 4 ? lines : [];
+    }
+
+    for (const arrayName of wanted) {
+      const spec = props[arrayName];
+      if (!spec || spec.type !== 'array') continue;
+      const itemProps = (spec.items && spec.items.properties) || null;
+      if (!itemProps) continue;
+      lines.push('**' + arrayName + '** 每一行的字段：');
+      lines.push('');
+      lines.push('| 字段 | 类型 | 必填 | 取值格式 |');
+      lines.push('|---|---|---|---|');
+      for (const field of Object.keys(itemProps)) {
+        const fieldSpec = itemProps[field];
+        lines.push('| ' + field + ' | ' + skeletonTypeLabel(fieldSpec) +
+          ' | ' + (fieldSpec && fieldSpec.required ? '是' : '否') +
+          ' | ' + (fieldSpec && fieldSpec.pattern ? fieldSpec.pattern : '无额外限制') + ' |');
+      }
+      lines.push('');
+    }
+    return lines.length > 4 ? lines : [];
+  },
+
+  /**
+   * 骨架单轮任务区块：写哪个文件、写哪个数组、写几条、写成什么格式。
+   *
+   * 与血肉/节奏的差别：
+   *   - 实体批次是**配额驱动**的：条数由框架的 quota 决定，
+   *     所以要逐项告诉模型"主角 2 个、核心配角 6 个"，
+   *     否则模型只能自己猜个数，校验器会报 QUOTA_MISMATCH。
+   *   - 关系批次要填**别类实体**的 id，所以要附可引用的 id 表，
+   *     否则模型只能凭空编 id（SKELETON_REF_MISSING）。
+   */
+  buildSkeletonBatchTask(opts) {
+    const o = opts || {};
+    const batch = o.batch || {};
+    const attempt = o.attempt || 1;
+    const isRetry = attempt > 1;
+    const stageDir = o.stageDir || '设定/raw/sources/骨架';
+    const buildDir = o.buildDir || stageDir + '/.skeleton-build';
+    const shardPath = buildDir + '/' + batch.shard;
+    const targetPath = stageDir + '/' + batch.file;
+
+    const lines = [];
+    lines.push('# 本轮派活：' + batch.file + ' / ' + (batch.groupKey || '整个文件'));
+    lines.push('');
+    // 行数口径不是"每源实体一行"时，开头不能说"只写下面列出的条目"——
+    // 下面列的是关系的两端（id），不是要写的行数（tt5 实测踩过）。
+    const rowsAreItems = batch.rowsMode !== 'quota';
+    lines.push('这是第 ' + attempt + ' 次写这一批。**' +
+      (rowsAreItems ? '只写下面列出的条目' : '只写下面这个数组') + '**，写到指定文件，写完就停。');
+    lines.push('');
+
+    if (isRetry) {
+      lines.push('## 上一轮校验没通过（脚本判出来的错误）');
+      lines.push('');
+      const failures = o.failures || [];
+      if (!failures.length) {
+        lines.push('（错误清单为空，按上一轮的字段要求重写这一批。）');
+      } else {
+        for (const f of failures) {
+          lines.push('- [' + (f.code || 'ERROR') + '] ' + (f.path || '(无路径)') + '：' + (f.message || '') + (f.hint ? '（' + f.hint + '）' : ''));
+        }
+      }
+      lines.push('');
+      lines.push('**只修上面点名的字段**，其余内容保持原样（包括已经写对的条目）。');
+      lines.push('');
+    }
+
+    lines.push('## 要写到哪里');
+    lines.push('');
+    lines.push('- 文件路径：`' + shardPath + '`');
+    lines.push('- 这是一个**分片**文件：只包含本批条目，不要包含别的条目，也不要动 `' + targetPath + '`。');
+    lines.push('- 如果需要看本文件已经写了什么（保持一致用），可以读 `' + targetPath + '`，但**不要修改它**。');
+    lines.push('');
+
+    lines.push('## 文件格式');
+    lines.push('');
+    if (batch.wholeObject) {
+      lines.push('文件内容是一个 JSON 对象，**顶层就是整个框架**，顶层键固定为：');
+      lines.push('');
+      lines.push('```');
+      lines.push('{');
+      lines.push('  "capacity": { ... },');
+      lines.push('  "input_snapshot": { ... },');
+      lines.push('  "quota": { ... },');
+      lines.push('  "volume_ratio": [ ... ],');
+      lines.push('  "derivations": { ... }');
+      lines.push('}');
+      lines.push('```');
+    } else {
+      const arrays = batch.arrays || [batch.groupKey];
+      const shape = arrays.map((a) => '  "' + a + '": [ ... ]').join(',\n');
+      lines.push('文件内容是一个 JSON 对象，顶层键固定为：');
+      lines.push('');
+      lines.push('```');
+      lines.push('{');
+      lines.push(shape);
+      lines.push('}');
+      lines.push('```');
+    }
+    lines.push('');
+    lines.push('键的顺序、缩进不重要，但**顶层键名不能改**，数组里只能有本批条目。');
+    lines.push('');
+    const fieldTypes = this.renderSkeletonFieldTypes(batch);
+    if (fieldTypes.length) {
+      lines.push.apply(lines, fieldTypes);
+      lines.push('');
+    }
+
+    if (batch.wholeObject) {
+      lines.push('## 本批要写的内容');
+      lines.push('');
+      lines.push('本批就是**整个 `' + batch.file + '`**：');
+      lines.push('');
+      lines.push('1. `capacity`：目标章节、目标字数、平均每章字数');
+      lines.push('2. `input_snapshot`：任务输入 8 项，原样照抄');
+      lines.push('3. `quota`：28 个配额字段（数量公式算出来的终值）');
+      lines.push('4. `volume_ratio`：每卷的章节比例，长度 = 卷数，比例之和 = 1.0');
+      lines.push('5. `derivations`：30 条公式推导，一条不多一条不少');
+      lines.push('');
+      lines.push('**下一段的实体清单要按这里的 quota 写**，所以 quota 与 derivations 必须先写对。');
+      lines.push('');
+    } else if (batch.quotaCounts) {
+      if (batch.count === 0) {
+        lines.push('## 本批要写的条目（0 条）');
+        lines.push('');
+        lines.push('这个数组的配额是 0，**一条都不写**，但**顶层键必须存在**（写成空数组 `[]`）。');
+        lines.push('');
+        lines.push('少了这个键，校验器会报 `REQUIRED`（必填字段不得为空），而且这个错归不到任何批次，重试也修不好。');
+        lines.push('');
+      } else {
+        lines.push('## 本批要写的条目（共 ' + batch.count + ' 条）');
+        lines.push('');
+        lines.push('条数由框架的 quota 决定，**严格按下面的分项写**：');
+        lines.push('');
+        lines.push('| 分类 | 条数 |');
+        lines.push('|---|---|');
+        for (const k of Object.keys(batch.quotaCounts)) {
+          lines.push('| ' + k + ' | ' + batch.quotaCounts[k] + ' |');
+        }
+        lines.push('');
+        lines.push('合计 **' + batch.count + ' 条**，写进 `' + batch.groupKey + '` 数组。');
+        lines.push('');
+        lines.push('**条数对不上就会报 `QUOTA_MISMATCH`** —— 校验器是拿框架的 quota 逐类核对实体清单的。');
+        lines.push('');
+      }
+    } else if (batch.rowsMode === 'quota' && batch.rowsSpec) {
+      // 行数由框架 quota 精确决定：必须把**数值和口径**都给模型，
+      // 只说"按 quota 写"它拿不到数（关系批次不投喂框架分节，tt5 实测）。
+      const rs = batch.rowsSpec;
+      lines.push('## 这个数组要写 ' + rs.total + ' 行');
+      lines.push('');
+      lines.push('**行数是硬要求**：`' + batch.groupKey + '` 一共写 **' + rs.total + ' 行**。');
+      lines.push('');
+      lines.push('拆解：`quota.' + rs.quotaPath + ' = ' + rs.pairs + '` 是**无向关系对数**，' +
+        '每一对要写成两行 —— `A→B` 一行、`B→A` 一行，所以总行数 = ' + rs.pairs + ' × ' + rs.multiplier + ' = **' + rs.total + '**。');
+      lines.push('');
+      lines.push('写少了或写多了，校验器会报 `QUOTA_MISMATCH`（path: `quota.' + rs.quotaPath + '`）。');
+      lines.push('');
+      lines.push('下面这些是关系的**两端**（可引用的 id），**不是要写的行数**：');
+      lines.push('');
+      lines.push('| id | name | 类型 |');
+      lines.push('|---|---|---|');
+      for (const item of batch.items) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' | ' + (item.type || item.category || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**id 和 name 原样抄，不要改一个字符。**');
+      lines.push('');
+    } else if (batch.rowsMode === 'optional') {
+      lines.push('## 本批负责的关系阶段（可 0 行）');
+      lines.push('');
+      lines.push('本批写 `' + batch.groupKey + '` 里 `' + (batch.ownerField || 'from') + '` 属于下表这些角色的行：');
+      lines.push('');
+      lines.push('| id | name | 类型 |');
+      lines.push('|---|---|---|');
+      for (const item of batch.items || []) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' | ' + (item.type || item.category || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**没有关系变化就写空数组 `[]`**；有关系变化才写行，不要为了凑数硬编。');
+      lines.push('每行只写一个阶段：`from` / `to` / `stage` / `state` / `start_chapter`，可选 `end_chapter` / `trigger_event` / `description`。');
+      lines.push('同一对角色按 `start_chapter` 严格递增；`from` 必须是上表里的角色 id。');
+      lines.push('');
+    } else if (batch.rowsMode === 'semantic') {
+      // 行数由关系本身决定：**不能说"写 N 条"**。
+      // 以前统一写"本批要写的条目（N 条）…每行一条"，模型把 N 当成真实行数，
+      // 结果角色关系被写成"一个角色一条"（tt5 实测：43 个角色只有 38 个有出边）。
+      lines.push('## 本批负责的关系');
+      lines.push('');
+      lines.push('本批写 `' + batch.groupKey + '` 里 **' +
+        (batch.ownerField ? '`' + batch.ownerField + '` 是上表这些实体' : '归属到上表这些实体') +
+        '** 的关系行' + (batch.ownerField ? '（`' + batch.ownerField + '` 就是这一列 id）' : '') + '：');
+      lines.push('');
+      lines.push('| id | name | 类型 |');
+      lines.push('|---|---|---|');
+      for (const item of batch.items) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' | ' + (item.type || item.category || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**id 和 name 原样抄，不要改一个字符。**');
+      lines.push('');
+      lines.push('**行数不预设** —— 这个数组写几行由关系本身决定，不是"一个实体一条"。' +
+        '按剧情需要写够就行，不要为了凑数硬凑，也不要漏。');
+      lines.push('');
+      lines.push('硬要求只有两条：');
+      lines.push('');
+      lines.push('- 上表每个实体都要在关系里出现（作为关系的哪一端都算），**不能有谁一条关系都没有**（`G_ISOLATED` 会查）');
+      lines.push('- 字段填法、枚举词表、互斥约束见契约第八节');
+      lines.push('');
+    } else if (batch.items && batch.items.length) {
+      lines.push('## 本批要写的条目（' + batch.count + ' 条）');
+      lines.push('');
+      lines.push('| id | name | 类型 |');
+      lines.push('|---|---|---|');
+      for (const item of batch.items) {
+        lines.push('| ' + (item.id || '-') + ' | ' + (item.name || '-') + ' | ' + (item.type || item.category || '-') + ' |');
+      }
+      lines.push('');
+      lines.push('**id 和 name 原样抄，不要改一个字符。**');
+      lines.push('');
+      lines.push('上表每个条目写一行 `' + batch.groupKey + '`，一行一条，不多不少' +
+        (batch.ownerField ? '（这一行里的 `' + batch.ownerField + '` 填上表对应的 id）' : '') + '。');
+      lines.push('');
+    }
+
+    if (o.existingEntities && o.existingEntities.length) {
+      lines.push('## 已经存在的实体（同一实体必须复用，不要换名新建）');
+      lines.push('');
+      lines.push('这些是前面批次已经写进实体清单的 id + name。写本批之前先对照：');
+      lines.push('');
+      lines.push('- 要写的实体已经在表里 → **复用原 id 和 name**，不要改一个字，也不要再建一条。');
+      lines.push('- 同一个人的本名、称呼、绰号、关系称谓（哥哥/父亲/老师/老板等）→ 只保留**本名/正式名**那一条，不要为称呼另建实体。');
+      lines.push('- 同一势力的全称、简称、集团/公司后缀 → 只保留已经存在的正式名，不要重复建。');
+      lines.push('- 表里没有、且确实是新实体 → 才按本批配额新建。');
+      lines.push('');
+      for (const line of o.existingEntities) lines.push(line);
+      lines.push('');
+    }
+
+    if (o.idTables && o.idTables.length) {
+      lines.push('## 可引用的 id（只能从下表里选）');
+      lines.push('');
+      for (const line of o.idTables) lines.push(line);
+      lines.push('');
+      lines.push('**id 填错或引用不存在的 id，校验器会报 `SKELETON_REF_MISSING`。**');
+      lines.push('');
+    }
+
+    if (o.extraContext && o.extraContext.length) {
+      lines.push('## 本批需要的对照数据（插件从上游读出，原样照抄）');
+      lines.push('');
+      for (const line of o.extraContext) lines.push(line);
+      lines.push('');
+    }
+
+    if (Array.isArray(batch.optionalArrays) && batch.optionalArrays.indexOf('other_entities') >= 0) {
+      lines.push('## 题材扩展实体（可选，0-8 条）');
+      lines.push('');
+      lines.push('同一个分片里还要写 `other_entities` 数组。它**不计入上面的条目数**：');
+      lines.push('如果题材里有灵魂、神魂、器灵、妖灵、鬼魂、概念体等**不适合当人物**的存在，就在这里登记；没有就写空数组 `[]`。');
+      lines.push('');
+      lines.push('- id 从 `O001` 起连续编号，三位数字；不要占用人物/势力/道具的 id。');
+      lines.push('- `kind` 写具体类别（灵魂/神魂/器灵/妖灵/鬼魂/概念体/其他），不要只写“其他”。');
+      lines.push('- 只登记会在故事里实际出场、且需要独立关系的存在；不要把普通人物换个名字塞进来。');
+      lines.push('- 它们与人物/其他实体的关系由 `关系.json` 的 `other_relations` 表达（如 `附身`、`寄宿`、`共生`、`镇压`）。');
+      lines.push('');
+    }
+
+    lines.push(referenceLogPromptBlock('骨架', batch));
+    lines.push('## 交付');
+    lines.push('');
+    lines.push('写完 `' + shardPath + '` 就结束本轮。');
+    lines.push('');
+    lines.push('**只回一句话**（例：`已写入 骨架-层级.b24.branch_span.json，10 条`），然后停下：');
+    lines.push('');
+    lines.push('- 不要解释设计思路、不要罗列自己检查过哪些项');
+    lines.push('- **不要引用错误码说"满足 XXX 要求"** —— 通过与否由插件的校验脚本判定，不是你说了算');
+    lines.push('- 不要宣布完成、不要运行任何校验脚本');
+    lines.push('');
+
+    return lines.join('\n');
+  },
+
+  /**
+   * 生成骨架阶段的系统提示词
+   *
+   * inputSnapshot：骨架阶段 框架.json 里的任务输入快照（权威来源）。
+   * 缺省时退回 topicData 拼一份（骨架产物还没落盘的兜底）。
+   */
+  generateRhythmSystemPrompt({ topicData, wikiReferences, inputSnapshot }) {
+    const { book_name, genre, target_chapters } = topicData;
+
+    // 读取节奏阶段提示词模板（prompts/03-rhythm-prompt.md）
+    let prompt = cleanPromptForLLM(readBuiltInReference('03-rhythm-prompt.md'));
+
+    // 替换变量
+    prompt = prompt.replace(/\$\{book_name\}/g, textField(book_name));
+    prompt = prompt.replace(/\$\{genre\}/g, textField(genre));
+    prompt = prompt.replace(/\$\{target_chapters\}/g, textField(target_chapters));
+    prompt = prompt.replace(/\$\{wikiReferences\}/g, wikiReferences || '');
+
+    // 任务输入清单：优先用骨架阶段的 input_snapshot 快照
+    const snapshot = inputSnapshot || snapshotFromTopicData(topicData);
+    prompt = prompt.replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot));
+
+    // 移除残余的 ${...} 占位符
+    prompt = prompt.replace(/\$\{[a-z_]+\}/g, '');
+
+    return prompt;
+  },
+
+  /**
+   * 生成写作阶段的「执行须知」（产物契约）
+   *
+   * 写作阶段改成插件驱动、按批派活之后，写作提示词不再是"一次投喂、
+   * LLM 自己跑完 T 章"的执行手册，而是"每批都带一遍"的产物契约：
+   * 写哪些文件、写成什么格式、什么会被校验拦下、收到错误后怎么改。
+   * 流程（读什么、校验什么、推进到哪一章）由 writing-driver.js 负责。
+   */
+  generateWritingContract({ topicData, benchmarkRefs, benchmarkDigest, projectRoot }) {
+    const { book_name, target_chapters } = topicData || {};
+
+    // 读取写作阶段提示词模板（prompts/04-writing-prompt.md）
+    let prompt = cleanPromptForLLM(readBuiltInReference('04-writing-prompt.md'));
+
+    // 替换变量
+    prompt = prompt.replace(/\$\{book_name\}/g, book_name || '');
+    prompt = prompt.replace(/\$\{target_chapters\}/g, String(target_chapters || ''));
+    // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
+    prompt = prompt.replace(/\$\{benchmark_refs_block\}/g, benchmarkRefs || '');
+    prompt = prompt.replace(/\$\{[a-z_]+\}/g, '');
+    if (benchmarkDigest) {
+      // 摘要正文直接注入，避免模型只收藏路径、写作时完全不看。
+      prompt = prompt + '\n\n' + String(benchmarkDigest).trim();
+    }
+    // 参考文件路径绝对化（基准钉死，见 absolutizeInlinePaths 的说明）
+    prompt = absolutizeInlinePaths(prompt, projectRoot);
+
+    // 追加"合法取值清单" —— 从 reading-power.js（唯一真源）动态生成。
+    //
+    // 为什么动态注入而不是把清单写死在 markdown 里：
+    //   写死两份必然漂移（旧 skill 就是这么坏的：deslop 24 类 / review"19 类" /
+    //   代码 21 类，三份互不一致）。这里保证**模型看到的清单和校验器判定的是同一份**。
+    prompt = prompt + '\n\n' + readingPowerLegend();
+
+    return prompt;
+  },
+
+  /**
+   * 生成去味阶段的「执行须知」（产物契约）
+   *
+   * 与写作阶段的契约同一套思路：提示词只讲"改成什么样"，
+   * 流程（检测哪一章、备份、派活、复扫、判比例、回滚）由 deslop-driver.js 负责。
+   *
+   * 末尾动态追加 24 类 AI 模式清单 —— 从 ai-patterns.js（唯一真源）派生。
+   * 写死一份必然漂移：旧 skill 就坏在这儿（deslop 说 24 类、review 说 19 类、
+   * 代码实现 21 类，三份对不上，模型根本不知道以哪套为准）。
+   */
+  generateDeslopContract({ topicData, projectRoot } = {}) {
+    const { book_name } = topicData || {};
+
+    // 读取去味阶段提示词模板（prompts/05-deslop-prompt.md）
+    let prompt = cleanPromptForLLM(readBuiltInReference('05-deslop-prompt.md'));
+
+    prompt = prompt.replace(/\$\{book_name\}/g, book_name || '');
+    prompt = prompt.replace(/\$\{[a-z_]+\}/g, '');
+    // 参考文件路径绝对化（基准钉死，见 absolutizeInlinePaths 的说明）
+    prompt = absolutizeInlinePaths(prompt, projectRoot);
+
+    // 追加"AI 模式清单" —— 每一类都带改法，模型照着改
+    prompt = prompt + '\n\n' + deslopLegend();
+
+    return prompt;
+  },
+
+  /**
+   * 生成分析阶段的系统提示词
+   */
+  generateAnalyzeSystemPrompt({ topicData, wikiReferences, reviewsContent = '' }) {
+    const { book_name, genre, target_chapters } = topicData;
+
+    // 分析阶段 prompt 直接内置（保持精简，避免和写作 prompt 混淆）
+    const header = `你正在执行**分析阶段**任务，本阶段读上游骨架/血肉/节奏的全文 + llm-wiki 审查结果，输出对全文的一致性 / 矛盾 / 建议的报告。
+
+**核心目标**：
+1. 读取 llm-wiki 给你返回的审查结果（reviewsContent）
+2. 对照骨架/血肉/节奏产物的实际内容，验证每条 review
+3. 输出可执行的修正建议
+
+**严格禁令**：
+- 不得修改 \`模板/\`、\`references/\`、\`设定/\` 下的任何文件
+- 不得自我追加或修改 review；只对现有 review 做确认/质疑/补充说明
+- 报告内容**只输出给用户**，不写入任何文件
+
+**任务输入**：
+- 书名：${book_name}
+- 题材：${genre}
+- 目标章节：${target_chapters}
+
+---
+
+`;
+
+    const reviewBlock = reviewsContent
+      ? `## LLM Wiki 审查结果（已分类）\n\n${reviewsContent}\n\n请逐项回应：\n\n- 对**矛盾**类：定性强弱（强 / 中 / 弱），提具体段落引用\n- 对**确认**类：回 yes/no + 证据\n- 对**建议**类：判断采纳 / 不采纳，并说明理由\n\n---\n\n`
+      : '';
+
+    const wikiBlock = wikiReferences
+      ? `## 同题材参考（仅供风格基线）\n\n${wikiReferences}\n\n---\n\n`
+      : '';
+
+    const outputTemplate = `## 输出格式
+
+\`\`\`markdown
+# 分析阶段报告
+
+## 书名：__BOOK_NAME__
+
+| # | 类型 | 标题 | 强/中/弱 | 回应 |
+|---|------|------|-----------|------|
+| 1 | 矛盾 | ... | ... | ... |
+
+## 中优先级：影响角色弧光的问题
+（说明）
+
+## 低优先级：优化类问题
+（说明）
+
+## 修正优先级清单
+1. 必须改
+2. 建议改
+3. 可不改
+\`\`\`
+
+请基于 reviewsContent 给出报告。没有 review 时直接说明"没有审查项"。`;
+
+return header + wikiBlock + reviewBlock + outputTemplate.replace(/__BOOK_NAME__/g, book_name || '未知');
+  },
+};