前言¶
DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在構建複雜的工作流時，管理多個子代理的角色定義、工具權限和調用預算往往需要硬編碼配置。dsh-plugin-subagent-roles 解決了這一問題，它允許通過文件系統來定義子代理角色。
插件介紹¶
這是一個由用戶 troytse 維護的 DSH 插件。它將子代理的角色定義爲 Markdown 文件，利用 YAML 前元數據進行配置。插件支持項目級和全局級目錄存儲，提供工具過濾策略和工具調用預算限制，並註冊了一個委託工具用於調用。
核心功能¶
- 文件化定義：通過 Markdown 文件定義角色，包含 YAML 前元數據和角色人設正文。
- 多級存儲：支持在項目目錄
.dsh/roles/和全局目錄~/.dsh/roles/中存儲角色文件。 - 路由與配置：在 YAML 前元數據中配置顯示名稱、路由描述、LLM 路由（provider/model）。
- 權限與預算：提供工具過濾策略和工具調用預算限制，嚴格拒絕未知的前元數據鍵。
- 目錄展示：註冊委託工具並展示角色目錄。
安裝與啓用¶
安裝前請確保環境滿足依賴要求：Node.js 20 或更新版本，以及 DSH 提供的 @deepseek-ai/dsh-tools 和 @deepseek-ai/dsh-subagent。
在 CLI 模式下（例如 dsh web），執行以下命令：
dsh plugin --profile web add dsh-plugin-subagent-roles
安裝後需要重啓對應的 Profile（例如 dsh web）。
典型用法¶
1. 創建角色文件¶
在項目根目錄或全局目錄下創建角色文件，文件名必須爲 kebab-case。文件格式爲 YAML 前元數據加 Markdown 正文。
示例：.dsh/roles/code-reviewer.md
---
displayName: Code Reviewer
description: Reviews a diff for correctness, security, and missing tests, and reports findings by severity.
provider: deepseek-official
model: deepseek-v4-flash
reasoningEffort: low
tools: [read, grep, glob]
---
You are a code reviewer. Read the diff before judging it, separate blocking
issues from suggestions, and cite file and line for every finding.
2. 調用角色¶
可以通過工具調用或自然語言指令來觸發子代理。
- 通過工具調用：
subagent_role({ role: "code-reviewer", prompt: "Review the staged diff.", description: "review staged diff" })
- 通過自然語言指令：
have the code-reviewer role review this diff
注意事項¶
- 版本限制：
maxToolCalls系列功能需要插件版本 >= 0.4.0。在舊版本中，該功能不可用。 - 配置變更：版本 0.2.0 移除了插件註冊的設置命名空間，配置選項通過覆蓋
cordis.patch.yml中的行來設置。 - 文件命名：角色文件名必須爲 kebab-case。
- 鍵名嚴格性：插件嚴格拒絕未知的前元數據鍵，防止配置錯誤導致工具權限意外擴大。
- 依賴關係：插件依賴
@deepseek-ai/dsh-tools和@deepseek-ai/dsh-subagent。
總結¶
dsh-plugin-subagent-roles 爲 DSH 提供了一種結構化、可版本控制的方式來管理子代理。通過文件系統，開發者可以清晰地定義不同角色的行爲、權限和資源限制，適合需要精細化管理多個智能體協作的場景。
- 目錄頁：https://www.skillhub.cn/plugins/troytse/dsh-plugin-subagent-roles
- GitHub：https://github.com/troytse/dsh-plugin-subagent-roles
