# @hy-sde-org/dsh-graph-executor 中文文档

规范地址：https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/

版本：0\.2\.1-rc\.5
npm 元数据更新时间：2026-11-01T04:24:45.129Z
中文译文更新时间：2026-11-01T09:23:01.020Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hy-sde-org/dsh-graph-executor
原文对照：https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/?lang=original
项目主页：https://github.com/hy-sde/dsh-graph#readme
源码仓库：https://github.com/hy-sde/dsh-graph

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：46.1 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@hy-sde-org/dsh-graph-stream ^0\.2\.1-rc\.5，@hy-sde-org/dsh-graph-control ^0\.2\.1-rc\.5
- 首次发布：2026-09-10T04:16:17.113Z
- 最新版本发布：2026-11-01T04:24:44.874Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

用于代理图的操作符执行器适配器：确定性工作树租约、持久操作符绑定和带有终端记录发射的子运行序列化。

## 安装

```sh
npm install @hy-sde-org/dsh-graph-executor
```

也可以使用：`pnpm add @hy-sde-org/dsh-graph-executor`、`yarn add @hy-sde-org/dsh-graph-executor`、`bun add @hy-sde-org/dsh-graph-executor`

## README

# @hy-sde-org dsh-graph-executor

英语| [中文](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/README.zh.md)

## 总结

`dsh-graph-executor` 是代理图的子操作符执行器适配器。它实现了协调器 `AgentGraphExecutor` 两个注入接缝的表面：a `GraphOperatorWorktreePool` （获取/发布一个存储库的工作树租约）和 `GraphOperatorChildRunner` （每次激活运行一个提供者支持的子节点）。控制存储保持持久的权限—条款和绑定是行，其他所有内容都是派生的。

供应是确定的和幂等的： `provisionOperator` 派生 `graph_operator_lease_<sha256(graphId, workId, provisionFingerprint)[32]>` 从供应中获取，因此重试采用相同的租赁密钥，并且 `pool.acquire` 每个键都是幂等的（设计为进程本地；绑定行是真正的池在重启后查询的持久提示）。当无法获得租约时，该方法返回 `undefined` 调和者将工作推迟到稍后的驱动。

每个操作符的执行被序列化（一次运行一个子程序），并且每次激活都精确地保存在一个终端记录中：运行者的摘要被截断为16 KiB (`truncateUtf8`， `…` 后缀)，并作为 `AgentGraphRecordSourceEvent` （`facets: ['message', 'terminal']`)通过 `recordSink`;没有发出摘要的失败运行 `[operator failed] <message>`． 一个孩子的失败永远不会抛起 `runClaimedAgentGraphIntent` —记录为观察通道。

这个包不提供任何工具、提示符或插件行——流层协调器和管理器工具会使用它。

## 目录表

-   [使用这个包](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/#readme-use-this-package)
-   [理解实现](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/#readme-understand-the-implementation)
-   [进一步的探索](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/#readme-further-exploration)
-   [模型经验](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/#readme-model-experience)
-   [已知的限制和延迟的工作](https://npmcn.com/package/%40hy-sde-org/dsh-graph-executor/#readme-known-limitations-and-deferred-work)

## 使用这个包

```ts
import { GraphControlStore } from '@hy-sde-org/dsh-graph-control'
import { AgentGraphCoordinator } from '@hy-sde-org/dsh-graph-stream'
import { createGraphOperatorExecutor } from '@hy-sde-org/dsh-graph-executor'

const executor = createGraphOperatorExecutor({
  store,
  pool: worktreePool,       // GraphOperatorWorktreePool over the git worktree engine
  childRunner: childRunner, // GraphOperatorChildRunner over the subagent runtime
  recordSink: recordSink,   // commits AgentGraphRecordSourceEvent rows
  newId,
})

const coordinator = new AgentGraphCoordinator(graphId, {
  store,
  executor,
  recordSource,
  newId,
  maxNewActivations: 4,
})
```

## 理解实现

### Provision：租赁键、绑定、持久行

`provisionKey(request)` 散列 `{ graphId, workId, provisionFingerprint }` 与 `stableHash32`，因此同一供应的重试会重用一个租约键。 `provisionOperator` 然后获得租赁（或采用租赁），坚持下去 `bindOperatorWorktree({ graphId, workId, provisionId, leaseId, path, repoRoot, boundAt })`，最后通过存储提交供应行——与控制存储已经拥有的具有修订条件、闭包阻塞的写相同。获取失败返回 `undefined`;如果没有租约，永远不会写入绑定行。拒绝用不同的租约id重新绑定相同的条文(`binding-conflict`)，因此一个provision只拥有一个工作树。

### 运行：admission、serialization和settlement

`runClaimedAgentGraphIntent` 在每个操作符承诺链上排队激活，因此一个操作符永远不会同时运行两个子节点。在队列内，它首先求值 `admitExecution` （序列化后修订门），并在返回时中止 `cancelled`;然后解析操作符的绑定——通过 `${graphId}:${workId}` 当意图的准备id命名供应工作（动态操作符）时索引，或者通过供应的 `operatorId` 对于以作业者为目标的作业，它重新运行已配置的作业者，并以 `{ sessionId, instructions, workspace: binding.path, runId, labels, abortSignal }`. `concurrencyHint` 可选地限制跨操作符并发运行的子启动。

孩子安顿下来后，一 `AgentGraphRecordSourceEvent` 是建(`runtimeEventId` 从 `newId`， `seq` 1、索赔 `targetRunId`（删节摘要）并交给 `recordSink`;被折叠的 `AgentGraphRecord` 也返回。 `recordSink` 故障传播——终端记录是阻止协调器重新调度相同声明的提交点。

### 控件存储中的绑定

控制存储区获得了一个权威表， `operator_bindings` (行键 `provisionId`)，带派生词 `${graphId}:${workId}` 索引在打开时重建。方法: `bindOperatorWorktree` (幂等相同-租约重新绑定保留原始 `boundAt`;异租约重新绑定抛出 `binding-conflict`)， `readOperatorBinding`， `readOperatorBindingByWork`， `listOperatorBindings(graphId?)`.

## 进一步的探索

-   [`@hy-sde-org/dsh-graph-control`](https://npmcn.com/package/%40hy-sde-org/graph-control/README.md)：存储行（条款、绑定）及其持久性契约。
-   [`@hy-sde-org/dsh-graph-stream`](https://npmcn.com/package/%40hy-sde-org/graph-stream/README.md)： `AgentGraphExecutor`，记录折叠`readCommittedAgentGraphProjection`)， `stableHash32`， `truncateUtf8`.
-   马卡参考: [`git-worktree-child-executor.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/git-worktree-child-executor.ts) （租赁标识、确定性路径、在终端运行中幸存的工作树）和 [`session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) （`runClaimedAgentGraphIntent`）。
-   `tests/graph-executor.spec.ts`：假的游泳池/跑步机加上一个真正的sqlite后台商店。

## 模型经验

没有面向模型的表面。包是主机端机器：它不呈现提示（流层呈现），它记录的终端摘要是主管工具呈现的内容。

## 已知的限制和延迟的工作

-   租赁等幂是进程本地的：真正的池实现在通过匹配重新启动后采用先前租用的工作树 `listWorktrees`;这里没有从存储绑定重新派生租约（绑定是持久提示，而不是租约授权）。
-   工作树有意在终端运行中存活（Maka合同）；执行人永远不会解除租约。池释放是为主机程序集拆图而连接的。
-   `recordSink` 失败作为执行失败传播——协调程序报告它们，主机重试；还没有崩溃一致的终端事件日志。
-   `runClaimedAgentGraphIntent` 注意到ssh -graph-stream README文档(`provisionOperator` 可能会返回 `undefined`）; 这个 `AgentGraphExecutor` 输入 `dsh-graph-stream`的 `src/types.ts` 仍然声明一个非可选条款结果，并期望在集成上排队。

## 常见问题

### @hy-sde-org/dsh-graph-executor 是什么？

用于代理图的操作符执行器适配器：确定性工作树租约、持久操作符绑定和带有终端记录发射的子运行序列化。

### 如何安装 @hy-sde-org/dsh-graph-executor？

在项目目录运行 npm install @hy-sde-org/dsh-graph-executor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@hy-sde-org/dsh-graph-stream（^0\.2\.1-rc\.5）、@hy-sde-org/dsh-graph-control（^0\.2\.1-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hy-sde-org/dsh-graph-executor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @hy-sde-org/dsh-graph-executor 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hy-sde-org/dsh-graph-executor 可以商用吗？

@hy-sde-org/dsh-graph-executor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @hy-sde-org/dsh-graph-executor 还在维护吗？

最新版本 0\.2\.1-rc\.5 发布于 2026/11/01（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。