@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/scraper-utils.js

@@ -0,0 +1,305 @@
+/**
+ * scraper-utils.js — 采集脚本公共工具
+ *
+ * 提供各平台 scraper 公用的纯函数，无外部依赖。
+ */
+
+export function getArg(args, name) {
+  const i = args.indexOf(name);
+  if (i >= 0) return i + 1 < args.length ? args[i + 1] : null;
+  const prefix = `${name}=`;
+  const inline = args.find((arg) => String(arg).startsWith(prefix));
+  // 显式空值（--name=）返回 ''，让调用方决定兜底
+  return inline === undefined ? null : String(inline).slice(prefix.length);
+}
+
+// ---------------------------------------------------------------------------
+// 扫描方式（取数路径）
+// ---------------------------------------------------------------------------
+
+/**
+ * 番茄的两种扫描方式。
+ *
+ *   api —— 书名/作者/简介取自番茄自家明文接口 /api/book/info。
+ *           实测该接口返回与榜单页完全相同的文本（明文），零识别误差，
+ *           整榜耗时约为 OCR 路径的 1/5。
+ *   ocr —— 渲染后截图 + tesseract 识别。不依赖番茄内部接口，接口失效时
+ *           仍能采到，但存在认字误差（实测简介字符错误率 8%~17%）。
+ *
+ * 这是插件层（templates/index）、编排层（run-scan）与 scraper 层之间的契约，
+ * 三处必须用同一套 id —— 不能各写各的字面量。
+ */
+export const SCAN_MODE_API = 'api';
+export const SCAN_MODE_OCR = 'ocr';
+export const SCAN_MODES = [SCAN_MODE_API, SCAN_MODE_OCR];
+export const DEFAULT_SCAN_MODE = SCAN_MODE_API;
+
+/**
+ * 把外部传入的扫描方式规整成合法值。
+ *
+ * 非法值 / 缺失一律回落到默认（api）：不能把未知值透传给 scraper ——
+ * scraper 遇到不认识的 mode 若既不截图也不取接口，会产出"只有排名没有
+ * 任何文本"的空采集，而这种失败在 receipt 上看不出来。
+ */
+export function normalizeScanMode(raw) {
+  const s = String(raw == null ? '' : raw).trim().toLowerCase();
+  return SCAN_MODES.includes(s) ? s : DEFAULT_SCAN_MODE;
+}
+
+/**
+ * Markdown 元字符的“保形替换表”。
+ *
+ * 扫榜数据来自平台页面，书名/作者/简介里可能出现 `#`、`*`、`[]`、`---`、
+ * `1.` 等写法。直接写进 Markdown 会变成标题、列表、分隔线或链接语法，
+ * 渲染后就不再是原文。统一替换成全角等价字符：看起来仍是同一个符号，
+ * 但不再触发 Markdown 语法。
+ */
+const MARKDOWN_REPLACEMENTS = {
+  '#': '＃', '*': '＊', '[': '［', ']': '］', '_': '＿',
+  '`': '｀', '>': '＞', '<': '＜', '|': '｜', '~': '～',
+  '\\': '＼', '-': '－', '+': '＋', '=': '＝', '&': '＆',
+};
+const MARKDOWN_INLINE_RE = /[#*\[\]_`<>|~\\\-+=&]/g;
+
+/**
+ * 处理单行/内联文本里的 Markdown 元字符。
+ * 保留换行；用于作者、书名、标签、分类名等单行字段。
+ */
+export function sanitizeMarkdownInline(value) {
+  return String(value == null ? '' : value)
+    .replace(MARKDOWN_INLINE_RE, (ch) => MARKDOWN_REPLACEMENTS[ch] || ch);
+}
+
+/**
+ * 处理一行正文：先拆掉行首的有序列表标记（`1. `），再处理其余元字符。
+ * 无序列表/标题/引用/分隔线的标记字符已在 sanitizeMarkdownInline 中替换。
+ */
+export function sanitizeMarkdownLine(value) {
+  const text = String(value == null ? '' : value)
+    .replace(/^[\s　]+|[\s　]+$/g, '')
+    // 1. / 1) 都算有序列表标记；即使点号后没有空格也要处理
+    .replace(/^(\d+)[.)](?=\s|$)/, (_m, num) => num + '．');
+  return sanitizeMarkdownInline(text);
+}
+
+/** 把一本书里要写进 Markdown 的单行字段做保形替换。 */
+export function sanitizeBookFields(book) {
+  if (!book || typeof book !== 'object') return book;
+  const out = { ...book };
+  for (const key of [
+    'title', 'author', 'genre', 'type', 'status', 'words', 'wordCount',
+    'group', 'category', 'subGenre', 'rankChange',
+  ]) {
+    if (typeof out[key] === 'string') out[key] = sanitizeMarkdownInline(out[key]);
+  }
+  if (Array.isArray(out.tags)) out.tags = out.tags.map(sanitizeMarkdownInline);
+  return out;
+}
+
+/**
+ * 把作品简介渲染成 markdown 行（四个平台共用一套格式）。
+ *
+ * ## 为什么抽出来（2026-10-29）
+ *
+ * 四个平台的简介此前各有各的写法：
+ *
+ *   起点  `**简介：** 首段` + 后续段落各自成段    ← 只有起点带冒号
+ *   番茄  空行 + `**简介**` + 简介全文整块
+ *   晋江  空行 + `**简介**` + 简介全文整块
+ *   七猫  空行 + `**简介**` + 分段
+ *
+ * 同一个插件产出的四份文件，字段格式却对不上：
+ * 番茄/晋江/七猫的"简介"没有冒号（不像 `**标签：**` 那样一眼看出是字段），
+ * 而且简介前多一个空行，跟前面的字段行断开了。
+ *
+ * 统一成一个无序列表项（2026-11-05 调整）：
+ *
+ *   - **简介：** 首段
+ *
+ *     第二段
+ *
+ * 规则：
+ *   - 简介本身是一个 `- ` 列表项，和作者/状态/在读等字段同一层级；
+ *   - 单换行 = 段内硬换行（行尾两个空格），四个平台统一；
+ *   - 空行 = 段落分隔，用缩进 + 空行留在同一个列表项里；
+ *   - **每段首尾的空白字符都去掉**（半角空格 / 全角空格 / 换行）。
+ *
+ * @param {string|string[]} raw - 简介正文，或已切好的段落数组
+ * @returns {string[]} markdown 行；没有简介时返回空数组
+ */
+export function renderIntroLines(raw) {
+  const source = Array.isArray(raw)
+    ? raw
+    : String(raw == null ? '' : raw)
+      .replace(/\r\n?/g, '\n')
+      // 只有空行（允许空行里夹空格/全角空格）才是段落分隔
+      .replace(/\n[ \t　]*\n/g, '\n\n')
+      .split(/\n{2,}/);
+  const paras = source
+    // 去掉每段首尾的空白字符：\s 已含全角空格 U+3000，这里再写一遍是防它被漏
+    .map(p => String(p).replace(/^[\s　]+|[\s　]+$/g, ''))
+    .filter(Boolean);
+  if (!paras.length) return [];
+
+  // 简介本身是列表项；段落之间用空行 + 两格缩进，段落内部的单换行
+  // （番茄/起点的 <br> 转出来的）用两个尾随空格做硬换行。
+  const lines = [];
+  let first = true;
+  for (const para of paras) {
+    const parts = String(para)
+      .split('\n')
+      .map((line) => sanitizeMarkdownLine(line.trim()))
+      .filter(Boolean);
+    for (let i = 0; i < parts.length; i += 1) {
+      const text = parts[i];
+      if (first) {
+        lines.push('- **简介：** ' + text);
+        first = false;
+      } else if (i === 0) {
+        lines.push('', '  ' + text);
+      } else {
+        lines[lines.length - 1] += '  ';
+        lines.push('  ' + text);
+      }
+    }
+  }
+  return lines;
+}
+
+/**
+ * 归一化作品简介文本。
+ *
+ * 起点移动端详情页的 bookInfo.desc 是"文本 + 内嵌 HTML"的混合体
+ * （实测 25 本：56% 用 <br> 分行、36% 用 \n 分段、段首带全角缩进 U+3000），
+ * 部分作品末尾带【书籍标签：…】这类标签块（实测新书榜 20 本中 1 本）。
+ * 这里统一转成纯文本：
+ *   - <br> 转成换行（行分隔）
+ *   - 段落标签转成空行（段分隔）
+ *   - 其余 HTML 标签去掉，常见实体反转义
+ *   - 去掉行首全角缩进与行尾空白，压缩多余空行
+ */
+export function normalizeBookIntro(raw) {
+  if (raw === null || raw === undefined) return '';
+  return String(raw)
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/?(p|div|li|h[1-6])\b[^>]*>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&#(\d+);/g, (_m, d) => String.fromCodePoint(Number(d)))
+    .replace(/[ \t　]+$/gm, '')
+    .replace(/^[ \t　]+/gm, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * 去掉数字里的千分位逗号。
+ *
+ * 晋江榜单页的积分是 "1,099,899,136" 这样带逗号的（10 亿级必带），
+ * 字数也可能到百万级带逗号。采集文件里存纯数字：
+ *   - 下游才好比较 / 求和 / 算份额；
+ *   - 模型照抄数字时不会把逗号一起抄走（"327,650,784" 和 "327650784"
+ *     在模型的算术里不是一回事）。
+ *
+ * 只处理"数字 + 逗号 + 数字"的形态，其余字符原样保留 ——
+ * 英文正文里的逗号（"共 3, 本"）后面跟的不是数字，不会被动到。
+ *
+ * @param {string|number|null|undefined} raw
+ * @returns {string}
+ */
+export function stripThousands(raw) {
+  if (raw === null || raw === undefined) return '';
+  return String(raw).replace(/(\d),(?=\d)/g, '$1');
+}
+
+/**
+ * 本地日期戳 YYYYMMDD（本地时区，非 UTC）。
+ *
+ * 全仓唯一的日期实现：run-scan.js 与 fancy-scan/index.js 都用它，
+ * 避免同一份 topic_decision_<date>.md 在不同时区口径下算出两个名字。
+ */
+export function localDateStamp() {
+  const d = new Date();
+  return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}`;
+}
+
+/**
+ * @typedef {Object} CliOutcome
+ * @property {number} planned      计划处理的项数
+ * @property {number} written      成功处理的项数
+ * @property {number} failed       失败的项数
+ * @property {boolean} partial     是否部分成功
+ * @property {string[]} partialReasons  失败原因列表
+ * @property {string[]} [files]    生成的文件路径
+ */
+
+/**
+ * CLI 收尾：在所有 scraper 共享的 finally 关闭 browser 资源，
+ * 然后用结构化 JSON 写出结果。保证进程不会因为孤儿 chromium 堆积。
+ *
+ * @param {Promise<number|CliOutcome>} promise - main() 返回的 promise
+ * @param {string} label - scraper 名称
+ * @param {Object} [opts]
+ * @param {() => Promise<void>} [opts.beforeExit] - 退出前的清理 hook（关 browser 等）
+ */
+export function runCli(promise, label, opts = {}) {
+  const { beforeExit } = opts;
+  Promise.resolve()
+    .then(() => promise)
+    .then(async (result) => {
+      const outcome = Number.isInteger(result)
+        ? { planned: result, written: result, failed: 0, partial: false, partialReasons: [] }
+        : result;
+
+      if (!outcome || !Number.isInteger(outcome.written)) {
+        throw new Error("no output was written");
+      }
+      if (outcome.written < 1) {
+        throw new Error("no output was written");
+      }
+
+      // 写结构化 receipt 到 stdout
+      console.log(JSON.stringify(outcome));
+
+      const failed = Number.isInteger(outcome.failed) ? outcome.failed : 0;
+      if (outcome.partial || failed > 0) {
+        console.error(
+          `${label} partial: wrote ${outcome.written}/${outcome.planned || outcome.written + failed}`
+        );
+      }
+
+      // 先清理再退出（关键：避免进程被强制 kill 导致孤儿 chromium）
+      if (typeof beforeExit === 'function') {
+        try {
+          await Promise.race([
+            beforeExit(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('cleanup timeout')), 5000)),
+          ]);
+        } catch (e) {
+          console.error(`${label} cleanup warning: ${e.message}`);
+        }
+      }
+      process.exit(outcome.partial || failed > 0 ? 2 : 0);
+    })
+    .catch(async (error) => {
+      const msg = error && error.message ? error.message : String(error);
+      // 关键：即使 msg === "no output was written" 也要写出错误，否则 OOM 时一无所知
+      console.error(`${label} failed: ${msg}`);
+      process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+      // 清理资源
+      if (typeof beforeExit === 'function') {
+        try {
+          await Promise.race([
+            beforeExit(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('cleanup timeout')), 5000)),
+          ]);
+        } catch (_) { /* 兜底 */ }
+      }
+      process.exit(1);
+    });
+}

package/lib/surreal-server.js

@@ -0,0 +1,338 @@
+/**
+ * Local SurrealDB server lifecycle for one workspace.
+ *
+ * The server is a separate process, not an embedded engine. Each project gets
+ * its own database (and database-scoped user); the server itself is shared by
+ * every project in the workspace.
+ */
+
+import fs from 'fs';
+import net from 'net';
+import path from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { Surreal, createRemoteEngines } from 'surrealdb';
+import { readSecrets, readWorkspace, updateWorkspace, workspacePaths } from './workspace.js';
+
+export const DEFAULT_SURREAL_VERSION = '2.3.10';
+
+export class SurrealServerError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'SurrealServerError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function healthUrl(workspace) {
+  const url = String(workspace.surreal?.url || 'http://127.0.0.1:8000/rpc');
+  return url.replace(/\/rpc\/?$/, '').replace(/\/$/, '') + '/health';
+}
+
+export function rpcUrl(workspace) {
+  const url = String(workspace.surreal?.url || 'http://127.0.0.1:8000/rpc');
+  return /\/rpc\/?$/.test(url) ? url.replace(/\/$/, '') : url.replace(/\/$/, '') + '/rpc';
+}
+
+export function findSurrealBinary(root) {
+  const candidates = [
+    process.env.FANCY_SURREAL_BIN,
+    root ? path.join(workspacePaths(root).fancy, 'bin', 'surreal') : null,
+    '/usr/local/bin/surreal',
+    '/usr/bin/surreal',
+    path.join(process.env.HOME || '', '.local', 'bin', 'surreal'),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+    } catch { /* ignore */ }
+  }
+  const which = spawnSync('sh', ['-lc', 'command -v surreal'], { encoding: 'utf8' });
+  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim();
+  return null;
+}
+
+export async function readHealth(workspace) {
+  const url = healthUrl(workspace);
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    const response = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!response.ok) return { ok: false, url, status: response.status };
+    return {
+      ok: true,
+      url,
+      version: response.headers.get('surreal-version') || '',
+    };
+  } catch (err) {
+    return { ok: false, url, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+export function readPid(workspace) {
+  const file = workspace.surreal?.pid_file || '';
+  if (!file) return null;
+  try {
+    const pid = Number(fs.readFileSync(file, 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function processAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function parseBind(bind) {
+  const text = String(bind || '127.0.0.1:8000');
+  const idx = text.lastIndexOf(':');
+  if (idx < 0) return { host: '127.0.0.1', port: 8000 };
+  const host = text.slice(0, idx).replace(/^\[|\]$/g, '') || '127.0.0.1';
+  const port = Number(text.slice(idx + 1)) || 8000;
+  return { host, port };
+}
+
+function urlForBind(host, port) {
+  const h = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+  return `http://${h}:${port}/rpc`;
+}
+
+async function isPortFree(port, host = '127.0.0.1') {
+  return await new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => server.close(() => resolve(true)));
+    server.listen(port, host);
+  });
+}
+
+async function findFreePort(startPort, host = '127.0.0.1') {
+  const start = Math.max(1, Number(startPort) || 8000);
+  for (let port = start; port < start + 100; port += 1) {
+    if (await isPortFree(port, host)) return port;
+  }
+  return null;
+}
+
+async function rootCredentialsValid(workspace, secrets) {
+  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.query('RETURN 1;');
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}
+
+export async function serverStatus(root) {
+  const workspace = readWorkspace(root);
+  const health = await readHealth(workspace);
+  const pid = readPid(workspace);
+  let credentialsOk = null;
+  if (health.ok) {
+    try { credentialsOk = await rootCredentialsValid(workspace, readSecrets(root)); }
+    catch { credentialsOk = false; }
+  }
+  return {
+    workspace: root,
+    endpoint: rpcUrl(workspace),
+    health,
+    running: Boolean(health.ok),
+    credentials_ok: credentialsOk,
+    pid: processAlive(pid) ? pid : null,
+    stale_pid: pid && !processAlive(pid) ? pid : null,
+    data_dir: workspace.surreal?.data_dir || workspacePaths(root).surrealData,
+    binary: findSurrealBinary(root),
+  };
+}
+
+export async function waitForServer(workspace, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  while (Date.now() < deadline) {
+    last = await readHealth(workspace);
+    if (last.ok) return last;
+    await sleep(250);
+  }
+  return last || { ok: false, error: 'timeout' };
+}
+
+export async function startServer(root, opts = {}) {
+  let workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  const username = secrets.surreal?.username || 'root';
+  const password = secrets.surreal?.password;
+  if (!password) {
+    throw new SurrealServerError('SURREAL_PASSWORD_MISSING', '工作区缺少 SurrealDB root 密码，请重新运行 /fancy-bootstrap。');
+  }
+
+  const current = await readHealth(workspace);
+  let endpointChanged = false;
+  let previousEndpoint = null;
+  let portChangedReason = null;
+
+  if (current.ok) {
+    if (await rootCredentialsValid(workspace, secrets)) {
+      return { started: false, already_running: true, ...(await serverStatus(root)) };
+    }
+    // Port 8000 may be occupied by a SurrealDB left over from a deleted or
+    // different workspace. Our new root password cannot authenticate to it;
+    // move this workspace to the next free port instead of failing.
+    previousEndpoint = rpcUrl(workspace);
+    const { host, port } = parseBind(workspace.surreal?.bind);
+    const nextPort = await findFreePort(port + 1, host);
+    if (!nextPort) {
+      throw new SurrealServerError('SURREAL_PORT_BUSY', '未找到可用的 SurrealDB 端口；请先停止占用端口 ' + port + ' 的进程。');
+    }
+    workspace = updateWorkspace(root, {
+      surreal: { bind: host + ':' + nextPort, url: urlForBind(host, nextPort) },
+    });
+    endpointChanged = true;
+    portChangedReason = 'auth_failed';
+  } else {
+    const { host, port } = parseBind(workspace.surreal?.bind);
+    if (!(await isPortFree(port, host))) {
+      const nextPort = await findFreePort(port + 1, host);
+      if (!nextPort) {
+        throw new SurrealServerError('SURREAL_PORT_BUSY', '未找到可用的 SurrealDB 端口；请先停止占用端口 ' + port + ' 的进程。');
+      }
+      workspace = updateWorkspace(root, {
+        surreal: { bind: host + ':' + nextPort, url: urlForBind(host, nextPort) },
+      });
+      endpointChanged = true;
+      portChangedReason = 'port_busy';
+    }
+  }
+
+  const binary = opts.binary || findSurrealBinary(root);
+  if (!binary) {
+    throw new SurrealServerError(
+      'SURREAL_BINARY_MISSING',
+      '未找到 surreal 可执行文件。请先运行 /fancy-db install，或将 SurrealDB 加入 PATH。',
+    );
+  }
+
+  const paths = workspacePaths(root);
+  fs.mkdirSync(paths.surrealData, { recursive: true });
+  fs.mkdirSync(path.dirname(paths.surrealLog), { recursive: true });
+  try { fs.unlinkSync(paths.surrealPid); } catch { /* ignore */ }
+
+  const bind = workspace.surreal?.bind || '127.0.0.1:8000';
+  // Keep the listen address visible in `ps`; keep the password in the
+  // environment so it never appears in the process command line.
+  const args = ['start', '--bind', bind, 'rocksdb:' + paths.surrealData];
+  const log = fs.openSync(paths.surrealLog, 'a');
+  const child = spawn(binary, args, {
+    detached: true,
+    stdio: ['ignore', log, log],
+    env: {
+      ...process.env,
+      SURREAL_USER: username,
+      SURREAL_PASS: password,
+      SURREAL_NO_BANNER: 'true',
+    },
+  });
+  child.unref();
+  fs.writeFileSync(paths.surrealPid, String(child.pid) + '\n', { encoding: 'utf8', mode: 0o600 });
+
+  const health = await waitForServer(workspace, Number(opts.timeoutMs) || 15000);
+  if (!health.ok) {
+    try { process.kill(child.pid, 'SIGTERM'); } catch { /* ignore */ }
+    throw new SurrealServerError(
+      'SURREAL_START_FAILED',
+      'SurrealDB 未在预期时间内启动。请查看日志：' + paths.surrealLog,
+      health,
+    );
+  }
+  return {
+    started: true,
+    already_running: false,
+    pid: child.pid,
+    endpoint_changed: endpointChanged,
+    previous_endpoint: previousEndpoint,
+    port_changed_reason: portChangedReason,
+    ...(await serverStatus(root)),
+  };
+}
+
+export async function stopServer(root, opts = {}) {
+  const workspace = readWorkspace(root);
+  const status = await serverStatus(root);
+  if (!status.running && !status.pid) {
+    try { fs.unlinkSync(workspacePaths(root).surrealPid); } catch { /* ignore */ }
+    return { stopped: false, already_stopped: true };
+  }
+  const pid = status.pid || readPid(workspace);
+  if (pid) {
+    try { process.kill(pid, 'SIGTERM'); } catch { /* ignore */ }
+    const deadline = Date.now() + (Number(opts.timeoutMs) || 10000);
+    while (Date.now() < deadline && processAlive(pid)) await sleep(150);
+    if (processAlive(pid)) {
+      try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ }
+    }
+  }
+  try { fs.unlinkSync(workspacePaths(root).surrealPid); } catch { /* ignore */ }
+  return { stopped: true, already_stopped: false, pid };
+}
+
+async function download(url, file) {
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok) throw new SurrealServerError('SURREAL_DOWNLOAD', '下载 SurrealDB 失败：HTTP ' + response.status, { url });
+  const body = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(file, body, { mode: 0o600 });
+}
+
+/**
+ * Install a standalone SurrealDB binary into <workspace>/.fancy/bin.
+ * Uses the official GitHub release tarball for the current platform.
+ */
+export async function installSurreal(root, opts = {}) {
+  const version = opts.version || DEFAULT_SURREAL_VERSION;
+  const paths = workspacePaths(root);
+  const binDir = path.join(paths.fancy, 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  const target = path.join(binDir, 'surreal');
+  if (fs.existsSync(target) && !opts.force) {
+    return { installed: false, already_installed: true, path: target, version: spawnSync(target, ['version'], { encoding: 'utf8' }).stdout.trim() };
+  }
+  const platform = process.platform;
+  const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : process.arch;
+  if (platform !== 'linux' && platform !== 'darwin') {
+    throw new SurrealServerError('SURREAL_PLATFORM', '当前平台不支持自动安装 SurrealDB：' + platform);
+  }
+  const ext = platform === 'linux' ? 'linux' : 'darwin';
+  const archive = `surreal-v${version}.${ext}-${arch}.tgz`;
+  const url = `https://github.com/surrealdb/surrealdb/releases/download/v${version}/${archive}`;
+  const tmp = path.join(binDir, `.download-${process.pid}.tgz`);
+  await download(url, tmp);
+  const extractDir = path.join(binDir, `.extract-${process.pid}`);
+  fs.mkdirSync(extractDir, { recursive: true });
+  const tar = spawnSync('tar', ['-xzf', tmp, '-C', extractDir], { encoding: 'utf8' });
+  if (tar.status !== 0) {
+    throw new SurrealServerError('SURREAL_EXTRACT', '解压 SurrealDB 压缩包失败：' + (tar.stderr || tar.stdout), { url });
+  }
+  const extracted = path.join(extractDir, 'surreal');
+  if (!fs.existsSync(extracted)) {
+    throw new SurrealServerError('SURREAL_EXTRACT', '压缩包中未找到 surreal 可执行文件。', { url });
+  }
+  fs.copyFileSync(extracted, target);
+  fs.chmodSync(target, 0o755);
+  try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+  try { fs.rmSync(extractDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  const versionOut = spawnSync(target, ['version'], { encoding: 'utf8' }).stdout.trim();
+  return { installed: true, already_installed: false, path: target, version: versionOut };
+}