From f33bfcb380782b86c5994805cb8911b9e1b44a03 Mon Sep 17 00:00:00 2001 From: youzini Date: Sun, 31 May 2026 17:34:32 +0000 Subject: [PATCH] docs: slim README to entry point, move detail into docs/usage --- README.md | 1026 ++---------------------------- docs/README.md | 17 +- docs/architecture/overview.md | 137 ++++ docs/contributing/development.md | 50 ++ docs/contributing/testing.md | 14 + docs/usage/configuration.md | 202 ++++++ docs/usage/panel.md | 111 ++++ docs/usage/storage-and-sync.md | 47 ++ docs/usage/troubleshooting.md | 66 ++ 9 files changed, 697 insertions(+), 973 deletions(-) create mode 100644 docs/usage/configuration.md create mode 100644 docs/usage/panel.md create mode 100644 docs/usage/storage-and-sync.md create mode 100644 docs/usage/troubleshooting.md diff --git a/README.md b/README.md index f2a7a38..458c79f 100644 --- a/README.md +++ b/README.md @@ -4,107 +4,42 @@ ST-BME（Bionic Memory Ecology）是一个 **SillyTavern 第三方前端扩展**。它会把长期聊天中出现的角色、事件、地点、规则、主线、反思和总结抽取成一张可视化记忆图谱，并在下一轮生成前自动召回最相关的记忆注入 prompt。 -> 本 README 是用户手册。想了解内部架构、算法原理、功能解析或参与维护，见 [`docs/`](docs/README.md)。 - --- -## 目录 +## 文档导航 -- [核心能力](#核心能力) -- [工作原理](#工作原理) -- [安装](#安装) -- [快速上手](#快速上手) -- [面板导览](#面板导览) -- [主要配置](#主要配置) -- [记忆模型](#记忆模型) -- [长聊天与历史安全](#长聊天与历史安全) -- [数据格式与向前兼容](#数据格式与向前兼容) -- [常用操作速查](#常用操作速查) -- [数据存储与同步](#数据存储与同步) -- [排障指南](#排障指南) -- [开发者参考](#开发者参考) -- [已知限制](#已知限制) -- [License](#license) +本 README 是**精简入口**。详细内容都在 [`docs/`](docs/README.md)： ---- +| 你想做什么 | 去哪看 | +| --- | --- | +| 配置、面板、排障、存储等使用说明 | [`docs/usage/`](docs/usage/) | +| 理解架构、控制平面、数据格式 | [`docs/architecture/`](docs/architecture/) | +| 理解检索/提取/向量等算法原理 | [`docs/algorithms/`](docs/algorithms/) | +| 理解各功能的机制与边界 | [`docs/features/`](docs/features/) | +| 参与开发、测试、贡献约定 | [`docs/contributing/`](docs/contributing/) | -## 数据格式与向前兼容 - -ST-BME 的记忆图谱以「耐久快照」形式存储在各存储层（IndexedDB / OPFS / Authority SQL / Luker chat-state）。为了避免以后每改一次数据结构就被迫做一次大迁移，耐久快照遵循一套**最小向前兼容纪律**（protobuf 风格），而不是再叠一层「信封」框架： - -- **聊天身份不变**：一个聊天对应一张记忆图谱，沿用宿主聊天身份作为键，不引入新的身份方案。 -- **冻结的顶层结构**：耐久快照顶层只有 `schemaVersion`、`meta`、`nodes`、`edges`、`tombstones`、`state` 六个键，永不新增、永不删除、永不改义。 -- **未来字段加法演进**：任何新增数据都放进 `meta` 或节点/边记录对象里——这些位置会**保留未知字段**，旧版本读到不认识的字段会忽略并原样保留，不报错、不丢弃。 -- **就地升级（upgrade-on-read）**：读到旧 `schemaVersion` 时在内存里逐级升级再用，下次保存自然写成新版；**存储命名空间永不更换**，不需要全量搬迁。 -- **更新版本不被降级**：读到比当前版本更新的快照时保持原样，绝不向下改写，避免旧客户端破坏新数据。 - -这套纪律意味着：以后扩展数据结构是「加字段 + 可选加一个升级步骤」，而不是再来一次 v4、v5 的整体迁移。 - -相关核心模块： - -- `sync/graph-snapshot-schema.js`：冻结顶层键集合、`schemaVersion`、宽容解析（保留未知嵌套字段、丢弃未知顶层键）； -- `sync/graph-snapshot-upgrade.js`：`upgradeGraphSnapshotOnRead` 就地升级链（单调、幂等、不降级、不抛错），已接入 `buildGraphFromSnapshot` 加载路径； -- `runtime/identity-resolver.js`：活动身份、图谱身份、排队身份和 marker 身份分离； -- `sync/persistence-reducer.js`：accepted / queued / pending 持久化状态机和事件 reducer。 - -> 贡献提示：新增图谱数据时，请加进 `meta` / `state` / 记录对象，**不要新增耐久快照顶层键**；只有在加入一个 `upgrade-on-read` 步骤时才提升 `GRAPH_SNAPSHOT_SCHEMA_VERSION`。`tests/graph-snapshot-schema.mjs`、`tests/snapshot-forward-compat.mjs` 是该契约的长期回归保护，请勿删除。 +常用直达：[配置参考](docs/usage/configuration.md) · [面板导览](docs/usage/panel.md) · [排障指南](docs/usage/troubleshooting.md) · [记忆模型](docs/features/memory-model.md) · [历史安全](docs/features/history-safety.md) --- ## 核心能力 -- **自动记忆提取** - - AI 回复后自动读取对话上下文，提取结构化节点和关系。 - - 支持角色、事件、地点、规则、主线、反思、主观记忆等类型。 - - 默认排除 `think`、`analysis`、`reasoning` 等推理标签，避免污染记忆。 - -- **多层混合召回** - - 生成前自动召回相关记忆。 - - 检索链路包含向量预筛、图扩散、词法增强、上下文混合查询、多意图拆分、DPP 多样性采样和可选 LLM 精排。 - - 支持消息级持久召回卡片，可查看、编辑、删除、重新召回。 - -- **认知架构** - - 支持角色 POV 记忆、用户 POV 记忆、客观世界记忆。 - - 支持空间区域、邻接区域、全局区域权重。 - - 支持故事时间线、时间桶、时间跨度和软引导。 - -- **总结与维护** - - 支持小总结、总结折叠、反思、整合、自动压缩、主动遗忘。 - - 维护操作带日志和回滚能力，可撤销最近维护。 - -- **图谱可视化** - - 内置 Canvas 力导向图谱。 - - 支持实时图谱、认知视图、总结视图、移动端图谱视图。 - - 支持主题切换、节点详情、子图召回卡片。 - -- **任务预设系统** - - 提取、召回、压缩、小总结、总结折叠、反思、整合、规划都走统一 task profile。 - - 支持任务块排序、生成参数、全局正则、局部规则、世界书扫描和 EJS 渲染。 - -- **ENA Planner 集成** - - ENA 规划器已整合到 ST-BME 配置页和 `planner` 任务预设。 - - 规划链路可使用角色卡、世界书、最近聊天、BME 记忆、历史 plot 和当前玩家输入。 - -- **持久化与同步** - - 本地优先，主路径使用 IndexedDB。 - - 支持自动云端镜像和手动备份/恢复。 - - 支持导入、导出、重建、修复、压实和持久化探测。 - -- **历史安全** - - 检测删楼、编辑、切 swipe 等历史变动。 - - 自动回滚受影响批次并从变动点恢复。 - - 对“聊天区只渲染最近 N 条”的截断视图有保护，避免误把渲染切片当成历史删除而清空运行时图谱。 - -- **长聊天优化** - - 可隐藏旧楼层来控制上下文 token。 - - 可限制聊天区最多渲染最近 N 条，降低超长聊天前端卡顿。 - - 图布局、持久化 delta、快照 hydrate 支持 Native/Worker/WASM 灰度加速和 JS fail-open 回退。 +- **自动记忆提取** — AI 回复后自动从对话中提取结构化节点和关系（角色、事件、地点、规则、主线、反思、主观记忆），默认排除 `think`/`analysis`/`reasoning` 等推理标签。 +- **多层混合召回** — 生成前自动召回相关记忆，链路含向量预筛、图扩散、词法增强、多意图拆分、DPP 多样性采样和可选 LLM 精排；支持消息级持久召回卡片。 +- **认知架构** — 角色 POV / 用户 POV / 客观世界记忆，空间区域权重，故事时间线。 +- **总结与维护** — 小总结、总结折叠、反思、整合、自动压缩、主动遗忘，带日志和回滚。 +- **图谱可视化** — 内置 Canvas 力导向图谱，支持实时/认知/总结视图和移动端视图。 +- **任务预设系统** — 提取、召回、压缩、总结、反思、整合、规划统一走 task profile，支持正则、世界书、EJS 渲染。 +- **ENA Planner 集成** — 发送前剧情规划，整合到配置页和 `planner` 任务预设。 +- **持久化与同步** — 本地优先（IndexedDB），支持云端镜像、备份/恢复、重建、修复。 +- **历史安全** — 检测删楼/编辑/swipe，自动回滚受影响批次并从变动点恢复；对"只渲染最近 N 条"的截断视图有保护。 +- **长聊天优化** — 隐藏旧楼层控制 token，限制渲染楼层降低卡顿，关键计算支持 Native/WASM 灰度加速。 --- ## 工作原理 -ST-BME 可以理解为三条链路：**写入**、**读取**、**安全**。 +ST-BME 可以理解为三条链路：**写入**（对话 → 记忆）、**读取**（记忆 → 注入）、**安全**（历史变化 → 恢复）。 ```mermaid flowchart LR @@ -134,51 +69,11 @@ flowchart LR P -.-> E ``` -### 写入链路 +- **写入**：对话被规范成结构化消息（默认排除推理标签）→ LLM 提取结构化图操作 → 写入图谱、同步向量、更新时间线 → 后处理（整合、压缩、总结、反思、遗忘）。 +- **读取**：解析召回目标 → 向量预筛 + 图扩散 + 词法增强 → 融合多种信号排序筛选 → 分桶注入 prompt，并可写入持久召回卡片。 +- **安全**：为已处理消息记录 hash，发现历史变动时优先用维护日志回滚重放，无法安全回滚才退化为全量重建。 -1. **结构化消息** - - 对话被规范为带楼层、角色、说话人、原文、来源类型的结构化消息。 - -2. **Assistant 边界过滤** - - 默认排除推理标签内容。 - - 可自定义提取标签、排除标签和正则规则。 - -3. **分层上下文** - - 提取 prompt 可以包含近期对话、图谱统计、活跃总结、故事时间、世界书和 Schema。 - -4. **LLM 提取** - - 输出结构化图操作。 - - 自动解析新增、更新、合并、关系建立和主客观归属。 - -5. **后处理** - - 向量同步。 - - 相似记忆整合。 - - 自动压缩。 - - 小总结与总结折叠。 - - 反思与主动遗忘。 - -### 读取链路 - -1. **召回输入解析** - - 从当前用户输入、发送意图、生成生命周期或持久召回记录中解析召回目标。 - -2. **候选召回** - - 向量预筛找语义相关节点。 - - 图扩散沿关系网络发现间接关联。 - - 词法增强补足实体名、地名、关键词匹配。 - -3. **排序与筛选** - - 融合向量分、图分、重要性、时间新旧、访问强化、认知区域权重。 - - 可选多意图拆分、上下文混合查询、DPP 多样性采样、LLM 精排。 - -4. **注入** - - 结果按当前状态、事件、反思锚点、规则约束等桶整理。 - - 注入到 SillyTavern prompt。 - - 同时可写入对应用户楼层的 `message.extra.bme_recall` 作为持久召回卡片。 - -### 安全链路 - -ST-BME 会为已处理消息记录 hash。发现历史被修改时，会找到最早受影响楼层，优先使用维护日志回滚并重放；无法安全回滚时才退化为全量重建。 +> 算法细节（公式、参数、阈值）见 [`docs/algorithms/`](docs/algorithms/)；架构与数据路径见 [`docs/architecture/overview.md`](docs/architecture/overview.md)。 --- @@ -186,23 +81,18 @@ ST-BME 会为已处理消息记录 hash。发现历史被修改时，会找到 ### 方法一：通过 SillyTavern 扩展安装 -1. 打开 SillyTavern。 -2. 进入扩展管理。 -3. 选择安装第三方扩展。 -4. 输入仓库地址： +打开 SillyTavern → 扩展管理 → 安装第三方扩展，输入仓库地址： ```text https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology ``` -5. 安装完成后刷新页面。 +安装后刷新页面。 > 请粘贴仓库根地址，不要粘贴 GitHub 的子页面地址。 ### 方法二：手动安装 -进入 SillyTavern 的第三方扩展目录： - ```bash cd SillyTavern/data/default-user/extensions/third-party git clone https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology.git st-bme @@ -214,440 +104,16 @@ git clone https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology.git st-bme ## 快速上手 -1. **打开面板** - - 左上角菜单中点击“记忆图谱”。 - - 或使用 ST-BME 注入的面板入口。 - -2. **启用插件** - - 进入“配置 → 功能开关”。 - - 确认 ST-BME 主开关已启用。 - -3. **配置模型** - - 记忆 LLM 留空时，会复用当前 SillyTavern 聊天模型。 - - 如果希望提取/总结/整合走独立模型，可在“API 配置”中填写 OpenAI-compatible 地址、Key 和模型名。 - -4. **配置 Embedding** - - 推荐使用“后端模式”，复用 SillyTavern 已配置的向量 provider。 - - 也可以使用直连模式，但需要自行处理浏览器 CORS。 - -5. **开始聊天** - - 正常对话即可。 - - AI 回复后自动提取，下一次生成前自动召回。 - -6. **查看结果** - - “总览”看运行状态。 - - “任务 → 记忆浏览”看节点。 - - 图谱区域看关系网络。 - - 用户消息下方可能出现召回卡片，可展开查看召回子图。 - -> 最小可用配置：启用插件，并保证当前聊天模型可用。Embedding 不可用时，召回质量会明显下降，建议尽早配置。 - ---- - -## 面板导览 - -### 总览 - -- **活跃节点、边连接、已归档、碎片率** -- **当前聊天 ID** -- **历史状态** -- **向量状态** -- **最近恢复** -- **最近提取** -- **最近持久化** -- **最近向量** -- **最近召回** -- **认知 / 空间状态** - -### 任务 - -任务页用于实时观察 ST-BME 的后台任务流。 - -- **管线总览** - - 提取、召回、持久化、向量等阶段状态。 - -- **任务流水** - - 最近任务的时间线和阶段结果。 - -- **记忆浏览** - - 浏览、筛选、查看节点详情。 - -- **注入预览** - - 查看当前构造出的注入文本和 token 估算。 - -- **消息追踪** - - 追踪楼层、提取范围、召回来源和持久记录。 - -- **持久化** - - 查看 IndexedDB、同步、恢复、sidecar、native hydrate 等诊断信息。 - -### 操作 - -- **重新提取** - - `提取未处理`：只处理还没提取的助手楼层。 - - `重新提取范围`：按起止楼层重跑指定范围。 - -- **手动压缩** - - 对冗余或相似记忆做压缩。 - -- **生成小总结** - - 基于近期原文窗口生成阶段性总结。 - -- **执行总结折叠** - - 将多条活跃总结折叠成更高层总结。 - -- **重建总结状态** - - 根据提取批次重建总结状态。 - -- **强制进化** - - 让新记忆主动影响旧记忆。 - -- **执行遗忘** - - 降低长期未使用节点的优先级或归档。 - -- **撤销最近维护** - - 回滚最近一次可撤销的维护动作。 - -- **重建向量 / 范围重建 / 直连重嵌** - - 重建节点向量，修复召回质量或切换向量模型后的不一致。 - -- **导出 / 导入 / 重建图谱** - - 图谱管理与危险操作。 - -- **持久化修复** - - 重试持久化、重新探测图谱、重建本地缓存、修复/压实主 sidecar。 - -### 配置 - -配置页包含以下工作区： - -- **API 配置** - - 记忆 LLM。 - - Embedding 后端模式/直连模式。 - -- **功能开关** - - 提取、召回、整合、总结、反思、压缩、遗忘、概率召回等主能力。 - - 云端存储模式。 - - 世界书过滤。 - - 隐藏旧楼层与聊天区渲染限制。 - -- **详细参数** - - 提取频率、上下文窗口、召回 Top-K、图扩散、认知权重、维护阈值等。 - -- **任务预设** - - 每个任务类型的 prompt blocks、生成参数、正则、世界书、EJS 模板。 - -- **ENA 规划器** - - ENA Planner 的 API、模型、规划配置和任务预设入口。 - -- **面板外观** - - 主题、通知样式、调试日志、Native 性能加速。 - -- **数据清理** - - 本地缓存、遗留数据、调试状态等清理入口。 - -### 图谱区域 - -桌面端会显示实时图谱区域。移动端提供子视图切换： - -- **实时图谱** -- **认知视图** -- **总结视图** - ---- - -## 主要配置 - -### 记忆 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` 任务预设接入。它可以使用： - -- 角色卡块。 -- 世界书块。 -- 最近聊天块。 -- BME 召回记忆块。 -- 历史 `` 块。 -- 当前玩家输入块。 - -建议： - -- 在“配置 → ENA 规划器”中配置基础 API 和启用状态。 -- 在“配置 → 任务预设 → planner”中调整规划 prompt 结构和生成参数。 - -### 隐藏旧楼层与渲染限制 - -这是两个不同功能： - -- **隐藏旧楼层** - - 用于控制上下文 token。 - - 不删除聊天内容。 - - 通过酒馆隐藏机制让较早楼层不再参与主回复和 ST-BME 读取。 - -- **限制聊天区渲染楼层** - - 用于减少超长聊天界面卡顿。 - - 同步到 SillyTavern 的 `chat_truncation`。 - - 只控制前端最多加载最近多少条。 - - 不等于上下文隐藏，也不等于删除消息。 - -重要提示： - -- 如果你要对很早的楼层做“重新提取范围”或完整历史恢复，建议临时关闭渲染限制或调大数量并刷新。 -- 当 ST-BME 检测到当前 `context.chat` 很可能只是最近 N 条渲染切片时，会暂停破坏性历史恢复，避免误清空运行时图谱。 - -### Native 性能加速 - -Native 加速目前是灰度能力，覆盖： - -- 图布局。 -- Persist Delta。 -- 快照 Hydrate。 - -默认策略： - -- 按节点、边、记录数、结构变化和序列化体积阈值自动命中。 -- `Fail-open` 默认开启，Native 不可用或失败时回退 JS。 -- 可以通过“全局强制关闭 Native”统一回退 JS。 - ---- - -## 记忆模型 - -### 节点类型 - -| 类型 | 说明 | 示例 | -| --- | --- | --- | -| 角色 | 角色状态、性格、外貌、能力变化 | “艾琳左肩受伤，暂时无法举弓” | -| 事件 | 已发生的剧情事件 | “两人在钟楼顶层达成约定” | -| 地点 | 地点状态和环境信息 | “旧实验室的北门被封住” | -| 规则 | 世界观设定、系统规则、约束 | “血契会在月蚀时失效” | -| 主线 | 任务线、剧情线、目标 | “寻找失踪的王冠碎片” | -| 全局概要 | 兼容旧概要体系的兜底节点 | “此前剧情摘要” | -| 反思 | 长期模式、叙事建议、关系趋势 | “二人遇到压力时倾向于互相隐瞒” | -| 主观记忆 | 某角色/用户视角中的信念、误解、情绪 | “她误以为对方背叛了自己” | - -### 关系类型 - -图谱会建立参与、发生在、推动、矛盾、更新、时序更新、引用、归属等关系，让召回不只依赖单点相似度，而能沿剧情网络扩散。 - -### 主客观分层 - -- **客观层** - - 世界事实、事件、地点、规则、主线。 - -- **角色 POV** - - 角色知道什么、误解什么、相信什么、在意什么。 - -- **用户 POV** - - 玩家/用户视角下需要保留的偏好、承诺、视角信息。 - -### 故事时间线 - -每条记忆可带有： - -- 当前。 -- 近过去。 -- 远过去。 -- 闪回。 -- 未来预告。 -- 时间跨度。 - -这些信息会影响召回排序和注入提示。 - ---- - -## 长聊天与历史安全 - -### 历史变动恢复 - -当你执行以下操作时： - -- 删除消息。 -- 编辑消息。 -- 切换 swipe。 -- 重跑某段提取。 - -ST-BME 会： - -1. 对比已处理消息 hash。 -2. 找到最早受影响楼层。 -3. 清空可能失效的注入。 -4. 回滚受影响批次中的节点、边和向量。 -5. 从变动点重放提取。 -6. 更新持久化快照。 - -如果维护日志不足以安全回滚，会进入全量重建路径。全量重建较慢，但优先保证正确性。 - -### 渲染限制保护 - -长聊天中如果开启“限制聊天区渲染楼层”，SillyTavern 可能只把最近 N 条消息暴露给前端上下文。这样 `context.chat.length` 会短于真实聊天。 - -ST-BME 已加入保护： - -- 当图谱显示已处理到更高楼层，但当前可见 chat 只有最近 N 条时，不会立刻判断为“历史被删除”。 -- `inspectHistoryMutation()` 会跳过这类渲染切片误判。 -- `recoverHistoryIfNeeded()` 会暂停破坏性恢复，避免 full-rebuild 清空运行时图谱。 -- 面板会提示你关闭/调大渲染限制后再做完整提取或恢复。 - -### Restore Lock - -以下操作期间，ST-BME 会进入恢复锁： - -- 手动重建图谱。 -- 导入图谱。 -- 重建总结状态。 -- 云端恢复。 -- 回滚上次恢复。 - -恢复锁期间会暂停自动提取、历史恢复、持久化重试和部分召回失效处理，避免并发写入破坏数据一致性。 +1. **打开面板** — 左上角菜单点击"记忆图谱"。 +2. **启用插件** — 配置 → 功能开关，确认主开关已启用。 +3. **配置模型** — 记忆 LLM 留空时复用当前聊天模型；也可在"API 配置"填独立的 OpenAI-compatible 地址/Key/模型。 +4. **配置 Embedding** — 推荐后端模式（复用 SillyTavern 已配置的向量 provider）；也可用直连模式但需自行处理 CORS。 +5. **开始聊天** — 正常对话即可，AI 回复后自动提取，下次生成前自动召回。 +6. **查看结果** — "总览"看状态，"任务 → 记忆浏览"看节点，图谱区域看关系网络，用户消息下方可能出现召回卡片。 + +> 最小可用配置：启用插件 + 保证当前聊天模型可用。Embedding 不可用时召回质量会明显下降，建议尽早配置。 +> +> 完整配置说明见 [配置参考](docs/usage/configuration.md)，面板每个区域的用途见 [面板导览](docs/usage/panel.md)。 --- @@ -666,418 +132,40 @@ ST-BME 已加入保护： | 重建向量 | 操作 → 向量操作 | 重建全部节点 embedding | | 范围重建 | 操作 → 向量操作 | 只重建指定楼层范围相关节点 | | 直连重嵌 | 操作 → 向量操作 | 使用直连 embedding 配置重嵌 | -| 导出图谱 | 操作 → 图谱管理 | 下载当前图谱 JSON | -| 导入图谱 | 操作 → 图谱管理 | 导入图谱，建议随后重建向量 | -| 重建图谱 | 操作 → 图谱管理 | 危险操作：清空后从当前聊天重提 | -| 备份到云端 | 配置 → 功能开关 → 云端存储模式 | 手动模式下主动上传备份 | -| 从云端获取备份 | 配置 → 功能开关 → 云端存储模式 | 手动模式下主动恢复备份 | -| 取消全部隐藏 | 配置 → 功能开关 → 隐藏旧楼层 | 恢复当前聊天由 ST-BME 隐藏的楼层 | +| 导出 / 导入 / 重建图谱 | 操作 → 图谱管理 | 图谱管理与危险操作 | +| 备份 / 恢复云端 | 配置 → 云端存储模式 | 手动模式下主动上传/恢复 | +| 取消全部隐藏 | 配置 → 隐藏旧楼层 | 恢复 ST-BME 隐藏的楼层 | + +> 切换 embedding 模式或模型后，建议执行"重建向量"。各操作的细节和危险提示见 [配置参考](docs/usage/configuration.md) 和 [面板导览](docs/usage/panel.md)。 --- -## 数据存储与同步 +## 数据存储与历史安全（要点） -### 本地主存储 +- **本地优先**：主存储使用 IndexedDB，按聊天隔离（`STBME_{chatId}`），热路径用增量提交。 +- **云端镜像**：复用 SillyTavern 文件 API，支持自动/手动模式，不需要自定义后端。 +- **历史安全**：检测删楼/编辑/swipe，优先回滚重放、必要时全量重建；对渲染切片截断有保护，避免误清空。 +- **向前兼容**：耐久快照顶层结构冻结、宽容解析、就地升级——扩展数据结构是"加字段"，不是大迁移。 -- 主存储使用 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. 两者都没有时，清空注入。 +> 详见 [存储与同步](docs/usage/storage-and-sync.md)、[历史安全](docs/features/history-safety.md)、[数据格式与向前兼容](docs/architecture/storage-and-formats.md)。 --- -## 排障指南 +## 遇到问题？ -### 面板打不开 - -- 刷新 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。 -- 优先尝试后端模式。 - ---- - -## 开发者参考 - -> 完整的架构、算法原理、功能解析和贡献指南在 [`docs/`](docs/README.md)： -> - 架构与控制平面 [`docs/architecture/`](docs/architecture/) -> - 算法原理 [`docs/algorithms/`](docs/algorithms/) -> - 功能解析 [`docs/features/`](docs/features/) -> - 参与维护 [`docs/contributing/`](docs/contributing/) - -### 目录结构 - -```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 回归测试与性能测试 -``` - -### 本地开发 - -安装依赖： - -```bash -npm install -``` - -语法检查： - -```bash -npm run check -``` - -稳定测试集： - -```bash -npm run test:stable -``` - -P0 回归： - -```bash -npm run test:p0 -``` - -控制面与数据格式专项： - -```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 -``` - -### 重要测试文件 - -- **`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` 依赖，都已由 `index.js` 对应的 `create*Runtime()` builder 提供；禁止用 `runtime[dynamicKey]` 绕过检查。 - -- **`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`** - - 任务预设迁移。 - -### 事件挂载 - -| SillyTavern 事件 | ST-BME 行为 | -| --- | --- | -| `CHAT_CHANGED` | 加载当前聊天图谱，恢复持久状态，应用隐藏/渲染限制 | -| `GENERATION_AFTER_COMMANDS` | 助手回复后触发自动提取 | -| `GENERATE_BEFORE_COMBINE_PROMPTS` | 生成前召回并注入 | -| `MESSAGE_SENT` | 捕获发送意图和权威用户输入 | -| `MESSAGE_RECEIVED` | 更新自动提取队列和持久化状态 | -| 编辑 / 删除 / Swipe | 检测历史变化并恢复 | - -### 贡献注意事项 - -- 优先保持扩展侧实现，不要把核心能力依赖到自定义 SillyTavern server plugin。 -- 修改中心抽象时，补充或更新对应测试。 -- 涉及持久化、历史恢复、导入/恢复等路径时，优先防止空图覆盖和并发写入。 -- 涉及 prompt 或正则迁移时，保留旧设置兼容。 -- **测试不得把 `index.js` 当文本切片执行。** 历史上部分回归测试用 `readFile(index.js)` + 标记字符串切片 + `vm.runInContext` 来测内部函数，这让 `index.js` 与字节偏移强耦合、反复出现 `X is not defined` 沙箱崩溃。现在这些逻辑已抽成可直接 `import` 的控制器/工厂模块（`runtime/`、`sync/`、`ui/`、`maintenance/` 下），测试应直接导入真实模块并注入依赖。`tests/index-slicing-ratchet.mjs` 会守住这条线：任何新测试若再读取 `index.js` 文本，CI 失败。 -- **注入式模块新增 `runtime.X` 依赖时，必须同步更新对应的 `create*Runtime()` builder。** `tests/runtime-deps-completeness.mjs` 会扫描 `sync/graph-persistence-io.js`、`sync/graph-load-persist.js`、`sync/graph-mutation-gate.js` 的直接 `runtime.X` 引用，并和 `index.js` 的 builder 返回键对比；漏注入或使用 `runtime[dynamicKey]` 都会失败。 -- 提交前至少运行 `npm run check` 和相关专项测试。 +常见情况（面板打不开、不自动提取、召回质量差、节点看似清空、召回卡片不显示、直连 Embedding 失败等）的排查步骤见 [排障指南](docs/usage/troubleshooting.md)。 --- ## 已知限制 -- **记忆质量依赖 LLM** - - 提取模型理解错误时，记忆也会错误。 - -- **Embedding 决定召回下限** - - 没有高质量向量，召回会更依赖词法和图结构。 - -- **直连模式可能受 CORS 影响** - - 浏览器安全策略可能阻止请求。 - -- **超长聊天仍有成本** - - 隐藏旧楼层、渲染限制、总结折叠可以降低压力，但不能消除所有开销。 - -- **历史恢复优先正确性** - - 日志不足时会退化全量重建，可能较慢。 - -- **第三方主题可能影响召回卡片挂载** - - 如果主题移除了标准消息 DOM 或楼层索引属性，卡片可能跳过挂载。 - -- **Native 加速是灰度能力** - - 默认 fail-open，失败时回退 JS；遇到异常可在面板中强制关闭 Native。 +- **记忆质量依赖 LLM** — 提取模型理解错误时记忆也会错误。 +- **Embedding 决定召回下限** — 没有高质量向量，召回更依赖词法和图结构。 +- **直连模式可能受 CORS 影响** — 浏览器安全策略可能阻止请求。 +- **超长聊天仍有成本** — 隐藏/渲染限制/总结折叠能降低压力，但不能消除所有开销。 +- **历史恢复优先正确性** — 日志不足时退化为全量重建，可能较慢。 +- **第三方主题可能影响召回卡片挂载** — 移除标准消息 DOM 或楼层索引属性时卡片可能跳过挂载。 +- **Native 加速是灰度能力** — 默认 fail-open，失败回退 JS，可在面板强制关闭。 --- diff --git a/docs/README.md b/docs/README.md index 22ad98d..06bf90e 100644 --- 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 集成、自动降级/升级、能力探测 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 5b0fd9e..0704e1d 100644 --- 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 | 检测历史变化并恢复 | diff --git a/docs/contributing/development.md b/docs/contributing/development.md index cd2048f..ce2a70d 100644 --- 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 +``` + ## 提交前 至少运行： diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index fd03602..49175d3 100644 --- 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 环境缺失会失败，非代码问题。 diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md new file mode 100644 index 0000000..788e43d --- /dev/null +++ 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 召回记忆块。 +- 历史 `` 块。 +- 当前玩家输入块。 + +建议： + +- 在“配置 → 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。 diff --git a/docs/usage/panel.md b/docs/usage/panel.md new file mode 100644 index 0000000..42cf50b --- /dev/null +++ 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 性能加速。 + +- **数据清理** + - 本地缓存、遗留数据、调试状态等清理入口。 + +### 图谱区域 + +桌面端会显示实时图谱区域。移动端提供子视图切换： + +- **实时图谱** +- **认知视图** +- **总结视图** diff --git a/docs/usage/storage-and-sync.md b/docs/usage/storage-and-sync.md new file mode 100644 index 0000000..4e09ac2 --- /dev/null +++ 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. 两者都没有时，清空注入。 diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md new file mode 100644 index 0000000..4ca1933 --- /dev/null +++ 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。 +- 优先尝试后端模式。