智能体图调度 hy-sde/dsh-graph

[!NOTE]
📦 这个插件住在 dsh-plugins 单体仓库里 —— 提 issue 和 pull request 请去那边。
npm：@hy-sde-org/dsh-graph-control · @hy-sde-org/dsh-graph-executor · @hy-sde-org/dsh-graph-host · @hy-sde-org/dsh-graph-projection · @hy-sde-org/dsh-graph-stream · @hy-sde-org/dsh-graph-wakes · @hy-sde-org/dsh-tool-graph

dsh-graph —— 给 DeepSeek Harness 用的持久化智能体图调度

这是 Maka Agent Graph 家族（控制存储、流核心、执行器、监督工具、唤醒、投影、宿主）的独立移植版，跑在 DeepSeek Harness 上 —— 提供持久化依赖调度，带 exactly-once 认领和 supervisor yield/wake。图根会话负责规划一份持久化的工作排期（view_agent_graph / update_agent_graph），然后用 yield_agent_graph 结束自己的回合，而不是轮询；operator 子节点作为子代理运行，待在 git-worktree 租约里，受 exactly-once 认领约束；宿主则在下一个空闲边界，根据持久化的 wake 行唤醒 supervisor。

| 身份 | 值 |
| 包 | 7 个已发布的 npm 包（见 Packages）；仓库根目录是私有工作区（dsh-graph 0.1.7-rc.2），没有总括性的 npm 包 |
| 插件行 id | graph-host（宿主组合）· tool-graph（图根会话的智能体预设）· graph-projection（挨着会话投影注册表） |
| 工具 | view_agent_graph · update_agent_graph · yield_agent_graph |
| 提示词段落 | orchestration:graph |
| 服务 id | agentGraphController · graphHostServices |
| 投影单元 | graph（由 graph/change 会话事件喂数据） |
| 存储单元 | agent_graph KvUnit（@deepseek-ai/dsh-storage） |

基于 Apache Maka（Apache-2.0） —— Agent Graph 的控制存储、流核心、执行器适配层、监督工具、唤醒投递、投影和宿主插件都移植自 Maka（No. 1），重新挂到 DeepSeek Harness 的原语上；这些模块也源自 DeepSeek Harness 代码库（MIT）。来源说明汇总在 THIRD-PARTY-NOTICES.md。

Packages

| 包 | 职责 |
| @hy-sde-org/dsh-graph-control | 持久化决策存储：只追加的排期日志、exactly-once 意图认领、operator 供给、supervisor 唤醒 |
| @hy-sde-org/dsh-graph-stream | 推导层：记录、追踪、就绪状态、输入交接，以及 AgentGraphCoordinator 驱动循环 |
| @hy-sde-org/dsh-graph-executor | 算子执行器适配层：确定性的 worktree 租约、持久绑定、串行化的子运行与终态记录 |
| @hy-sde-org/dsh-tool-graph | 面向模型的监督者工具，以及 orchestration:graph 提示词片段 |
| @hy-sde-org/dsh-graph-wakes | 基于持久唤醒行的空闲门控监督者唤醒投递 |
| @hy-sde-org/dsh-graph-projection | graph 会话投影单元，折叠宿主发布的整值 graph/change |
| @hy-sde-org/dsh-graph-host | 宿主平面装配：打开存储、在真实 harness 接缝上构建执行器、发布控制器 |

为什么

智能体只靠对话协调长时间的扇出工作，一旦重启、压缩上下文或遇到繁忙轮次，计划就丢了。这一组插件让调度变得持久：每个决策都是一行只追加的调度记录，带确定性的 sha256 id（graph_update_…、graph_claim_…、graph_operator_…、graph_wake_…）；精确一次的认领在观察到的调度修订上写入预分配的轮次/运行身份，因此重试会复用同一个激活身份，而不是把服务商调用两次。每次认领/供给状态转换都以观察到的调度修订为条件，所以过期的驱动无法重新派发。存储才是权威；记录、路由、就绪意图和工作状态都保持推导得出、可重新计算。监督者按波次汇报结果并让出，宿主在持久检查点重新驱动图并唤醒根会话——无需轮询。

前置条件

- Node.js 22.19 或更新版本，且 PATH 上有 npm 和 pnpm（仓库 engines：>=22.19.0）；
- 一套 DeepSeek Harness 安装，提供本组的 peer 范围——@deepseek-ai/* 接缝包为 ^0.2.0-rc.2（storage、session、session-projection、session-persistence、agent、subagent、compaction、llm、tools、system-prompt），@deepseek-ai/cordis 为 ~4.0.4——包括标准的 dsh 命令行；
- 已发布的 @hy-sde-org/dsh-git worktree 引擎（graph-host 的 peer）；
- 图控制单元的存储后端（默认 sqlite）——一个 agent_graph KvUnit，每个进程只打开一次。

继续之前先安装命令行和 pnpm：

npm install --global @deepseek-ai/dsh pnpm
dsh --version

快速开始

路线 A —— 已发布的 npm 包（推荐）

dsh plugin --profile web add @hy-sde-org/dsh-graph-host
dsh plugin --profile web add @hy-sde-org/dsh-tool-graph
dsh plugin --profile web add @hy-sde-org/dsh-graph-projection
四个库包（dsh-graph-control、dsh-graph-stream、dsh-graph-executor、dsh-graph-wakes）不带插件行；它们是宿主行的 peer 依赖。所有 peer 依赖都是已发布的包——这里不需要任何未发布的 fork 包。

路线 B —— 从源码安装（验证这份 checkout，或改插件）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins/dsh-graph
pnpm install
for pkg in graph-host tool-graph graph-projection; do
(cd packages/$pkg && PACKAGE_TARBALL="$(pnpm pack | tail -n 1)" && dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL")
done

每次 pnpm pack 都会跑一遍包自带的 prepack 构建，产出的 tarball 里包含 dist/。直接依赖 github:<this-repo> 拿不到构建产物，不是受支持的安装方式——请始终安装构建好的 tarball（或已发布的包）。

接上这些行

这个分组不带 bundle 补丁：要挂载，就把包行加进配置档组合（见 harness 插件文档）。graph-host 行位于宿主组合——它注入宿主服务，也发布新服务，所以它的一切都不能按会话区分。tool-graph 和 graph-projection 行位于图根会话的智能体预设：

host composition (loaded before any session)
- id: graph-host
name: '@hy-sde-org/dsh-graph-host'
config:
rootSessionId: <ROOT_SESSION_ID> # the graph root session id
subagentProvider: spawn # one-shot in-process subagent provider
backend: sqlite # backend owning the graph control unit
maxNewActivations: 4 # new operator activations per drive (default 4)

agent preset composition for the graph root session
- id: tool-graph
name: '@hy-sde-org/dsh-tool-graph'
- name: '@deepseek-ai/dsh-session'
- name: '@deepseek-ai/dsh-session-projection'
- name: '@hy-sde-org/dsh-graph-projection' # registers only when the registry is present

把 <ROOT_SESSION_ID> 换成部署的图根会话 id——只有那个会话能驱动 supervisor 工具，graph/change 事件也归它所有。预设行绝不能发布服务；这里预设行只做两件事：注册工具，以及提供投影单元。

验证组合后的配置

dsh web --dump-config

组合出的树里必须能看到：宿主组合中有一个 graph-host 行加载 @hy-sde-org/dsh-graph-host，图根会话的预设中有一个 tool-graph 行加载 @hy-sde-org/dsh-tool-graph，并且 @hy-sde-org/dsh-graph-projection 紧挨着会话投影注册表。

运行

dsh web
在 graph 根会话中，让智能体规划工作：update_agent_graph 每次调用提交一条持久决策（通过 targetKind 添加工作、停止目标，或用已提交的结果 id 收尾；idempotencyKey 让重试安全），yield_agent_graph 结束 supervisor 轮次，同时 graph 驱动 operator 子节点。宿主会在下一个持久检查点唤醒会话；view_agent_graph 展示有界调度——工作状态、截断的记录摘要、就绪意图、显式的 omitted 计数。

卸载

本组不附带 bundle 行——graph-host 行（宿主组合）以及 dsh-tool-graph / dsh-graph-projection 行（智能体预设）都是手动添加的，所以 dsh plugin remove 不会动它们。先移除这些行，然后：

dsh plugin --profile web remove @hy-sde-org/dsh-graph-host
dsh plugin --profile web remove @hy-sde-org/dsh-tool-graph
dsh plugin --profile web remove @hy-sde-org/dsh-graph-projection

bundle 做什么

本组不附带 bundle 补丁——三个可挂载包声明了 Cordis 插件行，由你自行放置：

1. graph-host（宿主平面行） 注入 agents、sessions、subagents、git、compaction；打开 graph 控制单元；在 git worktree 引擎和子代理运行时之上构建 operator 执行器（用 OncePerClaimGraphExecutor 精确一次守卫包裹）；发布 agentGraphController 服务，supervisor 工具用 ctx.get 解析它，同时发布整个 graphHostServices 装配句柄；每次调度提交、协调和唤醒投递之后，向根会话日志追加 graph/change 事件；在根会话的空闲边界驱动唤醒投递。根智能体发布（agent/created）时挂载，若已处于活动状态则立即挂载，并随其 fiber 撤回服务。
2. tool-graph（智能体平面行） 在 graph 根会话中注册三个 supervisor 工具和 orchestration:graph 提示词段落。即使控制器缺席，工具也会挂载——智能体预设绝不会破坏会话创建——在宿主提供控制器之前，每次调用都会以 [agent-graph-unavailable] 大声失败。
3. graph-projection 注册 graph 会话投影单元：对宿主的整值 graph/change 发布做纯折叠（在首次发布之前提供 null）。Web 聊天通过 useProjection('graph') 将其渲染为 graph 栏和 chip。没有投影注册表时，该单元不注册任何内容，其他装配也只是不提供 graph 键。

四个库不贡献任何工具、提示词或插件行——控制存储、协调器、执行器适配器和唤醒运行时由宿主装配消费。

忠实移植 Maka，并适配 harness

根据 THIRD-PARTY-NOTICES.md，控制存储、流核心、执行器适配器、监督工具、唤醒投递、投影和宿主插件都移植自 Apache Maka（No. 1），并重新托管在 DSH 原语之上，另有部分派生自 DeepSeek Harness 代码库。

忠实于 Maka 的部分：

- 唯一一条硬规则：持久化声明——连同预分配的 turn/run 身份——必须在运行时被要求执行之前写入，且每次声明/供给状态转换都以它观察到的调度修订为条件，因此重试会复用同一个激活身份。
- 确定性的 sha256 id 截断为 32 个十六进制字符，让重放在构造上就是幂等的；身份排序采用 UTF-16 代码单元顺序，跨进程稳定。
- 手写的驱动循环（供给 → 监督 → 选择 → 渲染 → 执行）、监督者唤醒状态机（pending → running → delivered/superseded/retryable_failed/exhausted），以及 Maka 的载荷上限（32 个 addWork 项、64 个输入 id、64 个选中结果、60 000 个指令字符、20 个停止目标、64 个完成结果 id、4 000 个原因字符）。
- Worktree 有意在终态运行后保留——执行器从不释放租约；池释放只在图拆除时接线。
- 一处有记录的刻意偏离：记录是带来源信息的精简复制形态，而非 Maka 的 18 面完整记录。

为适配 harness 所做的改动（以及原因）：

- 控制存储。 Maka 的存储层变成 @deepseek-ai/dsh-storage 上的一个 agent_graph KvUnit——五张权威表，加上执行器适配器新增的 operator_bindings 表——串行在一条写链上，派生唯一性索引在打开时重建，因此撕裂写入会自愈而不是损坏。
- Worktree 租约。 租约身份是派生的（graph_operator_lease_<sha256(graphId, workId, provisionFingerprint)[32]>），并通过 operator_bindings 绑定行持久化——这是真实池在重启后查询的持久提示，因为租约幂等性否则只存在于进程本地。
- 执行接缝。 子级通过 harness 子代理运行时（subagents.start，随附服务商 spawn）运行，而不是 Maka 的会话管理器；协调器从不直接调用服务商。
- 唤醒投递。 Maka 的监督者唤醒被重新表达为宿主运行时，以 harness 的 agent/status === 'idle' 观察接缝为门控（与 Schedule 包使用的同一模式），因此回合运行期间绝不会投递唤醒。
- 工具面。 DSH 没有 direct_only/nesting 工具标志，因此仅限根级的强制放在工具体内（call.sessionId 必须等于控制器的 rootSessionId），Maka 的运行列表映射到智能体循环的回合边界（graph_run_<n> / graph_turn_<n>）——已记录为与 Maka 不完全一致。
- 记录只存在于进程内。 持久权威是一组控制行（schedule、claims、provisions、wakes）；终态操作记录在内存中折叠，宿主重启就会丢失，直到宿主接线补上带归属的持久事件——此时会话投影回退到 schedule/claim 状态。

配置

唯一可配置的行是 graph-host；tool-graph 不接受任何选项。通过行的 config: 覆盖字段——快速开始 下的接线示例就是完整接线。

| 选项 | 默认值 | 用途 |
| rootSessionId | 必填 | 图根会话 id；只有这个会话可以驱动 supervisor 工具，并且它拥有 graph/change 事件 |
| subagentProvider | 必填 | 转发给 subagents.start 的服务商名称；随包提供的进程内服务商是 spawn |
| backend | sqlite | 承载图控制单元的存储后端名称 |
| worktreeRepoRoot / worktreeBaseBranch / worktreeMaxSlots | — | worktree 池几何参数 |
| maxNewActivations | 4 | 每次 reconcile 驱动允许的新操作激活数上限 |

唤醒重试行为固定在代码里，不走配置：retryable_failed 唤醒按 now + 30 s × attemptNumber 重新武装，并在 DEFAULT_MAX_DELIVERY_ATTEMPTS = 3 时持久耗尽。

兼容性

| 组件 | 支持的契约 |
| Node.js | 22.19 或更新 |
| DeepSeek Harness | ^0.2.0-rc.2 peer 范围（dsh-storage、dsh-session、dsh-session-projection、dsh-session-persistence、dsh-agent、dsh-subagent、dsh-compaction、dsh-llm、dsh-tools、dsh-system-prompt）；@deepseek-ai/cordis ~4.0.4 |
| 同级包 | @hy-sde-org/dsh-git —— worktree 引擎（graph-host peer） |
| 存储 | 一个 agent_graph KvUnit；单写者契约——每个进程只能打开该单元一次 |
| 接缝 | subagents、git worktree 引擎（acquire/list）、compaction 维护、会话事件（graph/change）、agent/status === 'idle' 观测；投影注册表可选（没有它就不提供 graph 键） |

设计范围：一个 DSH 会话拥有一个图——每个根多图暂缓——并且 agentGraphController 服务名在每个宿主 fiber 中是单例，所以有多个图根的部署需要在独立 realm 中为每个根配置宿主行。DeepSeek Harness 是开发者预览版；上游接缝契约变更需要发布新包并做契约评审。

开发

pnpm install
pnpm check # strict typecheck across all packages
pnpm test # vitest suites per package
pnpm build # tsc -> dist for every package
pnpm pack:all # pack every package (runs each prepack build)
每个包也有自己的 clean/build/check/test/prepack。测试套件跑在真实的 SQLite 存储之上：graph-stream 检验投影、校验、交接和端到端驱动场景；graph-executor 把假的 pool/runner 与真实存储配对；graph-wakes 使用假的空闲观察器；graph-host 伪造 subagents/worktrees/compaction 这几处接缝；graph-control 直接测试存储契约。每个子包的 README（链接见 Packages）都深入介绍了自己的接口面。

许可证与署名

本仓库采用 MIT 许可证（© 2026 hy-sde，见 LICENSE）。各模块源自 DeepSeek Harness 代码库（MIT，© 2026 DeepSeek）以及 Apache Maka（Apache-2.0，© the Apache Software Foundation —— “Apache Maka Incubating”）；根据 THIRD-PARTY-NOTICES.md，Apache License 2.0 文本适用于源自 Maka 的模块，仓库其余部分为 MIT。各子 README 中引用的 Maka 参考：agent-graph 流调度草案（第 7 章）、git-worktree-child-executor.ts、session-manager.ts、agent-graph-supervisor-wake.ts 和 stream-graph-supervisor-tools.ts。

这些包是各自独立的可安装组件；harness 仍归其自身项目所有。