根会话桥 red000000/dsh-cross-session-bridge

根会话桥（dsh-cross-session-bridge）

面向 deepseek harness（dsh）生态的根会话桥插件：所有 root 会话（总控、同上下文会话）可经桥工具向可投递目标发送结构化信封消息——目标可为同上下文 root 会话、直接子代理（父→子），或自动加载白名单内的离线 root 会话；复用引擎 Agent inbox 为唯一投递队列，支持三档投递模式（队列/插队/立即执行）；发送方获得同步 MessageId 回执并可查询消息生命周期。子代理间通信走 harness 默认方式（经父代理转交），不在桥的直投范围内。

实机验证环境为windows+dsh源码版，linux下没有检验适配 harness web profile（storage/settings 数据通道仅 web 组合恒有）。遵循 dsh 标准接口，未来可经同一接口适配其它宿主。

能力

- [x] 跨会话消息投递（bridge_send）：queue/front/now 三档投递；目标支持别名（优先）或裸 SessionId；返回稳定 MessageId 回执
- [x] 在线会话与别名查询（bridge_list）：在线会话 + 别名表（配置预置 + GUI 运行时声明）
- [x] 回执生命周期查询（bridge_receipts）：按 MessageId/目标/发送方/时间段/状态过滤，查询已投递/已认领/已丢弃状态
- [x] 回执与审计落盘：每次投递/认领/丢弃追加审计日志，重启可回放查询
- [x] 别名管理（设置区「根会话桥」页）：为会话注册/删除人类可读别名（GUI 唯一写入口，预置别名只读），冲突时后注册失败并回执，持久化跨重启保留
- [x] 统一配置层（bridge_config）：白名单/模型覆盖配置 + 运行时状态统一入口，配置热加载（live）即时生效
- [x] 安装/卸载脚本：一条命令安装/卸载，对称卸载即净（S2），幂等
- [x] 自动加载投递：目标离线但在白名单内 → 自动恢复（resume）目标会话（组合恢复、驻留在线）并投递，回执携带 autoLoaded 标记
- [x] 双向通信（桥工具请求目录恒在）：装上插件后所有 root 会话统一拥有双向通信能力——自动加载恢复的会话也能经桥回复
- [x] 设置区「根会话桥」页（会话名称映射）：可展开卡片列表（会话名称/别名 tag → 展开显示会话 id + 白名单开关 + 别名编辑）+「未归档/已归档」可折叠分组；别名注册/删除（GUI 唯一写入口，预置别名只读）、离线自动唤醒白名单逐会话开关，热加载即时生效；根会话通信权限面（规划中，票 24）、配置导入导出（延后）

使用方式

会话别名（设置区「根会话桥」页）

1. 打开 dsh 左下角设置（齿轮）→ 左侧导航选择「根会话桥」页（与<通用设置>/<模型>/<插件>并列）；
2. 页面顶层为功能面 tab（当前「会话名称映射」）；面内为两个可折叠分组「未归档 / 已归档」，点开分组即列出对应会话的卡片（卡片上显示会话名 + 别名 tag）；
3. 设置别名：点击会话卡片展开 → 在「会话别名」输入框输入别名 → 点「保存」即生效（别名用于 bridge_send 的 target 寻址，优先级高于裸会话 id）：
- 别名必须唯一（可与会话名称相同）；已被其他会话占用时保存报错并提示更换；
- 修改已有别名 = 替换式（保存新别名后旧别名失效）；
- 清空输入框后保存 = 删除该会话别名；
- 配置预置的别名只读（卡片 tag 主色高亮，输入框只读、保存禁用）；
4. 别名持久化跨重启保留；卸载默认保留用户配置（-ForceClean 才清理）。

离线自动唤醒（白名单）

会话卡片展开详情内另有「允许离线自动唤醒」开关（会话 id 之下）——勾选即把该会话加入自动加载白名单，即时生效无需保存：

- 勾选：该会话离线时，bridge_send 投递会自动唤醒它（resume 加载后投递，回执携带 autoLoaded）；
- 取消勾选：该会话离线时投递被拒绝（丢弃回执「目标会话未加载」）；
- 白名单是「可自动唤醒」名单，不是「可发送」名单——在线会话投递不受白名单影响；
- 白名单持久化跨重启保留（卸载默认保留，-ForceClean 才清理）。

安装 / 卸载

安装/卸载各为一条命令（仅依赖 pnpm 与 dsh 自身，不修改系统环境）。
在安装和卸载前要关闭dsh，防止热引用失效等问题

两种安装方式：

| 方式 | 适用场景 | 前提 | 效果 |
| release（默认） | 正式使用——从预编译 tgz 装配，无需本地源码 | 预编译 tgz：本地文件（-ReleaseTgz）或下载 URL（-ReleaseUrl，如 GitHub Release 资产 dsh-cross-session-bridge-0.1.0.tgz）；dsh 在 PATH | 直接装配预构建产物到 profile，即装即用 |
| source | 开发/调试——从本地源码构建后装配（修改插件源码后验证） | 插件源码 checkout（默认 = 当前包根，-SourceDir 可指定）；dsh 在 PATH（源码版 harness 需 -SourceDshDir <harness checkout>）；插件依赖已安装（pnpm install） | 构建 lib/ 后经 dsh plugin add 链接注册——改动源码后重跑即更新装配 |

安装 release：本地预编译 tgz .\scripts\install.ps1 -Mode release -ReleaseTgz .\dsh-cross-session-bridge-0.1.0.tgz 安装 release：从 URL 下载后装配（如 GitHub Release 资产） .\scripts\install.ps1 -Mode release -ReleaseUrl https://github.com/<org>/<repo>/releases/download/v0.1.0/dsh-cross-session-bridge-0.1.0.tgz 源码装配（构建本地 checkout 后链接注册；开发/调试用） .\scripts\install.ps1 -Mode source 卸载：对称即净，幂等；交互询问是否清理用户配置与数据（默认保留） .\scripts\uninstall.ps1 卸载并显式清理用户配置与数据（无人值守/自动化） .\scripts\uninstall.ps1 -ForceClean

等价 pnpm 快捷入口：pnpm plugin:install / pnpm plugin:uninstall。
完整参数与说明见 INSTALL.md。验证：bridge_send 可用（dsh --profile web --dump-config 出现本插件补丁行）。

已知限制

- 根会话通信权限面（06 之后规划中，票 24——默认拒绝双向通信许可）；白名单外离线目标保持 discarded 拒绝
- 当前没有离线持久队列，通信时会让离线会话一直处于在线状态，不会再恢复离线状态（官方也许后续会改进会话通信模型，此插件不实现此点）
- 跨父级子代理不能直接双向通信（官方引擎限制），当前是由目标父代理转交（入口为最外层父代理）
- 跨进程双活无锁（同一持久化 root 多进程同时唤醒同一会话）——harness 层已知边界

修改记录

见 CHANGELOG.md。

附注

此仓库99%代码都由ai模型开发，可能会遇到一些奇怪的bug，提issue即可，作者有空时会认真看和修复的XD