前言¶
DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”，這使得生態擴展非常靈活。但在實際開發中，子代理（Subagent）的路由往往缺乏確定性，且項目級知識（如常用命令、歷史教訓）容易散落在各處，導致複用困難。
evo-subagent 是一款由 ZekaiShi 維護的 DSH 插件。它解決了上述問題：通過將穩定的代理角色映射到已註冊的提供者/模型組合，確保路由可預測；同時維護每個角色的 prefercmd.md（偏好命令）和 memory.md（記憶教訓），使知識在項目範圍內得到隔離和複用。
安裝與前置要求¶
在安裝之前，請確保你的環境滿足以下條件：
* DeepSeek Harness 版本：0.1.5-rc.3 或更新
* Node.js 版本：>= 24.2.0
安裝命令如下：
dsh plugin add evo-subagent
核心功能¶
該插件提供以下核心能力：
* 確定性路由：根據 agent_key 自動路由到同名的 Markdown 綁定文件。
* 參數驗證：在創建子代理前，嚴格校驗提供者與模型的組合。
* 知識演進：爲每個角色維護 prefercmd.md 和 memory.md 文件。
* 項目隔離：將綁定關係和演進數據隔離在各自的項目工作區中。
* 啓動模式：支持全新的 spawn 子代理和上下文感知的 fork 子代理。
* 降級機制：當沒有綁定文件時，回退到 DSH 原生的模型繼承機制。
* 零憑證存儲：插件本身不存儲 API 密鑰、端點或提供者定義。
典型用法：代理綁定與調用¶
在項目根目錄下創建 agents/ 目錄，併爲每個角色添加一個 Markdown 文件。文件名（不含擴展名）將作爲 agent_key。
project/
├─ agents/
│ ├─ code-reviewer.md
│ └─ researcher.md
└─ .evo_subagent/
└─ evolution/
綁定文件必須包含嚴格的 Front Matter 塊，指定提供者和模型（需在 DSH 中已註冊，且匹配嚴格區分大小寫）：
---
provider: deepseek-official
model: deepseek-v4-flash
---
# Code reviewer
Optional role notes may follow.
調用插件工具時，傳入對應的 key：
{
"agent_key": "code-reviewer",
"description": "Review the implementation",
"prompt": "Report correctness, security, and test coverage issues.",
"run_in_background": false
}
插件內置了三個角色模板：code-reviewer（嚴重性排序的代碼審查）、researcher（基於證據的調查）和 wps-worker（辦公文檔生產）。如果項目中定義了同名綁定，將覆蓋內置模板。
進階：演進知識與技能¶
每個項目在 .evo_subagent/evolution/<agent_key>/ 目錄下存儲角色的演進知識。
prefercmd.md：記錄經過驗證的命令。memory.md：記錄可複用的教訓和需要避免的錯誤。
前臺子代理會收到一個知識塊，若需要返回新條目，可使用以下格式：
[[EVOLUTION]]
prefercmd:
- pnpm test
memory:
- Do not use --force in CI.
[[/EVOLUTION]]
插入條目時，可在行首添加前綴：
* !：保持最高優先級。
* ?：在上下文預算緊張時允許壓縮。
插件還隨安裝註冊了三個 DSH 兼容的技能（需確保 DSH 的技能註冊表和工具已啓用）：
* /evo-route-doctor：診斷意外的路由或無效的提供者/模型對。
* /evo-memory-review：審查角色的 prefercmd.md 和 memory.md，檢查過時或衝突的知識。
* /evo-delegation-guide：選擇現有角色並準備一個範圍化的子代理任務。
路由行爲¶
插件的路由邏輯遵循以下步驟：
1. 安全解析 <agent_key>.md。
2. 解析其 fenced 的 provider 和 model 字段。
3. 在實時模型註冊表中驗證這兩個值。
4. 通過選定的 spawn 或 fork 提供者啓動子代理。
如果綁定無效，子代理在創建前就會失敗。如果缺少綁定，則保留原生 DSH 繼承，除非內置模板匹配。
注意事項¶
- 插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼與許可證。
- 提供者和模型必須已經在 DSH 中註冊（精確且區分大小寫的匹配）。
- 舊版
.smart_subagent/evolution數據作爲只讀後備方案保留，並在下次保存時複製到新位置。
總結¶
evo-subagent 通過將代理角色、路由邏輯與項目級知識演進解耦，爲 DSH 提供了一種結構化管理子代理的方式。無論是通過命令行插件安裝，還是集成到現有工作流中，它都能幫助開發者保持子代理行爲的可預測性。
