@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-bootstrap/index.js

@@ -1,168 +1,313 @@
 /**
- * fancy-bootstrap plugin entry
+ * fancy-bootstrap — first-time workspace initialization.
+ *
+ * A workspace is a directory the user chooses once. It owns the shared
+ * scan/analyze artifacts, the SurrealDB server data, and every project
+ * directory under <workspace>/projects/<uuid>.
  */
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { askUserQuestion, notify, spawnScript } from '#infra';
-import { readDeployedState, deployedStateProblemText } from '#deployed-state';
-import { bootstrap } from './templates.js';
+
+import { existsSync, realpathSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { basename, dirname, isAbsolute, join, resolve } from 'path';
+import { askUserQuestion, notify } from '#infra';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+import { readDeployedState, deployedStateProblemText, DEPLOYED_STATUS } from '#deployed-state';
+import { initWorkspaceDatabase } from '#db-init';
+import { findSurrealBinary, installSurreal, serverStatus } from '#surreal-server';
+import {
+  findWorkspace,
+  isWorkspace,
+  formatLocalTime,
+  listGlobalWorkspaces,
+  readWorkspace,
+  resolvePath,
+  resolveWorkspace,
+  workspacePaths,
+} from '#workspace';
 
 export const inject = ['commands', 'userQuestions'];
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SCRIPTS_DIR = join(__dirname, 'scripts');
-
-// ---------------------------------------------------------------------------
-// 路径工具
-// ---------------------------------------------------------------------------
-
-// 敏感系统路径前缀（黑名单）：防止用户输入这些路径作为项目根
-const SENSITIVE_PATH_PREFIXES = [
-  '/etc', '/proc', '/sys', '/dev',
-  '/root/.ssh', '/root/.gnupg', '/root/.aws', '/root/.config',
-  '/var/log', '/var/lib', '/boot',
-  'C:\\Windows', 'C:\\Program Files',
-];
-
-function isValidPath(p) {
-  if (!p || typeof p !== 'string') return false;
-  if (p.includes('..')) return false;
-  if (/[<>:"'|?*[\x00-\x1f]/.test(p)) return false;
-  if (/\s/.test(p)) return false;
-  // 拒绝以敏感路径前缀开头的绝对路径
-  const normalized = p.replace(/\\/g, '/');
-  for (const prefix of SENSITIVE_PATH_PREFIXES) {
-    if (normalized === prefix || normalized.startsWith(prefix + '/')) return false;
+function helpText() {
+  return `📁 工作区初始化 用法
+
+/fancy-bootstrap              交互式指定工作区目录进行初始化
+/fancy-bootstrap <目录>       在指定目录初始化工作区
+/fancy-bootstrap status       查看当前工作区
+/fancy-bootstrap list         列出本机记录的所有工作区
+/fancy-bootstrap help         显示本帮助
+
+工作区结构：
+  <工作区>/projects/<UUID>/     每个小说项目一个目录
+  <工作区>/扫榜结果/             多个项目共享的扫榜产物
+  <工作区>/参考资料/             待拆解的对标小说（fancy-analyze 读取）
+  <工作区>/对标/                 多个项目共享的对标分析
+  <工作区>/.fancy/               SurrealDB 数据、密钥、工作区配置
+
+初始化会创建 SurrealDB 数据目录、项目注册表、数据库校验函数和素材库 schema。
+启动时按 FANCY_SURREAL_BIN → <工作区>/.fancy/bin/surreal → PATH 的顺序查找 surreal；
+都没有时才尝试下载官方二进制到 <工作区>/.fancy/bin/。`;
+}
+
+function normalizePath(raw, session) {
+  let value = String(raw || '').trim();
+  if (!value) return null;
+  if (value === '~' || value.startsWith('~/')) value = join(homedir(), value.slice(1));
+  if (!isAbsolute(value)) {
+    const base = session?.header?.cwd ? resolve(session.header.cwd) : null;
+    if (!base) return null;
+    value = resolve(base, value);
+  }
+  return value;
+}
+
+/**
+ * Resolve symlinks for an existing path, or for a not-yet-created path use the
+ * deepest existing ancestor and append the missing segments. This lets the
+ * sensitive-path check see through `/tmp/link -> /etc` even when the workspace
+ * directory itself does not exist yet.
+ */
+function realTargetPath(target) {
+  let current = resolve(target);
+  const missing = [];
+  for (;;) {
+    try {
+      if (existsSync(current)) {
+        const real = realpathSync(current);
+        return missing.length ? join(real, ...missing) : real;
+      }
+    } catch {
+      return resolve(target);
+    }
+    const parent = dirname(current);
+    if (parent === current) return resolve(target);
+    missing.unshift(basename(current));
+    current = parent;
   }
-  return true;
 }
 
-// ---------------------------------------------------------------------------
-// 注册
-// ---------------------------------------------------------------------------
+function formatWorkspace(root) {
+  const workspace = readWorkspace(root);
+  const paths = workspacePaths(root);
+  return [
+    '📁 工作区：' + root,
+    '工作区 ID：' + workspace.workspace_id,
+    '创建时间：' + formatLocalTime(workspace.created_at),
+    '更新时间：' + formatLocalTime(workspace.updated_at),
+    '当前项目：' + (workspace.active_project || '未选择（可用 /fancy-project use <名字|UUID> 指定）'),
+    '项目目录：' + paths.projects,
+    '扫榜结果：' + paths.scan,
+    '对标分析：' + paths.analyze,
+    '参考资料：' + paths.referenceSources,
+    'SurrealDB：' + (workspace.surreal?.url || '—'),
+    '素材库：' + (workspace.surreal?.material_database || 'material_library'),
+    '数据库目录：' + paths.surrealData,
+  ].join('\n');
+}
 
 export async function apply(ctx) {
   ctx.commands.register({
     name: 'fancy-bootstrap',
-    description: '📁 初始化项目根 ( usage: /fancy-bootstrap [项目根] )',
-    input: {
-      hint: '[项目根]',
-    },
+    description: '📁 初始化 fancy-webnovel 工作区 ( usage: /fancy-bootstrap [目录] | status | list | help )',
+    input: { hint: '[目录] | status | list' },
     handler: async (invocation) => {
       const session = invocation.agent.session;
-      const rawInput = invocation.rawInput ? invocation.rawInput.trim() : '';
-      const { signal } = invocation;
+      const rawInput = String(invocation.rawInput || '').trim();
 
-      let projectRoot = rawInput;
+      if (rawInput.toLowerCase() === 'help') return notify(session, 'success', helpText());
 
-      // 无参数 → 弹窗
-      if (!projectRoot) {
-        // Check if signal is already aborted before asking
-        if (signal?.aborted) {
-          return notify(session, 'error', bootstrap.notify({ type: 'cancelled' }));
+      if (rawInput.toLowerCase() === 'status') {
+        try {
+          const root = resolveWorkspace({ cwd: session?.header?.cwd, required: true });
+          return notify(session, 'success', formatWorkspace(root) + '\n\n' + JSON.stringify(await serverStatus(root), null, 2));
+        } catch {
+          return notify(session, 'error', '❌ 当前目录不是 fancy-webnovel 工作区，无法查看状态。请运行 /fancy-bootstrap 初始化工作区，或者切换到其他工作区。');
         }
-        // askUserQuestion 统一兜住 DSH 的错误码，永不抛异常
-        const asked = await askUserQuestion(ctx, invocation, [bootstrap.askPath()]);
-        if (!asked.ok) {
-          return notify(session, 'error', bootstrap.notify({
-            type: asked.failure.type,
-            err: asked.failure.message
-          }));
+      }
+
+      if (rawInput.toLowerCase() === 'list') {
+        let entries = listGlobalWorkspaces();
+        const current = findWorkspace(session?.header?.cwd);
+        if (!entries.length && !current) {
+          return notify(session, 'success', '🌐 本机未发现 fancy-webnovel 工作区。\n运行 /fancy-bootstrap <目录> 创建第一个工作区。');
         }
-        const result = asked.answer;
-        // Handle case where user skipped or X'd the question
-        if (!result?.answers?.[0]) {
-          return notify(session, 'error', bootstrap.notify({ type: 'cancelled' }));
+        let currentEntry = current ? entries.find((entry) => entry.workspace === current) : null;
+        if (current && !currentEntry) {
+          // A lightweight/legacy root may be usable without appearing in the
+          // registry yet. Keep it visible and put it first.
+          currentEntry = {
+            workspace: current,
+            workspace_id: '',
+            name: basename(current),
+            exists: isWorkspace(current),
+            last_used: '',
+          };
+          entries = [currentEntry, ...entries];
         }
-        projectRoot = result.answers[0]?.custom?.trim() || '';
+        const ordered = currentEntry
+          ? [currentEntry, ...entries.filter((entry) => entry !== currentEntry)]
+          : entries;
+
+        const details = await Promise.all(ordered.map(async (entry) => {
+          let surreal = null;
+          try { surreal = readWorkspace(entry.workspace).surreal || null; } catch { /* missing/lightweight */ }
+          let status = null;
+          if (entry.exists && surreal) {
+            try { status = await serverStatus(entry.workspace); } catch { /* ignore probe errors */ }
+          }
+          return { entry, surreal, status };
+        }));
+
+        const lines = ['🌐 本机工作区（' + ordered.length + '）', ''];
+        for (const { entry, surreal, status } of details) {
+          lines.push((entry.workspace === current ? '* ' : '- ') + entry.name);
+          lines.push('  路径：' + entry.workspace);
+          lines.push('  ID：' + (entry.workspace_id || '—') + (entry.exists ? '' : '　⚠️ 目录不存在/已删除'));
+          if (surreal) {
+            lines.push('  SurrealDB：' + (surreal.url || '—'));
+            if (surreal.namespace || surreal.registry_database) {
+              lines.push('  命名空间：' + (surreal.namespace || '—') + '　注册表：' + (surreal.registry_database || '—'));
+            }
+            if (surreal.data_dir) lines.push('  数据目录：' + surreal.data_dir);
+            if (status) {
+              if (status.running) {
+                const version = status.health?.version ? ' · ' + status.health.version : '';
+                const credentials = status.credentials_ok === false ? '（凭据不匹配）' : '';
+                lines.push('  服务：运行中' + version + credentials);
+              } else {
+                lines.push('  服务：未运行');
+              }
+            }
+          } else {
+            lines.push('  SurrealDB：—');
+          }
+          if (entry.last_used) lines.push('  最近使用：' + formatLocalTime(entry.last_used));
+          lines.push('');
+        }
+        lines.push('* 表示当前 cwd 所在工作区。');
+        return notify(session, 'success', lines.join('\n'));
       }
 
-      if (!projectRoot) {
-        return notify(session, 'error', bootstrap.notify({ type: 'no_path' }));
+      // Only auto-report a workspace when the caller is actually inside one,
+      // or when FANCY_HOME explicitly points at one. The global pointer is a
+      // convenience for other commands, not a reason to hijack bootstrap from
+      // an unrelated directory.
+      const cwd = session?.header?.cwd;
+      let insideWorkspace = null;
+      if (process.env.FANCY_HOME) {
+        const envRoot = resolvePath(process.env.FANCY_HOME, cwd || process.cwd());
+        if (isWorkspace(envRoot)) insideWorkspace = envRoot;
+      }
+      if (!insideWorkspace && cwd) insideWorkspace = findWorkspace(cwd);
+      if (insideWorkspace && !rawInput) {
+        return notify(session, 'success', 'ℹ️ 当前目录已位于工作区：\n\n' + formatWorkspace(insideWorkspace));
       }
 
-      if (projectRoot === '.') {
-        // 不能回退到 process.cwd()：那是宿主进程的工作目录，不是用户项目目录。
-        // 宿主若恰好在某个含 .fancy-deployed 的目录里启动，会对错误的项目初始化。
-        projectRoot = session.header?.cwd ?? null;
-        if (!projectRoot) {
-          return notify(session, 'error', bootstrap.notify({
-            type: 'no_project_root',
-            err: '无法确定项目目录（会话未提供 cwd）。请在项目目录下运行该命令。'
-          }));
+      let target = rawInput ? normalizePath(rawInput, session) : null;
+      if (!rawInput) {
+        if (invocation.signal?.aborted) return notify(session, 'error', '🚫 操作已取消。');
+
+        const asked = await askUserQuestion(ctx, invocation, [{
+          id: 'workspace_path',
+          header: '选择工作区',
+          question: '选择或输入工作区目录',
+          options: (() => {
+            const cwd = session?.header?.cwd ? resolve(session.header.cwd) : null;
+            const items = [];
+            if (cwd) items.push({ label: cwd, description: '当前目录' });
+            for (const item of [
+              { label: join(homedir(), 'fancy-webnovel'), description: '用户主目录' },
+              { label: join(homedir(), 'Documents', 'fancy-webnovel'), description: '文档目录' },
+            ]) {
+              if (!items.some((entry) => entry.label === item.label)) items.push(item);
+            }
+            return items;
+          })(),
+        }]);
+        if (!asked.ok) {
+          if (asked.failure?.type === 'cancelled') return notify(session, 'error', '🚫 操作已取消。');
+          return notify(session, 'error', asked.failure?.message || '❌ 提问失败');
         }
-        // Show notification but do NOT return - continue to confirmation step
-        // （确认框里会带上完整路径，用户能看到）
-        notify(session, 'success', bootstrap.notify({ type: 'using_cwd', projectRoot }));
+        const answer = asked.answer?.answers?.[0];
+        target = normalizePath(answer?.custom || answer?.selected?.[0] || '', session);
       }
 
-      if (!isValidPath(projectRoot)) {
-        return notify(session, 'error', bootstrap.notify({ type: 'invalid_path' }));
+      if (!target) return notify(session, 'error', '⚠️ 未提供工作区路径，操作已取消。');
+      const inputTarget = target;
+      const targetReal = realTargetPath(target);
+      if (isSensitiveProjectPath(targetReal) || !isValidProjectPath(targetReal)) {
+        return notify(session, 'error', '❌ 路径不合法或属于受保护目录：' + inputTarget
+          + (targetReal !== inputTarget ? '\n实际路径：' + targetReal : ''));
       }
+      target = targetReal;
+      try {
+        if (!statSync(target).isDirectory()) {
+          return notify(session, 'error', '❌ 工作区路径不是目录：' + target);
+        }
+      } catch { /* path does not exist yet; init will create it */ }
 
-      // 文件**存在**不等于"已初始化"。
-      // 之前只看存在性，于是文件损坏时也报"该目录已初始化"并拒绝执行 ——
-      // 而别处（fancy-topic / fancy-scan）会告诉你"重新运行 /fancy-bootstrap 初始化"，
-      // 两条指引互相打架，用户被卡在死循环里出不来。
-      const existingState = readDeployedState(projectRoot);
-      if (existingState.status === 'ok') {
-        return notify(session, 'error', bootstrap.notify({ type: 'already_initialized' }));
+      // A directory that already has .fancy-deployed is already initialized
+      // (full workspace or lightweight scan/topic root). A corrupt marker is
+      // reported explicitly instead of being overwritten or mistaken for a new
+      // workspace.
+      const deployed = readDeployedState(target);
+      if (deployed.status === DEPLOYED_STATUS.OK) {
+        return notify(session, 'error', '⚠️ 该目录已完成初始化，无需重复执行（.fancy-deployed 已存在）：' + target);
       }
-      if (existingState.status !== 'missing') {
-        // 存在但坏了 / phase 不认识 → 明确说清并给出修复办法，
-        // 而不是笼统地说"已初始化"（那会让用户以为一切正常）。
-        return notify(session, 'error',
-          deployedStateProblemText(existingState, { projectRoot })
-          || bootstrap.notify({ type: 'already_initialized' }));
+      if (deployed.status !== DEPLOYED_STATUS.MISSING) {
+        return notify(session, 'error', deployedStateProblemText(deployed, { projectRoot: target })
+          || '❌ 状态文件 .fancy-deployed 无法读取：' + target);
       }
 
-      // Check if signal is already aborted before asking confirm
-      if (signal?.aborted) {
-        return notify(session, 'error', bootstrap.notify({ type: 'cancelled' }));
-      }
-      // 注意：不要传 hideCustomInput —— DSH 的 AskUserQuestionItem 没有这个字段
-      // （合法字段只有 id / question / detail / header / options / multiSelect / intent），
-      // 传了会被运行时静默忽略，"只让点选项"的意图根本不生效。
-      const asked = await askUserQuestion(ctx, invocation, [{
-        id: 'confirm',
-        question: bootstrap.notify({ type: 'confirm', projectRoot }),
-        options: bootstrap.confirmOptions(),
+      if (invocation.signal?.aborted) return notify(session, 'error', '🚫 操作已取消。');
+      const confirmed = await askUserQuestion(ctx, invocation, [{
+        id: 'confirm_workspace',
+        header: '确认工作区',
+        question: '确认使用 ' + target + ' 作为 fancy-webnovel 工作区?',
+        options: [
+          { label: '确认创建', description: '创建/初始化工作区、数据库和校验函数' },
+          { label: '取消', description: '不做任何修改' },
+        ],
       }]);
-      if (!asked.ok) {
-        return notify(session, 'error', bootstrap.notify({
-          type: asked.failure.type,
-          err: asked.failure.message
-        }));
-      }
-      const confirm = asked.answer;
-      // Handle case where user skipped or X'd the question
-      if (!confirm?.answers?.[0]) {
-        return notify(session, 'error', bootstrap.notify({ type: 'cancelled' }));
-      }
-      const ans = confirm.answers[0];
-      const chosen = ans?.selected?.[0] ?? ans?.custom;
-      if (chosen !== '确认创建') {
-        // 区分"点了取消"与"自己输入了别的东西"：
-        // 后者此前会被静默当成取消，用户不知道自己输入的内容被丢掉了。
-        if (ans?.custom && !ans?.selected?.length) {
-          return notify(session, 'error', bootstrap.notify({
-            type: 'confirm_invalid',
-            custom: ans.custom
-          }));
-        }
-        return notify(session, 'error', bootstrap.notify({ type: 'cancelled' }));
+      if (!confirmed.ok) {
+        if (confirmed.failure?.type === 'cancelled') return notify(session, 'error', '🚫 操作已取消。');
+        return notify(session, 'error', confirmed.failure?.message || '❌ 提问失败');
       }
+      const choice = confirmed.answer?.answers?.[0]?.selected?.[0];
+      if (choice !== '确认创建') return notify(session, 'error', '🚫 操作已取消。');
 
-      const initResult = await spawnScript('node', [join(SCRIPTS_DIR, 'init.js'), projectRoot], { timeout: 30000 });
-
-      if (initResult.ok) {
-        return notify(session, 'success', bootstrap.notify({ type: 'success' }));
-      } else {
-        const err = (typeof initResult.error === 'object' && initResult.error !== null)
-          ? (initResult.error.message || JSON.stringify(initResult.error))
-          : String(initResult.error || '未知错误');
-        return notify(session, 'error', bootstrap.notify({ type: 'error', err }));
+      try {
+        // First init may need the standalone binary. Install it into the
+        // workspace so it survives PATH changes and is easy to remove.
+        const notes = [];
+        if (!findSurrealBinary(target)) {
+          notes.push('⏬ 未找到 surreal，已自动下载到工作区 .fancy/bin/。');
+          await installSurreal(target);
+        }
+        const result = await initWorkspaceDatabase(target);
+        return notify(session, 'success', [
+          '✅ 工作区初始化完成',
+          ...(notes.length ? ['', ...notes] : []),
+          '',
+          formatWorkspace(result.workspace),
+          '',
+          '数据库：schema ' + result.schema_version + ' · validation ' + result.validation_version,
+          '素材库：' + (result.material?.database || 'material_library') + '（schema ' + (result.material?.schema_version || 6) + '）',
+          '服务：' + (result.server.running ? '运行中' : '未运行'),
+          ...(result.started && result.started.endpoint_changed
+            ? ['⚠️ 原端口被另一个 SurrealDB 占用，已改用：' + result.started.endpoint]
+            : []),
+          '',
+          '下一步：',
+          '1. /fancy-scan 扫榜',
+          '2. /fancy-topic 选题',
+          '3. /fancy-topic setup 创建项目（会分配 UUID、项目库和独立数据库用户）',
+          '4. /fancy-material 生成素材库（可选，写作时查名字/金手指/冲突/场景）',
+          '5. /fancy-douyin add <主页> 采集抖音图文素材（可选）',
+          '6. /fancy-build scale 开始写故事',
+        ].join('\n'));
+      } catch (err) {
+        return notify(session, 'error', '❌ 初始化失败：' + (err && err.message ? err.message : String(err)));
       }
-    }
+    },
   });
 }

package/plugins/fancy-bootstrap/scripts/init.js

@@ -20,9 +20,11 @@
  *     启动时检查 topic_decision_<date>.md 文件是否存在；不存在则报错让用户
  *     先跑 fancy-scan 并等待 LLM 完成分析写入该文件。
  */
-import { writeFileSync, existsSync, mkdirSync, realpathSync, statSync, unlinkSync } from 'fs';
+import { existsSync, lstatSync, mkdirSync, realpathSync, statSync, unlinkSync } from 'fs';
 import { expandHome, resolvePath, joinPath } from './path-utils.js';
 import { EC, errorResponse } from '#error-codes';
+import { atomicWriteFile } from '#atomic-write';
+import { isValidProjectPath, isSensitiveProjectPath, projectPathProblem } from '#path-guard';
 
 function nowIso() {
   return new Date().toISOString().replace('.000Z', 'Z');
@@ -56,17 +58,15 @@ function fail(ec, extra = {}) {
 function main() {
   const projectRootRaw = process.argv[2] ?? '';
 
-  if (!projectRootRaw || projectRootRaw.includes('..') || /[<>:"'|?*]/.test(projectRootRaw) || /[\x00-\x1f]/.test(projectRootRaw)) {
-    fail(EC.EC001_INVALID_PATH);
+  // 路径校验与 plugins/fancy-bootstrap/index.js 用**同一套规则**
+  // （lib/path-guard.js）。此前两边不一致：index.js 拒空白、init.js 不拒；
+  // 两边都放行 shell 元字符（$ ` ; & |）—— 而路径会被原样拼进
+  // 提示词里的 shell 命令，双引号挡不住命令替换。
+  if (isSensitiveProjectPath(projectRootRaw)) {
+    fail(EC.EC019_SENSITIVE_PATH);
   }
-
-  // 二次校验：拒绝敏感系统路径
-  const SENSITIVE_PREFIXES = ['/etc', '/proc', '/sys', '/dev', '/root/.ssh', '/root/.gnupg', '/var/log', '/var/lib', '/boot'];
-  const normalized = projectRootRaw.replace(/\\/g, '/');
-  for (const prefix of SENSITIVE_PREFIXES) {
-    if (normalized === prefix || normalized.startsWith(prefix + '/')) {
-      fail(EC.EC019_SENSITIVE_PATH);
-    }
+  if (!isValidProjectPath(projectRootRaw)) {
+    fail(EC.EC001_INVALID_PATH, { message: projectPathProblem(projectRootRaw) || '路径不合法' });
   }
 
   const projectRoot = resolvePath(expandHome(projectRootRaw));
@@ -81,21 +81,38 @@ function main() {
   const projectRootReal = realPathOf(projectRoot);
   const deployed = joinPath(projectRootReal, '.fancy-deployed');
 
-  if (existsSync(deployed)) {
+  // 标记文件必须是普通文件；符号链接会把“写项目状态”变成“写链接指向的文件”，
+  // 而项目根是用户可写的 —— 一个坏链接就能把内容写到项目外。
+  let deployedStat = null;
+  try { deployedStat = lstatSync(deployed); } catch { /* 不存在 */ }
+  if (deployedStat) {
+    if (deployedStat.isSymbolicLink()) {
+      fail(EC.EC017_INIT_FAILED, {
+        message: '.fancy-deployed 是符号链接，拒绝写入；请删除该链接后重新初始化'
+      });
+    }
+    if (!deployedStat.isFile()) {
+      fail(EC.EC017_INIT_FAILED, {
+        message: '.fancy-deployed 已存在但不是普通文件，请先处理它再重新初始化'
+      });
+    }
     fail(EC.EC002_ALREADY_INITIALIZED);
   }
   if (!existsSync(projectRootReal)) {
-    fail(EC.EC018_DIR_NOT_FOUND, { message: `目录不存在: ${projectRoot}` });
+    fail(EC.EC018_DIR_NOT_FOUND, {
+      message: `项目根目录不存在: ${projectRoot}`,
+      reason: 'missing',
+    });
   }
   if (!isDirectory(projectRootReal)) {
-    fail(EC.EC018_DIR_NOT_FOUND, { message: `不是一个目录: ${projectRoot}` });
+    fail(EC.EC018_DIR_NOT_FOUND, {
+      message: `项目根路径不是目录: ${projectRoot}`,
+      reason: 'not_directory',
+    });
   }
   // 真实路径再查一遍敏感前缀（符号链接已经解开）
-  const realNormalized = projectRootReal.replace(/\\/g, '/');
-  for (const prefix of SENSITIVE_PREFIXES) {
-    if (realNormalized === prefix || realNormalized.startsWith(prefix + '/')) {
-      fail(EC.EC019_SENSITIVE_PATH);
-    }
+  if (isSensitiveProjectPath(projectRootReal)) {
+    fail(EC.EC019_SENSITIVE_PATH);
   }
 
   const now = nowIso();
@@ -107,12 +124,29 @@ function main() {
     // 而项目其实是个半初始化状态（这次失败、那次也失败）。
     // 现在标记文件是"最后一步"，失败就不会留下误导性的标记。
     //
-    // 预创建工具目录，方便 fancy-analyze 等插件直接使用
-    mkdirSync(joinPath(projectRootReal, '参考资料'), { recursive: true });
-    mkdirSync(joinPath(projectRootReal, '对标'), { recursive: true });
+    // 预创建工具目录，方便 fancy-analyze 等插件直接使用。
+    // 这两个目录后续会被其它插件写入（原文/拆解结果），不能是符号链接 ——
+    // 否则一次初始化就能把它们指到项目外。
+    for (const name of ['参考资料', '对标']) {
+      const p = joinPath(projectRootReal, name);
+      let st = null;
+      try { st = lstatSync(p); } catch { /* 不存在 */ }
+      if (st) {
+        if (st.isSymbolicLink()) {
+          throw new Error(`${name}/ 是符号链接，拒绝初始化；请换成真实目录`);
+        }
+        if (!st.isDirectory()) {
+          throw new Error(`${name}/ 已存在但不是目录，拒绝初始化`);
+        }
+      } else {
+        mkdirSync(p, { recursive: true });
+      }
+    }
 
-    // 写 .fancy-deployed 标记文件
-    writeFileSync(deployed, JSON.stringify({
+    // 写 .fancy-deployed 标记文件。
+    // 原子写 + 0600：里面有 llm_wiki_token，不能让同机其它用户读到；
+    // 也不能在写到一半被杀时留下半份 JSON（下次启动会报“状态文件损坏”）。
+    atomicWriteFile(deployed, JSON.stringify({
       deployed_at: now,
       project_root_abs: projectRootReal,
       phase: 'initialized',
@@ -121,7 +155,7 @@ function main() {
       reference_id: '',
       novel_id: '',
       provider: 'custom',
-    }, null, 2), 'utf-8');
+    }, null, 2), { mode: 0o600 });
   } catch (e) {
     const errMsg = e instanceof Error ? e.message : String(e);
     // 失败时把标记文件删掉，别留半初始化状态