@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/storydb/README.md

@@ -0,0 +1,271 @@
+# storydb — 故事图工作台
+
+> 分支：`refactor/workspace-mcp`
+> 目标：LLM 通过 MCP 工具在 SurrealDB 故事图上读写，不再生成阶段 JSON。
+>
+> v3 架构：一个工作区一个独立 SurrealDB server；每个项目一个 database + 独立用户；项目目录是 `A/projects/<uuid>`。完整说明见 [docs/workspace-mcp.md](../../../docs/workspace-mcp.md)。CLI 保留为调试/运维入口，不再是指令提示词里的主接口。
+
+## 1. 一句话
+
+```text
+LLM → MCP 工具（story_*） → SurrealDB server（图 + 文档 + 事件 + 时序 + 全文索引）
+运维/调试 → storydb CLI
+```
+
+- 写入即校验，错误原文返回。
+- 缺细节是 `pending`，不是 `error`。
+- 每次写入是一个 `change_set`，决策和数据同事务。
+- 查询只取相关子图，不读整份文件。
+
+## 2. 数据库
+
+```text
+A/.fancy/surreal/                 ← 独立 SurrealDB server 数据
+A/projects/<uuid>/                ← 项目目录
+  .fancy-project.json             ← UUID / database / db user
+namespace: fancy
+  fancy_registry                  ← 项目注册表
+  proj_<uuid>                     ← 每个项目一个库
+    fn::fancy::validate($scope)   ← 数据库内置校验
+```
+
+项目连接信息由 `.fancy-project.json` 和 `A/.fancy/secrets.json` 提供；不再使用嵌入式 `.fancy-storydb`。初始化/升级 schema：
+
+```bash
+/fancy-db init
+```
+
+## 3. 命令
+
+```bash
+node plugins/fancy-story-builder/storydb/cli.js [--db <项目根>] <command>
+```
+
+### 看 schema
+
+```bash
+storydb schema foreshadow
+storydb schema
+```
+
+### 读
+
+```bash
+storydb get character C001
+storydb get foreshadow FS012
+storydb search foreshadow --where status=draft --limit 20
+storydb context --chapter 341 --prev 3
+storydb context --entity foreshadow:FS012
+storydb context --chapter 341 --search "旧堤泵房"
+```
+
+`context --chapter` 返回：
+
+```json
+{
+  "chapter": {...},
+  "outline": {...},
+  "scenes": [...],
+  "cast": [...],
+  "locations": [...],
+  "knowledge": [...],
+  "actions": [{ "kind": "foreshadow", "entity_id": "FS012", "action": "plant", "chapter_no": 341 }],
+  "knowledge_events": [{ "subject_id": "FS012", "change": "learns", "coverage": "partial" }],
+  "requirements": [...],
+  "foreshadows_due": [...],
+  "payoffs_due": [...],
+  "previous": [
+    { "display_no": 340, "title": "...", "handoff": {...}, "tail": "（最后 600 字）" }
+  ],
+  "search": [{ "display_no": 312, "score": 0.86, "snippet": "..." }]
+}
+```
+
+### 写
+
+```bash
+storydb create foreshadow '{"id":"FS012","name":"空白的来源栏","type":"medium","scope":"volume"}'
+storydb apply ops.json                    # 一个事务
+storydb apply --per-chapter chapters.json # 多章，每章一个独立事务
+storydb stage-check rhythm
+storydb update foreshadow FS012 '{"status":"draft"}'
+storydb link foreshadow_action chapter:CH341 foreshadow:FS012 '{"action":"plant","chapter_no":341}'
+storydb unlink foreshadow_action chapter:CH341 foreshadow:FS012 --action plant
+```
+
+### 批量（推荐）
+
+```bash
+storydb apply ops.json
+```
+
+```json
+{
+  "workflow": "rhythm",
+  "summary": "写第 341 章",
+  "ops": [
+    { "op": "create", "kind": "chapter", "data": { "chapter_id": "CH341", "...": "..." } },
+    { "op": "link", "edge": "chapter_cast", "from": "chapter:CH341", "to": "character:C001", "data": { "role": "pov" } },
+    { "op": "link", "edge": "foreshadow_action", "from": "chapter:CH341", "to": "foreshadow:FS012", "data": { "action": "plant", "chapter_no": 341 } },
+    { "op": "knowledge", "data": { "chapter_id": "CH341", "subject_id": "FS012", "character_id": "C001", "change": "learns", "coverage": "partial" } }
+  ],
+  "decisions": [
+    { "subject": "chapter:CH341", "text": "本章让 C001 第一次看到来源栏", "source": "references/节奏指导/..." }
+  ]
+}
+```
+
+一个 `apply` 是一个事务：所有 ops + decisions 要么全成，要么全滚。
+
+### 校验 / 待办
+
+```bash
+storydb validate --scope chapter:CH341
+storydb stage-check rhythm
+storydb next --limit 20
+```
+
+### 影响分析
+
+```bash
+storydb impact relation C001 C002 --to 对立 --from 341
+storydb impact foreshadow FS012 --action reveal --chapter 400
+```
+
+### 导出
+
+```bash
+storydb export md 30-cast
+storydb export md all
+storydb export decisions
+```
+
+### 导入旧阶段 JSON
+
+```bash
+storydb import scale
+storydb import macro
+storydb import cast
+storydb import rhythm
+storydb import outline
+storydb import writing
+storydb import all
+```
+
+每个 chapter/outline/text 一个 `change_set`；失败的章节回滚，不影响已成功的章节。
+
+## 4. 数据模型
+
+### 节点
+
+```text
+story / scale / volume / act / chapter
+world_doc / story_doc / line / line_node / ending / role_slot / emotion_doc
+character / faction / location / item / conflict / foreshadow / payoff / climax / information
+outline / scene / chapter_text / handoff
+requirement / change_set / decision / validation_issue
+```
+
+### 边
+
+```text
+has_volume / has_act / has_chapter
+chapter_cast / chapter_location / chapter_line_node / chapter_branch / chapter_conflict
+relation / faction_relation / membership
+conflict_participant / climax_participant / foreshadow_payoff
+foreshadow_action / payoff_action / info_action / ending_action
+outline_scene / outline_cast / outline_location / outline_foreshadow
+scene_cast / scene_location / scene_foreshadow
+```
+
+### 生命周期
+
+```text
+seed → draft → complete → locked → archived
+```
+
+- `seed`：只有 id/name，缺细节正常。
+- `complete`：所有 hard requirement 必须 filled，否则 DB 拒绝。
+- `archived`：历史版本，不参与默认查询。
+
+### requirement（占位/待办）
+
+```text
+foreshadow: plant(hard) / progress(soft) / reveal(hard)
+payoff:     setup(hard) / payoff(hard)
+chapter:    outline(hard) / draft(hard)
+outline:    scenes(hard) / cast(soft)
+character:  arc(soft) / voice(soft)
+```
+
+缺细节不是错误，`next` 会列出来；只有 `status=complete` 时还有 hard pending 才报错。
+
+## 5. 事务与决策
+
+```text
+change_set = 一次写入事务
+decision   = 一条设计决策，必须属于某个 change_set
+```
+
+- 数据 + 决策同一个事务；回滚时一起消失。
+- 返工创建新 `change_set`，旧决策标 `superseded`。
+- `storydb why <subject>` 只看 active 决策。
+- `storydb history <subject>` 看全部版本。
+- `.reference-decisions.md` 不再是 append-only 事实源，只能是 `export decisions` 的导出物。
+
+## 6. 硬约束 vs 待办 vs 警告
+
+| 类型 | 例子 | 行为 |
+|---|---|---|
+| 硬约束 | 悬空边、知识状态回退、`hook` 连续 3 章重复、时间线倒退、`complete` 还有 hard pending | 写入失败、事务回滚 |
+| 待办 | 伏笔缺 reveal、章节缺细纲/正文、爽点缺 setup | 写入成功，`next` 列出 |
+| 警告 | 情绪平流、黄金三章钩子弱、主线/冲突缺章节落点 | 写入成功，`validate` 返回 warning |
+
+## 7. 全文索引与连续性
+
+- `chapter_text.content` 有 `FULLTEXT` 索引，写入/修改自动维护。
+- 中文用 `TOKENIZERS class FILTERS lowercase, ngram(1,2)`，`@1@` 查询可用。
+- `context --chapter N --prev 3` 返回前三章的 `handoff` + 结尾 600 字。
+- `handoff` 记录：`end_location` / `end_time` / `end_characters` / `open_threads` / `next_scene_hint` / `continuity_notes`。
+
+## 8. 从插件命令使用
+
+`/fancy-build scale|macro|cast|rhythm|outline|write` 已切到 storydb：
+
+```text
+1. 插件读取故事图，生成紧凑上下文
+2. 提示 LLM 用 storydb CLI 写库
+3. LLM 每个 apply 一个事务
+4. 插件运行 stage-check，把 DB 错误原文回给 LLM
+5. 通过后进入下一阶段
+```
+
+回退旧文件管线：`FANCY_STORY_GRAPH=0`。
+
+## 9. LLM 使用方式
+
+系统提示词只需要三样：
+
+1. 只能通过 `storydb` 读写，不许写阶段 JSON。
+2. 每次写入必须带 `change_set`（`apply`）和决策。
+3. 先 `context` / `get`，再写；写完 `validate`。
+
+典型回合：
+
+```text
+storydb context --chapter 341 --prev 3
+storydb apply ops.json
+storydb validate --scope chapter:CH341
+storydb next --limit 5
+```
+
+## 10. 已知边界
+
+- 嵌入式单进程；同一项目不能同时被两个会话写。
+- 开发期 schema 变更：当前 DDL 用 `IF NOT EXISTS`，不会覆盖旧字段类型；如果之前用早期 story-graph 版本建过 `story` 库，删掉 `.fancy-storydb` 重建即可（旧数据不保留）。
+- `import` 建议一次完成；正式数据以 LLM 直接 `apply` 为主。
+- 章节写入用 `apply --per-chapter`：每章独立 `change_set`，失败只回滚该章。`workflow: "rhythm"` 时默认替换该章的 cast/action 边。
+- `storydb` 首版是 CLI，后续包 MCP。
+- `/fancy-build ...` 已切到 storydb 提示词 + stage-check；`FANCY_STORY_GRAPH=0` 可回退旧文件管线。
+- `tools graph` / `storydb` / MCP 是同一套底层能力。
+- 质量规则只做 warning；硬规则才回滚。