Weiyang742/dsh-cross-session-messaging

DSH Cross-Session Relay

License: MIT
CI

让多个独立运行的 DeepSeek Harness（dsh）会话互相发现、对等收发文本消息。

解决的问题

dsh 内置了两种「跨会话」能力，但都不是对等的进程间通信：

- subagent（子代理）：主从委托——父 agent 派生子代理，子代理活在父的上下文里、受父控制，不是独立的对等会话。
- @session 引用：Web 界面的单向只读召回，只能「引用」另一个会话的历史快照，不能「发消息」给它。

但在实际协作里，两个会话常常需要互发消息。典型的例子是「数据库助手」和「前端助手」被拆成两个独立会话，各自待在最适合自己的环境里：

- 数据库助手跑在能连库的内网机器上，有数据库上下文和权限；
- 前端助手跑在开发机上，负责写页面。

当前端助手需要「用户表的建表 SQL」时，它自己没有数据库的上下文和权限，只能发消息去问数据库助手；数据库助手查出来之后，再回发给前端助手。

这种「不同专长 / 不同权限 / 不同机器之间的对等问答」，正是 subagent 的主从结构和 @session 的只读召回都覆盖不了的场景——它们要么是父子控制，要么只能单向看。本插件补上的就是这条对等的双向通道。

本插件怎么做

一条对等、无中心、跨进程（可跨机）的消息通道：

- 模型主动：agent 自己调用 cross_session_list_agents 发现对端、cross_session_send_message 发送，无需人手动转发。
- 对等注入、不授权：消息以 form: 'relay' 身份注入接收方 agent，只作为文本，不替用户批准任何工具调用——安全边界仍在接收方自己的审批。
- 可靠投递：发送方 spool 落盘 + 指数退避重试 + 死信；接收方先落盘再 ack；at-least-once + 内容去重。
- 本机 / 跨机一体：同机走 Unix socket，跨机走 TCP+TLS（fail-closed，静态 peers）。
- 无中心：磁盘 registry 即状态，没有中心 server。

与 dsh 内置能力的区别

| | subagent | @session 引用 | 本插件 |
|---|---|---|---|
| 会话关系 | 主从 | 单向只读 | 对等 |
| 能否互发消息 | 父 → 子控制 | 否 | 是，双向 |
| 跨进程 / 跨机 | 同进程 | 同进程 | 是 |
| 注入形态 | 子代理上下文 | 历史快照 | relay 文本，不授权 |

安装

前置：Node.js >= 24.11、一个可用的 dsh（DeepSeek Harness）环境。

从源码安装时先构建产物（lib/ 不随仓库分发）：

npm install
npm run build

然后把插件装进一个 profile：

dsh plugin --profile demo add ./cross-session-messaging
dsh --profile demo --dump-config   # 验证织入

插件通过 cordis.patch.yml 以 bundle 层插入 profile，未列出的配置走默认值。

使用

装好后，开两个 dsh 会话（例如 Web 界面的两个「New Session」），在其中一个里用自然语言说：

帮我看看当前还有哪些其他会话，给其中一个发条消息：你好。

模型会自己调用 cross_session_list_agents 发现对端、cross_session_send_message 发送；另一个会话会以 form: 'relay' 收到这条消息。人只下自然语言指令，不点任何工具名。

完整的端到端步骤见 Quick start。

配置

配置写在插件的 cordis.patch.yml 的 config: 段里（安装时已经用它织入），未列出的字段走默认值。本机使用通常只需要默认值，需要定制的主要是 name 和入站策略：

- insert:
- id: cross-session-messaging
name: '@wy/dsh-cross-session-messaging'
config:
dirs:
baseDir: ~/.dsh/cross-session   # 数据目录根，registry/socket/spool 等派生自它
inbound:
rules: []                        # 入站规则，见下
defaultDecision: auto            # 无规则命中时的兜底
name: ''                           # 本会话可读名，缺省为 shortId
跨机（可选，见「跨机」）：
remote:
listen: { host, port, identity, secret }
tls: { key, cert }
peers:
- { name, host, port, secret, tls, tlsCa/tlsFingerprint }

- dirs.baseDir：所有数据目录（registry / socket / spool / credential / deadletter / audit）的根，默认 ~/.dsh/cross-session；六个子目录都可单独覆盖。
- inbound.rules：按 receiver（本地会话 id/name）与 sender（发送方 sessionId）匹配的 accept | hold | refuse 规则；两者省略分别为「所有本地会话」与「默认规则」。
- inbound.defaultDecision：无规则命中时的兜底；auto（默认）参考接收方 DSH_PERMISSION_MODE（danger-full-access → hold，其余 → accept），也可显式设 accept | hold | refuse。
- name：本会话的可读名，供 cross_session_send_message 按名寻址。

跨机

跨机需要额外配 remote（本机互发不用管）：

- remote.listen：本机作为接收方时的 TCP 监听端点（host / port / identity / secret）；identity 是这台机器在对端眼里的身份，写入入站消息的 from。
- remote.tls：监听证书（key / cert）；省略则自动生成自签证书到 spool/tls，指纹写到 spool/tls/fingerprint。
- remote.peers：本机作为发起方时的静态对端列表（name / host / port / secret / tls / tlsCa 或 tlsFingerprint）。tls 缺省 true；跨机 TLS 必须提供 tlsCa 或 tlsFingerprint，否则拒绝连接。

容量与重试（调优）

limits.（队列上限、消息大小、限流、去重窗口）、delivery.（投递重试与退避）、metricsIntervalMs、auditMaxBytes 都有保守默认值，绝大多数场景不用改；需要调整时按字段名改即可。

工具

- cross_session_list_agents：列出可达的 peer session（sessionId / name / shortId / cwd / pid）。
- cross_session_send_message：向指定 session 发送文本；目标可用 sessionId、shortId 或 name。
- cross_session_inbox_review：查看 hold 中等待 accept/refuse 的消息。
- cross_session_inbox_resolve：对 hold 消息执行 accept 或 refuse。

权限语义

- peer 消息以 source.form = 'relay' 注入，只作为文本进入模型，不会替用户批准任何工具调用；接收方工具仍走自身的审批（默认 fail-closed）。
- 消息 from 由服务端鉴权覆盖（本地=sessionId、跨机=listen.identity），不信任发送方自报；本会话被权限系统拒绝过的工具名会被记住，send_message 不会替对方转发这类操作。

Hooks / 子进程回发

插件把当前 socket / sessionId / 握手 token 通过 ctx.shellEnv 注入 shell 子进程（DSH_CROSS_SESSION_SOCKET / DSH_CROSS_SESSION_ID / DSH_CROSS_SESSION_TOKEN）。长任务子进程或 hook 可连上 socket 回发文本，或调用导出的 sendToCurrentSession(text)。

测试

npm test          # 单元 + 集成（真实 socket）
npm run check     # lint + typecheck + build + test

测试分层、跨机压测矩阵与 CI 策略见 docs/testing.md。

限制

- 跨机发现是静态 peers 配置（需重启生效），无中心 registry，也不支持公网 NAT 穿透；真实公网双机已验证 transport/service 层（低频稳定、高频 ping 偶发），模型主动调工具的宿主端到端尚未验证。
- TLS 证书自动生成（openssl 自签），但未做过期轮换/吊销；跨机 TLS 必须配置 tlsCa / tlsFingerprint（fail-closed）。
- 投递为 at-least-once + 内容去重（含跨重启），非严格 exactly-once：窗口外或不同内容仍可能重复。
- accepted 与 held 均落盘（重启恢复）；accepted 消息在注入后标记，未注入会重新投递，崩溃点极小。
- 跨机身份是单对端：listen.identity 为单值（两台机器假设），未来多对端需扩展为 allowed 列表。
- 转交防护是启发式（best-effort），真正的安全边界是 relay 不授权 + 默认入站策略。
- peer 消息以 form: 'relay' 注入，不携带用户授权；接收方工具仍走自身审批（默认 fail-closed）。