@cloud411716/fancy-webnovel 1.0.45 → 2.2.0

package/plugins/fancy-import/prompts/01-import-prompt.md

@@ -0,0 +1,106 @@
+# 01 导入执行须知
+
+> 本文件是导入阶段的**产物契约**：从旧稿反推出什么文件、写成什么格式、什么会被拦下。
+> 导入的因果方向和正向四阶段相反：
+> **旧稿已经在那里了 → 你把它读成结构化产物**，而不是照配额从零造。
+>
+> 导入阶段由插件驱动：它扫目录、切章、算配额、跑校验器、把错误发回来。
+> **你不需要自己决定写哪些文件，也不需要自己跑校验脚本。**
+
+---
+
+## 一、核心铁律
+
+> 1. **只反推，不创作**。旧稿里没有的人物、势力、地点、伏笔**不许新增**。
+>    你的任务是"把旧稿里已经有的东西整理成结构化数据"，
+>    不是"补全一部没写完的小说"。
+>    旧稿确实没写到的部分**留空**，由插件在报告里列成待补清单。
+>
+> 2. **不改旧稿正文**。正文由插件直接落盘（保留原标题），
+>    你只负责反推结构化产物。写了正文也算违反契约。
+>
+> 3. **不修改 `模板/` 和 `references/` 下的任何文件**。这两个目录是只读输入。
+>
+> 4. **只写本轮指定的文件**。本轮要写哪几个文件，驱动会在派活时列清楚。
+>    不要顺手多写，也不要改别的阶段的文件。
+>
+> 5. **引用的实体只能用 id 引用**（如 `C001`），不要在关系里写名字。
+
+---
+
+## 二、产物清单
+
+| 阶段 | 文件 | 落盘路径 |
+|---|---|---|
+| 骨架 | 实体.json | `设定/raw/sources/骨架/实体.json` |
+| 骨架 | 关系.json | `设定/raw/sources/骨架/关系.json` |
+| 骨架 | 层级.json | `设定/raw/sources/骨架/层级.json` |
+| 血肉 | 角色.json 等 8 个 | `设定/raw/sources/血肉/<名字>.json` |
+| 节奏 | 章节规划.json 等 4 个 | `设定/raw/sources/节奏/<名字>.json` |
+| 写作 | 4 个台账 | `设定/raw/sources/写作/台账/<名字>.json` |
+
+**`骨架/框架.json` 由插件生成，不要写。** 里面的 `quota` 是插件从旧稿实际规模
+反推出来的（推不出来的按公式补齐），你写的实体条数必须和它对得上。
+
+---
+
+## 三、怎么反推
+
+### 3.1 通用原则
+
+1. **先通读**：驱动会把旧稿的正文（或设定资料）摘要给你，先建立整体印象。
+2. **再归类**：把旧稿里出现过的东西按类型归到实体清单里。
+3. **只登记出现过的东西**：每个实体都要能在旧稿里找到出处
+   （角色有出场、势力有提及、地点有场景）。
+4. **拿不准就留空**：宁可少写一个，也别编一个。插件会把没写的列进待补清单。
+
+### 3.2 各阶段要点
+
+| 阶段 | 反推什么 | 注意 |
+|---|---|---|
+| 骨架 | 实体 / 关系 / 层级 | 只登记"出现过"的；层级里的卷要对应旧稿实际的卷 |
+| 血肉 | 每个实体"具体什么样" | 旧稿里写明的外貌/动机/口吻照抄；没写的留空字符串 |
+| 节奏 | 什么时间发生什么 | 章节号对应旧稿的实际章号；旧稿没写的章不要编 |
+| 台账 | 已发生的状态 | 章台账按 `ch` 一章一条；人物/伏笔/时间线照实记 |
+
+### 3.3 字段与枚举
+
+- 字段结构、id 规则、枚举取值：**以 `模板/` 下对应模板为准**
+  （`模板/骨架/实体模板.json` 等）。
+- 枚举词表（角色类型、冲突类型、伏笔类型…）：**以 `references/glossary.md` 为准**。
+  写错枚举值会被校验器拦下。
+
+---
+
+## 四、会被拦下的东西
+
+| 类别 | 错误码 | 说明 |
+|---|---|---|
+| 必填 | `REQUIRED` | 必填字段为空 |
+| 类型 | `TYPE` | 字段类型不对（该是数组写成了对象） |
+| id 规则 | `ID_FORMAT` / `ID_DUP` | id 不符合 `C001` / `F001` 这类格式，或 id 重复 |
+| 枚举 | `ENUM_INVALID` | 取值不在 glossary 的词表里 |
+| 引用 | `REF_UNKNOWN` | 关系里引用了不存在的 id |
+| 结构 | `DERIVATION_MISSING` | 框架.json 缺推导记录（**这个由插件生成，你不用管**） |
+| 内容 | `NAME_PLACEHOLDER` / `TEXT_PLACEHOLDER` / `TEXT_TOO_SHORT` / `TEXT_DUPLICATE` | 实体名是"主角1"这类标签、字段是"待补充"这类占位、字段太短、同质化 |
+
+---
+
+## 五、收到校验错误后怎么改
+
+驱动会把校验错误原样发回来（`code` / `path` / `message` / `hint`）。按这个顺序处理：
+
+1. **只改错误指向的字段**。错误没提到的部分不要动。
+2. **按 `hint` 的方向改**，不要绕过。
+3. **不要为了通过校验而编造内容**。校验器拦下"实体名是占位名"时，
+   正确做法是**删掉这个编出来的实体**，不是给它起个像样的名字。
+4. 改完**重新写整个文件**（产物是整份覆盖，不是打补丁）。
+
+**汇报格式**（每轮完成后给一段话）：
+
+```
+本轮完成：骨架（实体.json / 关系.json / 层级.json）
+- 实体 12 条：角色 5、冲突 3、势力 2、地点 2
+- 关系 18 条、层级 1 卷 3 主线 5 支线
+- 旧稿没写到的：地点的详细描述（已留空）
+```

package/plugins/fancy-import/templates.js

@@ -0,0 +1,49 @@
+/**
+ * fancy-import 插件的文案模板
+ */
+
+export const importTemplates = {
+  /**
+   * 通知文案。
+   * @param {Object} o
+   * @param {string} o.type
+   */
+  notify({ type, err, extra, chapters, files, rounds, failed }) {
+    switch (type) {
+      case 'no_project_root':
+        return '❌ 无法确定项目目录：' + (err || '会话未提供 cwd') + '。请在项目目录下运行该命令。';
+
+      case 'not_initialized':
+        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+
+      case 'no_source':
+        return '❌ 导入失败：' + (err || '未知错误');
+
+      case 'no_source_arg':
+        return '⚠️ 请指定要导入的旧稿路径：\n'
+          + '/fancy-import <旧稿目录或文件>\n'
+          + '（目录里的 .txt / .md 会被扫描；正文与设定资料自动归类）';
+
+      case 'deploy_failed':
+        return '❌ 导入阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间与目录权限后重试。';
+
+      case 'setup_id_unavailable':
+        return '❌ 未能建立 llm-wiki 设定项目：' + (err || '未知原因') +
+          '\n导入的产物要落在「设定」目录下才会被纳管，请先按提示处理 llm-wiki 配置。';
+
+      case 'import_done':
+        return '✅ 导入完成：' + chapters + ' 章旧稿已转成 story-builder 格式，' +
+          (rounds || 0) + ' 轮反推的**单文件校验**都通过（跨文件一致性由骨架阶段的 `--all` 校验把关）。' +
+          '报告见 `导入报告/导入报告.md`。' +
+          (extra ? '\n\n' + extra : '');
+
+      case 'import_incomplete':
+        return '⚠️ 导入完成，但有 ' + (failed || 0) + ' 轮反推未通过校验。' +
+          '**导入的产物目前不完整**，待补清单见 `导入报告/导入报告.md`。' +
+          (extra ? '\n\n' + extra : '');
+
+      default:
+        return extra || '';
+    }
+  }
+};

package/plugins/fancy-scan/index.js

@@ -0,0 +1,319 @@
+/**
+ * fancy-scan plugin entry
+ */
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { askUserQuestion, llmFollowup, notify, spawnScript } from '#infra';
+import { readDeployedState, deployedStateProblemText } from '#deployed-state';
+import { localDateStamp, DEFAULT_SCAN_MODE } from '#scraper-utils';
+import { scan, PLATFORM_TABLE, RANK_LISTS, parseScanMode } from './templates.js';
+
+export const inject = ['commands', 'userQuestions'];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCAN_SCRIPTS_DIR = join(__dirname, 'scripts');
+
+/**
+ * 解析用户选择的榜单
+ * @param {string[]} selected - 用户选择的 label 数组（如 '畅销榜' 或 '全选'）
+ * @param {string} platform - 平台
+ * @returns {string[]} 榜单 ID 数组，如果选择"全选"则返回所有榜单
+ */
+function parseRankLists(selected, platform) {
+  if (!Array.isArray(selected) || selected.length === 0) return [];
+
+  const allLists = (RANK_LISTS[platform] || []);
+
+  // 如果选择了"全选"，返回所有榜单
+  if (selected.includes('全选')) {
+    return allLists.map(r => r.id);
+  }
+
+  // 否则通过 label 查找 rank id
+  const ids = [];
+  for (const label of selected) {
+    const rank = allLists.find(r => r.label === label);
+    if (rank) ids.push(rank.id);
+  }
+  return ids;
+}
+
+/**
+ * 获取榜单标签列表（用于通知显示）
+ */
+function getRankLabels(rankIds, platform) {
+  if (!Array.isArray(rankIds) || rankIds.length === 0) return '';
+
+  const allLists = (RANK_LISTS[platform] || []);
+  if (rankIds.length === allLists.length) {
+    return '全选';
+  }
+  const labels = [];
+  for (const id of rankIds) {
+    const rank = allLists.find(r => r.id === id);
+    labels.push(rank ? rank.label : id);
+  }
+  return labels.join('、');
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-scan',
+    description: '📊 扫榜分析 ( usage: /fancy-scan )',
+    input: {
+	      hint: '.',
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      // 获取项目根（忽略所有命令行参数，统一通过交互选择）
+      // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
+      // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
+      const projectRoot = session.header?.cwd ?? null;
+      if (!projectRoot) {
+        return notify(session, 'error', scan.notify({
+          type: 'no_project_root',
+          err: '会话未提供 cwd'
+        }));
+      }
+
+      // 体检 .fancy-deployed —— 必须在**扫榜之前**查。
+      //
+      // 之前只检查文件存不存在，于是文件损坏时：
+      //   扫榜照跑、产物照出、命令照报成功，
+      //   但 phase 推不动（advancePhase 读不了那个文件，失败只写进 stderr），
+      //   下游 /fancy-topic 于是永远过不了 phase 检查。
+      // 用户只能反复重扫，死循环。
+      const deployedState = readDeployedState(projectRoot);
+      if (deployedState.status !== 'ok') {
+        const problem = deployedStateProblemText(deployedState, { projectRoot });
+        return notify(session, 'error', problem || scan.notify({ type: 'not_initialized' }));
+      }
+
+      // 忽略命令行参数，始终进入交互选择流程
+      let platform = '';
+
+      // 平台选择
+      if (!platform) {
+        if (signal?.aborted) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        const askedChoice = await askUserQuestion(ctx, invocation, [scan.askPlatform()]);
+        if (!askedChoice.ok) {
+          return notify(session, 'error', scan.notify({
+            type: askedChoice.failure.type,
+            err: askedChoice.failure.message
+          }));
+        }
+        const choice = askedChoice.answer;
+        if (!choice?.answers?.length || !choice.answers[0]) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        const selectedValue = choice.answers[0]?.selected?.[0];
+        if (!selectedValue) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        if (signal?.aborted) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        const row = PLATFORM_TABLE.find(r => r[2] === selectedValue);
+        if (!row) {
+          return notify(session, 'error', scan.notify({ type: 'invalid_choice' }));
+        }
+        platform = row[1];
+      }
+
+      // 榜单选择
+      let rankIds = [];
+      let rankListsQuestion = scan.askRankLists(platform);
+
+      if (signal?.aborted) {
+        return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+      }
+      const askedrankResult = await askUserQuestion(ctx, invocation, [rankListsQuestion]);
+      if (!askedrankResult.ok) {
+        return notify(session, 'error', scan.notify({
+          type: askedrankResult.failure.type,
+          err: askedrankResult.failure.message
+        }));
+      }
+      const rankResult = askedrankResult.answer;
+      if (!rankResult?.answers?.length || !rankResult.answers[0]) {
+        return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+      }
+      const selectedLabels = Array.isArray(rankResult.answers[0]?.selected) ? rankResult.answers[0].selected : [];
+      if (!selectedLabels.length) {
+        return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+      }
+      if (signal?.aborted) {
+        return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+      }
+
+      // 解析选择的榜单
+      rankIds = parseRankLists(selectedLabels, platform);
+      // 空榜单必须硬失败：此前会一路走到"采集完成"文案，但一个文件都没采到、
+      // 也不会投喂 LLM，用户看到的却是一切正常。
+      if (!rankIds.length) {
+        return notify(session, 'error', scan.notify({ type: 'no_rank_selected' }));
+      }
+      const rankLabels = getRankLabels(rankIds, platform);
+
+      // 扫描方式选择（榜单选定之后）。
+      // 只有番茄有两条取数路径（明文接口 / 截图 OCR），其他平台 askScanMode
+      // 返回 null —— 此时不打扰用户，scanMode 留空表示"该平台无此选项"。
+      let scanMode = '';
+      const scanModeQuestion = scan.askScanMode(platform);
+      if (scanModeQuestion) {
+        if (signal?.aborted) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        const askedMode = await askUserQuestion(ctx, invocation, [scanModeQuestion]);
+        if (!askedMode.ok) {
+          return notify(session, 'error', scan.notify({
+            type: askedMode.failure.type,
+            err: askedMode.failure.message
+          }));
+        }
+        const modeAnswer = askedMode.answer;
+        if (!modeAnswer?.answers?.length || !modeAnswer.answers[0]) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        // DSH 的 selected 回传的是 label 字符串（options.value 会被静默忽略）
+        const selectedMode = modeAnswer.answers[0]?.selected?.[0];
+        if (!selectedMode) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        const parsedMode = parseScanMode(selectedMode);
+        if (!parsedMode) {
+          return notify(session, 'error', scan.notify({ type: 'invalid_scan_mode' }));
+        }
+        scanMode = parsedMode;
+      }
+
+      // 依次采集每个榜单（单个榜单失败不中断，失败清单在末尾汇总）
+      const allFiles = [];
+      let phaseBlocked = null;
+      const failedRanks = [];
+      let lastDate = '';
+      for (const rankId of rankIds) {
+        const rankRow = RANK_LISTS[platform]?.find(r => r.id === rankId);
+        const rankLabel = rankRow ? rankRow.label : rankId;
+
+        const scriptResult = await spawnScript(
+          'node',
+          [join(SCAN_SCRIPTS_DIR, 'run-scan.js'),
+           '--project-root', projectRoot, '--platform', platform, '--rank', rankId,
+           '--scan-mode', scanMode || DEFAULT_SCAN_MODE],
+          // 这一层是兜底预算，必须大于 run-scan.js 内部的 scraper 预算
+          // （25 分钟，见 run-scan.js 的 SCRAPER_TIMEOUT_MS）。
+          // 若两层等长，外层会先 δ（node 启动耗时）触发：外层杀的是
+          // run-scan.js 的进程组，而 scraper 是 detached 独立成组的，
+          // 外层够不到它 —— run-scan.js 一死，它内部的定时器也没了，
+          // scraper 就成了带 chromium 的孤儿，一路跑到自然结束。
+          { timeout: 1800000 }
+        );
+
+        if (!scriptResult.ok) {
+          const innerErr = (typeof scriptResult.error === 'object' && scriptResult.error !== null)
+            ? (scriptResult.error.message || JSON.stringify(scriptResult.error))
+            : String(scriptResult.error || '未知错误');
+          // 此前任一榜单失败就整体中断，已采集成功的榜单产物被丢弃，
+          // 用户既不知道采到了什么，也拿不到那些文件。
+          failedRanks.push({ label: rankLabel, error: innerErr });
+          continue;
+        }
+
+        // 解析 receipt
+        let receipt;
+        try { receipt = JSON.parse(scriptResult.output); } catch (_) {
+          failedRanks.push({ label: rankLabel, error: '采集结果解析失败（输出非 JSON）' });
+          continue;
+        }
+
+        lastDate = receipt.date || lastDate;
+        const files = receipt.scan_files || [];
+        allFiles.push(...files);
+        // scraper 内部的部分失败（番茄某个题材采失败）必须透出：
+        // run-scan.js 对这种情况仍报 ok:true（只要有文件），
+        // 若这里不读 partialReasons，失败信息会在插件层被整个吞掉，
+        // 用户只看到"采集完成"，不知道哪个题材没采到。
+        if (Array.isArray(receipt.partialReasons) && receipt.partialReasons.length) {
+          failedRanks.push({
+            label: rankLabel,
+            error: '部分题材失败：' + receipt.partialReasons.join('；'),
+          });
+        }
+        // phase 推不动 = 整个流程卡住（/fancy-topic 要求 phase === 'scanned'）。
+        // run-scan.js 以前只把失败写进 stderr，这里不读就等于没发生。
+        if (receipt.phase_blocked === true) {
+          const pa = receipt.phase_advance || {};
+          phaseBlocked = {
+            reason: pa.reason || '未知原因',
+            message: pa.message || '',
+          };
+        }
+      }
+
+      // 一个榜单都没采成功 → 硬失败
+      if (allFiles.length === 0) {
+        const detail = failedRanks.length
+          ? failedRanks.map(f => f.label + '：' + f.error).join('；')
+          : '未产生任何采集文件';
+        return notify(session, 'error', scan.notify({ type: 'scraper_failed', err: detail }));
+      }
+
+      // 日期口径必须与 run-scan.js 一致（本地时区）。此前 fallback 用
+      // toISOString()（UTC），凌晨 0-8 点会算出比采集时点早一天的文件名。
+      const topicFile = allFiles.length > 0
+        ? join(projectRoot, '扫榜结果', `topic_decision_${lastDate || localDateStamp()}.md`)
+        : '';
+
+      // 通知用户采集完成（返回结果会显示在消息栏左侧）
+      const result = notify(session, 'success', scan.notify({
+        type: 'handover',
+        files: allFiles,
+        topicFile,
+        projectRoot,
+        failedRanks,
+        scanMode,
+      }));
+
+      // phase 推不动就别再触发 LLM 分析了 —— 分析产物写进 topic_decision 后，
+      // /fancy-topic 依然会因为 phase 不对而跑不了，纯属浪费。
+      if (phaseBlocked) {
+        const detail = deployedStateProblemText(
+          readDeployedState(projectRoot),
+          { projectRoot }
+        ) || '';
+        return notify(session, 'error', scan.notify({
+          type: 'phase_advance_failed',
+          err: phaseBlocked.reason + (phaseBlocked.message ? `（${phaseBlocked.message}）` : ''),
+          detail,
+        }));
+      }
+
+      // 触发 LLM 分析
+      if (allFiles.length > 0 && rankLabels) {
+        const follow = await llmFollowup(invocation, scan.llmAnalysisPrompt({
+          platform,
+          rankLists: rankLabels ? rankLabels.split('、') : ['全选'],
+          date: lastDate,
+          files: allFiles,
+          topicFile,
+          projectRoot,
+        }));
+        // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
+        // 否则投递失败也会报"采集完成，正在将数据交给 LLM 进行分析"
+        if (!follow || follow.ok !== true) {
+          return notify(session, 'error', scan.notify({
+            type: 'llm_delivery_failed',
+            err: (follow && follow.error) || '提示词投递失败'
+          }));
+        }
+      }
+
+      return result;
+    }
+  });
+}