@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/plugins/fancy-story-builder/references/index.md

@@ -0,0 +1,581 @@
+# 网文生成系统 · 总索引
+
+> 本文件是整个体系的使用者入口。回答：这套体系有哪些文件、每个文件干什么、文件之间怎么依赖、常见任务怎么查。
+> 本文件不定义方法、不写公式、不写验证逻辑、不定义数据结构。
+
+---
+
+## 一、体系概览
+
+四阶段单向流水线，每个阶段读上游、产出本阶段文件、由脚本校验、通过后进入下游。
+
+```
+任务输入
+    │
+    ▼
+┌─────────────────────────────┐
+│ 骨架：有什么、有多少、怎么连  │ 4 个 JSON
+│ （无章节号）                │
+└──────────────┬──────────────┘
+               │ 只读
+               ▼
+┌─────────────────────────────┐
+│ 血肉：每个实体具体什么样      │ 8 个 JSON
+│ （无章节号）                │
+└──────────────┬──────────────┘
+               │ 只读
+               ▼
+┌─────────────────────────────┐
+│ 节奏：什么时间发生什么        │ 4 个 JSON
+│ （章节号唯一出现处）          │
+└──────────────┬──────────────┘
+               │ 只读
+               ▼
+┌─────────────────────────────┐
+│ 写作：具体怎么写             │ 逐章正文 + 台账
+│ （会变的阶段）              │
+└─────────────────────────────┘
+```
+
+**核心规则**：
+- 下游只读上游，不写上游
+- 新 ID 只能出现在骨架阶段
+- 章节号只能出现在节奏阶段
+- 每个文件生成后立即单检，不过不进下一个
+- 每个阶段有独立的 `.stage-status.json`
+
+---
+
+## 二、文件分类
+
+五类文件，五种职责：
+
+| 类型 | 只做 | 不包含 |
+|---|---|---|
+| `glossary.md` | 定义（术语、ID、枚举、字段归属） | 方法论、公式、验证、结构 |
+| `formulas-*.json` | 量化约束 | 方法论、验证、结构 |
+| `模板/*.json` | 数据结构 | 默认值、公式、验证、示例值 |
+| `*指导/*.md` | 方法论 | 数字区间、检查清单、错误代码、数据结构 |
+| `*-validate.js` | 验证 | 方法论、硬编码公式/枚举/结构 |
+
+---
+
+## 三、全部文件清单
+
+**总计 59 个体系文件 + 本索引 = 60 个文件**。
+
+### 3.1 基础层（3 个）
+
+| 文件 | 版本 | 职责 |
+|---|---|---|
+| `references/glossary.md` | v1.3 | 术语总表：四阶段边界、术语定义、15 个 ID 前缀、26 个枚举、章节号字段清单（含 `ch`/`turning`/`resolution`）、字段归属、生命周期 |
+| `references/formulas-skeleton.json` | v1.1 | 骨架阶段 **30 条**数量公式（含 3 条 `world_rule_counts`；`ending_count` 用条件表达式；`faction_relation_count` 下界改为 n-1） |
+| `references/formulas-rhythm.json` | v1.1 | 节奏阶段 10 个节：`constraints`（7 条联合可行性，脚本强制）+ `arc_phase_ratio` / `upgrade_guides` / `bridge_guides` / `hook_guides` / `satisfaction_guides` / `expectation_guides` / `foreshadow_guides` / `outline_guides` / `faction_guides`（9 个参考节，指导文件引用，脚本不强制） |
+
+### 3.2 骨架阶段（13 个）
+
+**模板（4 个）**：
+
+| 文件 | 内容 |
+|---|---|
+| `模板/骨架/框架模板.json` | capacity / input_snapshot / quota / volume_ratio / derivations |
+| `模板/骨架/实体模板.json` | 12 类常规实体数组（characters / conflicts / factions / ... / branches）+ 可选 other_entities 题材扩展 |
+| `模板/骨架/关系模板.json` | 9 类关系数组（character_relations / faction_membership / ... / main_line_branch_relation） |
+| `模板/骨架/层级模板.json` | volumes / acts / main_line_span / branch_span |
+
+**脚本（1 个）**：
+
+| 文件 | 版本 | 能力 |
+|---|---|---|
+| `references/skeleton-validate.js` | v2.5 | 单文件 + 全量模式；从 glossary 读枚举、从 formulas 读公式、从模板读结构；无章节号、无时序；新增 `QUOTA_MISMATCH` / `BOOK_ENDING_COUNT` / `VOLUME_COUNT_MISMATCH` / `ACT_INDEX_DUP` / `SPAN_RATIO_RANGE` / **关系组合重复检查（7 类）** / `NO_SELF_RELATION` / `EMPTY_HARD_CONSTRAINTS` / `CROSS_TYPE_NAME_DUP` / `NAME_ALIAS_SUSPECT`（归一化后的全称/简称/别名软重复）/ `faction_relation_count` 一致性；图检查 import `graph-utils.js`；`evalExpr` 支持三元运算符 |
+
+**提示词（1 个）**：
+
+| 文件 | 版本 | 内容 |
+|---|---|---|
+| `prompts/01-skeleton-prompt.md` | v1.1 | 前置检查（无上游）、4 文件生成顺序、每文件循环、5 次 BLOCKED、全量 3 轮 BLOCKED；§6.3 拓扑顺序补全 `faction_relation_count`；"27 条"改为"30 条" |
+
+**指导（7 个）**：
+
+| 文件 | 职责 |
+|---|---|
+| `references/骨架指导/00-index.md` | 骨架阶段入口 |
+| `references/骨架指导/01-positioning.md` | 定位、需求矩阵、平台矩阵、一句话故事 |
+| `references/骨架指导/02-packaging.md` | 书名、简介、标签、一句话卖点 |
+| `references/骨架指导/03-entities.md` | 角色/势力/其他实体建卡方法论 |
+| `references/骨架指导/04-conflict.md` | 矛盾四重、死亡赌注、黏结剂、双线 |
+| `references/骨架指导/05-quota.md` | 数量决策方法论（在公式区间内选终值） |
+| `references/骨架指导/06-audit.md` | 骨架验证流程与问题记录 |
+
+### 3.3 血肉阶段（16 个）
+
+**模板（8 个）**：
+
+| 文件 | 内容 |
+|---|---|
+| `模板/血肉/角色模板.json` | 角色档案（描述/目标/缺陷/弧光/语言/关系/退场） |
+| `模板/血肉/冲突模板.json` | 冲突档案（描述/矛盾/升级路径/信息差/收束） |
+| `模板/血肉/势力模板.json` | 势力档案（目标/资源/内部结构/压制手段/成员详述） |
+| `模板/血肉/剧情模板.json` | 主线驱动 + 支线目标 |
+| `模板/血肉/地点模板.json` | 地点档案（空间特征/关键事件/叙事作用） |
+| `模板/血肉/结局模板.json` | 结局档案（冲突解决/反套路/余韵/章节设计/伏笔回收计划） |
+| `模板/血肉/世界观规则模板.json` | R/I/SR 三类规则 + rule_conflict_plan |
+| `模板/血肉/关键道具模板.json` | core/branch/symbolic items + details |
+
+**脚本（1 个）**：
+
+| 文件 | 版本 | 能力 |
+|---|---|---|
+| `references/flesh-validate.js` | v1.2 | 单文件 + 全量模式；`--upstream=<骨架>`；检查 `FLESH_CHAPTER_FORBIDDEN` / 引用完整性 / 名称一致性 / arc 兼容性 / details 对应 / 规则前缀 / `FLESH_GROUP_CATEGORY_MISMATCH` / `FLESH_FREETEXT_CHAPTER_REF`（warning）/ `completenessCheck` 覆盖 9 类（用文件类型作 key） |
+
+**提示词（1 个）**：
+
+| 文件 | 版本 | 内容 |
+|---|---|---|
+| `prompts/02-flesh-prompt.md` | v1.0 | 前置检查（读骨架 PASSED）、8 文件生成顺序、每文件循环、5 次 BLOCKED、全量 3 轮 BLOCKED；各文件"已填/不填"清单 |
+
+**指导（6 个）**：
+
+| 文件 | 职责 |
+|---|---|
+| `references/血肉指导/00-index.md` | 血肉阶段入口 |
+| `references/血肉指导/01-character.md` | 人物深化、缺陷五类、弧光类型、语言档案、执念 |
+| `references/血肉指导/02-worldbuilding.md` | 世界背景、力量体系、势力卡、物品卡、地点卡、设定校验 |
+| `references/血肉指导/03-relations.md` | 关系网细化、支线设计、多线管理 |
+| `references/血肉指导/04-emotion-methods.md` | 情绪弧线类型、叠加规则、引擎七环、三板斧、题材策略 |
+| `references/血肉指导/05-audit.md` | 血肉验证流程与问题记录 |
+
+### 3.4 节奏阶段（14 个）
+
+**模板（4 个）**：
+
+| 文件 | 内容 |
+|---|---|
+| `模板/节奏/章节规划模板.json` | 每章：ch / volume / act / scene_focus |
+| `模板/节奏/时序映射模板.json` | 12 类时序映射（含关系阶段）——所有章节号在此 |
+| `模板/节奏/节奏参数模板.json` | chapter_hook_rate / 三参数 / derivations |
+| `模板/节奏/章节细纲模板.json` | 每章细纲（功能/情绪/爽点/伏笔/势力/钩子/字数） |
+
+**脚本（1 个）**：
+
+| 文件 | 版本 | 能力 |
+|---|---|---|
+| `references/rhythm-validate.js` | v1.2 | 单文件 + 全量模式；**强制 `--upstream` 至少两个目录（骨架 + 血肉）**；7 条联合约束 / 章节范围 / 时序一致性 / 布局吻合 / 覆盖性 / 钩子 / 图连通 / `RHYTHM_ACT_INVALID` / `RHYTHM_COVERAGE_SKIPPED`；启动时校验业务常量 `大伏笔` / `全书级` |
+
+**提示词（1 个）**：
+
+| 文件 | 版本 | 内容 |
+|---|---|---|
+| `prompts/03-rhythm-prompt.md` | v1.0 | 前置检查（双上游）、§7.2.2 联合可行性收敛算法、§7.2.3 时序映射填法、生成顺序、5 次 BLOCKED、全量 3 轮 BLOCKED |
+
+**指导（8 个）**：
+
+| 文件 | 职责 |
+|---|---|
+| `references/节奏指导/00-index.md` | 节奏阶段入口 |
+| `references/节奏指导/01-upgrade-rhythm.md` | 升级感三步法、粒度五分类、情绪模块、桥段结构、嵌套图 |
+| `references/节奏指导/02-arc-rhythm.md` | 弧线类型回顾、叠加算法、关键点换算到章 |
+| `references/节奏指导/03-highpoint-hooks.md` | 高潮 8 类、章首 7 式、章尾 13 式、钩子强度 |
+| `references/节奏指导/04-satisfaction.md` | 爽点分布、压制换算、期待管理、断期待诊断 |
+| `references/节奏指导/05-foreshadow-density.md` | 伏笔密度、唤醒策略、超期处理 |
+| `references/节奏指导/06-chapter-outline.md` | 细纲字段设计、钩子排布、伏笔推进、势力出场 |
+| `references/节奏指导/07-audit.md` | 节奏验证流程与问题记录 |
+
+### 3.5 写作阶段（11 个）
+
+**脚本（1 个）**：
+
+| 文件 | 版本 | 能力 |
+|---|---|---|
+| `references/writing-validate.js` | v1.2 | 单章校验；`--chapter=N`；`--upstream=<骨架>,<血肉>,<节奏>`；章节标题兼容三种格式（`# 第N章` / `# 第NNN章` / `# 第X章`，中文数字支持到"万"）；`EMPTY_BODY` / 字数 / 禁用词（`基本一致` / `无重大问题`）/ 与细纲对照；`UPSTREAM_PARTIAL` 在 outline 或 avgWords 任一缺失时触发；零反引号 |
+
+**提示词（1 个）**：
+
+| 文件 | 版本 | 内容 |
+|---|---|---|
+| `prompts/04-writing-prompt.md` | v1.1 | 前置检查（三上游）、逐章生成、单章校验、台账更新、5 次 BLOCKED；禁用词清单与脚本对齐；章节标题三种格式 |
+
+**指导（9 个）**：
+
+| 文件 | 职责 |
+|---|---|
+| `references/写作指导/00-index.md` | 写作阶段入口（加载顺序、产出清单、决策路由） |
+| `references/写作指导/01-scene.md` | 场景五要素、进出场、画面感、比例、非对话信息传递 |
+| `references/写作指导/02-chapter-workflow.md` | 八步流程、批量生成、版本管理 |
+| `references/写作指导/03-opening-chapter.md` | 五段式、题材变体、平台差异 |
+| `references/写作指导/04-dialogue-mastery.md` | 权力博弈、潜台词、场景路由、语言差异化、弹幕 |
+| `references/写作指导/05-genre-formulas.md` | 21 个题材公式的结构骨架 |
+| `references/写作指导/06-tone-ensemble.md` | 喜剧/悲剧/文学/群像/单元剧/非线性 |
+| `references/写作指导/07-ledger-audit.md` | 4 类台账、单元末/卷末盘点、上下文加载、改稿影响 |
+| `references/写作指导/08-diagnosis-revision.md` | 八种症状诊断树、修改优先级、四轮打磨、复验 |
+
+### 3.6 公共工具（2 个）
+
+| 文件 | 版本 | 职责 |
+|---|---|---|
+| `references/graph-utils.js` | v1.4 | 图工具库：`SimpleGraph` / `getIsolatedNodes` / `getDisconnectedCoreNodes` / `checkBidirectionalSymmetry` / `parseGlossaryFromMd`（统一 glossary 解析，剥离反引号，跳过计数类型） |
+| `references/check-guide-compliance.js` | v1.2 | 检查指导文件是否符合五条禁令（不数字区间 / 不检查清单 / 错误代码只在白名单节 / 有"与其他文件的关系"节 / 不重复枚举值）；**audit 文件豁免错误代码检查，写作指导豁免数字区间检查** |
+
+---
+
+## 四、文件依赖关系
+
+```
+glossary.md ────────────────────────────────┐
+    │                                       │
+    │ 被引用                                 │
+    ▼                                       ▼
+formulas-skeleton.json ──────────► skeleton-validate.js
+formulas-rhythm.json ────────────► rhythm-validate.js
+    │                                       ▲
+    │                                       │
+    ▼                                       │
+模板/骨架/*.json ──────────────────────────┤
+模板/血肉/*.json ─────────────► flesh-validate.js
+模板/节奏/*.json ─────────────► rhythm-validate.js
+                                writing-validate.js
+                                    ▲
+                                    │
+prompts/01-skeleton-prompt.md ──────┘（编排）
+prompts/02-flesh-prompt.md ─────────┘
+prompts/03-rhythm-prompt.md ────────┘
+prompts/04-writing-prompt.md ───────┘
+```
+
+**关键依赖**：
+- 所有模板的 `enumRef` 依赖 `glossary.md` 的枚举
+- 所有脚本的枚举校验依赖 `glossary.md`
+- `skeleton-validate.js` 的公式校验依赖 `formulas-skeleton.json`（30 条）
+- `rhythm-validate.js` 的联合约束依赖 `formulas-rhythm.json` 的 `constraints` 节（7 条）
+- 各阶段脚本通过 `--upstream` 读上游 JSON
+- 三个校验脚本（skeleton / flesh / rhythm）都 `import { parseGlossaryFromMd } from './graph-utils.js'`
+- 提示词通过读指导文件获得方法论、读模板获得结构、调脚本获得验证
+
+---
+
+## 五、常见任务导航
+
+### 5.1 "我要从零开始生成骨架"
+
+1. 读 `prompts/01-skeleton-prompt.md` 全文
+2. 按提示词的"六、生成顺序"逐个生成 4 个 JSON
+3. 每个文件生成后按"七、每文件生成循环"调 `skeleton-validate.js` 单检
+4. 全部通过后跑 `--all`
+5. 输出交付摘要
+
+### 5.2 "我要在已完成的骨架上补血肉"
+
+1. 确认骨架 `.stage-status.json` 的 `all_check.status === "PASSED"`
+2. 读 `prompts/02-flesh-prompt.md` 全文
+3. 按提示词的"六、生成顺序"逐个生成 8 个 JSON
+4. 每个文件生成后调 `flesh-validate.js --upstream=<骨架>` 单检
+5. 全部通过后跑 `--all`
+6. 输出交付摘要
+
+### 5.3 "我要在血肉基础上排节奏"
+
+1. 确认骨架和血肉的 `.stage-status.json` 都 PASSED
+2. 读 `prompts/03-rhythm-prompt.md` 全文
+3. **重点读 7.2.2**（联合可行性收敛算法）和 **7.2.3**（时序映射填法）
+4. 按提示词的"六、生成顺序"（章节规划 → 节奏参数 → 时序映射 → 章节细纲）逐个生成
+5. 每个文件生成后调 `rhythm-validate.js --upstream=<骨架>,<血肉>` 单检
+6. 全部通过后跑 `--all`
+7. 输出交付摘要
+
+### 5.4 "我要在节奏基础上写正文"
+
+1. 确认骨架、血肉、节奏的 `.stage-status.json` 都 PASSED
+2. 读 `prompts/04-writing-prompt.md` 全文
+3. 按提示词的"六、生成顺序"逐章生成
+4. 每章生成后调 `writing-validate.js --chapter=N --upstream=<骨架>,<血肉>,<节奏>` 单检
+5. 每章通过后更新 4 个台账
+6. 第 T 章通过后做完本检查 + 输出交付摘要
+
+### 5.5 "我要加一个角色"
+
+1. 判断是否影响框架（`quota.character_counts`）
+2. 若影响，先改 `框架.json` 的 `quota` 与 `derivations`
+3. 改 `实体.json` 加新角色（`id` 从 `C001` 到 `C0NN` 连续）
+4. 改 `关系.json` 给新角色建关系（至少一条，否则会报 `G_ISOLATED`）
+5. 重跑骨架阶段 `--all` 确认无破坏（`QUOTA_MISMATCH` 会检查 quota 与实体数量一致）
+6. 重跑血肉阶段（新角色需要补血肉档案）
+7. 重跑节奏阶段（新角色需要补时序映射）
+8. 重跑写作阶段（如果已经在写正文）
+
+### 5.6 "我要改章节总数 500 → 600"
+
+**不能走增量**，全量重跑：
+
+1. 改 `框架.json` 的 `capacity.target_chapters`
+2. 全部 30 条公式的 `derivations` 重算
+3. 从骨架阶段第 1 步重新生成所有文件
+4. 每阶段单检 + 全量
+5. 全部通过后交付
+
+### 5.7 "我要改某个角色的背景描述"
+
+1. 判断是否影响框架（通常不影响）
+2. 直接改 `血肉/角色.json` 对应角色的字段
+3. 重跑 `flesh-validate.js --input=角色.json ... --upstream=<骨架>`
+4. 若角色涉及时序（如退场章），重跑节奏阶段的时序映射
+5. 若已在写正文，重新生成受影响的章
+
+### 5.8 "我要改某条支线的章节范围"
+
+1. 判断改动后 `branch_chapter_total` / `overlap_chapter_count` / `main_progress_chapter_count` 是否变化
+2. 若变化，先改 `节奏参数.json` 并重算
+3. 改 `时序映射.json` 的 `branch_timeline`
+4. 重跑 `rhythm-validate.js --input=时序映射.json ... --upstream=<骨架>,<血肉>`
+5. 重跑全量
+6. 若已写正文，重新生成受影响的章
+
+### 5.9 "脚本报错了怎么办"
+
+1. **单文件校验 status:1**：读 `errors[]`，按 `path` 定位字段，按 `hint` 修改，重跑
+2. **单文件校验 status:2**：脚本自己没能跑完（参数错 / 文件读不到 / 上游缺失 / glossary 读不出来）。
+   **原因不在 stderr** —— 4 个校验器的 stderr 是空的，原因在 **stdout 的 `errors[0].message`** 里
+   （只有 `check-guide-compliance.js` 相反：它 exit 2 时 stdout 为空、原因在 stderr）。
+   **改命令，不要改产物**
+3. **全量校验 status:1**：读 `errors[]`，按 `file` 或 `path` 前缀分组，先改根因文件，重跑单检，重跑全量
+4. **连续 5 次 status:1**：触发 BLOCKED。按提示词的 BLOCKED 格式输出，停止，等人工介入
+5. **全量 3 轮失败**：触发 BLOCKED。同上
+
+### 5.10 "我要检查指导文件是否符合规范"
+
+```bash
+node references/check-guide-compliance.js --dir=references/骨架指导
+node references/check-guide-compliance.js --dir=references/血肉指导
+node references/check-guide-compliance.js --dir=references/节奏指导
+node references/check-guide-compliance.js --dir=references/写作指导
+```
+
+输出 JSON：`{status, total_files, total_errors, total_warnings, results}`。error 需修复，warning 可选。
+
+**怎么判**：`status:0` = 通过；`status:1` = 有问题，逐个文件的错在 `results[].errors[]` 里；
+`status:2` = 脚本自己没跑完 —— **这个脚本是例外：它的 stdout 是空的，原因在 stderr**
+（`需要 --dir 或 --file` / `目录不存在: …` / `glossary.md 解析失败: …`）。**改命令，不要改指导文件**。
+
+**v1.2 注**：audit 文件（文件名匹配 `0X-audit.md`）整体豁免 `ERROR_CODE_IN_BODY`；写作指导目录豁免 `RANGE_IN_GUIDE`。
+
+---
+
+## 六、ID 前缀速查
+
+| 前缀 | 实体 | 出现阶段 |
+|---|---|---|
+| C | 角色 | 骨架 |
+| X | 冲突 | 骨架 |
+| F | 势力 | 骨架 |
+| V | 卷 | 骨架 |
+| FS | 伏笔 | 骨架 |
+| M | 主线 | 骨架 |
+| B | 支线 | 骨架 |
+| L | 地点 | 骨架 |
+| E | 结局 | 骨架 |
+| R | 核心规则 | 骨架 |
+| I | 信息规则 | 骨架 |
+| SR | 社会规则 | 骨架 |
+| P | 关键道具 | 骨架 |
+| CL | 高潮 | 骨架 |
+| PL | 爽点 | 骨架 |
+
+**章节**：无独立 ID，节奏阶段用 `ch: N` 复合键。
+
+完整定义见 `references/glossary.md` 第四节。
+
+---
+
+## 七、字段归属速查
+
+| 阶段 | 文件 | 顶层字段 |
+|---|---|---|
+| 骨架 | 框架.json | capacity / input_snapshot / quota / volume_ratio / derivations |
+| 骨架 | 实体.json | characters / conflicts / factions / locations / items / endings / foreshadows / climaxes / pleasures / world_rules / main_lines / branches |
+| 骨架 | 关系.json | character_relations / faction_membership / faction_relations / conflict_participants / branch_protagonist / item_owner / location_conflict / ending_character / main_line_branch_relation |
+| 骨架 | 层级.json | volumes / acts / main_line_span / branch_span |
+| 血肉 | 角色.json | characters（id + name + 描述层） |
+| 血肉 | 冲突.json | conflicts |
+| 血肉 | 势力.json | factions |
+| 血肉 | 剧情.json | main_lines / branches |
+| 血肉 | 地点.json | locations |
+| 血肉 | 结局.json | endings |
+| 血肉 | 世界观规则.json | core_rules / information_rules / social_rules / rule_conflict_plan |
+| 血肉 | 关键道具.json | core_items / branch_items / symbolic_items / details |
+| 节奏 | 章节规划.json | chapters |
+| 节奏 | 时序映射.json | character_timeline / conflict_timeline / foreshadow_timeline / climax_timeline / pleasure_timeline / hook_timeline / main_line_timeline / branch_timeline / location_timeline / item_timeline / ending_timeline |
+| 节奏 | 节奏参数.json | chapter_hook_rate / branch_chapter_total / overlap_chapter_count / main_progress_chapter_count / derivations |
+| 节奏 | 章节细纲.json | outlines |
+
+完整定义见 `references/glossary.md` 第七节。
+
+---
+
+## 八、章节号归属速查
+
+**以下字段只能出现在节奏阶段**（完整清单见 `glossary.md` 第六节）：
+
+| 字段 | 含义 |
+|---|---|
+| `chapter` / `ch` | 单章号 |
+| `start` / `end` | 区间 |
+| `turning` | 支线转折章 |
+| `resolution` | 支线/冲突收束章（与 `resolution_chapter` 等价） |
+| `appear_start` / `appear_end` | 出现区间 |
+| `exit_chapter` | 退场章 |
+| `buried_chapter` / `recovered_chapter` | 伏笔埋/收 |
+| `escalation_nodes[].chapter` | 冲突升级节点 |
+| `resolution_chapter` | 冲突收束 |
+| `info_gaps[].created` / `resolved` | 信息差 |
+| `key_nodes[].chapter` | 主线节点 |
+| `interweaves[].chapter` | 支线交织 |
+| `foreshadow_recovery[].chapter` | 结局回收 |
+| `arc_stages[].chapter` | 弧光阶段 |
+| `appearance_chapters` | 出现区间（容器） |
+| `chapter_range` | 章节范围（容器） |
+| `chapter_count` | 章节计数（非章节号） |
+
+**例外**：`chapter_ratio` 和 `volume_ratio` 是"比例"不是"章节号"，允许在骨架。
+
+---
+
+## 九、脚本调用速查
+
+### 9.0 所有脚本的返回格式（先读这一节）
+
+7 个 CLI 脚本的 stdout 都是 **JSON**（多数是单行，`check-guide-compliance.js` 是多行）。
+判定字段是 `status`，**没有 `ok` 字段**：
+
+```json
+{"status":0,"file":"实体","errors":[],"warnings":[]}
+```
+
+| status | 含义 | 怎么判 |
+|---|---|---|
+| `0` | 通过 | `errors` 是空数组 |
+| `1` | 内容有问题 | `errors` 里有条目（**`warnings` 不算失败**） |
+| `2` | **脚本自己没跑完** | 不是你的产物有问题 —— 参数错 / 文件读不到 / 上游缺失 / glossary 读不出来 |
+
+**退出码 = status**（脚本里是 `process.exitCode = status`），
+所以 `echo $?` 的 0 / 1 / 2 与 JSON 里的 `status` 是一致的。
+
+**三个例外，必须分开看**：
+
+- `upstream-query.js`：`status:1` = **没查到**，不是失败。
+  它是查询工具，"查不到"本来就是合法答案（`items` 是空数组）。
+  `status:2` 才是真出错（参数错 / 上游文件不存在 / JSON 解析失败）。
+- `deslop-validate.js`：**不加 `--fail-on-blocking` 时 `status` 恒为 0**，
+  哪怕命中了很多 blocking 模式。而 `errors[]` 里既装了 blocking 命中，
+  也装了 advisory 命中（`AI_PATTERN_ADVISORY`）——
+  所以**「`errors[]` 非空」不等于失败**。
+  要让 blocking 命中导致失败，命令里必须带 `--fail-on-blocking`。
+- `check-guide-compliance.js`：输出的是**汇总**结构
+  `{"status":N,"total_files":…,"total_errors":…,"total_warnings":…,"results":[…]}`，
+  每个文件的错在 `results[].errors[]` 里，不是顶层的 `errors[]`。
+
+**`status:2` 的原因在哪看**（这个坑最容易踩）：
+
+| 脚本 | `status:2` 时 stdout | `status:2` 时 stderr |
+|---|---|---|
+| `skeleton-validate.js` / `flesh-validate.js` / `rhythm-validate.js` / `writing-validate.js` | **有** JSON，`errors[0].message` 是原因 | **空的** |
+| `upstream-query.js` | **有** JSON，`error` 字段是原因 | 空 |
+| `deslop-validate.js` | 有 JSON | 空 |
+| `check-guide-compliance.js` | **空的** | **有**原因（`需要 --dir 或 --file` / `目录不存在: …` / `glossary.md 解析失败: …`） |
+
+**看到 `status:2` 怎么办**：
+
+1. 按上表找到原因（4 个校验器看 stdout 的 `errors[0].message`；
+   `check-guide-compliance.js` 看 stderr）。
+2. 原因多半是**命令参数写错**（少了 `--upstream`、路径拼错、目录不存在）。
+   **改命令，不要改产物** —— 产物没错，改它只会把对的改错。
+3. 改完**重跑同一条命令**。
+
+### 9.1 骨架脚本
+
+```bash
+# 单文件（带 --upstream）
+node references/skeleton-validate.js --input=<json> --template=<模板> --file=<类型> --upstream=<骨架目录>
+
+# 全量
+node references/skeleton-validate.js --stage-dir=<骨架目录> --template-dir=<模板/骨架> --all
+```
+
+**单文件模式必须带 `--upstream=<骨架目录>`**：不带的话，
+`关系.json` 的引用完整性、支线挂主线的覆盖度、`层级.json` 的卷数/引用三项跨文件检查
+会被**静默跳过**（`relationRefCheck` / `checkBranchMainLineCoverage` / `hierarchyRefCheck`
+拿到空的上游就直接 `return`），而脚本**照样报 `status:0`** ——
+这是一次**假通过**。全量模式（`--all`）自己会读同目录的文件，不受这个影响。
+
+### 9.2 血肉脚本
+
+```bash
+# 单文件（必须带 --upstream）
+node references/flesh-validate.js --input=<json> --template=<模板> --file=<类型> --upstream=<骨架目录>
+
+# 全量
+node references/flesh-validate.js --stage-dir=<血肉目录> --template-dir=<模板/血肉> --upstream=<骨架目录> --all
+```
+
+### 9.3 节奏脚本
+
+```bash
+# 单文件（必须带双上游，v1.2 起强制）
+node references/rhythm-validate.js --input=<json> --template=<模板> --file=<类型> --upstream=<骨架目录>,<血肉目录>
+
+# 全量
+node references/rhythm-validate.js --stage-dir=<节奏目录> --template-dir=<模板/节奏> --upstream=<骨架目录>,<血肉目录> --all
+```
+
+### 9.4 写作脚本
+
+```bash
+# 单章（必须带章号和三上游）
+node references/writing-validate.js --input=<第NNN章.md> --chapter=<N> --upstream=<骨架目录>,<血肉目录>,<节奏目录>
+```
+
+### 9.5 合规检查脚本
+
+```bash
+node references/check-guide-compliance.js --dir=<指导目录>
+node references/check-guide-compliance.js --file=<单个指导文件>
+```
+
+**退出码统一**：0=通过、1=内容错误、2=脚本异常。
+
+### 9.6 去味脚本
+
+```bash
+# 单章（要让 blocking 命中导致失败，必须带 --fail-on-blocking）
+node references/deslop-validate.js --input=<第NNN章.md> --fail-on-blocking
+```
+
+**不带 `--fail-on-blocking` 时 `status` 恒为 0**，
+而且 `errors[]` 里混着 advisory 命中（`AI_PATTERN_ADVISORY`）——
+判定只看 `status` 和 `blockingCount`，**不要拿 `errors[]` 非空当失败**。
+
+### 9.7 上游查询脚本
+
+```bash
+# 查单个
+node references/upstream-query.js --stage=骨架 --file=实体 --id=C001
+
+# 查某个文件里有哪些记录（先列再查）
+node references/upstream-query.js --stage=骨架 --file=关系 --list
+
+# 查某一章 / 一批 id
+node references/upstream-query.js --stage=节奏 --file=章节细纲 --ch=12
+node references/upstream-query.js --stage=骨架 --file=实体 --ids=FS042,FS043
+```
+
+`status:0` = 命中（`items` 是查到的记录）；`status:1` = **没查到**（不是失败，
+`items` 是空数组，用 `--list` 看可用记录）；`status:2` = 参数错或上游文件读不到。
+
+---
+
+## 十、版本记录
+
+| 版本 | 变更 |
+|---|---|
+| v1.0 | 初建。总索引：体系概览、文件分类、全部文件清单、依赖关系、常见任务导航（10 个场景）、ID 前缀速查、字段归属速查、章节号归属速查、脚本调用速查 |
+| v1.1 | 修正文件数（61 → 58）；补全各文件的版本号（反映 P0-1 到 P3-1 的所有变更）；§3.1 补 formulas-skeleton 30 条说明、formulas-rhythm 10 节说明；§3.2 补 skeleton-validate v2.2 新增 6 项检查；§3.3 补 flesh-validate v1.1 扩展；§3.4 补 rhythm-validate v1.1 修订；§3.5 补 writing-validate v1.1 修订；§八 章节号清单补 `ch` / `turning` / `resolution`；§五 5.5 加 `QUOTA_MISMATCH` 提示 |
+| v1.2 | 修正节奏阶段文件数（13 → 14）；总数（57/58 → 59/60）；写作阶段补 `00-index.md`（10 → 11 个）；§3.2 skeleton-validate 版本更新 v2.4 并补"关系组合重复检查（7 类）"表述；§3.3 flesh-validate 更新 v1.2；§3.4 rhythm-validate 更新 v1.2（强制双上游）；§3.5 writing-validate 更新 v1.2；§3.6 公共工具版本更新（graph-utils v1.4 / check-guide-compliance v1.2）；§5.10 补 v1.2 的 audit / 写作指导豁免说明 |
+| v1.3 | §9.0 新增「所有脚本的返回格式」总则：`status` 0/1/2 的含义与判定依据、退出码与 status 一致、三个例外（upstream-query 的 status:1 是"没查到"、deslop-validate 不加 `--fail-on-blocking` 时 status 恒 0 且 errors[] 混着 advisory、check-guide-compliance 是汇总结构）、`status:2` 的原因在 stdout 还是 stderr 的对照表；§9.1 单文件模式补 `--upstream`（不带会静默跳过三类跨文件检查仍报 status:0 假通过）；§9.6 补去味脚本、§9.7 补上游查询脚本（原来速查表里没有这两个）；§5.9.2 修正"读 stderr"的说法（4 个校验器的 stderr 是空的，原因在 stdout 的 `errors[0].message`） |