dsh-graph-runtime: DeepSeek Harness 的图运行时能力

前言¶

在 DeepSeek Harness (DSH) 的开发中，直接集成 LangGraph 需要处理图的定义、工具注册以及路由逻辑。dsh-graph-runtime 是一个独立的 Cordis 插件/Bundle，它将 LangGraph 编译图注册为 DSH 工具，并提供一个基于图的驱动路由代理。

这是什么¶

这是一个为 DSH 提供图运行时能力的独立插件。它由开发者 snail30xx 维护，许可证为 MIT。主要解决在 DSH 环境下定义图、自动挂载以及智能路由的问题。

核心功能¶

定义与自动挂载：通过 defineGraph 定义扩展的 StateGraph，模块加载即完成注册。
工具注册：将 LangGraph 编译图注册为 DSH 工具（asTool），自动发现工具名称和描述。
图驱动路由代理：提供一个 GraphRoutingAgent，让 LLM 从图工具中选择一个执行。
验证与扩展：内置工具参数验证钩子，并提供 graphTools/pre-execute 和 graphTools/post-execute 两个扩展点。

安装与启用¶

安装前请确保环境满足依赖要求：
* Node.js >= 22.5
* 依赖项：@deepseek-ai/cordis、@deepseek-ai/dsh-llm、@langchain/langgraph

执行安装命令：

npm install dsh-graph-runtime

在 cordis.yml 的根组合中添加条目（插件自带 cordis.patch.yml，添加包名到配置会自动挂载）：

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

典型用法¶

1. 定义图¶

图作者只需使用 defineGraph 定义图，无需手动挂载或调用服务。

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

const State = Annotation.Root({
  topic: Annotation<string>,
  log: Annotation<string[]>({
    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 工具
})

2. 使用 GraphRoutingAgent¶

使用 GraphRoutingAgent 初始化路由代理，配置模型、过滤器等参数。

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

const router = new GraphRoutingAgent(ctx, {
  provider: 'deepseek',
  model: 'deepseek-chat',
  filter: { allow: ['echo_graph', 'search_graph'] },
  maxRetries: 3, // 验证失败时的最大重试次数
})

const outcome = await router.route({ input: 'echo hello for me' })

3. 利用扩展点¶

通过 ctx.on 监听 graphTools/pre-execute 和 graphTools/post-execute 事件，可以在图执行前后进行审计、策略门控或结果转换。

// 执行前门控
ctx.on('graphTools/pre-execute', async (execution, next) => {
  if (execution.tool === 'restricted_tool') {
    return { kind: 'deny', reason: 'Policy disabled' }
  }
  return next()
})

// 执行后转换
ctx.on('graphTools/post-execute', async (execution, outcome, next) => {
  if (execution.tool === 'sensitive_graph') {
    return { kind: 'accept', result: redact(outcome.result) }
  }
  return next()
})

适用场景与注意¶

这个插件适合需要在 DSH 中通过 LangGraph 构建复杂工作流，并需要统一工具管理和智能路由的场景。

注意事项：
* 插件以当前 DSH 进程的权限运行。
* 使用前建议检查源码与许可证（MIT）。
* 需要支持 TypeScript module (type: module)。

总结¶

dsh-graph-runtime 通过 defineGraph 和 GraphRoutingAgent 封装了 LangGraph 在 DSH 中的集成细节，提供了自动挂载、验证钩子和执行扩展点，简化了图工具的开发与路由逻辑。