| 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 个独立调用）
检查项：
阶段 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=厕所 → 中文查询 + 材料可用性
检查项：
阶段 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 信息密度、紧凑模式实用性、冲突诊断输出
检查项（地图可读性）：
检查项（诊断价值）：
阶段 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 预览
检查项（候选规划）：
检查项（建造预检复杂度）：
阶段 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 复用
检查项：
阶段 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 } }
检查项：
阶段 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 路由。
