ZSeven-W/dsh-crew

為什麼選擇 DSH Crew

DSH Crew 是 DeepSeek Harness（DSH）開源代理框架的外掛程式。它使 DSH 代理可從 Claude Code、Codex、Antigravity 與 Grok 分派：協調器保留自己的模型，工作在帶有該框架的工具、沙箱、預設和工作階段歷史紀錄的真正 DSH 代理上執行，主機仍然將其顯示為帶有即時進度的原生 subagent。

運行工作的是 DSH 代理，不是裸模型呼叫。Tier（flash / pro）選擇該代理從框架配置名單取得多少能力 — 目前為 DeepSeek V4 Flash 和 V4 Pro — 因此 DSH 中的模型變更不需要此處變更。

🧵 原生進度 UI

Worker 在 Claude Code / Codex / Antigravity / Grok 中顯示為一般 subagent — 分派計數、執行中步驟、工具呼叫和代幣使用都顯示在主機自己的工作面板中，加上 claude-hud 狀態列區段：⚙dsh 1▶pro 2m14s 21.7k/606 ✓3。

🎚️ Tier 策略與升級

flash 用於機械工作，pro 用於推理，effort 從 off 到 max。tier_policy 可在工具層級限制每次分派為一個 tier，escalate_on_failure 會在 flash 執行失敗時重試一次 pro — 基於證據，不是預先猜測難度。

🏛️ 主機內 DSH 工作階段

安裝束進 DSH 設定檔後，每個 worker 都是一級 DSH 工作階段：在 Web UI 中可見，按工作目錄分組，掛載您為每個 tier 選擇的 Agent 預設。不執行 DSH 時，分派會回落到獨立 DSH runtime，因此 CI 和無頭環境仍能工作。

👁️ 視覺與圖片生成

DSH 的模型是純文字。describe_image 現在只要有 key 就優先使用 DeepSeek 自己的視覺模型（deepseek-v4-flash-vision-exp），失敗再回落到您本機已登入的 CLI — Claude、Codex、Grok、Antigravity — 或任何您配置的 OpenAI 相容 API。generate_image 借用同樣這些 CLI 的筆刷。貼上的圖片在對話中保持可見並作為文字到達模型。

🛡️ 分派護欄

每次分派在真正拉起任何東西之前都會先過檢查。worker→worker 巢狀被限制在 origin chain 深度 3，環會被拒絕；workspace 已被執行中的任務持有時，第二個 worker 會被拒絕並附上持有者資訊 — 從不靜默排隊。拒絕是可讀的錯誤：等待或重新界定範圍，而不是繞過。

📋 任務看板

DSH Crew 面板同時是任務看板：每個 worker 任務 — 執行中或已結束 — 都帶著 tier、effort、即時進度與 token 列在板上，被持有的 workspace 會顯示持有者；中途消失的任務（例如 hub 重啟）會作為孤兒 ghost 浮出，而不是無聲消失。

🔌 自訂提供者

帶入您自己的端點（基底 URL + API 金鑰 + 模型）或本機命令範本。每個提供者都有連線測試檢查可達性和驗證，然後進行一次真實視覺呼叫，讓您現在就發現問題，而不是在工作中間。

📦 單鍵安裝

設定頁面為您安裝和更新 Claude Code 外掛程式、Codex 角色檔案以及 Antigravity / Grok 的 agent、skill 和命令 — marketplace 註冊、權限白名單、HUD 接線、為此機器轉譯的絕對路徑 — 也能同樣一鍵還原。每個設定檔都事先備份。

運作原理

Claude Code / Codex / Antigravity / Grok（協調器，保留自己的模型）
  └─ ds-flash / ds-pro  ← 原生 subagent 殼層（進度顯示在主機的工作 UI）
       └─ MCP: dsh_run_worker(tier, effort, cwd, worker=)
            ├─ worker="agy"/"grok" → 由該外部 CLI 執行任務（顯式 opt-in）
            ├─ hub 可達 → DSH 內工作階段（在 Web UI 中可見，按 cwd 分組）
            └─ 其他     → dsh-jsonrpc-agent runtime (worker.cordis.yml)
                 └─ DeepSeek V4 Flash / Pro（DSH SDK，事件流 → 進度和代幣統計）

一次分派，兩個視角

分派是可以鋪開的。下面這次，18 個 worker 並行翻譯這份 README：宿主把它們算作自己的子代理，harness 則把它們當作真實工作階段來跑。

安裝

從 npm 裝進 DSH profile：

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: 協定把 profile 相依軟連結到本儲存庫，改完重新建置即時可見。

設定 DeepSeek 憑證（standalone 模式專用）

在 hub 模式下 — 即上面的安裝方式 — worker 運行在 DSH 實例內部，使用 DSH 實例已設定的 DeepSeek 憑證。無需額外設定。

僅 standalone 回落方案需要自己的 key：從主機分派任務而沒有 DSH 實例運行時，會啟動一個獨立的 worker runtime 程序。從 platform.deepseek.com 取得 API key，寫入 ~/.config/dsh-crew/.env：

DEEPSEEK_API_KEY=sk-...

自我檢查

node scripts/smoke.mjs

smoke 測試會挑一條可用的路徑派一個廉價任務——DSH 實例在跑就走 hub，否則走 standalone——並印出實際用的是哪條。十幾秒內看到 smoke test passed — configuration OK 即設定成功。失敗會印出具體原因，且只針對實際測的那條路徑。

接著開啟 設定 → DSH Crew，一鍵裝好主機整合 — Claude Code、Codex、Antigravity、Grok，或用命令列驅動同一個安裝器：

node src/install/cli.mjs claude   # Claude Code 外掛程式：marketplace + 權限白名單 + HUD 狀態區段
node src/install/cli.mjs codex    # Codex agent + prompt
node src/install/cli.mjs agy      # Antigravity MCP 設定 + agent + skill
node src/install/cli.mjs grok     # Grok MCP 設定 + agent + 命令
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 束：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 模式已安裝時）：設定 → DSH Crew → "安裝到 Claude Code"
• 命令列：node src/install/cli.mjs all

兩者做同樣的事：註冊本機 marketplace（父目錄 dsh-plugins/ 作為 marketplace 根目錄）+ claude plugin install + MCP 工具權限白名單 + claude-hud worker 狀態區段設定（自動備份 settings.json 後再變更，冪等性）。安裝後重新啟動工作階段以令變更生效。

使用方式

• 直接在對話中說「分派 X 到 ds-flash」或「分派 X 到 ds-pro」，subagent 執行工作
• 分派計數和即時進度顯示在 Claude Code 工作 UI 中
• HUD 狀態列區段：⚙dsh 1▶pro 2m14s 21.7k/606 ✓3（目前 tier / 經過時間 / 代幣使用 / 完成計數）
  • 本機開發時，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=<preset id
/dsh-crew:on · /dsh-crew:off	開關本階段的分派（關閉是硬開關，工具層直接拒絕）
/dsh-crew:status	worker 任務即時狀態：tier、進度、tokens、目前工具
/dsh-crew:playbook	分派最佳實踐：flash vs pro 選擇、自包含任務簡報、平行、結果驗證、護欄

Codex

安裝

建議使用安裝程式（自動為此機器轉譯路徑，複製 /dsh-config、/dsh-status、/dsh-playbook prompt）：

node src/install/cli.mjs codex

或手動複製（複製後需要手動修改路徑）：

cp codex/agents/*.toml ~/.codex/agents/    # 全域或專案級 .codex/agents/

角色檔案預先設定了：

• MCP 伺服器掛載設定
• default_tools_approval_mode = "approve"（必要，否則工具呼叫在 exec 模式自動取消）
• tool_timeout_sec = 3600

注意：手動複製時，args 欄位中的絕對路徑必須更新以符合實際安裝位置；安裝程式會自動處理此項。

使用方式

• 在互動式 TUI 中，選擇「生成 ds-pro 到...」以分派工作；Active/Done 面板顯示進度
• codex exec 模式也可直接呼叫 dsh_run_worker

工作階段命令

Codex 端裝的是三條 prompt：

命令	作用
/dsh-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=<preset id
/dsh-status	worker 任務即時狀態：tier、進度、tokens、目前工具
/dsh-playbook	分派最佳實踐：flash vs pro 選擇、自包含任務簡報、平行、結果驗證、護欄

Antigravity (agy)

安裝

node src/install/cli.mjs agy

把 dsh-crew MCP server 註冊進 ~/.gemini/config/mcp_config.json，並把 ds-flash / ds-pro agent 與 dsh-config、dsh-status、dsh-playbook skill 裝進 ~/.gemini/config/（變更前自動備份）。安裝後重新啟動工作階段生效。

使用方式

• 選 ds-flash 或 ds-pro 作為 agent 來分派任務
• dsh_worker_config 讀取或覆寫本階段預設值

工作階段 skill

Skill	作用
/dsh-config	檢視或設定本階段預設值（tier / effort / mode / timeout / policy / escalation / reset）
/dsh-status	worker 任務即時狀態：tier、進度、tokens、目前工具
/dsh-playbook	分派最佳實踐：flash vs pro 選擇、自包含任務簡報、平行、結果驗證、護欄

注意事項

• agy 以 full approval 跑 worker（--dangerously-skip-permissions + accept-edits）：agy 1.1.16 沒有 workspace 級別的權限模式，headless 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 agent 與 /dsh-config、/dsh-status、/dsh-playbook 命令裝進 ~/.grok/（變更前自動備份）。

使用方式

• 選 ds-flash 或 ds-pro 作為 agent 來分派任務

工作階段命令

命令	作用
/dsh-config	檢視或設定本階段預設值（tier / effort / mode / timeout / policy / escalation / reset）
/dsh-status	worker 任務即時狀態：tier、進度、tokens、目前工具
/dsh-playbook	分派最佳實踐：flash vs pro 選擇、自包含任務簡報、平行、結果驗證、護欄

注意事項

• 出於安全設計，grok 不會在未信任的專案目錄裡啟動 repo 級 MCP server（grok mcp doctor 會報 "folder untrusted"）；全域安裝不受影響 — 換目錄或加 --trust。
• grok worker 以 bypassPermissions（always-approve）執行，是 grok 文件推薦的 headless 自動化方式；deny 規則與 hooks 依然生效。

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

MCP 工具

工具	說明
dsh_run_worker	同步工作分派（tier: flash/pro，effort: off/high/max，cwd，worker），等待結果
dsh_spawn_worker	非同步工作分派，返回工作 id（用於平行分散）；用 dsh_worker_result 收集結果
dsh_worker_status	查詢所有工作的即時進度（turn/step/目前工具/代幣）+ cwd 建議鎖
dsh_worker_result	取得結果，可指定 wait_seconds 等待
dsh_worker_cancel	取消指定工作，終止其 runtime 程序
dsh_worker_config	檢視/設定本階段預設值（tier、effort、mode、timeout、policy、escalation），並列出 worker_profiles

進度同時複製到 ~/.config/dsh-crew/status.d/（每個寫入者一個分片檔案，可由 statusline / 外部監控讀取）。

分派護欄

每次分派在真正拉起任何東西之前都會先過檢查 — 拒絕是可讀的錯誤，從不靜默排隊：

• Origin chain：每次分派都會往 worker→worker origin chain 上追加一跳。巢狀超過上限（origin_depth_limit，預設 3）會被拒絕；環（同一個 backend + cwd 在鏈上出現兩次）也會被拒絕 — 這是阻止 worker 遞迴自我放大的護欄。
• cwd 建議鎖：一個 workspace 同時只允許一個執行中的 worker。第二個分派會帶著持有者的工作 id、backend 與開始時間被拒絕 — 等它結束、用 dsh_worker_cancel 取消它，或傳 allow_concurrent_cwd: true（僅限唯讀任務）。

分派手冊（playbook）

如何把工作分派得好 — flash vs pro、自包含任務簡報、安全平行、結果驗證，以及上面的護欄 — 隨包按主機分發：/dsh-crew:playbook（Claude Code skill）、/dsh-playbook（Codex prompt、Antigravity skill、Grok 命令）。

顯式 CLI 後端

worker="agy" / worker="grok" 把一次分派固定到該外部 CLI（backend × model × effort），取代 DSH 的 tier 邏輯。它是顯式 opt-in — 沒有預設值，只有使用者點名要那個 CLI 時才設定。注意事項：grok 拒絕在未信任目錄裡啟動 repo 級 MCP server；agy 以 full approval 跑 worker（沒有 workspace 級別的權限模式）。

多模態：視覺與圖片生成

DeepSeek 是純文字模型，不支援圖片輸入或生成。此外掛程式透過 MCP 工具從外部取得這些功能：

原生視覺優先：當視覺 provider 是內建 CLI（或顯式 native）時，describe_image 會先試 DeepSeek 自己的視覺模型 deepseek-v4-flash-vision-exp（直接 API 呼叫；key 來自 DEEPSEEK_API_KEY 或 ~/.config/dsh-crew/.env）。任何失敗都會優雅回落到下面的 CLI provider 鏈，這條鏈原樣保留作為兜底。圖片生成不受影響 — 原生模型只看圖。

工具	說明
describe_image	透過查看圖片回答問題（螢幕截圖、設計、圖表等），結果由提供者 + 模型 + 圖片 + 問題快取
generate_image	從文字描述生成圖片，儲存到指定絕對路徑；輸出是平面點陣圖（需要 OpenPencil 進行圖層編輯）

工作階段圖片貼上：在 DSH 中，切換模型到 DeepSeek (vision) ◉ 以直接貼上圖片。圖片保留在工作階段中並正常顯示；外掛程式在其後附加轉錄文字並在傳送前移除圖片 — 你看到圖片，模型讀取文字。轉錄走同一條原生優先階梯：有 key 用 DeepSeek 視覺模型，否則用您配置的 CLI provider。

設定

在 DSH 設定頁面 → DSH Crew → Multimodal（或直接編輯 ~/.config/dsh-crew/config.json）：

視覺提供者（圖片查看）：

• native / deepseek-native（DeepSeek 自己的視覺模型 — 只要有 key，每個內建 provider 都會自動先試它）
• claude-code（預設，使用 haiku，便宜）
• codex（使用 GPT，可指定特定模型）
• grok（使用 Grok）
• agy（Antigravity）
• custom（OpenAI 相容 API 或本機命令）
• off（停用）

圖片生成提供者（圖片生成）：

• codex（$imagegen，gpt-image-2）
• agy（Nano Banana）
• grok（Imagine）
• custom（OpenAI 相容 API 或本機命令）
• off（停用）

自訂提供者

兩種整合方法：

API：任何 OpenAI 相容的端點

• 填入基底 URL、API 金鑰、模型列表
• 視覺使用 /chat/completions 搭配內聯 base64 圖片
• 圖片生成使用 /images/generations
• 必須指定「圖片生成模型」才能具有生成能力，否則提供者只會出現在視覺選擇中

CLI：本機命令範本，預留位置替換為安全參照

• 視覺：{image} {question} {model} → stdout 作為答案
• 圖片生成：{prompt} {output} {size} → 命令必須將檔案寫入 {output}
• 至少填寫一個命令；無論填入哪個都決定能力

連線測試：每個自訂提供者都有測試按鈕

• API：檢查端點可達性、驗證，傳送真實視覺要求以驗證
• CLI：檢查可執行檔案，執行真實命令以驗證
• 圖片生成：僅驗證設定，無實際圖片輸出

借用的訂閱 CLI（claude / codex / grok / agy）要求您在本機登入；外掛程式不會為您繞過其權限。

Hub 模式

此套件也是有效的 DSH 束（dsh.bundle + cordis.patch.yml）。使用 dsh plugin add dsh-crew 安裝進 DSH Web 設定檔後：

• Worker 工作階段成為一級公民：在 DSH 主機中作為一級工作階段執行（agents.create + 每工作階段模型/effort 瀑布 + 預設預設），出現在 Web UI 工作階段列表中，可隨時開啟以檢視完整執行
• 按工作目錄組織：在 Web UI 中按 cwd 管理 worker 工作階段
• Loopback API：
  • POST/GET /_dsh/dsh-crew/jobs：生成工作、列出、長時間輪詢結果、取消
  • GET /_dsh/dsh-crew/ping：健康檢查（MCP shim 使用此來檢測 hub 是否執行）
  • POST /_dsh/dsh-crew/install：單鍵安裝主機整合 — Claude Code / Codex / Antigravity / Grok（src/install/ 的後端）
• 自動偵測：各主機的 MCP shim 自動偵測 hub（DSHPLUGIN_CREW_HUB 環境變數，預設 http://127.0.0.1:3080）
  • DSH Web 執行中 → 工作進入 hub 模式（mode: "hub"）
  • 未執行 → 回落到獨立 runtime

方案選擇與限制

一般訂閱者 → shell subagent 方法（推薦）

• 目前狀態：Claude Code subagent 殼層使用 haiku 作為中介；每次分派增加數百到數千個代幣
• 權衡：使用少量 Anthropic 代幣以換取原生工作 UI、即時進度顯示、無額外設定
• 建議：如果您已訂閱 Claude Pro 或使用 Claude Code，使用此方法 — 方便且透明

隨用隨付 / CI 環境 → 直接路由器方法

• 目前狀態：Claude Code subagent 前置訊息不支援直接第三方模型連線；此儲存庫在 scratchpad 中的路由器實驗需要 Claude Code 的 API 金鑰認證，但訂閱 OAuth 被 Anthropic 上游以 403 阻擋
• 建議：
  • 如果使用 API 金鑰認證（非 OAuth）並希望節省 Anthropic 代幣，可以執行本機路由器以進行直接 DeepSeek 連線
  • CI 環境通常也使用 API 金鑰；此方法更經濟（全部 DeepSeek 代幣）
  • 需要自行測試路由器整合（不受官方支援）

執行 DSH Web → hub 模式自動啟用

• 目前狀態：如果 dsh plugin add dsh-crew 已安裝到 DSH Web 設定檔，工作在主機中作為一級工作階段執行，出現在 Web UI 工作階段列表中
• 建議：在本機開發反覆過程中，建議啟用 hub 模式；worker 進度可在 Web UI 中完全觀察；對於跨機器協作或無 Web UI 的環境，使用分派主機的 shell 方法

已知項目

• Codex 角色理論上可以嘗試 model_provider 直接指向 DeepSeek（未驗證）；此橋接不依賴它
• 圖片生成輸出是平面點陣圖；圖層編輯需要 OpenPencil
• Runtime 依賴項：僅 @modelcontextprotocol/sdk 和 zod；@deepseek-ai/* 是宿主執行階段元件（由 DSH 主機提供；一般 npm 安裝不會拉取它們）
• Codex 必須設定：default_tools_approval_mode = "approve"，否則工具呼叫自動取消

開發

pnpm install
node_modules/.bin/tsdown src/client/index.tsx --format cjs --platform browser \
  --target es2022 --tsconfig tsconfig.client.json --out-dir .client-build --clean
node scripts/build-client.mjs   # 為 DSH 模組載入器包裝束
node scripts/smoke.mjs          # 分派一個真實的 flash 工作端到端

Runtime 依賴項僅有 @modelcontextprotocol/sdk 和 zod；每個 @deepseek-ai/* 套件都是由 DSH 主機提供的 peer 依賴項，這樣外掛程式就保持在主機的單一模組領域內。

生態系

• DSH Android — 在對話中執行 Android 模擬器或 USB 實機，全部由 adb 驅動
• DSH iOS — 在對話中執行 iOS 模擬器與 USB 連接的實機
• DSH Noema — DSH 的長期記憶
• DSH OpenPencil — 在對話中檢查和編輯 .op 設計文件

授權

MIT