@cloud411716/fancy-webnovel 1.0.46 → 2.2.0

package/client.js

@@ -0,0 +1,183 @@
+/**
+ * fancy-webnovel 浏览器半边。
+ *
+ * 目标：新会话里执行 /fancy-* 时，
+ *   1) **看得见**初始化成功/失败的结果；
+ *   2) **LLM 完全不被触发**（不发 provider 请求、零额度、零噪音）；
+ *   3) **会话日志保持干净**（插件一条都不写），agent 之后照常能跑。
+ *
+ * ── 为什么必须放在浏览器半边 ──────────────────────────────────────────────
+ * DSH 的聊天区有一个硬门槛（dsh-client-ui-chat/lib/client.js:5385）：
+ *
+ *     isActive: (snapshot) => snapshot.order.some((key) => snapshot.nodes.get(key)?.kind !== "command")
+ *
+ * 只有 kind !== "command" 的节点才会点亮聊天区。而命令结果在 DSH 里**就是**
+ * 一个 kind === "command" 的 flow 节点（dsh-client-ui-chat/lib/client.js:5514），
+ * 所以「插件不碰会话」= 聊天区永远不亮 = 用户什么都看不到。这就是「彻底本地」
+ * 方案让人眼前一空的真正原因，不是渲染坏了，是**门就没开**。
+ *
+ * 而宿主侧点亮只有一条路：在会话里写一条 user/message 占住 surface 节点 0。
+ * DSH 规定 surface 第一个节点必须是 agent 的 system/message（protected first
+ * surface head），插件一占，agent 之后一跑整个会话就读不回来 —— 磁盘上已经
+ * 有 160 个这样的坏会话。所以宿主侧的路是死的。
+ *
+ * ── 浏览器半边怎么开这扇门 ────────────────────────────────────────────────
+ * 1) package.json 声明 dsh.client + exports["./client"]
+ *    → dsh-client-modules/lib/index.js:479 扫 host Loader entries 找 dsh.client
+ *    → dsh-client-modules/lib/index.js:630-636 要求 platform === "web" 且有
+ *      exports["./client"]；扫到的包进 window.__DSH_BOOT__，浏览器加载它的 client bundle。
+ *    这是 DSH 自带的「双面包」机制（官方示范：dsh-client-ui-goal 的 host 半边
+ *    就是空的 `function apply() {}`），**不需要改 harness 一行代码**。
+ *
+ * 2) 注册一个自己的 conversation-node Definition（kind = "fancy-notice"），
+ *    匹配 command/run + command/done，只对 fancy-* 命令产出节点。
+ *    它的 kind 不是 "command" → 聊天区被点亮 → 结果可见。
+ *    节点本身**不渲染任何内容**（display:none）：结果由 DSH 原生的命令卡片
+ *    （GenericCommandCard）渲染，本来就完整，不需要我们再画一遍。
+ *
+ * 3) 空白会话里聊天区不挂载 → chat target 永远不会自动激活 →
+ *    conversationPhase（dsh-client-ui-conversation/lib/client.js:14011）
+ *    恒为 "blank" → 死循环。所以这里主动订阅当前会话的 chat target，
+ *    强制 assembler 激活它（dsh-client-ui-conversation/lib/client.js:794）。
+ *
+ * ── 铁律 ──────────────────────────────────────────────────────────────────
+ * 浏览器半边**只读**会话事件，一个字都不往会话里写。
+ * 会话的写入权仍然只有宿主插件，插件也仍然只写命令自己的结果（command/done）。
+ */
+window.__ModuleLoader__.load({
+	id: "@cloud411716/fancy-webnovel",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		var react = require("react");
+
+		/** 我们自己的 conversation-node kind（非 "command"，专用于点亮聊天区）。 */
+		var NOTICE_KIND = "fancy-notice";
+		/** 只对这些命令产出节点，别人的命令一概不碰。 */
+		var FANCY_COMMANDS = [
+			"fancy-bootstrap",
+			"fancy-analyze",
+			"fancy-import",
+			"fancy-scan",
+			"fancy-story-builder",
+			"fancy-topic"
+		];
+
+		/** 复刻 dsh-client-ui-chat 的 contextLocation（那边是包内私有函数）。 */
+		function contextLocation(context) {
+			return context.start?.location ?? context.matches[0]?.location ?? { kind: "unresolved" };
+		}
+
+		/** 把 command/run + command/done 折算成一条 fancy 通知。 */
+		var noticeDefinition = {
+			kind: NOTICE_KIND,
+			target: "chat",
+			match: function (event) {
+				if (event.type === "command/run") return { id: String(event.data.commandId), role: "start" };
+				if (event.type === "command/done") return { id: String(event.data.commandId), role: "update" };
+				return null;
+			},
+			start: function (_context, match) {
+				return {
+					name: match.event.data.name ?? "",
+					args: match.event.data.args ?? null,
+					outcome: null
+				};
+			},
+			update: function (context, match) {
+				if (match.event.type !== "command/done") return context.state;
+				return {
+					name: context.state?.name ?? "",
+					args: context.state?.args ?? null,
+					outcome: {
+						kind: match.event.data.kind,
+						text: match.event.data.text ?? ""
+					}
+				};
+			},
+			buildViewNode: function (context) {
+				var state = context.state;
+				if (state === undefined) return null;
+				if (FANCY_COMMANDS.indexOf(state.name) === -1) return null;
+				return {
+					key: context.key,
+					kind: NOTICE_KIND,
+					id: context.id,
+					target: "chat",
+					anchorSeq: context.startSeq ?? context.matches[0].event.seq,
+					location: contextLocation(context),
+					visibility: "visible",
+					data: state
+				};
+			}
+		};
+
+		/**
+		 * 点亮用的隐形节点。真正的可见内容由 DSH 原生命令卡片渲染，
+		 * 这里只留一个 data 钩子，方便自动化测试断言。
+		 */
+		function FancyNoticeNodeView(props) {
+			var data = props?.node?.data ?? {};
+			return react.createElement("div", {
+				"data-fancy-notice": data.name ?? "",
+				"data-fancy-notice-kind": data.outcome?.kind ?? "",
+				style: { display: "none" }
+			});
+		}
+
+		/**
+		 * 客户端插件体。
+		 * @param ctx - client root context.
+		 */
+		function apply(ctx) {
+			ctx.uiConversation.events.register(noticeDefinition);
+
+			// 注册我们这个 kind 的渲染器。不注册的话 DSH 会走 JsonBlock 兜底，
+			// 聊天区里会冒出一行「未知 surface 事件：fancy-notice」。
+			ctx.slots.inject("conversation.chat.node", function () {
+				return ctx.slots.register({
+					name: "conversation.chat.node",
+					key: NOTICE_KIND
+				}, FancyNoticeNodeView);
+			});
+
+			/*
+			 * 强制激活当前会话的 chat target。
+			 *
+			 * 空白会话里聊天区不挂载 → chat target 不会被激活 →
+			 * conversation.activeTargets 为空 → conversationPhase 恒为 "blank" →
+			 * ConversationSession 直接 return null → 聊天区永远不出现。
+			 * 这里订阅一次 chat target，逼 assembler 把它激活
+			 * （dsh-client-ui-conversation/lib/index.js:794 activateTarget）。
+			 */
+			var disposeCurrent = null;
+			ctx.effect(function () {
+				var sessions = ctx.sessions;
+				return sessions.list.subscribe(function () {
+					var current = sessions.list.getSnapshot().current;
+					if (typeof current !== "string" || current.length === 0) return;
+					if (disposeCurrent !== null) {
+						try {
+							disposeCurrent();
+						} catch {}
+						disposeCurrent = null;
+					}
+					try {
+						var binding = ctx.uiConversation.binding(current);
+						if (binding === undefined) return;
+						disposeCurrent = binding.target("chat").subscribe(function () {});
+					} catch (error) {
+						disposeCurrent = null;
+						ctx.logger.warn("fancy-webnovel: chat target activation failed: %s", String(error));
+					}
+				});
+			});
+		}
+
+		exports.apply = apply;
+		exports.inject = ["uiConversation", "sessions", "slots"];
+		return module.exports;
+	}
+});

package/cordis.patch.yml

@@ -1,17 +1,3 @@
-# @cloud411716/fancy-webnovel — DSH Cordis Plugin Patch
-#
-# IMPORTANT: This plugin creates project directories at user-specified paths
-# (which may be OUTSIDE the DSH workspace). Therefore it REQUIRES
-# `danger-full-access` sandbox mode. Add this to your profile's patch, e.g.:
-#
-#   - insert:
-#       - id: sandbox-policy
-#         config:
-#           mode: danger-full-access
-#
-# All other services used (commands, userQuestions, timer, events, session)
-# are part of dsh-base and available in every DSH UI (tui, web, desktop).
-
 - insert:
     - id: fancy-webnovel
       name: "@cloud411716/fancy-webnovel"

package/index.js

@@ -1,41 +1,25 @@
-/**
- * @cloud411716/fancy-webnovel — DSH Cordis Plugin
- *
- * Provides slash commands for web novel project workflow:
- *   /fancy-bootstrap  — Initialize a project root
- *   /fancy-scan       — Scan platform rank lists
- *
- * Architecture:
- *   - All scrapers run IN-PROCESS (no subprocess).
- *     DSH manages the lifecycle via ctx.effect() and AbortSignal.
- *   - HTTP fetching uses Node.js native fetch (portable across all DSH UIs).
- *   - File operations use Node.js fs (project roots may be outside workspace).
- *   - ctx.timer (via ctx.timeout()) handles all delays/timeouts.
- *
- * Required Cordis services: commands, userQuestions, timer
- * (all are part of dsh-base, so this plugin works on dsh-tui, dsh-web, dsh-desktop).
- *
- * IMPORTANT: This plugin needs `danger-full-access` sandbox mode because it
- * creates project directories outside the DSH workspace (at paths the user
- * specifies). Declare this in the profile's cordis.patch.yml.
- */
+// @cloud411716/fancy-webnovel unified entry point
+import { apply as applyBootstrap } from './plugins/fancy-bootstrap/index.js';
+import { apply as applyScan } from './plugins/fancy-scan/index.js';
+import { apply as applyTopic } from './plugins/fancy-topic/index.js';
+import { apply as applyAnalyze } from './plugins/fancy-analyze/index.js';
+import { apply as applyStoryBuilder } from './plugins/fancy-story-builder/index.js';
+import { apply as applyImport } from './plugins/fancy-import/index.js';
+import { registerSafeRmPrompt } from './lib/safe-rm.js';
 
-import { apply as applyBootstrap } from './commands/bootstrap/index.js';
-import { apply as applyScan }      from './commands/scan/index.js';
+export const inject = ['commands', 'userQuestions'];
 
-/**
- * Services this plugin requires from the Cordis context.
- * All are provided by dsh-base, so this works on every DSH UI.
- */
-export const inject = ['commands', 'userQuestions', 'timer'];
+export async function apply(ctx) {
+  // bundle 级提示：沙箱下 rm 会挂死（见 lib/safe-rm.js）。
+  // 放在这里而不是各子插件里，是因为每个子插件都可能让模型删临时文件，
+  // 逐个加必然漏 —— 一次注册对整个 bundle 的所有会话生效。
+  registerSafeRmPrompt(ctx);
 
-/**
- * Called once when the plugin is loaded into a Cordis context (fiber).
- * Registers slash commands; actual logic lives in per-command modules.
- *
- * @param {object} ctx - Cordis plugin context
- */
-export function apply(ctx) {
-  applyBootstrap(ctx);
-  applyScan(ctx);
+  await applyBootstrap(ctx);
+  await applyScan(ctx);
+  await applyTopic(ctx);
+  await applyAnalyze(ctx);
+  await applyStoryBuilder(ctx);
+  // 导入放在最后：它要用 story-builder 的模板与校验器
+  await applyImport(ctx);
 }

package/lib/chinese-num.js

@@ -0,0 +1,111 @@
+/**
+ * chinese-num.js —— 中文数字 ↔ 阿拉伯数字（插件共用）
+ *
+ * 为什么单独一个模块：
+ *   导入阶段要读旧稿里的"第十二章"，去味阶段要判断"# 第十二章"与
+ *   "# 第12章"是不是同一章。两边各写一份转换函数的话，
+ *   遇到"二十三""两百"这类写法就会一边认一边不认。
+ */
+
+/** 中文数字字符 → 值 */
+const CN_DIGITS = {
+  零: 0, 〇: 0, 一: 1, 二: 2, 两: 2, 三: 3, 四: 4,
+  五: 5, 六: 6, 七: 7, 八: 8, 九: 9
+};
+
+/**
+ * 中文数字转阿拉伯数字。
+ *
+ * 支持：一 ~ 九十九、一百、一百零八、**两千、三千、一千零一**、
+ * 一万、十二万、**一亿**。
+ *
+ * 2026-10-27 扩展到千/万/亿：之前只认到"百"，
+ * 于是"第三千章""第十二万章"这类写法一律返回 null ——
+ * 而 split_source.js 还**自己**写了一份更弱的转换（只到千，且没有"两"），
+ * 同一本书在不同插件里被切成了不同的章号。
+ * 现在全仓库统一走这一个函数。
+ *
+ * @param {string} s 中文数字串（纯数字直接转）
+ * @returns {number|null} 认不出来返回 null
+ */
+export function cnToNumber(s) {
+  const str = String(s || '').trim();
+  if (!str) return null;
+  if (/^\d+$/.test(str)) return Number(str);
+
+  let total = 0;      // 已完成的万/亿级部分
+  let section = 0;    // 当前小节（万以下）
+  let num = 0;        // 当前数字
+  let seen = false;
+  let pendingZero = false;
+
+  for (const ch of str) {
+    if (ch in CN_DIGITS) {
+      if (ch === '零' || ch === '〇') {
+        pendingZero = true;
+        num = 0;
+      } else {
+        num = CN_DIGITS[ch];
+        pendingZero = false;
+      }
+      seen = true;
+      continue;
+    }
+    if (ch === '十' || ch === '百' || ch === '千') {
+      const unit = ch === '十' ? 10 : (ch === '百' ? 100 : 1000);
+      // 前面没有数字时按 1 处理（十二 = 12、两千 = 2000）
+      section += (num === 0 && !pendingZero ? 1 : num) * unit;
+      num = 0;
+      pendingZero = false;
+      seen = true;
+      continue;
+    }
+    if (ch === '万' || ch === '亿') {
+      const unit = ch === '万' ? 10000 : 100000000;
+      // 先收拢当前小节，再整体乘单位（十二万 = 12 * 10000）
+      section += num;
+      total = (total + section) * unit;
+      section = 0;
+      num = 0;
+      pendingZero = false;
+      seen = true;
+      continue;
+    }
+    return null;
+  }
+  section += num;
+  const result = total + section;
+  return seen && result > 0 ? result : null;
+}
+
+/**
+ * 从一行文本里抠出"第 N 章"里的 N（阿拉伯或中文都行）。
+ *
+ * @param {string} line
+ * @param {string} [units] 允许的量词（默认 章回节）
+ * @returns {{no:number, unit:string, rest:string}|null}
+ */
+export function parseChapterNo(line, units = '章回节') {
+  const re = new RegExp('第\\s*([0-9]+|[〇零一二三四五六七八九十百千万两]+)\\s*([' + units + '])\\s*(.*)$');
+  const m = re.exec(String(line || '').trim());
+  if (!m) return null;
+  const no = cnToNumber(m[1]);
+  if (no === null) return null;
+  return { no, unit: m[2], rest: (m[3] || '').trim() };
+}
+
+/**
+ * 归一化章节标题行：把章号统一成阿拉伯数字、去掉前导零。
+ * "# 第012章 夜巡" 与 "# 第十二章 夜巡" 归一后相同。
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function normalizeChapterHeading(line) {
+  const raw = String(line || '').trim();
+  if (!raw) return '';
+  return raw.replace(/第\s*([0-9]+|[〇零一二三四五六七八九十百千万两]+)\s*([章回节])/, (m, no, unit) => {
+    const n = cnToNumber(no);
+    return n === null ? m : '第' + n + unit;
+  });
+}

package/lib/deployed-state.js

@@ -0,0 +1,141 @@
+/**
+ * .fancy-deployed 状态文件的统一体检。
+ *
+ * 这个文件是整个项目的状态源：phase（当前阶段）、llm_wiki_url/token、
+ * reference_id、setup_id 都在里面。五个插件都要读它，但原先各写各的：
+ *   - fancy-topic    readPhaseSafe()      → missing / corrupt / no_phase
+ *   - fancy-analyze  readDeployedConfig()  → missing / corrupt
+ *   - fancy-scan     advancePhase()        → missing / unknown_phase / error
+ * 三套口径不一致 → 同一个坏文件在三个插件里表现不同，
+ * 而且**没有一个插件告诉用户该怎么修** —— 最糟的情况下形成死循环：
+ *   /fancy-scan   扫完、报成功，但 phase 没推进（失败只写进 stderr）
+ *   /fancy-topic  报"状态文件读不了，请重新运行 /fancy-bootstrap"
+ *   /fancy-bootstrap  报"该目录已初始化"（只看文件存在，坏文件也拒绝）
+ * 用户被困在中间，没有任何命令能推进那个 phase。
+ *
+ * 所以这里统一两件事：**怎么判断**（readDeployedState）与
+ * **怎么修**（deployedStateProblemText）。
+ *
+ * @module lib/deployed-state
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/** 阶段推进顺序（只能向前） */
+export const PHASE_ORDER = ['initialized', 'scanned', 'topic_done', 'bible_done', 'outline_done'];
+
+/** 体检结果的状态枚举 */
+export const DEPLOYED_STATUS = {
+  OK: 'ok',
+  /** 文件不存在 */
+  MISSING: 'missing',
+  /** 文件不是合法 JSON */
+  CORRUPT: 'corrupt',
+  /** 文件是合法 JSON，但没有 phase 字段（或不是字符串） */
+  NO_PHASE: 'no_phase',
+  /** 有 phase 字段，但值不在 PHASE_ORDER 里 */
+  UNKNOWN_PHASE: 'unknown_phase',
+};
+
+/**
+ * 体检 .fancy-deployed。
+ *
+ * @param {string} projectRoot - 项目根目录
+ * @returns {{status: string, config: object|null, phase: string|null, error: string|null}}
+ */
+export function readDeployedState(projectRoot) {
+  const deployed = join(projectRoot, '.fancy-deployed');
+  if (!existsSync(deployed)) {
+    return { status: DEPLOYED_STATUS.MISSING, config: null, phase: null, error: null };
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(deployed, 'utf-8'));
+  } catch (e) {
+    return {
+      status: DEPLOYED_STATUS.CORRUPT,
+      config: null,
+      phase: null,
+      error: e && e.message ? e.message : String(e),
+    };
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return {
+      status: DEPLOYED_STATUS.CORRUPT,
+      config: null,
+      phase: null,
+      error: '不是合法的 JSON 对象',
+    };
+  }
+  if (typeof data.phase !== 'string' || data.phase === '') {
+    return { status: DEPLOYED_STATUS.NO_PHASE, config: data, phase: null, error: null };
+  }
+  if (!PHASE_ORDER.includes(data.phase)) {
+    return {
+      status: DEPLOYED_STATUS.UNKNOWN_PHASE,
+      config: data,
+      phase: data.phase,
+      error: `phase 的值 "${data.phase}" 不认识`,
+    };
+  }
+  return { status: DEPLOYED_STATUS.OK, config: data, phase: data.phase, error: null };
+}
+
+/**
+ * 把体检结果渲染成用户可读的说明（含**可执行的修复指引**）。
+ *
+ * 关键点：不能只说"文件坏了"。用户需要知道改哪一行、改成什么，
+ * 或者干脆怎么重建 —— 否则就只能反复重跑命令直到放弃。
+ *
+ * @param {object} state - readDeployedState 的返回值
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot] - 项目根（用于生成模板里的路径）
+ * @returns {string|null} status 为 ok 时返回 null
+ */
+export function deployedStateProblemText(state, opts = {}) {
+  if (!state || state.status === DEPLOYED_STATUS.OK) return null;
+  const projectRoot = opts.projectRoot || '';
+
+  if (state.status === DEPLOYED_STATUS.MISSING) {
+    return '❌ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+  }
+
+  const head = state.status === DEPLOYED_STATUS.CORRUPT
+    ? '❌ 状态文件 .fancy-deployed 损坏（不是合法 JSON），无法确定项目状态。'
+    : state.status === DEPLOYED_STATUS.NO_PHASE
+      ? '❌ 状态文件 .fancy-deployed 缺少 phase 字段，无法确定项目当前阶段。'
+      : `❌ 状态文件 .fancy-deployed 的 phase 值不认识（"${state.phase}"），无法确定项目当前阶段。`;
+
+  const phaseHelp = state.status === DEPLOYED_STATUS.CORRUPT
+    ? `3. 如果整个文件不是合法 JSON，用下面的模板重建 .fancy-deployed，
+       并把原来的 llm_wiki_token / reference_id 等字段值填回去：
+
+       {
+         "deployed_at": "<ISO 时间>",
+         "project_root_abs": "${projectRoot}",
+         "phase": "initialized",
+         "llm_wiki_url": "http://localhost:19828/api/v1",
+         "llm_wiki_token": "",
+         "reference_id": "",
+         "novel_id": "",
+         "provider": "custom"
+       }
+`
+    : `3. 把 phase 改成合法值之一：${PHASE_ORDER.join(' / ')}。
+       拿不准就填 "initialized" —— 它允许流程从头再走一遍。`;
+
+  return `${head}${state.error ? `\n原因：${state.error}` : ''}
+
+这条消息不能靠重跑命令解决（重跑只会再撞一次同样的问题），需要手工修复：
+
+1. 打开项目根目录下的 .fancy-deployed
+2. ${state.status === DEPLOYED_STATUS.CORRUPT
+      ? '确认文件内容是不是被截断了（写入过程中断电/被编辑器改坏都会这样）'
+      : `找到 "phase" 那一行${state.phase ? `（当前值 "${state.phase}"）` : ''}，改成下面任一合法值`}
+${phaseHelp}
+4. 修完重新执行刚才的命令
+
+另一条路（会丢配置，慎用）：
+5. 删除 .fancy-deployed 后重新运行 /fancy-bootstrap 重建。
+   注意：这会丢掉 llm_wiki_token / reference_id / setup_id 等字段，需要重新填。`;
+}

package/lib/error-codes.js

@@ -0,0 +1,104 @@
+/**
+ * lib/error-codes.js — 全插件统一错误码定义
+ *
+ * 所有 fancy-* 插件共享此文件，保证错误码命名一致。
+ *
+ * 使用：
+ *   import { EC, makeError } from '#error-codes';
+ *   console.log(JSON.stringify({ ok: false, error: makeError(EC.EC001_INVALID_PATH) }));
+ *
+ * 命名规则：
+ *   - ECxxx_NAME  全大写，下划线分隔
+ *   - code        数字（1-999）
+ *   - code_name   字符串 `ECxxx`，由 makeError 自动从 key 生成
+ *   - message     默认描述；调用方可用 makeError(EC.XXX, { message: '...' }) 覆盖
+ *
+ * 码段分配：
+ *   001-019  bootstrap    路径校验、初始化
+ *   020-039  scan         浏览器、采集、超时
+ *   040-059  topic        参数、phase、状态
+ *   060-079  bible        （预留）
+ *   080-099  outline      （预留）
+ *   100-119  write        （预留）
+ *   120-139  shared       通用（atomic-write、permission 等）
+ *   200+     system       致命错误
+ */
+
+export const EC = {
+  // ─── 001-019: bootstrap ───────────────────────────────────────
+  EC001_INVALID_PATH:        { code: 1,  message: '路径不合法（不能含空格、.. 或特殊字符）' },
+  EC002_ALREADY_INITIALIZED: { code: 2,  message: '项目已存在，不能重复 init' },
+  EC003_INVALID_PROJECT_ROOT:{ code: 3,  message: '项目根路径不是绝对路径或不存在' },
+  EC017_INIT_FAILED:         { code: 17, message: '初始化失败' },
+  EC018_DIR_NOT_FOUND:       { code: 18, message: '目录不存在' },
+  EC019_SENSITIVE_PATH:      { code: 19, message: '拒绝访问敏感系统路径' },
+
+  // ─── 020-039: scan ────────────────────────────────────────────
+  EC020_BROWSER_LAUNCH:      { code: 20, message: '浏览器启动失败' },
+  EC021_BROWSER_DISCONNECTED: { code: 21, message: '浏览器在采集过程中断开' },
+  EC022_PAGE_GOTO_TIMEOUT:    { code: 22, message: '页面导航超时' },
+  EC023_WAIT_RENDER_TIMEOUT:  { code: 23, message: '等待榜单渲染超时' },
+  EC024_SCRAPER_TIMEOUT:      { code: 24, message: 'scraper 子进程超时' },
+  EC025_SCRAPER_NON_JSON:     { code: 25, message: 'scraper 输出非 JSON' },
+  EC026_OCR_FAILED:           { code: 26, message: 'OCR 识别失败' },
+  EC027_NO_OUTPUT_FILES:      { code: 27, message: '未找到采集输出文件' },
+  EC028_INVALID_RANK:         { code: 28, message: '未知或非法的榜单 ID' },
+  EC029_INVALID_PLATFORM_SCAN:{ code: 29, message: '不支持的平台' },
+
+  // ─── 040-059: topic ───────────────────────────────────────────
+  EC040_INVALID_PLATFORM:    { code: 40, message: 'platform 参数非法' },
+  EC041_INVALID_GENRE:       { code: 41, message: 'genre 参数非法' },
+  EC042_MISSING_REQUIRED:    { code: 42, message: '必填参数缺失' },
+  EC043_PHASE_NOT_TOPIC:     { code: 43, message: '当前 phase 不允许 fancy-topic' },
+  EC044_TOPIC_STATE_MISSING: { code: 44, message: '_story_state.json 不存在' },
+  EC045_TOPIC_WRITE_FAILED:   { code: 45, message: 'fancy-topic 写盘失败' },
+  EC046_INVALID_WORDS:        { code: 46, message: '目标字数不合法（必须为正整数）' },
+  EC047_INVALID_CHAPTERS:     { code: 47, message: '目标章数不合法（必须为正整数）' },
+  EC048_PLATFORM_NOT_FOUND:   { code: 48, message: 'topic_decision 中找不到该平台的内容块' },
+
+  // ─── 120-139: shared ──────────────────────────────────────────
+  EC120_ATOMIC_WRITE_FAIL:   { code: 120, message: '原子写文件失败' },
+  EC121_PHASE_ADVANCE_FAIL:  { code: 121, message: 'phase 推进失败' },
+  EC122_PERMISSION_DENIED:   { code: 122, message: '权限不足' },
+  EC123_JSON_PARSE_FAIL:     { code: 123, message: 'JSON 解析失败' },
+  // "项目未初始化"与 EC002（项目已存在，不能重复 init）语义相反，
+  // 不能复用。此前 run-scan.js / select-topic.js 都把"未初始化"报成 EC002，
+  // 导致 code_name 与 message 自相矛盾（退出码 2 实际表示"未初始化"）。
+  EC124_PROJECT_NOT_INITIALIZED: { code: 124, message: '项目未初始化（.fancy-deployed 不存在）' },
+
+  // ─── 200+: system ─────────────────────────────────────────────
+  EC200_SPAWN_FAIL:          { code: 200, message: '子进程启动失败' },
+  EC201_SCRIPT_TIMEOUT:      { code: 201, message: '脚本执行超时' },
+};
+
+/**
+ * 把 EC.XXX 引用转成标准 error 对象。
+ *
+ * @param {object} ec - EC.XXX 之一
+ * @param {object} [extra] - 额外字段：
+ *   - message: 覆盖默认 message
+ *   - 其他字段会合并进 error 对象
+ * @returns {{ code: number, code_name: string, message: string }}
+ */
+export function makeError(ec, extra = {}) {
+  if (!ec || typeof ec !== 'object' || typeof ec.code !== 'number') {
+    throw new Error('makeError: invalid EC reference');
+  }
+  // 自动从 EC 找到 key 名作为 code_name（如 'EC001_INVALID_PATH'）
+  const codeName = Object.keys(EC).find(k => EC[k] === ec) || `EC${String(ec.code).padStart(3, '0')}`;
+  return {
+    code: ec.code,
+    code_name: codeName,
+    message: extra.message || ec.message,
+    ...(extra && typeof extra === 'object' ? Object.fromEntries(
+      Object.entries(extra).filter(([k]) => k !== 'message')
+    ) : {}),
+  };
+}
+
+/**
+ * 便捷函数：直接拼出 ok:false 错误响应
+ */
+export function errorResponse(ec, extra = {}) {
+  return { ok: false, error: makeError(ec, extra) };
+}