@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/lib/db-init.js

@@ -0,0 +1,123 @@
+/**
+ * Workspace/project database initialization.
+ *
+ * This is the single place that creates schema, validation functions, registry
+ * metadata, and the per-project database. The `/fancy-db init` command and the
+ * MCP `fancy_db_init` tool both call it.
+ */
+
+import {
+  initWorkspace,
+  readWorkspace,
+  workspacePaths,
+} from './workspace.js';
+import {
+  getProject,
+  listProjects,
+  withRegistry,
+} from './projects.js';
+import { startServer, serverStatus } from './surreal-server.js';
+import { ensureMaterialDatabase, materialDatabaseName } from './material-db.js';
+import { SCHEMA_VERSION, VALIDATION_VERSION } from '../plugins/fancy-story-builder/storydb/validation.js';
+
+export async function initWorkspaceDatabase(root, opts = {}) {
+  const init = initWorkspace(root, opts);
+  // Always verify that the server on this workspace's endpoint is actually
+  // ours. A stale server from a deleted workspace may pass /health but reject
+  // our root password; startServer then moves us to a free port.
+  const started = await startServer(init.root);
+
+  await withRegistry(init.root, async (db, workspace) => {
+    await db.query(
+      `UPSERT fancy_meta:main SET
+         schema_version = $schema_version,
+         validation_version = $validation_version,
+         updated_at = time::now();`,
+      { schema_version: SCHEMA_VERSION, validation_version: VALIDATION_VERSION },
+    );
+    return workspace;
+  });
+
+  const material = await ensureMaterialDatabase(init.root);
+
+  return {
+    ok: true,
+    workspace: init.root,
+    created: init.created,
+    server: await serverStatus(init.root),
+    started,
+    schema_version: SCHEMA_VERSION,
+    validation_version: VALIDATION_VERSION,
+    material,
+  };
+}
+
+export async function initProjectDatabase(root, nameOrId, opts = {}) {
+  const project = await getProject(root, nameOrId);
+  if (!project) throw new Error('未找到项目：' + nameOrId);
+  const { openStoryGraph } = await import('../plugins/fancy-story-builder/storydb/client.js');
+  const sdb = await openStoryGraph(project.dir, { project, admin: true });
+  try {
+    await sdb.query(
+      `UPSERT fancy_meta:main SET
+         schema_version = $schema_version,
+         validation_version = $validation_version,
+         updated_at = time::now();`,
+      { schema_version: SCHEMA_VERSION, validation_version: VALIDATION_VERSION },
+    );
+    const info = await sdb.query('INFO FOR DB;');
+    const db = Array.isArray(info) && info[0] ? info[0] : info;
+    return {
+      ok: true,
+      project: { id: project.project_id, name: project.name, database: project.db_name },
+      schema_version: SCHEMA_VERSION,
+      validation_version: VALIDATION_VERSION,
+      tables: Object.keys((db && db.tables) || {}).length,
+      functions: Object.keys((db && db.functions) || {}),
+      users: Object.keys((db && db.users) || {}),
+    };
+  } finally {
+    await sdb.close();
+  }
+}
+
+export async function initAllProjectDatabases(root, opts = {}) {
+  const projects = await listProjects(root);
+  const results = [];
+  for (const project of projects) {
+    try {
+      results.push(await initProjectDatabase(root, project.project_id, opts));
+    } catch (err) {
+      results.push({
+        ok: false,
+        project: { id: project.project_id, name: project.name },
+        error: err && err.message ? err.message : String(err),
+      });
+    }
+  }
+  return results;
+}
+
+export async function initDatabases(root, opts = {}) {
+  const workspace = await initWorkspaceDatabase(root, opts);
+  let projects = [];
+  if (opts.project) {
+    projects = [await initProjectDatabase(root, opts.project, opts)];
+  } else if (opts.all !== false) {
+    projects = await initAllProjectDatabases(root, opts);
+  }
+  return { ...workspace, projects };
+}
+
+export function databaseLayout(root) {
+  const paths = workspacePaths(root);
+  const workspace = readWorkspace(root);
+  return {
+    workspace: paths.root,
+    server_data: paths.surrealData,
+    server_log: paths.surrealLog,
+    registry_database: workspace.surreal?.registry_database || 'fancy_registry',
+    material_database: materialDatabaseName(workspace),
+    projects: paths.projects,
+  };
+}

package/lib/deployed-state.js

@@ -97,18 +97,18 @@ export function deployedStateProblemText(state, opts = {}) {
   const projectRoot = opts.projectRoot || '';
 
   if (state.status === DEPLOYED_STATUS.MISSING) {
-    return '❌ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+    return '❌ 当前目录不是已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
   }
 
   const head = state.status === DEPLOYED_STATUS.CORRUPT
     ? '❌ 状态文件 .fancy-deployed 损坏（不是合法 JSON），无法确定项目状态。'
     : state.status === DEPLOYED_STATUS.NO_PHASE
-      ? '❌ 状态文件 .fancy-deployed 缺少 phase 字段，无法确定项目当前阶段。'
-      : `❌ 状态文件 .fancy-deployed 的 phase 值不认识（"${state.phase}"），无法确定项目当前阶段。`;
+      ? '❌ 状态文件 .fancy-deployed 缺少 phase 字段，无法确定当前工作区阶段。'
+      : `❌ 状态文件 .fancy-deployed 的 phase 值不在允许范围内（"${state.phase}"），无法确定当前工作区阶段。`;
 
   const phaseHelp = state.status === DEPLOYED_STATUS.CORRUPT
-    ? `3. 如果整个文件不是合法 JSON，用下面的模板重建 .fancy-deployed，
-       并把原来的 llm_wiki_token / reference_id 等字段值填回去：
+    ? `3. 如果整个文件不是合法 JSON，请使用下面的模板重建 .fancy-deployed，
+       并将原有的 llm_wiki_token / reference_id 等字段值填回：
 
        {
          "deployed_at": "<ISO 时间>",
@@ -122,20 +122,20 @@ export function deployedStateProblemText(state, opts = {}) {
        }
 `
     : `3. 把 phase 改成合法值之一：${PHASE_ORDER.join(' / ')}。
-       拿不准就填 "initialized" —— 它允许流程从头再走一遍。`;
+       无法确定时填写 "initialized"，即可允许流程从头重新执行。`;
 
   return `${head}${state.error ? `\n原因：${state.error}` : ''}
 
-这条消息不能靠重跑命令解决（重跑只会再撞一次同样的问题），需要手工修复：
+重复运行命令无法解决该问题，需要手动修复状态文件：
 
 1. 打开项目根目录下的 .fancy-deployed
 2. ${state.status === DEPLOYED_STATUS.CORRUPT
-      ? '确认文件内容是不是被截断了（写入过程中断电/被编辑器改坏都会这样）'
+      ? '确认文件是否被截断或意外修改（写入过程中断电、编辑器异常退出等均可能导致）'
       : `找到 "phase" 那一行${state.phase ? `（当前值 "${state.phase}"）` : ''}，改成下面任一合法值`}
 ${phaseHelp}
-4. 修完重新执行刚才的命令
+4. 修复完成后重新执行原命令
 
-另一条路（会丢配置，慎用）：
+备选方案（会丢失配置，请谨慎使用）：
 5. 删除 .fancy-deployed 后重新运行 /fancy-bootstrap 重建。
-   注意：这会丢掉 llm_wiki_token / reference_id / setup_id 等字段，需要重新填。`;
+   注意：该操作会丢失 llm_wiki_token / reference_id / setup_id 等字段，需要重新填写。`;
 }

package/lib/direction-labels.js

@@ -0,0 +1,265 @@
+/**
+ * direction-fields —— 选题方向的 11 项设计（**单一事实来源**）
+ *
+ * ## 为什么要有这个文件（2026-10-29 提示词评审 F2 / 11.2）
+ *
+ * 这 11 项同时出现在五处：
+ *
+ *   1. fancy-scan 的方向模板（模型照抄的 11 行）；
+ *   2. fancy-scan 的写入后校验脚本（查每个方向的标签齐不齐）；
+ *   3. fancy-topic 的 11 个独立字段（探索建议 + setup 弹框）；
+ *   4. fancy-topic 的字段校验（查 11 项齐不齐、内容够不够厚）；
+ *   5. fancy-story-builder 的任务输入快照（渲染给骨架/血肉/节奏阶段）。
+ *
+ * 现在只定义一次，五处都从它生成。`label` 是扫榜报告里的中文标签，
+ * `id` 是 JSON 里的字段名 —— 两边靠这张表一一对应，不再手写第二份。
+ *
+ * 2026-10-30：`direction_design` 从一个大字符串拆成 11 个平级字段。
+ * JSON 结构化后，弹框可以逐项展示，story-builder 也不用再解析文本。
+ * 其中「定位」与原来的 `core_summary` 合并为 `positioning`。
+ */
+export const DIRECTION_FIELDS = [
+  {
+    id: 'positioning',
+    label: '定位',
+    topicLabel: '一句话定位',
+    description: '题材、主角、核心卖点，一句话说清这本书是什么',
+    sample: '以家族为经营单元的长线修仙群像文，用几十代人的接力写一个小家族如何变成庞然大物',
+  },
+  {
+    id: 'reader_value',
+    label: '读者与情绪价值',
+    description: '目标读者是谁、提供什么情绪价值；尽量引用榜上同类书',
+    sample: '面向喜欢慢热经营与设定自洽的成年读者，提供「看着家底一点点变大」的踏实感与归属感',
+  },
+  {
+    id: 'golden_finger',
+    label: '金手指',
+    description: '能力、代价、限制，三者都要写',
+    sample: '铜镜或残魂式的家族传承，只给家族少数人有限度的启发与预警，代价绑定血脉与代际更替',
+  },
+  {
+    id: 'core_setting',
+    label: '核心设定',
+    description: '世界、规则、主线；要能自洽，不是副本',
+    sample: '完整的修真文明，规则包含灵气、境界、功法与家族长幼秩序，主线是家族从村落到一方势力的数代经营史',
+  },
+  {
+    id: 'payoff_model',
+    label: '爽点模式',
+    description: '前 10 章、每 3 章、长线各给什么爽点',
+    sample: '前 10 章立家族账目与人际矛盾，每 3 章一次资源或关系突破，长线以代际交替给出大尺度成就感',
+  },
+  {
+    id: 'emotion_curve',
+    label: '情绪价值曲线',
+    description: '压抑—释放—升级的节奏',
+    sample: '前期压抑在资源匮乏与族内分歧，中期靠经营突破释放，后期用代际传承升级成就感',
+  },
+  {
+    id: 'opening_hook',
+    label: '开篇切入点',
+    description: '第 1 章的场景、冲突与钩子',
+    sample: '第一章让传承物与外部威胁同时出现，主角在家族账目与生存压力之间做第一个选择',
+  },
+  {
+    id: 'pacing_plan',
+    label: '节奏规划',
+    description: '开篇 / 前期 / 中期 / 后期各阶段的推进方式',
+    sample: '开篇 10 章立设定，前期 30 章完成第一次资源积累，中期以卷为单位扩张，后期进入代际交替',
+  },
+  {
+    id: 'character_design',
+    label: '人物设定',
+    description: '主角、对手、关键配角与关系网',
+    sample: '主角是负责账目的旁支子弟，对手是同族嫡系与外部势力，关键配角覆盖族老、商路伙伴与叛徒',
+  },
+  {
+    id: 'differentiation',
+    label: '差异化策略',
+    description: '与榜上同类的具体区别，不能只说“更爽”',
+    sample: '同类多为个人修仙，本书把经营单位改成家族，用代际接力替代单主角升级',
+  },
+  {
+    id: 'risk_validation',
+    label: '风险与验证',
+    description: '主要风险与可验证指标',
+    sample: '风险是代际切换掉读者，验证指标看前 20 章追读、家族成员辨识度与每 3 章突破是否兑现',
+  },
+];
+
+/** 11 项设计标签 —— 顺序即模型照抄的顺序 */
+export const DIRECTION_LABELS = DIRECTION_FIELDS.map(f => f.label);
+
+/** 标签 → 字段 ID（旧 direction_design 文本迁移用） */
+export const DIRECTION_FIELD_BY_LABEL = new Map(
+  DIRECTION_FIELDS.map(f => [f.label, f])
+);
+
+/** 字段 ID → 定义 */
+export const DIRECTION_FIELD_BY_ID = new Map(
+  DIRECTION_FIELDS.map(f => [f.id, f])
+);
+
+/** 校验用的标签正则（加粗形式） */
+export const DIRECTION_LABEL_RE = new RegExp(
+  '^-\\s*\\*\\*(?:' + DIRECTION_LABELS.join('|') + ')\\*\\*\\s*[:：]',
+  'm'
+);
+
+/** 方向模板（模型照抄这 11 行） */
+export function directionTemplateBlock() {
+  return DIRECTION_LABELS.map(l => `- **${l}**：...`).join('\n');
+}
+
+/**
+ * 生成 python 源码里的标签列表（校验脚本用）。
+ *
+ * 校验脚本必须拿**同一份**清单去查 —— 手写一遍就等于埋了一个新的漂移点。
+ *
+ * @param {number} [perLine=4] 每行放几个标签
+ * @returns {string[]} python 源码行（第一行带 `labels = [`，后续行对齐）
+ */
+export function directionLabelsPythonLines(perLine = 4) {
+  const head = 'labels = [';
+  const pad = ' '.repeat(head.length);
+  const out = [];
+  for (let i = 0; i < DIRECTION_LABELS.length; i += perLine) {
+    const chunk = DIRECTION_LABELS.slice(i, i + perLine).map(l => `'${l}'`);
+    const prefix = i === 0 ? head : pad;
+    const suffix = i + perLine >= DIRECTION_LABELS.length ? ']' : ',';
+    out.push(prefix + chunk.join(', ') + suffix);
+  }
+  return out;
+}
+
+/** 正则里要转义的字符 */
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** 数汉字（CJK 统一表意文字，含扩展 A） */
+function cjkCount(text) {
+  let n = 0;
+  for (const ch of String(text || '')) {
+    const c = ch.codePointAt(0);
+    if ((c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf)) n++;
+  }
+  return n;
+}
+
+/**
+ * 校验一份 `direction_design` 文本：11 项标签是否齐全、每项内容是否够厚。
+ *
+ * 与 scan 的 `validateReportBody` 用同一份 `DIRECTION_LABELS`，
+ * 但这里只查 `direction_design` 这一个字段（topic 侧写盘前用）。
+ *
+ * @param {string} text
+ * @param {{minChars?: number}} [opts]
+ * @returns {{ok: boolean, missing: string[], short: Array<{label: string, chars: number}>}}
+ */
+export function inspectDirectionDesign(text, opts = {}) {
+  const minChars = Number.isInteger(opts.minChars) ? opts.minChars : 20;
+  const lines = String(text || '').split('\n');
+  const missing = [];
+  const short = [];
+
+  for (const label of DIRECTION_LABELS) {
+    const re = new RegExp(
+      '^\\s*(?:[-*+]\\s+)?\\*{0,2}' + escapeRe(label) + '\\*{0,2}\\s*[:：]\\s*(.*)$'
+    );
+    const hit = lines.map(l => re.exec(l)).find(Boolean);
+    if (!hit) {
+      missing.push(label);
+      continue;
+    }
+    const chars = cjkCount(hit[1]);
+    if (chars < minChars) short.push({ label, chars });
+  }
+
+  return { ok: missing.length === 0 && short.length === 0, missing, short };
+}
+
+/**
+ * 把旧的 `direction_design` 文本解析成 11 个字段。
+ *
+ * 旧格式每项一行：`- **定位**：内容`。只取标签后第一行的内容；
+ * 老产物本来就没有跨行条目。
+ *
+ * @param {string} text
+ * @returns {Record<string, string>} 字段 ID → 内容（没写到的项不出现）
+ */
+export function parseDirectionDesign(text) {
+  const out = {};
+  const lines = String(text || '').split('\n');
+  for (const field of DIRECTION_FIELDS) {
+    const re = new RegExp(
+      '^\\s*(?:[-*+]\\s+)?\\*{0,2}' + escapeRe(field.label) + '\\*{0,2}\\s*[:：]\\s*(.*)$'
+    );
+    const hit = lines.map(l => re.exec(l)).find(Boolean);
+    if (hit && hit[1].trim()) out[field.id] = hit[1].trim();
+  }
+  return out;
+}
+
+/**
+ * 校验 11 个设计字段：每一项都要有内容，且汉字数够。
+ *
+ * @param {Record<string, unknown>} data
+ * @param {{minChars?: number}} [opts]
+ * @returns {{ok: boolean, missing: string[], short: Array<{id: string, label: string, chars: number}>}}
+ */
+export function inspectDirectionFields(data, opts = {}) {
+  const minChars = Number.isInteger(opts.minChars) ? opts.minChars : 20;
+  const missing = [];
+  const short = [];
+  const d = data && typeof data === 'object' ? data : {};
+
+  for (const field of DIRECTION_FIELDS) {
+    const v = d[field.id];
+    if (typeof v !== 'string' || !v.trim()) {
+      missing.push(field.topicLabel || field.label);
+      continue;
+    }
+    const chars = cjkCount(v);
+    if (chars < minChars) {
+      short.push({ id: field.id, label: field.topicLabel || field.label, chars });
+    }
+  }
+
+  return { ok: missing.length === 0 && short.length === 0, missing, short };
+}
+
+/**
+ * 找出正文里**缺标签的方向**（插件侧兜底）。
+ *
+ * 下游 story-builder 拿到的是残缺输入。插件这边能自己查一遍，
+ * 就多一道防线（提示词是"请求"，插件检查才是"保证"）。
+ *
+ * 只做**告警**，不判块失败：格式差异不该把一整块报告判死。
+ *
+ * @param {string} text 块正文
+ * @returns {string[]} 每个缺标签方向的说明（没有则空数组）
+ */
+export function missingDirectionLabels(text) {
+  const lines = String(text || '').split('\n');
+  const dirRe = /^###\s*方向\s*\d+\s*[:：]/;
+  const pos = [];
+  lines.forEach((l, i) => { if (dirRe.test(l)) pos.push(i); });
+
+  const out = [];
+  pos.forEach((start, k) => {
+    const end = k + 1 < pos.length ? pos[k + 1] : lines.length;
+    const section = lines.slice(start, end);
+    const missing = DIRECTION_LABELS.filter(lab => {
+      const re = new RegExp(
+        '^\\s*(?:[-*+]\\s+)?\\*{0,2}' + escapeRe(lab) + '\\*{0,2}\\s*[:：]'
+      );
+      return !section.some(l => re.test(l));
+    });
+    if (missing.length) {
+      out.push(`方向 ${k + 1}（缺 ${missing.length} 项：${missing.join('、')}）`);
+    }
+  });
+  return out;
+}

package/lib/error-codes.js

@@ -26,49 +26,49 @@
 
 export const EC = {
   // ─── 001-019: bootstrap ───────────────────────────────────────
-  EC001_INVALID_PATH:        { code: 1,  message: '路径不合法（不能含空格、.. 或特殊字符）' },
-  EC002_ALREADY_INITIALIZED: { code: 2,  message: '项目已存在，不能重复 init' },
-  EC003_INVALID_PROJECT_ROOT:{ code: 3,  message: '项目根路径不是绝对路径或不存在' },
-  EC017_INIT_FAILED:         { code: 17, message: '初始化失败' },
-  EC018_DIR_NOT_FOUND:       { code: 18, message: '目录不存在' },
-  EC019_SENSITIVE_PATH:      { code: 19, message: '拒绝访问敏感系统路径' },
+  EC001_INVALID_PATH:        { code: 1,  message: '路径不合法（不能包含 .. 或 shell 特殊字符）。' },
+  EC002_ALREADY_INITIALIZED: { code: 2,  message: '项目已初始化，不能重复执行 init。' },
+  EC003_INVALID_PROJECT_ROOT:{ code: 3,  message: '项目根路径不是绝对路径，或不存在。' },
+  EC017_INIT_FAILED:         { code: 17, message: '初始化失败。' },
+  EC018_DIR_NOT_FOUND:       { code: 18, message: '目录不存在。' },
+  EC019_SENSITIVE_PATH:      { code: 19, message: '已拒绝访问系统受保护路径。' },
 
   // ─── 020-039: scan ────────────────────────────────────────────
   EC020_BROWSER_LAUNCH:      { code: 20, message: '浏览器启动失败' },
-  EC021_BROWSER_DISCONNECTED: { code: 21, message: '浏览器在采集过程中断开' },
-  EC022_PAGE_GOTO_TIMEOUT:    { code: 22, message: '页面导航超时' },
-  EC023_WAIT_RENDER_TIMEOUT:  { code: 23, message: '等待榜单渲染超时' },
-  EC024_SCRAPER_TIMEOUT:      { code: 24, message: 'scraper 子进程超时' },
-  EC025_SCRAPER_NON_JSON:     { code: 25, message: 'scraper 输出非 JSON' },
-  EC026_OCR_FAILED:           { code: 26, message: 'OCR 识别失败' },
-  EC027_NO_OUTPUT_FILES:      { code: 27, message: '未找到采集输出文件' },
-  EC028_INVALID_RANK:         { code: 28, message: '未知或非法的榜单 ID' },
-  EC029_INVALID_PLATFORM_SCAN:{ code: 29, message: '不支持的平台' },
+  EC021_BROWSER_DISCONNECTED: { code: 21, message: '浏览器在采集过程中断开。' },
+  EC022_PAGE_GOTO_TIMEOUT:    { code: 22, message: '页面导航超时。' },
+  EC023_WAIT_RENDER_TIMEOUT:  { code: 23, message: '等待榜单渲染超时。' },
+  EC024_SCRAPER_TIMEOUT:      { code: 24, message: '采集子进程执行超时。' },
+  EC025_SCRAPER_NON_JSON:     { code: 25, message: '采集进程输出不是合法 JSON。' },
+  EC026_OCR_FAILED:           { code: 26, message: 'OCR 识别失败。' },
+  EC027_NO_OUTPUT_FILES:      { code: 27, message: '未找到采集输出文件。' },
+  EC028_INVALID_RANK:         { code: 28, message: '榜单 ID 无效或不受支持。' },
+  EC029_INVALID_PLATFORM_SCAN:{ code: 29, message: '平台不受支持。' },
 
   // ─── 040-059: topic ───────────────────────────────────────────
-  EC040_INVALID_PLATFORM:    { code: 40, message: 'platform 参数非法' },
-  EC041_INVALID_GENRE:       { code: 41, message: 'genre 参数非法' },
-  EC042_MISSING_REQUIRED:    { code: 42, message: '必填参数缺失' },
-  EC043_PHASE_NOT_TOPIC:     { code: 43, message: '当前 phase 不允许 fancy-topic' },
-  EC044_TOPIC_STATE_MISSING: { code: 44, message: '_story_state.json 不存在' },
-  EC045_TOPIC_WRITE_FAILED:   { code: 45, message: 'fancy-topic 写盘失败' },
-  EC046_INVALID_WORDS:        { code: 46, message: '目标字数不合法（必须为正整数）' },
-  EC047_INVALID_CHAPTERS:     { code: 47, message: '目标章数不合法（必须为正整数）' },
-  EC048_PLATFORM_NOT_FOUND:   { code: 48, message: 'topic_decision 中找不到该平台的内容块' },
+  EC040_INVALID_PLATFORM:    { code: 40, message: 'platform 参数无效。' },
+  EC041_INVALID_GENRE:       { code: 41, message: 'genre 参数无效。' },
+  EC042_MISSING_REQUIRED:    { code: 42, message: '缺少必填参数。' },
+  EC043_PHASE_NOT_TOPIC:     { code: 43, message: '当前工作区阶段不允许执行 fancy-topic。' },
+  EC044_TOPIC_STATE_MISSING: { code: 44, message: '未找到 _story_state.json。' },
+  EC045_TOPIC_WRITE_FAILED:   { code: 45, message: 'fancy-topic 写入文件失败。' },
+  EC046_INVALID_WORDS:        { code: 46, message: '目标字数无效，必须为正整数。' },
+  EC047_INVALID_CHAPTERS:     { code: 47, message: '目标章数无效，必须为正整数。' },
+  EC048_PLATFORM_NOT_FOUND:   { code: 48, message: 'topic_decision 中未找到该平台的内容块。' },
 
   // ─── 120-139: shared ──────────────────────────────────────────
-  EC120_ATOMIC_WRITE_FAIL:   { code: 120, message: '原子写文件失败' },
-  EC121_PHASE_ADVANCE_FAIL:  { code: 121, message: 'phase 推进失败' },
-  EC122_PERMISSION_DENIED:   { code: 122, message: '权限不足' },
-  EC123_JSON_PARSE_FAIL:     { code: 123, message: 'JSON 解析失败' },
+  EC120_ATOMIC_WRITE_FAIL:   { code: 120, message: '原子写入文件失败。' },
+  EC121_PHASE_ADVANCE_FAIL:  { code: 121, message: '阶段状态推进失败。' },
+  EC122_PERMISSION_DENIED:   { code: 122, message: '权限不足。' },
+  EC123_JSON_PARSE_FAIL:     { code: 123, message: 'JSON 解析失败。' },
   // "项目未初始化"与 EC002（项目已存在，不能重复 init）语义相反，
   // 不能复用。此前 run-scan.js / select-topic.js 都把"未初始化"报成 EC002，
   // 导致 code_name 与 message 自相矛盾（退出码 2 实际表示"未初始化"）。
-  EC124_PROJECT_NOT_INITIALIZED: { code: 124, message: '项目未初始化（.fancy-deployed 不存在）' },
+  EC124_PROJECT_NOT_INITIALIZED: { code: 124, message: '项目尚未初始化（.fancy-deployed 不存在）。' },
 
   // ─── 200+: system ─────────────────────────────────────────────
-  EC200_SPAWN_FAIL:          { code: 200, message: '子进程启动失败' },
-  EC201_SCRIPT_TIMEOUT:      { code: 201, message: '脚本执行超时' },
+  EC200_SPAWN_FAIL:          { code: 200, message: '子进程启动失败。' },
+  EC201_SCRIPT_TIMEOUT:      { code: 201, message: '脚本执行超时。' },
 };
 
 /**

package/lib/infra.js

@@ -84,6 +84,7 @@
 
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
+import { join, resolve } from 'path';
 
 // --------------------------------------------------------------------------
 // ANSI escape cleanup
@@ -288,7 +289,29 @@ export function buildUserMessage(text) {
  * @param {string|object|null|undefined} content - 提示词正文
  * @returns {{ok: boolean, error: string|null}}
  */
-export function llmFollowup(invocation, content) {
+/**
+ * 给所有插件提示词追加统一的临时文件规则。
+ *
+ * 绝对路径来自会话 cwd（工作区目录），不依赖宿主进程的 process.cwd()。
+ */
+export function tempDirInstruction(invocation) {
+  const cwd = invocation && invocation.agent && invocation.agent.session
+    && invocation.agent.session.header
+    && invocation.agent.session.header.cwd;
+  if (typeof cwd !== 'string' || !cwd.trim()) return '';
+  const tempDir = join(resolve(cwd), '.tmp');
+  return [
+    '',
+    '【临时文件规则】',
+    '如果需要创建临时文件，必须创建在以下绝对路径目录中：',
+    tempDir,
+    '创建目录可用：mkdir -p ' + tempDir,
+    '不要把临时文件直接放在工作区目录、/tmp 或其他位置。',
+    '临时文件创建后不允许删除（任务结束也不要清理）；需要重写时直接覆盖同一个文件。',
+  ].join('\n');
+}
+
+export function llmFollowup(invocation, content, options) {
   let prompt;
   try {
     if (typeof content === 'string') prompt = content;
@@ -310,7 +333,9 @@ export function llmFollowup(invocation, content) {
     return { ok: false, error: reason };
   }
   try {
-    const message = buildUserMessage(prompt);
+    const appendTempRule = !options || options.appendTempRule !== false;
+    const finalPrompt = appendTempRule ? prompt + tempDirInstruction(invocation) : prompt;
+    const message = buildUserMessage(finalPrompt);
     const agent = invocation.agent;
     // DSH 对两者的语义区分得很明确：
     //   followup() — "排一个普通的后续 turn 并唤醒驱动器，
@@ -422,7 +447,7 @@ export async function broadcastResult(invocation, pluginName, result) {
     return { activated: false, reason: 'already_dispatched' };
   }
   const text = buildBroadcastText(pluginName, result);
-  const follow = await llmFollowup(invocation, text);
+  const follow = await llmFollowup(invocation, text, { appendTempRule: false });
   return follow.ok === true
     ? { activated: true, reason: 'activated' }
     : { activated: false, reason: 'dispatch_failed', error: follow.error };
@@ -447,7 +472,7 @@ export async function broadcastResult(invocation, pluginName, result) {
  * spawnScript 以 detached:true 起子进程，proc.pid 即新进程组的组长，
  * process.kill(-pid, sig) 会把整组一起收掉 —— 其中包含 playwright 拉起的
  * chromium。此前只调 proc.kill() 杀直接子进程，chromium 会变成孤儿进程，
- * 继续占 CPU/内存并往项目目录写盘。
+ * 继续占 CPU/内存并往工作区目录写盘。
  *
  * Windows 的 process.kill 不支持负 pid，此处退化为只杀直接子进程
  * （与改动前行为一致，不劣化）。