mcdk-mcp-game-testing-workflow

MCP 游戏测试工作流 Skill

适用场景

当用户希望使用 MCDK-MCP 对网易 Minecraft 基岩版 Addon、Python2 Mod、UI、玩法逻辑或资源效果进行测试、回归验证、日志分析时，使用本 Skill。

本 Skill 的核心判断是：不要默认让通用 Agent 仅依赖纯 LLM、截图和点击完成复杂游戏测试。优先要求或创建代码内测试入口，再通过 MCP Tool 调用测试入口；高版本 execute_code 已支持直接返回被执行代码的 return 结果，应优先读取返回值完成判定，仅在返回值缺失、异常、与预期不符或需要排查副作用时再拉取日志。

工作原则

1. 优先测试入口，不优先盲目操作游戏画面。
2. 优先 execute_code 返回值、结构化状态、错误日志，不优先截图。
3. 优先短链路、可复现测试函数，不优先长链路自由探索。
4. 优先多轮统计，不把单次偶然结果当结论。
5. 代码执行字符串应尽量短，只负责调用已存在的测试函数并返回结果。
6. 优先维护项目内测试函数，让测试能力随项目长期演进，而不是只写一次性 MCP 临时代码。

标准流程

1. 识别项目与目标

• 确认用户要验证的具体功能点。
• 定位客户端 / 服务端 / UI / 资源 / Shader / 纯逻辑等测试类型。
• 查找是否已有测试函数、诊断模块、debug 命令、稳定返回结构或稳定日志前缀。
• 如果没有测试入口，优先建议或实现一个只在开发环境启用的测试入口。
• 如果项目需要长期维护或后续回归，优先把测试函数保留在项目中，而不是仅通过一次性 MCP 代码片段完成验证。

2. 设计可维护测试入口

测试入口应满足：

• 可由 MCP execute_code 调用；
• 函数名、注释、docstring / 文档必须明确标注这是测试函数，例如 mcdk_test_*、debug_test_*、run_mcdk_self_test，避免被误认为正式业务入口；
• 放在诊断、测试、debug、自检等独立模块中，并与正式逻辑隔离；
• 仅在开发环境、调试配置或显式调用时启用，避免发布环境默认执行；
• 初始化固定测试场景；
• 触发一个明确目标行为；
• 优先 return 结构化结果，包含 case、ok、duration_ms、stage、error、metrics 等字段；
• 能在失败时返回可诊断信息；
• 必要时输出 [MCDK_TEST] 前缀的结构化日志作为辅助诊断，而不是作为默认唯一结果来源；
• 尽可能清理测试状态，避免污染后续用例。

推荐返回值示例：

return {"case": "case_name", "ok": True, "duration_ms": 12, "metrics": {"count": 1}}

可选日志示例：

[MCDK_TEST] {"case":"case_name","ok":true,"duration_ms":12,"metrics":{"count":1}}

3. 通过 MCP 执行

优先使用以下 Tool 顺序：

1. get_latest_error_logs：读取错误日志基线，便于之后判断是否产生新异常；
2. execute_code：执行客户端或服务端测试入口，并优先读取其直接返回的 return 结果；
3. 解析 execute_code 返回值：如果返回结构完整且符合预期，可直接进入统计与结论；
4. get_latest_error_logs：当返回值表示失败、执行异常、结果不符合预期，或需要确认是否有隐藏异常时使用；
5. get_latest_logs 或 get_log_range：仅在返回值缺失、日志本身是测试目标、需要分析 [MCDK_TEST] 辅助日志，或发生预期外情况时使用；
6. capture_game_window：仅在日志 / 返回值不足以判定视觉结果时使用；
7. mc_input：仅在测试入口无法覆盖且用户明确需要交互时使用；先 /help 了解步骤与参数，必要时 /state 确认指针是否被游戏独占；一次调用用 /run 提交整串操作，其成功只代表输入已投递，仍需截图或日志确认结果；使用 leave_held 后必须以 /release-all 收尾；
8. reload_game：仅在热更新或资源刷新不足时使用；资源级重载传入 reload_addons=true。