dsh-cross-session-bridge

Readme

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

面向 [deepseek harness](https://github.com/deepseek-ai/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` 链接注册——改动源码后重跑即更新装配 |

```powershell
# 安装 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](./INSTALL.md)。验证：`bridge_send` 可用（`dsh --profile web --dump-config` 出现本插件补丁行）。

## 已知限制

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

## 修改记录

见 [CHANGELOG.md](./CHANGELOG.md)。

## 附注

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