前言¶
DeepSeek Harness (DSH) 在進程級別只允許掛載一個 AgentFactory。之前的做法要麼全局切換，要麼需要禁用內置循環。這導致在同一個 DSH 實例中運行不同的智能體引擎（如 Claude Code、Codex、Pi）時，要麼無法共存，要麼需要重啓會話。
@vidge/dsh-omniloop 將這個單一的工廠槽位改造成路由器。它掛載多個引擎實例，並按會話分發請求，從而實現在一個 DSH 中運行多個智能體循環。
插件簡介¶
- 插件名：
@vidge/dsh-omniloop - 維護者：vidgewong
- 核心價值：在同一個 DSH 實例中運行 Claude Code、Codex、Pi 或內置循環，按會話選擇引擎，無需重啓即可切換，並共享會話存儲、歷史記錄和追蹤信息。
核心功能¶
- 多引擎並存：支持運行 Claude Code、Codex、Pi 以及 DSH 內置的循環。
- 會話級路由：每個會話可以獨立選擇使用的引擎，引擎選擇記錄在會話創建時。
- 運行時切換：無需重啓 DSH，新建會話即可切換引擎，當前會話保持運行。
- 共享基礎設施：所有引擎共享 DSH 的會話存儲、消息格式、模型路由和追蹤能力。
- 輸出翻譯：將不同引擎的原生輸出翻譯爲 DSH 的標準消息類型，確保歷史記錄和流式傳輸的兼容性。
- 持久化親和性：恢復會話時會自動回到創建該會話時指定的引擎，保持會話來源的一致性。
安裝與配置¶
安裝插件後，必須重啓 dsh web 才能生效。
1. 安裝插件¶
dsh plugin --profile web add @vidge/dsh-omniloop
2. 安裝引擎 SDK（可選）¶
插件本身只提供路由器，不包含具體引擎。根據需要安裝對應 SDK（必須通過 dsh plugin 命令安裝，不能直接 pnpm add）：
# 安裝 Claude Code SDK
dsh plugin --profile web add @anthropic-ai/claude-agent-sdk@0.3.220
# 安裝 Codex SDK
dsh plugin --profile web add @openai/codex@0.149.1
# 安裝 Pi SDK
dsh plugin --profile web add @earendil-works/pi-coding-agent@0.84.3
注意：必須固定 SDK 版本。不同版本間的消息詞彙可能不兼容，版本漂移會導致配置失效。
3. 遷移舊版本¶
如果之前安裝過 @vidge/dsh-agent-hub，需先移除以避免衝突：
dsh plugin --profile web remove @vidge/dsh-agent-hub
dsh plugin --profile web add @vidge/dsh-omniloop
使用方法¶
選擇引擎¶
在 Composer 中開始新會話時，通過下拉菜單選擇引擎。每個會話在其生命週期內固定使用該引擎。
切換引擎¶
要切換引擎，只需在 Composer 中開始一個新的會話。當前正在運行的會話會保持其引擎不變，不受新選擇影響。
默認設置¶
在 DSH 設置的 Loop engine 選項中，可以設置新會話的默認引擎，並控制是否在 Composer 中顯示引擎選擇器。
認證與權限¶
不同引擎的認證方式不同，且權限策略各異：
- Claude Code：憑據從 DSH 的 LLM 配置派生，無需單獨登錄 CLI。
- Codex：需要通過
codex login登錄或設置CODEX_API_KEY環境變量。 - Pi：使用
~/.pi/agent/auth.json文件或環境變量。
引擎特性說明¶
- Codex：沒有交互式的工具批准機制，權限由會話的
sandboxMode和approvalPolicy決定。 - Pi：沒有權限系統，整個子進程通過 DSH 的 subprocess 服務進行沙盒化（默認爲只讀）。
注意事項¶
- SDK 安裝方式：SDK 是可選的 peer 依賴，必須通過
dsh plugin --profile web add安裝到 DSH 運行的 profile 目錄，不能直接使用pnpm add。 - 未安裝 SDK 的影響：如果選擇了未安裝對應 SDK 的引擎，當前回合會失敗，但不會影響其他會話或引擎。
- 持久化：會話的引擎親和性在創建時記錄，恢復時會話將回到記錄的引擎。
結語¶
@vidge/dsh-omniloop 解決了 DSH 單一 AgentFactory 限制帶來的多引擎協作難題。它通過路由器模式，允許開發者靈活地在同一實例中切換 Claude Code、Codex 或 Pi，同時保持會話狀態的一致性。
