@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-story-builder/wiki-references.js

@@ -1,68 +1,120 @@
 /**
  * wiki-references.js
- * 对标参考（对标/wiki/）的目录清单与注入文本
+ * 对标参考（对标/wiki/）的目录清单、阶段映射与注入文本。
  *
- * 抽出来单独成模块的理由：这段逻辑决定了"哪些对标文件真的可以读"，
- * 必须能被直接测。放在 index.js 里只能靠跑整个插件来覆盖，测不动。
+ * 这里有三件事必须分开：
+ *   1. **有哪些目录**：22 个可能目录（14 个按章技法 + 8 个跨章节实体；没有源页的目录不会有总结）。
+ *   2. **哪个阶段/批次该看哪些**：阶段级清单 + 批次级重点。
+ *   3. **怎么保证模型真的看到**：除了列路径，还要把摘要正文注入批次提示词。
+ *
+ * 为什么第 3 点单独做：只给路径时，模型可以声称"已参考"但完全不读；
+ * 插件把摘要直接放进 prompt 后，"跳过参考文件"这件事在物理上就不成立了。
  */
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 // 各目录的作用说明（注入提示词时用）
 export const DIRECTORY_DESCRIPTIONS = {
-  '叙事视角': '叙事视角：分析视角选择和切换策略',
-  '章节结构': '章节结构：分析章节的起承转合结构',
-  '节奏韵律': '节奏韵律：分析叙事节奏的张弛控制',
-  '对话技巧': '对话技巧：分析对话中的言外之意和潜台词',
-  '描写技法': '描写技法：分析环境、动作，心理描写的技巧',
-  '伏笔回收': '伏笔回收：分析伏笔的埋设和回收技巧',
-  '世界观构建': '世界观构建：分析世界观设定的呈现方式',
-  '角色弧光': '角色弧光：分析角色在不同章节的成长弧线变化',
-  '情节机制': '情节机制：分析情节推进的内在逻辑',
-  '开头钩子': '开头钩子：分析开篇吸引读者的技巧',
-  '结尾收束': '结尾收束：分析章节结尾的收束技法',
-  '句式变化': '句式变化：分析句子的长短和节奏变化',
-  '段落布局': '段落布局：分析段落的疏密和布局',
-  '场景转换': '场景转换：分析场景切换的技巧',
-  '情绪渲染': '情绪渲染：分析情感氛围的营造方式',
-  '张力构建': '张力构建：分析冲突和悬念的构建方式',
-  '来源摘要': '来源摘要：章节的完整分析和要点提炼'
+  '叙事视角': '叙事视角与信息差：谁在看、读者知道多少、视角如何限制或释放信息',
+  '章节结构': '单章起承转合：一章内部如何组织冲突、转折、收束',
+  '节奏韵律': '叙事节奏：张弛、信息密度、呼吸位、加压与泄压',
+  '对话技巧': '对话功能：推进剧情、塑造人物、传递设定、制造潜台词',
+  '描写技法': '描写：环境、动作、心理、感官细节如何服务人物与制度',
+  '情节机制': '情节推进机制：信息差、资源门槛、因果链、金手指边界',
+  '开头钩子': '开篇/章首钩子：如何在前几百字制造问题与期待',
+  '结尾收束': '章末/卷末收束：如何留悬念、转目标、兑现情绪',
+  '句式变化': '句式节奏：长短句、问句、短句冲击、解释句铺陈',
+  '段落布局': '段落功能与视觉节奏：分段、独段、留白、信息焦点',
+  '场景转换': '场景切换：时空标定、焦点交接、转场如何推进调查或关系',
+  '情绪渲染': '情绪曲线：群体/个体、希望/挫败、自嘲/爆发、共情',
+  '张力构建': '张力与压力：信息缺口、金额/时限、门槛叠加、赌注',
+  '章节功能设计': '章节功能：开局、揭示、推进、转折、收束、下一门槛',
+  '人物关系设计': '关系设计：试探、互助、家庭分工、师徒、竞争、信任边界',
+  '势力结构': '势力设计：资源/武力双轨、组织信用、区域议价、成员动员',
+  '世界观设计': '世界观设计：规则、力量体系、测量/资格、阶层与制度',
+  '冲突设计': '冲突设计：公开节点、赌注、制度门槛、资源困境、组织对抗',
+  '主线支线结构': '主线/支线：核心目标稳定、难度结构改写、支线服务主线',
+  '分卷节奏': '分卷/幕结构：卷目标、卷内起伏、卷末升级',
+  '伏笔布局': '伏笔：埋设、分层揭示、预约兑现、传闻层、问题清单',
+  '角色弧光设计': '角色弧光：目标—成本—修正、缺陷、动摇不改、配角功能'
 };
 
-// 各阶段对应的 wiki 目录
-//
-// 映射依据：**这一层产物要回答什么问题**，再挑对标技法里对得上的那些。
-// 判据是"样本里的那招能不能直接指导本层的一个字段"，不是"主题沾边"。
+// 各阶段对应的 wiki 目录（阶段级“本阶段可以看哪些”，不是“本批必须全读”）
 //
-//   骨架：有哪些实体、怎么连、有多少、分几卷几幕
-//     → 情节机制（主线支线怎么构成）/ 张力构建（冲突与门槛怎么叠）
-//     → 伏笔回收（伏笔清单怎么埋）/ 角色弧光（成长型支线的走向）
-//     → 结尾收束（结局怎么设计）/ 世界观构建（规则与势力怎么成体系）
-//   血肉：实体长什么样（角色卡、世界观、关系、情绪）
-//     → 世界观构建 / 描写技法 / 对话技巧 / 场景转换 / 情绪渲染
-//     → 角色弧光 / 伏笔回收 / 情节机制
-//   节奏：什么时间发生（升级、弧线、高潮钩子、爽点、伏笔密度、章节切分）
-//     → 节奏韵律 / 张力构建 / 章节结构 / 伏笔回收 / 情绪渲染
-//     → 开头钩子 / 结尾收束 / 情节机制 / 角色弧光
-//   写作：具体怎么写（场景、章节工作流、开篇、对话、句式、语气）
-//     → 开头钩子 / 结尾收束 / 对话技巧 / 描写技法 / 段落布局 / 句式变化
-//     → 叙事视角 / 场景转换 / 节奏韵律
+// 判据：**这一层产物要回答什么问题**，不是“主题沾边”。
+//   skeleton：有哪些实体、怎么连、有多少、分几卷几幕
+//   flesh：实体长什么样（角色/关系/势力/世界/情绪/道具）
+//   rhythm：什么时间发生（升级、弧线、高潮、钩子、伏笔密度、章节切分）
+//   writing：具体怎么写（场景、视角、对话、描写、句式、段落、开篇、收束）
 export const PHASE_DIRECTORIES = {
-  skeleton: ['世界观构建', '情节机制', '张力构建', '伏笔回收', '角色弧光', '结尾收束'],
-  flesh: ['世界观构建', '描写技法', '对话技巧', '场景转换', '情绪渲染', '角色弧光', '伏笔回收', '情节机制'],
-  rhythm: ['节奏韵律', '张力构建', '章节结构', '伏笔回收', '情绪渲染', '开头钩子', '结尾收束', '情节机制', '角色弧光'],
-  // 写作阶段以前没有对应键 → readWikiReferences 会退回 skeleton 那套，
-  // 结果是写章节时拿到的是骨架阶段的目录（角色弧光/伏笔回收…），
-  // 真正该读的对话、句式、段落反而一个都没有（2026-10-27 查到）。
-  writing: ['开头钩子', '结尾收束', '对话技巧', '描写技法', '段落布局', '句式变化', '叙事视角', '场景转换', '节奏韵律'],
-  // 去味阶段不注入对标参考：改写的是"像不像人话"，不是"写得好不好"，
+  skeleton: [
+    '主线支线结构', '冲突设计', '世界观设计', '势力结构',
+    '人物关系设计', '角色弧光设计', '伏笔布局', '情节机制',
+    '张力构建', '分卷节奏'
+  ],
+  flesh: [
+    '角色弧光设计', '人物关系设计', '势力结构', '世界观设计',
+    '冲突设计', '情绪渲染', '描写技法', '对话技巧',
+    '伏笔布局', '情节机制', '主线支线结构'
+  ],
+  rhythm: [
+    '节奏韵律', '章节结构', '章节功能设计', '开头钩子',
+    '结尾收束', '张力构建', '冲突设计', '伏笔布局',
+    '角色弧光设计', '主线支线结构', '分卷节奏', '情绪渲染',
+    '情节机制', '场景转换'
+  ],
+  writing: [
+    '叙事视角', '场景转换', '对话技巧', '描写技法',
+    '句式变化', '段落布局', '情绪渲染', '节奏韵律',
+    '开头钩子', '结尾收束', '张力构建', '伏笔布局',
+    '章节结构'
+  ],
+  // 去味阶段不注入对标参考：改写的是“像不像人话”，不是“写得好不好”，
   // 拿别人的写法当参照反而会把旧稿的毛病一起抄进去。
-  deslop: [],
-  analyze: ['角色弧光', '伏笔回收', '结尾收束', '张力构建', '情节机制', '开头钩子', '节奏韵律', '世界观构建', '章节结构', '情绪渲染', '对话技巧', '场景转换', '描写技法']
+  deslop: []
+};
+
+/**
+ * 批次级映射：同一阶段里，不同产物该看哪几篇。
+ *
+ * 阶段级清单解决“本阶段大概有哪些参考”，批次级映射解决“这一批到底该看哪几篇”。
+ * 两者都保留：阶段级用于建立全局地图，批次级用于把摘要压到单批可消化的量。
+ */
+export const BATCH_DIRECTORIES = {
+  skeleton: {
+    '框架': ['主线支线结构', '冲突设计', '世界观设计', '分卷节奏', '张力构建'],
+    '实体': ['角色弧光设计', '势力结构', '世界观设计', '人物关系设计', '冲突设计', '伏笔布局'],
+    '关系': ['人物关系设计', '势力结构', '冲突设计', '角色弧光设计'],
+    '层级': ['主线支线结构', '分卷节奏', '势力结构', '冲突设计']
+  },
+  flesh: {
+    '角色': ['角色弧光设计', '人物关系设计', '情绪渲染', '对话技巧'],
+    '冲突': ['冲突设计', '角色弧光设计', '张力构建'],
+    '势力': ['势力结构', '世界观设计', '人物关系设计'],
+    '剧情': ['主线支线结构', '情节机制', '伏笔布局', '人物关系设计'],
+    '地点': ['世界观设计', '描写技法', '场景转换'],
+    '结局': ['主线支线结构', '情绪渲染', '结尾收束'],
+    '世界观规则': ['世界观设计', '势力结构', '冲突设计'],
+    '关键道具': ['伏笔布局', '世界观设计', '描写技法']
+  },
+  rhythm: {
+    '章节规划': ['节奏韵律', '章节功能设计', '章节结构', '分卷节奏', '主线支线结构'],
+    '节奏参数': ['节奏韵律', '张力构建', '冲突设计', '情绪渲染'],
+    '时序映射': ['角色弧光设计', '主线支线结构', '伏笔布局', '分卷节奏'],
+    '章节细纲': ['开头钩子', '结尾收束', '章节结构', '章节功能设计', '张力构建', '伏笔布局']
+  },
+  writing: {
+    default: [
+      '叙事视角', '场景转换', '对话技巧', '描写技法',
+      '句式变化', '段落布局', '情绪渲染', '节奏韵律',
+      '开头钩子', '结尾收束', '张力构建', '伏笔布局',
+      '章节结构'
+    ]
+  }
 };
 
 /**
- * 各阶段的"插件指导目录"与本阶段重点。
+ * 各阶段的“插件指导目录”与本阶段重点。
  *
  * 用来在提示词里把两层参考分开讲清楚：
  *   references/<阶段>指导/  = 高维方法论（这一层该怎么设计）
@@ -88,18 +140,40 @@ export const PHASE_GUIDANCE = {
 };
 
 /**
- * 找出当前阶段真正可读的对标总结文件。
- *
- * 只认 `<目录名>-总结.md`；目录在但总结文件不在的，记为 missing。
+ * 各阶段「方法论 vs 对标样本」的大致创作权重。
  *
- * @returns {{ available: Array<{dir:string, path:string}>, missing: string[] }}
+ * 不是硬配额：契约/选题/上游永远 100% 服从；这里的百分比只用于回答
+ * “当两者都可用时，创作判断更该听谁”。
  */
-export function collectWikiReferences(projectRoot, phase = 'skeleton') {
+export const STAGE_REFERENCE_WEIGHTS = {
+  skeleton: { method: '60%', benchmark: '40%', note: '结构、实体、关系模式可借样本校准；配额、图结构、字段以方法论和校验器为准' },
+  flesh: { method: '55%', benchmark: '45%', note: '人物、关系、世界质感可多借样本；字段与引用完整性以契约为准' },
+  rhythm: { method: '50%', benchmark: '50%', note: '节奏最依赖市场手感；公式与联合约束仍是硬门槛' },
+  writing: { method: '65%', benchmark: '35%', note: 'craft 下限优先；样本只校准题材语气与桥段，防止照抄' }
+};
+
+/** 已登记的总结目录集合（测试用来防止映射里写出不存在的目录）。 */
+export const KNOWN_SUMMARY_DIRS = Object.keys(DIRECTORY_DESCRIPTIONS);
+
+/** 取出某阶段的目录清单（保留映射顺序）。 */
+function phaseDirs(phase) {
+  return PHASE_DIRECTORIES[phase] || PHASE_DIRECTORIES.skeleton;
+}
+
+/** 取出某阶段某批次的重点目录；没有批次映射时退回阶段清单。 */
+function batchDirs(phase, batchType) {
+  const map = BATCH_DIRECTORIES[phase];
+  if (map && batchType && map[batchType]) return map[batchType];
+  if (map && map.default) return map.default;
+  return phaseDirs(phase);
+}
+
+/** 按给定目录顺序检查总结文件是否存在。 */
+function collectDirs(projectRoot, dirs) {
   const wikiDir = join(projectRoot, '对标', 'wiki');
-  const phaseDirs = PHASE_DIRECTORIES[phase] || PHASE_DIRECTORIES.skeleton;
   const available = [];
   const missing = [];
-  for (const dir of Array.from(phaseDirs).sort()) {
+  for (const dir of dirs) {
     const summaryFile = join(wikiDir, dir, dir + '-总结.md');
     if (existsSync(summaryFile)) {
       available.push({ dir, path: '对标/wiki/' + dir + '/' + dir + '-总结.md' });
@@ -111,9 +185,35 @@ export function collectWikiReferences(projectRoot, phase = 'skeleton') {
 }
 
 /**
- * 生成注入提示词的对标参考文本。
+ * 找出当前阶段真正可读的对标总结文件。
+ *
+ * 只认 `<目录名>-总结.md`；目录在但总结文件不在的，记为 missing。
+ * 返回顺序按 PHASE_DIRECTORIES 的映射顺序（方便摘要按优先级取前几篇）。
+ *
+ * @returns {{ available: Array<{dir:string, path:string}>, missing: string[] }}
+ */
+export function collectWikiReferences(projectRoot, phase = 'skeleton') {
+  return collectDirs(projectRoot, phaseDirs(phase));
+}
+
+/**
+ * 找出当前阶段、当前批次真正可读的对标总结文件。
+ *
+ * 批次映射优先；没有映射时退回阶段清单。
+ *
+ * @param {string} projectRoot
+ * @param {string} phase
+ * @param {string} [batchType] 例如“框架/实体/关系/层级”“角色/冲突/…”“章节规划/… ”
+ * @returns {{ available: Array<{dir:string, path:string}>, missing: string[] }}
+ */
+export function collectBatchWikiReferences(projectRoot, phase = 'skeleton', batchType = '') {
+  return collectDirs(projectRoot, batchDirs(phase, batchType));
+}
+
+/**
+ * 生成注入提示词的对标参考文本（只列路径，不展开正文）。
  *
- * 只注入**实际存在**的文件；缺失的目录明确告知"没有"，避免 LLM 去读不存在的
+ * 只注入**实际存在**的文件；缺失的目录明确告知“没有”，避免 LLM 去读不存在的
  * 路径后自行编造内容。
  */
 export function readWikiReferences(projectRoot, phase = 'skeleton') {
@@ -136,69 +236,305 @@ export function readWikiReferences(projectRoot, phase = 'skeleton') {
 }
 
 /**
- * 生成"参考分层"说明段，注入到各阶段提示词的参考小节。
+ * 生成“参考优先级”说明段，注入到各阶段提示词的参考小节。
  *
- * ## 为什么要单独生成这一段
+ * 这一段的职责不是“多列几个文件”，而是把四种参考的**优先级和边界**讲死：
  *
- * 插件自带的 `references/<阶段>指导/` 和项目里的 `对标/wiki/` 是**两种性质
- * 完全不同**的参考，模型很容易混着用：
+ *   1. 硬契约（模板/glossary/公式/校验器/上游 JSON）—— 100% 服从
+ *   2. 本项目选题与上游产物 —— 创作主权；对标不能改设定
+ *   3. references/<阶段>指导/ —— 方法论，决定下限
+ *   4. 对标/wiki/ 总结 —— 市场样本，校准上限
  *
- *   - `references/<阶段>指导/` = **高维方法论**：这一层该怎么设计的通则
- *     （数量怎么定、实体卡写什么、节奏怎么排）。是"怎么想"。
- *   - `对标/wiki/<技法>/<技法>-总结.md` = **市场验证过的落地样本**：
- *     从真实商业小说里提炼的"某招在成品里怎么生效"。是"怎么落地"。
- *
- * 混用的后果不是文风问题，是**设定污染**：拿别人的成品当规则 → 照抄专名、
- * 情节、句子、金手指 → 撞设定、涉嫌抄袭。所以这一段必须把两层的边界、
- * 优先级和红线一次讲清楚，并给出"本阶段该读哪几个"的明确清单。
- *
- * ## 为什么还必须注入到批次提示词
- *
- * 以前这份对标参考只挂在**系统提示词**上，而系统提示词那几个生成函数
- * （generateSkeletonSystemPrompt 等）**从来没有被调用** ——
- * 真正派给模型的是每批的批次提示词。结果就是：对标参考一次都没到过模型手里
- * （tt5 实测：39 条骨架批次指令里 0 条含"对标"，整个会话 0 次"对标参考"）。
+ * 为什么不能 50/50：方法论和样本回答的是不同问题。
+ * 方法论回答“这一层必须有什么、字段怎么成立”；样本回答“这一招在成品里怎么落地”。
+ * 把两者等权，模型就会拿样本里的桥段去覆盖模板/选题，最后写出一本“像对标但不像本项目”的书。
  *
  * @param {string} projectRoot 项目根目录
  * @param {string} phase 阶段（skeleton / flesh / rhythm / writing）
+ * @param {string} [batchType] 批次类型（可选；给了就额外列“本批优先”）
  * @returns {string} 注入文本（没有对标目录时返回空串）
  */
-export function renderBenchmarkGuidance(projectRoot, phase = 'skeleton') {
+export function renderBenchmarkGuidance(projectRoot, phase = 'skeleton', batchType = '') {
   const guide = PHASE_GUIDANCE[phase];
   if (!guide) return '';
   const wikiDir = join(projectRoot, '对标', 'wiki');
   if (!existsSync(wikiDir)) return '';
 
-  const { available, missing } = collectWikiReferences(projectRoot, phase);
+  const phaseRefs = collectWikiReferences(projectRoot, phase);
+  const batchRefs = batchType ? collectBatchWikiReferences(projectRoot, phase, batchType) : null;
+  const weights = STAGE_REFERENCE_WEIGHTS[phase] || STAGE_REFERENCE_WEIGHTS.skeleton;
 
   const lines = [];
-  lines.push('### 参考分三层，各读各的，别混\n');
-  lines.push('| 层 | 位置 | 是什么 | 怎么用 |');
+  lines.push('### 参考优先级（不是 50/50）');
+  lines.push('');
+  lines.push('| 优先级 | 参考 | 作用 | 冲突时怎么判 |');
   lines.push('|---|---|---|---|');
-  lines.push('| 硬契约 | `模板/`、`references/glossary.md` | 字段、枚举、id 规则 —— 校验器就按它判 | **必读**，动笔前先对齐 |');
-  lines.push('| 高维方法论 | `' + guide.guideDir + '/` | ' + guide.focus + '的通则 | **必读**，按本批文件选篇 |');
-  lines.push('| 市场验证样本 | `对标/wiki/` 下的 `<技法名>-总结.md` | 真实商业小说里某一招怎么生效 | **选读**，用来校准手法 |');
+  lines.push('| 1 | `模板/`、`references/glossary.md`、`formulas-*.json`、校验器 | 字段、枚举、公式、结构 | **100% 服从**，不能拿样本改契约 |');
+  lines.push('| 2 | 本项目选题、`input_snapshot`、上游 JSON | 这本书的创作主权 | 对标不能改设定；硬门禁不能破 |');
+  lines.push('| 3 | `' + guide.guideDir + '/` | ' + guide.focus + '的通则 | **主参考**：决定下限与字段质量 |');
+  lines.push('| 4 | `对标/wiki/` 的 `<技法>-总结.md` | 真实商业小说里某一招怎么落地 | **校准参考**：只在可行域内选点 |');
+  lines.push('');
+  lines.push('**本阶段的创作权重**：方法论约 **' + weights.method + '**，对标样本约 **' + weights.benchmark + '**。' + weights.note + '。');
+  lines.push('');
+  lines.push('**匹配度折扣**：对标样本还要看它和本项目的距离——同题材 + 同平台 + 同读者层按上表；同题材不同平台约 ×0.7；不同题材约 ×0.3（只借通用结构，不硬套桥段）。');
   lines.push('');
-  lines.push('**读法**：先读 `' + guide.guideDir + '/`（决定"该怎么想"），再按需翻对标样本（校准"怎么落地"）。');
+  lines.push('**读法**：先读 `' + guide.guideDir + '/`（决定“该怎么想”）；本批对标摘要只用于定位，**决策前必须核对原文件里的对应条目**，摘要不能替代原文。');
   lines.push('');
-  lines.push('**红线**：对标样本是**别人的成品**，只学结构与手法 —— '
-    + '禁止照搬专名、情节、句子、金手指设定；'
-    + '样本里的角色名/地名/机构名一律不许进本项目。');
+  lines.push('**本批强制**：摘要正文会直接注入，但摘要只负责定位；写作时必须先在原文件中核对 **1–2 条与本批字段/场景直接相关**的原则，落到具体设计上，并把参考文件和条目写进 `设定/.reference-decisions.md`。不要只收藏路径，也不要声称“已读取”却没有体现。确实没有适用条目时按契约写，不要硬套。');
+  lines.push('');
+  lines.push('**红线**：对标样本是**别人的成品**，只学结构与手法——禁止照搬专名、情节、句子、金手指设定；样本里的角色名/地名/机构名一律不许进本项目。');
   lines.push('');
 
-  if (available.length) {
-    lines.push('**本阶段可读的对标文件**（读哪些由你判断，读后不重读）：\n');
-    for (const a of available) {
+  if (phaseRefs.available.length) {
+    lines.push('**本阶段可读的对标文件**（阶段级地图，不等于每批都要全读）：\n');
+    for (const a of phaseRefs.available) {
       const desc = DIRECTORY_DESCRIPTIONS[a.dir] || '写作技法分析';
       lines.push('- `' + a.path + '` —— ' + desc);
     }
     lines.push('');
   } else {
-    lines.push('**本阶段没有可读的对标文件**（对标/wiki 下还没有总结文件）：不要凭空编造"对标分析"，照插件指导写。\n');
+    lines.push('**本阶段没有可读的对标文件**（对标/wiki 下尚无总结文件）：不要凭空编造“对标分析”，照插件指导写。\n');
   }
+
+  if (batchRefs) {
+    if (batchRefs.available.length) {
+      lines.push('**本批优先参考**（插件已按本批产物筛过；摘要正文会注入其中最相关的前几篇）：\n');
+      for (const a of batchRefs.available) {
+        const desc = DIRECTORY_DESCRIPTIONS[a.dir] || '写作技法分析';
+        lines.push('- `' + a.path + '` —— ' + desc);
+      }
+      lines.push('');
+    } else {
+      lines.push('**本批没有匹配到可读的对标文件**：按方法论与硬契约写，不要临时扩大到无关题材的样本。\n');
+    }
+  }
+
+  const missing = Array.from(new Set([...(phaseRefs.missing || []), ...((batchRefs && batchRefs.missing) || [])]));
   if (missing.length) {
-    lines.push('**以下对标目录本阶段没有总结文件，不要引用**：' + missing.join('、'));
+    lines.push('**以下对标目录本阶段/本批没有总结文件，不要引用**：' + missing.join('、'));
     lines.push('');
   }
   return lines.join('\n');
 }
+
+/** 摘要注入的体量上限（按阶段）。 */
+const DIGEST_LIMITS = {
+  skeleton: { maxFiles: 6, maxEntriesPerFile: 5, maxDetailFiles: 2, maxDetailEntries: 2, maxChars: 8000 },
+  flesh: { maxFiles: 4, maxEntriesPerFile: 8, maxDetailFiles: 2, maxDetailEntries: 2, maxChars: 7000 },
+  rhythm: { maxFiles: 6, maxEntriesPerFile: 6, maxDetailFiles: 2, maxDetailEntries: 2, maxChars: 8000 },
+  writing: { maxFiles: 10, maxEntriesPerFile: 6, maxDetailFiles: 2, maxDetailEntries: 1, maxChars: 9000 }
+};
+
+/** 截断文本，保留前 n 个字符。 */
+function truncate(text, n) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  if (s.length <= n) return s;
+  return s.slice(0, n).replace(/[，。；、,.;:\s]+$/, '') + '…';
+}
+
+/**
+ * 解析一个总结文件里的条目。
+ *
+ * 只解析 `## 核心技法` / `## 核心设计原则` 下的 `###` 条目；
+ * `- 来源章节：` / `- 来源实体：` 是登记字段，不进入摘要正文。
+ *
+ * @param {string} text
+ * @returns {Array<{title:string, fields:Object<string,string>}>}
+ */
+export function parseSummaryEntries(text) {
+  const source = String(text || '');
+  const sectionRe = /^##\s+(核心技法|核心设计原则)\s*$/m;
+  const m = sectionRe.exec(source);
+  if (!m) return [];
+
+  const rest = source.slice(m.index + m[0].length);
+  const nextH2 = /^##\s+/m.exec(rest);
+  const body = nextH2 ? rest.slice(0, nextH2.index) : rest;
+  const chunks = body.split(/^###\s+/m).slice(1);
+  const entries = [];
+
+  for (const chunk of chunks) {
+    const lines = chunk.split('\n');
+    const title = String(lines[0] || '').trim();
+    if (!title) continue;
+    const fields = {};
+    for (const line of lines.slice(1)) {
+      const fm = /^-\s*([^：]+)：\s*(.*)$/.exec(line.trim());
+      if (!fm) continue;
+      const key = fm[1].trim();
+      if (key.startsWith('来源')) continue; // 登记字段不进摘要
+      fields[key] = fm[2].trim();
+    }
+    entries.push({ title, fields });
+  }
+  return entries;
+}
+
+/** 判断这个总结文件是实体页总结还是按章技法总结。 */
+function isEntityEntries(entries) {
+  return entries.some((e) => Object.prototype.hasOwnProperty.call(e.fields, '为什么这么设计'));
+}
+
+/** 条目的一句话索引（优先取“为什么/核心要点”）。 */
+function entryOneLine(entry, entity) {
+  const keys = entity
+    ? ['为什么这么设计', '设计好处', '迁移到骨架/血肉/节奏']
+    : ['核心要点', '应用方式', '使用场景'];
+  for (const key of keys) {
+    if (entry.fields[key]) return truncate(entry.fields[key], 100);
+  }
+  return '';
+}
+
+/** 从批次里提取用于匹配条目的关键词。 */
+function batchTokens(batch) {
+  const tokens = [];
+  const add = (v) => {
+    const s = String(v || '').trim();
+    if (s && s.length >= 2 && !tokens.includes(s)) tokens.push(s);
+  };
+  if (batch) {
+    add(batch.type);
+    add(batch.groupKey);
+    for (const item of (batch.items || [])) {
+      add(item.name);
+      add(item.type);
+      add(item.category);
+      add(item.level);
+      add(item.scale);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * 选本批最该展开的条目。
+ *
+ * 没有语义模型可用，所以用“批次类型 / 条目名 / 类型词”做轻量匹配；
+ * 匹配不到时按原顺序取前几条（摘要本身已经按条目顺序组织）。
+ */
+function selectDetailEntries(entries, entity, batch, limit) {
+  const tokens = batchTokens(batch);
+  const scored = entries.map((entry, index) => {
+    const hay = entry.title + ' ' + Object.values(entry.fields).join(' ');
+    let score = 0;
+    for (const t of tokens) {
+      if (entry.title.includes(t)) score += 5;
+      else if (hay.includes(t)) score += 2;
+    }
+    return { entry, index, score };
+  });
+  scored.sort((a, b) => (b.score - a.score) || (a.index - b.index));
+  return scored.slice(0, Math.max(1, limit)).map((x) => x.entry);
+}
+
+/** 把一个条目展开成摘要正文。 */
+function renderEntryDetail(entry, entity) {
+  const lines = ['#### ' + entry.title];
+  const keys = entity
+    ? ['为什么这么设计', '设计好处', '如何服务剧情/人物/主题', '风险与反例', '迁移到骨架/血肉/节奏']
+    : ['核心要点', '使用场景', '应用方式'];
+  for (const key of keys) {
+    if (entry.fields[key]) lines.push('- ' + key + '：' + entry.fields[key]);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 生成“本批对标参考摘要”，直接注入批次提示词。
+ *
+ * 这是“防止模型跳过参考文件”的核心手段：
+ *   - 只给路径：模型可以声称读过但完全不看；
+ *   - 注入摘要：本批相关原则已经在上下文里，模型不需要（也不能假装）去读；
+ *   - 保留原文件路径：需要更细的条目时仍可回读，但本批不依赖它。
+ *
+ * @param {string} projectRoot
+ * @param {string} phase
+ * @param {Object} [batch] 批次对象（至少含 type；可选 items/groupKey）
+ * @param {Object} [opts] 覆盖默认上限：maxFiles/maxEntriesPerFile/maxDetailFiles/maxDetailEntries/maxChars
+ * @returns {string}
+ */
+export function renderBenchmarkDigest(projectRoot, phase = 'skeleton', batch = null, opts = {}) {
+  const wikiDir = join(projectRoot, '对标', 'wiki');
+  if (!existsSync(wikiDir)) return '';
+
+  const dirs = batchDirs(phase, batch && batch.type);
+  const { available } = collectDirs(projectRoot, dirs);
+  const limits = Object.assign({}, DIGEST_LIMITS[phase] || DIGEST_LIMITS.skeleton, opts || {});
+
+  if (available.length === 0) {
+    return [
+      '## 本批对标参考（已注入摘要；决策前仍需核对原文件）',
+      '',
+      '（本批没有可用的对标总结文件。按 `' + ((PHASE_GUIDANCE[phase] || {}).guideDir || 'references/') + '/` 与硬契约写，不要编造“对标分析”。）'
+    ].join('\n');
+  }
+
+  const selected = available.slice(0, Math.max(1, limits.maxFiles));
+  const indexBlocks = [];
+  const detailBlocks = [];
+
+  selected.forEach((entry, fileIndex) => {
+    let text = '';
+    try {
+      text = readFileSync(join(projectRoot, entry.path), 'utf-8');
+    } catch {
+      return;
+    }
+    const entries = parseSummaryEntries(text);
+    if (entries.length === 0) return;
+    const entity = isEntityEntries(entries);
+    const visible = entries.slice(0, Math.max(1, limits.maxEntriesPerFile));
+
+    const indexLines = [];
+    indexLines.push('### `' + entry.path + '`');
+    indexLines.push('');
+    indexLines.push('**原则索引**');
+    for (const e of visible) {
+      const one = entryOneLine(e, entity);
+      indexLines.push('- ' + e.title + (one ? '：' + one : ''));
+    }
+    if (entries.length > visible.length) {
+      indexLines.push('- ……还有 ' + (entries.length - visible.length) + ' 条（需要时读原文件）');
+    }
+    indexLines.push('');
+    indexBlocks.push(indexLines.join('\n'));
+
+    if (fileIndex < limits.maxDetailFiles) {
+      const details = selectDetailEntries(entries, entity, batch, limits.maxDetailEntries);
+      if (details.length) {
+        const dLines = ['**本批重点**', ''];
+        for (const d of details) dLines.push(renderEntryDetail(d, entity), '');
+        detailBlocks.push('### `' + entry.path + '` 的重点条目\n\n' + dLines.join('\n'));
+      }
+    }
+  });
+
+  const header = [
+    '## 本批对标参考（已注入摘要；决策前仍需核对原文件）',
+    '',
+    '> 下面是插件按本批任务从 `对标/wiki/` 筛出的原则索引和重点条目。它们是**校准样本**，不是硬规则：',
+    '> 与模板、选题、上游产物冲突时，以硬契约和本项目设定为准；禁止照搬专名、情节、句子。',
+    '> 这些摘要不是可选背景：本批至少选 1 条与本批字段/场景直接相关的原则，落到具体设计上；没有适用条目就按契约写，不要硬套。',
+    '> 摘要只覆盖本批重点，不能替代原文；做本批决策前必须核对原文件里的对应条目，并把参考文件和条目写进 `设定/.reference-decisions.md`。',
+    ''
+  ].join('\n');
+
+  if (indexBlocks.length === 0) {
+    return header + '（选中的总结文件里没有可解析的条目；按硬契约写，不要编造“对标分析”。）';
+  }
+
+  let out = header;
+  for (const block of indexBlocks) {
+    if (out.length + block.length > limits.maxChars) break;
+    out += block + '\n';
+  }
+  for (const block of detailBlocks) {
+    if (out.length + block.length > limits.maxChars) break;
+    out += block + '\n';
+  }
+  if (out.length > limits.maxChars) {
+    out = out.slice(0, limits.maxChars).replace(/[，。；、,.;:\s]+$/, '') + '\n\n（摘要已按上下文预算截断，需要完整条目时读原文件。）';
+  }
+  return out.trim();
+}