workinf_Blender_Wasm/docs/CURRENT_EXECUTION_PLAN.md

Web Blender V1 当前执行计划

更新时间：2026-08-14

1. 交付目标

当前交付物是 Web Blender Modeler V1，不是 Blender 5.2 的完整浏览器移植。 V1 产品承诺、明确排除项和发布门以 WEB_BLENDER_MODELER_V1_SCOPE.md 为准。

浏览器基线仅为 Chromium。产品架构保持为：

React 工作区和编辑器
  -> versioned TypeScript protocols
  -> Web Workers
  -> Blender Main / Depsgraph WASM 子集
  -> binary SceneIR / Three.js WebGL 或 OffscreenCanvas viewport
  -> OPFS 大文件 + IndexedDB 元数据

本计划是当前唯一的短周期领取队列。长期 Blender 功能对标仍记录在 BLENDER_5_2_WEB_FEATURE_PARITY.md 和 status/parity-ledger.json，但不以长期全域差距 阻断已明确限定范围的 V1。

2. 文档与事实源

文件	唯一职责
WEB_BLENDER_MODELER_V1_SCOPE.md	V1 产品契约、支持矩阵、非目标、发布标准
CURRENT_EXECUTION_PLAN.md	当前任务顺序、最小任务、依赖和退出条件
PROJECT_STATUS_AND_NEXT_WORK.md	已实现能力、风险、验证命令总览
BLENDER_5_2_WEB_FEATURE_PARITY.md	Blender 5.2 全域长期差距
status/parity-ledger.json	功能域和 V1 slice 的机器事实
status/release-evidence.json	最近一次可审计发布证据快照

文档冲突时按上表职责解释；机器状态冲突时以校验脚本能够同时验证的 ledger 和 evidence 为准，不靠描述性文字覆盖失败结果。

3. 完成规则

3.1 最小任务规则

每个任务只产生一个主要行为变化或一个证据变化。任务状态只允许：

• [ ] 未开始；
• [~] 正在执行；
• [x] 已实现且验收通过；
• [!] 有可复现阻断，必须附命令、错误和解除条件。

不能仅凭协议存在、fixture 存在、UI 可显示或测试代码已写入，就把任务标为完成。

3.2 功能任务完成定义

适用项必须同时具备：

1. 正例使用生产代码路径，不在测试中复制另一套实现。
2. 非法输入、预算超限或未声明能力返回稳定结构化错误码。
3. Worker 可取消；取消后不得发布迟到结果。
4. 资源释放可观测；释放后 CPU/WASM/GPU/OPFS 临时占用回到预算内。
5. Main 或持久化状态修改必须经过 revision，验证 undo/redo、原子保存和重开。
6. 浏览器行为至少在 Chromium 生产配置验证；视口相关能力覆盖主线程和 OffscreenCanvas Worker，除非 V1 范围明确只承诺其中一个。
7. 独立验收命令退出码为 0，并产生至少一个与实现或测试绑定的 SHA-256。
8. 状态文档、ledger、evidence 和代码描述一致。

3.3 发布证据规则

release-evidence.json 中任何 true 字段必须：

• 由成功 evidence record 绑定；
• 记录实际命令、耗时、输出摘要和非空构件 SHA-256；
• 失败时不能保留过期成功状态；
• 不得用 mock、跳过、仅 schema 单测或只有 hash 格式校验替代真实运行。

4. 重新盘点后的事实基线

4.1 已完成工程基础

• React/Three.js 工作区、主线程 WebGL 与 OffscreenCanvas Worker 视口已存在。
• Blender 5.2 Main 子集已编译为 WASM，Worker/C ABI、结构化错误和内存统计已存在。
• .blend 导入、已声明编辑命令、undo/redo、保存、OPFS/IndexedDB、重启重开已形成闭环。
• 二进制 Mesh/非 Mesh SceneIR、range patch、LOD cache、GLB 和有限 USD 路径已存在。
• VDB desktop/server converter、HTTP range/OPFS、Float32 NanoVDB WebGPU、有限多 grid 材质、显式 resident LRU 和故障恢复已存在。
• 12 个 N-015 至 N-026 功能域的 Blender 全域 parityStatus 均为 BLOCKED；其 V1 required slice 的 releaseStatus 均为 READY。这两个状态轴不得再次合并。

4.2 2026-08-14 本轮复核结果

检查	结果
npm --prefix web run typecheck	通过
npm --prefix web run lint	通过
npm --prefix web test	9/9 通过
npm --prefix web run test:status-consistency	通过；12 parity blocked、0 release blocked
npm --prefix web run test:release-evidence	通过；17 records、0 missing、READY

4.3 真实发布缺口

当前 V1 release gate 已无 evidence 字段缺失，faults.oom 由独立 Chromium 四场景命令和 构件 hash 绑定。geometry1M、4K/8K texture、600 帧 simulation cache、断网、device loss、 恶意 blend、zip bomb、离线包和 V1 用户闭环仍须在 M5 全矩阵中持续回归。Blender 全域 parityStatus=BLOCKED 的长期差距不因 V1 gate READY 而关闭。

5. 里程碑总览

里程碑	交付物	状态	退出条件
M0 范围与状态模型	V1 契约、双轴 ledger、P0 用户闭环	已完成，持续回归	状态一致性与 V1 闭环通过
M1 当前工作区收口	VDB/WebGPU 与现有证据可复验	已完成，持续回归	静态门、VDB 全矩阵、V1 闭环全部通过
M2 10M geometry	大几何浏览器性能与恢复证据	已完成，持续回归	performance.geometry10M=true
M3 long media	长时间线索引、seek、取消与重启证据	已完成，持续回归	performance.longMedia=true
M4 OOM	四类确定性内存故障与恢复证据	已完成，持续回归	faults.oom=true
M5 V1 RC	可复现离线候选包、SBOM、校验和	未开始	release gate READY

任务严格按 M1 -> M2 -> M3 -> M4 -> M5 领取。里程碑内部允许先写纯校验任务，但不得在 前一里程碑失败时把后一里程碑标为完成。

6. M0 范围、状态和 P0 闭环

M0.1 V1 范围收敛

• M0-SCOPE-01 定义 V1 用户和核心使用场景。
• M0-SCOPE-02 定义 LOCAL_EXACT/LOCAL_BOUNDED/SERVER/EXCLUDED。
• M0-SCOPE-03 明确 Chromium-only 和不承诺完整 Blender UI/渲染/模拟。
• M0-SCOPE-04 将 PBVH、完整 Geometry Nodes、任意 Shader、完整 NLA、完整 VDB demand paging 等移出 V1 required slice。

M0.2 双轴状态模型

• M0-STATE-01 ledger schema 分离 parityStatus 与 releaseStatus。
• M0-STATE-02 每个 family 声明 V1 required/excluded slices。
• M0-STATE-03 校验 required/excluded 不重叠且都引用已声明 slice。
• M0-STATE-04 校验 READY 的 required slices 全部完成。
• M0-STATE-05 校验依赖不存在缺失和环。
• M0-STATE-06 N-026 只聚合 V1 releaseStatus 和真实 evidence 缺口。
• M0-STATE-07 旧 schema、非法状态、依赖环、无构件 evidence 均有负例。

M0.3 单一 P0 用户闭环

固定流程：

import .blend
  -> object/mesh/material edit
  -> undo -> redo
  -> atomic save
  -> terminate StorageWorker + WebEngineWorker
  -> reopen and compare stable IDs/geometry/material
  -> main-thread + Offscreen viewport non-empty pixels
  -> GLB export and semantic round-trip
  -> unsupported shader stable block

• M0-LOOP-01 创建独立 test:v1-user-loop 命令。
• M0-LOOP-02 覆盖对象、Mesh 和 Principled 材质编辑。
• M0-LOOP-03 覆盖 Main revision 的 undo/redo。
• M0-LOOP-04 覆盖 StorageWorker 与 WebEngineWorker 双终止重开。
• M0-LOOP-05 比较稳定 object/mesh/material ID 和 geometry SHA-256。
• M0-LOOP-06 覆盖双生产视口非空像素。
• M0-LOOP-07 覆盖 GLB PBR 语义回读。
• M0-LOOP-08 覆盖未支持 Shader 的稳定阻断。
• M0-LOOP-09 将成功命令和两个构件 SHA-256 写入 evidence。

7. M1 当前工作区收口

目标：确认现有 VDB/WebGPU、状态模型和 P0 闭环不是只在局部测试成立。

M1.1 快速静态门

• M1-STATIC-01 TypeScript typecheck。
• M1-STATIC-02 ESLint。
• M1-STATIC-03 Node unit tests。
• M1-STATIC-04 status consistency。
• M1-STATIC-05 release evidence parser/evaluator。

M1.2 VDB/WebGPU 专项矩阵

• M1-VDB-01 校验 VDB availability 和 native resource catalog。
• M1-VDB-02 校验 desktop OpenVDB -> NanoVDB converter 与畸形输入。
• M1-VDB-03 校验 server job 隔离、取消、超时和 hash 等价。
• M1-VDB-04 校验 conversion boundary 结构化阻断。
• M1-VDB-05 校验 NanoVDB OPFS hash binding 和 Worker 重启。
• M1-VDB-06 校验 Float32/Vec3 CPU 与 WGSL sampling。
• M1-VDB-07 校验主线程与 Offscreen 生产视口。
• M1-VDB-08 校验多 grid/X 视角固定 golden，不仅检查 hash 格式。
• M1-VDB-09 校验全局 resident budget、LRU 次序和唯一释放。
• M1-VDB-10 校验网络、Worker、device-loss 故障恢复。
• M1-VDB-11 确认文档仍明确阻断自动缺页重绘、联合重开、大 bundle 联合故障和发布 三视角 golden。

M1.3 P0 和工作区一致性

• M1-REG-01 重新运行 test:v1-user-loop。
• M1-REG-02 重新运行包含 release gate 的 Chromium 专项。
• M1-REG-03 执行 git diff --check。
• M1-REG-04 核对所有未提交文件都有明确来源，不删除或回退既有用户改动。
• M1-REG-05 更新本节状态和 evidence 时间戳时不伪造未运行命令。

M1 退出命令：

npm --prefix web run typecheck
npm --prefix web run lint
npm --prefix web test
npm --prefix web run test:status-consistency
npm --prefix web run test:release-evidence
npm --prefix web run test:vdb-availability
npm --prefix web run test:vdb-native
npm --prefix web run test:vdb-server
npm --prefix web run test:vdb
npm --prefix web run test:vdb-opfs
npm --prefix web run test:vdb-webgpu
npm --prefix web run test:vdb-viewport
npm --prefix web run test:vdb-faults
npm --prefix web run test:v1-user-loop
git diff --check

8. M2 10M Geometry 发布门

目标：证明 10,000,000 triangles 项目能通过二进制/分块路径在 Chromium 内先显示可交互 LOD，并能取消、释放和恢复。禁止构造 10M 元素 JSON，禁止同时保留多份完整源数组。

M2.1 契约和预算

• M2-GEO-01 定义 10M report：triangle/vertex/chunk 数、源字节、传输字节、 first-interactive-frame、JS/WASM/GPU 峰值、取消延迟、释放后占用和最终状态。
• M2-GEO-02 固定 10M 精确计数、chunk 上限、LOD triangle budget 和测试超时。
• M2-GEO-03 发布命令没有可把默认 fixture 降到小规模的环境开关。
• M2-GEO-04 为非法计数、chunk 越界、重复/缺失 range 定义稳定错误。

M2.2 分块二进制输入

• M2-GEO-05 以固定大小生成 positions/indices chunk；任一时刻只保留有界工作集。
• M2-GEO-06 每个 chunk 使用 transferable ArrayBuffer，发送后验证发送端 detached。
• M2-GEO-07 range 表连续覆盖 10M triangles，无重叠、空洞或整数溢出。
• M2-GEO-08 对输入流和 range manifest 生成确定性 SHA-256。
• M2-GEO-09 在中途取消，验证 Worker 停止、迟到 chunk 被丢弃且下一会话可启动。

M2.3 LOD 与首个可交互帧

• M2-GEO-10 复用现有 LOD cache key/manifest，不创建测试专用缓存格式。
• M2-GEO-11 在完整源仍流入时先发布有界 LOD，记录首个非空像素时间。
• M2-GEO-12 主线程视口渲染 LOD 并完成一次相机/选择交互。
• M2-GEO-13 OffscreenCanvas Worker 渲染同一 LOD 并报告非空像素。
• M2-GEO-14 验证近/远 LOD 切换不重建完整 10M geometry。

M2.4 内存、释放和证据

• M2-GEO-15 采集 performance.memory（可用时）、WASM allocated bytes 和估算 GPU buffer bytes，报告峰值而不是只有最终值。
• M2-GEO-16 明确 JS/WASM/GPU 上限并对超限给出稳定失败。
• M2-GEO-17 dispose renderer/geometry/material、终止 Worker、删除临时 OPFS 数据。
• M2-GEO-18 释放后运行一个小场景，证明浏览器会话可恢复。
• M2-GEO-19 创建独立 test:geometry-10m-performance 命令。
• M2-GEO-20 将成功 record 绑定 performance.geometry10M，至少 hash 测试、生产实现和 range manifest/golden。
• M2-GEO-21 更新 release checker，期望 missing 从 3 降为 2。

M2 退出条件：独立命令连续通过；报告 triangleCount=10_000_000；双视口有非空像素；取消和 释放通过；evidence 中 geometry10M=true 且有唯一成功 record。

9. M3 Long Media 发布门

目标：验证 V1 有限 Timeline/Sequencer 在长时间线下的索引、seek、取消、cache 和 Worker 重启， 不把完整媒体编辑器或最终编码器纳入 V1。

M3.1 范围和 fixture

• M3-MEDIA-01 固定长时间线 frame range、strip 数和 preview byte budget。
• M3-MEDIA-02 使用本地确定性 PNG/WAV 和 manifest；测试不得依赖网络或系统 codec。
• M3-MEDIA-03 明确 V1 支持的 IMAGE/SOUND 时间索引子集和排除的 movie codec/encode。
• M3-MEDIA-04 为未声明 codec、最终编码、损坏 manifest 定义结构化阻断。

M3.2 索引和 seek

• M3-MEDIA-05 建立有界索引，不按总帧数展开巨型 JSON。
• M3-MEDIA-06 验证时间线起点、中点、终点和随机 seek 的精确 strip 命中。
• M3-MEDIA-07 验证连续 scrub 合并过期请求，只发布最新 revision/frame。
• M3-MEDIA-08 记录冷 seek、热 seek 和索引构建时间。

M3.3 cache、取消和重启

• M3-MEDIA-09 对 media preview bytes 使用显式 byte budget 和 LRU。
• M3-MEDIA-10 超预算时逐项淘汰，活动 frame 不被错误淘汰。
• M3-MEDIA-11 在索引、seek 和 decode 三个阶段分别验证 AbortSignal。
• M3-MEDIA-12 终止 Worker 后从 OPFS/IndexedDB manifest 恢复索引和当前 frame。
• M3-MEDIA-13 损坏 session manifest 被隔离，正确 manifest 仍可重建。

M3.4 证据

• M3-MEDIA-14 创建独立 test:long-media-performance 命令。
• M3-MEDIA-15 输出计数、耗时、峰值 cache bytes、取消和重启结果。
• M3-MEDIA-16 将成功 record 绑定 performance.longMedia。
• M3-MEDIA-17 更新 release checker，期望 missing 从 2 降为 1。

M3 退出条件：确定性长时间线专项通过；seek/取消/LRU/restart/unsupported codec 均有断言； longMedia=true 且 evidence 构件可复核。

10. M4 OOM 发布门

目标：用确定性故障注入验证内存不足不会损坏当前项目或留下不可恢复会话。测试不能依赖真的 耗尽宿主机内存。

M4.1 统一故障注入契约

• M4-OOM-01 定义仅测试构建可用的 allocation fault point 和 fail-after-bytes/count。
• M4-OOM-02 fault session 使用 token 隔离，默认关闭且不能泄漏到后续请求。
• M4-OOM-03 为 WASM、OPFS staging、GPU geometry/texture、VDB resident 分配映射稳定 错误码和 stage。
• M4-OOM-04 统一报告 before/peak/after bytes、revision、临时资源和恢复状态。

M4.2 WASM 与 Main

• M4-OOM-05 在 open/read 临时分配失败时不创建半初始化 handle。
• M4-OOM-06 在 edit/save 分配失败时保留旧 Main revision 和 undo 栈。
• M4-OOM-07 释放 native buffer/handle，Worker 重启后可重开旧项目。

M4.3 OPFS staging

• M4-OOM-08 在 staging write 中途注入 quota/OOM。
• M4-OOM-09 journal 不提交，新 revision 不替换旧 revision。
• M4-OOM-10 清理临时文件；重启后旧项目 hash 不变。

M4.4 GPU 与 VDB

• M4-OOM-11 GPU geometry/texture budget 超限不创建部分 scene object。
• M4-OOM-12 dispose 已创建 GPU buffer/texture，随后小场景可渲染。
• M4-OOM-13 VDB resident budget 超限返回 NANOVDB_GPU_BUDGET_EXCEEDED。
• M4-OOM-14 VDB page table/resident pages 唯一释放，device/session 可恢复。

M4.5 证据

• M4-OOM-15 创建独立 test:oom-recovery 命令，四类 fault 全部执行。
• M4-OOM-16 记录每类错误码、旧 revision/hash、释放字节和恢复结果。
• M4-OOM-17 将成功 record 绑定 faults.oom。
• M4-OOM-18 更新 release checker，期望 missing 为 0、gate 为 READY。

M4 退出条件：四类确定性故障均通过；不存在静默成功、旧 revision 丢失、临时文件泄漏或只能 刷新浏览器恢复的情况；faults.oom=true。

完成证据：npm --prefix web run test:oom-recovery 在 Chromium 中执行 WASM/Main、OPFS staging、 WebGL GPU 资源组和 NanoVDB WebGPU resident/page-table 四类确定性失败；release:evidence-oom 生成第 17 条 record。测试报告分别验证 Main revision/hash、undo/redo、旧 OPFS revision/hash、 临时文件归零、部分 GPU object 不发布、NanoVDB buffer 唯一释放以及同会话/重启恢复。

11. M5 V1 发布候选

M5.1 全矩阵

• M5-RC-01 clean install 后通过 typecheck、lint、unit。
• M5-RC-02 运行所有 V1 required slice acceptance commands。
• M5-RC-03 运行 P0 用户闭环和 Chromium 全套 E2E。
• M5-RC-04 运行 geometry/media/texture/simulation 性能矩阵。
• M5-RC-05 运行 OOM/device-loss/network/malformed/zip-bomb 故障矩阵。
• M5-RC-06 运行 VDB 全矩阵和双生产视口。

M5.2 构件和可复现性

• M5-RC-07 重新生成 SBOM 和 third-party notices。
• M5-RC-08 生成离线二进制包和 corresponding source 包。
• M5-RC-09 连续生成两次并比较规范化摘要。
• M5-RC-10 生成 SHA256SUMS.txt，每个引用文件存在且 hash 匹配。
• M5-RC-11 检查包内无 CDN、绝对开发路径、测试 secret 或未声明运行时依赖。

M5.3 声明和最终状态

• M5-RC-12 UI、README、scope 和 capability report 只声明 V1 白名单。
• M5-RC-13 长期 parity 差距继续保持，不因发布 V1 被改成全域 COMPLETE。
• M5-RC-14 重新收集 release evidence，不复用与当前构件 hash 不一致的旧 record。
• M5-RC-15 release gate 输出 READY 且 missing 为空。
• M5-RC-16 git diff --check、状态一致性和 release evidence checker 全部通过。
• M5-RC-17 工作区生成物均被忽略、纳入构件或有文档解释。

M5 退出条件：所有必需命令退出码 0；release gate READY；离线包可复现；当前构件、源码、 SBOM、状态和 evidence SHA-256 相互一致。

12. V1 后任务

V1 RC 完成前不领取以下任务：

1. VDB 自动 page-fault feedback、渐进重绘和生产 Offscreen device-loss 联合恢复。
2. Volume Main + asset binding + 生产视口联合重开，以及三视角 desktop/Chromium golden。
3. 64 MiB/512 MiB/1 GiB sparse bundle、深度合成和完整 VDB 大包/取消矩阵。
4. 新外部字体、PBVH、完整 paint、Geometry Nodes/Simulation evaluator、任意 Shader、完整 NLA、Compositor、Sequencer、Tracking、Asset Browser、Editor 和 Scripting 对标。
5. Firefox/WebKit 支持和跨浏览器发布门。

V1 后按产品需求和风险重新排序，不再仅按 N-015 至 N-026 编号顺序扩大范围。