@ran-sh/dsh-crew 0.3.0

package/README.zh-TW.md

@@ -0,0 +1,359 @@
+<p align="center">
+  <img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
+</p>
+
+<h1 align="center">DSH Crew</h1>
+
+<p align="center">
+  <strong>一個 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 外掛程式：從 Claude Code / Codex 分派工作給 DSH 代理，而不放棄主機的原生 subagent UI。</strong><br />
+  <sub>原生進度 UI • Tier 策略與升級 • 主機內 DSH 工作階段 • 視覺與圖片生成 • 單鍵安裝</sub>
+</p>
+
+<p align="center">
+  <sub>GitHub: <code>Ran-sh/dsh-crew</code> • 目前外掛程式版本: <code>0.1.0-rc.1</code> • 測試版本 DSH <code>0.1.0-rc.6</code></sub>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> &middot; <a href="./README.zh.md">简体中文</a> &middot; <a href="./README.zh-TW.md"><b>繁體中文</b></a> &middot; <a href="./README.ja.md">日本語</a> &middot; <a href="./README.ko.md">한국어</a> &middot; <a href="./README.fr.md">Français</a> &middot; <a href="./README.es.md">Español</a> &middot; <a href="./README.de.md">Deutsch</a> &middot; <a href="./README.pt.md">Português</a> &middot; <a href="./README.ru.md">Русский</a> &middot; <a href="./README.hi.md">हिन्दी</a> &middot; <a href="./README.tr.md">Türkçe</a> &middot; <a href="./README.th.md">ไทย</a> &middot; <a href="./README.vi.md">Tiếng Việt</a> &middot; <a href="./README.id.md">Bahasa Indonesia</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Ran-sh/dsh-crew/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ran-sh/dsh-crew?color=64748b" alt="License" /></a>
+</p>
+
+<br />
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-overview.png" alt="DSH Crew — settings page" width="100%" />
+</p>
+<p align="center"><sub>DSH Crew 設定頁面 — 主機整合、分派策略、執行與多模態橋接</sub></p>
+
+## 為什麼選擇 DSH Crew
+
+DSH Crew 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）開源代理框架的外掛程式。它使 DSH 代理可從 Claude Code 和 Codex 分派：協調器保留自己的模型，工作在帶有該框架的工具、沙箱、預設和工作階段歷史紀錄的真正 DSH 代理上執行，主機仍然將其顯示為帶有即時進度的原生 subagent。
+
+運行工作的是 DSH 代理，不是裸模型呼叫。Tier（`flash` / `pro`）選擇該代理從框架配置名單取得多少能力 — 目前為 DeepSeek V4 Flash 和 V4 Pro — 因此 DSH 中的模型變更不需要此處變更。
+
+<table>
+<tr>
+<td width="50%">
+
+### 🧵 原生進度 UI
+
+Worker 在 Claude Code / Codex 中顯示為一般 subagent — 分派計數、執行中步驟、工具呼叫和代幣使用都顯示在主機自己的工作面板中，加上 claude-hud 狀態列區段：`⚙dsh 1▶pro 2m14s 21.7k/606 ✓3`。
+
+</td>
+<td width="50%">
+
+### 🎚️ Tier 策略與升級
+
+`flash` 用於機械工作，`pro` 用於推理，`effort` 從 `off` 到 `max`。`tier_policy` 可在工具層級限制每次分派為一個 tier，`escalate_on_failure` 會在 flash 執行失敗時重試一次 pro — 基於證據，不是預先猜測難度。
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🏛️ 主機內 DSH 工作階段
+
+安裝束進 DSH 設定檔後，每個 worker 都是一級 DSH 工作階段：在 Web UI 中可見，按工作目錄分組，掛載您為每個 tier 選擇的 Agent 預設。不執行 DSH 時，分派會回落到獨立 DSH runtime，因此 CI 和無頭環境仍能工作。
+
+</td>
+<td width="50%">
+
+### 👁️ 視覺與圖片生成
+
+DSH 的模型是純文字。`describe_image` 和 `generate_image` 借用您已有的 CLI 的眼睛和筆刷 — Claude、Codex、Grok、Antigravity — 或任何您配置的 OpenAI 相容 API。貼上的圖片在對話中保持可見並作為文字到達模型。
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🔌 自訂提供者
+
+帶入您自己的端點（基底 URL + API 金鑰 + 模型）或本機命令範本。每個提供者都有連線測試檢查可達性和驗證，然後進行一次真實視覺呼叫，讓您現在就發現問題，而不是在工作中間。
+
+</td>
+<td width="50%">
+
+### 📦 單鍵安裝
+
+設定頁面為您安裝和更新 Claude Code 外掛程式以及 Codex 角色檔案 — marketplace 註冊、權限白名單、HUD 接線、為此機器轉譯的絕對路徑 — 也能輕鬆還原。每個設定檔都事先備份。
+
+</td>
+</tr>
+</table>
+
+## 運作原理
+
+```
+Claude Code / Codex（協調器，保留自己的模型）
+  └─ ds-flash / ds-pro  ← 原生 subagent 殼層（進度顯示在主機的工作 UI）
+       └─ MCP: dsh_run_worker(tier, effort, cwd)
+            ├─ hub 可達 → DSH 內工作階段（在 Web UI 中可見，按 cwd 分組）
+            └─ 其他     → dsh-jsonrpc-agent runtime (worker.cordis.yml)
+                 └─ DeepSeek V4 Flash / Pro（DSH SDK，事件流 → 進度和代幣統計）
+```
+
+## 一次分派，兩個視角
+
+分派是可以鋪開的。下面這次，18 個 worker 並行翻譯這份 README：宿主把它們算作自己的子代理，harness 則把它們當作真實工作階段來跑。
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-host.png" alt="Claude Code" width="100%" />
+</p>
+<p align="center"><sub>Claude Code 裡，dsh-crew worker 就是原生子代理；狀態列區段即時顯示執行中的 tier、耗時與 token。</sub></p>
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-jobs.png" alt="DSH Crew" width="100%" />
+</p>
+<p align="center"><sub>DSH Crew 面板從 harness 一側看同一次執行：每個任務由哪個宿主分派、tier 與 effort、即時進度與 token 用量。</sub></p>
+
+## 安裝
+
+從 GitHub 裝進 DSH profile：
+
+```bash
+node scripts/setup.mjs install   # Safe install: see the canonical Install section of README.md (dedicated Crew home/profile; official web profile is never modified).
+Repository source: github:Ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh web
+```
+
+或者從原始碼樹本機開發：
+
+```bash
+node scripts/setup.mjs install   # Safe install: see the canonical Install section of README.md (dedicated Crew home/profile; official web profile is never modified).
+Repository source: github:Ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh web
+```
+
+`link:` 協定把 profile 相依軟連結到本儲存庫，改完重新建置即時可見。
+
+### 設定 DeepSeek 憑證（standalone 模式專用）
+
+在 hub 模式下 — 即上面的安裝方式 — worker 運行在 DSH 實例內部，使用 DSH 實例已設定的 DeepSeek 憑證。無需額外設定。
+
+僅 standalone 回落方案需要自己的 key：從 Claude Code / Codex 分派任務而沒有 DSH 實例運行時，會啟動一個獨立的 worker runtime 程序。從 [platform.deepseek.com](https://platform.deepseek.com) 取得 API key，寫入 `~/.config/dsh-crew/.env`：
+
+```
+DEEPSEEK_API_KEY=sk-...
+```
+
+### 自我檢查
+
+```bash
+node scripts/smoke.mjs
+```
+
+smoke 測試會挑一條可用的路徑派一個廉價任務——DSH 實例在跑就走 hub，否則走 standalone——並印出實際用的是哪條。十幾秒內看到 `smoke test passed — configuration OK` 即設定成功。失敗會印出具體原因，且只針對實際測的那條路徑。
+
+接著開啟 設定 → DSH Crew，一鍵裝好 Claude Code / Codex 整合。
+
+## 背景與術語
+
+- **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`、`reset` |
+| `/dsh-crew:on` · `/dsh-crew:off` | 開關本階段的分派（關閉是硬開關，工具層直接拒絕） |
+| `/dsh-crew:status` | worker 任務即時狀態：tier、進度、tokens、目前工具 |
+
+## Codex
+
+### 安裝
+
+建議使用安裝程式（自動為此機器轉譯路徑，複製 `/dsh-config`、`/dsh-status` 命令）：
+
+```bash
+node src/install/cli.mjs codex
+```
+
+或手動複製（複製後需要手動修改路徑）：
+
+```bash
+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`、`reset` |
+| `/dsh-status` | worker 任務即時狀態：tier、進度、tokens、目前工具 |
+
+## MCP 工具
+
+| 工具 | 說明 |
+|---|---|
+| `dsh_run_worker` | 同步工作分派（`tier`: flash/pro，`effort`: off/high/max，`cwd`），等待結果 |
+| `dsh_spawn_worker` | 非同步工作分派，返回工作 id（用於平行分散） |
+| `dsh_worker_status` | 查詢所有工作的即時進度（turn/step/目前工具/代幣） |
+| `dsh_worker_result` | 取得結果，可指定 `wait_seconds` 等待 |
+| `dsh_worker_cancel` | 取消指定工作，終止其 runtime 程序 |
+
+進度同時複製到 `~/.config/dsh-crew/status.d/`（每個寫入者一個分片檔案，可由 statusline / 外部監控讀取）。
+
+## 多模態：視覺與圖片生成
+
+**DeepSeek 是純文字模型**，不支援圖片輸入或生成。此外掛程式透過 MCP 工具從外部取得這些功能：
+
+| 工具 | 說明 |
+|---|---|
+| `describe_image` | 透過查看圖片回答問題（螢幕截圖、設計、圖表等），結果由提供者 + 模型 + 圖片 + 問題快取 |
+| `generate_image` | 從文字描述生成圖片，儲存到指定絕對路徑；輸出是平面點陣圖（需要 OpenPencil 進行圖層編輯） |
+
+**工作階段圖片貼上**：在 DSH 中，切換模型到 `DeepSeek (vision) ◉` 以直接貼上圖片。圖片保留在工作階段中並正常顯示；外掛程式在其後附加轉錄文字並在傳送前移除圖片 — 你看到圖片，模型讀取文字。
+
+### 設定
+
+在 **DSH 設定頁面 → DSH Crew → Multimodal**（或直接編輯 `~/.config/dsh-crew/config.json`）：
+
+**視覺提供者**（圖片查看）：
+
+- `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 整合（`src/install/` 的後端）
+- **自動偵測**：CC/Codex 的 MCP shim 自動偵測 hub（`DSH_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 的環境，使用 Claude Code / Codex shell 方法
+
+### 已知項目
+
+- Codex 角色理論上可以嘗試 `model_provider` 直接指向 DeepSeek（未驗證）；此橋接不依賴它
+- 圖片生成輸出是平面點陣圖；圖層編輯需要 OpenPencil
+- **Runtime 依賴項**：僅 `@modelcontextprotocol/sdk` 和 `zod`；`@deepseek-ai/*` 是 peerDependencies（由 DSH 主機提供）
+- **Codex 必須設定**：`default_tools_approval_mode = "approve"`，否則工具呼叫自動取消
+
+## 開發
+
+```bash
+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 Noema](https://github.com/ZSeven-W/dsh-noema) — DSH 的長期記憶
+- [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — 在對話中檢查和編輯 `.op` 設計文件
+
+## 授權
+
+MIT

package/README.zh.md

@@ -0,0 +1,305 @@
+<p align="center">
+  <img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
+</p>
+
+<h1 align="center">DSH Crew</h1>
+
+<p align="center">
+  <strong>让 Codex Desktop / Claude Code 负责统筹，把编码任务交给 DeepSeek Harness 中的 worker 角色（另有独立的 reviewer 角色），由可配置的 Worker Model Policy 决定用哪个模型。</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh.md"><b>简体中文</b></a>
+</p>
+
+## 功能
+
+- Codex Desktop / Claude Code 作为主统筹 Agent
+- **角色（Role）**：worker（实现 / 修复 / 测试 / 搜索）与 reviewer（独立审查 + 结论）
+- **模型策略（Model Policy）**：每个角色独立解析有序 provider/model 候选（首选 → 优先级 → 升级 → Harness Default）
+- 旧版 Flash Only · Pro Only · Balanced · Review Pipeline 自动迁移到角色模型
+- Follow DSH Provider
+- DSH Hub 一等公民会话（Web UI 可见、异步任务带进度）
+- 可选的视觉 / 生图（独立开关）
+
+## 工作方式
+
+```
+Codex Desktop / Claude Code
+          │
+          ▼
+       dsh-crew
+          │
+     Workflow（run 与 spawn 共用同一套状态机）
+          │
+     ┌────┴────┐
+     │         │
+   worker    reviewer
+     │         │
+  Model Policy  │  （各角色独立解析 provider/model；
+  cheap→strong  │   升级基于证据：FAIL 测试、缺失交付、阻塞任务）
+     │          │
+     └────┬────┘
+          │
+          ▼
+   DeepSeek Harness
+          │
+          ▼
+   DSH 当前选择的 provider/model
+```
+
+主 Agent 决定**做什么**并负责接受 / 拒绝 / 要求修改；Workflow 决定**何时 / 状态**；
+**角色**决定**谁来做**（worker 执行、reviewer 审查）；**模型策略**决定**用哪个模型**
+（永不与角色绑定）；工作区隔离决定**在哪里做**（每个 coding worker 跑在独立临时
+git worktree，并行 worker 不会互相踩 working tree）；验证 / reviewer 决定**是否接受**。
+
+## 安装
+
+前置条件：带 npm/npx 的 Node.js、Git 和 pnpm。
+
+> **官方 Harness 隔离** — dsh-crew 安装到它自己的专用 DSH home
+> （`~/.config/dsh-crew/harness`）和专用 profile（`dsh-crew`），永远不会安装
+> 到官方 DSH home（`~/.dsh`）或官方 `web` profile。你的正常 DeepSeek Harness
+> 安装不会被修改。
+
+从本仓库克隆后，跨平台安装：
+
+```bash
+node scripts/setup.mjs install
+```
+
+Windows：
+
+```bat
+install.cmd
+```
+
+然后打开 **设置 → DSH Crew**，在 Codex 一行点击 **安装**。Claude Code 集成是可选项，有独立的安装按钮。
+
+安装器会把本检出以 `@ran-sh/dsh-crew` 方式链接到专用 `dsh-crew` profile，并把 Crew Hub 指向自己的端口；不会改动官方 web profile 或任何官方凭据存储。本 fork 不发布到 npm registry。
+
+### 更新
+
+重新执行源码安装器：
+
+```bash
+git pull
+node scripts/setup.mjs install
+```
+
+更新后重启 DSH。
+
+### 迁移旧版 fork 安装
+
+旧版发布把 Crew 安装进官方 DSH `web` profile，这些安装不在受支持路径内。请先用源码卸载器卸载旧版 Crew（见“卸载”），再执行上述源码安装器，它会安装到专用 Crew home/profile。
+
+### 旧版 web-profile 命令（不支持 — 仅作参考）
+
+旧版发布和工具曾使用直接 `--profile web` 命令把 Crew 安装进官方 DSH `web` profile。这些命令**不受支持**，不得用于新的安装、更新或卸载 — 受支持的 Crew 工具绝不会修改官方 web profile：
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add github:Ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh plugin --profile web remove @ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh plugin --profile web remove @zseven-w/dsh-crew
+```
+
+`ZSeven-W/dsh-crew` 是上游项目标识；本 fork 是 `Ran-sh/dsh-crew`。请改用源码安装/卸载器（`node scripts/setup.mjs install|uninstall`）。
+
+### 从 Flash / Pro 迁移（v0.1 → v0.2 角色）
+
+v0.2 保留所有旧配置字段继续生效。`collaboration_mode`、`tier_policy`、
+`flash_state` / `pro_state`、`flash_model_priority` / `pro_model_priority`、
+`escalate_on_failure`、`pro_reviews_flash` 都会被读取，迁移逻辑集中重建角色模型：
+
+- `flash-only` → worker auto、reviewer disabled、`economy` 策略。
+- `pro-only` → worker auto（强模型类）、reviewer disabled。
+- `balanced` → worker auto、reviewer manual（点名时可用）。
+- `review-pipeline` → worker auto + reviewer auto（`auto_review` 开启）；
+  reviewer 使用旧 Pro priority。
+- `escalate_on_failure` → worker 升级策略 `enabled`。
+- `pro_reviews_flash` → worker 成功后自动追加一次复查。
+
+旧的 `ds-flash` / `ds-pro` 子代理保留为**弃用别名**：它们映射到 worker 角色并带上
+历史模型类提示，旧 prompt 照常可用；新 prompt 请改用 `ds-worker` / `ds-reviewer`。
+同时传 role 与冲突的 legacy tier 会被明确拒绝（`ROLE_TIER_CONFLICT`），绝不静默猜测。
+
+### 故障排查：`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`
+
+pnpm 11 有默认供应链策略（`minimum-release-age`，24 小时）：最近一天内发布的
+lockfile 条目会被拒绝，除非列入 `minimumReleaseAgeExclude`。全新 profile 安装
+dsh-crew 不受影响；但如果你 profile 里已带刚发布的 DSH 插件（例如可选的
+`dsh-plugin-image-mind`），安装会报此错。
+
+解除方法：在 profile 的 `pnpm-workspace.yaml` 里加**不带版本号**的包名排除，然后重跑 add：
+
+```yaml
+# ~/.dsh/profiles/web/pnpm-workspace.yaml
+minimumReleaseAgeExclude:
+  - dsh-plugin-image-mind
+  - '@ran-sh/dsh-vision@0.1.0'
+```
+
+注意：用不带版本的裸包名——同名多条 `pkg@version` 只认第一条（先命中先赢），可能把
+新版本漏掉。排除项要放在 `pnpm-workspace.yaml`，校验器不读 `.npmrc`。该策略只针对
+发布不到一天的 registry 包（git 托管的 dsh-crew 本身从不做 age 校验），所以问题通常
+在 24 小时内自动消失。
+
+## 卸载
+
+DSH Crew 与 Codex / Claude Code 宿主集成是两层：
+
+1. 在 **设置 → DSH Crew** 中，对已安装的 Codex / Claude Code 集成点击 **还原**。
+2. 移除 profile plugin：
+
+```bash
+node scripts/setup.mjs uninstall   # Safe uninstall: see the canonical Uninstall section of README.md (official web profile is never modified).
+```
+
+只移除 profile plugin 不会隐式修改 `~/.codex` 或 `~/.claude`。Crew 配置、备份、凭据和其他 DSH bundle 都会保留。
+
+## 开发 / 源码安装
+
+源码安装器继续保留，供贡献者与本地 checkout 开发使用。
+
+Windows：
+
+```bat
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
+install.cmd
+```
+
+以后更新：
+
+```bat
+git pull
+install.cmd
+```
+
+跨平台：
+
+```bash
+node scripts/setup.mjs install
+```
+
+源码安装器会：
+
+- 把本仓库以 link 方式装进 DSH web profile（`link:<repo>`）
+- 安装 Codex Desktop 集成（**不需要** `codex` CLI）
+- 检测到 `claude` CLI 时自动安装 Claude Code 集成（可选）
+- 幂等，可安全重复执行
+
+Windows 源码卸载：
+
+```bat
+uninstall.cmd
+```
+
+跨平台源码卸载：
+
+```bash
+node scripts/setup.mjs uninstall
+```
+
+它会移除：
+
+- DSH web profile 中的 DSH Crew
+- Codex Desktop 集成
+- Claude Code 集成
+
+它会保留：
+
+- 仓库
+- Crew 配置（`~/.config/dsh-crew`）
+- 备份与凭据
+
+## 快速开始
+
+1. 照常启动 DSH：`npx -y @deepseek-ai/dsh web`
+2. 打开 **设置 → DSH Crew**。
+3. 保持新安装默认工作流：Codex → **worker** 角色 → Codex（reviewer 关闭）。
+4. 需要时用 **刷新 Harness 模型** 为各角色分别设置有序模型优先级。
+5. 重启 Codex Desktop / Claude Code。
+
+然后直接说：
+
+- “用 ds-worker 实现这个改动。”
+- “用 ds-reviewer 审查这个实现。”
+
+## 角色
+
+- **worker** — 执行角色：实现、修复、测试、搜索、分析。任意编码请求的默认角色。它是薄派发器；后台用哪个模型由 Worker Model Policy 决定。
+- **reviewer** — 独立审查角色：检查实现结果、工作区 diff、测试与风险，给出结论。默认只读，不做二次实现。
+- **ds-flash / ds-pro** 保留为弃用别名（见上面的迁移说明）。
+
+角色状态为 `disabled | manual | auto`：disabled 拒绝一切请求；manual 只在显式点名时运行；auto 可被 orchestrator 自动选择。未采用 canonical 配置时，生效状态来自旧协作模式。
+
+## 模型策略
+
+各角色通过实时 Harness 目录独立解析有序候选：
+
+- attempt 0 → 角色首选（便宜 / 快）优先级；
+- attempt ≥ 1 → 升级（强）优先级——升级基于**证据**（FAIL 测试、交付缺失、阻塞 / 未完成任务、工作区 diff 与 worker 报告不一致），并非只看失败，且不超 `max_attempts`（0..max-1，总尝试次数）；
+- 否则 → Harness Default。
+
+基础设施失败（缺 API key、Hub 不可达、worktree 隔离下非 Git 工作区）**不会**靠“换更强模型”解决，而是以稳定错误码失败。Flash / Pro 只作为历史模型类提示存在，不再是角色。
+
+## 工作流
+
+每次派发——`dsh_run_worker`（阻塞）与 `dsh_spawn_worker`（异步）、Hub 或 Standalone——都走**同一套** workflow runtime：
+
+```
+CREATED -> (繁忙时 QUEUED) -> RUNNING -> VERIFYING
+  -> ESCALATING（证据驱动）-> RUNNING -> VERIFYING
+  -> REVIEWING（自动审查）-> READY -> COMPLETED
+  （或 FAILED / CANCELLED）
+```
+
+阻塞与异步的唯一区别是调用方是否等待。coding worker 默认在独立临时 git worktree 中执行；返回 `change candidate`（base revision、committed + 未提交 + 新增文件、有界脱敏 patch、指纹）供 orchestrator 接受 / 拒绝 / 要求修改——runtime 绝不自动合并进你的 working tree。
+
+### 隔离
+
+`execution.isolation` 默认为 `worktree`：worker 角色在 HEAD 的分离 worktree 上工作，主工作区永不被动（即使它是 dirty 的；未提交的主工作区改动不会混入 candidate）。如果目标工作区**不是** git 仓库，worktree 隔离任务会 **fail closed**（`NOT_GIT_REPOSITORY`）而不是静默共享——需要旧的就地行为请显式设 `execution.isolation: "shared"`。
+
+## 模式
+
+| 模式 | 迁移后的角色行为 |
+|---|---|
+| Flash Only | worker auto、reviewer disabled、economy 模型策略 |
+| Pro Only | worker auto（强模型类）、reviewer disabled |
+| Balanced | worker auto、reviewer manual（点名时可用） |
+| Review Pipeline | worker auto + reviewer auto（`auto_review` 开启） |
+
+Custom 模式可分别配置 worker / reviewer 状态。
+
+## Provider
+
+Crew 会读取 DeepSeek Harness 当前注册的全部 provider 与模型。各角色独立解析候选：**worker** 使用首选（便宜）优先级 + 升级（强）模型池，**reviewer** 有独立审查优先级——旧版新鲜偏好为 `deepseek-v4-flash` / `deepseek-v4-pro`，以 Harness Default 兜底。
+
+- **Follow DSH Provider** — 从 Harness 目录解析角色的 provider/model 优先级（新配置默认值）。
+- **DeepSeek Official** — 为兼容旧配置保留内置固定路由。
+
+凭据始终由 DSH 的 provider 配置管理。已在 OpenAI 兼容的 OpenCode Go 网关实测。Standalone 模式（无 DSH 运行）始终使用 DeepSeek Official + `DEEPSEEK_API_KEY`。
+
+## 宿主
+
+- **Codex Desktop** 通过共享的 `~/.codex` 配置直接受支持，**不要求** `codex` CLI；CLI 只是可选的补充宿主 / 管理接口。
+- **Claude Code** 为可选；一键安装检测到 Claude CLI 时自动安装其集成。
+
+## 备注
+
+- Main Agent Mode 是路由指引，不是对宿主工具的硬沙箱。
+- Standalone 只使用 DeepSeek Official。
+- Crew Vision 的工具注册改动可能需要重启 DSH。
+- 集成内容改动后请重启 Codex Desktop。
+- 每个 worker 都会返回可审查的交付报告（`## Diff` / `## Tests` / `## Risks`），隔离候选捕获有界、脱敏的 patch，方便在接受前核对改动。
+- 阻塞与异步任务执行**同一套** workflow（证据驱动升级 + 自动审查）；异步只是立刻返回 workflow id 并在后台继续。
+- `dsh_worker_status` / `dsh_worker_result` / `dsh_worker_cancel` 以 workflow id（`wf-…`）为主；旧的 `hub-…` / `job-…` id 仍兼容。
+- Standalone 以 `node <dsh-sdk-jsonrpc-demo/lib/bin.js>` 启动 worker（Windows 安全；pnpm 的 `.bin` sh shim 无法被 Node spawn）。Standalone 默认 DeepSeek Official + `DEEPSEEK_API_KEY`，但支持 `DEEPSEEK_BASE_URL`——已配置在 `~/.dsh` 的 OpenAI 兼容网关（如 `opencode-*`）可通过同时设置这两个环境变量来支撑 Standalone worker。
+- 设置 UI 在本过渡构建里仍展示旧的 Flash/Pro 兼容控件；新 worker/reviewer 角色策略与 `execution.isolation` 的写回是后续项。
+
+## 版权与许可
+
+本 fork 基于 [ZSeven-W](https://github.com/ZSeven-W/dsh-crew) 的原始 DSH Crew，保留原 MIT 许可与署名，并增加可配置的 Harness 模型优先级、worker/reviewer 角色、统一任务工作流、git worktree 隔离、可审计交付等工作流能力。
+
+MIT License —— 见 [LICENSE](LICENSE)。