智能体团队编排 leinasi2014/dsh-agent-swarm

dsh-agent-swarm

给 DeepSeek Harness (DSH) 用的多智能体团队。你的主对话只管盯住目标，另有一位独立的 Captain 负责招募成员、协调任务、审查成员的工作。

GitHub Releases 提供带版本号的安装包，以及每个版本验收通过的范围。当前这份代码准备的是恢复补丁 v0.1.5，把功能基线拉回 v0.1.3，并带上单独验收通过的任务取消依赖守卫。发布和全新 Profile 验收是两步，分开进行；已发布版本和已验证范围请看 release notes。安装时请用已发布的 release tarball；本仓库为 npm 发布设置了 private: true，没有公开的 npm 包。

你能做什么

- 同时跑多个团队。 每个团队有自己的 Captain Session 和成员。你的根 Session 叫 Main Brain，负责创建团队、在团队之间派活，但不加入任何团队的花名册。
- 协调交付。 Captain 招募成员，按依赖关系组织任务，分配工作，审查提交。可选的「先规划」流程会在激活团队前先征求批准。
- 跟进团队讨论。 读群聊、查看成员资料、打开对应的官方 Session 记录。成员可以翻看公开历史，按 ID 分段读取某条消息，也能回复真实的公开消息。
- 配置成员的工作方式。 用模型路由、推理等级、Skill 白名单、预算、基于角色的工具策略，还能让 Captain 逐个审批工具调用。
- 保留团队上下文。 团队状态通过官方 Storage Domain 持久化。团队共享记忆和成员私人笔记各有独立的访问边界。
- 在 DSH 里干活。 团队面板和插件设置都用官方 web UI。官方 Session 保留对话历史，成员由官方 Subagent 运行。

Main Brain (your root conversation)
+-- Team A: Captain Session -> Members -> Tasks and reviews
+-- Team B: Captain Session -> Members -> Tasks and reviews

服务归属和持久化的细节见能力架构（中文）。

安装

| 要求 | 支持的基线 |
| DeepSeek Harness | 0.1.5-rc.2 |
| Node.js | ^22.19.0 || >=24 |
| pnpm | 9.15.9，且在 PATH 上可用 |
| UI | 官方 DSH web Profile |

兼容目标固定在 package.json、pnpm-lock.yaml 和 OFFICIAL_BASELINE.json 里。其他 DSH 版本不在本基线覆盖范围内；兼容性更新会跟随 release candidate 和正式版本。
先完成 DSH 官方安装，再准备一个能运行所选模型的配置档。配置档必须组合官方 Storage、Storage Domain、会话持久化和子代理运行时。初次试用时，请使用单独的 DSH_HOME 或专用配置档，并在安装或更新其包之前停止目标配置档。

从 最新发布的 release 下载带版本号的 .tgz 包和 SHA256SUMS.txt。在 PowerShell 中，切换到下载目录，并使用为所选配置档配置好的 shell，把文件名设为下载的包：

$swarmPackage = (Resolve-Path './dsh-agent-swarm-<version>.tgz').Path
Get-FileHash -Algorithm SHA256 $swarmPackage
Get-Content './SHA256SUMS.txt'

确认哈希一致，然后安装并检查组合后的配置：

dsh plugin --profile web add --workspace-root $swarmPackage
dsh --profile web --dump-config
dsh --profile web --host 127.0.0.1 --port 3180 --no-open

把 web 换成你配置的配置档名称，并选一个未占用的端口。打开 DSH 打印的本地 URL。该 bundle 默认启用其插件组；安装它不会创建团队或成员，也不会替你选择模型。如果缺少必需的服务，插件会保持 pending，直到配置档提供这些服务。

更新已有配置档

让进行中的工作先结束，保留已安装的包、配置和持久化数据，然后停止配置档。把 $swarmPackage 指向新的、已验证的 tarball，并使用官方替换命令：

dsh plugin --profile web add --workspace-root --force $swarmPackage

重启后检查实际安装的版本，以及已有的团队和会话记录。每个源码构建使用不同的产物路径。回滚时，保留之前的包和匹配的配置，并在恢复工作前确认当前数据仍可读取。自动迁移和无损回滚目前尚未覆盖；恢复旧备份可能丢弃该备份之后记录的工作。

第一个团队

在根会话中，描述一个结果及其验收标准。例如：

Create a delivery team for this repository. Ask its Captain to recruit
implementation and review members, plan tasks with dependencies, and
require executable test results before accepting the work.

Main Brain 使用 agent_swarm_create_managed 进行委派，然后让 Captain 和成员在各自的会话中继续。如果要在工作开始前先审批，请走 plan-first 流程：create_managed(stage=true)、set_plan，然后 approve_plan(ask_user=true)。
打开 Team 面板，跟进群组讨论、任务和成员配置档。在配置档里打开该成员的官方会话，查看记录，再返回团队。用 Captain 的聊天调整团队目标或方向。依赖成员持续对话之前，先看下面的私聊限制。

在 Settings -> Plugins -> Agent Swarm 下配置默认值。Captain 可以用 agent_swarm_set_communication 覆盖团队的沟通强度。模型和推理选择遵循显式配置和发起会话；不捆绑任何特定模型服务商。消息进入队列只表示已排队，不代表成员已读取或已处理。

发布边界与已知限制

- 恢复范围： 点击成员卡片，打开配置档，在该成员的官方会话里继续聊天，再返回群聊。公开消息历史和有限的消息读取已恢复，下面描述的可选 Skills 管理器也已恢复；它在默认 Bundle 中仍处于禁用状态。恢复的取消保护会拒绝取消任务，只要还有另一个未取消的任务依赖它。
- 后续工作： 向已有团队追加成员仍属于后续切片。更广泛的 C2/A1/M3/G1 交付仍未完成；恢复文件或接受单个修复，并不代表这些工作流已完成。
- 成员私聊： v0.1.2 恢复了在同一官方成员会话中继续对话，包括其 Captain 不可用时；见 issue #286。界面接受文本和图片消息；真实模型验收目前只覆盖文本。普通文件附件会被拒绝，草稿保留。
- v0.1.3 新增下面描述的可选 Skills 管理器。 它未在默认 Bundle 中启用，也不在 v0.1.2 的 tarball 里。新的选择性协作配额仍在开发中。查看已安装包的 release notes，了解其验收范围。
- 本地执行是已交付的目标。 远程成员、跨进程分布式协调、Canvas 消费方、自动 Skill 演化仍在已交付范围之外。
- 验收是有边界的。 当前版本尚未确立自动升级、数据迁移、长时间稳定性，以及覆盖整个版本的恢复与无障碍矩阵。工程检查和真实 Profile 验收是两类独立证据。

implementation roadmap 定义了剩余的能力边界和验收标准（中文）。

私密笔记召回

从 v0.1.2 起，成员当前任务支持成员笔记维护和可选召回。召回默认是 disabled；Profile 所有者可以在 Agent Swarm Host 配置里设置 privateMemoryRecall: active-task。成员和 Captain 无法通过提示词或工具审批启用它。参见 private-memory contract（中文）。这些新增内容不包含在 v0.1.1 的 tarball 里。

可选 Skills 管理器（v0.1.3）

独立的 dsh-agent-swarm/skills Host 插件负责管理技能请求、不可变候选、Captain 审核，以及已批准版本的分配。默认 Bundle 不启用它。Profile 必须已经提供主 Swarm 运行时、官方 agent 和存储服务、Skills 注册表，以及选定的模型服务商。

再保存一份 Profile 补丁，命名为 swarm-skills.yml，把占位符替换成你 Host 的精确 workspace scope、Team ID 和已配置的模型路由：

- insert:
- id: agent-swarm-skills
name: dsh-agent-swarm/skills
config:
manager:
provider: REPLACE_WITH_PROVIDER_ID
model: REPLACE_WITH_MODEL_ID
management:
- scope: REPLACE_WITH_EXACT_HOST_WORKSPACE_SCOPE
teamId: REPLACE_WITH_TEAM_ID

scope 是规范的 Session workspace，不是某次 attempt 的执行目录。management 列表为空表示不授权任何 team。manager 路由的两个字段都要提供；缺一个字段就无效，两个都省略则返回 unavailable。manager 不继承 Captain 的模型，也不继承通用工具权限。

检查合成后的配置，然后用同一个 overlay 启动：

dsh --profile web --patch ./swarm-skills.yml --dump-config
dsh --profile web --patch ./swarm-skills.yml --host 127.0.0.1 --port 3180 --no-open

对于一个已授权且处于活动状态的 Team：

1. Captain 提交 agent_swarm_skills_request，并读取 agent_swarm_skills_status；读取状态不会调用模型。
2. manager 用它作用域内的 skills_management_investigate 工具做调查和批量确认，用 agent_swarm_skills_propose 捕获候选。提出候选并不会发布它。
3. Captain 用 agent_swarm_skills_candidates 读取捕获到的正文，然后调用 agent_swarm_skills_review，带上 decision: approve 或 reject。作者不能批准自己的候选。
4. Captain 使用 agent_swarm_skills_assign，带上精确的 skill_name、version、member 里的成员 Session ID，以及 expected_revision。新分配用 0，或者用当前 revision 选择另一个已批准版本，包括回滚。

已经加载的技能在当前任务 attempt 内保持不变，即使成员的 Agent 被释放后又恢复也一样。分配变更在下一个有效任务 attempt 生效。分配会保留 Team 允许列表，而仅凭一条已存储的分配，并不能证明成员加载了它或从中受益。
这一片支持捕获的技能文本，资源树为空。完整资源包、按结果拒绝无收益的提案、在真实工作中体现改进、跨团队完整观测与复用，这些都还没做完。参见 Skills contract 和 roadmap（中文）。

早期 Team 面板截图

这张真实截图拍摄于 2026-09-09，用的是 DSH 0.1.2-rc.1。它展示的是早期的团队与任务布局，早于当前的群聊界面；它不是当前兼容性基线的截图。

早期 DSH Team 面板，含多个团队与成员树

文档

大部分详细的产品与架构文档目前是中文。

| 读这个 | 用来了解 |
| 文档索引 | 阅读顺序与已登记的权威文档 |
| 产品章程 | 目标、范围与完成标准 |
| 能力架构 | 会话、服务、服务商与状态归属 |
| 核心协议 | 任务、消息、权限、持久化与恢复 |
| Team UI | 团队面板、导航与交互契约 |
| 测试与验证 | 工程检查与真实 Profile 验收 |
| 兼容性策略 | 官方 DSH 接口与证据要求 |

开发

动手改之前先读 CONTRIBUTING.md 和 AGENTS.md。在仓库检出目录下，用上面提到的 Node.js 和 pnpm 版本：

pnpm install --frozen-lockfile
pnpm verify:isolation:status
pnpm verify:candidate
pnpm pack --pack-destination ./artifacts

verify:candidate 包含工程检查、测试、构建和打包校验。外部验收证据缺失时，它给出的托管 Team 产品证据结果可能是 NOT_CONFIGURED；工程跑通并不等于产品验收通过。所需证据见 测试与验证。

写者配额用项目自带的 pnpm isolation open|status|close|reconcile 生命周期管理。治理、指令或文档权威发生变化时跑 pnpm verify:policy；官方兼容性或参考兼容性影响决策时跑 pnpm verify:compatibility。源码包是开发产物；更新正在用的安装之前，先在隔离的 Profile 里验证。

许可证

MIT