@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-material/scripts/query.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Query the workspace material library before generating new cards.
+ *
+ * This script is deliberately self-contained (Node built-ins + fetch) so the
+ * plugin can copy it into <workspace>/.fancy-tools/fancy-material/ and run it
+ * from there without needing the plugin's node_modules.
+ *
+ * Examples:
+ *   node query.js --workspace /path/to/A --kind place_name --name 归墟 --json
+ *   node query.js --workspace /path/to/A --genre '仙侠·修真文明' --kind color_word --limit 20
+ *   node query.js --workspace /path/to/A --search '残影 高速' --limit 20 --json
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WORKSPACE_FILE = path.join('.fancy', 'workspace.json');
+const SECRETS_FILE = path.join('.fancy', 'secrets.json');
+
+function usage() {
+  return `素材库查询
+
+用法：
+  node query.js [--workspace <工作区>] [--kind <kind>] [--genre <题材>] [--name <精确名字>] [--search <关键词>] [--limit N] [--json]
+
+参数：
+  --workspace <目录>  工作区目录；省略时从 cwd/FANCY_HOME 向上查找
+  --kind <kind>       只查某个 kind，例如 place_name / color_word / ability_cost
+  --genre <题材>      只查某个题材；必须与素材 genres 中的值完全一致
+  --name <名字>       精确查某个名字，用于生成前检查重名
+  --search <关键词>   全文检索 name，支持空格分隔多个词
+  --limit N           最多返回 N 条，默认 50，最大 500
+  --json              一行一个 JSON 对象输出，便于模型读取
+  -h, --help          显示本帮助
+
+说明：
+  - 不传 --json 时输出人类可读列表。
+  - 生成前至少用 --name 或 --search 检查候选素材，避免重复。
+  - 脚本只读；不要修改本文件或 .fancy-tools 下的其它脚本。
+  - 导入脚本还会用 (kind, name) 唯一索引兜底。`;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    workspace: process.env.FANCY_HOME || '',
+    kind: '',
+    genre: '',
+    name: '',
+    search: '',
+    limit: 50,
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const take = () => {
+      const value = argv[i + 1];
+      if (value === undefined) throw new Error(arg + ' 需要一个值');
+      i += 1;
+      return value;
+    };
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--workspace') opts.workspace = take();
+    else if (arg.startsWith('--workspace=')) opts.workspace = arg.slice('--workspace='.length);
+    else if (arg === '--kind') opts.kind = take();
+    else if (arg.startsWith('--kind=')) opts.kind = arg.slice('--kind='.length);
+    else if (arg === '--genre') opts.genre = take();
+    else if (arg.startsWith('--genre=')) opts.genre = arg.slice('--genre='.length);
+    else if (arg === '--name') opts.name = take();
+    else if (arg.startsWith('--name=')) opts.name = arg.slice('--name='.length);
+    else if (arg === '--search') opts.search = take();
+    else if (arg.startsWith('--search=')) opts.search = arg.slice('--search='.length);
+    else if (arg === '--limit') opts.limit = Number(take());
+    else if (arg.startsWith('--limit=')) opts.limit = Number(arg.slice('--limit='.length));
+    else throw new Error('未知参数：' + arg);
+  }
+  if (!Number.isInteger(opts.limit) || opts.limit < 1) opts.limit = 50;
+  opts.limit = Math.min(opts.limit, 500);
+  return opts;
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isWorkspace(dir) {
+  return fs.existsSync(path.join(dir, WORKSPACE_FILE));
+}
+
+function findWorkspace(start) {
+  let current = path.resolve(start || process.cwd());
+  try {
+    if (fs.existsSync(current) && !fs.statSync(current).isDirectory()) current = path.dirname(current);
+  } catch { /* ignore */ }
+  for (;;) {
+    if (isWorkspace(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function resolveWorkspace(opts) {
+  if (opts.workspace) {
+    const dir = path.resolve(opts.workspace);
+    if (!isWorkspace(dir)) throw new Error('不是 fancy-webnovel 工作区：' + dir);
+    return dir;
+  }
+  const found = findWorkspace(process.cwd());
+  if (found) return found;
+  throw new Error('当前目录不是 fancy-webnovel 工作区。请用 --workspace 指定工作区目录。');
+}
+
+function sqlUrl(workspace) {
+  const raw = String(workspace.surreal?.url || 'http://127.0.0.1:8000/rpc').replace(/\/+$/, '');
+  if (/\/rpc$/.test(raw)) return raw.slice(0, -4) + '/sql';
+  if (/\/sql$/.test(raw)) return raw;
+  return raw + '/sql';
+}
+
+function q(value) {
+  return JSON.stringify(String(value));
+}
+
+function rowText(row) {
+  const tags = Array.isArray(row.tags) ? row.tags.join('、') : '';
+  const genres = Array.isArray(row.genres) ? row.genres.join('、') : '';
+  const source = row.source === 'other' ? ' | other' : '';
+  return `[${row.kind}] ${row.name}${tags ? ' | ' + tags : ''}${genres ? ' | ' + genres : ''}${source}`;
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write('❌ ' + (err && err.message ? err.message : String(err)) + '\n\n' + usage());
+    process.exitCode = 2;
+    return;
+  }
+  if (opts.help) {
+    process.stdout.write(usage() + '\n');
+    return;
+  }
+
+  let root;
+  try {
+    root = resolveWorkspace(opts);
+  } catch (err) {
+    process.stderr.write('❌ ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspace = readJson(path.join(root, WORKSPACE_FILE));
+  const secrets = readJson(path.join(root, SECRETS_FILE));
+  if (!workspace || !secrets) {
+    process.stderr.write('❌ 工作区配置或密钥文件无法读取：' + root + '\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const where = [];
+  if (opts.kind) where.push('kind = ' + q(opts.kind));
+  if (opts.genre) where.push('genres CONTAINS ' + q(opts.genre));
+  if (opts.name) where.push('name = ' + q(opts.name));
+  if (opts.search) where.push('name @1@ ' + q(opts.search));
+
+  let sql = 'SELECT id, kind, name, tags, genres, source';
+  if (opts.search) sql += ', search::score(1) AS score';
+  sql += ' FROM material';
+  if (where.length) sql += ' WHERE ' + where.join(' AND ');
+  sql += opts.search ? ' ORDER BY score DESC' : ' ORDER BY kind, name';
+  sql += ' LIMIT ' + opts.limit + ';';
+
+  const namespace = workspace.surreal?.namespace || 'fancy';
+  const database = workspace.surreal?.material_database || 'material_library';
+  const username = secrets.surreal?.username || 'root';
+  const password = secrets.surreal?.password || '';
+  if (!password) {
+    process.stderr.write('❌ 工作区缺少 SurrealDB root 密码。\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  let response;
+  try {
+    response = await fetch(sqlUrl(workspace), {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        Authorization: 'Basic ' + Buffer.from(username + ':' + password).toString('base64'),
+        'surreal-ns': namespace,
+        'surreal-db': database,
+      },
+      body: sql,
+    });
+  } catch (err) {
+    process.stderr.write('❌ 无法连接 SurrealDB：' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const text = await response.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    process.stderr.write('❌ SurrealDB 返回了非 JSON 响应：' + text.slice(0, 300) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+  if (!response.ok) {
+    process.stderr.write('❌ 查询失败：HTTP ' + response.status + ' ' + (payload?.details || payload?.description || '') + '\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const first = Array.isArray(payload) ? payload[0] : null;
+  if (!first || first.status !== 'OK') {
+    process.stderr.write('❌ 查询失败：' + JSON.stringify(first?.result ?? first ?? payload).slice(0, 500) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+  const result = Array.isArray(first.result) ? first.result : [];
+
+  if (opts.json) {
+    for (const row of result) {
+      process.stdout.write(JSON.stringify({
+        id: String(row.id || ''),
+        kind: row.kind,
+        name: row.name,
+        tags: row.tags || [],
+        genres: row.genres || [],
+        ...(row.score !== undefined ? { score: row.score } : {}),
+      }) + '\n');
+    }
+  } else {
+    process.stdout.write(`数据库：${database}\n`);
+    process.stdout.write(`结果：${result.length} 条\n`);
+    for (const row of result) process.stdout.write('- ' + rowText(row) + '\n');
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write('❌ 查询失败：' + (err && err.message ? err.message : String(err)) + '\n');
+  process.exitCode = 1;
+});

package/plugins/fancy-material/templates.js

@@ -0,0 +1,258 @@
+/**
+ * fancy-material command text for atomic material blocks.
+ */
+
+export function helpText() {
+  return `🧩 素材库 用法
+
+/fancy-material                 生成全部素材类型：54 个 kind，每个新增 50 条
+/fancy-material <素材类型>      只生成指定类型，例如：/fancy-material 地名
+/fancy-material import <文件>   导入 JSONL；导入前先校验格式
+/fancy-material init            创建/补齐素材库 schema、索引和查询/校验脚本
+/fancy-material remove          删除整个素材库（会二次确认）
+/fancy-material prompt          展示全类型提示词，不发送给 LLM
+/fancy-material export          把素材库导出为 <工作区>/素材库.md
+/fancy-material help            显示本帮助
+
+说明：
+- 素材是原子积木，每条只有 id / kind / name / tags / genres / note / source。
+- 每次运行：每个 kind 新增 50 条；每批最多 10 条，插件自动分批直到完成。
+- 未指定类型：54 个 kind 全部排队；有多份 topic_decision 文件时先弹窗选择。
+- 指定类型：只生成指定 kind，沿用最新的 topic_decision 文件。
+- 不设库内上限：运行两次就是每个 kind 累计 100 条；已有素材只用于去重。
+- 中断后重跑会开始新一轮 50 条配额，已经导入的素材不会撤销。
+- 只追加，不覆盖；同 kind 同 name 的素材会被跳过。
+- 全文索引：name（中文 ngram）；tags / genres 精确过滤。
+- 查询脚本：<工作区>/.fancy-tools/fancy-material/query.js
+- 校验脚本：<工作区>/.fancy-tools/fancy-material/validate.js`;
+}
+
+export const DEFAULT_TARGET_PER_KIND = 50;
+export const DEFAULT_BATCH_SIZE = 10;
+
+/**
+ * Replace {{KEY}} placeholders in the static prompt.
+ */
+export function renderPrompt(base, vars = {}) {
+  let text = String(base || '');
+  for (const [key, value] of Object.entries(vars)) {
+    text = text.split('{{' + key + '}}').join(value === undefined || value === null ? '' : String(value));
+  }
+  return text;
+}
+
+export function promptDisplayText(prompt) {
+  return `📚 fancy-material 提示词（未发送给 LLM）\n\n${String(prompt || '').trim()}`;
+}
+
+function compactRules(genres, queryScript, workspace) {
+  const lines = [
+    '## 本批规则（与最初提示词一致）',
+    '',
+    '- 只写本批指定的一个 kind；不要把其它 kind 混进同一个文件。',
+    '- 每条必须独立、具体、可复用；拒绝“火红、耀眼、神秘、强大”这类空泛词。',
+    '- 命名类必须有具体锚点；拒绝“复原眼、章眼、旧仓单、神秘剑、黑色长刀”这类废名。',
+    '- 字段只能是 id / kind / name / tags / genres / note / source；source 写 builtin；tags 3–8 个，genres 1–3 个。',
+  ];
+  if (Array.isArray(genres) && genres.length) {
+    lines.push('- genres 必须原样包含本次题材之一：' + genres.join('、'));
+  }
+  if (queryScript) {
+    lines.push('- 生成前查询已有素材：`node \'' + queryScript + '\' --workspace \'' + workspace
+      + '\' --kind <kind> --name \'<候选名>\' --json`');
+  }
+  lines.push('- 一行一个合法 JSON 对象；不要 Markdown 围栏、解释、前后缀。');
+  return lines;
+}
+
+export function generationPrompt({
+  base,
+  target,
+  workspace,
+  batchId,
+  attempt = 1,
+  failures = [],
+  mode,
+  genres,
+  focus,
+  targetPerKind = DEFAULT_TARGET_PER_KIND,
+  batchSize = DEFAULT_BATCH_SIZE,
+  kind,
+  kindLabel,
+  kindIndex = 1,
+  kindTotal = 1,
+  generated = 0,
+  dbExisting = 0,
+  requestCount = batchSize,
+  includeBase = true,
+  validateScript,
+  queryScript,
+  existingIndex,
+  existingTotal,
+}) {
+  const lines = [];
+  if (includeBase && base) {
+    lines.push(String(base || '').trim(), '', '---', '');
+  } else {
+    lines.push('## 继续生成（同一素材库）', '');
+    lines.push('继续遵守最初提示词中的角色、写作原则、质量红线、命名标准、描写标准、查询与追加规则。不要重新解释规则，直接写本批素材。', '');
+    lines.push(...compactRules(genres, queryScript, workspace), '');
+  }
+
+  lines.push('## 本次运行', '');
+  lines.push('- 工作区目录：' + workspace);
+  lines.push('- 目标文件（**绝对路径**）：`' + target + '`');
+  lines.push('- 批次 ID：`' + batchId + '`');
+  lines.push('- 题材模式：' + (mode === 'topic_decision' ? 'topic_decision（选题方向）' : 'all_genres（番茄全题材）'));
+  if (Array.isArray(genres) && genres.length) lines.push('- 本次题材：' + genres.join('、'));
+  if (focus && focus.query) {
+    const kinds = (focus.kinds || []).map((item) => `\`${item}\``).join('、');
+    lines.push('- 本次重点：' + focus.query + (kinds ? '（' + kinds + '）' : ''));
+  }
+
+  if (kind) {
+    const label = kindLabel ? '（' + kindLabel + '）' : '';
+    lines.push('- kind 队列：第 ' + kindIndex + ' / ' + kindTotal + ' 个');
+    lines.push('- 本批 kind：`' + kind + '`' + label);
+    lines.push('- 本次该 kind 配额：' + targetPerKind + ' 条（追加到数据库，不是库内上限）');
+    lines.push('- 本次已生成：' + generated + ' 条');
+    lines.push('- 本次还需：' + Math.max(0, targetPerKind - generated) + ' 条');
+    lines.push('- 库中已有：' + dbExisting + ' 条（只用于去重，不影响本次配额）');
+    lines.push('- 本批要写：' + requestCount + ' 条（只写 `' + kind + '`）');
+    lines.push('- 写不满时可以少写；不要用重复、换皮、空泛命名凑数，插件会继续补下一批');
+    lines.push('- 写完本批后立即结束本轮；插件会自动发下一批，不要在同一个文件里继续写其它 kind');
+  } else {
+    lines.push('- 本次目标：每个 kind ' + targetPerKind + ' 条');
+    lines.push('- 每批最多：' + batchSize + ' 条');
+  }
+  if (validateScript) lines.push('- 格式校验脚本：`' + validateScript + '`');
+  if (existingIndex) lines.push('- 已有素材索引：`' + existingIndex + '`');
+  if (Number.isFinite(existingTotal)) lines.push('- 本次题材下已有素材：' + existingTotal + ' 条');
+
+  lines.push('');
+  lines.push('写入要求：');
+  lines.push('1. 只把 JSONL 写进目标文件，一行一个对象；字段只能是 id / kind / name / tags / genres / note / source，source 固定写 builtin。');
+  lines.push('2. 不要在文件里写 Markdown 代码围栏、标题、解释、前后缀。');
+  lines.push('3. 可以直接写 JSONL，也可以使用 Python/Node 生成器；生成器放 <工作区>/.tmp/，输出必须是目标 JSONL。');
+  lines.push('4. 本批文件只放本批素材；数据库导入只追加，不会覆盖已有素材。');
+  lines.push('5. 生成前先用查询脚本/索引检查候选名字；同 kind 同 name 已存在就换一个。');
+  lines.push('6. 写完后运行 validate.js；失败就按错误修正，直到通过。');
+  lines.push('7. 不要自己运行导入命令；插件会负责最终校验、按 kind+name 去重并追加导入。');
+  if (kind) {
+    lines.push('8. 本批写完后（尽量写满 ' + requestCount + ' 条）通过校验，只回复：已写入 <目标文件路径>；然后结束本轮，等插件发下一批。');
+  } else {
+    lines.push('8. 写完后只回复：已写入 <目标文件路径>。');
+  }
+
+  if (attempt > 1) {
+    lines.push('');
+    lines.push('## 上次文件没有通过校验');
+    lines.push('');
+    const list = Array.isArray(failures) ? failures : [failures];
+    for (const failure of list) {
+      const content = String(failure || '').trim();
+      if (content) lines.push('```text', content, '```');
+    }
+    lines.push('');
+    lines.push('请只修正上面这些问题，重新写入同一个目标文件；不要把已经正确的素材删掉重写。');
+  }
+  return lines.join('\n');
+}
+
+function formatDuration(ms) {
+  const total = Math.max(0, Math.round(Number(ms) || 0) / 1000);
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = Math.round(total % 60);
+  if (hours) return hours + ' 小时 ' + minutes + ' 分';
+  if (minutes) return minutes + ' 分 ' + seconds + ' 秒';
+  return seconds + ' 秒';
+}
+
+/**
+ * Final report for a queue-driven generation run.
+ */
+export function generationRunText({
+  database,
+  targetPerKind,
+  batchSize,
+  elapsedMs,
+  queue = [],
+  completed = [],
+  incomplete = [],
+  notStarted = [],
+  importedTotal = 0,
+  batches = 0,
+  total,
+  progressFile,
+  aborted = false,
+  stopReason = '',
+}) {
+  const title = aborted
+    ? '⚠️ 素材生成已中断'
+    : ((incomplete.length || notStarted.length || stopReason) ? '⚠️ 素材生成未全部完成' : '✅ 素材生成完成');
+  const lines = [
+    title,
+    '目标：本次每个 kind 新增 ' + targetPerKind + ' 条；每批最多 ' + batchSize + ' 条',
+    '数据库：' + database,
+  ];
+  if (queue.length) lines.push('本次队列：' + queue.length + ' 个 kind');
+  if (completed.length) lines.push('本次完成：' + completed.length + ' 个 kind');
+  if (notStarted.length) lines.push('未开始：' + notStarted.length + ' 个 kind');
+  if (incomplete.length) {
+    lines.push('未完成：' + incomplete.length + ' 个 kind');
+    for (const item of incomplete.slice(0, 20)) {
+      lines.push('  - ' + item.kind + '：' + item.generated + '/' + targetPerKind
+        + (item.reason ? '（' + item.reason + '）' : ''));
+    }
+    if (incomplete.length > 20) lines.push('  - 其余 ' + (incomplete.length - 20) + ' 个省略');
+  }
+  if (!batches && !incomplete.length && !notStarted.length && !stopReason) lines.push('本次没有生成任何素材。');
+  lines.push('本次新增：' + importedTotal + ' 条');
+  if (Number.isFinite(total)) lines.push('库中素材：' + total + ' 条');
+  if (batches) lines.push('已导入批次：' + batches + ' 批');
+  if (Number.isFinite(elapsedMs) && elapsedMs > 0) lines.push('耗时：' + formatDuration(elapsedMs));
+  if (stopReason) lines.push('停止原因：' + stopReason);
+  if (progressFile) lines.push('进度文件：' + progressFile);
+  if (aborted || incomplete.length || notStarted.length || stopReason) {
+    lines.push('再次运行 /fancy-material 会开始新一轮配额；已导入素材不会撤销。');
+  }
+  return lines.join('\n');
+}
+
+export function validationFailedText({ file, detail }) {
+  return [
+    '❌ 文件没有通过格式校验，未写入数据库',
+    '文件：' + file,
+    '',
+    String(detail || '').trim(),
+    '',
+    '修正后请重新运行：/fancy-material import ' + file,
+  ].join('\n');
+}
+
+export function importResultText({ file, importedText, total, database }) {
+  const lines = [
+    '✅ 素材导入完成',
+    '文件：' + file,
+  ];
+  if (importedText) lines.push(importedText.trim());
+  if (Number.isFinite(total)) lines.push('库中素材：' + total + ' 条');
+  if (database) lines.push('数据库：' + database);
+  return lines.join('\n');
+}
+
+export function exportResultText({ file, count, kinds }) {
+  if (!count) {
+    return [
+      '✅ 素材库已导出（当前素材库为空）',
+      '文件：' + file,
+      '可运行 /fancy-material 生成素材，或运行 /fancy-material import <文件> 导入。',
+    ].join('\n');
+  }
+  return [
+    '✅ 素材库已导出',
+    '文件：' + file,
+    '素材：' + count + ' 条 · 类型：' + kinds + ' 个',
+  ].join('\n');
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Deploy the material query script into the workspace.
+ *
+ * The LLM runs query.js through bash. Keeping it inside
+ * <workspace>/.fancy-tools/fancy-material/ gives it a stable, workspace-local
+ * path (same model as fancy-scan) and avoids depending on the plugin package
+ * path being readable/executable from the sandbox.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { localIsoString } from '#workspace';
+
+export const MATERIAL_TOOL_VERSION = 4;
+export const MATERIAL_TOOLS_DIR = path.join('.fancy-tools', 'fancy-material');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SOURCE_SCRIPT = path.join(HERE, 'scripts', 'query.js');
+const SOURCE_VALIDATE = path.join(HERE, 'validate.js');
+const SOURCE_KINDS = path.join(HERE, 'kinds.js');
+
+function isRealDir(dir, label, problems) {
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) {
+      problems.push(label + ' 不能是符号链接：' + dir);
+      return false;
+    }
+    if (!st.isDirectory()) {
+      problems.push(label + ' 不是目录：' + dir);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false;
+    problems.push(label + ' 无法检查：' + (err && err.message ? err.message : String(err)));
+    return false;
+  }
+}
+
+function ensureRealDir(dir, label, problems) {
+  if (isRealDir(dir, label, problems)) return true;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    problems.push(label + ' 创建失败：' + (err && err.message ? err.message : String(err)));
+    return false;
+  }
+  return isRealDir(dir, label, problems);
+}
+
+function writeReadOnly(file, content) {
+  const tmp = file + '.' + process.pid + '.' + Date.now() + '.tmp';
+  try {
+    fs.writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o444 });
+    try { fs.chmodSync(tmp, 0o444); } catch { /* best effort */ }
+    try { fs.renameSync(tmp, file); } catch (e) {
+      if (e.code !== 'EPERM' && e.code !== 'EACCES') throw e;
+      try { fs.chmodSync(file, 0o644); } catch { /* ignore */ }
+      fs.renameSync(tmp, file);
+    }
+    try { fs.chmodSync(file, 0o444); } catch { /* best effort */ }
+  } finally {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * @param {string} root workspace directory
+ * @returns {{ok: boolean, dir: string, queryScript: string, validateScript: string, version: number, written: boolean, problems: string[]}}
+ */
+export function deployMaterialTools(root) {
+  const problems = [];
+  const workspace = path.resolve(root);
+  const fancyTools = path.join(workspace, '.fancy-tools');
+  const target = path.join(workspace, MATERIAL_TOOLS_DIR);
+
+  if (!ensureRealDir(fancyTools, '.fancy-tools', problems)) {
+    return { ok: false, dir: target, queryScript: '', validateScript: '', version: MATERIAL_TOOL_VERSION, written: false, problems };
+  }
+  if (!ensureRealDir(target, '.fancy-tools/fancy-material', problems)) {
+    return { ok: false, dir: target, queryScript: '', validateScript: '', version: MATERIAL_TOOL_VERSION, written: false, problems };
+  }
+
+  let querySource;
+  let validateSource;
+  let kindsSource;
+  try {
+    querySource = fs.readFileSync(SOURCE_SCRIPT, 'utf8');
+    validateSource = fs.readFileSync(SOURCE_VALIDATE, 'utf8');
+    kindsSource = fs.readFileSync(SOURCE_KINDS, 'utf8');
+  } catch (err) {
+    problems.push('读取素材工具脚本失败：' + (err && err.message ? err.message : String(err)));
+    return { ok: false, dir: target, queryScript: '', validateScript: '', version: MATERIAL_TOOL_VERSION, written: false, problems };
+  }
+
+  const queryScript = path.join(target, 'query.js');
+  const validateScript = path.join(target, 'validate.js');
+  try {
+    writeReadOnly(queryScript, querySource);
+    writeReadOnly(validateScript, validateSource);
+    writeReadOnly(path.join(target, 'kinds.js'), kindsSource);
+  } catch (err) {
+    problems.push('写入素材工具脚本失败：' + (err && err.message ? err.message : String(err)));
+    return { ok: false, dir: target, queryScript: '', validateScript: '', version: MATERIAL_TOOL_VERSION, written: false, problems };
+  }
+
+  const versionFile = path.join(target, 'version.json');
+  try {
+    writeReadOnly(versionFile, JSON.stringify({
+      name: 'fancy-material',
+      version: MATERIAL_TOOL_VERSION,
+      deployed_at: localIsoString(),
+      files: ['query.js', 'validate.js', 'kinds.js'],
+      read_only: true,
+    }, null, 2) + '\n');
+  } catch (err) {
+    problems.push('写入 version.json 失败：' + (err && err.message ? err.message : String(err)));
+  }
+
+  try {
+    writeReadOnly(path.join(target, 'README.txt'),
+      '本目录由 fancy-material 自动部署，供 LLM 查询已有素材和校验 JSONL。\n'
+      + 'query.js / validate.js / kinds.js 是只读工具：不要修改、删除、chmod 或另建副本。\n'
+      + '重新运行 /fancy-material 会刷新本目录。\n');
+  } catch { /* README is best effort */ }
+
+  return {
+    ok: problems.length === 0,
+    dir: target,
+    queryScript,
+    validateScript,
+    version: MATERIAL_TOOL_VERSION,
+    written: true,
+    problems,
+  };
+}