@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-scan/tool-deploy.js

@@ -0,0 +1,335 @@
+/**
+ * tool-deploy.js —— 把 `append-block.js` 及其依赖部署到工作区内
+ *
+ * ## 为什么不在插件目录里跑
+ *
+ * 插件装在 `node_modules/@cloud411716/fancy-webnovel/` 下，部署位置、包名、
+ * 版本目录都可能变。提示词让 LLM 去那里执行脚本有三个问题：
+ *
+ *   1. 路径长且随安装位置变化，模型容易抄错、抄漏；
+ *   2. 插件目录是只读的（包管理器管理），出问题不好修；
+ *   3. 脚本依赖 `#path-guard` 等包内 imports，模型看到的路径和实际解析
+ *      位置对不上。
+ *
+ * 所以每次 `/fancy-scan` 先把**最新版**脚本复制到
+ * `<工作区目录>/.fancy-tools/fancy-scan/`，提示词只给工作区内路径。
+ *
+ * ## 为什么单独一层 `fancy-scan/`
+ *
+ * `fancy-analyze` 的 `.fancy-tools/append-summary-chapter.js` 是 CJS。
+ * 如果在 `.fancy-tools/` 根放 `"type":"module"`，会把那个 CJS 脚本带崩。
+ * 因此 package.json 只放在 `.fancy-tools/fancy-scan/` 里，作用域仅限本目录。
+ *
+ * ## 依赖清单
+ *
+ * scripts/append-block.js:
+ *   - `./report-validate.js`
+ *   - `#path-guard` → `./lib/path-guard.js`
+ * scripts/report-validate.js:
+ *   - `../templates/report-schema.js`
+ * templates/report-schema.js:
+ *   - `#direction-labels` → `./lib/direction-labels.js`
+ *
+ * 清单是**手写**的，所以测试会按这份清单真的部署一次并启动脚本 ——
+ * 漏一个依赖，脚本会以 ERR_MODULE_NOT_FOUND 失败，测试立刻发现。
+ */
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync } from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+import { atomicWriteFile } from '#atomic-write';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+/** 工作区内的工具目录（相对工作区目录） */
+export const SCAN_TOOL_DIR = join('.fancy-tools', 'fancy-scan');
+
+/**
+ * 部署清单。
+ *
+ * `src` 相对插件包根，`dest` 相对 `.fancy-tools/fancy-scan/`。
+ * **顺序不重要**，但每个脚本的相对 import 层级必须保持不变：
+ * `scripts/append-block.js` → `./report-validate.js`。
+ */
+export const TOOL_FILES = [
+  { src: 'lib/path-guard.js', dest: join('lib', 'path-guard.js') },
+  { src: 'lib/direction-labels.js', dest: join('lib', 'direction-labels.js') },
+  { src: 'plugins/fancy-scan/templates/report-schema.js', dest: join('templates', 'report-schema.js') },
+  { src: 'plugins/fancy-scan/scripts/report-validate.js', dest: join('scripts', 'report-validate.js') },
+  { src: 'plugins/fancy-scan/scripts/append-block.js', dest: join('scripts', 'append-block.js') },
+];
+
+/**
+ * 部署目录的 package.json。
+ *
+ * `"type": "module"` 让 Node 按 ESM 解析 `.js`；
+ * `imports` 把插件包内的 `#path-guard` / `#direction-labels` 映射到
+ * 复制过来的同目录文件。**不能**把这两个映射放到 `.fancy-tools/` 根 ——
+ * 那会影响 fancy-analyze 的 CJS 脚本。
+ */
+export const TOOL_PACKAGE_JSON = {
+  name: 'fancy-tools-fancy-scan',
+  private: true,
+  type: 'module',
+  imports: {
+    '#path-guard': './lib/path-guard.js',
+    '#direction-labels': './lib/direction-labels.js',
+  },
+};
+
+/**
+ * 写一次运行的 manifest（目标/工作区目录/块 ID/数据文件/正文/指标/开关）。
+ *
+ * 提示词里的预检与写入命令只引用这个文件，模型不用抄一长串参数。
+ * 文件放在部署目录内、mode 0600；同一目标+块 ID 覆盖同一个文件。
+ *
+ * @param {string} projectRoot
+ * @param {{
+ *   topicFile: string,
+ *   blockId: string,
+ *   dataFiles: string[],
+ *   bodyFile: string,
+ *   metricLabel: string,
+ *   grouped: boolean,
+ *   multiList: boolean,
+ *   rankLabels?: string[],
+ * }} data
+ * @returns {{ok: boolean, path: string, problems: string[]}}
+ */
+export function writeScanManifest(projectRoot, data = {}) {
+  const problems = [];
+  let root = '';
+  let dir = '';
+  try {
+    root = realpathSync(resolve(projectRoot));
+    dir = join(root, SCAN_TOOL_DIR);
+  } catch (e) {
+    return { ok: false, path: '', problems: [`工作区目录或工具目录不可用：${e.message}`] };
+  }
+  try {
+    const st = lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+      problems.push(`${dir} 不是真实目录，拒绝写运行清单`);
+    }
+  } catch (e) {
+    problems.push(`工具目录不存在（请先部署）：${e.message}`);
+  }
+  for (const [key, value] of Object.entries({
+    topicFile: data.topicFile,
+    blockId: data.blockId,
+    bodyFile: data.bodyFile,
+    metricLabel: data.metricLabel,
+  })) {
+    if (!value || typeof value !== 'string') problems.push(`运行清单缺少 ${key}`);
+  }
+  if (!Array.isArray(data.dataFiles)) problems.push('运行清单缺少 dataFiles 数组');
+  if (problems.length) return { ok: false, path: '', problems };
+
+  const key = createHash('sha256')
+    .update(`${data.topicFile}|${data.blockId}`)
+    .digest('hex')
+    .slice(0, 10);
+  const file = join(dir, `run-${key}.json`);
+  const payload = {
+    version: 1,
+    project_root: root,
+    target: data.topicFile,
+    block_id: data.blockId,
+    data_files: data.dataFiles,
+    body_file: data.bodyFile,
+    metric_label: data.metricLabel,
+    grouped: !!data.grouped,
+    multi_list: !!data.multiList,
+    rank_labels: Array.isArray(data.rankLabels) ? data.rankLabels : [],
+  };
+  try {
+    atomicWriteFile(file, JSON.stringify(payload, null, 2) + '\n', { mode: 0o400 });
+  } catch (e) {
+    return { ok: false, path: '', problems: [`写运行清单失败：${e.message}`] };
+  }
+  return { ok: true, path: file, problems: [] };
+}
+
+/**
+ * 确保某个目录存在且不是符号链接。
+ *
+ * `mkdirSync(recursive)` 会**穿过**已存在的符号链接创建子目录 ——
+ * 工作区目录用户可写，`/.fancy-tools -> /tmp/attacker` 就能把整个工具目录
+ * 部署到项目外。所以逐级 lstat。
+ *
+ * @param {string} dir
+ * @param {string[]} problems
+ * @returns {boolean}
+ */
+function ensureRealDir(dir, problems) {
+  let st = null;
+  try { st = lstatSync(dir); } catch { /* 不存在 */ }
+  if (st) {
+    if (st.isSymbolicLink()) {
+      problems.push(`${dir} 是符号链接，拒绝部署工具（请换成真实目录）`);
+      return false;
+    }
+    if (!st.isDirectory()) {
+      problems.push(`${dir} 已存在但不是目录，拒绝部署工具`);
+      return false;
+    }
+    return true;
+  }
+  try {
+    mkdirSync(dir);
+    return true;
+  } catch (e) {
+    problems.push(`创建目录失败 ${dir}：${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * 把工具部署到 `<projectRoot>/.fancy-tools/fancy-scan/`。
+ *
+ * - 内容一致时**不重写**（不白改 mtime）；
+ * - 目标文件是符号链接 / 非普通文件 → 拒绝；
+ * - 部署后逐个回读比对，确保落盘内容与插件内一致；
+ * - 失败不抛异常，返回 `{ok:false, problems}`，调用方必须停止后续流程。
+ *
+ * @param {string} projectRoot 工作区目录（绝对路径）
+ * @returns {{
+ *   ok: boolean,
+ *   problems: string[],
+ *   dir: string,
+ *   appendScript: string,
+ *   written: string[],
+ *   unchanged: string[],
+ * }}
+ */
+export function deployScanTools(projectRoot) {
+  const problems = [];
+  const written = [];
+  const unchanged = [];
+  let root = '';
+
+  try {
+    if (!projectRoot || typeof projectRoot !== 'string') {
+      return { ok: false, problems: ['缺少工作区目录'], dir: '', appendScript: '', written, unchanged };
+    }
+    if (!isAbsolute(projectRoot)) {
+      return { ok: false, problems: [`工作区目录必须是绝对路径：${projectRoot}`], dir: '', appendScript: '', written, unchanged };
+    }
+    root = resolve(projectRoot);
+    if (isSensitiveProjectPath(root) || !isValidProjectPath(root)) {
+      return { ok: false, problems: [`工作区目录路径不合法或属于受保护目录：${root}`], dir: '', appendScript: '', written, unchanged };
+    }
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+      return { ok: false, problems: [`工作区目录不存在或不是目录：${root}`], dir: '', appendScript: '', written, unchanged };
+    }
+    // 符号链接的工作区目录已经由调用方 realpath；这里再解一次，保证部署
+    // 路径与后续 append-block 的 realpath containment 完全一致。
+    root = realpathSync(root);
+  } catch (e) {
+    return { ok: false, problems: [`检查工作区目录失败：${e.message}`], dir: '', appendScript: '', written, unchanged };
+  }
+
+  const toolsDir = join(root, '.fancy-tools');
+  const scanDir = join(toolsDir, 'fancy-scan');
+  const libDir = join(scanDir, 'lib');
+  const templatesDir = join(scanDir, 'templates');
+  const scriptsDir = join(scanDir, 'scripts');
+
+  for (const dir of [toolsDir, scanDir, libDir, templatesDir, scriptsDir]) {
+    if (!ensureRealDir(dir, problems)) {
+      return { ok: false, problems, dir: scanDir, appendScript: join(scriptsDir, 'append-block.js'), written, unchanged };
+    }
+  }
+
+  // package.json 先写：如果写到一半失败，至少不会留下“脚本在、包配置不在”
+  // 这种一执行就 ERR_MODULE_NOT_FOUND 的半成品。
+  const pkgPath = join(scanDir, 'package.json');
+  const pkgContent = JSON.stringify(TOOL_PACKAGE_JSON, null, 2) + '\n';
+  try {
+    writeIfChanged(pkgPath, pkgContent, problems, written, unchanged);
+  } catch (e) {
+    problems.push(`写 package.json 失败：${e.message}`);
+  }
+
+  for (const item of TOOL_FILES) {
+    const srcPath = join(PACKAGE_ROOT, item.src);
+    const destPath = join(scanDir, item.dest);
+    try {
+      if (!existsSync(srcPath)) {
+        problems.push(`插件内缺少工具源文件：${item.src}`);
+        continue;
+      }
+      const content = readFileSync(srcPath, 'utf-8');
+      writeIfChanged(destPath, content, problems, written, unchanged);
+      // 回读比对：写成功但内容不对（磁盘满、被并发改写）不能当成部署成功。
+      const back = readFileSync(destPath, 'utf-8');
+      if (back !== content) {
+        problems.push(`部署后回读不一致：${item.dest}`);
+      }
+    } catch (e) {
+      problems.push(`部署 ${item.dest} 失败：${e.message}`);
+    }
+  }
+
+  const appendScript = join(scriptsDir, 'append-block.js');
+  // 最后再确认入口真的能落到普通文件上（不是被替换成链接/目录）。
+  try {
+    const st = lstatSync(appendScript);
+    if (st.isSymbolicLink() || !st.isFile()) {
+      problems.push(`部署后的 append-block.js 不是普通文件：${appendScript}`);
+    }
+  } catch (e) {
+    problems.push(`部署后未找到 append-block.js：${e.message}`);
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    dir: scanDir,
+    appendScript,
+    written,
+    unchanged,
+  };
+}
+
+/**
+ * 内容相同就跳过；目标存在但是符号链接/目录则拒绝。
+ *
+ * @param {string} dest
+ * @param {string} content
+ * @param {string[]} problems
+ * @param {string[]} written
+ * @param {string[]} unchanged
+ */
+function writeIfChanged(dest, content, problems, written, unchanged) {
+  let st = null;
+  try { st = lstatSync(dest); } catch { /* 不存在 */ }
+  if (st) {
+    if (st.isSymbolicLink()) {
+      problems.push(`${dest} 是符号链接，拒绝覆盖`);
+      return;
+    }
+    if (!st.isFile()) {
+      problems.push(`${dest} 已存在但不是普通文件，拒绝覆盖`);
+      return;
+    }
+    try {
+      if (readFileSync(dest, 'utf-8') === content) {
+        // 老项目里的工具文件可能是 0644；内容没变也要去掉写权限，
+        // 否则“只读工具”的承诺只在下次内容变化时才生效。
+        try { chmodSync(dest, 0o444); } catch (e) {
+          problems.push(`设置只读权限失败 ${dest}：${e.message}`);
+        }
+        unchanged.push(dest);
+        return;
+      }
+    } catch (e) {
+      problems.push(`读取已有工具文件失败 ${dest}：${e.message}`);
+      return;
+    }
+  }
+  atomicWriteFile(dest, content, { mode: 0o444 });
+  written.push(dest);
+}

package/plugins/fancy-scan/wait-turn.js

@@ -0,0 +1,46 @@
+/**
+ * wait-turn.js —— 等 LLM 把这一次分析回合真正跑完
+ *
+ * ## 为什么需要
+ *
+ * `llmFollowup()` 的返回值只代表**消息已入队**，不代表模型已经处理完。
+ * DSH 的 `agent.followup()` 是异步的：命令处理器返回后，agent loop 才
+ * 开始跑下一轮。
+ *
+ * 之前 fancy-scan 在 `llmFollowup` 之后**立刻**做写入复核，于是：
+ *   - 模型还没开始写，目标文件不存在 → 报“本次分析没有正确写进文件”；
+ *   - 实际上几秒后模型就正常写进去了，用户却先看到一条红色错误；
+ *   - 第三次单榜时也是同样的误报，看起来像“卡住”。
+ *
+ * 这里复用 story-builder 已经踩过坑的 `makeWaitForTurn`：
+ * 轮询 `agent.status`，观察到 `running` 后等它回到 `idle`；
+ * 同时处理用户中断与 provider 报错。
+ *
+ * 本函数**不判断产物内容**——回合结束后仍由 `verifyBlockWritten` 复核。
+ * 等待失败（超时/无 agent）也把结果交给调用方：调用方可以先复核，
+ * 产物真的在就仍然算成功，避免“等不到状态但文件其实写了”的误报。
+ */
+import { makeWaitForTurn } from '#story-builder/writing-driver.js';
+
+/**
+ * @param {object} invocation DSH 命令 invocation
+ * @param {{timeoutMs?: number, idleGraceMs?: number, signal?: AbortSignal, pollMs?: number}} [opts]
+ * @returns {Promise<{ok: boolean, code: string, reason?: string}>}
+ */
+export async function waitForAnalysisTurn(invocation, opts = {}) {
+  const wait = makeWaitForTurn(invocation, {
+    timeoutMs: opts.timeoutMs || 30 * 60 * 1000,
+    idleGraceMs: opts.idleGraceMs || 120 * 1000,
+    pollMs: opts.pollMs || 300,
+    signal: opts.signal,
+  });
+
+  // 不传 expectedFiles：本函数只负责“等回合结束”，产物校验交给调用方。
+  // 对空 expectedFiles，makeWaitForTurn 在观察到 running→idle 后会返回
+  // NO_OUTPUT（意思是“回合结束了，但我没有可检查的预期文件”），
+  // 这里把它翻译成 TURN_ENDED。
+  const r = await wait([]);
+  if (r && r.ok) return { ok: true, code: 'TURN_ENDED', sawRunning: r.sawRunning };
+  if (r && r.code === 'NO_OUTPUT') return { ok: true, code: 'TURN_ENDED', sawRunning: true };
+  return r || { ok: false, code: 'UNKNOWN', reason: '等待 LLM 回合结束失败' };
+}

package/plugins/fancy-story-builder/db/README.md

@@ -0,0 +1,106 @@
+# fancy-story-builder × SurrealDB
+
+这个分支把 `fancy-story-builder` 的事实源从阶段 JSON 换成了嵌入式 SurrealDB。
+
+## 1. 运行形态
+
+```text
+项目根/.fancy-storydb/          ← SurrealKV 单文件库（目录）
+  └── 由 @surrealdb/node 在 DSH 进程内打开
+```
+
+- 零外部服务，不需要 `surreal start`。
+- 一个项目一个库；同一目录同时只能被一个进程打开。
+- 需要多人/多会话/MCP 时，把连接串从 `surrealkv://...` 换成 `wss://...` 即可，schema 和查询不变。
+
+依赖：
+
+```json
+{
+  "surrealdb": "2.2.2",
+  "@surrealdb/node": "3.2.0",
+  "@surrealdb/node-native": "4.0.1"
+}
+```
+
+## 2. 真源与投影
+
+```text
+SurrealDB（唯一事实源）
+    │  projectForStage()
+    ▼
+设定/**/*.json（只读投影，供现有 prompt / validator 使用）
+    │  LLM 生成
+    ▼
+importStage()（事务写入 + 约束校验）
+    │
+    └── 失败 → 回滚，删除出问题的文件，重试当前阶段
+```
+
+- `设定/` 下的阶段 JSON 只是投影，删掉后下一次命令会从数据库重建。
+- `tools export` 也是先从数据库投影，再生成 Markdown。
+- 所有 `query` / `analyze` 只读数据库，不读文件。
+
+## 3. 数据模型
+
+| 数据 | 模型 | 表 / 边 |
+|---|---|---|
+| 故事、卷、幕、章节 | 关系型 | `story` / `volume` / `act` / `chapter` |
+| 规模、配额、节奏预算 | 文档 | `scale` |
+| 世界观、故事、情绪、角色功能位、卷纲、主线、结局 | 文档 | `stage_doc` + `volume` / `act` / `line` / `line_node` / `ending` |
+| 人物、势力、地点、道具、冲突、伏笔、爽点、高潮、信息差 | 文档 | 每种实体一张 `SCHEMAFULL` 表 |
+| 人物关系、势力关系、成员、章节出场、伏笔/爽点/信息差/结局动作 | 图边 | `relation` / `faction_relation` / `membership` / `chapter_cast` / `chapter_location` / `foreshadow_action` / `payoff_action` / `info_action` / `ending_action` |
+| 角色知识变化 | 事件表 | `knowledge_event` |
+| 角色知识状态 | 派生状态表 | `knowledge_state` |
+| 情感值、字数、钩子强度 | 时序表 | `chapter_metric` |
+| 细纲 | 文档 | `outline` |
+| 正文 | 文档 | `chapter_text` |
+| 章台账 | 文档 | `ledger_entry` |
+| 阶段状态 / 校验问题 / 决策 | 文档 | `stage_state` / `validation_issue` / `decision_log` |
+
+## 4. 写时约束
+
+核心规则在 `db/schema.js`：
+
+- `SCHEMAFULL` + `ASSERT`：枚举、必填、类型。
+- `TYPE RELATION ... ENFORCED`：关系两端必须存在。
+- `DEFINE EVENT knowledge_rules`：
+  - `confirms → full`
+  - `partially_learns → partial`
+  - `forgets → unknown`
+  - `misinforms → false`
+  - `how=told` 必须有 `source_character`
+  - 信息差 / 伏笔必须存在
+  - `knowledge_state` 回放：`full` 不能再 `learns`，`unknown` 不能直接 `confirms`
+- 所有阶段写入在一个 `db.transaction()` 中；任何一条失败整批回滚。
+
+## 5. 命令
+
+```text
+/fancy-story-builder build scale|macro|cast|rhythm|outline|writing
+/fancy-story-builder tools export <stage>
+/fancy-story-builder tools query status
+/fancy-story-builder tools query foreshadow FS001
+/fancy-story-builder tools query character C001
+/fancy-story-builder tools query chapter 341-360
+/fancy-story-builder tools query knowledge C001 --chapter 341
+/fancy-story-builder tools query relations C001
+/fancy-story-builder tools query sql "SELECT ..."
+/fancy-story-builder tools analyze relation C001 C002 --to 对立 --from 341
+/fancy-story-builder tools analyze foreshadow FS001 --action 回收 --chapter 350
+```
+
+`tools query` / `tools analyze` 输出 JSON，方便 LLM 直接消费。
+
+## 6. 已知边界
+
+1. **DB 校验发生在阶段导入时**，不是 LLM 每写一条就校验。LLM 仍然先写 JSON 投影，再整阶段事务导入；失败会回滚并只重生成出问题的文件。
+2. **阶段 JSON 会留在磁盘上**，作为 prompt/validator 的投影缓存；它不是事实源。
+3. **嵌入式单进程**：同一项目不能同时被两个 DSH 会话写入。
+4. `deslop` / `maintain sync|lint|patch` 仍走旧文件管线，不在本分支范围内。
+
+## 7. 后续
+
+- 把 `prompts.js` 的 `_context` 读取改为直接查询数据库，去掉投影层。
+- 把阶段导入拆成 chunk 级事务，让 LLM 每写一个 chunk 就得到 DB 反馈。
+- 切换服务端模式，接 MCP，让外部 Agent 直接查询故事库。