这是本节的多页打印视图。 .

Documentation

Eventboat Agent 原生事件路由器的指南、参考与教程。

1: 介绍
- 1.1: 什么是 Eventboat？
- 1.2: 架构
2: 快速上手
- 2.1: 安装
- 2.2: 第一条管道
3: 参考
- 3.1: CLI 参考

1 - 介绍

Eventboat 是什么、为什么存在、解决什么问题。

1.1 - 什么是 Eventboat？

Go 单二进制 DAG 事件路由器，为 AI Agent 端到端操作而设计。

Eventboat 通过有向无环图（DAG）路由事件——从源（Kafka、HTTP、cron、SQL、文件）到汇（Kafka、HTTP、文件），保证 at-least-once 投递、死信可查可回放。

它是 Agent 原生的：所有能力都可通过 MCP（Model Context Protocol）、CLI 和语言服务器访问——AI Agent 可以自主编写、验证、部署和运维事件管道。

有什么不同

维度	方案
谓词	CEL（K8s 标准）——零自研 DSL，训练语料巨大
转换	Starlark（Python 方言，沙箱，确定性）
验证	四道机器关卡：verify、test、explain、operate
可靠性	七条不变量测试，spool/settle/checkpoint 引擎（SQLite）
作业	cron 调度、补偿窗口、类型化参数、回补
扩展	CEL → Starlark → WASM → gRPC 进程外插件
互操作	CESQL 方言（CloudEvents），官方 TCK 100%

一句话

Eventboat 让 AI Agent 构建和运行不丢消息的事件管道——因为机器在上线前验证每一步。

1.2 - 架构

Eventboat 引擎的工作方式：三层管道模型、spool+settle+checkpoint 可靠性、四道验证关卡。

三层模型

YAML (+overlay) → Config（类型化）→ Static IR → Runtime Engine
                                        ↓
                            Source → Transform → Sink 插件

Config 层：YAML 解析、严格 schema 校验、变量替换
Static IR：校验后的 DAG + 预编译 CEL 程序 + Starlark 程序 + schema
Runtime：spool + settle + checkpoint 引擎，只消费 IR

可靠性模型

source → [spool: 追加式持久队列] → 内存 DAG → sinks
              │                        │
              └── checkpoint ←── settle 跟踪 ←── 终态

Spool：每条消息先落 SQLite 再进 DAG（不变量 1）
Settle：消息的全部分支到达终态即 settle
Checkpoint：只推进已 settle 的连续前缀（不变量 2）
崩溃恢复：kill -9 → 重启 → 从 checkpoint 重放，绝不丢（不变量 3）
死信：重试耗尽 → 死信库（可查询 + 可回放）

七条不变量测试

每条都有专属测试，CI 必须通过：

spool 先于可见
settle 先于 checkpoint
kill -9 重放覆盖全部未 settle
死信写失败阻塞 settle
required: false 边不阻塞兄弟分支
重复投递保持 message ID 稳定
水位不超过已 settle 最大值

四道机器关卡

关卡	命令	做什么
verify	`eventboat verify`	Schema、拓扑、CEL+Starlark 编译、lint — 静态零副作用
test	`eventboat test`	对真实引擎跑合约测试 — fixture 进、断言出
explain	`eventboat explain --message sample.json`	确定性路径推演（真实 CEL 求值 + Starlark dry-run）
operate	`eventboat mcp`	MCP 服务器：15 个工具覆盖完整 Agent 生命周期

2 - 快速上手

安装 Eventboat，写第一条管道，验证并运行。

2.1 - 安装

在你的平台上安装 Eventboat CLI。

前提

Go 1.25+（从源码构建）
零运行时依赖——全部编译进一个二进制

安装

go install github.com/eventboat/eventboat/cmd/eventboat@latest

验证：

eventboat help

应看到帮助界面，列出 11 个命令。

下一步

2.2 - 第一条管道

写一个三段式 YAML 管道，验证、测试并运行。

三段式格式

每个 Eventboat 管道是一个 YAML 文件，三个顶层段：sources、transforms、 sinks——通过 from 连边。

apiVersion: eventboat/v3
kind: Pipeline
metadata: { name: my-first-pipeline }

sources:
  ingest:
    cron: { expression: "*/5 * * * *" }   # 每 5 分钟

transforms:
  hello:
    from: [ingest]
    script: |
      payload.greeting = "hello from eventboat"
      payload.timestamp = meta.ingest_time

sinks:
  console:
    from: [hello]
    drop: {}                              # 丢弃（演示用）

验证（关卡 1）

eventboat verify --config pipeline.yaml

输出：pipeline.yaml: 0 error(s), 0 warning(s)

运行

eventboat run --config pipeline.yaml

管道启动；每 5 分钟 cron 源触发，Starlark 脚本丰富消息，sink 接收。

加分支（CEL 谓词）

sinks:
  important:
    from: { hello: { when: 'payload.score > 100' } }
    http: { url: "https://api.example.com/alerts" }

  archive:
    from: [hello]                          # 无条件边
    drop: {}

Agent 模式

# 启动 MCP 服务器 — AI Agent 经 stdio 连接
eventboat mcp --stdio

# 或带管理界面
eventboat mcp --http

3 - 参考

CLI 命令、配置段、插件清单与扩展阶梯。

3.1 - CLI 参考

全部 11 个 Eventboat CLI 命令及旗标。

总览

eventboat [--json] verify --config <pipeline.yaml> [--strict]
eventboat [--json] test <testfile-or-dir> [...]
eventboat run --config <pipeline.yaml> [--data-dir DIR] [--ephemeral]
eventboat run --config-dir <dir> [--runtime runtime.yaml]
eventboat [--json] trigger --config <job.yaml> [--parameters '{"from":"..."}']
eventboat [--json] jobs list --config <job.yaml> [--limit N]
eventboat [--json] jobs show <run-id> --config <job.yaml>
eventboat [--json] explain --config <pipeline.yaml> [--message f.json] [--topology]
eventboat [--json] replay --config <pipeline.yaml> (--dlq | --spool --from N | --job <run-id>) [--dry-run]
eventboat repl [--message sample.json] [--cel 'expr' | --script f.star]
eventboat lsp
eventboat [--json] plugin catalog
eventboat [--json] plugin schema <name>
eventboat mcp (--stdio | --http) [--config-dir <dir>] [--data-dir DIR]

verify

静态验证管道。检查 schema、拓扑不变量（无环、无孤立节点、源无入边、汇无出边、至少一条源→汇通路）、CEL 谓词编译、Starlark 脚本编译、作业配置和语义 lint。

旗标	默认值	说明
`--config`	（必填）	管道 YAML 文件
`--strict`	false	将 warning 升级为 error

test

对真实进程内引擎跑合约测试。测试文件声明注入点、期望捕获和死信断言。

run

执行管道。作业管道（含 run.mode: job）在作业管理器下运行，带调度和补偿。 --config-dir 启动多管道守护进程（含管理界面）。

trigger

手动触发作业管道一次，可选传参（回补）。

eventboat trigger --config sync.yaml --parameters '{"from":"2026-08-01","to":"2026-09-01"}'

explain

管道的确定性推演。带 --message 时做真实 CEL 求值和 Starlark dry-run；带 --topology 时渲染 DAG（mermaid + ASCII）。

replay

将死信（--dlq）、spool 窗口（--spool --from N）或某次运行的死信（--job <run-id>）重新注入活跃管道。

repl

不跑管道，对样例消息求值 CEL 谓词或执行 Starlark 脚本。

mcp

启动面向 AI Agent 的 MCP 服务器。

旗标	说明
`--stdio`	经 stdin/stdout 说 MCP（供 Agent 宿主拉起）
`--http`	HTTP 形态 MCP + Admin REST + SSE + 管理界面