前言¶

在 DeepSeek Harness（DSH）裏做複雜任務，常見做法是讓主模型直接調用工具，或手寫一層子代理調度。前者容易把 Codex、Claude Code 等外部產品的會話能力浪費掉；後者則要自己處理進程生命週期、會話恢復和權限邊界。

dsh-plugin-product-subagents 走另一條路：把已安裝並登錄的外部 Agent CLI 註冊爲 DSH 子代理提供方，用聲明式角色庫描述「誰來做、能做什麼、能不能再委派」，並在 Harness 會話裏暴露一組統一工具。主模型始終是隻讀中繼，寫權限與委派上限落在遠程產品上。

下面按安裝、工具用法和權限模型說明這個插件能做什麼、適合什麼場景。

這是什麼¶

• 插件名稱：dsh-plugin-product-subagents
• 維護者：shaokeyibb
• 分類：工作流（SkillHub 目錄）
• 當前版本：0.3.1（MIT）
• 倉庫：github.com/shaokeyibb/dsh-plugin-product-subagents

一句話定位：面向 DSH 的基於角色的 Codex / Claude Code / ACP 子代理提供方。它把外部 Agent CLI 變成可同步、可續跑、可恢復會話的子代理，並提供按角色的產品權限與帶上限的委派能力。

核心功能¶

可續跑的子代理¶

子任務可以一次性同步執行，也可以異步續跑。續跑場景下，模型通過 send_message、list_agents、interrupt_agent 控制子代理；需要同步等待結果時，用 product_wait 掛接。

會話持久與恢復¶

子代理關聯的遠程產品會話在空閒回收或進程重啓後仍可恢復：插件用持久化註冊表和日誌標記跟蹤會話；Claude Code / Codex 按 id resume，ACP 提供方則重連。

聲明式角色庫¶

角色定義在 roles/*.json，內置包括：

• general（默認）
• code-review
• explore（不委派）
• debug

委派默認開啓，單個角色可關閉。未知角色回退到 general。

兩層權限與委派上限¶

• 中繼模型：在任何角色下都只有只讀管道，不獲得寫能力工具。
• 遠程產品：由角色的 permissionMode 控制，取值爲 readonly / default / full，並映射到各產品自己的 CLI 參數。
• 委派上限：子代理不能生成權限高於自身的後代（readonly < default < full）。

任意 ACP 提供方¶

除內置的 claude-code、codex、acp 外，可在 config.providers 裏聲明 Cursor（agent acp）、CodeBuddy（cbc --acp）、Gemini（gemini --acp）等 ACP CLI，無需改插件代碼。只有 PATH 上檢測到的命令會出現在委派枚舉裏。

資源與跨平臺¶

支持空閒回收、可配置超時、併發上限（maxConcurrentChildren）。Windows 提供 .cmd shim 與安全路徑轉義；CI 覆蓋 macOS、Ubuntu、Windows。

環境要求¶

• 已部署 DSH（web profile）
• PATH 上至少有一個已認證的產品 CLI：claude、codex，或 ACP CLI（如 opencode、agent、cbc 等）
• Node ≥ 18

安裝與啓用¶

推薦用 dsh plugin add 安裝。該命令會安裝包並通過 package.json 裏聲明的 cordis.patch.yml 自動寫入 host-plane 行，無需手改 profile 補丁。

dsh plugin --profile web add dsh-plugin-product-subagents

安裝後重啓 Harness，插件纔會加載。

若要自定義 ACP 提供方或空閒超時，在 profile 的 cordis.patch.yml（例如 ~/.dsh/profiles/web/cordis.patch.yml）裏覆蓋 product-subagents 這一行。注意：配置覆蓋會替換整個 config 對象，需要保留的鍵要一併寫出。

- id: product-subagents
  config:
    idleTimeoutMs: 600000
    providers:
      cursor:    { type: acp, command: agent, args: [acp] }
      codebuddy: { type: acp, command: cbc, args: [--acp] }

高級用戶也可在 profile 目錄用 pnpm 手動安裝，再自行插入 cordis.patch.yml 行；README 建議用 pnpm 而非 npm，以避免 peer 依賴被自動安裝。

典型用法¶

安裝並重啓後，會話裏會出現六個工具：

下面是一次委派加等待的示例：

product_delegate role=general task="Refactor demo-project/calc.js and run its tests"
product_wait subagent_id=<childId>

角色文件示例（節選）：

{
  "id": "code-review",
  "description": "Review code for bugs, security, maintainability (read-only).",
  "provider": "claude-code",
  "permissionMode": "readonly",
  "allowDelegation": true,
  "instructions": "You are a code reviewer. READ-ONLY: never modify files. …"
}

permissionMode 與各產品 CLI 的對應關係（來自 README）：

• readonly：Claude --permission-mode plan；Codex --sandbox read-only
• full：Claude --dangerously-skip-permissions；Codex --dangerously-bypass-approvals-and-sandbox

配置項¶

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # 子代理 settle 後空閒多久釋放遠程會話（0 表示不回收）
  maxConcurrentChildren: 8    # 同時存在的可續跑子代理上限
  rolesDir: <path>            # 角色庫目錄（默認 roles/）
  registryPath: <path>        # 遠程會話註冊表路徑

適用場景與注意¶

適合誰

• 已在 DSH web profile 上跑工作流，希望把 Claude Code、Codex 或 Cursor 等 CLI 納入統一子代理調度的人
• 需要按任務類型切換角色（代碼審查只讀、探索不委派、調試可寫）的團隊
• 希望子代理會話在空閒或重啓後仍能續跑的長任務場景

使用前請確認

• 插件以當前 DSH 進程的用戶權限啓動你配置的 CLI；安裝前建議閱讀倉庫源碼與 SECURITY.md。
• permissionMode: full 會傳遞各產品自帶的「跳過權限檢查」類參數，屬於配置即信任邊界，生產環境應收緊角色與提供方列表。
• SkillHub 目錄（skillhub.cn/plugins/shaokeyibb/dsh-plugin-product-subagents）是社區索引，與 DeepSeek / 幻方無官方從屬關係；以 GitHub README 與發佈包爲準。

結尾¶

dsh-plugin-product-subagents 把「外部 Agent 產品 + 聲明式角色 + 權限上限」收成 DSH 裏一組可複用的子代理工具，適合需要跨 Codex、Claude Code、ACP 統一編排、又要把寫權限關在遠程產品一側的場景。

• 目錄頁：skillhub.cn/plugins/shaokeyibb/dsh-plugin-product-subagents
• 源碼與文檔：github.com/shaokeyibb/dsh-plugin-product-subagents