管理插件

按照“安装 → 配置 → 确认权限 → 检查 → 启动”的顺序操作。插件包来自AI 开发流程或你信任的作者；插件会运行本机代码，权限声明不等于文件系统沙箱。

本页使用 Linux/macOS 命令写法，在运行包目录执行；Windows PowerShell 将 python3 换为可用的 python，按本机路径填写参数。Python 管理 CLI 需要 Python 3.10+，独立 Go 插件的运行不需要 Python。托管用户按服务提供的管理入口完成同样的步骤；本页不要求托管服务向用户开放命令行或管理令牌。

指定实例

以下示例使用默认回环地址和令牌路径：

TARGET_URL=http://127.0.0.1:18793
TARGET_TOKEN_FILE=state/token

修改过端口或数据目录时，换成目标实例的实际值。令牌路径与实例必须对应，令牌内容不需要复制到命令里。

安装并启动

以下以插件包 hello.zip 和安装名 hello 为例。安装名用于后续管理，包内插件 ID 由作者提供，两者不是同一个字段。

安装已取得的插件包。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" install hello hello.zip

按配置向导填写实际参数。
sh
```
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" configure hello
```
未提供配置 schema 的插件可跳过这一步。config.example.json 是示例，放进包里不会自动变成实例配置。
审阅权限用途，输入“同意”保存授权。
sh
```
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" permissions hello
```
没有申请权限的插件也需要确认。保存后如询问是否启动，先按回车保持停止。
检查插件是否满足启动条件。
sh
```
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" doctor hello
```
先处理缺失配置、权限或事件来源，再启动。授权不能为离线宿主补上游戏连接。

启动并核对实际状态。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" start hello
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" plugins
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" logs hello

看到 running 后，在游戏内触发一次插件功能，确认玩家实际收到预期结果。

停止与自动启动

命令	效果
`start hello`	启动当前插件
`stop hello`	停止当前运行，保留已有自动启动设置
`enable hello`	保存自动启动设置，并启动尚未运行的插件
`disable hello`	停止插件，同时关闭自动启动

将上表命令接在 python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" 后执行。只有完成游戏内检查、确认适合持续运行后，才使用 enable。

存在插件依赖时，先启动提供服务的插件，再启动依赖方；停用时先停止依赖方。

更新到固定版本

先取得作者发布的固定版本 ZIP，核对适用框架版本及迁移说明。以下选择停用后更新，适用于可以安排维护时间的插件。

确认插件没有未完成或结果不明的业务，关闭自动启动并停止。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" disable hello
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" plugins

预览更新，核对版本、权限变更和准备状态。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" update-plan hello hello-new.zip --maintenance-mode stopped --json

使用同一包和维护模式提交更新，审阅后输入“更新”。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" update hello hello-new.zip --maintenance-mode stopped

查询当前版本、运行状态与日志，再到游戏内检查功能。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" plugins
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" logs hello

此更新流程会启动候选版本完成激活检查，成功后仍保留 enabled=false。需要随宿主自动启动时，检查通过后单独执行 enable hello。

如果出现 maintenance_pending、recovery_required，或请求未取得可靠结果，先按排查问题核对当前安装，不重复提交更新。恢复插件数据不会撤销已经发生的游戏操作；不要通过卸载重装绕过未决任务。

卸载

确认不再需要运行插件后执行：

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" uninstall hello

卸载不会清空插件的持久数据，同名重装可能继续使用原数据。卸载前先处理依赖方；需要彻底清理数据时，按插件作者的迁移或清理说明单独操作。

查找官方插件

在插件市场按名称、运行时和平台查找版本，打开详情核对依赖、权限和固定版本安装命令。默认来源保持官方目录；目录发现不代表授权或自动启动。

管理插件 ​

指定实例 ​

安装并启动 ​

停止与自动启动 ​

更新到固定版本 ​

卸载 ​