@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/confirmation.js

@@ -0,0 +1,80 @@
+/**
+ * Two-phase confirmation tokens for natural-language writes.
+ *
+ * The server cannot see the chat window, so it enforces a protocol-level
+ * two-step flow: `story_preview` returns a signed token over the exact payload;
+ * `story_apply` refuses to write without it. The tool description instructs the
+ * agent to show the preview to the user and only pass the token after an
+ * explicit confirmation. DSH's native adapter adds a real UI confirmation on
+ * top of this.
+ */
+
+import crypto from 'crypto';
+import { readSecrets, readWorkspace } from './workspace.js';
+
+const TTL_MS = 10 * 60 * 1000;
+
+function secretFor(workspace) {
+  try {
+    const secrets = readSecrets(workspace);
+    if (secrets.confirmation_secret) return secrets.confirmation_secret;
+    // Fall back to the SurrealDB root password: it is already workspace-local
+    // and 0600. Never expose it in the token itself.
+    if (secrets.surreal?.password) return 'surreal:' + secrets.surreal.password;
+  } catch { /* ignore */ }
+  return 'fancy-confirmation-fallback';
+}
+
+function canonical(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+function sign(secret, body) {
+  return crypto.createHmac('sha256', secret).update(body).digest('base64url');
+}
+
+export function createConfirmation(workspace, project, payload) {
+  const body = Buffer.from(JSON.stringify({
+    v: 1,
+    workspace: workspace,
+    project: project.project_id,
+    exp: Date.now() + TTL_MS,
+    payload,
+  }), 'utf8').toString('base64url');
+  const token = body + '.' + sign(secretFor(workspace), body);
+  return {
+    confirmation_token: token,
+    expires_at: new Date(Date.now() + TTL_MS).toISOString(),
+    ttl_seconds: Math.floor(TTL_MS / 1000),
+  };
+}
+
+export function verifyConfirmation(workspace, project, token, payload) {
+  const text = String(token || '');
+  const idx = text.lastIndexOf('.');
+  if (idx <= 0) return { ok: false, reason: 'malformed' };
+  const body = text.slice(0, idx);
+  const signature = text.slice(idx + 1);
+  const expected = sign(secretFor(workspace), body);
+  if (signature.length !== expected.length
+    || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    return { ok: false, reason: 'signature' };
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'body' };
+  }
+  if (decoded.v !== 1) return { ok: false, reason: 'version' };
+  if (decoded.workspace !== workspace) return { ok: false, reason: 'workspace' };
+  if (decoded.project !== project.project_id) return { ok: false, reason: 'project' };
+  if (Number(decoded.exp) < Date.now()) return { ok: false, reason: 'expired' };
+  if (canonical(decoded.payload) !== canonical(payload)) return { ok: false, reason: 'payload' };
+  return { ok: true };
+}

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

@@ -0,0 +1,141 @@
+/**
+ * .fancy-deployed 状态文件的统一体检。
+ *
+ * 这个文件是整个项目的状态源：phase（当前阶段）、llm_wiki_url/token、
+ * reference_id、setup_id 都在里面。五个插件都要读它，但原先各写各的：
+ *   - fancy-topic    readPhaseSafe()      → missing / corrupt / no_phase
+ *   - fancy-analyze  readDeployedConfig()  → missing / corrupt
+ *   - fancy-scan     advancePhase()        → missing / unknown_phase / error
+ * 三套口径不一致 → 同一个坏文件在三个插件里表现不同，
+ * 而且**没有一个插件告诉用户该怎么修** —— 最糟的情况下形成死循环：
+ *   /fancy-scan   扫完、报成功，但 phase 没推进（失败只写进 stderr）
+ *   /fancy-topic  报"状态文件读不了，请重新运行 /fancy-bootstrap"
+ *   /fancy-bootstrap  报"该目录已初始化"（只看文件存在，坏文件也拒绝）
+ * 用户被困在中间，没有任何命令能推进那个 phase。
+ *
+ * 所以这里统一两件事：**怎么判断**（readDeployedState）与
+ * **怎么修**（deployedStateProblemText）。
+ *
+ * @module lib/deployed-state
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/** 阶段推进顺序（只能向前） */
+export const PHASE_ORDER = ['initialized', 'scanned', 'topic_done', 'bible_done', 'outline_done'];
+
+/** 体检结果的状态枚举 */
+export const DEPLOYED_STATUS = {
+  OK: 'ok',
+  /** 文件不存在 */
+  MISSING: 'missing',
+  /** 文件不是合法 JSON */
+  CORRUPT: 'corrupt',
+  /** 文件是合法 JSON，但没有 phase 字段（或不是字符串） */
+  NO_PHASE: 'no_phase',
+  /** 有 phase 字段，但值不在 PHASE_ORDER 里 */
+  UNKNOWN_PHASE: 'unknown_phase',
+};
+
+/**
+ * 体检 .fancy-deployed。
+ *
+ * @param {string} projectRoot - 项目根目录
+ * @returns {{status: string, config: object|null, phase: string|null, error: string|null}}
+ */
+export function readDeployedState(projectRoot) {
+  const deployed = join(projectRoot, '.fancy-deployed');
+  if (!existsSync(deployed)) {
+    return { status: DEPLOYED_STATUS.MISSING, config: null, phase: null, error: null };
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(deployed, 'utf-8'));
+  } catch (e) {
+    return {
+      status: DEPLOYED_STATUS.CORRUPT,
+      config: null,
+      phase: null,
+      error: e && e.message ? e.message : String(e),
+    };
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return {
+      status: DEPLOYED_STATUS.CORRUPT,
+      config: null,
+      phase: null,
+      error: '不是合法的 JSON 对象',
+    };
+  }
+  if (typeof data.phase !== 'string' || data.phase === '') {
+    return { status: DEPLOYED_STATUS.NO_PHASE, config: data, phase: null, error: null };
+  }
+  if (!PHASE_ORDER.includes(data.phase)) {
+    return {
+      status: DEPLOYED_STATUS.UNKNOWN_PHASE,
+      config: data,
+      phase: data.phase,
+      error: `phase 的值 "${data.phase}" 不认识`,
+    };
+  }
+  return { status: DEPLOYED_STATUS.OK, config: data, phase: data.phase, error: null };
+}
+
+/**
+ * 把体检结果渲染成用户可读的说明（含**可执行的修复指引**）。
+ *
+ * 关键点：不能只说"文件坏了"。用户需要知道改哪一行、改成什么，
+ * 或者干脆怎么重建 —— 否则就只能反复重跑命令直到放弃。
+ *
+ * @param {object} state - readDeployedState 的返回值
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot] - 项目根（用于生成模板里的路径）
+ * @returns {string|null} status 为 ok 时返回 null
+ */
+export function deployedStateProblemText(state, opts = {}) {
+  if (!state || state.status === DEPLOYED_STATUS.OK) return null;
+  const projectRoot = opts.projectRoot || '';
+
+  if (state.status === DEPLOYED_STATUS.MISSING) {
+    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}"），无法确定当前工作区阶段。`;
+
+  const phaseHelp = state.status === DEPLOYED_STATUS.CORRUPT
+    ? `3. 如果整个文件不是合法 JSON，请使用下面的模板重建 .fancy-deployed，
+       并将原有的 llm_wiki_token / reference_id 等字段值填回：
+
+       {
+         "deployed_at": "<ISO 时间>",
+         "project_root_abs": "${projectRoot}",
+         "phase": "initialized",
+         "llm_wiki_url": "http://localhost:19828/api/v1",
+         "llm_wiki_token": "",
+         "reference_id": "",
+         "novel_id": "",
+         "provider": "custom"
+       }
+`
+    : `3. 把 phase 改成合法值之一：${PHASE_ORDER.join(' / ')}。
+       无法确定时填写 "initialized"，即可允许流程从头重新执行。`;
+
+  return `${head}${state.error ? `\n原因：${state.error}` : ''}
+
+重复运行命令无法解决该问题，需要手动修复状态文件：
+
+1. 打开项目根目录下的 .fancy-deployed
+2. ${state.status === DEPLOYED_STATUS.CORRUPT
+      ? '确认文件是否被截断或意外修改（写入过程中断电、编辑器异常退出等均可能导致）'
+      : `找到 "phase" 那一行${state.phase ? `（当前值 "${state.phase}"）` : ''}，改成下面任一合法值`}
+${phaseHelp}
+4. 修复完成后重新执行原命令
+
+备选方案（会丢失配置，请谨慎使用）：
+5. 删除 .fancy-deployed 后重新运行 /fancy-bootstrap 重建。
+   注意：该操作会丢失 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;
+}