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

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

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

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

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

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

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

## 中文简介

代理图流层：纯派生（记录、跟踪、准备、移交、调度协调）和流程本地协调器。

## 安装

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

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

## README

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

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

## 总结

`dsh-graph-stream` 是Agent图的派生层。它层层叠叠 `@hy-sde-org/dsh-graph-control` （持久决策存储）和拥有 **可以从提交的行重新计算的所有内容**：工作状态投影、记录折叠、跟踪/路线派生、准备意图、输入切换和单次飞行协调驱动程序(`AgentGraphCoordinator`)，它沿着Maka编写的驱动循环（供应→监督→选择→渲染→执行）对该存储。

拆分遵循Maka的一个硬性规则：存储是权威，流层除了通过存储自己的commit/claim/provision方法外，永远不会写入任何内容。这里的每一个投影都是确定的和纯粹的——重新计算它永远不会开始工作；允许和执行是存储密封的（在它观察到的时间表修订时，使用预先分配的转弯/运行身份进行索赔）。

id是确定的sha256切割为32十六进制字符(`graph_intent_…`， `graph_operator_…`， `graph_edge_…`， `graph_route_…`， `graph_record_…`， `graph_claim_…`)，因此重播在构造上是幂等的。标识比较使用UTF-16代码单元顺序(`compareAgentGraphIdentity`)，而不是语言环境比较。

这个包不提供任何工具、提示符或插件行——执行器适配器和管理器工具会使用它。

## 目录表

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

## 使用这个包

```ts
import Storage, { storageBackendServiceKey } from '@deepseek-ai/dsh-storage'
import { GraphControlStore } from '@hy-sde-org/dsh-graph-control'
import { AgentGraphCoordinator } from '@hy-sde-org/dsh-graph-stream'

const backend = await ctx[storageBackendServiceKey('sqlite')]
const unit = await backend.kv.open(GraphControlStore.descriptor)
const store = await GraphControlStore.open(unit)

const coordinator = new AgentGraphCoordinator(graphId, {
  store,
  executor: { provisionOperator, runClaimedAgentGraphIntent, stopSession },
  recordSource,
  newId,
})

await coordinator.scheduleUpdate({ graphId, addWork: [work] }) // commits, then wakes the drive
const result = await coordinator.reconcileAndWait()             // runs one drive to idle
```

## 理解实现

### 确定性恒等式和排序

`stableHash(value)` ＝ `sha256:` +十六进制的规范化JSON(排序对象键， `undefined`/函数/→象征 `"[undefined]"`， bigint→数值型字符串； `required`/`enum` 排序为 `localeCompare`，日期→ISO)。所有id都使用前32个十六进制字符。 `compareAgentGraphIdentity` UTF-16代码单元顺序在进程中是稳定的吗 `localeCompare`.

### 预测

-   **安排投影** （`projectAgentGraphSchedule`)：将仅追加的更新日志折叠到模型可见的工作视图中；验证连续性（从1开始的修订），完成后没有更新，没有重复的工作id，错误的图id被拒绝。 `stopped` 赢了 `superseded`.
-   **记录褶皱** （`readCommittedAgentGraphProjection`)：从每个（操作员，会话）提交的事件中派生仅引用的记录；跳过部分事件；每次激活最多一个终端记录；确定的订单。
-   **跟踪** （`validateAgentGraphTraceTopology`， `buildAgentGraphTraceSnapshot`)：验证DAG（重复的id /端点，自循环，未知操作符，通过Kahn的循环）并派生出一条路由（记录×传出边）。
-   **准备** （`buildAgentGraphReadinessSnapshot`): map策略-每条路由通过声明的传入边缘接收一个意图，并根据触发记录进行密封(`policyFingerprint`， `readinessContextFingerprint`， `graph_intent_…` 通过稳定哈希)。
-   **切换** （`hydrateAgentGraphInputHandoffs`， `renderAgentGraphScheduledWorkPrompt`)：解析有界结论文本(16 KiB/条，共48 KiB； `…` 省略号（对代码点进行二进制搜索）并呈现操作符提示符：指令+ `GRAPH_OPERATOR_HANDOFF_PROTOCOL` + `<agent_graph_input_handoffs>` 与 `<` 逃出来的一样 `\u003c`． 记录保持仅供参考；文本仅在呈现时解析。

### 和解和协调者

`reconcileAgentGraphSchedule` 走Maka的阶段：A提供操作符→B派生主管意图→C选择（现有索赔总是；新的上限） `maxNewActivations`、过剩→ `activation_limit`)→D呈现（全部或失败）→E执行(在修订时索赔→运行 `admitExecution` =在修订时开始执行)。状态: `reconciled | waiting | limit_reached | failed | cancelled | stale`. `applyScheduleStops` 替换(`status: 'superseded'`)、取消索赔和批量停止会话。

`AgentGraphCoordinator` 是流程本地单次飞行驱动程序： `scheduleUpdate` 提交一行然后唤醒驱动器； `reconcileAndWait` 恰好连接一个驱动器； `recover` 重新启动后，以非空调度恢复图； `stop`/`wake`/`isClosed` 表面相同的生命周期。当工作或停止的目标仍然存在时，驱动器重新运行，并将现有的索赔视为已经分派（执行者根据索赔id进行重复）。

### 遗嘱执行人缝

```ts
export interface AgentGraphExecutor {
  provisionOperator(request: AgentGraphOperatorProvisionRequest): Promise<AgentGraphOperatorProvisionResult | undefined>
  runClaimedAgentGraphIntent(input: AgentGraphRunClaimedIntentInput): Promise<void>
  stopSession(sessionId: string, opts?: { reason?: string }): Promise<void>
}
```

协调器从不直接调用提供者——执行器包提供子代理/工作树支持的实现。

## 进一步的探索

-   [`@hy-sde-org/dsh-graph-control`](https://npmcn.com/package/%40hy-sde-org/graph-control/README.md)：该层折叠的持久行。
-   `src/reconcile.ts` / `src/coordinator.ts`：驱动回路和状态推导。
-   `src/hash.ts` / `src/identity.ts`：每个id和指纹所依赖的规范化和排序原语。
-   `tests/graph-stream.spec.ts` / `tests/reconcile.spec.ts`：投影、验证、切换和端到端驱动场景，针对真实的sqlite支持的存储。

## 模型经验

该包是纯TypeScript，具有狭窄的、单一职责的模块，没有环境状态。类型是显式的；结果是普通数据（除了协调器之外，没有跨模块边界的类实例）。错误进行 `reason` 验证失败和存储冲突错误的代码不加更改地传播。

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

-   准备策略类型： `map` 只有- - - - - - `all_settled` 而管理就绪类型则被推迟到管理工具层。
-   没有客户端投影/检查点(`onCheckpoint`);没有工具视图分页；住院医师是不可能的。
-   映射策略意图是派生的，但不是由调和器自动分派的——它们会出现在管理器工具上。
-   唱片的形状是带有出处的复制（细长），故意偏离了Maka的18面全唱片；流层永远不会改变存储的记录。
-   协调器是进程本地的：持有相同图存储的另一个进程不会自动唤醒这个驱动程序（唤醒传递是） `dsh-graph-wakes`）。

## 常见问题

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

代理图流层：纯派生（记录、跟踪、准备、移交、调度协调）和流程本地协调器。

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

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

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

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

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

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

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

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

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

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