前言¶
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
