lyingloong/dsh-agent-team-workflow ↗★ 0

dsh-agent-team-workflow

DSH plugin for user-defined, resumable agent-team workflows with model-lane failover, gates and a local kanban board.

套件
dsh-agent-team-workflow
相容性
待驗證
Harness 依賴範圍
>=0.2.1-rc.2
版本
0.3.0
授權
MIT
最近更新
2026年11月3日

同名套件的其他儲存庫

安裝

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:lyingloong/dsh-agent-team-workflow

dsh-agent-team-workflow

A resumable, provider-aware workflow engine and kanban board for agent teams.

dsh-agent-team-workflow turns "a bunch of coding agents" into a workflow you can trust over days: roles with capacity, a durable event log, model lanes with automatic failover, gates that record decisions instead of taking them, and a local board that shows the real projected state.

Status: engine, pull-mode coordination, the standalone board, the DSH plugin adapter, and the embedded Web GUI panel (P1–P4). Optional forge observation lands next. The engine imports no host, model vendor or forge — the DSH adapter talks to the host only through ctx services.

Why another agent orchestrator

The 2026 tooling wave (Vibe Kanban, Conductor, Claude Squad, MulmoTerminal, agent-orchestrator, …) mostly solves running agents: parallel sessions, worktrees, diffs, a board. Those are the floor, not the differentiator.

dsh-agent-team-workflow keeps the part that is hard to get right once a team runs unattended:

  • Every write is an event. Projections rebuild from the log, so a crash cannot leave the scheduler believing a task is assigned when it is not.
  • Roles, slots and lanes are first-class. "3 accounts × 3 roles, 9 active tasks, switch lanes when one quota runs out" is configuration, not a fork.
  • One live coordinator per data directory. A second process fails loudly instead of double-dispatching.
  • No fake work. When nothing is ready, the planner returns nothing. Idle roles are a signal, never a reason to invent a task.
  • Gates never act. A gate records "waiting for an external signal" or "approved by a human". Merging, closing a PR and pushing stay outside.

Concepts

TermMeaning
DefinitionJSON data: roles, providers, stages, gates, sources, policies.
RoleA kind of worker with instances, capacity and a provider pool.
StageA unit of work a role performs, with allowed outcomes and transitions.
ItemA unit of work flowing through stages (a seed, requirement, point, …).
TaskThe executable unit for one stage of one item.
AttemptOne execution of a task, bound to a member, a lane and a lease.
GateA decision point that pauses an item; it never merges or closes.
ProviderA model lane with concurrency, watermark and failover backoff.
SlotOne capacity unit of a role; a slot runs at most one task.

Quick start

Requires Node.js >= 22.5 (node:sqlite). The engine prints Node's experimental SQLite warning; it is expected on current releases.

node src/cli.mjs init                 # write workflow.json (bundled dev-team example)
node src/cli.mjs define workflow.json
node src/cli.mjs board                # http://127.0.0.1:7171/

From an installed package the same commands are agent-team-workflow or the short alias atw.

Validate and inspect without starting anything:

node src/cli.mjs validate workflow.json
node src/cli.mjs status
node src/cli.mjs roster

Run the tests:

npm test                          # one process, no child spawn
node --test "tests/*.test.mjs"    # standard runner with per-file isolation

Use as a DSH plugin

Install into a DSH profile (the path that gives sessions the team_workflow_* tools and the usage section):

# from GitHub
dsh plugin --profile desktop add github:lyingloong/dsh-agent-team-workflow

# or from a local checkout
dsh plugin --profile desktop add /absolute/path/to/dsh-agent-team-workflow

# restart that profile's Harness process, then refresh the Web GUI

Published npm installs use the same plugin name: dsh plugin --profile desktop add dsh-agent-team-workflow.

cordis.patch.yml mounts the plugin. In any session, describe the workflow in natural language:

创建一个自动开发的工作流:三个需求师、三个工程师、三个审查师,三条模型线路;审查通过后需要我批准才能合并。

The model translates that into a definition and calls team_workflow_define; the result includes a validation summary and the board URL. Reply "开始" to let it enqueue work and delegate tasks.

ToolPurpose
team_workflow_defineCreate or replace the session workflow from JSON the model composes.
team_workflow_statusProjected counts, stage columns, lane health, pending gates, board URL.
team_workflow_boardStart (or return) the local board.
team_workflow_enqueueCreate an item at the entry stage.
team_workflow_planRead-only ready tasks and pending gates.
team_workflow_claimClaim one task for a role (external worker path).
team_workflow_completeReport a stage outcome; advance, pause on a gate, or finish.
team_workflow_failReport failure; lane parking and retry backoff.
team_workflow_gateApprove or reject a pending gate.
team_workflow_delegateClaim a single-outcome task, spawn a subagent to do it, record the result.

team_workflow_delegate is fire-and-forget: it returns once the child starts and the plugin records completion when that child settles. Poll team_workflow_status for progress. Stages with several outcomes (for example a review with pass / needs_revision) are decided explicitly with team_workflow_complete or team_workflow_gate.

Configuration (profile patch):

KeyDefaultMeaning
dataDirplatform user-data dirRoot for per-session state: /sessions/.
boardPort7171Board port; falls back to an ephemeral port when busy.
autoBoardtrueStart/restart the board after team_workflow_define.
subagentProviderspawnSubagent provider used by team_workflow_delegate.

The standalone board and CLI read one session directory explicitly:

atw board --data "$LOCALAPPDATA/agent-team-workflow/sessions/"
atw status --data "$LOCALAPPDATA/agent-team-workflow/sessions/"

Embedded panel

Installing the bundle also registers a native Web GUI panel (dsh.client, lib/client.js): after restarting the host, a 工作流 entry appears in the conversation header, and the same tab is available in the right sidebar. The panel is React, not an iframe:

  • the tab is bound to the session that opened it; each session has its own workflow;
  • it renders the session workflow as a collapsible DAG: stages layered by dependency depth, outcome labels and loops around the side, gate markers; clicking a node filters the task list to that stage;
  • it reads and writes through same-origin /plugins/dsh-agent-team-workflow/api/* routes registered by the host plugin, so it works in the Electron and browser clients without CORS;
  • approving/rejecting a gate and adding a task call the same engine paths as the tools. It never merges, closes or pushes.

Workflow state is session-scoped under /sessions/. Two sessions opened in the same directory get independent workflows. A session with no workflow shows an empty state instead of creating one.

The standalone board below remains for headless/CLI use.

Board

board serves a local page plus a small JSON API. It binds to 127.0.0.1 by default and has no authentication because it is loopback-only.

node src/cli.mjs board --port 7171
  • Columns are the workflow stages in traversal order; cards are items.
  • A card shows its current task, member, lane and attempt count; details expand to the task contract and result.
  • Pending gates appear both on the card and in 待决策, with approve/reject actions that append events. There is no merge, close or push action.
  • 模型线路 shows lane health, active/concurrency and the blocked-until time.
  • The page polls every 3 seconds (paused when the tab is hidden); only the JSON projection is read.

API: GET /api/board, POST /api/gate, POST /api/enqueue, POST /api/expire, GET /api/health.

How work runs

The engine does not start agents. A worker pulls work, does it, and reports back:

node src/cli.mjs enqueue "Add retry to the uploader" --input '{"prompt":"..."}' --json
node src/cli.mjs claim --role engineer --member engineer-1 --json
node src/cli.mjs complete --attempt attempt-… --outcome complete --result '{"summary":"…"}'
# or, when the attempt failed:
node src/cli.mjs fail --attempt attempt-… --error "tests failed"
  • claim runs admission, task selection and the attempt write in one SQLite transaction; two workers cannot both claim past a free slot.
  • An attempt is a capability: only its holder can complete or fail that task, and repeating the same call is a no-op.
  • A crashed worker leaves a lease behind. expire (or the board's reaper) fails those attempts and releases the task with the policy's backoff.
  • A blocking gate pauses the item after the stage completes; approving advances it, rejecting blocks it for a human.

Providers and failover

Each role may list several providers, and a stage may narrow that pool:

{
  "roles": [
    { "id": "engineer", "instances": 3, "providers": ["lane-a", "lane-b", "lane-c"] }
  ],
  "stages": [
    { "id": "implement", "role": "engineer", "providers": ["lane-a", "lane-b"] }
  ]
}
  • claim without --provider picks the least-loaded healthy lane in the allowed pool, so a lane is chosen per task rather than pinned to a worker.
  • claim --provider lane-a is an explicit request. A blocked or over-capacity lane is refused with an actionable error; it is never silently replaced.
  • fail classifies quota/rate-limit/timeout errors (429, 402, 5xx, quota, rate limit, timed out, …) and parks that lane until now + backoffMinutes[0]. The task is released immediately, so the next claim moves it to another lane. Use --provider-error to force this for a message the heuristic does not recognize.
  • A parked lane becomes usable again when blockedUntil passes; the board and status report it as healthy at that point. Keys are never rotated.

Nodes and executors

A node is one stage in the definition. It is control-flow data, not a running process:

{
  "id": "review",
  "title": "审查",
  "role": "reviewer",
  "executor": "agent",
  "options": ["pass", "needs_revision"],
  "on": { "pass": "ready", "needs_revision": "draft" },
  "providers": ["lane-a", "lane-b"],
  "maxAttempts": 3
}
  • role decides who may claim the task; the role's kind and providers narrow the worker type and lane pool.
  • executor is either agent (default) or external. An agent stage may be delegated to a model subagent with team_workflow_delegate; an external stage is pulled by a script, automation or human through team_workflow_claim / team_workflow_complete.
  • The plugin does not embed shell commands. A script worker is a process you run next to the workflow; it claims an attempt and reports back. That is deliberate: execution stays outside the engine and works with any runner.
  • options / on define the review mechanism: a review stage returns pass or needs_revision, and the graph loops or advances accordingly.
  • gates are the user-verification mechanism. A manual gate pauses the item after a stage/outcome; approve/reject it from the panel or team_workflow_gate. Pending gates show their wait time, but there is no built-in push/reminder scheduler yet.
  • Provider lanes are real execution hints for delegated agents: when a stage claims a lane, the lane's adapter, model, reasoningEffort and maxTokens are passed to the subagent as agentOptions. Omit them (or use model: "host-default") to inherit the host default.
  • Several lanes per role/stage give least-loaded selection; a provider error parks that lane and releases the task so the next claim can use another lane. The caller (or model) re-delegates to use the fallback.

Definition

{
  "apiVersion": 1,
  "name": "dev-team",
  "roles": [
    { "id": "analyst",  "instances": 3, "providers": ["lane-a", "lane-b", "lane-c"] },
    { "id": "engineer", "instances": 3, "providers": ["lane-a", "lane-b", "lane-c"] },
    { "id": "reviewer", "instances": 3, "providers": ["lane-a", "lane-b", "lane-c"] }
  ],
  "providers": [
    { "id": "lane-a", "model": "deepseek-flash", "concurrency": 3, "backoffMinutes": [10, 30, 60] },
    { "id": "lane-b", "model": "deepseek-flash", "concurrency": 3, "backoffMinutes": [10, 30, 60] },
    { "id": "lane-c", "model": "deepseek-flash", "concurrency": 3, "backoffMinutes": [10, 30, 60] }
  ],
  "stages": [
    { "id": "specify",   "role": "analyst",  "on": { "complete": "implement" } },
    { "id": "implement", "role": "engineer", "on": { "complete": "review" } },
    { "id": "review",    "role": "reviewer", "options": ["pass", "needs_revision"],
      "on": { "pass": "approved", "needs_revision": "implement" } },
    { "id": "approved",  "role": "reviewer" }
  ],
  "gates": [
    { "id": "merge", "after": "review", "outcome": "pass", "kind": "manual" }
  ],
  "policies": {
    "concurrency": { "global": 9 },
    "fallback": { "sameRole": true },
    "retry": { "maxAttempts": 3, "backoffSeconds": [30, 120, 300] }
  }
}
  • entry defaults to the first stage. A stage without on transitions is terminal, and a definition must declare at least one.
  • on maps an outcome to the next stage. If options is omitted, its keys are the allowed outcomes; if present, every on key must be declared.
  • A gate may target one outcome (outcome: "pass"), so a review loop does not trigger the merge decision on needs_revision.
  • Definitions are stored as authored and validated again on load, so a model can revise one and a human can review the diff.

Guarantees

  • The event log is the only write path; projections are derived and rebuildable.
  • claim is atomic across processes; a member cannot exceed its per-member capacity, and a role cannot exceed its total slots.
  • Provider degraded stops new dispatch; blocked expires at blockedUntil. Existing tasks are left alone.
  • Gates only record decisions. No merge, close, push or branch rewrite exists in the engine or the board.
  • The single-instance lock is stale-aware: a dead process on the same host or an old heartbeat can be taken over.
  • No credentials are read or stored. Providers are ids; hosts own secrets.

CLI reference

CommandPurpose
init [file]Write the bundled dev-team workflow (refuses to overwrite).
validate Validate and summarize a definition.
define Record the definition in the event log (takes the lock).
status / rosterProjected counts, slots, lanes and attention items.
boardServe the kanban board and JSON API.
enqueueCreate an item at the entry stage.
claimClaim the next ready task for a role (optionally a lane).
complete / failReport an attempt, advance or retry.
gateApprove or reject a pending gate.
expireReap attempts whose lease expired.
events / rebuildInspect or replay the event log.
simulateRun the scheduler over synthetic tasks.

State location

Default root: %LOCALAPPDATA%\agent-team-workflow (Windows), ~/Library/Application Support/agent-team-workflow (macOS), $XDG_DATA_HOME/agent-team-workflow or ~/.local/share/agent-team-workflow (Linux). Every DSH session stores its workflow under sessions/; the tools resolve the session automatically. Override the root with dataDir or AGENT_TEAM_WORKFLOW_DATA. The standalone CLI takes --data DIR pointing at one session directory.

Roadmap

PhaseScope
P1Definition schema, event store, lock, roster/status, scheduler simulation — done
P2Pull-mode lifecycle, attempt leases, retry backoff, gates, recovery — done
P3Provider failover, local kanban board, workflow scaffolding — done
P4DSH plugin: `te