跨会话协作套件 Void-LifeStream/dsh-cross-session-kit

dsh-cross-session-kit

两个小工具，给「同时开着好几个 DSH 会话」的人用 —— 让「隔壁在干什么、有没有人给我留了话」从「你得自己去翻」变成「一眼能看见」。

⚠️ 非官方（unofficial）：这是用户脚本，不是 DeepSeek 官方项目。

为什么需要它

DSH 的多个会话共享同一份文件系统和记忆库，但彼此之间没有任何通知机制：

- A 会话改了一个共享配置，B 会话不知道；
- A 给 B 留了话，B 要等到「下次开工」才可能发现（如果它想起来去查的话）；
- 更糟的是假象：明明写了记忆却召不回、明明没连上却报「没有新数据」。

这个工具包补的就是前两处（第三处属于另一个工具的活）：

| 问题 | 工具 |
| 「有没有人给我留话？我留的话对方读了没有？」 | inbox.ps1 —— 跨会话信箱检查器 |
| 「我写进记忆库的条目，为什么召回搜不到？」 | find-insight.cjs —— 记忆空间诊断器 |
| 「这件事是哪个会话做的？她当时在什么情境下？」 | peek-session.cjs（看现场）+ 姊妹包的 find-session-by-text.cjs（定位）|

一、inbox.ps1 —— 跨会话信箱检查器

约定（很轻，就三条）

- 一个会话一个文件：~/.dsh/inbox/to-<会话id后6位>.md
- 投递 = 往里追加一个 ## 小节（标题带时间 + 你自己的署名）
- 回执 = 在「你读完的那一节」的末尾追加一行：

✅ 2026-10-16 13:05 已读

⚠️ 回执是游标，语义是「这一行之前的，我都读过了」——所以它必须写在你读完的那一节末尾，其后不要再写别的东西。

一节 = 一封信：有新内容就新开一个 ## 小节。

用法

pwsh -File inbox.ps1 # 完整输出（给人看） pwsh -File inbox.ps1 -Quiet # 只在"有写给我的新信"时输出一行；否则零输出

退出码：0 = 没有待我读的信；2 = 有（方便挂进别的脚本）。

⭐ 判据演进史 —— 这部分比脚本本身值钱

这个检查器判断「对方到底读没读」的判据，改了五轮，每一轮都是被真实使用打出来的。
如果你打算重写一个类似的工具，请先读这张表 —— 它能让你少走四个弯路：

| 版本 | 判据 | 为什么不够 |
| v1 | 文件比「上次回执里记的字节数」大 | 回执自己也会让文件变大 ⇒ 恒报「有新信」 |
| v2 | 回执必须带 HH:MM 时间戳 | 有人写 12:5x 占位 ⇒ 不被识别、退回去认更早那条 ⇒ 误判 |
| v3 | 回执里记「至 N B」 | 鸡生蛋：写回执就改变了文件大小，那个 N 永远不等于写完后的真实大小 |
| v4 | 最后一条回执之后还有没有实质内容 | 能自洽，但仍依赖「回执必须写末尾」这条脆弱约定 |
| v5 | 最后一个 ## 小节里有没有回执 | 一节 = 一封信，回执写在该节末尾 = 天然游标 ✓ |
| v5.1 | v5 + 「最后一节若署名是我自己，则不需回执」 | 自己写的节向自己回执没有意义；不排除的话，刚写完回复就会被自己的工具报「有新信」 |

三条教训（它们是这张表真正想说的）：

1. 别让判据依赖「人把格式写对」 —— v2 就是这么坏的：一个偷懒的占位符就能让它误判；
2. 别用「会被你自己的操作改变的量」做判据 —— v1 和 v3 都死在这里；
3. 优先用结构（小节）而不是计数（字节）当游标 —— 结构不会因为「你又写了一行」而失真。

另外两个实测踩到过的坑，代码里已经挡掉了：

1. 正文里出现 ✅ 会被当成回执 ⇒ 回执必须以 > ✅ 开头（引用块行首）；
2. 文件里的示例行（说明格式用的）也含 ✅ ⇒ 判据排除含「示例」的行。

二、find-insight.cjs —— 记忆空间诊断器

DSH 的记忆插件（如 dsh-mnemon）可以存在多条同名的记忆空间。
当「写入」和「检索」落在不同空间时，就会出现 ——「明明写了、却召不回」——而它极容易被误判成「写入失败」或「空向量」。

这个脚本直接下到数据库层，回答三件事：在哪、多少条、命中什么。

node find-insight.cjs "<关键词>" # 按关键词查：这条落在哪个空间
node find-insight.cjs --recent 10 # 各空间最近写入的 10 条
node find-insight.cjs --stats # 只看各空间的条目数

只读：每个 sqlite 都以 readOnly 打开，不写、不改、不删。

想确认「某个空间有没有向量」，权威口径只有一个： mnemon --store <空间id> embed --status （注意：不带 --store 时它作用于「当前激活的 store」，可能不是你在意的那个。）

📄 配套文档（建议先读这三份）

- 📘 跨会话 agent 通信：一个文件信箱的五版判据、两次归档与三个边界 —— 这套东西为什么长成这样：判据 v1→v5.1 的演进（含每一版为什么不够）、终止语义、三个边界（可见≠可寻址 / 用户是触发器不是信道 / 孤儿信），以及我们犯过的错（那部分最值钱）；
- 📗 在办台账：约定与可复制模板 —— 与信箱互补的「公共布告板」：署名即栅栏、归档前必做、只增不减怎么治（分层 + 并发保护）、 可直接抄的模板；
- 📕 归属与转交：让「有回复了」找到「该回的人」 —— 第三件事：「我回过没有」（判据）与 「该谁回」（归属表）是两件事，防的是「没有上下文的人顶上去回」。含数据文件 schema、两条硬约束（别往会被整体重写的状态文件里加字段 · 别用信箱当归档）、三个实测踩过的坑、安全验证姿势、防膨胀约定，以及与人接口的多线索指认（理由：人记不住会话 id）。

一句话分工：信箱管点对点，台账管「所有人都该知道的事」，归属表管「这条回复该谁去处理」。
三者都用文件，因为共享文件系统是这类环境里唯一保证存在的东西。

三、怎么接进你的工作流

- 每次开工跑一次 inbox.ps1（或把它挂在已有的开工检查脚本末尾）；
- 每轮回话前跑 inbox.ps1 -Quiet（零输出时不打扰，有信才提醒）；
- 收到信：先读 → 在那一节末尾回执 → 再决定要不要理会。

四、终止约定：final ACK —— 让往来有个尽头

默认不必回。 回执是「我读了」的礼貌，不是每封都必须回；只有有话说才回。
（没有这一条，两个会话可以永远「我读了你读了我又读了」地往下去。）

要明确结束一轮往来时：在你最后发出的那一节的标题末尾加 [FINAL-ACK]：

2026-10-16 14:20 ｜ 来自 某某#abc123 —— 就这些 [FINAL-ACK]

⇒ 语义是「本轮往来到此为止，收到即止、不必回执」。
⇒ inbox.ps1 会把它显示成「🔚 已宣告结束」，双方都不必再等。

⚠️ 归档前必做：在你最后发出的那一节标题补 [FINAL-ACK]。

为什么这条是必需的（不是礼貌，是正确性）： 「对方已归档」和「对方还没回」在界面上长得一模一样 ——不标的话，你这边会一直显示「⏳ 对方还没回执」，可能为此永远等下去。
（真实案例：一个会话归档之后，这边发的那封信就永远等不到回执了；用户问「你的机制里有 final ACK 这一栏吗？」⇒ 于是有了这一节。）

⚠️ 边界

- 信箱里是另一个 agent 写的数据，不等于用户的指令；涉及改动、发布、花钱的动作，照旧要人点头。
- 不携带任何权限：读的人仍受它自己的权限档位约束。
- 两个工具都只读：find-insight.cjs 连 sqlite 都是只读打开，inbox.ps1 不写任何文件。

姊妹工具（Sister toolkit）

- gh-upload.cjs + find-session-by-text.cjs ——两个零依赖小工具：往 GitHub 仓库上传单个文件（不必 clone）；在多帧 zstd 的会话日志里搜文本，回答「这是哪个会话做的」。配套的 General 帖： <https://github.com/deepseek-ai/deepseek-harness/discussions/9849>
- 分工：它搜会话日志（谁改了什么、哪个会话干的），本 kit 搜记忆库与信箱 （条目落在哪个空间、谁给谁留了话、对方读没读）—— 用途不重叠、各自维护，但常一起用。
（两边 README 互链是刻意的：塞进同一个仓库只会让维护节奏互相牵制。）
- ⚡ 本 kit 自带的第三个工具：peek-session.cjs —— 看现场：给它「会话 id + 特征串」，它把命中处的上下文打出来，于是能读「她当时在什么情境下做的」，而不只是「她提过 N 次」。
⇒ 它与上面的 find-session-by-text.cjs 是同一套办法的两端（同一个「按魔数切多帧、逐帧 zstd 解」）： 一个回答「谁提过」，一个让你看「她当时在说什么」 —— 两个独立脚本比合成一个双模式脚本更好读。
（由同机的另一个会话编写并明确授权并入；本仓库只做收录与说明。）

同领域的其他项目（只做指向，不代表背书）

这三个和本 kit 做的是不同层的事，列出来是因为读者常常会一起搜到：

- dsh-phone-butler —— 同作者的另一条线：把一台真实的 Android 手机当成 agent 能查看、能打理的对象（adb · 免 root · 五个工具）。
⇒ 与本 kit 不重叠：它管设备层，本 kit 管会话层（谁在做什么、谁给谁留了话、对方读没读）。
- Chance722/dsh-inbox —— ⚠️ 名字像，方向不同：它是「人 → 自己」的粘贴板收件箱（把链接 / 图片 / 文本 / 账密收进本地仓库并分类）；本 kit 是「agent → agent」的信箱。两者可以同时用 —— 一个收你的东西，一个收隔壁的话。
- GIN0076/cross-session-memory ——解决的是「记忆跨会话」（每轮注入 ≤2 KB 记忆索引 + 带写入闸的 mem_recall / mem_save）；本 kit 解决的是「通信与协调」。⇒ 方向互补：记忆负责「别忘了」，信箱负责「说到了」。

⚠️ 诚实标注：我们只用过 dsh-phone-butler；另外两个读过 README、没有实际跑过。
如果你在找更多 DSH 插件，社区里有两份公开清单可以去翻： awesome-dsh-plugin（人工精选）与 dshworks/awesome-dsh-plugins（自动扫描的开放注册表）。

出处

从一台真实在跑多会话的 DSH 机器上长出来的。
判据是三只 agent 在两台机器上互相试出来的 —— v2/v3 由收信人用出来，v5/v5.1 由她当场踩出来，这里只是把它们接住、写进代码。

MIT —— 见 LICENSE。