docs: slim README to entry point, move detail into docs/usage

2026-06-13 18:31:16 +08:00 · 2026-05-31 17:34:32 +00:00
parent 061b8cd19a
commit f33bfcb380
9 changed files with 697 additions and 973 deletions
--- a/README.md
+++ b/README.md
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,15 +1,24 @@
-# ST-BME 开发者文档
+# ST-BME 文档

-这里是 ST-Bionic-Memory-Ecology（ST-BME）的**开发者/架构文档**。面向想理解内部原理、算法、或参与维护的人。
+这里是 ST-Bionic-Memory-Ecology（ST-BME）的完整文档。仓库根目录的 [`README.md`](../README.md) 是精简入口（介绍、安装、快速上手、导航），细节都在这里。

-普通用户的安装、面板、配置、排障说明在仓库根目录的 [`README.md`](../README.md)，本目录不重复。
+- 想**用好插件**（配置、面板、排障、存储）→ 看 [`usage/`](#usage--使用手册)
+- 想**理解内部原理**（架构、算法、功能机制）或**参与维护** → 看后面几节

 ## 文档地图

+### usage/ — 使用手册
+面向用户："怎么配、怎么用、出问题怎么查"。从精简后的 README 下沉的详细内容。
+
+- [`configuration.md`](usage/configuration.md) — 完整配置参考：记忆 LLM、Embedding、提取/召回/认知/维护设置、任务预设、ENA、隐藏/渲染、Native
+- [`panel.md`](usage/panel.md) — 面板导览：总览、任务、操作、配置、图谱区域
+- [`troubleshooting.md`](usage/troubleshooting.md) — 排障指南
+- [`storage-and-sync.md`](usage/storage-and-sync.md) — 数据存储、云端镜像、兼容兜底、持久召回卡片
+
 ### architecture/ — 架构与控制平面
 跨文件的结构、数据路径、不变量。这些内容变化慢，是理解"为什么这样组织"的入口。

- [`overview.md`](architecture/overview.md) — 子系统地图 + 写入/读取/安全三条数据路径
+- [`overview.md`](architecture/overview.md) — 子系统地图 + 写入/读取/安全三条数据路径 + 完整目录结构 + 事件挂载
 - [`control-plane.md`](architecture/control-plane.md) — 身份解析、持久化状态机、必须维持的不变量
 - [`storage-and-formats.md`](architecture/storage-and-formats.md) — 存储分层、快照契约、向前兼容纪律
 - [`server-integration.md`](architecture/server-integration.md) — 三档 Authority 集成、自动降级/升级、能力探测
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -85,3 +85,140 @@ Restore Lock → 恢复期间阻断图谱变更
 - **数据平面**：实际的 IndexedDB/OPFS/Authority/Luker 读写。仍在编排层，由控制平面的决定驱动。

 这条分界是过去大量 bug（陈旧 pending、未进入聊天、reroll 乱召回、一致性漂移）的修复基础。详见 [`control-plane.md`](control-plane.md)。
+
+## 完整目录结构
+
+```text
+ST-BME/
+├── index.js                       # 主入口：事件绑定、流程调度、历史恢复、持久化协调
+├── manifest.json                  # SillyTavern 扩展清单
+├── style.css                      # 扩展样式
+├── package.json                   # 测试与开发脚本
+│
+├── graph/                         # 图数据模型与领域状态
+│   ├── graph.js                   # 节点/边 CRUD、序列化、迁移
+│   ├── graph-persistence.js       # 持久化常量、加载状态、身份别名
+│   ├── schema.js                  # 节点和关系 Schema
+│   ├── memory-scope.js            # 主客观作用域与空间区域
+│   ├── knowledge-state.js         # 认知归属、可见性、区域状态
+│   ├── story-timeline.js          # 故事时间线
+│   ├── summary-state.js           # 活跃总结状态
+│   └── node-labels.js             # 节点显示名工具
+│
+├── maintenance/                   # 写入链路
+│   ├── extractor.js               # LLM 提取管线
+│   ├── extraction-controller.js   # 自动/手动提取编排
+│   ├── extraction-success-controller.js # 提取成功后处理编排（注入式）
+│   ├── reroll-recovery-controller.js # reroll 回滚 + 历史恢复编排（注入式）
+│   ├── extraction-context.js      # 结构化消息和边界过滤
+│   ├── chat-history.js            # 楼层、hash、历史恢复工具
+│   ├── consolidator.js            # 记忆整合
+│   ├── compressor.js              # 压缩与遗忘
+│   ├── hierarchical-summary.js    # 小总结和折叠总结
+│   ├── smart-trigger.js           # 智能触发
+│   └── task-graph-stats.js        # 任务图谱统计
+│
+├── retrieval/                     # 读取链路
+│   ├── retriever.js               # 召回编排
+│   ├── shared-ranking.js          # 共享排序核心
+│   ├── recall-controller.js       # 召回输入和注入控制
+│   ├── recall-persistence.js      # 消息级召回持久化
+│   ├── retrieval-enhancer.js      # 多意图、DPP、残差召回
+│   ├── diffusion.js               # 图扩散
+│   ├── dynamics.js                # 混合评分与访问强化
+│   └── injector.js                # 注入格式化
+│
+├── prompting/                     # Prompt 与任务预设
+│   ├── prompt-builder.js
+│   ├── prompt-profiles.js
+│   ├── default-task-profile-templates.js
+│   ├── prompt-node-references.js
+│   ├── task-regex.js
+│   ├── task-worldinfo.js
+│   ├── task-ejs.js
+│   ├── injection-sanitizer.js
+│   └── mvu-compat.js
+│
+├── llm/                           # LLM 请求封装
+│   ├── llm.js
+│   └── llm-preset-utils.js
+│
+├── vector/                        # 向量索引与直连 Embedding
+│   ├── vector-index.js
+│   ├── vector-gate.js             # 向量准备/修复门禁策略
+│   ├── vector-sync-controller.js  # 向量同步编排（注入式）
+│   └── embedding.js
+│
+├── runtime/                       # 运行时状态和设置
+│   ├── identity-resolver.js        # 身份解析核心
+│   ├── runtime-state.js
+│   ├── reroll-transaction-boundary.js # reroll 召回复用事务边界
+│   ├── recall-input-state.js       # 召回 input/intent/trivial-skip 状态工厂
+│   ├── reroll-recall-input.js      # reroll 复用 + planner handoff 输入工厂
+│   ├── generation-recall-transactions.js # 生成召回事务生命周期工厂
+│   ├── final-recall-injection.js   # 最终召回注入解析工厂
+│   ├── auto-extraction-defer.js    # 自动提取 defer/resume 工厂
+│   ├── planner-recall-controller.js # ENA planner 召回管线（注入式）
+│   ├── settings-defaults.js
+│   ├── generation-options.js
+│   ├── planner-tag-utils.js
+│   ├── request-timeout.js
+│   ├── runtime-debug.js
+│   ├── debug-logging.js
+│   └── user-alias-utils.js
+│
+├── sync/                          # 持久化与同步
+│   ├── bme-db.js                  # IndexedDB 数据层
+│   ├── bme-opfs-store.js          # OPFS/sidecar 存储
+│   ├── bme-sync.js                # 云端镜像与备份恢复
+│   ├── bme-chat-manager.js        # chatId → 数据库生命周期
+│   ├── persistence-reducer.js      # 持久化 accepted/queued/pending reducer
+│   ├── graph-persistence-io.js     # IndexedDB 图谱 save/load/queue/retry（注入式）
+│   ├── graph-load-persist.js       # 图谱加载/持久化/authority 编排（注入式）
+│   ├── graph-mutation-gate.js      # 图谱变更门禁 + 持久化 live-state 投影（注入式）
+│   ├── legacy-persistence-repair.js # 旧状态安全修复策略
+│   ├── graph-snapshot-schema.js    # 耐久快照契约：冻结顶层键 + 宽容解析
+│   └── graph-snapshot-upgrade.js   # 快照 upgrade-on-read 就地升级链
+│
+├── host/                          # SillyTavern 宿主适配
+│   ├── event-binding.js
+│   ├── runtime-host-adapter.js
+│   ├── st-context.js
+│   ├── st-native-render.js
+│   └── adapter/
+│
+├── ui/                            # 面板、图谱和消息级 UI
+│   ├── panel.html
+│   ├── panel.js
+│   ├── panel-bridge.js
+│   ├── panel-ena-sections.js
+│   ├── ui-actions-controller.js
+│   ├── ui-status.js
+│   ├── message-render-limit.js    # 聊天区渲染楼层限制策略
+│   ├── history-notice.js          # 历史变更通知文案
+│   ├── graph-renderer.js
+│   ├── graph-layout-solver.js
+│   ├── graph-native-bridge.js
+│   ├── recall-message-ui.js
+│   ├── recall-message-ui-controller.js # 召回卡片挂载/刷新工厂（封装定时器/observer 状态）
+│   ├── hide-engine.js
+│   ├── notice.js
+│   └── themes.js
+│
+├── ena-planner/                   # ENA Planner
+├── native/                        # Native/WASM 源码与构建产物相关目录
+├── vendor/                        # vendored 依赖
+├── lib/                           # 浏览器侧库文件
+└── tests/                         # Node 回归测试与性能测试
+```
+
+## 事件挂载
+
+| SillyTavern 事件 | ST-BME 行为 |
+| --- | --- |
+| `CHAT_CHANGED` | 加载当前聊天图谱，恢复持久状态，应用隐藏/渲染限制 |
+| `GENERATION_AFTER_COMMANDS` | 助手回复后触发自动提取 |
+| `GENERATE_BEFORE_COMBINE_PROMPTS` | 生成前召回并注入 |
+| `MESSAGE_SENT` | 捕获发送意图和权威用户输入 |
+| `MESSAGE_RECEIVED` | 更新自动提取队列和持久化状态 |
+| 编辑 / 删除 / Swipe | 检测历史变化并恢复 |
--- a/docs/contributing/development.md
+++ b/docs/contributing/development.md
@@ -21,6 +21,56 @@ npm install

 控制面/数据格式专项测试见 [`testing.md`](testing.md)。

+## 完整脚本参考
+
+控制面与数据格式专项：
+
+```bash
+npm run test:identity-resolver
+npm run test:persistence-reducer
+npm run test:runtime-deps
+npm run test:vector-gate
+npm run test:reroll-transaction-boundary
+npm run test:graph-snapshot-schema
+npm run test:graph-snapshot-upgrade
+npm run test:snapshot-forward-compat
+npm run test:luker-snapshot-forward-compat
+```
+
+持久化矩阵：
+
+```bash
+npm run test:persistence-matrix
+```
+
+IndexedDB 专项：
+
+```bash
+npm run test:indexeddb
+```
+
+Native / 性能相关：
+
+```bash
+npm run test:native-layout-parity
+npm run bench:graph-layout
+npm run bench:persist-delta
+npm run bench:persist-load
+npm run bench:load-preapply
+```
+
+构建 Native WASM：
+
+```bash
+npm run build:native:wasm
+```
+
+更新 manifest 版本：
+
+```bash
+npm run version:bump-manifest
+```
+
 ## 提交前

 至少运行：
--- a/docs/contributing/testing.md
+++ b/docs/contributing/testing.md
@@ -42,6 +42,20 @@ ST-BME 的测试是 Node 回归测试（`tests/*.mjs`），`npm run test:stable`

 详见 [`conventions.md`](conventions.md)。

+## 重要测试文件
+
+- **`tests/p0-regressions.mjs`** — 主回归集合，覆盖提取、召回、恢复、UI 关键路径。
+- **`tests/runtime-history.mjs`** — 消息 hash、历史 dirty、恢复状态。
+- **`tests/message-render-limit.mjs`** — 聊天区渲染限制和渲染切片历史保护。
+- **`tests/graph-persistence.mjs`** — 图谱持久化基础行为。
+- **`tests/identity-resolver.mjs` / `tests/persistence-reducer.mjs`** — 身份解析核心、持久化 accepted/queued/pending 状态机。
+- **`tests/runtime-deps-completeness.mjs`** — 检查注入式控制器模块的 `runtime.X` 依赖均由对应 builder 提供。
+- **`tests/graph-snapshot-schema.mjs` / `tests/snapshot-forward-compat.mjs`** — 耐久快照契约、宽容解析和真实存储向前兼容往返。
+- **`tests/indexeddb-persistence.mjs`** — IndexedDB 快照、增量提交、hydrate。
+- **`tests/indexeddb-sync.mjs`** — 云端同步与冲突合并。
+- **`tests/native-rollout-matrix.mjs`** — Native 灰度开关和阈值迁移。
+- **`tests/task-profile-migration.mjs`** — 任务预设迁移。
+
 ## 已知环境限制

 - `tests/indexeddb-migration.mjs` 等需要 IndexedDB 测试依赖；某些 Node 环境缺失会失败，非代码问题。
--- a/docs/usage/configuration.md
+++ b/docs/usage/configuration.md
@@ -0,0 +1,202 @@
+# 主要配置
+
+本文从 [README](../../README.md) 拆出 ST-BME 的主要用户配置说明，保留设置名称、默认值和表格，便于按功能查阅。
+
+### 记忆 LLM
+
+记忆 LLM 用于：
+
+- 提取记忆。
+- 召回精排。
+- 整合。
+- 压缩。
+- 小总结。
+- 总结折叠。
+- 反思。
+- ENA Planner 规划。
+
+配置方式：
+
+- **留空**
+  - 复用当前 SillyTavern 聊天模型。
+
+- **填写 OpenAI-compatible 配置**
+  - 使用独立模型处理记忆任务。
+  - 适合把主聊天模型和后台维护模型分开。
+
+安全建议：
+
+- 不要把包含 API Key 的 `extension_settings` 或浏览器存储导出后公开。
+- 调试日志默认关闭，需要排障时再临时开启。
+
+### Embedding
+
+Embedding 是智能召回的核心。
+
+#### 后端模式
+
+推荐优先使用后端模式：
+
+- 复用 SillyTavern 后端的 embedding provider。
+- 通常不需要浏览器直接持有 embedding API Key。
+- 可使用 SillyTavern 已支持的 OpenAI、Cohere、Mistral、Ollama、LlamaCpp、vLLM 等来源。
+
+#### 直连模式
+
+直连模式由浏览器直接请求 embedding 服务：
+
+- 需要填写 API 地址、Key 和模型。
+- 可能遇到 CORS 限制。
+- 适合自建网关或独立 embedding 服务。
+
+> 切换 embedding 模式或模型后，建议执行“重建向量”。
+
+### 提取设置
+
+| 设置 | 默认 | 说明 |
+| --- | --- | --- |
+| 每 N 条回复提取 | `1` | 每几条助手回复触发一次提取 |
+| 提取上下文轮数 | `2` | 提取时向前看的对话轮数 |
+| 自动延后最新助手 | `false` | 可让最新回复稳定后再提取 |
+| Assistant 排除标签 | `think,analysis,reasoning` | 默认排除推理标签 |
+| 提取消息上限 | `0` | `0` 表示不限 |
+| 提取 Prompt 结构模式 | `both` | 同时提供 transcript 和 structured messages |
+| 提取世界书模式 | `active` | 复用当前激活世界书上下文 |
+| 包含故事时间 | `true` | 提取时提供故事时间线 |
+| 包含总结快照 | `true` | 提取时提供活跃总结 |
+| 手动提取模式 | `pending` | 面板中的提取模式默认值 |
+
+### 召回设置
+
+| 设置 | 默认 | 说明 |
+| --- | --- | --- |
+| 启用召回 | `true` | 生成前自动检索记忆 |
+| 向量预筛 | `true` | 先用 embedding 找候选 |
+| 图扩散 | `true` | 沿图关系扩散相关节点 |
+| LLM 精排 | `true` | 让 LLM 从候选中筛最终结果 |
+| 召回 Top-K | `20` | 向量预筛数量 |
+| 最终节点上限 | `12` | 注入前最多保留节点数 |
+| 图扩散 Top-K | `100` | 图扩散候选数量 |
+| LLM 候选池 | `30` | 进入精排的候选池大小 |
+| 多意图拆分 | `true` | 一条输入拆成多个检索意图 |
+| 上下文混合查询 | `true` | 融合当前输入、上一轮助手、前一条用户消息 |
+| 词法增强 | `true` | 关键词精确匹配加权 |
+| 时序链接 | `true` | 临近时间节点互相增强 |
+| 多样性采样 | `true` | 避免召回结果过于同质 |
+
+### 认知与空间设置
+
+| 设置 | 默认 | 说明 |
+| --- | --- | --- |
+| Scoped Memory | `true` | 启用作用域记忆 |
+| POV Memory | `true` | 启用角色/用户视角记忆 |
+| 区域目标 | `true` | 区分当前区域、邻接区域、全局 |
+| 认知记忆 | `true` | 启用主客观认知归属 |
+| 空间邻接 | `true` | 地区之间可建立邻接关系 |
+| 故事时间线 | `true` | 启用故事时间标签 |
+| 注入故事时间标签 | `true` | 在注入中提示当前故事时间 |
+| 软时间引导 | `true` | 以提示方式引导，不强制改写 |
+
+### 维护设置
+
+| 设置 | 默认 | 说明 |
+| --- | --- | --- |
+| 启用整合 | `true` | 相似/冲突记忆分析与合并 |
+| 整合阈值 | `0.85` | 相似度触发阈值 |
+| 启用小总结 | `true` | 兼容旧 `synopsis` 名称 |
+| 启用层级总结 | `true` | 使用小总结 + 折叠的总结体系 |
+| 小总结频率 | `3` | 每几次提取生成小总结 |
+| 总结折叠扇入 | `3` | 同层总结达到几条后折叠 |
+| 启用智能触发 | `false` | 只在高信息量场景增强提取 |
+| 启用主动遗忘 | `false` | 周期性降低低价值节点 |
+| 启用概率召回 | `false` | 少量弱相关记忆按概率入围 |
+| 启用反思 | `true` | 周期性总结长期趋势 |
+| 启用自动压缩 | `true` | 按提取周期压缩同类记忆 |
+
+### 任务预设与正则清理
+
+任务预设类型：
+
+- **`extract`**
+  - 记忆提取。
+
+- **`recall`**
+  - 召回精排。
+
+- **`compress`**
+  - 记忆压缩。
+
+- **`synopsis`**
+  - 小总结生成。
+
+- **`summary_rollup`**
+  - 总结折叠。
+
+- **`reflection`**
+  - 长期反思。
+
+- **`consolidation`**
+  - 记忆整合。
+
+- **`planner`**
+  - ENA Planner 规划。
+
+正则清理用于减少污染标签进入提取、召回和注入：
+
+- `thinking` / `think` / `analysis` / `reasoning`
+- `choice`
+- `UpdateVariable`
+- `status_current_variable`
+- `StatusPlaceHolderImpl`
+
+用户可以在“任务预设”中调整全局正则和任务局部规则。显式保存为空规则时，插件不会自动把默认规则加回去。
+
+### ENA Planner
+
+ENA Planner 现在通过 `planner` 任务预设接入。更深入的实现与流程说明见 [ENA Planner 功能文档](../features/ena-planner.md)。它可以使用：
+
+- 角色卡块。
+- 世界书块。
+- 最近聊天块。
+- BME 召回记忆块。
+- 历史 `<plot>` 块。
+- 当前玩家输入块。
+
+建议：
+
+- 在“配置 → ENA 规划器”中配置基础 API 和启用状态。
+- 在“配置 → 任务预设 → planner”中调整规划 prompt 结构和生成参数。
+
+### 隐藏旧楼层与渲染限制
+
+这是两个不同功能；更深入的实现与边界说明见 [隐藏旧楼层与渲染限制功能文档](../features/hide-and-render.md)：
+
+- **隐藏旧楼层**
+  - 用于控制上下文 token。
+  - 不删除聊天内容。
+  - 通过酒馆隐藏机制让较早楼层不再参与主回复和 ST-BME 读取。
+
+- **限制聊天区渲染楼层**
+  - 用于减少超长聊天界面卡顿。
+  - 同步到 SillyTavern 的 `chat_truncation`。
+  - 只控制前端最多加载最近多少条。
+  - 不等于上下文隐藏，也不等于删除消息。
+
+重要提示：
+
+- 如果你要对很早的楼层做“重新提取范围”或完整历史恢复，建议临时关闭渲染限制或调大数量并刷新。
+- 当 ST-BME 检测到当前 `context.chat` 很可能只是最近 N 条渲染切片时，会暂停破坏性历史恢复，避免误清空运行时图谱。
+
+### Native 性能加速
+
+Native 加速目前是灰度能力，更深入的实现与回退策略见 [Native 性能加速功能文档](../features/native-acceleration.md)，覆盖：
+
+- 图布局。
+- Persist Delta。
+- 快照 Hydrate。
+
+默认策略：
+
+- 按节点、边、记录数、结构变化和序列化体积阈值自动命中。
+- `Fail-open` 默认开启，Native 不可用或失败时回退 JS。
+- 可以通过“全局强制关闭 Native”统一回退 JS。
--- a/docs/usage/panel.md
+++ b/docs/usage/panel.md
@@ -0,0 +1,111 @@
+# 面板导览
+
+本文从 [README](../../README.md) 拆出 ST-BME 面板各区域的用户导览，保留原有条目结构，方便日常查找。
+
+### 总览
+
+- **活跃节点、边连接、已归档、碎片率**
+- **当前聊天 ID**
+- **历史状态**
+- **向量状态**
+- **最近恢复**
+- **最近提取**
+- **最近持久化**
+- **最近向量**
+- **最近召回**
+- **认知 / 空间状态**
+
+### 任务
+
+任务页用于实时观察 ST-BME 的后台任务流。
+
+- **管线总览**
+  - 提取、召回、持久化、向量等阶段状态。
+
+- **任务流水**
+  - 最近任务的时间线和阶段结果。
+
+- **记忆浏览**
+  - 浏览、筛选、查看节点详情。
+
+- **注入预览**
+  - 查看当前构造出的注入文本和 token 估算。
+
+- **消息追踪**
+  - 追踪楼层、提取范围、召回来源和持久记录。
+
+- **持久化**
+  - 查看 IndexedDB、同步、恢复、sidecar、native hydrate 等诊断信息。
+
+### 操作
+
+- **重新提取**
+  - `提取未处理`：只处理还没提取的助手楼层。
+  - `重新提取范围`：按起止楼层重跑指定范围。
+
+- **手动压缩**
+  - 对冗余或相似记忆做压缩。
+
+- **生成小总结**
+  - 基于近期原文窗口生成阶段性总结。
+
+- **执行总结折叠**
+  - 将多条活跃总结折叠成更高层总结。
+
+- **重建总结状态**
+  - 根据提取批次重建总结状态。
+
+- **强制进化**
+  - 让新记忆主动影响旧记忆。
+
+- **执行遗忘**
+  - 降低长期未使用节点的优先级或归档。
+
+- **撤销最近维护**
+  - 回滚最近一次可撤销的维护动作。
+
+- **重建向量 / 范围重建 / 直连重嵌**
+  - 重建节点向量，修复召回质量或切换向量模型后的不一致。
+
+- **导出 / 导入 / 重建图谱**
+  - 图谱管理与危险操作。
+
+- **持久化修复**
+  - 重试持久化、重新探测图谱、重建本地缓存、修复/压实主 sidecar。
+
+### 配置
+
+配置页包含以下工作区：
+
+- **API 配置**
+  - 记忆 LLM。
+  - Embedding 后端模式/直连模式。
+
+- **功能开关**
+  - 提取、召回、整合、总结、反思、压缩、遗忘、概率召回等主能力。
+  - 云端存储模式。
+  - 世界书过滤。
+  - 隐藏旧楼层与聊天区渲染限制。
+
+- **详细参数**
+  - 提取频率、上下文窗口、召回 Top-K、图扩散、认知权重、维护阈值等。
+
+- **任务预设**
+  - 每个任务类型的 prompt blocks、生成参数、正则、世界书、EJS 模板。
+
+- **ENA 规划器**
+  - ENA Planner 的 API、模型、规划配置和任务预设入口。
+
+- **面板外观**
+  - 主题、通知样式、调试日志、Native 性能加速。
+
+- **数据清理**
+  - 本地缓存、遗留数据、调试状态等清理入口。
+
+### 图谱区域
+
+桌面端会显示实时图谱区域。移动端提供子视图切换：
+
+- **实时图谱**
+- **认知视图**
+- **总结视图**
--- a/docs/usage/storage-and-sync.md
+++ b/docs/usage/storage-and-sync.md
@@ -0,0 +1,47 @@
+# 数据存储与同步
+
+本文从 [README](../../README.md) 拆出 ST-BME 的数据存储、云端镜像与持久召回卡片说明；durable snapshot contract 和 forward-compat 细节见 [存储与格式架构文档](../architecture/storage-and-formats.md)。
+
+### 本地主存储
+
+- 主存储使用 IndexedDB。
+- 数据库按聊天隔离，命名类似 `STBME_{chatId}`。
+- 热路径使用增量提交，避免整图替换。
+- 加载时优先从本地数据库恢复图谱。
+
+### 云端镜像
+
+云端同步使用 SillyTavern 已有文件 API，不需要自定义后端路由。
+
+- 自动模式：
+  - 本地写入后按当前镜像逻辑同步。
+
+- 手动模式：
+  - 本地写入仍正常进行。
+  - 不自动写云端。
+  - 需要点击“备份到云端”或“从云端获取备份”。
+
+### 兼容与兜底
+
+- 旧版 `chat_metadata.st_bme_graph` 仅作为迁移和兜底来源。
+- shadow snapshot 和 metadata-full 是 recoverable 锚点，不是首选主存储。
+- tombstone 用于同步删除状态，避免旧数据复活。
+- 插件设置存放在 SillyTavern 的 `extension_settings.st_bme`。
+- 消息级召回存放在对应用户消息的 `message.extra.bme_recall`。
+
+### 持久召回卡片
+
+带有有效 `message.extra.bme_recall` 的用户消息会显示召回卡片：
+
+- 展开后可查看召回文本。
+- 可查看召回子图。
+- 可点击节点查看详情。
+- 可编辑注入文本。
+- 可删除持久召回。
+- 可重新召回并覆盖记录。
+
+优先级：
+
+1. 本轮有新召回成功时，使用新召回并写回目标用户楼层。
+2. 本轮无新召回时，从当前生成对应用户楼层读取持久召回作为回退。
+3. 两者都没有时，清空注入。
--- a/docs/usage/troubleshooting.md
+++ b/docs/usage/troubleshooting.md
@@ -0,0 +1,66 @@
+# 排障指南
+
+本文从 [README](../../README.md) 拆出 ST-BME 常见用户问题与处理方式，便于按症状快速定位。
+
+### 面板打不开
+
+- 刷新 SillyTavern 页面。
+- 确认扩展目录包含 `manifest.json`、`index.js`、`style.css`。
+- 打开浏览器控制台搜索 `[ST-BME]`。
+- 检查是否有其他扩展覆盖了左上角菜单结构。
+
+### 没有自动提取
+
+- 确认插件已启用。
+- 确认当前聊天已有助手回复。
+- 查看“总览 → 最近提取”和“任务 → 管线总览”。
+- 检查记忆 LLM 是否可用。
+- 如果开启智能触发，确认当前内容满足触发条件。
+- 如果处于恢复锁或持久化加载中，等待状态恢复。
+
+### 召回质量差
+
+- 配置或修复 Embedding。
+- 执行“重建向量”。
+- 检查召回 Top-K、最终节点上限、LLM 精排是否开启。
+- 检查节点是否过多过散，可执行整合或压缩。
+- 查看消息级召回卡片确认实际注入内容。
+
+### 旧楼层隐藏后模型仍看到太多内容
+
+- “限制聊天区渲染楼层”只减少前端加载，不负责节省 token。
+- 真正控制上下文需要开启“隐藏旧楼层”。
+- 设置修改后可点击“重新应用当前隐藏”。
+
+### 手动提取时提示历史恢复暂停
+
+通常是因为开启了“限制聊天区渲染楼层”，当前前端只加载了最近 N 条。
+
+处理方式：
+
+1. 临时关闭“限制聊天区渲染楼层”，或把 N 调大到覆盖需要处理的范围。
+2. 刷新当前聊天。
+3. 再执行“提取未处理”或“重新提取范围”。
+
+这是保护机制，不代表图谱丢失。
+
+### 节点看起来突然清空
+
+- 先刷新页面。
+- 如果刷新后恢复，通常是运行时状态暂时不一致，持久化图谱没有丢。
+- 查看“总览 → 最近恢复”和“任务 → 持久化”。
+- 不要立刻执行“重建图谱”，除非确认要从聊天记录重新生成全部记忆。
+
+### 召回卡片不显示
+
+- 确认目标楼层是用户消息。
+- 确认 `message.extra.bme_recall.injectionText` 非空。
+- 第三方主题需要保留 `#chat .mes` 消息节点和稳定楼层索引属性，例如 `mesid`、`data-mesid` 或 `data-message-id`。
+- 打开调试日志后搜索 `[ST-BME] Recall Card UI`。
+
+### 直连 Embedding 失败
+
+- 检查 API 地址和模型名。
+- 检查 Key。
+- 检查浏览器 CORS。
+- 优先尝试后端模式。