@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/patch-driver.js

@@ -0,0 +1,390 @@
+/**
+ * patch-driver.js —— 用户意见 → llm_wiki 影响分析 → DSH LLM 修订
+ *
+ * 设计原则：
+ *   - 影响分析先于修改；分析结果不可靠时按“有影响”处理，要求用户确认。
+ *   - patch 只改已生成阶段的事实源 JSON，不创建未生成阶段，不直接改 wiki。
+ *   - 修改后按阶段级联校验：改骨架就校验骨架+血肉+节奏；只改血肉就校验血肉+节奏。
+ *   - 纯函数（提示词、解析、阶段检测）与网络/LLM 调用分离，方便测试。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { referenceLogPromptBlock } from './scripts/reference-log.js';
+
+export const PATCH_STAGE_ORDER = ['skeleton', 'flesh', 'rhythm'];
+export const PATCH_STAGE_LABEL = { skeleton: '骨架', flesh: '血肉', rhythm: '节奏', writing: '写作' };
+export const PATCH_STAGE_DIR = { skeleton: '骨架', flesh: '血肉', rhythm: '节奏', writing: '写作' };
+
+const SRC = ['设定', 'raw', 'sources'];
+
+export function patchStageDir(projectRoot, stage) {
+  return join(projectRoot, ...SRC, PATCH_STAGE_DIR[stage] || stage);
+}
+
+function jsonFilesIn(dir) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter((name) => name.endsWith('.json') && !name.startsWith('.'))
+      .sort()
+      .map((name) => join(dir, name));
+  } catch {
+    return [];
+  }
+}
+
+/** 当前已经产出、可以被 patch 的结构化阶段。 */
+export function detectGeneratedStages(projectRoot) {
+  const stages = [];
+  if (existsSync(join(patchStageDir(projectRoot, 'skeleton'), '实体.json'))) stages.push('skeleton');
+  if (jsonFilesIn(patchStageDir(projectRoot, 'flesh')).length > 0) stages.push('flesh');
+  if (jsonFilesIn(patchStageDir(projectRoot, 'rhythm')).length > 0) stages.push('rhythm');
+  return stages;
+}
+
+/** 写作阶段只提示，不自动 patch。 */
+export function hasWritingFiles(projectRoot) {
+  const dir = patchStageDir(projectRoot, 'writing');
+  if (!existsSync(dir)) return false;
+  try {
+    return readdirSync(dir).some((name) => /^第\d+章\.md$/.test(name));
+  } catch {
+    return false;
+  }
+}
+
+/** patch 的事实源文件：只收各阶段顶层 JSON，派生文件（细纲/档案）不算。 */
+export function collectPatchFiles(projectRoot, stages) {
+  const out = [];
+  for (const stage of stages || []) {
+    if (PATCH_STAGE_ORDER.indexOf(stage) < 0) continue;
+    for (const file of jsonFilesIn(patchStageDir(projectRoot, stage))) out.push(file);
+  }
+  return out;
+}
+
+/** 文件快照：path → 内容。 */
+export function snapshotPatchFiles(files) {
+  const map = new Map();
+  for (const file of files || []) {
+    try { map.set(file, readFileSync(file, 'utf-8')); } catch { /* ignore */ }
+  }
+  return map;
+}
+
+/** 和快照相比，哪些阶段发生了实际变化（含新增 JSON 文件）。 */
+export function changedPatchStages(projectRoot, stages, before) {
+  const changed = [];
+  for (const stage of stages || []) {
+    const dir = patchStageDir(projectRoot, stage);
+    const files = jsonFilesIn(dir);
+    const prefix = dir + '/';
+    const deleted = before
+      ? [...before.keys()].some((file) => file.startsWith(prefix) && !existsSync(file))
+      : false;
+    const modified = files.some((file) => {
+      if (!before || !before.has(file)) return true;
+      try { return readFileSync(file, 'utf-8') !== before.get(file); } catch { return true; }
+    });
+    if (deleted || modified) changed.push(stage);
+  }
+  return changed;
+}
+
+/** 修改意见 → 影响分析提示词。 */
+export function buildImpactAnalysisPrompt(opts) {
+  const o = opts || {};
+  const userRequest = String(o.userRequest || '').trim();
+  const stages = Array.isArray(o.generatedStages) ? o.generatedStages : [];
+  return [
+    '你是小说设定影响分析器。用户提出了一条对当前故事的修改意见，请判断它会带来什么影响。',
+    '',
+    '## 用户意见',
+    userRequest,
+    '',
+    '## 当前已生成阶段',
+    stages.length ? stages.map((s) => '- ' + (PATCH_STAGE_LABEL[s] || s)).join('\n') : '- （无）',
+    '',
+    '## 你的任务',
+    '只基于当前 LLM Wiki 中真实存在的页面分析，不要发明页面里没有的设定。',
+    '重点检查：',
+    '- 角色关系类型与关系阶段；',
+    '- 冲突参与方、主线/支线；',
+    '- 伏笔的埋设与回收；',
+    '- 章节时间线、角色状态、信息差；',
+    '- 已写正文是否出现与该修改相反的既成事实。',
+    '',
+    '## 输出格式（必须是 JSON，不要只写散文）',
+    '```json',
+    '{',
+    '  "verdict": "ok" | "impact" | "unknown",',
+    '  "confidence": "high" | "medium" | "low",',
+    '  "summary": "一句话结论",',
+    '  "effects": ["具体影响 1", "具体影响 2"],',
+    '  "affected_pages": ["页面 ID 或标题"],',
+    '  "affected_stages": ["skeleton", "flesh", "rhythm", "writing"],',
+    '  "recommendation": "建议怎么处理"',
+    '}',
+    '```',
+    '',
+    '规则：',
+    '- 只有确认没有任何矛盾、没有下游变化时，才允许 verdict="ok"。',
+    '- 不确定时必须 verdict="unknown"，不能猜 ok。',
+    '- 如果修改会改变关系，必须检查双方关系类型、关系阶段、章节落点和正文。',
+    '- 如果修改只影响措辞、不影响事实和下游引用，才可以 ok。',
+  ].join('\n');
+}
+
+/** llm_wiki /chat 的深度分析请求体。 */
+export function buildImpactAnalysisRequest(opts) {
+  const o = opts || {};
+  return {
+    message: buildImpactAnalysisPrompt(o),
+    mode: 'deep',
+    retrievalMode: 'smart',
+    tools: { wiki: true, web: false, anytxt: false },
+    topK: 10,
+    includeContent: true,
+    history: [],
+    historyExplicit: true,
+    persistSession: false,
+    stream: false,
+  };
+}
+
+/** 从文本里提取第一个完整 JSON 对象（容忍代码块/前后说明）。 */
+export function extractFirstJsonObject(text) {
+  const source = String(text || '');
+  for (let start = source.indexOf('{'); start >= 0; start = source.indexOf('{', start + 1)) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < source.length; i++) {
+      const ch = source[i];
+      if (inString) {
+        if (escaped) { escaped = false; continue; }
+        if (ch === '\\') { escaped = true; continue; }
+        if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') { inString = true; continue; }
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          try { return JSON.parse(source.slice(start, i + 1)); } catch { break; }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function asStringArray(value) {
+  const format = (x) => {
+    if (x === null || x === undefined) return '';
+    if (typeof x === 'string') return x.trim();
+    if (typeof x === 'object') {
+      try { return JSON.stringify(x); } catch { return String(x); }
+    }
+    return String(x);
+  };
+  if (Array.isArray(value)) return value.map(format).filter(Boolean);
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  if (value && typeof value === 'object') return [format(value)];
+  return [];
+}
+
+function normalizeVerdict(value) {
+  const v = String(value || '').trim().toLowerCase();
+  if (v === 'ok' || v === 'no-impact' || v === 'no_impact' || v === 'no impact' || v === 'pass' || v === '无影响') return 'ok';
+  if (v === 'impact' || v === 'affected' || v === 'change' || v === '有影响') return 'impact';
+  return 'unknown';
+}
+
+function normalizeConfidence(value) {
+  const v = String(value || '').trim().toLowerCase();
+  if (v === 'high' || v === 'medium' || v === 'low') return v;
+  if (v === '高' || v === '高置信') return 'high';
+  if (v === '中' || v === '中置信') return 'medium';
+  if (v === '低' || v === '低置信') return 'low';
+  return 'medium';
+}
+
+/**
+ * 解析影响分析答案。
+ * JSON 优先；没有 JSON 时接受 PATCH_IMPACT/VERDICT 标记。
+ * 无法解析时返回 unknown（宁可多让用户确认一次，也不自动改错）。
+ */
+export function parseImpactAnalysis(text) {
+  const raw = String(text || '').trim();
+  const json = extractFirstJsonObject(raw);
+  if (json && typeof json === 'object') {
+    return {
+      verdict: normalizeVerdict(json.verdict || json.status || json.result),
+      confidence: normalizeConfidence(json.confidence),
+      summary: String(json.summary || json.why || '').trim(),
+      effects: asStringArray(json.effects || json.impact || json.impacts),
+      affectedPages: asStringArray(json.affected_pages || json.affectedPages),
+      affectedStages: asStringArray(json.affected_stages || json.affectedStages)
+        .map((s) => ({ 骨架: 'skeleton', 血肉: 'flesh', 节奏: 'rhythm', 写作: 'writing', 正文: 'writing' }[s] || s))
+        .filter((s) => PATCH_STAGE_ORDER.indexOf(s) >= 0 || s === 'writing'),
+      recommendation: String(json.recommendation || '').trim(),
+      raw,
+    };
+  }
+
+  const marker = /(?:PATCH_IMPACT|VERDICT|影响结论)\s*[:：]\s*(OK|IMPACT|UNKNOWN|无影响|有影响|不确定)/i.exec(raw);
+  if (marker) {
+    const v = marker[1].toLowerCase();
+    return {
+      verdict: (v === 'ok' || v === '无影响') ? 'ok' : (v === 'unknown' || v === '不确定' ? 'unknown' : 'impact'),
+      confidence: 'medium',
+      summary: raw.slice(0, 300),
+      effects: [],
+      affectedPages: [],
+      affectedStages: [],
+      recommendation: '',
+      raw,
+    };
+  }
+
+  return {
+    verdict: 'unknown',
+    confidence: 'low',
+    summary: raw ? raw.slice(0, 300) : '影响分析没有返回内容',
+    effects: [],
+    affectedPages: [],
+    affectedStages: [],
+    recommendation: '影响分析结果无法解析，请人工确认后再修改。',
+    raw,
+  };
+}
+
+/** 只有明确的 ok + high 才自动改；其余都让用户确认。 */
+export function shouldAutoApplyImpact(impact) {
+  return !!impact
+    && impact.verdict === 'ok'
+    && impact.confidence === 'high'
+    && (!impact.effects || impact.effects.length === 0)
+    && (!impact.affectedPages || impact.affectedPages.length === 0)
+    && (!impact.affectedStages || impact.affectedStages.length === 0);
+}
+
+export function formatImpactForUser(impact) {
+  const i = impact || {};
+  if (i.verdict === 'ok') {
+    return '影响分析：未发现明确的下游影响。' + (i.summary ? '\n\n' + i.summary : '');
+  }
+  const effects = Array.isArray(i.effects) ? i.effects : [];
+  const affectedPages = Array.isArray(i.affectedPages) ? i.affectedPages : [];
+  const affectedStages = Array.isArray(i.affectedStages) ? i.affectedStages : [];
+  const lines = ['影响分析：这次修改可能会影响以下内容。'];
+  if (i.summary) lines.push('', i.summary);
+  if (effects.length) {
+    lines.push('', '具体影响：');
+    for (const x of effects) lines.push('- ' + x);
+  }
+  if (affectedPages.length) {
+    lines.push('', '涉及页面：' + affectedPages.join('、'));
+  }
+  if (affectedStages.length) {
+    lines.push('', '涉及阶段：' + affectedStages.map((s) => PATCH_STAGE_LABEL[s] || s).join('、'));
+  }
+  if (i.recommendation) lines.push('', '建议：' + i.recommendation);
+  if (!effects.length && !affectedPages.length && i.summary) {
+    lines.push('', '（模型没有列出具体条目，建议按“有影响”处理。）');
+  }
+  return lines.join('\n');
+}
+
+function stageScopeLines(opts) {
+  const o = opts || {};
+  const stages = Array.isArray(o.generatedStages) ? o.generatedStages : [];
+  const patchStages = Array.isArray(o.patchStages) ? o.patchStages : [];
+  const lines = [];
+  lines.push('已生成阶段：' + (stages.length ? stages.map((s) => PATCH_STAGE_LABEL[s] || s).join('、') : '无'));
+  lines.push('本次允许修改阶段：' + (patchStages.length ? patchStages.map((s) => PATCH_STAGE_LABEL[s] || s).join('、') : '无'));
+  if (!stages.includes('rhythm')) {
+    lines.push('节奏阶段尚未生成：**不要创建节奏目录或节奏 JSON**。');
+  }
+  if (o.hasWriting) {
+    lines.push('写作阶段已有正文：**不要改正文**；如有影响，在报告里列出受影响章节，由用户另行处理。');
+  }
+  return lines;
+}
+
+/** DSH LLM 的 patch 提示词。 */
+export function buildPatchPrompt(opts) {
+  const o = opts || {};
+  const userRequest = String(o.userRequest || '').trim();
+  const impact = o.impact || null;
+  const patchStages = Array.isArray(o.patchStages) ? o.patchStages : [];
+  const validationErrors = Array.isArray(o.validationErrors) ? o.validationErrors : [];
+  const attempt = o.attempt || 1;
+  const lines = [];
+  lines.push('# 本轮任务：按用户意见修订已生成的故事设定');
+  lines.push('');
+  lines.push('这是第 ' + attempt + ' 轮 patch。');
+  lines.push('');
+  lines.push('## 用户意见');
+  lines.push(userRequest);
+  lines.push('');
+  if (impact) {
+    lines.push('## llm_wiki 影响分析');
+    lines.push(formatImpactForUser(impact));
+    lines.push('');
+  }
+  lines.push('## 阶段边界（硬约束）');
+  lines.push(stageScopeLines(o));
+  lines.push('');
+  lines.push('只允许修改这些阶段的事实源 JSON：');
+  for (const stage of patchStages) {
+    lines.push('- `' + join('设定/raw/sources', PATCH_STAGE_DIR[stage]) + '/`（' + (PATCH_STAGE_LABEL[stage] || stage) + '）');
+  }
+  lines.push('');
+  lines.push('## 允许改的文件');
+  for (const file of (o.files || [])) {
+    lines.push('- `' + file + '`');
+  }
+  lines.push('');
+  lines.push('## 修改规则');
+  lines.push('1. 只改与用户意见直接相关的最小字段；不要重写整个文件，不要删无关条目。');
+  lines.push('2. 保留所有 id、name、枚举、章节号、已有引用；新增/改名会制造下游错误。');
+  lines.push('3. 关系类型改变时，必须同步骨架 `关系.json` 和血肉 `角色.json` 的 `relationships[]`。');
+  lines.push('4. 关系阶段改变时，只有在节奏阶段已生成时才改 `时序映射.json` 的 `relationship_timeline`；未生成时不要创建。');
+  lines.push('5. 血肉阶段不要写章节号；章节落点属于节奏阶段。');
+  lines.push('6. 不要修改 `设定/wiki/`、`模板/`、`references/`、校验脚本、`档案/`、`节奏/细纲/`。');
+  lines.push('7. 不要修改写作正文（`写作/第NNN章.md`）。');
+  lines.push('8. 改完就停，不要运行校验脚本；插件会跑阶段校验器并把错误回喂。');
+  lines.push('');
+  if (validationErrors.length) {
+    lines.push('## 上一轮校验错误（只修这些）');
+    lines.push('');
+    for (const e of validationErrors) {
+      lines.push('- [' + (e.code || 'ERROR') + '] ' + (e.stage ? '[' + (PATCH_STAGE_LABEL[e.stage] || e.stage) + '] ' : '') +
+        (e.path || '(无路径)') + '：' + (e.message || '') + (e.hint ? '（' + e.hint + '）' : ''));
+    }
+    lines.push('');
+    lines.push('**只修上面点名的字段**，其余内容保持原样。');
+    lines.push('');
+  }
+  lines.push(referenceLogPromptBlock('patch', { type: 'patch' }, {
+    allowedFileText: '除本阶段允许修改的事实源 JSON 外，`设定/.reference-decisions.md` 是本轮唯一允许写的额外文件；不要修改 wiki、模板、references 目录或其它阶段。',
+  }));
+  lines.push('## 交付');
+  lines.push('');
+  lines.push('改完用一句话说明改了哪些文件/字段，然后停下。');
+  return lines.join('\n');
+}
+
+/** 修改后需要校验的阶段：从最早被改的结构化阶段，到所有已生成的下游阶段。 */
+export function buildPatchValidationStages(changedStages, generatedStages) {
+  const generated = Array.isArray(generatedStages) ? generatedStages : [];
+  const changed = Array.isArray(changedStages) ? changedStages : [];
+  const structured = PATCH_STAGE_ORDER.filter((s) => generated.includes(s));
+  const changedStructured = changed.filter((s) => PATCH_STAGE_ORDER.includes(s));
+  if (!structured.length || !changedStructured.length) return [];
+  const earliest = Math.min(...changedStructured.map((s) => PATCH_STAGE_ORDER.indexOf(s)));
+  return structured.filter((s) => PATCH_STAGE_ORDER.indexOf(s) >= earliest);
+}

package/plugins/fancy-story-builder/prompts/01-skeleton-prompt.md

@@ -18,8 +18,8 @@
 产出 4 个 JSON 文件到 `设定/raw/sources/骨架/`：
 
 1. `框架.json` —— 定数量（quota）、定卷比例（volume_ratio）、记录公式推导（derivations）
-2. `实体.json` —— 12 类实体清单（id + name + 枚举）
-3. `关系.json` —— 9 类关系清单（ID 引用）
+2. `实体.json` —— 12 类常规实体清单（id + name + 枚举）+ 可选的 `other_entities` 题材扩展实体
+3. `关系.json` —— 9 类常规关系清单（ID 引用）+ 可选的 `other_relations`
 4. `层级.json` —— 卷/幕/主线/支线的卷级归属
 
 **本阶段回答**：有哪些实体、实体如何连接、有多少、分几卷几幕。
@@ -49,6 +49,7 @@ ${input_snapshot_block}
 **注**：
 
 - **目标章节**是全部数量公式的输入（T）。先算 T，后面所有数量都从 T 推。
+- **选题方向 + 11 项方向设计**是扫榜报告里选定方向的设计（一句话定位、读者与情绪价值、金手指、核心设定、爽点模式、情绪价值曲线、开篇切入点、节奏规划、人物设定、差异化策略、风险与验证）。**逐项原样抄进 `input_snapshot`**：血肉、节奏阶段都从这份快照读它，不必也不得自行重设计。
 - **一句话故事**决定主角是谁、核心冲突是什么；**核心冲突**决定要配几个核心冲突、几个核心反派。
 - **硬门禁**与**反套路**是硬约束：配实体类型、势力性质、结局走向时不得违背。
 
@@ -71,7 +72,7 @@ ${input_snapshot_block}
 
 > 1. **不得出现任何章节号**（`chapter` / `ch` / `start` / `end` / `appearance_chapters` / `chapter_range` / `buried_chapter` / `recovered_chapter` / `key_nodes` 等，完整清单见 glossary 第六节）。骨架脚本会拦截 `SKELETON_CHAPTER_FORBIDDEN`。
 >
-> 2. **id+name 必须严格遵守 glossary 枚举**。例如 `character_type` 只允许"主角/贯穿级核心配角/卷级重要配角/贯穿级核心反派/卷级反派"，不能自创。ENUM 校验会拦截。
+> 2. **常规实体的枚举必须遵守 glossary**。例如 `character_type` 只允许"主角/贯穿级核心配角/卷级重要配角/贯穿级核心反派/卷级反派"，不能自创。题材特有存在不要硬塞进 `characters`，改写进可选的 `other_entities`（`kind` 是自由文本，如 灵魂/神魂/器灵/妖灵/概念体）。ENUM 校验会拦截常规枚举。
 >
 > 3. **引用关系只允许 id，不允许编名字**。关系.json 的 `from`/`to`/`character`/`faction`/`item`/`location`/`ending`/`main_line`/`branch` 必须是 `C001`/`X001`/`F001` 这种 id，不是名字。`SKELETON_REF_MISSING` 会拦截。
 >
@@ -79,9 +80,9 @@ ${input_snapshot_block}
 >
 > 5. **公式推导（`derivations`）必须 30 条齐全**，每条 `{formula, range_low, range_high, note}`，且 `formula` 逐字与 `formulas-skeleton.json` 一致。`DERIVATION_MISSING` / `DERIVATION_RANGE_MISMATCH` 会拦截。
 >
-> 6. **关系类型只能取第 8.2 节各自那套词表**。`character_relations[].relation_kind` 取 12 值（血缘/师徒/雇佣/服从/提携/合作/利益交换/利用/对立/敌对/竞争/中立）；`faction_membership[].member_relation` 取 8 值（利益交换/合作/对立/利用/师徒/雇佣/血亲/无）；`faction_relations[].relation_type` 取 4 值（合作/对立/利用/中立）；`main_line_branch_relation[].relation_kind` 取 6 值（促成/阻碍/并行/揭示/收束/依存）。不要写"盟友""对手""上下级""血亲"——它们不在对应词表里，ENUM 会拦截。
+> 6. **关系类型只能取第 8.2 节各自那套词表**。`character_relations[].relation_kind` 取 13 值（血缘/师徒/雇佣/服从/提携/合作/利益交换/利用/对立/敌对/竞争/中立/其他）；用 `其他` 时必须填 `relation_label` 写清具体关系（如 附身/寄生/契约/共生）。非人物实体的关系写 `other_relations`；`faction_membership[].member_relation` 取 8 值（利益交换/合作/对立/利用/师徒/雇佣/血亲/无）；`faction_relations[].relation_type` 取 4 值（合作/对立/利用/中立）；`main_line_branch_relation[].relation_kind` 取 6 值（促成/阻碍/并行/揭示/收束/依存）。不要写"盟友""对手""上下级""血亲"——它们不在对应词表里，ENUM 会拦截。
 >
-> 7. **实体名要是真名字，内容要是真内容**。名字写"陆子仲"而不是"主角1"；`input_snapshot` 的 `core_summary` / `core_conflict` 要写清一个具体处境，而不是"核心概述。"。`NAME_PLACEHOLDER` / `TEXT_TOO_SHORT` / `TEXT_PLACEHOLDER` 会拦截。
+> 7. **实体名要是真名字，内容要是真内容**。名字写"陆子仲"而不是"主角1"；`input_snapshot` 的 `positioning` / `core_conflict` 要写清一个具体处境，而不是"核心概述。"。`NAME_PLACEHOLDER` / `TEXT_TOO_SHORT` / `TEXT_PLACEHOLDER` 会拦截。
 >
 > 8. **实体条数必须与框架的 quota 完全一致**。框架里声明 `character_counts.protagonist = 2`，实体清单里就恰好要有 2 个 `type=主角` 的角色；多一个少一个都会报 `QUOTA_MISMATCH`。
 
@@ -124,7 +125,7 @@ ${benchmark_refs_block}
 | 顶层键 | 写什么 |
 |---|---|
 | `capacity` | `{target_chapters, target_words, avg_words_per_chapter}` |
-| `input_snapshot` | 任务输入 8 项，原样照抄 |
+| `input_snapshot` | 任务输入 17 项（书名/题材/一句话定位/核心冲突/选题方向/11 项方向设计/硬门禁/反套路），原样照抄 |
 | `quota` | 每类实体要多少个（见下） |
 | `volume_ratio` | 每卷占多少章，数组 |
 | `derivations` | 30 条公式推导，对象 |
@@ -278,7 +279,7 @@ Level 3（依赖实体数）：
 <!-- contract:file:实体 -->
 ## 七、实体.json 的字段契约
 
-**顶层**：12 个数组　**模板**：`模板/骨架/实体模板.json`
+**顶层**：12 个常规数组 + 可选的 `other_entities`　**模板**：`模板/骨架/实体模板.json`
 
 ### 7.1 每类实体的字段
 
@@ -296,12 +297,11 @@ Level 3（依赖实体数）：
 | `world_rules` | R / I / SR | `id` `name` `category` |
 | `main_lines` | M | `id` `name` |
 | `branches` | B | `id` `name` `type` |
+| `other_entities`（可选） | O | `id` `name` `kind`（`note` 可选） |
 
-**id 规则**：`C001`/`X001`/`F001`/`L001`/`P001`/`E001`/`FS001`/`CL001`/`PL001`/`M001`/`B001`，三位数从 001 连续递增，不跳号。
+**id 规则**：`C001`/`X001`/`F001`/`L001`/`P001`/`E001`/`FS001`/`CL001`/`PL001`/`M001`/`B001`，三位数从 001 连续递增，不跳号。可选扩展实体用 `O001` 起单独编号。
 **同一个数组里的 id 必须两两不同 —— 不管 `type` / `scale` / `kind` 是不是同一类。**
-一个数组只有一个 id 前缀时，**不同类别也共用同一个编号空间**，必须合在一起连续编号：
-`climaxes` 的小高潮 / 中高潮 / 大高潮共用 `CL`，要写成 `CL001`…`CL079` 这样一路排下来，
-**不能按类型各编一套**（各编一套必然撞号，`ID_DUP` 会拦截 —— 2026-10-24 实测就是这么失败的）。
+一个数组只有一个 id 前缀时，**不同类别也共用同一个编号空间**，必须合在一起连续编号：`climaxes` 的小高潮 / 中高潮 / 大高潮共用 `CL`，要写成 `CL001`…`CL079` 这样一路排下来，**不能按类型各编一套**（各编一套必然撞号，`ID_DUP` 会拦截 —— 2026-10-24 实测就是这么失败的）。
 世界观的规则按分类用不同前缀：**R** = 核心规则、**I** = 信息规则、**SR** = 社会规则
 （`WORLD_RULE_CATEGORY_MISMATCH` 会核对前缀与所属数组）；这三个前缀各自独立编号，互不冲突。
 
@@ -325,14 +325,16 @@ Level 3（依赖实体数）：
 | `pleasures[].kind` | 打脸 / 收获 / 身份 / 情感 / 智力 / 探索 / 团战 |
 | `world_rules[].category` | 核心规则 / 信息规则 / 社会规则 |
 | `branches[].type` | 角色成长型 / 身份揭示型 / 背景揭示型 |
+| `other_entities[].kind` | **自由文本**：灵魂 / 神魂 / 器灵 / 妖灵 / 鬼魂 / 概念体 / 其他题材特有类别 |
 
 ### 7.3 关键约束
 
 - **全书级结局恰好 1 个**（`level=全书级`），其余是卷级（`BOOK_ENDING_COUNT` 会查）
 - **每类实体的条数严格等于框架 quota 里对应字段的值**（`QUOTA_MISMATCH` 会查）
 - **id 与 name 都不能重复**（`ID_DUP` / `NAME_DUP`）；**角色 / 势力 / 冲突 / 地点**四类之间也不能同名（`CROSS_TYPE_NAME_DUP` warning）
+- **同一实体只建一条**：本名/正式名优先。称呼（哥哥/父亲/老师/老板）、绰号、简称、集团/公司/大学等后缀不要另建实体；归一化后重名会报 `NAME_ALIAS_SUSPECT` warning
 - **名字是真名**：写"陆子仲"不写"主角1"（`NAME_PLACEHOLDER` 会查）
-- **不许有描述性字段**：实体只写 id + name + 枚举，描述属于血肉阶段（`EXTRA_FIELD` 会查）
+- **常规实体只写 id + name + 枚举**；`other_entities` 只写 `id` / `name` / `kind`（可带一句 `note`）。描述属于血肉阶段（`EXTRA_FIELD` 会查）
 - **不许出现章节号**（`SKELETON_CHAPTER_FORBIDDEN` 会查）
 - **不许同质化**：不同实体的同一字段不能几乎一字不差（`TEXT_DUPLICATE` 会查）
 
@@ -341,13 +343,14 @@ Level 3（依赖实体数）：
 <!-- contract:file:关系 -->
 ## 八、关系.json 的字段契约
 
-**顶层**：9 个数组　**模板**：`模板/骨架/关系模板.json`
+**顶层**：9 个常规数组 + 可选的 `other_relations`　**模板**：`模板/骨架/关系模板.json`
 
 ### 8.1 每类关系的字段
 
 | 数组 | 一行代表什么 | 字段 |
 |---|---|---|
-| `character_relations` | 两个角色之间的关系 | `from` `to` `relation_kind` |
+| `character_relations` | 两个角色之间的关系 | `from` `to` `relation_kind`；`relation_kind=其他` 时加 `relation_label` |
+| `other_relations`（可选） | 非人物实体参与的关系 | `from`（O 开头）`to`（C/O 开头）`relation_label`（必填）`description`（可选） |
 | `faction_membership` | 一个角色属于一个势力 | `character` `faction` `member_relation` `position_level` |
 | `faction_relations` | 两个势力之间的关系 | `from` `to` `relation_type` |
 | `conflict_participants` | 一个冲突的参战方 | `conflict` `protagonist_side` `main_antagonist` `secondary_antagonist` `third_party` |
@@ -359,7 +362,7 @@ Level 3（依赖实体数）：
 
 ### 8.2 关系类型词表
 
-**`character_relations[].relation_kind`** —— 只从这 12 个值里选：
+**`character_relations[].relation_kind`** —— 只从这 13 个值里选：
 
 | 词表值 | 什么时候用 |
 |---|---|
@@ -375,8 +378,11 @@ Level 3（依赖实体数）：
 | 敌对 | 敌视仇视 |
 | 竞争 | 争夺同一目标 |
 | 中立 | 无特殊立场 |
+| 其他 | 词表外的题材特有角色关系（附身/寄生/契约/共生…）；**必须同时填 `relation_label`**，能归入前 12 类的不要滥用 |
 
-**不要写的**（不在词表，ENUM 拦截）：`盟友`→写 `合作`；`对手`→写 `对立` 或 `敌对`；`上下级`→写 `师徒` / `雇佣` / `服从`；`血亲`→写 `血缘`。
+**不要写的**（不在词表，ENUM 拦截）：`盟友`→写 `合作`；`对手`→写 `对立` 或 `敌对`；`上下级`→写 `师徒` / `雇佣` / `服从`；`血亲`→写 `血缘`；`附身` 不是词表值，人物之间写 `其他` + `relation_label: 附身`，灵魂/神魂等非人物存在写进 `other_relations`。
+
+**`other_relations[].relation_label`** —— 自由文本，但必须具体：`附身` / `寄宿` / `共生` / `契约` / `镇压` / `吞噬` / `前世` 等。`from` 必须是 `other_entities` 的 id，`to` 可指人物或其他实体。
 
 **`main_line_branch_relation[].relation_kind`** —— 只从这 6 个值里选：`促成` / `阻碍` / `并行` / `揭示` / `收束` / `依存`。
 
@@ -385,7 +391,7 @@ Level 3（依赖实体数）：
 **`faction_relations[].relation_type`** —— 只从这 4 个值里选：`合作` / `对立` / `利用` / `中立`。
 
 > ⚠️ **这是四套互不相同的词表，别串用**：
-> `relation_kind`（角色关系，12 值）/ `member_relation`（成员关系，8 值）/ `relation_type`（势力关系，4 值）/ `main_line_branch_relation[].relation_kind`（支线挂主线，6 值）。
+> `relation_kind`（角色关系，13 值，含扩展出口 `其他`）/ `member_relation`（成员关系，8 值）/ `relation_type`（势力关系，4 值）/ `main_line_branch_relation[].relation_kind`（支线挂主线，6 值）。
 > 拿 `relation_kind` 的值去填 `member_relation` 或 `relation_type` 一律报 ENUM
 > （tt5 实测 2026-10-27：9 条 ENUM 错误，2 个批次重写，理由全是"从角色关系词表里取值"）。
 
@@ -399,7 +405,8 @@ Level 3（依赖实体数）：
 - **每个实体都要连上**：`G_ISOLATED` 会查孤立节点 —— 角色、冲突、势力都得有关系
 - **`faction_relations` 的行数 = `quota.faction_relation_count`（每对关系一行）或它的 2 倍**（对立关系写双向两行时）。`quota.faction_relation_count` 记的是**无向关系对数**，不是行数
 - **每条支线都要挂到主线上**：`main_line_branch_relation` 一行代表"一条支线挂到主线上"，每个支线 id 都要出现（`BRANCH_MAINLINE_UNLINKED` 会查）；反过来每条主线也要挂到支线（`MAINLINE_BRANCH_UNLINKED` 会查）
-- **只写 ID 引用 + 关系类型枚举**，不写描述（描述属于血肉阶段，`EXTRA_FIELD` 会查）
+- **只写 ID 引用 + 关系类型/标签**，不写大段描述（描述属于血肉阶段，`EXTRA_FIELD` 会查）
+- **`other_relations` 不能自环**：`from` 与 `to` 不能是同一个 id；每个 `other_entities` 至少要有一条关系，不能是孤立设定（`G_ISOLATED` 会查）
 
 ---
 
@@ -441,6 +448,7 @@ Level 3（依赖实体数）：
 | 占位符 | `PLACEHOLDER` | error |
 | ID 唯一 | `ID_DUP` | error |
 | 名称唯一 | `NAME_DUP` | error |
+| 名称软重复 | `NAME_ALIAS_SUSPECT` | warning |
 | derivations 完整性 | `DERIVATION_MISSING` / `DERIVATION_EXTRA` | error |
 | derivations 区间 | `DERIVATION_RANGE_MISMATCH` | error |
 | derivations 公式文本 | `DERIVATION_FORMULA_TEXT` | warning |
@@ -485,6 +493,7 @@ Level 3（依赖实体数）：
 | `MAINLINE_BRANCH_UNLINKED` | 有主线没挂任何支线 | 给这条主线补支线关系 |
 | `ID_DUP` | 同文件 ID 重复 / 关系组合重复 | 重新编号 / 删重复 |
 | `NAME_DUP` | 名称重复 | 改名 |
+| `NAME_ALIAS_SUSPECT`（warning） | 归一化后同名，疑似同一实体的全称/简称/别名 | 确认后只保留正式名，合并另一条 |
 | `CHARSET_KO` / `CHARSET_JP` | 含韩文/日文 | 删除 |
 | `PLACEHOLDER` | 含占位符 | 改为具体值 |
 | `DERIVATION_MISSING` | 缺推导记录 | 补 derivations |
@@ -508,10 +517,11 @@ Level 3（依赖实体数）：
 | `G_REL_ASYMMETRIC` | 势力关系不对称 | 统一双向 |
 | `QUANTITY_MISMATCH`（warning） | 数量偏离公式区间 | 在 note 写理由，或调回区间 |
 | `WORLD_RULE_CATEGORY_MISMATCH` | 规则 id 前缀与 `category` 字段不匹配 | R→核心规则，I→信息规则，SR→社会规则（骨架只有 `world_rules` 一个数组） |
-| `CROSS_TYPE_NAME_DUP`（warning） | 跨类型同名 | 改名，避免跨类型歧义 |
+| `CROSS_TYPE_NAME_DUP`（warning） | 跨类型同名（含归一化后的全称/简称） | 改名，避免跨类型歧义 |
 | `EMPTY_HARD_CONSTRAINTS` | 硬门禁为空 | 至少写一条硬约束，或确认任务输入本就没有 |
 | `NO_SELF_RELATION` | 关系两端相同 | 删掉自环 |
 | `REL_KIND_CONFLICT` | 同一有序对写了两种关系类型 | 保留一种 |
+| `REL_LABEL_REQUIRED` | `relation_kind=其他` 或 `other_relations` 缺 `relation_label` | 补具体关系名（附身/寄生/契约/共生） |
 | `REL_ASYMMETRIC_INCOMPATIBLE` | 同一对角色正反两个方向的关系语义冲突 | 统一成一个意思 |
 | `REL_KIND_META_DRIFT` | 关系词表与元数据不同步 | 脚本/词表不同步，停下来上报 |
 | `NAME_PLACEHOLDER` | 实体名是"主角1"这类占位名 | 换成有辨识度的专名 |