# 常见疑问（FAQ）

> 这些是**真实用户（包括我自己）用起来最容易误判的地方**。每条都写了插件实际怎么做的、以及为什么这么做。
> 英文版见 [FAQ.md](FAQ.md)。

---

## 一、注入：到底什么时候发、发多少？

### Q：既然是"每个会话自动注入"，那是不是**每聊一句都把全部记忆发一遍**？

**不是。** 这套记忆的核心机制之一叫**差分注入**：

| 轮次 | 实际发给模型的内容 |
| --- | --- |
| 新会话第一轮 | **全量基线**：所有「已在用」条目的结论首行 + 一小段框架说明 |
| 之后每一轮 | 先算差异 —— **没有任何变化就一个字都不发**；有变化（你提升 / 归档 / 取代了条目）就**只发那几条的变化** |

所以成本结构是：

```
一个会话的总注入 ≈ 基线（一次） + 期间发生的所有变化
```

面板上显示的「注入 4546 / 5000 字节」是**基线体积** —— 它衡量的是**每开一个新会话要付多少**，
不是"每轮都付这么多"。

### Q：那"没有变化就一个字不发"，我怎么知道记忆还在？

因为**没变化本身就是信号**：一轮里没有任何记忆消息进来，就意味着"上一轮的结论全部仍然有效"。
只有**失效**（被取代 / 归档）时才会主动告诉你一条「已失效，不要再依据」。

### Q：超出预算会怎样？会不会把条目丢掉？

**不会丢。** 注入**不截断** —— 超预算只是每轮多花这些 token，同时在三个地方告警：
`mem inject` / `mem validate` 的输出、侧边栏面板顶部一块琥珀色提示。

处理办法按代价从低到高：

1. **把结论首行写短**（注入只取首行；正文写多长都不花预算）
2. **归档 / 撤回**不再需要的条目
3. **调大预算**（优先改 `memory.config.json` 的 `injectBudget` —— 那是"这份库要多少"的权威声明）

> 预算的来源顺序：**显式配的 `maxBytes`** → 库的 `injectBudget` → 3072，只有一份实现
> （`bin/mem.mjs` 的 `resolveBudget()`）。
> ⚠️ 2026-10-08 修的一个真问题：插件的 Config schema 原来给 `maxBytes` 带了默认值 3072，
> 于是它**永远**压过库配置 —— 只改库里的值重启后不生效，只能反过来再去 profile 里钉一个数，
> 两个来源互相打架。现在 `maxBytes` **不给默认值**：不写就听库的。

### Q：为什么非要有个上限？让它全量注入不行吗？

因为这段内容是**每一轮都发给模型的常驻上下文**，属于持续性成本。粗略换算：**3 字节 ≈ 1 token**，
3000 字节 ≈ 1000 tokens。库越大，每个新会话的起始成本越高 —— 所以设计上用"上限 + 告警 + 归档"来管，
而不是任它长。

---

## 二、阶段与动作：归档、撤回、取代有什么区别？

「待你确认（inbox）→ 已在用（facts/decisions）→ 已归档（archive）」是**流程阶段**，不是三份拷贝。

| 你想表达 | 用哪个 | 效果 |
| --- | --- | --- |
| 这条我认可了 | `mem promote <id>`（面板「提升」） | inbox → facts/decisions，**从此每轮注入** |
| 先不当真，但别删 | `mem demote <id>`（面板「撤回」） | 常驻 → inbox（**不改 status**，以后再 promote 原样回去） |
| 不再适用，也没有新版本顶上 | `mem archive <id>`（面板「归档」） | → archive/，`status=expired`，**不再注入，但搜得到** |
| 有更好的说法取代它 | `mem supersede <旧> <新>` | 双向链接 + 旧条目标 `superseded` + 进 archive |
| 归档错了，想捞回来 | `mem restore <id>`（面板「取回」） | archive → inbox（**再确认一次**才重新生效，不绕过"人确认"） |
| 这条候选根本不算数 | `mem rm <id>`（面板「删除」） | **只允许删 inbox**；常驻条目直接删 = 静默消失，所以不允许 |

**关键：归档 ≠ 删除。** `mem recall` / 面板搜索**仍然搜得到**归档条目，只是它不再每轮发给模型。

### Q：归档区那一堆分类和主题是怎么回事？

面板里「已归档」是三层，读起来是：

```
已归档（archive）
  已废弃 (20)         ← 分类：为什么退场。三个是常驻的（已蒸馏 / 已废弃 / 暂时不用，空的就是 0 条）
    · gitignore-…     ← 没写主题的条目直接列在分类下
    DSH 插件开发 (6)   ← 主题行：点开才列出条目
    开源与发布 (5)
  已蒸馏 (20)         ← 被取代 / 结论已搬进文档的那些（自动归类，不是手选的）
  暂时不用 (0)        ← 暂时用不上、但可能再启用的那些（想再用：「取回」→「提升」）
```

- **分类**（`category` 字段）= 为什么退场。三个默认：
  `已蒸馏`（结论进了文档 / 被新版本顶上）、`已废弃`（彻底没用了、不会再启用）、
  `暂时不用`（这个工作区暂时用不上，但换个业务/项目可能又要）。
  归档时（含批量归档）可以选现成的，也可以**自己写一个新的**。
  `暂时不用` 与 `已废弃` 的差别只在"还会不会回来"，两者的 `status` 都是 `expired`。
- **主题行** = 这条记忆原本的 `topic`。**点开主题才看到条目** —— 归档区先给你一张目录，不会一上来倒几十条。
  主题**只有一级**：同名就是一组（主题名里真写了 `/` 也只是普通字符，不再是父子两级）。
- 想挪分类：条目行上的「分类」按钮，或 `mem set <id> --category "…"`。
- v1.2.x 写进文件的旧默认名 `已过期` 会按 `已废弃` 归组（读和写两边都归一），不用预先迁移。

### Q：为什么"只允许删候选"？

常驻条目很可能已经被注入过、被别的条目引用过。直接删掉，模型和你的界面同时失去它 ——
这就是**静默消失**，最难排查的一类问题。所以常驻只有两条退场路径：**撤回**（先不当真）或
**归档 / 取代**（不再适用 / 有替代）。这两条都可逆（`restore` 能捞回来）。

### Q：为什么"一个 key 只能有一个真相"？

`key` 是这条记忆的**语义标识**（比如 `sandbox-no-pipe`）。同一个 key 上如果同时存在两条「已在用」，
模型每轮会收到两句互相打脸的话 —— 这比"少记了一条"更糟。所以提升撞 key 时会被挡住，
要你显式说清"新的取代旧的"（`--supersedes`）。

---

## 三、和 DSH 自带的 `AGENTS.md` 会不会重复注入？

不会，两者是**不同插件、不同来源**：

| | 谁负责 | 注入什么 | 有没有差分 |
| --- | --- | --- | --- |
| `AGENTS.md`（全局 / 工作区 / `.local`） | **DSH 自带的 `dsh-agent-instructions`** | 那些文件**整篇** | **没有**（文件一变就整篇重注入） |
| 本插件 | `dsh-memory-delta` | `<工作区>/memory` 里「已在用」的条目 | **有**（见第一节） |

侧边栏「记忆」页签里会把这两类都显示出来（全局规范 / 工作区规范），但**注入归各自负责** ——
本插件**不做**第二套全局注入（否则会出现两个"全局真相"）。

---

## 四、模型能做什么、不能做什么？

模型只有两个工具：

- `memory_write` —— **只能写 inbox**（候选），并且不会自动提升
- `memory_search` —— 检索（条目 + 流水）

它**不能** promote / demote / archive / supersede —— 这些都要人做。原因很简单：
错误结论一旦静默进入常驻层，会**每轮都被注入**，代价远大于"多问一句"。

### Q：那"知识沉淀"这件事谁做？

人在回路里做。典型节奏：

1. 会话里出现了值得留存的坑 / 约定 → 模型写进 inbox（你会在面板「待你确认」看到）
2. 你确认 → 提升为常驻（从此每轮注入）
3. 攒到一定量（比如发了一版）→ 把**"怎么做"那类**搬进文档 / 技能，条目归档
   （判据：**搬进文档的必须是"我会主动去查也会查到"的东西**；一旦搬走就别指望它自动找上你）

---

## 五、一条现成的判据（省 token 用）

| 内容 | 放哪 |
| --- | --- |
| **"我希望我不用主动去查就会知道"** —— 当前约定、账号、环境事实、在途待办 | **记忆体「已在用」**（每会话自动到手） |
| **"只有做那类事时才需要，而且我会主动去查"** —— 踩过的坑与避开法、流程、检查表 | **文档 / 技能**（按需加载，不占每轮预算） |

⚠️ 别把"在途的决策"搬进文档：搬走后模型**不会自动知道**，而你还以为它有效 —— 这是静默失效。

---

## 六、还有疑问？

- 库自带说明书：`mem init` 会在库根写一份 `README.md`（**永不覆盖**），讲清三种退场别混
- 面板顶部有流程条与超预算告警，点各组标题可折叠 / 展开
- 命令行：`mem help`（或 `mem <命令>` 不带参数看用法）