oni-mcp-testing

name	oni-mcp-testing
description	当用户要求测试、验证或审计 ONI MCP 服务器功能、连接状态、工具可用性，或评估 MCP 操作体验和易用性时使用。指导 agent 执行系统化的功能测试流程，覆盖连接、查询、地图、建造、相机、订单等核心能力，并生成测试报告。

ONI MCP 功能测试

何时使用

• 用户说「测试 MCP」、「看看 MCP 好不好用」、「验证连接」
• 用户要求审计 ONI MCP 服务器状态、工具覆盖或操作体验
• 新环境/新存档首次连接后，快速验证 MCP 是否正常工作
• 排查 MCP 工具调用失败、数据异常或行为不符合预期

测试原则

• 只读优先：前两个阶段全部使用只读工具，不修改游戏状态
• dryRun 先行：所有写/执行操作必须先 dryRun，确认通过再执行
• 最小侵入：实际建造/挖掘测试选择影响最小的位置和规模
• 重点倾斜：适当精简基础工具测试，重点考核「地图易于理解性」和「规划难度」

测试流程

阶段 1: 连接与基础状态（只读）

验证服务器连接和游戏基本状态：

server_control domain=diagnostics action=status → 服务器加载状态、端口、工具数量
game_control domain=speed action=time                  → 游戏时间、周期、暂停状态
colony_control domain=snapshot action=get      → 殖民地完整快照（替代 6 个独立调用）

检查项：

• server_control domain=diagnostics action=status 返回的 loaded 为 true
• toolCount 为核心公开工具数量，正常应为 8
• game_control domain=speed action=time 返回有效周期和时间
• colony_control domain=snapshot action=get 返回复制人、食物、建筑、研究、告警

阶段 2: 关键信息查询（只读，精简版）

并行测试对规划决策最关键的信息工具，跳过非核心查询：

read_control domain=infrastructure action=power_summary includeDetails=true   → 重点检测未接入电路的设备
dupes_control domain=info action=status_check → 复制人导航可达性、被困风险
building_control domain=planning action=search_defs query=厕所     → 中文查询 + 材料可用性

检查项：

• read_control domain=infrastructure action=power_summary 发现未连接设备（如 circuitId=-1）为加分项
• dupes_control domain=info action=status_check 无被困风险，导航样本合理
• building_control domain=planning action=search_defs 中文关键词可用，返回 placement.anchor 规则

阶段 3: 地图易于理解性（只读，重点）

这是测试核心。重点验证地图输出是否真正「可读、可规划、可决策」：

read_control domain=world action=text_map
  view=base, includeBuildings=true, includeItems=true, format=markdown
  → 测试连续区段地图的可读性、图例完整性、对象标注精度

read_control domain=world action=text_map
  view=temperature, format=markdown
  → 测试温度视图是否能快速识别 hot/mild/cold 区域

read_control domain=world action=area_snapshot
  preset=utilities, overlays=[power,gas_conduits,liquid_conduits,logic]
  compact=true
  → 测试多 overlay 信息密度、紧凑模式实用性、冲突诊断输出

检查项（地图可读性）：

• 连续区段式地图比像素网格更易读，行列坐标清晰
• 图例覆盖 bld/dup/itm/tile/sol/bp/bp_a 等全部标记
• 对象列表含 anchor/footprint/size，多格建筑边界明确
• 温度视图按区段标注 hot/mild/cold，无大面积混淆
• compact=true 下对象表省略空字段，信息密度高但不丢失关键数据

检查项（诊断价值）：

• 自动检测 unsupported 建筑（缺失支撑格坐标列出）
• 自动检测 overlap 冲突（列出具体冲突对象，如 tile@x,y 或 building:Door@x,y）
• 电力 overlay 正确区分 w(电线) / p(电力设备) / .(空)
• 逻辑 overlay 为空时简洁输出，不冗余

阶段 4: 规划难度（dryRun + 分析，重点）

测试 MCP 是否能有效降低殖民地规划的认知负担：

read_control domain=world action=layout_candidates purpose=barracks limit=5
  → 评分、分类、需挖掘/铺砖量、危险格、可达性

read_control domain=world action=layout_candidates purpose=bathroom limit=5
  → 不同用途的候选推荐是否差异化

building_control domain=planning action=preview prefabId=Outhouse x=... y=... dryRun=true
  → 应拒绝 raw coordinates，并提示使用 operation-file 路由

world_editor command=read path=/active/ops/tools.md
  → 只选择当前公开 typed files/tools，忽略 hidden coordinate_control 和 /active/ops/coordinate.md

world_editor command=read path=/active/map/viewport.md
  → 把目标空格 token 改为 `建筑名:优先级[#材料字]`，以外层 dryRun=true/confirm=false 预览

检查项（候选规划）：

• read_control domain=world action=layout_candidates 返回 score 和 scoreExplanation，扣分逻辑透明
• 候选分类（open_ready/mixed_platform 等）能帮助快速决策
• requiredDig/requiredTiles/existingSupportCells 量化改造工作量
• hazardCells 标注液体/危险元素坐标，避免盲目挖掘

检查项（建造预检复杂度）：

• 普通 building_control 对 raw x/y 返回明确拒绝和 operation-file 引导
• 地图 token edit dry-run 返回支撑、阻碍和 footprint 预检结果
• 默认单 SEARCH/REPLACE block；多 block 仅外层 allowPartial=true 允许且无法事务回滚
• operation file 每个 replacement 恰好一条可执行命令
• material=auto 自动选择当前星球可用材料

阶段 5: 批量与区域规划（dryRun / 轻量执行）

测试大范围规划的基础设施：

read_control domain=area action=define x1=... y1=... x2=... y2=... label=plan_zone
read_control domain=area action=blocks blockWidth=20 blockHeight=20 label=plan_blocks
read_control domain=area action=merge areaIds=[blk1,blk2]
  → 区域定义、切块、合并的连贯性

building_control domain=planning action=build_area prefabId=Tile anchors=[[x1,y1],[x2,y2],[x3,y3]] dryRun=true
  → 验证普通工具拒绝 raw anchors

world_editor command=read path=/active/ops/orders.md
  → 以 `挖 x1=... y1=... x2=... y2=... priority=7 dryRun=true` 验证精确矩形 dry-run 路由

orders_control domain=area action=dig areaId=... dryRun=true detail=true
orders_control domain=area action=sweep areaId=... dryRun=true detail=true
  → 区域级订单预览，检测风险与 previewToken 复用

检查项：

• read_control domain=area action=define / read_control domain=area action=blocks / read_control domain=area action=merge 生成的 areaId 可在后续工具复用
• 普通 building_control 对 raw anchors 拒绝，不残留部分蓝图
• dry-run 外层 edit 用 dryRun=true 且 confirm=false/省略；独立执行 edit 用 dryRun=false 且 confirm=true，内外标志不冲突
• orders_control domain=area action=dig 返回目标元素、质量、温度、风险列表
• previewToken 支持复用，避免重复扫描

阶段 6: 相机与视图控制（精简版）

合并为少量调用，验证可用即可：

navigation_control action=get_view
navigation_control action=focus_cell x=... y=...
navigation_control action=switch_view view=power screenshot=false
navigation_control action=coordinate_screenshot areaId=... focusCamera=true

检查项：

• 相机读取、格子聚焦、覆盖层切换和坐标截图正常

阶段 7: 批量调用与游戏控制（可选）

server_control domain=batch action=call_many responseMode=summary
  items:
    - { t: navigation_control, a: { action: get_view } }
    - { t: building_control, a: { domain: planning, action: search_defs, query: 梯子, limit: 3 } }

检查项：

• 批量调用成功，requireAllValid=true 正确工作

阶段 8: 实际建造验证（可选）

如果前 7 阶段全部通过，可选执行一次小规模建造验证：

world_editor command=read path=/active/map/viewport.md
# replace target empty tokens with Ladder:5 using outer dryRun=true and confirm=false/omitted
# after reviewing the preview, make a new edit with outer dryRun=false and confirm=true
read_control domain=world action=text_map x1=... y1=... x2=... y2=...
  → 验证直线建造后地图是否正确显示 bp 标记

规则：

• 只建造影响极小的建筑（如梯子）
• 优先使用地图 token edit dry-run 已验证通过的位置
• 建造后必须验证地图 bp / bp_a 标记
• 如果用户未明确要求，可以跳过此阶段

测试报告模板

每轮测试后返回简洁报告，重点评价「地图易于理解性」和「规划难度」：

## ONI MCP 测试报告

### 连接状态
| 项目 | 结果 |
|------|------|
| 服务器加载 | ✅/❌ |
| 工具数量 | N 个 |
| 游戏状态 | 第 X 周期，暂停/运行 |

### 功能测试结果
| 类别 | 状态 | 备注 |
|------|------|------|
| 基础查询 | ✅/❌ | |
| 地图可读性 | ✅/❌ | |
| 地图诊断价值 | ✅/❌ | unsupported/overlap/overlay |
| 规划候选质量 | ✅/❌ | read_control domain=world action=layout_candidates 评分与分类 |
| 建造预检复杂度 | ✅/❌ | 多格/支撑/阻碍检测 |
| 批量与区域 | ✅/❌ | 原子性、areaId 复用 |
| 相机/视图 | ✅/❌ | |
| 实际建造 | ✅/❌/跳过 | |

### 发现的问题
- （如有）

### 总体评价
| 维度 | 评分 | 说明 |
|------|------|------|
| 易用性 | ⭐x/5 | |
| 安全性 | ⭐x/5 | |
| 地图可读性 | ⭐x/5 | 连续区段、图例、overlay 清晰度 |
| 规划难度 | ⭐x/5 | 候选评分、预检诊断、批量原子性 |

常见问题排查

现象	可能原因	排查步骤
server_control domain=diagnostics action=status 返回 loaded=false	游戏未运行或模组未加载	确认游戏已启动，检查模组是否启用
工具调用返回 not found	工具名拼写错误或不在核心列表	使用 server_control domain=catalog action=search 查找正确工具名
普通 building_control preview 传 raw x/y	当前公开运行时拒绝 raw coordinates	将返回拒绝视为预期成功，改测 /active/map/viewport.md token dry-run
普通订单工具拒绝 raw coordinates	当前公开运行时要求 operation-file 路由	读 /active/ops/tools.md，忽略 hidden coordinate 入口，使用 /active/ops/orders.md
colony_control domain=snapshot action=get 告警未更新	建筑只是蓝图，未完工	蓝图不等于完工建筑；等复制人建造后重新读取
中文查询无结果	查询词不在本地化数据中	尝试英文关键词或 category 过滤
orders_control domain=area action=dig 风险提示不全	只检测明显风险，不保证全面	结合 read_control domain=world action=text_map 人工确认液体/高温/真空相邻
read_control domain=world action=layout_candidates 评分偏低	区域含大量危险格或需大量挖掘	检查 hazardCells 和 requiredDig，更换 purpose 或扩大区域

快速测试路径（压缩版）

如果时间有限，只测核心链路：

server_control domain=diagnostics action=status
game_control domain=speed action=time
colony_control domain=snapshot action=get profile=brief
read_control domain=world action=text_map x1=... y1=... x2=... y2=... format=markdown
read_control domain=world action=layout_candidates purpose=barracks limit=3
building_control domain=planning action=preview prefabId=Outhouse x=... y=... dryRun=true  # 应拒绝 raw coordinates
world_editor command=read path=/active/ops/tools.md
# only current public typed files/tools; ignore hidden coordinate_control and /active/ops/coordinate.md
world_editor command=read path=/active/map/viewport.md

8 个调用即可验证连接、查询、地图可读性、规划候选、raw-coordinate 拒绝和 map-edit 路由。