joekytc/dsh-swarm

dsh-swarm

简体中文 · English

---

Say one requirement, reply one confirmation — six specialist agents take it from planning to verified delivery. No commands to memorize.

dsh-swarm is a DSH plugin that turns one requirement into a strict, evidence-verified delivery pipeline. An orchestrator (V) decomposes an approved spec into a strictly ordered phase chain (p → (pt?) → w2 → d → dt → w3 → summary); six single-purpose roles (V / P / W / D / PT / DT) run each phase with isolated, permission-gated tool faces; every handoff is machine-verified against an evidence contract; failures recover through idempotent retry and human-gated reviews; and a live Workflow kanban tab streams all state to the browser via SSE. Design inspired by the Hermes Agent kanban.

---

Swarm mode (recommended)

Swarm mode turns your main session into a team lead: you state the requirement, it clarifies, plans, confirms, delegates and follows through — entirely in natural language, no commands to remember.

• No commands to memorize — just state your requirement; no /plan: or /openspec: prefixes needed.
• Automatic intent recognition — development requests → clarify/plan and build a chain; lessons & retrospectives → persist to memory; group notifications → deliver to WeCom; Q&A / chit-chat → answered directly. Intent is judged by the model, not by a code-level classifier — the confirmation gate below is what stops a misjudged chain.
• Free delivery — /sms <intent> (e.g. "post current progress to the group"): facts are grounded via kanban lookup, then the body is composed per intent and delivered; -s or wording like "private chat" targets the DM. A bare /sms re-sends the latest completed-chain report and /sms blocked [chainId] the block notice — those two bodies are rendered by system code from kanban facts, never rewritten by the lead. Group and private-chat targets auto-resolve to the single saved target (0 or 2+ targets error out; clean up in dsh-im settings, or pin imDelivery.targetId / imDelivery.dmTargetId, which skips the count check — though with imDelivery.botId empty the pinned target must still belong to the auto-discovered bot, or it errors out).
• Confirmation gate against accidental chains — after the checklist is saved, the lead is instructed to build a chain only once you reply with an explicit affirmative (确认 / 开干 / 开跑 / 开始 / go, etc.). The gate is judged by the model, not enforced by a code-level check; vague replies, topic switches, or edit-only feedback count as not confirmed.
• The lead is read-only — the main session cannot write/edit repo sources, nor run git mutations (push/commit/reset…); a bare git checkout/git switch of an existing branch is allowed. Writing code is done by the executor (D) in an isolated workspace by design.
• Progress is always actually queried — ask "how is it going?" anytime and the lead reports from real kanban lookups, never fabricated.

Why it's designed this way

Coordinating several agents on one task typically fails in three ways:

• Role drift — the "planner" starts writing code, the "executor" reviews its own work, and nobody owns the outcome.
• Unverifiable handoffs — an agent claims "done" with no reproducible evidence, and the next agent builds on sand.
• Silent deadlocks — an agent stops without finishing and the pipeline hangs, or bad code is merged before anyone reviewed it.

dsh-swarm encodes a contract against all three: one responsibility per role, enforced by the permission matrix, tool faces and task-body instructions; every handoff must carry structured evidence or the phase will not close; every stall or review failure lands in a visible, recoverable state — with you (the human) as the final trust anchor. It is built correctness-first: deterministic state machines, append-only event sourcing, idempotent schedulers, and a red-team test suite that replays the event log and rejects any illegal transition (mechanics in Advanced).

Two modes

---

Quickstart

1. Install

Prerequisites: a working DSH runtime (@deepseek-ai/*), Node.js ≥ 22.19 and npm. Optional: a wiki-vault HTTP service (KB features, see Configuration).

From npm (the published tarball ships the built lib/):

dsh plugin --profile web add @joekytc/dsh-swarm

From a source checkout (rebuild first so lib/ matches the sources):

npm install
npm run build        # tsc -p tsconfig.build.json + client bundle (lib/client.js)
dsh plugin --profile web add .

From GitHub source: dsh plugin --profile web add github:joekytc/dsh-swarm — the repository tracks the built lib/.

2. Switch your main-session preset

Switch the main session's agent preset to Swarm (蜂群模式) — it is installed at $DSH_HOME/.agent-presets/swarm once the plugin is installed.

3. Say → confirm → watch progress

Example conversation:

You: Add a role-management page to the admin project with CRUD and permission checkboxes

Lead: Let me confirm a few things first —
  · Which role fields do you need (name/description/status/…)?
  · Permission source: the existing menu tree, or custom?
  · Any acceptance requirements, e.g. "deleting a role must not affect linked users"?

You: Fields are name and description, permissions from the existing menu tree, acceptance via TDD

Lead: Checklist saved (six spec sections + repo facts). Reply "confirm" to launch —
      I'll spin up the p → (pt) → w2 → d → dt → w3 pipeline.

You: confirm

Lead: Chain created (ch_…), live progress on the kanban tab (Conversation → Trajectory → Kanban).
      First phase: Planning (P)…

• Kanban: the third tab of the conversation center (Conversation → Trajectory → Kanban). Click a card for Overview / Trajectory / Handoff / Spec / Comments.
• Completion: when a chain completes, the system audits the workspace and (for D chains) automatically merges the feature branch into the spec-declared target branch. An audit warning blocks the final wrap-up until you confirm ownership in the GUI — it does not gate the merge.
• Progress: just ask "how is it going?" — the lead reports from real kanban lookups and relays blocking reasons faithfully.

---

What it does for you

Six roles, one job each — boundaries enforced by the permission matrix, trimmed tool faces and task-body instructions, so no role creep:

The pipeline (strictly serial within a chain, parallel across chains):

p ──> (pt?) ──> w2 ──> d ──> dt ──> w3 ──> summary
plan   plan rev.  KB    impl  impl rev.  KB    wrap-up

• pt appears only when P decides a plan review is needed; d is always followed by an implementation review (dt).
• Chain completion is decided by a mechanical rule (W3 done + D done with delivery evidence + no open tasks), not by an agent's self-assessment.

---

Configuration

All keys are optional; schema lives in src/config.ts. Most users only need the first three — keep the rest at their defaults.

The 「模型链」 (model chain) card in the config panel: every role gets its own model — pick provider, model and reasoning effort per role; roles you leave untouched show 「继承」 (inherit) and follow the default.

---

Review engine (ocr)

Implementation reviews (the in-chain DT phase and standalone reviews) are powered by open-code-review (ocr), with two modes switchable in the web config panel under 「Swarm 配置 → 评审引擎（ocr）」 (Swarm config → Review engine (ocr)):

The 「评审引擎（ocr）」 (review engine) card in the config panel: with ocr installed, choose the mode (managed / delegate) plus provider and model, then click 「应用到 ocr」 (Apply to ocr) to wire it up.

Install

• When ocr is missing, the config panel shows a red banner — click 「安装 ocr」 (Install ocr) for a one-click global install (async, cancellable);
• or run npm install -g @alibaba-group/open-code-review in a terminal, then verify with ocr --version.

Standalone review (no chain needed)

1. Switch the session to 「交付评审官（DT）」 (Delivery Reviewer (DT)) at the top of the dsh web UI and just talk;
2. State the review target: a local directory / branch range (from…to) / a single commit / uncommitted workspace diff / a public repo URL (auto-cloned into a temp dir, discarded afterwards);
3. The report is first fully output to the conversation;
4. Only after you confirm is it written to the KB at projects/<repo>/reviews/<topic>-<date>/ — remote KB mode only; with the default empty wikiVault.baseUrl (local mode) no wiki page is written.

Read-only in practice: bash/run_code writes and wiki writes outside the reviews namespace are blocked by the guard, while the fs write/edit tools are not blocked in a standalone DT session.

Configuration notes

• Mode, provider and model are all chosen on the 「评审引擎（ocr）」 card; the provider/model dropdowns share the same catalog as the model chain;
• After picking, click 「应用到 ocr」 (Apply to ocr) — the system writes the wiring into ocr's custom config (dsh-managed); the API key is resolved from the dsh model config and written into ocr, never shown in plain text in the panel; if resolution fails it degrades gracefully and points you to a manual ocr config provider in a terminal;
• When managed is not ready, the ocr tool refuses the managed call and returns delegate guidance; the reviewer switches to delegate mode — nothing is blocked.

Official docs: Installation · Model configuration · Delegate mode

---

Trust & guardrails (user's view)

• Read-only hard gate for the lead — in swarm mode, main-session writes to sources and git mutations are blocked by a system gate; if blocked, just let the lead explain — execution is done by the D role.
• Confirmation gate — the lead only builds a chain after you reply with an explicit affirmative (enforced by the lead's instructions, not by a code-level check).
• TDD hard gate — implementations must ship with tests (or an explained skip); reviews machine-verify "tests really ran, and were written first".
• Human trust anchors — spec approval, unblock, audit confirmation and chain deletion are human-only; role agents cannot approve specs, and a chain is only created from your confirmed routing call (the main session routes as human).
• Guardrails are constraints, not a sandbox — PT/DT write guards rely on path and command regexes (reviewers get no git credentials), and review evidence is existence-checked: fields must be present and well-formed, while replaying the commands to prove they ran happens only when evidenceReplay.enabled is turned on.
• Full mechanics (permission matrix, delivery contract, review chain, rework, failure recovery) live under Advanced / Developers.

---

Advanced / Developers

Mechanics and implementation details below — regular users can skip.

Roles & the execution pipeline (full table)

Six roles are dispatched by the scheduler as one-shot agent sessions (deterministic session id kbn-<taskId>; a retry resumes that same session — resumeSessionId is always null in the current implementation — while a rework task starts its own kbn-<reworkId> session). Each role-agent session is bound to exactly one task (boundTaskId) and gets a trimmed tool face. V is the exception: a chain-scoped orchestrator session (kbn-v-<chainId>) with no boundTaskId.

Guardrails in detail

Permission matrix

can(action, actor, task, { boundTaskId }) in src/domain/permissions.ts. "Bound" means the actor is the role agent session spawned for that exact task (boundTaskId === task.id and, for complete, also actor === task.assignee).

Key guarantees (two):

• The main session cannot execute. Its kanban tool face is a read-only subset — kanban_show/kanban_chain/kanban_list/kanban_comment plus the human-recovery pair kanban_reopen_chain/kanban_waive_review — together with spec_card_view, kanban_route, the planning_* tools and sms_send; never kanban_create/kanban_complete/kanban_block. Chains/specs are created only via swarm-mode intents or /plan:+/openspec:; the GUI observes and mutates task state but never creates chains or tasks — "who decided to run what" stays explicit and auditable.
• Session binding prevents cross-task escalation (a W agent bound to task A cannot complete/block task B even though both are W tasks); DT writes are confined to the projects/<repoSlug>/<chain>/review/ namespace by a ToolGuard on top of the matrix; and no role agent can approve specs, unblock, confirm audits, waive a review or reopen a chain — those are human trust anchors; system handles only mechanical bookkeeping.

Delivery contract (upstream owes downstream)

Each phase's handoff must carry the keys its downstream actually reads (src/domain/delivery-contract.ts). Missing delivery keys block the W/P card immediately and admit no human exemption; the D/PT/DT evidence gates instead reject complete with an error (the card stays running) and are human-exempt. The orchestrator never builds a downstream card on a blocked parent:

TDD hard gate (evidence threshold)

D completes only with tdd — test_files (with test_first) or skipped.reason (XOR, delivery-evidence.ts). DT's review_evidence must carry tdd; whenever tdd.test_files are declared the runner must be vitest (test.runner), and on a pass verdict test_first === true must hold (review-evidence.ts). This makes "tests actually ran, and were written first" a machine-checked property rather than a claim.

Gate skip alarm & declaration cross-check

A declaration that disagrees with the diff no longer passes the gate silently (three silent-skip modes remain, emitting no event: gates.enabled=false, a handoff without worktree_dir, and non-d:execute cards):

• task/gate-skipped event — a declared tdd.skipped is allowed when the diff is pure docs/config, or when the diff cannot be computed (conservative alarm-skip); both leave the event as an audit trail. Otherwise the gate bounces the card back (same session, agent fixes and re-completes).
• Declaration ↔ reality cross-check — declaring test_files with no test-file change in the diff (stale-test h