前言¶

在 DeepSeek Harness (DSH) 生態中，管理子智能體通常需要編寫額外的配置或腳本。該插件解決了這個問題：它允許你直接使用本地 Markdown 文件定義智能體，並將它們註冊爲官方 DSH subagents。這提供了一個輕量級的方式來擴展 DSH 的能力，支持後臺任務派發與雙向追問。

核心功能¶

1. Markdown 文件即 Agent 定義
   在 ~/.dsh/agents/ 目錄下創建一個 .md 文件，文件名即 Agent 名稱。Frontmatter 定義元數據（如模型、思考強度），正文即 system prompt，修改後立即生效。

2. 斷點續跑
   長任務在運行過程中若發生中斷（報錯、取消、限額或崩潰），再次調用時會自動從已保存的進度繼續，無需從頭開始。

3. 後臺派發與雙向追問
   支持將代理置於後臺運行，主對話繼續進行。通過 ask_agent 接口可以向後臺代理發送追問並等待回覆。

4. 開箱即用的預置 Agent
   插件內置 workhorse、oldfox 和 rubber-duck 三個預置 Agent。它們僅在首次啓動且目錄爲空時植入，後續修改不會覆蓋。

5. 基於官方 Spawn Provider
   所有自定義 Agent 均通過 DSH 官方的 spawn provider 啓動，屬於貨真價實的 dsh subagent，繼承官方原生的會話、持久化和雙向通信能力。

6. 併發與深度控制
   支持通過配置項 maxActiveSubagents（同時活躍子代理上限，默認 8）和 maxDepth（委託嵌套深度上限，默認 1）來限制併發行爲。

安裝與啓用¶

本插件依賴 DSH 版本 >= 0.1.7-rc.1（RC/穩定線；Alpha 線不再支持）。

1. 本地安裝
   將倉庫克隆到本地並在 Profile 中掛載：

    dsh plugin --profile tui add ~/github/dsh-subagent-registry

重啓 DSH 後插件生效。

2. NPM 安裝

    npm i @aiwayds/dsh-subagent-registry

在 Profile 配置中通過穩定 ID `dsh-subagent-registry` 加載，或使用 bundle patch 掛載。

典型用法¶

1. 主對話點名調用
   在對話中直接使用 Agent 名稱：

    用 workhorse 把今天的發佈清單整理成表格

底層調用 `use_agent(agent: "workhorse", prompt: "…")`。

2. 後臺代理追問
   使用 ask_agent 對後臺代理發送消息並等待回覆：

    ask_agent(agent: "worker", message: "…")

3. 定義自定義 Agent
   在 ~/.dsh/agents/ 創建文件，配置 frontmatter：

    ---
    name: my-agent
    description: "一行簡介"
    model: opencode-go/deepseek-flash
    thinking: high
    ---
    You are my-agent. 這段正文作爲 system prompt。

4. 配置併發上限
   在 profile patch 中寫入配置：

    subagent: {
      maxActiveSubagents: N,
      maxDepth: M
    }

適用場景與注意¶

• 適用人羣：需要管理多個角色分工（如開發、審查、測試）的開發者，或希望用純文本管理 AI 行爲邏輯的用戶。
• 卸載方式：dsh plugin --profile <name> remove @aiwayds/dsh-subagent-registry。卸載後 Agent 文件保留，但 use_agent / ask_agent 工具會消失。
• 降級處理：如果沒有本插件，dsh-tui-pi 會優雅降級，只是失去自定義 Agent 派發能力。
• 依賴檢查：使用前請確認當前 DSH 版本滿足 >= 0.1.7-rc.1。

結尾¶

該插件通過引入本地 Markdown 文件機制，降低了 DSH 子代理的使用門檻，同時保持了與官方機制的兼容性。更多配置細節可參考文檔。