@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

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

@@ -8,7 +8,9 @@ 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');
@@ -89,17 +91,53 @@ function joinField(v, sep = '；', fallback = '无') {
  * 那份快照是骨架校验器验过的，更权威。这里只在"骨架产物还没落盘"时兜底。
  */
 function snapshotFromTopicData(topicData) {
-  const t = topicData || {};
-  return {
-    book_name: t.book_name,
-    genre: t.genre,
-    core_summary: t.core_summary,
-    core_conflict: t.core_conflict,
-    hard_constraints: Array.isArray(t.hard_constraints) ? t.hard_constraints : [],
-    anti_tropes: Array.isArray(t.anti_tropes) ? t.anti_tropes : [],
-    target_chapters: t.target_chapters,
-    target_words: t.target_words
-  };
+  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" */
@@ -123,43 +161,67 @@ export const storyBuilder = {
    *
    * 数值给默认值，是为了让"调用方忘了传某个字段"退化成 0 而不是崩。
    */
-  notify({ type, err, phase, id, fileCount, missingCount, queueCount, detail, source, extra,
+  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 '🚫 已取消';
+        return '🚫 操作已取消。';
 
       case 'no_provider':
-        return '⚠️ 当前环境不支持交互式提问。请在 dsh-tui 中运行此命令，或确保 web UI 已正确加载交互组件。';
+        return '⚠️ 当前运行环境不支持交互式提问。请在 dsh-tui 中运行该命令，或确认 Web UI 已正确加载交互组件。';
 
       case 'no_project_root':
-        return '❌ 无法确定项目目录：' + (err || '会话未提供 cwd') + '。请在项目目录下运行该命令。';
+        return '❌ 无法确定当前项目：' + (err || '会话未提供当前工作目录') + '。请在项目目录下运行，或用 /fancy-project use <名字|UUID> 指定当前项目。';
 
       case 'ask_failed':
-        return '❌ 提问失败：' + (err || '未知错误');
+        return '❌ 交互提问失败：' + (err || '未知错误');
 
       case 'not_initialized':
-        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+        return '⚠️ 当前没有可用项目。请先运行 /fancy-bootstrap 初始化工作区，再运行 /fancy-topic setup 创建项目。';
 
       case 'config_corrupt':
-        return '❌ ' + (err || '.fancy-deployed 解析失败') + '';
+        return '❌ ' + (err || '无法解析 .fancy-deployed 状态文件。') + ' 请检查文件内容，或重新运行 /fancy-bootstrap 初始化工作区。';
 
       case 'no_project_root':
         return '❌ ' + (err || '无法确定项目目录');
 
       case 'no_topic':
-        return '⚠️ 未找到选题信息。请先运行 /fancy-topic 进行选题。';
+        return '⚠️ 未找到选题信息。请先运行 /fancy-topic 完成选题。';
 
       case 'setup_id_unavailable': {
         // 分类原因 → 人话 + **针对该原因**的排查步骤。
-        // 此前这里只有一句"未设置 setup_id，请先运行 /fancy-story-builder skeleton"，
+        // 此前这里只有一句"未设置 setup_id，请先运行 /fancy-build skeleton"，
         // 而用户正是运行着这条命令 —— 死胡同，且把真实原因（token 无效 / 服务没起）藏了。
         // 注意：步骤必须按原因分流。给"连不上服务"的人列一堆 token 步骤，
         // 比不给步骤更糟 —— 会把人引到错误的方向上去。
         const reasonText = {
           unauthorized: 'llm-wiki 拒绝了请求（token 无效或服务端未配置 token）',
-          network: '连不上 llm-wiki 服务',
+          network: '无法连接 llm-wiki 服务',
           api_error: 'llm-wiki 返回了错误',
           unexpected_response: 'llm-wiki 返回了非预期结构'
         };
@@ -167,15 +229,15 @@ export const storyBuilder = {
           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'
+            '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',
+            '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 的日志/控制台输出，确认服务端报的具体错误',
+            '1. 查看 llm-wiki 日志或控制台输出，确认服务端返回的具体错误',
             '2. 确认 .fancy-deployed 里的 llm_wiki_url 与 llm_wiki_token 正确'
           ],
           unexpected_response: [
@@ -190,10 +252,10 @@ export const storyBuilder = {
         const head = '❌ 未能建立 llm-wiki 设定项目：' + (reasonText[err] || err || '未知原因');
         const detailLine = detail ? '\n详情：' + detail : '';
         const consequence =
-          '\n\n后果：llm-wiki 侧还不认识本项目的「设定」目录，' +
-          '本阶段产物不会被 ingest 纳管，后续 /fancy-story-builder wiki 与 analyze 阶段也会失败。';
+          '\n\n后果：llm-wiki 尚未识别本项目的「设定」目录，' +
+          '本阶段产物不会被 ingest 纳管，后续 /fancy-build maintain sync 与 maintain lint 也会失败。';
         const tail = '\n' + (steps.length + 1) +
-          '. 处理好后重新执行本命令，插件会自动把「设定」目录建成为 llm-wiki 项目';
+          '. 处理完成后重新执行本命令，插件会自动将「设定」目录创建为 llm-wiki 项目。';
         return head + detailLine + consequence + '\n处理办法：\n' + steps.join('\n') + tail;
       }
 
@@ -207,10 +269,12 @@ export const storyBuilder = {
       }
 
       case 'deploy_failed':
-        return '❌ 阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间与目录权限后重试。';
+        return '❌ 阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间和目录权限后重试。';
 
       case 'schema_copy_failed':
-        return '⚠️ 设定目录准备不完整：' + (detail || '未知原因') + '。本阶段仍会继续，但 schema.md / purpose.md 可能缺失。';
+        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';
@@ -224,14 +288,14 @@ export const storyBuilder = {
         // "does not identify the settlement of any particular message"）。
         // 说"阶段开始"会让用户以为模型已经在写；实际 DeepSeek 侧 401 / 限流 / 超时，
         // 插件这一侧完全无感，错误只会出现在会话流里。
-        return `✅ ${phase}提示词已投递给会话模型，产物由模型生成。` + (extra ? '\n\n' + extra : '');
+        return `✅ ${phase}提示词已发送至会话模型，产物将由模型生成。` + (extra ? '\n\n' + extra : '');
 
       case 'flesh_incomplete':
         // 血肉阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
         // 2026-10 tt5 实测过静默失败——少产出一个文件、全量校验从没跑过，
         // 而插件早就返回了"阶段开始"。现在血肉阶段改成插件逐批派活，
         // 没过的批次由插件用脚本判出来并回喂重试，仍没过就把清单摆出来。
-        return '⚠️ 血肉阶段未完成：部分文件没通过校验，或全量校验（--all）没通过。'
+        return '❌ 血肉阶段未完成：部分文件未通过校验，或全量校验（--all）未通过。'
           + (extra ? '\n\n' + extra : '');
 
       case 'flesh_complete':
@@ -239,17 +303,22 @@ export const storyBuilder = {
         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，再跑节奏阶段。'
+        return '❌ 节奏阶段未启动：' + (err || '上游阶段未通过全量校验')
+          + '\n\n节奏阶段依赖骨架和血肉两个上游，且两者的全量校验（--all）都必须已通过。'
+          + '请先完成上游阶段，并确认各自的 .stage-status.json 中 all_check.status = PASSED，再执行节奏阶段。'
           + (extra ? '\n\n' + extra : '');
 
       case 'rhythm_incomplete':
         // 节奏阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
         // 节奏的绝大多数校验是跨文件口径的，单文件过了不代表阶段过了。
-        return '⚠️ 节奏阶段未完成：部分批次没通过校验，或全量校验（--all）没通过。'
+        return '❌ 节奏阶段未完成：部分批次未通过校验，或全量校验（--all）未通过。'
           + (extra ? '\n\n' + extra : '');
 
       case 'rhythm_complete':
@@ -259,7 +328,7 @@ export const storyBuilder = {
       case 'skeleton_incomplete':
         // 骨架阶段没跑完时不能用"阶段开始"的说法（更不能用 ✅）：
         // 引用完整性 / 图连通性 / 配额一致性都要全量校验才判得了。
-        return '⚠️ 骨架阶段未完成：部分批次没通过校验，或全量校验（--all）没通过。'
+        return '❌ 骨架阶段未完成：部分批次未通过校验，或全量校验（--all）未通过。'
           + (extra ? '\n\n' + extra : '');
 
       case 'skeleton_complete':
@@ -272,46 +341,48 @@ export const storyBuilder = {
         // 用户会以为没有需要写的章，实际可能是全书都没写。
         return '✅ 写作阶段完成：新写 ' + count + ' 章' +
           (reused > 0 ? '，复用 ' + reused + ' 章（已复检通过）' : '') +
-          '。' + (extra ? '\n\n' + extra : '');
+          '；全部章节逐章校验通过。' + (extra ? '\n\n' + extra : '');
 
       case 'writing_incomplete':
-        return '⚠️ 写作阶段结束，但有 ' + failed.length + ' 章未通过校验（已写 ' + written + ' 章' +
+        return '❌ 写作阶段结束，但有 ' + failed.length + ' 章未通过校验（已写 ' + written + ' 章' +
           (reused > 0 ? '，复用 ' + reused + ' 章（已复检通过）' : '') +
           '）。未通过章号：' + failed.join('、') +
-          '。请修好对应章节后重新执行本命令，会自动跳过已写好的章。' + (extra ? '\n\n' + extra : '');
+          '。请修复对应章节后重新执行本命令；已完成的章节将自动跳过。' + (extra ? '\n\n' + extra : '');
 
       case 'deslop_no_chapters':
-        return '⚠️ 去味阶段没有可处理的章节：写作目录里找不到 `第NNN章.md` 文件。'
-          + '（目录：' + (extra || '未知') + '）请先运行 /fancy-story-builder writing 写出正文。';
+        return '❌ 去味阶段没有可处理的章节：写作目录中未找到 `第NNN章.md` 文件。'
+          + '（目录：' + (extra || '未知') + '）请先运行 /fancy-build write all 生成正文。';
 
       case 'deslop_done':
-        return `✅ 去味阶段完成：${count} 章已处理（${clean} 章本来就干净，${passed} 章改写后复扫通过）。`
+        return `✅ 去味阶段完成：${count} 章已处理（${clean} 章原本已符合要求，${passed} 章改写后复扫通过）。`
           + (extra ? '\n\n' + extra : '');
 
       case 'deslop_incomplete':
-        return `⚠️ 去味阶段结束，但有 ${failed.length} 章没改干净（其中 ${rolledBack} 章改动超 35% 已被回滚，${errored} 章执行出错）。`
+        return `❌ 去味阶段结束，但有 ${failed.length} 章未通过去味校验（其中 ${rolledBack} 章改动超 35% 已被回滚，${errored} 章执行出错）。`
           + '问题章号：' + (failed.length ? failed.join('、') : '无') + '。'
           + '原文已备份在 `设定/raw/sources/写作/.revisions/`，报告见 `审查报告/`。'
           + (extra ? '\n\n' + extra : '');
 
       case 'no_subcommand':
-        return `⚠️ 请指定子命令：
-/fancy-story-builder skeleton  - 骨架阶段
-/fancy-story-builder flesh    - 血肉阶段
-/fancy-story-builder rhythm   - 节奏阶段
-/fancy-story-builder writing  - 写作阶段（按节奏的章节细纲逐章写）
-/fancy-story-builder deslop   - 去 AI 味阶段（逐章检测、改写、复扫）
-/fancy-story-builder wiki     - 对设定文件执行 ingest
-/fancy-story-builder analyze  - 分析阶段`;
+        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 目录。请先执行骨架/血肉/节奏阶段生成设定文件。';
+        return '⚠️ 未找到 raw/sources 目录。请先执行骨架、血肉或节奏阶段，生成设定文件。';
 
       case 'no_files_to_ingest':
-        return '⚠️ raw/sources 目录下没有找到可 ingest 的文件。';
+        return '⚠️ raw/sources 目录中未找到可 ingest 的文件。';
 
       case 'ingest_started':
-        return `✅ 已启动 ingest，共 ${fileCount} 个文件正在处理。请稍后执行 /fancy-story-builder analyze 进行分析。` + (extra ? '\n\n' + extra : '');
+        return `✅ 已启动 ingest，共 ${fileCount} 个文件正在处理。稍后可执行 /fancy-build maintain lint 进行检查。` + (extra ? '\n\n' + extra : '');
 
       case 'ingest_failed':
         return '❌ ingest 失败：' + (err || '未知错误');
@@ -319,6 +390,32 @@ export const storyBuilder = {
       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);
     }
@@ -332,10 +429,17 @@ export const storyBuilder = {
       id: 'subcommand',
       question: '请选择要执行的阶段：',
       options: [
-        { label: 'skeleton', description: '骨架阶段：生成核心冲突、角色、框架' },
-        { label: 'flesh', description: '血肉阶段：补充世界观、势力、物品、地点' },
-        { label: 'rhythm', description: '节奏阶段：规划分卷、伏笔、细纲' },
-        { label: 'analyze', description: '分析阶段：检查结构问题' },
+        { 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: '显示全部子命令说明' },
       ],
     };
   },
@@ -349,7 +453,7 @@ export const storyBuilder = {
       genre,
       target_words,
       target_chapters,
-      core_summary,
+      positioning,
       core_conflict,
       hard_constraints,
       anti_tropes,
@@ -363,7 +467,7 @@ export const storyBuilder = {
     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(/\$\{core_summary\}/g, textField(core_summary));
+    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));
@@ -379,7 +483,7 @@ export const storyBuilder = {
    * 缺省时退回 topicData 拼一份（骨架产物还没落盘的兜底）。
    */
   generateFleshSystemPrompt({ topicData, wikiReferences, inputSnapshot }) {
-    const { book_name, genre, target_chapters, core_summary, hard_constraints, anti_tropes } = topicData;
+    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'));
@@ -388,7 +492,6 @@ export const storyBuilder = {
     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(/\$\{core_summary\}/g, textField(core_summary));
     // 血肉 prompt 文件暂未引用，但保持幂等
     prompt = prompt.replace(/\$\{hard_constraints\}/g, joinField(hard_constraints));
     prompt = prompt.replace(/\$\{anti_tropes\}/g, joinField(anti_tropes));
@@ -432,9 +535,12 @@ export const storyBuilder = {
 
     const contract = readBuiltInReference('02-flesh-prompt.md');
     const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
-    const withSnapshot = contract
-      .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
-      .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || '');
+    const withSnapshot = absolutizeInlinePaths(
+      contract
+        .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
+        .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || ''),
+      o.projectRoot
+    );
 
     // 首轮带全量契约；重试轮只带"本文件字段契约 + 质量 + 错误码速查"，
     // 任务输入在首轮已经建立，后续轮不必重复。
@@ -451,6 +557,13 @@ export const storyBuilder = {
     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');
@@ -484,9 +597,12 @@ export const storyBuilder = {
 
     const contract = readBuiltInReference('03-rhythm-prompt.md');
     const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
-    const withSnapshot = contract
-      .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
-      .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || '');
+    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']
@@ -497,6 +613,11 @@ export const storyBuilder = {
     }
 
     const parts = [picked.text, '', '---', ''];
+    if (o.benchmarkDigest) {
+      // 摘要正文必须每轮都在：重试轮不抽 refs 小节，但参考不能跟着消失。
+      parts.push(String(o.benchmarkDigest).trim());
+      parts.push('', '---', '');
+    }
     parts.push(this.buildRhythmBatchTask({
       batch: batch,
       attempt: attempt,
@@ -591,6 +712,21 @@ export const storyBuilder = {
       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('');
@@ -627,6 +763,7 @@ export const storyBuilder = {
       lines.push('');
     }
 
+    lines.push(referenceLogPromptBlock('节奏', batch));
     lines.push('## 交付');
     lines.push('');
     lines.push('写完 `' + shardPath + '` 就结束本轮。');
@@ -731,6 +868,7 @@ export const storyBuilder = {
       lines.push('');
     }
 
+    lines.push(referenceLogPromptBlock('血肉', batch));
     lines.push('## 交付');
     lines.push('');
     lines.push('写完 `' + shardPath + '` 就结束本轮。');
@@ -782,10 +920,13 @@ export const storyBuilder = {
 
     const contract = readBuiltInReference('01-skeleton-prompt.md');
     const snapshot = o.inputSnapshot || snapshotFromTopicData(o.topicData || {});
-    const withSnapshot = contract
-      .replace(/\$\{input_snapshot_block\}/g, renderInputSnapshot(snapshot))
-      // 参考分层说明（插件指导 vs 对标样本）+ 本阶段可读的对标文件清单
-      .replace(/\$\{benchmark_refs_block\}/g, o.benchmarkRefs || '');
+    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']
@@ -796,12 +937,18 @@ export const storyBuilder = {
     }
 
     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
     }));
@@ -1026,6 +1173,21 @@ export const storyBuilder = {
       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 当成真实行数，
@@ -1068,6 +1230,20 @@ export const storyBuilder = {
       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('');
@@ -1084,6 +1260,20 @@ export const storyBuilder = {
       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 + '` 就结束本轮。');
@@ -1134,7 +1324,7 @@ export const storyBuilder = {
    * 写哪些文件、写成什么格式、什么会被校验拦下、收到错误后怎么改。
    * 流程（读什么、校验什么、推进到哪一章）由 writing-driver.js 负责。
    */
-  generateWritingContract({ topicData, benchmarkRefs }) {
+  generateWritingContract({ topicData, benchmarkRefs, benchmarkDigest, projectRoot }) {
     const { book_name, target_chapters } = topicData || {};
 
     // 读取写作阶段提示词模板（prompts/04-writing-prompt.md）
@@ -1146,6 +1336,12 @@ export const storyBuilder = {
     // 参考分层说明（插件指导 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（唯一真源）动态生成。
     //
@@ -1167,7 +1363,7 @@ export const storyBuilder = {
    * 写死一份必然漂移：旧 skill 就坏在这儿（deslop 说 24 类、review 说 19 类、
    * 代码实现 21 类，三份对不上，模型根本不知道以哪套为准）。
    */
-  generateDeslopContract({ topicData } = {}) {
+  generateDeslopContract({ topicData, projectRoot } = {}) {
     const { book_name } = topicData || {};
 
     // 读取去味阶段提示词模板（prompts/05-deslop-prompt.md）
@@ -1175,6 +1371,8 @@ export const storyBuilder = {
 
     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();