开发流程总览
从「想加个东西」到「能上线」要走完的九步。
加一个东西,完整走九步。每一步都有对应的参考页。
1. 先判断:这是模块还是发行版
- 只是加一条规则、加一个资源、加一种建筑 → 写模块。
- 要换掉整套规则(另一套资源、另一个时代、另一个胜利条件) → 写发行版。
- 只是改模型的提示词、上下文策略 → 改发行版的语言包或客户端,不动模块。
判据:你的改动能不能独立成一个目录 + 一个 mod.toml?能,就是模块。
2. 划边界:这个模块拥有什么
先写下三行字,再动手写代码:
这个模块拥有:<状态键>
这个模块提供:<能力名>.<方法名>
这个模块需要:<别人的能力>.<方法名>
这三行直接对应 mod.toml 的 [State]、[Capabilities]、[Interfaces]。 先定接口,再写实现——否则写到一半会发现要改别人的状态,或者能力名和别人的撞了。
命名规矩:
- 能力名一律
模块ID:能力名,模块 ID 用自己的命名空间(example:hello)。 - 状态键短而具体(
accounts、territory),不要跟别人重名。 - 方法名用动词短语(
exchange、owner、transfer)。
3. 写声明:mod.toml
[Mod]
Id = "example:hello"
Version = "1.0.0"
Entry = "mods.examples.hello.mod:HelloMod"
Requires = [] # 必须存在的依赖模块
After = [] # 结算顺序:我在这些模块之后
Before = []
[State]
Owns = ["hello"] # 只有我能写
Requests = [] # 我要写别人的状态时在这里申请
[Capabilities]
Provides = ["example:hello"]
Needs = [] # 我要用的能力
Optional = [] # 可选依赖
[Interfaces]
"example:other" = ["method"] # 我要调对方哪些方法
字段全表见 模块声明。
4. 写实现:GameMod 子类
最少要实现 mixins;常用的是 initialize_world、objects、tools、stages、rule_sections。 方法清单见 引擎 API。
5. 暴露给模型:工具与事实
模型只看得见工具和事实。这一步决定模型能不能玩你的内容。
- 动作 → 一个
Tool,read_only=False,写清description。 - 只读查询 → 一个
Tool,read_only=True;写进发行版的PlayerState就会每回合自动发给模型。 - 规则的完整正文 →
rule_sections,模型用player_rules按主题查。 - 结束回合 →
end_turn必须收summary并在回执里回text。
细节见 暴露给模型。
6. 让模型看得懂
模型的判断力取决于它看到的东西写没写清楚:
- 工具的
description写清参数、约束、失败原因——模型只看得见它。 - 资源、建筑、兵种注册成内容,模型就能用短键值和中文名两种写法。
- 规则正文分主题写,关键词要覆盖模型可能搜的词。
细节见 规则与手册。
7. 跨模块协作
需要别人的数据时,走能力接口,不要直接 import 别的模块:
- 在
Capabilities.Needs声明要谁的能力。 - 在
Interfaces写明调对方哪些方法。 - 在
owner/needs/optional里声明依赖,引擎替你解析顺序。
需要写别人的状态时,在 [State].Requests 申请,写入由引擎裁决。
细节见 跨模块协作。
8. 存档
模块要能存进档、读回档:
save_state返回可序列化的状态。load_state读回。- 版本变了要改
Mod.Version;发行版装载时严格核对,依赖不一致直接拒绝装载,不做静默迁移。
细节见 状态与存档。
9. 验收
- 离线回归全绿:
.venv/bin/python -m unittest discover -s tests - 自己的模块有测试:至少覆盖声明、行为、存档、错误路径、跨模块五项。
- 跑一遍真实对局,看模型是不是真的用上了你的内容。
细节见 测试与验收。
一张表看完
| 步骤 | 产出 | 参考 |
|---|---|---|
| 1 判断 | 模块 or 发行版 | 三层结构 |
| 2 划边界 | 三行接口定义 | 跨模块协作 |
| 3 写声明 | mod.toml | 模块声明 |
| 4 写实现 | GameMod 子类 | 引擎 API |
| 5 暴露给模型 | 工具、事实 | 暴露给模型 |
| 6 让模型看得懂 | 描述、内容、规则 | 规则与手册 |
| 7 跨模块 | 能力接口 | 跨模块协作 |
| 8 存档 | save_state / load_state | 状态与存档 |
| 9 验收 | 测试与对局 | 测试与验收 |