| 名称 | godot-real-window-acceptance |
| 描述 | 在真实窗口中验证 Godot 4 游戏或 UI 变更。当任务需要证明玩家能够看到、点击并获得真实结果时使用;当无头测试或调试截图被误认为玩家验收时使用;当需要将玩家 UI 与内部调试工具分离时使用。涵盖 Windows 窗口捕获、证据层级和人工验收卡。 |
| 开源协议 | MIT |
Godot 真实窗口验收
一套实用工作流,用于证明 Godot 变更确实可用,而不仅仅是存在于代码、测试或调试控制台中。
本技能刻意聚焦于证据与验收,而非编辑器自动化。如果智能体能够驱动编辑器,请将其与 Godot MCP/工具技能配合使用;本技能定义必须证明什么,以及不得声称什么。
使用本技能的场景
- 仅凭无头测试就将某项变更称为“可玩”“完成”“已修复”或“可见”。
- 必须在 1600×900(或其他明确尺寸)的真实窗口中检查 UI 变更。
- 调试工具与玩家 UI 被混淆。
- 在没有 PID、标题、时间戳或内容检查的情况下接受截图。
- 需要真人执行一段简短验收路径并记录真实摩擦。
- 上一个候选版本已通过,而新提交必须独立证明。
不要将其用于没有可见/UI 表面的纯逻辑工作。那类工作应使用普通单元测试。
不可妥协的规则
- 无头测试证明逻辑,不证明玩家体验。 绿色测试套件是必要条件,但绝不是“可玩”的充分条件。
- 玩家入口不得是调试控制台。 将调试工具放在显式标志之后(例如
--debug-ui),并清晰标注(例如PROJECT DEBUG / NOT PLAYER UI)。如果默认入口仍打开调试视图,则 UI 任务未完成。 - 机器证据与人工验收是分开的行。 自动输入、截图和脚本点击可以证明路径存在,但不能证明真人理解并完成了该路径。
- 捕获实际游戏窗口。 记录进程 ID、窗口标题和可执行文件。在 Windows 上,使用窗口原生捕获,例如
PrintWindow;桌面捕获可能显示锁屏、壁纸、覆盖层或另一个窗口,而不是游戏。没有窗口身份信息的截图不是证据。 - 一个候选版本,一个槽位。 冻结提交/哈希和用户数据目录。绝不混用旧窗口、其他分支或其他存档的截图或日志。
- 诚实状态胜过漂亮数字。 未知、过期、待定或缺失数据必须显示为未知并给出原因。绝不要将其渲染为
0、正常或成功。 - 不得用固定装置、自点击或页面切换冒充人工验收。 如果真人没有执行该路径,结果保持“待定”或“受阻”。
- 明确窗口尺寸。 使用产品真实尺寸(例如 1600×900),验证视口和操作系统窗口,并检查 DPI/HiDPI 行为。最大化或缩放后的窗口不是同等证据。
工作流
1. 冻结候选版本
- 记录提交哈希、构建命令、Godot 版本和启动命令。
- 使用干净的用户数据/存档目录,使过期存档无法掩盖失败。
- 用一句话说明受测的具体变更。
2. 运行无头门禁
- 运行项目的逻辑/回归测试套件。
- 记录原始摘要(套件、检查、失败、观察)。
- 将跳过、截断或未验证的输出视为限制,而不是通过。
3. 启动全新的真实窗口
- 先关闭旧游戏窗口。
- 只启动一个实例。
- 使用产品正常启动器和隔离的用户数据目录。
- 确认进程 ID、窗口标题、可执行文件和启动日志。
- 确认调试面板默认隐藏。
- 从日志或运行时探针确认视口/窗口尺寸。
4. 证明该窗口就是游戏
- 确认窗口标题是玩家标题,而不是调试标题。
- 捕获游戏窗口,而不是桌面。
- 检查截图:必须在预期尺寸下显示预期场景。如果黑屏、空白、0 字节,或显示锁屏/壁纸,停止并修复捕获路径。
- 记录截图哈希。
5. 执行一个真实循环
路径必须是:选择对象 → 执行合法玩家操作 → 命令进入模拟 → 发生真实事件/状态变化 → 玩家看到结果 → 同一世界继续运行。
记录:
- 选择了什么以及为什么;
- 执行了什么操作;
- 观察到的待定/中间/最终状态;
- 发生变化的真实状态/事件;
- 如果真人重复该操作会看到什么。
脚本可以为机器证据自动化此过程,但不能替代人工行。
6. 人工验收卡
使用带时间盒的简短卡片,例如 0–10、10–30 和 30–60 分钟。请真人记录:
- 是否找到对象和操作;
- 理解了什么;
- 误点击和困惑;
- 感觉等待过久的地方;
- 实际结果(成功/失败/拒绝)及原因;
- 是否愿意继续。
智能体可以准备卡片并启动窗口。智能体不得填写真人的观察或签名。
7. 结论
使用以下之一:
- 通过:本候选版本的机器门禁和人工路径均已完成;
- 需要改进:仍存在具体的可见/输入/结果问题;
- 受阻:人工路径无法完成,或证据无法关联到候选版本。
绝不要仅凭测试数量、调试截图或自动点击就写“可玩”。
证据包
保持证据包小而可归因:
candidate.txt 提交、构建、Godot 版本、启动命令
startup.log 启动行、场景、视口、窗口尺寸、调试状态
machine-summary.json 原始套件/检查数字、失败、观察
window-*.png 实际窗口截图 + SHA-256
human-card.md 真人自己的笔记,已填写或明确待定
如果截图无法关联到 PID/标题/候选版本,它就不是证据。
需要拒绝的失败模式
- 将带窗口标题的文本控制台当作玩家 UI。
- 锁屏桌面截图显示壁纸/黑屏;却被称作渲染缺陷或 UI 通过。
- 用“所有测试通过”作为验收结论。
- 脚本点击按钮,结果却被称为“玩家完成了它”。
- 将固定装置或预置测试世界展示为生产状态。
- 未知/过期值显示为零。
- 复用上一提交的旧截图/日志。
- 原型改名了,但同一调试面板仍是默认入口。
最小检查清单
- [ ] 已记录候选哈希和启动命令。
- [ ] 使用全新的隔离用户数据目录。
- [ ] 恰好一个游戏窗口。
- [ ] 已确认窗口标题/PID/尺寸。
- [ ] 调试面板默认隐藏。
- [ ] 玩家 UI 不是文本控制台。
- [ ] 已检查真实窗口截图,而不仅仅是生成截图。
- [ ] 完成一个真实循环并发生真实状态变化。
- [ ] 人工卡单独提供;不是由智能体填写。
- [ ] 结论为通过 / 需要改进 / 受阻,并附证据。
参考资料
references/evidence-hierarchy.md— 每种证据能证明什么、不能证明什么。references/windows-real-window.md— Windows 捕获、锁屏、DPI、窗口身份。references/acceptance-card.md— 可复用的人工验收卡。references/anti-patterns.md— 具体的假通过模式及替代做法。