备忘录检索 wonderandyou/dsh-memo

dsh-memo

给 DSH（DeepSeek Harness）加一组按需查备忘录的工具，外加一个小动画：围着书架转圈、抽书查看。

一句话：把一份 19 万字符的 MEMO.md 切成几百段，每次只取需要的那一段——而不是把整份读进上下文。

它解决什么问题

AI 助手长期工作，会攒出一份越来越大的备忘录（本机的 MEMO.md 已经 19 万字符 ≈ 3 万 token）。
每次要查「那个端口是多少」，如果把整份读进去，一次就烧掉 3 万 token，而且大部分内容跟当前问题无关。

这个插件把备忘录做成可按需索引的知识库：

- 想找东西 → 先看目录（约 600 token），再取那一节（几百到几千 token）
- 想全局扫一眼 → 取「精简版」（约为原文 1/5）
- 每次查询省了多少，右上角面板实时显示

安装

DSH 插件的安装位置有三个，缺一个都不生效：

$profile = "$env:USERPROFILE\.dsh\profiles\desktop"
$src = "C:\path\to\dsh-memo" # 你解压出来的目录

1) 依赖：在 profile 的 package.json 里加一行 "dsh-memo": "link:<上面那个 $src>"

2) 启动清单：同文件的 dsh.profile.bundles 数组里加 "dsh-memo"

3) 软链： cmd /c mklink /J "$profile\node_modules\dsh-memo" "$src"

然后关掉 DSH 窗口重新打开（client 插件不热重载）。

仓库里的 scripts/install-local.mjs 可以自动做上面三步：

node scripts/install-local.mjs --profile desktop

工具（模型用）

| 工具 | 用途 | 典型消耗 |
| memo_outline | 目录：节号 / 标题 / 行号 / 字符数 / 估算 token | ~600 tok |
| memo_section | 按节号取原文（0.2、3.6、5 …） | 0.5~4k tok |
| memo_search | 关键词或正则搜索，带上下文与所属节 | ~300 tok |
| memo_project | 按项目名取整张卡（支持中文名与别名） | 1~4k tok |
| memo_quick | 速查：machine / ports / interpreters / dirs / commands | ~150 tok |
| memo_status | §6 当前状态表 | ~500 tok |
| memo_playbook | §5 里的可复用套路 | ~300 tok |
| memo_append | 追加内容（自动备份 + 读回校验 + 失败回滚） | 一行确认 |
| memo_lite | 取精简版（全局速览） | 1~3k tok |
| memo_compact | 生成精简版 MEMO.lite.md（原文件一字不动） | 一行确认 |

面板（人用）

右上角一个书签按钮，点开是面板：

- 备忘录规模（字符 / 行 / 节 / 项目卡）
- 本次运行统计：查询次数、累计返回字符、比整份读省了多少、精简版省了多少
- 最近查询：时间 / 工具 / 参数 / 返回大小 / 节省比例（失败标红）
- 分类：按用途分组（速查 / 环境与坑 / 项目 / 套路 / 状态 / 专题），组可折叠，点任意节就地预览
- 搜索框：自己搜备忘录
- 精简：点按钮 → 确认 → 生成 MEMO.lite.md

原理

1. 索引：把 Markdown 切成节

lib/memo-core.js 只做一件事：把 MEMO.md 解析成「节」的数组。

- 只认 ## 和 ### 两级标题（# 当文件标题）
- 每节的区间 = 本节标题行 → 下一个「同级或更高级」标题之前
- 节号从标题前缀提取：## 3.6 QQ 机器人 → id 3.6；没有数字前缀的用 h<行号>
- 每次查询前先 stat 比对 mtime 和 size，文件没变就复用上次的索引

所有查询共用这个索引，返回统一的 { text, chars, tokens }。

2. 为什么能省 token

| 操作 | 返回量 |
| 整份读 | ~191,000 字符 |
| memo_outline | ~2,000 字符 |
| memo_section 0.2 | 880 字符 |
| memo_quick ports | 880 字符 |

一次「查端口」从 19 万字符降到 880，省 99.5%。

3. 分类：按节号前缀归类

规则只看节号前缀，不看标题文字，所以换一份备忘录只要节号约定相同就自动生效：

0.x → 速查 1 / 2 / 4 / 7 → 环境与坑 3 / 3.x → 项目 5 → 套路 6 → 状态其余 → 专题

⚠ 一个坑：父节的字符数包含全部子节（§3 的 range 覆盖了 3.1~3.18）。
统计总数时只能累加叶子节，否则数目会翻倍——第一次实现就是这么错的。

4. 精简备忘录：逐行打分

不是「删东西」，而是另存一份高密度版，原文件一个字不动。

对每一行按「信息密度」打分：

| 特征 | 分数 |
| 标题行 | 必留（100） |
| 表格行 \| ... \| | 45 |
| 含路径（C:\ / ~/ / /api/ / 文件扩展名） | 42 |
| 含端口 / 127.0.0.1 / localhost | 36 |
| 含命令（pip / npm / git / curl / pwsh …） | 30 |
| 含「坑 / 踩过 / 注意 / 不要 / 禁止 / 必须 / 铁律」 | 30 |
| 列表项 | 22 |
| 又长又没有信号（>160 字且分数 <25） | 0 —— 直接丢 |

然后按节的预算截断：

预算 = max(280, 节字符数 × ratio) // ratio 默认 0.16 短节（<700 字符）整段保留，不值得压代码块只留前 3 行超出预算时从最低分行开始丢

⚠ 第二个坑：父节只输出标题，正文交给子节各自压缩。
否则 §3 会把所有 3.x 再压一遍，同一段内容在精简版里出现两次（第一次实现输出 6.4 万字符、内容重复）。

实测（19 万字符的备忘录）：191,790 → 36,053 字符，省 81%，86 个章节标题全部保留。

产物落在同目录的 MEMO.lite.md，随时可以重新生成。

5. 书架动画

分两层，主方案是预渲染视频，兜底才是实时绘制。

5.1 场景设计

- 三个双面书架摆成等边三角形（边长 2.45，重心在原点），每个书架朝外转，中间留出空地
- 每层 8 本书，书是有厚度的三维盒子（前面 / 左面 / 右面三个面），高矮胖瘦用确定性伪随机，正反两面都摆满
- 相机绕 Y 轴 8 秒转满一圈，同时抬高 2.5 米（约 25° 俯视），所以三角形的三个顶点分得开
- 每转 90° 抽一本书：那本书从它自己的槽位离开（架上当场留一个洞），朝镜头飞 2.8 米、边飞边自转一圈、体积放大到 2.2 倍，然后沿原路落回同一个洞

5.2 为什么落地看不出接缝

架上书和飞行书用同一个绘制函数、同一组尺寸与颜色：

u=0 飞行书 = 原尺寸，位置 = 架上位置 → 与架上那本完全重合
u=1 飞行书 = 原尺寸，位置 = 架上位置 → 落回原位
中间 放大 1 + sin(πu)×1.15 倍，飞到镜头前

所以「动画放完突然补一本书上去」这种事不会发生——它从来没有消失过，只是离开了原位。

早期版本踩过两次：
- 飞行书单独画成亮边框的盒子 → 落地瞬间换皮，像凭空补一本
- 书架上不画书（只有格子）→ 抽出来就是凭空出现

5.3 怎么渲染成视频

用 Remotion 逐帧渲染成 VP9 + alpha 透明的 webm：

透明版（给插件用）
npx remotion render MemoShelf out/memo-shelf.webm
--codec=vp9 --pixel-format=yuva420p --image-format=png --crf=45

带界面底图的演示片（给人看）
npx remotion render MemoShelfButton out/demo.mp4 --codec=h264

- --pixel-format=yuva420p 必须有，否则没有 alpha 通道
- --crf=45 把 8 秒 1080p 压到 5~7 MB（不带这个参数会到 15 MB）
- 8 秒正好转满一圈，首尾角度一致 → 可以无缝循环播放

5.4 触发与播放

host 侧：每次工具调用 → stats.calls++ → 写 query-log.jsonl client 侧：每 1.4 秒拉 /api/memo/ping.json 发现 calls 变大 → 按钮加 playing 类 → 播视频播满 8 秒没有新查询 → 收回成书签

- 动画不是全屏浮层，而是右上角书签按钮自己从 34×34 展开成 200×200 的圆角小窗（CSS transition）
- 视频是按钮的子元素（position:absolute; inset:0; object-fit:cover; border-radius:inherit），所以展开收起时位置自动跟随
- 1600×900 的画面塞进正方形窗口时居中裁切

5.5 Canvas 兜底

如果视频加载失败（没打包 / 解码失败 / 浏览器不支持 alpha），lib/client.js 里的 Canvas 场景会用同一套投影数学实时画一遍：

- 同样的三角函数投影（绕 Y 轴旋转 + 25° 俯仰 + 透视）
- 同样的三角形布局与抽书逻辑
- 尺寸固定 200×200，画在按钮里

兜底版比视频版朴素一些（没有辉光滤镜），但布局和动作一致。

效果一致性（装好就是视频里那样）

| 保证项 | 做法 |
| 动画画面 | 视频文件打包在 assets/memo-shelf.webm，不是运行时现算的，安装即带 |
| 动画参数 | 全硬编码在源码里，不读配置文件，不会被环境改动 |
| 摆放与节奏 | 三角形、绕圈速度、抽书间隔都是常量 |
| 兜底 | 视频不可用时用 Canvas 画同一套场景，不会变成"什么都没有" |
| 备忘录路径 | file 留空时自动用 ~/.dsh/MEMO.md，换机器不用改 |

唯一的运行时依赖是 Chromium 内核（DSH 桌面端是 Electron，天然支持 VP9 alpha webm）。
如果你的宿主不是 Chromium，动画会退到 Canvas 兜底版。

配置

cordis.patch.yml：

- insert:
- id: memo
name: 'dsh-memo'
config:
file: '' # 留空 = 自动取 ~/.dsh/MEMO.md tokenChars: 3.2 # token 估算系数（中英混排经验值，只用于展示）

自测

node scripts/selftest-core.mjs # 解析 / 检索 / 追加 / 分类 / 精简，41 项
node scripts/preview/screenshot.mjs # 用无头 Edge 截图面板（离线，不连 DSH）

scripts/preview/index.html 加载的是真实的 lib/client.js，只是用假宿主和假 /api 响应，所以它能当 UI 的离线回归测试用： #cats 截分类面板、#confirm 截精简确认层、#anim 截按钮动画。

边界

- 只依赖 DSH 提供的 tools、webServer、slots 服务，不 spawn 任何外部进程，不需要 Python / CLI / 本地服务
- webServer 缺失时工具照常可用，只是没有面板和动画
- 面板端点只放行本机请求（127.0.0.1 / localhost）
- 精简版和备份都写在备忘录同目录：MEMO.lite.md 和 memo-backups/

License

MIT