Agent DAG Workflow：Host-neutral 的智能体 DAG 工作流运行时

前言¶

在 DeepSeek Harness (DSH) 或 Codex 等环境中，Agent 常常以离散方式调用 Tool 或 Skill。如果没有结构，这些调用难以保存、校验或恢复。@gm-hz/agent-dag-workflow 提供了一个解决方案，它允许 Codex、DSH 或其他 Agent 复用已有的 Tool、Skill 与 MCP，将离散调用组织成可保存、校验、恢复、审计和重放的 WorkflowTemplate JSON。

这是什么¶

这是一个 Host-neutral DAG Workflow Runtime，由 GM-HZ 维护。它不是另一个 Coze 或 Dify 平台，也不内建模型 Provider、凭据中心或 Tool 市场。Host 继续负责已有的 Agent/Tool/Skill/MCP 生态；本项目只负责把离散能力变成稳定流程。

核心功能¶

Host-neutral DAG Workflow Runtime：支持 Codex、DSH 和嵌入式 Host。
CLI-native access：提供简写 adw 和完整命令 agent-workflow，支持本地数据库存储。
Fixed MCP Gateway：提供固定的 MCP Tool 网关。
On-demand Skills：支持按需激活 Skills。
Triggers：支持 Cron、Webhook 和 Channel 触发器。
Replay and Trace support：支持运行追踪和重放。
Visual Canvas：提供可视化 Canvas 设计能力。
WorkflowTemplate JSON：使用单一 JSON 定义，支持 Schema 校验、审计和重放。
Journal and Checkpointing：支持 Journal 和 Checkpointing，用于持久化状态。
Multi-host support：支持多宿主环境。

安装与启用¶

运行前请确保 Node.js 版本为 22.19 或更高版本。

npm install @gm-hz/agent-dag-workflow

该包作为单一模块发布，通过子路径导入按需引用特定功能：

import { WorkflowRuntime } from '@gm-hz/agent-dag-workflow'
import { SqliteWorkflowRunStore } from '@gm-hz/agent-dag-workflow/sqlite'
import { createMcpGateway } from '@gm-hz/agent-dag-workflow/mcp'
import * as DshWorkflow from '@gm-hz/agent-dag-workflow/dsh'

典型用法¶

CLI 操作¶

CLI 提供简写 adw 和完整命令 agent-workflow，二者完全等价。CLI 默认使用当前目录的 .agent-dag-workflow.db，也可用 --db 指定 SQLite 文件。

adw validate examples/script-transform.workflow.
adw draft put examples/script-transform.workflow. --db workflows.db
adw publish script-transform-demo --expected 1 --db workflows.db
adw run script-transform-demo@1 --input input. --db workflows.db
adw trace <runId> --events --db workflows.db
adw replay <runId> --mode recorded --db workflows.db

SDK 集成¶

SDK 用例示例（最小化，仅执行确定性 JSON 变换）：

import {
  InMemoryWorkflowCatalogRepository,
  InMemoryWorkflowRunStore,
  WorkflowNodeRegistry,
  WorkflowRuntime,
  WorkflowTemplateCatalog,
  registerCoreNodes,
} from '@gm-hz/agent-dag-workflow'

const nodes = new WorkflowNodeRegistry()
registerCoreNodes(nodes)

const catalog = new WorkflowTemplateCatalog(
  new InMemoryWorkflowCatalogRepository(),
  nodes,
)

const runtime = new WorkflowRuntime({
  nodes,
  catalog,
  runStore: new InMemoryWorkflowRunStore(),
})

const template = {
  apiVersion: 'workflow.gm-hz.dev/v1',
  kind: 'WorkflowTemplate',
  metadata: { id: 'hello', name: 'Hello' },
  spec: {
    inputSchema: {
      type: 'object',
      required: ['name'],
      properties: { name: { type: 'string' } },
    },
    outputSchema: {
      type: 'object',
      required: ['message'],
      properties: { message: { type: 'string' } },
    },
    requires: [{ kind: 'script-runtime', uses: 'json.expr@1' }],
    nodes: [
      { id: 'start', uses: 'core.start@1', with: {}, inputs: {} },
      {
        id: 'format',
        uses: 'core.script@1',
        with: { language: 'json.expr@1', source: '{ message: "Hello, " + input.name }' },
        inputs: { name: { input: { path: ['name'] } } },
      },
      {
        id: 'end',
        uses: 'core.end@1',
        with: {},
        inputs: { message: { output: { nodeId: 'format', path: ['message'] } } },
      },
    ],
    edges: [
      { id: 'start-format', source: 'start', target: 'format' },
      { id: 'format-end', source: 'format', target: 'end' },
    ],
    outputs: { message: { output: { nodeId: 'end', path: ['message'] } } },
  },
}

const handle = await runtime.launch({
  target: { type: 'inline', template },
  inputs: { name: 'Workflow' },
  authorityRef: 'sdk:local',
  authority: {},
  origin: { type: 'sdk' },
})

console.log(await handle.result)

适用场景与注意¶

适用场景：需要将离散的 Tool 调用组织成结构化、持久化工作流，且需要校验、审计和重放能力的 Agent 开发。

注意事项：
* Host 责任：该插件不提供内建模型 Provider、凭据中心或 Tool 市场。Host 负责维护 Agent/Tool/Skill/MCP 生态。
* Script 纯 JSON：Script 仅包含纯 JSON，不支持网络请求、文件读写、环境变量、密钥或动态代码执行（eval）。含外部副作用的循环必须使用 core.foreach@1。
* 权限收窄：权限遵循 Template requires -> Node uses -> Host Policy 的收窄逻辑。
* 触发器逻辑：Cron、Webhook、Channel 等触发器只产生可信 Envelope，不直接进入 DAG，需通过固定 Binding 启动发布修订。
* 依赖适配器：Queue/Runner 是可选适配器，默认由当前 Agent、CLI 或 Host 直接调用 Runtime。

总结¶

@gm-hz/agent-dag-workflow 提供了一套 Host-neutral 的 DAG 工作流运行时，通过单一 JSON 定义连接 Tool、Skill 与 MCP。它支持校验、审计、恢复与重放，适合需要在 DeepSeek Harness 或 Codex 等环境中构建确定性流程的开发者。