3d-scene-forge 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# 3d-scene-forge — AI 建造 3D 场景的验收闭环工作流
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI agent skill（源自 Google Gemini Argon 3D 方法论，本地化到 three.js 工具链）。七阶段：A 对齐(grill) → B 2D 锚定 → C 计划(goal) → D 并行建造(≥4 分区子代理) → E Critic 循环(四机位协议，总分 ≥9.0 才许停) → F 控制面板 → G 靶图逼近。
+
+内含实战坑清单：three.js 渲染坑检查清单、氛围 FX 食谱（雨/蒸汽/湿地/布料/灯影）、Critic 协议与缺陷回归追踪（flaw-registry）。
+
+用法：将 `SKILL.md` 与 `references/` 安装到你的 agent 技能目录（如 `.agents/skills/3d-scene-forge/`）。搭配 `3d-prompt-forge`（其定稿输出直接作为本技能的规格契约）使用。

package/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: 3d-scene-forge
+description: >
+  AI 建造 3D 场景/3D 游戏/程序化世界的验收闭环工作流（源自 Google Gemini Argon 3D
+  方法论，已本地化到本机工具链）。七阶段：先拷问对齐再自治执行（grill→goal）、
+  2D 图纸锚定比例、并行子代理分区建造、四机位 Critic 验收循环（9/10 门槛）、
+  人工艺术指导控制面板（JSON 固化）、目标渲染图逼近（图生靶图反推代码）。
+  触发词：3D 场景、3D 游戏、three.js 建场景、程序化世界、3D 建模、场景迭代优化、
+  光照材质调优、模型悬浮穿模、3D scene、build a 3D game/world、让场景更好看。
+  凡是"让 AI 建一个 3D 东西并且要好看"的任务都用本技能；three.js 动画出成片走
+  science-film，不要用本技能渲染视频。
+---
+
+# 3d-scene-forge —— AI 建造 3D 场景的验收闭环工作流
+
+**核心思想**：把 3D 建模从"一次性生成"变成**带视觉验收闭环的长期自主工程**。
+
+角色分工：**用户是艺术总监**（出品味），**主线 Agent 是施工队长**（出执行），
+**Critic 子代理是监理**（出门槛）。经验教训："让模型'不停迭代直到场景好看'往往没用——
+很多模型第 2 轮就自我感觉良好宣布完工。" 所以一切质量来自**协议化的验收**
+（固定机位、固定缺陷清单、数值门槛），不来自模型自觉。
+
+## 0. 本机前置
+
+| 依赖 | 用途 | 说明 |
+|---|---|---|
+| three.js | 场景本体 | 单文件用 CDN import map；多模块用 Vite |
+| `ego-browser` 技能 | 截图验收 | 对本地服务 `page.screenshot` 逐机位抓帧 |
+| `tokengo-cli` 技能 | 概念图/纹理/靶图 | **付费生成**，调用前必须先向用户确认 |
+| Agent 工具 | 并行子代理 + Critic | general-purpose；一条消息多个调用即并行 |
+| `python -m http.server` / `npx vite` | 本地服务 | 截图前先起服务 |
+| `mcp-blender`（可选） | 主角级高精度模型 | 写 Python 脚本无头建模导出 .glb，普通形体不必用 |
+
+## 1. 生命周期总览（七阶段）
+
+```
+A 对齐(grill) → B 2D锚定(?) → C 计划(goal) → D 并行建造(?)
+  → E Critic循环(必) → F 控制面板(?) → G 靶图逼近(?) → 固化交付
+```
+
+| 阶段 | 何时启用 | 参考文件（进阶段前必读） |
+|---|---|---|
+| A 对齐 | 每次必做（纯试验可缩为 1 问）；**有参考图时必须跑量化统计**（中位亮度/p95/sat占比 → 写入 PLAN 量化验收线） | `references/grill-goal.md` |
+| B 2D 锚定 | **布局/比例要准**：真实题材还原 / 多室建筑 / 空间上很难做对时 | `references/grounding-2d.md` |
+| C 计划 + goal | 长任务（预计 >1 轮对话）必做 | `references/grill-goal.md` |
+| D 并行建造 | **场景类项目默认强制**：标准四分法（主体/环境/前场道具/氛围光照）≥4 子代理并行；少于 4 须在启动消息显式申请理由。平台期单类别打磨轮豁免（主编直接改） | `references/parallel-zones.md` |
+| E Critic 循环 | **默认必开**，任何面向展示的 3D 产出；缺陷 registry 回归追踪 + 量化对照 | `references/critic-protocol.md` |
+| F 控制面板 | 面向展示的产出**默认启用**（轻量版：里程碑后给 2-3 组预调参数让用户挑）；用户明说"全自动"才跳 | `references/control-panel.md` |
+| G 靶图逼近 | **画面要真**：追照片级、或光照材质调参停滞时（B 管"布局准"，G 管"画面真"，互不替代） | `references/target-render.md` |
+
+阶段判定要在 A 对齐结束时一次性做完并告诉用户（"本单走 A-C-E-F，B/G 不需要"），
+之后不再反复改判。E 永不跳过。
+
+## 2. 各阶段一句话守则
+
+- **A 对齐**：写代码前先出 2D 概念图给用户签核；改一张图比改一个场景便宜两个数量级。有参考图 → 先跑它的亮度/色彩统计，作为全项目的量化验收线。
+- **B 2D 锚定**：平面图的坐标系就是 3D 世界坐标系，先图后体。
+- **C 计划**：PLAN.md 的验收标准必须可机检/可截图（含量化线），goal 宪章由 Agent 起草、用户批准一次。
+- **D 并行建造**：分区分析强制先行——标准四分法 ≥4 子代理；先签《分区契约》再派工；合并是关口不是打包，机检审计 + 四机位截图全过才进 E。
+- **E Critic 循环**：四机位固定协议 + 独立 Critic 子代理 + 总分 ≥9.0 才许停；缺陷 registry 回归追踪，每轮先复验上轮修复项。
+- **F 控制面板**：让用户拖滑杆，把品味变成 JSON；验收画面里不许出现面板。
+- **G 靶图逼近**：先拍干净靶本，生成 1:1 同机位靶图，代码追靶——禁止贴图糊弄。
+
+## 3. 铁律（违反 = 交付作废重做）
+
+1. **评分画面必须干净**：截图一律 `?clean=1` 隐藏全部 UI/滑杆/HUD——Critic 和图像模型
+   会把按钮误判成场景元素，整轮白跑。
+2. **机位必须确定**：场景从第一天就实现 `?cam=overview|detail|low|wireframe`，
+   协议截图才可复现、轮次之间才可比。
+3. **产物落盘**：概念图进 `concept/`，验收物进 `_review/`（`r{n}/` 截图、critic JSON、
+   audit JSON、progress.html）。绝不闭眼交付。
+4. **靶图只能追不能贴**：禁止把靶图当背景/天空盒/贴图进场景冒充完成；
+   wireframe 机位 + 相机移动检查即可揭穿。
+5. **付费生成先确认**：tokengo-cli 图像生成是付费操作，批量出图前向用户报数量与用途；
+   未授权时降级用用户提供的参考图。
+6. **门槛不议价**：Critic 总分 <9.0 不得宣布完工；Critic 每轮必须列出 ≥3 个**新**具体缺陷
+   （或逐条确认零缺陷），列不出来说明它在放水，换更严的提示词重派。
+7. **量化对照与回归追踪**：验收截图必须与量化验收线同口径测量（中位亮度/p95/
+   sat>0.7 占比/暗部占比——B0 从靶图实测）；缺陷清单持久化为 `_review/flaw-registry.json`，
+   每轮 Critic 先逐条复验上轮修复项再扫新项。连续 2 轮 |Δoverall|≤0.2 触发**平台期协议**：
+   强制产出根因分类卡（参数类/比例类/资产类/构图类 + 各类预估轮数）提交用户，同时切换
+   单类别纪律（每轮只动一类，主编直接改，不派子代理）。
+
+## 4. 交付物清单（收尾自查）
+
+- [ ] 场景代码（多模块或单文件）+ 场景 README（写明调试参数与机位定义）
+- [ ] `PLAN.md`（里程碑 + 验收标准 + 量化验收线）
+- [ ] `concept/`（参照物 + 概念图）与 `_review/`（各轮截图、critic JSON、audit JSON、progress.html）
+- [ ] `settings.json`（控制面板 JSON 固化的最终参数，作为场景默认值）
+- [ ] 几何审计报告（零穿插、零悬浮的机检证据，非目测）
+- [ ] `_review/flaw-registry.json`（缺陷回归追踪）+ **按杠杆排序的 backlog**
+      （残余缺陷分 参数类/资产类/结构类，每项标注确诊原因与预估轮数）
+
+## 5. 与其他技能的衔接
+
+- 场景要出**成片视频** → 转 `science-film`（seek 安全与配音约束在那边生效）。
+- **人物（摊主/路人/食客等剪影角色）→ 一律 `mcp-blender` 基型管线**（`references/pitfalls-threejs.md`
+  附 figures 基型脚本），禁止图元拼装人物进入 Critic 循环——图元人物在暖光下只会读作
+  "米色白模/石灯笼"，烧轮数不涨分。主角级雕塑感模型同理。
+- 与 `3d-prompt-forge` 衔接：其定稿输出含《建造规格表》（量化附录），直接转成
+  PLAN.md 量化验收线与本 skill 的 Critic 对照基线——规格契约交接，不只是提示词交接。
+- 浏览器操作与截图 → `ego-browser`（注意 CDP setCacheDisabled 防模块缓存）；
+  图像生成 → `tokengo-cli`。
+- **three.js 渲染坑**（layers/GLB 依赖链/Reflector 性能/bloom linear 阈值/toon 饱和）
+  → `references/pitfalls-threejs.md` 检查清单；氛围 FX（雨/蒸汽/湿地/布料）参数
+  → `references/fx-recipes.md`。

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "3d-scene-forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AI 3D scene building workflow with acceptance loop: parallel zone subagents, four-camera Critic protocol (>=9.0 gate), quantified acceptance lines, three.js pitfalls & FX recipes. AI agent skill (3D 场景验收闭环工作流).",
+  "keywords": ["ai-agent-skill", "3d", "threejs", "workflow", "claude-skills", "agent-skills"],
+  "license": "MIT",
+  "files": ["SKILL.md", "references"]
+}

package/references/control-panel.md

@@ -0,0 +1,37 @@
+# F：控制面板 + JSON 固化（人的品味入口）
+
+> 原理：Critic 抓的是技术缺陷（悬浮、穿插、材质扁平）；"我喜欢哪种感觉"
+> 只有用户能输入。给用户造工具，把品味变成结构化数据——这是本工作流里
+> 最聪明的一步： taste 从聊天记录里的形容词，变成可固化、可复放的 JSON。
+
+## 建面板
+
+- 工具：`lil-gui`（CDN 一个 import 即可）或手写 DOM 面板；`?debug=1` 时显示。
+- 必备控件（按场景裁剪）：
+  - 光照：太阳方位角、高度角、光强、色温、环境光强、雾密度；
+  - 材质：粗糙度、金属度、纹理平铺密度；
+  - 相机：距离、FOV、高度；
+  - 后期：Bloom 强度、曝光、对比度。
+- 必备按钮：**"Copy Settings as JSON"**——把面板当前值序列化进剪贴板。
+- 所有参数从 `settings.json` 读默认值；**固化 = 用用户贴回的 JSON 覆盖这个文件**，
+  场景加载时应用为默认。
+
+## 工作循环
+
+1. 每个里程碑后请用户开 `?debug=1` 拖滑杆；用户没空时，主线按 Critic 缺陷预调
+   2-3 组参数，各截一张图让用户挑（这就是"给用户艺术总监席位"）。
+2. 用户把 JSON 贴回会话 → 主线写入 `settings.json` 作为永久默认 → 截图对比确认。
+3. 交付前：面板保留在 `?debug=1` 后面（默认隐藏，用户随时可再调），或按用户要求移除。
+   **任何验收截图一律 `?clean=1`，画面里不许出现面板。**
+
+## progress.html 画廊
+
+- 每个里程碑把各机位截图追加进 `_review/progress.html`，`<figure>` 带标题
+  （里程碑号 + 轮次 + 一句话，如"M3·r2：金色黄昏，Bloom 降到 0.6"）。
+- 用途：让用户随时回看"场景在怎么变好"、指认"从哪一版开始不对"——
+  这既是汇报资产，也是回滚参照。
+
+## 泛化提醒
+
+面板 + Copy JSON 模式不限于 3D：视频调色（DaVinci）、排版风格、动画曲线
+都适用。套路固定：**Agent 造面板 → 人拖到满意 → Copy JSON → Agent 固化 → 删面板**。

package/references/critic-protocol.md

@@ -0,0 +1,79 @@
+# E：四机位 Critic 验收循环（默认必开）
+
+> 原理："迭代到好看"没有终止条件，模型会提前自我满意。
+> 协议化 = 固定机位 + 固定缺陷清单 + 数值门槛，把"好看"变成可判定的工程量。
+
+## 场景必须实现的调试参数（建场景第一天就写进去）
+
+- `?clean=1`：隐藏全部 UI/滑杆/HUD/水印。评分画面里出现按钮即废片。
+- `?cam=overview|detail|low|wireframe`：四个标准机位——
+  | 机位 | 看什么 |
+  |---|---|
+  | overview | 3/4 俯视，整体构图与布局 |
+  | detail | 特写，表面细节与纹理质量 |
+  | low | 低机位仰视，物体是否落地、有无悬浮 |
+  | wireframe | 线框视图，证明几何干净、暴露穿插 |
+
+  实现：`URLSearchParams` 读取后设置 camera.position/lookAt 与 `material.wireframe`；
+  机位定义写进场景 README（描述性参数，不是硬编码像素）。
+
+## 循环步骤
+
+1. 起本地服务，用 `ego-browser` 技能逐机位截图，存 `_review/r{n}/cam-<机位>.png`。
+2. **派独立 Critic 子代理**（Agent 工具，general-purpose），提示词要求它：
+   - Read 全部 4 张截图，逐机位打分并给总分 /10；
+   - **列出 ≥3 个具体视觉缺陷**——方块感、悬浮、阴影裁剪、材质扁平、比例失真、
+     UV 拉伸、颜色脏……每个缺陷指明在哪个机位、哪个位置；
+   - 输出 verdict JSON（schema 见下）；
+   - 明确告知它："你的价值在挑剔，礼貌性放水的 Critic 没有存在意义。"
+   - 注意：用 general-purpose 直接 Read 图片；**不要用 visual-judge**
+     （它只负责文档类交付物的验收，不收 3D 截图）。
+3. 总分 <9.0：主线修复**全部**列出缺陷 → 回到 1（轮次 +1）。修复前先对照缺陷 registry 逐条复验：上轮修复项逐条确认（复发项标注 regressed，双倍权重），再处理本轮新缺陷。
+4. 总分 ≥9.0：把 verdict 与 4 张图给用户过目 → 进下一阶段。
+5. 每轮同步更新 `_review/progress.html` 画廊（标题带轮次号与一句话说明）。
+
+## 量化对照与缺陷回归追踪（B0 验收线的执行端）
+
+**量化对照**：每轮验收截图必须与 PLAN.md 的量化验收线（B0 从靶图实测：中位亮度/p95/sat>0.7 占比/暗部占比）同口径测量对照。探针：页内 `renderer.render` 后 `drawImage` 到 2D canvas 取直方图（WebGL 画布合成后清空，必须同步重渲再取样）。判定：中位差 ±20% 内合格；死黑/过曝/饱和类缺陷以数字为准，不接形容词。
+
+**缺陷回归追踪（flaw-registry）**：缺陷清单持久化为 `_review/flaw-registry.json`。每轮 Critic 的工单必须包含【复验区】（上轮全部修复项逐条列出）与【新扫描区】。规则：新缺陷 ≥3 条或逐条确认零缺陷；**修复项复发 = regressed，双倍权重**。闭合的项标 verified 留档——registry 是打地鼠的解药。
+
+**平台期协议**：连续 2 轮 |Δoverall|≤0.2 → 强制产出根因分类卡（残余缺陷归入参数类/比例类/资产类/构图类 + 各类预估轮数）提交用户决策；同时切换单类别纪律（每轮只动一类，主编直接改，不派子代理）。三种策略连续失效即定稿交付 + backlog。
+## verdict JSON schema
+
+`overall` = **四机位最低分**（短板定生死，不做平均——一个 5 分的机位不该被
+三个 9 分拉平）。达标线：overall ≥ 9.0。
+
+```json
+{
+  "round": 3,
+  "scores": {"overview": 9.0, "detail": 8.5, "low": 9.2, "wireframe": 9.4},
+  "overall": 8.5,
+  "flaws": [
+    {"view": "detail", "where": "桥栏杆", "what": "木纹 UV 拉伸"},
+    {"view": "low", "where": "左侧石灯笼", "what": "底部悬浮约 0.02m"},
+    {"view": "overview", "where": "水面", "what": "高光过曝成纯白"}
+  ],
+  "verdict": "REJECT"
+}
+```
+
+## 缺陷的处理规则
+
+- overall < 9.0：`flaws` 全部必修，修完复拍（轮次 +1）。
+- overall ≥ 9.0：循环停止，但该轮列出的缺陷**不静默丢弃**——随 verdict 一并
+  呈给用户，由用户挑哪些进 backlog 顺手修。达标即停，不为了凑分空转。
+
+verdict 落盘为 `_review/critic-r{n}.json`。连续 2 轮 overall 无提升即触发停机条款
+（见 grill-goal.md 的 goal 宪章），带着差距分析找用户，不要无限空转。
+
+## 与玩法相机的关系
+
+`?cam=` 是**验收机位**，优先级最高：带该参数时直接覆盖玩家相机。
+实现顺序：URL 参数 > settings.json > 场景默认玩法相机；验收截图会话结束即恢复
+默认玩法相机，两者互不污染。
+
+## 人工变体（无子代理预算时）
+
+把 4 张截图直接发进会话请用户批评指正。用户反馈逐条记入缺陷清单，
+与 Critic 缺陷同等对待——修完复拍再请验。

package/references/fx-recipes.md

@@ -0,0 +1,68 @@
+# 氛围 FX 食谱（雨 / 蒸汽 / 湿地 / 布料 / 灯影）
+
+> 参数全部经过 Critic 验收实战。每条含**已知缺陷与改进方向**——用前先看缺陷，
+> 别重复交过的学费。通用规则：所有 FX 对象标 `userData.isFx = true`
+> （wireframe 机位隐藏 + bbox 审计剔除——光和雾不是实体）。
+
+## 雨（三层 instanced 线）
+
+- **配方**：远层 520 根（宽 0.005 / 长 0.22 / opacity 0.15，z<-2.5）、
+  中层 180（0.008 / 0.30 / 0.22，全域）、近层 24（0.011 / 0.50 / 0.18，z>1.5）；
+  角度基准 0.17rad ±0.04 扰动；远层整组正弦风携平移 ±0.3。
+- **落点排除**：棚顶投影区（外扩余量）做全高拒绝采样——雨丝整根不得穿入棚下，
+  否则"棚下避雨"逻辑穿帮。
+- **已知缺陷（r51）**：等宽等亮白棒、末端 bloom 圆头像划痕、无落地溅点/涟漪、
+  近远差异读不出来。
+- **改进方向**：近层再减量加长、末端不做圆头（改渐隐）；地面加涟漪环
+  （RingGeometry 静态圈 + M4 动态扩散）；雨帘竖片（canvas 细线纹理）补空气感。
+
+## 蒸汽（多层噪声 alpha 交叉平面）
+
+- **配方**：6-8 片 PlaneGeometry 竖片绕 y 等角错开（22.5°），从锅口叠到棚下
+  （高 1.1-1.3），alpha 下浓上淡（0.5→0.06）、下窄上宽；canvas 画絮状烟形
+  （软团堆叠 + destination-out 内部镂空）；MeshBasicMaterial 暖白不吃灯光。
+- update()：绕 y 慢旋（0.03 rad/s）+ 透明度呼吸（±10% 错相）。
+- **已知缺陷（r51）**：近景读作"白色实心柱/棉团"，边缘发硬挡住暖帘文字，
+  量感与锅口不匹配；不吃暖光。
+- **改进方向**：体积化——多层噪声 alpha + 顶点漂移动画；或 SpriteStack；
+  与锅口对位要精确（Blender 出的锅位置变了必须同步）。
+- **明令禁用**：一列同尺寸圆 sprite 叠堆（读作"发光圆头糖葫芦"）。
+
+## 湿地（Reflector 真镜面 + 覆盖层）
+
+- **配方**：Reflector(PlaneGeometry, {clipBias:0.003, 512RT, color:0x55647a})
+  + 半透明沥青覆盖层（MeshStandardMaterial, transparent, opacity 0.62-0.68）；
+  覆盖层 **alphaMap 在"水洼"处更透明** → 真实倒影从洼里透出。
+- **性能**：Reflector 内建逐帧重渲病态耗时（13×降速）——512RT +
+  `onBeforeRender` 4Hz 节流（静态观感无损），节流后 35fps 可用。
+- **已知缺陷（r51）**：覆盖层 0.62 仍太不透明 → 倒影不可读，读作哑光黑板；
+  水洼 alpha 洞位置必须**对位光源正下方**（灯笼/霓虹/贩卖机各一处），
+  放错位置就是无源光斑。
+- **改进方向**：覆盖层降到 0.5-0.55；水洼洞逐一对位光源；配竖向灯影拉丝
+  （竖向渐变贴图 additive，从光源正下方拖向观者 2.2-2.7 长）。
+
+## 竖向灯影拉丝（湿地倒影的画龙点睛）
+
+- **配方**：PlaneGeometry 竖条 + canvas 竖向渐变 alpha（上下渐隐 + 横向 soft
+  destination-out），MeshBasicMaterial AdditiveBlending，铺在光源正前方的地面上，
+  从光源位置拖向观者 1.7-2.7 长、0.15-0.55 宽，opacity 0.10-0.31，isFx。
+- 每处主要光源一条：灯笼×2、摊内主光、霓虹、贩卖机——**必须对位真实光源**，
+  无源拉丝会被 Critic 点名"像嵌进地面的霓虹管/舞台追光"。
+
+## 布料（暖帘/旗帜）
+
+- **配方**：PlaneGeometry 多段细分（5×4）+ 顶点 z 扰动（正弦×两频率，
+  越靠下振幅越大）+ 底缘 sin 波浪剪裁；材质 DoubleSide；挂点用小圆柱横杆 +
+  细吊绳可见。
+- **已知缺陷（r51）**：掀幅翻过横杆后背面是纯黑板（材质替换后忘了背面），
+  缝线与字缘相切。
+- **改进方向**：掀幅背面用同色系深一档的"衬布里"材质；幅间加缝线明度差；
+  布面加法线扰动或细密织纹 alpha。
+
+## 灯影光晕（sprite）
+
+- **配方**：径向渐变 canvas → SpriteMaterial（AdditiveBlending,
+  depthWrite:false），标 isFx。
+- **已知缺陷**：近距强光下的 sprite 会被 bloom 二次放大成"火球/白圆头"。
+- **修法**：sprite opacity 与 bloom strength 联动预算——bloom 0.15 时 sprite
+  opacity ≤0.4；宁可欠一点，bloom 会补。

package/references/grill-goal.md

@@ -0,0 +1,67 @@
+# A+C：先拷问对齐，再自治执行
+
+> 原理：长时自治执行非常"用力"——方向错了，错的不是一段代码，而是一整段算力。
+> 花几分钟锁定创意方向，保证后面所有长时努力都花在用户脑中的那个愿景上。
+
+## A1. 收集视觉参照
+
+- 用户有照片/草图/环拍视频：直接收下，存 `concept/refs/`。
+- 用户没有：先做桌面研究——目标物体的结构、比例、典型材质、常见光照条件，
+  产出 `concept/research.md` + 参考图（WebSearch/WebFetch 或用户提供）。
+- **关键动作：先出 2D 概念图，再写 3D。** 首选用 `tokengo-cli` 技能生成 3-5 张
+  概念渲染图（付费，先确认数量与用途），存 `concept/mocks/`，连同研究笔记一起给用户审。
+  2D 概念图是对齐光照/尺度/氛围最快的方式。
+**参考图量化统计（有参考图时必做）**：对参考图跑亮度/色彩统计——中位亮度、
+p95、sat>0.7 像素占比、暗部（luma<0.08）占比、主色聚类。这些数字写入 PLAN.md
+作为**量化验收线**：后续每轮 Critic 截图同口径测量对照，死黑/过曝/饱和以数字
+判定，不接形容词。探针：页内 `renderer.render` 后 `drawImage` 到 2D canvas 取
+直方图（WebGL 画布合成后清空，必须同步重渲再取样）。
+- **降级路径**（用户拒付 / 未授权图像生成 / 服务不可用）：改为产出**文字版艺术方向圣经**
+  （`concept/art-bible.md`：基调一句话、色板 hex、光照方案、材质清单、尺度表），
+  附一张手绘 SVG 构图草图，给用户签核——便宜，但同样把方向钉在写代码之前。
+
+## A2. 拷问（grill）
+
+写任何 3D 代码之前，用 AskUserQuestion 分批问清（每批 ≤4 问，通常 1-2 批）：
+
+1. **相机**：第一人称 / 追尾 / 固定机位 / 自由环绕？
+2. **尺度**：真实米制还是风格化比例？主角多大、参照物多大？
+3. **交互**：可玩（控制什么）/ 可点击 / 纯观赏？可玩的话，手感类验收写进
+   PLAN.md 里程碑（如"用户试玩确认漂移手感"），几何/物理则走 D 阶段机检；
+4. **光照氛围**：时间点、色温、情绪（清晨冷调 / 黄昏金调 / 霓虹夜）？
+5. **参照物处理**：照搬实物还是风格化？
+
+用户说"你看着办"也必须给出你的默认方案让他确认一次，不许静默跳过。
+AI Studio 式的等价说法（用户在 Build 类产品里）："先问我关于计划的问题，再动手"。
+
+## A3. 写 PLAN.md（模板）
+
+```markdown
+# PLAN: <项目名>
+## 愿景（一句话）
+## 里程碑
+| # | 里程碑 | 验收标准（可机检/可截图） | 依赖 |
+|---|---|---|---|
+| M1 | 地形+网格 | ?cam=overview 截图，网格对齐地面 | - |
+| M2 | 道具分区 | audit JSON 零穿插零悬浮 | M1 |
+| M3 | 光照氛围 | Critic ≥9.0（detail 机位过）+ 量化线达标（中位亮度/暗部占比 vs 靶图 ±20%） | M2 |
+## 风险与降级
+## 纹理制备清单（哪些图像生成、哪些程序化；付费量预估）
+```
+
+验收标准写"可机检/可截图"的具体判据，不写"做好看一点"。
+
+## C. 起草 goal 宪章，再开跑
+
+不要自己憋长任务指令——**让主线 Agent 起草，用户批准一次**，之后一路执行不再逐事请示。
+宪章内容：
+
+- **授权范围**：允许自治改哪些文件、跑哪些命令、图像生成次数上限。
+- **停机条件**：Critic ≥9.0 达标 / 全部里程碑通过 / 连续 2 轮无改进。
+- **汇报点**：每个里程碑更新 progress.html 后暂停等用户，或声明全自动。
+- **例外**：破坏性操作（删文件、覆盖非本项目产物）和付费操作仍需逐次确认。
+- **平台期协议**：连续 2 轮 |Δoverall|≤0.2 → 强制根因分类卡（残余缺陷归入
+  参数类/比例类/资产类/构图类 + 各类预估轮数）提交用户；同时切换单类别纪律
+  （每轮只动一类，主编直接改）。三类策略连续失效即定稿交付 + 按杠杆排序的 backlog。
+
+宪章批准后执行中途不复读计划、不重复请示；只有例外项停下来问。

package/references/grounding-2d.md

@@ -0,0 +1,53 @@
+# B：用 2D 图纸锚定比例（空间精确时）
+
+> 原理：在 3D 里凭感觉挪坐标又慢又容易比例漂移；先在 2D 里把布局钉死，
+> 用户确认后再拉伸成 3D，返工成本低一个数量级。大多数程序化场景不需要本阶段。
+
+## 何时启用
+
+- 真实世界主体要高精度还原（建筑、地标、实物复刻）。
+- 多室 interiors、复杂平面布局（房间/柱列/通道关系要压准）。
+- 空间上很难凭直觉做对的场景（多物体精确咬合、严格对称）。
+
+## 方法一：俯视平面图（复杂布局）
+
+1. Agent 生成 `.svg` 俯视图，**带米制标注**（每个主要元素的尺寸与位置）。
+2. 给用户确认布局 → 确认后按图拉伸/挤出成 3D。
+3. **平面图的坐标系就是 3D 世界坐标系**：原点、朝向、比例保持一致，
+   之后所有分区子代理都以这张图为共享契约（配合 parallel-forge 的 world-spec.md）。
+
+## 方法二：照片叠网格（从照片读比例）
+
+给参考照片叠编号 X/Y 网格，逐格读出各元素的比例与对齐关系，再建模：
+
+```python
+from PIL import Image, ImageDraw
+img = Image.open("concept/refs/ref.jpg"); d = ImageDraw.Draw(img)
+W, H = img.size; N = 12
+for i in range(N + 1):
+    x = W * i / N
+    d.line([(x, 0), (x, H)], fill=(255, 0, 0), width=2)
+    d.text((x + 2, 2), str(i), fill=(255, 255, 0))
+for j in range(N + 1):
+    y = H * j / N
+    d.line([(0, y), (W, y)], fill=(255, 0, 0), width=2)
+    d.text((2, y + 2), str(j), fill=(255, 255, 0))
+img.save("concept/refs/ref_grid.jpg")
+```
+
+建模时在回复里逐条写"第 i 列第 j 行是什么"，让用户能对着网格图核对。
+
+## 方法三：反算相机（1:1 复刻照片构图）
+
+要从照片 1:1 还原时，**先对机位，后建景**：
+
+1. 从照片反算：相机俯仰角、地平线在画面中的位置、视场（由灭点间距/线条收敛估计）。
+2. 先把 3D 相机调到与原照片一致的机位（对比截图确认）。
+3. 再往相机里填内容，直到任意机位都与原照片构图吻合。
+
+反着来（先建景再对机位）必返工。
+
+## 铁律
+
+- 平面图/网格图也是验收物：存 `concept/`，**用户确认后才许建 3D**。
+- 比例漂移的早期信号：两个物体的相对大小与参照图矛盾 → 立即回查平面图，不要在 3D 里硬调。

package/references/parallel-forge.md

@@ -0,0 +1,69 @@
+# D：并行子代理分区建造
+
+> 原理：3D 世界由大量互相独立的件组成（地形/建筑/植被/道具/光照/物理/UI）。
+> 单 Agent 串行写一个大文件又慢又容易互相踩；按分区并行、契约合并，又快又好。
+> **资产密度规律**：串行建造的细节深度有硬上限——专职代理 + 独立上下文预算才
+> 做得出围裙背带、品牌灯箱、粉笔价目这个层级的细节。实战：串行卡 7.0 平台期
+> 4 轮，4 代理并行后单轮 +0.2~0.4。
+
+## 何时用（强制规则）
+
+- **场景类项目默认强制**：标准四分法（主体/核心资产、环境与建筑、地台与前场
+  道具、氛围与光照）**≥4 子代理并行**；少于 4 须在启动消息中显式申请理由——
+  "静默单线程"是本技能的已知失败模式，不要等用户提醒。
+- 世界能切 **≥3 个低耦合分区**时用。2-3 个小物件不值得，直接主线写。
+- **豁免**：平台期单类别打磨轮（见 critic-protocol.md 平台期协议）由主编直接改，
+  不派子代理——为改一盏灯的强度派 4 个代理是纯开销。
+- 详细分区分类学、《分区契约》模板、合并关口细则 → **`parallel-zones.md`**（本文件
+  的升级版，含实战 brief 实例与踩坑记录）。
+
+## 切分原则
+
+- 按**空间分区或模块边界**切，不按"步骤"切（"先建模再打光"是步骤，不是分区）。
+- 每个分区有明确的文件归属 `src/<module>/` 和对外接口（导出什么、被谁调用）。
+- 先写 `world-spec.md`（共享契约），内容：
+  - 世界原点、朝向、单位（米 or 场景单位）、上方向；
+  - 地面定义（平面高度或高度函数签名）；
+  - 公共材质/纹理命名约定与目录（`assets/textures/`）；
+  - 场景装配入口（谁负责把各模块 add 进 scene）。
+
+## 执行
+
+1. 主线写完 `world-spec.md` + `PLAN.md` 后，**一条消息里并行发多个 Agent 工具调用**
+   （subagent_type: general-purpose），即并行。
+2. 每个子代理提示词包含：分区范围与清单、文件归属、`world-spec.md` 路径、
+   自测要求（自己起本地服务、截自己分区的图自检能看）。
+3. 子代理**只建自己的分区**，不改共享文件；需要新共享资源（材质/纹理）时写进
+   自己目录的 `NEEDS.md`，合并时由主线统一处置，避免并发写冲突。
+
+典型分区示例（Desk Racer 式）：桌面与道具建筑师 / 赛道与物理工程师 /
+光照氛围与 HUD 集成师 / 纹理绘制师（图像生成类工作单独一个代理）。
+
+## 合并 + 几何审计（合并是关口，不是打包）
+
+主线合并所有分区后，**先跑几何审计，再进 Critic 循环**：
+
+- **穿插检测**：静态物体两两 AABB 粗筛 + `three-mesh-bvh` 精查；
+  或在场景里实现 `?audit=collide` 页内模式，遍历输出 JSON。
+- **悬浮检测**：从每个物体底部向下打射线，到地面距离 ≈ 0 才合格
+  （容差按场景尺度定，写进 world-spec）。
+- 输出 `_review/audit-r{n}.json`：
+  ```json
+  {"round": 1, "checked": 68, "intersections": [], "floating": [],
+   "tolerance_m": 0.005, "method": "AABB+bvh"}
+  ```
+- 有红字先修完再进 E 阶段。**"看上去行"不算数——穿插要机检证明为零。**
+
+（本条来自实战教训：68 根过山车立柱全部与桌面和道具严丝合缝零穿插，
+靠的是合并阶段的数学相交检查，不是任何人的目测。）
+
+## 合并后再加两道关口（雨夜屋台实战补充）
+
+1. **四机位截图人检**：机检零穿插 ≠ 画面成立——缓存（CDP setCacheDisabled）、
+   材质重定向、光照层都会在机检之外出问题。
+2. **语义豁免规则**：合法接触（伞沿搭凳沿）进 ALLOWED 白名单必须注理由；
+   光晕/FX sprite 从 bbox 审计剔除（光不是实体）；斜置薄墙走 OBB 精判。
+   细则见 `pitfalls-threejs.md` 第 7 条。
+
+其余合并与审计细节（OBB/AABB 混判、语义豁免全表、四分法分类学）见
+**`parallel-zones.md`**。

package/references/parallel-zones.md

@@ -0,0 +1,77 @@
+# D：强制并行分区建造（分区契约 + 合并关口）
+
+> 原理：单 Agent 串行建造的资产密度有硬上限——每个分区的细节深度（围裙背带、
+> 品牌灯箱、粉笔价目）只有"专职代理 + 独立上下文预算"才做得出来。实战数据：
+> 同一项目，串行建造在 Critic 7.0 平台期卡 4 轮，改 4 代理并行后单轮 +0.2~0.4。
+>
+> **本阶段强制执行**：场景类项目一律 ≥4 子代理并行；少于 4 须在启动消息中显式
+> 申请理由（"静默单线程"是本技能的已知失败模式）。平台期单类别打磨轮豁免——
+> 那时由主编直接改（见 critic-protocol.md 平台期协议）。
+
+## 1. 标准四分法（默认分区，允许增补，不得少于 4）
+
+| 分区 | 职责 | 典型内容 |
+|---|---|---|
+| ① 主体/核心资产 | 视觉中心的完整建造 | 主建筑/载具/摊车 + 其上的核心道具与人物 |
+| ② 环境与建筑 | 主体之外的世界 | 建筑墙/街道纵深/邻里道具/叙事小件 |
+| ③ 地台与前场道具 | 基底与前景 | 地台切面/地面材质/水洼/前景道具群 |
+| ④ 氛围与光照 | 空气感与光 | 雨/雾/蒸汽/粒子/灯光氛围/环境贴图 |
+
+- 分区按**空间或模块边界**切，不按"步骤"切（"先建模再打光"是步骤）。
+- 判断标准：每个分区是一个子代理一个独占文件（`src/zones/<zone>.js`），
+  两个分区之间除 ctx 契约外零共享状态。
+- 小场景也照切——四分法对几乎所有场景类项目通用；确需合并两区时在启动消息
+  显式说明。
+
+## 2. 《分区契约》（world-spec.md，派工前必须完成）
+
+主线在派工前写好并让所有子代理只读引用：
+
+```markdown
+# 分区契约
+## 坐标系
+- 世界原点/朝向/单位；+z 朝观者（或注明）
+- 地台范围（如 10×10，顶面 y=0）
+## 边界框
+- 各分区占用区域（防止越界；例：①主体 x -4.9..0.2, ②环境 x 0.8..4.9）
+## 共享资源
+- 色板常量（hex 表）、材质工厂函数签名、贴图工具
+- 命名规范：材质名前缀（O_/P_/区域前缀）、对象命名
+## 机检注册
+- AUD 注册键清单（谁注册什么键）+ 语义豁免（FLOOR/MOUNTED/ALLOWED，须注理由）
+## 跨区依赖
+- 例：③前场的凳子须面对①主体的柜台前缘（柜台前缘世界 z=1.82）
+```
+
+## 3. 子代理 brief 模板
+
+每个子代理的提示词必须包含：
+
+1. **独占文件**（只许改这一个）+ 只读上下文清单（契约/规范/靶图路径）
+2. **本区工单**：验收要点逐条列出（来自 Critic 缺陷清单或 PLAN）
+3. **硬约束**：底座边界、落地判据（min.y ≤ 容差）、色板限制、禁外部资源、
+   文字用 canvas 手绘（原创，无真实品牌）
+4. **自检要求**：语法检查 + 自己起服务截自己分区的图自检
+5. **交付格式**：改动摘要 + 新增 AUD 注册键 + 需要的 ALLOWED 豁免（注理由）
+6. **禁项**：不跑全局验收截图（主编合并时统一拍）；不改其他分区文件与共享文件
+
+## 4. 合并关口（合并是关口，不是打包）
+
+主线合并全部分区后，**按序过三关，全过才准进 E 阶段 Critic**：
+
+1. **机检审计**：`?audit=1` 输出 JSON——零悬浮/零出界/零穿插
+   （OBB 精判几何体 + AABB 组混判；语义豁免 FLOOR/MOUNTED/ALLOWED 须注理由）。
+   注意把 FX sprite/光晕从包围盒剔除（光不是实体，会虚假撑大 bbox）。
+2. **四机位截图**：`?clean=1&cam=四机位`，逐张人检 + 查 `window.__errs` 为空。
+   **缓存警告**：模块改动后浏览器会吃缓存——ego-browser 必须
+   `CDP Network.setCacheDisabled`，否则改了等于没改（本轮白跑）。
+3. **跨区冲突修复**：位置越界/风格漂移/重复道具在合并层修，修完重跑 1-2。
+
+## 5. 实战记录
+
+完整实例见 ramen-yatai（雨夜屋台）：四分区 brief、摊车 ×1.12 后的全链坐标
+重排、三轮合并关口记录。已知坑：
+- 摊车缩放后，凳/伞/自行车/水洼 alpha 全链坐标要重排（缩放原点变了）；
+- 人物/道具的"支撑关系"（伞沿搭凳沿）在 bbox 审计里是合法接触，进
+  ALLOWED 白名单时必须注理由，否则下一轮会被人当成穿模重修；
+- 各区自建的光效 sprite 记得 `userData.isFx`，wireframe 机位与 bbox 审计都靠它。

package/references/pitfalls-threejs.md

@@ -0,0 +1,71 @@
+# three.js 渲染坑检查清单（症状 → 探针 → 修法）
+
+> 每条都来自实战烧轮数的坑。出现同类症状时**先查这里再动手**，每条坑平均烧 1-2 轮验收。
+
+## 1. 人物/对象全体隐身，只剩描边壳或黑块
+- **症状**：新建的对象屏幕上不可见（或只剩黑色 outline 壳），wireframe 里也看不到网格。
+- **探针**：`camera.layers.mask` vs `object.layers.mask`——light/camera 默认只在 layer 0。
+- **修法**：对象用了 `layers.set(n)` 做光照分离时，**camera 必须 `layers.enable(n)`**；
+  照亮它的每盏灯也要 `layers.enable(n)`；不想被某盏灯照的对象则 `layers.set(n)` 排除。
+- **教训**：人物光照分离（layer 2）做了，camera 没开 layer 2 → Critic 看到的是
+  黑描边壳，白烧 2 轮（r46）。
+
+## 2. GLB 动态导入静默失败，模块卡死在 await
+- **症状**：`GLTFLoader.loadAsync` 永不 resolve，页面无 canvas、无报错
+  （静态导入缺文件时连 error 事件都不触发）。
+- **探针**：`performance.getEntriesByType('resource')` 看 .js/.glb 是否全部 200。
+- **修法**：GLTFLoader 不只一个文件——`utils/BufferGeometryUtils.js` 与
+  `utils/SkeletonUtils.js` 是它的相对依赖，vendor 时必须一起拷。
+- **教训**：与 GLTFExporter（缺 `utils/TextureUtils.js`）同一类坑。
+
+## 3. 材质重定向不生效 / 颜色和预期不符
+- **症状**：`retarget`/材质替换后对象仍是原色，或暗 albedo 渲染成米白。
+- **探针**：遍历 scene 读 `material.color.getHexString()` + `material.name`
+  （Blender 导出的 GLB 材质名可能为空，名字映射会失配——改用**保留 GLB 自带色
+  toon 化 + 亮度分压**：亮部轻压 0.8、暗部重压 0.15）。
+- **修法**：暗 albedo（0.05）在 50+cd 近距灯下照样被 toon 满格抬成米白——
+  要暗剪影就**光照层隔离**（对象不进主光层）+ 专属低强度补光，别指望压 albedo。
+
+## 4. Reflector（镜面湿地）把帧率打到 1-3fps
+- **症状**：加 Reflector 后 fps 从 40+ 崩到个位数。
+- **探针**：`mirror.visible=false` 前后各测 fps 差值。
+- **修法**：textureWidth/Height 降到 512 + **onBeforeRender 4Hz 节流**
+  （静态观感无损）。节流后 35fps 可用。
+
+## 5. bloom 阈值"不生效"——白布也发光
+- **症状**：把 UnrealBloomPass threshold 提到 1.0+，受光的白布/锅沿照样 bloom。
+- **原因**：composer 渲染在 **linear 空间**，白布被 50cd 灯照后的 linear 亮度
+  轻松超过 2——阈值选择性对"受光面"失效，只对真自发光（emissive ≥2）有效。
+- **修法**：接受"低强度全局 halation"路线（strength 0.15 / radius 0.4 /
+  threshold 0.8），物体级发光靠 emissive+sprite 自控。
+
+## 6. 暗色对象在强光下读作米白（toon 饱和）
+- **症状**：albedo 0x16161d 的剪影人物渲染成米色团块。
+- **原因**：MeshToonMaterial 输出 = albedo × 满格阶梯光，近灯 irradiance 巨大，
+  暗色也饱和到灯色。
+- **修法**：三选——layer 隔离（不进主光层）+ 专属弱补光；压灯强度；
+  albedo 再压暗（有下限，0.04 以下无感）。
+
+## 7. bbox 审计误报：光晕撑大包围盒 / 斜墙 AABB 虚假膨胀
+- **症状**：审计报"穿插"，wireframe 看不到任何接触。
+- **修法**：审计函数**跳过 sprite/isFx 节点**（光晕不是实体）；有几何体的对象用
+  OBB（matrixWorld 逆变换到局部空间判定），Group 退回 AABB；斜置薄墙必须走 OBB
+  否则 AABB 角点虚假相交。合法接触（伞沿搭凳沿）进 ALLOWED 白名单时**必须注理由**。
+- **附带**：`Object3D.layers` 是渲染遮罩位，不是"子层"——取 Group 子层用 `.children`。
+
+## 8. 改了模块代码，浏览器跑的还是旧版
+- **症状**：改完 src/*，截图行为/外观没变化，本地 curl 却是新内容。
+- **修法**：ego-browser 截图会话必须
+  `page.cdp('Network.enable') + page.cdp('Network.setCacheDisabled', {cacheDisabled:true})`。
+- **附带**：python http.server 单线程易死——截图脚本前加守卫重启。
+
+## 9. WebGL 画布取像素全黑
+- **症状**：`drawImage(webglCanvas, ...)` 到 2D canvas 取直方图，全 0。
+- **原因**：WebGL 画布合成后缓冲清空（无 preserveDrawingBuffer）。
+- **修法**：取样前**同步** `renderer.render(scene, camera)` 再立即 drawImage
+  （同一 JS task 内缓冲有效）。
+
+## 10. Windows 下 node -e 内联脚本被反引号/中文坑
+- **症状**：`node -e "…template literal…"` 报语法错误或变量被 shell 吞。
+- **修法**：多行/含反引号/含中文的补丁脚本**落成 .cjs 临时文件**执行
+  （package.json type:module 时 .js 会被当 ESM，require 不可用）。

package/references/target-render.md

@@ -0,0 +1,30 @@
+# G：靶图逼近（照片级停滞时的破局）
+
+> 原理：在黑暗中调光照/材质数字容易停滞——模型缺一个**与当前机位完全一致的
+> 视觉靶**。先用图像模型生成这个靶，再让真实 3D 代码去追它，
+> "调好看"就变成了可判定的"追平差异清单"。
+
+## 步骤
+
+1. **拍干净靶本**：`?clean=1` 下抓 3-5 个关键机位截图（无任何 UI）。
+2. **生成靶图**（付费操作，先向用户确认数量；`tokengo-cli` 技能图像生成，
+   或用户提供实拍/效果图）——提示词模板逐字用：
+
+   > 把这张 3D 视口截图转换成照片级渲染：自然光照、真实表面纹理、大气纵深。
+   > **保持完全相同的相机角度、构图与建筑布局**，使它可以作为 1:1 视觉参考靶。
+
+   靶图存 `concept/targets/cam-<机位>.png`。
+3. **并排 diff**：把靶图 + 当前截图**成对**交给主线（或子代理），
+   逐项列差异：光照、阴影、表面纹理、植被、水面、大气——每项写明"靶图什么样、
+   当前什么样、差在哪"。
+4. **追靶**：按差异清单迭代升级**真实的几何、shader、材质、光照代码**，
+   每轮用 E 阶段四机位复拍比对，直到每个机位都追平。
+5. 追平后：控制面板参数固化进 `settings.json`，交付。
+
+## 铁律
+
+- **禁止把靶图贴进场景当背景/天空盒/贴图冒充完成**。
+  靶图是代码升级的参照物，不是素材。验收时用 wireframe 机位 + 相机移动检查即可揭穿。
+- 没有图像生成预算时：降级为用户找 1-2 张气质接近的实拍参考图，
+  走同样的 diff-追靶循环（靶不必完美，方向对就值钱）。
+- 靶图与当前画面的相机参数必须一致——机位漂移会让 diff 全部失真。