snail30xx/dsh-graph-runtime

dsh-graph-runtime

DeepSeek Harness（DSH）的 graph 运行时能力集，以独立 Cordis 插件/bundle 形式发布。

当前能力：

- 图定义与自动挂载：以 defineGraph 定义"扩展 StateGraph"——图工厂 +
注册声明（是否成为 DSH tool、是否登记注册表）+ 工具入参校验钩子。模块被
加载即完成注册：插件启动时自动挂载已定义的图，其后定义的即时挂载，开发者
无需任何 service 调用。工具名/描述自动发现（compile({ name, description })
或结构合成），编译惰性且记忆化（注册路径零编译副作用），参数校验、取消转发
与结果渲染都由本插件承担。
- GraphRoutingAgent：graph 驱动的路由 Agent。把 graphTools 注册表（可
过滤）交给 LLM，要求必须选择一个工具；对返回的工具调用做存在性、JSON、
schema 与作者 validate 校验，不通过带原因重试（默认 3 次，可配置），
通过后执行对应 graph。每次被选中工具的执行前后有 graphTools/pre-execute /
graphTools/post-execute 两个 waterfall 扩展点（门禁、审计、结果加工）。

安装与接入

发布后
npm install dsh-graph-runtime
或本地路径（例如在 yolo-agent 仓库内）
npm install file:../dsh-graph-runtime

接入方式与其他 DSH bundle 一致，二选一或同时：

- 根组合 cordis.yml 增加一行（本包自带 cordis.patch.yml，web profile 的
dsh.profile.bundles 加入包名后同样自动挂载）：

- id: graph-runtime
name: dsh-graph-runtime

用法

图作者只需 defineGraph——定义即注册，不需要任何 mount 或 service 调用：

// graphs/echo.ts
import { defineGraph } from 'dsh-graph-runtime'
import { Annotation, END, START, StateGraph } from '@langchain/langgraph'

const State = Annotation.Root({
topic: Annotation,
log: Annotation({
reducer: (left, right) => [...left, ...right],
default: () => [],
}),
})

export const echoGraph = defineGraph({
name: 'echo_graph',
description: 'Echo the given topic.',
build: () =>
new StateGraph(State)
.addNode('echo', async (state) => ({ log: [seen:${state.topic}] }))
.addEdge(START, 'echo')
.addEdge('echo', END),
asTool: true, // 声明为模型可见的 DSH tool；默认 false
// asGraphTool: true, // 登记进 graphTools 注册表供发现；默认 true，可省
// validate: (input) => Boolean((input as { topic?: string }).topic), // 入参校验钩子，缺省恒通过
})

唯一的接线要求：graph 模块需要在某个 bundle 入口被 import（barrel 一行
import './graphs' 即可）。插件 apply 时自动挂载已定义的全部图，其后
定义的即时挂载；单个图挂载失败（重名、非法声明）告警跳过，不阻断启动。

asTool: true 的工具注册在插件的全局层：所有 agent（含默认 agent）可见。
需要 scope 私有或运行时动态构造的场景，使用下述命令式入口。

GraphRoutingAgent

参考 dsh ReactLoopAgent 裁剪为单步：一次路由 = LLM 选工具 → 校验 →
（可选重试）→ 执行 graph。

import { GraphRoutingAgent } from 'dsh-graph-runtime'

const router = new GraphRoutingAgent(ctx, {
provider: 'deepseek',
model: 'deepseek-chat',
filter: { allow: ['echo_graph', 'search_graph'] }, // 同 tools.restrict 的 allow/deny
maxRetries: 3, // 校验不通过时重新调用 LLM 的最大次数，默认 3
// fallback: myFallbackTool, // 可选：覆盖内置兜底 tool
})

const outcome = await router.route({ input: '帮我回显一下 hello' })
// outcome: { tool: 'echo_graph', args: {...}, result:  }

行为细节：

- 必须选工具：dsh-llm 的 GenerateOptions 没有 toolChoice 字段，
"required" 语义由循环兜底——模型未选择任何工具（纯文本回复）时不重试，
直接执行兜底 tool 并在结果上标记 fallback: true。缺省兜底是内置的
graph_routing_fallback（什么都不做：空入参、返回 {}）；可通过
fallback 传入 ToolDefinition 或 GraphDefinition 覆盖，覆盖者自行
保证空入参 {} 能通过其 schema（如 parameters: {}）。
- 校验链（任一不通过即带原因重试）：工具存在于（过滤后的）注册表；
参数是合法 JSON；执行期 schema 校验（ToolArgsError）；作者 validate
钩子（GraphValidationError，经路由时携带 context.request 可做语义
拒绝）。graph 自身的运行失败不是路由失败，原样上抛。
- 过滤：filter 的 allow/deny 语义同 tools.restrict（可同给取交集）；
名单含未知工具或过滤后为空视为配置错误。
- 重试用尽后以最后一次失败原因收场。

路由扩展点

被路由的执行不走 dsh 的 ctx.tools 管线（那是另一套注册面），管线
形态的扩展点因此落在路由循环自身：以 cordis waterfall 事件提供，每个
被选中工具的尝试在 graph 执行前经过 graphTools/pre-execute、在执行
落定后经过 graphTools/post-execute。审计日志、指标、策略门禁、结果
加工都挂在这两个事件上：

// 执行前门禁：deny 的原因会反馈给模型重试，与 validate 拒绝完全一致。
ctx.on('graphTools/pre-execute', async (execution, next) => {
if (disabledTools.has(execution.tool)) {
return { kind: 'deny', reason: "${execution.tool}" 已被策略禁用 }
}
return next()
})

// 观察或改写落定结果；成功与失败都会经过。
ctx.on('graphTools/post-execute', async (execution, outcome, next) => {
if (execution.tool === 'search_graph' && !('error' in outcome)) {
return { kind: 'accept', result: redact(outcome.result) } // 替换返回值
}
return next()
})

语义：

- execution 携带 tool / args / request（原始路由文本）/
signal；同一次尝试的两个事件收到同一个 execution 对象。
- waterfall 顺序：监听器按注册顺序执行；next() 表示放行并委托后续，
不调 next() 直接作答则否决余下监听器——第一个决策生效。
- deny（pre）与 block（post）并入常规重试循环：原因反馈给模型，
重试用尽后抛标准错误。block 拒绝的是任何已落定的结果——也可以把
本会上抛的 graph 错误转化为一次带原因的重试。
- accept 维持落定结果；携带 result 时替换返回给调用方的值（各监听
器观察到的仍是原值）。
- 兜底路径（模型未选工具）不经过这两个事件；如需在兜底上加钩子，请
自行包装 fallback 工具的 execute。监听器抛错会原样上抛。监听器用
普通 ctx.on 注册（与任何 cordis 事件一致）；监听器内 this 是
Agent 所在的 ctx。

注册声明

| 字段 | 说明 |
| --- | --- |
| asTool | 是否注册为模型可见的 DSH tool（ctx.tools）。默认 false；自动挂载路径注册在插件全局层（所有 agent 可见），命令式 mount 路径注册在传入 ctx 的层。 |
| asGraphTool | 是否登记进 graphTools 注册表供发现（get/list、GraphRoutingAgent）。默认 true。 |

defineGraph 字段

| 字段 | 说明 |
| --- | --- |
| name | 图名，即注册后的 tool 名；全局唯一，禁用保留名 run_code。 |
| description | 可选。面向模型的工具描述；缺省时取 build() 产物上 compile({ description }) 写入的描述（作者自行编译时），或由节点与 state 键合成的结构描述。 |
| build | 图工厂：返回未编译 builder（插件在首次调用时 plain compile()，不传任何选项），或作者自行编译的实例。checkpointer 等编译选项完全归作者所有——要 state 记忆就返回 builder.compile({ checkpointer: new MemorySaver() })。 |
| validate | 可选的工具入参校验钩子：graph 执行前收到 (input, context)，context.tool 是工具名，经 GraphRoutingAgent 路由时 context.request 携带原始请求文本（直连调用时无此字段）。返回 false 或抛错即拒绝（抛错 message 进入拒绝原因）；缺省恒通过。据此可实现"这个请求不属于我"的语义拒绝，路由循环会带原因重试。 |
| parameters | 可选的 DSH ParameterSchemaSpec。提供时整个参数对象作为 graph 输入；缺省时工具暴露唯一的必填 input JSON 参数（其描述会拼上结构发现的 state 键名，但值本身不透明）。模型可见的图应始终声明，见下节。 |
| threadId | 可选的线程键；仅透传为 graph config 的 thread_id。是否形成 state 记忆由 graph 自带的 checkpointer 决定（插件不代管）。 |
| configurable | 可选的 configurable 附加键透传（thread_id 以 threadId 为准）。 |
| timeoutMs | 可选的协作式超时预算；graph 必须响应取消信号并收敛。 |

参数 schema 质量（模型可见的图必读）

parameters 原样透传为 DSH ParameterSchemaSpec 并在执行前强制校验
（越界枚举、类型不符、缺 required 都会被 ToolArgsError 拦下）。给模型
看的图，请保证每个参数类型明确、描述具体、枚举列全：

defineGraph({
name: 'greet_graph',
build: () => buildGreetGraph(),
parameters: {
name: { type: 'string', required: true, description: 'The name to greet.' },
style: {
type: 'string',
required: true,
enum: ['formal', 'casual'],
description: 'Greeting style.',
},
times: { type: 'integer', description: 'Repeat count.', default: 1 },
tags: { type: 'array', items: { type: 'string' }, description: 'Extra tags.' },
},
})

支持的能力：type 取 string / number / integer / boolean / null / array /
object / json，联合用 oneOf；每个键可带 description / title / default /
examples；枚举用与类型匹配的 enum（如字符串数组），单值约束用 const；
嵌套对象用 object + properties + additionalProperties，数组用 items；
逐键 required: true 标注必填。

为什么不自动派生：langgraph 在编译时即丢弃 Annotation 的类型信息，
运行时结构只剩键名与聚合语义——伪造类型或 required 的 schema 会误导模型
拼出被校验层拒绝的参数，比诚实的 input 更糟。因此未声明 parameters
的兜底是单一必填 input（json），结构发现的 state 键会拼进它的描述
（如 Expected state keys: topic, log (accumulated).）；asTool: true
且未声明参数时，挂载路径会经 ctx.logger 打一条 warn 提醒作者。

命令式入口（动态/低层场景）

// 运行时动态构造的图：createGraphDefinition 只构造不发布（defineGraph
// 会自动挂载，插件活跃时再显式 mount 会双重注册），配合显式 mount；
// ctx 是 fiber 归属与 tools 注册落点。
const dynamicGraph = createGraphDefinition({
name: 'dynamic_flow',
build: () => buildDynamicGraph(),
asTool: true,
})
const mounted = ctx.graphTools.mount(dynamicGraph, ctx)

// 发现侧：ctx.graphTools.get('echo_graph') / ctx.graphTools.list()

// 手里已是编译产物、或只想一次性转换：
const entry = ctx.graphTools.register(compiledGraph, ctx)
const tool = ctx.graphTools.create(compiledGraph)

也可以直接 import { createGraphTool } from 'dsh-graph-runtime' 做纯转换，
效果等价。向 register 传图定义会得到指向 mount 的错误——图定义自带
注册声明。defineGraph 面向图作者（声明即发布、自动挂载）；
createGraphDefinition 面向运行时动态场景（构造归构造，挂载归挂载）。

行为契约

- 定义即注册：defineGraph 把图定义发布到包级静态队列；插件 apply 时
接管并清空积压，其后定义的图即时挂载。单个图挂载失败（重名、非法声明）
经 ctx.logger 告警跳过，不阻断启动；插件释放后 defineGraph 重新入队，
可随插件重载再次挂载。
- 注册只是注册：defineGraph/mount/register 全程不调用 langgraph 的
compile()；未编译 builder 在该 tool 首次实际调用时才 plain compile()
一次并记忆化（结构发现只读取 builder 的 nodes/channels，同样不触发编译）。
- checkpointer 归 graph：插件从不注入或代管编译选项；threadId 仅是
thread_id 透传，记忆是否生效取决于作者在 build() 里返回的实例。
- 每次工具调用即一次 graph.invoke；工具入参先经 DSH 参数 schema 校验与
作者 validate 钩子，再进入 graph；调用方的 AbortSignal 原样转发。
- graph 最终 state 必须是 lossless JSON，否则以明确错误拒绝；工具结果以
pretty JSON 文本块返回给模型。
- 与 ctx.tools 的交互只发生在声明 asTool: true 时：自动挂载路径注册在
插件的全局层（所有 agent 含默认 agent 可见）；命令式 mount(definition,
ctx) 注册在传入 ctx 的层（agent scoped ctx 上则仅该 agent 可见并 shadow
全局同名工具）。graphTools 注册表是独立状态：登记名唯一、unregister
幂等、随挂载路径的 fiber 释放自动移出。
- 自动发现的边界：Annotation 的类型信息与 addNode 的 description 在
langgraph 编译时即被丢弃，参数 schema 无法自动派生。自定义 GraphInvocable
缺少运行时字段时发现安全降级，但名字必须显式提供。