linkbag/dsh-swarm-orchestrator

dsh-swarm-orchestrator

English · 简体中文

面向 DeepSeek Harness 的基于角色的 AI 集群。给它一个目标，就能得到一支团队：架构师将工作拆解为任务图，并行构建者执行任务，审查者守住质量底线，集成者交付成果——而你可以通过实时看板观看整个过程运转。

它运行在你的 dsh web 宿主内部。没有守护进程，没有第二个进程，没有胶水脚本。任务代理就是普通的 DSH 子代理，拥有你的工具访问权限和你的模型；编排器只是一个行为良好的 Cordis 插件。

它已经交付过真实工作：首次生产运行逆向工程了一个生物技术研究仪表盘，并在一个下午内将其重建为一个六适应症套件（涵盖六种癌症的 680 项精选临床试验）——五个数据整理代理并行工作，每一项交付物都经过机器验证。

概览

dsh-swarm-orchestrator 在 DeepSeek Harness 内将一个目标转化为一支受监督的代理团队：架构师将你的计划评审为 PLAN.md，并行构建者将其作为任务 DAG 执行，审查者把关质量，集成者交付。每个角色都运行你从实时目录中指定的模型，每一项交付物都可以经过机器验证，整个流水线都可在实时看板 + 流程图上看得到。

you ── "spawn a swarm: ⟨goal⟩"
│
▼
your chat agent            (free to plan/research on its own —
│  swarm_dispatch     its plan becomes the proposal)
▼
┌─────────────────┐
│ architect-review │  deep-reviews the proposal against the repo,
│  → PLAN.md       │  consolidates parallel workstreams (evidence-checked)
└────────┬────────┘
┌──────┼──────┐
▼      ▼      ▼
builder builder builder    ▸ parallel wave — one model per role,
│      │      │           fallback chains, exclusive write scopes
▼      ▼      ▼
reviewer reviewer (human)   ▸ rejections loop back with feedback;
└──────┼──────┘            reviewGate: "human" parks it on you
▼
integrator             ▸ merges, verifies, ships
▼
📄 run report          ▸ per-task summaries · models used · stats

看板视图示例（实时工作流）

可选混合工作团队

为什么不直接让一个代理来做？

因为单个代理是串行的。长时间的研究任务会排在快速编辑后面，上下文会被填满，质量会漂移，而且除了写出输出的同一个模型之外，没有任何东西会检查输出。

这个插件认真对待协调工作，这样你就不必操心：
- 并行是构造出来的。 任务声明依赖关系（blockedBy）；所有相互独立的任务会同时运行，并受一个并发上限约束，该上限会在提供商吃力时自适应调整。
- 每个角色都有自己的模型。 将 DeepSeek、GLM、Kimi、Claude——任何在 DSH 中配置的模型——固定到任意角色，并配有有序的回退链和按角色划分的推理强度阶梯。选择器会读取你的实时模型目录，因此新的提供商会自动出现。
- 在“完成”之前先审查，才意味着真正完成。 标记为 reviewBy 的任务会由审查者代理根据任务简报进行评判；被拒绝会带着反馈循环回构建者。想自己说了算？设置 reviewGate: "human"，然后从仪表盘批准。
- 失败是一种状态，而不是谜团。 提供商超时、配额耗尽、证据不佳——每一种都会被检测到、如实报告并得到处理：带恢复提示的重试、暂停/恢复运行而不是一路烧毁、在反复失败后自动轮换模型。
- 范围限定在你所在的位置。 每个聊天的 Swarm 标签页显示该聊天工作区的运行；一个持久化开关会在你想要全貌时显示这台机器上的所有内容。
- 每个目标一次运行，先审查再构建。 向已有活动运行的工作区分派会发出警告（或阻止，由你选择）；并且除非你选择退出，架构师代理会在任何构建者开始之前，将分派器的计划审查进 PLAN.md。
- 内存安全的并发。 Swarm 代理在 DSH 主机上以进程内方式运行，共享其 Node.js 堆。全局上限（maxTotalConcurrentAgents，默认 8）确保来自不同工作区的并发运行共享代理预算——防止在同时运行过多代理时可能使主机崩溃的堆耗尽。
- 每个代理都留在面板上。 任务代理不能生成自己的隐藏子代理（maxSubagentDepth，默认 1）。没有这个限制，代理可以委托给分派器看不见也无法核算的助手——不被全局上限计数，不被看门狗跟踪，不显示在面板上，却全都共享主机堆。在一台真实机器上测得：一个任务生成了 12 个这样的隐藏助手，而面板只显示一个任务。
- 工作比它的代理活得更久。 每个任务代理都会在最后一步写一份简短的完成报告。如果主机在代理完成工作与被记录之间重启并杀死了代理，分派器会采用磁盘上的报告，而不是丢弃已完成的工作并重新运行任务。任务也永远不会一直停留在 dispatching：spawnTimeoutSeconds 会启动一个滑动的无进展窗口——它从创建时开始运行，然后每次心跳都会重新启动它，因此正在工作的子任务永远不会因为经过的时间而被杀死，而从未启动或陷入沉默的子任务则会被回收（在 Roster 中可按角色覆盖）。
- 正确的模型配正确的努力级别。 在派生子任务之前，固定的推理努力级别会依据部署所声明的模型能力进行校验：无法接受该级别的模型会被剥离该固定值，并且候选链永远不会被过滤——在一次运行中导致 6 个任务失败的 UNSUPPORTED_REASONING_EFFORT 崩溃不可能发生。如果某个固定值仍然到达了一个拒绝它的模型，子任务会快速失败且无输出，调度器会在任何模型轮换之前，在努力级别阶梯的下一级（max → high → … → 无固定值）重试同一个模型——且不消耗任务的重试预算。审查者固定值也以相同方式校验。

⚠️ 从不同工作区并行运行多个 swarm：在全局上限下，这是受支持且安全的。但请注意，每个 swarm 代理都是主机上的一个进程内会话。我们建议最多 2 个并发运行，除非你的主机有更多余量——全局上限默认为 100 个进程内代理，适合大型机器。如果你遇到 ERR_CONNECTION_REFUSED（主机崩溃），请在 Runtime 设置中调低 maxTotalConcurrentAgents。

可靠性说明（v0.5.8 – v0.6.17）

根据 47 次记录的运行 / 184 次任务失败以及以下事件诊断得出，随后修复并进行了回归测试：

- 证据命令在 PowerShell 下运行（其他环境为 bash），从工作区根目录执行，并且 evidence.commands 模式也如此说明。此前它们被交给 cmd.exe，因此一个完全正常的 PowerShell 门禁（if (Test-Path …) { exit 0 }）会导致任务失败——占所有记录的任务失败的 32%。在文件检查可以表达该门禁时，优先使用 evidence.files：它完全不涉及 shell。
- modlens 默认对 swarm 角色禁用，这是随附名册指南中的规定：它是一个会向用户提问的交互式工具，而 swarm 子任务以非交互方式运行。如果你的部署有无头视觉提供程序，请从名册中按角色将其加回。
- 未声明 "status": "completed" 的任务报告永远不会被采纳——采纳无法掩盖未完成的工作。
- 被采纳的报告还必须由当前活动尝试写入。 .dsh-swarm/task-.json 以任务 id 为键，而非以运行为键，因此复用 id 会在不同运行之间静默共享该文件。现在，早于当前尝试的 task/started 的报告会被忽略（并记录日志），而不会被记作本次尝试的工作。
- 恢复仅限定于正在运行的运行。 孤儿恢复只会重新排队那些运行仍在进行中的任务，因此已终止运行的任务会保持冻结，而不会在每次主机重启时被重新判定为失败。
- 审查结论从完整的最终消息中解析——解析器过去只读取 2,000 字符的摘要，导致每个详尽的审查都失败开放。现在，省略结论行的审查者会在失败开放之前收到一次明确的重新询问。
- 看门狗回收已采纳的完成工作，并重新武装重试退避。 一个在被回收前片刻才写好报告的子任务会被记功，而不是判为失败——旧路径会让一次运行滞留在 retrying 状态长达七小时。孤儿恢复会重新武装滞留的 retrying 任务，而每一次新的尝试都从干净的静默时钟开始。
- 存活判定基于进展，而非已用时间。 生成上限是一个滑动的无进展窗口，每次心跳都会重新武装它，并在 Roster 中提供按角色覆盖的 spawnTimeoutSeconds——健康的子任务绝不会因为运行时间长而被杀死。
- Web 客户端只持有一个 /swarm/events 连接，由标签页、徽章、头部弹出层和每张调度卡片通过引用计数共享。此前它会为每张渲染出的调度卡片打开一个流，耗尽浏览器每源约 6 个连接的上限，并在主机仍然健康时冻结整个 UI。
- 仅证据失败不再重跑工作。 只做一次仅命令的复查，然后任务就搁置等待人工处理（blocked + 人工审查）。记录的结果携带退出码、超时状态、已用时间和输出尾部——一个绿色但非零的测试套件可以从事件日志中诊断出来。

仪表盘

Web GUI 中，Chat 旁边有一个 Swarm 标签页，包含三种视图：

- Board — 左侧是运行列表，任务列（Queued / Running / Done / Failed）位于正中央。点击任务可查看其完整简报、模型、尝试次数、代理的临时笔记、审查者反馈以及重试。已完成的运行会折叠成一份报告，包含每个任务的摘要以及回退/重试/审查统计。
- Flow — 以动态流程图呈现任务 DAG：调度器在顶部，任务扇出为并行波次（同一波次 = 并发运行），依赖箭头在阻塞项完成时变绿，每个节点上都有审查者和写入范围提示，全部汇聚到运行报告中。你可以一眼看出哪些是并行运行的、哪些是顺序运行的，以及这次运行究竟进展到了哪里。
- Roster — 值班表编辑器：由你的实时目录提供的按角色模型选择器、回退链顺序、努力阶梯、并发上限、按角色的生成超时、工具过滤器、角色设定、自定义角色，以及一个“别动我的表”的覆盖锁定。选择器只列出你在 DSH 中配置了 API 密钥的提供方，并自动跟随变更——需要 DSH 0.1.6+。
- 其他所有位置 — 每个会话头部都有一个 🐝 状态按钮，一个用于显示活动运行的小徽章，以及聊天中派发运行处的实时进度卡片。
- 工作区感知 — 每个聊天的 Swarm 标签页显示该聊天所属工作区的运行；一个 All 开关可显示机器上的所有运行。值班表保持全局（一张表，适用于所有工作区）。
- 语言 — Swarm UI 自动跟随 DSH 语言偏好（Settings → General → Language）：内置英语和简体中文，切换时原地重新渲染。

一次运行如何工作
1. 派发 — 告诉你的 agent 你想要什么；它会用任务图调用 swarm_dispatch。运行以门控方式启动：规划中，零个 agent 被生成。
2. 执行 — 架构师审查提案并生成 PLAN.md；然后并行构建者开始工作。
3. 观察 — Board 显示看板；Flow 显示工作流程图；点击任意任务查看其抽屉。

快速上手（约 5 分钟）

1 · 安装

从这个 GitHub 仓库安装（pnpm 会运行该包的 prepare 脚本从源码构建）：

dsh plugin --profile web add github:linkbag/dsh-swarm-orchestrator

pnpm ≥ 10 会先要求你允许该构建 — 将它打印出的确切键添加到该 profile 的 pnpm-workspace.yaml 中：

allowBuilds:
dsh-swarm-orchestrator: true

然后重新运行 add。（该许可会在安装时于你的机器上执行此包的代码 — 适用通常的信任规则；如果你愿意，可以固定某个提交：github:linkbag/dsh-swarm-orchestrator#。）

或者从 npm 安装预构建版本 — 无需构建许可：

dsh plugin --profile web add dsh-swarm-orchestrator

然后重启 dsh web（或重新加载该 profile）。你应该会在 Chat 旁边看到 Swarm 标签页、每个会话标题栏中的 🐝 按钮，以及 Settings → AI Swarm（标题会显示正在运行的版本 — 这是确认安装成功的快捷方式）。

2 · 为角色分配模型

在任意聊天中打开 Swarm 标签页并切换到 Roster — 或者打开 Settings → AI Swarm，这是可从任何位置访问的同一个编辑器。四个内置角色：

| 角色 | 作用 |
| --- | --- |
| architect | 审查提案，将其细化为 PLAN.md |
| builder | 实现一个任务直至完成，并带有验证 |
| reviewer | 根据任务简报评判已完成的工作 |
| integrator | 合并并行工作并交付结果 |

为每个角色从下拉菜单中选择一个模型。它会列出 DSH 中配置的每个 provider（DeepSeek、GLM、Kimi、Claude……），按 provider 分组 — 与 Models 设置页面相同的实时目录。将某个角色保留为 inherit deployment default，即可使用派发聊天所运行的任何模型。

每个角色可选（均有合理的默认值）：

- Fallback chain — 当主模型不可用时，按顺序尝试的模型。
- Effort + effort ladder — 该角色固定的推理强度；梯级会随每次尝试推进，并最终以未固定状态结束，模型无法接受的级别会在生成前被剥离。
- Concurrency cap — 限制该角色同时运行的 agent 数量。
- Spawn timeout — 按角色覆盖无进展窗口，用于回收静默的子 agent。
- Tool filter — 拒绝该角色 agent 使用特定工具（例如只读的 reviewer）。
- Persona — 该角色的常驻指令。

缺少某个模型？先在 DSH Settings → Models 中添加该 provider，然后在 Roster 中点击 refresh catalog。

3 · 派发你的第一个 swarm

在任意聊天中，只需询问：
“生成一个 swarm：审计此仓库中每个 package.json 的过时依赖，每个包一个任务，然后由一个集成器汇总成一张摘要表。审查集成器的输出。”

或者使用一次性形式：

/swarm build a landing page for this project

你的 agent 将使用任务 DAG 调用 swarm_dispatch。（它可能会先自行规划——这没问题：架构师 agent 会审查并完善它发送的任何计划。）

4 · 观察运行

- Board 显示看板；Flow 将同一次运行显示为工作流图（调度器 → 并行波次 → 报告）；点击任意任务可打开其抽屉——简报、模型、临时笔记、审查者反馈、重试。
- 带有 reviewGate: "human" 的任务会停在看板上，等待你批准/拒绝。
- 发起调度的聊天会收到实时进度卡片；🐝 标题按钮和右下角徽章可从任何位置跟踪活动运行。

5 · 阅读报告

运行结束后会汇总成一份报告：每个任务的摘要、使用的模型、回退/重试/审查统计。整个历史是一个仅追加的事件日志，你可以重放。

值得了解的默认值： 每次运行都会先由架构师审查计划（每次调度可用 architectReview: false 跳过）；向已有活动运行的工作区发起调度会发出警告——并行工作流应放在一个 DAG 中；名册、徽章和标题按钮在所有工作区中全局生效。

与它对话

一切都通过普通聊天驱动——无需手动编辑配置文件：

“生成一个 swarm：审计此仓库中每个 package.json 的过时依赖，每个包一个任务，然后由一个集成器汇总成一张摘要表。审查集成器的输出。”

或者使用一次性形式：/swarm build a landing page for this project（先规划，再执行）。

| 工具 | 作用 |
| --- | --- |
| swarm_dispatch | 提交一次运行：标题、目标、任务 DAG（id / subject / description / role / blockedBy / reviewBy / reviewGate / model / evidence / writes）。 |
| swarm_status | 文本形式的看板：运行、任务状态、正在使用的模型、最新笔记。 |
| swarm_wait | 阻塞直到看板发生变化或超时——无需 sleep 轮询即可监督。 |
| swarm_retry | 在你修复原因后，将失败/阻塞的任务重新入队（仅限发起调度的会话）。 |
| swarm_interrupt | 中止停滞/运行中的任务，并在同一次运行中重新入队——无需辅助任务（仅限发起调度的会话）。 |
| swarm_complete | 当任务的工作在 swarm 之外完成时，将其标记为已完成（仅限发起调度的会话）——使运行记录与现实保持同步。 |
| swarm_report | 任务 agent 向看板发布临时笔记（已通过其自身任务的身份验证）。 |
任务还接受一份证据契约——evidence: { files: [...], commands: [...] }——它会在任务关闭前经过机器校验；一个写入范围——writes: [files]——用于避免并发构建者互相触碰对方的文件（调度器会在重叠时发出警告）；以及一道人工审查关卡，它会将裁决挂起在仪表盘上。证据命令失败后不再重新运行已完成的工作：它只会获得一次仅限命令的复查，如果该命令仍然失败——非零退出码或超时（evidenceTimeoutMs，默认 120 秒）——任务就会挂起在面板上等待人工裁决，同时退出码和输出尾部会记录到事件日志中。

配置

一切都有默认值；在你的 profile 的 cordis.patch.yml 中覆盖：

- id: swarm
require: dsh-swarm-orchestrator
config:
storageDir: !!js dshHomePath("storages/swarm")   # event log + duty table
maxConcurrent: 50           # simultaneous task agents per run
maxTotalConcurrentAgents: 100 # global cap across ALL runs (they share the budget)
adaptiveConcurrency: true   # shrink on provider pain, recover on success
spawnStaggerMs: 750         # pace launches within a wave
nudgeAfterMinutes: 20       # board marker for long-silent tasks (0 = off)
workspaceRunPolicy: warn      # one-run-per-goal guard: warn | block | off
requireArchitectReview: true  # architect reviews the dispatcher's plan into PLAN.md first
staleTimeoutSeconds: 14400  # watchdog: silent agents get reclaimed
maxRetries: 2               # per task
evidenceTimeoutMs: 120000   # per evidence command (1 s – 10 min)
reviewLoops: 3              # review rejections per task
notifyDispatchSession: true  # push completion notification to the dispatching chat
retryBackoffBaseMs: 5000    # retry backoff: base × 2^attempt before retrying
circuitBreakerThreshold: 3  # failures in 30s before pausing all retries (0 = off)
circuitBreakerCooldownMs: 60000  # circuit breaker pause duration
spawnTimeoutSeconds: 3600   # sliding no-progress window per child, re-armed by heartbeats (0 = off)
maxSubagentDepth: 1         # delegation-depth cap for task agents (1 = no delegation)
bootGraceSeconds: 3         # wait after plugin load before orphan recovery

运行时控制

所有并发、加固和看门狗参数都可以从仪表盘调整——无需编辑 YAML 或重启。打开 Settings → AI Swarm → Runtime tuning（或 Roster tab → Runtime tuning）并调整：

| 参数 | 默认值 | 控制内容 |
|---|---|---|
| Max concurrent agents | 50 | 每次运行中同时运行的任务代理数 |
| Global agent cap | 100 | 所有运行中的最大代理数——并发运行共享此预算（60+40，而不是 100+100）。这些代理在进程内运行并共享宿主 Node 堆：较高的默认值适合大型机器，因此在资源受限的机器上应调低它 |
| 生成错峰（毫秒） | 750 | 同一波次中启动之间的延迟——缓解同时产生的提供方负载 |
| 重试退避基数（毫秒） | 5000 | 失败任务在重试前等待 基数 × 2^尝试次数（5 秒 → 10 秒 → 20 秒）——防止当提供方故障一次性杀死所有任务时出现同步重试级联 |
| 熔断器阈值 | 3 | 在暂停所有重试之前 30 秒内的失败次数（0 = 关闭）——检测提供方范围的故障 |
| 熔断器冷却时间（毫秒） | 60000 | 熔断器触发后重试暂停的时长 |
| 静默后提醒（分钟） | 20 | 针对静默任务的看板标记——0 = 关闭 |
| 陈旧超时（秒） | 14400 | 对完全静默的代理的最后手段回收（4 小时） |
| 生成超时（秒） | 3600 | 每个子任务的滑动无进展窗口——每次心跳都会重新计时，因此正在工作的子任务绝不会因经过的时间而被杀死；从未启动或陷入静默的子任务会被回收（0 = 关闭） |

更改会立即应用（无需重启），并持久化到 runtime.json（位于 swarm 存储目录中），覆盖配置文件的 cordis.patch.yml 值。它们在主机重启后依然保留。

💡 如果你从不同工作区并行运行多个 swarm，请注意全局代理上限（默认 100 个进程内代理），并将并发运行数保持在最多 2 个。如果你遇到 ERR_CONNECTION_REFUSED（主机崩溃），请在 Runtime 设置中降低全局上限。

底层机制

- 主机侧（Node）：一个 SwarmService——值班表存储、仅追加的 JSONL 事件存储、投影折叠、调度器（位于服务自有锚点代理之后的并行一次性子代理）、审查循环、看门狗、暂停/恢复，以及 /swarm/* HTTP + SSE 路由。
- 客户端侧（浏览器）：Swarm 标签页、聊天进度卡片、页眉弹出框和 Settings 部分——全部通过单个引用计数的 SSE 连接由看板快照提供数据。模型选择器使用与 Models 设置页面相同的 LLM RPC。
- 按角色的推理投入 搭载于 DSH 的 agent/request 瀑布流，仅作用于被跟踪的 swarm 子任务——在子任务生成之前，会依据部署所声明的模型能力进行验证（调度和审查固定项皆如此），并记录在 task/started 上。
- 确定性重放：状态是对事件日志的折叠，并带有合法性防护——恶意或重复的事件流无法复活已中止的运行，也无法将任务完成两次。

已知限制

直白地写出来，因为你在生产环境中发现一个限制的代价，远高于在这里读到一个限制。

- 看板报告的是磁盘真相，而磁盘可能滞后于模型。 任务代理可能完成了它的工作，却没有执行协议要求它执行的每一步簿记操作（例如，写入其 .dsh-swarm/task-.json 报告）。看板显示的是实际记录的内容，而不是代理声称的内容。将任务摘要视为已记录内容的证据，并自行验证交付物。
- 证据契约对文件是建议性的，对命令是硬性的。 缺失或为空的 evidence.files 条目会变成看板警告，而不是关闭任务；只有失败的 evidence.commands 条目才会阻止完成（在一次仅命令的复查之后，持续失败会将任务搁置等待人工处理，而不是重新运行工作）。因此，范围控制是完成时的审计，而不是写入拦截——没有任何机制阻止 agent 写入其声明的 writes 范围之外；调度器只会在调度时对重叠范围发出警告。
- 状态由文件支持，并在单个 DSH 进程内串行化。 并发进程编辑同一工作区的 swarm 状态不会被协调。每个工作区运行一个主机。
- 成员消息传递是单向的。 任务 agent 可以向调度器报告进度；它们不能互相发送消息。协调通过 DAG（依赖关系和写入范围）进行，而不是通过对话。
- 一个角色可以同时持有多个任务。 调度器按角色和全局限制并发，而不是每个 agent 一个开放任务，因此单个角色可以同时拥有多个进行中的任务。
- 恢复是按每次启动限制的，而不是全局限制的。 孤儿恢复在每次主机启动时最多将一个滞留任务重新排队一次。反复重启的主机会反复将同一个不情愿的任务重新排队——这是有意设计的，这样未完成的任务不会被静默放弃。
- 看板头部中的版本是启动时加载的版本，而不是磁盘上的版本。手动编辑 duty-table.json 也需要重启主机；通过 Roster UI 所做的更改会实时生效。
- lib/ 是构建产物，不是提交的。 对 client/ 的源代码更改在运行 npm run build 之前是不可见的；如果 bundle 过期，tests/bundle-freshness.test.ts 会失败。

状态

v0.6.19，已在日常使用中运行。测试套件针对一个假的 spawn 提供程序对调度器进行了端到端覆盖（169 个测试：调度、背书、架构师注入、审查循环、人工门禁、回退轮换、断路器、重试退避、配额暂停/恢复、救援路径、证据契约和仅证据复查门禁、写入范围警告、事件日志合法性、委托深度、工具过滤器、工作区作用域、通知遏制、尝试记账、工具过滤器净化、预检工作量验证、工作量阶梯及其同模型层级重试、部署声明的工作量预检（调度和审查固定）、值班表工具过滤器防护、人工审查通知、全局状态徽章标签、过期任务报告拒绝、模型目录的线上接口、界面本地化、看门狗存活性和回收采用、客户端插件加固、客户端连接预算、针对生产事件存储的实时启动审计，以及一个针对调度器不变量的 故障矩阵，包含 10 个对抗性测试），外加在真实部署上的实时验证和一次隔离的端到端冒烟运行。

许可证

MIT © linkbag

简体中文文档见 docs/zh-CN.md。