暴露给模型
工具、事实、描述、参数:模型到底看得见什么,怎么让它用对。
模型在这个游戏里只能通过工具说话。它看不见你的 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 必须:
- 接受一个
summary参数(模型自己写的一句话总结); - 在回执数据里返回
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,模型就不会被催着交国策。
完整清单见 模型面向契约。
自查
写完工具后,用这四条检查:
- 模型只拿工具表和状态,能不能猜出每个参数该填什么?
- 每个动作的失败原因,回执里说得清吗?
- 只读事实够不够模型判断局势?缺什么补什么。
end_turn收 summary、回text了吗?