@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

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

@@ -96,9 +96,12 @@
 | `P` | 关键道具 | 骨架 | P001 | 三类道具共享编号空间 |
 | `CL` | 高潮 | 骨架 | CL001 | |
 | `PL` | 爽点 | 骨架 | PL001 | |
+| `O` | 其他实体 | 骨架 | O001 | 灵魂/神魂/器灵/妖灵/概念体等题材特有存在；不塞进 characters |
 
 **说明**：钩子（hook）不是骨架实体——它的类型（`hook_form_head`/`hook_form_tail`）属于节奏阶段，它的数量下限由节奏参数 `chapter_hook_rate` 表达，不需要独立 ID。因此本表不含 `HK` 前缀。
 
+**题材扩展实体**：当题材需要灵魂、神魂、器灵、妖灵、鬼魂、概念体等**非人物存在**时，在骨架 `实体.json` 的 `other_entities` 里登记（`O001` 起），不要硬塞进 `characters`。它们与人物/其他实体的关系写在 `关系.json` 的 `other_relations`，用 `relation_label` 写具体关系（附身/寄宿/共生/契约/镇压等）。普通人物之间如果需要词表外的关系（如附身），`character_relations[].relation_kind` 用 `其他`，并填 `relation_label`。
+
 ### 4.1 编号规则
 
 - 从 001 开始，连续递增，不跳号
@@ -313,6 +316,7 @@
 | 对立 | 立场对立、互为反对者 | 对称 | 立场 |
 | 敌对 | 敌视仇视、互为敌人 | 对称 | 立场 |
 | 竞争 | 争夺同一目标或资源 | 对称 | 立场 |
+| 其他 | 词表外的题材特有角色关系 | 有向 | 扩展 |
 | 中立 | 无特殊立场、互不相干 | 对称 | 立场 |
 
 **说明**：
@@ -321,7 +325,9 @@
 - **身份维度**（血缘/师徒/雇佣）与**立场维度**（合作/利益交换/利用/对立/敌对/竞争/中立）可同时成立，例如"A 是 B 的表弟，同时两人是竞争对手"。
 - **立场维度**下同一对角色只能有一种关系：A→B 声明"合作"、B→A 声明"敌对"会被 `REL_ASYMMETRIC_INCOMPATIBLE` 拦截。
 - **有向关系**不能双向互指同一个值：A→B 与 B→A 都写"服从"会被 `REL_ASYMMETRIC_INCOMPATIBLE` 拦截。
-- 血肉阶段的 `relationships[]` 语义是"**本角色**对 `target_name` 的关系"，方向与骨架的 `from`→`to` 一致，跨阶段比对见 `REL_TYPE_MISMATCH`。
+- `其他` 是**扩展出口**，不能只写 `其他` 就结束：必须同时填 `relation_label`（如 `附身`、`寄生`、`契约`、`前世`、`共生`），否则报 `REL_LABEL_REQUIRED`。能归入现有 12 类的，优先用现有值，不要滥用 `其他`。
+- 血肉阶段的 `relationships[]` 语义是"**本角色**对 `target_name` 的关系"，方向与骨架的 `from`→`to` 一致，跨阶段比对见 `REL_TYPE_MISMATCH`；`relation_label` 也必须与骨架一致。
+- **关系会变化**：血肉 `relationships[].changes[]` 写阶段变化（`stage` / `from` / `to` / `trigger` / `description`，可带 `timing` 粗时间），不写章节号；章节落点由节奏 `时序映射.json` 的 `relationship_timeline` 决定。
 
 #### branch_relation_kind（主线与支线的交织关系）
 
@@ -457,6 +463,8 @@
 | `appear_start` | 单章号 | 角色/地点/道具出现起点 |
 | `appear_end` | 单章号 | 角色/地点/道具出现终点 |
 | `exit_chapter` | 单章号 | 角色退场章 |
+| `start_chapter` | 单章号 | 关系阶段的开始章 |
+| `end_chapter` | 单章号 | 关系阶段的结束章（可选） |
 | `buried_chapter` | 单章号 | 伏笔埋设章 |
 | `recovered_chapter` | 单章号 | 伏笔回收章 |
 | `escalation_nodes[].chapter` | 单章号 | 冲突升级节点章 |
@@ -499,15 +507,15 @@
 | 文件 | 顶层字段 |
 |---|---|
 | `框架.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` | `characters`、`other_entities`（可选）、`conflicts`、`factions`、`locations`、`items`、`endings`、`foreshadows`、`climaxes`、`pleasures`、`world_rules`、`main_lines`、`branches` |
+| `关系.json` | `character_relations`、`other_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` |
 
-### 7.2 血肉阶段（8 个 JSON）
+### 7.2 血肉阶段（8 个核心 JSON + 按需 1 个扩展文件）
 
 | 文件 | 顶层字段 |
 |---|---|
-| `角色.json` | `characters`（含 description/goals/core_flaw/golden_finger/information_state/arc_type/arc_stages/language_profile/behavior_repeat_points/mirror_type/relationships/arc_changes/memory_points/exclusive_needs/exit） |
+| `角色.json` | `characters`（含 description/goals/core_flaw/golden_finger/information_state/arc_type/arc_stages/language_profile/behavior_repeat_points/traits/mirror_type/relationships/arc_changes/memory_points/exclusive_needs/exit） |
 | `冲突.json` | `conflicts`（含 description/core_goal/influence_scope/focus_points/surface_contradiction/deep_contradiction/ultimate_contradiction/escalation_path/information_gaps/resolution_plan） |
 | `势力.json` | `factions`（含 goal/resources/internal_structure/suppression_method/resource_seizure_path/main_line_connection/members/relations） |
 | `剧情.json` | `main_lines`（core_drive）、`branches`（goal/main_relation/expected_outcome） |
@@ -515,13 +523,14 @@
 | `结局.json` | `endings`（conflict_summary/conflict_solution/anti_trope_design/aftermath/emotion_trajectory/core_emotion/final_point/chapter_design/memorable_scenes/epilogue_hints/foreshadow_recovery_plan） |
 | `世界观规则.json` | `core_rules`、`information_rules`、`social_rules`、`rule_conflict_plan` |
 | `关键道具.json` | `core_items`、`branch_items`、`symbolic_items`、`details` |
+| `其他实体.json`（按需） | `other_entities`（id/name/kind/description/traits/abilities/limits/extensions）；只有骨架 `other_entities` 非空时才生成 |
 
 ### 7.3 节奏阶段（4 个 JSON）
 
 | 文件 | 顶层字段 |
 |---|---|
 | `章节规划.json` | `chapters`（每章：ch/volume/act/scene_focus） |
-| `时序映射.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` | `character_timeline`、`relationship_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`（每章一行，可只对重点章写） |
 

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

@@ -79,7 +79,7 @@
 | 文件 | 内容 |
 |---|---|
 | `模板/骨架/框架模板.json` | capacity / input_snapshot / quota / volume_ratio / derivations |
-| `模板/骨架/实体模板.json` | 12 类实体数组（characters / conflicts / factions / ... / branches） |
+| `模板/骨架/实体模板.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 |
 
@@ -87,7 +87,7 @@
 
 | 文件 | 版本 | 能力 |
 |---|---|---|
-| `references/skeleton-validate.js` | v2.4 | 单文件 + 全量模式；从 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` / `faction_relation_count` 一致性；图检查 import `graph-utils.js`；`evalExpr` 支持三元运算符 |
+| `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 个）**：
 
@@ -152,7 +152,7 @@
 | 文件 | 内容 |
 |---|---|
 | `模板/节奏/章节规划模板.json` | 每章：ch / volume / act / scene_focus |
-| `模板/节奏/时序映射模板.json` | 11 类时序映射——所有章节号在此 |
+| `模板/节奏/时序映射模板.json` | 12 类时序映射（含关系阶段）——所有章节号在此 |
 | `模板/节奏/节奏参数模板.json` | chapter_hook_rate / 三参数 / derivations |
 | `模板/节奏/章节细纲模板.json` | 每章细纲（功能/情绪/爽点/伏笔/势力/钩子/字数） |
 
@@ -332,7 +332,10 @@ prompts/04-writing-prompt.md ───────┘
 ### 5.9 "脚本报错了怎么办"
 
 1. **单文件校验 status:1**：读 `errors[]`，按 `path` 定位字段，按 `hint` 修改，重跑
-2. **单文件校验 status:2**：脚本异常。读 stderr，检查参数 / 上游 / glossary
+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。同上
@@ -348,6 +351,10 @@ 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`。
 
 ---
@@ -433,16 +440,71 @@ node references/check-guide-compliance.js --dir=references/写作指导
 
 ## 九、脚本调用速查
 
+### 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
-# 单文件
-node references/skeleton-validate.js --input=<json> --template=<模板> --file=<类型>
+# 单文件（带 --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
@@ -479,6 +541,34 @@ 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` = 参数错或上游文件读不到。
+
 ---
 
 ## 十、版本记录
@@ -488,3 +578,4 @@ node references/check-guide-compliance.js --file=<单个指导文件>
 | 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`） |

package/plugins/fancy-story-builder/references//350/212/202/345/245/217/346/214/207/345/257/274/00-index.md

@@ -48,7 +48,7 @@
 | 产出 | 落到哪个 JSON |
 |---|---|
 | 章节归属 | `章节规划.json` 的 `chapters` |
-| 所有实体的章节位置 | `时序映射.json` 的 11 类映射 |
+| 所有实体的章节位置 | `时序映射.json` 的 12 类映射（含关系阶段） |
 | 三个核心参数 | `节奏参数.json` 的 `branch_chapter_total` / `overlap_chapter_count` / `main_progress_chapter_count` |
 | 重点章细纲 | `章节细纲.json` 的 `outlines` |
 

package/plugins/fancy-story-builder/references//350/212/202/345/245/217/346/214/207/345/257/274/07-audit.md

@@ -28,9 +28,26 @@
 
 ---
 
-## 三、全量校验失败的处理
+## 三、校验失败的处理
 
-### 3.1 按文件分组
+### 3.1 单文件校验失败的处理
+
+单文件校验返回的是 **JSON**，判定看 `status`（**没有 `ok` 字段**）：
+
+| status | 含义 | 怎么办 |
+|---|---|---|
+| `0` | 这个文件过了 | 接着做下一个文件；4 个都过了才跑全量 |
+| `1` | 这个文件的内容有问题 | 按 `errors[]` 回喂：只改 `errors` 指出的字段，按 `hint` 改，改完重跑这条单检 |
+| `2` | **脚本自己没跑完，不是这个文件的问题** | 看 **stdout** 的 `errors[0].message`（**stderr 是空的**）：多半是 `--template` 路径错、`--upstream` 目录不存在、glossary 读不出来。**改命令，不要改文件**，改完重跑同一条命令 |
+
+**`status:2` 的原因不在 stderr** —— 这是最容易踩的坑：
+stderr 里什么都没有，模型就容易以为自己写错了文件，
+去改本来正确的产物，越改越坏。
+
+**单检过 ≠ 阶段过**：单检只查这一个文件，跨文件的问题
+（时序与参数的可行性、章节引用完整性）要全量校验才查得出来。
+
+### 3.2 按文件分组
 
 `errors[]` 每条有 `path` 字段。按"根因文件"分组：
 
@@ -55,14 +72,14 @@
 | `RHYTHM_HOOK_DUP_WARN`（warning） | `时序映射.json` 的 `hook_timeline` |
 | `RHYTHM_WORD_TARGET`（warning） | `章节细纲.json` 的 `word_target` |
 
-### 3.2 改根因文件
+### 3.3 改根因文件
 
 一次只改一类错误：
 - 先修 error，再修 warning
 - 同类错误一起修
 - 不顺手改其他字段
 
-### 3.3 重跑受影响文件的单检
+### 3.4 重跑受影响文件的单检
 
 ```bash
 node references/rhythm-validate.js \
@@ -72,9 +89,9 @@ node references/rhythm-validate.js \
   --upstream=设定/raw/sources/骨架,设定/raw/sources/血肉
 ```
 
-单检通过后，才重跑全量。
+单检通过后（`status:0`），才重跑全量。
 
-### 3.4 重跑全量
+### 3.5 重跑全量
 
 ```bash
 node references/rhythm-validate.js \
@@ -84,7 +101,7 @@ node references/rhythm-validate.js \
   --all
 ```
 
-### 3.5 最多 3 轮
+### 3.6 最多 3 轮
 
 全量最多跑 3 轮。第 3 轮仍失败时，按提示词的 BLOCKED 格式输出，附第 3 轮完整 errors。
 
@@ -161,3 +178,4 @@ node references/rhythm-validate.js \
 | 版本 | 变更 |
 |---|---|
 | v1.0 | 从原 03-05 精简。删除所有 `- [ ]` 检查清单（验证归脚本）；保留验证流程、问题清单模板、输出确认；新增"跨文件错误的特殊处理"节；新增"与其他文件的关系"节 |
+| v1.1 | §三 原先只有"全量校验失败的处理"，整段缺单检失败处理：新补 §3.1 单文件校验失败的处理（`status` 0/1/2 各自的判据、`status:2` 的处置、"单检过 ≠ 阶段过"），原 §3.1-3.5 顺延为 §3.2-3.6 |

package/plugins/fancy-story-builder/references//350/241/200/350/202/211/346/214/207/345/257/274/01-character.md

@@ -35,6 +35,8 @@
 - `arc_change_descriptions`：起点/转折/中点/终点的**文本描述**（不填章节号）
 - `language_profile`：语言档案 7 维（见 §5）
 - `behavior_repeat_points`：行为重复点（见 §3.4）
+- `traits`：3-5 条独有特征/习惯/感官锚点（见 §3.4）
+- `extensions`：题材特有的扩展设定（如灵异题材的阴气/附身痕迹），键用中文
 - `relationships`：关系数组（见 §6）
 - `arc_changes`：弧光变化数组（stage + description）
 - `memory_points`：记忆点（外貌/性格/口头禅）
@@ -84,7 +86,7 @@
 
 ### 3.1 配角的功能
 
-配角在血肉阶段补的字段：`description` / `goals` / `core_flaw` / `language_profile` / `behavior_repeat_points` / `relationships` / `memory_points` / `exclusive_needs` / `exit`。
+配角在血肉阶段补的字段：`description` / `goals` / `core_flaw` / `language_profile` / `behavior_repeat_points` / `traits` / `extensions` / `relationships` / `memory_points` / `exclusive_needs` / `exit`。
 
 配角的设计核心是"功能"。每个配角至少占一个功能（可兼两个）：
 
@@ -114,6 +116,8 @@
 
 抓住行为特质反复写维持长篇。每个角色 2-3 个行为重复点，落在 `behavior_repeat_points` 数组。
 
+`traits` 则是更具体的“这个人独有”的细节：紧张时摸腕环、说话前先看门口、袖口永远沾着墨。写 3-5 条，每条都能在场景里演出来；不要用“善良”“勇敢”“聪明”这类评价词凑数。
+
 **疲劳边界**：同一行为连续多次无差异化时，换场景/换对象/换后果，否则读者疲劳。
 
 ---

package/plugins/fancy-story-builder/references//350/241/200/350/202/211/346/214/207/345/257/274/03-relations.md

@@ -23,9 +23,10 @@
 
 血肉阶段在 `角色.json` 的 `relationships` 数组中补"描述层"：
 - `target_name`：对方姓名（必须存在于骨架角色中）
-- `relationship_type`：关系类型，**必须与骨架里同一对角色的 `relation_kind` 完全一致**，取值见 glossary 第五节 `relation_kind`（血缘 / 师徒 / 雇佣 / 服从 / 提携 / 合作 / 利益交换 / 利用 / 对立 / 敌对 / 竞争 / 中立）
+- `relationship_type`：关系类型，**必须与骨架里同一对角色的 `relation_kind` 完全一致**，取值见 glossary 第五节 `relation_kind`（血缘 / 师徒 / 雇佣 / 服从 / 提携 / 合作 / 利益交换 / 利用 / 对立 / 敌对 / 竞争 / 中立 / 其他）
+- `relation_label`：`relationship_type=其他` 时必填，写具体关系（附身 / 寄生 / 契约 / 共生…）
 - `description`：一段话描述关系的质地
-- `changes`：关系变化数组（`from` / `to` / `description`，**不含章节号**）
+- `changes`：关系变化数组，每条写 `stage`（阶段名）/ `from`（变化前）/ `to`（变化后）/ `trigger`（触发事件）/ `description`（怎么变），可加 `timing`（前期/中期/后期，**不含章节号**）
 
 **关系类型只能用词表里的值**，不要写"盟友""对手""上下级""血亲"这类近义词：
 
@@ -42,6 +43,9 @@
 | 被当作棋子 | 利用（起点写利用者） |
 | 抢同一个位置 | 竞争 |
 | 互不相干 | 中立 |
+| 附身/寄生/契约等词表外关系 | 人物之间用 `其他` + `relation_label`；灵魂/神魂等非人物存在写骨架 `other_relations` |
+
+**关系会变**：不要把关系写成一条静态边。前期对立、某事件后转为合作，就写两条 `changes`（或一条从“对立”到“合作”的变化），把 `trigger` 写清楚；具体从第几章开始变留给节奏阶段的 `relationship_timeline`。
 
 **方向**：`relationships[]` 表达的是"**本角色**对 `target_name` 的关系"，方向与骨架的 `from`→`to` 一致。有向关系（师徒 / 雇佣 / 服从 / 提携 / 利用）只能写在关系起点的那个角色文件里。
 

package/plugins/fancy-story-builder/references//350/241/200/350/202/211/346/214/207/345/257/274/05-audit.md

@@ -30,11 +30,20 @@
 
 ## 三、单文件校验失败的处理
 
-单文件 `status: 1` 时：
-- 按 `errors[]` 回喂
-- 只改 `errors` 指出的字段
-- 重跑该文件单检
-- 累计 5 次失败 → BLOCKED
+单文件校验返回的是 **JSON**，判定看 `status`（**没有 `ok` 字段**）：
+
+| status | 含义 | 怎么办 |
+|---|---|---|
+| `0` | 这个文件过了 | 接着做下一个文件；8 个都过了才跑全量 |
+| `1` | 这个文件的内容有问题 | 按 `errors[]` 回喂：只改 `errors` 指出的字段，改完重跑该文件单检；累计 5 次失败 → BLOCKED |
+| `2` | **脚本自己没跑完，不是这个文件的问题** | 看 **stdout** 的 `errors[0].message`（**stderr 是空的**）：多半是 `--template` 路径错、`--upstream` 目录不存在、glossary 读不出来。**改命令，不要改文件**，改完重跑同一条命令 |
+
+**`status:2` 的原因不在 stderr** —— 这是最容易踩的坑：
+stderr 里什么都没有，模型就容易以为自己写错了文件，
+去改本来正确的产物，越改越坏。
+
+**单检过 ≠ 阶段过**：单检只查这一个文件，跨文件的问题（引用完整性、
+与世界规则类别的对应）要全量校验才查得出来。
 
 ---
 
@@ -175,3 +184,4 @@ node references/flesh-validate.js \
 | 版本 | 变更 |
 |---|---|
 | v1.0 | 从原 02-06 精简。删除所有 `- [ ]` 检查清单（验证归脚本）；保留验证流程、问题清单模板、输出确认；新增"与其他文件的关系"节 |
+| v1.1 | §3 补单检返回的完整判定：`status` 0/1/2 各自的含义与判据（原只有 status:1）；补 `status:2` 的处置（原因在 stdout 的 `errors[0].message`，stderr 是空的，**改命令不要改文件**）；补"单检过 ≠ 阶段过" |

package/plugins/fancy-story-builder/references//351/252/250/346/236/266/346/214/207/345/257/274/00-index.md

@@ -44,7 +44,7 @@
 
 | 产出 | 落到哪个 JSON |
 |---|---|
-| 实体清单 | `实体.json` 的 12 类数组 |
+| 实体清单 | `实体.json` 的 12 类常规数组 + 可选 `other_entities` |
 | 关系清单 | `关系.json` 的 9 类数组 |
 | 数量配额 | `框架.json` 的 `quota` 与 `volume_ratio` |
 | 卷级归属 | `层级.json` 的 `volumes` / `acts` / `main_line_span` / `branch_span` |

package/plugins/fancy-story-builder/references//351/252/250/346/236/266/346/214/207/345/257/274/01-positioning.md

@@ -171,8 +171,9 @@
 落到 `框架.json` 的 `input_snapshot`：
 - `book_name`：书名
 - `genre`：都市复仇
-- `core_summary`：一句话故事
+- `positioning`：一句话定位（题材 + 主角 + 核心卖点）
 - `core_conflict`：主角 vs 缅北园区
+- `direction_title` / 11 项方向设计：扫榜报告选定方向原样抄入
 - `hard_constraints`：无超自然战斗能力
 - `anti_tropes`：主角不加入任何组织
 

package/plugins/fancy-story-builder/references//351/252/250/346/236/266/346/214/207/345/257/274/03-entities.md

@@ -293,7 +293,7 @@
 
 | 本文件输出 | 落到哪个字段 | 参考哪个公式 | 由哪个脚本验证 |
 |---|---|---|---|
-| 实体清单 | `实体.json` 的 12 类数组 | `formulas-skeleton.json` 的 `character_elements.*` / `conflict_elements.*` / `faction_elements.faction_count` / `location_elements` / `item_elements` / `foreshadow_elements` / `climax_elements` / `pleasure_elements` / `ending_elements` / `fixed.structure.main_line_count` / `structure.branch_count` | `skeleton-validate.js` 的 `PATTERN` / `ENUM` / `ID_DUP` / `NAME_DUP` / `QUANTITY_MISMATCH`（warning） |
+| 实体清单 | `实体.json` 的 12 类常规数组 + 可选 `other_entities` | `formulas-skeleton.json` 的 `character_elements.*` / `conflict_elements.*` / `faction_elements.faction_count` / `location_elements` / `item_elements` / `foreshadow_elements` / `climax_elements` / `pleasure_elements` / `ending_elements` / `fixed.structure.main_line_count` / `structure.branch_count` | `skeleton-validate.js` 的 `PATTERN` / `ENUM` / `ID_DUP` / `NAME_DUP` / `QUANTITY_MISMATCH`（warning） |
 | 关系清单 | `关系.json` 的 9 类数组 | `formulas-skeleton.json` 的 `faction_elements.faction_relation_count`（理论上限） | `skeleton-validate.js` 的 `SKELETON_REF_MISSING` / `G_ISOLATED` / `G_REL_ONE_WAY` / `G_REL_ASYMMETRIC` / `G_DISCONNECTED`（warning） |
 
 ---

package/plugins/fancy-story-builder/references//351/252/250/346/236/266/346/214/207/345/257/274/06-audit.md

@@ -55,7 +55,24 @@ node references/skeleton-validate.js \
   --upstream=设定/raw/sources/骨架
 ```
 
-单检通过后，才重跑全量。
+**单检的返回怎么判**（返回是 JSON，判定看 `status`，**没有 `ok` 字段**）：
+
+| status | 含义 | 怎么办 |
+|---|---|---|
+| `0` | 这个文件过了 | 接着做下一个文件；4 个都过了才重跑全量 |
+| `1` | 这个文件的内容有问题 | 看 `errors[]`：按 `path` 定位字段、按 `hint` 改，**只改 `errors` 指出的字段**，改完重跑这条单检 |
+| `2` | **脚本自己没跑完，不是这个文件的问题** | 看 **stdout** 的 `errors[0].message`（**stderr 是空的**）：多半是 `--template` 路径错、`--upstream` 目录不存在。**改命令，不要改文件** |
+
+**`status:2` 的原因不在 stderr** —— 这是最容易踩的坑：
+stderr 里什么都没有，模型就容易以为自己写错了文件，
+去改本来正确的产物，越改越坏。
+
+**`--upstream` 不能省**：省掉的话，关系引用完整性、支线挂主线的覆盖度、
+层级卷数与引用这三项跨文件检查会被**静默跳过**（拿不到上游就直接返回），
+而脚本**照样报 `status:0`** —— 那是一次**假通过**。
+
+单检通过后，才重跑全量。**单检过 ≠ 阶段过**：单检只查这一个文件，
+跨文件的问题要全量校验才查得出来。
 
 ### 2.4 重跑全量
 
@@ -140,3 +157,4 @@ node references/skeleton-validate.js \
 | 版本 | 变更 |
 |---|---|
 | v1.0 | 从原 01-08 精简。删除所有 `- [ ]` 检查清单（验证归脚本）；删除 §2-§8 的验证项（转化为脚本的检查逻辑）；保留验证流程、问题清单模板、输出确认；新增"与其他文件的关系"节 |
+| v1.1 | §2.3 补单检的返回判定：`status` 0/1/2 各自的含义与判据；补 `status:2` 的处置（原因在 stdout 的 `errors[0].message`，stderr 是空的，**改命令不要改文件**）；补 `--upstream` 不能省的理由（不带会静默跳过三类跨文件检查仍报 status:0 假通过）；补"单检过 ≠ 阶段过" |