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 等環境中構建確定性流程的開發者。