配置

项目 YAML 参考

Suzumio 项目用 YAML 声明，解析成一个 canonical config 后随项目保存。配置描述 task、agents、message channels、Docker backend、scheduler 和模型 preset。

解析流程

Suzumio 把配置当作 source material，而不是可变运行时状态。运行 suzumio init 时，loader 会执行与 suzumio config render 相同的步骤，并把结果保存为 resolved.yaml。

source YAML
  -> quote bare @import(...) markers
  -> substitute environment placeholders in text
  -> parse YAML
  -> resolve whole-field imports recursively
  -> apply extends profiles
  -> apply defaults and validate
  -> write resolved.yaml and SQLite project config

评审或初始化前建议运行 suzumio config render path/to/project.yaml。它会展示 Suzumio 实际运行的完整配置。

最小项目

name: demo
task: |
  Demonstrate one non-preemptive turn.

backend:
  runner:
    mode: mock

agents:
  pm:
    role: project-manager
    prompt: |
      Handle the user request and stay concise.
    tools:
      - messages.send

完整结构

下面的例子展示主要字段。实际项目通常会把 task、长 prompt 和可复用 backend 设置拆到 import 或 profile 中。

name: research-demo
task: @import(tasks/main.md)

scheduler:
  kind: nonpreemptive-mailbox
  intervalMs: 2000
  maxPromptMessages: 20

channels:
  - "#project"
  - "#blocked"
  - "#reviews"

backend:
  kind: docker-chat
  image: suzumio-runner:dev
  controllerUrl: http://host.docker.internal:39400
  docker:
    network: bridge
  runner:
    mode: ai
    model: main
    models:
      default: main
      providers:
        gateway:
          type: openai-compatible
          baseURL: https://your-gateway.example/v1
          apiKeyEnv: SUZUMIO_GATEWAY_API_KEY
          timeoutMs: 300000
      presets:
        main:
          provider: gateway
          model: gpt-5.5
          apiModel: gpt-5.5
          toolChoice: auto
          maxOutputTokens: 2000

agents:
  pm:
    role: project-manager
    prompt: @import(prompts/pm.md)
    model: main
    tools:
      - messages.send
      - artifacts.list
      - completion.submit
  worker:
    role: worker
    count: 2
    prompt: @import(prompts/worker.md)
    model: main
    tools:
      - messages.send
      - artifacts.publish
      - artifacts.list

顶层字段

字段是否必需说明
name是SUZUMIO_ROOT 下的项目 id 和运行目录名。
task是持久任务描述，会渲染进每个 turn prompt。
agents是Agent id 到 agent config 的映射。至少需要一个 agent。
extends否一个 profile object 或 profile object 列表，在本地字段之前合并。
scheduler否Scheduler 类型和 prompt message batching。默认是 nonpreemptive-mailbox。
backend否Docker runner image、ToolHost URL、Docker options 和 model runner 设置。
channels否允许的频道名。默认包含 #project 和 #blocked。
observability否文档层面的 HTTP/WebUI 默认值。实际 server bind 地址仍由 CLI flags 控制。

YAML 写法约定

Suzumio 使用普通 YAML map、array、scalar 和 block string。长文本建议使用 block string 或导入文件，这样 resolved prompt 更容易阅读。

写法用途例子
Block scalar多行 task 和 prompt。task: |
Quoted stringsChannel 名称和包含特殊符号的字符串。"#project"
ArraysTools、channels、profile lists。- messages.send
MapsAgents、providers、presets、Docker options。agents: { ... }
task: |
  Write the final result as a short report.
  Mention any assumptions and artifacts.

channels:
  - "#project"
  - "#blocked"

Whole-field Imports

当某个字段的完整值是 @import(path) 时，该字段会被导入文件替换。关键点是：import marker 必须占满整个字段值。Suzumio 不支持在更大的字符串里做插值。

task: @import(tasks/main.md)
agents:
  pm: @import(agents/pm.yaml)
  worker:
    prompt: @import(prompts/worker.md)

如果导入的 YAML 或 JSON 文件包含 object，该 object 会成为 import 位置的值。如果导入 Markdown 或 text 文件，完整文本会成为 import 位置的值。

导入文件Suzumio 如何读取常见用途
.yaml 或 .yml作为 YAML 解析，并继续解析其中的 import。Agents、backend profiles、scheduler profiles。
.json作为 JSON 解析，并继续解析其中的 import。生成的 model preset maps 或 tool lists。
其他扩展名作为 UTF-8 原始文本导入。Tasks、prompts、report templates。

Import 路径

Import 路径相对包含该 import 的文件解析，而不是相对进程工作目录解析。嵌套 profile 可以稳定地导入自己旁边的 fragment。

# configs/project.yaml
agents:
  pm: @import(agents/pm.yaml)

# configs/agents/pm.yaml
role: project-manager
prompt: @import(../prompts/pm.md)

有效和无效写法

写法结果
prompt: @import(prompts/pm.md)有效。字段值会被文件内容替换。
pm: @import(agents/pm.yaml)有效。导入对象成为 agents.pm。
prompt: "Read this: @import(x.md)"不会作为 import 处理。它只是普通字符串；不做插值。
url: @import(https://example.com/x.yaml)拒绝。禁用 HTTP import。

嵌套对象例子

如果 agents/pm.yaml 内容如下，导入到 agents.pm 时会完整保留这个嵌套结构。

# agents/pm.yaml
role: project-manager
prompt: @import(../prompts/pm.md)
tools:
  - messages.send
  - completion.submit

# resolved shape
agents:
  pm:
    role: project-manager
    prompt: "...contents of prompts/pm.md..."
    tools:
      - messages.send
      - completion.submit

Suzumio 会拒绝循环 import 和过深的 import 链，避免项目意外无限展开配置。

Extends 和合并规则

extends 用来复用 profile。每个 entry 必须解析成 object。Suzumio 会按顺序合并 profile，然后把当前文件合并到最上层。

extends:
  - @import(profiles/base.yaml)
  - @import(profiles/ai.yaml)

name: theorem-project
task: @import(tasks/theorem.md)

agents:
  worker:
    count: 3
合并情况行为
Object 合并 object递归 deep-merge。
Array 合并 array后面的 array 替换前面的 array。
Scalar 合并任意值后面的 scalar 替换前面的值。
当前文件 vs profile当前文件胜出。

Profile 合并例子

# profiles/base.yaml
backend:
  image: suzumio-runner:dev
  runner:
    mode: mock
channels:
  - "#project"
  - "#blocked"

# project.yaml
extends:
  - @import(profiles/base.yaml)
name: demo
task: @import(tasks/demo.md)
backend:
  runner:
    mode: ai
channels:
  - "#project"
  - "#reviews"

# important resolved effects
backend.image: suzumio-runner:dev
backend.runner.mode: ai
channels: ["#project", "#reviews"]

backend 是 object，所以会 deep-merge：profile 中的 backend.image 保留，本地 backend.runner.mode 覆盖。channels 是 array，所以整体替换，不会自动 append。

Scheduler Config

scheduler:
  kind: nonpreemptive-mailbox
  intervalMs: 2000
  maxPromptMessages: 20
字段说明
kind第一版只有 nonpreemptive-mailbox。
intervalMs预期 scheduler loop 间隔。当前 server 使用与默认值一致的固定 loop。
maxPromptMessages一个 turn prompt 中最多渲染多少条 unread inbound messages。

Backend Config

backend:
  kind: docker-chat
  image: suzumio-runner:dev
  controllerUrl: http://host.docker.internal:39400
  docker:
    network: bridge
  runner:
    mode: mock
字段说明
kindBackend implementation。当前 backend 基于 Docker。
image每个 turn container 使用的 Docker image。
controllerUrl容器访问 Suzumio ToolHost 的 URL。本地 Docker 通常使用 host.docker.internal。
docker.network可选 Docker network mode。
runner.modemock 用于基础设施测试，ai 用于模型 turn。

AI Runner Config

backend:
  runner:
    mode: ai
    model: main
    models:
      default: main
      providers:
        gateway:
          type: openai-compatible
          baseURL: https://your-gateway.example/v1
          apiKeyEnv: SUZUMIO_GATEWAY_API_KEY
          timeoutMs: 300000
      presets:
        main:
          provider: gateway
          model: gpt-5.5
          apiModel: gpt-5.5
          toolChoice: auto
          maxOutputTokens: 2000

提交到仓库的示例必须保持脱敏。真实 endpoint 和 key 应放在本地未跟踪配置或环境变量中。

Agent Config

agents:
  worker:
    role: worker
    count: 2
    prompt: @import(prompts/worker.md)
    model: main
    tools:
      - messages.send
      - artifacts.publish
      - artifacts.list
字段说明
role随 agent 保存的人类可读角色。
count将一个配置项展开为 worker-1、worker-2 等编号 agents。
prompt每个 turn prompt 中包含的 agent instructions，通常从 Markdown 导入。
modelAI mode 中可选的 model preset override。
tools该 agent 允许调用的工具名。
env传给 runner containers 的附加环境变量。

Channels

channels:
  - "#project"
  - "#blocked"
  - "#reviews"

发送到未声明 channel 的消息会失败。这样可以避免拼写错误产生噪音频道。

验证流程

suzumio config render path/to/project.yaml
suzumio init path/to/project.yaml
suzumio status project-name

使用多个 profile 时尤其要在 review 中渲染配置。检查 resolved output 中是否有意外的 array replacement、继承来的 model 设置，以及不应该提交的私有 endpoint。

下一步：CLI 参考。