CMO Agent Bridge

让 Codex、Claude Code、Cursor 等 Agent 直接读取和操作本机运行中的 **Command: Modern Operations（CMO）**想定。

平台支持：仅限 Windows。

下载 v0.8.0 · 快速上手 · 各框架安装 · CMO Lua API

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 模式，为这个想定添加一个进入区域后触发的增援事件，并检查触发器、 条件和动作是否关联正确。

它适合三类工作：

快速开始（Windows）

下面以 Steam 默认安装路径和 PowerShell 为例。完整的升级、卸载和自定义路径说明见 安装文档。

1. 安装 uv

bridge 由 uv 管理，在 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 安装脚本：

$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

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

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 客户端的配置见各框架安装。这些 框架必须同时注册本地 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 只作为 安装与故障排查时的备用入口。

插件仍固定使用同版本 wheel：

$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。详见 升级门槛。

4. 在编辑器中挂好两个桥接事件

首次接入、两个事件都没有的想定，先运行 prepare 部署脚本，再由玩家在推演开始前打开想定编辑器，分别创建以下两个 event， 均设为已启用、概率 100%、无条件，不混入计分或其他玩法动作。

命令轮询 event（Repeatable / 可重复）：

1. 添加 Regular Time trigger，间隔设为 1 秒；

2. 添加 Lua Script action，内容为：

return ScenEdit_RunScript('CMOAgentBridge/inbox/request.lua')

3. 把这组 trigger 和 action 关联到命令轮询 event。

结束记录 event（不勾选 Repeatable / 只执行一次）：

1. 添加 Scenario Ends / ScenEnded trigger；

2. 添加另一条 Lua Script action，内容为：

return ScenEdit_RunScript('CMOAgentBridge/on_scenario_ended.lua')

3. 把这一组 trigger 和 action 关联到结束记录 event。需要保留配置时，由玩家另存想定副本。

已有命令轮询的想定可以直接连接：Agent 会在连接成功后的首次态势读取窗口内检查、补挂结束记录 事件；玩家已确认两个事件都挂好时，就跳过检查。这个过程依赖时间流动，但不会为检查单独反复 释放、暂停时间，也不会自动保存想定。只读任务不补挂。原有连接诊断和故障恢复流程不变。 prepare 本身只部署文件，不创建想定事件。 两个 trigger 不要合到同一个 event，也不要在推演途中手动运行结束记录 action。 完整说明见安装文档。

事件随想定保存后，普通推演模式也可以直接使用 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；制作想定或进行测试裁决时，再切换到相应模式。这样既能让 Agent 充分利用编辑器能力，也能保留正常推演中的情报不确定性。

工作原理

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 写队列，支持暂停等待与重启恢复。

文档

• 快速上手

• 安装、升级与卸载

• 各 Agent 框架配置

• 变更记录

• 安全说明

• 参与贡献

• CMO 官方 Lua API

项目状态

• 当前版本：v0.8.0 Preview

• 已验证环境：Windows 10/11、CMO Build 1868

• Python：3.12，由 uv 隔离管理

• 许可证：MIT

这是一个非官方社区项目，与 WarfareSims、Matrix Games、Slitherine 或 CMO 的开发商、发行商 没有隶属关系。Agent 的操作会直接修改当前想定，首次使用前请保存副本；脚本执行等详细注意事项见 安全说明。 插件和 Skill 中的 CMO 图标取自游戏随附的 Command.ico；相关权利归原权利人所有，不受本项目 MIT 许可证覆盖。