@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-material/index.js

@@ -0,0 +1,835 @@
+/**
+ * fancy-material — workspace-level material library.
+ *
+ * Commands:
+ *   /fancy-material                  send the generation prompt, wait for JSONL, validate, import
+ *   /fancy-material import <file>    validate then import an existing JSONL
+ *   /fancy-material prompt           print the prompt without sending it to the LLM
+ *   /fancy-material export           export the library to <workspace>/素材库.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { askUserQuestion, llmFollowup, notify, spawnScript } from '#infra';
+import {
+  localIsoString,
+  readSecrets,
+  readWorkspace,
+  resolvePath,
+  resolveWorkspace,
+  workspacePaths,
+} from '#workspace';
+import { connectMaterial, ensureMaterialDatabase, materialDatabaseName, removeMaterialDatabase } from '#material-db';
+import { makeWaitForTurn } from '../fancy-story-builder/writing-driver.js';
+import { exportMaterials } from './exporter.js';
+import { allKnownGenres, listTopicDecisionFiles, parseTopicDecisionGenres, resolveMaterialGenres } from './genres.js';
+import { buildExistingIndex, countByKind, countKind } from './inventory.js';
+import { KIND_LABELS, MATERIAL_KINDS, focusBlock, renderKindTable, resolveFocus } from './kinds.js';
+import { nextBatchRequest, planMaterialQueue } from './queue.js';
+import { deployMaterialTools } from './tool-deploy.js';
+import {
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_TARGET_PER_KIND,
+  exportResultText,
+  generationPrompt,
+  generationRunText,
+  helpText,
+  importResultText,
+  promptDisplayText,
+  renderPrompt,
+  validationFailedText,
+} from './templates.js';
+
+export const inject = ['commands', 'userQuestions'];
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = path.resolve(__dirname, '..', '..', 'docs', 'material-library');
+const IMPORT_SCRIPT = path.join(DOCS_DIR, 'import.js');
+const PROMPT_FILE = path.join(DOCS_DIR, 'prompt.md');
+const QUERY_SCRIPT = path.join(__dirname, 'scripts', 'query.js');
+const VALIDATE_SCRIPT = path.join(__dirname, 'validate.js');
+
+const GENERATION_ATTEMPTS = 3;
+const GENERATION_TIMEOUT_MS = 30 * 60 * 1000;
+const GENERATION_IDLE_GRACE_MS = 60 * 1000;
+const MAX_STALLED_BATCHES = 3;
+const KIND_FAILURE_STREAK_LIMIT = 3;
+const FULL_PROMPT_EVERY = 10;
+
+function cwdOf(session) {
+  return session && session.header && session.header.cwd ? session.header.cwd : null;
+}
+
+function workspaceOf(session) {
+  return resolveWorkspace({ cwd: cwdOf(session), required: true });
+}
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const value = Number.parseInt(String(raw), 10);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function generationConfig() {
+  return {
+    targetPerKind: envInt('FANCY_MATERIAL_TARGET_PER_KIND', DEFAULT_TARGET_PER_KIND),
+    batchSize: envInt('FANCY_MATERIAL_BATCH_SIZE', DEFAULT_BATCH_SIZE),
+  };
+}
+
+function abortRequested(invocation) {
+  return Boolean(invocation && invocation.signal && invocation.signal.aborted);
+}
+
+function writeProgress(file, report) {
+  try {
+    fs.writeFileSync(file, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  } catch { /* progress is best-effort */ }
+}
+
+function readPrompt() {
+  try {
+    return fs.readFileSync(PROMPT_FILE, 'utf8');
+  } catch (err) {
+    throw new Error('缺少素材提示词文件：' + PROMPT_FILE + '（' + (err && err.message ? err.message : String(err)) + '）');
+  }
+}
+
+function renderBasePrompt({
+  mode,
+  genres,
+  topicFile,
+  existingIndex,
+  existingTotal,
+  batchId,
+  workspace,
+  focus,
+  queryScript,
+  validateScript,
+  targetPerKind = DEFAULT_TARGET_PER_KIND,
+  batchSize = DEFAULT_BATCH_SIZE,
+}) {
+  return renderPrompt(readPrompt(), {
+    MATERIAL_MODE: mode,
+    GENRES: (genres || []).join('、'),
+    TOPIC_FILE: topicFile || '（无）',
+    KIND_TABLE: renderKindTable(),
+    FOCUS_BLOCK: focusBlock(focus),
+    TARGET_PER_KIND: String(targetPerKind),
+    BATCH_SIZE: String(batchSize),
+    AUDIENCE: '男频 / 女频 / 通用',
+    STYLE_RULES: '未指定（执行通用创作标准）',
+    BATCH_ID: batchId || 'material-YYYYMMDD-01',
+    SEED: batchId || 'material-v4',
+    EXISTING_INDEX: existingIndex || '（运行 /fancy-material 时由插件提供）',
+    EXISTING_TOTAL: Number.isFinite(existingTotal) ? String(existingTotal) : '（运行时读取）',
+    QUERY_SCRIPT: queryScript || QUERY_SCRIPT,
+    VALIDATE_SCRIPT: validateScript || VALIDATE_SCRIPT,
+    WORKSPACE: workspace || '（运行时提供）',
+  });
+}
+
+function stripQuotes(value) {
+  const text = String(value || '').trim();
+  if (text.length >= 2
+    && ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+/**
+ * Resolve a user-provided import path. Relative paths are resolved from the
+ * session cwd first, then from the workspace directory.
+ */
+function resolveInputFile(raw, session, root) {
+  const value = stripQuotes(raw);
+  if (!value) return { input: '', file: null };
+  const cwd = cwdOf(session) || root;
+  const first = resolvePath(value, cwd);
+  const second = resolvePath(value, root);
+  for (const candidate of [first, second]) {
+    try {
+      if (fs.statSync(candidate).isFile()) return { input: value, file: candidate };
+    } catch { /* try next */ }
+  }
+  return { input: value, file: first };
+}
+
+function scriptDetail(result) {
+  const stderr = String(result && result.stderr || '').trim();
+  const stdout = String(result && result.output || '').trim();
+  return stderr || stdout || String(result && result.error || '').trim() || ('退出码 ' + (result && result.code));
+}
+
+async function checkFile(file) {
+  return spawnScript(process.execPath, [IMPORT_SCRIPT, '--check', file], { timeout: 60000 });
+}
+
+/**
+ * Every generated card must keep at least one exact selected genre in `genres`.
+ * The model may add subgenres, but replacing the selected label with a synonym
+ * breaks genre filtering and the existing-library index.
+ */
+function genreCoverageProblem(file, genres) {
+  const selected = new Set((genres || []).filter(Boolean));
+  if (!selected.size) return '';
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return ''; }
+  const lines = text.split(/\r?\n/);
+  const bad = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    const values = Array.isArray(record.genres) ? record.genres.map(String) : [];
+    if (!values.some((genre) => selected.has(genre))) {
+      bad.push(`第 ${i + 1} 条「${record.name || record.id || '未命名'}」`);
+    }
+  }
+  if (!bad.length) return '';
+  return '以下素材的 genres 没有原样包含本次主题材：' + bad.slice(0, 8).join('、')
+    + (bad.length > 8 ? `等 ${bad.length} 条` : '')
+    + '。请把本次题材列表中的主题材名原样写进 genres，可再附加子题材。';
+}
+
+/**
+ * A batch file must contain exactly the kind requested in the prompt. The
+ * queue schedule and per-kind counts assume one kind per batch; mixed files
+ * would make later kinds silently overshoot their target.
+ */
+function kindCoverageProblem(file, kind) {
+  if (!kind) return '';
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return ''; }
+  const lines = text.split(/\r?\n/);
+  const bad = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    if (String(record.kind || '') !== kind) {
+      bad.push(`第 ${i + 1} 条「${record.name || record.id || '未命名'}」是 ${record.kind || '空 kind'}`);
+    }
+  }
+  if (!bad.length) return '';
+  return '本批只能写 `' + kind + '`，但文件里混入了其它 kind：' + bad.slice(0, 8).join('、')
+    + (bad.length > 8 ? `等 ${bad.length} 条` : '')
+    + '。请只保留本批 kind，重新写入目标文件。';
+}
+
+/**
+ * Generated batches belong to the builtin catalog. A batch may omit `source`
+ * (the database defaults it to builtin), but it must not mark entries as
+ * `other` to bypass the builtin kind list.
+ */
+function sourceCoverageProblem(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return ''; }
+  const lines = text.split(/\r?\n/);
+  const bad = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    if (record.source !== undefined && record.source !== 'builtin') {
+      bad.push(`第 ${i + 1} 条「${record.name || record.id || '未命名'}」是 ${record.source}`);
+    }
+  }
+  if (!bad.length) return '';
+  return '生成批次只能写 source=builtin，但文件里出现了其它 source：' + bad.slice(0, 8).join('、')
+    + (bad.length > 8 ? `等 ${bad.length} 条` : '')
+    + '。请把 source 改成 builtin，或省略 source（数据库默认 builtin）。';
+}
+
+function importEnv(root) {
+  const workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  return {
+    ...process.env,
+    SURREAL_ENDPOINT: workspace.surreal?.url || 'http://127.0.0.1:8000/rpc',
+    SURREAL_NAMESPACE: workspace.surreal?.namespace || 'fancy',
+    SURREAL_DATABASE: materialDatabaseName(workspace),
+    SURREAL_USER: secrets.surreal?.username || 'root',
+    SURREAL_PASS: secrets.surreal?.password || '',
+  };
+}
+
+async function importFile(root, file, options = {}) {
+  const args = [IMPORT_SCRIPT];
+  if (options.noPrefetch) args.push('--no-prefetch');
+  args.push(file);
+  const result = await spawnScript(process.execPath, args, {
+    timeout: 180000,
+    env: importEnv(root),
+  });
+  if (result.code !== 0) throw new Error(scriptDetail(result));
+  return String(result.output || '').trim();
+}
+
+async function materialTotal(root) {
+  const { db } = await connectMaterial(root);
+  try {
+    const rows = await db.query('SELECT count() FROM material GROUP ALL;');
+    const row = Array.isArray(rows) && Array.isArray(rows[0]) ? rows[0][0] : null;
+    return row ? Number(row.count) || 0 : 0;
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}
+
+function batchIdOfNow() {
+  const stamp = localIsoString().replace(/[-:T+.]/g, '').slice(0, 14);
+  return 'material-' + (stamp || String(Date.now()));
+}
+
+async function runImport(ctx, invocation, session, rawPath) {
+  const root = workspaceOf(session);
+  const { input, file } = resolveInputFile(rawPath, session, root);
+  if (!input || !file) {
+    return notify(session, 'error', '用法：/fancy-material import <文件.jsonl>');
+  }
+
+  let stat = null;
+  try { stat = fs.statSync(file); } catch { /* reported below */ }
+  if (!stat || !stat.isFile()) {
+    return notify(session, 'error', '❌ 未找到素材文件，或目标不是普通文件：' + file);
+  }
+
+  const checked = await checkFile(file);
+  if (checked.code !== 0) {
+    return notify(session, 'error', validationFailedText({ file, detail: scriptDetail(checked) }));
+  }
+
+  await ensureMaterialDatabase(root);
+  const database = materialDatabaseName(readWorkspace(root));
+  let importedText;
+  try {
+    importedText = await importFile(root, file, { noPrefetch: true });
+  } catch (err) {
+    return notify(session, 'error', '❌ 导入失败：' + (err && err.message ? err.message : String(err))
+      + '\n文件：' + file);
+  }
+  let total;
+  try { total = await materialTotal(root); } catch { total = undefined; }
+  return notify(session, 'success', importResultText({
+    file,
+    importedText,
+    total,
+    database,
+  }));
+}
+
+async function runInit(ctx, invocation, session) {
+  const root = workspaceOf(session);
+  const result = await ensureMaterialDatabase(root);
+  const tools = deployMaterialTools(root);
+  if (!tools.ok) {
+    return notify(session, 'error', [
+      '❌ 素材库 schema 已初始化，但查询脚本部署失败：',
+      ...(tools.problems || []),
+      '可重试 /fancy-material init。',
+    ].join('\n'));
+  }
+  return notify(session, 'success', [
+    '✅ 素材库初始化完成',
+    '数据库：' + result.database,
+    'schema：' + result.schema_version,
+    '字段：' + result.fields + ' 个',
+    '索引：' + (result.indexes || []).join('、'),
+    ...(result.pruned ? ['已清理旧类型素材：' + result.pruned + ' 条'] : []),
+    '查询脚本：' + tools.queryScript,
+    '校验脚本：' + tools.validateScript,
+    '',
+    '初始化只补齐 schema/索引，不会清空合法素材；已下线的 builtin kind 会被清理。',
+  ].join('\n'));
+}
+
+async function runRemove(ctx, invocation, session) {
+  const root = workspaceOf(session);
+  const asked = await askUserQuestion(ctx, invocation, [{
+    id: 'confirm_material_remove',
+    header: '删除素材库',
+    question: '确定删除整个素材库吗？\n数据库：' + materialDatabaseName(readWorkspace(root)) + '\n所有已生成素材都会丢失，且不能撤销。',
+    options: [
+      { label: '取消', description: '不删除任何素材' },
+      { label: '删除素材库', description: '删除整个 material_library 数据库' },
+    ],
+  }]);
+  if (!asked.ok) {
+    return notify(session, 'error', asked.failure?.message || '❌ 提问失败');
+  }
+  const selected = asked.answer?.answers?.[0]?.selected?.[0];
+  if (selected !== '删除素材库') return notify(session, 'success', '操作已取消。');
+  const result = await removeMaterialDatabase(root);
+  return notify(session, 'success', [
+    '✅ 已删除素材库：' + result.database,
+    '运行 /fancy-material init 可重新创建 schema 和索引。',
+  ].join('\n'));
+}
+
+async function runExport(ctx, invocation, session) {
+  const root = workspaceOf(session);
+  await ensureMaterialDatabase(root);
+  const result = await exportMaterials(root);
+  return notify(session, 'success', exportResultText(result));
+}
+
+async function runGenerate(ctx, invocation, session, focusRaw = '') {
+  const root = workspaceOf(session);
+  const focus = resolveFocus(focusRaw);
+  if (focusRaw && !focus.kinds.length) {
+    return notify(session, 'error', '❌ 未识别素材类型：' + focusRaw
+      + '\n可用示例：地名、人名、姓氏、门派、技能、超能力、武器、颜色、特效、脑洞、人物性格、关系、场景。');
+  }
+  // No-arg generation asks which topic_decision report to use when several
+  // exist. Focused runs keep the previous behavior (latest report) so a
+  // targeted one-kind request does not require an extra click.
+  const topicFiles = !focusRaw ? listTopicDecisionFiles(root) : [];
+  let selectedTopicFile = null;
+  if (topicFiles.length > 1) {
+    const options = topicFiles.map((file) => {
+      let genres = [];
+      try { genres = parseTopicDecisionGenres(fs.readFileSync(file, 'utf8')); } catch { /* preview only */ }
+      return {
+        label: path.basename(file),
+        description: genres.length ? genres.join('、') : '未解析到选题方向',
+      };
+    });
+    const asked = await askUserQuestion(ctx, invocation, [{
+      id: 'material-topic-file',
+      header: '选择选题方向',
+      question: '📊 请选择本次素材库使用的 topic_decision 文件：',
+      detail: '只会读取选中文件里的「选题方向」，不会合并多个文件。',
+      options,
+    }]);
+    if (!asked.ok) {
+      return notify(session, 'error', asked.failure?.message || '❌ 提问失败');
+    }
+    const selected = asked.answer?.answers?.[0]?.selected?.[0];
+    if (!selected) return notify(session, 'error', '已取消素材生成。');
+    selectedTopicFile = topicFiles.find((file) => path.basename(file) === selected) || null;
+    if (!selectedTopicFile) {
+      return notify(session, 'error', '❌ 未找到选中的选题文件：' + selected);
+    }
+  } else if (topicFiles.length === 1) {
+    selectedTopicFile = topicFiles[0];
+  }
+
+  const config = generationConfig();
+  await ensureMaterialDatabase(root);
+  const tools = deployMaterialTools(root);
+  if (!tools.ok) {
+    return notify(session, 'error', '❌ 部署素材查询脚本失败：\n' + (tools.problems.join('\n') || '未知错误'));
+  }
+  const database = materialDatabaseName(readWorkspace(root));
+  const plan = resolveMaterialGenres(root, { topicFile: selectedTopicFile || undefined });
+  if (selectedTopicFile && plan.mode !== 'topic_decision') {
+    return notify(session, 'error', '❌ 选中的文件没有解析到「选题方向」：' + path.basename(selectedTopicFile));
+  }
+  const counts = await countByKind(root, plan.genres);
+  const kinds = [...new Set(focus.kinds.length ? focus.kinds : MATERIAL_KINDS)];
+  const planned = planMaterialQueue({ kinds, target: config.targetPerKind });
+
+  const startedAt = Date.now();
+  const batchId = batchIdOfNow();
+  const stamp = batchId.replace(/^material-/, '');
+  const runDir = path.join(workspacePaths(root).tmp, 'fancy_material_' + stamp);
+  fs.mkdirSync(runDir, { recursive: true });
+  const progressFile = path.join(runDir, 'progress.json');
+  const batchLog = path.join(runDir, 'batches.jsonl');
+  const existing = await buildExistingIndex(root, plan.genres, stamp);
+  const base = renderBasePrompt({
+    mode: plan.mode,
+    genres: plan.genres,
+    topicFile: plan.topicFile,
+    existingIndex: existing.file,
+    existingTotal: existing.count,
+    batchId,
+    workspace: root,
+    focus,
+    queryScript: tools.queryScript,
+    validateScript: tools.validateScript,
+    targetPerKind: config.targetPerKind,
+    batchSize: config.batchSize,
+  });
+
+  const queue = planned.all.map((item) => ({
+    kind: item.kind,
+    label: KIND_LABELS[item.kind] || item.kind,
+    db_existing: Number(counts[item.kind]) || 0,
+    generated: item.generated,
+    target: item.target,
+    remaining: item.remaining,
+    status: item.status,
+    batches: 0,
+    imported: 0,
+    reason: '',
+  }));
+  const pending = queue.filter((item) => item.remaining > 0);
+
+  const report = {
+    status: 'running',
+    mode: 'per_run_quota',
+    started_at: new Date(startedAt).toISOString(),
+    updated_at: new Date(startedAt).toISOString(),
+    batch_id: batchId,
+    database,
+    workspace: root,
+    target_per_kind: config.targetPerKind,
+    batch_size: config.batchSize,
+    genre_mode: plan.mode,
+    genres: plan.genres,
+    kinds: queue,
+  };
+  const saveProgress = () => {
+    report.updated_at = new Date().toISOString();
+    writeProgress(progressFile, report);
+  };
+  saveProgress();
+
+  const waitForTurn = makeWaitForTurn(invocation, {
+    timeoutMs: GENERATION_TIMEOUT_MS,
+    idleGraceMs: GENERATION_IDLE_GRACE_MS,
+    signal: invocation.signal,
+    changed: (files, before) => {
+      try {
+        return fs.readFileSync(files[0], 'utf8') !== before;
+      } catch {
+        return true;
+      }
+    },
+  });
+
+  const completed = [];
+  const incomplete = [];
+  let importedTotal = 0;
+  let batchCount = 0;
+  let stopReason = '';
+  let aborted = false;
+  let fatal = false;
+  let kindFailureStreak = 0;
+  const maxBatchesPerKind = Math.max(1, Math.ceil(config.targetPerKind / config.batchSize) * 4);
+
+  for (let index = 0; index < pending.length; index += 1) {
+    const item = pending[index];
+    item.status = 'running';
+    let stalled = 0;
+    let lastReason = '';
+
+    while (item.generated < config.targetPerKind && item.batches < maxBatchesPerKind) {
+      if (abortRequested(invocation)) {
+        aborted = true;
+        lastReason = '用户中断';
+        break;
+      }
+      const next = nextBatchRequest({
+        generated: item.generated,
+        target: config.targetPerKind,
+        batchSize: config.batchSize,
+      });
+      if (!next.requestCount) break;
+
+      const batchNo = item.batches + 1;
+      const file = path.join(
+        runDir,
+        String(index + 1).padStart(3, '0') + '_' + item.kind + '_' + String(batchNo).padStart(2, '0') + '.jsonl',
+      );
+      const includeBase = batchNo === 1 || batchNo % FULL_PROMPT_EVERY === 1;
+      let attemptDetail = '';
+      let accepted = false;
+
+      for (let attempt = 1; attempt <= GENERATION_ATTEMPTS; attempt += 1) {
+        if (abortRequested(invocation)) {
+          aborted = true;
+          break;
+        }
+        let before = null;
+        try { before = fs.readFileSync(file, 'utf8'); } catch { /* first attempt */ }
+
+        const prompt = generationPrompt({
+          base,
+          target: file,
+          workspace: root,
+          batchId,
+          attempt,
+          failures: attemptDetail ? [attemptDetail] : [],
+          mode: plan.mode,
+          genres: plan.genres,
+          focus,
+          targetPerKind: config.targetPerKind,
+          batchSize: config.batchSize,
+          kind: item.kind,
+          kindLabel: item.label,
+          kindIndex: index + 1,
+          kindTotal: pending.length,
+          generated: item.generated,
+          dbExisting: item.db_existing,
+          requestCount: next.requestCount,
+          includeBase,
+          validateScript: tools.validateScript,
+          queryScript: tools.queryScript,
+          existingIndex: existing.file,
+          existingTotal: existing.count,
+        });
+        const sent = await llmFollowup(invocation, prompt, { appendTempRule: false });
+        if (!sent || sent.ok !== true) {
+          fatal = true;
+          stopReason = '提示词发送失败：' + ((sent && sent.error) || '未知错误');
+          break;
+        }
+
+        const waited = await waitForTurn([file], before);
+        if (!waited.ok && waited.code === 'ABORTED') {
+          aborted = true;
+          break;
+        }
+        if (!waited.ok && waited.code === 'TIMEOUT') {
+          if (fs.existsSync(file)) {
+            const checked = await checkFile(file);
+            const genreProblem = checked.code === 0 ? genreCoverageProblem(file, plan.genres) : '';
+            const kindProblem = checked.code === 0 ? kindCoverageProblem(file, item.kind) : '';
+            const sourceProblem = checked.code === 0 ? sourceCoverageProblem(file) : '';
+            if (checked.code === 0 && !genreProblem && !kindProblem && !sourceProblem) {
+              try {
+                await importFile(root, file, { noPrefetch: true });
+              } catch (err) {
+                fatal = true;
+                stopReason = '等待超时后导入数据库失败：' + (err && err.message ? err.message : String(err));
+                break;
+              }
+              const beforeCount = item.db_existing;
+              const afterCount = await countKind(root, item.kind, plan.genres);
+              const imported = Math.max(0, afterCount - beforeCount);
+              item.db_existing = afterCount;
+              item.generated += imported;
+              importedTotal += imported;
+              batchCount += 1;
+              item.batches = batchNo;
+              item.imported += imported;
+              item.remaining = Math.max(0, config.targetPerKind - item.generated);
+              try {
+                fs.appendFileSync(batchLog, JSON.stringify({
+                  at: new Date().toISOString(),
+                  kind: item.kind,
+                  batch: batchNo,
+                  file,
+                  request_count: next.requestCount,
+                  db_before: beforeCount,
+                  db_after: afterCount,
+                  imported,
+                  generated: item.generated,
+                  attempts: attempt,
+                  timeout_salvage: true,
+                }) + '\n');
+              } catch { /* best effort */ }
+              accepted = true;
+            }
+          }
+          fatal = true;
+          stopReason = '等待 LLM 写入超时' + (accepted ? '，已导入当前批次' : '');
+          break;
+        }
+        if (!waited.ok && waited.code !== 'NO_CHANGE') {
+          attemptDetail = waited.reason || waited.code || '等待 LLM 写入文件失败';
+          continue;
+        }
+        if (!waited.ok && waited.code === 'NO_CHANGE') {
+          attemptDetail = 'LLM 本轮结束但目标文件没有变化';
+          continue;
+        }
+
+        const checked = await checkFile(file);
+        if (checked.code !== 0) {
+          attemptDetail = scriptDetail(checked);
+          continue;
+        }
+        const genreProblem = genreCoverageProblem(file, plan.genres);
+        if (genreProblem) {
+          attemptDetail = genreProblem;
+          continue;
+        }
+        const kindProblem = kindCoverageProblem(file, item.kind);
+        if (kindProblem) {
+          attemptDetail = kindProblem;
+          continue;
+        }
+        const sourceProblem = sourceCoverageProblem(file);
+        if (sourceProblem) {
+          attemptDetail = sourceProblem;
+          continue;
+        }
+
+        try {
+          await importFile(root, file, { noPrefetch: true });
+        } catch (err) {
+          fatal = true;
+          stopReason = '导入数据库失败：' + (err && err.message ? err.message : String(err));
+          break;
+        }
+        const beforeCount = item.db_existing;
+        const afterCount = await countKind(root, item.kind, plan.genres);
+        const imported = Math.max(0, afterCount - beforeCount);
+        item.db_existing = afterCount;
+        item.generated += imported;
+        importedTotal += imported;
+        batchCount += 1;
+        item.batches = batchNo;
+        item.imported += imported;
+        item.remaining = Math.max(0, config.targetPerKind - item.generated);
+        try {
+          fs.appendFileSync(batchLog, JSON.stringify({
+            at: new Date().toISOString(),
+            kind: item.kind,
+            batch: batchNo,
+            file,
+            request_count: next.requestCount,
+            db_before: beforeCount,
+            db_after: afterCount,
+            imported,
+            generated: item.generated,
+            attempts: attempt,
+          }) + '\n');
+        } catch { /* best effort */ }
+        accepted = true;
+        if (imported === 0) {
+          stalled += 1;
+          attemptDetail = '本批没有新增素材（可能全是重复），必须写库中不存在的新素材';
+        } else {
+          stalled = 0;
+          attemptDetail = '';
+        }
+        break;
+      }
+
+      if (aborted || fatal) break;
+      if (!accepted) {
+        lastReason = attemptDetail || '未产出可导入的批次';
+        break;
+      }
+      saveProgress();
+      if (item.generated >= config.targetPerKind) break;
+      if (stalled >= MAX_STALLED_BATCHES) {
+        lastReason = '连续 ' + stalled + ' 批没有新增素材';
+        break;
+      }
+    }
+
+    item.remaining = Math.max(0, config.targetPerKind - item.generated);
+    if (item.generated >= config.targetPerKind) {
+      item.status = 'done';
+      completed.push({ ...item });
+      kindFailureStreak = 0;
+    } else {
+      item.status = aborted ? 'aborted' : 'incomplete';
+      item.reason = lastReason || (aborted ? '用户中断' : '未完成本次配额');
+      incomplete.push({ ...item });
+      kindFailureStreak += 1;
+    }
+    saveProgress();
+    if (aborted || fatal) break;
+    if (kindFailureStreak >= KIND_FAILURE_STREAK_LIMIT) {
+      stopReason = '连续 ' + kindFailureStreak + ' 个 kind 未完成，已停止以免继续空转';
+      break;
+    }
+  }
+
+  let total;
+  try { total = await materialTotal(root); } catch { total = undefined; }
+  report.total = total;
+  report.imported_total = importedTotal;
+  report.batches = batchCount;
+  const notStarted = queue.filter((item) => item.status === 'pending' || item.status === 'running');
+  report.not_started = notStarted.map((item) => item.kind);
+  report.status = aborted
+    ? 'aborted'
+    : ((incomplete.length || notStarted.length || fatal || stopReason) ? 'incomplete' : 'complete');
+  report.stop_reason = stopReason;
+  saveProgress();
+
+  return notify(session, (aborted || incomplete.length || notStarted.length || stopReason) ? 'error' : 'success', generationRunText({
+    database,
+    targetPerKind: config.targetPerKind,
+    batchSize: config.batchSize,
+    elapsedMs: Date.now() - startedAt,
+    queue,
+    completed,
+    incomplete,
+    notStarted,
+    importedTotal,
+    batches: batchCount,
+    total,
+    progressFile,
+    aborted,
+    stopReason,
+  }));
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-material',
+    description: '🧩 素材库 ( usage: /fancy-material [素材类型] | import <文件> | init | remove | prompt | export | help )',
+    input: { hint: '[素材类型] | import <文件> | init | remove | prompt | export' },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const raw = String(invocation.rawInput || '').trim();
+      const tokens = raw.split(/\s+/).filter(Boolean);
+      const command = (tokens[0] || '').toLowerCase();
+
+      if (command === 'help' || command === '?') return notify(session, 'success', helpText());
+
+      if (command === 'prompt') {
+        if (tokens.length > 1) return notify(session, 'error', '用法：/fancy-material prompt（不接受额外参数）');
+        try {
+          let root = null;
+          try { root = workspaceOf(session); } catch { /* prompt also works outside a workspace */ }
+          const genres = allKnownGenres(root);
+          const rendered = renderBasePrompt({
+            mode: 'all_genres',
+            genres,
+            topicFile: '（prompt 子命令固定输出全题材）',
+            existingIndex: '（运行 /fancy-material 时由插件提供）',
+            existingTotal: undefined,
+            batchId: 'material-YYYYMMDD-01',
+            workspace: root || '（运行时提供）',
+            focus: null,
+            validateScript: VALIDATE_SCRIPT,
+          });
+          return notify(session, 'success', promptDisplayText(rendered));
+        } catch (err) {
+          return notify(session, 'error', '❌ ' + (err && err.message ? err.message : String(err)));
+        }
+      }
+
+      try {
+        if (!command) return await runGenerate(ctx, invocation, session, '');
+        if (command === 'import') {
+          if (tokens.length < 2) return notify(session, 'error', '用法：/fancy-material import <文件.jsonl>');
+          return await runImport(ctx, invocation, session, tokens.slice(1).join(' '));
+        }
+        if (command === 'export') {
+          if (tokens.length > 1) return notify(session, 'error', '用法：/fancy-material export（不接受额外参数）');
+          return await runExport(ctx, invocation, session);
+        }
+        if (command === 'init') {
+          if (tokens.length > 1) return notify(session, 'error', '用法：/fancy-material init（不接受额外参数）');
+          return await runInit(ctx, invocation, session);
+        }
+        if (command === 'remove') {
+          if (tokens.length > 1) return notify(session, 'error', '用法：/fancy-material remove（不接受额外参数）');
+          return await runRemove(ctx, invocation, session);
+        }
+        // 其它参数视为素材类型重点，例如 /fancy-material 地名
+        return await runGenerate(ctx, invocation, session, raw);
+      } catch (err) {
+        return notify(session, 'error', '❌ ' + (err && err.message ? err.message : String(err)));
+      }
+    },
+  });
+}