Skip to main content
Glama
civ-atlas

civ-atlas

by Lain-Eugem

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

License: AGPL-3.0 Node MCP Upstream

查看器跑完两轮的样子:左边是政区图与 AI 决策,右边是国家和君主信息

本页图片均为程序模拟生成的地图,不是真实地图。

这是什么

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

  • 不重写引擎:所有扩展都在编排层,通过「停止推演 → 下命令 → 接着推」的 play API 完成。

  • 引擎确定性不破:同一世界 + 同一命令史 = 逐字节一致的结果(21 组指纹对账全过)。

  • 全程可回放:AI 下的每一道命令都进命令史,civ_session_verify 能重推对账。

Related MCP server: Fieldkit

新增了什么

模块

内容

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。

快速开始

需要 Node.js 22+ 与 pnpm。

1. 跑原版网站

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

Windows 下也可以双击根目录的 启动.bat。

2. 构建 MCP 工具层

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

构建产物在 mcp/.build/,把 MCP 客户端指向 mcp/.build/mcp/server.js:

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

3. 跑查看器

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。

验证

# 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)。

截图

魔力动态场

地块级场

魔力场:魔脉扩散渗流,逐年变化

地块级场:每块地逐年演化,再聚合成州值影响容量

小事件裁决层:一次 petty 回合的决策与摘要

目录

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

文档

许可与致谢

  • 本项目基于 guaner-334/civ-atlas(AGPL-3.0),保留其全部历史与许可证。

  • 本仓库的修改同样以 AGPL-3.0 发布;如果把它改完挂到网上给别人用,需要按 AGPL 公开修改。

  • 引擎、星球生成、历史推演、原网站的所有功劳归上游作者与贡献者;这里新增的是多 Agent 编排、场系统、查看器与工具层。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server that acts as a local stdio adapter for Civarium agent HTTP APIs, enabling interaction with game agents through tools like get_active_round, get_visible_state, submit_command, list_my_commands, and wait_next_round.
      15
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to inspect and reverse-engineer large binaries through bounded stdio JSON-RPC 2.0 tools for graph queries, SSA facts, path solving, runtime grounding, and mod scaffolding.
      1
      AGPL 3.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI tools and agents to form contract-bound organizations, execute persistent task DAGs with independent audits, score decisions with counterfactual trees, run time-compressed world simulations, and control an on-demand localhost dashboard via stdio tools.
      6
      1
      Apache 2.0