快速开始¶

这一页只完成一件事：让你在本地跑起一个 iamai，并理解一次消息从输入到回复会经过哪些对象。更深入的插件、状态、适配器和运维内容放在后面的教程与指南里。

你会得到什么¶

跑完这一页后，你应该能判断：

配置文件是否能被 iamai 正确读取；
插件路径是否能被发现和加载；
TerminalAdapter 是否能把本地输入转换成统一 Event；
handler 是否能通过 Context 回复消息。

准备环境¶

在仓库根目录安装依赖：

uv sync

先不要直接启动长期进程。对一个 Runtime 项目来说，第一步应该是让配置检查通过：

uv run python -m iamai --config examples/echo-runtime/config.terminal.toml config-check

config-check 会验证 TOML 结构、适配器配置、插件配置模型和高风险运行参数。如果这里已经报错，启动命令通常只会把问题暴露得更晚。

运行示例 Runtime¶

最小的本地交互入口是 TerminalAdapter：

uv run python -m iamai --config examples/echo-runtime/config.terminal.toml

终端出现提示符后，输入：

/echo hello iamai

示例插件会把文本回复回来。这个流程虽然简单，但已经走完整条运行链路：

terminal input -> TerminalAdapter -> Event -> Runtime -> Plugin handler -> Context.reply()

读懂最小配置¶

一个可运行配置通常包含四块：

[runtime]
command_prefixes = ["/"]
adapters = ["terminal"]
plugins = ["src/echo_runtime/plugins/echo.py:EchoPlugin"]

[adapter.terminal]
prompt = "iamai> "

[runtime]: 定义全局运行时行为，例如命令前缀、启用哪些适配器、加载哪些插件。
[adapter.<name>]: 定义协议接入点。终端、OneBot11、Webhook 都是适配器，只是外部协议不同。
[plugin.<name>]: 放插件自己的配置。插件如果声明了 config_model，这里会在启动前被严格校验。
[state]: 定义插件持久化后端。没有配置时，状态只存在内存里。

写一个自己的插件¶

创建一个插件类，暴露一个命令：

from iamai import Context, Plugin, command


class HelloPlugin(Plugin):
    name = "hello"

    @command("hello")
    async def hello(self, ctx: Context) -> None:
        await ctx.reply("Hello from iamai.")

把插件加入 [runtime].plugins 后重新运行：

[runtime]
command_prefixes = ["/"]
adapters = ["terminal"]
plugins = [
  "src/echo_runtime/plugins/echo.py:EchoPlugin",
  "src/echo_runtime/plugins/hello.py:HelloPlugin",
]

如果启用了热重载，也可以用管理命令重新加载插件；生产环境应只允许 superuser 使用这类命令。

常见卡点¶

ModuleNotFoundError: 插件路径不在配置根目录或 python_paths 里。优先使用相对配置文件的路径。
config-check 通过但没有响应: 先确认命令前缀，例如默认示例使用 /，所以命令是 /echo 而不是 echo。
管理命令提示权限不足: 检查 [runtime].superusers 和 [plugin.management] 的权限开关。