战国 Mod 开发文档

配置与启动

配置要填什么、怎么体检、一键启动的几种用法。

默认跑 native

./start.sh 默认读 mp_config.json,走 native 发行版(mods.toml)。 发行版由配置里的 mods 字段决定:没写就是 native。

./start.sh                       # 续局(没有存档就新开一局)
./start.sh --new --turns 10      # 开新局跑 10 个周期
./start.sh --check               # 配置体检:逐国核对,打印结果后退出,不开局
./start.sh --config 我的配置.json # 换配置(发行版由该文件的 mods 决定)
./start.sh --offline             # 换到零依赖的 minigame 开发模式,不需要任何 API key

首次运行没有 mp_config.json 时,脚本会从 mp_config.example.json 复制一份并停下, 让你先填密钥。

源码默认v13;选择v14候选规则AI需要NumPy/SciPy;普通启动脚本会在项目虚拟环境安装requirements.txt。直接运行mp_run.py或desktop.py前应先安装同一份依赖。推荐Python3.13(支持3.11/3.12),Windows便携包已内置求解环境;LLM协议、v13/v11plus和minigame仍保留各自的标准库实现。

配置放哪、填什么

文件作用入库
mp_config.example.jsonnative 的模板(密钥是占位文字)是
mp_config.experimental.example.jsonexperimental 发行版的模板是
mp_config.minigame.example.jsonminigame 开发模式的模板,零依赖是
mp_config.json你真正用的配置否(含明文密钥,已在 .gitignore)
mp_config.<名字>.json其它配置的命名变体否

每个国家要填什么

只有 "client": "llm" 的国家才需要密钥:

字段必填说明
id是国家标识(scenario:qin)
name是显示名
client是llm(接模型)/ rule(内置规则 AI)/ 发行版自带的其它客户端
base_url接模型时必填API 端点地址(provider 可选 openai/responses/anthropic)
api_key接模型时必填该端点的密钥
model接模型时必填模型名
provider否openai(缺省)/ responses / anthropic,不按 base_url 猜
enable_turn / enable_turn_max否中途加入的回合窗口

其余字段(temperature、max_tokens、max_steps、thinking、reasoning_effort、 ctx_window、ctx_fill …)都有缺省值,按需调。

顶层默认:写在顶层的 base_url / api_key / model 会被每个国家继承, 国家自己的值优先——同一家服务接八个国家时不用写八遍。

配置体检

./start.sh --check

逐国打印客户端、端点、模型与状态,缺什么说清楚:

配置体检
  发行版:native 4.19.0  (入口 mods.toml)
  地图:60×60  种子:20260905
  · 秦(scenario:qin)
      客户端:llm
      端点:https://api.deepseek.com/v1    模型:deepseek-v4-flash
      状态:缺 api_key
  · 楚(scenario:chu)
      客户端:rule
      状态:就绪(内置规则 AI,不需要密钥)

模板里的占位文字(「粘贴你的 api key」之类)会被当成没填。

体检不通过时,开局前就会停下并说明缺什么——不会等到第一次请求时抛一个 KeyError。

零依赖的离线模式

minigame 发行版是纯标准库实现,不需要装任何东西、不需要 API key:

./start.sh --offline --new --turns 5

它的规则是三种资源、一个地形、五种建筑、一个兵种、宣战与议和。 这套规则就是开发模式——写新 Mod 时拿它当试验场。

配置在 mp_config.minigame.example.json:

{
  "mods": "mods.minigame.toml",
  "map_size": 12,
  "seed": 20261020,
  "nations": [
    {"id": "scenario:qin", "name": "秦", "client": "mini", "position": [3, 3]},
    {"id": "scenario:chu", "name": "楚", "client": "mini", "position": [8, 8]}
  ]
}

"client": "mini" 用发行版自带的简易策略驱动;换成 "client": "llm" 就交给真实模型, 发行版一行不用改——发行版与模型客户端之间的约定见 模型面向契约。

依赖策略

start.sh 会先看配置里有没有 "client": "llm":

  • 有:建 .venv、按 requirements.txt 装依赖(清华镜像优先,失败回落官方源)。 2026-10-24 起 LLM 接入为标准库原生实现,requirements.txt 本身已无第三方依赖; 该分支只是保留建 venv 的行为。
  • 没有:直接用系统 python3,不建虚拟环境、不装任何东西。

地图 PNG 图另需 Pillow(requirements-vision.txt);不装不影响开局,只是没有那张图。

密钥安全

  • 密钥只写进 mp_config.json(或 mp_config.<名字>.json),这些文件已在 .gitignore 里。
  • 模板文件(*.example.json)里放的是占位文字,可以入库。
  • 体检与日志都不打印密钥;--check 只显示端点与模型名。
  • 别把真实配置复制成模板再提交——先确认 git status 里没有 mp_config*.json。

终局结算

./settle.sh              # 打分 + 结算厅聊天
./settle.sh --table      # 只看成绩单
./settle.sh --no-chat    # 只打分

settle.sh 复用 start.sh 建好的 .venv;没有就用系统 python3。

常见问题

现象原因
体检说「缺 api_key」模板占位文字没换掉
体检说「不是本发行版声明的客户端」配置里的 client 与该发行版对不上(minigame 用 mini,native 用 llm / rule)
启动报「存档依赖与当前发行版不一致」存档是旧发行版/旧模块版本写的,见状态与存档
第一次跑要装依赖配置里有 llm 客户端;纯离线局不会触发