跨宿主派发 Douglas4958/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 是一个开源智能体框架。有了它，就能从 Claude Code、Codex、Antigravity 和 Grok 派发 DSH 智能体：编排方保留自己的模型，活儿交给真正的 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 配置档里装好插件包后，每个 worker 都是完整的 DSH 会话：在 Web UI 里可见，按工作目录分组，按你为各层级选定的 Agent 预设挂载。DSH 没运行时，派发会回退到独立的 DSH 运行时，所以 CI 和无头环境照样能用。

👁️ 视觉与图像生成

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

🛡️ 派发护栏

每次派发都在启动任何东西之前先做检查。worker→worker 嵌套的源链深度上限为 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。失败时会打印原因，并限定在测试过的那条路径上。

然后打开 设置 → 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 工具集成协议，让大模型能安全调用外部工具和数据源。
- Cordis bundle：DSH 的插件格式。本项目既能作为 MCP 服务独立运行，也能装进 DSH Web，以 hub 模式运行。
- 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（当前档位 / 已用时间 / 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 提示词）：

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/（每个写入者一个分片文件，状态栏 / 外部监控可读取）。

派发护栏

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

- 来源链：每次派发都会在 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