调试与交付

先看失败发生在哪一步，再修改对应输入。插件 ZIP 检查通过、Host 显示运行、服务端确认动作和玩家看到效果是不同的验收结果。

离线失败：按报告定位

在工具包目录运行：

python3 runtime-plugins.py lint plugins/hello --json

将 hello 换成实际目录名。读取 exit_code 和 checks；语法错误可按 path、line、column 定位，其他错误参考 message 和 hint。

结果	下一步
退出码 `1`	修正插件文件、manifest、清单或配置，复查受影响项
退出码 `2`	检查命令参数、工具包是否完整及检查器是否适合当前系统
某项 `skip`	保留跳过原因；按实际需求另验依赖、动态配置与业务行为
`ok: true`	继续打包；这只覆盖实际执行的静态检查

新增文件逐个加入 package.files.json。真实 config.json、令牌、运行数据库和日志不进入发布目录。清单能限制收录文件，但不能识别源码里任意硬编码的秘密，交付前仍需检查内容。

启动失败：查同一个目标实例

先确认已有授权、目标实例、Host 版本和游戏连接。命令在该实例所在的本机管理环境中执行，TARGET_URL 与 TARGET_TOKEN_FILE 由管理员提供，后者仅为私有令牌文件路径。

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" status
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" doctor hello
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" logs hello

需要跟随日志时执行下面的命令，观察完按 Ctrl+C 结束本地日志读取；这不会停止插件：

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

现象	检查方向
配置不合法	对照配置参考修正已安装插件的真实配置
权限未确认或拒绝	对照权限参考检查声明、Host 能力与管理员授权
缺少模块或无法启动 Python	检查 Host 使用的 Python、随包 SDK 和插件依赖；离线 lint 不执行导入
`running` 但没有事件	核对事件源与订阅、实际触发条件和 ACK；授权不会产生缺失的事件源
会话不可用或版本不符	核对实例连接与版本；保留目标身份，不改连其他服务器尝试

修改后重新验证

先重新执行 lint、pack、check，得到对应最终源码的新 ZIP。修改配置类型时同步导出 schema；增加权限时让管理员审阅新声明。

安装新 ZIP 属于插件更新，按插件管理执行更新计划和维护步骤。候选检查通过不保证切换后启动成功；切换后仍需查询状态与日志。不要仅凭旧教程中的 reload 就认定新代码已经装入。

只需重新启动当前已安装制品时，可由管理员在核对目标后使用：

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

此命令未提供新包，不会从开发目录收取代码。停止、重载或卸载不会自动删除持久业务数据；验证失败时保留证据和数据，不通过清空存储掩盖问题。

动作已提交，但没有确认结果

使用 ctx.operations.submit(...) 获得的 operation_id 仅表示提交，需要查询该动作的最终状态和证据。数据库提交、命令回执与游戏内结果各自记录。

保留原请求。 保存原 operation_id / commit_id、幂等键、请求和期限；涉及敏感信息时保存到私有证据中。
查询原结果。 用公开的动作或存储回执接口核对原 ID，并检查对应实例日志；参考SDK与错误处理。
保留不确定状态。 unknown、失去响应或等待超时都不等于动作未执行；停止等待也不撤销动作。不能生成新 ID 或新键自动重放。
补充必要验收。 只有获得相应读回或玩家观察，才能报告对应层面的效果；证据不足标注待核对。

交付前核对

交付物	用户应能确认
源码与插件 ZIP	对应同一版本；包含发布清单和无秘密配置示例
ZIP 的 SHA-256	下载后可核对文件是否与检查时一致
兼容和权限说明	Host/工具包版本、依赖、所需授权及原因
验证结果	执行命令、通过/失败/跳过；离线、实例与游戏验收分别标注
运行与停止说明	配置方法、验收步骤、停止方法及需保留的测试数据

框架行为与公开文档不符时，整理最小插件、准确版本、复现步骤、预期/实际结果和脱敏日志。保留操作 ID，说明是否仍有运行任务或未确认动作；不附管理令牌、完整数据库或未脱敏的玩家聊天。

调试与交付 ​

离线失败：按报告定位 ​

启动失败：查同一个目标实例 ​

修改后重新验证 ​