多智能体编排wxxb789/dsh-legion

dsh-legion：面向 DeepSeek Harness 的多智能体团队与模型路由

English · 简体中文

CI
License: MIT
Node.js

dsh-legion 是一个面向 DeepSeek Harness (DSH) 的 TypeScript 多智能体编排插件。它添加了可配置的 AI 智能体 Profile、精确的模型路由、声明式 Team 和 Strategy、结构化结果，以及有界的子智能体委派，而不会替换 DSH 运行时。

为一个 DSH 智能体提供一个精简而有意义的委派接口——例如 quick、deep 和 review——同时由部署负责人控制每个选项背后的模型、后端、工具、人设、限制和输出契约。

重要提示： Legion 是一个 DSH 插件，而不是独立的智能体框架或应用。DeepSeek Harness 提供 Agent、Session、模型适配器、子智能体运行时、沙箱、审批和 Web GUI。

目录

- dsh-legion 用于什么？
- 能力
- 工作原理
- 安装
- 设置 Legion 智能体预设
- 升级
- 卸载
- 用法
- 配置
- Doctor 与 explain
- 状态与限制
- FAQ

dsh-legion 用于什么？

当一个 AI 编程智能体需要在明确、可复用的策略下委派不同类型的工作时，Legion 非常有用。

- 按任务类型路由工作。 将提取或摘要发送到快速模型，将架构或调试发送到更深入的模型。
- 运行独立审查。 为审查者提供只读工具、独立的人设，以及结构化的 review-v1 结果。
- 构建多智能体工作流。 定义有界的 Team 和声明式的 plan/execute/review 或 research fanout Strategy。
- 限制工作量和风险。 限制深度、并发、参与者、截止时间、输出大小、工具和可用路由。这些边界约束了成本驱动因素，但 Legion 不提供聚合 token 或货币成本准入。
- 标准化委派。 当底层模型或后端发生变化时，保持语义化 Profile 名称稳定。
- 在运行时之前验证策略。 根据明确的提供方能力 fixture 诊断配置。
- 无需 fork 即可自定义。 通过 Catalog Layer 添加、替换、禁用或恢复 Profile、Team 和 Strategy。

Legion 面向已经使用 DSH 的开发者与部署负责人，他们希望获得可配置的多智能体委派，而不必采用另一个调度器、会话存储或智能体运行时。

能力

| 能力 | 它提供什么 |
|---|---|
| 语义配置 | 使用 quick、deep 和 review 等命名策略，而不是在每个提示中直接选择原始模型。 |
| 精确模型路由 | 最多八个有序的提供商/模型候选，并带有静态上下文和输出预算约束。 |
| 多后端 | 每个 Profile 使用 spawn、fork、codex、claude-code 或其他 DSH 注册的子代理提供商。 |
| 工具与角色策略 | 限制子工具、添加 Profile 指令、设置深度，并选择前台/后台默认值。 |
| 结构化结果 | 版本化的 text、findings-v1 和 review-v1 前台结果契约。 |
| 自定义团队 | 声明引用现有 Profile 的有界成员槽位。 |
| 声明式策略 | 将类型化产物图编译为冻结的 DSH 委托原语。 |
| 硬性限制 | 为每次团队运行限制代理数量、并发数、截止时间和可接受的输出大小。 |
| 目录自定义 | 对用户或第三方目录条目进行分层、替换、禁用和恢复。 |
| 提示片段 | 从部署拥有的根目录加载受限的、不可变的 UTF-8 提示资源。 |
| 可解释策略 | 稳定的摘要、确定性的诊断、路由证据和 JSON 解释输出。 |
| 实时重新配置 | 可选：当 Host 挂载设置提供程序时，通过 legion 命名空间编辑同一配置并重新发布，无需重启。 |
| Web 设置卡片 | DSH 设置 → 插件选项卡上的插件卡片，带有暂存编辑和覆盖徽章。参见设置卡片。 |
| ACP 委托 | 通过 DSH 的 ACP 后端为 Codex、Claude Code、oh-my-pi、Kimi Code、Grok Build、Pi、GitHub Copilot CLI、Hermes 和 ZCode 提供可选 Profile。参见 ACP 委托。 |
| 原生 DSH 生命周期 | 延续、取消、结算、提供程序和 HMR 安全注册仍由 DSH 拥有。 |

工作原理

~~~text
目录层
├─ Profiles   -> 模型路由、后端、角色、工具、结果契约
├─ Teams      -> 引用 Profile 的有界成员槽位
└─ Strategies -> 类型化产物图 + 硬性限制
│
▼
冻结的 DSH 原语 IR
│
▼
原生 DSH 子代理
~~~

一个典型的面向模型的 Profile 调用很小：

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

协调器选择一个语义 Profile；提示无法更改该 Profile 由部署拥有的模型、工具、角色、深度或结果策略。

Legion 有意不拥有代理循环、会话、持久化、模型适配器、凭据、沙箱、审批、子代理注册表或 Web GUI。它使用 DSH 的公共 ctx.subagents、ctx.tools 和 ctx.systemPrompt 接缝，因此只有一个运行时和生命周期所有者。

安装

先决条件
- 一个兼容的 DeepSeek Harness 安装。
- PATH 中有 pnpm；dsh plugin 会将包操作转发给 pnpm。
- 一个 DSH 主机配置文件，例如默认的 web 配置文件。
- 一个已配置的 DSH 子代理提供程序，以及你的 Profiles 所引用的 LLM 提供程序/模型路由。
- 对于本地开发：Node.js ^22.19.0 || >=24.0.0 和 pnpm 11.21.0。

从 GitHub 安装

将一个不可变的提交 SHA 安装到 web 配置文件中：

~~~bash
dsh plugin --profile web add github:wxxb789/dsh-legion#
~~~

如果 Legion 应在另一个 DSH 主机配置文件中可用，请替换 web。目前尚未发布 release 标签，因此请使用提交 SHA 而不是会移动的分支。当版本出现在 GitHub Releases 上后，该 release 的标签也是一个不可变的安装规格。

Git 依赖项会运行 Legion 的 prepare 构建。pnpm 10+ 可能会拒绝首次安装，直到该包被明确允许。将 pnpm 打印出的确切键 添加到 $DSH_HOME/profiles/web/pnpm-workspace.yaml，然后重复安装：

~~~yaml
allowBuilds:
dsh-legion: true
~~~

如果 pnpm 打印出带来源限定的键，请使用该确切键而不是短名称。

从本地检出安装

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

本地检出需要已构建的 lib/ 产物。bundle 补丁有意为空：安装使 dsh-legion 可从用户拥有的代理预设中解析，但不会注入进程全局的模型工具。

设置 Legion 代理预设

安装包只是第一步。Legion 还必须由代理预设加载。

推荐：扩展现有预设

1. 打开 DSH Web GUI。
2. 将随附的 standard 预设复制为名为 legion 的用户拥有的预设。
3. 从 示例片段 中追加 Legion 行。
4. 根据你的部署调整提供程序名称、模型 ID、工具和限制。
5. 使用 legion 预设启动一个新会话。

不要直接编辑 DSH 随附的 standard 预设。

替代方案：复制捆绑的预设

将 presets/legion 复制到 $DSH_HOME/.agent-presets/legion。它包含一个专注的编码工具集以及示例 deep、quick 和 review Profiles。

复制的预设是一个带版本的模板。它不会自动继承后续的 DSH 或 Legion 更改。现有的非空会话也无法更改其记录的预设，因此在更改组合后请启动一个新会话。

升级

GitHub 安装

使用新的确切提交 SHA 重新添加该包。在 release 存在后，也可以改用更新的已发布 release 标签：

~~~bash
dsh plugin --profile web add github:wxxb789/dsh-legion#
~~~

对于注册表或移动引用安装，DSH 也会转发 pnpm 的更新命令：

~~~bash
dsh plugin --profile web update dsh-legion
~~~

升级后：

1. 查看 CHANGELOG.md。
2. 将你的用户自有预设与当前示例进行对比；Legion 从不自动覆盖预设。
3. 重启受影响的 DSH 进程。如果预设组成发生了变化，请启动一个新会话。

本地检出

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

卸载

从所有安装了 Legion 的 DSH 主机配置文件中移除它：

1. 在用户自有的 agent 预设中移除或禁用 name: dsh-legion 行。
2. 移除该包：

~~~bash
dsh plugin --profile web remove dsh-legion
~~~

3. 如果不再需要该复制的预设，可选择删除 $DSH_HOME/.agent-presets/legion。
4. 重启受影响的 DSH 进程。

移除包不会删除用户自有的预设或配置。

用法

通过 Profile 进行委派

协调器会看到一个 legion 工具以及各个活跃 Profile 的描述：

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

如果配置了 defaultProfile，则可以省略 profile。并发的同级调用使用 DSH 的常规并行工具执行。

运行 Strategy

Strategy 默认处于隐藏状态。部署必须显式设置 enableStrategies: true。此后同一个工具会接受严格的 Strategy 请求：

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

Profile 和 Strategy 字段不能混用。调用限制只能收窄已编译的 Strategy 限制。

配置

一个最小的 agent 预设行：

~~~yaml
- id: tool-legion
name: dsh-legion
config:
configVersion: 2
toolName: legion
defaultProfile: quick
profiles:
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
~~~

请为你的部署使用有效的 provider 和 model ID。参见完整的预设片段和独立配置示例。
当 Host 挂载设置提供程序时（DSH 0.1.0-rc.7 会服务每个已注册的命名空间），Legion 也会将同一 schema 注册为 legion 设置命名空间：上方的预设行成为基础层，存储的用户区段覆盖单个字段，而一次提交会重新发布该工具，无需重启 DSH。在没有设置提供程序的组合中，一切保持不变。参见实时重配置和设置卡片。

要委托给外部编码代理——Codex、Claude Code、Kimi Code、GitHub Copilot CLI 等——请为每个代理挂载一次 DSH 的 ACP 后端，并追加生成的目录层。参见 ACP 委托和 examples/legion.acp.fragment.yml。

顶层字段

| 字段 | 默认值 | 含义 |
|---|---:|---|
| configVersion | 2 | 当前配置契约；旧版 v1 输入会迁移到 v2。 |
| toolName | legion | 面向模型的工具名称。 |
| profiles | 必填 | 语义 Profile 映射。 |
| defaultProfile | 无 | 当调用省略 profile 时使用的 Profile。 |
| enableRunInBackground | true | 暴露后台委托。 |
| enableStrategies | false | 向模型显式暴露活动的 Strategy。 |
| guidance | 无 | 额外的协调器指导。 |
| resourceRoots | {} | Prompt Fragment 的相对部署根目录。 |
| maxResourceBytes | 65536 | 每个 Profile 的 Prompt Fragment 字节数；硬上限为 4 MiB。 |
| catalogLayers | [] | 有序的第三方或项目策略层。 |
| teams | {} | 最终部署层的 Team。 |
| strategies | {} | 最终部署层的 Strategy。 |

Profile 名称必须匹配 ^[a-z][a-z0-9-]*$。

Profile 字段

| 字段 | 默认值 | 含义 |
|---|---:|---|
| description | 必填 | 向协调器展示的任务适配指导。 |
| subagentProvider | spawn | DSH 子代理后端，而非 LLM 提供程序。 |
| agentOptions | 继承 | 固定的 provider、model 和 maxTokens；不能与 routes 组合使用。 |
| routes | 无 | 最多八个有序的精确 Route Candidate。 |
| persona | 继承 | 子代理 persona/系统策略覆盖。 |
| toolFilter.allow / deny | 无 | 子代理工具可见性限制。 |
| maxDepth | 3 | 子代理深度，或对外部一次性产品使用 provider-managed。 |
| defaultRunInBackground | true | 默认使用可继续的子代理。 |
| result | text | text、findings-v1 或 review-v1。 |
| promptFiles | 无 | 在验证后加载的有序 Prompt Fragment。 |

对于 codex 和 claude-code，模型选择属于外部产品。通常使用 maxDepth: provider-managed 和 defaultRunInBackground: false。

精确 Route Candidate

~~~yaml
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
~~~

在子进程启动之前，Legion 会观察已注册的 DSH 适配器和精确模型元数据。它选择第一个没有已知静态矛盾的候选者。缺失的元数据保持未知且可接受；Legion 绝不会将缺失的元数据转化为健康声明。

Legion 最多启动一个子进程，并且在提供方、认证、配额、网络或子进程失败后绝不会重试另一条路由。

目录层、团队和策略

Config v2 对 Profiles、Teams 和 Strategies 进行分层。后一个定义会替换同名定义；墓碑会禁用它；后一个定义可以将其恢复。根映射是最终部署层。

~~~yaml
configVersion: 2
teams:
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 验证产物图，并将接受的阶段降为分离的、深度冻结的 DSH 原语 IR。它是 DSH 一次性子代理之上的适配器，而不是持久调度器。默认目录包含 independent-review、research-panel 和 plan-execute-review 作为普通的可替换数据，默认关闭模型暴露。

有关确定性协议门禁和单独的真实模型证据要求，请参阅 benchmarks/README.md。

提示片段、结构化结果和信任

提示片段是显式部署资源，而不是任意工作区读取。Legion 将相对路径限制在配置的根目录之下，并拒绝链接、格式错误的 UTF-8、NUL 字节、缺失文件和字节预算违规。编辑需要插件或预设重新激活。

结构化前台契约被有意设计得很窄：

- findings-v1：摘要、有证据支持的发现、决策、验证和未决风险；
- review-v1：裁决、严重性发现、建议和验证；
- 后台延续仍以文本/会话为导向。
预设、Catalog 层、插件包、资源根目录和 Prompt Fragment 都是受信任的部署配置。工具过滤器和路径限制为受信任的部署强制执行策略和完整性；它们不是用于抵御恶意预设或不受信任插件的沙箱。参见 SECURITY.md。

Doctor 与 explain

根据显式 provider fixture 验证独立的 Legion 配置：

~~~bash
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 打印简洁摘要；explain 额外输出 Profiles、执行模式、模型路由、结果契约和诊断代码。--json 输出带版本的 legion-explain 视图。

fixture 仅证明所提供的静态事实。CLI 不会检查实时 DSH 进程、凭据、可达性、健康状态、配额、计费、延迟或实际模型可用性。

退出码：0 表示无错误诊断，1 表示能力错误，2 表示用法、I/O、资源、解析或 schema 失败。

状态与限制

源码树声明版本 1.2.0 和配置契约 v2。在选择或升级安装修订版本之前，请查看 CHANGELOG.md、路线图 和 GitHub Releases。

已知限制：

- 精选 Strategies 不会自动暴露给模型；部署所有者可通过 enableStrategies: true 选择启用。
- 选定的子项失败后，Legion 不会重试或切换模型。
- 进程内子项继承父项的具名 DSH agent 预设；Profiles 仍可改变模型、persona、工具、后端和限制。
- GUI 设置卡片编辑四个标量策略；Profiles、Teams、Strategies 和 catalog 层保留在配置文档中。
- 该卡片的浏览器部分手工复现了 DSH 未公开的客户端 bundle 格式，因此上游对该格式的更改会在加载时失败，而不是在构建时失败。
- 不支持没有兼容 DSH peer 的裸包。

FAQ

dsh-legion 是一个独立的多 agent 框架吗？

不是。它是一个用于多 agent 策略和委派的 DeepSeek Harness 插件。DSH 仍然是运行时和生命周期的所有者。

Legion 会自动选择最便宜或最健康的模型吗？

不会。它根据已知静态事实检查有序路由。它不声称实时健康、价格、身份验证、配额或延迟，也不会在失败后重放。

我可以创建自定义 Profiles、Teams 和 Strategies 吗？

可以。Default Catalog 使用与用户和第三方条目相同的公开、可替换契约。

为什么 Legion 工具消失了？

只有其 subagent provider 已注册的 Profiles 才会被发布。如果没有一个处于活动状态，该工具和指引会消失，并在 provider 恢复时重新出现。同时请确认 Legion 已安装到宿主 profile 中，并且新会话使用了包含其行的预设。
我可以编辑 DSH 自带的 standard 预设吗？

不要这样做。将其复制到用户拥有的预设中，这样升级就不会覆盖你的更改。

兼容性、开发与发布

该包要求 Node.js ^22.19.0 || >=24.0.0，以及 DSH 对等依赖 >=0.1.0-rc.6 <0.2.0。CI 覆盖 Windows、Ubuntu、打包的 DSH 消费者、公共契约、协议基准测试以及可复现的软件包。

~~~bash
pnpm install --frozen-lockfile
pnpm run check
~~~

实用参考：

- 实现路线图
- 公共契约 v1
- 持久化策略运行
- 日志契约 v1
- 运行重放
- 版本化配置与回滚
- 声明式团队与策略 IR
- 显式策略暴露权限
- 可复现发布
- 所有架构决策

欢迎通过 GitHub 问题跟踪器 提出问题与贡献。

许可证

MIT

持久化策略运行（v1.1，可选启用）

持久化运行默认禁用，并保留 v1.0 的临时行为。当部署启用时，策略调用方通过 execution: { durability: 'journal' } 显式选择日志模式；省略则仍为临时模式。它们在调用方 DSH 会话日志中使用八种类型化事件，并在状态版本 6 中使用投影键 legion-run。运行控制支持有界只读 inspect、单次激活 resume、已刷新的 cancel，以及经过验证的仅提案 steer。任务投递至少一次；匹配的栅栏与代际允许恰好一次被接受的提交，而非恰好一次的外部效果。邮件会被预留、合并、在需要时持久化刷新，然后确认；过期的预留可被回收。

该包不附带 DSH 持久化、投影、原子协调、全局准入或子回执 Host 服务。已发布的 DSH 0.1.0-rc.6 缺少生产级持久化变更所需的投影与协调服务。在那里启用持久化运行会产生稳定的能力诊断，并在变更前故障关闭；纯契约、验证、重放与检查仍然可用。参见持久化策略运行和日志契约 v1。