Codex-DSH-Orchestrator

English | 简体中文

Codex-DSH-Orchestrator 是一个以 Codex 为先的编排层和调用方侧 MCP 桥接器，用于与 DeepSeek Harness（DSH）进行有边界的协作。它让 Codex 可以把实现、调研、调试和长日志处理等工作委派给 DSH，然后在不离开正常工作流的前提下观察、继续或取消这些会话。Claude Code 仍通过共享的调用方集成层获得支持；其他调用方被有意暂缓，直到其宿主行为得到验证为止。

本仓库中的共享桥接运行时是上游 dsh-Agentlink 项目 的独立维护衍生版本。该项目保留上游 MIT 许可证和版权归属，与 DeepSeek、OpenAI 或上游维护者无关联，也未获得其认可。

项目边界

Codex-DSH-Orchestrator 是调用方侧的编排和 MCP 桥接项目。它将受支持的调用方连接到独立运行的 DSH Web Host；它不启动、不拥有、也不认证该 Host，并且绝不对 DSH 请求进行自动批准。它不是 DSH Cordis 捆绑包。

Related MCP server: deepseek-harness-mcp

项目组成

• skill/codex-dsh-orchestrator/ — 项目专属的 Codex 编排技能及其 agent 元数据。

• skill/codex-dsh/ — 共享的 Codex 调用方兼容技能。

• skill/claude-code-dsh/ — 保留的 Claude Code 调用方兼容技能。

• src/ — 共享的、调用方无关的 MCP 桥接运行时和设置工具。

• test/ — 本地 mock-host、安全、兼容性和集成测试。

• docs/project-overview.md — 详细的职责与架构图。

dsh-Agentlink 名称保留在运行时标识符和上游归属中，以确保兼容性和法律明确性；它不是该项目的公开名称。

调用方支持

目前，只有标记为 Supported 的调用方在本仓库中存在安装路径。计划中的条目只是方向，并不是发布承诺。

安装

先准备环境：你需要 Node.js 22+、受支持的调用方（Codex 或 Claude Code）以及可用的 DSH CLI。经过测试的跨平台基线是 x64 Node.js 22 和 24；其他 Node.js 主版本和 ARM64 环境不在当前测试矩阵覆盖范围内。在 DSH 中只配置一次你偏好的模型；共享桥接会继承该生效路由，除非某个被委派方明确请求受支持的语义配置文件。

可移植性和安装边界

• 在另一台机器上，请全新 clone。不要只复制单个 worktree 目录：其 .git 文件指向源 clone 的 worktree metadata。同一台机器上请使用 git worktree add 从 source clone 创建 worktree。

• 进行干净、可复现的安装时优先使用 npm ci。仅在你确实想更新 lockfile 时才使用 npm install。

• npm run setup 会把构建后的桥接入口和绝对路径写进调用方配置。请把检出放在稳定的工具目录中。移动它、更换 Node.js 安装或切换到另一个 worktree 后，请重新构建并重新运行 setup，同时审查现有条目，并在明确同意时才能加 --replace。

• Codex MCP setup 与 Codex skill 安装是两回事。npm run setup 会注册 MCP 条目，但不会安装 skill/codex-dsh-orchestrator/。请通过常规的 Codex skill 工作流安装并启用该技能，确保其可被发现，然后才能依赖 $codex-dsh-orchestrator。

• DSH_BRIDGE_HOME 请放在可靠的本地磁盘上。不要把旧的 bridge 主目录传给新机器；在新机器上用一个全新的主目录即可。DSH 会话历史属于 DSH Web Host；桥接任务映射、游标、claim 等不会自动迁移。

• Windows 上的 desktop-auto 是可选加载项。它需要已经运行的 DSH Desktop Host，以及受支持的 Windows 进程/loopback discovery 前置条件；CI 会对这些行为进行 mock，不能证明真实的 Desktop 安装或登录。setup 向导绝不会启动、停止或登录 DSH Desktop。

通过 AI agent 安装

将下面的仓库 URL 和提示词发送给 Codex 或其他编码 agent：

Install Codex-DSH-Orchestrator from https://github.com/Fly2Kiana/Codex-DSH-Orchestrator.
Check Node.js 22+, the DSH CLI, and my DSH Web Host first. Clone it into a location I approve,
run npm ci and npm run check. For Codex, run npm run setup -- --yes, then install and verify
the shipped Codex skill separately through my normal Codex skill workflow. For Claude Code, run
npm run setup:claude -- --yes --project /absolute/path/to/my/project.
For Claude Code, let setup install the project MCP entry and shipped project skill; use --replace and --replace-skill only after reviewing existing files.
If dsh_agentlink or the legacy dsh_collab entry already exists, show me the conflict before using --replace.
Do not start or stop dsh web for me. Tell me when I need to reload the selected caller and approve project MCP trust.

手动安装

1. 检查环境。DSH CLI 0.1.0-rc.6 是当前测试目标。

   node --version
   dsh --version

2. 在自己的终端中启动官方 DSH Web Host。

   dsh web

3. Clone 仓库并安装依赖。

   git clone https://github.com/Fly2Kiana/Codex-DSH-Orchestrator.git
   cd Codex-DSH-Orchestrator
   npm ci

4. 配置调用方。

   对于 Codex：

   npm run setup
   npm run doctor

   在 Windows 上，面对 DSH Desktop 及其动态变化的 loopback 端口时，请显式选择自动发现：

   npm run setup -- --desktop-auto

   Codex wizard 会备份 Codex TOML 配置，并在 MCP 条目中安装 approval_mode = "prompt"；但不会安装 skill/codex-dsh-orchestrator/。请通过你的 Codex skill 工作流安装和启用该技能，然后验证它可被发现。静态 setup 仍要求 dsh --version；而 --desktop-auto 可以在 CLI 不在 PATH 上时改为验证已在运行的 Desktop Host，并将该缺失软件包版本报告为兼容性警告。它绝会启动或停止 DSH Desktop。把既有 bridge 条目切换到任一模式，仍要求先审查再添加 --replace。重启 Codex 后，使用 /mcp 或 Codex Settings 确认 dsh_agentlink 已连接。若要完全手动处理 TOML，请参阅 Manual 配置说明。

   对于 Claude Code 2.1.199 或更新版本，请把 setup 命令指向应共享 .mcp.json 的项目：

   npm run setup:claude -- --project /absolute/path/to/your/project
   cd /absolute/path/to/your/project
   claude mcp get dsh_agentlink

   Claude setup 只修改那个项目的 .mcp.json 和 .claude/skills/claude-code-dsh/SKILL.md，不动其他 server，并会分别报告以下各项：

   • MCP 注册

   • 项目信任

   • Claude skill 状态

   • Claude 审批支持

   • DSH 权限 / 沙箱所有权

   • DSH Host 可达性

   在该项目中打开 Claude Code，用 /mcp 批准待连接的 server；bridge 会把 dsh_resolve_approval 标记为需要人工交互。

   添加 --yes 可使用默认值。若要更新现有 MCP 条目，先审查再加 --replace；若要更新现有 Claude 项目 skill，先审查并添加 --replace-skill；若要自己管理 skill，添加 --no-skill。两个安装器都识别旧的 dsh_collab 条目，并且只在明确替换批准时才把它迁移到 dsh_agentlink。它们都不会启动 DSH、修改 DSH 权限/沙箱设置或重启调用方。

doctor 只读地报告 DSH_BRIDGE_HOME 下 bridge 的 fail-closed lock 位置，并且绝不清理它们，因此即使在锁存在时运行 doctor 也是安全的。

这一源码补丁能停止新的 projection/chunk 洪流带来的协调账本扩张，但不会压缩已有的 5 MB+ 账本。请保留旧 bridge 目录，以利检查；新的委派可使用独立的 DSH_BRIDGE_HOME。DSH 的 session.history 仍是对话的权威来源，而非 bridge 账单。关于保守的恢复边界，请参考 来已知的问题。

该 bridge（运行时名称 dsh_agentlink）是调用方侧插件，不是 DSH Cordis bundle。请勿使用 dsh plugin --profile ... add ... 安装它。

为什么用 Codex-DSH-Orchestrator？

使用 DSH 的工作台能力

DSH 为复杂工作整合了持久会话、工具调用、子 agent 和人工监督。Codex-DSH-Orchestrator 让你当前的主调用方（目前是 Codex 或 Claude Code）能在保持工作流的同时，通过第二 harness 进行讨论与协作。

不仅是又一个原生子 agent

原生子 agent 仍在调用方自己的 agent 树内部。本共享 bridge 增加的是一个独立、由用户配置的 harness：它的会话在 DSH Web 中可见、可使用 DSH 自身的 worker 和模型路由，并能被主调用方观察、继续或取消。

节省时间与成本

• 省时。 把实现、调研、提取和长日志处理交给 DSH 中配置的快速模型（如 DeepSeek V4 路由），同时你的主 agent 继续负责规划和验证。

• 省成本。 将执行密集型 work 转移到成本更低的 DeepSeek 路由，可以降低更昂贵主模型的消耗。

实际速度和成本取决于所选模型、部署、网络和任务。安装后，你还能继续照常在 Codex 或 Claude Code 中工作，并在 DSH 是更合适的执行路径时直接请求委派即可。

使用

当 dsh web 正在运行，且你的调用方已加载并信任 MCP 配置后，你可以用自然语言让 Codex 或 Claude Code，例如：

Use Codex-DSH-Orchestrator to delegate the implementation of this task to DSH. Keep it visible in DSH Web, Report progress, and ask me before any approval.

它则会委派该任务、观察其事件流、继续同一会话、与你协作问答，或取消工作。打开配置好的 DSH Web origin 来查看和操作同一个会话。在 Windows 上，可选的 DSH_HOST_MODE=desktop-auto 运行模式能自行发现 DSH Desktop 已验证的 loopback 监听器，而不是依赖其动态 临时端口；显式的 DSH_HOST_URL 始终优先。

在新委派前，调用方只根据已有的进度和只读工作区证据，在 prompt 中构建一个紧凑的交接说明：目标、已完成工作、Git HEAD/状态和变更路径（若能用、重点的代码/文档路径、相关测试、限制和未解决的问题。它让会读那个焦点路径，除非被阻断否则不进行全仓库扫描。该交接不包含 secrets、原始大 diff、文件正文、调用方对话和内部推理。这是对调用方的指引，不是新增的文件系统授权；dsh-Agentlink 不会自动获得先前的调用方会话状态。对于已知 BridgeTask，调用方使用 dsh_followup；如果没有匹配的已知 task id，它会开启新委派，而不是猜测旧 id。

当用户明确指向现存 DSH Desktop 会话时，调用方可先使用 dsh_find_sessions 读取有限的 root-session metadata，再用 dsh_attach_session 并传它返回的 session id 和新的 metadata 前置条件。标题只是发现的辅助，绝不是附加身份的标识。attach 只接受空闲的 root 会话，会创建或复用 bridge 本地的映射和 worktree claim 状态，也可以为监督而 match 历史，但不会返回或持久化对话主体。它既不会 DSH，也不会创建/重命名 DSH 会话、发送 prompt 或改变模型路由。若工作要继续，后续的 dsh_followup 中会携带紧凑的交接说明。

跨 Codex 任务复用会话是一个保守的三选一：same-known-task、attached-existing-task 或 new-session。只对同一个工作流复用同一个已知 BridgeTask；对于有明确延续证据的新任务，只通过纯元数据的 dsh_find_sessions 发现恰好一个 canonical-cwd、已映射、空闲的根会话，并在继续 dsh_followup 之前以新的前置条件附加。绝不按标题或相似性复用，也绝不为发现而去读取历史；对含糊不清、运行中、过期、缺少 cwd 或映射冲突的候选一律失败关闭。复用可以省去交接和读取仓库的工作，但可能增加输入 token，因此只有在连续性仍然相关时才是一种成本优化。复用和避免了重新扫描并不能证明提供了提示词缓存命中或 token 折扣；除非 DSH 发布文档化的聚合用量遥测，否则不会暴露这些 provider 缓存证据。

MCP 工具

• dsh_host_status — 仅连接层面的 Host 状态与能力

• dsh_find_sessions — 对有界会话做有界、仅元数据的发现；不涉及历史或原始投影

• dsh_attach_session — 使用新的 id/title/cwd/update 前置条件仅附加到一个准确的空闲根会话；不改变提示词或模型

• dsh_delegate — 创建根会话并入队初始提示词；可选用 inherit|flash|pro|modlens-flash|modlens-pro 以及目录支持的 reasoningEffort；默认是分离的（waitSeconds=0）；workspaceMode 是网桥本地声明，而不是 DSH 沙箱选择器

• dsh_followup — 以显式 mode="queue"|"steer"（默认 queue）继续同一根会话；可在提示词之前选择相同的语义模型配置和刚验证的推理强度

• dsh_continue — dsh_followup 的兼容别名

• dsh_status — 可用性、执行、谱系、队列、待处理交互、最终消息、游标及工作区声明的语义

• dsh_tail — 使用桥接任务游标获取有界的事件摘要

• dsh_wait — 最多等待 30 秒，等待一个持久事件、状态变化、待处理交互或终态

• dsh_observe — 围绕 dsh_wait 的兼容别名；桥接游标取代属性会话头部游标

• dsh_cancel — scope="turn"|"queue"

• dsh_list — 任务映射，附有当前派生的状态

• dsh_answer_question — 针对待处理问题 rpcId 的类型化回答

• dsh_resolve_approval — 针对待处理审批 rpcId 的类型化 allow_once|reject 响应

• dsh_release_workspace — 在不关闭 DSH 会话的情况下，显式释放持久的桥接工作区声明

模型路由是显式选择，并且对委派和后续操作都向后兼容。当省略 modelProfile 和 reasoningEffort 时，操作读取 session.models.current，验证 routable，并且不会调用 session.selectModel。语义映射为：flash/pro 对应 flash/pro 的 deepseek-official/deepseek-v4-{flash,pro}，modlens-flash/modlens-pro 对应 deepseek-modlens/deepseek-v4-{flash,pro}。被请求的 provider、model 和 effort 必须存在于实时 session.models 目录中。初始提示词或后续提示词发送前会执行并重新读取该选择；任何不匹配都将失败关闭且不会发送该提示词。

用户的显式选择始终优先。否则，一条主调用路径可保留 inherit（继承），日常搜索/实现/测试修复用 Flash，架构或困难的多步调试用 Pro，而在视觉证据至关重要时使用相应的 ModLens 配置。dsh-Agentlink 只传输文本提示：要包含 DSH Host 和 ModLens 工具可访问的绝对本地图片路径；它不会上传图片字节。selectionReason 提供可选审计说明，不发送给 DSH。

在本地验证过的 DSH rc.6 compact Code Mode 路径上，视觉交接使用外层 run_code 传输，并通过程序内部通过注入的 tools SDK 调用注册的 modlens_read_image。调用方应将其视作预期，禁止 shell/浏览器/OCR/图像库回退，并等待嵌套结果或显式的嵌套/终端错误。插件文档中记载的内层超时不是整个委派的整体截止线。这是版本特定范围的兼容性说明；如果后来版本的 Host 能力有此不同，推迟以它们验证过的实时能力为准。

重要的 DSH rc.6 副作用： session"thread" 也会把该选择保存为 DSH 之后会话的端点。无论何时发生显式选择，委派和后续结果都会报告 modeMapping.persistsAsDshDefault=true 并给出警告。如果不接受这种持久化，请忽略路由字段。如果写入后选择验证失败，则不会发送提示词，但该请求的选择可能已经是全局默认值。

"Dual 启动时 " dsh_wait " does state reading，同时观察持久桥接状态。助理的 delta/chunk 帧以及顶级 session/projection 快照将被跳过，因此它们不会推进任务修订唤醒 waiters；在轮次结束后，完整最终消息仍可通过 status/tail 观察到。

路线图

以下只是一个计划方向，并不是已实现的需求，也不是发布承诺。

1 请求 更多调用方入口 — 待调用方恢复启动时先评估 ZCode，然后再考虑 OpenCode、Work 和 Claude Code MCP 等调用方，并采用相同的 Integration Pack 架构。 2. Agent调用与信息传输 — 改善 prompt 组织、上下文打包、输出摘要和压缩，同时保证提问、审批、错误及最终答案依然可靠。 3. 支持插件的 DSH 的会话 — 保留现有 agentPreset 路径给基于 preset 的插件，加入只读 preset/能力校验和 resolved-preset 上报，只有插件证明需要类型化后安装时才引入声明式会话启动配置。 4. 更多集成 — 在共享 Runtime 和调用方兼容契约稳定后继续扩张。

更多文档

介绍 项目概览 — 公共身份、组件归属与技术架构

• 架构与安全模型 — 身份、状态、恢复、审批、取消与工作区的协调

• 多调用方扩展架构 — Codex、Claude Code 及未来调用方共享的 Runtime 与 Integration Pack 边界

• 推迟的路径 — 有意延迟的工作、激活触发器与保持的安全边界

• 自动化验证 — 一下兼容性和操作厂商验收检查

• 已知问题 — 现有的升级和并发注意事项

• 贡献指南 与 安全说明

许可证

MIT

Alpha 说明：DSH 仍处于开发者预览阶段，此项目是独立于 DeepSeek 和 OpenAI 的社区项目。0.1.0-alpha.1 存在一个共享账本并发 bug；此问题在 0.1.0-alpha.2 修复。在升级或并发运行桥接进程之前，请先阅读已知问题。