@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/llm-wiki.js

@@ -0,0 +1,109 @@
+/**
+ * llm_wiki 客户端的共享工具。
+ *
+ * 两个插件接的是同一个 llm_wiki 服务：
+ *   plugins/fancy-analyze       —— 拆书（产出到 对标/）
+ *   plugins/fancy-story-builder —— 故事圣经（产出到 设定/）
+ *
+ * 它们踩过同一批坑，所以解法收敛到这里，而不是各写一份：
+ *   1. fetch 失败时 Node 只抛一句 `TypeError: fetch failed`，
+ *      真正的原因（ECONNREFUSED / ENOTFOUND / 超时）藏在 err.cause 里。
+ *      直接报 err.message，用户既不知道是服务没启动、地址写错，还是超时。
+ *   2. HTTP 4xx/5xx 与响应体里的 { ok:false, error } 是**两种**失败，
+ *      只看其中一种就会漏 —— 漏掉的后果是"失败了却报成功"。
+ *   3. 服务端可能返回非 JSON（例如网关的 HTML 错误页），
+ *      response.json() 会抛 SyntaxError，把真正的原因盖掉。
+ *
+ * @module lib/llm-wiki
+ */
+
+/**
+ * 把 fetch 抛出的异常翻译成人话。
+ *
+ * @param {Error} err - fetch 抛出的异常
+ * @param {number} [timeoutMs] - 本次请求的超时设置（用于生成超时文案）
+ * @returns {string}
+ */
+export function describeFetchError(err, timeoutMs = 30000) {
+  if (!err) return '未知错误';
+  if (err.name === 'AbortError' || err.name === 'TimeoutError') {
+    return `连接 llm_wiki 超时（${Math.round(timeoutMs / 1000)}s 没有响应）——`
+      + '请确认服务已启动，且 .fancy-deployed 里的 llm_wiki_url 指向正确地址';
+  }
+  // 多地址（IPv4/IPv6）时 undici 会抛 AggregateError
+  const cause = err.cause || {};
+  const first = (cause.errors && cause.errors.length) ? cause.errors[0] : cause;
+  const code = first.code || cause.code || '';
+  const addr = first.address || cause.address;
+  const port = first.port || cause.port;
+  const where = addr ? `${addr}:${port}` : '';
+
+  if (code === 'ECONNREFUSED') {
+    return `连不上 llm_wiki（${where} 拒绝连接）——服务很可能没启动；`
+      + '请确认服务已启动，且 .fancy-deployed 里的 llm_wiki_url 指向正确地址';
+  }
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+    return `llm_wiki 地址解析失败（${first.hostname || cause.hostname || '未知主机'}）`
+      + '——请检查 .fancy-deployed 里的 llm_wiki_url';
+  }
+  if (code === 'ECONNRESET' || code === 'EPIPE') {
+    return `llm_wiki 连接被中断（${code}）——服务可能正在重启`;
+  }
+  if (code === 'ETIMEDOUT') {
+    return `连接 llm_wiki 超时（${code}）——服务无响应`;
+  }
+  if (code) {
+    return `${err.message}（${code}${where ? ' ' + where : ''}）`;
+  }
+  return err.message || String(err);
+}
+
+/**
+ * 安全地读 JSON 响应体：不是 JSON 就返回 null，不抛异常。
+ *
+ * 服务端返回 HTML 错误页时，response.json() 会抛
+ * `SyntaxError: Unexpected token '<'`，把真正的 HTTP 状态盖掉。
+ *
+ * @param {Response} response - fetch 的 Response
+ * @returns {Promise<object|null>}
+ */
+export async function readJsonSafe(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把 llm_wiki 的响应翻译成一句人话；成功返回 null。
+ *
+ * 必须同时看 HTTP 状态码和响应体 —— 只看其中一个都会漏：
+ *   - 只看 body：llm_wiki 返回 502/401 时 body 里可能没有 error 字段
+ *   - 只看 status：llm_wiki 的错误约定是 HTTP 200 + { ok:false, error }
+ *
+ * @param {object} result - { status, data }
+ * @returns {string|null} 错误描述；null 表示成功
+ */
+export function llmWikiError(result) {
+  const status = result && result.status;
+  const data = result && result.data;
+  const apiErr = data && data.error ? String(data.error) : '';
+
+  if (status !== undefined && (status < 200 || status >= 300)) {
+    if (status === 401 || status === 403) {
+      // 401/403 几乎必然是 token 的问题，比服务端那句泛泛的
+      // error 更有指向性，所以鉴权提示在前。
+      return `鉴权失败（HTTP ${status}），请检查 .fancy-deployed 里的 llm_wiki_token`
+        + (apiErr ? `（服务端返回：${apiErr}）` : '');
+    }
+    if (!data) {
+      // 响应体不是 JSON —— 多半是网关/反代的错误页
+      return `HTTP ${status}（服务端返回的不是 JSON，可能是网关错误页）`;
+    }
+    return apiErr || `HTTP ${status}`;
+  }
+  if (apiErr) return apiErr;
+  if (data && data.ok === false) return '接口返回 ok=false';
+  return null;
+}

package/lib/material-db.js

@@ -0,0 +1,149 @@
+/**
+ * Shared material library database.
+ *
+ * The material library is workspace-level: one database per workspace
+ * (`material_library`), shared by every project. It lives on the same
+ * SurrealDB server as the registry and project databases.
+ *
+ * The schema is kept in `docs/material-library/schema.surql` so the standalone
+ * docs/import tooling and the plugin initialize exactly the same tables.
+ */
+
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { Surreal, createRemoteEngines } from 'surrealdb';
+import { MATERIAL_KINDS } from '../plugins/fancy-material/kinds.js';
+import { readSecrets, readWorkspace } from './workspace.js';
+import { rpcUrl, startServer } from './surreal-server.js';
+
+export const MATERIAL_DATABASE = 'material_library';
+export const MATERIAL_SCHEMA_VERSION = 6;
+
+const SCHEMA_FILE = fileURLToPath(new URL('../docs/material-library/schema.surql', import.meta.url));
+
+export function materialDatabaseName(workspace) {
+  return (workspace && workspace.surreal && workspace.surreal.material_database) || MATERIAL_DATABASE;
+}
+
+export function materialSchemaText() {
+  return fs.readFileSync(SCHEMA_FILE, 'utf8');
+}
+
+/**
+ * Connect as the workspace root user to the material database.
+ *
+ * `startServer` verifies the workspace credentials and may move the workspace
+ * to a free port when another SurrealDB is squatting on the configured one.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{db: Surreal, workspace: object, secrets: object, namespace: string, database: string}>}
+ */
+export async function connectMaterial(root) {
+  await startServer(root);
+  const workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  const db = new Surreal({ engines: { ...createRemoteEngines() } });
+  await db.connect(rpcUrl(workspace));
+  await db.signin({
+    username: secrets.surreal?.username || 'root',
+    password: secrets.surreal?.password,
+  });
+  const namespace = workspace.surreal?.namespace || 'fancy';
+  const database = materialDatabaseName(workspace);
+  await db.use({ namespace, database });
+  return { db, workspace, secrets, namespace, database };
+}
+
+/**
+ * Ensure the material database and its schema exist. Idempotent.
+ *
+ * Schema v6 adds `source` (builtin/other) and narrows builtin kinds to the current 54-kind catalog. Before applying the
+ * new ASSERT, rows belonging to retired kinds are removed; otherwise SurrealDB
+ * refuses to overwrite the field because existing records no longer conform.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{ok: boolean, namespace: string, database: string, schema_version: number, fields: number, indexes: string[], pruned: number}>}
+ */
+export async function ensureMaterialDatabase(root) {
+  const { db, namespace, database } = await connectMaterial(root);
+  try {
+    let pruned = 0;
+    const info = await db.query('INFO FOR DB;');
+    const dbInfo = Array.isArray(info) && info[0] ? info[0] : info;
+    const tables = (dbInfo && dbInfo.tables) || {};
+    if (tables.material) {
+      // Old databases may have rows created before these fields existed.
+      // SCHEMAFULL tables reject writes to undefined fields, so add them
+      // before backfilling.
+      await db.query('DEFINE FIELD IF NOT EXISTS created_at ON material TYPE datetime DEFAULT time::now();');
+      await db.query('DEFINE FIELD IF NOT EXISTS updated_at ON material TYPE datetime VALUE time::now();');
+      await db.query("DEFINE FIELD IF NOT EXISTS source ON material TYPE string DEFAULT 'builtin';");
+      await db.query('UPDATE material SET created_at = time::now() WHERE created_at = NONE;');
+      await db.query('UPDATE material SET updated_at = time::now() WHERE updated_at = NONE;');
+      await db.query("UPDATE material SET source = 'builtin' WHERE source = NONE OR source NOT IN ['builtin', 'other'];");
+      // Builtin rows cannot use retired kinds, so remove them before the
+      // DEFINE FIELD OVERWRITE. Rows with source='other' may use any kind and
+      // are deliberately kept.
+      const invalid = await db.query(
+        "SELECT count() AS n FROM material WHERE source = 'builtin' AND kind NOT IN $kinds GROUP ALL;",
+        { kinds: MATERIAL_KINDS },
+      );
+      const invalidRow = Array.isArray(invalid) && Array.isArray(invalid[0]) ? invalid[0][0] : null;
+      pruned = invalidRow ? Number(invalidRow.n) || 0 : 0;
+      if (pruned > 0) {
+        await db.query("DELETE material WHERE source = 'builtin' AND kind NOT IN $kinds;", { kinds: MATERIAL_KINDS });
+      }
+    }
+    await db.query(materialSchemaText());
+    const tableInfo = await db.query('INFO FOR TABLE material;');
+    const table = Array.isArray(tableInfo) && tableInfo[0] ? tableInfo[0] : {};
+    if (!table.fields || !table.fields.source || !table.fields.kind || !table.fields.name || !table.fields.tags) {
+      throw new Error('素材库 schema 初始化后仍未找到 material.kind/name/tags 字段。');
+    }
+    return {
+      ok: true,
+      namespace,
+      database,
+      schema_version: MATERIAL_SCHEMA_VERSION,
+      fields: Object.keys(table.fields || {}).length,
+      indexes: Object.keys(table.indexes || {}),
+      pruned,
+    };
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Remove the workspace material database.
+ *
+ * Connect through the registry database (never through the target database)
+ * and issue `REMOVE DATABASE IF EXISTS`.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{removed: boolean, database: string}>}
+ */
+export async function removeMaterialDatabase(root) {
+  await startServer(root);
+  const workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  const namespace = workspace.surreal?.namespace || 'fancy';
+  const database = materialDatabaseName(workspace);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(database)) {
+    throw new Error('素材库数据库名不合法：' + database);
+  }
+  const registry = workspace.surreal?.registry_database || 'fancy_registry';
+  const db = new Surreal({ engines: { ...createRemoteEngines() } });
+  try {
+    await db.connect(rpcUrl(workspace));
+    await db.signin({
+      username: secrets.surreal?.username || 'root',
+      password: secrets.surreal?.password,
+    });
+    await db.use({ namespace, database: registry });
+    await db.query('REMOVE DATABASE IF EXISTS ' + database + ';');
+    return { removed: true, database };
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}

package/lib/path-guard.js

@@ -0,0 +1,150 @@
+/**
+ * path-guard.js — 项目路径校验（bootstrap / scan / topic 共用一套）
+ *
+ * ## 为什么改成白名单（2026-10-29）
+ *
+ * 之前用的是黑名单：禁掉 `< > : " ' | ? *` 和控制字符，其余放行。
+ * 但项目路径会被**原样拼进提示词里的 shell 命令**：
+ *
+ *   cat >> "${topicFile}" <<'FANCY_SCAN_EOF'
+ *
+ * 双引号**挡不住**命令替换 —— `$()` 和反引号在双引号里照样展开。
+ * 于是 `/tmp/$(sh${IFS}/tmp/pwn.sh)` 这种目录名能通过校验：
+ * 它不含空格、不含 `..`、不含任何被禁字符。
+ *
+ * 黑名单永远列不全（要挡 `$(`、`` ` ``、`;`、`&`、`|`…），
+ * 所以改成白名单：**只放行确实需要的字符**。
+ *
+ * ## 为什么放行空格和括号
+ *
+ * 路径在提示词里是**单引号赋值 + 双引号引用**：
+ *
+ *   TOPIC_FILE='/path/带 空格/项目(测试)'
+ *   cat >> "$TOPIC_FILE" <<'FANCY_SCAN_EOF'
+ *
+ * 单引号内不做任何展开，`$TOPIC_FILE` 展开成字面路径后**不再二次展开**，
+ * 所以空格、括号、花括号在引号内都是安全的 —— 没必要为此把用户挡在门外。
+ *
+ * 真正危险的是 `$`、`` ` ``、`;`、`&`、`|`、`<`、`>` 和两种引号本身 ——
+ * 它们能让路径跳出引号，或者让 shell 在路径里执行命令。这些一律拒绝。
+ */
+
+/**
+ * 敏感系统路径前缀（黑名单）。
+ *
+ * **只是额外一层提示，不是安全边界** —— 安全边界是上面的白名单。
+ * 攻击者可以自己造一个不在名单里的敏感路径（/home/x/.ssh 等）。
+ */
+import os from 'os';
+
+export const SENSITIVE_PATH_PREFIXES = [
+  '/etc', '/proc', '/sys', '/dev', '/root', '/boot',
+  '/usr', '/bin', '/sbin', '/lib', '/lib64', '/opt', '/var', '/run', '/snap',
+  '/System', '/Library', '/private',
+  'C:/Windows', 'C:/Program Files', 'C:/Program Files (x86)',
+];
+
+/** Home-relative directories that must never become a workspace. */
+const HOME_SENSITIVE_DIRS = [
+  '.ssh', '.gnupg', '.aws', '.config', '.local', '.cache', '.kube',
+  '.docker', '.npm', '.cargo', '.rustup', '.password-store',
+  '.netrc', '.git-credentials', '.mozilla', '.thunderbird',
+];
+
+/**
+ * 明确拒绝的字符。
+ *
+ * `$` `` ` `` → 命令替换
+ * `;` `&` `|` → 命令分隔
+ * `<` `>`       → 重定向
+ * `"` `'`       → 提前闭合引号
+ * `!` `#` `?` `*` `%` `^` → 交互式历史展开 / 注释 / 通配 / 其它 shell 语义
+ * 控制字符 → 不可见、会被各种工具截断
+ */
+const FORBIDDEN_CHARS = /[$\u0060;&|<>"'!?#*%^]/;
+
+function normalizePathForGuard(p) {
+  return String(p || '').replace(/\\/g, '/');
+}
+
+/**
+ * Return the sensitive prefix that matches, or null. Prefixes are normalized
+ * so Windows-style input and the home-directory exclusions use one rule.
+ */
+function sensitivePrefixOf(p) {
+  if (!p || typeof p !== 'string') return null;
+  const normalized = normalizePathForGuard(p);
+  if (normalized === '/') return '/';
+  const home = normalizePathForGuard(os.homedir()).replace(/\/+$/, '');
+  for (const name of HOME_SENSITIVE_DIRS) {
+    const prefix = home + '/' + name;
+    if (normalized === prefix || normalized.startsWith(prefix + '/')) return prefix;
+  }
+  for (const prefix of SENSITIVE_PATH_PREFIXES) {
+    const normalizedPrefix = normalizePathForGuard(prefix);
+    if (normalized === normalizedPrefix || normalized.startsWith(normalizedPrefix + '/')) return normalizedPrefix;
+  }
+  return null;
+}
+
+/**
+ * 路径是否可用作项目根。
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isValidProjectPath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.includes('..')) return false;
+  if (FORBIDDEN_CHARS.test(p)) return false;
+  // 控制字符（含换行 / 制表符）
+  if (/[\x00-\x1f\x7f]/.test(p)) return false;
+  // 敏感系统路径
+  if (sensitivePrefixOf(p)) return false;
+  return true;
+}
+
+/**
+ * 路径是不是敏感系统目录（单独拎出来，因为错误码不一样）。
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isSensitiveProjectPath(p) {
+  return sensitivePrefixOf(p) !== null;
+}
+
+/**
+ * 路径不可用时，给用户看的原因（人话）。
+ *
+ * @param {string} p
+ * @returns {string|null} null 表示路径可用
+ */
+export function projectPathProblem(p) {
+  if (!p || typeof p !== 'string') return '路径不能为空。';
+  if (p.includes('..')) return '路径中不能包含 ".."。';
+  if (FORBIDDEN_CHARS.test(p)) {
+    return '路径中不能包含以下字符：$ ` ; & | < > " \' ! # ? * % ^'
+      + '（它们在 shell 命令里会有特殊含义，路径必须能被安全引用）';
+  }
+  if (/[\x00-\x1f\x7f]/.test(p)) return '路径中不能包含控制字符。';
+  const sensitive = sensitivePrefixOf(p);
+  if (sensitive) {
+    if (sensitive === '/') return '不能将根目录作为工作区目录。';
+    return `不能将系统受保护目录（${sensitive}）作为工作区目录。`;
+  }
+  return null;
+}
+
+/**
+ * 把路径安全地写进 shell 的单引号字符串。
+ *
+ * 单引号内不做任何展开；路径里的单引号用 `'\''` 断开再接上。
+ * 本插件的路径校验本来就禁止单引号，这里是双保险。
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function shellSingleQuote(p) {
+  return "'" + String(p == null ? '' : p).split("'").join("'\\''") + "'";
+}