配置与启动
配置要填什么、怎么体检、一键启动的几种用法。
默认跑 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.json | native 的模板(密钥是占位文字) | 是 |
mp_config.experimental.example.json | experimental 发行版的模板 | 是 |
mp_config.minigame.example.json | minigame 开发模式的模板,零依赖 | 是 |
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 客户端;纯离线局不会触发 |