zerosloney/dsh-state-graph

安装

## 这是什么

`dsh-state-graph` 是一个 **dsh bundle 包**：导出一个 cordis 插件（`state-graph`），提供 `ctx.graph` 服务。插件的核心是设计文档《状态图（StateGraph）编排引擎技术方案与架构设计》中的有向状态图运行时内核：

| 能力 | 落点 |
| --- | --- |
| 声明式拓扑构造（Fluent API：addNode / addEdge / addConditionalEdge） | `StateGraph` |
| 纯函数增量补丁：节点只返回 `Partial<State>`，引擎不可变合并 | `StateGraph.run` |
| 防死循环熔断（默认 25 次迭代，超限抛错） | `StateGraph` 内置 |
| 双向事件流观测（`graph/*` 事件，追加式轨迹） | `ctx.emit` 事件总线 |
| 隔离的状态图实例工厂 | `ctx.graph.create()` |

## 核心接口

| 接口 / 类型 | 签名 | 说明 |
| --- | --- | --- |
| `NodeHandler<T>` | `(state: T, ctx: Context, signal?: AbortSignal) => Promise<Partial<T>> \| Partial<T>` | 节点业务执行体，返回需合并的状态增量；第二参数仍为 `ctx`，第三参数接收本次运行的取消信号 |
| `ConditionHandler<T>` | `(state: T, ctx: Context, signal?: AbortSignal) => string \| Promise<string>` | 动态路由，返回下一个 NodeName 或 `"__END__"`；第二参数仍为 `ctx`，第三参数接收本次运行的取消信号 |
| `GraphExecutionResult<T>` | `{ graphId: string; finalState: T; trajectory: string[]; iterations: number }` | 每次执行的 graphId（区分重复/并发轨迹）、最终状态、全量跳转轨迹、迭代次数 |
| `ctx.graph.create<T>(maxIterations?)` | → `StateGraph<T>` | 创建隔离的图实例 |

一次运行可通过 `run(initialState, { signal })` 传入 `AbortSignal`；不传第二参数时保持原有调用方式。引擎会在节点执行、节点结果合并、条件路由以及跳转边界检查取消状态，并把同一个 signal 作为 `NodeHandler` / `ConditionHandler` 的第三参数传入。

### 事件（`ctx.on("graph/…")` 订阅）

| 事件 | 载荷 | 时机 |
| --- | --- | --- |
| `graph/start` | `{ graphId, initialState, entryPoint }` | 图开始执行 |
| `graph/node-start` | `{ graphId, node, state, iteration }` | 每个节点执行前 |
| `graph/node-end` | `{ graphId, node, state }` | 节点补丁合并后 |
| `graph/node-error` | `{ graphId, node, error }` | 节点抛错或被取消中断（随后上抛；取消还会补发 `graph/error`） |
| `graph/error` | `{ graphId, error, state, lastNode }` | 迭代熔断 / 目标节点缺失 / 路由抛错 / 取消（`graph/start` 之后） |
| `graph/end` | `{ graphId, finalState, trajectory, iterations }` | 仅正常终止（END 或无出边） |

`graphId` 标识每次执行（同一图实例的重复/并发运行各自独立生成），用于区分并发图之间可能重名的节点轨迹。`graph/end` 只在正常终止时发出；**所有异常终止统一发 `graph/error` 后上抛**——包括迭代熔断、条件路由返回未注册节点名/非字符串、路由函数抛错，以及 `graph/start` 之后的取消（节点执行中的取消先发 `graph/node-error` 过程诊断、再发 `graph/error` 终态；`graph/start` 之前的预取消无任何事件）。节点自身业务抛错仅发 `graph/node-error` 后上抛。`graph/*` 监听器同步执行且异常会传播进引擎（cordis `emit` 语义），订阅方不应在监听器中抛错。

`logTrajectory` 开启时，插件订阅 `node-start`（debug 级）与 `end`（info 级）把轨迹写入 `ctx.logger("graph")`。

## 安装

作为一个 bundle 包装进某个 profile：

把 zerosloney/dsh-state-graph 加入你的 DSH 配置（web profile）即可启用。