架构

Core 负责协调，Container 执行 turn。

Suzumio 将 orchestration 与 execution 分离。核心进程拥有项目事实和调度；Docker runner 执行一个隔离 turn 后退出。

层次图

CLI / HTTP / WebUI
        |
        v
Suzumio Core
  Config loader
  SQLite store
  Message router
  Artifact registry
  ToolHost
  Non-preemptive scheduler
        |
        v
Docker backend
  Creates turn input JSON
  Starts one container per turn
  Monitors container exit
        |
        v
Container runner
  Reads /turn/input.json
  Runs mock or AI mode
  Calls Suzumio /tool for project tools
  Writes /turn/output.json

核心进程

核心进程是项目级记录的权威来源。CLI、HTTP、WebUI 或审计日志需要看到的数据，都应通过 core store 写入 SQLite。

模块	职责
`config.ts`	加载 YAML、解析 import、应用 `extends`、验证配置并渲染最终 YAML。
`store.ts`	创建和查询 projects、agents、messages、reads、turns、events、tool_calls、artifacts 等 SQLite 表。
`scheduler.ts`	实现 `nonpreemptive-mailbox` 调度规则。
`tools.ts`	定义 core tools，并对 ToolHost call 做 token 和 allowlist 检查。
`server.ts`	HTTP API、SSE stream、ToolHost route 和内嵌 WebUI。
`backend.ts`	Docker 容器创建、bind mount、runner input/output、turn completion。
`runner.ts`	mock 或模型驱动 turn 的容器入口。

Runner Contract

Runner 通过一个 input 文件接收全部上下文，通过一个 output 文件返回结果。这让执行层可替换，同时不改变项目状态语义。

type RunnerTurnInput = {
  project: string
  agent: { id: string; role: string; prompt: string; model?: string }
  turn: { id: string; prompt: string }
  workspace: string
  controllerUrl: string
  token: string
  runner: RunnerConfig
  tools: ToolDefinition[]
}

type RunnerTurnOutput = {
  text: string
  usage?: Record<string, unknown>
}

Docker 隔离

每个 turn container 只获得明确的小环境：

/turn bind mount，包含 input/output 文件。
/workspace bind mount，作为 agent workspace。
project、agent、turn、token 以及配置的 provider key 环境变量。
host.docker.internal 映射，用于访问 host 上的 Suzumio ToolHost。

当前版本保留 completed containers 便于 early debugging。后续应把 cleanup policy 配置化。

Tool Flow

Model asks for tool
  runner converts model tool call
  runner POSTs /tool to Suzumio
  ToolHost verifies token and tool allowlist
  ToolHost records tool_calls row
  core tool runs against SQLite/artifact store
  ToolHost records success or failure
  runner returns tool output to model

模型默认不会获得任意 host tools。工具按 agent 配置，并由 core ToolHost 执行。

SQLite 是项目事实

每个项目有一个 SQLite 文件。Container runner 不维护项目数据库；持久状态必须通过 output 文件或 ToolHost call 回到 core。

表	用途
`projects`	项目状态、任务、resolved config JSON、submitted report path。
`agents`	Agent roster、prompt、tool allowlist、token、active turn。
`messages`	直接消息和频道消息。
`message_reads`	哪个 turn 消费了哪个 inbound message。
`turns`	Turn 执行记录和 output text。
`events`	Append-style event timeline。
`tool_calls`	已审计的工具调用记录。
`artifacts`	带 hash 和 metadata 的已发布文件。

边界的价值

项目事实留在 core 中，agent execution 就可以是一次性的。Runner 可以失败、替换或升级，而项目数据库、消息历史、artifact 和用户控制面保持稳定。