chore: checkpoint web Blender migration source, tools and docs

Accumulated uncommitted work: GHOST Web backend, WebGL/GPU web layer,
web workflow engine and protocol, tooling, docs and task records.
Large generated evidence, user-testing archives, build snapshots and
imported test assets remain untracked.

Co-Authored-By: Claude Code <noreply@anthropic.com>

AGENTS.md

@@ -15,6 +15,13 @@
 
 ## 移植铁律
 
+- **验证前置条件优先。** 验证时，先准备前置条件，之后再验证；前置条件准备也必须考虑依赖关系和先后顺序，以提高验证的准确性和效率。按依赖顺序准备构件与资源、运行环境、服务与接口、数据与场景；前置条件不满足时先补齐，不重复运行依赖它的下游验证。复用仍有效的前置检查结果，环境或依赖变化后仅重新检查受影响项；如实记录缺项、失败及验证范围。
+- **按合理的小批次推进。** 每批只处理一个明确业务缺口及其必要调用链；单次读源码≤30行、修改≤2文件且增删合计≤10行（含交接）。按实际字节控制提交提示、交接与工具输出，区分已统计内容与系统附加内容；断流/超量后缩小下一批，连续稳定交接后才有界放宽。达到预算先保留源码与continuationNotes（断点、已完成、残余、下一动作）再续接，禁止堆叠全量历史、盲目重发大包或靠删缺口缩量；不改变实现期禁止验证的规则。
+- **当前工作定位：用户明确“桌面 Blender → Web Blender 移植”基本完成，后续仅以补充具体功能缺口为主，不得重新开展整体移植或偏离主线。科学、高效率地充分复用已有源码、模块、适配接口、WASM 和应用产物，使操作者能使用全面完整的功能。**
+- 领取任何补缺工作，先定位对应业务的已有实现和最新交接，只修改明确缺失、未接通或阻塞实际操作的环节。历史任务卡的 planned/in_progress、旧 remaining 或未验证状态，不得单独作为重新实现已有功能的依据；不得将补缺扩大成无关重构、重复造轮子或无限底层加固。
+- 无人值守执行者必须自行定位并处理空转、阻塞、冷却、反复重启、等待和遗漏，完成查缺补漏。每个问题必须对应具体原因、受影响的用户功能和下一修复动作；同一路径反复失败应改变有源码依据的修复策略，保留部分成果并继续可独立推进的缺口，不得只重复报告或盲目重启、重编译。外部限流或权限限制应如实分类并合理退避，不得绕过限制或伪称已解决。
+- “基本完成”是本阶段复用成果、聚焦补缺的工作定位，不等于所有功能已验证或验收通过。实际残余缺口必须保留并解决；不得通过删除缺口、调整统计、推进队列或编译成功来宣称完整可用。
+
 - 为了正常推进移植项目工作，用户已授权执行代理在无人值守流程中自主完成必要工作，包括自行修改 Blender 源码、Web/WASM 适配层、协议、Worker、前端入口、构建脚本和任务交接产物；无需为常规实现动作重复请求确认。所有修改仍须遵守本文件其余铁律，并如实记录未验证状态。
 
 - 功能先打通，只有全部功能实现完成后，用户才在使用时验证。全部功能完成是主要工作，中途不进行任何形式的验证，包括测试、回归、冒烟、浏览器验收、类型检查、独立语法检查、上下文检查和证据审计。优先复用本机源码和产物，集中实现真实业务入口；仅为生成所需产物进行增量编译，不把编译成功当作功能完成或验收通过。未验证功能如实记录，不得伪造通过结果。
@@ -29,3 +36,50 @@
 - 遇到问题先检索用户提供的 `blender-5.2.0` 对应源码，再查当前模块相关资料；源码行为优先于路由分类、前端近似实现或外部资料。
 - 源码检索使用聚焦工具，可通过 `--unit <source-unit-id>` 限定当前源码单元；禁止默认加载完整源码 inventory 或历史计划。
 - 计时、索引、构建和验证是执行保障，不能代替业务功能完成；报告必须说明工作流、具体功能路由及源码依据。
+
+## 工作方式铁律
+
+- **通过案例，找到缺口，完善程序，稳步实现项目桌面程序到 WEB 移植的完整功能。**
+  每个工作批次必须先落到一个具体的用户案例（桌面 Blender 可复现的操作路径或仓库内已有 fixture/对比案例），在 Chromium 中实走该路径，找出与桌面行为的真实差异；差异必须是用户可见的功能缺口，而不是测试口径、证据簿记或统计口径。找到缺口后直接完善程序实现，再继续下一个案例。禁止用「跑通已有 spec」「补充证据」「重绑覆盖率」替代功能推进。
+
+## 已验证的工作流（后续批次直接复用，不重新摸索）
+
+**一条案例的固定推进顺序**
+
+1. **选案例**：从 `blender-5.2.0/tests/files/` 取真实资产，按"桌面可复现的操作路径"定义，不造合成场景。
+2. **查源码**：先读桌面实现（operator exec、RNA 写路径、DNA 字段），确认桌面语义，再动 Web 侧。
+3. **走真实入口**：Chromium 里用产品自身入口（`blend-file-input`、菜单按钮、`__nativeWorkflowEngine`），不另建第二个 `/browser` 写者。
+4. **定位缺口**：行为差异必须用户可见；区分"我造成的回归"和"既有缺口"，必要时用 A/B（临时禁掉自己那行）判定。
+5. **最小修复**：改到能解释现象的那一处，优先扩展已有函数，不新增并行实现。
+6. **增量构建 + 同步**：`cmake --build build_web_blender6 --target web_engine -j8` → `node tools/web/sync-web-engine-runtime.mjs`；不要手工拷贝产物。
+7. **复测并留证**：结果写入该 case 的 validation，标 `NOT_CLAIMED`；绑定回执不得被复跑覆盖（写目标用 `WBV2_BATCH_PRODUCTION` 之类的可覆盖路径）。
+8. **交接**：continuation 记录断点/已完成/残余/下一动作，status 追加一节。
+
+**探针技法（已验证有效）**
+
+- 驱动 App 自己的 worker：`window.__nativeWorkflowEngine.postMessage({requestId, command})`，按 `requestId + kind==='result'` 收结果；`command()` 等 `__nativeWorkflowRequests/Responses` 增长。
+- 每次打开后等 `main.blender-app` 的 `data-project-id` 与 `engine-status` 含 `SceneIR`，否则会沿用上一个 Main 导致假结论。
+- 点击被原生画布遮挡时先 `exposeWebTools(page)`；保存要靠 `waitForEvent("download")`。
+- 状态判定用 `snapshot` 的语义摘要（剔除 `revision`）与 `saveBlend` 的 SHA-256 摘要分开比较，能区分"数据变了"和"仅序列化抖动"。
+- 判断某分支是否真的执行，用能留痕的副作用（场景名、输出行、打印），不要只看返回 ok。
+- 源码/产物一致性用 `grep -a` 查二进制；`cd` 后相对路径会失效，一律用绝对路径或每批重新 `cd`。
+
+**判定原则**
+
+- 首次调用与后续调用不等价时（一次性运行期初始化），比较"相邻两次重复操作"而不是"前后各一次"。
+- 放宽守卫必须配反向用例：构造真实违规路径，确认仍被拒绝。
+- 编译通过、探针 ok、单 case 通过都只是证据素材，不是验收通过，不给整体完成度。
+
+## 主线铁律（最高优先）
+
+- **唯一主线：把桌面 Blender 的既有功能移植到 Web，让用户能在浏览器里真实操作。** 任何批次的产出都必须落在这条线上：真实的用户入口、真实的原生执行、真实的读回与撤销。
+- **不发散探查。** 不为「查覆盖率」「查声明是否符合」这类台账问题开批次；不连读多看源码只为准确定位一个函数；不为疑似缺口编写大量探针。源码只需读到能改对那一处为止。
+- **每批只做一件事：** 一个用户可见缺口 → 一处原生/前端修复 → 一次编译同步 → 一条有界 Chromium 复测 → 断点落盘。做完即收尾，不顺手扩范围。
+- **方向（2026-11-01 用户书面确认，最高优先）：不做单条失败用例的考古式推进。** 按「盘点已实现能力 → 打包候选 → 全模块实测 → 只修真实阻塞」推进：先枚举现有可用入口、构件与用例并实际跑通，最大化复用已实现功能，尽快形成可验证、可上线的候选；只有实测暴露的真实用户功能阻塞才开修复批次，且一次只改到能解释现象的那一处。
+- **铁律 A — 资产优先，不重复实现。** 先盘清“已接通/已实现”功能清单，再谈缺口；已实现的功能直接复用，不重新走实现流程。队列、任务卡、continuation 只作为“证据来源与资产索引”，不作为推进节拍器。
+- **铁律 B — 阻塞分级，只修真实阻塞。** 失败分三类：真实功能缺陷 / 异步时序 / 测试误操作。只有第一类进入修复，后两类走证据纠正或测试修正，且需证据支撑。同一路径反复失败，先改源码策略，不盲目重跑、重启、重编译。
+- **铁律 C — 打包候选优先于逐例深挖。** 以冻结候选 `build_web_main_desktop/versioning-filepath-20261101` 为基线，按模块打包实测；不以单例通过替代模块结论，也不以单例失败阻塞全量盘点。单例深挖只在“该例阻塞某个模块整体验收”时才做。
+- **铁律 D — 证据必须绑定构件身份。** 正式候选测试绑定绝对路径与构件哈希；开发服务器结果不代替发布验收；不覆盖冻结候选与历史回执。本地 WASM 与原生后端分别记录，互不代替。
+- **铁律 E — 绝对路径 + 最小上下文。** 所有文件、库、构件、日志引用一律绝对路径；读取遵守本文件字节预算，不默认加载完整路线图、parity ledger、源码 inventory、全部历史日志。
+- **铁律 F — 不降标准达成“完成”。** 不删缺口、不缩承诺、不放宽断言、不跳必测项、不调统计。RUN、单例通过、编译成功、源码覆盖统计均不等于整体验收。
+- **缺口按用户能否触发排序。** 用户点得到但无效果 > 用户点不到 > 已接通待验证。台账、能力表、静态清单不与功能实现混在同一批。