CMO Agent Bridge
by Nuclear2
README.md
# CMO Agent Bridge
让 Codex、Claude Code、Cursor 等 Agent 直接读取和操作本机运行中的
**Command: Modern Operations（CMO）**想定。
[](https://github.com/Nuclear2/cmo-agent-bridge/actions/workflows/ci.yml)
[](docs/installation.md)
[](https://github.com/Nuclear2/cmo-agent-bridge/releases)
[](LICENSE)
> **平台支持：仅限 Windows。**
[下载 v0.8.0](https://github.com/Nuclear2/cmo-agent-bridge/releases/tag/v0.8.0) ·
[快速上手](docs/quickstart.md) ·
[各框架安装](docs/frameworks/README.md) ·
[CMO Lua API](https://commandlua.github.io/)
CMO Agent Bridge 将推演和想定制作中常用的 Lua API 整理成结构化 MCP 工具。Agent
可以读取战场态势、创建任务、分配兵力、规划航路和加油，也可以协助制作单位、天气与事件。
所有通信都留在本机，CMO 侧使用两个很短的独立事件：命令轮询，以及结束时的一次性记录。
Agent 也可以直接读取 CMO 已有的 `Logs\YYYY-MM-DD_HH.mm.ss.txt` 消息日志。这个读取不经过 Lua，
不会改写日志目录，想定暂停时仍然可用，可用于接收剧本消息、事件结果和排查意外暂停。
进入一个想定后，Agent 会先读取想定介绍和当前玩家方的 briefing，确认战役目标、已知情报、
ROE、时间限制与胜负标准，再开始态势评估和部署；其他阵营的简报不会被读取。
大型想定会分三层读取兵力：先建立轻量单位目录，再读取 CMO 原生概览，最后只对可能投入行动的
单位深读战备、载荷和库存。这样既能看清数百个单位的整体编成，也不会把时间和上下文浪费在无关
单位的完整字段上。
> **当前版本是 v0.8.0 预览版。** 已在 Windows、CMO Build 1868 上验证；第一次接入建议使用
> 想定副本。
## 你可以直接这样说
> 以 `LIVE_PLAYER` 模式连接当前想定。先汇总我方空中态势和已知威胁，再给出 CAP 调整建议，
> 暂时不要修改想定。
> 在现有两个 CAP 区中间创建一个新任务区，把所有 J-36 分配过去；完成后读回任务和分配结果。
> 以 `SCENARIO_AUTHOR` 模式，为这个想定添加一个进入区域后触发的增援事件，并检查触发器、
> 条件和动作是否关联正确。
它适合三类工作：
| 场景 | 可以完成的工作 |
|---|---|
| 推演 | 态势评估、任务规划、兵力分配、条令与 WRA、EMCON、航路、加油、交战和时间倍率 |
| 想定制作 | 阵营、单位、任务、天气、时间线、事件、Special Action、计分和部分库存设置 |
| 测试与裁决 | 受控注入、想定检查、故障诊断和裁决记录 |
## 快速开始（Windows）
下面以 Steam 默认安装路径和 PowerShell 为例。完整的升级、卸载和自定义路径说明见
[安装文档](docs/installation.md)。
### 1. 安装 uv
bridge 由 [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 管理，在 PowerShell 中执行：
```powershell
winget install --id astral-sh.uv -e
uv --version
```
需要 `uv 0.11.26` 或更高版本；如果已安装但版本较旧，运行
`winget upgrade --id astral-sh.uv -e`。`uvx` 会为 bridge 准备独立的 Python 3.12 环境和运行依赖。
### 2. 安装 Agent 插件
#### 只有 ChatGPT / Codex Desktop
如果没有可用的 `codex` CLI，下载并运行 Desktop 安装脚本：
```powershell
$installer = Join-Path $env:TEMP "install-codex-desktop.ps1"
Invoke-WebRequest `
-UseBasicParsing `
-Uri "https://github.com/Nuclear2/cmo-agent-bridge/releases/download/v0.8.0/install-codex-desktop.ps1" `
-OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer
```
脚本会把本地插件源加入 **Plugins → Personal**，不需要 Codex CLI。完全退出并重启 Desktop，
然后在 **Personal** 中打开 `cmo-agent-bridge` 并点击安装。插件运行 MCP 时仍需要第 1 步安装的
`uv` / `uvx`。
#### 有 Codex CLI
```powershell
codex plugin marketplace add Nuclear2/cmo-agent-bridge --ref stable
codex plugin add cmo-agent-bridge@cmo-tools
```
第二条命令也可以改为在 Codex 中打开 `/plugins`，从 **CMO Tools** 安装
`cmo-agent-bridge`。远程自建 marketplace 不会自动出现在官方插件目录中，必须先执行第一条命令。
`stable` 只会在 Release 完整发布后推进；Codex 启动时会自动检查更新，也可以运行
`codex plugin marketplace upgrade cmo-tools` 立即刷新。
#### Claude Code
```powershell
claude plugin marketplace add Nuclear2/cmo-agent-bridge@stable
claude plugin install cmo-agent-bridge@cmo-tools --scope user
```
Claude Code 默认关闭第三方 marketplace 的自动更新。安装后可在 `/plugin` → **Marketplaces** →
`cmo-tools` 中启用 auto-update；也可以手动运行
`claude plugin update cmo-agent-bridge@cmo-tools --scope user`。执行 `/reload-plugins` 或新建会话
即可载入。Codex 和 Claude 的 plugin 都同时包含 MCP 配置和完整的 `operate-cmo` Skill。
OpenCode、Cursor、Qoder 和通用 MCP 客户端的配置见[各框架安装](docs/frameworks/README.md)。这些
框架必须同时注册本地 `stdio` MCP Server，并安装完整的 `operate-cmo` Skill；MCP 协议本身不会
携带 Skill。
### 3. 部署 CMO 侧运行时
重启 Agent 并新建任务，然后直接告诉它：
> 调用 `cmo_bridge_diagnose` 检查当前安装；如果还没准备好，用
> `D:\Program Files (x86)\Steam\steamapps\common\Command - Modern Operations` 作为
> `game_root` 调用 `cmo_bridge_prepare`。
`cmo_bridge_prepare` 会部署与插件版本匹配的 Lua runtime，并让当前 MCP 会话里的普通工具立即
可用，不需要再次重启。CMO 安装在其他位置时，把提示中的路径换成实际路径即可。CLI 只作为
[安装与故障排查](docs/installation.md)时的备用入口。
插件仍固定使用同版本 wheel：
```powershell
$wheel = "https://github.com/Nuclear2/cmo-agent-bridge/releases/download/v0.8.0/cmo_agent_bridge-0.8.0-py3-none-any.whl"
```
升级已有安装时，先用旧/当前版本确认 `cmo_queue_status` 中 `queued=0`、`active=0`，并让 worker
完成 pending journal 收敛，再升级 plugin/wheel 和运行 `prepare`。v0.7.3 起，`prepare` 会安全终结
旧版遗留、不会改变想定的 `status`/`read` 孤立记录；真正可能改变想定的未决证据仍会返回
`STATE_CONFLICT`。此时查看 `active_barriers` 和错误明细，不要手工删除或伪造 journal。详见
[升级门槛](docs/installation.md#升级与-prepare-的安全门槛)。
### 4. 在编辑器中挂好两个桥接事件
首次接入、两个事件都没有的想定，先运行 `prepare` 部署脚本，再由玩家在推演开始前打开想定编辑器，分别创建以下两个 event，
均设为已启用、概率 100%、无条件，不混入计分或其他玩法动作。
命令轮询 event（**Repeatable / 可重复**）：
1. 添加 **Regular Time** trigger，间隔设为 1 秒；
2. 添加 **Lua Script** action，内容为：
```lua
return ScenEdit_RunScript('CMOAgentBridge/inbox/request.lua')
```
3. 把这组 trigger 和 action 关联到命令轮询 event。
结束记录 event（**不勾选 Repeatable / 只执行一次**）：
1. 添加 **Scenario Ends / ScenEnded** trigger；
2. 添加另一条 **Lua Script** action，内容为：
```lua
return ScenEdit_RunScript('CMOAgentBridge/on_scenario_ended.lua')
```
3. 把这一组 trigger 和 action 关联到结束记录 event。需要保留配置时，由玩家另存想定副本。
已有命令轮询的想定可以直接连接：Agent 会在连接成功后的首次态势读取窗口内检查、补挂结束记录
事件；玩家已确认两个事件都挂好时，就跳过检查。这个过程依赖时间流动，但不会为检查单独反复
释放、暂停时间，也不会自动保存想定。只读任务不补挂。原有连接诊断和故障恢复流程不变。
`prepare` 本身只部署文件，不创建想定事件。
两个 trigger 不要合到同一个 event，也不要在推演途中手动运行结束记录 action。
完整说明见[安装文档](docs/installation.md)。
事件随想定保存后，普通推演模式也可以直接使用 bridge。Regular Time 会在想定时间流动时处理请求。
如果想定已经暂停，Agent 可以用 `cmo_simulation_pulse(handshake=true)` 以 1x 短暂释放时间，完成
首次握手后尝试重新暂停并恢复原倍率，不需要玩家手动配合。调用方必须检查返回的
`final_pause_verified` 和 `prior_rate_restored`，不能把恢复动作当作无条件保证。已建立 session binding 后，也可以在
暂停期间先排入普通写操作，再用同一工具等待队列中的未完成请求生效。
### 5. 确认连接
保持 CMO 和目标想定打开，告诉 Agent：
> 先调用 `cmo_time_get_state`。如果想定正在运行，直接调用 `cmo_bridge_status`；如果已经暂停，调用
> `cmo_simulation_pulse` 并设置 `handshake=true`。告诉我当前 CMO build、runtime tag 和想定 lineage。
返回成功结果，说明 CMO 侧已经接通。暂停时的 handshake pulse 会短暂推进想定并尝试复停；只有
`final_pause_verified=true` 才能确认最后确实恢复了暂停。如果
仍然超时，检查轮询 event 是否启用且允许重复。如果 Agent 中没有出现 `cmo_*` 工具，检查插件与
`uvx` 后重启 Agent 并新建任务。
## 大型想定的态势读取
开局或阶段性重评估时，Agent 默认按下面的顺序读取己方兵力：
1. `cmo_unit_catalog` 快速建立 GUID、名称和单位类型目录；
2. `cmo_unit_overview` 分页读取 CMO 自己生成的原生概览，先看编成、位置和粗略状态；
3. `cmo_unit_operational_status_batch` 及现有的战备、载荷、库存工具，只深读与当前决策有关的单位。
旧的 `cmo_unit_list` 仍为兼容保留，但不会再作为大型想定战前评估的默认入口。Lua-backed 读取按顺序
执行，不并发堆叠；如果某次读取卡住或超时，Agent 会先检查 CMO 是否暂停，再决定使用已有快照、短暂
释放时间刷新，或修复轮询，而不是原样重试。
## 写操作与暂停
v0.2.0 会把普通写操作先持久化到本地 FIFO 队列，工具立即返回
`QueuedOperationReceipt`。用回执中的 `request_id` 调用 `cmo_request_get` 或
`cmo_request_wait` 取得最终结果；`cmo_request_wait` 自己超时不会取消请求。
CMO 暂停时，已经提交的写操作会一直保留，恢复时间流动后按提交顺序执行。此时仍可在本机使用
`cmo_request_get`、`cmo_request_list`、`cmo_queue_status`，并用 `cmo_request_cancel` 取消尚未进入
执行阶段的 `queued` 请求。已经 `active` 的请求不能撤销，关闭 Agent 或 MCP 也不会取消它；下次启动
会继续核对和恢复。若 CMO 进程或想定已经变化，bridge 会拒绝或隔离旧请求，不会把它带到新想定。
互不依赖的修改可以连续提交，由队列保持顺序。后一步需要前一步返回的 GUID（例如先创建任务、
再分配单位）时，必须先等待创建请求 `completed` 并从结果中取到 GUID。读取工具仍然同步依赖 CMO
轮询；handshake pulse 只负责连接状态检查。暂停期间若还需要刷新其他态势，应先用
`cmo_time_set` 以 1x 运行，完成读取后再暂停。需要让已排队请求立即生效时，先用
`cmo_request_list(states=["queued", "active"], limit=null)` 取全量未完成请求，或以相同筛选翻完全部页，
再把当前所有 `queued` 或 `active` 请求的 `request_id` 一并交给
`cmo_simulation_pulse`。如果遗漏任何非终态请求，pulse 会在释放时间前拒绝执行，避免意外推进
未选中的 FIFO 工作。调用前还要确认 `cmo_queue_status.barrier_active=false`；已有未决隔离时不会
释放时间，运行中出现未决隔离时会立即结束等待并尝试恢复暂停和原倍率，而不是耗尽 timeout。
恢复结果由 `final_pause_verified` 与 `prior_rate_restored` 明确报告；任一核验失败都必须作为需要
人工确认 UI 状态的可恢复故障处理。只有全部指定请求都进入 `completed` 且握手成功（如有）时，
pulse 才会返回成功。
原生消息日志是另一条完全只读的主机侧路径。建立想定 session 和玩家阵营后，Agent 会先调用
`cmo_message_log_status`，再用
`cmo_message_log_read(side_name=<己方精确名称>, start="now")` 从当前文件尾建立游标，以后只读取新增的
己方消息，以及 CMO 对玩家可见但未附阵营前缀的全部信息，包括武器终端、干扰、诱饵和系统记录；这在
CMO 暂停时也有效。无前缀信息沿用现有 JSON 条目结构，在 `text` 中返回原有纯文本投影并以
`side_name=null` 标识，不增加额外分类字段；需结合己方单位、接触目标和武器分配再判断双方身份。
`HIT` 只能证明命中，不能单独证明毁伤、击毁或战果归属。只有丢失游标或首次接手时需要追溯已发生消息的显式恢复才使用
`start="recent"`，因为同一个 CMO 进程的日志文件可能包含之前加载过的想定内容。bridge 不会调用
`SetScenarioMessageLogPath`，也不会接管或搬走游戏自己的日志。
正在运行、只需改变倍率时，优先使用已有的 `cmo_scenario_time_compression_set(code=...)` Lua 队列
工具，保留回执并等待 `completed`；它不能释放已暂停的想定。暂停、恢复及明确需要立即核验的 UI
操作使用以下主机侧工具：
- `cmo_time_get_state` 读取暂停/运行状态和当前倍率；
- `cmo_time_set` 幂等地暂停、恢复或选择倍率；`rate_code` 从 `0` 到 `5` 分别表示 1x、2x、5x、
15x，以及两档粗粒度火焰模式。最高档按五秒粗粒度推进，实际速度取决于机器性能，不是固定倍率；
- `cmo_simulation_pulse` 只用于已经暂停的想定。它以 1x 短暂放行，等待已列出的全部非终态
durable request 和/或握手完成，然后尝试重新暂停并恢复原倍率；调用方必须核对
`final_pause_verified` 与 `prior_rate_restored`。未决隔离会提前终止等待，`rejected`、
`cancelled` 或 `quarantined` 不算成功；超时不会取消或重复提交请求。
`cmo_time_get_state` 和 `cmo_time_set` 的 UI 状态读取/操作不依赖 Lua 轮询；pulse 的暂停与释放动作
也在主机侧完成，但要让握手或队列请求进入终态，想定中的 Regular Time 轮询事件仍必须
正常工作。
CMO 不需要预先切到前台。时间控制使用语义 Windows UI Automation，不注入全局键盘、鼠标或
屏幕坐标。CMO/WPF 在按钮调用时仍可能短暂切到前台；bridge 会尽力恢复调用前的前台窗口，
但不承诺全程无感。多实例、无法访问的 UI 或阻塞主窗口的 modal 对话框都会使工具拒绝操作。
正常推演默认保持当前倍率，普通命令直接入队或执行，不必暂停，也不必例行降到 1x。只有想定开局
制定全局计划、阶段目标完成后的重新部署或其他复杂规划，才应由 Agent 评估后暂停；有一定时效风险
但不需要完整停表时，可以临时降到 1x，完成后恢复原倍率。pulse 仍会让想定时间短暂前进，bridge
不支持在完全冻结的游戏时间内执行 Regular Time 轮询，也不提供“零时间单步”。
## 结束后的报告
想定自然到时或由事件结束后，先调用主机只读工具 `cmo_scenario_end_report_get()`。它读取与当前
握手场次匹配的结束事件快照，不依赖 Regular Time，不恢复时间，也不会重放队列。
结果是 `available`、`partial` 或 `unavailable`；它绑定最后一次成功握手，**不实时验证当前加载的
想定**。不要为了读结束报告再握手；换想定后则按正常接入流程建立新场次绑定。
`finality=scenario_end_event_snapshot` 表示结束记录 action 执行时的数据；不保证其他结束动作的
加分或损失变更已经全部完成。结束原因没有证据时保持 unknown/null，旧的战损读取或暂停状态也不能
替代结束证明。若没有匹配记录，工具明确返回 unavailable，不把开局文件或预结束缓存充作最终报告。
Build 1868 实测中，自然到时会先显示 **Scenario End** 通知，点 **OK** 后才执行结束记录事件。
如果通知还开着、报告暂不可用，先请玩家确认这条结束通知，再读取报告；不要恢复时间或反复重试。
插件不会自动关闭弹窗。
需要精确最终评价时，应与 CMO 的 Player Evaluation 核对，并注明证据边界。
## 推演、想定制作与测试
Skill 会根据工作内容采用不同的信息范围：
| 模式 | 信息范围 | 适用工作 |
|---|---|---|
| `LIVE_PLAYER` | 己方状态和己方观察到的 contacts | 正常推演、部署、交战与保障 |
| `SCENARIO_AUTHOR` | 完整想定状态 | 制作或修改想定、事件、兵力与计分 |
| `UMPIRE` | 获准裁决范围内的完整状态 | 测试、注入、诊断和裁决 |
日常推演使用 `LIVE_PLAYER`；制作想定或进行测试裁决时，再切换到相应模式。这样既能让 Agent
充分利用编辑器能力，也能保留正常推演中的情报不确定性。
## 工作原理
```text
Agent ── stdio / MCP ──> cmo-bridge ── 本机文件桥 ──> CMO Lua 事件
└── 只读 ──> CMO 原生 Logs
```
- **MCP Server** 提供有类型的 `cmo_*` 工具，负责主机准备、诊断、时间控制、原生消息日志、持久写队列以及读取和修改 CMO 状态；
- **operate-cmo Skill** 提供态势评估、作战规划、执行检查和想定制作流程；
- **CLI** 用于安装运行时、诊断连接和人工测试；`submit` 只持久化请求，`request-wait` 才会在
没有 MCP server 时启动一个前台 worker；
- **Plugin** 为 Codex 和 Claude Code 打包 MCP 配置与 Skill，其他框架可以直接注册标准
`stdio` MCP Server。
bridge 以本地 `stdio` 进程运行。Agent、Python 进程和 CMO Lua 运行时通过本机文件交换请求与
结果；本地 SQLite 保存 session binding 和持久 FIFO 写队列，支持暂停等待与重启恢复。
## 文档
- [快速上手](docs/quickstart.md)
- [安装、升级与卸载](docs/installation.md)
- [各 Agent 框架配置](docs/frameworks/README.md)
- [变更记录](CHANGELOG.md)
- [安全说明](SECURITY.md)
- [参与贡献](CONTRIBUTING.md)
- [CMO 官方 Lua API](https://commandlua.github.io/)
## 项目状态
- 当前版本：[`v0.8.0 Preview`](https://github.com/Nuclear2/cmo-agent-bridge/releases/tag/v0.8.0)
- 已验证环境：Windows 10/11、CMO Build 1868
- Python：3.12，由 `uv` 隔离管理
- 许可证：[MIT](LICENSE)
这是一个非官方社区项目，与 WarfareSims、Matrix Games、Slitherine 或 CMO 的开发商、发行商
没有隶属关系。Agent 的操作会直接修改当前想定，首次使用前请保存副本；脚本执行等详细注意事项见
[安全说明](SECURITY.md)。
插件和 Skill 中的 CMO 图标取自游戏随附的 `Command.ico`；相关权利归原权利人所有，不受本项目
MIT 许可证覆盖。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessUnresponsive