dsh-mutiagent

为 DeepSeek Harness 提供可递归分工、逐成员选模型、相互通信和等待的协作代理树。

本插件支持 DSH 0.2.1-rc.2 / 0.2.1-rc.3、Node.js 22 及以上版本。需要已有 dsh-base 和持久会话存储；不需要安装或启用官方 Agent Teams。所有代理共享当前工作目录，插件不创建 worktree 或文件锁。

安装并开始使用

在已有的 Web profile 中安装发布版本：

dsh plugin --profile web add github:wlyzqm/dsh-mutiagent#v0.1.3

也可从 GitHub Releases 下载 .tgz 安装包和 SHA-256 校验文件，再将安装包的本地绝对路径传给 dsh plugin --profile web add。

本地开发时使用：

dsh plugin --profile web add link:/opt/DSH-Plugin/dsh-mutiagent

使用其他安装位置时，将 link: 后的路径换成插件的实际绝对路径；CLI 用户可将 web 换成自己的已初始化 profile。插件安装会停用该 profile 中四个顶层旧 Subagent 工具入口，并启用本插件的工具集，底层 spawn、fork 服务继续使用。

若当前启用了 @deepseek-ai/dsh-experimental-agent-team-profile，先移除它，避免两套同名协作工具并存：

dsh plugin --profile web remove @deepseek-ai/dsh-experimental-agent-team-profile

安装后按 DSH 的 application 结果处理：若返回 restart-required，重启对应服务；随后在新会话中使用。无需另外启用「智能体团队」开关。

若之前安装 v0.1.0 时因 rc.3 版本不兼容被拒，并提示 node_modules could not be reinstalled，先修复该 profile 的依赖，再安装修正版：

dsh plugin --profile web install
dsh plugin --profile web add github:wlyzqm/dsh-mutiagent#v0.1.3

将 web 换成实际使用的 profile；此修复不需要 allow-version 豁免。

若旧版本启用时出现 tools.restrict() names unknown global tool "subagent"，升级到 v0.1.3 后重启对应 DSH 服务。新版支持 Web 预设将旧工具直接注册在现有 Agent 作用域的情况，无需手工删除宿主工具或预设。

v0.1.3 修复长回复在保存前被截断的问题。升级后产生的终态文本会完整保存；read_messages 返回保留消息的全文，wait_agent / wait_all 返回所选成员最新结果的全文。自动上下文与成员列表仍使用有限长度预览，列表中的 text_truncated 表示预览省略。旧版已丢弃的尾部不会因升级自动恢复，可到对应子代理原会话查找。

可以直接给主代理这样的任务：

创建 researcher 和 reviewer 两个协作代理。researcher 调查实现，reviewer 检查风险；两人可以互相发消息。researcher 如需帮助，可自行创建一个专家。先明确各自文件范围，等待所需结果后汇总。

需要不同模型时，在任务中写明已在 DSH 配置的 provider、模型 ID 和推理强度。插件不配置模型凭据，也不把某个模型名称视为一定可用。

组织一棵代理树

每个会话的主代理地址为 /root。成员创建自己的子代理后，地址继续向下展开，例如 /root/researcher/expert。创建工具返回地址和成员信息；后续通信优先使用返回的完整地址。

所有本插件成员都可以创建子代理，并在创建时选择：

• task_name 与 message：成员名称和完整初始任务。
• fork_turns: "none"：新上下文，默认方式。
• fork_turns: "all"：继承父代理已完成轮次。DSH 不会复制当前正在创建子代理的未结束轮次，因此当前任务和临时决策必须写入 message。
• model、provider、reasoning_effort：可选的独立模型路由；省略时使用配置默认值或继承父代理。
• max_tokens：当前执行的可选输出限制，不等同于团队累计预算。

名称在同一个父节点下区分成员。相对名称可用于附近成员，发生歧义时使用完整路径。代理不能通过地址访问其他根会话的团队。

发送通知或启动后续工作

send_message 用于通知。它记录消息并交给目标的协作信箱，不主动唤醒已停止执行的目标；未读消息会在下一次模型步骤的动态上下文中显示，也可通过 read_messages 或等待工具读取。发送成功代表已接收，不代表模型已经阅读。信箱保留最近 maxMailboxMessages 条消息，超过容量会移除旧消息；读取结果中的 truncated 表示请求游标之前有内容被移除，大量或重要产物应同时落盘。

followup_task 用于追加任务。目标未活动时启动或恢复工作；目标正在执行时，在 DSH 允许的步骤边界处理输入。它不会强行越过当前工具调用。

例如，“我采用了你的接口建议”适合 send_message；“请按新接口重新检查测试”适合 followup_task。不要为了确认收信反复唤醒队友。

等待结果并管理成员

工具	用途
spawn_agent	创建子代理，选择上下文和模型
send_message	向同一棵树中的成员发送通知
followup_task	给成员追加任务并触发执行
list_agents	查看树中成员、地址和当前状态
wait_agent	阻塞等待协作活动或指定目标的结果
read_messages	读取信箱，可选择是否推进已读游标
interrupt_agent	中断授权范围内成员的当前执行
close_agent	关闭授权范围内的成员并回收其子树
team_up	一次创建多个成员，逐项报告创建结果
wait_all	等待指定成员结果并汇总，协调输入可提前唤醒
team_status	查看代理树与共享任务概况
task_create	创建共享任务，指定 owner、依赖和写范围
task_list	查看共享任务、依赖就绪情况和写范围冲突
task_get	读取单个任务及当前 revision
task_update	使用 revision 校验领取、完成、修改或重新分配任务

等待和完成是两件事：成员没有运行，不代表它完成了某项任务。以等待结果中对应执行的完成、失败、取消或超时状态为准。结果会保留来源和执行标识，避免把上一轮产物误当作当前结果。

出现互相提问时，先发送问题，再让出等待；收到新协调输入后先处理它，再继续等原目标。不要让 A 和 B 同时在无法处理消息的工具中无限等待对方。interrupt_agent 保留会话，后续可继续派工；close_agent 用于结束成员的团队生命周期。

共享任务与文件范围

共享任务工具用于记录待办、负责人、依赖和预期写范围。任务更新使用 revision 校验，避免覆盖其他成员刚提交的更新；依赖关系帮助判断哪些工作已准备好，但任务就绪不会自动启动负责人。需要开始工作时，向负责人发送后续任务。

写范围用于协调，不是文件访问权限。给不同成员划分互不重叠的文件范围；格式化、生成脚本和 Bash 写文件也需要协调。根代理负责汇总变更和运行必要验证。

配置

可在 profile 的 cordis.patch.yml 中配置插件行：

- id: dsh-mutiagent
  config:
    maxAgents: 8
    maxDepth: 4
    spawnConcurrency: 4
    waitTimeoutMs: 60000
    maxWaitTimeoutMs: 3600000
    maxMessageBytes: 65536
    maxMailboxMessages: 256
    maxDigestChars: 4000
    defaultModel: ''
    defaultEffort: ''

配置	默认值	含义
maxAgents	8	同一棵树的活动成员上限，包含根代理；终态成员保留地址但不占活动名额
maxDepth	4	相对于本插件根的委派深度上限，根深度为 0
spawnConcurrency	4	批量创建时同时执行的创建操作数
waitTimeoutMs	60000	默认等待时长，毫秒
maxWaitTimeoutMs	3600000	单次等待的最大时长，毫秒
maxMessageBytes	65536	单条消息的最大 UTF-8 字节数
maxMailboxMessages	256	单成员信箱容量限制
maxDigestChars	4000	自动上下文及状态结果预览字符上限，不截断邮箱或等待工具返回的全文
defaultModel	空	未指定模型时使用的默认模型
defaultEffort	空	未指定推理强度时使用的默认值

DSH 底层仍有自己的子代理容量和能力校验。插件限制不会提高宿主限制；批量创建的并发数也不代表团队可以无限扩张。

恢复、权限和兼容范围

• 协作状态记录在根会话的插件日志中，子代理会话继续使用 DSH 的持久化机制。恢复需要根会话和相应会话存储仍然可读。
• 给已经回收的深层成员追加任务时，插件会按父链自动恢复中间成员。这些中间成员可能产生维护轮次；冷恢复结束后的原生父代理通知也可能唤醒父代理。普通 send_message 不会触发这些恢复操作。
• max_tokens 属于当前激活的输出限制，DSH 原生冷恢复不保留该值；模型和推理强度会恢复。它不是团队累计 token 预算。
• 子代理消息是其他代理的输出，不是用户授权。中断、关闭和派工均按实际调用成员与树关系校验。
• 插件使用宿主已有的模型、工具和权限系统，不授予额外文件或网络权限。
• 当前没有自定义 Team Web 面板。使用 list_agents、team_status 查看全树；子代理会话沿用宿主现有呈现。
• 宿主兼容声明与 SDK peers 同时接受已验证的 rc.2、rc.3；未自动放行其他 RC 或正式版本。实验 SDK 可能改变，升级 DSH 后应重新运行验证。
• Web 预设继承的旧 subagent、subagent_fork 委派入口通过继承限制屏蔽；直接注册在 Agent 自己作用域中的旧入口从原生模型声明移除，并通过执行 guard 禁用。PTC SDK 文本可能仍声明旧函数，但调用同样被拦截并提示使用 spawn_agent。卸载插件后原工具恢复，其他预设工具继续保留。

卸载

dsh plugin --profile web remove dsh-mutiagent

按卸载结果重启服务，再开启新会话。移除 bundle 会去掉本插件层，顶层旧工具配置回到其余 profile 层的组合结果；已有会话日志不会因卸载被删除。

开发与文档

在装有匹配 DSH SDK 的开发环境中运行：

npm install
npm test
npm run check
npm pack --dry-run

版本发布通过 Git 标签触发：更新 package.json 和 docs/releases/<标签>.md，推送对应的 v<版本> 标签。GitHub Actions 先在独立 rc.2、rc.3 环境运行测试，再检查版本一致性、检查源文件、生成安装包和校验值并发布 Release；不会发布到 npm。

本机已有匹配 DSH 安装时，可用以下命令复用它的 SDK，再执行测试；只在插件目录建立开发依赖链接，不修改 DSH 安装：

node scripts/link-host.mjs /opt/dsh/lib/node_modules/@deepseek-ai/dsh
npm test

• 文档索引
• 当前架构
• 工具参数与协作示例
• 验证范围与复现
• 历史方案
• Codex 机制调研
• 跨框架协作调研

包名按项目约定拼作 dsh-mutiagent；研究资料中的 multiagent 是通用术语或历史名称。