排查问题

先确认“哪个实例、哪个插件、哪一步失败”，再保存状态与日志。反复启动或重发命令可能掩盖最初的错误。

先收集三项信息

自行部署用户在运行包目录执行以下命令；非默认实例需要替换地址、令牌路径和安装名：

python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token status
python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token plugins
python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token logs hello

托管用户从服务提供的状态和日志入口收集对应信息；没有相关入口时，将实例、插件和发生时间提供给服务维护方。

字段	如何判断
ready	宿主管理是否就绪，不能单独判断游戏连接
in_game	机器人是否处于游戏连接中
chat_running	聊天采集是否运行
read_only	是否处于禁止游戏命令及世界写入的只读模式
actions_ready	当前宿主是否可以接收游戏动作，不代表某次动作已经成功

按现象检查

现象	下一步
管理命令无法连接或提示令牌错误	确认宿主仍在运行、地址为目标实例的回环端口、令牌路径对应同一实例
进程运行但机器人没有进服	检查 in_game，核对认证资料、服务器号码及进入密码
安装成功，插件无法启动	运行 doctor hello，补全配置、权限或游戏事件来源
插件 running，玩家却没有反应	对照插件触发条件查看日志，核对连接、只读状态和实际动作回执
更新或重载后异常	查看当前版本、日志及恢复字段，先确认究竟运行着哪个制品

doctor 同样需要指定实例：

python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token doctor hello

离线宿主没有聊天和玩家事件来源；这里的来源缺失不能通过重复授权解决。

持续查看日志

python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token logs hello --follow

用 Ctrl+C 退出查看，不会停止插件。只关心警告及错误时，在命令末尾增加 --level WARNING。

日志保留最近三次运行，每次最多 64 KiB 尾部。discarded_bytes 或跟踪输出中的 GAP 表示部分日志已不在保留范围，不能据此断言某件事从未发生。出现问题后及时保存相关片段，分享前删除凭据和私人信息。

操作结果是 unknown

unknown 表示结果尚未确认，操作可能已经产生了游戏效果。等待超时也不等于动作已取消。

1. 保留原 operation_id、幂等键、时间和日志。

2. 让插件作者查询原动作回执，服主同时核对游戏内实际结果。

3. 查询恢复报告，确认是否存在未决动作或恢复要求。

   python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token recovery

4. 根据具体原因处理恢复，再决定后续操作。

不要换一个请求编号或幂等键重发奖励、扣费或世界写入，也不要删数据库或反复重启来清除恢复状态。恢复报告是诊断信息，不会自动撤销或补做游戏操作。

提交可复现的问题

复制以下内容，填写后交给插件作者或服务维护方：

框架版本或运行包标识：
插件名称和版本：
系统及 Python 版本（自行部署时填写）：
发生时间、复现步骤和预期结果：
实际现象、错误片段及 operation_id（如有）：

附上已脱敏的状态与日志。不要附管理令牌、认证密码、完整私有配置或数据库；开发工具包的检查通过也不能代替游戏内复现结果。