zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(t1b-alpha): 执行版v1.1——Codex评审13条全采纳,Gate0启动序定稿

Browse Source 
- P0×5:Gate0(lane-core先行七件交付→core-protocol-v0冻结→其余lane才并行)/视觉证据两层拆分(node测状态参数+浏览器哈希在集成段,禁node-canvas)/P9降级alpha本地adapter(SDK StoragePlugin契约补丁列β,不声称契约已存在)/同步统一(主会话收编提交→mini-desktop拉精确SHA,cat仅紧急单文件)/参考件评估主体=主会话维护的e2e-input.cdp.cjs+两个3轮分立+裁决包四选终态
- 关键解法:发行版源码=ESM JS+JSDoc+手写d.ts——零工具链node直测,esbuild只在集成段(lane阶段彻底摆脱构建依赖)
- P1×5:math fuzz性质测试/P10本波RuntimeProbe六锚点字段级(只复用channel-probe形状不搬渠道语义)/SIZES命令口径写死/薄能力面优先序(P1P4P9P10闭环优先)+插件段扩3天/evidence目录约定沿T1结构
- P2×3:mmx停机阈值(每轮≤20次,quota失败即停)/IP gate扩产物grep+截图核/serve生命周期(unit命名固定端口探活轮终stop)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
zizi 2026-06-12 10:48:52 +00:00
parent 2446b712d5
commit 8d3cf1383f
1 changed files with 39 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/agent-specs/2026-06-12-T1b-α插件库与参考件-execution.md
View File

@ -1,38 +1,55 @@
# T1b-α · LittleJS 能力插件库 seed 八件 + 王蓝莓参考件 · 执行版(HJ-T1B-A-EXEC-001)
> **状态:v1 待评审(Codex 优先,503 则回落 Claude 注明)→ 过审放 agent。** 配对评审版 = `2026-06-12-W-T1b-Runner与双层模板-review.md` v2.1(架构/范围门/主门护栏以它为准,本文只管执行)。开工授权:创始人 2026-06-12「按默认开工」。
> **状态:v1.1,Codex Xhigh 评审(5 P0/5 P1/3 P2)全采纳;启动序=先放 lane-core 做 Gate0,协议冻结过审后其余 lane 并行。** 配对评审版 = `2026-06-12-W-T1b-Runner与双层模板-review.md` v2.1。开工授权:创始人 2026-06-12「按默认开工」。
> 修订:v1.1 = Gate0 启动序/视觉证据两层拆分(禁 node-canvas)/P9 降级 alpha 本地 adapter(契约补丁列 β)/同步统一(SHA 拉取)/参考件评估主体与失败终态/源码形态改 ESM JS+JSDoc(零工具链直测)/RuntimeProbe 本波锚点定义/SIZES 命令口径写死/evidence 目录约定/薄能力面优先序+时间盒扩/mmx 停机阈值/IP gate 产物扫描/serve 生命周期。
## 1. 工程位置与工具链
## 1. 工程位置·源码形态·同步纪律
- **新建仓根工程 `game-runtime/`**(LittleJS 增强发行版,独立 npm 工程,后续拆仓友好):`src/plugins/{collision,physics-lite,particles-juice,gamefeel,palette-post,audio-music,save-progress,sdk-probe}/`+`src/core/`(发行版入口/插件注册)+`docs/`(给 agent 读的插件文档)+`test/`+`games/`(参考件等 agent 生成游戏工程)+`host-dev/`(开发宿主页,简版 Runner:加载发行版+游戏 entry,留八锚点接线)。
- 依赖:littlejsengine@1.18.x(锁 T1 终裁版)+esbuild+TS;测试=node:test 零外依赖(沿 spike 纪律);**构建/装依赖只在 mini-desktop**(6c6g 禁,staging-ops 红线),lane 在仓内写码、经 `ssh mini-desktop 'bash -ls'` 同步构建(git 经 Gitea 拉取或 cat 管道单文件传,禁 scp 目录)。
- 仓根新建 `game-runtime/`:`src/core/`+`src/plugins/<八件>/`+`docs/`+`test/`+`games/`+`host-dev/`+`scripts/`+`schema/`。
- **源码形态(P0-2 解法的地基)**:发行版源码=**ESM JS+JSDoc 类型注释**,公开能力面=**手写 `api.d.ts`**——零工具链,lane 阶段 `node --test` 本地直跑;esbuild(锁参数,见 §5)只在集成段(mini-desktop)打包压缩。
- **同步统一(P0-4)**:lane 在仓内写码不跑 git → **主会话按里程碑收编提交推送** → mini-desktop **只拉精确 commit SHA** 构建;lane 阶段一切测试=本地零依赖 node,**一切构建/浏览器证据=集成段**;cat 管道仅限紧急单文件,不作源码树同步。
## 2. 插件协议(shared 契约,先于 lane 定稿)
## 2. Gate0(lane-core 先行,协议冻结后其余 lane 才开)
每插件固定五件:`api.d.ts`(公开能力面,**禁玩法/品类语义**)/`impl.ts`/`test/*.test.cjs`(node 可跑)/`PLUGIN.md`(给 agent 读:能力/集成点/示例)/`manifest.json`(名称/版本/gz 预算/依赖)。插件只经公开 API 暴露,**禁直透 LittleJS 裸接口给游戏层**(保引擎可换);单件 gz 配额见评审版 §1(P1 8K/P2 6K/P3 10K/P4 4K/P5 8K/P6 12K/P9 2K/P10 6K),超配额→评审,合计>60K→创始人放行。
lane-core 交付七件 → 主会话审 → 提交冻结为 **core-protocol-v0**:
1. `src/core/plugin.js`+`core/api.d.ts`:Plugin 接口(name/version/init(ctx)/dispose)/注册器与生命周期/PluginContext(engine 句柄经受控面暴露,**禁直透 LittleJS 裸接口给游戏层**);
2. `schema/plugin-manifest.schema.json`(名称/版本/gz 预算/依赖声明/exports 规则,`additionalProperties:false`);
3. `src/plugins/_example/` 空插件样例(五件全:api.d.ts/impl.js/test/PLUGIN.md/manifest.json,可直接克隆);
4. `docs/PLUGIN-TEMPLATE.md`(PLUGIN.md 模板:能力/集成点/示例/边界——给 agent 读的文档规格);
5. `scripts/`:build.mjs(esbuild 锁参)/size.mjs(增量测量)/test.sh(全插件 node --test);
6. `test/harness/browser-evidence.cjs` 骨架+说明(集成段 mini-desktop Chrome 用:固定 viewport 390×844/DPR 2/seed/时间源 mock,输出 ImageData 哈希+非空/色彩/几何断言+截图);
7. 目录与证据约定 README(见 §6)。
core 注册器自身带零依赖 node 测试(注册/重名拒绝/生命周期顺序/dispose 幂等)。
## 3. Lane 切分(互斥文件面,lane 不跑 git)
## 3. Lane 切分(Gate0 后并行,互斥文件面,不跑 git)
| Lane | 插件 | 要点 |
| Lane | 插件 | 测试纪律 |
|---|---|---|
| lane-math | P1 collision(空间哈希/圆 AABB SAT/射线)+P2 physics-lite(弹道/弹簧阻尼/运动学约束)+P4 gamefeel(输入缓冲/coyote/缓动库/连击窗) | 数学正确性单测为主(已知解对照) |
| lane-vfx | P3 particles-juice(预设粒子+hit-stop/屏震/闪白)+P5 palette-post(调色引擎+后处理;**不内置成品色板**) | 视觉件以确定性快照测(seed 固定→canvas 哈希) |
| lane-sys | P6 audio-music(ZzFXM 序列器+情绪分层+ZzFX 预设)+P9 save(SDK storage 契约)+P10 sdk-probe(SDK 接入面+八锚点取证集成点,**只复用 channel-spike 取证 API 形状,不搬其实体资产**) | P10 对齐 contracts/sdk-interface.d.ts 语义 |
| lane-core | 发行版入口/插件注册器/host-dev 宿主页/构建脚本(esbuild 分项产物+SIZES 实测) | 先行半天定插件协议骨架,其余 lane 依协议并行 |
| lane-math | P1 collision(空间哈希/圆 AABB SAT/射线)+P2 physics-lite(弹道/弹簧阻尼/运动学约束)+P4 gamefeel(输入缓冲/coyote/缓动/连击窗) | 已知解对照+**确定性 fuzz 与性质测试**(broadphase 对 brute-force/SAT 退化边/射线边界/弹簧单调收敛/全程无 NaN/时间步容差/输入缓冲与 coyote 边界) |
| lane-vfx | P3 particles-juice+P5 palette-post(**不内置成品色板**) | **两层**:node 层只测确定性状态与参数(粒子数/生命周期/调色映射表);canvas 渲染哈希=集成段浏览器证据(harness),**禁 node-canvas 兜底** |
| lane-sys | P6 audio-music(ZzFXM 序列器+情绪分层+ZzFX 预设)+P9 save(**alpha 降级=本地 adapter**,统一 API 后接 localStorage/host-dev 桩;SDK StoragePlugin 契约补丁列入 β/9 契约组,**不声称契约已存在**)+P10 runtime-probe | P6 node 层测序列器数据流(无 AudioContext 断言),发声=集成段;P10 见下 |
| lane-ref(集成后) | 王蓝莓参考件 | §4 |
集成门(lane 全绿后,主会话编排):全插件注册构建绿+SIZES 分项实测(增量法,沿 channel-spike 口径)+host-dev 页冒烟(空游戏挂全插件不抛错)。
**P10 RuntimeProbe 本波锚点(定义到字段,P1-2)**:`t_boot→t_plugins_ready→t_game_init→t_first_paint→t_input_bound→t_game_start`,JSONL 字段=seq/单调时钟/前条哈希(FNV-1a 链)/buildSha/pluginSet;`verify` 命令随附;**只复用 channel-probe 的 mark/verify/哈希链"形状",不搬渠道语义锚点**(t_config_loaded 等渠道专属不进本波)。
## 4. 参考件(王蓝莓,人肉循环)
## 4. 参考件(王蓝莓,人肉循环,Gate0+集成门后)
- **循环协议**(主会话编排,全程留痕入 `games/wanglanmei-ref/LOOP-LOG.md`):每轮=①计划(本轮目标/调用哪些插件)→②开发 agent 写码→③mini-desktop 构建+host-dev serve(systemd-run 配方)→④评估(可测性红线:取证清单导出+真输入脚本过五要素 checklist 自动子项)→⑤判词(中间轮=我按 checklist 预判;终轮=创始人亲玩打分)。迭代≤3 轮预判收敛后才提请亲玩。
- **资产铁律(mmx)**:美术=`mmx image generate`(手绘市井风占位,**不用王蓝莓名称/形象**,IP gate)+P5 调色;音乐=`mmx music generate --instrumental`;**每轮资产生成前后 `mmx quota show --output json` 对账,生成清单(prompt/文件/字节)入 LOOP-LOG**(创始人令 watch the usage);资产入 `games/wanglanmei-ref/assets/` 并登记 manifest(尺寸/用途/hash)。
- **主门**:创始人亲玩(手机+桌面,serve URL)按五要素各 1~5 分,均分 ≥4 过;判词与轮次全留痕。
- 游戏工程红线:只用插件公开 API(禁裸 LittleJS);导出取证清单(可交互几何/锚点接线/闭环可达断言);GameConfig 过 channel-spike 合规 schema 扫描(红线复用,资产域名豁免本地)。
- **循环**(主会话编排,留痕 `games/wanglanmei-ref/LOOP-LOG.md`):①计划→②开发 agent 写码→③主会话收编提交→mini-desktop 拉 SHA 构建+host-dev serve→④**评估(执行主体=主会话维护的 `games/wanglanmei-ref/test/e2e-input.cdp.cjs`,非开发 agent 所有)**:mini-desktop Chrome CDP 真输入跑 host-dev URL,输出输入轨迹/截图与 canvas 哈希/probe JSONL/checklist JSON 四件→⑤判词。
- **两个"3 轮"分立(P0-5)**:内部预判轮 ≤3(checklist 自动子项+我按 checklist 预判;第 3 轮仍不达线→**裁决包**交创始人四选:接受当前版/砍范围/重定目标/延时间盒);达线→提请亲玩;**亲玩判词轮 ≤3=评审版主门护栏**(五要素 1~5 分均分 ≥4 过),两组计数互不混算。
- **mmx 资产铁律**:美术 `mmx image generate`(占位手绘市井风)+P5 调色;音乐 `mmx music generate --instrumental`;**每轮生成 ≤20 次(停机阈值),quota show 失败→停止生成上报**;每轮前后 `mmx quota show --output json` 对账+生成清单(prompt/文件/字节/hash)入 LOOP-LOG;资产入 `games/wanglanmei-ref/assets/`+manifest。
- **IP gate(扩到产物,P2-2)**:源码路径/内部文档可用 wanglanmei 代号;**构建产物 grep 零「王蓝莓」字样**(对外页面标题/manifest/GameConfig/资产 prompt)+截图人工核对无受保护形象;违者不出门。
- **serve 生命周期(P2-3)**:每轮 `systemd-run --unit=t1ba-ref-r<N>` 固定端口 4320,起服 5×6s 探活;轮终 `systemctl stop`+日志归档 evidence/round-N/,不留孤儿 unit/端口。
- 游戏红线:只用插件公开 API;导出取证清单(可交互几何/锚点接线/闭环可达断言);GameConfig 过 channel-spike 合规 schema 扫描(本地资产域名豁免)。
## 5. 验收与收口
## 5. SIZES 与集成门(命令口径写死,P1-3)
1. seed 八件:单测全绿+单件 gz ≤配额+PLUGIN.md 齐(给 agent 读的文档=一等公民,缺文档=未交付);2. 集成门三项过;3. 参考件过评估门+**创始人亲玩 ≥4**(主门);4. mmx 用量台账完整;5. 过门后按 wave-close 七步收口(蒸馏:插件协议→9a 契约组草案、循环留痕→W-G2 选型需求输入);判不过→按判词迭代(≤3 轮触发创始人裁决)。失败处置:任一插件结构性受阻(LittleJS 不可扩展点)→停 lane 上报,不绕道 hack。
- esbuild:`bundle+minify+format=iife+target=es2019+sourcemap=false`;gz=`gzip -9 -c | wc -c`;**增量法**(基线壳→+core→逐插件叠加取差值,沿 channel-spike 口径);`SIZES.md` 表=分项 raw/gz 双列+命令注记。
- 集成门三项:全插件注册构建绿;SIZES 实测单件 ≤配额(P1 8K/P2 6K/P3 10K/P4 4K/P5 8K/P6 12K/P9 2K/P10 6K,超→评审;合计>60K→创始人放行);host-dev 冒烟(空游戏挂全插件不抛错)+浏览器证据 harness 对 vfx 出首批哈希断言。
## 6. 时间盒与红线
## 6. 证据与目录约定(P1-5,沿 T1 结构)
插件段 ≤2 天等效;参考件段 ≤3 天等效(含迭代);超盒上报不静默续期。全代码简体中文注释;lane 不跑 git(主会话收编);mini-desktop 不起长驻进程(serve 走 systemd-run);不碰 channel-spike/ 与 contracts/(P10 只读对齐);IP gate:对外可见物零「王蓝莓」字样与形象。
每 lane:`REPORT.md`(实现说明+边界+红线声明)/`test/RESULT.txt`(node --test 原始输出)/PLUGIN.md×N;集成段:`game-runtime/SIZES.md`+`evidence/integration/`(构建日志/浏览器证据哈希+截图);参考件:`evidence/round-N/`(四件套+serve 日志)+`LOOP-LOG.md`+`sha256-manifest.txt`(校验脚本复用 channel-spike verify-evidence 形状)。
## 7. 验收·时间盒·优先序
1. **薄能力面优先序(P1-4)**:P1/P4/P9/P10 优先闭环(参考件最小依赖),P3/P5/P6 最小可用版(预设各 ≥3 个/调色映射可用/一首循环曲),不足处在 PLUGIN.md 声明 v2 边界;2. 插件段 ≤**3 天**等效,参考件段 ≤3 天等效(含预判轮),超盒上报降级裁决不静默续期;3. 验收=评审版 §5 五条+本文证据约定;4. 失败处置:结构性受阻(LittleJS 不可扩展点)→停 lane 上报不绕 hack;5. 收口=wave-close 七步(蒸馏:插件协议→9a 草案/循环留痕→W-G2 需求输入)。