制作发行版
清单怎么写、挂点怎么排、客户端工厂怎么接模型。
发行版是装配清单,不写业务逻辑。
两层文件
mods/native/ 模块目录(实现)
mod.toml 发行版清单
resources/ 一个模块一个目录
army/
...
mods.toml 仓库根的入口:装哪个发行版
# mods.toml
[Load]
Packages = ["mods/native"]
# mods/native/mod.toml
[Distribution]
Id = "native"
Version = "4.9.0"
Members = ["mods/resources.toml", "mods/territory.toml", "mods/army.toml", ...]
RequiredState = ["resources", "territory", "army", ...]
ActorCollection = "nation_actors"
ActionGate = {Capability = "native:government", Method = "can_act"}
PlayerClock = {Capability = "native:government", Method = "period"}
PlayerEvents = "news"
PlayerState = ["government", "land", "army", ...]
[Distribution.Tools]
Entry = "mods.native.tools:build"
[Distribution.Session]
Entry = "mods.native.session:NativeSession"
字段全表见 发行版清单。
挂点
挂点是发行版定义的结算时机:
[[Hooks]]
Id = "cycle.start"
[[Hooks]]
Id = "cycle.end"
模块的结算阶段挂到这些点上:
def stages(self):
return (Stage('mini:buildings.produce', self._produce, hook='cycle.start',
provides=('production.done',)),)
引擎按挂点顺序、模块顺序跑阶段。挂点顺序由发行版声明的先后决定。
客户端工厂
发行版决定「谁来替玩家行动」:
[Distribution.ClientFactories.llm]
Entry = "clients.llm:LLMClient"
Configuration = "clients.config:normalize"
[Distribution.ClientFactories.mini]
Entry = "mods.examples.minigame.client:MinigameClient"
Entry:客户端类,按模块:类名解析。Configuration:这个客户端的配置归一化函数(模型客户端要api_key、model等字段)。- 客户端类要接受宿主的工厂契约:
__init__(self, cfg, record=None, services=None)。
配置里 "client": "llm" 的国家就交给模型客户端,"client": "mini" 交给简易策略。
同一个发行版可以同时接模型和不接模型——发行版与模型客户端之间没有耦合, 耦合在「工具面与事实形状」这份契约上,见 模型面向契约。
场景与剧本
[Distribution.Scenarios]
Entry = "scenarios.eight_nations:build"
剧本声明开局国家、地图尺寸、种子,以及可选的胜负条件。
管理 API
发行版可以挂管理 API(发消息、暂停、改配置):
[Distribution.Session]
Entry = "mods.native.session:NativeSession"
Observer = {Capability = "native:intelligence", Records = "to_save", Announce = "announce", Send = "send"}
Observer 声明观察者能力:记哪份记录、怎么公告、怎么送信。
发布一个发行版
- 目录结构:模块目录 +
mod.toml。 - 根目录加一个入口
mods.<名字>.toml。 - 配置里
"mods": "mods.<名字>.toml"。 - 写测试:装配成功、跑几回合、存档往返、模型客户端能驱动。
- 在
docs/site/content/附录/01-示例索引.md里登记。
换掉整套规则要改什么
只要两样:发行版清单(Members 换成另一批模块声明)与实现(新模块的代码)。 引擎、模型客户端、观察者、存档格式都不动。