多智能体编排 wxxb789/dsh-legion

dsh-legion：面向 DeepSeek Harness 的多智能体编排与 LLM 模型路由

English · 简体中文

CI
License: MIT
Node.js
TypeScript
DSH plugin

dsh-legion 是一个面向 DeepSeek Harness (DSH) 的 TypeScript 多智能体编排插件。它将单个 AI 编码智能体转变为一个有边界的编排队列：可配置的 AI 智能体专家、精确的 LLM 模型路由器、声明式 Cohort 与 Strategy、结构化结果，以及深度受限的子智能体委派——且无需替换 DSH 运行时。

TL;DR

- 它是什么。 一个用于多智能体委派策略的 DeepSeek Harness 插件——而非独立的智能体框架。
- 它新增了什么。 一个面向模型的 legion 工具，其选项是语义化专家，例如 quick、deep 和 review。每个专家都携带由部署方拥有的模型路由、子智能体后端、人设、工具过滤器、深度和结果契约。
- 它为何有用。 协调智能体选择的是意图而非模型 ID，提示词永远无法扩大专家背后的策略，而更改 deep 背后的模型无需重写任何提示词。
- 它的成本是什么。 用户自有智能体预设中的一行配置。无需额外的调度器、会话存储、数据库或智能体运行时。
- 它面向谁。 已经在运行 DSH、并希望获得可审查、可复用多智能体委派能力的开发者和部署方。

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

快速开始

~~~bash
1. Install the plugin into a DSH host profile (append # 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

协调器现在看到一个 legion 工具，其 specialist 值就是你的语义委派选择。分步说明见安装和设置 Legion 代理预设。

目录

- TL;DR
- 快速开始
- dsh-legion 用于什么？
- dsh-legion 与独立多代理框架对比
- 能力
- 工作原理
- 底层机制：从工具调用到子代理
- 安装
- 设置 Legion 代理预设
- 升级
- 卸载
- 用法
- 配置
- Doctor 与 explain
- 状态与限制
- FAQ
- 持久化策略运行
- 相关项目

dsh-legion 用于什么？

当一个 AI 编码代理应在明确、可复用的策略下委派不同类型的工作时，Legion 就派上了用场。

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

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

dsh-legion 与独立多代理框架对比

独立多代理框架（如 LangGraph、CrewAI 和 AutoGen）自带运行时、状态模型和进程生命周期，因此采用其中一个框架就意味着在你已经运行的编码代理旁边再放置一个编排器。Legion 采取相反的方法：它完全不添加运行时，而是将委派策略编译为原生 DSH 子代理。

| | dsh-legion | 独立代理框架 |
| 你采用什么 | 为你已运行的代理提供委派策略 | 第二个运行时、状态模型和进程生命周期 |
| 谁拥有 agent 循环 | DeepSeek Harness | 框架 |
| 会话、沙箱、审批、模型适配器 | DSH 拥有且保持不变 | 框架拥有，与你的 agent 并行 |
| 模型选择 | 每个 Specialist 按顺序精确的 provider/model Route Candidates | 通常按节点或按 agent 在代码中接线 |
| 采用成本 | 用户拥有的预设中的一行配置 | 新的依赖树、服务或进程 |
| 提示词权限 | 提示词选择一个 Specialist，且永远无法扩大该 Specialist 的模型、工具、人设或深度 | 因框架而异 |
| 何时选错工具 | 你没有运行 DSH | 你想要一个自包含的编排器 |

如果你没有运行 DeepSeek Harness，Legion 就不是合适的工具，独立框架是更好的选择。

能力

| 能力 | 它提供什么 |
| 语义化 Specialist | 使用诸如 quick、deep 和 review 这样的命名策略，而不是在每个提示词中直接选择原始模型。 |
| 精确模型路由 | 最多八个按顺序排列的 provider/model 候选，并带有静态上下文和输出预算约束。 |
| 多种后端 | 每个 Specialist 可使用 spawn、fork、codex、claude-code 或另一个 DSH 注册的子 agent provider。 |
| 工具与人设策略 | 限制子工具、添加 Specialist 指令、设置深度，并选择前台/后台默认值。 |
| 结构化结果 | 带版本的 text、findings-v1 和 review-v1 前台结果契约。 |
| 自定义 Cohort | 声明引用现有 Specialist 的有界 Member Slot。 |
| 声明式 Strategy | 将类型化 artifact 图编译为冻结的 DSH 委托原语。 |
| 硬性限制 | 为每次 Cohort Run 限制 agent 数量、并发数、截止时间和可接受的输出大小。 |
| 目录自定义 | 对用户或第三方目录条目进行分层、替换、禁用和恢复。 |
| 提示词片段 | 从部署拥有的根目录加载受限、不可变的 UTF-8 提示词资源。 |
| 可解释策略 | 稳定的摘要、确定性的诊断、路由证据和 JSON explain 输出。 |
| 实时重新配置 | 可选：当 Host 挂载设置提供程序时，通过 legion 命名空间编辑同一配置并重新发布，无需重启。 |
| Web 设置卡片 | DSH 设置 → 插件选项卡上的插件卡片，带有分阶段编辑和覆盖徽章。参见设置卡片。 |
| 实时 Run Receipt | 单独打包的 dsh-legion-receipts 配套组件显示当前 Session 的实时逐成员 Cohort Run 事实；无头执行保留有界的终端摘要。参见 Run Receipts。 |
| ACP 委托 | 通过 DSH 的 ACP 后端为 Codex、Claude Code、oh-my-pi、Kimi Code、Grok Build、Pi、GitHub Copilot CLI、Hermes 和 ZCode 提供的可选 Specialist。参见 ACP 委托。 |
| 原生 DSH 生命周期 | 延续、取消、结算、提供程序和 HMR 安全注册仍由 DSH 拥有。 |

工作原理

~~~text
Catalog Layers
├─ Specialists -> 模型路由、后端、人设、工具、结果契约 ├─ Cohorts -> 引用 Specialists 的有界 Member Slots └─ Strategies -> 类型化产物图 + 硬性限制 │ ▼ 冻结的 DSH 原语 IR │ ▼ 原生 DSH 子代理

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

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

协调器选择一个语义化的 Specialist；提示词无法改变该 Specialist 由部署方拥有的模型、工具、人设、深度或结果策略。

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

底层机制：从工具调用到子代理

激活，当 DSH 在 Cordis fiber 上挂载该插件时：

1. Legion 依据严格 schema 校验配置，该 schema 会拒绝文档中任何位置的未知字段。
2. Catalog Layers 按顺序合并：后一层按名称替换前一层条目，tombstone 会禁用继承的条目，而该名称的任何后续定义都会使其复活。
3. Specialists 引用的 Prompt Fragments 会被读取一次，受每个 Specialist 的字节预算限制，并作为带有内容摘要的不可变快照捕获。
4. Legion 观察 Host 当前注册了哪些子代理后端以及哪些 LLM 适配器。
5. 每个 Specialist 都会依据该观察结果进行编译，并且仅当其配置的后端能够实际满足该 Specialist 的策略时才会变为活跃：执行模式、工具过滤、人设、深度和结构化输出。
6. 委派工具会随一个从活跃 Specialists 派生的参数 schema 一起发布，并且会向系统提示词贡献一个匹配的路由表。
7. 如果没有 Specialist 处于活跃状态，该工具会被撤回，指导内容渲染为空。每当后端或适配器发生变化时，整个序列都会重新运行。

一次委派，在协调器的工具调用与返回结果之间：

8. 参数会被校验并解析为恰好一个 Specialist：所指定的那个，或配置的 defaultSpecialist。
9. 如果该 Specialist 声明了 routes，Legion 会读取每个候选者的精确模型元数据，并按你编写的顺序取第一个没有任何静态事实与之矛盾的候选者。
10. 只有静态事实参与判断，例如上下文窗口和输出预算。元数据无法读取的候选者仍保持合格；只有当所有候选者都被明确排除时，调用才会失败。
11. Legion 通过 Host 的 subagent API 恰好启动一个子进程，并应用 Specialist 的固定策略，当该子进程或其 provider 失败时，绝不重试或切换路由。
12. 后台调用会立即返回一个可继续的子进程 id；前台调用会等待，根据其契约重新验证结构化结果，并在返回前将其重建为全新的纯数据。

从该设计可以得出两个值得明确说明的特性。编译后的 Cohort 和 Strategy IR 是深度冻结且分离的：它不持有对你配置对象的任何引用，也不携带任何函数。编译后的 Strategy 计划还会通过对象标识在一个进程级注册表中被跟踪，因此执行只接受由本进程编译的计划——即使内容和摘要完全相同，重建或反序列化的副本也会被拒绝。

安装

先决条件

- 一个兼容的 DeepSeek Harness 安装。
- pnpm 位于 PATH 中；dsh plugin 会将包操作转发给 pnpm。
- 一个 DSH Host profile，例如默认的 web 组合。
- 一个已配置的 DSH subagent provider，以及你的 Specialist 所引用的 LLM provider/model 路由。
- 用于本地开发：Node.js ^22.19.0 || >=24.0.0 和 pnpm 11.21.0。

从 GitHub 安装

将默认分支安装到 web Host 组合中：

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

如果 Legion 应在另一个 DSH Host profile 中可用，请替换 web。

这会在安装时解析一次 main。dsh plugin 会转发给 pnpm，后者将解析后的提交记录在 Host profile 的 lockfile 中，因此已安装的修订版本不会跟随之后的推送，除非你显式升级。

固定一个修订版本

git 安装会在你的机器上运行 Legion 的 prepare 构建，且处于 agent 运行所在的任何沙箱之外。只要已安装的代码必须保持可审计和可复现——生产 Host 组合、共享机器，或你审查允许构建内容的部署——就应附加一个不可变的修订版本：

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

目前尚未发布 release tag。当版本出现在 GitHub Releases 上后，该 release 的 tag 也是一个不可变的安装规格。

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

~~~yaml
allowBuilds:
dsh-legion: true

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

从本地检出安装

~~~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/ 产物。根包会安装精确版本的 dsh-legion-receipts 配套依赖，而 bundle 补丁会挂载两行 Host 平面：legion-settings 提供 legion 命名空间和 Settings 卡片，而 legion-receipts 提供实时 Run Receipt 流和 Web UI。这两个包是版本耦合的一对；不要将配套包覆盖为其他版本。缺少任一 Client 产物都会导致 Host 激活时大声失败。安装仍然不会注入任何进程全局的模型工具——委托工具保留在 agent 平面上，由预设在那里请求它。

设置 Legion agent 预设

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

推荐：扩展现有预设

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

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

替代方案：复制捆绑预设

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

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

升级

GitHub 安装

分支安装会通过 pnpm 的 update 命令重新解析到当前的 main 提交，DSH 会转发该命令。根更新会随之解析其精确的配套依赖；不要独立更新这一对：

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

固定安装按设计会停留在其记录的修订版本上。通过添加新的精确修订版本来迁移它——后续的发布标签也以相同方式工作：

~~~bash
dsh plugin --profile web add github:wxxb789/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 Host profile 中移除它：

1. 在用户自有 agent 预设中移除或禁用 name: dsh-legion 行。在下一步中移除根包会移除其精确的配套依赖，以及贡献 legion-settings 和 legion-receipts 两者的 bundle 层；你手动复制到组合 cordis.yml 中的行需要你在那里自行移除。
2. 移除该包：

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

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

卸载软件包不会删除用户拥有的预设或配置。

用法

通过 Specialist 进行委派

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

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

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

运行 Strategy

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

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

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

观察运行回执

当 Web Host 挂载软件包捆绑包时，dsh-legion-receipts 配套组件会在 Run Receipt 覆盖层中显示当前 Session 的 Cohort Runs。它会在完整替换之前接收完整基线，因此当父 Session 和配套实例保持活跃时，Client 刷新和 carrier 重连会恢复相同的活跃事实。

完整事实是进程本地的观察状态：Session 销毁、配套组件重新加载或 Host 重启都会从空状态开始，浏览器存储仅包含展示偏好。官方 DSH 接缝无法证明的远程事实会显示为不可用而非零；因此已知的小计可能只有部分覆盖。无头执行或缺少配套组件的执行仍会完成，并返回有界的终端工具摘要。有关操作、状态语义、验收证据和手动 Web 检查清单，请参阅 Run Receipts。

配置

一个最小的 agent-preset 行：

~~~yaml
- id: tool-legion
name: dsh-legion
config:
configVersion: 3
toolName: legion
defaultSpecialist: 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:
allow: [read, glob, grep]
maxDepth: 2
defaultRunInBackground: false
result: review-v1

为你的部署使用有效的 provider 和 model ID。参见完整预设片段和独立配置示例。

当 Host 挂载一个 settings provider 时（DSH 0.1.0-rc.7 会提供每个已注册的命名空间），legion settings 命名空间由 bundle patch 所安装的 Host-plane 行拥有，并且它会发布相同的 schema。上方的预设行仍然是其自身委派面的基础层：它将存储的用户配置节应用到自己条目之上，一次提交即可重新发布该工具而无需重启 DSH。在没有 settings provider 的组合中，一切都不会改变。参见实时重配置和settings 卡片。

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

顶层字段

| 字段 | 默认值 | 含义 |
| role | delegation | 此行的组合角色，从该行自身的条目读取，绝不从 settings 层读取。settings 行只注册 legion 命名空间，别的什么都不做——没有工具、没有 prompt 节、没有投影、没有服务。 |
| configVersion | 3 | 规范的当前契约。已发布的 1.x 调用若省略 export target，在 2.0 之前仍会物化/导出 v2；旧版 v1/v2 键在加载时会给出替换诊断，且绝不会就地重写。 |
| toolName | legion | 面向模型的工具名称。 |
| specialists | 必填 | 语义 Specialist 映射。 |
| defaultSpecialist | 无 | 当调用省略 specialist 时使用的 Specialist。 |
| enableRunInBackground | true | 暴露后台委派。 |
| enableStrategies | false | 显式向模型暴露活动的 Strategies。 |
| guidance | 无 | 额外的协调者指导。 |
| resourceRoots | {} | Prompt Fragments 的相对部署根目录。 |
| maxResourceBytes | 65536 | 每个 Specialist 的 Prompt Fragment 字节数；硬上限为 4 MiB。 |
| catalogLayers | [] | 有序的第三方或项目策略层。 |
| cohorts | {} | 最终部署层的 Cohorts。 |
| strategies | {} | 最终部署层的 Strategies。 |

Specialist 名称必须匹配 ^[a-z][a-z0-9-]$。包根导出当前的 Specialist、Cohort、CohortRun、Config v3 物化器、诊断以及 ACP 辅助工具。已发布的 1.x Profile/Team 名称仍作为显式弃用的兼容别名保留，移除时间不早于 2.0.0。

Specialist 字段

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

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

精确路由候选

~~~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 最多启动一个子任务，并且在提供方、认证、配额、网络或子任务失败后绝不会重试另一条路由。

目录层、队列和策略

配置 v3 对专家、队列和策略进行分层。后一个定义会替换同名定义；墓碑标记会禁用它；后一个定义可以将其恢复。根映射是最终部署层。

~~~yaml
configVersion: 3
cohorts:
coding:
description: One executor and one reviewer.
members:
executor: { specialist: deep }
reviewer: { specialist: review }
strategies:
reviewed:
description: Execute and review.
cohort: 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。

Prompt Fragments、结构化结果与信任

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

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

- findings-v1：摘要、有证据支撑的发现、决策、验证以及未决风险；
- review-v1：裁决、严重性发现、建议以及验证；
- 后台延续仍以文本/会话为导向。

预设、Catalog Layers、插件包、资源根目录以及 Prompt Fragments 都是受信任的部署配置。工具过滤器和路径限制为这一受信任的部署强制执行策略与完整性；它们并非用于抵御恶意预设或不受信任插件的沙箱。参见 SECURITY.md。

工具呈现与只读审查

捆绑预设以 native 模式运行。 其 review Specialist 使用显式的 read/glob/grep 允许列表，因此子级无法继承预设的 shell、文件系统变更、作业控制或委托工具。read_image 被有意省略，因为 DSH 仅在存在附件服务时才注册它；可移植的允许列表无法指定一个条件性工具。官方的 @deepseek-ai/dsh-agent-tool-presentation 行拥有这一选择，而 Legion 不会在其源码中重新实现呈现。

PTC 仍可用于受信任的协调部署。ptc 行仅呈现 run_code 以及一个生成的 SDK，其绑定遵循调用 Agent 经过过滤的可见工具。然而，DSH 的工作线程代码运行时明确提供的是隔离而非安全边界：模型编写的代码对 Node API 具有等同于 bash 的访问权限，并且 run_code 本身无法通过 toolFilter 移除。因此，不能仅因为缺少写入形态的 SDK 绑定就将 PTC 子级描述为只读。

被委托的子级通过预设的常驻作用域继承其协调者的呈现。仅当每个被委托的 Specialist 都被信任拥有该代码运行时权限时，才将捆绑行切换为 mode: ptc。追加到你的预设的片段（examples/legion.agent.cordis.fragment.yml）未声明任何呈现，因为在现有组合中进行第二次声明会被拒绝而非合并；它会跟随接收它的那个预设。

PTC 部署还需要下面的 Host 平面运行时。两个随附的捆绑包都已组合了一个；手工组装的 Host 必须在选择 ptc 之前添加它：

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

当未组合 codeRuntime 时，Legion 会记录 PTC 加速不可用，并继续通过原生工具工作。

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 额外输出 Specialists、执行模式、模型路由、结果契约和诊断代码。--json 输出带版本的 legion-explain 视图。

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

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

状态与限制

源码树声明版本为 1.2.0；规范当前配置为 v3，而已发布的 1.x 无目标物化/导出仍为 v2 以保持兼容。在选择或升级安装修订版本之前，请查看 CHANGELOG.md、roadmap 和 GitHub Releases。

已知限制：

- 精选 Strategies 不会自动暴露给模型；部署所有者可通过 enableStrategies: true 选择启用。
- DSH 在 provider 重试和 Route Candidates 之间没有统一的恢复负责人，因此 Legion 仅启动选定的子项，且失败后绝不重试或切换模型。
- DSH 将一次准备好的调用绑定到一个 adapter generation 和一次 dispatch，但 Legion 的启动前 Route 观察是时间点上的尽力而为事实，而非原子性的 adapter 拓扑快照。
- Specialist 无法覆盖子项的推理强度。
- 进程内子项继承父项的命名 DSH agent preset；在一次性、可继续和冷恢复路径中，均无法使用按子项的命名 preset 或 Specialist 本地的 DSH Skill 设置。Specialists 仍可改变模型、persona、工具、后端和限制。
- Legion 不会检查实时 provider 健康状况、凭据、授权、配额、可达性或延迟；Route Plans 将这些事实报告为未知。
- 聚合 token 或货币成本准入仍是未来由 Host 拥有的能力；它与仅用于观察的 Run Receipt 配套功能无关。当前限制涵盖成员、并发、截止时间、可接受输出、工具和合格路由。
- GUI 设置卡片编辑五项标量策略；Specialists、Cohorts、Strategies 和 catalog 层仍保留在配置文档中。
- DSH 现在发布经评估的客户端契约，包括 settings.plugin.item 槽位声明，但不发布其 clientBundle 构建预设。因此 Legion 针对公共包进行类型检查，同时手工复现加载器产物格式；Host 格式变更会在加载时失败，而不是在构建时失败。
- Specialist 的 result schema 仍然接受 plan-delta-v1，这是一个面向持久运行计划提案而非普通委托的契约。在它被门控或有意发布之前，应将其视为 Specialists 不支持。
- 没有兼容 DSH 对等项的裸包不受支持。

常见问题

dsh-legion 是一个独立的多智能体框架吗？

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

它与 LangGraph、CrewAI 或 AutoGen 相比如何？

那些框架自带运行时、状态模型和进程生命周期，因此采用其中一个会在你的智能体旁边增加第二个编排器。Legion 完全不增加运行时：它是针对你已运行的 DSH 部署的声明式委托策略，编译为原生 DSH 子智能体。完整对比见 dsh-legion 与独立多智能体框架的对比。

它可以路由到哪些 LLM 提供商和模型？

你的 DSH 部署注册为适配器的任何提供商和确切模型，以普通配置命名。Legion 从不内嵌提供商列表、凭据或定价：它会根据已知的静态能力事实检查有序的 Route Candidates，并启动一个子项。

它可以委托给 Codex、Claude Code 或 GitHub Copilot CLI 吗？

可以，通过 DSH 的 ACP 后端。Legion 附带一个可选目录层，其中包含面向 Codex、Claude Code、oh-my-pi、Kimi Code、Grok Build、Pi、GitHub Copilot CLI、Hermes 和 ZCode 的 Specialists。参见 ACP 委托。

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

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

我可以创建自定义 Specialists、Cohorts 和 Strategies 吗？

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

为什么 Legion 工具会消失？
只有当 Specialist 配置的后端确实能满足该 Specialist 的策略时，它才会被发布：包括其默认的执行模式，以及 Agent 选项覆盖、工具过滤、persona、depth 和结构化输出。未注册的子代理提供程序会使其停用，已注册但无法提供 Specialist 所需内容的后端也会使其停用——例如，为 findings-v1 Specialist 提供结构化输出。如果没有 Specialist 符合条件，该工具会被撤回，指导内容会渲染为空；一旦缺失的能力出现，两者都会恢复。还要验证 Legion 已安装到预期的 Host profile 中，并且新会话使用包含其行的预设。

我可以编辑 DSH 随附的 standard 预设吗？

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

兼容性、开发和发布

该包要求 Node.js ^22.19.0 || >=24.0.0，以及 contracts/compatibility.json 中声明的 DSH 对等版本范围。Legion 根据这一单一策略跟踪经评估的 Host 系列：包对等版本范围、声明的最低版本、最新测试版本、CI 渠道和打包验证器都会对照它进行检查，而不是复制版本字面量。CI 覆盖 Windows、Ubuntu、打包的 DSH 消费者、公共契约、协议基准和可复现包。

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

实用参考：

- 实现路线图
- 公共契约 v1
- 持久化 Strategy Runs
- Journal 契约 v1
- Run 重放
- Run Receipts
- 版本化配置与回滚
- 声明式 Cohort 与 Strategy IR
- 显式 Strategy 暴露权限
- 可复现发布
- 所有架构决策

欢迎通过 GitHub issue tracker 提出问题并贡献代码。

持久化 Strategy Runs（v1.1，可选启用）

持久化运行默认禁用，并保留 v1.0 的临时行为。当部署启用时，Strategy 调用方通过 execution: { durability: 'journal' } 显式选择 journal 模式；省略则仍为临时模式。它们在发起调用的 DSH Session journal 中使用八种类型化事件，并在状态版本 7 下使用投影键 legion-run。运行控制支持有界只读 inspect、单次激活 resume、已刷新的 cancel，以及经过验证的仅提案 steer。任务投递至少一次；匹配的 fence 和 generation 允许恰好一次被接受的提交，而不是恰好一次外部效果。邮件会被预留、并入、在需要时持久刷新，然后确认；过期的预留可被回收。
本包不附带 DSH 持久化、投影、Session Query、原子协调、全局准入或子回执 Host 服务。DSH 0.1.2-alpha.4 仍不提供原子运行协调服务。其生成的持久化目录排除了仓库外必需的 legion/* 事件；ignorable 信封标记仅适用于重建时可安全跳过的事实，而 Legion 的状态变更事件并非此类。因此，生产环境的持久化变更仍不可用，并会在追加前以失败关闭方式终止。也没有任何构建绑定持久化 Strategy 激活适配器，因此 execution 仍不在面向模型的 schema 中；程序化 journal 请求会返回缺失的 Host 能力代码或 LEGION_DURABLE_EXECUTION_ADAPTER_UNAVAILABLE。纯契约、验证、重放和检查仍可使用。临时 Cohort Run Receipts 仅通过可选的 dsh-legion-receipts 伴随组件发布完整的实时事实：同一实时 Session 和伴随实例在 Client 刷新/重连后仍然存活，而 Session 销毁、伴随组件重载或 Host 重启则从空状态开始。无头部署和缺少伴随组件的部署仍会收到有界的终端工具摘要，且不使用任何自定义 Session 事件或 Receipt 存储。参见 Durable Strategy Runs、Journal Contract v1 和 DSH 0.1.2-alpha.4 审计。

相关项目

- DeepSeek Harness (DSH) — 开源 agent harness，拥有 Agent、Session、模型适配器、子代理运行时、沙箱、审批以及 Legion 所接入的 Web GUI。
- Cordis — DSH 所基于的插件和服务框架；Legion 通过普通 Cordis fiber 注册。
- Agent Client Protocol — DSH 的 ACP 后端背后的协议，供 Legion 可选的外部代理 Specialist 使用。
- dsh-plugin 主题 — 发现更多 DeepSeek Harness 插件。

如果 dsh-legion 为你节省了工作，给仓库加星可以帮助其他 DSH 用户发现它。

许可证

MIT