@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-analyze/index.js

@@ -16,18 +16,23 @@
  * 不依赖 phase：这个 skill 可以独立于整条流水线使用
  * （用户在写正文之前、中途、之后都可以调用来分析参考爆款）
  */
-import { existsSync, statSync, readdirSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, unlinkSync, renameSync } from 'fs';
+import { existsSync, statSync, lstatSync, chmodSync, readdirSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, unlinkSync, renameSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
+import { atomicWriteFile } from '#atomic-write';
 import { askUserQuestion, spawnScript } from '#infra';
 import { notify, llmFollowup } from '#infra';
 import { describeFetchError, llmWikiError, readJsonSafe } from '#llm-wiki';
 import { readDeployedState, DEPLOYED_STATUS } from '#deployed-state';
+import { resolveWorkspace } from '#workspace';
+import { sortByChapter, chapterNumber } from '#chapter-order';
+import { findMissingIngestOutputs } from './ingest-coverage.js';
 import { analyze } from './templates.js';
 import {
   scanSummaryProgress,
   dirsToDispatch,
-  listTechDirs,
+  listSummaryDirs,
+  LEGACY_STRUCTURE_DIRS,
 } from './summary-progress.js';
 import { normalizeCommandInput, matchSubcommand } from './command-input.js';
 
@@ -35,7 +40,104 @@ export const inject = ['commands', 'userQuestions'];
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SPLIT_SCRIPT = join(__dirname, 'scripts', 'split_source.js');
+// 登记脚本：把"追加技法内容 + 登记章节"做成幂等原子的操作。
+// 让模型手工编辑 YAML 头部很容易把已登记的清单冲掉 —— 头部是唯一事实源，
+// 冲掉了下次 summary 会把老章节全部重做一遍。
+//
+// **脚本不在插件目录里执行** —— 插件目录在 node_modules 下（部署后位置
+// 还不一样），让模型去那里跑文件既别扭又易变。派发提示词前把它复制到
+// 项目里的 .fancy-tools/，提示词里给项目内的路径。
+const REGISTER_SCRIPT = join(__dirname, 'scripts', 'append-summary-chapter.js');
+const REGISTER_TOOL_DIR = '.fancy-tools';
+
+/**
+ * 确保项目里有最新版登记脚本，返回它的绝对路径（失败返回 null）。
+ *
+ * 内容比对后才写 —— 每次 summary 都覆盖一次的话会白白改 mtime，
+ * 也会让"这个文件是不是被人手改过"变得看不出来。
+ *
+ * @param {string} projectRoot
+ * @returns {string|null}
+ */
+export function ensureRegisterScript(projectRoot) {
+  try {
+    if (!projectRoot || typeof projectRoot !== 'string') return null;
+    if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) return null;
+    if (!existsSync(REGISTER_SCRIPT)) return null;
+
+    const destDir = join(projectRoot, REGISTER_TOOL_DIR);
+    let dirStat = null;
+    try { dirStat = lstatSync(destDir); } catch { /* 不存在 */ }
+    if (dirStat) {
+      // .fancy-tools 绝不能是符号链接 —— 否则脚本会被写到项目外。
+      if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+        console.error('[fancy-analyze] .fancy-tools 不是真实目录，拒绝部署登记脚本');
+        return null;
+      }
+    } else {
+      mkdirSync(destDir);
+    }
+
+    const dest = join(destDir, 'append-summary-chapter.js');
+    let destStat = null;
+    try { destStat = lstatSync(dest); } catch { /* 不存在 */ }
+    if (destStat && (destStat.isSymbolicLink() || !destStat.isFile())) {
+      console.error('[fancy-analyze] 登记脚本目标不是普通文件，拒绝覆盖：' + dest);
+      return null;
+    }
+
+    const srcContent = readFileSync(REGISTER_SCRIPT, 'utf-8');
+    if (destStat) {
+      const same = readFileSync(dest, 'utf-8') === srcContent;
+      if (!same) atomicWriteFile(dest, srcContent, { mode: 0o444 });
+      // 内容没变也要去掉写权限（老项目里可能是 0644）。
+      chmodSync(dest, 0o444);
+      return dest;
+    }
+
+    atomicWriteFile(dest, srcContent, { mode: 0o444 });
+    return dest;
+  } catch (err) {
+    console.error('[fancy-analyze] 准备登记脚本失败：' + (err && err.message ? err.message : String(err)));
+    return null;
+  }
+}
 const SCHEMA_SOURCE = join(__dirname, 'schema-analyze.md');
+const DEFINITIONS_SOURCE = join(__dirname, 'analyze-definitions.md');
+const DEFINITIONS_FILENAME = '分析定义.md';
+
+/** 按章写作技法（与 schema-analyze.md 的 13 项保持一致）。 */
+const CHAPTER_WRITING_TYPES = [
+  '叙事视角',
+  '章节结构',
+  '节奏韵律',
+  '对话技巧',
+  '描写技法',
+  '情节机制',
+  '开头钩子',
+  '结尾收束',
+  '句式变化',
+  '段落布局',
+  '场景转换',
+  '情绪渲染',
+  '张力构建',
+];
+/** 只做称呼/关系称谓、通常不该单独建角色页的名字。 */
+const RELATION_ONLY_ENTITY_RE = /^(?:哥哥|姐姐|弟弟|妹妹|父亲|母亲|爸爸|妈妈|爷爷|奶奶|外公|外婆|师父|师傅|老师|老板|同学|朋友|儿子|女儿)$/u;
+/** 按章建页的类型集合（13 写作技法 + 章节功能设计）。 */
+const CHAPTER_PAGE_TYPES = new Set([...CHAPTER_WRITING_TYPES, '章节功能设计']);
+
+/** 结构设计页类型（与 schema-analyze.md 的 8 项保持一致）。 */
+const ENTITY_STRUCTURE_TYPES = [
+  '人物关系设计',
+  '势力结构',
+  '世界观设计',
+  '冲突设计',
+  '主线支线结构',
+  '分卷节奏',
+  '伏笔布局',
+  '角色弧光设计',
+];
 
 /** resummary 备份旧总结文件的目录（放在 对标/ 下，不在 wiki 树里，免得被当成技法目录）。 */
 const SUMMARY_BACKUP_DIRNAME = '.summary-backup';
@@ -52,11 +154,16 @@ function backupStamp(ts) {
 }
 
 function getProjectRoot(session) {
-  // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
-  // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
-  // 此时返回 null，由调用方给出明确报错。
+  // Analysis is shared at the workspace level: <workspace>/对标.
   const cwd = session.header?.cwd;
-  return cwd || null;
+  if (!cwd) return null;
+  try {
+    return resolveWorkspace({ cwd, required: true });
+  } catch {
+    // Fall back to the session cwd so the caller can report "not initialized"
+    // with the right path instead of "no project root".
+    return cwd;
+  }
 }
 
 /**
@@ -180,6 +287,68 @@ async function queryIngestStatus(baseUrl, token, projectId) {
   return callLlmWikiApi(baseUrl, token, `/projects/${projectId}/ingest/querystatus`, 'GET', null);
 }
 
+/**
+ * summary / resummary 的前置门禁：ingest 必须真的完成。
+ *
+ * 只看本地 `对标/wiki` 存在是不够的：ingest 还在排队时，wiki 目录可能已经
+ * 有一半页面，summary 会把“还没落盘的章节”当成“没有输入”或永远等不到。
+ *
+ * 这里用 llm_wiki 的 /ingest/querystatus：
+ *   - missingFiles 非空 → 还有源文件没进 wiki；
+ *   - queue.pending / processing > 0 → 队列还在跑；
+ *   - queue.failed > 0 → 有失败任务，需要 /fancy-analyze fix。
+ * 任一条成立都不让 summary 开工。
+ *
+ * @returns {{ok:boolean, text?:string}}
+ */
+async function checkIngestReadyForSummary(projectRoot, opts = {}) {
+  const command = opts.command || 'summary';
+  const { config, errorText } = loadDeployedConfig(projectRoot);
+  if (errorText) return { ok: false, text: errorText };
+  const referenceId = config && typeof config.reference_id === 'string' ? config.reference_id.trim() : '';
+  if (!referenceId) {
+    return { ok: false, text: analyze.notify({ type: 'no_reference_id' }) };
+  }
+  const llmWikiUrl = (config.llm_wiki_url || '').replace(/\/$/, '');
+  const llmWikiToken = config.llm_wiki_token || '';
+  if (!llmWikiUrl || !llmWikiToken) {
+    return { ok: false, text: analyze.notify({ type: 'llm_wiki_not_configured' }) };
+  }
+  let result;
+  try {
+    result = await queryIngestStatus(llmWikiUrl, llmWikiToken, referenceId);
+  } catch (err) {
+    return { ok: false, text: analyze.notify({
+      type: 'status_query_failed',
+      err: describeFetchError(err),
+    }) };
+  }
+  const apiErr = llmWikiError(result);
+  if (apiErr) {
+    return { ok: false, text: analyze.notify({ type: 'status_query_failed', err: apiErr }) };
+  }
+  const data = result.data || {};
+  // 和 status 用同一套排序：服务端返回 missingFiles 的顺序是随机的，
+  // summary / summary-status / resummary 三个入口都走这里，统一按书名+章号排。
+  const missingFiles = sortByChapter(Array.isArray(data.missingFiles) ? data.missingFiles : []);
+  const queue = data.queue && typeof data.queue === 'object' ? data.queue : {};
+  const pending = Number(queue.pending) || 0;
+  const processing = Number(queue.processing) || 0;
+  const failed = Number(queue.failed) || 0;
+  if (missingFiles.length || pending || processing || failed) {
+    return {
+      ok: false,
+      text: analyze.notify({
+        type: 'summary_ingest_not_ready',
+        command,
+        missingFiles,
+        queue: { ...queue, pending, processing, failed },
+      }),
+    };
+  }
+  return { ok: true };
+}
+
 /**
  * 在 参考资料/ 下查找匹配的源文件
  *
@@ -207,17 +376,24 @@ function findSourceFile(refDir, bookName) {
   const targetBase = bookName.trim().split(/[\\/]/).pop();
   const target = stripExt(targetBase);
 
-  const stat = statSync(refDir);
-  const entries = stat.isDirectory()
-    ? readdirSync(refDir)
-    : [];
+  const stat = (() => {
+    try { return statSync(refDir); } catch { return null; }
+  })();
+  if (!stat) return { error: 'dir_missing' };
+  let entries = [];
+  try {
+    entries = stat.isDirectory() ? readdirSync(refDir) : [];
+  } catch {
+    entries = [];
+  }
 
   // 情况：参考资料/<书名>.txt（文件）
   const directMatches = [];
   for (const name of entries) {
     if (stripExt(name) === target) {
       const full = join(refDir, name);
-      const st = statSync(full);
+      let st = null;
+      try { st = statSync(full); } catch { continue; }
       if (st.isFile()) {
         directMatches.push({ path: full, kind: 'file' });
       }
@@ -238,6 +414,181 @@ function findSourceFile(refDir, bookName) {
   return { error: 'not_found', matches: allCandidates.map(c => c.name) };
 }
 
+/**
+ * 从来源页里解析 `### 列表` / `### 结构设计分析` 的「| 名称 | 有/无 |」表格。
+ */
+function parseHasTable(content, heading) {
+  const headingIndex = content.indexOf(heading);
+  if (headingIndex === -1) return {};
+  const after = content.substring(headingIndex);
+  const nextHeading = after.match(/\n#{1,3}\s+\S/);
+  const tableEnd = nextHeading ? after.indexOf(nextHeading[0]) : after.length;
+  const tableContent = after.substring(0, tableEnd);
+  const out = {};
+  for (const line of tableContent.split('\n')) {
+    const row = line.match(/^\|\s*(.+?)\s*\|\s*(有|无)\s*\|/);
+    if (row) out[row[1].trim()] = row[2] === '有';
+  }
+  return out;
+}
+
+/**
+ * 只保留当前 schema 定义的按章类型。
+ * 旧来源页的「### 列表」里还有 伏笔回收/世界观构建/角色弧光 ——
+ * 它们是按章页面，新版不会再生成对应页面。不过滤的话 status 会一直
+ * 报这三类缺失、fix 重传后又永远补不上。
+ */
+function filterChapterTypes(table) {
+  return Object.fromEntries(
+    Object.entries(table).filter(([type]) => CHAPTER_PAGE_TYPES.has(type)));
+}
+
+/**
+ * 从来源页的「### 跨章节结构实体」表里解析实体行。
+ * 表头：结构类型 | 实体/线索 | 页面文件 | 本章动作 | 首次章节 | 本次章节
+ */
+function parseEntityRows(content, bookName, chapterKey) {
+  const heading = '### 跨章节结构实体';
+  const headingIndex = content.indexOf(heading);
+  if (headingIndex === -1) return [];
+  const after = content.substring(headingIndex);
+  const nextHeading = after.match(/\n#{1,3}\s+\S/);
+  const tableEnd = nextHeading ? after.indexOf(nextHeading[0]) : after.length;
+  const lines = after.substring(0, tableEnd).split('\n');
+  const rows = [];
+  for (const line of lines) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
+    if (cells.length < 6) continue;
+    const [type, entity, rawPageFile, action, firstChapter, currentChapter] = cells;
+    if (!ENTITY_STRUCTURE_TYPES.includes(type)) continue;
+    // 模型经常漏掉 .md、加反引号、或者写成 wiki/类型/文件名 的完整路径。
+    // 这里统一成裸文件名；带“第X章”的仍保留，交给下面的 invalidPageFile 报错。
+    let pageFile = String(rawPageFile || '')
+      .trim()
+      .replace(/^`+|`+$/g, '')
+      .replace(/^\[\[|\]\]$/g, '')
+      .trim();
+    if (pageFile.includes('/')) pageFile = pageFile.split('/').pop();
+    if (pageFile && pageFile !== '无' && pageFile !== '-' && !pageFile.endsWith('.md')) {
+      pageFile += '.md';
+    }
+    if (!pageFile || !pageFile.endsWith('.md')) continue;
+    rows.push({
+      bookName,
+      chapterKey,
+      type,
+      entity,
+      pageFile,
+      action,
+      // 跨章节实体页的文件名必须稳定：带“第X章”说明模型又按章建页了。
+      invalidPageFile: /第\d+章/.test(pageFile),
+      firstChapter: firstChapter && firstChapter !== '-' ? firstChapter : chapterKey,
+      currentChapter: currentChapter && currentChapter !== '-' ? currentChapter : chapterKey,
+    });
+  }
+  return rows;
+}
+
+/**
+ * 读实体页 frontmatter 里的 tags（支持行内数组和块列表）。
+ * 角色弧光页常把正式姓名/别名写在 tags 里，例如老班页的 tags 含“刘安国”。
+ */
+function parseFrontmatterTags(content) {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(content || ''));
+  if (!fm) return [];
+  const lines = fm[1].split(/\r?\n/);
+  const tags = [];
+  let inTags = false;
+  for (const line of lines) {
+    const m = /^tags\s*:\s*(.*)$/.exec(line.trim());
+    if (m) {
+      const raw = m[1].trim();
+      if (raw.startsWith('[') && raw.endsWith(']')) {
+        for (const item of raw.slice(1, -1).split(',')) {
+          const tag = item.trim().replace(/^["']|["']$/g, '');
+          if (tag) tags.push(tag);
+        }
+        inTags = false;
+      } else if (raw) {
+        tags.push(raw.replace(/^["']|["']$/g, ''));
+        inTags = false;
+      } else {
+        inTags = true;
+      }
+      continue;
+    }
+    if (!inTags) continue;
+    const item = /^\s*-\s+(.+)$/.exec(line);
+    if (item) {
+      const tag = item[1].trim().replace(/^["']|["']$/g, '');
+      if (tag) tags.push(tag);
+    } else if (line.trim()) {
+      inTags = false;
+    }
+  }
+  return tags;
+}
+
+/** 从实体页正文提取“正式姓名为X / 本名X / 又名X”这类别名。 */
+function parseAliasesFromContent(content) {
+  const out = [];
+  const re = /(?:正式姓名|本名|真名|原名|又名|化名|姓名)\s*[为是：:]\s*([\u4e00-\u9fa5]{2,4})/g;
+  let match;
+  while ((match = re.exec(String(content || ''))) !== null) {
+    if (match[1]) out.push(match[1]);
+  }
+  return out;
+}
+
+function hasChapterHeading(content, chapter) {
+  if (!chapter) return true;
+  const escaped = escapeRegExp(chapter);
+  // 允许 `### 第5章`、`## 第5章 转折`、`### 第5章：转折` 等写法；
+  // 但 `第1章` 不能匹配 `第10章`（后面紧跟数字时不放行）。
+  return new RegExp(`^#{2,3}\\s*${escaped}(?:\\s|$|[：:（(—-])`, 'm').test(content);
+}
+
+/**
+ * fix 重新 ingest 时带给 LLM 的修复指令。
+ *
+ * 只重传文件不够：模型可能再次漏掉同样的实体页/结构表。把这次
+ * 修复要重点检查的项目直接写进 ingest 任务，让分析/生成两个阶段都看到。
+ */
+function buildFixInstruction(bookName, chapter, pageInfo = null) {
+  const existing = Array.isArray(pageInfo?.existing) ? pageInfo.existing : [];
+  const missing = Array.isArray(pageInfo?.missing) ? pageInfo.missing : [];
+  const list = (items) => items.slice(0, 40).map((item) => `- ${item}`).join('\n');
+
+  const lines = [`这是《${bookName}》${chapter} 的修复性重新 ingest。`, ''];
+
+  if (existing.length > 0) {
+    lines.push('上次已经生成并保留的页面（本次不要重写）：');
+    lines.push(list(existing));
+    lines.push('');
+  }
+
+  lines.push('本次需要补的页面/小节：');
+  if (missing.length > 0) {
+    lines.push(list(missing));
+  } else {
+    // 正常不该走到这里；如果真没有 pageInfo，也只能给出本章级的明确动作，
+    // 不能再让模型去“猜 status 的缺失清单”。
+    lines.push('- 本章没有可枚举的页面级缺失；请重新核对来源页的「### 列表」与「### 跨章节结构实体」表，并按 schema 补齐。');
+  }
+  lines.push('');
+
+  lines.push('要求：');
+  lines.push('1. 只输出本次缺失页面/小节对应的 FILE 块；已经存在的页面不要重新生成；');
+  lines.push('2. 如果缺失的是实体页的 ### 第X章 小节，输出该实体页并只追加本章小节，页面合并会保留旧内容；');
+  lines.push('3. 如果缺失的是来源页或整章产物，按 schema 正常生成；');
+  lines.push('4. 已有实体页只追加本章小节，不得按章新建，不得换名新建；');
+  lines.push('5. 先读 对标/分析定义.md，按其中的术语定义判断，不要自创定义；');
+  lines.push('6. 14 种按章类型（13 种写作技法 + 章节功能设计）逐项判断“有/无”，标“有”的必须创建对应按章页面；');
+  lines.push('7. 本名/正式名优先；称呼、绰号、简称、集团/公司后缀不要另建实体。');
+  return lines.join('\n');
+}
+
 /**
  * 拷贝 schema 文件到目标目录
  */
@@ -245,13 +596,108 @@ function copySchemaFile(targetDir) {
   const targetPath = join(targetDir, 'schema.md');
   mkdirSync(targetDir, { recursive: true });
   copyFileSync(SCHEMA_SOURCE, targetPath);
+  // 术语定义是 schema 的配套权威文件，必须和 schema 一起部署。
+  copyFileSync(DEFINITIONS_SOURCE, join(targetDir, DEFINITIONS_FILENAME));
   return targetPath;
 }
 
+/** 读项目里的 对标/schema.md；不存在或读不了返回 null。 */
+function readAnalyzeSchema(projectRoot) {
+  const schemaPath = join(projectRoot, '对标', 'schema.md');
+  if (!existsSync(schemaPath)) return null;
+  try {
+    return readFileSync(schemaPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判断 对标/schema.md 是否是上一版（按章结构设计）。
+ * 旧版没有「### 跨章节结构实体」，且带「### 结构设计分析」。
+ * 旧 schema 会让 fix 继续生成按章的 伏笔回收/世界观构建/角色弧光 页面，
+ * 所以 fix 前必须先把它换成新版。
+ */
+function isLegacyAnalyzeSchema(content) {
+  if (!content) return true;
+  if (content.includes('### 结构设计分析')) return true;
+  if (!content.includes('### 跨章节结构实体')) return true;
+  if (!content.includes('世界观设计') || !content.includes('角色弧光设计')) return true;
+  return false;
+}
+
+/**
+ * fix 是否要把 对标/schema.md 刷新成插件当前版本。
+ *
+ * 不能只看“是不是旧版”：schema 里新加的强制核对清单、命名规则也要
+ * 能同步到已经初始化的项目，否则模型看不到最新约束。
+ */
+/**
+ * 对标/raw/sources 下是否有任何拆书分片（递归，忽略隐藏目录）。
+ *
+ * status / fix 的第一步：连源文件都没有，说明还没跑过 /fancy-analyze <书名>，
+ * 这时去检查 schema、覆盖、.retry 全是无意义的噪音。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasAnySourceFiles(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.isFile()) return true;
+    if (entry.isDirectory() && hasAnySourceFiles(join(dir, entry.name))) return true;
+  }
+  return false;
+}
+
+/**
+ * 对标/wiki 下是否已有任何拆解产物（旧项目可能清掉了 raw 分片）。
+ *
+ * 只看子目录里的 .md：wiki 根目录的 index.md / log.md / overview.md 是
+ * llm_wiki 建项目时生成的元数据，不能拿来证明“已经拆解过”。
+ */
+function hasAnyAnalyzeOutput(dir, depth = 0) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.isDirectory() && hasAnyAnalyzeOutput(join(dir, entry.name), depth + 1)) return true;
+    if (depth > 0 && entry.isFile() && entry.name.endsWith('.md')) return true;
+  }
+  return false;
+}
+
+function schemaNeedsRefresh(projectRoot) {
+  const current = readAnalyzeSchema(projectRoot);
+  if (!current) return true;
+  try {
+    const latest = readFileSync(SCHEMA_SOURCE, 'utf-8');
+    if (current.trim() !== latest.trim()) return true;
+
+    const defPath = join(projectRoot, '对标', DEFINITIONS_FILENAME);
+    if (!existsSync(defPath)) return true;
+    const currentDef = readFileSync(defPath, 'utf-8');
+    const latestDef = readFileSync(DEFINITIONS_SOURCE, 'utf-8');
+    return currentDef.trim() !== latestDef.trim();
+  } catch {
+    return isLegacyAnalyzeSchema(current);
+  }
+}
+
 export async function apply(ctx) {
   ctx.commands.register({
     name: 'fancy-analyze',
-    description: '🔍 拆解爆款小说（参考对标） ( usage: /fancy-analyze [书名] | status | fix | summary | summary-status | resummary [技法名] )',
+    description: '🔍 拆解爆款小说（参考对标） ( usage: /fancy-analyze [书名] | status | fix | summary | summary-status | resummary [技法名] | help )',
     input: {
       hint: '.',
     },
@@ -259,11 +705,15 @@ export async function apply(ctx) {
       const session = invocation.agent.session;
       const { signal } = invocation;
 
+      if ((invocation.rawInput || '').trim().toLowerCase() === 'help') {
+        return notify(session, 'success', analyze.notify({ type: 'help' }));
+      }
+
       const projectRoot = getProjectRoot(session);
       if (!projectRoot) {
         return notify(session, 'error', analyze.notify({
           type: 'no_project_root',
-          err: '会话未提供 cwd'
+          err: '会话未提供当前工作目录'
         }));
       }
 
@@ -321,30 +771,73 @@ export async function apply(ctx) {
           return notify(session, 'error', analyze.notify({ type: 'no_reference_id' }));
         }
 
+        const rawSourcesDir = join(projectRoot, '对标', 'raw', 'sources');
+        const hasSources = hasAnySourceFiles(rawSourcesDir);
+        const hasOutputs = hasAnyAnalyzeOutput(join(projectRoot, '对标', 'wiki'));
+        if (!hasSources && !hasOutputs) {
+          return notify(session, 'error', analyze.notify({ type: 'fix_not_analyzed' }));
+        }
+
+        // fix 是迁移旧项目的主要入口：先把 对标/schema.md 换成新版，
+        // 否则重新 ingest 会继续按旧 schema 生成按章结构页。
+        // 这一步放在 .retry 之前：即使没有缺失章节，用户也能用 fix 完成
+        // schema 迁移，而不会被“没有需要重试的项目”提前挡回去。
+        let schemaUpdated = false;
+        try {
+          if (schemaNeedsRefresh(projectRoot)) {
+            copySchemaFile(join(projectRoot, '对标'));
+            schemaUpdated = true;
+          }
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return notify(session, 'error',
+            `❌ 无法更新 对标/schema.md：${msg}\n\n` +
+            '续跑 fix 仍会按旧 schema 生成按章结构页，所以本次没有提交 ingest。\n' +
+            '请确认 对标/ 可写后重试。');
+        }
+        const schemaNote = schemaUpdated
+          ? '## 已更新对标 schema\n对标/schema.md 已更新为新版（写作技法 + 跨章节实体页）。\n\n'
+          : '';
+        const withSchemaNote = (text) => schemaNote ? schemaNote + text : text;
+
         // 读取 .retry 文件
         const retryFilePath = join(projectRoot, '.retry');
         if (!existsSync(retryFilePath)) {
-          return notify(session, 'error', `没有找到 .retry 文件。
-1. 如果已执行过 fancy-analyze status 子命令则代表已成功提取，可以继续执行 fancy-analyze summary
-2. 如果未执行过 fancy-analyze status 子命令请先执行该命令`);
+          return notify(session, 'error', withSchemaNote(`未找到 .retry 文件。
+1. 如果已执行过 /fancy-analyze status，说明已成功提取，可以继续执行 /fancy-analyze summary；
+2. 如果尚未执行过 /fancy-analyze status，请先执行该命令。`));
         }
 
         let retryData;
         try {
           retryData = JSON.parse(readFileSync(retryFilePath, 'utf-8'));
         } catch {
-          return notify(session, 'error', '.retry 文件格式错误');
+          return notify(session, 'error', withSchemaNote('.retry 文件格式错误，请检查文件内容后重试。'));
         }
 
         if (!retryData || !Array.isArray(retryData.items) || retryData.items.length === 0) {
-          return notify(session, 'success', '没有需要重试的项目');
+          return notify(session, 'success', withSchemaNote('当前没有需要重试的项目。'));
+        }
+
+        // status 额外写出的“已有页面 / 缺失页面”清单。旧项目没有这个文件时，
+        // fix 自动退回原来的通用修复指令。
+        let retryPageInfo = {};
+        try {
+          const pagesPath = join(projectRoot, '.retry-pages.json');
+          if (existsSync(pagesPath)) {
+            const parsed = JSON.parse(readFileSync(pagesPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object') retryPageInfo = parsed;
+          }
+        } catch {
+          retryPageInfo = {};
         }
 
-        const rawSourcesDir = join(projectRoot, '对标', 'raw', 'sources');
         const results = [];
         const errors = [];
 
-        for (const item of retryData.items) {
+        // .retry 是 status 写的（现在有序），但老文件可能是乱序的 ——
+        // 补传顺序跟着章号走，跟 ingest 的正常流程保持一致。
+        for (const item of sortByChapter(retryData.items, (it) => it && it.bookName)) {
           const { bookName, chapter } = item;
           // 定位文件：书名/ 目录下查找文件名包含"第X章"的文件
           const bookDir = join(rawSourcesDir, bookName);
@@ -353,7 +846,7 @@ export async function apply(ctx) {
             continue;
           }
 
-          let matchedFile = null;
+          let matchedFiles = [];
           try {
             const files = readdirSync(bookDir);
             // 查找文件名中包含"第X章"的文件（如：第8章-心好痛.txt）
@@ -361,21 +854,42 @@ export async function apply(ctx) {
             // 直接拼进正则的话，一旦内容里出现正则元字符就会抛 SyntaxError，
             // 而且 "." 未转义会让"第1章"匹配上"第1章X"这种文件名。
             const pattern = new RegExp(`${escapeRegExp(chapter)}.*\\.txt$`);
-            matchedFile = files.find(f => pattern.test(f));
-            if (!matchedFile) {
+            //
+            // **要全部匹配到的分片，不能只取第一个** ——
+            // 超长章会被 split_source.js 二次切分成
+            //   第7章-武科五大关-1.txt / 第7章-武科五大关-2.txt
+            // 两个文件名都匹配同一个正则，而 files.find() 只返回其中一个，
+            // 另一个分片永远补不上：服务端那一章的产物始终是残缺的
+            // （第一次 ingest 是把整章的分片一起传的，服务端会合并成
+            //   一章的产物；只补一半反而会把完整产物覆盖成半章）。
+            //
+            // 排序用自然序，保证「第-10」排在「第-2」后面，
+            // 补传顺序与初次 ingest 一致。
+            matchedFiles = files
+              .filter(f => pattern.test(f))
+              .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+            if (matchedFiles.length === 0) {
               errors.push(`未找到文件：${bookName} 下包含 ${chapter} 的文件`);
               continue;
             }
 
             // 清除 ingest-cache 中对应条目的 hash
+            // （一次读、一次改、一次写：多个分片共用一份 cache，
+            //   循环里反复读写会把前一次的结果覆盖掉）
             const ingestCachePath = join(projectRoot, '对标', '.llm-wiki', 'ingest-cache.json');
             if (existsSync(ingestCachePath)) {
               try {
                 const cacheContent = readFileSync(ingestCachePath, 'utf-8');
                 const cacheData = JSON.parse(cacheContent);
-                const cacheKey = `${bookName}/${matchedFile}`;
-                if (cacheData.entries && cacheData.entries[cacheKey]) {
-                  cacheData.entries[cacheKey].hash = '';
+                let cacheChanged = false;
+                for (const f of matchedFiles) {
+                  const cacheKey = `${bookName}/${f}`;
+                  if (cacheData.entries && cacheData.entries[cacheKey]) {
+                    cacheData.entries[cacheKey].hash = '';
+                    cacheChanged = true;
+                  }
+                }
+                if (cacheChanged) {
                   writeFileSync(ingestCachePath, JSON.stringify(cacheData, null, 2), 'utf-8');
                 }
               } catch {
@@ -383,7 +897,9 @@ export async function apply(ctx) {
               }
             }
 
-            const filePath = `raw/sources/${bookName}/${matchedFile}`;
+            // 整章的分片一起传 —— 与初次 ingest 的语义一致
+            // （初次是 split_files 全部一次传给服务端）。
+            const filePaths = matchedFiles.map(f => `raw/sources/${bookName}/${f}`);
             // 必须检查返回：ingest 返回 4xx/5xx 时 llm_wiki 根本没收到文件，
             // 之前这里不检查，命令照报"## 重新 ingest 成功"（实测：两个 POST
             // 都返回 500，用户看到的仍是"成功"）。
@@ -392,14 +908,23 @@ export async function apply(ctx) {
               llmWikiToken,
               `/projects/${referenceId}/sources/ingest`,
               'POST',
-              { paths: [filePath] }
+              {
+                paths: filePaths,
+                instruction: buildFixInstruction(
+                  bookName,
+                  chapter,
+                  retryPageInfo[`${bookName}::${chapter}`] || null,
+                ),
+              }
             );
             const apiErr = llmWikiError(ingestResult);
             if (apiErr) {
-              errors.push(`${bookName}/${matchedFile} - ${apiErr}`);
+              errors.push(`${bookName}/${matchedFiles.join('、')} - ${apiErr}`);
               continue;
             }
-            results.push(`${bookName}/${matchedFile}`);
+            for (const f of matchedFiles) {
+              results.push(`${bookName}/${f}`);
+            }
           } catch (err) {
             errors.push(`${bookName}/${chapter} - ${describeFetchError(err)}`);
           }
@@ -421,7 +946,7 @@ export async function apply(ctx) {
         const headline = (errors.length > 0 && results.length === 0)
           ? '重新 ingest 失败：\n\n'
           : '';
-        const finalMessage = headline + message + '\n\n请稍后执行 /fancy-analyze status 查看结果，如果仍有缺失需再次执行 /fancy-analyze fix';
+        const finalMessage = headline + schemaNote + message + '\n\n请稍后执行 /fancy-analyze status 查看结果，如果仍有缺失需再次执行 /fancy-analyze fix';
         return notify(session, results.length > 0 ? 'success' : 'error', finalMessage);
       }
 
@@ -444,12 +969,31 @@ export async function apply(ctx) {
           return notify(session, 'error', analyze.notify({ type: 'no_reference_id' }));
         }
 
+        const rawSourcesDir = join(projectRoot, '对标', 'raw', 'sources');
+        const hasSources = hasAnySourceFiles(rawSourcesDir);
+        const hasOutputs = hasAnyAnalyzeOutput(join(projectRoot, '对标', 'wiki'));
+        if (!hasSources && !hasOutputs) {
+          return notify(session, 'error', analyze.notify({ type: 'status_not_analyzed' }));
+        }
+
+        const schemaOutdated = isLegacyAnalyzeSchema(readAnalyzeSchema(projectRoot));
+
         // 检查来源目录下的文件，从"### 列表"表格中获取【有/无】信息
         // 同时读取"来源"和"来源摘要"两个目录
         // 映射格式：{ "书名": { "第X章": { "技法名": true/false, ... }, ... } }
         const bookChapterTechHas = {};
         // 记录缺少列表的章节
-        const missingListReports = [];
+        // 用 let：下面会按（书名, 章号）重排 —— readdirSync 返回的是目录项
+        // 哈希序（ext4 上表现为第7章排在第4章前面），不是字典序。
+        let missingListReports = [];
+        let structuralTableSeen = false;
+        let legacyStructuralTableSeen = false;
+        const entityRows = [];
+        const legacySourceChapters = [];
+
+        // "来源"和"来源摘要"两个目录里已有的 .md 文件名。
+        // 用来回答："raw/sources 里的这个分片，拆解产物落地了吗？"
+        const sourceFileNames = new Set();
 
         const sourceDirs = ['来源', '来源摘要'];
         for (const sourceDir of sourceDirs) {
@@ -460,6 +1004,7 @@ export async function apply(ctx) {
             const sourceFiles = readdirSync(duiBiaoWikiDir);
             for (const file of sourceFiles) {
               if (!file.endsWith('.md')) continue;
+              sourceFileNames.add(file);
               // 提取书名和第X章（如：全球高武-第10章-气血检查.md → 书名:全球高武, 第X章:第10章）
               // 格式：书名-第X章-xxx.md 或 书名-技法名-第X章.md
               const fullMatch = file.match(/^(.+?)-(第\d+章)-/);
@@ -473,6 +1018,14 @@ export async function apply(ctx) {
 
               const content = readFileSync(join(duiBiaoWikiDir, file), 'utf-8');
 
+              // 来源页没有新版结构表 → 这一章还是旧 schema 的产物。
+              // 只认 来源/，不认 来源摘要/：摘要页本来就可能没有技法表。
+              const hasNewStructureTables = content.includes('### 跨章节结构实体')
+                || content.includes('### 章节级结构设计');
+              if (sourceDir === '来源' && !hasNewStructureTables) {
+                legacySourceChapters.push({ bookName, chapter: chapterKey, file });
+              }
+
               // 查找"### 列表"三级标题的位置
               const listHeadingIndex = content.indexOf('### 列表');
               if (listHeadingIndex === -1) {
@@ -481,29 +1034,19 @@ export async function apply(ctx) {
                 continue;
               }
 
-              // 从"### 列表"之后提取表格内容（到下一个三级标题之前）
-              const afterList = content.substring(listHeadingIndex);
-              const nextHeadingMatch = afterList.match(/\n#{1,3}\s+\S/);
-              const tableEndIndex = nextHeadingMatch
-                ? afterList.indexOf(nextHeadingMatch[0])
-                : afterList.length;
-              const tableContent = afterList.substring(0, tableEndIndex);
-
-              // 解析 markdown 表格
-              const tableLines = tableContent.split('\n');
-              const techHas = {}; // { "世界观构建": true, "伏笔回收": false, ... }
-
-              for (const line of tableLines) {
-                // 匹配表格行：| 技法名 | 有/无 |
-                const rowMatch = line.match(/^\|\s*(.+?)\s*\|\s*(有|无)\s*\|/);
-                if (rowMatch) {
-                  const techName = rowMatch[1].trim();
-                  const hasValue = rowMatch[2] === '有';
-                  techHas[techName] = hasValue;
-                }
+              if (content.includes('### 跨章节结构实体') || content.includes('### 章节级结构设计')) {
+                structuralTableSeen = true;
               }
-
+              // 上一版 schema 的按章结构设计表；只用于提示迁移，不参与检查。
+              if (content.includes('### 结构设计分析')) legacyStructuralTableSeen = true;
+              // 按章类型：写作技法 + 章节功能设计。
+              // 过滤旧类型，避免 status 追着已废弃的按章页面不放。
+              const techHas = {
+                ...filterChapterTypes(parseHasTable(content, '### 列表')),
+                ...filterChapterTypes(parseHasTable(content, '### 章节级结构设计')),
+              };
               bookChapterTechHas[bookName][chapterKey] = techHas;
+              entityRows.push(...parseEntityRows(content, bookName, chapterKey));
             }
           } catch {
             // 忽略读取错误
@@ -513,6 +1056,7 @@ export async function apply(ctx) {
         // 检查各技法目录下是否有对应的文件
         // 映射格式：{ "书名": { "技法名": ["第X章", "第Y章", ...], ... }, ... }
         const bookTechChapters = {};
+        const legacyStructureDirs = new Map();
 
         const duiBiaoWikiRoot = join(projectRoot, '对标', 'wiki');
         if (existsSync(duiBiaoWikiRoot)) {
@@ -522,9 +1066,20 @@ export async function apply(ctx) {
             if (dir === '来源' || dir === '来源摘要') continue;
 
             const dirPath = join(duiBiaoWikiRoot, dir);
-            if (!statSync(dirPath).isDirectory()) continue;
-
-            const files = readdirSync(dirPath);
+            let dirStat = null;
+            try { dirStat = statSync(dirPath); } catch { continue; }
+            if (!dirStat.isDirectory()) continue;
+
+            let files = [];
+            try { files = readdirSync(dirPath); } catch { continue; }
+
+            // 旧版按章结构页：只统计并提示迁移，不当作新版技法/实体页。
+            if (LEGACY_STRUCTURE_DIRS.includes(dir)) {
+              const pageCount = files.filter(
+                (file) => file.endsWith('.md') && !file.endsWith('-总结.md')).length;
+              legacyStructureDirs.set(dir, pageCount);
+              continue;
+            }
             for (const file of files) {
               if (!file.endsWith('.md')) continue;
               // 提取书名和第X章（如：全球高武-节奏韵律-第10章.md → 书名:全球高武, 第X章:第10章）
@@ -546,11 +1101,79 @@ export async function apply(ctx) {
           }
         }
 
+        // 跨章节实体页：按“类型 + 文件名”索引，并读取正文用于检查章节小节。
+        const entityPageContents = new Map();
+        const legacyEntityChapterPages = new Map();
+        for (const type of ENTITY_STRUCTURE_TYPES) {
+          const dirPath = join(duiBiaoWikiRoot, type);
+          if (!existsSync(dirPath)) continue;
+          let files = [];
+          try { files = readdirSync(dirPath); } catch { continue; }
+          for (const file of files) {
+            if (!file.endsWith('.md')) continue;
+            if (file.endsWith('-总结.md')) continue;
+            // 实体目录里的按章文件是上一版 schema 的产物；不把它当成
+            // 新版实体页，否则 status 会误以为实体页已经存在。
+            if (/第\d+章/.test(file)) {
+              const list = legacyEntityChapterPages.get(type) || [];
+              list.push(file);
+              legacyEntityChapterPages.set(type, list);
+              continue;
+            }
+            try {
+              entityPageContents.set(
+                `${type}::${file}`,
+                readFileSync(join(dirPath, file), 'utf-8'),
+              );
+            } catch {
+              // 读不到就当缺失，下面会报出来
+            }
+          }
+        }
+
+        // 章节列表按（书名, 章号）排 —— 遍历用的是 readdirSync 的返回顺序
+        missingListReports = sortByChapter(missingListReports);
+
+        // ---- 拆解产物缺失检查 ----
+        //
+        // 前两项检查都是"文件在 来源/ 里存在"的前提下做的：
+        //   · "列表未找到" —— 文件在，但内容里没有 ### 列表 段；
+        //   · "缺失检测"   —— 文件在，列表说某技法"有"，但技法文件没落地。
+        //
+        // 但还有一种更靠前的情况压根没被检查到：**分片在 raw/sources/ 里，
+        // 而 来源/ 和 来源摘要/ 里连对应的章节文件都没有** —— 这一章
+        // 根本没被拆解，或者拆了但没落盘。
+        //
+        // 服务端的 missingFiles 只反映它自己的队列状态，拆解"跑完了"
+        // 但产物没落盘这种情况它不知道，所以要本地查这一份。
+        const missingIngestOutputs = findMissingIngestOutputs({
+          rawSourcesDir,
+          sourceFileNames,
+        });
+        const missingIngestReports = sortByChapter(
+          missingIngestOutputs.map(o => o.report));
+        const missingIngestItems = missingIngestOutputs
+          .filter(o => o.chapter)
+          .map(o => ({ bookName: o.bookName, chapter: o.chapter }));
+
         // 比对结果：找出"标记为有、但技法目录里没有对应文件"的章节。
         // 之前同一段逻辑算了两遍（一次出报告、一次出 .retry），
         // 两份循环还得保持一致，改一处漏一处就会让报告和 .retry 对不上。
-        const missingReports = [];
+        let missingReports = [];
         const retryItems = [];
+        const retryReasons = new Map();
+        const addRetry = (bookName, chapter, reason) => {
+          if (!bookName || !chapter) return;
+          const key = bookName + '::' + chapter;
+          if (reason) {
+            const set = retryReasons.get(key) || new Set();
+            set.add(reason);
+            retryReasons.set(key, set);
+          }
+          const exists = retryItems.some(
+            (item) => item.bookName === bookName && item.chapter === chapter);
+          if (!exists) retryItems.push({ bookName, chapter });
+        };
         for (const [bookName, chapterTechHas] of Object.entries(bookChapterTechHas)) {
           for (const [chapter, techHas] of Object.entries(chapterTechHas)) {
             const missingTechs = [];
@@ -565,10 +1188,134 @@ export async function apply(ctx) {
             }
             if (missingTechs.length > 0) {
               missingReports.push(`${bookName}${chapter}的ingest有缺失，缺失的为${missingTechs.join('、')}`);
-              retryItems.push({ bookName, chapter });
+              addRetry(bookName, chapter, '按章技法页缺失：' + missingTechs.join('、'));
+            }
+          }
+        }
+        // 跨章节实体页检查：页面不存在 → 重 ingest 首次章节；
+        // 页面存在但没有本次章节小节 → 重 ingest 本次章节。
+        const entityMissingReports = [];
+        const entitySectionGaps = new Map();
+        const pushRetry = (bookName, chapter, reason) => addRetry(bookName, chapter, reason);
+        // 同一实体可能在多章被引用；按“类型 + 页面文件”分组后再报，
+        // 否则一个缺失页面会按章重复几十行，真正的缺失反而被淹没。
+        const entityGroups = new Map();
+        for (const row of entityRows) {
+          const chapter = row.currentChapter || row.chapterKey;
+          const key = `${row.bookName}::${row.type}::${row.pageFile}`;
+          let group = entityGroups.get(key);
+          if (!group) {
+            group = {
+              bookName: row.bookName,
+              type: row.type,
+              pageFile: row.pageFile,
+              invalidPageFile: row.invalidPageFile,
+              entities: new Set(),
+              chapters: new Set(),
+            };
+            entityGroups.set(key, group);
+          }
+          group.entities.add(row.entity);
+          if (chapter) group.chapters.add(chapter);
+          if (row.invalidPageFile) group.invalidPageFile = true;
+        }
+
+        for (const group of entityGroups.values()) {
+          const chapters = [...group.chapters].sort(
+            (a, b) => (chapterNumber(a) ?? Number.MAX_SAFE_INTEGER) -
+              (chapterNumber(b) ?? Number.MAX_SAFE_INTEGER));
+          const firstChapter = chapters[0] || null;
+          const entityLabel = [...group.entities].join('、');
+          if (group.invalidPageFile) {
+            entityMissingReports.push(
+              `${group.bookName}的${group.type}实体「${entityLabel}」页面文件名 ${group.pageFile} 带章节号；跨章节实体页必须用稳定实体名，不能按章建页`);
+            for (const chapter of chapters) pushRetry(group.bookName, chapter, '实体页文件名带章节号：' + group.pageFile);
+            continue;
+          }
+          const content = entityPageContents.get(`${group.type}::${group.pageFile}`);
+          if (content === undefined) {
+            entityMissingReports.push(
+              `${group.bookName}的${group.type}实体「${entityLabel}」缺少页面 ${group.pageFile}（首次出现 ${firstChapter || '未知'}；涉及 ${chapters.join('、') || '未知章节'}）`);
+            for (const chapter of chapters) pushRetry(group.bookName, chapter, '实体页整页缺失：' + group.pageFile);
+            continue;
+          }
+          for (const chapter of chapters) {
+            if (hasChapterHeading(content, chapter)) continue;
+            entityMissingReports.push(
+              `${group.bookName}的${group.type}实体「${entityLabel}」页面 ${group.pageFile} 缺少 ${chapter} 小节`);
+            entitySectionGaps.set(
+              group.type, (entitySectionGaps.get(group.type) || 0) + 1);
+            pushRetry(group.bookName, chapter, '实体页缺少 ' + chapter + ' 小节：' + group.pageFile);
+          }
+        }
+
+        // 角色弧光覆盖的启发式检查：人物关系页的两端通常就是角色。
+        // 缺页的角色所在关系章节进 .retry，fix 重传后才会按新版 schema
+        // 为这些角色补角色弧光页。
+        let missingArcs = [];
+        const missingArcChapters = new Map();
+        {
+          const arcNames = new Set();
+          for (const row of entityRows) {
+            if (row.type !== '角色弧光设计') continue;
+            const entity = String(row.entity || '').trim();
+            if (entity) arcNames.add(entity);
+            // 弧光页可能用“老班”建档，但正式姓名“刘安国”写在 tags 或正文里。
+            // 只看 entity 会把这种别名的关系端点误报成“缺角色弧光页”。
+            const content = entityPageContents.get(`${row.type}::${row.pageFile}`) || '';
+            for (const tag of parseFrontmatterTags(content)) arcNames.add(tag);
+            for (const alias of parseAliasesFromContent(content)) arcNames.add(alias);
+          }
+          const relationCharacterNames = new Set();
+          const nonCharacterName = /(父母|家人|兄弟|姐妹|同学|老师|全班|众人|人群|集团|公司|大学|学院|医院|银行|协会|联盟|家族|国家|班级|政府|部门|学校|武大|一中)/u;
+          for (const row of entityRows) {
+            if (row.type !== '人物关系设计') continue;
+            for (const part of String(row.entity || '').split(/[-—–与、,，]/u)) {
+              const name = part.trim();
+              if (name.length < 2 || name.length > 4) continue;
+              if (nonCharacterName.test(name)) continue;
+              relationCharacterNames.add(name);
+            }
+          }
+          missingArcs = [...relationCharacterNames].filter((name) => !arcNames.has(name));
+          for (const name of missingArcs) {
+            const byBook = new Map();
+            for (const row of entityRows) {
+              if (row.type !== '人物关系设计') continue;
+              const parts = String(row.entity || '')
+                .split(/[-—–与、,，]/u)
+                .map((part) => part.trim());
+              if (!parts.includes(name)) continue;
+              const chapter = row.currentChapter || row.chapterKey;
+              if (!chapter) continue;
+              if (!byBook.has(row.bookName)) byBook.set(row.bookName, new Set());
+              byBook.get(row.bookName).add(chapter);
+            }
+            for (const [bookName, chapters] of byBook) {
+              missingArcChapters.set(bookName + '::' + name, chapters);
+              for (const chapter of chapters) {
+                pushRetry(bookName, chapter, '角色弧光页整页缺失：' + name);
+              }
             }
           }
         }
+
+        // 旧 schema 的来源页：重传这一章，才能生成「### 跨章节结构实体」
+        // 表和后续实体页。没有这一步，旧项目永远停留在按章结构页。
+        for (const item of legacySourceChapters) {
+          pushRetry(item.bookName, item.chapter, '来源页需要重生成跨章节结构实体表');
+        }
+
+        // 实体目录里已经存在按章文件：重传对应章节，让 ingest 先把它们
+        // 合并成稳定实体页，再补本章内容。
+        for (const files of legacyEntityChapterPages.values()) {
+          for (const file of files) {
+            const match = file.match(/^(.+?)-.*?第(\d+)章/);
+            if (!match) continue;
+            pushRetry(match[1], `第${match[2]}章`, '按章命名的实体页需要合并：' + file);
+          }
+        }
+
         // 添加缺少列表的章节到 retry
         for (const report of missingListReports) {
           const match = report.match(/^(.+?)(第\d+章)的列表未找到/);
@@ -577,17 +1324,117 @@ export async function apply(ctx) {
             const chapter = match[2];
             const exists = retryItems.some(item => item.bookName === bookName && item.chapter === chapter);
             if (!exists) {
-              retryItems.push({ bookName, chapter });
+              addRetry(bookName, chapter, '来源页缺少「### 列表」表');
+            }
+          }
+        }
+        // 拆解产物缺失的章节同样进 retry —— 补传这一章才能把产物补出来
+        for (const item of missingIngestItems) {
+          const exists = retryItems.some(
+            r => r.bookName === item.bookName && r.chapter === item.chapter);
+          if (!exists) {
+            addRetry(item.bookName, item.chapter, '整章拆解产物缺失');
+          }
+        }
+        // 章节列表按（书名, 章号）排
+        missingReports = sortByChapter(missingReports);
+
+        // 给 fix 准备“已有哪些页面 / 本次缺哪些页面”。
+        // 写在单独的 .retry-pages.json，避免改变 .retry 的既有结构。
+        const buildRetryPageInfo = (bookName, chapter) => {
+          const existing = new Set();
+          const missing = new Set();
+
+          const sourcePrefix = `${bookName}-${chapter}-`;
+          const sourcePages = [...sourceFileNames].filter((file) => file.startsWith(sourcePrefix));
+          for (const file of sourcePages) {
+            const sourceDir = existsSync(join(projectRoot, '对标', 'wiki', '来源', file))
+              ? '来源'
+              : existsSync(join(projectRoot, '对标', 'wiki', '来源摘要', file))
+                ? '来源摘要'
+                : '来源';
+            existing.add(`wiki/${sourceDir}/${file}`);
+          }
+          if (sourcePages.length === 0) {
+            missing.add(`wiki/来源/${bookName}-${chapter}-*.md（来源页）`);
+          }
+
+          const techHas = bookChapterTechHas[bookName]?.[chapter] || {};
+          for (const [tech, hasValue] of Object.entries(techHas)) {
+            if (hasValue !== true) continue;
+            const pagePath = `wiki/${tech}/${bookName}-${tech}-${chapter}.md`;
+            if (bookTechChapters[bookName]?.[tech]?.includes(chapter)) {
+              existing.add(pagePath);
+            } else {
+              missing.add(pagePath);
+            }
+          }
+
+          const rows = entityRows.filter(
+            (row) => row.bookName === bookName &&
+              (row.currentChapter || row.chapterKey) === chapter);
+          for (const row of rows) {
+            if (row.invalidPageFile) {
+              missing.add(`wiki/${row.type}/${row.pageFile}（文件名带章节号，必须改成稳定实体名）`);
+              continue;
+            }
+            const pagePath = `wiki/${row.type}/${row.pageFile}`;
+            const content = entityPageContents.get(`${row.type}::${row.pageFile}`);
+            if (content === undefined) {
+              missing.add(`${pagePath}（实体页整页缺失）`);
+            } else if (!hasChapterHeading(content, chapter)) {
+              missing.add(`${pagePath}（缺少 ${chapter} 小节）`);
+            } else {
+              existing.add(pagePath);
+            }
+          }
+
+          // 角色弧光缺页：必须把具体页面写进 .retry-pages.json，
+          // 否则 fix 的提示词没有可列出的页面，只能让模型去猜。
+          for (const [key, chapters] of missingArcChapters) {
+            if (!chapters.has(chapter)) continue;
+            const sep = key.indexOf('::');
+            const arcBook = key.slice(0, sep);
+            const arcName = key.slice(sep + 2);
+            if (arcBook !== bookName || !arcName) continue;
+            missing.add(`wiki/角色弧光设计/${bookName}-角色-${arcName}.md（整页缺失）`);
+          }
+
+          // 其他无法枚举成页面路径的缺失原因（来源页缺列表、旧 schema 等）
+          // 也要明确写出来，不能让 fix 去猜。
+          if (missing.size === 0) {
+            const reasons = retryReasons.get(bookName + '::' + chapter);
+            if (reasons) {
+              for (const reason of reasons) missing.add(reason);
             }
           }
+
+          if (sourcePages.length === 0 && rows.length === 0 &&
+              !Object.values(techHas).some((value) => value === true)) {
+            missing.add('整章拆解产物（来源页 + 按章页面 + 实体页）');
+          }
+
+          return { existing: [...existing], missing: [...missing] };
+        };
+
+        const retryPageInfo = {};
+        for (const item of retryItems) {
+          retryPageInfo[`${item.bookName}::${item.chapter}`] =
+            buildRetryPageInfo(item.bookName, item.chapter);
         }
+
+        // .retry 里的 items 同样排序：它是按缺失检测的遍历顺序 push 的，
+        // 乱序会让 /fancy-analyze fix 的补传顺序跟着乱。
+        const sortedRetryItems = sortByChapter(retryItems, (it) => it && it.bookName);
+
         // 根据当前检查结果覆盖 .retry 文件
         // 写失败必须说出来：写不进去的话，后面 /fancy-analyze fix 只会报
         // "没有找到 .retry 文件"，用户完全不知道真正的失败原因在这里。
         let retryWriteError = null;
+        let retryPagesWriteError = null;
         try {
-          if (retryItems.length > 0) {
-            writeFileSync(join(projectRoot, '.retry'), JSON.stringify({ items: retryItems }, null, 2), 'utf-8');
+          if (sortedRetryItems.length > 0) {
+            writeFileSync(join(projectRoot, '.retry'), JSON.stringify({ items: sortedRetryItems }, null, 2), 'utf-8');
           } else {
             // 没有缺失项时删除 .retry 文件
             const retryFilePath = join(projectRoot, '.retry');
@@ -599,6 +1446,17 @@ export async function apply(ctx) {
           retryWriteError = err instanceof Error ? err.message : String(err);
         }
 
+        try {
+          const pagesPath = join(projectRoot, '.retry-pages.json');
+          if (sortedRetryItems.length > 0) {
+            writeFileSync(pagesPath, JSON.stringify(retryPageInfo, null, 2), 'utf-8');
+          } else if (existsSync(pagesPath)) {
+            unlinkSync(pagesPath);
+          }
+        } catch (err) {
+          retryPagesWriteError = err instanceof Error ? err.message : String(err);
+        }
+
         try {
           const result = await queryIngestStatus(llmWikiUrl, llmWikiToken, referenceId);
 
@@ -612,26 +1470,164 @@ export async function apply(ctx) {
             }));
           }
 
-          const missingFiles = result.data.missingFiles || [];
+          const missingFiles = sortByChapter(result.data.missingFiles || []);
           const queue = result.data.queue || {};
 
-          let message = '';
+          const entityStats = ENTITY_STRUCTURE_TYPES.map((type) => {
+            const pages = new Set(
+              entityRows.filter((row) => row.type === type).map((row) => row.pageFile));
+            const missing = [...pages].filter(
+              (file) => !entityPageContents.has(`${type}::${file}`)).length;
+            return {
+              type,
+              entities: pages.size,
+              missing,
+              sectionGaps: entitySectionGaps.get(type) || 0,
+            };
+          });
+          const coverageLines = [];
+          if (entityStats.some((s) => s.entities > 0)) {
+            coverageLines.push('## 跨章节实体覆盖');
+            for (const s of entityStats) {
+              const arcGap = s.type === '角色弧光设计' ? missingArcs.length : 0;
+              if (s.entities === 0) {
+                coverageLines.push(`- ℹ️ ${s.type}：0 个（本书未引用，不算缺失）`);
+              } else if (s.missing > 0 || s.sectionGaps > 0 || arcGap > 0) {
+                const parts = [`${s.entities} 个实体页`];
+                if (s.missing > 0) parts.push(`缺 ${s.missing} 个`);
+                if (s.sectionGaps > 0) parts.push(`另有 ${s.sectionGaps} 个章节小节缺失`);
+                if (arcGap > 0) parts.push(`另有 ${arcGap} 个角色缺页`);
+                coverageLines.push(`- ❌ ${s.type}：${parts.join('，')}`);
+              } else {
+                coverageLines.push(`- ✅ ${s.type}：${s.entities} 个实体页`);
+              }
+            }
+            const totalMissingPages = entityStats.reduce((n, s) => n + s.missing, 0);
+            const hasLegacyStructureFiles = legacyStructureDirs.size > 0 || legacyEntityChapterPages.size > 0;
+            coverageLines.push('');
+            if (hasLegacyStructureFiles) {
+              coverageLines.push('⚠️ 结构设计覆盖未完成：还有旧版/按章命名的实体文件需要迁移。');
+            } else if (missingArcs.length > 0) {
+              coverageLines.push(`❌ 角色弧光覆盖不完整：${missingArcs.length} 个角色缺角色弧光页。`);
+            } else if (entityMissingReports.length === 0 && totalMissingPages === 0) {
+              coverageLines.push('✅ 结构设计覆盖完整，未发现缺失。');
+            }
+            coverageLines.push('');
+          }
+          if (legacyStructureDirs.size > 0) {
+            coverageLines.push('## 旧版结构页（不参与新实体检查）');
+            for (const [name, pageCount] of legacyStructureDirs) {
+              coverageLines.push(`- ⚠️ ${name}：${pageCount} 个按章页面`);
+            }
+            coverageLines.push('  ⚠️ 新版改用跨章节实体页：伏笔回收→伏笔布局、世界观构建/世界观规则设计→世界观设计、角色弧光→角色弧光设计。');
+            coverageLines.push('  ⚠️ 重新 ingest 对应章节后由新 schema 生成实体页；旧页面不会自动迁移，可确认后手动删除。');
+            coverageLines.push('');
+          }
+          if (legacyEntityChapterPages.size > 0) {
+            coverageLines.push('## 按章命名的实体页（不符合跨章节规则）');
+            for (const [type, files] of legacyEntityChapterPages) {
+              coverageLines.push(`- ❌ ${type}：${files.length} 个带章节号的文件`);
+            }
+            coverageLines.push('  ❌ 实体页文件名不应带 `第X章`；/fancy-analyze fix 会在重新 ingest 时自动合并为稳定实体页。');
+            coverageLines.push('');
+          }
+          // 去掉最后一个空行，同时保证各覆盖小节之间恰好一个空行。
+          while (coverageLines.length > 0 && coverageLines[coverageLines.length - 1] === '') {
+            coverageLines.pop();
+          }
+          let structuralCoverage;
+          if (coverageLines.length > 0) {
+            structuralCoverage = coverageLines.join('\n');
+          } else if (structuralTableSeen) {
+            structuralCoverage = '## 跨章节实体覆盖\nℹ️ 结构设计表存在，但还没有记录任何跨章节实体。';
+          } else if (legacyStructuralTableSeen) {
+            structuralCoverage = '## 跨章节实体覆盖\n⚠️ 检测到旧版「### 结构设计分析」表（按章结构页）。新版改为「### 跨章节结构实体」；重新 ingest 后才会生成跨章节实体页。';
+          } else {
+            structuralCoverage = '## 跨章节实体覆盖\nℹ️ 未发现结构设计分析表（可能是旧版拆解结果；重新 ingest 后才会出现跨章节实体页）。';
+          }
+
+          const problemLines = [];
+          if (schemaOutdated) {
+            problemLines.push('## 对标 schema 版本');
+            problemLines.push('⚠️ 检测到 对标/schema.md 是旧版（按章结构设计）。');
+            problemLines.push('⚠️ /fancy-analyze fix 会先更新为新版 schema，再补传缺失章节；否则重新 ingest 仍会生成伏笔回收/世界观构建/角色弧光这些按章页面。');
+          }
           if (retryWriteError) {
-            message += `\n\n❌ 写入 .retry 文件失败：${retryWriteError}` +
-              '\n缺失清单没能保存，/fancy-analyze fix 将无法工作。';
+            problemLines.push('## .retry 写入失败');
+            problemLines.push(`❌ 写入 .retry 文件失败：${retryWriteError}`);
+            problemLines.push('❌ 缺失清单没能保存，/fancy-analyze fix 将无法工作。');
+          }
+          if (retryPagesWriteError) {
+            problemLines.push('## .retry-pages 写入失败');
+            problemLines.push(`⚠️ 写入 .retry-pages.json 失败：${retryPagesWriteError}`);
+            problemLines.push('⚠️ fix 将退回通用修复指令，无法列出“已有页面/缺失页面”。');
           }
           if (missingReports.length > 0) {
-            message += '\n\n## 缺失检测\n' + missingReports.join('\n');
+            problemLines.push('## 缺失检测');
+            for (const report of missingReports) problemLines.push(`❌ ${report}`);
           }
           if (missingListReports.length > 0) {
-            message += '\n\n## 列表未找到\n' + missingListReports.join('\n');
+            problemLines.push('## 列表未找到');
+            for (const report of missingListReports) problemLines.push(`❌ ${report}`);
+          }
+          if (missingIngestReports.length > 0) {
+            problemLines.push('## 拆解产物缺失');
+            for (const report of missingIngestReports) problemLines.push(`❌ ${report}`);
+          }
+          if (entityMissingReports.length > 0) {
+            problemLines.push('## 结构设计实体缺失');
+            for (const report of entityMissingReports) problemLines.push(`❌ ${report}`);
+          }
+          const aliasReports = new Map();
+          for (const row of entityRows) {
+            if (!RELATION_ONLY_ENTITY_RE.test(String(row.entity || '').trim())) continue;
+            aliasReports.set(`${row.type}::${row.pageFile}`, row);
+          }
+          if (aliasReports.size > 0) {
+            problemLines.push('## 疑似称呼实体');
+            for (const row of aliasReports.values()) {
+              problemLines.push(`⚠️ ${row.type}「${row.entity}」可能是某个角色的称呼，不应单独建页；请合并到本名页`);
+            }
+          }
+
+          if (missingArcs.length > 0) {
+            problemLines.push('## 角色弧光覆盖');
+            problemLines.push(`⚠️ 以下角色出现在人物关系里，但没有角色弧光页：${missingArcs.join('、')}`);
+            problemLines.push('⚠️ 新版 schema 要求每个有名角色都有角色弧光页；/fancy-analyze fix 重传相关章节后会补。');
+          }
+
+          if (legacyStructureDirs.size > 0 || legacyEntityChapterPages.size > 0) {
+            problemLines.push('## 结构设计文件需要迁移');
+            problemLines.push('⚠️ 检测到旧版结构页或按章命名的实体页，详见下方覆盖统计；/fancy-analyze fix 会合并/重传。');
+          }
+          if (legacySourceChapters.length > 0) {
+            const byBook = new Map();
+            for (const item of legacySourceChapters) {
+              if (!byBook.has(item.bookName)) byBook.set(item.bookName, new Set());
+              byBook.get(item.bookName).add(item.chapter);
+            }
+            const lines = [];
+            let total = 0;
+            for (const [book, chapters] of byBook) {
+              const sorted = [...chapters].sort(
+                (a, b) => a.localeCompare(b, 'zh-Hans-CN', { numeric: true }));
+              const preview = sorted.slice(0, 5).join('、') +
+                (sorted.length > 5 ? ` 等 ${sorted.length} 章` : '');
+              lines.push(`⚠️ ${book}：${preview}`);
+              total += sorted.length;
+            }
+            problemLines.push('## 旧 schema 章节');
+            problemLines.push(...lines);
+            problemLines.push(`⚠️ 共 ${total} 章缺少「### 跨章节结构实体」表。`);
+            problemLines.push('⚠️ /fancy-analyze fix 会先更新 schema，再用新版重传这些章节。');
           }
 
           return notify(session, 'success', analyze.notify({
             type: 'status_result',
             missingFiles,
             queue,
-            extraMessage: message,
+            extraMessage: problemLines.join('\n').replace(/\n(?=## )/g, '\n\n'),
+            coverageMessage: structuralCoverage,
           }));
         } catch (err) {
           const errMsg = describeFetchError(err);
@@ -642,12 +1638,19 @@ export async function apply(ctx) {
         }
       }
 
-      // 2.3 summary-status：查技法总结进度（纯本地，零网络、零 LLM）
+      // 2.3 summary-status：查技法总结进度。
       //
-      // 这一支刻意不碰 llm_wiki：summary 的进度是**本地文件系统事实**
-      // （总结文件头部的「已总结章节」清单），跟 llm_wiki 的 ingest 队列
-      // 是两回事 —— ingest 队列是"拆解"进度，summary-status 是"总结"进度。
+      // 和 summary / resummary 一样先确认 ingest 完成：ingest 还没结束时，
+      // wiki 里可能只有一部分来源页，此时显示"进度"会把用户引向错误结论。
+      // 进度本身仍然是本地文件系统事实，但门禁必须先过。
       if (isSummaryStatus) {
+        if (signal?.aborted) {
+          return notify(session, 'error', analyze.notify({ type: 'cancelled' }));
+        }
+        const ingestReady = await checkIngestReadyForSummary(projectRoot, { command: 'summary-status' });
+        if (!ingestReady.ok) {
+          return notify(session, 'error', ingestReady.text);
+        }
         const wikiRoot = join(projectRoot, '对标', 'wiki');
         if (!existsSync(wikiRoot)) {
           return notify(session, 'error', '❌ "对标/wiki" 目录不存在');
@@ -669,12 +1672,19 @@ export async function apply(ctx) {
       // 新写的和旧的混在一起，文件越滚越胖。移走是最干脆的"重来"。
       // 备份而不是删除：旧总结可能还有参考价值。
       if (isResummary) {
+        if (signal?.aborted) {
+          return notify(session, 'error', analyze.notify({ type: 'cancelled' }));
+        }
+        const ingestReady = await checkIngestReadyForSummary(projectRoot, { command: 'resummary' });
+        if (!ingestReady.ok) {
+          return notify(session, 'error', ingestReady.text);
+        }
         const wikiRoot = join(projectRoot, '对标', 'wiki');
         if (!existsSync(wikiRoot)) {
           return notify(session, 'error', '❌ "对标/wiki" 目录不存在');
         }
 
-        const allDirs = listTechDirs(wikiRoot);
+        const allDirs = listSummaryDirs(wikiRoot);
         const targets = resummaryTarget
           ? allDirs.filter((name) => name === resummaryTarget)
           : allDirs;
@@ -682,8 +1692,8 @@ export async function apply(ctx) {
         if (resummaryTarget && targets.length === 0) {
           const known = allDirs.join('、');
           return notify(session, 'error',
-            `❌ 没有名为「${resummaryTarget}」的技法目录` +
-            (known ? `。可用：${known}` : '（对标/wiki 下还没有技法目录）'));
+            `❌ 未找到名为「${resummaryTarget}」的总结目录` +
+            (known ? `。可用目录：${known}` : '（对标/wiki 下尚无可用总结目录）'));
         }
 
         const stamp = backupStamp(Date.now());
@@ -709,6 +1719,7 @@ export async function apply(ctx) {
         // 提示词同样只给目录：章节名让模型自己去目录里找。
         const tasks = dirsToDispatch(progress).map((p) => ({
           name: p.name,
+          scope: p.scope,
           sourceCount: p.sourceCount,
           pendingCount: p.pendingFiles.length,
         }));
@@ -716,7 +1727,23 @@ export async function apply(ctx) {
 
         let dispatched = 0;
         if (tasks.length > 0) {
-          const prompt = analyze.generateSummarySystemPrompt({ tasks, remainingChapters });
+          // 脚本复制到项目里再让模型调用 —— 不在 node_modules 里跑
+          const registerTool = ensureRegisterScript(projectRoot);
+          if (!registerTool) {
+            return notify(session, 'error', analyze.notify({
+              type: 'register_script_failed',
+              projectRoot,
+            }));
+          }
+          const prompt = analyze.generateSummarySystemPrompt({
+            tasks,
+            remainingChapters,
+            projectRoot,
+            registerScript: registerTool,
+          });
+          if (signal?.aborted) {
+            return notify(session, 'error', analyze.notify({ type: 'cancelled' }));
+          }
           const follow = await llmFollowup(invocation, prompt);
           if (!follow || follow.ok !== true) {
             return notify(session, 'error',
@@ -744,6 +1771,13 @@ export async function apply(ctx) {
       // 模型一个字都还没写 —— 那是假成功。
       if (isSummary) {
         try {
+          if (signal?.aborted) {
+            return notify(session, 'error', analyze.notify({ type: 'cancelled' }));
+          }
+          const ingestReady = await checkIngestReadyForSummary(projectRoot, { command: 'summary' });
+          if (!ingestReady.ok) {
+            return notify(session, 'error', ingestReady.text);
+          }
           const wikiRoot = join(projectRoot, '对标', 'wiki');
           if (!existsSync(wikiRoot)) {
             return notify(session, 'error', '❌ "对标/wiki" 目录不存在');
@@ -767,15 +1801,32 @@ export async function apply(ctx) {
           // 每个目录里写清楚"怎么判断哪些章节还没总结"，模型自己去目录里找。
           const tasks = toDispatch.map((p) => ({
             name: p.name,
+            scope: p.scope,
             sourceCount: p.sourceCount,
             pendingCount: p.pendingFiles.length,
           }));
           const remainingChapters = toDispatch.reduce((n, p) => n + p.pendingFiles.length, 0);
 
           // 生成提示词
-          const prompt = analyze.generateSummarySystemPrompt({ tasks, remainingChapters });
+          // 脚本复制到项目里再让模型调用 —— 不在 node_modules 里跑
+          const registerTool = ensureRegisterScript(projectRoot);
+          if (!registerTool) {
+            return notify(session, 'error', analyze.notify({
+              type: 'register_script_failed',
+              projectRoot,
+            }));
+          }
+          const prompt = analyze.generateSummarySystemPrompt({
+            tasks,
+            remainingChapters,
+            projectRoot,
+            registerScript: registerTool,
+          });
 
           // 调用 LLM 进行总结
+          if (signal?.aborted) {
+            return notify(session, 'error', analyze.notify({ type: 'cancelled' }));
+          }
           const follow = await llmFollowup(invocation, prompt);
           // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
           // 否则投递失败也会报"技法总结完成"