@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/scripts/reading-power.js

@@ -0,0 +1,298 @@
+/**
+ * reading-power.js —— 阅读动力的规则真源
+ *
+ * 这些规则原先散在旧版 skill 的两份 markdown 里（旧 fancy-write/references/
+ * hooks.md 与 reading-power.md），是纯给人读的规范，没法程序判定：
+ *   · hooks.md        —— 13 式章末钩子 + 7 式章首引子 + "严禁连续 3 章用同一种"
+ *   · reading-power.md —— 5 大钩子分类 / 5 级强度 / 8 大爽点 / 7 种微兑现 / 30-40-30
+ *
+ * 现在落成**可判定的词表**：写作阶段每章把用了哪种钩子、含哪些微兑现写进章台账，
+ * writing-validate.js 拿这些词表逐条对账（见 validateChapter）。
+ *
+ * 设计要点：
+ *   1. 词表是**唯一真源**。旧 skill 里有三份互相漂移的副本（deslop 的 24 类、
+ *      review 声称的"19 类"、代码里的 21 类），这里不再重复造第四份。
+ *   2. 每条都带 id。台账里记的是 id（不是中文名），改名不会让历史台账失效。
+ *   3. 判定与文案分离：这里只回答"哪些合法 / 哪些违规"，
+ *      "应该写成什么样"是提示词和写作指导的事。
+ */
+
+/**
+ * 13 式章末钩子。
+ * 每章末必用其中一种 —— 这是"读者为什么要翻下一章"的答案。
+ */
+export const TAIL_HOOK_TYPES = [
+  { id: 'sudden_reveal', name: '突然揭示', category: '悬念钩', desc: '一句话把读者以为知道的事掀翻' },
+  { id: 'urgent_crisis', name: '紧急危机', category: '危机钩', desc: '危险正在逼近，角色必须立刻行动' },
+  { id: 'unfinished_action', name: '未完成的动作', category: '选择钩', desc: '动作停在最要紧的一步' },
+  { id: 'identity_flip', name: '身份反转', category: '悬念钩', desc: '身份/立场的反转' },
+  { id: 'dilemma', name: '两难选择', category: '选择钩', desc: '二选一，且两边都有代价' },
+  { id: 'mystery_item', name: '神秘物品', category: '悬念钩', desc: '出现一个来历不明的物或线索' },
+  { id: 'time_limit', name: '时间限制', category: '危机钩', desc: '倒计时开始了' },
+  { id: 'promise_threat', name: '承诺威胁', category: '情绪钩', desc: '有人在预告/威胁后果' },
+  { id: 'odd_disappearance', name: '离奇消失', category: '悬念钩', desc: '人或物凭空不见' },
+  { id: 'implication', name: '言外之意', category: '情绪钩', desc: '话没说破，但读者听懂了' },
+  { id: 'imagery', name: '意象钩子', category: '悬念钩', desc: '用反复出现的意象收尾' },
+  { id: 'echo', name: '回声钩子', category: '情绪钩', desc: '结尾与开篇形成回响' },
+  { id: 'blank', name: '留白钩子', category: '悬念钩', desc: '停在关键信息之前，让读者自己脑补' }
+];
+
+/**
+ * 7 式章首引子。
+ * 每章首必用其中一种 —— 决定读者第一段会不会滑走。
+ */
+export const HEAD_HOOK_TYPES = [
+  { id: 'dialogue_suspense', name: '悬念对话引子', desc: '用一句对话把悬念抛出来' },
+  { id: 'inner_monologue', name: '内心独白引子', desc: '从角色的内心切进去' },
+  { id: 'contrast_scene', name: '反差场景引子', desc: '两个画面并置，反差制造张力' },
+  { id: 'unfinished_move', name: '未完成动作引子', desc: '动作停在半途' },
+  { id: 'imagery_foreshadow', name: '意象伏笔引子', desc: '用意象埋伏笔' },
+  { id: 'time_shift', name: '时间错位引子', desc: '时间跳跃制造疑问' },
+  { id: 'object_detail', name: '物件细节引子', desc: '从一个物件切进去' }
+];
+
+/**
+ * 5 大钩子分类 —— 用来判断一章的钩子"有没有变化"。
+ * 同一分类连续用 3 章 = 钩子开始重复（比同一种更隐蔽，所以两层都要查）。
+ */
+export const HOOK_CATEGORIES = ['危机钩', '悬念钩', '渴望钩', '情绪钩', '选择钩'];
+
+/**
+ * 钩子强度 5 级。中间章用 1-2 级，高潮章用 3-5 级。
+ * 强度不是越高越好 —— 全书都是 5 级反而平。
+ */
+export const HOOK_STRENGTHS = [
+  { id: 'curiosity', name: '好奇悬念', level: 1, usage: '中间章节' },
+  { id: 'concern', name: '关切悬念', level: 2, usage: '中间章节' },
+  { id: 'urgent', name: '迫切悬念', level: 3, usage: '高潮章节' },
+  { id: 'survival', name: '生存悬念', level: 4, usage: '高潮/结局前' },
+  { id: 'ultimate', name: '终极悬念', level: 5, usage: '全书结尾' }
+];
+
+/**
+ * 8 大爽点模式。识别靠标识与结构，不靠词表 ——
+ * 这一项只能由模型判（LLM 报 finding），脚本只校验报上来的类型合法。
+ */
+export const PAYOFF_PATTERNS = [
+  { id: 'flex_counter', name: '装逼打脸', en: 'Flex & Counter', arc: '嘲讽→反转→震惊' },
+  { id: 'underdog_reveal', name: '扮猪吃虎', en: 'Underdog Reveal', arc: '示弱→暴露→碾压' },
+  { id: 'underdog_victory', name: '越级反杀', en: 'Underdog Victory', arc: '差距→策略→逆转' },
+  { id: 'authority_challenge', name: '打脸权威', en: 'Authority Challenge', arc: '权威→挑战→成功' },
+  { id: 'villain_downfall', name: '反派翻车', en: 'Villain Downfall', arc: '得意→反杀→落幕' },
+  { id: 'sweet_surprise', name: '甜蜜超预期', en: 'Sweet Surprise', arc: '期待→超预期→升华' },
+  { id: 'misunderstanding', name: '迪化误解', en: 'Misunderstanding Elevation', arc: '随意行为→配角脑补升华' },
+  { id: 'identity_reveal', name: '身份掉马', en: 'Identity Reveal', arc: '身份伪装→关键时刻→揭露' }
+];
+
+/**
+ * 7 种微兑现 —— 每章至少含 1 个。
+ * "微兑现"是让读者觉得这一章没白读的东西：哪怕很小，也得给一个。
+ */
+export const MICRO_PAYOFFS = [
+  { id: 'info', name: '信息兑现', desc: '揭示了新信息或线索' },
+  { id: 'relation', name: '关系兑现', desc: '关系推进或确认' },
+  { id: 'ability', name: '能力兑现', desc: '能力提升或掌握新技能' },
+  { id: 'resource', name: '资源兑现', desc: '获得物品或资源' },
+  { id: 'recognition', name: '认可兑现', desc: '获得认可或面子' },
+  { id: 'emotion', name: '情绪兑现', desc: '情绪释放或共鸣' },
+  { id: 'clue', name: '线索兑现', desc: '伏笔回收或推进' }
+];
+
+/**
+ * 30/40/30 结构 —— 一章内部的节奏配比。
+ * 这里的比例是"参考值"，不作为硬判定（章节长度差异太大），但要在写作指导里讲清楚。
+ */
+export const STRUCTURE_3030 = [
+  { id: 'setup', name: '铺垫', ratio: 0.3, role: '建立信息差、压力、期待' },
+  { id: 'delivery', name: '兑现', ratio: 0.4, role: '核心爽点执行' },
+  { id: 'aftermath', name: '余波', ratio: 0.3, role: '反应、收获、新期待' }
+];
+
+/** 题材偏好的微兑现类型与每章数量（参考值，不作硬判定） */
+export const GENRE_PAYOFF_PREFERENCE = {
+  爽文: { types: ['ability', 'resource', 'recognition'], perChapter: '2-3' },
+  言情: { types: ['relation', 'emotion', 'recognition'], perChapter: '1-2' },
+  悬疑: { types: ['info', 'clue'], perChapter: '1-2' }
+};
+
+// ---------------------------------------------------------------------------
+// 判定辅助
+// ---------------------------------------------------------------------------
+
+const TAIL_BY_ID = new Map(TAIL_HOOK_TYPES.map((x) => [x.id, x]));
+const TAIL_BY_NAME = new Map(TAIL_HOOK_TYPES.map((x) => [x.name, x]));
+const HEAD_BY_ID = new Map(HEAD_HOOK_TYPES.map((x) => [x.id, x]));
+const HEAD_BY_NAME = new Map(HEAD_HOOK_TYPES.map((x) => [x.name, x]));
+const MICRO_BY_ID = new Map(MICRO_PAYOFFS.map((x) => [x.id, x]));
+const MICRO_BY_NAME = new Map(MICRO_PAYOFFS.map((x) => [x.name, x]));
+
+/**
+ * 查一个章末钩子（台账里可能写 id，也可能写中文名）。
+ * @returns {{id,name,category}|null}
+ */
+export function resolveTailHook(value) {
+  if (typeof value !== 'string' || !value) return null;
+  const s = value.trim();
+  return TAIL_BY_ID.get(s) || TAIL_BY_NAME.get(s) || null;
+}
+
+/**
+ * 查一个章首引子。
+ * @returns {{id,name,desc}|null}
+ */
+export function resolveHeadHook(value) {
+  if (typeof value !== 'string' || !value) return null;
+  const s = value.trim();
+  return HEAD_BY_ID.get(s) || HEAD_BY_NAME.get(s) || null;
+}
+
+/**
+ * 查一个微兑现类型。
+ * @returns {{id,name,desc}|null}
+ */
+export function resolveMicroPayoff(value) {
+  if (typeof value !== 'string' || !value) return null;
+  const s = value.trim();
+  return MICRO_BY_ID.get(s) || MICRO_BY_NAME.get(s) || null;
+}
+
+/** 全部合法的章末钩子 id（给提示词/文档用） */
+export function tailHookIds() {
+  return TAIL_HOOK_TYPES.map((x) => x.id);
+}
+
+/** 全部合法的章首引子 id */
+export function headHookIds() {
+  return HEAD_HOOK_TYPES.map((x) => x.id);
+}
+
+/** 全部合法的微兑现 id */
+export function microPayoffIds() {
+  return MICRO_PAYOFFS.map((x) => x.id);
+}
+
+/**
+ * 查连续重复的钩子。
+ *
+ * 规则（旧 fancy-write/references/hooks.md:77）：
+ *   "严禁连续 3 章用同一种" —— 同一 tail_hook 连续出现 3 章就报。
+ * 同理，"同一大分类连续 3 章"也算重复 —— 因为 13 式里有好几式同属悬念钩，
+ * 换了个名字但读者感受没变。
+ *
+ * @param {Array<{ch:number, hook_tail_type?:string}>} entries 章台账条目（按 ch 升序）
+ * @returns {{sameType:Array, sameCategory:Array}}
+ *   sameType     —— 连续 3 章用同一 tail_hook 的段落
+ *   sameCategory —— 连续 3 章用同一大分类的段落
+ */
+export function findHookRepeats(entries) {  const list = (entries || [])
+    .filter((e) => e && e.ch !== undefined && e.ch !== null)
+    .slice()
+    .sort((a, b) => a.ch - b.ch);
+
+  const sameType = [];
+  const sameCategory = [];
+
+  let typeRun = [];
+  let catRun = [];
+
+  const flush = (run, out, keyOf, label) => {
+    if (run.length >= 3) {
+      out.push({
+        key: keyOf(run[0]),
+        label: label,
+        chapters: run.map((e) => e.ch),
+        value: keyOf(run[0])
+      });
+    }
+  };
+
+  for (let i = 0; i < list.length; i++) {
+    const cur = list[i];
+    const hook = resolveTailHook(cur.hook_tail_type);
+
+    // 同一种
+    if (hook) {
+      if (typeRun.length && typeRun[0]._hook.id !== hook.id) {
+        flush(typeRun, sameType, (e) => e._hook.id, 'hook_tail_type');
+        typeRun = [];
+      }
+      typeRun.push(Object.assign({}, cur, { _hook: hook }));
+    } else {
+      flush(typeRun, sameType, (e) => e._hook.id, 'hook_tail_type');
+      typeRun = [];
+    }
+
+    // 同一大分类
+    const cat = hook ? hook.category : null;
+    if (cat) {
+      if (catRun.length && catRun[0]._cat !== cat) {
+        flush(catRun, sameCategory, (e) => e._cat, 'hook_tail_category');
+        catRun = [];
+      }
+      catRun.push(Object.assign({}, cur, { _cat: cat }));
+    } else {
+      flush(catRun, sameCategory, (e) => e._cat, 'hook_tail_category');
+      catRun = [];
+    }
+  }
+  flush(typeRun, sameType, (e) => e._hook.id, 'hook_tail_type');
+  flush(catRun, sameCategory, (e) => e._cat, 'hook_tail_category');
+
+  return { sameType, sameCategory };
+}
+
+// ---------------------------------------------------------------------------
+// 清单生成（唯一真源 → 提示词/文档）
+// ---------------------------------------------------------------------------
+
+/**
+ * 生成"合法取值清单"，给写作提示词动态注入。
+ *
+ * 为什么要动态生成而不是把清单写死在 markdown 里：
+ *   手写两份必然漂移 —— 旧 skill 正是这么坏的：
+ *   deslop 的"24 类"、review 声称的"19 类"（实际 20 条）、
+ *   代码里实现的 21 类，三份互不一致，模型根本不知道以哪套为准。
+ *
+ *   这里清单只有一份（本文档），提示词、校验器、写作指导都从它派生。
+ *
+ * @returns {string} 可直接拼进提示词的 markdown 段
+ */
+export function readingPowerLegend() {
+  const lines = [];
+  lines.push('---');
+  lines.push('');
+  lines.push('## 附：合法取值清单（由校验器判定，填错会被拦下）');
+  lines.push('');
+  lines.push('章台账里这三个字段只能填下面清单里的值（中文名或 id 都行）：');
+  lines.push('');
+
+  lines.push('### `hook_head_type` —— 章首引子 7 式');
+  lines.push('');
+  lines.push('| id | 名称 |');
+  lines.push('|---|---|');
+  for (const h of HEAD_HOOK_TYPES) lines.push('| ' + h.id + ' | ' + h.name + ' |');
+  lines.push('');
+
+  lines.push('### `hook_tail_type` —— 章末钩子 13 式');
+  lines.push('');
+  lines.push('| id | 名称 | 大分类 |');
+  lines.push('|---|---|---|');
+  for (const h of TAIL_HOOK_TYPES) lines.push('| ' + h.id + ' | ' + h.name + ' | ' + h.category + ' |');
+  lines.push('');
+  lines.push('**不得连续 3 章用同一种**（同一大分类也不行）：`HOOK_REPEAT`。');
+  lines.push('');
+
+  lines.push('### `micro_payoffs` —— 微兑现 7 种（每章至少 1 个）');
+  lines.push('');
+  lines.push('| id | 名称 |');
+  lines.push('|---|---|');
+  for (const m of MICRO_PAYOFFS) lines.push('| ' + m.id + ' | ' + m.name + ' |');
+  lines.push('');
+  lines.push('### `hook_strength` —— 钩子强度 5 级');
+  lines.push('');
+  lines.push('| id | 名称 | 级别 | 适用位置 |');
+  lines.push('|---|---|---|---|');
+  for (const s of HOOK_STRENGTHS) lines.push('| ' + s.id + ' | ' + s.name + ' | ' + s.level + ' | ' + s.usage + ' |');
+  lines.push('');
+  return lines.join('\n');
+}

package/plugins/fancy-story-builder/scripts/reference-log.js

@@ -0,0 +1,110 @@
+/**
+ * reference-log.js —— 参考决策台账
+ *
+ * 目的：LLM 每做一个会进入产物的设计决策，都要留下“依据了哪份参考、
+ * 具体哪一条、为什么这么用”的可追溯记录。
+ *
+ * 文件放在 `设定/.reference-decisions.md`：
+ *   - 不属于阶段产物，不参与 schema/ingest；
+ *   - 人类可读的 Markdown 表格；
+ *   - 只追加，不覆盖已有行。
+ *
+ * 这里只负责初始化、计数和生成提示词块；真正的“读取参考并做决策”
+ * 由 LLM 执行。插件在阶段收尾时把行数报给用户，缺失时给出警告。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const REFERENCE_LOG_PATH = '设定/.reference-decisions.md';
+export const REFERENCE_LOG_COLUMNS = ['阶段', '批次', '决策对象', '决策内容', '参考文件', '参考条目', '备注'];
+
+export const REFERENCE_LOG_HEADER = [
+  '# 参考决策记录',
+  '',
+  '> 本文件由 LLM 在每次设计决策后追加。只追加，不覆盖。',
+  '> 参考文件可以是 `references` 目录下的方法论，也可以是 `对标/wiki/` 下的总结。',
+  '',
+  '| ' + REFERENCE_LOG_COLUMNS.join(' | ') + ' |',
+  '|' + REFERENCE_LOG_COLUMNS.map(() => '---').join('|') + '|',
+  '',
+].join('\n');
+
+/** 确保 `设定/.reference-decisions.md` 存在；不覆盖已有内容。 */
+export function ensureReferenceDecisionLog(projectRoot) {
+  if (!projectRoot) return false;
+  const dir = join(projectRoot, '设定');
+  if (!existsSync(dir)) return false;
+  const file = join(projectRoot, REFERENCE_LOG_PATH);
+  if (existsSync(file)) return true;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, REFERENCE_LOG_HEADER, { encoding: 'utf-8', flag: 'wx' });
+    return true;
+  } catch {
+    // 并发创建时另一个批次可能已经写了；文件存在就算成功。
+    return existsSync(file);
+  }
+}
+
+/** 解析参考决策台账里的数据行。 */
+export function parseReferenceDecisionRows(projectRoot) {
+  const file = join(projectRoot, REFERENCE_LOG_PATH);
+  if (!existsSync(file)) return [];
+  let text = '';
+  try { text = readFileSync(file, 'utf-8'); } catch { return []; }
+  const rows = [];
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (trimmed.startsWith('| ' + REFERENCE_LOG_COLUMNS[0] + ' |')) continue;
+    const cells = trimmed.replace(/^\|/, '').replace(/\|$/, '').split('|').map((x) => x.trim());
+    if (cells.length < REFERENCE_LOG_COLUMNS.length) continue;
+    rows.push(Object.fromEntries(REFERENCE_LOG_COLUMNS.map((c, i) => [c, cells[i] || ''])));
+  }
+  return rows;
+}
+
+export function countReferenceDecisionRows(projectRoot) {
+  return parseReferenceDecisionRows(projectRoot).length;
+}
+
+/** 阶段收尾提示：把台账行数报给用户，空台账必须显眼。 */
+export function referenceLogNote(projectRoot) {
+  const count = countReferenceDecisionRows(projectRoot);
+  if (count > 0) {
+    return '📚 参考决策记录：' + count + ' 条（' + REFERENCE_LOG_PATH + '）';
+  }
+  return '⚠️ 参考决策记录为空：本次 LLM 没有按契约把“决策依据了哪份参考”写入 `' +
+    REFERENCE_LOG_PATH + '`。';
+}
+
+/**
+ * 批次提示词里的强制记录块。
+ *
+ * 这里不把“参考文件”限死在 对标/wiki：方法论 references 目录也是参考。
+ */
+export function referenceLogPromptBlock(stageLabel, batch, options = {}) {
+  const batchName = (batch && (batch.type || batch.groupKey || batch.file)) || '本批';
+  const allowed = options.allowedFileText || ('除本批分片外，`' + REFERENCE_LOG_PATH + '` 是本批唯一允许写的额外文件；不要修改 wiki、模板、references 目录或其它阶段。');
+  return [
+    '## 参考决策记录（必须）',
+    '',
+    '本批开始前必须实际读取本批参考清单中的 `references` 目录指导文档和 `对标/wiki` 目录总结；',
+    '插件注入的摘要只用于快速定位，**不能替代原文件**。本批列出的“本批优先参考”必须逐份核对；阶段级清单用于全局判断，不要求逐篇通读。',
+    '',
+    '每完成一个会进入产物的独立设计决策，就要向 `' + REFERENCE_LOG_PATH + '` 追加一行：',
+    '',
+    '| 阶段 | 批次 | 决策对象 | 决策内容 | 参考文件 | 参考条目 | 备注 |',
+    '|---|---|---|---|---|---|---|',
+    '| ' + stageLabel + ' | ' + batchName + ' | 例如 FS004 | 例如 设计“反向验证”式伏笔 | 例如 对标/wiki 下的伏笔布局总结 | 例如 用反向验证排除“整体替换”式解释 | 例如 让读者先看到结果再反推原因 |',
+    '',
+    '记录规则：',
+    '1. **每个独立决策至少一行**：每个实体、每条关系、每个伏笔/爽点/冲突节点、每章规划、每章细纲、每章正文都算独立决策；同一对象的多个字段如果依据不同参考，拆成多行。',
+    '2. `参考文件` 必须写实际读过的路径；`参考条目` 必须写原文里的标题/原则名，不能只写文件名；原文有“来源章节 / 来源实体”时，把对应章节或实体一并写进 `参考条目`。',
+    '3. `备注` 写清“为什么用、怎么用、哪些地方没有采用”，不要写“参考了”。',
+    '4. **只追加数据行**，不要重复写表头，不要覆盖或删除已有行；备注里的 `|` 写成 `\\|`。',
+    '5. ' + allowed,
+    '',
+  ].join('\n');
+}