# 从装好到好用

装完插件只是给了你一个**空的档案柜**。这份文档讲的是怎么把它喂成"这个助手真的懂我"——README 讲安装，这里讲用法。

如果你装完三天就觉得"好像没什么用"，九成是卡在本文第 3、4 节。

---

## 1. 先理解你得到了什么

插件给你的核心不是人格，是**三级记忆**：

| 层级 | 文件 | 体积上限 | 什么时候读 |
|---|---|---|---|
| **L0 核心卡** | `master/core.md` | **1500 字符** | 每个**新会话**的第一次请求自动注入 system prompt |
| **L1 缩略版** | `master/summary.md` | 6000 字符（超了 `master_status` 会提醒） | 助手需要了解你时，主动调用 `read_master_profile` 读它 |
| **L2 完整版** | `master/full/<主题>.md` | 单个主题无上限，单条事实 ≤2000 字符 | L1 不够用时，按主题名精读 |

存放位置：

- Windows：`%USERPROFILE%\.dsh\plugins\dsh-whale-companion\master\`
- 其他：`$DSH_HOME/plugins/dsh-whale-companion/master/`

配套工具：`read_master_profile [topic]`（读）、`remember <topic> <content>`（写）、`master_status`（查体积）。

### 为什么是三级

因为**注入的 token 是复利**。L0 每个新会话都要注入一次，是固定成本，所以它必须短；L2 可能很大，但它永远躺在磁盘上，只有需要某一主题时才被读进上下文。

这个设计的全部意义就是：**该省的省死，该记的记全。**

---

## 2. 谁写、谁读、谁压缩

| 动作 | 谁做 | 怎么做 |
|---|---|---|
| **写**（日常积累） | 助手 | 你在对话里纠正它、告诉它事实，它调 `remember` 追加到 L2 |
| **读** | 助手 | 新会话自动拿 L0；不够时它自己调 `read_master_profile` 逐级下钻 |
| **压缩** | 你指挥助手做 | 让它把 L2 归纳进 L1、把 L1 提炼进 L0（见第 5 节） |

注意：**写入是 append-only**，只追加不覆盖。所以不压缩的话，L2 会一路长大——虽然不占日常上下文，但会越来越难归纳。定期压缩是唯一的维护动作。

---

## 3. 第一步：亲手写一张 L0 核心卡

安装后 `core.md` **不存在**，此时新会话不注入任何东西——助手对一无所知。

L0 由你亲自写（这是唯一强烈建议手动写的文件，因为它是你对自己的定义）。直接创建 `master/core.md`，参考模板：

```markdown
# 我的核心卡

## 我是谁
- 称呼：叫我「老板」；我用中文交流
- 环境：Windows 11，主力编辑器 VS Code，终端 PowerShell
- 时区：Asia/Shanghai；常在深夜工作

## 在做什么
- 主项目：`F:\work\my-app`（Node + TypeScript）
- 副项目：一个周末在写的博客

## 我的雷区（重要）
- 动数据库迁移前必须先备份
- 不要自作主张删文件、重置 git、推送远端
- 别改我正在跑的服务，先问

## 我的偏好
- 回答简短直接，别铺垫
- 长任务先给预计时间
- 出错要直说，不要糊弄

## 细节去哪查
- 技术栈、历史决策、踩过的坑：`read_master_profile` 读 L1，再按主题下钻 L2
```

### ⚠️ L0 最容易踩的坑：超过 1500 字符会**静默失效**

`loadCore()` 的实现是：文件超过 1500 字符就返回 `null`，即**整个核心卡不注入**，而且没有任何报错提示。你会觉得"我明明写了核心卡，它怎么还是不懂我"。

写完自己数一下：

```powershell
(Get-Content "$env:USERPROFILE\.dsh\plugins\dsh-whale-companion\master\core.md" -Raw).Length
```

超过就往 L1 搬。**L0 只放"每轮都必须知道"的东西：称呼、语言、环境、当前主项目、硬性雷区。** 一切"以后可能有用"的都放 L1/L2。

---

## 4. 第二步：记账三习惯（真正的胜负手）

这是插件本身**无法替你完成**的部分。同样的插件，喂和不喂，是两个东西。

### 习惯一：被纠正就落一条

你说"不对，应该用 pnpm 不是 npm"——说完这一轮，就让助手记：

> 记住：这个项目用 pnpm，不是 npm。

别嫌麻烦。**每一条都是省下的一次重复纠正**，而且它会一直有效，跨会话、跨项目。

### 习惯二：只记"稳定事实"，不记流水账

`remember` 的定位是稳定事实（身份、项目、偏好、习惯、雷区），**不是**一次性任务细节。

| ✅ 该记 | ❌ 不该记 |
|---|---|
| "主人讨厌跑步机" | "今天让我改第 3 行" |
| "这个仓库要在 Windows 上跑，别用 bash 语法" | "刚跑了一次测试，过了" |
| "改完代码必须自己跑一遍 typecheck" | "现在时间是下午三点" |
| "某库在 Node 24 下会崩"（踩过的坑） | "我试了三种方案，第三种成功了" |

判断标准：**这条事实半年后还有效吗？** 有效就记。

### 习惯三：坑要带上下文地记

只记"X 会崩"没什么用，要记成能自救的样子：

> 记住（known-issues）：`xxx` 包在 pnpm 10+ 下装不上，因为它声明了 postinstall，需要写进 `pnpm-workspace.yaml` 的 `allowBuilds`。

主题名自己定，全小写、字母或数字开头、≤32 字符（如 `known-issues`、`techstack`、`aversions`、`projects`）。助手第一次用某主题时会自动建文件。

---

## 5. 第三步：定期压缩

### 什么时候压

对助手说"看一下主人档案状态"，它会调 `master_status`，你会得到一行类似：

```
core: 1200 字符；summary: 7800 字符（超过阈值，建议压缩）；full 主题 24 个（共 96000 字符）：aversions(1300)、known-issues(8600)、prefs(10700)、projects(50000)…
```

出现「超过阈值，建议压缩」（`summary` 超 6000 字符），或者 L2 主题数上了 20+，就该压缩。

### 怎么压

直接把这句话丢给助手：

> 读 `master/full/` 下所有主题，归纳去重，重写 `master/summary.md`（控制在 6000 字符内，覆盖全部主题的要点）；再从 summary 里提炼一份 ≤1500 字符的 `core.md`。**原文件不要删。**

它会用普通文件读写工具完成（插件没有专门的压缩工具，因为压缩需要判断力，交给模型做）。

压缩的原则：

- **L2 → L1**：同一主题的流水条目合并成结论。20 条"他讨厌 X"合成 1 条"他讨厌 X、Y、Z"。
- **L1 → L0**：只留每轮都要用到的。拿不准就不往 L0 放。
- **永不删 L2 原文**。它是证据链，L1/L0 只是它的索引。

---

## 6. 可选：其他模块

装完就有，按需用：

- **人格**：WebUI 设置里新增「鲸鱼娘人格」页，直接输入正文即可（不用三引号），插件自动加边界。覆写会存到 `persona.json`，**需要重启** `dsh web` 才生效。不想要鲸鱼娘也行，把这份配置当模板改成你自己的助手设定。
- **多人记忆（peer）**：`recall_peer_memory` / `remember_peer`，每个对话者有独立记忆空间，和主人档案隔离——群聊素材不会污染你的档案。
- **跨 profile 信箱**：`send_message_to_shen` / `read_mailbox`，如果你同时跑 GUI 和 QQ 两个 profile 的助手，它们可以互相传话、接力任务。
- **人格成长**：`grow_persona` / `read_whale_persona`，让助手自己积累"新学到的小秘密"，不注入 system prompt，按需读回。
- **离线识图**：`see_image` / `stop_vision_model`，当前模型不支持图片输入时，用本机 Ollama 的视觉模型旁路识图（识图脚本随包分发，可用 `DSH_DESCRIBE_IMAGE` 指向自己的实现）。用完记得 `stop_vision_model` 释放显存（约 6-7GB）。

---

## 7. 常见坑速查

| 症状 | 原因 | 处理 |
|---|---|---|
| 改了人格没生效 | 保存不会自动重启 | 重启 `dsh web`，刷新页面不算 |
| 写了 L0 却像没写 | `core.md` 超 1500 字符被静默忽略 | 数一下字符数，超了就精简 |
| `master_status` 一直提示 needsCompact | L1 超 6000 字符 | 走第 5 节压缩流程 |
| `dsh` 起不来，报 `duplicate loader entry id: dsh-whale-companion` | 在 `cordis.patch.yml` 里重复 `insert` 了同一 id | 见 README「故障排查」，改成 id 定向 patch |
| `dsh plugin add` 卡在 pnpm 要求 `allowBuilds` | 别的包声明了安装期脚本 | 按提示写进 profile 的 `pnpm-workspace.yaml` |
| 助手记了一堆没用的流水账 | 记账标准失守 | 重读第 4 节，并在 L0 里写死"只记稳定事实" |

---

## 一句话总结

**插件提供机制，你提供内容。** 机制装完就有，内容是喂出来的——被纠正一次记一条，定期压缩一次，三个月后它和别人的助手就不是同一个东西了。