wxxb789/dsh-legion 预览 preview

wxxb789/dsh-legion

插件Plugin 原生Native ⭐ 3 MIT 代理编排Agent Orchestration编程Coding

DeepSeek Harness 的多代理团队、模型路由与声明式编排

项目介绍Project Overview

dsh-legion 是 DeepSeek Harness 的多智能体编排插件。它将单一编码智能体转换为有界智能体团队,通过 legion 工具按 quick、deep、review 等语义 Profile 路由到精确的模型与子智能体后端,并支持声明式 Teams 与 Strategies、结构化结果及深度受限的委派。适用于在 DSH 内复用委派策略、按任务类型分派不同模型或运行独立审查。注意:它不是独立智能体框架,依赖 DSH 运行时;且不提供聚合 token 或货币成本准入控制。

dsh-legion is a multi-agent orchestration plugin for DeepSeek Harness. It turns one coding agent into a bounded team by exposing a legion tool that routes to semantic Profiles such as quick, deep, and review, each binding a model route, subagent backend, persona, tool filter, depth, and result contract. Use it inside DSH to standardize delegation, run independent reviews, or compose declarative Teams and Strategies. Note: it is a plugin, not a standalone framework, and it does not provide aggregate token or monetary-cost admission control.

或使用命令行安装(适合开发者)Or use CLI install (for developers)

命令行安装CLI Install

dsh plugin --profile web add github:wxxb789/dsh-legion

wxxb789/dsh-legion 加入你的 DSH 配置(web profile)即可启用。

READMEREADME

dsh-legion: Multi-Agent Orchestration and LLM Model Routing for DeepSeek Harness

English · 简体中文

dsh-legion architecture: a coordinator agent calls one legion tool, which routes to quick, deep, and review Specialists that run as native DeepSeek Harness subagents

CI License: MIT Node.js TypeScript DSH plugin

dsh-legion is a TypeScript multi-agent orchestration plugin for DeepSeek Harness (DSH). It turns one AI coding agent into a bounded orchestration cohort: configurable AI agent Specialists, an exact LLM model router, declarative Cohorts and Strategies, structured results, and depth-limited subagent delegation — without replacing the DSH runtime.

TL;DR

  • What it is. A DeepSeek Harness plugin for multi-agent delegation policy — not a standalone agent framework.
  • What it adds. One model-facing legion tool whose choices are semantic Specialists such as quick, deep, and review. Each Specialist carries a deployment-owned model route, subagent backend, persona, tool filter, depth, and result contract.
  • Why it helps. The coordinating agent picks intent instead of model IDs, a prompt can never widen the policy behind a Specialist, and changing the model behind deep rewrites no prompts.
  • What it costs. One configuration row in a user-owned agent preset. No extra scheduler, session store, database, or agent runtime.
  • Who it is for. Developers and deployment owners already running DSH who want reviewable, reusable multi-agent delegation.

Important: Legion is a DSH plugin, not a standalone agent framework or application. DeepSeek Harness supplies the Agent, Session, model adapters, subagent runtime, sandbox, approvals, and Web GUI.

Quick start

# 1. Install the plugin into a DSH host profile (append #<commit-sha> to pin a revision)
dsh plugin --profile web add github:wxxb789/dsh-legion

# 2. Copy the Legion row into a user-owned agent preset, then start a NEW session
#    template: examples/legion.agent.cordis.fragment.yml

# 3. Validate the routing policy before you depend on it
dsh-legion doctor examples/legion.config.yml --providers examples/providers.fixture.yml

The coordinator now sees one legion tool whose specialist values are your semantic delegation choices. Step-by-step instructions are in Install and Set up a Legion agent preset.

Contents

What is dsh-legion used for?

Legion is useful when one AI coding agent should delegate different kinds of work under explicit, reusable policy.

  • Route work by task type. Send extraction or summaries to a fast model and architecture or debugging to a deeper model.
  • Run independent reviews. Give a reviewer read-only tools, a separate persona, and a structured review-v1 result.
  • Build multi-agent workflows. Define bounded Cohorts and declarative plan/execute/review or research fanout Strategies.
  • Bound workload and risk. Limit depth, concurrency, participants, deadlines, output size, tools, and eligible routes. These bounds constrain cost drivers, but Legion does not provide aggregate token or monetary-cost admission.
  • Standardize delegation. Keep semantic Specialist names stable when the underlying model or backend changes.
  • Validate policy before runtime. Diagnose configuration against explicit provider capability fixtures.
  • Customize without forking. Add, replace, disable, or revive Specialists, Cohorts, and Strategies through Catalog Layers.

Legion is for developers and deployment owners who already use DSH and want configurable multi-agent delegation without adopting another scheduler, session store, or agent runtime.

dsh-legion vs standalone multi-agent frameworks

Standalone multi-agent frameworks such as LangGraph, CrewAI, and AutoGen ship their own runtime, state model, and process lifecycle, so adopting one places a second orchestrator beside the coding agent you already run. Legion takes the opposite approach: it adds no runtime at all and compiles delegation policy down to native DSH subagents.

dsh-legion A standalone agent framework
What you adopt Delegation policy for an agent you already run A second runtime, state model, and process lifecycle
Who owns the agent loop DeepSeek Harness The framework
Sessions, sandbox, approvals, model adapters DSH-owned and unchanged Framework-owned, parallel to your agent's
Model selection Ordered exact provider/model Route Candidates per Specialist Usually wired per node or per agent in code
Cost to adopt One configuration row in a user-owned preset A new dependency tree, service, or process
Prompt authority A prompt selects a Specialist and can never widen that Specialist's model, tools, persona, or depth Varies by framework
Wrong tool when You do not run DSH You want one self-contained orchestrator

If you are not running DeepSeek Harness, Legion is not the right tool, and a standalone framework is the better fit.

Capabilities

Capability What it provides
Semantic Specialists Named policies such as quick, deep, and review instead of raw model choices in every prompt.
Exact model routing Up to eight ordered provider/model candidates with static context and output-budget constraints.
Multiple backends Use spawn, fork, codex, claude-code, or another DSH-registered subagent provider per Specialist.
Tool and persona policy Restrict child tools, add Specialist instructions, set depth, and choose foreground/background defaults.
Structured results Versioned text, findings-v1, and review-v1 foreground result contracts.
Custom Cohorts Declare bounded Member Slots that reference existing Specialists.
Declarative Strategies Compile typed artifact graphs to frozen DSH delegation primitives.
Hard limits Bound agents, concurrency, deadline, and accepted output size for each Cohort Run.
Catalog customization Layer, replace, disable, and restore user or third-party catalog entries.
Prompt Fragments Load confined, immutable UTF-8 prompt resources from deployment-owned roots.
Explainable policy Stable digests, deterministic diagnostics, route evidence, and JSON explain output.
Live reconfiguration Optional: when the Host mounts a settings provider, edit the same config through the legion namespace and republish without a restart.
Web settings card A plugin card on the DSH Settings → Plugins tab, with staged edits and override badges. See the settings card.
ACP delegation Optional Specialists for Codex, Claude Code, oh-my-pi, Kimi Code, Grok Build, Pi, GitHub Copilot CLI, Hermes, and ZCode over DSH's ACP backend. See ACP delegation.
Native DSH lifecycle Continuations, cancellation, settlement, providers, and HMR-safe registration remain DSH-owned.

How it works

Catalog Layers
  ├─ Specialists   -> model routes, backend, persona, tools, result contract
  ├─ Cohorts      -> bounded Member Slots referencing Specialists
  └─ Strategies -> typed artifact graph + hard limits
                         │
                         ▼
                frozen DSH primitive IR
                         │
                         ▼
                 native DSH subagents

A typical model-facing Specialist call is small:

{
  "specialist": "quick",
  "description": "summarize findings",
  "prompt": "Summarize the investigation and preserve source paths.",
  "run_in_background": true
}

The coordinator chooses a semantic Specialist; the prompt cannot change that Specialist's deployment-owned model, tools, persona, depth, or result policy.

Legion intentionally does not own the agent loop, sessions, persistence, model adapters, credentials, sandbox, approvals, subagent registry, or Web GUI. It uses DSH's public ctx.subagents, ctx.tools, and ctx.systemPrompt seams so there is only one runtime and lifecycle owner.

Under the hood: from tool call to child agent

Activation, when DSH mounts the plugin on a Cordis fiber:

  1. Legion validates the configuration against a strict schema that rejects unknown fields anywhere in the document.
  2. Catalog Layers merge in order: a later layer replaces an earlier entry by name, a tombstone disables an inherited one, and any later definition of that name revives it.
  3. Prompt Fragments referenced by Specialists are read once, under a per-Specialist byte budget, and captured as an immutable snapshot with a content digest.
  4. Legion observes which subagent backends and which LLM adapters the Host currently has registered.
  5. Each Specialist is compiled against that observation and becomes active only if its configured backend can actually satisfy the Specialist's policy: execution mode, tool filtering, persona, depth, and structured output.
  6. The delegation tool is published with a parameter schema derived from the active Specialists, and a matching routing table is contributed to the system prompt.
  7. If no Specialist is active, the tool is withdrawn and the guidance renders empty. The whole sequence reruns whenever backends or adapters change.

One delegation, between the coordinator's tool call and the returned result:

  1. Arguments are validated and resolved to exactly one Specialist: the one named, or the configured defaultProfile.
  2. If that Specialist declares routes, Legion reads each candidate's exact-model metadata and takes the first candidate in your authored order that no static fact contradicts.
  3. Only static facts participate, such as context window and output budget. A candidate whose metadata cannot be read stays eligible; the call fails only when every candidate is positively ruled out.
  4. Legion starts exactly one child through the Host's subagent API with the Specialist's fixed policy applied, and never retries or switches routes when that child or its provider fails.
  5. A background call returns a continuable child id immediately; a foreground call waits, revalidates a structured result against its contract, and rebuilds it as fresh plain data before returning.

Two properties follow from that design and are worth stating plainly. Compiled Cohort and Strategy IR is deep-frozen and detached: it holds no reference to your configuration objects and carries no functions. A compiled Strategy plan is also tracked by object identity in a process-wide registry, so execution accepts only a plan this process compiled — a reconstructed or deserialized copy is rejected even when its contents and digest are identical.

Install

Prerequisites

  • A compatible DeepSeek Harness installation.
  • pnpm on PATH; dsh plugin forwards package operations to pnpm.
  • A DSH Host profile, such as the default web composition.
  • A configured DSH subagent provider and the LLM provider/model routes referenced by your Specialists.
  • For local development: Node.js ^22.19.0 || >=24.0.0 and pnpm 11.21.0.

Install from GitHub

Install the default branch into the web Host composition:

dsh plugin --profile web add github:wxxb789/dsh-legion

Replace web if Legion should be available in another DSH Host profile.

This resolves main once, at install time. dsh plugin forwards to pnpm, which records the resolved commit in the Host profile lockfile, so the installed revision does not follow later pushes until you upgrade explicitly.

Pin a revision

A git install runs Legion's prepare build on your machine, outside any sandbox the agent runs under. Append an immutable revision whenever the installed code has to stay auditable and reproducible — production Host compositions, shared machines, or a deployment where you review what you allow to build:

dsh plugin --profile web add github:wxxb789/dsh-legion#<commit-sha>

No release tag is published yet. After a version appears on GitHub Releases, that release's tag is an immutable installation spec too.

Git dependencies run Legion's prepare build. pnpm 10+ may reject the first install until the package is explicitly allowed. Add the exact key printed by pnpm to $DSH_HOME/profiles/web/pnpm-workspace.yaml, then repeat the install:

allowBuilds:
  dsh-legion: true

If pnpm prints a source-qualified key, use that exact key instead of the short name.

Install from a local checkout

git clone https://github.com/wxxb789/dsh-legion.git
cd dsh-legion
pnpm install --frozen-lockfile
pnpm run build
dsh plugin --profile web add .

A local checkout needs built lib/ artifacts, and the consequence of skipping the build has changed: because the bundle patch makes dsh-legion a Host loader entry, the Host's client module registry now scans it, and a missing lib/client.js fails Host activation loudly rather than merely leaving the card out. Run pnpm run build before installing a checkout. Installation still injects no process-global model tool — the delegation tool stays on the agent plane, where a preset asks for it. The bundle patch now mounts one Host-plane row, id: legion-settings with role: settings, so the legion settings namespace and its Web card belong to the process instead of existing only while a session using the preset is alive.

Set up a Legion agent preset

Installing the package is only the first step. Legion must also be loaded by an agent preset.

Recommended: extend your existing preset

  1. Open the DSH Web GUI.
  2. Copy the shipped standard preset to a user-owned preset named legion.
  3. Append the Legion row from the example fragment.
  4. Adjust provider names, model IDs, tools, and limits for your deployment.
  5. Start a new session with the legion preset.

Do not edit DSH's shipped standard preset directly.

Alternative: copy the bundled preset

Copy presets/legion to $DSH_HOME/.agent-presets/legion. It contains a focused coding tool set and example deep, quick, and review Specialists.

A copied preset is a versioned template. It does not automatically inherit later DSH or Legion changes. Existing nonblank sessions also cannot change their recorded preset, so start a new session after changing composition.

Upgrade

GitHub installation

A branch installation re-resolves to the current main commit through pnpm's update command, which DSH forwards:

dsh plugin --profile web update dsh-legion

A pinned installation stays on its recorded revision by design. Move it by adding the new exact revision — a later release tag works the same way:

dsh plugin --profile web add github:wxxb789/dsh-legion#<new-commit-sha>

After upgrading:

  1. Review CHANGELOG.md.
  2. Compare your user-owned preset with the current example; Legion never overwrites presets automatically.
  3. Restart the affected DSH process. If the preset composition changed, start a new session.

Local checkout

cd dsh-legion
git pull --ff-only
pnpm install --frozen-lockfile
pnpm run build
dsh plugin --profile web add .

Uninstall

Remove Legion from every DSH Host profile where it was installed:

  1. Remove or disable the name: dsh-legion row in user-owned agent presets. Removing the package in the next step removes the bundle layer that contributes the legion-settings row; a row you copied by hand into a composed cordis.yml is yours to remove there.

  2. Remove the package:

    dsh plugin --profile web remove dsh-legion
    
  3. Optionally delete $DSH_HOME/.agent-presets/legion if that copied preset is no longer needed.

  4. Restart the affected DSH process.

Package removal does not delete user-owned presets or configuration.

Usage

Delegate through a Specialist

The coordinator sees one legion tool plus active Specialist descriptions:

{
  "specialist": "review",
  "description": "review the authentication change",
  "prompt": "Inspect the diff for correctness and security issues. Cite files and lines.",
  "run_in_background": false
}

If defaultProfile is configured, specialist may be omitted. Concurrent sibling calls use DSH's normal parallel tool execution.

Run a Strategy

Strategies are hidden by default. A deployment must explicitly set enableStrategies: true. The same tool then accepts a strict Strategy request:

{
  "kind": "strategy",
  "strategy": "independent-review",
  "objective": "Review the implementation and return evidence-backed findings.",
  "limits": { "deadlineMs": 60000 }
}

Specialist and Strategy fields cannot be mixed. Invocation limits may only narrow compiled Strategy limits.

Configuration

A minimal agent-preset row:

- id: tool-legion
  name: dsh-legion
  config:
    configVersion: 2
    toolName: legion
    defaultProfile: quick
    specialists:
      quick:
        description: Fast exploration, extraction, and summaries.
        subagentProvider: spawn
        agentOptions:
          provider: your-llm-provider
          model: your-fast-model
          maxTokens: 8192
        maxDepth: 2
        defaultRunInBackground: true

      review:
        description: Independent correctness and security review.
        subagentProvider: spawn
        agentOptions:
          provider: your-llm-provider
          model: your-review-model
        toolFilter:
          deny: [write, edit]
        maxDepth: 2
        defaultRunInBackground: false
        result: review-v1

Use valid provider and model IDs for your deployment. See the complete preset fragment and standalone configuration example.

When the Host mounts a settings provider (DSH 0.1.0-rc.7 serves every registered namespace), the legion settings namespace is owned by the Host-plane row the bundle patch installs, and it publishes this same schema. The preset row above stays the base layer for its own delegation surface: it applies the stored user section over its own entry, and a commit republishes that tool without restarting DSH. Nothing changes in a composition without a settings provider. See live reconfiguration and the settings card.

To delegate to an external coding agent — Codex, Claude Code, Kimi Code, GitHub Copilot CLI, and others — mount DSH's ACP backend once per agent and append the generated catalog layer. See ACP delegation and examples/legion.acp.fragment.yml.

Top-level fields

Field Default Meaning
role delegation Composition role of this row, read from the row's own entry and never from the settings layer. A settings row registers the legion namespace and nothing else — no tool, no prompt section, no projection, no service.
configVersion 2 Current configuration contract. Omitted or 1 is accepted and normalized to 2; a v1 document that uses catalogLayers, cohorts, strategies, enableStrategies, or durable runs is rejected at activation instead of upgraded.
toolName legion Model-facing tool name.
specialists required Semantic Specialist map.
defaultProfile none Specialist used when a call omits specialist.
enableRunInBackground true Expose background delegation.
enableStrategies false Explicitly expose active Strategies to the model.
guidance none Extra coordinator guidance.
resourceRoots {} Relative deployment roots for Prompt Fragments.
maxResourceBytes 65536 Prompt Fragment bytes per Specialist; hard ceiling 4 MiB.
catalogLayers [] Ordered third-party or project policy layers.
cohorts {} Final deployment-layer Cohorts.
strategies {} Final deployment-layer Strategies.

Specialist names must match ^[a-z][a-z0-9-]*$.

Specialist fields

Field Default Meaning
description required Task-fit guidance shown to the coordinator.
subagentProvider spawn DSH subagent backend, not an LLM provider.
agentOptions inherited Fixed provider, model, and maxTokens; cannot be combined with routes.
routes none Up to eight ordered exact Route Candidates.
persona inherited Child persona/system-policy override.
toolFilter.allow / deny none Child tool visibility restriction.
maxDepth 3 Child depth or provider-managed for external one-shot products.
defaultRunInBackground true Default to a continuable child.
result text text, findings-v1, or review-v1.
promptFiles none Ordered Prompt Fragments loaded after validation.

For codex and claude-code, model selection belongs to the external product. Normally use maxDepth: provider-managed and defaultRunInBackground: false.

Exact Route Candidates

routes:
  - id: primary
    provider: your-llm-provider
    model: your-deep-model
    maxTokens: 16384
    constraints:
      minContextTokens: 65536
      minEffectiveOutputTokens: 8192
  - id: fast-static
    provider: your-llm-provider
    model: your-fast-model
    constraints:
      minContextTokens: 32768

Immediately before child start, Legion observes registered DSH adapters and exact-model metadata. It selects the first candidate without a known static contradiction. Missing metadata remains unknown and admissible; Legion never turns absent metadata into a health claim.

Legion starts at most one child and never retries another route after provider, authentication, quota, network, or child failure.

Catalog Layers, Cohorts, and Strategies

Config v2 layers Specialists, Cohorts, and Strategies. A later definition replaces the same name; a tombstone disables it; a later definition may revive it. Root maps are the final deployment layer.

configVersion: 2
cohorts:
  coding:
    description: One executor and one reviewer.
    members:
      executor: { profile: deep }
      reviewer: { profile: review }
strategies:
  reviewed:
    description: Execute and review.
    team: coding
    stages:
      - kind: delegate
        id: execute
        member: executor
        inputs: [{ artifact: objective, contract: objective-v1 }]
        output: { artifact: execution, contract: text }
        prompt: Execute and return evidence.
      - kind: delegate
        id: review
        member: reviewer
        inputs: [{ artifact: execution, contract: text }]
        output: { artifact: review, contract: review-v1 }
        prompt: Review the evidence independently.
    completion: { artifact: review, contract: review-v1 }
    limits:
      maxAgents: 2
      maxConcurrent: 1
      deadlineMs: 900000
      maxOutputBytes: 524288
    memberFailure: fail

Legion validates the artifact graph and lowers accepted stages to detached, deep-frozen DSH primitive IR. It is an adapter over DSH one-shot subagents, not a persistent scheduler. The Default Catalog includes independent-review, research-panel, and plan-execute-review as ordinary replaceable data, with model exposure off by default.

See benchmarks/README.md for deterministic protocol gates and separate real-model evidence requirements.

Prompt Fragments, structured results, and trust

Prompt Fragments are explicit deployment resources, not arbitrary workspace reads. Legion confines relative paths below configured roots and rejects links, malformed UTF-8, NUL bytes, missing files, and byte-budget violations. Edits require plugin or preset reactivation.

Structured foreground contracts are deliberately narrow:

  • findings-v1: summary, evidence-backed findings, decisions, verification, and open risks;
  • review-v1: verdict, severity findings, recommendations, and verification;
  • background continuations remain text/session oriented.

Presets, Catalog Layers, plugin packages, resource roots, and Prompt Fragments are trusted deployment configuration. Tool filters and path confinement enforce policy and integrity for that trusted deployment; they are not a sandbox for hostile presets or untrusted plugins. See SECURITY.md.

Tool presentation (Code Mode / PTC mode)

The bundled preset runs in Code Mode. Whether a model sees every tool schema (native), only run_code plus a generated TypeScript SDK (code — the Web client labels this PTC mode), or both is decided by the official @deepseek-ai/dsh-agent-tool-presentation row, falling back to the deployment's dsh-tools default. Coordination is the work Code Mode is best at: one run_code program starts several delegations together, waits on them as values, and reduces their results without a model round trip per child — the guidance Legion injects ("start independent delegations together") is a suggestion under native and an ordinary Promise.all here.

Legion selects it by composing that row, never by reimplementing it, and owns no part of the mechanism in its own source — so it always runs the current official Code Mode, with no version to pin or lag behind. There is deliberately no Legion setting for this: a plugin key would compete with the official row for one decision.

Delegated children inherit the same presentation. dsh-agent-presets re-parents a child agent's scope onto the parent's preset standing scope, and the registry resolves the mode along that chain — so a child of a PTC-mode Legion coordinator is itself in PTC mode, with the SDK section regenerated for that child's own visible tools.

Specialist toolFilter keeps its meaning under Code Mode. The SDK binding table is built from the calling agent's visible set, so a denied capability never appears in the generated SDK, and a call naming it from inside run_code still resolves to UNKNOWN_TOOL: the review Specialist's deny of write/edit holds in both presentations. Two boundaries belong to the Host's design rather than Legion's — run_code itself can never be denied, and a filter constrains only the surface a child inherits, never the tools that child's own scope registers (its report and structured-output tools).

Which path you took decides where the row lives. The bundled preset (presets/legion) owns its whole composition and carries it. The append-to-your-preset fragment (examples/legion.agent.cordis.fragment.yml) carries none, because one composition selects one presentation and a second declaration is refused rather than merged — appending it to the official code preset gives you PTC mode, appending it to standard gives you native, and Legion follows either.

The row waits for the host's codeRuntime rather than assuming it, so a deployment that composes no TypeScript runtime fails the preset at mount, naming the row, instead of at the first request. Read that as install the runtime, not turn Code Mode off: Legion is a development coordinator and this is the mode it is built for. The runtime is host-plane — a preset can select the presentation but can never supply it — so the fix belongs in your Host composition (cordis.yml):

- id: code-runtime
  name: '@deepseek-ai/dsh-code-runtime-worker-thread'

Both shipping bundles compose one already, so this only comes up on a hand-assembled deployment. Legion says the same thing at runtime: mounted where nothing composes a codeRuntime, it logs that package name and keeps working in the native presentation rather than failing. mode: native is for deliberately wanting native tools, not for working around a missing runtime.

Doctor and explain

Validate a standalone Legion config against an explicit provider fixture:

dsh-legion doctor examples/legion.config.yml --providers examples/providers.fixture.yml
dsh-legion explain examples/legion.config.yml --providers examples/providers.fixture.yml --json

doctor prints a compact summary; explain adds Specialists, execution modes, model routes, result contracts, and diagnostic codes. --json emits the versioned legion-explain view.

The fixture proves only supplied static facts. The CLI does not inspect a live DSH process, credentials, reachability, health, quota, billing, latency, or actual model availability.

Exit codes: 0 for no error diagnostic, 1 for capability errors, and 2 for usage, I/O, resource, parse, or schema failures.

Status and limitations

The source tree declares version 1.2.0 and config contract v2. Check CHANGELOG.md, the roadmap, and GitHub Releases before selecting or upgrading an install revision.

Known limitations:

  • Curated Strategies are not automatically model-exposed; deployment owners may opt in with enableStrategies: true.
  • Legion does not retry or switch models after a selected child fails.
  • In-process children inherit the parent's named DSH agent preset; Specialists can still vary model, persona, tools, backend, and limits.
  • The GUI settings card edits four scalar policies; Specialists, Cohorts, Strategies, and catalog layers stay in the configuration document.
  • The card's browser half reproduces DSH's unpublished client bundle format by hand, so an upstream change to that format fails at load time rather than at build time.
  • The Specialist result schema still accepts plan-delta-v1, a contract meant for durable-run plan proposals rather than ordinary delegation. Treat it as unsupported for Specialists until it is either gated or deliberately published.
  • A bare package without compatible DSH peers is unsupported.

FAQ

Is dsh-legion a standalone multi-agent framework?

No. It is a DeepSeek Harness plugin for multi-agent policy and delegation. DSH remains the runtime and lifecycle owner.

How does it compare with LangGraph, CrewAI, or AutoGen?

Those frameworks ship their own runtime, state model, and process lifecycle, so adopting one adds a second orchestrator beside your agent. Legion adds no runtime at all: it is declarative delegation policy for a DSH deployment you already run, compiled to native DSH subagents. See dsh-legion vs standalone multi-agent frameworks for the full comparison.

Which LLM providers and models can it route to?

Any provider and exact model that your DSH deployment registers as an adapter, named as ordinary configuration. Legion never embeds a provider list, credentials, or pricing: it checks ordered Route Candidates against known static capability facts and starts one child.

Can it delegate to Codex, Claude Code, or GitHub Copilot CLI?

Yes, through DSH's ACP backend. Legion ships an optional catalog layer with Specialists for Codex, Claude Code, oh-my-pi, Kimi Code, Grok Build, Pi, GitHub Copilot CLI, Hermes, and ZCode. See ACP delegation.

Does Legion automatically choose the cheapest or healthiest model?

No. It checks ordered routes against known static facts. It does not claim live health, price, authentication, quota, or latency, and does not replay after failure.

Can I create custom Specialists, Cohorts, and Strategies?

Yes. The Default Catalog uses the same public, replaceable contracts as user and third-party entries.

Why does the Legion tool disappear?

A Specialist is published only when its configured backend can actually satisfy that Specialist's policy: the execution mode it defaults to, plus tool filtering, persona, depth, and structured output. An unregistered subagent provider deactivates it, and so does a registered backend that cannot supply what the Specialist asks for — structured output for a findings-v1 Specialist, for example. If no Specialist qualifies, the tool is withdrawn and the guidance renders empty; both return once the missing capability appears. Also verify that Legion is installed into the intended Host profile and that a new session uses the preset containing its row.

Can I edit DSH's shipped standard preset?

Do not. Copy it to a user-owned preset so upgrades cannot overwrite your changes.

Compatibility, development, and releases

The package requires Node.js ^22.19.0 || >=24.0.0 and DSH peers in >=0.1.1-rc.1 <0.2.0. Legion tracks the current Host release line: the peer range, the declared minimum, the latest tested version, and the assessed-version list in contracts/compatibility.json advance together, and none of them advances alone. The range is anchored on a 0.1.1 prerelease comparator because semver admits a prerelease only against a comparator sharing its major.minor.patch, so every future 0.1.N-rc.x Host line enters the range only once it has been assessed. CI covers Windows, Ubuntu, packed DSH consumers, public contracts, protocol benchmarks, and reproducible packages.

pnpm install --frozen-lockfile
pnpm run check

Useful references:

Issues and contributions are welcome through the GitHub issue tracker.

Durable Strategy Runs (v1.1, opt-in)

Durable runs are disabled by default and preserve v1.0 ephemeral behavior. When enabled by deployment, a Strategy caller explicitly selects journal mode with execution: { durability: 'journal' }; omission remains ephemeral. They use eight typed events in the invoking DSH Session journal and projection key legion-run at state version 6. Run control supports bounded read-only inspect, one-activation resume, flushed cancel, and validated proposal-only steer. Task delivery is at least once; matching fence and generation permit exactly one accepted commit, not exactly-once external effects. Mail is reserved, incorporated, durably flushed when required, then acknowledged; expired reservations are reclaimable.

This package does not ship DSH persistence, projection, atomic coordination, global admission, or child-receipt Host services. Session flush and the projection registry are ordinary DSH services that the base composition already mounts; what no published DSH release provides is the atomic run coordination service, so production durable mutation stays unavailable. No build binds a durable Strategy activation adapter yet either, so journal mode cannot start on any Host. The execution parameter is therefore kept out of the model-facing schema, and a programmatic journal request fails closed: with the missing Host capability codes on a release such as 0.1.1-rc.2, and with LEGION_DURABLE_EXECUTION_ADAPTER_UNAVAILABLE on an otherwise fully capable Host. Enabling durable runs there produces stable capability diagnostics and fails closed before mutation; pure contracts, validation, replay, and inspection remain usable. See Durable Strategy Runs and Journal Contract v1.

Related projects

  • DeepSeek Harness (DSH) — the open-source agent harness that owns the Agent, Session, model adapters, subagent runtime, sandbox, approvals, and Web GUI that Legion plugs into.
  • Cordis — the plugin and service framework DSH is built on; Legion registers through ordinary Cordis fibers.
  • Agent Client Protocol — the protocol behind DSH's ACP backend, used by Legion's optional external-agent Specialists.
  • dsh-plugin topic — discover more DeepSeek Harness plugins.

If dsh-legion saves you work, starring the repository helps other DSH users find it.

License

MIT

上一个 Prev dsh-ds-attach 下一个 Next dsh2wechat