战国 Mod 开发文档

暴露给模型

工具、事实、描述、参数:模型到底看得见什么,怎么让它用对。

模型在这个游戏里只能通过工具说话。它看不见你的 Python 代码,只看得见工具表与工具回执。 所以「怎么写工具」不是接口问题,是产品问题。

工具分两类

类型标记作用
动作read_only=False改世界:建造、征兵、移动、宣战
只读查询read_only=True看世界:地块、部队、存量、外交

只读工具写进发行版的 PlayerState 后,每回合自动发给模型,模型不必额外查询:

[Distribution]
PlayerState = ["nations", "government", "land", "view", "army", "diplomacy", "stock", "catalog", "news"]
PlayerEvents = "news"

PlayerState 里的每一项都必须是存在且只读的工具名,否则发行版装载时就被拒绝。

描述就是给模型看的说明书

工具的 description 直接进模型工具表。写得含糊,模型就会瞎传参。

坏的写法:

Tool('build', self._build)      # 模型只看到一个词:build

好的写法:

Tool('build', self._build,
     description='在本国地块上动工:x、y 是地块坐标,kind 是建筑种类(查 catalog)。'
                 '只能建在本国地块上,材料不足会返回原因。')

写描述的 checklist:

  • 参数是什么、什么格式(坐标从 0 开始?地名还是编号?)
  • 有什么前置条件(在自己地块上?需要先有兵营?)
  • 失败会怎样(材料不足?不在交战状态?)
  • 要不要先查别处(价格看 catalog;战况看 query)

让模型能认内容

模型看到的是短键值(gold)和显示名(黄金)两套写法。内容注册表负责这层翻译。

def content_definitions(self):
    return {cls.TYPE_ID: cls for cls in RESOURCE_TYPES}     # 内容 ID → 定义

注册过的内容才有短键和显示名;没注册的内容,模型看到的是原始 ID(mini:plain), 它多半会照抄,然后失败。

再注册一组同义词,模型照抄面板里的中文名也能直接提交:

self.runtime.content.register_aliases('example:hello', {
    '黄金': 'example:gold', 'money': 'example:gold',
})

工具的参数如果接受内容键值,声明 content_parameters,引擎会在调用前归一化:

Tool('build', self._build,
     parameters={..., 'kind': {'type': 'string', 'enum': ['farm', 'mine']}},
     content_parameters=('kind',))

这样模型传 farm 或「农场」都行,引擎统一转成内容 ID。

结束回合:唯一的硬契约

模型客户端会这样处理回合结束:

if action == 'end_turn' and receipt['ok']:
    self.state.summaries.append({'turn': obs['period'], 'text': receipt['data']['text']})

所以 end_turn 必须:

  1. 接受一个 summary 参数(模型自己写的一句话总结);
  2. 在回执数据里返回 text(可以就是把 summary 原样带回)。

漏了 text,模型客户端会直接抛异常——这是发行版接模型时最常踩的坑。

@staticmethod
def _end_turn(world, actor, summary: str = ''):
    result = world.government.end_turn(actor)
    return {**result, 'text': summary or f'第 {result["period"]} 期行动结束。'}

模型看得见的事实词汇

模型面向的简报与仪表盘按事实名取数。发行版给哪些事实,简报就出哪些节:

事实名是什么
land本国地块明细
view视野内逐格
army部队(本国与他国)
stock资源存量(简化发行版用)
econ完整经济快照(stocks / latest_turn / latest_report / preview)
building_sites / building_catalog建筑工地与图鉴
government回合与国策(带 plan 键 = 有国策概念)
diplomacy外交(wars / alliances / entity_members …)
news事件流

发行版没有某个概念,简报就不出那一节——不会拿「0」冒充「没有这个东西」。 比如 minigame 没有 government.plan,模型就不会被催着交国策。

完整清单见 模型面向契约。

自查

写完工具后,用这四条检查:

  1. 模型只拿工具表和状态,能不能猜出每个参数该填什么?
  2. 每个动作的失败原因,回执里说得清吗?
  3. 只读事实够不够模型判断局势?缺什么补什么。
  4. end_turn 收 summary、回 text 了吗?