html-game-parallel-builder 是一个用于构建模块化 TypeScript 浏览器游戏的技能,核心机制是“并行编码子代理 + 共享契约 + 成批次的集成检查点”,用来缩短实际耗时;在观众实时观看的情况下,也能从 run_web_server.sh 启动的 http://localhost:<port>/ 本地预览中看到游戏逐步成形。
用途与目标 该技能主要用于时间压力较大的实时场景,例如播客、课堂演示或直播;在这些场景中,缩短实际耗时比严格串行执行更重要。它并不追求替代串行流程;在时间不受限的场合,带 TDD(测试驱动开发)的串行代理能以相同的总成本产出更整洁的结果。
主要能力
- 为浏览器游戏预先指定的工作流布局与 src/ 模块拆分(默认按 A0-E 归属图划分)。
- 构建身份区分:默认面向 GitHub Pages 的 TypeScript 游戏构建到 dist/;只有在用户明确要求便携文件时,才使用单文件 HTML 导出到 dist-single/。run_web_server.sh、build_github_pages.sh、export_single_file.sh 三个脚本分别负责实时预览、标准构建和可选单文件导出,不能混用。
- 成批次的 Playwright 冒烟测试:每批完成后运行一次,失败时先修复再进入下一批。
- 针对 Web 平台的常见问题,例如 canvas 与 innerHTML、品牌化 id 泄漏到 DOM、在 verbatimModuleSyntax 下使用 type-only import。
使用方式 流程为:先收集 UI 偏好,约 2 分钟;再定义最小可行范围,即 1-2 个机制、1-2 种内容类型,首轮不做存档;然后顺序编写类型契约到 src/types/,并确保 npx tsc --noEmit -p tsconfig.json 通过;接着配置构建,即复制模板、设置可执行位、安装 GitHub Actions 工作流;之后分四批派发代理,第 1 批为基础,顺序执行,第 2 至第 4 批并行;最后在最终冒烟测试后进入集成修复循环,用 Playwright 查看控制台与快照,定位问题模块,并派发小型修复代理。编排者除第 1 批外不写游戏代码;编码子代理若需要跨模块类型,必须暂停并调用 typescript-engineer 获取类型化桩,不得在本地重新声明形状。
关键护栏 在编写契约并让 tsc 通过之前,不派发任何编码代理;没有让 npx tsc --noEmit 通过,不能宣布某批完成;批与批之间不能跳过冒烟测试;除了品牌化 id 构造器或存档文件类型守卫之外,禁止使用 as 断言;每个子代理报告必须引用确切的 npx tsc --noEmit 命令及其成功输出行,“全部通过”若没有证据则视为虚假通过并重新派发。
适用场景 需要多个子代理同时编写 .ts、CSS 和 HTML;应用包含相互作用的模块,例如数据生成、显示和用户交互;涉及 canvas 渲染的图表或游戏图形;发布目标为 GitHub Pages 或可选单文件导出。
限制与不适用 不适用于简单单文件编辑、服务端应用、使用了 Vite、Webpack、Next 等重型构建工具的多页应用,或单个子代理 10 分钟内即可完成的任务,因为并行开销不划算。该技能依赖上游的 typescript-engineer、delegate-manager-to-subagents 和 parallel-plan 技能;工具链脚手架本身来自 starter-repo-template,不属于本技能所有。