前言¶
DSH 的理念是「一切皆插件」，多智能体协作一开始并没有统一的角色层。手工做法是：在宿主里写若干 subagent bundle，各自配好提示词、模型和工具，再让主代理按需 spawn。问题在于角色定义散落在各个工具配置里，改一次模型或提示词都要翻配置；组件之间也没有统一的角色目录和运行记录。
下面介绍的插件是社区作者 Delthin 维护的 dsh-agent-roles。它在 DSH Web 左侧提供「多智能体」入口，让用户用界面维护角色模板（职责提示词、模型与思考强度、工具白名单、Skills），再由主代理通过原生 Agent Team 接口创建成员、分发任务和继续对话，不需要预设固定工作流。插件配合 DSH Web 0.2.1-rc.5 及以上使用，当前版本 0.4.0。
定位¶
一句话：这是一个角色管理插件，为 DeepSeek Harness Web 提供角色目录界面，并基于 DSH 原生 Agent Team 接口创建成员和继续对话。
插件里有两个核心概念。角色（Role） 是可复用的配置模板，保存职责提示词、模型与思考强度、工具白名单和 Skills。成员（Member） 是主代理按角色启动的具体运行实例。主代理在会话中能看到所有已启用角色的职责、模型和已选 Skills，并判断当前任务是否调用 spawn_role 创建成员。
仓库页还给出了迁移说明：后续源码开发和维护迁入 Delthin/dsh-plugins monorepo 下的作用域包 @delthin/dsh-agent-roles，旧仓库保留用于查阅历史提交与早期版本记录。安装时需要注意当前源码采用 Apache-2.0 许可证，历史版本 <= 0.4.0 已授予的 MIT 许可不撤回。作者在社区目录的收录信息显示星标为 0，属于早期项目。
环境与安装¶
安装前确认三件事：Node.js 22.18+、DSH Web 0.2.1-rc.5 及以上、至少一个已配置的模型供应商。底层 Agent Team 接口仍处于实验阶段。
安装的 v0.4.0 通过 GitHub Release 归档：
dsh plugin --profile web add https://github.com/Delthin/dsh-agent-roles/releases/download/v0.4.0/dsh-agent-roles-0.4.0.tgz
如果对应版本已在 npm 发布，也可以执行：
dsh plugin --profile web add dsh-agent-roles@0.4.0
安装前可以先核对 npm 可用性：
npm view dsh-agent-roles@0.4.0 version
安装过程无需编译，也不执行安装脚本。装完刷新 DSH Web 页面，左侧导航栏会出现「多智能体」入口；如果宿主没有自动加载，重启对应的 Web profile。插件市场收录独立于上面两种安装方式。
安装会改到什么¶
插件 bundle 会启用 DSH 原生团队服务、团队工具与界面，并停用旧的 tool-subagent、tool-subagent-fork、tool-subagent-control、tool-subagent-list-agents 条目，切换方式与官方实验团队 profile 一致。如果当前环境已经有自定义团队 bundle，需要检查是否存在相同 ID 的配置覆盖。
首次安装得到空角色目录，不包含作者的角色、提示词或运行记录；从旧版升级会保留本地数据。
创建角色¶
先从创建角色开始。在左侧打开「多智能体 → 角色 → 新增角色」，按下面几步填：
- 填显示名称、分发名称（小写字母、数字、连字符，如
reviewer）和职责描述。职责描述用来供主代理判断何时选用该角色。 - 为该角色选择模型供应商、具体模型和思考强度。
- 在「提示词」中写清角色职责、工作边界和交付标准；在「工具」中只勾选该角色必需的工具白名单。
- 在「技能」中搜索并勾选 DSH 已发现的 Skills。默认为空，不自动继承全局技能目录。
- 把角色设为启用并保存。
任务分发与协作¶
角色启用后，直接在主会话里向主代理描述任务。README 给的例子是配置了只读审阅角色 reviewer 之后，对主代理说：
请把这份改动交给 reviewer 审阅，要求指出有依据的问题；你汇总结果并决定如何处理。
运行机制有几点值得注意。主代理通过 spawn_role({role, name, prompt}) 启动成员，底层走原生 agentTeams.spawnTeammate。成员启动时会保存当时的角色提示词、模型设置和 Skills 正文快照，之后修改或删除角色不影响已创建的成员。成员在独立的全新会话中启动，不继承主代理的上下文历史，所以任务背景和材料必须写在 prompt 里。需要追问时，主代理可以用原生 send_message 继续和同一成员实例沟通。
成员的工具白名单不含递归委派工具，成员之间也不能主动互相通信。任务拆解、结果汇总和跨成员协调全部由主代理负责，并依靠 list_agents、send_message、interrupt_agent、wait_agent 这组接口管理。其中 list_agents 查询的是当前已创建的成员实例，不是角色目录。
成员状态显示 inactive 只代表当前没有正在执行的回合，不代表任务成功完成，结论和错误要看成员输出内容。在成员记录的「请求详情」中，插件会记录实际发出的模型、思考强度与工具列表，并核对 DSH 基础系统提示词、角色提示词原文以及所选技能正文是否完整加载。DSH 0.2.1-rc.5 原生成员列表的模型字段可能保留父会话描述，实际路由以「请求详情」为准。
Skills 的加载与沟通成本¶
新建和已有角色默认 skills: []。勾选 Skills 后，插件在启动成员时通过 DSH 原生技能服务读取内容，以原生 <skill_content> 格式（含资源基目录与字面正文）完整注入新成员的系统提示词。即使角色不勾选任何工具，也能接收所选 Skills 的指令。
需要注意两点。Skills 只提供文本指令，不会自动赋予工具权限，技能依赖的外部命令、软件仍要在宿主和工具白名单里另外配。若所选技能在启动时不可用，成员启动直接失败并报告缺失的技能名称，恢复或取消勾选后可重试。
沟通成本方面，勾选的 Skills 完整正文计入成员会话输入，所以建议只为角色勾选必要的 Skills。简单直接的任务由主代理直接完成即可，不必拆成多智能体协作。
数据存储与配置¶
默认数据目录为 $DSH_HOME/agent-roles，未设置 DSH_HOME 时为 ~/.dsh/agent-roles。目录里两个文件：roles.json 保存角色目录、结构版本号和目录修订号；runs.json 保存成员启动快照、所选技能正文、请求加载校验结果，以及最多 30,000 字符的最近输出摘要。完整对话历史仍由 DSH 原生会话存储保存。
自定义数据目录或启用可选的供应商 Fast 开关，改当前 profile 的 cordis.patch.yml：
- id: agent-roles
config:
dataDir: ~/my-dsh-data/agent-roles
fastProviders: []
dataDir 支持绝对路径、~ 和相对当前进程工作目录的路径，建议用绝对路径。当前文件存储不提供跨进程写锁，多个独立运行的 DSH 进程应配置不同的 dataDir。
公开包默认 fastProviders: []，模型选择器旁的 Fast 按钮不可启用。插件只记录 Fast/标准模式选择，不内置特定供应商的 priority 传输实现；只有环境中已装好对应传输适配且能读取角色启动快照时，才把供应商 ID 加入 fastProviders。启用 priority 传输可能改变供应商侧的计费标准。
限制主代理可委派的模型¶
在「多智能体 → 设置」里可以加规则：选择主代理模型，勾选禁止的子代理模型，保存后立即生效。模型选项来自 DSH 已配置目录，默认没有规则。也可以用通用 delegationRules，下面是 README 示例 ID，替换成自己的模型 ID：
- id: agent-roles
config:
delegationRules:
- leaderModel: lead-model-id
denyModels:
- blocked-member-model-id
模型 ID 精确匹配，不区分供应商。策略按主代理当前请求的模型执行，切换模型后下一轮随之变化。角色目录会隐藏被禁止的角色，工具调用在启动前拒绝。受限制的主代理必须使用 spawn_role，通用委派工具也会被拦截；向已有禁止模型成员发消息同样拒绝。已经运行的成员不会被自动中断。
运行限制与安全边界¶
- 单个团队最多 32 个已创建成员、256 个共享任务。并发数和委派深度受 DSH 原生 subagent 配置约束；宿主把委派深度设为
0时需先在宿主配置里允许委派。插件不会越权修改全局配额或系统权限。 - 插件通过原生
agent/created钩子在成员首个请求发出前挂载模型路由、系统提示词与工具白名单守卫，不接管或替换 DSH 原生模型执行循环。角色管理 API 复用 DSH Web 连接服务的身份验证，拒绝未认证请求。 - 角色工具白名单只约束模型可调用的工具集，不是操作系统级文件或目录沙箱，具体文件读写和命令执行仍受 DSH 全局权限与文件策略控制。插件代码运行在宿主进程权限下，请勿把同一个已登录的 DSH Web 会话暴露给不可信用户。
runs.json中的成员快照包含提示词、技能全文和输出摘要，备份时按私人敏感数据保护。卸载插件不会删除数据目录，删除角色也不清理已生成的运行记录。运行记录目前不自动过期，列表 API 默认返回最近 200 条。
适用场景与注意¶
适合需要在 DSH Web 里管理多个具有不同模型、工具组合的协作角色（如审阅、检索、代码生成各一个角色），同时希望主代理按需决定调用谁的开发者和小团队。角色目录集中维护后，改提示词、换模型、加技能都在界面里完成，不必逐个编辑 bundle。
安装前建议先读源码和许可证。插件以当前 DSH 进程权限运行，会禁用旧的 subagent 工具条目，也会在角色成员启动时向系统提示词注入 Skills 正文；请结合自己的权限与文件策略评估。也要留意仓库迁移状态：后续维护在 Delthin/dsh-plugins，旧仓库不接收新开发。
小结¶
dsh-agent-roles 的价值在于把「角色」变成可维护的配置模板，并复用 DSH 原生 Agent Team 接口：角色管职责和模型，成员是按需创建的运行实例，协调仍由主代理集中承担。对想在 Web 界面里做多智能体分工的人来说，它比手工配 subagent 少了重复劳动。
- 社区目录页：https://www.skillhub.cn/plugins/Delthin/dsh-agent-roles
- GitHub：https://github.com/Delthin/dsh-agent-roles
