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

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

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

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

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

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

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

## 中文简介

代理图管理器唤醒交付：闲置门控主机运行时的持久唤醒行。

## 安装

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

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

## README

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

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

## 总结

`dsh-graph-wakes` 是Agent Graph管理器唤醒路径的交付一半。 `dsh-graph-control` 已拥有持久尾流行(`pending | running | waiting_permission | delivered | superseded | retryable_failed`）; 此包提供进程本地运行时，该运行时将适当的唤醒传递到其所属的根会话中 **在下一个空闲边界处** -从不在一个回合运行时-并通过商店自己的开始/完成CAS持久地解决每个尝试。

运行时是有意解耦的。 `GraphWakeRuntime` 取一个存储缝(`GraphControlStore` 在结构上满足它) `deliver` 接收的钩子 `{ graphId, wakeId, rootSessionId, snapshotVersion }` (主机接线重新驱动 `AgentGraphCoordinator` 并排队管理检查点（运行时从不导入协调器），这是可选的 `onCompact(sessionId)` 压缩钩子，以及一个可注入的空闲观察者。交付是由构造闲置控制的：唯一的交付入口点是 `handleIdle()`，注入的观察者向前移动 `agent/status === 'idle'` 它的边界——与Schedule包使用的状态观察缝相同——因此运行时不会自行启动交付。守灵可能会安排在未来 `dueAt` 被束缚着 `recurMs` 变成循环的工作(参见 [定期和经常性的觉醒](https://npmcn.com/package/%40hy-sde-org/dsh-graph-wakes/#readme-scheduled-and-recurring-wakes)）。

这个包不提供任何工具、提示符或插件行——宿主程序集挂载运行时，并提供观察者和交付钩子。

## 目录表

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

## 使用这个包

```ts
import { GraphWakeRuntime } from '@hy-sde-org/dsh-graph-wakes'

const runtime = new GraphWakeRuntime({
  store, // GraphControlStore (structural seam)
  deliver: async ({ graphId, wakeId, rootSessionId, snapshotVersion }) => {
    await coordinator.wake() // host wiring: re-drive the graph, enqueue the checkpoint
    return { kind: 'delivered' }
  },
  onCompact: sessionId => ctx.compaction.compactIfNeeded({ session }, 'context-overflow', signal).then(() => {}),
  observeIdle: onIdle => {
    return ctx.on('agent/status', ({ agent, status }) => {
      if (status === 'idle') onIdle(agent.id)
    })
  },
})

runtime.start('session-root') // scope: one root; observe every root when omitted
await runtime.handleIdle('session-root') // the delivery entry point (and test hook)
await runtime.stop() // unsubscribe, cancel timers, await the in-flight sweep
```

```ts
// Accessors
await runtime.pendingWakes('graph_g1') // pending + retryable wakes (terminal statuses excluded)
await runtime.wakeStatus('graph_wake_abc') // durable row, any status
```

```ts
import type { ScheduleAgentGraphSupervisorWakeRequest } from '@hy-sde-org/dsh-graph-control'

// A future or recurring wake: durable, exactly-once per wakeId.
const driftSweep: ScheduleAgentGraphSupervisorWakeRequest = {
  graphId: 'graph_g1',
  wakeId: 'graph_wake_drift_sweep', // chains as `${wakeId}#occurrence-1`, -2, …
  snapshotVersion: 'rev-3',
  rootSessionId: 'session-root',
  dueAt: Date.now() + 60_000, // epoch ms; withheld until then (undefined = immediately due)
  recurMs: 60_000, // optional: next occurrence scheduled after each delivery
}
// Hand `driftSweep` to the durable store's scheduleSupervisorWake.
```

## 理解实现

### Idle-gated交付

交付只从 `handleIdle(sessionId?)`. `start(rootSessionId?)` 注册注入的 `observeIdle` 观察者，它的生产布线返回 `agent.ctx.on('agent/status', …)` 谨慎, `status === 'idle'` 完全像时间表插件；观察者仅仅转发到 `handleIdle`． 空闲信号在转弯之间发射，所以转弯运行时不会产生尾流；交付钩子本身必须通过拥有代理的维护/空闲接缝（主机布线）运行尾流，镜像如何运行 `ScheduleRuntime` 声明空闲阶段 `runMaintenance` 之前 `followup()`. `start` 永远不会自己送达。观察者只报告活的根，因此枚举的范围自然局限于可以实际接收到一个回合的会话；重新武装的计时器只是一个重新驱动的提示，仍然可以进入 `handleIdle`.

### 交付尝试和持久状态机

对于每个到期唤醒，运行时调用存储的 `beginSupervisorWakeAttempt` 带有确定的尝试id (`graphWakeAttemptId(wakeId, attemptIndex)`， `turnId` 相同的值)：存储增量 `attemptCount` 并移动尾流 `pending → running` 在它的写链下原子地，一旦行被交付或取代就拒绝。然后，通过解决交付钩子的结果 `completeSupervisorWakeAttempt`：

| 交付结果 | 持久尝试状态 | 武装? |
| --- | --- | --- |
| `delivered` | `delivered` | 没有(除非 `recurMs`：计划下一次发生) |
| `waiting_permission` | `waiting_permission` | 否（停至主机恢复） |
| `superseded` / `stopped` | `superseded` | 否 |
| `retryable_failed` | `retryable_failed` | 是的，除非筋疲力尽 |

### 重试、退出和终端失败

一、 `retryable_failed` 结果重新武装了守夜人 `outcome.nextAttemptAt` 或者 `now + 30 s × attemptNumber` (默认值: `DEFAULT_RETRY_BACKOFF_MS`， `DEFAULT_MAX_DELIVERY_ATTEMPTS = 3`）; 重新手臂是进程本地和分段计时器重新驱动 `handleIdle` 为所属根。一次 `attemptCount` 到达 `maxAttempts` 运行时持久地耗尽尾流(`exhausted`（最后一个失败原因在尾流行）：它离开未处理/可重试的列表，永远不会重新武装，并且在重启期间保持终端状态。

### 定期和经常性的觉醒

尾流行可以携带一个epoch-milliseconds `dueAt`：在此之前，扫描将保留交付，并且未来到期的尾流不会获得任何尝试行(`dueAt === undefined` 保留历史上立即到期的行为)。调度是一个存储级的只发生一次的中断 `store.scheduleSupervisorWake` 键控的 `wakeId` -因此重试调度程序或重放重启不能重写已声明的行。两个 `dueAt` 和 `recurMs` 是持久的尾流行字段。

守夜 `recurMs` 链条：发货后(仅限 `delivered` （可重试的、被取代的或停止的结果永远不会重复出现），运行时在确定性id下调度下一个事件 `${baseWakeId}#occurrence-${n}` （occurrence 0是预定的基本id；该id不嵌入任何其他内容） `dueAt = delivery time + recurMs`，同样的分段重臂定时器重新驱动 `handleIdle` 为新的到期时间。停止抑制仍然适用：已完成、已停止或已关闭的图不会安排下一次发生，而在停止之前已经安排的事件将像任何应有的唤醒一样被取代。

### Context-overflow复苏

当快递返回时 `retryable_failed` 与 `overflow: true`，运行时调用 `onCompact(rootSessionId)` 每个尾流最多一次，然后立即为一个有界的部分交付重新武装（交付钩子决定部分形状并报告它） `partialResult: true`）. 如果局部尝试本身溢出，或者在压缩之后到达溢出而没有声明局部，则运行时拒绝第三个相同的完整交付：尾流终止(`exhausted` 恢复状态)。没有 `onCompact` 连线，溢出的尾流在第一次尝试后终止。尝试行没有 `partialResult` 列，因此这些标记保持进程本地（请参阅限制）。

### 停止镇压

应有的尾流被取代 **没有交付** 当图的调度日志显示图已停止或关闭时：任何带有 `finish` (图闭合-协调器的 `isClosed` 权限)，或日志停止的权限 `targetId` 是根会话或图形id。后者是图形级停止约定：一个会话拥有一个图形，因此图形停止被记录为针对根标识的停止，而工作项停止（工作id）永远不会取消唤醒。运行时通过在每次扫描时折叠持久日志而不是信任进程状态来镜像Schedule包的停止-取消-到期记录行为。

### 单次飞行和幂等

重叠的空闲信号合并成一个串行扫描（单次飞行，在结算期间信号着陆时重新请求），存储CAS在第一次交付时进行一次尝试：第二次运行时或重试扫描，开始相同的尝试id观察 `acquired: false` 却什么也没提供。存储故障通过 `onError` 离开尝试区 `running` 用于主机恢复；一个投掷的钩子固定为 `retryable_failed` 带着钩子的信息。

### 重启耐久性

运行时所需的所有状态都在存储中：一个新鲜的 `GraphWakeRuntime` 在同一商店看到相同的尾流行-包括他们的 `dueAt`/`recurMs` 时间表-重新武装孤儿 `retryable_failed` 在下一个空闲时间醒来（像玛卡一样） `recover`)，并持久地耗尽任何at-cap可重试的行，而不是使其不稳定。后退时间戳、溢出标记和重新武装计时器本身是进程本地的，并且故意不持久化。

## 进一步的探索

-   [`@hy-sde-org/dsh-graph-control`](https://npmcn.com/package/%40hy-sde-org/graph-control/README.md)：持久尾流行和此运行时设置的开始/完成CAS。
-   [`@hy-sde-org/dsh-graph-stream`](https://npmcn.com/package/%40hy-sde-org/graph-stream/README.md)： `AgentGraphCoordinator`，由主机重新驱动送钩。
-   [`@deepseek-ai/dsh-schedule`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/schedule/schedule) -观测模式(`agent/status === 'idle'` + `agent.whenIdle`)这个运行时镜像。
-   马卡参考: [`agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-supervisor-wake.ts) （权威尾流语义）。
-   `tests/graph-wakes.spec.ts`：真正的sqlite支持的商店，带有一个假的空闲观察者和交付钩子。

## 模型经验

没有面向模型的表面。这个包是主机端机器；主管工具 `dsh-tool-graph` 模型看到的是什么，主机接线是什么 `deliver` 转到模型可见的检查点。

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

-   尝试行没有 `partialResult` （或溢出）列：one-compact/one-partial标记是进程本地的。重新启动将清除它们，因此可以在重新启动之前再进行一次完整的尝试 `attemptCount` 封顶停止重试；超过上限仍然是不可能的。
-   一次又一次的守夜之间的碰撞 `scheduleSupervisorWake` Write结束递归链（交付的事件保持交付；稍后不会重新派生链）。需要保证循环的主机自己重新驱动调度。
-   在尝试上限时，运行时将持久地耗尽尾流(`exhausted`）; 最后一个可重试的完成和耗尽调用之间的崩溃离开行 `retryable_failed` 在封顶处，下一个空转扫将其排出。
-   `running` 这里不恢复唤醒（开始和完成之间的崩溃）：中断的尝试是否真正完成是一个运行时事实，而控制存储的 `recoverSupervisorWakes` No-op将事实与主机连线保持一致。
-   `waiting_permission` 守灵的人停在那里，再也没有尝试过；权限响应恢复（Maka’s） `notifyPermissionResponse`)被延迟到主机布线。
-   跨进程协调不在范围之内：与协调器一样，运行时是进程本地的，因此持有相同存储的另一个进程不会唤醒此运行时。
-   图级停止约定（使用日志停止） `targetId` 等于根/图id)在这里定义；工作项停止不会抑制唤醒。 `dsh-tool-graph` 必须提交图形停止与根身份的抑制参与。

## 常见问题

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

代理图管理器唤醒交付：闲置门控主机运行时的持久唤醒行。

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

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

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

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

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

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

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

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

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

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