技能使用指南

develop-web-game（网页游戏开发技能）Skill 是什么？

develop-web-game（网页游戏开发技能）是面向 HTML/JS 网页游戏的 AI 开发与测试闭环技能：小步改代码，用 Playwright 脚本模拟键鼠输入，检查截图、render_game_to_text 文本状态与控制台错误，配合 progress.md 记录进度。本文详解安装配置、工作流程、动作负载写法、竞品对比与常见问题，帮你把网页游戏真正调到能玩，现在就上手试试。

网页游戏开发技能Skill"develop-web-game"
9 个章节 约 16 分钟阅读 AI 智能生成

网页游戏开发技能：让 AI 用小步迭代 + Playwright 闭环测试，把网页游戏真正「调到能玩」

  • 它是什么：develop-web-game 是一个面向 HTML/JS 网页游戏的开发+测试闭环技能，作者 openai，技能 ID 为 12296。
  • 核心节奏：把每次迭代拆成「实现 → 行动 → 暂停 → 观察 → 调整」，每次只改一点，改完必须验证。
  • 验证手段：用基于 Playwright 的客户端脚本发送短输入爆发、抓截图、读 render_game_to_text 文本状态、缓冲控制台错误。
  • 关键约定：游戏需要暴露单个画布、window.render_game_to_text、window.advanceTime(ms) 三个集成点，否则自动化测试会不稳定。
  • 适用人群：用 Codex 做网页小游戏、Demo、教学案例的独立开发者、前端工程师与内容创作者。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：网页游戏开发技能 技能英文名：develop-web-game 技能 ID：12296 作者：openai

它解决的问题很具体：AI 帮你写网页游戏时，代码常常「能跑」但「不对」——画面元素没出现、跳跃穿墙、分数不更新、菜单点了没反应。原因不是模型不会写 JS，而是缺少一个可靠的验证回路。这个技能把「改一小步 → 用脚本真的去操作游戏 → 看截图和文本状态 → 查控制台报错 → 修」固化成流程，让每次改动都能被观察到、被确认。

安装思路与步骤

1）安装前提

  • 具备 Codex 环境，并且能读写技能目录；
  • 已安装 Node/npm，可用 npx；
  • Playwright 可用：优先使用项目已有的本地 playwright 依赖；不确定时先检查 npx（command -v npx >/dev/null 2>&1），如缺失则先装 Node/npm，再全局安装，例如 npm install -g @playwright/mcp@latest。

2）安装位置与路径配置

用户范围的技能统一安装在 $CODEX_HOME/skills 下（默认 ~/.codex/skills）。装好后按官方说明在终端配置一次路径（以下为技能详情中给出的真实配置）：

  • export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
  • export WEB_GAME_CLIENT="$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js"
  • export WEB_GAME_ACTIONS="$CODEX_HOME/skills/develop-web-game/references/action_payloads.json"

其中 WEB_GAME_CLIENT 是测试客户端脚本，WEB_GAME_ACTIONS 是示例动作负载参考文件。具体的「一键安装」命令入口以官方说明为准，不同平台与版本的安装方式可能不同。

3）验证是否生效

  • 用 ls 之类的方式确认上面两个路径下确实存在对应的脚本与参考文件；
  • 在项目里启动本地开发服务器（示例使用 http://localhost:5173），让游戏能通过浏览器访问；
  • 用技能详情中的示例命令跑一次，看是否产出截图、文本状态与控制台输出。
node "$WEB_GAME_CLIENT" --url http://localhost:5173 --actions-file "$WEB_GAME_ACTIONS" --click-selector "#start-btn" --iterations 3 --pause-ms 250

只要能看到「脚本成功连接页面 → 执行点击与按键 → 产出截图与状态文本」这条链路走通，就说明技能已生效。若命令报错，优先排查 Playwright 是否可用、端口是否与本地服务一致。

该技能的主要功能和特点

  • 小步迭代的工作方式：明确禁止「一次写一大坨再祈祷它能跑」。每次只挑一个功能或行为做最小改动，改完立刻进入验证环节，一次只变动一个变量（帧数、输入、计时、位置）。
  • Playwright 动作循环客户端：内置 web_game_playwright_client.js，提供虚拟时间步进、截图捕获、控制台错误缓冲三项能力，动作爆发可通过 --actions-file、--actions-json 或 --click / --click-selector 传入。
  • 动作负载参考库：action_payloads.json 提供键盘 + 鼠标的示例动作，按帧捕获，避免自己瞎猜按键字段名（如 left_mouse_button、right、space）。
  • 文本状态渲染约定：要求游戏暴露 window.render_game_to_text，返回简洁 JSON，涵盖模式、玩家坐标/半径、实体列表、分数等，做到「没有画面也能读懂局面」。
  • 确定性时间推进：要求暴露 window.advanceTime(ms)，让测试脚本能以固定步长推进帧，避免依赖真实时间导致测试抖动。
  • 截图即真相：强调必须真的打开最新截图肉眼检查，而不是只生成不看；如果屏幕上看不见，就等于实现里没有。
  • 测试检查列表：从主移动/交互、胜负过渡、分数/生命值变化、边界条件（碰撞、墙体、屏幕边缘）、菜单/暂停/开始流程，到特殊能力与计时器，逐项过一遍。
  • 跨会话进度沉淀：用 progress.md 记录原始提示（前缀 Original prompt:）、待办、笔记、坑点，让下一个代理能无缝接续，且不得覆盖原始提示。
  • 游戏呈现规范：偏好单个画布居中；屏幕文本最小化，操作说明放开始/菜单页而不是游戏过程中叠加；避免过暗场景；背景画在画布上而不是靠 CSS；用 f 切换全屏、Esc 退出并同步调整画布尺寸与输入映射。

和「随便开个浏览器点两下」的传统做法相比，它最大的差异是可重复、可观察、可回溯：动作是脚本化的，状态是结构化的，进度是文件化的。

如何使用该技能？

  1. 配置一次技能路径：执行上文三条 export，确保 CODEX_HOME、WEB_GAME_CLIENT、WEB_GAME_ACTIONS 指向正确位置。
  2. 准备 Playwright：项目里已有本地依赖就复用；不确定就先检查 npx，必要时全局安装 Playwright。除非明确要求，不要切换到 @playwright/test，坚持使用客户端脚本。
  3. 初始化进度文件：若 progress.md 不存在就创建，并在顶部写入 Original prompt: <你的原始需求>；若已存在，先读它，确认原始提示还在顶部，同时看上一个代理留下的待办与建议。
  4. 声明本次目标：用一句话定义这一轮只做什么，例如「让角色能左右移动并受重力落地」。
  5. 补齐集成点：保证只有一个画布，并暴露 window.render_game_to_text 与 window.advanceTime(ms)。文本状态示例结构：mode、player（x/y/r）、entities（各实体 x/y/r）、score，同时说明坐标系原点与轴方向。
  6. 做最小实现：只改推动目标前进的那部分代码。
  7. 写动作负载并运行脚本：动作可写成内联 JSON，例如：
{
  "steps": [
    { "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 120, "mouse_y": 80 },
    { "buttons": [], "frames": 6 },
    { "buttons": ["right"], "frames": 8 },
    { "buttons": ["space"], "frames": 4 }
  ]
}

然后执行上文示例命令，把 --url 换成自己的本地地址（示例为 http://localhost:5173），配合 --click-selector "#start-btn"、--iterations 3、--pause-ms 250 做起始操作与短爆发。

  1. 看三样东西：最新截图、最新 render_game_to_text 输出的 JSON 文本、控制台错误日志。先修第一个新出现的错误，再往下走。
  2. 端到端验证多步链路：按「原因 → 中间状态 → 结果」验证完整序列，例如射击命中后敌人生命值下降、生命值归零后消失并加分、拾取钥匙后门解锁并允许过关；同时确认文本状态与画面显示一致。
  3. 换场景前重置状态：验证另一个功能时避免沿用上一轮的残留状态。
  4. 小增量重跑：一次只调一个变量，重复第 7—10 步直到稳定；修复后要回归测试所有重要交互，确认没有引入新问题。
  5. 更新 progress.md：每次有意义的块工作后追加记录，结束时留给下一个代理待办与建议。

输出说明：脚本产出的是「截图 + 文本状态 + 控制台错误缓冲」三类工件；你的判断依据是它们，而不是代码看起来对不对。如果怀疑无头模式或 WebGL 捕获异常，用头模式重新跑脚本再检查。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
develop-web-game（本技能） 网页游戏的 AI 开发+测试闭环 Playwright 动作循环客户端、截图捕获、控制台错误缓冲、render_game_to_text 文本状态、advanceTime 确定性步进、progress.md 进度沉淀 需 Codex 环境、Node/npm、Playwright；需按约定暴露三个集成点 HTML/JS 小游戏迭代、AI 辅助调试、教学演示 优势：闭环完整、对 AI 友好、状态可读可回溯；不足：依赖游戏按约定暴露接口，通用业务站点不适用
手动浏览器调试（DevTools） 人工肉眼验收 打断点、看控制台、手动点击操作 门槛最低，零安装 快速看一两眼画面是否正常 优势：直观、自由；不足：不可重复、无法回归、状态难以结构化比对，AI 无法自主观察
@playwright/test 通用 E2E 框架 通用端到端自动化测试 用例组织、断言、报告、并行 需搭建测试工程与用例体系 业务系统回归测试、CI 集成 优势：工程化成熟；不足：对游戏画面与帧推进支持需自行封装，前期成本高，本技能明确建议不要切换过去
通用浏览器自动化 MCP（如 @playwright/mcp） 浏览器操作能力供给 打开页面、点击、截图等通用操作 全局安装即可用 网页抓取、表单流程、通用交互 优势：通用性强；不足：缺少为游戏定制的时间步进、状态文本约定与测试检查清单

该技能的典型应用场景与实际体验情况

场景一：独立开发者做网页小游戏 Demo 角色：想快速验证「这个玩法好不好玩」的个人开发者。痛点：玩法逻辑写完手上没有稳定验收手段，改一处坏一处。使用方式：把需求写进 progress.md 的 Original prompt:，按技能流程一次只加一个机制，每轮跑脚本抓截图确认。体验：上手不算难，难点在前期要老老实实补 render_game_to_text 和 advanceTime 两个钩子，补完之后迭代速度明显变快。

场景二：在已有 HTML/JS 游戏上做迭代与回归 角色：接手他人项目的工程师。痛点：不敢改，怕影响已有交互。使用方式：先读 progress.md 了解历史待办，改动后按测试检查列表逐项验证移动、跳跃、射击、菜单流程、边界碰撞，并确认没有回归。体验：检查列表是最大价值点，能显著减少「修好 A 坏了 B」；注意不同功能验证之间要重置场景状态。

场景三：需要确定性复现的问题排查 角色：遇到偶发 bug 的开发者。痛点：手动操作每次结果都不一样，无法稳定复现。使用方式：用内联动作 JSON 精确控制输入帧数与鼠标坐标，用 advanceTime(ms) 固定步长推进。体验：同样的动作序列能反复跑出同样的局面，定位效率高；若怀疑无头/WebGL 截图异常，切头模式重跑即可。

场景四：多轮/多代理接力开发 角色：把长任务拆给多个会话或代理的团队。使用方式：每轮结束更新 progress.md，保留原始提示、记录坑点、留下待办。体验：接续成本明显降低，但前提是每轮都真的写、真的读，否则文件会变成摆设。

总体体验与注意事项：上手难度中等偏上，收益随迭代轮次放大。最关键的一条纪律是「必须真的打开截图看」——只生成不检查等于没测。

该技能能为用户带来的价值

  • 把「写完」变成「验完」：每次改动都有截图、文本状态、控制台日志三类证据，减少「看起来能跑」的误判。
  • 显著降低调试成本：动作脚本可复用，问题可复现，避免反复手动点击；一次只改一个变量，能快速定位是哪次改动引入的问题。
  • 降低 AI 参与游戏开发的门槛：render_game_to_text 让模型不依赖视觉也能理解局面，advanceTime 让帧推进可控，二者共同把「AI 全自动调试游戏」变成现实。
  • 减少回归风险：测试检查列表覆盖主交互、胜负过渡、数值变化、边界条件与菜单流程，改动后逐项确认，避免局部修复引发全局问题。
  • 沉淀长期资产：progress.md 让项目上下文不随会话结束而丢失，多轮开发可以无缝接续。
  • 统一呈现规范：单画布居中、屏幕文本最小化、画布内绘制背景、f/Esc 全屏切换，让成品观感更接近可交付的 Demo。

常见问题 FAQ

Q1：这个技能怎么安装？ 先确认 Codex 环境与 Node/npm 可用，把技能装到 $CODEX_HOME/skills（默认 ~/.codex/skills），然后按技能详情配置 CODEX_HOME、WEB_GAME_CLIENT、WEB_GAME_ACTIONS 三个环境变量，并确保 Playwright 可用。具体的一键安装命令与入口以官方说明为准。

Q2：使用它要收费吗？ 技能详情中没有涉及收费信息。实际成本取决于你所使用的平台、模型与 Playwright 的运行环境，请以官方说明为准。

Q3：它适合谁用？ 适合用 Codex 构建或迭代 HTML/JS 网页游戏的开发者、独立创作者与教学者；如果你做的是普通业务网站而不是游戏，技能里的帧步进、状态文本等约定并不是为你设计的，收益有限。

Q4：和 @playwright/test 怎么选？ 技能详情明确建议：除非明确要求，不要切换到 @playwright/test，坚持使用自带的客户端脚本。前者适合大型业务系统的用例工程化，后者为游戏场景做了虚拟时间步进、截图与错误缓冲的定制，更贴合本技能的闭环流程。

Q5：为什么一定要暴露 render_game_to_text 和 advanceTime？ 前者让测试脚本能以文本方式读取当前局面，判断状态是否与画面一致；后者提供确定性的帧推进，避免依赖真实时间造成测试不稳定。技能明确指出：如果不提供确定性步进钩子，自动化测试可能不稳定。