⚡

Godot真实窗口验收Skill godot-real-window-acceptance

用于在 Godot 4 游戏或 UI 变更中执行真实窗口验收,区分无头测试、调试面板与玩家实际体验,记录窗口截图、PID、标题、尺寸、状态变更和人工验收卡,避免把测试通过或调试截图误称为可玩。关键词:Godot 4、真实窗口验收、游戏UI测试、玩家验收、窗口截图、证据链、人工验收、调试面板隔离、Windows PrintWindow、可玩性验证。

游戏开发 0 次安装 4 次浏览 更新于 11/20/2026
名称 godot-real-window-acceptance
描述 在真实窗口中验证 Godot 4 游戏或 UI 变更。当任务需要证明玩家能够看到、点击并获得真实结果时使用;当无头测试或调试截图被误认为玩家验收时使用;当需要将玩家 UI 与内部调试工具分离时使用。涵盖 Windows 窗口捕获、证据层级和人工验收卡。
开源协议 MIT

Godot 真实窗口验收

一套实用工作流,用于证明 Godot 变更确实可用,而不仅仅是存在于代码、测试或调试控制台中。

本技能刻意聚焦于证据与验收,而非编辑器自动化。如果智能体能够驱动编辑器,请将其与 Godot MCP/工具技能配合使用;本技能定义必须证明什么,以及不得声称什么。

使用本技能的场景

  • 仅凭无头测试就将某项变更称为“可玩”“完成”“已修复”或“可见”。
  • 必须在 1600×900(或其他明确尺寸)的真实窗口中检查 UI 变更。
  • 调试工具与玩家 UI 被混淆。
  • 在没有 PID、标题、时间戳或内容检查的情况下接受截图。
  • 需要真人执行一段简短验收路径并记录真实摩擦。
  • 上一个候选版本已通过,而新提交必须独立证明。

不要将其用于没有可见/UI 表面的纯逻辑工作。那类工作应使用普通单元测试。

不可妥协的规则

  1. 无头测试证明逻辑,不证明玩家体验。 绿色测试套件是必要条件,但绝不是“可玩”的充分条件。
  2. 玩家入口不得是调试控制台。 将调试工具放在显式标志之后(例如 --debug-ui),并清晰标注(例如 PROJECT DEBUG / NOT PLAYER UI)。如果默认入口仍打开调试视图,则 UI 任务未完成。
  3. 机器证据与人工验收是分开的行。 自动输入、截图和脚本点击可以证明路径存在,但不能证明真人理解并完成了该路径。
  4. 捕获实际游戏窗口。 记录进程 ID、窗口标题和可执行文件。在 Windows 上,使用窗口原生捕获,例如 PrintWindow;桌面捕获可能显示锁屏、壁纸、覆盖层或另一个窗口,而不是游戏。没有窗口身份信息的截图不是证据。
  5. 一个候选版本,一个槽位。 冻结提交/哈希和用户数据目录。绝不混用旧窗口、其他分支或其他存档的截图或日志。
  6. 诚实状态胜过漂亮数字。 未知、过期、待定或缺失数据必须显示为未知并给出原因。绝不要将其渲染为 0、正常 或成功。
  7. 不得用固定装置、自点击或页面切换冒充人工验收。 如果真人没有执行该路径,结果保持“待定”或“受阻”。
  8. 明确窗口尺寸。 使用产品真实尺寸(例如 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 — 具体的假通过模式及替代做法。