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

dsh-memo

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

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

它解决什么问题

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

想找东西 → 先看目录（约 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              → 状态
其余            → 专题

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 行
超出预算时从最低分行开始丢

实测（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）

边界

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

License

MIT

wonderandyou/dsh-memo

dsh-memo

它解决什么问题

安装

工具（模型用）

面板（人用）

原理

1. 索引：把 Markdown 切成节

2. 为什么能省 token

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

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

5. 书架动画

5.1 场景设计

5.2 为什么落地看不出接缝

5.3 怎么渲染成视频

5.4 触发与播放

5.5 Canvas 兜底

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

配置

自测

边界

License

Community comments

wonderandyou/dsh-memo

dsh-memo

它解决什么问题

安装

工具（模型用）

面板（人用）

原理

1. 索引：把 Markdown 切成节

2. 为什么能省 token

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

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

5. 书架动画

5.1 场景设计

5.2 为什么落地看不出接缝

5.3 怎么渲染成视频

5.4 触发与播放

5.5 Canvas 兜底

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

配置

自测

边界

License

Community comments