@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-analyze/templates.js

@@ -11,6 +11,7 @@
  *   for_write/{voice,sentence_patterns}.md
  *   for_write/phrase_bank/{action,psychology,environment,dialogue}.md
  */
+import { shellSingleQuote } from '#path-guard';
 
 export const CONSUMER_DIRS = {
   bible: [
@@ -79,30 +80,52 @@ function humanAgo(ms, now) {
 function renderSummaryStatus(progress, now) {
   const lines = [];
   const total = progress.total;
-  lines.push('📊 技法总结进度（对标/wiki）');
+  lines.push('📊 总结进度（对标/wiki：按章技法 + 跨章节实体）');
   lines.push('');
 
-  const nameWidth = Math.max(4, ...progress.dirs.map((d) => d.name.length));
+  const displayNameOf = (p) => `${p.name}${p.scope === 'entity' ? ' [实体]' : ''}`;
+  const nameWidth = Math.max(4, ...progress.dirs.map((d) => displayNameOf(d).length));
   const pad = (name) => name + ' '.repeat(nameWidth - name.length);
   const lineOf = (p) => {
+    const isEntity = p.scope === 'entity';
     const parts = [];
     if (p.sourceCount > 0) {
+      const unit = isEntity ? '个实体页' : '章';
       parts.push(p.state === 'done'
-        ? `${p.sourceCount} 章全部已总结`
-        : `已总结 ${p.summarized.length}/${p.sourceCount} 章`);
+        ? `${p.sourceCount} ${unit}全部已总结`
+        : `已总结 ${p.summarized.length}/${p.sourceCount} ${unit}`);
     }
-    parts.push(`${p.entries} 条技法`);
+    parts.push(`${p.entries} 条${isEntity ? '设计原则' : '技法'}`);
     if (p.exists) {
       parts.push(humanBytes(p.bytes));
       parts.push(`${humanAgo(p.updatedAt, now)}更新`);
     }
-    if (p.chapterSource === 'inferred') parts.push('章节清单由正文反推');
-    if (p.chapterSource === 'none' && p.sourceCount > 0) parts.push('无章节清单');
-    return `  · ${pad(p.name)}  ${parts.join(' · ')}`;
+    if (p.chapterSource === 'inferred') {
+      parts.push(isEntity ? '实体清单由正文反推' : '章节清单由正文反推');
+    }
+    if (p.chapterSource === 'none' && p.sourceCount > 0) {
+      parts.push(isEntity ? '无实体清单' : '无章节清单');
+    }
+    return `  · ${pad(displayNameOf(p))}  ${parts.join(' · ')}`;
   };
 
+  if (total === 0
+      && (!progress.legacyDirs || progress.legacyDirs.length === 0)) {
+    lines.push('（对标/wiki 下没有可总结的目录）');
+    return lines.join('\n');
+  }
+
+  if (progress.legacyDirs && progress.legacyDirs.length > 0) {
+    lines.push(`⚠️ 旧版按章结构页（不参与 summary）：${progress.legacyDirs.length} 个目录`);
+    for (const d of progress.legacyDirs) {
+      lines.push(`  · ${d.name}  ${d.pageCount} 个按章页面`);
+    }
+    lines.push('  新版改用跨章节实体页（伏笔布局 / 世界观设计 / 角色弧光设计），重新 ingest 后取代。');
+    lines.push('');
+  }
+
   if (total === 0) {
-    lines.push('（对标/wiki 下没有技法目录）');
+    lines.push('（没有需要总结的目录）');
     return lines.join('\n');
   }
 
@@ -129,34 +152,47 @@ function renderSummaryStatus(progress, now) {
   if (noList.length > 0) {
     lines.push('');
     lines.push(`⚠️ 既无头部「已总结章节」清单、也无法从正文反推：${noList.map((p) => p.name).join('、')}`);
-    lines.push('   这些目录按"全部章节未总结"处理，下次 summary 会重新派发它们。');
+    lines.push('   这些目录按"全部来源未总结"处理，下次 summary 会重新派发它们。');
   }
 
   lines.push('');
-  lines.push('💡 /fancy-analyze summary 只派发"还有章节没总结"的目录；');
-  lines.push('   /fancy-analyze resummary [技法名] 强制重来（会把旧总结移入备份目录）。');
+  lines.push('💡 /fancy-analyze summary 只派发"还有来源没总结"的目录；');
+  lines.push('   /fancy-analyze resummary [目录名] 强制重来（会把旧总结移入备份目录）。');
   return lines.join('\n');
 }
 
 export const analyze = {
   CONSUMER_DIRS,
 
-  notify({ type, bookName, bookNameClean, projectRoot, refDir, matches, err, missingFiles, queue, extraMessage, summary }) {
+  notify({ type, bookName, bookNameClean, projectRoot, refDir, matches, err, missingFiles, queue, extraMessage, coverageMessage, summary, command }) {
     switch (type) {
+      case 'help':
+        return `🔍 对标分析 用法
+
+/fancy-analyze <书名>              拆解爆款小说，产出到 对标/
+/fancy-analyze status              查看拆解与 ingest 状态
+/fancy-analyze fix                 重新 ingest 缺失文件
+/fancy-analyze summary             汇总拆解结果
+/fancy-analyze summary-status      查看汇总进度
+/fancy-analyze resummary [目录名]  强制重新汇总（省略目录名则全部）
+/fancy-analyze help                显示本帮助
+
+作用：拆解工作区 A/参考资料/ 下的爆款小说，产出到 A/对标/，供多个项目共享。`;
+
       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-webnovel 工作区或项目目录下运行，或设置 FANCY_HOME。';
 
       case 'ask_failed':
-        return '❌ 提问失败：' + (err || '未知错误');
+        return '❌ 交互提问失败：' + (err || '未知错误');
 
       case 'not_initialized':
-        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+        return '⚠️ 当前目录不属于已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
 
       case 'deployed_unreadable':
         // .fancy-deployed 存在但读不了。报"未初始化"会把用户引到
@@ -164,30 +200,30 @@ export const analyze = {
         // （文件已存在），等于白跑一趟。
         return `❌ 状态文件 .fancy-deployed 无法读取（${err || '内容异常'}）。
 
-这不是"未初始化"，所以重跑 /fancy-bootstrap 没用。
-请检查该文件是否被手工改坏，或从版本库/备份恢复它。`;
+该状态不是“未初始化”，重新运行 /fancy-bootstrap 无法解决。
+请检查该文件是否被手动修改或损坏，或从版本库/备份恢复。`;
 
       case 'source_dir_missing':
-        return `❌ 参考资料/ 目录不存在：${refDir || ''}
+        return `❌ 工作区的 参考资料/ 目录不存在：${refDir || ''}
 
 请按以下步骤准备：
-1. 创建 参考资料/ 目录
+1. 在工作区根目录创建 参考资料/ 目录（不是 projects/<uuid>/ 项目目录）
 2. 手动下载《${bookName}》，并拷贝到 参考资料/${bookName}.txt
 3. 重新运行 /fancy-analyze ${bookName}
 
-提示：文件名后缀不限（.txt / .md / .epub 都可以），书名匹配忽略后缀。`;
+说明：文件名后缀不限（.txt / .md / .epub 均可），书名匹配时忽略后缀。`;
 
       case 'source_missing': {
         const matchList = (matches && matches.length > 0)
           ? `\n\n参考资料/ 下已有的条目：\n${matches.map(m => `  - ${m}`).join('\n')}`
           : '';
-        return `❌ 找不到《${bookName}》的参考资料${matchList}
+        return `❌ 未找到《${bookName}》的参考资料${matchList}
 
 请按以下步骤准备：
-1. 手动下载《${bookName}》，并拷贝到当前项目的 参考资料/ 目录下
+1. 手动下载《${bookName}》，并拷贝到工作区根目录的 参考资料/ 下（多个项目共享）
 2. 重新运行 /fancy-analyze ${bookName}
 
-提示：匹配书名时忽略后缀。`;
+说明：匹配书名时忽略后缀。`;
       }
 
       case 'source_ambiguous':
@@ -200,7 +236,7 @@ export const analyze = {
         return '❌ 拆分来源文件失败：' + (err || '未知错误');
 
       case 'llm_wiki_not_configured':
-        return '❌ llm_wiki 未配置。请在 .fancy-deployed 中配置 llm_wiki_url 和 llm_wiki_token';
+        return '❌ llm_wiki 未配置。请在 .fancy-deployed 中配置 `llm_wiki_url` 和 `llm_wiki_token`。';
 
       case 'llm_wiki_failed':
         return '❌ 调用 llm_wiki 失败：' + (err || '未知错误');
@@ -218,7 +254,39 @@ export const analyze = {
   2. /fancy-analyze fix      重新提交缺失章节`;
 
       case 'no_reference_id':
-        return '⚠️ 未设置 reference_id。请先运行 /fancy-analyze <书名> 初始化项目';
+        return '⚠️ 尚未设置 reference_id。请先运行 /fancy-analyze <书名> 初始化项目。';
+
+      case 'status_not_analyzed':
+        return '⚠️ 无法执行 status：当前没有任何拆解源文件。\n\n'
+          + '`对标/raw/sources/` 为空，说明尚未执行过 `/fancy-analyze <书名>`。\n'
+          + '请先执行 `/fancy-analyze <书名>` 完成拆书与 ingest，再查看 status。';
+
+      case 'fix_not_analyzed':
+        return '❌ 无法执行 fix：当前没有可修复的拆解产物。\n\n'
+          + '`对标/raw/sources/` 中没有源文件，说明尚未执行过 `/fancy-analyze <书名>`。\n'
+          + '请先执行 `/fancy-analyze <书名>` 完成拆书与 ingest，再执行 fix。';
+
+      case 'summary_ingest_not_ready': {
+        const cmd = command || 'summary';
+        const lines = ['⚠️ ' + cmd + ' 未启动：ingest 尚未完成。'];
+        const q = queue || {};
+        const pending = Number(q.pending) || 0;
+        const processing = Number(q.processing) || 0;
+        const failed = Number(q.failed) || 0;
+        if (missingFiles && missingFiles.length) {
+          lines.push('', '❌ 仍有 ' + missingFiles.length + ' 个源文件未进入 wiki：');
+          for (const f of missingFiles.slice(0, 20)) lines.push('  - ' + f);
+          if (missingFiles.length > 20) lines.push('  - …… 其余 ' + (missingFiles.length - 20) + ' 个省略');
+        }
+        if (pending || processing || failed) {
+          lines.push('', 'ingest 队列：等待 ' + pending + '，处理中 ' + processing + '，失败 ' + failed + '。');
+        }
+        lines.push('', '请等待 ingest 完成；如存在失败或缺失，请执行：');
+        lines.push('1. `/fancy-analyze status` 查看详细状态');
+        lines.push('2. `/fancy-analyze fix` 重新提交缺失/失败的章节');
+        lines.push('3. 确认队列空闲后再执行 `/fancy-analyze ' + cmd + '`');
+        return lines.join('\n');
+      }
 
       case 'status_query_failed':
         return '❌ 查询 ingest 状态失败：' + (err || '未知错误');
@@ -227,7 +295,7 @@ export const analyze = {
         const lines = [];
 
         if (missingFiles && missingFiles.length > 0) {
-          lines.push('⚠️ 当前仍有文件未拆解完成：');
+          lines.push('❌ 当前仍有文件未拆解完成：');
           for (const f of missingFiles) {
             lines.push(`  - ${f}`);
           }
@@ -243,19 +311,33 @@ export const analyze = {
           ];
           for (const s of states) {
             if (queue[s.key] > 0) {
-              lines.push(`当前${s.label}状态的任务为 ${queue[s.key]} 个`);
+              lines.push(`ℹ️ 当前${s.label}状态的任务为 ${queue[s.key]} 个`);
             }
           }
+          if ((queue.pending || 0) + (queue.processing || 0) > 0) {
+            lines.push('⏳ 队列中仍有未完成任务；以下缺失或覆盖结果可能尚未落盘，建议等待队列空闲后重新查询。');
+          }
         }
 
-        // 有缺失报告时，不显示"完成"消息
+        // 有真实问题：保留“检测到问题”的警示头；覆盖统计单独追加。
         if (extraMessage) {
-          const baseMsg = lines.length > 0 ? lines.join('\n') : '⚠️ ingest 队列状态正常，但检测到以下问题：';
-          return baseMsg + '\n' + extraMessage;
+          const baseMsg = lines.length > 0
+            ? lines.join('\n')
+            : '⚠️ ingest 队列状态正常，但检测到以下问题：';
+          return baseMsg + '\n\n' + extraMessage +
+            (coverageMessage ? '\n\n' + coverageMessage : '');
+        }
+
+        // 没有真实问题：不要再说“检测到以下问题”。覆盖统计只是信息。
+        if (coverageMessage) {
+          const baseMsg = lines.length > 0
+            ? lines.join('\n')
+            : '✅ ingest 队列状态正常，未发现缺失。';
+          return baseMsg + '\n\n' + coverageMessage;
         }
 
         if (lines.length === 0) {
-          return '✅ 所有文件已 ingest 完成，队列空闲';
+          return '✅ 所有文件均已完成 ingest，队列空闲。';
         }
 
         return lines.join('\n');
@@ -264,17 +346,32 @@ export const analyze = {
       case 'summary_status':
         return renderSummaryStatus(summary, Date.now());
 
+      case 'register_script_failed':
+        return `❌ 无法部署章节登记脚本到项目内（${projectRoot || '项目根未知'}/.fancy-tools/append-summary-chapter.js）。
+
+请确认：
+1. 项目根可写；
+2. .fancy-tools 不是符号链接、也不是普通文件；
+3. 已有目标文件不是符号链接。
+
+修复后重新运行 /fancy-analyze summary。`;
+
       case 'summary_dispatched': {
         const tasks = summary?.tasks || [];
         const lines = [];
-        lines.push('✅ 已派发技法总结任务');
+        lines.push('✅ 已派发总结任务');
         lines.push('');
-        lines.push(`📋 本次派发 ${tasks.length} 个技法目录：`);
+        lines.push(`📋 本次派发 ${tasks.length} 个总结目录：`);
         for (const task of tasks) {
+          const isEntity = task.scope === 'entity';
           const parts = [];
-          if (Number.isFinite(task.sourceCount)) parts.push(`共 ${task.sourceCount} 章`);
-          if (Number.isFinite(task.pendingCount)) parts.push(`还差 ${task.pendingCount} 章`);
-          lines.push(`  · ${task.name}${parts.length ? '   ' + parts.join(' · ') : ''}`);
+          if (Number.isFinite(task.sourceCount)) {
+            parts.push(`共 ${task.sourceCount} ${isEntity ? '个实体页' : '章'}`);
+          }
+          if (Number.isFinite(task.pendingCount)) {
+            parts.push(`还差 ${task.pendingCount} ${isEntity ? '个实体页' : '章'}`);
+          }
+          lines.push(`  · ${task.name}${isEntity ? ' [实体]' : ''}${parts.length ? '   ' + parts.join(' · ') : ''}`);
         }
         if (summary?.skippedDone?.length) {
           lines.push('');
@@ -285,16 +382,16 @@ export const analyze = {
         }
         lines.push('');
         if (Number.isFinite(summary?.remainingChapters)) {
-          lines.push(`📚 全部待总结 **${summary.remainingChapters} 章**（提示词只给目录，章节由模型自己去目录里找）`);
+          lines.push(`📚 全部待总结 **${summary.remainingChapters} 个来源项**（提示词只给目录，章节/实体页由模型自己去目录里找）`);
         }
-        lines.push('💡 模型正在后台写文件，用 /fancy-analyze summary-status 查真实进度。');
-        lines.push('⚠️ 本命令只代表"提示词已入队"，不代表模型已经写完。');
+        lines.push('💡 模型正在后台写入文件，可用 /fancy-analyze summary-status 查看实际进度。');
+        lines.push('⚠️ 本命令仅表示提示词已入队，不代表模型已完成写入。');
         return lines.join('\n');
       }
 
       case 'summary_nothing_to_do': {
         const lines = [];
-        lines.push('✅ 没有需要总结的章节');
+        lines.push('✅ 当前没有需要总结的来源。');
         if (summary?.done?.length) {
           lines.push('');
           lines.push(`已完成：${summary.done.join('、')}`);
@@ -303,13 +400,13 @@ export const analyze = {
           lines.push(`ℹ️ 无输入文件：${summary.skippedNoInput.join('、')}`);
         }
         lines.push('');
-        lines.push('💡 要强制重来：/fancy-analyze resummary [技法名]');
+        lines.push('💡 如需强制重新总结，请运行：/fancy-analyze resummary [目录名]');
         return lines.join('\n');
       }
 
       case 'summary_reset': {
         const lines = [];
-        lines.push(`♻️ 已重置 ${summary?.reset?.length || 0} 个技法的总结`);
+        lines.push(`♻️ 已重置 ${summary?.reset?.length || 0} 个目录的总结`);
         lines.push('');
         for (const item of summary?.reset || []) {
           lines.push(`  · ${item.name}   旧总结已备份到：${item.backup}`);
@@ -319,7 +416,7 @@ export const analyze = {
           lines.push(`♻️ 已重新派发：${summary.dispatched.length} 个目录`);
         } else {
           lines.push('');
-          lines.push('ℹ️ 没有可派发的目录（源文件为空），只做了重置。');
+          lines.push('ℹ️ 没有可派发的目录（源文件为空），仅执行了重置。');
         }
         lines.push('');
         lines.push('💡 用 /fancy-analyze summary-status 查进度。');
@@ -331,13 +428,13 @@ export const analyze = {
         // 也是对标/raw/sources/ 下的目录名）——
         // 用 bookName 的话，调用处不传就会显示成《undefined》。
         const doneBook = bookNameClean || bookName || '';
-        return `✅ 《${doneBook}》正在后台拆解中......
+        return `✅ 《${doneBook}》正在后台拆解…
 
 📁 输出位置：${projectRoot}/对标/
   ├── schema.md                ← LLM Wiki 项目配置
   └── raw/sources/${bookNameClean}/  ← 拆书结果
 
-💡 可在 llm_wiki 中查看拆解进度和拆解结果,也可稍后执行 fancy-analyze status 查看进度`;
+💡 可在 llm-wiki 中查看拆解进度和结果，也可稍后执行 /fancy-analyze status 查看进度。`;
       }
 
       default:
@@ -678,21 +775,21 @@ ${projectRoot}/对标/${bookName}/
 
 ## 4. 完成检查
 
-写完所有文件后，检查每个文件存在且非空：
-- 对标/${bookName}/_summary.md（≥ 200 字）
-- 对标/${bookName}/for_bible/characters.md（≥ 500 字）
-- 对标/${bookName}/for_bible/relationships.md（≥ 200 字）
-- 对标/${bookName}/for_bible/world.md（≥ 200 字）
-- 对标/${bookName}/for_outline/plot_structure.md（≥ 200 字）
-- 对标/${bookName}/for_outline/pacing.md（≥ 200 字）
-- 对标/${bookName}/for_outline/chapter_templates.md（≥ 200 字）
-- 对标/${bookName}/for_outline/foreshadow_patterns.md（≥ 200 字）
-- 对标/${bookName}/for_write/voice.md（≥ 200 字）
-- 对标/${bookName}/for_write/sentence_patterns.md（≥ 200 字）
-- 对标/${bookName}/for_write/phrase_bank/action.md（≥ 10 条）
-- 对标/${bookName}/for_write/phrase_bank/psychology.md（≥ 10 条）
-- 对标/${bookName}/for_write/phrase_bank/environment.md（≥ 10 条）
-- 对标/${bookName}/for_write/phrase_bank/dialogue.md（≥ 10 条）
+写完所有文件后，检查每个文件存在且非空（**用绝对路径查**，别拼相对路径）：
+- ${projectRoot}/对标/${bookName}/_summary.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_bible/characters.md（≥ 500 字）
+- ${projectRoot}/对标/${bookName}/for_bible/relationships.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_bible/world.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_outline/plot_structure.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_outline/pacing.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_outline/chapter_templates.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_outline/foreshadow_patterns.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_write/voice.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_write/sentence_patterns.md（≥ 200 字）
+- ${projectRoot}/对标/${bookName}/for_write/phrase_bank/action.md（≥ 10 条）
+- ${projectRoot}/对标/${bookName}/for_write/phrase_bank/psychology.md（≥ 10 条）
+- ${projectRoot}/对标/${bookName}/for_write/phrase_bank/environment.md（≥ 10 条）
+- ${projectRoot}/对标/${bookName}/for_write/phrase_bank/dialogue.md（≥ 10 条）
 `;
   },
 
@@ -729,75 +826,308 @@ ${projectRoot}/对标/${bookName}/
    * 而不是寄望模型自觉。
    *
    * @param {object} opts
-   * @param {Array<{name: string, sourceCount?: number, pendingCount?: number}>} opts.tasks
-   *   每个要处理的技法目录：name=目录名，sourceCount=该目录共多少章节文件，
-   *   pendingCount=按现有清单还差多少章（算不出来时省略）
-   * @param {number} [opts.remainingChapters] - 全部目录加起来还剩多少章（只用于给用户看）
+   * @param {Array<{name: string, scope?: 'chapter'|'entity', sourceCount?: number, pendingCount?: number}>} opts.tasks
+   *        每个要处理的总结目录：name=目录名，scope=按章技法/跨章节实体，
+   *        sourceCount=该目录共多少章节/实体页文件，
+   *        pendingCount=按现有清单还差多少来源项（算不出来时省略）
+   * @param {number} [opts.remainingChapters] - 全部目录加起来还剩多少来源项
+   *        （章节 + 实体页，只用于给用户看）
+   * @param {string} [opts.projectRoot] - 项目根绝对路径。
+   *        给了就把目录路径写成**绝对路径** —— 只给相对路径的话，
+   *        LLM 的工作目录未必是项目根，文件会写到别的地方去。
+   * @param {string} [opts.registerScript] - 登记脚本（append-summary-chapter.js）的绝对路径。
+   *        给了才给"追加 + 登记"的命令模板 —— 脚本把这两件事做成幂等原子的，
+   *        不用命令模板时退回"手工编辑文件头"的旧说法。
    * @returns {string} 提示词正文
    */
-  generateSummarySystemPrompt({ tasks, remainingChapters }) {
+  generateSummarySystemPrompt({ tasks, remainingChapters, projectRoot, registerScript }) {
     const list = Array.isArray(tasks) ? tasks : [];
+    const quotedRegisterScript = registerScript ? shellSingleQuote(registerScript) : '';
+    const projectArg = projectRoot ? ` --project-root=${shellSingleQuote(projectRoot)}` : '';
     const taskBlocks = list.map((task) => {
+      const isEntity = task.scope === 'entity';
       const sourceCount = Number.isFinite(task.sourceCount) ? task.sourceCount : null;
       const pendingCount = Number.isFinite(task.pendingCount) ? task.pendingCount : null;
+      const sourceUnit = isEntity ? '个实体页' : '个章节文件';
+      const pendingUnit = isEntity ? '个实体页' : '章';
       const scale = [];
-      if (sourceCount !== null) scale.push(`共有 ${sourceCount} 个章节文件`);
-      if (pendingCount !== null) scale.push(`按现有清单还差 ${pendingCount} 章`);
+      if (sourceCount !== null) scale.push(`共有 ${sourceCount} ${sourceUnit}`);
+      if (pendingCount !== null) scale.push(`按现有清单还差 ${pendingCount} ${pendingUnit}`);
       const scaleLine = scale.length > 0 ? `- 规模：${scale.join(' · ')}\n` : '';
       const dir = task.name;
+      // 绝对路径优先：LLM 的工作目录未必是项目根，相对路径会写到别处
+      const sourceDir = projectRoot
+        ? `${projectRoot}/对标/wiki/${dir}/`
+        : `对标/wiki/${dir}/`;
+      const summaryPath = projectRoot
+        ? `${projectRoot}/对标/wiki/${dir}/${dir}-总结.md`
+        : `对标/wiki/${dir}/${dir}-总结.md`;
+
+      if (isEntity) {
+        return `#### 跨章节实体目录：${dir}
+
+- 源文件目录：\`${sourceDir}\`
+- 总结文件：\`${summaryPath}\`
+${scaleLine}- 这个目录是跨章节实体页（角色弧光设计/势力结构/世界观设计/冲突设计/主线支线结构/分卷节奏/伏笔布局/人物关系设计）。每个文件是一个实体页，不是一章；不要按章节总结。
+- **怎么找出这次要总结的实体页**（每个目录都照这个流程走）：
+  1. 打开总结文件 \`${summaryPath}\`，**只看文件头**（开头两段 \`---\` 之间的 YAML），里面 \`已总结章节:\` 下列的就是**已经总结过**的实体页名（键名沿用旧格式，实际登记的是实体页名）。总结文件还不存在时，这一步跳过（等于一张白纸）
+  2. 列出源文件目录 \`${sourceDir}\` 下所有 \`.md\` 文件，**排除** \`${dir}-总结.md\` 本身
+  3. 第 2 步的清单减掉第 1 步的清单，**差集**就是这次要总结的实体页
+  4. **不要把实体清单写进你的计划或正文** —— 边读边处理，读一个处理一个
+- **每个实体页重点读这两段**：
+  - \`## 可复用设计规则\`：作者已经提炼出的设计原则
+  - \`## 风险与反例\`：这种设计在什么情况下会失效、写崩、套路化
+  - 需要理解上下文时再看 \`## 实体定义\`、\`## 章节演进\`、\`## 当前状态\`，但**不要复述剧情**
+  - 如果这两段缺失或不完整，就直接读整页，按下面的角度提炼；不要因为缺段就跳过这个实体页
+- **提炼角度（专业网文作家视角，必须回答）**：
+  1. **为什么这么设计**：是为了让人物更立体、服务某段剧情、凸显冲突、建立世界观可信度、控制节奏，还是满足读者期待？
+  2. **这么设计的好处**：对人物、剧情、关系、主题、情绪、读者体验分别有什么作用？
+  3. **它是怎么服务的**：通过什么结构、选择、代价、信息差、关系变化、节奏位置实现的？
+  4. **适用条件**：什么题材、什么阶段、什么冲突强度下有效？
+  5. **风险与反例**：什么时候会失效、套路化、写崩？
+  6. **迁移到骨架/血肉/节奏**：抽象成下一本书可以直接套用的原则。
+- **不要做的事**：
+  - 不要逐条复述实体页的剧情；
+  - 不要把某个角色的具体经历当成通用规则；
+  - **正文**不要写原书专名、组织名、具体事件名，用“势力A/角色B/事件C”等占位符；
+  - **例外**：\`- 来源实体：\` 行必须写实体页的真实文件名（含原书名/角色名），不要替换成占位符；
+  - 不要把“可复用设计规则”和“风险与反例”简单拼接，要归纳成更高层、可迁移的设计原则；
+  - 不要把实体页的所有细节都搬进来：每条只保留最关键、可迁移的判断，每个字段 1–3 句，风险与反例只写 3–5 个最关键的失效条件。`;
+      }
+
       return `#### 技法目录：${dir}
 
-- 源文件目录：\`对标/wiki/${dir}/\`
-- 总结文件：\`对标/wiki/${dir}/${dir}-总结.md\`
-${scaleLine}- **怎么找出这次要总结的章节**（每个目录都照这个流程走）：
-  1. 打开总结文件 \`对标/wiki/${dir}/${dir}-总结.md\`，**只看文件头**（开头两段 \`---\` 之间的 YAML），里面 \`已总结章节:\` 下列的就是**已经总结过**的章节名（章节名 = 源文件名去掉 \`.md\` 后缀）。总结文件还不存在时，这一步跳过（等于一张白纸）
-  2. 列出源文件目录 \`对标/wiki/${dir}/\` 下所有 \`.md\` 文件，**排除** \`${dir}-总结.md\` 本身
+- 源文件目录：\`${sourceDir}\`
+- 总结文件：\`${summaryPath}\`
+${scaleLine}- 这个目录是按章建页的写作技法或章节功能设计（叙事视角/节奏韵律/场景转换/章节功能设计/…）。
+- **怎么找出这次要总结的章节**（每个目录都照这个流程走）：
+  1. 打开总结文件 \`${summaryPath}\`，**只看文件头**（开头两段 \`---\` 之间的 YAML），里面 \`已总结章节:\` 下列的就是**已经总结过**的章节名（章节名 = 源文件名去掉 \`.md\` 后缀）。总结文件还不存在时，这一步跳过（等于一张白纸）
+  2. 列出源文件目录 \`${sourceDir}\` 下所有 \`.md\` 文件，**排除** \`${dir}-总结.md\` 本身
   3. 第 2 步的清单减掉第 1 步的清单，**差集**就是这次要总结的章节
   4. **不要把章节清单写进你的计划或正文** —— 边读边处理，读一个处理一个`;
     }).join('\n\n');
 
-    const checkList = list.map((task) => `- \`对标/wiki/${task.name}/${task.name}-总结.md\``).join('\n');
+    const checkList = list.map((task) => {
+      const p = projectRoot
+        ? `${projectRoot}/对标/wiki/${task.name}/${task.name}-总结.md`
+        : `对标/wiki/${task.name}/${task.name}-总结.md`;
+      return `- \`${p}\``;
+    }).join('\n');
 
     const totalPending = Number.isFinite(remainingChapters) ? remainingChapters : null;
     const scaleNote = totalPending !== null
-      ? `> 全部目录加起来，按现有清单还差 **${totalPending} 章**没总结。`
+      ? `> 全部目录加起来，按现有清单还差 **${totalPending} 个来源项（章节/实体页）**没总结。`
+      : '';
+    const missingFileHint = registerScript
+      ? '下一次写入命令会自动创建'
+      : '按第二步手动写入文件头';
+
+    // 有登记脚本才给命令模板（脚本负责幂等 + 原子写）
+    const chapterWriteSection = registerScript
+      ? `**第二步：写入（必须用下面这条命令）**
+
+一条命令同时做两件事：把技法内容追加到「## 核心技法」下 + 把章节名登记进文件头的「已总结章节」清单。
+
+登记脚本已经放在项目里了（下面这条命令里的路径就在你的项目目录下），直接调用即可：
+
+\`\`\`bash
+node ${quotedRegisterScript}${projectArg} --file="[总结文件绝对路径]" --chapter="[章节名]" <<'FANCY_SUMMARY_EOF'
+### 提炼出的技法名称
+- 来源章节：[来自哪些文件]
+- 核心要点：[技法的核心内容]
+- 使用场景：[在哪些情况下使用]
+- 应用方式：[如何应用]
+FANCY_SUMMARY_EOF
+\`\`\`
+
+- 命令里的 \`[章节名]\` 填这一章去掉 \`.md\` 后缀的名字
+- **\`[章节名]\` 只是占位符，实际值不要带方括号**：\`--chapter\` 和 \`- 来源章节：\` 都写纯文件名（如 \`书名-技法-第3章\`），不要写 \`[书名-技法-第3章]\`
+- **\`- 来源章节：\` 必须原样照抄源文件名**（含原书名、数字、英文），它是登记与反推的依据；它不算“原书专名”，不要翻译或替换成占位符
+- 命令里的 \`--project-root\` 是项目根，脚本会用它校验总结文件没有跑到项目外；不要改成别的路径
+- 命令里的 \`[总结文件绝对路径]\` 填**当前正在处理的那个技法目录**的总结文件绝对路径
+  —— 上面每个「技法目录」小节都列了它（\`源文件目录\` / \`总结文件\` 两行）。
+  **填错目录，章节就登记到别的目录的清单里**：那一章下次还会被重做，
+  而被误登记的那个目录会多出一条它根本不该有的章节
+- heredoc 里是**要写进总结文件的正文内容**（脚本从 stdin 读它），
+  格式就照上面这几行：\`###\` 开头是技法名，下面四个 \`-\` 分别是来源、要点、场景、用法
+- **如果这一章没有新的可复用技法，heredoc 可以留空** —— 脚本仍会登记章节，但不会追加正文
+- **\`- 来源章节：\` 这一行必须写** —— 它是头部损坏时反推已总结章节的兜底依据
+  （见第三步的 \`entriesMissingSource\`），缺了就只剩头部一个事实源
+- **不要用 write 重写整个总结文件** —— write 会把文件头里已经登记的章节清单一起冲掉，
+  之前总结过的章节会被当成"没总结"，下次执行时全部重做一遍，文件越滚越胖
+- 正文块里只写技法条目本身（\`###\` 开头的那几行），**不要写代码块围栏**
+- **文件头不用你写** —— 命令会自动建好并维护它，你只要管正文内容
+
+**命令返回的 JSON 怎么看**：
+
+\`\`\`json
+{"ok":true,"added":true,"alreadyRegistered":false,"bodyAdded":true,"bodyAlreadyPresent":false,"total":12,...}
+\`\`\`
+
+- \`ok:true\` = 这次写入**确实落盘了**（写盘失败时命令会非零退出并返回 \`ok:false\` + \`error\`）
+- \`added:true\` = 这一章刚刚登记成功；\`added:false\` 且 \`alreadyRegistered:true\`
+  = 这一章之前就登记过，**跳过它**，不要重复总结，也不要再追加正文
+- \`bodyAdded:true\` = 这次确实追加了技法正文；\`bodyAlreadyPresent:true\`
+  = 正文里已经有这一章的「来源章节」行，脚本没有重复追加
+- \`total\` = 写完后已登记的章节总数
+
+**写入失败怎么办（\`ok:false\`）**：
+
+- \`error\` 里说了原因（比如路径不对、目录没权限）→ **先修掉原因再重试**，
+  同一章最多重试一次。重试仍失败就**跳过这一章，继续下一章**，
+  并在最后的报告里写明"第 N 章写入失败：原因"。
+- **跳过是安全的**：这一章没登记成功，下次执行 summary 会自动再处理它，
+  不会漏。**不要为了"必须全部成功"而反复重试或手工改文件**。
+- 如果 \`repaired:true\`（头部原本是坏的，已自动修复）→ 看 \`recovered\`：
+  那是脚本从残留内容里反推回来的章节数。清单可能仍不完整，
+  **照常继续**，但要在报告里提一句。
+
+**第三步：校验登记状态（只读，不修改文件）**
+
+第二步那条命令已经把章节登记进文件头了，这一步只是**看一眼**状态：
+
+\`\`\`bash
+node ${quotedRegisterScript}${projectArg} --file="[总结文件绝对路径]" --verify
+\`\`\`
+
+它会回一行 JSON，**\`ok\` 已经是判定结果** —— 不用你自己推断字段之间的关系：
+
+\`\`\`json
+{"ok":true,"problems":[],"total":52,"last":"甲-第3章","entries":48,
+ "entriesWithSource":48,"entriesMissingSource":0,"duplicates":[],...}
+\`\`\`
+
+**正常 = \`ok:true\` 且 \`problems\` 是空数组**（这是总的判定，脚本已经把所有
+问题都算进 \`problems\` 了，每条都有一句中文说明）。各字段的含义：
+
+- \`total\` = 已登记的章节数；\`last\` = 最后登记的那一条（**跟章节总数无关**，
+  章节攒到几百个也能看清当前状态）
+- \`entries\` = 「核心技法」下的技法条目数；\`entriesMissingSource\` = 其中缺
+  「来源章节」行的条数，**必须是 0**
+- \`duplicates\` = 空数组
+- \`frontmatterOk:true\`、\`hasCoreSection:true\`
+
+**还要对一下"写进的是不是这个目录"**（填错路径时脚本不会报错，只会把章节登记到别的目录）：
+- \`last\` 必须是你**刚写的那一章**（\`--chapter\` 里给的那个名字）
+- 写入返回 \`added:true\` 时，\`total\` 必须比写之前**多 1**
+  （写前先跑一次 \`--verify\` 记下 total；总结文件还不存在时基线按 0 算，首次写完 total 应为 1）
+- 写入返回 \`added:false\` / \`alreadyRegistered:true\` 时，\`total\` **不变**，
+  说明这一章之前就登记过，直接跳过，不要重复总结
+- 对不上 → **路径填错了**：换成上面那个技法目录的总结文件绝对路径重跑一次。
+  已经写到别的目录的那一条，用那个目录的 \`--verify\` 找到它并说明情况
+
+**首次写入前总结文件还不存在时**：\`--verify\` 会返回 \`exists:false\`，
+这是正常的起点，不是坏文件。首次写入后文件应存在，且 \`total\` 为 1。
+
+**任何一项不对就是不对**（\`ok:false\`）。此时 \`problems\` 里会写清楚是哪一条，
+按它说的处理：
+
+- \`frontmatterOk:false\`（文件头坏了）→ **先别写这个目录**。
+  头部是唯一事实源，它坏了你就不知道哪些章节已经总结过，
+  继续写只会把状态搞得更乱。用 \`recovered\` 字段看看脚本反推回了多少章，
+  把它记在报告里，然后**跳到下一个目录**。
+- \`entriesMissingSource\` > 0（有条目缺「来源章节」行）→ 记进报告，
+  继续处理下一个目录。**不要为了补这一行重复追加条目** —— 脚本只会追加，
+  不会改写已有条目，重复追加只会让文件更乱；下次 summary 仍会按头部清单跳过这些章节。
+- \`duplicates\` 非空 / \`hasCoreSection:false\` → 记进报告，
+  继续处理下一个目录，别在坏状态上继续写。
+
+**\`entries\` 和 \`total\` 不要求相等**，谁大谁小都正常：
+- 一章提炼出多条技法 → \`entries\` > \`total\`
+- 某章没有新的可复用技法，只登记章节 → \`entries\` < \`total\`
+- 一章一条 → \`entries\` == \`total\`
+
+**⚠️ 不要修改登记脚本本身** —— \`${registerScript}\` 是插件提供的**只读工具**，
+它由插件在每次派发前自动铺好（内容变了会被覆盖回去）。
+只管调用它，不要读写、改写、移动或删除这个文件；你要写的**只有**
+总结文件本身（\`--file=\` 指向的那个）。`
+      : `**第二步：写入文件头（仅当文件不存在时）**
+
+每次追加写入前，先检查总结文件是否存在。如果不存在，则先写入文件头（见下方「写入格式」）。
+
+**第三步：追加技法内容（每次提炼后）**
+
+如果文件已存在，则在 \`## 核心技法\` 章节下追加技法条目（见下方「写入格式」）。
+
+**第四步：登记已总结章节（每总结完一章立刻做）**
+
+**每总结完一章，立刻把该章节名追加进总结文件头部的「已总结章节」列表**
+（不要覆盖已有条目，不要重复添加同一个章节名）。
+
+**重要**：不要用 write 重写整个总结文件 —— 那会把文件头里已登记的章节清单冲掉，
+之前总结过的章节会被当成"没总结"，下次执行时全部重做一遍。`;
+
+    const hasEntityTasks = list.some((task) => task.scope === 'entity');
+    const entityWriteSection = registerScript && hasEntityTasks
+      ? `**跨章节实体目录：写入格式**
+
+跨章节实体目录使用同一登记脚本，但要用 \`--section="核心设计原则"\`，正文按下面格式写：
+
+\`\`\`bash
+node ${quotedRegisterScript}${projectArg} --file="[实体目录总结文件绝对路径]" \\
+  --chapter="[实体页名]" --section="核心设计原则" <<'FANCY_SUMMARY_EOF'
+### 设计原则名称
+- 来源实体：[实体页名]
+- 为什么这么设计：[让人物立体/服务剧情/凸显冲突/建立世界观/控制节奏/满足读者期待]
+- 设计好处：[对人物、剧情、关系、主题、情绪、读者体验的作用]
+- 如何服务剧情/人物/主题：[通过什么结构、选择、代价、信息差、关系变化实现]
+- 适用条件：[什么题材、阶段、冲突强度下有效]
+- 风险与反例：[什么时候会失效、套路化、写崩]
+- 迁移到骨架/血肉/节奏：[抽象成下一本书可套用的原则]
+FANCY_SUMMARY_EOF
+\`\`\`
+
+- \`--chapter\` 填**实体页名**（去掉 \`.md\` 后缀），不是章节名；
+- **\`[实体页名]\` 只是占位符，实际值不要带方括号**：\`--chapter\` 和 \`- 来源实体：\` 都写纯文件名（如 \`书名-角色-角色A\`），不要写 \`[书名-角色-角色A]\`
+- **\`- 来源实体：\` 必须原样照抄实体页文件名**（含原书名、角色名、数字、英文），它是登记与反推的依据；它不算“原书专名”，不要用“角色A/势力A”等占位符替换
+- \`--section\` 必须是 \`核心设计原则\`，否则脚本会去「核心技法」里找条目并报 \`hasCoreSection:false\`；
+- \`- 来源实体：\` 这一行必须写，它是头部损坏时反推已总结实体页的兜底依据；
+- 如果这个实体页没有新的可复用原则，heredoc 可以留空，但仍要登记实体页名；
+- 校验时用 \`--verify --section="核心设计原则"\`。`
       : '';
 
     return `你是一位经验丰富、资历深厚、在小说领域有着独到见解并且逻辑思维缜密的小说技法分析师。
 
 ## 核心铁律
 **每次调用都是全新流程**，不读取上下文，不读取之前的选择，不读 memory。
-**只处理下面明确列出的技法目录**，不要自行扩大范围。
+**只处理下面明确列出的总结目录**，不要自行扩大范围。
 
 ${scaleNote}
-> ⚠️ 本提示词**故意不列具体章节名** —— 一本长篇可能几千章，列出来会把提示词撑爆。
-> 哪些章节还没总结，由你按每个目录下方写的步骤**自己去目录里判断**。
+> ⚠️ 本提示词**故意不列具体来源名** —— 一本长篇可能几千章、上千个实体页，列出来会把提示词撑爆。
+> 哪些来源还没总结，由你按每个目录下方写的步骤**自己去目录里判断**。
 
 ## ⚠️ 语言强制要求
 
-**所有输出内容必须是中文，包括：**
-- 文件名：使用中文
+**总结正文和标题必须使用中文：**
 - 标题：使用中文
 - 正文内容：所有文字描述必须使用中文
 - 表格内容：所有表格中的文字必须使用中文
-- YAML 元数据：**键和值都必须用中文**
+- YAML 值：使用中文（文件头由登记脚本维护，键名不用你改；登记的文件名照抄，不要翻译）
+
+**文件路径 / 文件名沿用上面给出的路径，不要改名。**
 
 **禁止输出英文内容：**
 - ❌ 英文描述、英文分析
-- ❌ 英文 YAML 键
 - ❌ 英文 YAML 值
 - ❌ 中英混合
 
+**登记字段例外**：\`--chapter\`、\`- 来源章节：\`、\`- 来源实体：\` 三处必须**原样照抄源文件名/实体页名**（去掉 \`.md\` 后缀）。文件名里可能带英文、数字、原书名，这是登记依据，不算“英文内容”；不要翻译、不要改写、不要加方括号。
+
 ## ⚠️ 占位符说明
 
 下方提示词中用 **\`[\`** 和 **\`]\`** 包裹的内容都是**占位符**，需要你根据读取到的文件内容进行推理和补充，不要直接输出占位符原文。
+**代码块只是格式展示** —— 写进文件时只写内容本身，**不要把 \`\`\` 围栏一起写进文件**。
+
+**特别注意**：\`--chapter\`、\`- 来源章节：\`、\`- 来源实体：\` 这三处**不要保留方括号**。实际值必须是源文件名/实体页名去掉 \`.md\` 后的纯文本（例如 \`书名-角色-角色A\`，不是 \`[书名-角色-角色A]\`）。
+
+**标题不要保留方括号**：命令块里的 \`### 提炼出的技法名称\` / \`### 设计原则名称\` 只是占位格式；实际把“提炼出的技法名称”/“设计原则名称”替换成真实标题，不要写成 \`### [提炼出的技法名称]\`。
 
 ## 任务
 
-请对下面每个技法目录里**尚未总结**的章节进行归纳、总结、提炼、挖掘、扩展，
-提炼出通用的、可复用的写作技法。
+请对下面每个目录里**尚未总结**的来源进行归纳、总结、提炼、挖掘、扩展。
+按章技法目录提炼“可复用的写作技法”；跨章节实体目录提炼“可复用的设计原则”（为什么这么设计、好处、如何服务剧情/人物/冲突/节奏/主题/读者体验）。
 
-### 本次要总结的技法目录
+### 本次要总结的目录
 
 ${taskBlocks}
 
@@ -805,57 +1135,22 @@ ${taskBlocks}
 
 **增量写入方式**：为避免超出上下文限制，请采用增量写入方式，每个目录处理流程如下：
 
-1. **按上述步骤算出这次要总结的章节**（读总结文件头 → 列源文件 → 求差集）
-2. **逐文件读取提炼**：依次读取算出来的每个文件（文件名去掉 \`.md\` 后缀即为章节名），边读边提炼，**每读完一个文件立即将提炼结果追加写入总结文件**（使用文件路径 \`对标/wiki/[目录名]/[目录名]-总结.md\`）
-3. **登记章节**：**每总结完一个章节，立刻把该章节名追加进总结文件头部的「已总结章节」列表**（见下方写入格式）。这是本次任务的关键产出 —— 插件靠它判断哪些章节已经总结过，下次执行时只派发剩下的
-4. **不要写章节清单**：不要把"待总结章节列表"整体写进计划、进度汇报或正文里（章节可能上千个，写出来会挤爆上下文）；只报"处理了 N 个"这类数字即可
-5. **做不完就停**：按你的上下文能力处理，做到快满时停下，剩下的**下次执行 summary 会继续**（已完成的章节已经登记，不会重复）
-6. **去重合并**：当多个文件提炼出相同技法时，在总结文件中合并，只保留一条
+1. **按上述步骤算出这次要总结的来源**（读总结文件头 → 列源文件 → 求差集）
+2. **逐文件读取提炼**：依次读取算出来的每个文件（文件名去掉 \`.md\` 后缀即为章节名/实体页名），边读边提炼
+3. **每读完一个文件，立刻写入**（写入方式见下一节）
+4. **不要写来源清单**：不要把"待总结来源列表"整体写进计划、进度汇报或正文里（章节/实体可能上千个，写出来会挤爆上下文）；只报"处理了 N 个"这类数字即可
+5. **做不完就停**：按你的上下文能力处理，做到快满时停下，剩下的**下次执行 summary 会继续**（已完成的来源已经登记，不会重复）
+6. **去重**：新来源与已有条目重复时，不要重复追加同一条；如果这一来源没有新的可复用内容，只登记来源（heredoc 留空），不要用 write 删改已有条目
 7. **继续下一目录**：完成一个目录后，继续处理下一个目录
+8. **控制并发**：如果工具支持子代理，可以按目录并行，但一次最多 4–5 个；不要一次开 20 个（可能触发模型服务的 429 限流）。遇到 429/限流就降低并发、等待后重试，不要把同一批全部重开
 
 ### 写入格式
 
-**第一步：写入文件头（仅当文件不存在时）**
-
-每次追加写入前，先检查总结文件是否存在。如果不存在，则先写入以下内容：
+第一步是“算出这次要总结的来源”（见上面「操作要求」）；下面说明写入方式（使用登记脚本时还会做一次只读校验）。
 
-\`\`\`yaml
----
-标题: [目录名]-总结
-标签: [总结, 目录名]
-已总结章节:
-  - [已总结的章节名，去掉 .md 后缀]
----
-# [目录名]技法总结
-
-## 核心技法
-\`\`\`
-
-**第二步：追加技法内容（每次提炼后）**
-
-如果文件已存在，则在 \`## 核心技法\` 章节下追加以下内容：
-
-\`\`\`yaml
-### [提炼出的技法名称]
-- 来源章节：[来自哪些文件]
-- 核心要点：[技法的核心内容]
-- 使用场景：[在哪些情况下使用]
-- 应用方式：[如何应用]
-\`\`\`
-
-**第三步：登记已总结章节（每总结完一章立刻做）**
-
-在文件头部的 \`已总结章节:\` 列表下**追加**一行（不要覆盖已有条目，
-不要重复添加同一个章节名）：
-
-\`\`\`yaml
-已总结章节:
-  - [第1个章节名]
-  - [第2个章节名]
-\`\`\`
+${chapterWriteSection}${entityWriteSection ? '\n\n' + entityWriteSection : ''}
 
-章节名 = 源文件名去掉 \`.md\` 后缀（例如源文件 \`[书名]-[技法名]-第3章.md\`
-→ 章节名 \`[书名]-[技法名]-第3章\`）。
+来源名 = 源文件名去掉 \`.md\` 后缀。例如源文件 \`书名-技法名-第3章.md\` → 来源名 \`书名-技法名-第3章\`；实体页同理，如 \`书名-角色-角色名.md\` → \`书名-角色-角色名\`。实际文件名可能是中文、英文、数字，**原样照抄，不要加方括号**。
 
 ## 闭环检查
 
@@ -864,17 +1159,20 @@ ${taskBlocks}
 **文件存在性检查**：确认以下每个目录下都存在总结文件：
 ${checkList}
 
-如果发现某个目录下缺少总结文件，必须立即生成。
+如果某个目录还没有总结文件：${missingFileHint}。
 
-**章节登记检查**：确认每个总结文件的 \`已总结章节:\` 列表包含了该目录下
-**你已经处理过的全部章节**。少登记一个，下次执行 summary 就会重复总结它。
+**来源登记检查**：确认每个总结文件的 \`已总结章节:\` 列表包含了该目录下
+**你已经处理过的全部来源（章节 / 实体页）**。少登记一个，下次执行 summary 就会重复总结它。
 
 ## ⚠️ 重要提醒
 
-- **去重原则**：如果多个章节使用了相同技法，只总结一次
-- **不越界**：只处理算出来的差集，不要顺手处理目录里其它章节
-- **格式要求**：每个总结文件必须包含 YAML 元数据
-- **内容要求**：总结内容必须是具体、可操作的写作技法，不是泛泛而谈的描述
+- **去重原则**：已存在的条目不要重复追加；没有新内容时只登记来源（heredoc 留空）
+- **不越界**：只处理算出来的差集，不要顺手处理目录里其它来源
+- **内容要求**：按章目录总结具体、可操作的写作技法；实体目录总结具体、可迁移的设计原则（为什么这么设计、好处、服务对象、适用条件、风险），不是剧情复述
+- **控制篇幅**：每条只保留最关键、可迁移的判断；每个字段 1–3 句；风险与反例只写 3–5 个最关键的失效条件，不要把实体页的所有细节都搬进来
+- **正文抽象**：按章目录也不要把原书人名、地名、组织名写进正文；具体数字、台词只作为示例，用“例如”引出，不要当成通用规则。\`来源章节\` / \`来源实体\` 行例外，必须原样照抄文件名
+- **写完自检**：正文是否混入原书人名、地名、组织名、专有体系名、英文缩写或方括号？有就替换成通用表述；\`来源章节\` / \`来源实体\` 行必须保留真实文件名，不参与抽象
+- **别冲掉清单**：不要用 write 覆盖重写总结文件，登记过的来源会丢
 
 请开始执行总结任务，完成后输出总结报告。`;
   },