Neomega

外观

第一个插件 ​

制作一个“启动问候”插件：每次启动时记录一句可配置的问候语，持久保存累计启动次数。它只写插件自身的数据与日志，不发送游戏命令。

本页使用 Linux/macOS 命令写法；Windows PowerShell 使用本机 python 命令。选择匹配系统与架构的工具包。先从工具包下载、校验并解压当前版本，需要 Python 3.10+。离线步骤不需要框架源码、Go、管理令牌或游戏连接。目标 Host 的兼容性另按版本页核对。

1. 创建插件 ​

在新解压的工具包目录中执行，plugins 目录仅放本次示例，避免后续安装时扫描到其他项目：

sh
python3 runtime-plugins.py --directory plugins --id example.hello --template basic new hello

看到 Created plugins/hello 后，目录中会生成源码、manifest、配置 schema、配置示例、说明和发布清单。hello 是本地目录/安装名，example.hello 是插件 ID；这两个名称的用途不同。

创建模板只产生文件，不安装或启动插件。目录已存在时，换用一个未使用的名称，不覆盖已有项目。

2. 理解最小源码 ​

plugins/hello/main.py 的核心实现如下；工具生成的文件还可能包含供扩展使用的导入项：

python
from dataclasses import dataclass, field
from neomega_runtime import Plugin, PluginContext


@dataclass
class Settings:
    greeting: str = field(
        default="你好",
        metadata={"title": "启动问候语", "description": "插件启动时记录的问候语。"},
    )


class MyPlugin(Plugin):
    config_type = Settings

    async def on_start(self, ctx: PluginContext):
        starts = await ctx.storage.increment("starts")
        ctx.log.info("%s; persisted starts=%d", ctx.config.greeting, starts)

    async def on_stop(self, ctx: PluginContext):
        ctx.log.info("plugin stopped; saved data is retained")


if __name__ == "__main__":
    MyPlugin().run()

Settings 提供默认问候语，ctx.storage.increment 在插件的持久存储中增加计数，ctx.log 输出带安装身份的日志。停止或重载不会删除计数。运行入口由 Host 调用，不直接执行 python3 main.py 模拟插件宿主。

生成的 manifest 使用 main.py 入口，声明空的事件订阅、动作权限和服务权限。默认 session_required: true，因此即使这个示例不修改游戏，实际启动仍需目标 Host 已建立游戏会话。更改声明前先查生命周期与权限。

默认配置示例为：

json
{"greeting": "你好"}

要改变某次安装的问候语，运行后面的配置向导；config.example.json 是发布示例，不会自动成为宿主实际配置。要新增配置字段，按配置参考同步更新类型、schema 和示例。

3. 检查并打包 ​

仍在工具包目录执行：

sh
python3 runtime-plugins.py lint plugins/hello --json
python3 runtime-plugins.py pack plugins/hello hello.zip
python3 runtime-plugins.py check hello.zip

三条命令都应退出为 0 并报告 ok: true。pack/check 还会给出 plugin_id: "example.hello" 和实际 ZIP 的 SHA-256。产物 hello.zip 位于源码目录外。

lint 检查语法和静态配置，动态导入与业务运行显示 skip；check 检查 ZIP 与 manifest。到此得到可交付的离线产物，尚未证明 Host 启动或游戏内行为。

4. 在获授权实例启动 ​

只有具备目标实例本机管理权限时才执行本节。托管用户由实例管理员安装，使用与本节相同的配置、权限和验收要求。

管理员先确认目标实例及游戏连接，并将 TARGET_URL 设为该实例的本机管理地址，TARGET_TOKEN_FILE 设为对应私有令牌文件路径。它们是环境变量名称，不是可直接使用的地址或令牌；令牌内容不放入插件、聊天或发布包。发现服务地址不是实例管理地址。

sh
python3 runtime-plugins.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" --directory plugins console

先确认目标没有同名 hello 安装。在 plugins> 控制台依次输入：

text
load
configure hello
permissions hello
doctor hello
start hello

load 安装新目录并保持停止，已有安装不会被替换。配置向导保存问候语；权限向导由管理员审阅并确认，后续启动询问回车保持停止，再以 doctor 检查后单独启动。空权限也需要完成授权确认。

随后检查：

text
plugins
logs hello

预期安装状态为 running，日志包含配置的问候语与 persisted starts= 后的计数。新安装第一次启动应为 1；已有历史数据的安装继续原计数。

5. 验证持久化并结束 ​

在同一个控制台输入：

text
stop hello
start hello
logs hello
stop hello
quit

第二次启动日志中的计数应比第一次增加 1。最后一条 stop 停止本次示例；quit 只退出控制台，不会自动停止插件或机器人。示例数据保留在宿主安装数据中。

把源码、hello.zip、SHA-256、离线检查结果和实际运行日志摘要交付给用户。未执行本节时标注“离线检查通过，实例运行未验收”。继续添加聊天或周期功能前，读事件与生命周期；修改后按调试与交付重新检查和更新。

Neomega · 使用、开发与参考文档