跨宿主智能体派发 RaziMoretti/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 的模型只支持文本。只要密钥可用，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 + models）或本地命令模板。每个服务商都有连通性测试，检查可达性和鉴权，然后发起一次真实的视觉调用，让你现在就发现问题，而不是等到任务中途。

📦 一键安装

设置页会为你安装并更新 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 runtime (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 # 一次装齐四个宿主
对称卸载（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=<秒>、policy=auto\|flash-only\|pro-only、escalate=true\|false、origin_depth_limit=<1-32>、preset_flash/preset_pro=<预设 id\|default>、reset |
| /dsh-crew:on · /dsh-crew:off | 打开或关闭本会话的任务派发（off 是硬开关：工具会直接拒绝） |
| /dsh-crew:status | 查看 worker 任务的实时状态：层级、进度、token、当前工具 |
| /dsh-crew:playbook | 派发最佳实践：如何选 flash 还是 pro、自包含的任务简报、并行、验证结果、护栏 |

Codex

安装

推荐用安装器（自动生成本机路径，并复制 /dsh-config、/dsh-status、/dsh-playbook 三个提示词）：

node src/install/cli.mjs codex

也可以手动复制（复制后需要自己改路径）：

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)

安装

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

安装

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