Agent War Game

回合制 AI agent 对抗沙盘。每个 agent 扮演一个国家的 commander，由 pi-mono 持久 session 驱动 OpenAI-compatible 模型，通过 move_troops tool 下达指令。所有 UI 和 system prompt 均使用中文。

快速开始

# 1. 安装依赖
pnpm install

# 2. 配置模型 — 复制示例文件并填入 API key
cp data/models.example.json data/models.local.json
# 编辑 data/models.local.json，填入你的 API key

# 3. 启动开发服务器
pnpm dev

打开 http://localhost:5173，点击「创建战局」开始游戏。

• 每个国家由一个 AI commander 控制，通过 LLM 生成军事指令
• 点击「推进一回合」让所有 commander 思考并执行本回合移动
• 左侧 Canvas 棋盘实时显示战场态势（支持缩放/平移）
• 右侧面板查看国家状态、commander 思考过程、历史回合回放

技术栈

• TypeScript + pnpm monorepo
• VoidZero vite-plus
• React + Vite web
• Hono Node.js API
• pi-mono: @mariozechner/pi-agent-core + @mariozechner/pi-ai
• 文件存储：data/games

配置模型

data/models.local.json 已被 .gitignore 忽略。支持配置多个模型，创建战局时轮流分配给各国。

[
  {
    "id": "deepseek-flash",
    "name": "DeepSeek Flash",
    "provider": "deepseek",
    "baseUrl": "https://api.deepseek.com",
    "modelId": "deepseek-v4-flash",
    "apiKey": "<your-api-key>",
    "contextWindow": 64000,
    "maxTokens": 4096
  }
]

开发命令

pnpm install                  # 安装依赖
pnpm dev                      # 同时启动 API + web（并行）
pnpm api                      # 仅启动 API（tsx watch，端口 8787）
pnpm web                      # 仅启动 web（Vite，端口 5173）
pnpm check                    # 类型检查 + lint
pnpm test                     # 运行所有测试
pnpm build                    # 构建所有包

Vite dev server 会把 /api 代理到 http://localhost:8787。

游戏规则

基本设定

• 默认棋盘 50 × 50，至少 3 个国家，每国首都格初始 1000 士兵。
• 创建游戏时可自定义棋盘大小、国家数量、移动距离、每回合指令上限等参数。

移动

• 每回合每个 commander 通过 move_troops tool 下达最多 maxOrdersPerTurn（默认 30）条移动指令。
• 仅支持正交移动（上下左右），Manhattan 距离不超过 moveRange（默认 5）。
• 单格士兵每回合只能被调度一次，校验基于回合开始时的来源格兵力。
• 来源格可以被移空；领土仍归原占领方，直到被其他国家重新占领。

穿透战斗

部队沿 L 型正交路径移动，途经每个敌方格子时触发战斗：

• 途经空格或己方格：无消耗通过。
• 途经敌方空占格（0 士兵）：直接占领，无损耗。
• 途经敌方驻军格：与守军交战，胜者占领该格；攻方胜则剩余兵力继续前进，败则全军覆没。
• 到达终点时，所有到达的同国部队合并为友军，与原驻军一同参与结算。

战斗结算

• 同一格所有势力（攻方 + 守军）统一比较兵力，唯一最多者占领，平局变中立。

首都与淘汰

• 首都需要进攻兵力超过守军的 capitalCaptureRatio（默认 1.2）倍才能占领。
• 首都被占领后，原国家淘汰；全部领土和驻军归进攻方。
• 领土数为 0 也视为失败。

增援

• 每回合存活国家每块领土获得 reinforcementPerCell（默认 10）士兵，直接补充到该格。

胜利条件

• 场上仅剩一个存活国家时游戏结束，该国获胜。

API

方法	路径	说明
GET	/health	健康检查 + 模型状态
GET	/api/models	可用模型列表
POST	/api/games	创建游戏
GET	/api/games	游戏列表
GET	/api/games/:id	游戏状态
POST	/api/games/:id/tick	推进一回合
GET	/api/games/:id/commanders	commander 记录
GET	/api/games/:id/turns	回合列表
GET	/api/games/:id/turns/:turn	回合快照（含 commander 记录）
GET	/api/games/:id/events	SSE 事件流

创建游戏时 body 可选，支持自定义参数：

{
  "width": 30,
  "height": 30,
  "nationCount": 4,
  "moveRange": 8,
  "maxOrdersPerTurn": 20,
  "modelIds": ["deepseek-flash"]
}

关键路径

• 游戏规则和结算：packages/game-engine/src
• 共享类型：packages/contracts/src/types.ts
• pi-mono commander session：apps/api/src/runtime/commander-session.ts
• Hono API：apps/api/src/app.ts
• React 战场页面：apps/web/src/components/WarRoom.tsx
• Canvas 棋盘渲染：apps/web/src/components/BattleCanvas.tsx
• SSE 事件解析：apps/web/src/event-utils.ts