前言¶
用 DeepSeek Harness（dsh）做智能體開發時，你可能會遇到這樣的需求：讓會話裏的 agent 找一個外部編碼智能體——比如 OpenAI 的 Codex——要個第二意見，或者並行跑一段編碼任務。手動做這件事，意味着自己 spawn codex 進程、捕獲 JSONL 輸出、輪詢狀態、再把結果接回會話。這些腳手架代碼與主任務無關，卻每次都要寫一遍。
dsh-codex-bridge 要解決的就是這個問題。DSH 的理念是「一切皆插件」，能力以插件形式掛進 harness，這個項目是這一思路下的一個具體實現。下面介紹它是什麼、怎麼裝、提供了哪些工具、有哪些限制。
這是什麼¶
dsh-codex-bridge 是 pandashere 維護的雙面（host + browser）插件，把 Codex CLI 接入 DeepSeek Harness，許可證爲 MIT。雙面的含義是：宿主側向 agent 暴露一組工具，瀏覽器側在 Web 會話窗格里提供可視化。對 agent 而言，Codex 成爲一個可以直接調用的工具；對使用者而言，每次 Codex 會話的完整過程在網頁上可觀測。
核心功能¶
call_codex：把 Codex 當工具調用¶
在 dsh 會話的工作目錄啓動 Codex（底層命令爲 codex -a never exec --json），支持兩種模式：
async：立即返回，多個調用可並行；block：等待最終答案。
參數爲 { prompt, mode?: async|block, sandbox?: read-only|workspace-write, model?, timeout_ms?, codex_session_id? }。
codex_status 與 codex_abort¶
codex_status 列出當前 dsh 會話的 codex 會話，包括狀態、prompt 預覽和進度，適合在 async 啓動後輪詢。
codex_abort 按 codex_session_id 終止 codex 進程組：先發 SIGTERM，超過 killGraceMs（默認 2000ms）再發 SIGKILL。
codex_steer：在同一 thread 上續接¶
codex_steer 用於在同一 thread 上繼續一個已結束（settled）的 Codex 會話，底層是 codex exec resume <thread_id>，新記錄通過 parent 鏈回溯到原會話。參數爲 { codex_session_id, prompt, mode?: async|block, model?, timeout_ms? }。典型用途是在已有會話基礎上追問或調整方向。
Web 端 Codex 標籤頁¶
瀏覽器側在 Web 會話窗格提供 Codex 標籤頁（與 Chat / Trajectory 並列），顯示：狀態、prompt、Agent Loop 瀑布圖（消息、帶命令與參數的工具調用、可摺疊的工具輸出與退出碼、輪次分隔符）、transcript 與最終答案。
狀態通過 session projection 通道即時推送（codex/session 事件、codex/sessions 投影），頁面刷新後可通過歷史回放恢復。瀏覽器端由 /plugins/dsh-codex-bridge/client.js 提供，遵循 __ModuleLoader__.load({id, factory}) 協議。
安裝與啓用¶
運行要求：
- Node.js 22 或更新版本；
@deepseek-ai/dsh@0.1.0-rc.6；- 已認證且可用的 Codex CLI（可執行名
codex，或用codexPath指定路徑）。
插件不讀取也不存儲 API key，認證由 Codex CLI 自持。
先在插件目錄構建打包，生成獨立 bundle：
npm install
npm run check
npm pack
再把生成的 tarball 安裝到 DSH profile，然後啓動 dsh web 並重啓：
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
注意：不支持把源碼目錄以鏈接方式安裝（host peers 由 DSH profile 提供），必須安裝打包後的 tarball 並重啓。
驗證瀏覽器端是否就位（默認 Web profile 跑在本機 3080 端口時）：
curl -s http://127.0.0.1:3080/plugins/dsh-codex-bridge/client.js | head
更新時，用更新的包版本重新打包 tarball，先移除已安裝 bundle，再添加新 tarball 並重啓。卸載命令：
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web remove dsh-codex-bridge
配置項¶
README 給出的配置項及默認值如下：
| 配置項 | 默認值 | 含義 |
|---|---|---|
codexPath |
codex |
codex 可執行文件（絕對路徑或 PATH 查找） |
defaultSandbox |
read-only |
codex 自身 shell 命令的 sandbox 策略（部署可調高） |
defaultTimeoutMs |
0 |
單個 codex 會話的生命週期上限（0 = 不限） |
maxParallel |
3 |
全局併發 codex 進程上限 |
maxSessionsPerSession |
8 |
每個 dsh 會話內活躍 codex 會話上限 |
maxRetained |
16 |
每個 dsh 會話保留的已結束記錄數（淘汰最舊） |
maxPromptChars |
16384 |
prompt 長度上限（超限拒絕） |
maxTranscriptChars |
16384 |
事件/投影中記錄的 transcript 上限 |
maxLoopSteps |
32 |
agent-loop 窗口的步數上限 |
maxLoopBytes |
16384 |
loop 窗口的序列化字節上限（UTF-8，淘汰最舊的已完成步驟） |
allowedAgents |
roots |
誰可調用 call_codex：roots 或 all |
killGraceMs |
2000 |
abort 時 SIGTERM → SIGKILL 的寬限期 |
設計立場與資源限制¶
README 明確了設計立場：這是一個 UX 通道，不是安全邊界。Codex 以調用用戶的權限、在其自身 sandbox 策略下運行——read-only 和 workspace-write 會提供給模型，danger-full-access 僅限部署配置。
模型可見的調用面刻意收得很緊：
- Codex 始終在會話工作目錄運行，絕不使用宿主 cwd（fail closed）；
- 默認僅頂級 agent 可調用（
allowedAgents: roots，可改爲all）； - 通過
maxParallel、maxSessionsPerSession、maxLoopSteps、maxLoopBytes限制資源佔用與寫入放大。
已知限制¶
使用前值得知道的幾條，列自 README：
- 每次調用一次性執行，之後靠
codex_steer續接。標準 CLI 不支持運行中即時插話，那需要實驗性的codex app-server/remote-control路徑。 - loop 窗口是近期活動，不是審計日誌。舊步驟會在
maxLoopSteps/maxLoopBytes下被物理淘汰；dsh 會話日誌仍保留完整快照，但標籤頁只顯示保留窗口。 - sandbox 是 Codex 自己的。
defaultSandbox映射到codex -s，約束的是 Codex 的 shell 命令能碰什麼，不是 harness 的安全邊界。 - 進程組終止僅支持 POSIX。Windows 移植需要 Job Object 或
taskkill /T樹狀終止。 - 遙測脫敏僅覆蓋 dsh 導出，Codex 自身的遙測不在範圍內。
適用場景與注意¶
適合的人羣：在 dsh 上做智能體開發、希望把 Codex 作爲第二意見或並行編碼通道、又不想到處寫進程管理腳手架的開發者。典型用法是用 async 模式啓動並行任務，codex_status 輪詢進度，結束後用 codex_steer 續問，整個過程在 Web 端的 Codex 標籤頁可觀測。
安裝前注意：插件以當前 dsh 進程的權限運行，裝進 profile 前建議先讀一遍源碼，確認許可證（本項目爲 MIT）符合自己的使用場景。
結尾¶
dsh-codex-bridge 把「調用外部編碼智能體」從手工腳手架變成一個受控的工具調用加一個可觀測的標籤頁，接入成本和出錯面都小了不少。項目地址：
- GitHub：https://github.com/pandashere/dsh-codex-bridge
- 社區目錄頁：https://www.skillhub.cn/plugins/pandashere/dsh-codex-bridge（地址來自線索，未做覈實；該目錄爲獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）
