跨项目智能体舰队 nilesh32236/dsh-squad

dsh-squad

从一个编排聊天中，跨你的项目运行一支 AI 智能体舰队。

dsh-squad 是一个 DeepSeek Harness 插件，它允许一个会话创建并协调运行在其他工作区中的工作智能体会话。
你与编排器对话；它委派给工作智能体，每个工作智能体在自己的项目目录中工作，并向你汇报。

you ──▶ orchestrator ──▶ worker: opencode-ai-reviewer
├─▶ worker: performance-optimisation
└─▶ worker: duoport-connect-for-opencode
│
└── squad_report ──▶ orchestrator wakes up

为什么

DSH 已经能够针对任意工作区创建会话、向其发送提示、取消它，以及读取其日志。它尚未具备的概念是命名这些会话、记住哪个编排器拥有哪个工作智能体，以及把“把这个任务发到那边，并在完成时告诉我” 转化为一次工具调用。

这一层就是本插件。每个工作智能体都保留自己持久的会话日志，作为其工作的事实来源；dsh-squad 持有一份指针名册，以及工作智能体提交的报告和升级请求。

它的不同之处

大多数多智能体配置会让你在阻塞（编排器坐着等待）和空转（它在循环中轮询，消耗 token）之间做选择。

dsh-squad 两者都不做：

- 工作智能体会唤醒编排器。 当工作智能体汇报时，插件会将一条消息投递到编排器的会话中。如果它处于空闲状态，就会立即开始一轮；如果它正忙，消息会排在当前轮之后。无需轮询任何内容。
- squad_watch 是真正的非阻塞。 它注册一个真正的 DSH 后台作业，并立即返回一个作业 id，因此编排器可以在长时间任务运行期间进行审查、规划或准备下一轮。它会在结果出来时被唤醒。
- 舰队在重启后依然存活。 名册会被持久化，并且每个工作智能体会话都带有一个持久的 squad: 标题——因此即使状态文件丢失，身份也能保留，重新生成时会采用现有会话，而不是创建重复会话。

要求

- DeepSeek Harness >= 0.1.7-rc.1
- 一个其 Web profile 提供 @deepseek-ai/dsh-tool-jobs 的 harness 版本（squad_watch 所需）——它随标准 DSH web profile 一起提供。

安装

从 npm（或直接从 GitHub）

dsh plugin --profile web add @nilesh32236/dsh-squad
or straight from GitHub, same plugin:
dsh plugin --profile web add github:nilesh32236/dsh-squad

然后在插件管理器中启用该 bundle，并重启 DSH——插件 JavaScript 不会热重载。

从本地检出（开发）

git clone https://github.com/nilesh32236/dsh-squad ~/dsh-squad
cd ~/dsh-squad
node tools/dev-links.mjs /path/to/dsh-install # link the harness-provided peers
dsh plugin --profile web add link:$PWD

tools/dev-links.mjs 的存在是因为，作为 link: 安装到某个位于 harness 树之外的目录没有通往 harness 自身包的路径： Node 会从链接目录的真实路径解析导入，向上遍历你的主目录，永远无法到达 harness 安装位置。该脚本会创建符号链接。在 profile 的 node_modules 内通过 npm/GitHub 安装则不需要它。

快速开始

1. 启动一个新会话，并选择 Orchestrator agent 预设。
2. 创建团队——每个项目、每个角色各一个 worker：

squad_spawn name: reviewer project: my-frontend preset: squad-reviewer
squad_spawn name: fixer project: my-backend preset: squad-fixer

3. 先分发，再统一收集。 squad_assign 会立即返回，所以在等待任何一个任务之前，先把所有任务都发出去：

squad_assign name: reviewer task: "Audit the auth flow for missing checks."
squad_assign name: fixer task: "Fix the flaky retry test in tests/retry.test.js."
squad_wait mode: all
squad_collect name: reviewer
squad_collect name: fixer

最常见的错误是 assign → wait → collect，对每个 worker 重复一遍。这会把本可以并发运行的团队串行化。先给所有人分配任务。

4. 对于耗时较长的工作，使用 squad_watch 而不是 squad_wait，并继续工作。

工具

Orchestrator 工具

| 工具 | 用途 |
| squad_spawn | 创建或接管一个绑定到另一个工作区的 worker。按名称幂等。将未知的 cwd 注册为新工作区。 |
| squad_resume | 重新附加每个 worker，并报告各自需要什么。每当你恢复时都先调用它，以及在任何重启之后。 |
| squad_list | 名册：项目、状态、排队中的任务、未读报告和升级请求。 |
| squad_assign | 发送任务。queue = 其自身的新回合；steer = 注入到正在运行的回合中。也是你回应升级请求的方式。 |
| squad_wait | 阻塞直到 worker 完成。mode: "all" 在一次调用中收集整个分发批次。 |
| squad_watch | 相同的条件，但在后台运行。 立即返回一个 job id，并在有结果时唤醒你。 |
| squad_status | 详细查看单个 worker：最后调用的工具、被阻塞的问题、最后的回答、排队中的工作。 |
| squad_collect | 读取报告和升级请求，并将其标记为已送达。 |
| squad_stop | 取消 worker 的活动回合；保留或丢弃其排队中的工作。 |
| squad_close | 将 worker 从名册中移除。其会话日志会保留。 |

Worker 工具

| 工具 | 用途 |
| squad_report | 提交结果（done / partial / blocked），附带摘要和产物。唤醒 orchestrator。 |
| squad_escalate | 向 orchestrator 请求只有它才能做出的决定。唤醒 orchestrator。 |

当调用会话不是 squad worker 时，这两个 worker 工具都会拒绝执行，因此它们在其他任何地方都无害。

寻址 worker

每个 orchestrator 工具都接受worker 名称或其会话 id，因此一个持有来自 squad_list 的 id 的调用者可以寻址同一个 worker。无论哪种方式，所有权都会被强制执行。

协调模型

队列 vs. 引导

两者都是同一条持久化消息，只是投递目标不同：

| 模式 | 投递为 | 何时使用 |
| queue | next-turn —— 在当前回合结束后开启一个新回合 | 常规任务派发。从不打断。 |
| steer | next-step —— 在运行中回合的下一个步骤边界注入 | 重定向进行中的工作，以及回答升级请求。 |

如果 worker 处于空闲状态，两者都会立即开启一个回合。

编排器如何得知 worker 已完成

报告或升级会将一条消息投递到编排器的会话中：

[SQUAD] Worker "reviewer" (my-frontend) reported done.
…
Call squad_collect with name "reviewer" to read the full report.

这就是为什么空闲的编排器仍能做出反应——它不需要轮询。
设置 notifyOnReport: false 可禁用它，改为轮询。

活动记忆

squad_spawn 会报告一棵活动树，报告会自动以 markdown 形式归档到其中：

$DSH_HOME/squad/campaigns//
INDEX.md regenerated on every report — roster table + layout reports/ one markdown file per worker report escalations/ one markdown file per worker question notes/ campaign memory (written by the orchestrator) tasks/ the task board

花名册是插件的索引；这棵树是它旁边持久、可供人工浏览的记录，仅用文件浏览器即可读取。它以编排器会话为键——新的编排器会话会以一棵空树开始。

状态值

| 状态 | 含义 |
| idle | 存活，处于任务之间。 |
| working | 有回合正在运行。 |
| stuck | 正在运行，但日志超过 stuckAfterMs 没有增长。 |
| reported | 已提交报告，但编排器尚未收集。 |
| needs-answer | 因未回答的 ask_user_question 而阻塞。没有人监视 worker 的会话，因此一个悬而未决的问题否则会让它悄无声息地卡住。 |
| dormant | 在花名册上但未附加到活动会话——重启后恢复。会自动重新附加。 |
| unattachable | 无法重新附加；原因会被报告。 |

配置

在 bundle patch 的 squad 行中设置：

| 键 | 默认值 | 含义 |
| defaultProvider | （空） | Worker 路由提供方。为空 = worker 继承会话默认值。 |
| defaultModel | （空） | Worker 模型。为空 = 继承。将两者都设置以固定每个 worker 到一条路由，这样之后主机默认值的更改就不会悄悄地把正在运行的 worker 移到无法胜任该工作的模型上。 |
| defaultReasoningEffort | （空） | Worker 推理强度；仅在固定路由时应用。 |
| workerPreset | （空） | 应用于已生成 worker 的预设。 |
| stuckAfterMs | 900000 | 运行中的 worker 被判定为 stuck 之前的无日志增长阈值。 |
| notifyOnReport | true | 当 worker 报告或升级时，向 orchestrator 的会话投递一条消息。 |
| pollMs | 20000 | 活动时间戳刷新频率。 |
| maxTextChars | 4000 | 返回给模型的任何文本块的上限。 |
| maxWaitMs | 600000 | 单次 squad_wait / squad_watch 的上限。 |

内置 agent 预设

该 bundle 附带五个预设：Orchestrator、Squad Worker、 Squad Reviewer、Squad Fixer 和 Squad Auditor。

预设的 plugins 列表是完整的，而非追加式的。 一个只声明 persona 的预设会从会话中剥离所有工具。因此，这里的每个预设都携带随附的 standard 预设的完整插件列表，仅替换了 persona 行。verify-presets.py 会在结构上对此进行断言。

权限与数据

直白说明，因为安装插件会以你的权限运行第三方代码。

它会写入的内容
- $DSH_HOME/squad/roster.json — worker 名册和收集到的报告。
- $DSH_HOME/squad/campaigns// — 归档的报告、升级内容和 INDEX.md。
- 在它创建的每个 worker 会话上添加一个 squad: 标题。
- 在每个 worker 会话上进行模型选择，仅当你设置了 defaultProvider/defaultModel 时。

它会创建并驱动的内容
- 它会创建 DSH 会话并向它们发送提示。这些会话运行你配置的模型并消耗你的 token。这正是该插件的全部目的，因此请将 orchestrator 视为能够代表你派发工作。
- worker 的审批和沙箱边界属于 harness，而非此插件。
它不会授予 worker 任何 harness 原本会拒绝的能力。
worker 被会话沙箱限制在其自己的工作区内。

网络与凭据
- 该插件本身不进行任何网络调用，也不读取任何凭据。它唯一的 I/O 是上面列出的文件以及交给它的 DSH 会话服务。
- worker 仅通过其自身预设赋予它们的工具访问网络。

兼容性
- 需要 DSH >= 0.1.7-rc.1。
- squad_watch 需要在 agent 预设中包含 @deepseek-ai/dsh-tool-jobs（它随标准 DSH web profile 一起提供）。在缺少它的地方，该工具会如此报告，插件的其余部分不受影响。

市场

由社区中心索引，它们直接读取此仓库：

- dsh-plugin.org — 从 dsh-plugin GitHub 主题自动发现。
- dsh-market — 通过向 awesome-dsh-plugin 注册表提交 PR 来列出。

文档

- docs/ORCHESTRATOR-GUIDE.md — 如何良好地运行一次 campaign
- docs/INTERNALS.md — 设计决策与平台陷阱
- docs/DESIGN-NOTES.md — 研究结果与路线图

开发

node smoke-test.mjs # 8 轮共 37 项检查
python3 verify-presets.py # 预设与随附的 standard 的一致性校验
python3 generate-presets.py # 在编辑 persona 后重新生成 cordis.patch.yml

测试套件会在模拟宿主上运行每个工具主体，并断言（除其他事项外）没有任何工具结果包含 JavaScript 的 undefined（工具结果必须是无损 JSON）。模拟中的每个签名都从服务目录转录而来，并检查其参数个数，因为已发布的三个 bug 都是签名错误，它们之所以能存活下来，仅仅是因为模拟比真实 API 更宽松。

重载语义： 补丁数据（cordis.patch.yml）通过切换 bundle 实时重载。插件 JavaScript（fleet.js）不会热重载——加载器会在进程的整个生命周期内缓存该条目的模块导入，因此修正后的 fleet.js 需要真正重启 DSH。

许可证

MIT