快速开始

端到端运行运行时

本指南在 Docker 中运行一个 mock agent turn，不需要模型 API key，并验证 config、SQLite、scheduler、Docker backend、runner、HTTP API 和 WebUI。

前置要求

要求	用途	检查
Node.js 24+	CLI、server、runner build、内置 SQLite 模块。	`node --version`
npm	安装 TypeScript 和运行时依赖。	`npm --version`
Docker	每个智能体 turn 都在容器中运行。	`docker ps`
Git	clone 仓库并管理本地修改。	`git --version`

1. Clone 和 Build

git clone git@github.com:OmegaCombinator/suzumio.git
cd suzumio
npm install
npm run build

2. 构建 Runner 镜像

docker build -t suzumio-runner:dev .

示例配置使用 suzumio-runner:dev。如果使用其他 tag，请修改项目配置中的 backend.image。

3. 选择 Runtime Root

export SUZUMIO_ROOT=/tmp/suzumio-root
mkdir -p "$SUZUMIO_ROOT"

SUZUMIO_ROOT 存储项目数据库、turn 文件、workspace 和 artifact。建议放在 Git 仓库外。

4. 检查配置

suzumio config render examples/demo.yaml

运行前先渲染配置，可以看到 import 内容、默认值和写入 SQLite 的最终形状。

5. 初始化项目

suzumio init examples/demo.yaml
suzumio status demo

初始化后项目还不会被调度。需要在 server 运行后显式 start。

6. 启动 Server

suzumio serve --host 0.0.0.0 --port 39400

这会启动 HTTP API、ToolHost、WebUI、SSE stream 和 scheduler loop。浏览器打开 http://127.0.0.1:39400。

7. 发送第一条消息

在另一个终端中使用同一个 SUZUMIO_ROOT。

export SUZUMIO_ROOT=/tmp/suzumio-root
suzumio start demo
suzumio send demo pm P1 "Start the mock demo and report status."

Scheduler 会发现 pm 有 unread message，创建一个 turn，并启动一个 Docker 容器。

8. 检查结果

suzumio turns demo --limit 5
suzumio messages demo --limit 10
suzumio events demo --limit 20

成功的 mock run 会显示 completed turn，文本类似：

Mock turn completed for pm.

This container runner is wired correctly. In AI mode, the same runner calls the configured model and Suzumio ToolHost.

9. 验证非抢占行为

如果智能体已经处于 running，发送新消息不会打断当前 turn。消息会保持 unread，直到当前 turn 完成。

10. 可选 AI Runner 测试

examples/ai-demo.yaml 已脱敏。加入私有 endpoint 之前，请复制到本地未跟踪文件。

cp examples/ai-demo.yaml /tmp/suzumio-ai-demo.yaml
# 在本地编辑 /tmp/suzumio-ai-demo.yaml
export SUZUMIO_GATEWAY_API_KEY=...
suzumio init /tmp/suzumio-ai-demo.yaml

不要提交真实 API key、私有 gateway URL 或私有 provider 名称。请放在本地配置和环境变量中。

排错

现象	原因	处理
Turn 没有写 output 就失败。	镜像未构建、镜像名错误或容器启动失败。	运行 `docker build -t suzumio-runner:dev .` 并检查 `docker logs <container>`。
Tool call connection refused。	容器无法访问 Suzumio server。	用 `--host 0.0.0.0` 启动 server，并使用 `http://host.docker.internal:39400`。
Agent 不启动。	项目不是 `running`，或 agent 没有 unread inbound message。	运行 `suzumio start project` 并向该 agent 发送直接消息。
自定义域名只有 HTTP。	GitHub Pages 证书仍在签发。	等待证书完成后再启用 HTTPS enforcement。