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

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

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

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

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

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

- 包体积（解压后）：157 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ~4\.0\.5，@deepseek-ai/dsh-agent ^0\.2\.1-rc\.5，@deepseek-ai/dsh-tools ^0\.2\.1-rc\.5，@hy-sde-org/dsh-graph-stream ^0\.2\.1-rc\.5，@hy-sde-org/dsh-graph-control ^0\.2\.1-rc\.5，@deepseek-ai/dsh-system-prompt ^0\.2\.1-rc\.5，@deepseek-ai/dsh-session-projection ^0\.2\.1-rc\.5
- 首次发布：2026-09-10T04:16:25.575Z
- 最新版本发布：2026-11-01T04:26:39.559Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

代理图管理器工具：view\_agent\_graph， update\_agent\_graph， yield\_agent\_graph通过主机提供的图控制器，与编排：图提示部分。

## 安装

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

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

## README

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

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

## 总结

`dsh-tool-graph` Agent Graph的面向模型的工具层(以Maka的 `stream-graph-supervisor-tools`）. 它贡献了三种工具 `view_agent_graph`， `update_agent_graph`， `yield_agent_graph` -加上 `orchestration:graph` 提示符部分，以及它们运行的主机端控制器。这些工具是仅根的和直接的：只有图的根会话可以调用它们，它们通过id来处理图，而不是将工作生成委托给模型。

主机组成控制-存储和流层包，构造一个 `AgentGraphController`，并在 `agentGraphController` 服务。插件解析该服务 `ctx.get`;当它不存在时，工具仍然会挂载（代理预设永远不会破坏可选主机程序集上的会话创建），并且每个图形工具调用都会失败 `[agent-graph-unavailable]` 直到主机提供控制器。所有持久决策都流经控制器的协调器，因此工具调用只提交一个存储更新，而不会重新运行提供程序。

每个模型可见列表都以显式为界 `omitted` 计数，每一个 `update_agent_graph` 负载在到达存储之前由Maka的判别容忍预处理器进行清理。源三重幂等使重放或重试调用成为no-op：相同的图/会话/密钥负载提交一次并返回现有行。

## 目录表

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

## 使用这个包

```ts
import toolGraph, { createAgentGraphController } from '@hy-sde-org/dsh-tool-graph'
import { GraphControlStore } from '@hy-sde-org/dsh-graph-control'

const store = await GraphControlStore.open(unit)
const controller = createAgentGraphController({
  store,
  rootSessionId: session.id,
  newId,
  options: { executor, recordSource, maxNewActivations: 4 },
})
ctx.provide('agentGraphController', controller)
await ctx.plugin(toolGraph, {})
```

每个图根会话只构造一个控制器。插件的 `apply` 注册三个工具和提示部分；将种子会话的代理与挂载的预设组合在一起 `tool-graph` 使工具解决。

## 理解实现

-   **只是执行**： DSH没有 `direct_only`/`nesting` 工具标志，因此保护装置位于工具体中 `call.sessionId` 必须等于控制器的 `rootSessionId`,否则 `not_root_session`。标识来自实时执行上下文(`agent.session.id` 加上 `turnBoundary` 投影的 `lastTurn`）。
-   **运行/把映射**： DSH没有Maka运行列表，因此一个工具调用映射到代理循环转弯边界： `runId = graph_run_<n>` 和 `turnId = graph_turn_<n>` 从 `lastTurn`, `toolCallId` 从来电显示。地图是有记录的，不是声称与马卡相同。
-   **幂等性**： `graphUpdateId` 散列 `(graphId, sessionId, runId, turnId, toolCallId)`;一个显式的 `idempotencyKey` 替换run/turn/call的所有三个方法，以便在任何以后的回合中重试相同的更新只提交一次(`created: false`（相同的修订，一个存储行）。
-   **预处理器**： `cleanUpdateInput`/`cleanAddWorkInput` 通过discriminator -选择字段 `targetKind` 只保留其中一个 `agentId`/`subagentId`/`operatorId`， `replacementMode: 'none'` 滴 `replaces`，指令被修剪。边界匹配Maka: 32个addWork项，64个输入id， 64个选择结果，60000个指令字符，20个停止目标，64个完成结果id， 4000个原因字符。
-   **视图边界**：通过一个不透明的活动（请求的）工作页面 `work:<id>` 光标（每页64个）；终端工作、停止的目标、记录（被截断的摘要）和准备意图被减少到64，每个都是明确的 `omitted` 计数。 `view_agent_graph` Is total：未知图返回空快照。
-   **后的语义**工具从不轮询 `yield_agent_graph` 调用 `claimSupervisorWake` 当请求的工作、现场索赔或准备意图存在并返回时 `nothing_to_yield` 否则。主机驱动协调并从持久唤醒行唤醒根会话。

## 进一步的探索

-   马卡参考: [`stream-graph-supervisor-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-supervisor-tools.ts).

## 模型经验

模型看到三个工具和一个提示部分（这个包中的其他部分都是模型可见的）：

-   `view_agent_graph` -一个图形的有界快照：工作状态，截断的记录摘要，准备意图， `omitted` 计数和不透明 `nextCursor` 用于分页活动状态。
-   `update_agent_graph` -每次调用一个持久的决策：通过添加工作（每个项目一个标识字段） `targetKind`， `replaces` 一个已存在的工作id)，停止目标，或者完成具有已提交结果id的图。 `idempotencyKey` 使重试安全。
-   `yield_agent_graph` -结束监工的配合，图形工作继续进行；主机在下一个持久检查点唤醒根会话。
-   `orchestration:graph` 提示部分-指示主管放弃而不是投票，每波报告结果，永远不要发明工作id。

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

-   没有图注册表：存储没有创建/列出图操作，所以 `view_agent_graph` 在未知图上返回空快照，而不是 `unknown_graph` （错误代码存在于未来的图形注册表中）。
-   完成的工作停留 `requested` （流层状态模型没有终端工作状态），因此 `yield_agent_graph.pendingWorkCount` 计数请求的调度行——活动（声明/意图）由唤醒门反映，而不是计数。
-   这些工具接受显式的 `workId` 每个addWork项（Maka的扩展），因此更新可以确定地引用自己的新工作；确定性派生的id仍然是默认值。
-   该插件通过手工构建的测试组合来运行；装载机引导的cordis。Yml组合测试被推迟。预定的安装在 [dsh-graph-host自述](https://npmcn.com/package/%40hy-sde-org/graph-host/README.md)：主机行提供控制器，此包作为图根会话的预设行挂载。

## 常见问题

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

代理图管理器工具：view\_agent\_graph， update\_agent\_graph， yield\_agent\_graph通过主机提供的图控制器，与编排：图提示部分。

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

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

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

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

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

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

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

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

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

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