快速开始
克隆仓库,安装 Pillow,把门指向一个游戏。harness 是一组小的 Node/Python 脚本;它不 import 你的游戏,而是用无头 Chrome 驱动一个页面。
git clone https://github.com/NorwinYu/photoreal-game.git cd photoreal-game python3 -m pip install -r requirements.txt # 安装 skill 到技能目录,或把 SKILL.md 当作 AGENTS.md ./install.sh ~/.agents/skills # --dir 是被静态服务器托管的项目根 node harness/verify.mjs --dir ../my-game --page index.html
命令可以在任意目录运行。工具路径从 harness 目录解析;--dir 和 --out 从当前目录解析。运行会把截图和日志写到 shots/。
环境要求
| 需要 | 为什么 | 检查 |
|---|---|---|
| Node.js 22+ | Chrome DevTools Protocol 需要全局 WebSocket | node --version |
| Python 3.10+ | 图像统计与校准 | python3 --version |
| Pillow | PNG 解码与图像滤波 | python3 -c "import PIL; print(PIL.__version__)" |
| Chrome / Chromium | 无头渲染与 CDP | 不在标准路径时设置 CHROME_PATH |
没有 npm install,没有打包器,没有 API key。游戏本身应该是单文件、运行时零网络请求;harness 也不需要联网。
安装
DeepSeek Harness(DSH)
DSH 在 <workspace>/.dsh/skills/<name>/SKILL.md 发现 skill。安装到那里,然后开一个新会话;技能目录在会话开始时读取。
./install.sh /path/to/your-workspace/.dsh/skills
# 结果:<workspace>/.dsh/skills/photoreal-game/SKILL.md + harness/然后在新会话里请求 photoreal-game。更新时 git pull 后重跑同一条安装命令;卸载就是删掉那一个目录。完整说明:INSTALL.md。
通用技能目录
如果 agent 以 <dir>/<name>/SKILL.md 发现技能:
./install.sh ~/.agents/skills
# 或项目内技能目录
./install.sh .agent/skills如果 agent 只读一个指令文件,把 skill 复制成 AGENTS.md(或对应文件):
cp SKILL.md ../my-game/AGENTS.md
harness 会随 skill 一起复制。它不会进入模型上下文;agent 从 shell 运行它。看不见自己输出的 skill,是没有眼睛的流程。
页面契约
验收门不读源码,只读一小组全局变量和 URL 参数。只实现页面能支持的钩子;缺少某个钩子时,需要它的门会带着钩子名失败。
| 钩子 | 使用方 | 用途 |
|---|---|---|
window.__READY = true | shaders / 所有渲染 | 渲染几帧后置真;永远不为真会失败 |
window.__STATS | product / qa | { calls, triangles, fps, lights } |
window.__SCENE | census / collide / lights | 场景图;每个渲染 mesh 与灯可达 |
window.__COLLIDERS | collide | { x0, z0, x1, z1, y0?, y1? } 数组 |
window.__BOUNDS | collide | { x0, z0, x1, z1, playerRadius } |
window.__TESTMOVE(x,z,dx,dz) | collide | 返回一步之后解析出的 [x,z] |
window.__TEST(action,arg) | playtest / product | 脚本动作;协议见下 |
window.__GAME | 可选 | { state, actions, reset } |
window.__PRODUCT | product / mobile / look | 外壳、内容、存档、触屏、音频、预算、机位 |
window.__AUDIT | audit | 可选的对象预算清单 |
?shot=1 | 所有静帧 | 隐藏 chrome、冻结时钟,但保留 DOM 可检查 |
?cam=x,y,z,tx,ty,tz | look / qa | 固定机位,保证可比 |
?seed=N | 所有 | 固定随机种子,帧可复现 |
静帧模式不要删除调试 UI,用 display:none。product 和 playtest 读的是同一个 DOM;删掉它会让截图干净,却让游戏不可测。
验收命令
node harness/verify.mjs \ --dir ../my-game \ --page index.html \ [--profile refs/profile.json] \ [--target 0.85]
命令按失败类别顺序跑完所有门,再给一个结论。红色结论是构建失败;进程以非零状态退出,CI 可以直接消费。
shaders PASS census PASS collide PASS lights PASS playtest PASS product PASS mobile PASS look PASS look mode: FALLBACK (tone + emptiness; no profile at refs/profile.json) VERDICT: PASS (8/8)
八道门
| 门 | 读什么 | 什么时候失败 |
|---|---|---|
shaders | console、__READY | GLSL 编译/链接错误,或页面永远不 ready |
census | __SCENE | 可见 mesh 缺段数、表面贴图或声明的身份 |
collide | __SCENE / __COLLIDERS / __BOUNDS / __TESTMOVE | 阻挡物没有碰撞体、边界是裸的、高物体可穿、移动者穿透 |
lights | __SCENE | 点光/聚光 0.4 m 内没有实体灯具 |
playtest | __TEST | 胜利、失败、死因、可见后果或重开失败 |
product | __PRODUCT / DOM | 界面、设置、持久化、触屏、内容角色、HUD 组、音频事件、机位或预算缺失 |
mobile | __PRODUCT / DOM | 390×844 溢出、标题不可用,或声明触屏却没有控件 |
look | 截图 / __PRODUCT.cameras | 最差声明机位低于 profile,或色调失败;无 profile 时退化为色调/空置 |
look 门故意放最后。漂亮画面救不了缺失的产品;look 分数是一套参考的指南针,不是成品分。
校准
采集 2–3 张项目自己的目标帧——参考构建、静帧、概念图——分辨率和构图类别与输出一致,然后生成 profile:
python3 harness/calibrate.py refs/target-a.png refs/target-b.png \ --out refs/profile.json node harness/verify.mjs --dir ../my-game --page index.html \ --profile refs/profile.json
profile 存多尺度能量中位数、空间 p10、对比、平坦 tile 比例和色彩度。评分比较的是比值,不是绝对值,并附加与风格无关的色调检查。
用别的题材生成的 profile 量的是风格相似度,不是完成度。风格化场景可能天然低于照片感场景,哪怕它是更完整的游戏。用项目自己的 profile,或者明确使用回退模式并写出来。
没有 profile 时,verify 会打印 look mode: FALLBACK,只检查色调和空置:高光裁切 ≤ 1%、死黑 ≤ 3%、中间调 45–80%、平坦 tile ≤ 12%、平均亮度 0.10–0.62。
Playtest 协议
playtest.mjs 只认两种协议,且不含任何坐标。两者都没实现时,它会带着说明失败,而不是带着某个项目的坐标崩溃。
1. 页面拥有脚本:__TEST('selftest')
适合赛车、解谜、经营,以及胜利条件不是一组坐标点的循环。真实跑一遍胜利、失败和重开,返回 JSON:
window.__TEST = (action) => {
if (action === 'selftest') {
reset();
const win = runScriptedWin(); // 真实驱动循环
const loss = runScriptedLoss();
const restart = resetAndCheck();
return {
win: win.done === true,
fail: loss.failed === true,
restart: restart.health === 100,
cause: loss.cause, // 不能为空
steps: ['win', 'loss', 'restart'],
};
}
// start / pause / resume / openSettings / closeSettings / save / state ...
};2. 页面声明计划:__TEST('plan')
适合交互契约:走到每个目标,双向检查提示,交互,把进度和可见世界对照,再测致命伤害和重开。
window.__TEST = (action, arg) => {
if (action === 'plan') return {
key: 'E',
farPoint: [30, 30],
targets: [
{ id: 'relay-a', pos: [0, 10] },
{ id: 'relay-b', pos: [8, 4] },
{ id: 'relay-c', pos: [-6, 2] },
],
required: 3,
};
// reset / goto / step / interact / hurt / state / visual ...
};门检查反方向(范围外不出现按键提示)、正方向(提示、交互、进度、可见世界变化)、致命伤害与死因、结算界面和重开。伤害动作是 __TEST('hurt', n);可见痕迹是 __TEST('visual')。
排错
| 症状 | 原因 | 处理 |
|---|---|---|
Chrome/Chromium not found | 不在标准路径 | CHROME_PATH=/path/to/chrome node harness/render.mjs ... |
needs Node.js 22+ | 没有全局 WebSocket | 升级 Node |
ready=false,白屏或黑屏 | 页面没设 __READY,或 shader 失败 | 先看 console 错误;修编译,不要先调曝光 |
no __TEST | 页面没有暴露契约 | 加 window.__TEST,见上面的协议 |
profile not found | 没有 refs/profile.json | 先校准,或不用 --profile 接受回退 |
| look 分低但色调正常 | 画面细节不足 | 加中尺度物体和材质变化,不要加对比或 bloom |
单物体判断用 harness/objectbox.py 裁切测量;重复代码块和符号用 harness/structcheck.mjs;固定机位表格用 harness/qa.mjs。
隐私与许可
站点无统计、无 cookie、无第三方请求。游戏是单文件,运行时零网络请求。设置和最佳成绩存储在玩家本机的 localStorage。
代码、harness 和文字是 MIT。游戏构建和截图版权归 Norwin Yu,作为证据提供,不是游戏本身的授权。第三方名称和 Saltline 参考帧归各自所有者。
发现问题
因为错误原因失败的门,是 bug。