报错速查
装载期与运行期的常见错误,按症状查原因。
装载期:发行版装不起来
| 报错 | 原因 | 怎么办 |
|---|---|---|
重复的 Mod ID | 两个模块用了同一个 Mod.Id | 改 ID,或用命名空间前缀 |
同时加载多个发行版 | 一次装了两个发行版 | 一个进程只装一个发行版 |
玩家状态必须声明唯一的只读工具 | PlayerState 里有不存在或不是只读的工具 | 核对工具名与 read_only |
玩家事件必须引用只读工具 | PlayerEvents 指的工具不存在或不是只读 | 同上 |
ReadOnlyPanel must reference a registered read-only tool | ReadOnlyPanel 里的面板没注册 | 用已注册的只读工具名 |
行动门声明缺少公共能力或方法 | ActionGate 写的能力/方法不存在 | 核对 Capability 与 Method |
玩家时钟必须引用公共能力和方法 | PlayerClock 写错 | 核对能力与方法名 |
发行版须声明 PlayerClock 或实现 clock() | 发行版没声明时钟 | 加 PlayerClock 或实现 clock() |
发行版须实现定时登场策略或采用 GridSession | 发行版缺登场策略 | 用 GridSession 或自己实现 |
Session.Observer 必须引用公共能力 | 观察者能力写错 | 核对 Observer 里的能力 |
Session.Observer.Records 必须返回包含 events / messages 的对象 | 观察者的 to_save 返回值形状不对 | 返回 {'events': [...], 'messages': [...]} |
场景必须是本发行版声明的 | 场景 id 不在发行版声明里 | 在发行版 Scenarios 里声明 |
模块工具不能占用玩家 API 保留名称 | 工具名撞了 player_state / player_rules / player_events / memory_search | 改工具名 |
对象接口不能调用私有方法 | 通过能力调了 _ 开头的方法 | 暴露成公开方法 |
装载期:模块装不起来
| 报错 | 原因 |
|---|---|
依赖模块缺失 | Requires 指向的模块没装 |
| 能力名冲突 | 两个模块 Provides 同一个能力名 |
| 状态键重复拥有 | 两个模块 Owns 同一个键 |
| 工具名重复 | 两个工具同名 |
未声明的能力 | self._call 调了没在 Capabilities.Needs 声明的能力 |
方法未在接口清单中 | 调了对方没在 Interfaces 声明的方法 |
运行期:模型或玩家提交动作
| 报错 | 原因 | 怎么办 |
|---|---|---|
该国当前不能行动:已亡国,或不在行动阶段 | 该回合已经交过动作 | 每个回合一次行动 |
仅行动阶段可以提交动作 | 不在行动阶段 | 检查回合流程 |
该动作不属于行动者的作用域 | 工具对该行动者不可见 | 作用域或权限声明问题 |
该工具不属于行动者的作用域 | 同上 | 检查 PlayerState / 作用域声明 |
未知内容键值:… | 模型传了没注册的内容 id | 注册内容或加 register_aliases |
键值冲突,请指定命名空间 | 短键在多个内容里重名 | 用带命名空间的 id |
工具参数须为对象 / 参数必须是一个对象 | 参数不是 dict | 检查工具函数签名 |
query 只能查已注册的只读动作 | 拿只读工具去 submit 了 | 只读用 query,动作用 submit |
topic 必须是字符串 | player_rules 传了非字符串 | 传字符串 |
内容键值须为字符串 | 内容 id 不是字符串 | 检查 content_definitions |
存档
| 报错 | 原因 | 怎么办 |
|---|---|---|
存档 Mod 依赖/版本/工具契约与当前加载环境不相同,拒绝加载 | 存档与当前发行版不匹配 | 用匹配的版本,或走迁移脚本 |
存档 Mod 状态清单与当前环境不相同 | 模块的状态键变了 | 升版本并迁移 |
Unsupported session format | 存档格式号不认识 | 检查 zhanguo.session/5 |
Save only at an action boundary | 在回合中间存档 | 在行动边界存 |
Scenario differs from saved scenario | 存档的场景与当前配置不同 | 用同样的场景配置 |
排查顺序
- 先看报错类型:装载期 → 声明问题;运行期 → 作用域/参数/内容问题;存档 → 版本问题。
- 再看是不是声明没写全:八成的问题出在
mod.toml与实现不一致。 - 最小复现:用
Runtime.load('你的模块目录')单独装它,别拉上整个发行版。 - 还是不行:跑
python3 scripts/api_doc.py --check看参考页与代码是否同步, 再对照 API 参考 核字段。