<h1>civ-atlas · 多 Agent 沙盒</h1>

> 给 [civ-atlas](https://github.com/guaner-334/civ-atlas) 的星球历史推演加一层「可被 AI 接管」的沙盒：MCP 工具层、AI 君主回合、小事件裁决层、可配置场与地块级演化、本地浏览器查看器。

[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)
![MCP](https://img.shields.io/badge/protocol-MCP-5b8def)
[![Upstream](https://img.shields.io/badge/upstream-guaner--334%2Fciv--atlas-lightgrey)](https://github.com/guaner-334/civ-atlas)

![查看器跑完两轮的样子：左边是政区图与 AI 决策，右边是国家和君主信息](docs/screenshots/viewer.png)

<sub>本页图片均为程序模拟生成的地图，不是真实地图。</sub>

## 这是什么

上游 civ-atlas 是纯前端的世界生成 + 历史推演网站。这个仓库在它之上加了一层**无头、可编排、可 AI 接管**的沙盒：

- 不重写引擎：所有扩展都在编排层，通过「停止推演 → 下命令 → 接着推」的 `play` API 完成。
- 引擎确定性不破：同一世界 + 同一命令史 = 逐字节一致的结果（21 组指纹对账全过）。
- 全程可回放：AI 下的每一道命令都进命令史，`civ_session_verify` 能重推对账。

## 新增了什么

| 模块 | 内容 |
|---|---|
| **MCP 工具层**（`mcp/`） | 零依赖 JSON-RPC stdio 服务，21 个 `civ_*` 工具：建世界、开会话、下单、推演、编年史、导出、回放对账、君主回合、DM 小决策、小事件裁决、场目录 |
| **AI 君主**（`mcp/monarch.ts`） | 每个国家先拿简报，再由 LLM（或 mock）决定命令；每国每回合最多 3 条，编译成引擎命令后统一推演；支持 DeepSeek / 百炼 / 自定义 OpenAI 兼容 |
| **小事件裁决层**（`mcp/petty*.ts`） | 接官方 Jev `POST /api/v1/decisions`；客户端控 token（≤4250）、严格串行优先队列（P0/P1/P2）、超时/背压/熔断/降级，概率交给引擎统一随机流抽样 |
| **DM 小决策与故事** | 天灾/小贸易真写进引擎；`story` 干预让 DM 按剧情写事件，效果只落在城市折损、人口上限、发展、叙事四类 |
| **浏览器查看器**（`mcp/viewer.ts`） | 本地 `127.0.0.1:5190`：地图/疆域/国家详情/AI 决策/编年史/回合日志/回放对账/导出，含 DM、小事件、场图层与 hover 精确值 |
| **可配置场**（`fieldPlugin.ts`） | 玩家给一份 spec 就能生成一组原生插件表：自己选密度、扩散、衰减、强度，以及影响哪些官方数值（`city.capacity`/`war.odds`/`unrest.add` 等 6 个口） |
| **地块级场** | `unit: "tile"` 时场按世界全部地块逐年演化，出手前聚合成州值再影响引擎；图层内存按地块、存档按 `cell` 层 |
| **官方 .civplugin 加载器**（`plugin-loader.ts`） | 在 MCP 的 CommonJS 产物里用 QuickJS 直装官方推演插件（文件或源码目录，最多 4 个），与内置场并列 |
| **魔力动态场**（`magicPlugin.ts`） | 内置示例插件：魔脉扩散渗流 + 人口耗散，每 50 年一帧，影响城市容量；强度 0 时官方指纹逐字节不变 |

更多细节在 [`mcp/README.md`](mcp/README.md)。

## 快速开始

需要 Node.js 22+ 与 pnpm。

### 1. 跑原版网站

```bash
pnpm install
pnpm dev          # http://localhost:5188
```

Windows 下也可以双击根目录的 [`启动.bat`](启动.bat)。

### 2. 构建 MCP 工具层

```bash
# 本机没有 pwsh 可执行文件时用 powershell 调脚本
powershell -NoProfile -ExecutionPolicy Bypass -File mcp/build.ps1
```

构建产物在 `mcp/.build/`，把 MCP 客户端指向 `mcp/.build/mcp/server.js`：

```json
{
  "mcpServers": {
    "civ-atlas": {
      "command": "node",
      "args": ["<仓库路径>/mcp/.build/mcp/server.js"]
    }
  }
}
```

### 3. 跑查看器

```bash
node mcp/.build/mcp/viewer.js --port 5190
# 浏览器打开 http://127.0.0.1:5190
```

查看器只监听本机，世界/会话在内存里，关掉就没了；日志写在 `mcp/.runs/`（不提交）。

### 4. 一个最小 AI 对局

1. `civ_world_create`（`seed` 必填，`params.cells` 可选）
2. `civ_monarch_setup`（`polities: "all"`，`mock: true` 先不联网）
3. `civ_session_open`（`worldId` + `startYear`）
4. `civ_monarch_round` 反复跑；中途 `civ_state_get` / `civ_session_verify`

想要场：`civ_session_open` 加 `fields`（可带 `"unit": "tile"`）；想要官方插件：加 `plugins`。

## 验证

```bash
# 13 个自检（引擎、协议、君主、press、DM、小事件、场、插件、地块场）
node mcp/.build/mcp/selftest.js
node mcp/.build/mcp/selftest-protocol.js
node mcp/.build/mcp/selftest-monarch.js
node mcp/.build/mcp/selftest-press.js
node mcp/.build/mcp/selftest-dm.js
node mcp/.build/mcp/selftest-dm-oracle.js
node mcp/.build/mcp/selftest-petty-core.js
node mcp/.build/mcp/selftest-petty-oracle.js
node mcp/.build/mcp/selftest-field.js
node mcp/.build/mcp/selftest-magic.js
node mcp/.build/mcp/selftest-field-plugin.js
node mcp/.build/mcp/selftest-plugin-loader.js
node mcp/.build/mcp/selftest-tile-field.js
```

- 13 组自检全绿（含地块场 30/30）。
- 根 `tsc --noEmit` 与 `examples/plugins` 类型检查均为 0 错误；已发布的插件接口第 1 版未改动。
- 确定性指纹 21/21 一致（含改地形、干预、分段推演等 21 组，2026-11-11）。

## 截图

| 魔力动态场 | 地块级场 |
|---|---|
| ![魔力场：魔脉扩散渗流，逐年变化](docs/screenshots/magic-field.png) | ![地块级场：每块地逐年演化，再聚合成州值影响容量](docs/screenshots/tile-field.png) |

![小事件裁决层：一次 petty 回合的决策与摘要](docs/screenshots/petty-panel.png)

## 目录

```
mcp/                 无头工具层（MCP 服务、君主、DM、小事件、查看器、场渲染、自检）
src/gen/civ/         引擎与官方推演插件接口（新增 magicPlugin / fieldPlugin / storyEngine 等）
ai-ruler/            「AI 扮演统治者」独立原型（简报 → 决策 → 命令，含 mock）
docs/                开发文档、截图
examples/plugins/    官方格式推演插件示例
多Agent沙盒-改造计划.md  这次改造的设计与分阶段计划
UPSTREAM.md          上游 civ-atlas 原 README
```

## 文档

- [`mcp/README.md`](mcp/README.md)：MCP 工具、AI 君主、DM/小事件、场系统、插件加载器、查看器的详细用法与边界
- [`多Agent沙盒-改造计划.md`](多Agent沙盒-改造计划.md)：三阶段改造的目标、约束、验收标准
- [`ai-ruler/README.md`](ai-ruler/README.md)：AI 统治者原型（可先不接 MCP 单独跑）
- [`docs/development.md`](docs/development.md)：上游的引擎开发说明

## 许可与致谢

- 本项目基于 [guaner-334/civ-atlas](https://github.com/guaner-334/civ-atlas)（AGPL-3.0），保留其全部历史与许可证。
- 本仓库的修改同样以 **AGPL-3.0** 发布；如果把它改完挂到网上给别人用，需要按 AGPL 公开修改。
- 引擎、星球生成、历史推演、原网站的所有功劳归上游作者与贡献者；这里新增的是多 Agent 编排、场系统、查看器与工具层。