great-html 是做什么的?
一句话:用户说一句,你交付一个双击即开的 .html。
不是「能跑的 demo」,是可交付的作品:首屏有加载进度、桌面鼠标键盘可用、手机能点、控制台无报错、断网也能开。
三条硬规则(不可协商)
| # | 规则 | 判定方式 |
|---|---|---|
| 1 | 单文件:一个 .html,无 src=、无 link rel=stylesheet、无 import 外部 URL | 交付前 grep 一遍 |
| 2 | 零请求:断网可用。图片、字体、模型、音频一律不许外链 | scripts/verify.py 会拦截所有请求并断言为 0 |
| 3 | 资产是代码:几何用图元拼、表面用 GLSL 算、声音用 WebAudio 合成 | 没有 base64、没有 .png/.glb/.mp3 |
唯一允许的外部依赖是 three.js —— 而且必须内联(见第 5 步)。开发期可以走 CDN,交付前必须 vendored。
流程(按顺序,不许跳)
0 · 先问,再动手
任何情况下都先确认需求,用 references/10-intake.md 里的四问脚本。不要替用户想象场景细节,也不要问超过四个问题。
必须拿到:轨道(游戏 / 落地页 / 交互站 / 工具)、题材与参考、核心交互、画质与体积预期。
拿不到就用默认值并在开工前一句话说明假设。
1 · 定轨道,读对应手册
| 用户说的话 | 轨道 | 必读 |
|---|---|---|
| 枪战 / 第一人称 / 能走动 / 有敌人 | GAME | references/40-game.md |
| 官网 / 落地页 / 产品介绍 / 活动页 | LANDING | references/50-landing.md |
| 展厅 / 产品分解 / 可旋转查看 / 作品集 | SHOWCASE | references/60-showcase.md |
轨道决定骨架,不要混。落地页塞进 FPS 操作是最常见的翻车方式。
2 · 定视觉(先定光和色,再定模型)
读 references/70-design.md,写下一句话的视觉命题,例如:
黄昏逆光、湿地面反射、雾把远景压成剪影;主色是铁锈橙 + 冷青灰。
90% 的「像不像」由光照与调色决定,不是由模型面数决定。 先搭天空 + 一盏主光 + 雾,再堆物体。
3 · 抄骨架
从 templates/ 复制最接近的一版,改而不是从零写:
templates/fps-starter/— 第一人称:指针锁定、AABB 碰撞、程序化材质、单 quad 粒子、HUD、自适应画质templates/landing-3d/— 滚动驱动的 3D 背景 + 玻璃拟态文案templates/site3d/— 手写轨道相机 + DOM 热点 + 分解视图
骨架里的分区顺序就是构建顺序:渲染器 → 材质 → 几何 → 场景 → 特效 → 交互 → HUD → 循环。
4 · 按「资产 → 算法」写内容
核心手法在 references/20-procedural.md。最小可用组合:
- 表面:一个
surface()材质工厂 + GLSL 噪声,靠 uniform 区分沥青/漆面/金属 - 几何:盒子/圆柱 + 顶点色 + 手写 merge,一个材质一次 draw call
- 重复物:实例化或合并,不要逐个
new Mesh - 粒子:一个 quad/线段批次 + 顶点着色器算形状与朝向
- 声音:噪声 + 滤波 + 包络,20 行能出枪声
写之前先决定这个物体由几个盒子组成。想不清楚就先画侧影,用 ExtrudeGeometry 挤出。
5 · 离线化(必做)
python scripts/vendor_three.py index.html -o index.offline.html
mv index.offline.html index.html
它把 import * as THREE from 'three' 换成 const THREE = window.THREE,并把库内联成 ≈705 KB 的普通 <script>。
6 · 验证(必做,不许口头保证)
python scripts/verify.py index.html --shots 3
它会:断网加载 → 等 window.__ready → 抓 window.__stats() → 收 console.error → 从三个视角截图。
通过标准:requests=0、errors=[]、无黑屏、fps 在任何机器上不为 0(无头环境除外)。
然后按 references/90-qa.md 走一轮截图自审:开一个只看图不看代码的子 Agent,要它按严重程度列问题。
7 · 交付
回复里必须写清:文件大小、首帧耗时、操作方式、已知取舍。不要把「打不开」留给用户发现。
每轨道的最低完成度
GAME
指针锁定可用、WASD 能走且不会穿墙、能射击且有反馈(枪口焰 + 命中标记 + 声音)、有目标和结束条件、有暂停/重开、掉帧自动降分辨率。
LANDING
首屏 3 秒内出内容、滚动有推进感、所有文案是真文案(不是 Lorem)、手机端不横向溢出、prefers-reduced-motion 时不抖。
SHOWCASE
能拖动旋转、能缩放、有 3–6 个可点击热点、点开有信息卡、空闲时缓慢自转(提示可交互)。
反模式(出现即返工)
- ❌ 用 CSS 渐变假装 3D,却没有真正的相机与光照
- ❌ 把 three.js 以外的东西也 CDN 化(字体、图标库、GSAP)
- ❌ 截图里好看的模型,近看全是穿模与悬空
- ❌ 写
TODO、写「示例文本」、写假数据却不说 - ❌ 只做桌面端,手机上按钮被裁掉
- ❌ 交付不带
__stats,导致无法回归验证 - ❌ 一次写 3000 行再运行——每 200 行跑一次
文件索引
| 文件 | 什么时候读 |
|---|---|
references/00-contract.md | 开工前,确认边界与约束 |
references/10-intake.md | 需求确认,四问脚本 |
references/20-procedural.md | 写任何材质、几何、粒子、音效时 |
references/30-render.md | 配渲染器、光照、阴影、后处理时 |
references/40-game.md | GAME 轨道 |
references/50-landing.md | LANDING 轨道 |
references/60-showcase.md | SHOWCASE 轨道 |
references/70-design.md | 定视觉、排版、配色 |
references/80-perf.md | 掉帧、黑屏、内存爆掉时 |
references/90-qa.md | 交付前的自审清单 |
prompts/brief.md | 用户只给一句话时,直接套用的需求模板 |
prompts/build.md | 构建期的约束提示词(贴给自己的系统提示) |
prompts/review.md | 开子 Agent 审图时的提示词 |
templates/ | 骨架,复制后改 |
examples/fps-harbor/ | 上限参考:1.4 MB 的完整 FPS |
examples/hogwarts-duel/ | 换皮参考:754 KB,看骨架哪几块该换、哪几块不该动 |
scripts/vendor_three.py | 离线化 |
scripts/verify.py | 自动化验收 |