第一步：跑通一个终端 Runtime

这一章把 iamai 当成本地程序来使用。终端适配器没有网络鉴权、平台账号和回调地址， 适合先把插件模型理解清楚。

本章目标

• 跑通一个已有示例；

• 写一个新的 @command；

• 看懂一次事件分发中各对象的职责。

使用现成示例

先做配置检查：

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

再启动：

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

输入：

/echo hello

示例已经包含一个终端适配器、一个 echo 插件和一组开发态管理命令配置。

自己写一个命令

新插件只需要继承 Plugin，并用 decorator 声明 handler：

from iamai import Context, Plugin, command


class HelloPlugin(Plugin):
    name = "hello"

    @command("hello")
    async def hello(self, ctx: Context) -> None:
        await ctx.reply("你好，iamai 已经工作。")

Context 是插件作者最常用的对象。它把事件、适配器、插件配置、状态和回复方法放在一起， 避免 handler 直接依赖具体平台。

把插件挂进配置

插件可以用 module:ClassName 或 path/to/file.py:ClassName 引用。示例项目通常使用 后者，因为它对新读者更直观：

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

如果你把插件放在包里，也可以配置 python_paths 后使用模块路径。

Checkpoint

到这里你应该能说清楚：

• 事件来自适配器，而不是插件自己读取输入；

• Runtime 负责把事件分发给匹配的 handler；

• handler 通过 Context 回复消息；

• 命令是否匹配，先受 command_prefixes 影响。

下一章会加入规则和权限，让同一个 Runtime 根据消息内容、来源和用户身份做不同响应。