# 本地开发与验证

自己边改边测的操作手册。**不用懂编程也能照着做完。**

> 下面所有路径里的 `<你的用户名>` 换成你自己的 Windows 用户名。
> 后面例子统一用 `C:\Users\<你的用户名>\`，别照抄字面意思。

---

## 0. 先分清两样东西（这一步很重要）

很多人会在这里搞混，然后以为"改了没生效"：

| | 是什么 | 在哪 | 谁动它 |
|---|---|---|---|
| **插件** | 代码。决定它怎么记事 | `D:\肥鱼日记` | 你（改代码、改参数） |
| **档案** | 它记住的东西。你的私事 | `~\.dsh\feiyu-diary\` | 它自己（你只在想改人格时动 `persona.md`） |

推论：

- **删代码不会丢记忆**，删档案也不会坏代码。
- 换账号 / 换机器时，带走的是**档案**，不是代码。
- 改代码要**重启 DSH** 才生效（模块是启动时加载的）。
- 改档案里的 `persona.md` **立刻生效**（下一轮对话就读到了）。

---

## 1. 现状：它还没装进 DSH

现在 `D:\肥鱼日记` 只是硬盘上的一堆文件。你正在用的这个 AI **还没有记忆**。

装进 DSH 有两种路子：

| 方式 | 装到哪 | 要退出 Desktop 吗 | 适合 |
|---|---|---|---|
| `link:` 本地路径 | 你的 desktop profile | **要** | 现在，边改边测 |
| `github:` | 你的 desktop profile | **要** | 以后发布给别人用 |

**打包和 GitHub 可以先不管** —— 本地 `link:` 装法完全够你测到满意。

### ⚠️ 一个绕不过去的坑

`dsh plugin --profile desktop` 要求 **DeepSeek Harness Desktop 完全退出**
（不是最小化、不是关窗口 —— 托盘图标上右键退出）。

而你和我说话的这个界面就跑在 Desktop 里。**所以我不能替你执行这条命令** ——
一执行就等于切断自己。这一步只能你手动来，而且必须在你不用它的时候。

---

## 2. 第一步：装进去

### 2.1 `dsh` 命令不在 PATH 上

DSH 的 CLI 在：

```
C:\Users\<你的用户名>\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd
```

直接敲 `dsh` 是不认的（我验过了）。

**三个办法，选一个：**

**(a) 每次用全路径**（最省事，不改系统）
```powershell
& "C:\Users\<你的用户名>\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "link:D:\肥鱼日记"
```

**(b) 永久加进用户 PATH**（一次搞定，以后直接敲 `dsh`）
```powershell
$bin = "C:\Users\<你的用户名>\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin"
$old = [Environment]::GetEnvironmentVariable('Path','User')
if ($old -notlike "*$bin*") { [Environment]::SetEnvironmentVariable('Path', "$old;$bin", 'User') }
```
改完**要重开一个终端**才生效。

**(c) 去 DSH 设置里找** —— DSH 自带一个"把命令行工具注册进 PATH"的机制
（`runtime\cli\command-path.ps1`），界面上可能有对应的开关。有就用它，最正统。

### 2.2 装

1. **完全退出 Desktop**（托盘图标右键 → 退出）
2. 开一个 PowerShell，跑：

```powershell
& "C:\Users\<你的用户名>\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "link:D:\肥鱼日记"
```

（如果你做了 2.1 的 (b)，就直接 `dsh plugin --profile desktop add "link:D:\肥鱼日记"`）

3. **重新打开 Desktop**

### 2.3 怎么知道装上了

**看档案目录有没有被创建出来：**

```
C:\Users\<你的用户名>\.dsh\feiyu-diary\
├── 日记.md          ← 看这个。给人读的版本
├── persona.md       ← 想改它的人格就编辑这个
├── relationship.json
├── lexicon.json
├── manifest.json
└── diary\
    └── 2026-10.jsonl  ← 真数据在这（每行一条）
```

**目录出现 = 插件活了。** 就这一个判断，不用看别的。

**平时只需要打开 `日记.md`。** 那是自动生成给人看的版本：按月分组、最新的在最上面、
分类和状态都是人话（"搞砸了""还欠着"而不是 `failure`/`false`）。

> ⚠️ **别改 `日记.md`** —— 它是单向生成的，下一次对话就被覆盖。
> 想改人格 → 编辑 `persona.md`；想删某条记忆 → 编辑 `diary\*.jsonl` 删掉那一行，
> 然后跑一下 `node tools\render-diary.mjs` 刷新（或者重启 Desktop 让它自己刷）。

要是没出现，去 `~\.dsh\profiles\desktop\package.json` 看看：
`dependencies` 里有没有 `feiyu-memory`、`dsh.profile.bundles` 末尾有没有它。
都有但还是没档案目录 → 看第 5 节开日志。

---

## 3. 第二步：用几天，看看它像不像

装好之后**正常聊天就行**，不用做任何特别的事。

它会在这些时刻记东西（本地判断，微秒级）：

- 你在纠正它（"不对""我说的是…"）
- 你明确要它记住
- 你在说自己的事（"我其实…""我最近…"）
- 你情绪上来了（脏话、感叹号刷屏、大段吐槽）
- 同一个话题又回来了
- 会话拖得很长了

**不会每次都记** —— 这是刻意的。日记要稀疏才有分量。

### 想立刻看效果，最快的办法

1. 聊一句带纠正的话，比如「不对，我说的是 X，你怎么写成 Y 了」
2. 等十几秒（它在后台写日记）
3. 打开 `~\.dsh\feiyu-diary\日记.md`，用记事本看（比 jsonl 好读得多）
4. **开一个全新对话**，问「你还记得我们之前聊过什么吗？」
5. 如果它提到了刚才那件事 → 成了

---

## 4. 第三步：调它

### 4.1 改参数（不用碰代码）

编辑 `~\.dsh\profiles\desktop\cordis.patch.yml`，找到 `feiyu-memory` 那一段。
**改完重启 Desktop。**

只有标了 `.volatile()` 的字段会即时生效，其余要重启。**统一重启最省心。**

### 4.2 症状 → 该动哪个旋钮

| 它的表现 | 动这个 | 往哪动 |
|---|---|---|
| 老是翻旧账，动不动就"突然想起来" | `maxShowPerTurn` | 调成 `0`（彻底不主动提） |
| 想起来的总是些不相干的事 | `highSim` 调高（0.6~0.7）、`wanderChance` 调低（0.02） | 变挑 |
| 该想起来的时候想不起来 | `highSim` 调低（0.35）、`minSalience` 调低（0.2） | 变敏感 |
| 记的东西太水（"用户说了你好"这种） | `minSalience` 调高（0.5） | 变挑食 |
| 注入太长，担心费 token | `budgetTokens` 调低（400） | 省钱 |
| 它把跨会话的事说得像刚才发生的 | 这是模型措辞，动不了参数；在 `persona.md` 里加一句约束 | — |
| 觉得它记错了 / 不想留某条 | 直接编辑 `diary\*.jsonl` 删掉那一行 | 立即生效 |

### 4.3 改人格

直接编辑 `~\.dsh\feiyu-diary\persona.md`，用记事本就行。

**注意那个 `<!-- feiyu:anchor:begin -->` / `end` 之间的部分**：
插件永远不会自动改它，你也最好别删标记。自动学到的认知只会写在
`## 我后来想明白的` 后面。

### 4.4 想清空重来

把 `~\.dsh\feiyu-diary\` 整个删掉，重启 Desktop。
下次对话它会重新建一份出厂档案。

> 想留个备份再删的话：整个目录复制走就是一份完整档案，
> 换机器时直接拷回去（这就是"换账号也是同一条鱼"的实现方式）。

---

## 5. 卡住了怎么查

**第一件事：开调试日志。**

编辑 `~\.dsh\profiles\desktop\cordis.patch.yml`：

```yaml
- id: feiyu-memory
  config:
    debugLog: true
```

重启，聊几句，然后看日志。它会打这些行（**只打形状，不打你的对话内容**）：

```
[feiyu] 已加载，档案目录：…             ← 插件起来了
[feiyu] 档案就绪：N 条日记               ← 档案读到了
[feiyu] 已为会话 session-… 注册记忆段    ← 注入点挂上了
[feiyu] 开闸（用户在纠正我），排队固化    ← 闸门开了
[feiyu] 固化开始：N 条消息 → 模型         ← 开始调模型
[feiyu] 模型返回 N 个 chunk               ← 模型答了
[feiyu] 记下一条 d_…（failure，0.70）     ← 日记写进去了
[feiyu] 会话 … 想起 1 条：想起来一点      ← 召回触发了
[feiyu] 会话 … 第 N 轮：无召回（…）        ← 没想起来（括号里写了为什么）
```

**看见哪一行断了，问题就在那一行之后。**

| 断在哪 | 说明 |
|---|---|
| 连"已加载"都没有 | 插件没起来。去 profile 的 `package.json` 看依赖登记 |
| 有"已加载"但没有"注册记忆段" | 注入点没挂上（DSH 版本变了？） |
| 有"开闸"但没有"固化开始" | 拿不到模型信息，或没有可总结的对话 |
| 有"固化开始"但没有"模型返回" | 模型调用卡住或失败。看有没有"固化失败" |
| 有"记下一条"但日记文件没变 | 写盘失败（磁盘满 / 权限） |
| 有"无召回" | 括号里写了原因：查询 0 字 = 时机不对；候选 0 条 = 还没记下东西 |

查完记得把 `debugLog` 改回 `false`。

---

## 6. 改代码

### 6.1 改完怎么生效

`link:` 装法下，**代码改动是立刻可见的**（它是个符号链接，不是拷贝）。
但模块是启动时加载的，所以：**改完代码 → 重启 Desktop。**

### 6.2 跑测试

**双击 `D:\肥鱼日记\selfcheck.cmd` 就行。**

（直接敲 `node --test` 是跑不了的 —— 这台机器的 node 不在 PATH 上，
那个脚本会自己去找 DSH 自带的那份。）

它会跑 222 项测试 + 检查配置文件结构。全过会打 `[OK]`。

**规矩：改完代码先跑它。** 它能在几秒内告诉你有没有把东西改坏。
但请注意 ——

> ⚠️ **测试全绿不代表插件能用。**
>
> 这个项目在**当时只有 105 项测试**的时候全绿过一次，然后在真实 DSH 里一跑，
> 还是抓出 5 个致命问题（日志看不见、模型调用死等、日记时好时坏…）。
> 它们全都在「插件 × 运行时 × 生命周期」的交界处，纯逻辑测试碰不到。
>
> **改完代码，除了跑测试，还要真的装上用一次。** 这一条写在 SPEC 第 18 节。

### 6.3 万一改坏了

```powershell
cd D:\肥鱼日记
git log --oneline          # 看历史
git checkout .             # 丢弃所有未提交的改动（回到上次提交的状态）
```

`git checkout .` 会**丢掉你所有没提交的修改**，确定不要了再用。

---

## 7. 什么时候上 GitHub

**你自己测顺了、参数调满意了、用了一两周没出大问题，再上。**

现在的状态是：代码在本地 git 仓库里，3 次提交，工作区干净，随时可以推。

推的时候：

```powershell
cd D:\肥鱼日记
git remote add origin https://github.com/<你的用户名>/feiyu-memory.git
git push -u origin main
```

第一次推要登录 GitHub（浏览器会弹窗，或者用 Personal Access Token）。
这个我做不了，只能你来。

推上去之后，别人就能：

```
dsh plugin --profile desktop add github:<你的用户名>/feiyu-memory
```

**推之前值得再看一眼的：**

- `README.md` 的安装命令是不是指向你自己的仓库
- 想清楚要不要公开。档案是私人的、不进仓库（`.gitignore` 已经挡住了），
  但**代码和文档会公开**
- `SPEC.md` 里有不少"我的思考过程"，你觉得太啰嗦可以删；但里面的
  决策理由对未来维护很有用

---

## 8. 最后：三个容易踩的坑

**坑一：中文路径 + 批处理。**
`selfcheck.cmd` 是**纯 ASCII** 的，这是故意的。
cmd.exe 用 GBK 读批处理文件，UTF-8 的中文会把语法搞坏。
以后你自己写 `.cmd` 也要注意。

**坑二：`~\.dsh\profiles\desktop\cordis.patch.yml` 的 config 是整体替换。**
不是"深合并"。所以如果你在那里面写 `config:`，只想改一个键也要注意 ——
对我们这个插件**没问题**（插件自己会补默认值），但如果哪天你去改别人的插件，
只写一半可能会把它的其他配置清掉。

**坑三：别把档案放进仓库。**
`.gitignore` 已经挡了 `*.dshpack` 和 `diary/`。
如果你自己把 `~\.dsh\feiyu-diary\` 拷进项目目录里做测试，**记得别提交**。