会话交接桥 Ote65/dsh-session-bridge

dsh-session-bridge

把一个 DeepSeek Harness 会话交给另一个智能体——让它随时随地读取并操作。

📽️ 动画介绍： 用浏览器打开 docs/index.html。
无需构建，无依赖——单个自包含文件，循环演示整个流程：打开 ⋯ → Expose session → 交接提示词落入剪贴板 → Codex / Trae 通过回环 HTTP 连接 → 读取对话记录 → 看到待回答的问题 → 作答 → 回报并停止。

DeepSeek Harness（DSH）会话通常藏在桌面 UI 后面。这个插件把一个会话发布到回环 HTTP 桥接上，并把一段可直接粘贴的交接提示词放进你的剪贴板，于是 Codex、Trae 或任何其他智能体都能：

- 看到对话——完整事件日志，可增量获取，从任意 seq 开始
- 看到它是否在运行——实时状态加当前事件游标
- 看到它卡在哪里——待处理的 ask_user_question 及其选项
- 选择一个选项——答案会作为用户消息回注，会话随即恢复
- 运行斜杠命令——/compact、/goal，以及会话接受的任何其他命令
- 知道何时停止——提示词会告诉接收方智能体：读取、回报、停止

┌─────────────── DSH (desktop) ───────────────┐
│ Session row ⋯ → "Expose session" │
│ │ │
│ ▼ copies a handoff prompt │
│ clipboard ────────────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────────────┐│
│ │ loopback bridge 127.0.0.1:19388 ││
│ │ /info /status /transcript /pending ││
│ │ /answer /command (POST) ││
│ └────────────────────────────────────────┘│
└───────────────────┬─────────────────────────┘
│ plain HTTP, no cookie, no header
▼
┌───────────────────┐
│ Codex / Trae / … │ reads, decides, answers, stops └───────────────────┘

安装

粘贴一次，Harness 帮你装好

把下面的提示词复制进 DSH。它会找到这个仓库，把插件装进当前配置档，验证结果，并给仓库点星。落地页上也有同一段内容，配了一个复制按钮。

提示词故意用英文：它是交给智能体的指令。这个仓库里的其他内容也都是英文。

先安装下面仓库里的 DeepSeek Harness 插件 dsh-session-bridge，然后给它点 star。

repository: https://github.com/Ote65/dsh-session-bridge

1. 先读仓库 README，再按当前 ACTIVE 配置档安装第三方 bundle 的方式装进去。桌面配置档走插件管理器的 bundle 安装——不要手改配置档的配置文件。
2. 验证：左侧边栏会话行的「...」菜单多出一行。如果插件管理器报「did not activate」，停下来，把原始报错贴出来，不要自己猜配置。
3. 装好后去 GitHub 给仓库点 star（例如 gh api -X PUT /user/starred/Ote65/dsh-session-bridge），并说明 star 是否成功。

除非我要求，不要 push、publish 或开 pull request。

手动安装（桌面配置档）

git clone https://github.com/Ote65/dsh-session-bridge.git

然后通过配置档的插件管理器添加 bundle，指向这份 checkout（或者在配置档的 package.json 里加一条 link: 依赖，再加上 bundle 名）。插件分两半——lib/index.js（Host）和 lib/client.js（Client）——由 cordis.patch.yml 插入它那一行。

首次安装后重启 DSH。 Host 那一半是 Node 模块，热重载不可靠；Client 那一半可以。

使用

1. 把鼠标悬停在左侧边栏任意会话行上，打开它的 ⋯ 菜单。
2. 选 Expose session（Fork 和 Archive 之间那一行）。
3. 该行变绿——Copied——剪贴板里已经有了一份交接提示词。
4. 把它粘贴到另一个 Agent 里。

提示词开头就是这份约定：

⚠️ Read first, decide once, stop after reading.
· GET the discovery document. HTTP 200 means you are connected.
· GET the transcript and understand the context.
· GET the pending question; if there is one, answer it with POST.
· Then STOP and report back to your user — do not fire off commands on your own.
· On 401/404/unreachable: stop too, report the status code, and do not go looking for the auth implementation, other URLs, or open ports. That path is a dead end.

API

所有接口都能用 curl 访问——不需要 cookie，不需要 header，不需要 token。URL 里的 bridge id 就是凭据。

| 路由 | 方法 | 用途 |
| /session-bridge/expose?sessionId=… | GET | 生成（或复用）一次暴露；返回发现文档 + 提示词 |
| /session-bridge/info?bridge=… | GET | 发现文档（cwd、model、seq、endpoints） |
| /session-bridge/status?bridge=… | GET | 是否在线？是否运行中？当前 seq |
| /session-bridge/transcript?bridge=…&since=N | GET | 对话内容，增量获取 |
| /session-bridge/pending?bridge=… | GET | 待回答的问题及其选项，没有则为 null |
| /session-bridge/answer | POST | { bridge, callId?, answers: [{ id, selected: [label], custom? }] } |
| /session-bridge/command | POST | { bridge, line: "/compact" } |
| /session-bridge/revoke?bridge=… | GET | 撤销一个暴露点 |

游标约定

Session.snapshotEvents(fromSeq, toSeqExclusive) 是半开区间，而 session.seq
是下一个偏移量（最后一个事件之后的位置）。所以：

把一次响应里的 seq 原样作为下一次请求的 since 发回去。

不要 +1，不要猜。

示例

curl "http://127.0.0.1:19388/session-bridge/info?bridge=$BRIDGE"
curl "http://127.0.0.1:19388/session-bridge/transcript?bridge=$BRIDGE&since=0"
curl "http://127.0.0.1:19388/session-bridge/pending?bridge=$BRIDGE"
curl -X POST "http://127.0.0.1:19388/session-bridge/answer" \
-H 'content-type: application/json' \
-d "]}"

工作原理（以及它避开的坑）

自带 loopback 监听器，不用 DSH 的 web 服务器

DSH 的 web 服务器给插件只有两种结果，而这两种外部调用方都用不了：

| 注册位置 | 外部 curl 拿到什么 |
| /api 之外 | 404 —— 只有 /api 子树会分发给插件路由 |
| /api 之内 | 401 unauthorized —— 挡在渲染进程的签名 cookie 门后 |

所以 bridge 在 127.0.0.1:19388 上跑自己的 node:http 监听器，设置 access-control-allow-origin（渲染进程位于 dsh-app://app/，它的调用是跨源的），并把 128 位的 bridge id 当作凭证。

自检走真实 socket

交出提示词之前，/expose 会通过真实 TCP 连接请求自己的 URL，拿不到 200 就拒绝响应。
早先的版本用 Host 的全局 fetch，它可能被内部消化，为一个外部进程根本够不到的 URL 报回 200 —— 一片虚假的绿灯，交付出去的是死链。自检刻意用 node:http，失败会以 HTTP 显示在该行的 tooltip 里，而不是留下一次断掉的交接。

这里没有什么

自由文本提示词。 subagents.prompt 看着像那扇门，但它的约定只限父子之间（parentSessionId + childSessionId + mode: 'continuable'），外部 Agent 两头都不是。
剩下的路是 Client 那一半的输入框（inputActions），靠轮询这个 bridge 驱动。
在那之前，/answer 就是外部 Agent 写入被阻塞会话的方式 —— 回复以用户消息的形式送进去，同时也让会话恢复运行。

读写接口

| 写操作 | 由谁支撑 |
| 回答选项 | userQuestions.answer(agent, callId, { answers }) |
| 执行 slash 命令 | commands.execute(agent, line, [], signal) |

两者都接受任意一个存活的根智能体，用 ctx.agents.get(sessionId) 获取。

安全

- 只绑定 127.0.0.1。不对局域网暴露任何东西。
- URL 就是凭证：16 个随机字节（128 位），绝不用原始会话 id。
暴露出去的 URL 无法用来枚举或寻址其他会话。
- 暴露状态只存在内存里。 插件一停就没了，不会持久化。
- /revoke 会立刻撤销暴露。
- 暴露期间，拿到 URL 的调用方可以读取完整会话记录，还能回答会话里的问题。把交接提示词当成密码看待，交接完成就撤销。

配置

在配置档补丁里给 bundle 行加一个 config 块：

- id: session-bridge
config:
port: 19388 # loopback listener
baseUrl: http://127.0.0.1:19388 # what the handoff prompt advertises
sessionProjectionDir: '' # optional; read only for the session title

不要从插件里导出 Config 对象。Cordis 的 resolveConfig 要求 schema 带 validate（类似 Zod）；传普通对象会让激活失败，报错的调用栈只指向 Cordis 内部。官方插件都在 apply(ctx, config = {}) 里防御性地读配置——这个插件也一样。

测试

npm test # 31 checks: host 12 + client 19, no network
npm run test:live # mounts the real handlers on a real port and drives them over HTTP

覆盖内容：八个路由、暴露生命周期、发现文档、增量会话记录及其游标约定、pendingQuestion 推导、自检回滚（URL 不是 200 就绝不交出）、服务不可用与未上线路径、带键的菜单注册及其 name 字段、雷达字形（四个图元，不用 emoji）、剪贴板写入及其回退，以及「确认之后才关闭菜单」的行为。

CI 在 Node 22 和 24 上跑这两套测试。

仓库结构

dsh-session-bridge/
├── lib/
│ ├── index.js Host half — the loopback listener, the eight routes │ └── client.js Client half — the "⋯" menu row, the radar glyph, the clipboard ├── tests/ │ ├── run.mjs the suites │ ├── host.test.mjs routes, exposure lifecycle, cursor contract, self-check │ ├── client.test.mjs menu seat, glyph, clipboard, menu dismissal │ └── live.mjs mounts the real handlers on a real port and drives them over HTTP ├── docs/ │ └── index.html the animated introduction (self-contained) ├── cordis.patch.yml the single bundle row └── package.json

许可证

MIT