跨宿主派发 cRicci5744/dsh-crew

DSH Crew

一个 DeepSeek Harness 插件：从 Claude Code / Codex / Antigravity / Grok 把活儿派给 DSH 智能体，同时不丢掉宿主原生的子代理 UI。
原生进度 UI • 层级策略与升级 • 派发护栏 • 任务看板 • 宿主内 DSH 会话 • 视觉与图像生成（原生优先）• 一键安装

npm：@zseven-w/dsh-crew · 当前插件版本：0.1.0-rc.11 · 已在 DSH 0.1.1-rc.1 上测试

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

DSH Crew 设置页 —— 宿主集成、派发策略、执行与多模态桥接

为什么选 DSH Crew

DSH Crew 是 DeepSeek Harness（DSH）的插件，DSH 是一个开源智能体框架。它让 DSH 智能体可以从 Claude Code、Codex、Antigravity 和 Grok 派发：编排方保留自己的模型，活儿跑在真正的 DSH 智能体上，用上那套框架的工具、沙箱、预设和会话历史，宿主那边照样把它显示成原生子代理，进度实时可见。

干活的是 DSH 智能体，不是裸的模型调用。层级（flash / pro）决定这个智能体能从框架配置好的名册里拿到多少能力 —— 目前是 DeepSeek V4 Flash 和 V4 Pro —— 所以 DSH 里换模型，这边不用动。

🧵 原生进度 UI

在 Claude Code / Codex / Antigravity / Grok 里，干活的智能体就是普通子代理 —— 派发数、当前步骤、工具调用和 token 用量都显示在宿主自己的任务面板里，外加一段 claude-hud 状态栏：⚙dsh 1▶pro 2m14s 21.7k/606 ✓3。

🎚️ 层级策略与升级

flash 用于机械性工作，pro 用于推理，effort 从 off 到 max。tier_policy 能在工具层把每次派发限制到单一层级，escalate_on_failure 则会在 flash 运行失败后改用 pro 重试一次——依据实际证据，而不是事先猜测难度。

🏛️ 宿主内 DSH 会话

在 DSH 配置档中安装该 bundle 后，每个 worker 都是完整的 DSH 会话：在 Web UI 中可见，按工作目录分组，并按你为每个层级选定的 Agent 预设挂载。DSH 未运行时，派发会回退到独立的 DSH 运行时，因此 CI 和无头环境依然可用。

👁️ 视觉与图像生成

DSH 的模型只支持文本。只要有可用的 key，describe_image 就优先使用 DeepSeek 自家的 VL 模型（deepseek-v4-flash-vision-exp），否则回退到你已有的命令行工具——Claude、Codex、Grok、Antigravity——或你配置的任意 OpenAI 兼容 API。generate_image 借用同一批命令行工具的画笔。粘贴的图片在对话中保持可见，并以文本形式送达模型。

🛡️ 派发护栏

每次派发在启动任何进程之前都会先做检查。worker→worker 嵌套的 origin-chain 深度上限为 3，出现环则拒绝；某个工作区已被其他任务占用时，再派第二个 worker 会被拒绝，并附上占用者信息——绝不静默排队。拒绝信息是可读的错误：等待或重新划定范围，不要绕过。

📋 任务面板

DSH Crew 面板同时充当任务面板：每个 worker 任务——运行中或已完成——都会列出层级、effort、实时进度和 token，被占用的工作区显示其占用者，运行中途消失的任务（例如 hub 重启）会以孤儿幽灵的形式呈现，而不是无声消失。

🔌 自定义服务商

自带端点（Base URL + API key + 模型）或本地命令模板。每个服务商都有连通性测试，检查可达性和鉴权，然后发起一次真实的视觉调用，让你现在就发现问题，而不是等到任务中途。

📦 一键安装

设置页会为你安装并更新 Claude Code 插件、Codex 角色文件以及 Antigravity / Grok 的智能体、技能和命令——包括 marketplace 注册、权限允许列表、HUD 接线、为本机渲染的绝对路径——也能同样轻松地还原。每个设置文件都会先备份。

工作原理

Claude Code / Codex / Antigravity / Grok (orchestrator, keeps its own model)
└─ ds-flash / ds-pro ← native subagent shell (progress shows in the host's task UI)
└─ MCP: dsh_run_worker(tier, effort, cwd, worker=)
├─ worker="agy"/"grok" → that external CLI runs the task (explicit opt-in)
├─ hub reachable → session inside DSH (visible in the Web UI, grouped by cwd)
└─ 否则 → dsh-jsonrpc-agent 运行时（worker.cordis.yml） └─ DeepSeek V4 Flash / Pro（DSH SDK，事件流 → 进度与 token 统计）

一次运行，两个视角

Dispatch 会扇出任务。下面，十八个 worker 并行翻译这份 README：宿主把它们算作自己的子代理，而 harness 把它们当作真实会话运行。

Claude Code 把 dsh-crew 的 worker 看作原生子代理，状态栏有一段跟踪运行中的层级、已用时间和 token。

DSH Crew 面板从 harness 一侧看到同一次运行：哪个宿主派发了每个任务、它的层级与 effort、实时进度和 token 用量。

这个面板同时也是任务板：运行中和已完成的任务会一直列出，附带层级、进度和 token；被占用的工作区会标出占用者；中途消失的任务（hub 重启）会以孤儿幽灵的形式出现，而不是悄无声息地消失。

安装

从 npm 安装到 DSH 配置档：

dsh plugin --profile web add @zseven-w/dsh-crew@latest
dsh web

或者，直接从源码树做本地开发：

dsh plugin --profile web add link:/path/to/dsh-crew
dsh web

link: 协议会把配置档依赖软链到这个仓库，所以重新构建后立刻可见。

配置 DeepSeek 凭据（仅限独立模式）

在 hub 模式下——也就是上面的安装方式——worker 运行在 DSH 实例内部，使用它已经配置好的 DeepSeek 凭据。不需要额外设置。

只有独立回退模式才需要自己的密钥：从没有 DSH 实例运行的宿主派发任务时，会以独立进程启动 worker 运行时。从 platform.deepseek.com 获取 API key，写入 ~/.config/dsh-crew/.env：

DEEPSEEK_API_KEY=sk-...

验证

node scripts/smoke.mjs

冒烟测试会通过可用的路径派发一个低成本任务——有 DSH 实例运行时走 hub，否则走独立模式——并打印它用了哪条路径。大约十秒内你应该看到 smoke test passed — configuration OK。失败时会打印原因，并限定在测试过的路径上。

然后打开 Settings → DSH Crew，一键安装宿主集成——Claude Code、Codex、Antigravity、Grok——或者从命令行驱动同一个安装器：

node src/install/cli.mjs claude # Claude Code plugin: marketplace + permissions + HUD segment
node src/install/cli.mjs codex # Codex agents + prompts
node src/install/cli.mjs agy # Antigravity MCP config + agents + skills
node src/install/cli.mjs grok # Grok MCP config + agents + commands
node src/install/cli.mjs all # all four hosts at once

uninstall symmetrically (uninstall-claude | uninstall-codex | uninstall-agy | uninstall-grok):

node src/install/cli.mjs uninstall-claude

背景与术语

- DSH（DeepSeek Harness）：DeepSeek 开源的智能体框架，形态是 Web UI 里的代码智能体，用法类似 Claude Code，但驱动的是 DeepSeek 模型。
- MCP（Model Context Protocol）：Anthropic 的 AI 工具集成协议，让 LLM 能安全调用外部工具和数据源。
- Cordis bundle：DSH 的插件格式。本项目既能作为 MCP 服务独立运行，也能以 hub 模式装进 DSH Web。
- tier：能力档位，决定 worker 拿到 DSH 已配置模型清单里的哪个槽位。flash 快而便宜，适合简单任务；pro 推理更强，适合复杂问题。目前两者分别对应 DeepSeek V4 Flash 和 V4 Pro；在 DSH 里换模型，这里不用改。
- worker：真正干活的 DSH 智能体，是一个完整会话，自带工具、沙箱和预设，不是裸的模型调用。
- effort：推理强度。off 表示不推理，high 表示高推理投入，max 表示最高推理投入。

Claude Code

安装

一键安装，任选其一：

- DSH 设置页（装了 hub 模式才有）：Settings → DSH Crew →「Install to Claude Code」
- 命令行：node src/install/cli.mjs all

两者做的事一样：注册本地 marketplace（就是本仓库，通过 .claude-plugin/marketplace.json）+ claude plugin install + MCP 工具权限白名单 + claude-hud worker 状态段配置（改动前自动备份 settings.json，可重复执行）。安装后重启会话才生效。

用法

- 直接在对话里说「把 X 派给 ds-flash」或「把 X 派给 ds-pro」，子代理就会执行任务
- 派发数量和实时进度显示在 Claude Code 任务 UI 里
- HUD 状态栏段：⚙dsh 1▶pro 2m14s 21.7k/606 ✓3（当前 tier / 已用时间 / token 用量 / 完成数）
- 本地开发时，statusline/statusline.sh 或 statusline/worker-segment.sh 可以单独接入
- 长任务：CC 对 MCP 调用有超时限制（MCP_TOOL_TIMEOUT 可调）。长任务可以让编排方用 dsh_spawn_worker + dsh_worker_result(wait_seconds) 轮询
- 本地开发调试：claude --plugin-dir /path/to/dsh-crew 临时加载

会话命令

这些命令只覆盖当前会话的全局默认值，且在工具层强制执行，不靠提示词约束：

| 命令 | 作用 |
| /dsh-crew:config | 查看或设置本会话默认值：tier=flash\|pro、effort=off\|high\|max、mode=auto\|hub\|standalone、timeout=<seconds>、policy=auto\|flash-only\|pro-only、escalate=true\|false、origin_depth_limit=<1-32>、preset_flash/preset_pro=<preset id|default>、reset |
| /dsh-crew:on · /dsh-crew:off | 打开或关闭本会话的任务派发（关闭是硬开关：工具会直接拒绝） |
| /dsh-crew:status | 查看 worker 任务的实时状态：层级、进度、token、当前工具 |
| /dsh-crew:playbook | 派发最佳实践：如何选 flash 还是 pro、自包含的任务简报、并行、验证结果、护栏 |

Codex

安装

推荐用安装器（自动生成本机路径，并复制 /dsh-config、/dsh-status、/dsh-playbook 提示词）： bash
node src/install/cli.mjs codex

也可以手动复制（复制后需要自己改路径）： bash
cp codex/agents/.toml ~/.codex/agents/ # global or project-level .codex/agents/

角色文件已预置好：

- MCP 服务器挂载配置
- default_tools_approval_mode = "approve"（必填，否则 exec 模式下工具调用会被自动取消）
- tool_timeout_sec = 3600

注意：手动复制时，args 字段里的绝对路径必须改成实际安装位置；安装器会自动处理。

用法

- 在交互式 TUI 里选「spawn ds-pro to ...」派发任务；Active/Done 面板显示进度
- codex exec 模式也可以直接调用 dsh_run_worker

会话命令

为 Codex 安装了三个提示词：

| 命令 | 作用 |
| /dsh-config | 查看或设置本会话的默认值：tier=flash\|pro、effort=off\|high\|max、mode=auto\|hub\|standalone、timeout=<seconds>、policy=auto\|flash-only\|pro-only、escalate=true\|false、origin_depth_limit=<1-32>、preset_flash/preset_pro=<preset id|default>、reset |

| /dsh-status | 查看 worker 任务的实时状态：层级、进度、token、当前工具 |
| /dsh-playbook | 派发最佳实践：如何选 flash 还是 pro、自包含的任务简报、并行、验证结果、护栏 |

Antigravity (agy)

安装 bash
node src/install/cli.mjs agy

在 ~/.gemini/config/mcp_config.json 里注册 dsh-crew MCP 服务器，并把 ds-flash / ds-pro 智能体以及 dsh-config、dsh-status、dsh-playbook 技能安装到 ~/.gemini/config/（所有文件先备份）。安装后重启会话。

用法

- 选 ds-flash 或 ds-pro 作为派发任务的智能体
- dsh_worker_config 读取或覆盖本会话的默认值

会话技能

| 技能 | 作用 |
| /dsh-config | 查看或设置本会话的默认值（tier / effort / mode / timeout / policy / escalation / reset） |
| /dsh-status | 查看 worker 任务的实时状态：层级、进度、token、当前工具 |
| /dsh-playbook | 派发最佳实践：如何选 flash 还是 pro、自包含的任务简报、并行、验证结果、护栏 |

注意事项
- agy 运行 worker 时使用完全批准（--dangerously-skip-permissions + accept-edits）：agy 1.1.16 没有工作区级权限模式，所以无头 worker 必须自动批准工具请求。

卸载：node src/install/cli.mjs uninstall-agy

Grok

安装 bash
node src/install/cli.mjs grok

把 [mcp_servers.dsh-crew] 段写入 ~/.grok/config.toml，并把 ds-flash / ds-pro 智能体以及 /dsh-config、/dsh-status、/dsh-playbook 命令安装到 ~/.grok/（所有文件先备份）。

用法

- 选择 ds-flash 或 ds-pro 作为派发任务的智能体

会话命令

| 命令 | 作用 |
| /dsh-config | 查看或设置本会话的默认值（tier / effort / mode / timeout / policy / escalation / reset） |
| /dsh-status | worker 任务的实时状态：tier、进度、token、当前工具 |
| /dsh-playbook | 派发最佳实践：如何选择 flash 与 pro、自包含的任务简报、并行、验证结果、护栏 |

注意事项

- 出于安全设计，grok 不会在不受信任的项目目录中启动仓库级 MCP 服务器（grok mcp doctor 会报告 "folder untrusted"）；全局安装不受影响——切换目录或传入 --trust。
- grok worker 以 bypassPermissions 运行（始终批准，grok 文档推荐无头自动化这样做）；拒绝规则和钩子仍然生效。

卸载：node src/install/cli.mjs uninstall-grok

MCP 工具

| 工具 | 描述 |
| dsh_run_worker | 阻塞式任务派发（tier：flash/pro，effort：off/high/max，cwd，worker），等待结果 |
| dsh_spawn_worker | 异步派发，返回 job id（用于并行扇出）；用 dsh_worker_result 收集结果 |
| dsh_worker_status | 所有任务的实时进度（turn/step/当前工具/token）+ cwd 咨询锁 |
| dsh_worker_result | 获取结果，可指定 wait_seconds 等待 |
| dsh_worker_cancel | 取消指定任务，终止其运行时进程 |
| dsh_worker_config | 读取/设置会话默认值（tier、effort、mode、timeout、policy、escalation）并列出 worker_profiles |

进度同时镜像到 ~/.config/dsh-crew/status.d/（每个写入者一个分片文件，可由 statusline / 外部监控读取）。

派发护栏

每次派发在启动任何东西之前都会检查——拒绝会以可读错误返回，绝不静默排队：

- 来源链：每次派发都会在 worker→worker 来源链上追加一跳。嵌套深度超过上限（origin_depth_limit，默认 3）会被拒绝，任何循环（同一 backend + cwd 出现两次）也会被拒绝——这道护栏阻止递归的 worker 自我放大。
- cwd 咨询锁：每个工作区同时只允许一个运行中的 worker。向已被占用的工作区再次派发会被拒绝，并返回持有者的 job id、backend 和开始时间——等它结束、用 dsh_worker_cancel 取消它，或传入 allow_concurrent_cwd: true（仅限只读任务）。

派发手册如何高效地*派发任务——flash 与 pro 怎么选、自包含的任务简报怎么写、如何安全并行、如何验证结果，以及上面那些护栏——都打包成按宿主区分的操作手册：/dsh-crew:playbook（Claude Code 技能）、/dsh-playbook（Codex 提示词、Antigravity 技能、Grok 命令）。

显式 CLI 后端

worker="agy" / worker="grok" 把一次派发固定到对应的外部 CLI（后端 × 模型 × 强度），不再走 DSH 的分级逻辑。这是显式选择加入——没有默认值，所以只在用户点名要那个 CLI 时才设置。注意事项：grok 在不受信任的文件夹里会拒绝启动仓库本地的 MCP 服务器；agy 以完全批准模式运行 worker（没有工作区范围的权限模式）。

多模态：视觉与图像生成

DeepSeek 是纯文本模型，不支持图像输入或生成。本插件通过 MCP 工具从外部获取这些能力：

优先走原生视觉：当视觉服务商是内置 CLI（或显式设为 native）时，describe_image 会先尝试 DeepSeek 自家的 VL 模型 deepseek-v4-flash-vision-exp（直接调用 API；密钥取自 DEEPSEEK_API_KEY 或 ~/.config/dsh-crew/.env）。任何失败都会平稳降级到下面的 CLI 服务商链，该链保留为兜底。图像生成不受影响——原生模型只负责看图。

| 工具 | 说明 |
| describe_image | 通过查看图像（截图、设计稿、图表等）来回答问题，结果按服务商 + 模型 + 图像 + 问题缓存 |
| generate_image | 根据文字描述生成图像，保存到指定的绝对路径；输出为扁平位图（图层编辑需要 OpenPencil） |

会话内粘贴图像：在 DSH 中把模型切换到 DeepSeek (vision) ◉ 即可直接粘贴图像。图像留在会话里并正常显示；插件会在图像后追加转写出的文本，并在发送前剥离图像——你看到的是图，模型读到的是文字。转写走同一套原生优先的阶梯：有密钥时用 DeepSeek 的 VL 模型，否则用你配置的 CLI 服务商。

配置

在 DSH 设置页 → DSH Crew → 多模态（或直接编辑 ~/.config/dsh-crew/config.json）：

视觉服务商（看图）：

- native / deepseek-native（DeepSeek 自家的 VL 模型——只要有密钥，每个内置服务商都会自动优先尝试它）
- claude-cod