快速开始

克隆仓库,安装 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 需要全局 WebSocketnode --version
Python 3.10+图像统计与校准python3 --version
PillowPNG 解码与图像滤波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。安装到那里,然后开一个新会话;技能目录在会话开始时读取。

DSH / 工作区技能目录
./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 = trueshaders / 所有渲染渲染几帧后置真;永远不为真会失败
window.__STATSproduct / qa{ calls, triangles, fps, lights }
window.__SCENEcensus / collide / lights场景图;每个渲染 mesh 与灯可达
window.__COLLIDERScollide{ x0, z0, x1, z1, y0?, y1? } 数组
window.__BOUNDScollide{ 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.__PRODUCTproduct / mobile / look外壳、内容、存档、触屏、音频、预算、机位
window.__AUDITaudit可选的对象预算清单
?shot=1所有静帧隐藏 chrome、冻结时钟,但保留 DOM 可检查
?cam=x,y,z,tx,ty,tzlook / 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)

八道门

门读什么什么时候失败
shadersconsole、__READYGLSL 编译/链接错误,或页面永远不 ready
census__SCENE可见 mesh 缺段数、表面贴图或声明的身份
collide__SCENE / __COLLIDERS / __BOUNDS / __TESTMOVE阻挡物没有碰撞体、边界是裸的、高物体可穿、移动者穿透
lights__SCENE点光/聚光 0.4 m 内没有实体灯具
playtest__TEST胜利、失败、死因、可见后果或重开失败
product__PRODUCT / DOM界面、设置、持久化、触屏、内容角色、HUD 组、音频事件、机位或预算缺失
mobile__PRODUCT / DOM390×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:

页面 / selftest
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')

适合交互契约:走到每个目标,双向检查提示,交互,把进度和可见世界对照,再测致命伤害和重开。

页面 / 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。

开 issue ↗