dsh-codex-bridge

English | 中文

面向 DeepSeek Harness（dsh）的双面（宿主 + 浏览器）插件：把 Codex CLI 桥接进 harness。

为什么需要它

dsh agent 经常想找外部编码 agent（OpenAI Codex）要一个第二意见或并行编码一遍。手动做这件事——spawn codex、抓 JSONL、轮询、把输出接回来——正是 harness 插件存在的意义。本插件让 Codex 成为 dsh 的一等公民：

1. 把 Codex 当工具调用 — call_codex 在会话工作目录启动 Codex 会话（codex -a never exec --json），支持 async（立即返回；多次调用并行）与 block（等待最终答案）两种模式，另有 codex_status 轮询、codex_abort 取消。
2. 同一线程续跑 — codex_steer 在同一线程上恢复已 settle 的 Codex 会话（codex exec resume <thread_id>），可纠偏、追问、改方向且保留完整历史。线程是线性的：父必须是该线程最新记录，且同一线程只允许一个进行中的延续。
3. 展示整个 agent loop — 会话 pane 里的 Codex 标签（与 Chat/Trajectory 平级）实时观察每个会话：状态、提示词、Agent Loop waterfall（消息、带命令/参数的工具行、可折叠的工具输出与退出码、回合分隔）、transcript 与最终回答——经 session projection 通道推送。

定位：UX 通道，不是安全边界。 Codex 以调用用户权限运行，使用其自身 sandbox 策略（模型可选 read-only/workspace-write；danger-full-access 仅部署配置可设）。模型面对的面刻意收紧：Codex 恒在会话工作目录运行（绝不回退宿主 cwd——fail closed），默认仅顶层 agent 可调用，maxParallel/maxSessionsPerSession/maxLoopSteps/maxLoopBytes 约束资源与写放大。

安装

前置条件：Node.js 22 或更高版本、@deepseek-ai/dsh@0.1.0-rc.6，以及已完成认证且可通过 codex 调用的 Codex CLI（也可配置 codexPath）。插件不读取或保存 API Key；认证仍由 Codex CLI 管理。

在插件目录内构建、校验并打包独立 bundle：

npm install
npm run check
npm pack

把生成的 tarball 安装进 DSH profile，然后重启 dsh web。不要把源码目录作为 link 安装，因为宿主 peer 依赖由 DSH profile 提供：

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add ./dsh-codex-bridge-0.1.0.tgz
npx @deepseek-ai/dsh@0.1.0-rc.6 web

浏览器端由 /plugins/dsh-codex-bridge/client.js 提供，并显示在会话 pane 中。对运行中的默认 Web profile 验证：

curl -s http://127.0.0.1:3080/plugins/dsh-codex-bridge/client.js | head

更新时先提高 package 版本并重新打包，再移除旧 bundle、添加新 tarball 并重启。卸载命令：

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web remove dsh-codex-bridge

配置

Key	默认	含义
codexPath	codex	codex 可执行文件（绝对路径或 PATH 查找）
defaultSandbox	read-only	codex shell 命令的 sandbox 策略（部署可提高）
defaultTimeoutMs	0	每个 codex 会话的生命周期上限（0 = 不限）
maxParallel	3	并发 codex 进程的全局上限
maxSessionsPerSession	8	每个 dsh session 的活跃 codex 会话上限
maxRetained	16	每个 dsh session 保留的（已 settle）记录数（淘汰最旧）
maxPromptChars	16384	提示词长度上限（超长拒绝）
maxTranscriptChars	16384	记录进事件/投影的 transcript 上限
maxLoopSteps	32	agent loop 有界窗口（记录/投影中保留的步数）
maxLoopBytes	16384	loop 窗口的序列化字节上限（UTF-8；淘汰最旧已完成步）
allowedAgents	roots	谁可调用 call_codex：roots | all
killGraceMs	2000	abort 时 SIGTERM → SIGKILL 宽限

工具

• call_codex — { prompt, mode?: async|block, sandbox?: read-only|workspace-write, model?, timeout_ms?, codex_session_id? }。async 立即返回（并行）；block 等待答案（带 codex_session_id 时等待此前启动的会话）。被取消的阻塞等待会中止该 codex 会话。
• codex_status — 列出当前 session 的 codex 会话（状态、提示词摘要、进度）。
• codex_abort — { codex_session_id }；对进程组 SIGTERM，killGraceMs 后 SIGKILL。
• codex_steer — { codex_session_id, prompt, mode?: async|block, model?, timeout_ms? }。在同一线程上继续已 settle 的父会话（codex exec resume <thread_id>）；新记录经 parent 链接（Codex 标签显示谱系）。宿主重启后的父记录只要带有 codex thread id 也能 steer。

模型体验（UI）

Codex 标签（会话 pane，Chat/Trajectory 之后）：

• 左列 — 当前 dsh session 的每个 codex 会话：状态点、提示词摘要、相对时间。点击选择。
• 右列 — 状态徽标、元信息（id/codexId/cwd/sandbox/model/耗时/退出码/错误）、提示词，以及 Activity | Text 切换：
  • Activity — Agent Loop waterfall：消息、工具行（工具名、running/done/failed、耗时、退出码、truncated 标记；失败自动展开输出）、回合分隔、窗口淘汰时显示「此前 N 步未保留」。
  • Text — 流式 transcript 与最终回答。

状态变化走 session projection 通道（codex/session 事件、codex/sessions 投影），标签页实时更新并可从历史重放恢复（刷新页面不丢）。

已知限制与后续工作

• 一次调用一次运行，之后靠延续。 call_codex 每次启动新的 codex exec；运行中实时 steer（Codex 工作时插话）标准 CLI 不支持——需要实验性的 codex app-server/remote-control daemon 路径。
• loop 窗口是「最近活动」而非审计轨迹。 旧步骤在 maxLoopSteps/maxLoopBytes 下物理淘汰；dsh 会话日志仍保留 whole-value 快照，但标签页只展示保留窗口。
• sandbox 是 Codex 自己的。 defaultSandbox 映射到 codex -s；它约束 Codex shell 命令的触达范围，不是 harness 的 sandbox。不要称之为 harness 安全边界。
• 仅 POSIX 进程组。 abort 使用 detached + 负 pid kill；Windows 移植需要 Job Object / taskkill /T 整树终止。
• telemetry 脱敏只覆盖 dsh 导出。 Codex 自身 telemetry 不在范围内。

开发

npm run check    # typecheck + 测试 + compliance
npm run build    # 宿主（tsc）+ 客户端 bundle（esbuild，__ModuleLoader__ ABI）

客户端 bundle 遵循 harness 的 __ModuleLoader__.load({id, factory}) 协议，以平台模块表为 externals；宿主半遵循 create-dsh-plugin 的 bundle 格式。

License

MIT