# 排障指南

**中文** · [English](troubleshooting.en.md)

本文从 [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。
- 优先尝试后端模式。