运行时工作流编排jiruidai/dsh-meta-orchestrator

CI
npm
Tests
License: MIT
DeepSeek Harness

一个 DeepSeek Harness 插件，教会智能体在运行时合成针对具体任务的工作流——而不是硬编码流水线或固定的智能体拓扑。适合任何在 DSH 中运行多步骤工作、并希望智能体所遵循的计划是显式的、有版本记录的、可持久保存的，而非隐式的人。

🧭 工作原理

通常，智能体收到你的请求后就直接开始干活。有了这个插件，它会先规划，再按计划执行——而且工作流是动态的：由模型自己针对每个请求编写：

1. 分析——智能体阅读请求；如果确实存在歧义，它会先提问再行动。
2. 选择模式——它从五种经过验证的组织工作方式中选择一种：⛓️ 按顺序执行步骤（prompt-chaining）、⚡ 并行展开独立部分（parallel-workers）、🔀 先分类再分发（router）、🎯 委派并审查（supervisor）、🔁 起草 → 评分 → 改进（evaluation-loop）。每种模式的详细操作手册仅在选中时才加载。
3. 把计划写下来——它调用 orchestrate，传入各个阶段、它将委派的角色，以及可验证的成功标准。插件会校验结构并持久保存。这就是插件所做的全部：它记录计划，从不执行计划。
4. 用 DSH 自带的工具完成工作——子智能体、待办事项、工作流脚本、计划模式。插件不添加任何自己的运行时。
5. 调整或收尾——如果现实情况出现偏差，adapt_workflow 会修订计划（每次修订都有版本记录）；工作完成后，complete_workflow 会记录每条成功标准的达成情况。

简单的请求会跳过这一切——智能体会被明确告知不要为了编排而编排。

flowchart LR
A["1 · 分析"] --> P["2 · 选择模式"] --> W["3 · 写下计划orchestrate"] --> E["4 · 完成工作DSH 原语"] --> M["监控进度"]
M -- "现实发生偏离" --> AD["修订计划adapt_workflow"] --> E
M -- "工作完成" --> D["5 · 收尾complete_workflow"]

所有这些行为都来自插件添加到智能体系统提示中的一小段指令块——无需额外的模型调用，也没有后台进程。

安装了什么

| 添加到你的智能体 | 它是什么 |
|---|---|
| 一个指令块（约 330 词） | 教授上述计划优先协议；存在于每个会话的系统提示中 |
| 五份模式操作手册 | 目录中的技能；在模型加载之前不产生任何开销 |
| orchestrate / adapt_workflow / complete_workflow | 三个记录工具：保存计划、修订计划、关闭计划 |

🧩 为什么这样构建

- 模型就是规划者——没有硬编码的流水线，也没有固定的智能体拓扑来决定你的任务如何运行；模型按请求进行选择和组合，并可在任务需要时偏离。
- 只记录，不执行——插件不持有运行时、调度器或消息总线。执行仍依托于经过实战检验的框架原语，因此没有额外的东西会出故障。
- 计划在重启后依然存在——每个计划都存放在 DSH 的存储域中，作为仅追加的 create → adapt* → complete 链，并按会话生命周期隔离。没有自定义的会话事件类型，因此编排的会话总能干净地恢复。
- 为跟踪快速演进的框架而构建——只使用稳定的公开插件接口；没有任何东西绑定到框架内部。

flowchart TB
subgraph P["🧭 dsh-meta-orchestrator"]
direction LR
PS["策略部分"]
SK["5 个模式技能"]
TL["orchestrate · adapt_workflow · complete_workflow"]
end
subgraph H["🐋 DeepSeek Harness"]
direction LR
SYS["系统提示"]
CAT["技能目录"]
REG["工具注册表"]
DOM[("存储域")]
end
PS --> SYS
SK --> CAT
TL --> REG
TL --> DOM
H --> EX["子智能体 · 工作流 · 待办 · 目标 · 计划模式"]

与其他 DSH 编排插件的比较

| | dsh-meta-orchestrator | workflow-capsule 引擎 | agent-team 插件 |
|---|---|---|---|
| 谁来规划 | 模型，按请求，在运行时 | 捆绑沙箱运行时中生成的脚本 | 固定的负责人 + 专家拓扑 |
| 模式选择 | 从五种规范模式中选择并组合 | 固化在 capsule 脚本中 | 每个任务一种拓扑 |
| 执行 | 仅使用框架原生原语 | 自有 QuickJS/WASM 运行时 + 运行存储 | 自有邮箱/唤醒机制 |
| 重新规划 | adapt_workflow 对模式本身重新规划，带版本 | 对同一脚本暂停/恢复/重跑 | 在固定拓扑内重新简报 |
| DSH 耦合 | 仅公开插件接口 | 绑定到框架快照 | 修补框架依赖 |

✅ 兼容性

| | |
|---|---|
| DSH 包 | peer 范围 @deepseek-ai/@^0.1.0-rc.5 — 已针对 0.1.0-rc.6 验证，即当前 npm 发布版本 |
| 主线 | 47f9438 (2026-08-13) |
| 最后验证 | 2026-08-14 — 真实 npm 安装，46/46 测试，实时 web profile 会话 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| Profile | 需要存储栈，由 @deepseek-ai/dsh-web-app bundle（标准 web profile）提供。原版 headless profile 不提供它 — 见故障排除。 |
| 平台 | Windows 11（开发），Ubuntu（CI） |

仅使用公开插件接口 — systemPrompt、skills、tools、storageDomain、agent/pre-step — 因此普通的 harness 变动很少造成影响。但 harness 尚处于 1.0 之前，semver 插入符不跨越预发布线：^0.1.0-rc.5 匹配 0.1.0-rc.6，但不匹配未来的 0.1.1-rc.1。当新的 rc 线发布时，此处的 peer 范围需要提升 — 如果你先遇到，请提交 issue。

📦 安装

需要一个带存储栈的 profile — 标准 web profile（dsh-web-app bundle）提供它（见兼容性）。

dsh plugin --profile web add dsh-meta-orchestrator                           # 从 npm
dsh plugin --profile web add github:jiruidai/dsh-meta-orchestrator#v0.2.0    # 从 git，固定版本

dsh plugin 会在 profile 目录内转发给 pnpm，因此所有 pnpm 命令都可用。在 add 或 remove 后重启 dsh — bundle 层列表在启动时读取；只有 cordis.patch.yml 层会热重载。

git 安装会通过包的 prepare 脚本构建，因此 pnpm 会要求你在 profile 的 pnpm-workspace.yaml 中将其加入允许列表一次（allowBuilds: { dsh-meta-orchestrator: true }）。

升级

dsh plugin --profile web update dsh-meta-orchestrator                        # 在已安装范围内
dsh plugin --profile web add dsh-meta-orchestrator@latest                    # 跨范围
dsh plugin --profile web add github:jiruidai/dsh-meta-orchestrator#v0.3.0    # git 安装：重新添加新 ref

禁用而不移除

profile 自身的 patch 层在每个 bundle 层之后应用并热重载 — 这会在下一个请求时生效，无需重启，无需重装。在 $DSH_HOME/profiles/web/cordis.patch.yml 中（$DSH_HOME 默认为 ~/.dsh）：

- id: meta-orchestrator
disabled: true

删除这两行即可重新启用。无论哪种方式，已记录的工作流都不受影响。

卸载

dsh plugin --profile web remove dsh-meta-orchestrator   # 移除依赖和 bundle 层

重启 dsh。若要完全移除，CLI 不会触及的残留项：

| 残留项 | 如何处理 |
|---|---|
| $DSH_HOME/storages/meta_orchestrator.json | 插件记录的每个工作流。删除该文件即可清除它们 — 没有其他东西会读取它。 |
| $DSH_HOME/profiles/web/pnpm-workspace.yaml 中的 allowBuilds 条目 | 如果你为 git 安装添加过，请将其移除。 |
| $DSH_HOME/profiles/web/cordis.patch.yml 中的 meta-orchestrator 行 | 如果你使用了下面的开发安装方式，请将其移除。 |
| 过往会话的 session.jsonl | 会话会保留已经发生的 orchestrate 调用——这是普通的会话历史，不是插件可以重写的。 |

开发安装（本地检出）

使用 pnpm build 构建，然后向 $DSH_HOME/profiles//cordis.patch.yml 添加一行绝对路径：

- insert:
- id: meta-orchestrator
name: file:////lib/index.js
config:
autoTrigger: false

web profile 会热重载其 patch 层——插件会在下一次请求时生效，无需重启。

🚀 快速开始

无需配置——默认值就是预期的设置。安装到 web profile，重启 dsh，然后交给 agent 一个真正多部分的任务：

审计此仓库的错误处理，然后写一份简短报告，按风险排序给出具体修复方案。

你应该依次看到：

1. agent 用一句话说出其模式——“这是一条链：审计 → 排序 → 撰写。”*
2. 一次 skill 调用，加载该模式的 playbook。
3. 一次 orchestrate 调用，其结果回读如下：

workflow "wf-3f2a91c4" recorded (v1)
pattern: prompt-chaining
stages: 4
success criteria: 3
Execute it with the harness's native primitives and report the final result against the success criteria.

4. 然后是普通的 DSH 工作——todos、subagents、tools。插件不运行其中任何一项：它记录了计划，然后就让开了。
5. 最后，一次 complete_workflow 调用——workflow "wf-3f2a91c4" completed (achieved, v1)。

证明它被持久化了，而不仅仅是叙述（该文件会在第一个已记录的工作流出现时出现）：

cat $DSH_HOME/storages/meta_orchestrator.json   # $DSH_HOME defaults to ~/.dsh

每个 session id 一个条目，保存仅追加的 create → adapt* → complete 链，并在每一步都带有完整的 spec 快照。

换一个简单的问题——“这个文件夹里有什么？”——agent 会完全跳过 orchestrate。这是协议在正常工作，而不是失败。

⚙️ 配置

一个键，没有环境变量，没有敏感内容：

| 键 | 默认值 | 含义 |
|---|---|---|
| autoTrigger | false | 在会话的第一个请求中追加一次性协议提醒（通过组合 agent/pre-step 决策来传递）。默认关闭：仅策略部分就能以零额外 token 成本驱动协议。 |

🔐 权限与数据

| | |
|---|---|
| 网络 | 无——没有请求，没有额外的模型调用 |
| 文件系统 | 无直接访问——一个 Node 内置模块，crypto.randomUUID |
| 凭据 / 环境变量 | 不读取，不存储 |
| 子进程 | 无 |
| 持久化存储 | DSH 存储域 meta_orchestrator，表 workflows，以会话 ID 为键 — 在标准 JSON 后端上位于 $DSH_HOME/storages/meta_orchestrator.json |

值得了解那个文件里存了什么：每一次变更都会存储一份完整的 spec 快照 — 模型对你请求的书面分析、阶段名称与细节、它会交给子代理的简报、成功标准，以及完成报告。那就是对你任务的转述，以明文形式，按会话，存在你的机器上。它永远不会离开这台机器，而删除该文件就是全部的清除手段。

范围说明：这是一个主机平面插件。约 330 词的政策部分和三个工具会全局注册，因此该配置文件中的每个会话都会携带它们 — 这是设计使然（参见安装了什么），而不是泄漏。在 autoTrigger: true 时，每个会话的第一个请求会追加一条提醒消息，仅一次。

🩺 故障排除

启动失败：meta-orchestrator: pending (waiting for services: storageDomain)
该配置文件没有存储栈。只有 dsh-web-app 捆绑包附带 storage / storage-json / storage-domain；标准的 headless 配置文件没有。请安装到 web 配置文件中 — 或者将那三行插入到该插件之上你配置文件的补丁层中。

没有 orchestrate 工具 — 插件似乎不存在
检查该行是否真的被组合进去了：dsh --profile web --dump-config，并查找 dsh-meta-orchestrator 层。缺失 → 该包未安装（重新运行 dsh plugin … add，然后重启 dsh）。存在但 disabled: true → 某个补丁层将其关闭了。

从 git 首次 add 因构建脚本被阻止而失败
pnpm ≥ 10 会拒绝 git 依赖的 prepare 脚本，直到将其加入允许列表。将 pnpm 打印出的确切键复制到 $DSH_HOME/profiles/web/pnpm-workspace.yaml 中的 allowBuilds: 下，然后重新运行。该允许意味着在安装时运行包代码 — 请固定一个 tag 或 sha。

模型没有进行编排就直接回答
对于简单请求这是有意为之。如果你希望在每个会话开始时得到提示，请设置 autoTrigger: true。

orchestrate rejected the spec: …
结构上无效的 spec（没有阶段、没有成功标准、未知模式）。错误会列出所有问题，模型通常会在下一次调用时修复它。被拒绝的调用不会持久化任何内容。

… could not record the spec (storage write failed)
后端拒绝了写入 — 检查 $DSH_HOME/storages/ 是否可写。写入失败会使已记录的链条保持原样；它绝不会记录一半。

到哪里查看

| | |
|---|---|
| 启动和插件错误 | dsh 进程的 stderr |
| 实际发生了什么 | $DSH_HOME/sessions///session.jsonl — 工具调用和结果是普通的会话事件 |
| 持久化记录 | $DSH_HOME/storages/meta_orchestrator.json |
回滚，最快优先：在 profile 补丁层中设置 disabled: true（下一次请求即生效），或执行 dsh plugin --profile web remove dsh-meta-orchestrator 并重启。两者都不会删除已记录的工作流。

🛠️ 开发

pnpm install      # 普通检出：安装已发布的 @deepseek-ai/* 包
pnpm build        # clean + tsc → lib/
pnpm typecheck    # src + tests
pnpm test         # vitest — 46 个单元测试 + 挂载集成测试

欢迎提交 issue 和 PR —— pnpm typecheck && pnpm test 必须全部通过。CI 在 Node 22 和 24 上运行 install → build → typecheck → test，使用 --frozen-lockfile 并基于已提交的 pnpm-lock.yaml（该文件是针对 registry.npmjs.org 生成的）。

维护者的本地检出则通过手工构建的 junction 树从相邻的 harness 检出中解析 @deepseek-ai/*（参见 pnpm-workspace.yaml 中的注释）——在该配置下从不运行 pnpm install。

Token 与 KV 缓存行为

- 每次请求的固定开销：策略部分 + 三个工具 schema；模式正文仅在通过 skill 加载时才会产生开销。
- 当 section、tools 和技能目录保持不变时，前缀保持缓存稳定；在会话中途启用插件会从第一个发生变化的目录 token 起使复用失效。
- 工具结果是小型结构化摘要（id、version、pattern、counts）。

🚧 限制

- 提示词约束是主要的执行手段——模型可能完全跳过 orchestrate。
- 按设计，规格以会话生命周期为界；复用的会话 id 永远不会继承过时的工作流。
- 尚无客户端 UI——工作流状态可在对话、工具结果和存储域中查看。

📄 许可证与安全

MIT。

报告漏洞 —— 请不要公开提交 issue。请使用 GitHub 针对本仓库的私密漏洞报告；参见 SECURITY.md。从表面来看，几乎没有需要担心的地方：该插件不执行任何操作、不打开任何套接字，也不读取任何凭据——现实中值得关注的是它注入的策略文本以及它在本地存储的任务转述（参见权限与数据）。