Host Adapter 接入

Host Adapter 是 Runtime 与现有 Agent 生态之间的薄边界，不是 Provider 系统。Workflow 仍然只保存 DAG、固定 Tool/Skill 名、输入输出 Schema 和依赖 allowlist；凭据、连接、模型 SDK、MCP Client、DSH Tool 与真实权限都由 Host 持有。

最小接口

只实现当前 Workflow 实际使用的 Gateway。纯脚本 Workflow 可以不传 Host；只有 Tool 节点时只实现 services.tools.execute：

import { defineWorkflowCliHost } from '@gm-hz/agent-dag-workflow/cli'

export default defineWorkflowCliHost({
  authorityRef: 'company:local-agent',
  authority: { subject: 'current-user', allowedTools: ['my_tool'] },
  services: {
    tools: {
      async execute(request) {
        request.signal.throwIfAborted()
        if (request.uses !== 'my_tool') throw new Error(`Tool denied: ${request.uses}`)
        const authority = request.authority
        if (authority === null || typeof authority !== 'object'
          || !Array.isArray(authority.allowedTools) || !authority.allowedTools.includes(request.uses)) {
          throw new Error('Authority denied')
        }
        return await callExistingTool(request.inputs)
      },
    },
  },
})

defineWorkflowCliHost() 不包装调用、不保存状态，只提供类型约束。CLI 加载模块时会 fail-fast 校验 Host 结构，避免执行到某个节点后才发现 execute、request 或 resolve 写错。

Host 字段	何时实现	最小方法
`services.tools`	`tool.call@1`	`execute(request)`；`list(authority)` 可选
`services.agents`	`agent.run@1`	`execute(request)`
`services.approvals`	`approval.request@1`	`request(request)`
`services.subworkflows`	自定义子流程 Gateway	`execute(request)`
`services.capabilities`	自定义 Node 能力	`resolve(capability)`
`authorityResolver`	后台恢复	`resolve(authorityRef, signal)`
`registerNodes`	定制 Node	`registerNodes(registry)`

Gateway 的返回值仍会经过节点 Schema、expects 和 Workflow 输出 Schema；Host 不能跳过校验。节点只能取得 Node Definition 声明、且模板 spec.requires 允许的能力。Host 自己还必须执行真实 Authority 校验，spec.requires 不是授权来源。

运行最小示例

仓库内的 minimal-host.mjs 把已有 echo Tool 适配给通用 Tool Gateway。完整发布和运行过程为：

bash

pnpm build
node lib/cli.js draft put examples/tool-echo.workflow.yaml --db .agent-dag-workflow.db --host examples/minimal-host.mjs
node lib/cli.js publish tool-echo --expected 1 --db .agent-dag-workflow.db --host examples/minimal-host.mjs
node lib/cli.js run tool-echo@1 --input-json '{"message":"hello"}' --db .agent-dag-workflow.db --host examples/minimal-host.mjs

成功结果保留 runId。读取权威轨迹时必须继续使用同一数据库和 Authority：

bash

node lib/cli.js trace <runId> --events --db .agent-dag-workflow.db --host examples/minimal-host.mjs

错误与排查

CLI 的 agent-workflow.cli/v1 失败 Envelope 包含稳定 error.code 和机器可读 error.hints。Workflow 已经启动但节点失败时，结果仍是成功传输的 Envelope，data.status 为 failed、进程退出码为 5，并在 data.hints 给出 Trace 与 Host 排查命令。

重点区分：

WORKFLOW_HOST_LOAD_FAILED：文件、ESM 或依赖加载失败；
WORKFLOW_HOST_INVALID：Host 对象结构不符合最小 Gateway 契约；
WORKFLOW_AUTHORITY_DENIED：Host/Authority 拒绝，不能通过扩大 spec.requires 绕过；
WORKFLOW_OUTPUT_INVALID：动态结果不满足声明，应先读 Trace，再修 Host/Agent 输出；
WORKFLOW_RUN_FAILED：读取 Trace 定位节点；缺少 Gateway 时传入正确的 --host。

Host Adapter 不读取模板里的明文 Secret，也不根据输入动态选择未声明的 Tool。连接信息应使用 connectionRef/credentialRef 等不透明引用，由 Host 在 Authority 范围内解析。

Host Adapter 接入 ​

最小接口 ​

运行最小示例 ​

错误与排查 ​

Host Adapter 接入

最小接口

运行最小示例

错误与排查