dsh-bridge

本机 DSH ↔ ChatGPT/Codex 会话 MCP 双工桥：让 DeepSeek Harness（DSH）会话与 ChatGPT 桌面应用 / Codex CLI 中的本地 Codex 会话之间实现双向消息、协同开发与对方能力调用。

• 零外部依赖（Node ≥ 22.5 内置 node:sqlite、WebSocket、fetch）
• 单进程常驻 coordinator：SQLite 持久队列、会话所有权状态机、统一投递决策（steer / new_turn / queue / auto）
• writer 租约：桥仅在执行 turn 期间持有会话 writer，结束自动交还（archive→unarchive，实测唯一 per-thread 释放手段）——桌面应用可无感打开桥会话
• 临时介入循环：DSH 托管的长任务可随时 session_pause 让用户原生接管，操作完 DSH 下一条指令自动收回托管
• 对桌面当前持有的活跃会话不抢占：自动降级排队（mailbox），桌面释放后经 session_claim 切换
• 同一 MCP server 同时供 ChatGPT 桌面应用与 Codex CLI 加载（共享 ~/.codex/config.toml 的 [mcp_servers.*] 段）

设计基线见仓库内文档：

• dsh-codex-mcp-bridge.md —— 方案（评审稿，含实测勘误）
• dsh-codex-mcp-bridge-implementation.md —— 实施细节（协议实测值、通知/RPC 目录、边界矩阵）
• docs/chatgpt-usage-prompt.md —— 粘贴给 ChatGPT 会话的使用说明 prompt

架构

 ChatGPT 桌面任务                  Codex CLI / bridge 控制台
         │ MCP stdio                         │ CLI / unix socket
         ▼                                   ▼
 ┌──────────────────────────────────────────────────────────┐
 │                  dsh-bridge Coordinator                  │
 │  - 统一 session interface（steer/start/queue/auto）      │
 │  - 会话注册表 / writer 租约 / active execution           │
 │  - SQLite mailbox、回执、事件游标、熔断                    │
 └───────────────┬──────────────────────────┬───────────────┘
                 │                          │
        DshSessionAdapter          CodexHostAdapter
        HTTP RPC（事件流 WS）        JSON-RPC over WS
                 │                          │
                 ▼                          ▼
        DSH Web :3080             bridge 管理的 Codex App Server

核心模块：

组件	路径	说明
Coordinator	src/coordinator.mjs	单例进程：DB、registry、mailbox、双 adapter、unix socket IPC、/healthz、KILLSWITCH
DshSessionAdapter	src/adapters/dsh_http.mjs	DSH Web HTTP RPC（session.list/history/prompt/cancel/create；events.mux 为 WS 流）
CodexHostAdapter	src/adapters/codex_ws.mjs	独立 Codex App Server（thread/*、turn/*、settings/name/release）
Delivery 决策	src/adapters/host.mjs	steer / new_turn / queue / auto 与 writer 租约、介入循环的单一实现
MCP stdio 前端	src/frontends/mcp_stdio.mjs	供 ChatGPT 桌面 / Codex CLI 加载（15 个工具）
DSH CLI	src/frontends/cli.mjs	dsh-bridge status/send/guide/…（与 MCP 同构）
运维	src/ops/backup.mjs	SQLite 每日快照（VACUUM INTO，保留 7 份）

MCP 工具面（15 个）

工具	作用
bridge_status / capabilities	桥与双 host 状态、能力与限制
session_list / session_history	枚举会话（dsh/codex）、读历史（dsh 带 seq 游标）
session_send	普通消息：目标空闲→新 turn，运行中→排队
session_guide	引导/指令：auto（默认）/ steer（追加到执行中 turn，不打断工具）/ new_turn / queue
session_cancel	取消：dsh=session.cancel；codex=turn/interrupt
session_pause	临时介入：中断当前 turn + 立即交还 writer（桌面原生接管），DSH 下条指令自动收回托管
session_settings	codex：切换模型 / 思考程度（影响后续 turn）
session_create	新建会话：codex=桥会话（threadSource=user，桌面侧栏可见）；dsh=新建空白 DSH 会话（queue 消息自动启动）
session_ownership	codex：claim / release / status（不抢占桌面活跃会话）
session_receive / session_ack	mailbox 收件箱轮询与回执
task_submit / task_report	结构化任务提交（--from 溯源）与结果回传

快速开始（Linux）

git clone https://github.com/SoftDefender/dsh-bridge.git
cd dsh-bridge
node --version        # 需要 ≥ 22.5

# 1) 启动 coordinator（首次启动生成默认配置 ~/.codex-bridge/）
node src/coordinator.mjs &
curl http://127.0.0.1:45170/healthz   # 健康检查：双 host up

# 2) CLI 冒烟
node src/frontends/cli.mjs status

默认 codex.cli_path = /usr/lib/chatgpt/resources/codex（ChatGPT 桌面内置二进制）； code_mode_host = true（false 时桥会话无法执行 shell，勿改回）。 纯 Codex CLI 环境可将 cli_path 改为 codex。其他参数在 ~/.codex-bridge/bridge.toml 调整。

生产运行（systemd user unit）

cp systemd/dsh-bridge.service ~/.config/systemd/user/   # 把 ExecStart 的 node 换成绝对路径
systemctl --user daemon-reload && systemctl --user enable --now dsh-bridge
cp systemd/dsh-bridge-backup.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now dsh-bridge-backup.timer   # 每日 03:00 SQLite 快照（保留 7 份）

• 熔断：touch ~/.codex-bridge/KILLSWITCH 即拒绝全部投递（quota-exceeded），删除即恢复。
• 日志：~/.codex-bridge/log/bridge.log（jsonl，含 App Server 通知流）。

接入 ChatGPT 桌面应用 / Codex CLI

两者共用同一配置段（追加到 ~/.codex/config.toml）：

[mcp_servers.dsh-bridge]
command = "node"
args = ["/home/<user>/dsh-bridge/src/frontends/mcp_stdio.mjs"]
startup_timeout_sec = 30

[mcp_servers.dsh-bridge.env]
DSH_BRIDGE_SOCKET = "/home/<user>/.codex-bridge/run/coordinator.sock"

• ChatGPT 桌面应用：重启后自动加载；每个会话独立 spawn 一个 mcp_stdio 前端，工具面是会话创建时刻的桥版本快照——升级桥后需新开会话（或重启应用）获取最新工具集（当前 15 个）。给会话粘贴 docs/chatgpt-usage-prompt.md 即可让它按约定协同 DSH 会话。
• Codex CLI：同段自动生效；也可 codex mcp add dsh-bridge -- node <abs-path>/src/frontends/mcp_stdio.mjs。
• coordinator 必须先于任一端运行（mcp_stdio.mjs 是无状态薄前端，仅转发 coordinator.sock）。

协同操作总览（实测矩阵）

ChatGPT → DSH（DSH 会话执行长任务期间全程可操作）：

操作	方式	状态
发送/启动	session_send、session_guide new_turn；空白会话 queue 消息即自动启动	✅ 实测
执行中引导	session_guide delivery=steer（注入执行中回合，不打断工具）	✅ 实测
排队	session_guide delivery=queue	✅ 实测
取消	session_cancel（session.cancel，turn/end aborted）	✅ 实测
历史/列表/新建	session_history / session_list / session_create	✅ 实测
切换模型/思考程度	无会话级 RPC（仅创建时 agent_preset）	❌ 协议限制

DSH → ChatGPT（桥托管 codex 会话）：

操作	方式	状态
执行中 steer	session_guide delivery=steer（同 turn 注入）	✅ 实测
取消/暂停	session_cancel、session_pause	✅ 实测
排队	mailbox 自动降级（desktop-owned/busy）	✅ 实测
模型/思考程度	session_settings（影响后续 turn）	✅ 实测
桌面原生接管	session_pause → 用户操作 → DSH 下条指令自动收回	✅ 实测

执行模型（混合）：DSH 发起的自主长任务由桥宿主执行（配合暂停介入）；用户在场任务经 task_submit 投递，由桌面会话原生执行。两者共用同一 mailbox/任务协议，可随时切换。

CLI 用法

alias dsh-bridge='node /home/<user>/dsh-bridge/src/frontends/cli.mjs'

dsh-bridge status                                        # coordinator + 双 host + 队列
dsh-bridge session create --host codex|dsh --cwd /path [--title 任务名] [--agent-preset p]
dsh-bridge session claim <threadId> | release <threadId> | pause <threadId>
dsh-bridge session cancel <dsh:|codex:><id>             # 取消运行中会话
dsh-bridge session list --host dsh|codex                # 枚举会话
dsh-bridge session settings --to codex:<id> [--model m] [--effort e]
dsh-bridge history --to <dsh:|codex:><id> [--limit N]
dsh-bridge guide --to codex:<threadId> --message "优先处理测试失败" --delivery auto
dsh-bridge send    --to dsh:<sessionId> --text "hello"
dsh-bridge receive --to codex:<threadId> --status all   # 收件箱（含排队消息）
dsh-bridge ack     --message-id <id> --reply "收到"
dsh-bridge task submit --to codex:<threadId> [--from dsh:<sessionId>] --kind task --title T --brief B
dsh-bridge task report <taskId> --status done --summary S
dsh-bridge capabilities

目标格式：dsh:<DSH sessionId> 或 codex:<threadId>。

测试

node --no-warnings --test test/unit.test.mjs               # 单测（无需外部依赖）
node --no-warnings --test test/integration_codex.test.mjs  # 真实 App Server 集成（慢，少量模型配额）

已覆盖（实测断言）：thread/start(threadSource=user) → turn/start(sleep) → steer → STEER_OK 且 rollout 真实执行过 exec（防假绿）；已存在会话再次引导；确定性模拟桌面宿主（第二 App Server 持有活跃 turn）→ 降级排队 + claim 拒绝；writer 租约交还与第二宿主无感接管；session_meta.thread_source=user 侧栏可见性断言。

与 ChatGPT 原生协同机制的定位差异

	dsh-bridge	ChatGPT 桌面 collab agent
范围	跨应用：DSH ↔ ChatGPT/Codex 会话	应用内：ChatGPT 会话之间
触发	MCP 工具 / CLI / 桥队列	应用内任务分派
外部可编程性	完全可编程（协议/CLI/库）	不可外部编程接入
适用	跨模型（DeepSeek ↔ GPT）协同开发	同模型多会话分工

两者互补：dsh-bridge 面向"DSH 与 ChatGPT/Codex 的跨应用双工协同"。

已知限制

• 桌面应用当前持有的活跃会话不可被外部直接 steer（单写者）；排队 + session_claim（桌面释放后）切换。桌面仅加载未运行时 claim 即可成功。
• 桥新建的 Codex 会话跑过第一个 turn 后出现在桌面侧栏（线程列表/状态库在首 turn 才落库；命名在建会话时已写入）。
• turn/steer 影响后续模型决策、不强制中断正在执行的 shell/MCP 工具；立即停止用 session_cancel。
• 桥执行 turn 期间桌面原生 UI 无法接管（协议级单写者，跨宿主 steer/interrupt 均 thread not found）；轻量控制经任意桌面会话的桥 MCP 工具完成，原生接管用 session_pause。DSH 方向无此限制；DSH 无会话级模型/思考程度切换 RPC。
• App Server WebSocket transport 为实验性（codex 官方标注）；升级 Codex 后需重跑集成测试。
• DSH HTTP schema 处于 developer preview；coordinator 启动做 capability probe，失败即拒绝相关操作（fail-closed）。events.mux 是 WebSocket 流（非 SSE）。

License

MIT