Skip to main content
Glama
swanwickk

witp-ae

by swanwickk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

WitP-AE Autonomous Commander & Neural Staff System

《太平洋战争：海军上将篇》（War in the Pacific: Admiral's Edition）通用自动化作战参谋与智能指挥系统

License: MIT Platform Game Protocol

⚠️ 测试范围说明： 本系统底层内存直控、存档解析读写与 AI 参谋部推理架构均为战区通用设计。目前仅对官方《珊瑚海》（Scenario 003: The Battle of the Coral Sea）战役剧本进行过实机自动化推演与完整闭环测试。

目录

Related MCP server: CMO Agent Bridge

一、这是什么（系统介绍）

1.1 系统定位与核心价值

《War in the Pacific: Admiral's Edition》（WitP-AE）是硬核兵棋推演的标杆级作品，全图涵盖数以万计的真实舰船、航空中队、基地设施、后勤网络与海空战斗结算。

本项目是面向 WitP-AE 的通用自动化指挥与 AI 作战参谋框架。它通过逆向底层二进制数据与内存映射，彻底解耦传统脆弱的屏幕点击，提供毫秒级、零键鼠的游戏状态读写通道，并基于大语言模型（LLM）构建战术可自由配置的通用参谋推理引擎。

1.2 核心支柱与技术架构

┌──────────────────────────────────────────────────────────────────┐
│                   LLM Commander & AI Agent                       │
└──────────────┬───────────────────────────────────┬───────────────┘
               │                                   │
      [下达战术决策/自由意图]                 [感知态势/研判方案]
               ▼                                   ▲
┌──────────────────────────────┐   ┌──────────────────────────────┐
│     前线操作手 (witp-cmd)      │   │   通用参谋部 (witp_staff.py)   │
│  - 编队航路点内存直写        │   │  - 多维交战威胁客观评估      │
│  - 航空防空分层与扇面设定    │   │  - 动态锚点与机动阵位核算    │
│  - 单键 E+y 注入推进回合     │   │  - 专职化海空侦察网络构建    │
└──────────────┬───────────────┘   └──────────────▲───────────────┘
               │                                   │
      [T1 内存直控 / T2 键盘]             [二进制读层 / 战报解析]
               ▼                                   │
┌──────────────────────────────────────────────────┴──────────────┐
│               WitP-AE 运行时底层 (Wine 1108r9)                   │
│  • .pws 存档二进制流解析 (gzip + raw deflate + zlib)             │
│  • 进程内存双镜像实时读写 (PWSTaskGroup / PWSAirGroup / Ship)    │
│  • 终局模态弹窗自动 OCR 评分与自旋防护 (witp_endgame.py)         │
└─────────────────────────────────────────────────────────────────┘

  1. T1 内存直控与二进制读写（Zero-GUI Direct Control）：

    • 逆向 WitP-AE 的 .pws 数据流结构与进程内存映射，实现编队航路点（Waypoints）、航空队任务、CAP 防空比例、搜索扇面、地面部队战斗模式的内存毫秒级直接修改；

    • 双镜像同步与校验机制，杜绝游戏存档覆盖冲突与数据脏化。

  2. T2 极简按键单键推进（Single-Key Turn Advance）：

    • 依托标准 RFB 键盘通道，以极简的 E → y 单键指令完成回合推进，配合全屏哈希变化校验与终局画面拦截保护，无需依赖鼠标拖曳。

  3. 通用作战参谋系统（Neural Staff Intelligence）：

    • 参谋部为纯通用代码实现，战术目标、交战规则与优先级完全由使用者通过配置与指令自由定义；

    • 实时进行战场态势研判、航路风险测算与侦察扇面规划，出具结构化的《作战方案建议书》。

  4. 决策因果日志留痕（Causal Logging）：

    • 逐回合记录 $(S, D, R)$（态势认知、决策意图、实际战果），为战役复盘与推演分析提供完整数据支撑。

1.3 通用作战参谋部特性

  • 战术意图自主配置：支持通过配置文件（config.yaml）或环境变量（WITP_COMMANDER_PRIORITY）注入指挥官作战指导原则，参谋部在此原则下评估机动风险与打击收益。

  • 动态威胁与阵位核算：根据当回合读层推导出的基地与舰队坐标，动态计算舰载机打击位，自动标定并避开最近敌方陆基机场轰炸圈，同时核算最近的友方退路锚点。

  • 专职化侦察体系：根据机种性能（远程巡逻机、舰载侦察机、近距水上机）自动规划最优对海搜索扇面与反潜配比。

二、在什么环境下使用（运行环境与前置依赖）

2.1 基础系统与依赖栈

  • 操作系统：Linux x86_64（Ubuntu 22.04 / 24.04 LTS 或 Debian 12 验证通过）。

  • Python 环境：

    • 宿主环境：Python 3.10+（运行 MCP 服务端、参谋部推理系统、前线 CLI）。

    • Wine 虚拟子环境：内置 32 位 Python 3.11（C:\py32\python.exe，用于调用游戏原生 pwsdll.dll 解析器）。

  • 系统工具包：

    sudo apt-get update && sudo apt-get install -y \
    wine wine32 wine64 \
    tigervnc-standalone-server x11vnc openbox \
    xdotool imagemagick tesseract-ocr tesseract-ocr-eng \
    git curl jq

2.2 游戏本体与运行模式

  • 必须采用官方原版英文 1108r9：

    • 严禁使用第三方汉化版 EXE（汉化版写入存档时原生 pwsdll.dll 会报 -5 解密校验失败）。

  • 分辨率与桌面规范：

    • 原生游戏分辨率为 1024x768；

    • 虚拟桌面（Xvnc）推荐配置为 1400x1050x24 或 1024x768x24；

    • 必须运行 Openbox 窗口管理器：Wine 依赖窗口管理器分配按键焦点，缺失 Openbox 将导致按键静默丢失。

2.3 关键系统补丁（音效崩溃规避与 cgroup 隔离）

① quartz.dll 二进制规避补丁（根治随机段错误）

  • 现象：游戏自带音效解码组件 witprec.exe 在 Wine 环境下运行 1.5~3.5 小时后必报 filesource.c:397 越界断言并发生段错误崩溃。

  • 解法：启动脚本 automation/witp-launch-en1108.sh 内置安全出口补丁，将越界跳转重定向至安全释放分支，实现百小时长效稳定运行。

② 独立 systemd cgroup 隔离守护

  • 先决条件：游戏必须跑在独立的 systemd 服务中，严禁从交互式 shell 中直接启动：

    # /etc/systemd/system/witp-game-en.service
[Unit]
Description=WitP-AE (English 1108r9) game instance - isolated cgroup
After=witp-xvnc98d.service witp-openbox98.service

[Service]
Type=simple
ExecStart=/bin/bash /path/to/witp/automation/witp-launch-en1108.sh
WorkingDirectory=/path/to/witp/automation
Environment=DISPLAY=:98
Restart=no
KillMode=control-group
TimeoutStopSec=5
SendSIGKILL=yes

三、怎么使用（完整操作指南）

3.1 快速部署与初始化

  1. 克隆项目代码：

    git clone https://github.com/swanwickk/witp.git /opt/witp
cd /opt/witp

  2. 配置 Python 虚拟环境与依赖：

    python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

  3. 配置参谋部大模型连接（可选）：

    cp staff/config.yaml.example staff/config.yaml
# 填入您的大模型 API Base URL、API Key 与主模型配置

  4. 配置命令行快捷方式：

    sudo ln -sf /opt/witp/bin/witp-cmd /usr/local/bin/witp-cmd

3.2 命令行前线工具（witp-cmd）

witp-cmd 提供了开箱即用的指挥官操作集合：

① 参谋部自检与方案获取

witp-cmd staff --check         # 参谋部服务健康体检（API/快照新鲜度/存档一致性）
witp-cmd staff --fix           # 自动修复：拉起服务 + 强制重读存档
witp-cmd staff --saves         # 枚举当前游戏目录下的可用存档清单
witp-cmd staff --save 000      # 召唤参谋部针对最新 Autosave 产出《作战方案建议书》

② 自动开局与游戏控制

WITP_SIDE=allied witp-cmd launch   # 以盟军视角一键启动战役剧本并进入第 1 回合
WITP_SIDE=japan  witp-cmd launch   # 以日军视角一键启动战役剧本
witp-cmd save-game --slot 3        # 将当前战局手动存档至槽位 003
witp-cmd status                    # 查看当前屏幕画面与战局状态

③ 亲手落子与指令下达

# 编队航路点设置（自动执行邻域校验）
witp-cmd set-dest TF14 100 137

# 战斗机 CAP 防空比例设定
witp-cmd set-cap VF-2 60 --alt 15000

# 侦察中队对海搜索比例与扇面设定
witp-cmd set-search VP-11 100 --arc 315,45

④ 推进过回合与因果留痕

# 单键 E+y 注入推进过回合，并在终局画面时自动保护截屏
witp-cmd end-turn

# 每回合回写因果记录（态势、决策、战果）
witp-cmd record-turn \
  --decision "编队就位战区预备阵位，空军加强搜索" \
  --result "成功推进过回合，前方捕获敌编队信号" \
  --orders "TF14->100,137; VP-11 search=100"

# 终局战果台账归档
witp-cmd close-game \
  --outcome "DECISIVE VICTORY" \
  --own-score 1200 \
  --enemy-score 300 \
  --notes "推演终局统计完成"

3.3 参谋部推演系统（Staff Intelligence）

参谋部负责全局感知与战术方案推演：

  • 方案包含板块：

    1. 战场客观态势与威胁研判（按红/黄/绿标示前沿交战区、交通线与后方基地）；

    2. 核心战略意图与侦察指导；

    3. 己方兵力与战损态势（航母完好度、其他舰种构成）；

    4. 推荐行动清单（含目标编队、动作类型、坐标参数与置信度）。

  • 运行看板 API：

    python3 staff/kev_server.py --port 18091

    可通过浏览器打开 dashboard/witp-dashboard.html 查看推演大屏。

3.4 MCP 服务协议接入（AI Agent 工具调用）

本系统完整实现了 MCP（Model Context Protocol）标准。在支持 MCP 的 Agent 环境（如 Hermes Agent、Claude Desktop、Cursor）中，只需配置服务入口：

mcpServers:
  witp-ae:
    command: /opt/witp/venv/bin/python3
    args:
      - /opt/witp/mcp-server/server.py
    env:
      WITP_INSTANCE: /root/.wine-witp/drive_c/1108r9
      WITP_DISPLAY: ":98"
      WITP_VNC_PORT: "5902"
    enabled: true

常用核心 MCP 工具

  • witp_status：毫秒级解析当前存档态势，返回双方 VP、编队旗舰、坐标及任务码。

  • witp_taskforces / witp_airgroups / witp_ships：直读舰队、航空中队、舰船全量内存字段。

  • witp_mem_set_tf_waypoints：**【零键鼠】**直接向游戏内存写入编队航路点序列。

  • witp_mem_set_airgroup：**【零键鼠】**修改航空队 CAP 百分比、搜索比例与扇面。

  • witp_mem_object_set：**【零键鼠】**通用对象字段内存修改（支持舰船、基地、地面部队战斗模式）。

  • witp_end_turn：单键注入 E → y，安全等待引擎结算并回读新 Autosave。

  • witp_victory_forecast：依据手册 ch17 公式实时推演胜负判定等级。

  • witp_weather_report：9 象限气象数据实时预测。

3.5 决策因果日志机制（Causal Logging）

系统鼓励以结构化数据追踪决策演进：

  • 每一回合操作均沉淀为因果记录 JSON（包含时间、回合数、前置态势、决策动作与次日战报结算反馈）；

  • 为多局对照分析、战术对比与策略优化提供可信、可复现的事实依据。

四、项目目录结构

witp/
├── README.md                      # 本说明文档
├── LICENSE                        # MIT 开源许可证
├── requirements.txt               # Python 依赖清单
├── .gitignore                     # 运行时临时文件与缓存忽略
├── bin/
│   └── witp-cmd                   # 指挥官前线命令行中枢工具
├── mcp-server/
│   ├── server.py                  # MCP 协议服务端（70+ 零键鼠与内存工具）
│   └── test_*.py                  # 自动化端对端测试套件
├── staff/
│   ├── witp_staff.py              # 通用参谋部方案推理核心
│   ├── witp_cmd_staffops.py       # 参谋部自愈与回写运维模块
│   ├── auto_start_coral_sea.py    # 战役自动化启动器
│   ├── kev_server.py              # 看板后端 API 服务
│   ├── orchestrator.py            # 推演主循环编排
│   ├── witp_models.py             # 参谋大模型调用封装
│   ├── config.yaml.example        # 参谋部配置模板（已脱敏）
│   └── lib/                       # 底层执行、感知、几何计算核心库
├── reader/
│   ├── witp_read.sh               # 存档读层入口（flock 进程锁与原子切换）
│   ├── detect_side.py             # 顶栏阵营权威检测
│   ├── witp_report.py             # 战报解析引擎
│   ├── witp_summarize.py          # 态势中文简报生成
│   └── pywitpaescraper/           # 32 位原生 DLL 存档解析器
├── skills/                        # Hermes Agent 推演技能集
│   ├── witp-ae-autopilot/         # 参谋指挥联动 SOP
│   ├── witp-ae-control/           # MCP 直控操作规范
│   ├── witp-ae-interface/         # Wine/VNC 与系统层规范
│   ├── witp-ae-manual/            # 游戏官方手册与机制知识库
│   └── witp-ae-save-format/       # pws 二进制格式逆向说明
├── automation/
│   ├── witp-launch-en1108.sh      # 游戏启动守护与崩溃安全出口补丁
│   ├── witp_endgame.py            # 终局模态弹窗捕获与自旋恢复
│   ├── witp_nav.py                # 地图导航与实体定位
│   └── witp_vnckey.py             # VNC 键盘注入
├── docs/                          # 详细逆向分析报告与手册覆盖表
└── dashboard/                     # Web 可视化仪表盘插件

五、开源许可证

本项目采用 MIT License 开源许可证。 欢迎全球太平洋战争兵棋爱好者、AI 游戏智能体与决策智能研究者共同参与贡献！

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • defcon-mcp-server

    jorisvddonk
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI tools to play the game DEFCON by providing tools to communicate with the game, analyze game state, and issue commands such as placing structures, moving fleets, and launching nukes.
    3
    -

  • CMO Agent Bridge

    Nuclear2
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to read and control Command: Modern Operations scenarios locally via MCP tools, supporting real-time battle assessment, task planning, and scenario editing.
    7
    MIT

  • San9MCP

    aoye516
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to connect to and control a windowed copy of Romance of the Three Kingdoms IX with Power Up Kit, letting them observe the game UI, gather officer/city intelligence, issue facility/transport commands, and advance turns through exposed MCP tools.
    -

  • Clausewitz-MCP

    smerss
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with Hearts of Iron IV by reading live game memory and sending commands through the game's own command queue for real-time gameplay and strategic decisions.
    18
    -