前言¶
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，同时保持会话状态的一致性。
