@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-analyze/summary-progress.js

@@ -0,0 +1,495 @@
+/**
+ * fancy-analyze/summary-progress.js —— 技法总结进度（纯本地，零网络、零 LLM）。
+ *
+ * ## 为什么需要它
+ *
+ * `/fancy-analyze summary` 的真实动作只有一件：把一段提示词投给模型
+ * （plugins/fancy-analyze/index.js 的 summary 分支 → llmFollowup）。
+ * 真正的写作由模型在后续 agent loop 里**异步**完成，而 llmFollowup 的
+ * 返回值只代表"消息已入队"（lib/infra.js:329-332 明写："这里的 ok 只代表
+ * '消息已入队'，不代表模型已处理"）。
+ *
+ * 所以命令返回"✅ 技法总结完成"时，模型一个字都还没写 ——
+ * 进度只能从**文件系统事实**里读出来。
+ *
+ * ## 单一事实源：总结文件头部的「已总结章节」
+ *
+ * 提示词要求增量写入：每读完一个源文件就把提炼结果追加进
+ * `对标/wiki/<技法>/<技法>-总结.md`。
+ *
+ * 但"增量追加"本身挡不住重复劳动 —— 第二次跑 summary 时，模型会把
+ * 已经总结过的章节再读一遍、再追加一遍（提示词里的"去重合并"是软约束，
+ * 模型不保证做到）。
+ *
+ * 所以**头部要记章节清单**，而且它就是唯一事实源：
+ *
+ *     ---
+ *     已总结章节:
+ *       - 全球高武-节奏韵律-第1章
+ *       - 全球高武-节奏韵律-第2章
+ *     ---
+ *
+ * 头部**只有这一个键** —— 早先还写过「标题:」「标签:」，但整个插件里
+ * 没有任何代码读它们，是死字段（详见 append-summary-chapter.js）。
+ *
+ * 由此：
+ *   · 待总结章节 = 源文件清单 − 头部已总结章节
+ *   · 派活时**只给目录**，章节由模型自己去目录里比对（几千章时列名字会撑爆提示词）
+ *   · 待总结章节为空 → 该技法**已完成**
+ *
+ * ## 为什么不另写状态文件
+ *
+ * 一切都能从总结文件本身推出来，所以**不写** `.summary-state.json` 之类的东西：
+ * 少一个可能与事实漂移的数据源，少一份"写失败要报出来"的复杂度，
+ * 而且这个命令可以随时查、查多少次都一样。
+ *
+ * ## 头部缺字段怎么办
+ *
+ * 老文件、或模型没按格式写头部 → 章节清单解析为空。
+ * 这时**保守退化**：把全部源文件当成"未总结"（等于回到派发整个目录的老行为），
+ * 并且在进度报告里明说"头部没有章节清单，无法判断哪些已总结"。
+ * 宁可多派一次（模型会去重合并），也不能因为头部格式没写对就卡住不动。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 总结文件头部里记录已总结章节的字段名。 */
+export const SUMMARY_FRONTMATTER_KEY = '已总结章节';
+
+/** llm_wiki 的摄入产物目录，不是技法目录。 */
+export const EXCLUDED_WIKI_DIRS = ['来源', '来源摘要'];
+
+/**
+ * 跨章节实体页目录：这些目录也要做 summary，但总结单位是“实体页”，
+ * 不是“章节”。提示词会读取每个实体页的 `## 可复用设计规则` 和
+ * `## 风险与反例`，提炼跨实体、跨章节的设计原则。
+ */
+export const ENTITY_SCOPED_DIRS = [
+  '人物关系设计',
+  '势力结构',
+  '世界观设计',
+  '冲突设计',
+  '主线支线结构',
+  '分卷节奏',
+  '伏笔布局',
+  '角色弧光设计',
+];
+
+/**
+ * 旧版按章结构页目录。它们与新版实体页**不是同一种东西**：
+ *   · 伏笔回收（按章）→ 伏笔布局（按伏笔实体）
+ *   · 世界观构建 / 世界观规则设计（按章）→ 世界观设计（按规则/体系实体）
+ *   · 角色弧光（按章）→ 角色弧光设计（按角色实体）
+ *
+ * 不能自动迁移，也不能把它们当实体页检查 —— 否则每章一个页面会被误判成
+ * “同一个实体有多个页面”。这里只负责让它们不参与 summary 派发，并在
+ * status / summary-status 里提示重新 ingest。
+ */
+export const LEGACY_STRUCTURE_DIRS = [
+  '伏笔回收',
+  '世界观构建',
+  '世界观规则设计',
+  '角色弧光',
+];
+
+/** 进度状态。 */
+export const SUMMARY_STATE = {
+  DONE: 'done',
+  RUNNING: 'running',
+  PENDING: 'pending',
+  NO_INPUT: 'no-input',
+};
+
+/**
+ * 取文件开头的 YAML front-matter 文本。
+ *
+ * 只做"取开头两段 --- 之间的原文"，不做 YAML 解析 ——
+ * 本插件不能引入新依赖，而我们需要的东西就是一个键值对列表。
+ *
+ * @param {string} text - 文件全文
+ * @returns {string|null} front-matter 原文；没有 front-matter 时返回 null
+ */
+export function extractFrontmatter(text) {
+  if (typeof text !== 'string') return null;
+  const normalized = text.replace(/^/, '');
+  if (!/^---\r?\n/.test(normalized)) return null;
+  const rest = normalized.slice(normalized.indexOf('\n') + 1);
+  const end = rest.search(/^---[ \t]*(\r?\n|$)/m);
+  if (end === -1) return null;
+  return rest.slice(0, end);
+}
+
+/**
+ * 从 front-matter 里读出已总结章节清单。
+ *
+ * 支持两种写法（容错：模型不一定照抄示例）：
+ *   块列表（示例里的写法）
+ *       已总结章节:
+ *         - 甲-第1章
+ *         - 甲-第2章
+ *   行内数组
+ *       已总结章节: [甲-第1章, 甲-第2章]
+ *
+ * @param {string} frontmatter - front-matter 原文
+ * @returns {string[]} 已总结章节标识（去重、保序）
+ */
+export function parseSummarizedChapters(frontmatter) {
+  if (typeof frontmatter !== 'string' || frontmatter.length === 0) return [];
+  const lines = frontmatter.split(/\r?\n/);
+  const out = [];
+  const seen = new Set();
+  const push = (value) => {
+    const v = String(value).trim().replace(/^["']|["']$/g, '').trim();
+    if (v.length === 0 || seen.has(v)) return;
+    seen.add(v);
+    out.push(v);
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const keyMatch = line.match(/^\s*已总结章节\s*[:：]\s*(.*)$/);
+    if (!keyMatch) continue;
+    const inline = keyMatch[1].trim();
+    if (inline.startsWith('[') && inline.endsWith(']')) {
+      for (const part of inline.slice(1, -1).split(',')) push(part);
+      continue;
+    }
+    // 块列表：往下吃所有 "- xxx"
+    for (let j = i + 1; j < lines.length; j++) {
+      const item = lines[j].match(/^\s*-\s+(.*\S)\s*$/);
+      if (!item) {
+        // 空行继续；碰到别的键就停
+        if (lines[j].trim() === '') continue;
+        break;
+      }
+      push(item[1]);
+    }
+    break;
+  }
+  return out;
+}
+
+/**
+ * 把「已总结章节」的名字对齐到源文件标识。
+ *
+ * 模型写章节名的格式很不统一（实测）：
+ *   - `全球高武-场景转换-第3章`          精确
+ *   - `[全球高武-世界观构建-第2章, 第3章]`  带方括号 + 简写
+ *   - `第7章`                            裸章号
+ *
+ * 对齐策略（从严到宽，只在**唯一**时才认，绝不猜）：
+ *   1. 精确等于某个源文件标识 → 对齐
+ *   2. 尾部是「第N章」，且目录里**只有一个**文件以它结尾 → 对齐
+ *
+ * 第 2 条能救回简写；第 1 条之外的绝不宽松 —— 上游数据里出现过错名文件
+ * （`全球高武-伏文富武-第3章.md`，技法名打错字），宽松匹配会把
+ * 真的没总结的章节误判成已总结，于是那一章永远不再被处理。
+ *
+ * @param {string[]} names - 待对齐的章节名
+ * @param {string[]} sourceFiles - 源文件标识集合
+ * @returns {{aligned: string[], unmatched: string[]}}
+ */
+export function alignChapterIds(names, sourceFiles) {
+  const known = Array.isArray(sourceFiles) ? sourceFiles : [];
+  const aligned = [];
+  const unmatched = [];
+  const seen = new Set();
+  for (const raw of names) {
+    // 去方括号、引号、空白，以及 .md 后缀
+    // （实测三种写法都出现过：`甲-第1章`、`[甲-第1章]`、`[甲-第1章.md]`）
+    const name = String(raw)
+      .trim()
+      .replace(/^[[\]]+|[[\]]+$/g, '')
+      .trim()
+      .replace(/\.md$/i, '')
+      .trim();
+    if (name.length === 0) continue;
+    let hit = null;
+    if (known.includes(name)) {
+      hit = name;
+    } else {
+      const tail = name.match(/第\d+章\s*$/);
+      if (tail) {
+        const candidates = known.filter((f) => f.endsWith(tail[0]));
+        if (candidates.length === 1) hit = candidates[0];
+      }
+    }
+    if (hit === null) {
+      unmatched.push(name);
+      continue;
+    }
+    if (seen.has(hit)) continue;
+    seen.add(hit);
+    aligned.push(hit);
+  }
+  return { aligned, unmatched };
+}
+
+/**
+ * 从总结正文里**反推**已总结章节。
+ *
+ * ## 为什么需要反推
+ *
+ * 「已总结章节」头部是新加的，老总结文件（本次改动之前生成的）里没有。
+ * 如果只认头部，所有老项目都会被判成"一个章节都没总结"，
+ * 下次 summary 会把整本重新跑一遍 —— 对用户来说是灾难性的返工。
+ *
+ * 好在每条技法条目本身就记着它来自哪些文件：
+ *
+ *     ### 轻叙、爆料与心理停顿交替
+ *     - 来源章节：全球高武-节奏韵律-第1章
+ *
+ * 于是可以从正文里反推"哪些章节被总结过"。
+ *
+ * 反推的结果**不如头部权威**（模型可能写错、可能漏写），
+ * 所以调用方要能区分两者：头部优先，缺失时用反推兜底，两者都没有才算
+ * "完全不知道"。
+ *
+ * @param {string} text - 总结文件全文
+ * @param {string[]} knownIds - 已知的源章节标识（用于对齐与过滤）
+ * @returns {{chapters: string[], unmatched: string[]}}
+ */
+export function inferSummarizedChapters(text, knownIds) {
+  if (typeof text !== 'string' || text.length === 0) return { chapters: [], unmatched: [] };
+  const raw = [];
+  for (const match of text.matchAll(/^\s*-\s*来源(?:章节|实体|页面)\s*[:：]\s*(.+)$/gm)) {
+    // "来源章节：甲-第1章、甲-第2章" → 拆开
+    for (const part of String(match[1]).split(/[、,，;；]/)) {
+      const v = part.trim();
+      if (v.length > 0) raw.push(v);
+    }
+  }
+  return alignChapterIds(raw, knownIds);
+}
+
+/**
+ * 取出章节标识里的章号。
+ *
+ * 章节标识长这样：`全球高武-场景转换-第10章`。
+ * 章号是稳定语义（技法名可能被打错字，章号不会），所以排序靠它。
+ *
+ * @param {string} id - 章节标识
+ * @returns {number|null} 章号；取不到时返回 null
+ */
+export function chapterNumber(id) {
+  const match = String(id).match(/第(\d+)章/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * 章节标识的自然排序：先按章号升序，再按名称。
+ *
+ * 纯字典序会把「第10章」排在「第2章」前面 —— 那样批次推进会跳着来，
+ * 模型拿到的章节序列也不连续。
+ *
+ * @param {string} a - 章节标识
+ * @param {string} b - 章节标识
+ * @returns {number} 比较结果
+ */
+export function compareChapterIds(a, b) {
+  const na = chapterNumber(a);
+  const nb = chapterNumber(b);
+  if (na !== null && nb !== null && na !== nb) return na - nb;
+  if (na !== null && nb === null) return -1;
+  if (na === null && nb !== null) return 1;
+  return String(a).localeCompare(String(b), 'zh-Hans-CN');
+}
+
+/**
+ * 列出对标/wiki 下的技法目录（排除 llm_wiki 的摄入产物目录）。
+ *
+ * @param {string} wikiRoot - 对标/wiki 的绝对路径
+ * @returns {string[]} 目录名，按字典序
+ */
+export function listTechDirs(wikiRoot) {
+  let entries;
+  try {
+    entries = fs.readdirSync(wikiRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (EXCLUDED_WIKI_DIRS.includes(entry.name)) continue;
+    dirs.push(entry.name);
+  }
+  // 中文目录名按拼音排（否则 UTF-16 码位序会把「已完成/未开始/进行中」这类
+  // 名字排得毫无章法），localeCompare 在 Node 的 ICU 下可用。
+  return dirs.sort((a, b) => a.localeCompare(b, 'zh-Hans-CN'));
+}
+
+/**
+ * 返回需要做 summary 的目录：按章技法目录 + 跨章节实体目录。
+ * 旧版按章结构目录仍排除（它们等待迁移，不参与新 summary）。
+ */
+export function listSummaryDirs(wikiRoot) {
+  return listTechDirs(wikiRoot).filter(
+    (name) => !LEGACY_STRUCTURE_DIRS.includes(name));
+}
+
+function countEntityPages(wikiRoot, dirName) {
+  try {
+    const files = fs.readdirSync(path.join(wikiRoot, dirName), { withFileTypes: true });
+    return files.filter((file) =>
+      file.isFile() &&
+      file.name.endsWith('.md') &&
+      !file.name.endsWith('-总结.md')
+    ).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * 读一个技法目录的进度。
+ *
+ * @param {string} wikiRoot - 对标/wiki 的绝对路径
+ * @param {string} dirName - 技法目录名
+ * @returns {object|null} 进度对象；目录读不到时返回 null
+ */
+export function readDirProgress(wikiRoot, dirName) {
+  const dirPath = path.join(wikiRoot, dirName);
+  const summaryName = `${dirName}-总结.md`;
+  const summaryPath = path.join(dirPath, summaryName);
+
+  let files;
+  try {
+    files = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const sourceFiles = [];
+  let sourceBytes = 0;
+  for (const file of files) {
+    if (!file.isFile()) continue;
+    if (!file.name.endsWith('.md')) continue;
+    // 总结文件本身不是输入
+    if (file.name === summaryName) continue;
+    sourceFiles.push(file.name.replace(/\.md$/, ''));
+    try {
+      sourceBytes += fs.statSync(path.join(dirPath, file.name)).size;
+    } catch {
+      // 单个文件读不到就当它不存在，不影响其余统计
+    }
+  }
+  sourceFiles.sort(compareChapterIds);   // 按章号升序，不是字典序
+
+  const progress = {
+    name: dirName,
+    /** chapter = 按章技法；entity = 跨章节实体页。 */
+    scope: ENTITY_SCOPED_DIRS.includes(dirName) ? 'entity' : 'chapter',
+    summaryPath,
+    sourceFiles,
+    sourceCount: sourceFiles.length,
+    sourceBytes,
+    hasInput: sourceFiles.length > 0,
+    exists: false,
+    summarized: [],
+    chapterSource: 'none',
+    unmatchedChapters: [],
+    pendingFiles: sourceFiles.slice(),
+    hasChapterList: false,
+    entries: 0,
+    bytes: 0,
+    updatedAt: 0,
+    state: SUMMARY_STATE.PENDING,
+  };
+
+  if (!progress.hasInput) {
+    // 一个源文件都没有 → 无输入，不该派发（连总结文件存不存在都无所谓）
+    progress.state = SUMMARY_STATE.NO_INPUT;
+    return progress;
+  }
+
+  let text;
+  try {
+    text = fs.readFileSync(summaryPath, 'utf8');
+  } catch {
+    return progress;
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(summaryPath);
+  } catch {
+    return progress;
+  }
+
+  progress.exists = true;
+  progress.bytes = stat.size;
+  progress.updatedAt = stat.mtimeMs;
+  // 技法条目 = 总结文件里的三级标题（### 开头）。
+  // 文件结构是「## 核心技法」下面挂若干「### 技法名」，所以 ### 正好是条目数。
+  progress.entries = (text.match(/^###\s+\S/gm) || []).length;
+
+  const frontmatter = extractFrontmatter(text);
+  const fromHeader = alignChapterIds(parseSummarizedChapters(frontmatter), sourceFiles);
+  const fromBody = inferSummarizedChapters(text, sourceFiles);
+  // 头部权威；头部缺失时用正文反推兜底
+  const summarized = fromHeader.aligned.length > 0 ? fromHeader.aligned : fromBody.aligned;
+  const chapterSource = fromHeader.aligned.length > 0
+    ? 'header'
+    : (fromBody.aligned.length > 0 ? 'inferred' : 'none');
+  progress.summarized = summarized;
+  progress.chapterSource = chapterSource;
+  progress.hasChapterList = chapterSource !== 'none';
+  progress.unmatchedChapters = [...fromHeader.unmatched, ...fromBody.unmatched];
+
+  if (!progress.hasChapterList) {
+    // 头部没有章节清单 → 保守：全部源文件都算"未总结"
+    progress.state = SUMMARY_STATE.PENDING;
+    return progress;
+  }
+
+  const done = new Set(summarized);
+  progress.pendingFiles = sourceFiles.filter((f) => !done.has(f));
+  progress.state = progress.pendingFiles.length === 0
+    ? SUMMARY_STATE.DONE
+    : SUMMARY_STATE.RUNNING;
+  return progress;
+}
+
+/**
+ * 扫描全部技法目录的进度。
+ *
+ * @param {string} wikiRoot - 对标/wiki 的绝对路径
+ * @returns {{dirs: object[], legacyDirs: object[], done: object[], running: object[], pending: object[], noInput: object[], total: number}}
+ */
+export function scanSummaryProgress(wikiRoot) {
+  const allDirs = listTechDirs(wikiRoot);
+  const legacyDirs = allDirs
+    .filter((name) => LEGACY_STRUCTURE_DIRS.includes(name))
+    .map((name) => ({ name, pageCount: countEntityPages(wikiRoot, name) }));
+  const dirs = allDirs
+    .filter((name) => !LEGACY_STRUCTURE_DIRS.includes(name))
+    .map((name) => readDirProgress(wikiRoot, name))
+    .filter((p) => p !== null);
+
+  return {
+    dirs,
+    legacyDirs,
+    done: dirs.filter((p) => p.state === SUMMARY_STATE.DONE),
+    running: dirs.filter((p) => p.state === SUMMARY_STATE.RUNNING),
+    pending: dirs.filter((p) => p.state === SUMMARY_STATE.PENDING),
+    noInput: dirs.filter((p) => p.state === SUMMARY_STATE.NO_INPUT),
+    total: dirs.length,
+  };
+}
+
+/**
+ * 该派给模型的目录：有输入、且还有章节没总结。
+ *
+ * 已完成的目录不再重复派发（要重做就用 resummary）——
+ * 否则每次 summary 都会让模型把已经提炼过的技法再追加一遍。
+ *
+ * @param {object} progress - scanSummaryProgress 的结果
+ * @returns {object[]} 进度对象数组（按目录名排序）
+ */
+export function dirsToDispatch(progress) {
+  return progress.dirs.filter(
+    (p) => p.hasInput && p.state !== SUMMARY_STATE.DONE && p.pendingFiles.length > 0
+  );
+}