mcdevtool

name	mcdevtool
description	当用户希望使用 MCDK-MCP 对网易 Minecraft 基岩版 Addon、Python2 Mod、UI、玩法逻辑或资源效果进行测试、回归验证、日志分析时，使用本 Skill。 Use when this capability is needed.
metadata	{"author":"GitHub-Zero123"}

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. click_game_window：仅在测试入口无法覆盖且用户明确需要交互时使用；
8. reload_game / reload_addon_and_game：仅在热更新或资源刷新不足时使用。

4. 统计与结论

• 优先对 execute_code 返回的结构化结果做解析。
• 只有在需要辅助诊断时，再对 [MCDK_TEST] 日志做解析。
• 多轮执行时统计成功率、耗时、异常类型、失败阶段。
• 区分“测试入口失败”“业务断言失败”“MCP 连接失败”“游戏未启动 / 未启用 MCP”“返回值缺失 / 结构异常”。
• 输出结论时附带可复现步骤，而不是只描述画面观察。

维护方案

为了方便项目维护，允许并鼓励在项目内编写一组由 AI 自行调用的测试函数，用于自检和回归验证：

• 测试函数应有稳定、可搜索的命名，例如 mcdk_test_*、run_mcdk_self_test、debug_test_*。
• 函数注释、docstring 或模块文档必须明确写明“这是测试函数 / 自检函数，仅供 MCP、AI 或开发调试调用”。
• 测试函数应尽量只编排场景、调用正式业务 API、断言结果，不复制正式业务逻辑。
• 测试函数应返回结构化字典 / JSON 兼容对象，便于 execute_code 直接返回和解析。
• 测试函数应支持按 case、参数或配置执行单个用例，避免每次运行全部长耗时测试。
• 测试函数应清理临时实体、UI 状态、计时器、全局变量、缓存和事件监听，避免影响玩家实际存档或后续测试。
• 如果测试函数需要保留在发布包内，必须保证默认不自动运行，且不会暴露危险操作。
• 当修复 bug 或新增玩法机制时，优先同步补充对应测试函数，以便后续 AI 能直接调用自检。

决策规则

• 如果用户要求“自动测试游戏功能”，先寻找或补充测试函数，再调用 MCP。
• 如果用户要求“看一下效果”，也应先读取 execute_code 返回值或错误日志；只有视觉效果本身是目标时才截图。
• 如果 MCP 不可用，提示用户需要通过 MCDK 启动游戏并启用 mcp_server_config.enabled。
• 如果需要执行代码，优先调用项目内已命名测试函数，并直接 return 其结果，避免在 MCP 临时代码中堆叠复杂业务逻辑。
• 如果 execute_code 返回值已经完整、可信、符合预期，不要为了惯性再拉取普通日志；仅在失败、异常、返回值不完整、需要排查副作用或用户明确要求日志证据时拉取。
• 如果测试需要修改项目文件，应保持测试入口与正式逻辑隔离，并避免发布环境默认启用。

输出格式建议

完成 MCP 测试后，按以下结构回复：

1. 测试目标：验证了什么。
2. 执行方式：调用了哪些测试入口和 MCP Tool。
3. 返回值摘要：列出关键 execute_code 结构化返回结果。
4. 日志摘要：仅在拉取日志时列出关键 [MCDK_TEST] 或错误日志结果。
5. 统计结果：成功率、耗时、异常分布。
6. 结论：通过 / 不通过 / 无法判定。
7. 后续动作：如果失败，给出最小复现与建议修复点；如果适合长期维护，说明建议保留或新增的项目内测试函数。

禁止倾向

• 不要把复杂玩法验证简化成“截图看起来正常”。
• 不要长期循环点击或截图而没有明确停止条件。
• 不要忽略错误日志，但也不要在 execute_code 返回值已经足够时机械拉取普通日志。
• 不要在没有结构化返回值或结构化输出的情况下声称回归测试稳定通过。
• 不要把 MCP 代码执行当成临时堆业务逻辑的地方；它应主要调用项目内测试函数。
• 不要编写名称、注释、docstring 不清晰的“隐藏测试函数”，以免后续维护者误删或误用。

---

Source: GitHub-Zero123/MCDevTool — distributed by TomeVault.