@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-scan/index.js

@@ -0,0 +1,708 @@
+/**
+ * fancy-scan plugin entry
+ */
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { askUserQuestion, llmFollowup, notify, spawnScript } from '#infra';
+import { readDeployedState, deployedStateProblemText } from '#deployed-state';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+import { resolveWorkspace } from '#workspace';
+import { localDateStamp, DEFAULT_SCAN_MODE } from '#scraper-utils';
+import {
+  backupTopicDecision,
+  listMarkerBlocks,
+  repairTopicDecision,
+  inspectTopicDecision,
+  dedupeMarkerBlocks,
+  ensureTrailingNewline,
+} from '#topic-decision';
+import { readFileSync, existsSync, lstatSync, realpathSync, unlinkSync, mkdirSync } from 'fs';
+import { scan, PLATFORM_TABLE, RANK_LISTS, parseScanMode } from './templates.js';
+import { captureFileState, verifyBlockWritten } from './scripts/report-validate.js';
+import { inspectExistingBlock, EXISTING_BLOCK_STATUS } from './existing-block.js';
+import { waitForAnalysisTurn } from './wait-turn.js';
+import { deployScanTools, writeScanManifest } from './tool-deploy.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 [help] )',
+    input: {
+	      hint: '.',
+    },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const { signal } = invocation;
+
+      if ((invocation.rawInput || '').trim().toLowerCase() === 'help') {
+        return notify(session, 'success', scan.notify({ type: 'help' }));
+      }
+
+      // 获取工作区目录（忽略所有命令行参数，统一通过交互选择）
+      // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户工作区目录。
+      // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目执行部署与写盘。
+      const cwd = session.header?.cwd ?? null;
+      let projectRoot;
+      try {
+        projectRoot = resolveWorkspace({ cwd, required: true });
+      } catch {
+        projectRoot = cwd ? resolve(cwd) : null;
+      }
+      if (!projectRoot) {
+        return notify(session, 'error', scan.notify({
+          type: 'no_project_root',
+          err: '会话未提供当前工作目录'
+        }));
+      }
+      // 工作区目录来自会话 cwd；写盘前仍要过一遍路径守卫。
+      // 一个手工放置过 .fancy-deployed 的敏感目录（/etc 等）不能成为扫榜目标。
+      if (isSensitiveProjectPath(projectRoot) || !isValidProjectPath(projectRoot)) {
+        return notify(session, 'error', scan.notify({
+          type: 'no_project_root',
+          err: '工作区目录路径不合法或属于受保护目录'
+        }));
+      }
+      // 解开工作区目录的符号链接后再查一次：`/home/link -> /etc` 这种字符串
+      // 检查看不出来，但 run-scan 会跟着链接把 扫榜结果/ 写到 /etc。
+      try {
+        projectRoot = realpathSync(projectRoot);
+      } catch (e) {
+        return notify(session, 'error', scan.notify({
+          type: 'no_project_root',
+          err: `无法读取工作区目录：${e.message}`
+        }));
+      }
+      if (isSensitiveProjectPath(projectRoot) || !isValidProjectPath(projectRoot)) {
+        return notify(session, 'error', scan.notify({
+          type: 'no_project_root',
+          err: '工作区目录的真实路径属于受保护目录'
+        }));
+      }
+
+      // 扫榜结果/ 是插件自己的产物目录；如果它是指向工作区外的符号链接，
+      // 备份/修复/写入都会落到外面。run-scan 会拒绝，这里有旧项目时也要拦。
+      try {
+        const scanDirPath = join(projectRoot, '扫榜结果');
+        if (existsSync(scanDirPath)) {
+          const st = lstatSync(scanDirPath);
+          if (st.isSymbolicLink() || !st.isDirectory()) {
+            return notify(session, 'error', scan.notify({
+              type: 'no_project_root',
+              err: '扫榜结果/ 不是真实目录，拒绝写入；请换成真实目录'
+            }));
+          }
+        }
+      } catch { /* 目录不存在或检查失败交给后续流程 */ }
+
+      // 体检 .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);
+
+      // ── 采集前先查：今天这个平台 + 榜单是不是已经分析过 ──────────
+      // 平台、榜单、日期在采集前就确定了，块 ID 可以提前算出来。
+      // 如果目标文件里已经有本次块，再跑几十分钟采集没有任何意义；
+      // 直接发一条通知，不启动采集脚本、不改动任何文件。
+      const scanDateForCheck = localDateStamp();
+      const topicFileForCheck = join(
+        projectRoot,
+        '扫榜结果',
+        `topic_decision_${scanDateForCheck}.md`
+      );
+      const blockIdForCheck = scan.makeBlockId(platform, rankLabels, scanDateForCheck);
+      const existing = inspectExistingBlock(topicFileForCheck, blockIdForCheck);
+      if (existing.status === EXISTING_BLOCK_STATUS.FOUND) {
+        // 这不是失败：插件已经正确判断"今天这个块分析过了"，
+        // 没有启动采集、也没有改文件。用 success，避免命令面板把它
+        // 渲染成红色错误（用户会以为扫榜坏了）。
+        return notify(session, 'success', scan.notify({
+          type: 'already_scanned',
+          platform: scan.platformLabel(platform),
+          rankLabels,
+          date: scanDateForCheck,
+          topicFile: topicFileForCheck,
+          projectRoot,
+          blockId: blockIdForCheck,
+          closed: existing.blocks.length > 0 ? existing.blocks[0].closed : true,
+        }));
+      }
+      if (existing.status === EXISTING_BLOCK_STATUS.UNREADABLE) {
+        return notify(session, 'error', scan.notify({
+          type: 'existing_block_unreadable',
+          topicFile: topicFileForCheck,
+          projectRoot,
+          err: existing.error || '目标文件无法读取',
+        }));
+      }
+
+      // 扫描方式选择（榜单选定之后）。
+      // 只有番茄有两条取数路径（明文接口 / 截图 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;
+      }
+
+      // ── 部署工作区内工具脚本 ──────────────────────────────────────
+      // 提示词里的预检/追加命令只能引用工作区内路径。脚本放在插件目录下时，
+      // 模型会去 node_modules 里执行：路径长、随安装位置变化、且那里是
+      // 包管理器管理的只读目录。部署失败就直接停 —— 没有脚本就没有
+      // 可信的校验与写入路径，继续采集只会产出一份没人能兜底的报告。
+      const deployed = deployScanTools(projectRoot);
+      if (!deployed.ok) {
+        return notify(session, 'error', scan.notify({
+          type: 'tool_deploy_failed',
+          err: deployed.problems.join('；'),
+        }));
+      }
+
+      // 依次采集每个榜单（单个榜单失败不中断，失败清单在末尾汇总）
+      const allFiles = [];
+      let phaseBlocked = null;
+      const failedRanks = [];
+      const succeededRankIds = [];
+      const receiptDates = new Set();
+      let lastDate = '';
+      for (const rankId of rankIds) {
+        // 用户按停止后不要再启动下一个榜单的采集（每个榜单可能跑几十分钟）。
+        if (signal?.aborted) {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        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;
+        if (/^\d{8}$/.test(receipt.date || '')) receiptDates.add(receipt.date);
+        // receipt 来自子进程，不能假设字段一定是数组：字符串会被 spread 成字符。
+        const files = Array.isArray(receipt.scan_files) ? receipt.scan_files : [];
+        if (!files.length) {
+          failedRanks.push({ label: rankLabel, error: '采集回执里没有 scan_files 数组' });
+          continue;
+        }
+        allFiles.push(...files);
+        if (files.length > 0) succeededRankIds.push(rankId);
+        // 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 || '',
+          };
+        }
+      }
+
+      // 只把**真正采成功**的榜单写进提示词/块 ID。
+      // 之前把所有选中的 label 都传进去，某个榜失败时提示词会声称
+      // “它们都在本次数据文件里”，模型于是分析一个不存在的榜单。
+      const effectiveRankLabels = succeededRankIds.length
+        ? getRankLabels(succeededRankIds, platform)
+        : rankLabels;
+
+      // 一个榜单都没采成功 → 硬失败
+      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 在各自启动时取日期，可能出现
+      // 畅销榜 20261029、其它榜 20261030 的混合。此时不能拿最后一个
+      // receipt 的日期当整份日报的日期 —— 会把两天数据写进 10/30。
+      if (receiptDates.size > 1) {
+        return notify(session, 'error', scan.notify({
+          type: 'scan_date_mixed',
+          dates: [...receiptDates].sort(),
+          files: allFiles,
+          projectRoot,
+        }));
+      }
+
+      if (signal?.aborted) {
+        return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+      }
+
+      // 日期口径必须与 run-scan.js 一致（本地时区）。此前 fallback 用
+      // toISOString()（UTC），凌晨 0-8 点会算出比采集时点早一天的文件名。
+      // receipt 里的日期必须再验一次格式；坏日期不能拼进路径/块 ID。
+      const scanDate = /^\d{8}$/.test(lastDate) ? lastDate : localDateStamp();
+      const topicFile = allFiles.length > 0
+        ? join(projectRoot, '扫榜结果', `topic_decision_${scanDate}.md`)
+        : '';
+
+      // 2026-10-27：投递提示词之前，先把 topic_decision 的状态收拾干净。
+      //
+      // 写这个文件的是 LLM，而 LLM 的 write 工具是**覆盖**语义 ——
+      // 实测（tt5 项目）第二个平台分析时，模型先 write("") 把文件清空，
+      // 再 cat >> 追加自己的内容，第一个平台的分析就此消失，全程无报错。
+      // 提示词已经改成"只许 cat >> 追加、不许用 write"，但提示词只是建议，
+      // 真正的兜底是备份 + 校验恢复。
+      //
+      // 顺序不能乱：**先修复 → 再备份 → 最后才把已有内容告诉模型**。
+      //   修复 —— 上一轮可能被覆盖过，先把丢掉的段落补回来；
+      //   备份 —— 存的必须是补全后的内容，不然备份也是残缺的；
+      //   告知 —— 模型知道文件里已经有什么，才知道自己只该追加。
+      let repairedKeys = [];
+      try {
+        const repair = repairTopicDecision(topicFile);
+        if (repair.repaired.length) {
+          repairedKeys = repair.repaired;
+          console.error(`[fancy-scan] 上一次分析把 topic_decision 覆盖了，已从备份补回 ${repairedKeys.length} 个内容块：${repairedKeys.join('、')}`);
+        }
+      } catch (e) {
+        console.error('[fancy-scan] 校验 topic_decision 失败：' + (e && e.message ? e.message : String(e)));
+      }
+
+      const backup = backupTopicDecision(topicFile);
+      if (backup.backupPath) {
+        console.error(`[fancy-scan] 已备份 topic_decision → ${backup.backupPath}`);
+      }
+
+      // 文件末尾没有换行时，新追加的 start 标记会粘在旧行尾 ——
+      // grep 的 '^# …-start$' 就匹配不到了，模型会误判"没写进去"而重写，
+      // 于是同一个平台出现两个 start（写重了）。
+      // 这件事模型看不见，插件自己能看出来，所以在派发前补上。
+      try {
+        const nl = ensureTrailingNewline(topicFile);
+        if (nl.fixed) {
+          console.error('[fancy-scan] topic_decision 末尾缺换行，已补上（否则新块会粘在旧行尾）');
+        }
+      } catch (e) {
+        console.error('[fancy-scan] 补末尾换行失败：' + (e && e.message ? e.message : String(e)));
+      }
+
+      // 查文件里"上次写歪"的痕迹：同一个平台写了两遍、或把校验命令写进了正文。
+      //
+      // 模型自己看不见自己写进去的东西（写完就交差了），指望它"下次注意"没用。
+      // 插件查出来，写进提示词（让模型知道现状、别再重蹈覆辙），
+      // 同时通知用户。
+      //
+      // **重复的块直接收敛**（保留最后一个，与 topic 侧"后覆盖前"同向）：
+      // 重复内容对 topic 是有害的（同一平台两份，用户看到的是混乱），
+      // 而收敛前一定先备份，删错了能从 .revisions/ 找回来。
+      // 命令痕迹只报告不删 —— 删正文行有误伤风险，交给用户自己看。
+      let dirt = null;
+      let fileWarnings = [];
+      let deduped = null;
+      try {
+        if (existsSync(topicFile)) {
+          let found = inspectTopicDecision(readFileSync(topicFile, 'utf-8'));
+          if (found.duplicateKeys.length) {
+            const dd = backupTopicDecision(topicFile);
+            // 备份失败就不删任何重复块：删了找不回来，宁可把重复留给用户处理。
+            if (!dd.backupPath) {
+              fileWarnings.push('检测到重复块，但备份失败；为避免丢数据，本次不自动收敛，请人工检查');
+            } else {
+              const res = dedupeMarkerBlocks(topicFile);
+              if (res.ok && res.removed.length) {
+                deduped = {
+                  removed: res.removed,
+                  backupPath: dd.backupPath,
+                  kept: res.kept,
+                };
+                console.error(`[fancy-scan] topic_decision 收敛了 ${res.removed.length} 个重复块`);
+                // 收敛后重新查一遍，剩下的才是真正要提醒的
+                found = inspectTopicDecision(readFileSync(topicFile, 'utf-8'));
+              }
+            }
+          }
+          if (found.duplicateKeys.length || found.commandLines.length || found.unclosedBlocks.length) {
+            const lines = [];
+            for (const d of found.duplicateKeys) {
+              const msg = `「${d.key}」这个平台在文件里有 **${d.count} 个块**（上次追加写重了）`;
+              lines.push('- ' + msg);
+              fileWarnings.push(msg);
+            }
+            for (const c of found.commandLines) {
+              const msg = `「${c.key}」的块里混进了命令：\`${c.text}\``;
+              lines.push('- ' + msg);
+              fileWarnings.push(msg);
+            }
+            for (const u of found.unclosedBlocks) {
+              const msg = `「${u.key}」这个块**只有 start 标记、没有 end 标记**（上次没写完，内容被截断了）`;
+              lines.push('- ' + msg);
+              fileWarnings.push(msg);
+            }
+            dirt = { lines, deduped };
+            console.error(`[fancy-scan] topic_decision 有写歪痕迹：${lines.length} 条`);
+          }
+        }
+      } catch {
+        dirt = null;
+      }
+
+      // 把文件里已有的标记块告诉模型，让它知道"里面已经有什么"，
+      // 自己只该追加、不该重写。
+      //
+      // **必须在收敛之后读**（2026-10-29 审计）：之前这段在 dedupe 之前，
+      // 于是刚被删掉的重复块还留在列表里 ——
+      // 提示词告诉模型"文件里已经有这个块，一个字都不许动"，
+      // 而那个块刚被插件删了。
+      let existingBlocks = [];
+      try {
+        if (existsSync(topicFile)) {
+          existingBlocks = listMarkerBlocks(readFileSync(topicFile, 'utf-8'));
+        }
+      } catch {
+        existingBlocks = [];
+      }
+      if (existingBlocks.length) {
+        console.error(`[fancy-scan] topic_decision 已有 ${existingBlocks.length} 个内容块，提示词已告知模型只追加`);
+      }
+
+      // 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 && effectiveRankLabels) {
+        // 本次块的固定参数只算一次：块 ID、正文路径、指标与开关。
+        // 这些值同时进 manifest、提示词与回合结束后的复核 —— 三处必须完全一致。
+        const ds = scan.dataShape(platform);
+        const multiList = effectiveRankLabels === '全选'
+          || effectiveRankLabels.split('、').filter(Boolean).length > 1;
+        const metricLabel = scan.heatMetric(platform).label;
+        const blockId = scan.makeBlockId(platform, effectiveRankLabels, scanDate);
+        mkdirSync(join(projectRoot, '.tmp'), { recursive: true });
+        const bodyFile = scan.bodyFilePath(projectRoot, blockId, topicFile || projectRoot || '');
+        // 上一次运行可能留下同名的临时正文（同一块 ID）。先删掉：
+        // 模型如果跳过 5.1 直接跑 5.2，脚本会因为正文文件不存在而拒绝，
+        // 不会把上一轮的旧正文再追加一遍。
+        if (bodyFile.includes('fancy_scan_body_')) {
+          try { unlinkSync(bodyFile); } catch { /* 不存在 */ }
+        }
+        const manifest = writeScanManifest(projectRoot, {
+          topicFile,
+          blockId,
+          dataFiles: allFiles,
+          bodyFile,
+          metricLabel,
+          grouped: ds.grouped,
+          multiList,
+          rankLabels: (RANK_LISTS[platform] || []).map(r => r.label),
+        });
+        if (!manifest.ok) {
+          return notify(session, 'error', scan.notify({
+            type: 'manifest_failed',
+            err: manifest.problems.join('；'),
+          }));
+        }
+
+        // 写之前把文件状态记下来 —— 模型回合结束后要核对
+        // "旧内容有没有被动过"。模型看不见自己写进去的东西，
+        // 这一层只有插件能查。
+        let preWrite = null;
+        try {
+          preWrite = captureFileState(topicFile);
+        } catch {
+          preWrite = null;
+        }
+
+        const follow = await llmFollowup(invocation, scan.llmAnalysisPrompt({
+          platform,
+          rankLists: effectiveRankLabels ? effectiveRankLabels.split('、') : ['全选'],
+          date: scanDate,
+          files: allFiles,
+          topicFile,
+          projectRoot,
+          existingBlocks,
+          fileWarnings,
+          failedRanks,
+          appendScript: deployed.appendScript,
+          manifestPath: manifest.path,
+        }));
+        // llmFollowup 内部已捕获异常并返回 { ok, error }，必须检查返回值，
+        // 否则投递失败也会报"采集完成，正在将数据交给 LLM 进行分析"
+        if (!follow || follow.ok !== true) {
+          return notify(session, 'error', scan.notify({
+            type: 'llm_delivery_failed',
+            err: (follow && follow.error) || '提示词投递失败'
+          }));
+        }
+
+        // llmFollowup 只代表“消息已入队”，模型是异步跑的。
+        // 必须等这一轮真正结束再复核；否则会在模型还没开始写的时候
+        // 立刻报“目标文件不存在”，而几秒后模型又正常写进去了。
+        let waited = await waitForAnalysisTurn(invocation, { signal });
+        if (waited && waited.code === 'ABORTED') {
+          return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+        }
+        // DSH 在 TRANSPORT 错误后会自动给 agent 发“继续”，模型往往在
+        // 下一轮才真正写完。第一轮 wait 已经返回错误时，不要立刻判定
+        // 失败；只对明确的传输错误再等一轮，给自动重试一个机会。
+        if (waited && waited.code === 'TURN_ERROR'
+          && (waited.providerCode === 'TRANSPORT'
+            || /TRANSPORT|Connection error/i.test(waited.reason || ''))) {
+          waited = await waitForAnalysisTurn(invocation, {
+            signal,
+            timeoutMs: 10 * 60 * 1000,
+            // 实测 DSH 的自动“继续”在本轮报错后约 2 分钟才启动；
+            // 默认 120 秒的 idle 宽限只差 3 秒就会误判超时。
+            idleGraceMs: 5 * 60 * 1000,
+          });
+          if (waited && waited.code === 'ABORTED') {
+            return notify(session, 'error', scan.notify({ type: 'cancelled' }));
+          }
+        }
+
+        // ── 复核：这一次到底写进去没有、写对没有 ──────────────────
+        // 提示词里唯一的写入路径是 append-block.js（它自己会校验），
+        // 但模型**可能绕过脚本**。所以插件自己再查一遍：
+        // 块在不在、闭合没闭合、正文过不过机械校验、旧内容有没有被动过。
+        // 查出来不对就告诉用户 —— 不能让"没写进去"被当成"写成功了"。
+        try {
+          const vres = verifyBlockWritten(
+            topicFile,
+            blockId,
+            {
+              metricLabel,
+              grouped: ds.grouped,
+              multiList,
+              dataFiles: allFiles,
+              knownLists: (RANK_LISTS[platform] || []).map(r => r.label),
+            },
+            preWrite
+          );
+          if (!vres.ok) {
+            console.error('[fancy-scan] 写入复核不通过：' + vres.problems.join('；'));
+            const waitNote = (waited && waited.ok !== true && waited.code !== 'TURN_ENDED')
+              ? `（等待 LLM 回合：${waited.reason || waited.code}）`
+              : '';
+            return notify(session, 'error', scan.notify({
+              type: 'write_verify_failed',
+              err: `本次分析没有正确写入 ${topicFile}：${vres.problems.join('；')}${waitNote}`,
+            }));
+          }
+        } catch (e) {
+          // 复核本身出错（文件读不了 / 解析异常）不能静默放过：
+          // 否则用户会收到“成功”，但没人知道报告到底写没写对。
+          const msg = e && e.message ? e.message : String(e);
+          console.error('[fancy-scan] 写入复核出错：' + msg);
+          return notify(session, 'error', scan.notify({
+            type: 'write_verify_failed',
+            err: `写入复核本身失败：${msg}`,
+          }));
+        }
+      }
+
+      // 只有走到这里才是真的完成：采集成功 + LLM 回合结束 + 写入复核通过。
+      // 不能返回投递前的 handover 文案 —— 那会显示“正在将数据交给 LLM
+      // 进行分析”，而实际上分析已经做完了（真实日志 91f7ae4e 的第三条
+      // 命令就是这样：turn/end 之后仍显示“正在分析”）。
+      const doneText = scan.notify({
+        type: 'analysis_done',
+        platform: scan.platformLabel(platform),
+        rankLabels: effectiveRankLabels,
+        date: scanDate,
+        files: allFiles,
+        topicFile,
+        projectRoot,
+        failedRanks,
+        scanMode,
+        repaired: repairedKeys,
+      });
+      const dirtText = dirt ? '\n\n' + scan.notify({ type: 'dirty_file', dirt }) : '';
+      return notify(session, 'success', doneText + dirtText);
+    }
+  });
+}