@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/docs/story-graph-design.md

@@ -0,0 +1,602 @@
+> 2026-11 架构更新：项目已改为“工作区 A + projects/<uuid> + 共享 SurrealDB server”。本文关于故事图的设计仍然有效，但连接方式和目录布局以 [workspace-mcp.md](./workspace-mcp.md) 为准。
+
+# story-graph：DB 工作台设计稿
+
+> 分支：`feat/story-graph`  
+> 目标：把 `fancy-story-builder` 从“LLM 写 JSON、脚本导入 DB”改成“LLM 直接在故事图上工作”。
+
+---
+
+## 0. 一句话
+
+**LLM 不再生成阶段文件，而是通过工具读写一张带生命周期、待办占位和事务边界的故事图。**
+
+---
+
+## 1. 当前方案的问题
+
+| 问题 | 现状 | 后果 |
+|---|---|---|
+| 二段式写入 | LLM 写 JSON → 脚本导入 DB | 失败晚、原因不返回给 LLM、返工大 |
+| 上下文靠读文件 | 每个 chunk 注入整本书摘要 | token 浪费、容易压缩失忆 |
+| 校验是批处理 | 全书写完才跑 | 500 章后才发现 579 个错误 |
+| 缺细节 = 失败 | 字段不齐就报错 | 无法“先立伏笔，后补细节” |
+| 决策日志 append-only | `.reference-decisions.md` 只追加 | 返工后残留旧决策，无法回滚 |
+| 阶段僵化 | scale→macro→cast→rhythm→… | LLM 不能按“当前缺什么”工作 |
+
+---
+
+## 2. 目标与非目标
+
+### 目标
+
+1. **单一写路径**：LLM → 工具 → DB，没有 JSON 中转。
+2. **写入即校验**：硬约束当场拒绝，错误原文返回给 LLM。
+3. **按需查询**：想知道某个伏笔，只取那条伏笔和它的关系，不读整份文件。
+4. **渐进完整**：允许 `seed` 占位，缺细节是 `pending`，不是 `error`。
+5. **事务化决策**：决策和数据在同一个事务里提交/回滚；返工不会残留旧决策。
+6. **图优先**：关系、时间线、影响分析都是图查询。
+7. **阶段退化成工作流**：数据模型不再绑定 scale/macro/cast。
+
+### 非目标
+
+- 不做通用低代码平台；只服务小说构建。
+- 不把文风/节奏/“AI 味”写成数据库触发器；这些是 warning/LLM 审校。
+- 首版不做多用户权限和分布式；嵌入式单进程。
+
+---
+
+## 3. 核心模型
+
+### 3.1 节点
+
+| 类型 | 说明 | 生命周期 |
+|---|---|---|
+| `story` | 故事根 | seed → active → locked |
+| `volume` / `act` / `chapter` | 结构骨架 | seed → draft → complete |
+| `character` / `faction` / `location` / `item` | 实体 | seed → draft → complete |
+| `conflict` / `foreshadow` / `payoff` / `climax` / `information` | 叙事实体 | seed → draft → complete |
+| `outline` / `scene` | 章节计划 | seed → draft → complete |
+| `chapter_text` | 正文 | draft → final |
+| `requirement` | 待办/占位 | pending → filled / waived |
+| `change_set` | 一次写入事务 | committed / rolled_back / superseded |
+| `decision` | 设计决策/来源 | active / superseded / rolled_back |
+| `validation_issue` | 校验结果 | open / resolved / ignored |
+
+### 3.2 边
+
+```text
+story -contains-> volume -contains-> act -contains-> chapter
+chapter -chapter_cast-> character        (role: pov/cast/mentioned)
+chapter -chapter_location-> location
+character -relation-> character          (kind, from_chapter, to_chapter)
+faction -faction_relation-> faction
+character -membership-> faction
+conflict -conflict_participant-> character
+climax -climax_participant-> character
+chapter -foreshadow_action-> foreshadow  (plant/progress/reveal)
+chapter -payoff_action-> payoff          (setup/payoff)
+chapter -info_action-> information       (created/progressed/resolved)
+chapter -ending_action-> ending
+requirement -requirement_for-> subject
+decision -decision_about-> subject
+change_set -supersedes-> change_set
+```
+
+`knowledge_event` 是事件表，不直接做边；它链接 `chapter`、`character`、`subject`。
+
+### 3.3 状态不是装饰
+
+`status` 决定“缺字段算不算错误”：
+
+```text
+seed      只要求 id + name；缺细节是正常的
+draft     关键字段开始补；允许 pending
+complete  所有 hard requirement 必须 filled
+locked    不允许普通更新，只能新 change_set 覆盖
+archived  历史版本，不参与默认查询
+```
+
+---
+
+## 4. 占位与渐进完整
+
+### 4.1 requirement 节点
+
+不把“缺失”藏在空字段里，而是显式建待办：
+
+```surql
+DEFINE TABLE requirement SCHEMAFULL;
+DEFINE FIELD story       ON requirement TYPE record<story>;
+DEFINE FIELD kind        ON requirement TYPE string;
+DEFINE FIELD subject     ON requirement TYPE string;   -- "foreshadow:FS012"
+DEFINE FIELD status      ON requirement TYPE string
+  ASSERT $value IN ['pending','filled','waived'];
+DEFINE FIELD due_chapter ON requirement TYPE option<int>;
+DEFINE FIELD filled_by   ON requirement TYPE option<string>;
+DEFINE FIELD change_set  ON requirement TYPE record<change_set>;
+```
+
+### 4.2 伏笔例子
+
+创建时只写：
+
+```json
+{ "id": "FS012", "name": "空白的来源栏", "status": "seed" }
+```
+
+工具自动建：
+
+```text
+foreshadow_plant     pending  due 341
+foreshadow_progress  pending  due 360
+foreshadow_reveal    pending  due 400
+```
+
+后续：
+
+```text
+story.link foreshadow_action chapter:CH341 foreshadow:FS012 {action: plant}
+→ event 把 foreshadow_plant 标成 filled
+→ 仍然 pending: progress, reveal
+→ story.validate 返回 pending，不是 error
+```
+
+当 LLM 决定完成：
+
+```text
+story.update foreshadow FS012 {status: complete}
+→ 校验器检查：还有 pending 就报 error
+```
+
+### 4.3 为什么不用“特殊字符占位”
+
+- 特殊字符会被当成数据，查询/校验都要特殊处理。
+- `requirement` 是图上的真实节点：可查、可排序、可设 due、可 waive、可追溯 filled_by。
+- 以后要加“章节细纲待办”“角色弧光待办”，只是多一种 `kind`，不用改 schema。
+
+---
+
+## 5. 事务与决策：解决 `.reference-decisions.md` 残留
+
+### 5.1 核心原则
+
+**决策不是日志文件，是数据的一部分；它必须和数据在同一个事务里。**
+
+### 5.2 change_set
+
+```surql
+DEFINE TABLE change_set SCHEMAFULL;
+DEFINE FIELD story    ON change_set TYPE record<story>;
+DEFINE FIELD workflow ON change_set TYPE string;   -- cast/rhythm/manual
+DEFINE FIELD status   ON change_set TYPE string
+  ASSERT $value IN ['committed','rolled_back','superseded'];
+DEFINE FIELD parent   ON change_set TYPE option<record<change_set>>;
+DEFINE FIELD summary  ON change_set TYPE string;
+DEFINE FIELD created_at ON change_set TYPE datetime VALUE time::now();
+```
+
+一次 `story.apply(ops, decisions)`：
+
+```text
+BEGIN
+  CREATE change_set
+  apply 所有 ops
+  CREATE decision[]，全部指向这个 change_set
+  DB 约束/事件校验
+COMMIT
+```
+
+任何一条失败：
+
+```text
+ROLLBACK
+→ 数据没有
+→ 决策也没有
+→ 不会出现“数据回滚了、决策留下”的残留
+```
+
+### 5.3 decision
+
+```surql
+DEFINE TABLE decision SCHEMAFULL;
+DEFINE FIELD story      ON decision TYPE record<story>;
+DEFINE FIELD change_set ON decision TYPE record<change_set>;
+DEFINE FIELD scope      ON decision TYPE string;    -- cast/rhythm/chapter:CH341
+DEFINE FIELD subject    ON decision TYPE string;    -- "foreshadow:FS012"
+DEFINE FIELD text       ON decision TYPE string;
+DEFINE FIELD source     ON decision TYPE option<string>;
+DEFINE FIELD reference  ON decision TYPE option<string>;
+DEFINE FIELD reason     ON decision TYPE option<string>;
+DEFINE FIELD status     ON decision TYPE string
+  ASSERT $value IN ['active','superseded','rolled_back'];
+DEFINE FIELD supersedes ON decision TYPE option<record<decision>>;
+```
+
+### 5.4 返工
+
+返工不是“再追加一行”，而是新 change_set：
+
+```text
+change_set#2 (parent = #1)
+  ops: 覆盖 chapter:CH341 的 outline
+  decisions: 新决策
+  旧 decisions: status = superseded, supersedes 指向新决策
+```
+
+默认查询只取 `status='active'` 的决策。历史仍可查：
+
+```text
+story.why foreshadow:FS012      → 当前生效的决策
+story.history foreshadow:FS012  → 所有版本，含 superseded/rolled_back
+```
+
+### 5.5 `.reference-decisions.md`
+
+从“事实源”降级为“导出物”：
+
+```text
+storydb export decisions
+→ 只导出 active 决策，按 scope 分组
+→ 文件可删、可重建，不再是 append-only 日志
+```
+
+---
+
+## 6. Schema 编译器
+
+一份定义，生成五样东西，避免漂移：
+
+```text
+schema/definitions.js
+        │
+        ├─ generated/schema.surql      DDL
+        ├─ generated/tools.json        LLM 工具参数 JSON Schema
+        ├─ generated/schema-card.md    LLM 看的紧凑 schema
+        ├─ generated/validators.js     字段/枚举/必填
+        └─ generated/export-md.js      Markdown 导出映射
+```
+
+定义示例：
+
+```js
+foreshadow: {
+  table: 'foreshadow',
+  idPrefix: 'FS',
+  fields: {
+    name:   { type: 'string', required: true },
+    type:   { type: 'enum', values: ['small', 'medium', 'large'] },
+    status: { type: 'enum', values: ['seed', 'draft', 'complete'], default: 'seed' },
+    scope:  { type: 'enum', values: ['chapter', 'volume', 'book'] },
+    setup:  { type: 'text' },
+  },
+  requirements: [
+    { kind: 'plant',    due: 'chapter', hard: true },
+    { kind: 'progress', hard: false },
+    { kind: 'reveal',   due: 'chapter', hard: true },
+  ],
+  edges: {
+    foreshadow_action: {
+      in: 'chapter', out: 'foreshadow',
+      fields: {
+        action: { enum: ['plant', 'progress', 'reveal'] },
+        chapter_no: { type: 'int' },
+      },
+    },
+  },
+}
+```
+
+LLM 看到的是 schema card：
+
+```text
+foreshadow
+  id: string, 必填, 唯一（FS001）
+  name: string, 必填
+  type: enum[small, medium, large]
+  status: enum[seed, draft, complete]
+  scope: enum[chapter, volume, book]
+  边: chapter -foreshadow_action-> foreshadow
+      action: enum[plant, progress, reveal]
+  待办: plant / progress / reveal
+  示例: {"id":"FS012","name":"空白的来源栏","type":"medium","status":"seed"}
+```
+
+---
+
+## 7. 工具层
+
+首版用 CLI（LLM 通过 bash 调用），后续包成 MCP。
+
+```text
+storydb schema [table]
+storydb get <kind> <id> [--fields a,b,c]
+storydb search <kind> [--where k=v] [--limit N]
+storydb context --chapter N | --entity kind:id | --chapters a-b
+storydb create <kind> '<json>'
+storydb update <kind> <id> '<json>'
+storydb link <edge> <from> <to> '<json>'
+storydb unlink <edge> <from> <to>
+storydb apply '<json>'          # 批量 ops + decisions，一个事务
+storydb validate [--scope ...]
+storydb next [--limit N]
+storydb why <kind>:<id>
+storydb history <kind>:<id>
+storydb query '<read-only SurrealQL>'
+storydb export md <stage|all>
+storydb export decisions
+```
+
+### 返回格式
+
+成功：
+
+```json
+{ "ok": true, "change_set": "change_set:...", "ids": ["foreshadow:FS012"] }
+```
+
+失败：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "KNOWLEDGE_ORDER",
+    "table": "knowledge_event",
+    "field": "change",
+    "message": "C001 已经知道 FS034，不能再写成 learns",
+    "hint": "改用 confirms，或先写 forgets/corrects"
+  }
+}
+```
+
+### 权限
+
+- `create/update/link` 只允许故事表。
+- 禁止 DDL、用户、权限、`REMOVE`。
+- `query` 只读。
+- 每次写入必须带 `change_set`，可追溯。
+
+---
+
+## 8. 上下文组装
+
+`story.context` 是省 token 的核心。
+
+### 8.1 写章节时
+
+```text
+story.context --chapter 341
+```
+
+返回：
+
+```json
+{
+  "chapter": { "id": "CH341", "title": "...", "act": "A012", "pov": "C001" },
+  "cast": [{ "id": "C001", "name": "沈砚" }, { "id": "C002", "name": "韩雨棠" }],
+  "locations": [{ "id": "L001", "name": "旧堤泵房" }],
+  "foreshadows_due": [
+    { "id": "FS012", "name": "空白的来源栏", "status": "seed", "next": "reveal", "due": 400 }
+  ],
+  "payoffs_due": [],
+  "knowledge": [{ "character": "C001", "subject": "FS012", "state": "partial" }],
+  "continuity": { "prev": "CH340 重建的第一课是修配额", "next": "CH342 ..." },
+  "requirements": [{ "kind": "chapter_outline", "status": "pending" }]
+}
+```
+
+只给相关实体，不给全书 88 个伏笔。
+
+### 8.2 查伏笔时
+
+```text
+story.get foreshadow FS012
+```
+
+返回：
+
+```json
+{
+  "id": "FS012",
+  "name": "空白的来源栏",
+  "status": "draft",
+  "timeline": [{ "chapter": 341, "action": "plant" }],
+  "pending": ["reveal"],
+  "linked_payoffs": ["PL072"],
+  "knowledge": [{ "character": "C001", "state": "partial" }]
+}
+```
+
+### 8.3 token 预算
+
+- `context` 默认上限 8k tokens；超了按优先级裁剪：chapter → cast → due foreshadows → knowledge → continuity。
+- `get` 默认只返回核心字段 + 关系 ID，不返回长文本。
+- `search` 默认只返回 `id/name/status`。
+
+---
+
+## 9. 校验分层
+
+| 层 | 机制 | 失败后果 | 例子 |
+|---|---|---|---|
+| **硬约束** | `ASSERT` / `EVENT` / 事务 | 写入失败，整批回滚 | 关系端点不存在；reveal 早于 plant；`full` 再 learns |
+| **待办** | `requirement` | 写入成功，`next` 列出 | FS012 还差 reveal；CH341 还差细纲 |
+| **质量** | 查询 → `validation_issue` | 写入成功，warning | 情绪平流；黄金三章；钩子重复；POV 密度 |
+
+`story.validate --scope chapter:CH341` 只返回本章相关问题：
+
+```json
+{
+  "errors": [],
+  "pending": [{ "kind": "chapter_outline", "status": "pending" }],
+  "warnings": [{ "code": "EMOTION_FLAT", "message": "第 339-341 章情绪值连续相同" }]
+}
+```
+
+关键：
+
+- **缺细节不是错误**，是 pending。
+- **质量问题不阻断**，只提示。
+- **只有事实/状态机错误才回滚。**
+
+---
+
+## 10. 工作流（阶段退化成批量操作）
+
+```text
+workflow.scale
+  → 创建 story/volume/act + 配额 + story.requirements
+
+workflow.macro
+  → 创建 world/story/line/line_node/ending + requirements
+
+workflow.cast
+  → 创建 character/faction/location/item/conflict/foreshadow/payoff/information
+  → 建 relation/membership/foreshadow_payoff 边
+  → 给每个实体建 requirement
+
+workflow.rhythm
+  → 批量创建 chapter + chapter.requirements
+  → 建 chapter_cast/location/foreshadow_action/payoff_action/info_action
+  → 写 knowledge_event
+
+workflow.outline
+  → 填充 chapter_outline requirement
+  → 创建 outline/scene
+
+workflow.writing
+  → 填充 chapter_draft requirement
+  → 创建 chapter_text/ledger
+```
+
+但它们不再是“必须按顺序通过的门”，而是**批量 seed/填充**。LLM 也可以直接说：
+
+```text
+story.next
+→ 当前最该补的是 CH341 的细纲和 FS012 的 reveal
+```
+
+---
+
+## 11. LLM 交互协议
+
+### 系统提示词只放三样
+
+1. 角色和硬规则（不写库外文件、只通过 storydb、每次写入必须带决策）。
+2. 工具清单 + 何时用哪个。
+3. 一张总览 schema card（表名 + 关键字段 + 边），详细字段按需 `storydb schema <table>`。
+
+### 一次典型回合
+
+```text
+LLM: storydb context --chapter 341
+工具: 返回本章相关子图（2-5KB）
+
+LLM: storydb create outline '{"chapter":"CH341","status":"draft",...}'
+工具: ok 或具体字段错误
+
+LLM: storydb link chapter_cast chapter:CH341 character:C001 '{"role":"pov"}'
+工具: ok
+
+LLM: storydb create knowledge_event '{...}'
+工具: error KNOWLEDGE_ORDER，附 hint
+
+LLM: 改 change/coverage，重新 create
+工具: ok
+
+LLM: storydb validate --scope chapter:CH341
+工具: pending: [] / warnings: [...]
+```
+
+### 重试策略
+
+- 硬错误：同一操作最多 3 次，错误原文在 tool result 里。
+- pending：不重试，留给 `story.next`。
+- warning：不阻断，记录到 `validation_issue`。
+
+---
+
+## 12. 实施计划
+
+### P0：地基
+
+1. `schema/definitions.js` + 编译器（DDL/tools/schema card/validators）。
+2. `storydb` CLI：`schema/get/create/update/link/validate/next/context/apply/query`.
+3. `change_set` + `decision` 事务模型。
+4. `requirement` 模型 + `next` 查询。
+5. 单测：编译、事务回滚、决策不残留、requirement 生命周期。
+
+### P1：纵向切片（cast + rhythm）
+
+1. `workflow.cast`：seed 实体 + 边 + requirements。
+2. `workflow.rhythm`：seed chapter + actions + knowledge events。
+3. LLM 用 `context` + `apply` 写 5 章一个小块；DB 错误当场返回。
+4. 对比 token/失败率与当前 `feat/surrealdb`。
+
+### P2：scale / macro / outline / writing
+
+按同一套节点/边/requirement 接。
+
+### P3：影响分析、MCP、Markdown 导出
+
+- `storydb impact relation/foreshadow`。
+- MCP server 包装 CLI。
+- `export md` 从 DB 生成。
+
+---
+
+## 13. 风险与取舍
+
+| 风险 | 应对 |
+|---|---|
+| 工具调用次数增加 | 每次只传相关子图；批量 `apply`；上下文更小 |
+| LLM 不按 schema 写 | schema card + 工具 JSON Schema + 错误 hint |
+| requirement 泛滥 | 创建时去重；支持 `waived`；只对 hard 项阻断 |
+| 事务太大 | 一章/一个 chunk 一个 change_set；批量用 `apply` |
+| 嵌入单进程 | 首版接受；后续切 server |
+| 旧数据迁移 | `feat/surrealdb` 保留为 fallback；新分支从空库开始 |
+| 质量规则误判 | 只做 warning，不阻断；可 `ignore` |
+
+---
+
+## 14. 和当前 `feat/surrealdb` 的关系
+
+保留：
+
+- 嵌入式 SurrealDB 连接、schema 迁移、图/事件/时序模型。
+- `knowledge_event` + `knowledge_state` 回放。
+- 影响分析的图查询思路。
+
+替换：
+
+- 阶段 JSON 投影 → 直接写 DB。
+- `importStage` → `story.apply`。
+- 文件校验器为主 → DB 硬约束 + requirement + 查询式 warning。
+- `.reference-decisions.md` append-only → `decision` + `change_set` 事务。
+
+`feat/surrealdb` 继续作为可用备份；`feat/story-graph` 是下一版。
+
+---
+
+## 15. 实现状态（P0–P3）
+
+- [x] `schema/definitions.js` + 编译器（DDL / schema card / tool schema）
+- [x] `storydb` CLI：schema / get / search / context / create / update / link / unlink / apply / validate / next / why / history / query / impact / export / import
+- [x] `change_set` + `decision` 同事务；`why` / `history`；`export decisions`
+- [x] `requirement` 占位 + `next` 待办队列
+- [x] `stage-check`：scale/macro/cast/rhythm/outline/writing 的数据库完成度检查
+- [x] 6 个 `build` 命令切到 storydb 提示词 + stage-check 驱动
+- [x] `tools query` / `tools analyze` / `tools export` 在 graph 模式下直连故事图
+- [x] `FANCY_STORY_GRAPH=0` 回退旧文件管线
+- [x] 硬约束：悬空边、知识时间线、钩子连续重复、时间线倒退、`complete` 守卫
+- [x] 软待办：伏笔 reveal、章节细纲/正文、爽点 setup
+- [x] 质量 warning：情绪平流、黄金三章、主线/冲突覆盖
+- [x] `context`：章节 + 细纲 + 场景 + 出场人物 + 待办 + 前三章 handoff/结尾 + 全文检索
+- [x] 中文全文索引：`TOKENIZERS class FILTERS lowercase, ngram(1,2)`
+- [x] 影响分析：relation / foreshadow
+- [x] 旧阶段 JSON 导入：scale / macro / cast / rhythm / outline / writing
+- [x] Markdown 导出：10-scale ~ 50-writing + decisions
+- [x] MCP stdio server（12 个工具）
+- [x] 插件入口：`/fancy-story-builder tools graph ...`
+- [x] 测试：storydb-core 7 个用例 + 全量 1883 通过

package/docs/story-graph-validation.md

@@ -0,0 +1,81 @@
+> 2026-11 架构更新：校验正在下沉到数据库。`fancy-db init` 会生成 `fn::fancy::validate($scope)`；写入硬规则仍由 `DEFINE EVENT` 执行。目录与命令以 [workspace-mcp.md](./workspace-mcp.md) 为准。
+
+# 故事图校验：谁校验、校验什么、信任边界
+
+## 1. 谁执行校验
+
+有三层，职责不同：
+
+| 层 | 谁执行 | 作用 |
+| --- | --- | --- |
+| 写入事件 | SurrealDB 自己 | 硬约束，写入时立即拒绝并回滚 |
+| `storydb validate` / `stage-check` | LLM 或用户通过 CLI | 自查、看缺口；不是最终裁决 |
+| `runStageLoop` 的 `stageCheck` | 插件进程（`driver.js` / `stage-command.js`） | 最终门禁；LLM 回合结束后由插件执行 |
+
+关键点：**最终门禁不是 LLM 跑出来的结果**。LLM 回合结束后，插件关闭数据库、重新打开，调用 `stageCheck`；不通过就把 `errors` 原文回灌给 LLM。LLM 自己运行的 `stage-check` 只是提前发现问题。
+
+## 2. 校验什么
+
+### 写入时（数据库事件）
+
+- `chapter_guard`：卷/幕必须存在；`emotion.value` 1-10；连续 3 章同 `hook.type`；`time.story_day` 不能倒退（闪回要标 `flashback=true`）。
+- `foreshadow_order`：`plant` 必须早于 `progress` / `reveal`；`reveal` 后不能再 `plant`。
+- `payoff_order`：`setup` 必须早于 `payoff`；已有更晚的 setup 时不能补更早的 payoff。
+- `knowledge_rules`：`change` / `coverage` 映射、`how=told` 的来源、知识状态不能从 `full` 再学、误信必须先 `corrects`。
+- `complete_*`：有 hard `requirement` 未完成时，不能把实体标成 `complete`。
+- `fill_*` / `unfill_*`：章节动作、细纲、正文写入/删除时同步 requirement。
+
+### `validate`（全局/范围检查）
+
+- hard requirement 仍在 pending 却已标 `complete` → error。
+- 连续 3 章同钩子、时间线倒退 → error。
+- 伏笔回收早于埋设、爽点兑现早于铺垫 → error。
+- 伏笔/爽点还没有任何章节动作 → pending。
+- 主线节点/冲突没有章节落点、情绪连续平流、黄金三章钩子弱 → warning。
+
+### `stage-check`
+
+| 阶段 | 额外检查 |
+| --- | --- |
+| `scale` | scale 存在；有卷/幕；卷覆盖 1..target；卷起止不倒置 |
+| `macro` | world_doc / story_doc / line / line_node / ending / role_slot 均存在 |
+| `cast` | 人物按类型、势力、势力关系、地点、道具、冲突、伏笔、高潮、爽点达到 scale 配额 |
+| `rhythm` | 章节数达到 target、章号无缺口、每章至少 1 个 cast，加上 `validate` 的非 pending 错误 |
+| `outline` | 每章有 outline、每个 outline 至少 1 个 scene，加上 `validate` 的错误 |
+| `writing` | 每章有 chapter_text、word_count > 0，加上 `validate` 的错误 |
+
+## 3. 信任边界：LLM 改脚本怎么办
+
+- `storydb` CLI 现在通过 **writer 会话** 访问数据库：`story_writer` 是 `VIEWER` 角色，但数据表通过 `ALTER TABLE ... PERMISSIONS FOR select, create, update, delete FULL` 开放 CRUD。
+- 这个会话**不能** `DEFINE` / `REMOVE` 表、函数、事件，也不能改 schema；schema 初始化只发生在插件 root 会话。
+- 硬规则本身是数据库事件，LLM 即使改 CLI 代码，也不能让数据库接受非法写入。
+- 最终 `stageCheck` 在插件进程里执行。插件进程在 LLM 回合开始前已经加载了 `stage.js` / `store.js`，本轮内编辑磁盘文件不会替换已加载的模块。
+- 仍然存在的边界：LLM 如果有任意 shell 且能直接运行 Node，它可以绕过 CLI 用 root 打开嵌入式数据库。要彻底防住，需要 OS 级沙箱/只读挂载/独立用户；仅靠插件代码做不到。
+
+## 4. SurrealDB 函数/存储过程研究结论
+
+在本机嵌入模式下已验证：
+
+```sql
+DEFINE FUNCTION fn::story::check_scale() {
+  RETURN SELECT count() FROM volume GROUP ALL;
+};
+RETURN fn::story::check_scale();
+```
+
+可以创建并调用用户函数；事件触发器也已经在用。SurrealDB 还支持 `DEFINE USER`：
+
+```sql
+DEFINE USER story_writer ON ROOT PASSWORD '...' ROLES VIEWER;
+```
+
+并验证了：`VIEWER` + 表级 `PERMISSIONS ... FULL` 可以读写记录，但不能 `DEFINE FUNCTION` / `DEFINE TABLE`。CLI 已切到这个 writer 会话。
+
+### 为什么不把所有校验都搬进函数
+
+`scale` / `cast` 的计数检查可以很容易写成 SQL；但 `validate` 里有跨 500 章的循环（连续钩子、时间线、覆盖）和带优先级的错误/警告分类，用 SurrealQL 写会明显更难维护。当前策略是：
+
+1. 硬约束留在事件（已经是数据库内）。
+2. 最终门禁留在插件进程（不信任 LLM）。
+3. writer 会话限制 schema/函数修改。
+4. 后续可把 `stage-check` 的计数部分做成 `fn::story::stage_metrics($stage)`，复杂规则继续保留在插件侧。