核心概念

Suzumio 如何组织工作

Suzumio 把项目建模为持久消息和隔离 turn。Scheduler 很保守：只有当智能体有 inbound message 时才开始工作，并且不会打断正在运行的智能体。

Project

Project 是持久工作单元，包含名称、任务描述、解析后的配置、agent roster、channel、SQLite 数据库、artifact 目录和事件时间线。

状态调度行为常见来源
initialized不调度。suzumio init
runningScheduler 可以启动 ready agent。suzumio start 或 request changes。
submitted等待用户审批。completion.submit
completed不再调度。suzumio approve
stopped调度关闭。suzumio stop

Agent

Agent 是带 role、prompt、model、workspace 和 tool allowlist 的参与者。Agent 不拥有项目状态；它通过 Suzumio 产生消息、工具调用、artifact 和 turn output。

状态含义
quiet空闲且没有 unread inbound message。
running一个 Docker turn 正在运行，scheduler 不能 prompt 它。
failed上一次 turn 或 backend 操作失败。
stopped该 agent 被禁用。

Message

Message 是唤醒 agent 的正常方式。可以是带 recipient 的直接消息，也可以是带 channel 的频道消息。

{
  "sender": "user",
  "recipient": "pm",
  "priority": "P1",
  "body": "Start the project."
}

只有当消息被写入某个 agent 的 turn prompt 时，才会对该 agent 变成 read。

Turn

Turn 是一个 agent 的一次隔离执行。Suzumio 创建 turn record，写入 input.json，启动 Docker 容器，等待 output.json，并记录成功或失败。

turn.started -> container runs -> output.json -> turn.completed

Mailbox Scheduler

默认 scheduler 是 nonpreemptive-mailbox。

  1. 跳过非 running 项目。
  2. 跳过已经 running 的 agent。
  3. 为每个 idle agent 获取 unread inbound messages。
  4. 没有 unread message 时保持 quiet。
  5. 有 unread message 时渲染一个 prompt 并启动一个 turn。
  6. 不创建 heartbeat、status prompt 或自动提醒。

ToolHost

工具由 Suzumio core 提供，而不是由模型 runner 任意执行。每次调用都会校验 project、agent、turn、token、tool name 和 allowlist。

messages.send

创建直接或频道消息。

artifacts.publish

把 workspace 文件发布到 artifact registry。

artifacts.list

返回已发布 artifact。

completion.submit

写入最终报告并标记项目 submitted。

Artifact 和 Event

Artifact 是从 agent workspace 发布的文件，记录 id、creator、turn、路径、hash 和描述。Event 是项目时间线，用于 WebUI、debug、审计和未来 replay 工具。

project.initialized
message.created
turn.started
tool.called
artifact.published
turn.completed
project.submitted
下一步：配置。