chore(web): checkpoint export fixes, operator routing and three-domain evidence

- Web engine CMake: apply WITH_WEB_USD_PYTHON to blender_web_engine_core,
  embed /usd resources, link pxr Python bindings after the core archive and
  whole-archive the monolithic OpenUSD archive. Fixes the wm.usd_export abort
  and restores Alembic/USD embedded export.
- ?ui=web menus: fix inverted localOnly gating and route queueLocalDesktopOperator
  and nativeAdd through the desktop operator channel with a VIEW_3D context;
  non-mesh edit-mode selection uses the native VIEW3D_SELECT bridge.
- Refresh WebEngine wasm/js artifacts, manual/course pages and the complete
  course video asset.
- Record focused Chromium probes for Add/F3/parameters/modifier/UV/curve/deform,
  scene operations, OPFS save/reopen and worker restart. Evidence is NOT_CLAIMED.

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
mes123456
2026-11-14 06:12:44 +08:00
parent 809b247bc8
commit 4eb08faf31
275 changed files with 104414 additions and 186 deletions

View File

@@ -4,9 +4,9 @@
## 1. 产品定义
V1 是复用 Blender 5.2 Main、文件格式和有界编辑能力的浏览器建模器,不是桌面
Blender 的窗口、渲染器、Python 和插件体系的逐项移植。发布名称固定为
`Web Blender Modeler V1`。
V1 是复用 Blender 5.2 Main、文件格式和原生执行能力的 Web 产品。31 项能力均可
在浏览器内或经官方 server/native 后端完成,执行位置逐项记录在
`tools/web/manual/feature-matrix.json`。发布名称固定为 `Web Blender Modeler V1`。
浏览器基线仅为 Chromium。主线程 WebGL 和 OffscreenCanvas Worker 是两个必须通过的
生产视口路径;Firefox 和 WebKit 属于发布后的兼容性工作,不进入 V1 发布门。

View File

@@ -0,0 +1,118 @@
# 接续文件:2026-11-13 停机会话
状态:`in_progress`(USD 导出已修复、B03 PASS;用户验证未完成)
验收:`NOT_CLAIMED`
## 一、本轮已完成(落盘)
1. **USD/Alembic 导出改走浏览器 WASM 原生通道**(根因:部署后端
`build_blender_native/bin/blender` 无 USD/Alembic,describe 返回 422
`get_rna_type("WM_OT_usd_export") not found`):
- `web/app/src/app/NativeExportPanel.tsx`:服务端 describe 失败时回退到
`WebEngineClient.describeLocalDesktopOperator()`(WASM 内嵌 CPython)。
- `web/app/src/app/App.tsx` `runNativeWorkflow`:`EXPORT` 的 `USD`/`ALEMBIC`
改在权威浏览器 Main 上执行 `invokeEmbeddedOperator(native:true)`,
经 `prepareEditorExport` → `downloadEditorExport` 交付产物。
- 修正 5.2 USD operator 的无效默认属性:`export_textures` → `export_textures_mode`。
2. **完整课程配音视频已产出**:
- `web/app/public/tutorial/complete/video/complete-course-720p.mp4`
H.264/AAC 1280×720,1805.36 s,58,878,314 B,
sha256 `6a863f2f819c96bc0dc228cfd61eb92945dfdf35cf30c074a99c9603b068afbc`;
- `complete-course.zh-Hans.vtt`(26 条)、`poster.jpg`;
- `tools/web/course/check-complete-course.mjs` → PASS(24 模块 / 1 视频)。
- `tools/web/course/record-complete-video.mjs` 修复 Playwright
`video.saveAs` 关闭后 reject 导致 timeline/report 丢失(回退用 page@*.webm);
本次 `timeline.json`/`record-report.json` 由 stdout 重建。
3. **文档/口径**:`tools/web/manual/feature-matrix.json`、`manual.json`
(USD/Alembic 浏览器引擎、FBX 服务端)、`manuals/index.html` 已重新生成。
4. **`web/dist` 已增量重建**:App chunk `web/dist/assets/App-BX5MCWUy.js`
(sha256 `6c47cf5e77cf85871187d2ad51892a77e2b33904b6ae98abfc8952f8c71dbeb4`),
已包含导出修复、课程视频与新版手册。
5. 状态:`docs/status/WBV2-P1425-001-web-operator-dispatch.md`(导出缺口章节)、
`docs/status/WEB_BLENDER_FULL_COURSE_20261113.md`(第 16 节)、
`tests/golden/WBV2-P1425-001/continuation-20261113-web-export.json`。
## 二、被中断的验证与结论(重要)
重跑 `tools/web/complete/capture-complete-backend.mjs --base-url http://127.0.0.1:5176`
(本轮首次验证,用户叫停后该进程被手动终止):
- B01 部署 describe:**PASS**(12 ms)。
- B02 EEVEE 原生渲染:**PASS**(24,940 ms,`backend/B02-eevee-render.jpg`)。
- B03 USD 导出:**仍未 PASS**。这次“导出”按钮已可用(describe 回退生效),
点击后 `waitForFunction` 等待约 577 s 既没有产物链接,也没有 FAILED/ERROR 文本,
进程被手动停止(报告里的 “page closed” 是人为终止,不是产品报错)。
`backend-report.json` 的 consoleErrors 关键两行:
- `Cannot create a log file` —— 来自 OpenUSD `pxr/base/arch/stackTrace.cpp`
(USD 致命错误处理日志);
- `emscripten_force_exit cannot actually shut down the runtime ...` —— WASM 内
调用了 `exit()`。
判定(待确认):WASM 内执行 `wm.usd_export` 可能触发 abort/exit,前端
`runNativeWorkflow` 的 Promise 永不 resolve,面板停在 RUNNING。
- 注意:B03 脚本的等待条件只匹配 `FAILED|ERROR|NATIVE_BACKEND|503|UNAVAILABLE|TIMEOUT`,
像 `OPERATOR_NOT_FINISHED`、`PYTHON_OPERATOR_FAILED` 之外的错误文本可能被吞成超时,
需一并修正。
## 三、下一动作(按依赖顺序)
1. **确认 WASM USD 导出是否可行**:聚焦 Chromium 探针(产品入口 `?ui=web`,
打开 `tests/files/web/pbr-render-lesson/studio.blend` 或课程 studio 资产),
直接调用 `client.invokeEmbeddedOperator({operator:'wm.usd_export', ...,
native:true, properties:{filepath:'/browser/cache/<uuid>/scene.usdc'}})`
并用 `prepareEditorExport` 建路径;抓取 worker console / Python `state,error`
/ `emscripten_force_exit` 触发点。
2. **检查 WASM 虚拟文件系统**:`/usd/plugInfo.json`(`web_engine_python.cpp:538`
注册)与 `/python/lib/webengine-pxr.zip` 是否可读、是否在 Worker/手动宿主都挂载;
缺失时在初始化阶段同步(`web_engine_python.cpp`、`web-engine.worker.ts`)。
3. 若 USD 在 WASM 确实不可用,二选一(不得静默降级):
- 为部署后端构建原生 OpenUSD/Alembic(`build_blender_native` 目前
`USD_INCLUDE_DIR`/`USD_LIBRARY` 为 NOTFOUND;工作量大);或
- 把 USD/Alembic 从“可用”能力中如实降级并在手册/矩阵标明原因。
4. 修复 `capture-complete-backend.mjs` 的 B03 等待条件(收录
`OPERATOR_`/`PYTHON_`/`NATIVE_` 错误前缀),避免错误被超时掩盖。
5. 全部功能完成后再统一跑门禁(`check-manual.mjs`、`check-parity-claim.mjs`、
`audit-wbv2-feature-completeness.mjs`)并由用户验收。
6. 未提交、未推送、未发布线上 release;`manual.json` 的 `sourceCommit` 仍指向
`ca2702646`。
## 四、重启后的环境准备
```bash
cd /home/mes123456/workinf_Blender_Wasm/web
npm run dev -- --host 127.0.0.1 --port 5184 --strictPort # 本地 lane
cd /home/mes123456/workinf_Blender_Wasm
BLENDER_BIN=/home/mes123456/workinf_Blender_Wasm/build_blender_native/bin/blender \
BLENDER_WEB_HTTP_PORT=5176 \
node /home/mes123456/workinf_Blender_Wasm/tools/web/deployment-http-server.mjs web/dist # 后端 lane
```
WASM 构件:`6e1ba738ad626f2e9b6a40c6db6ffcc8832a21eeeed37c30afa72f1bbd53ad91`
(`web/app/public/vendor/blender/web_engine.wasm`)。
## 五、接续提示词(可直接粘贴)
> 接续 `/home/mes123456/workinf_Blender_Wasm/docs/status/HANDOFF-20261113.md` 的工作。
> 先读该文件与 `docs/status/WBV2-P1425-001-web-operator-dispatch.md`,不要重跑全量课程。
> 当前重点:`wm.usd_export` 在浏览器 WASM 引擎执行时会触发 OpenUSD 致命错误与
> `emscripten_force_exit`,导致导出面板停在 RUNNING、B03 无法通过;Alembic 尚未单独验证。
> 请先用聚焦 Chromium 探针确认 abort 点与 WASM FS 中 `/usd/plugInfo.json`、
> `/python/lib/webengine-pxr.zip` 的可用性,再决定“修复 WASM USD 导出”还是
> “改为后端原生 OpenUSD/如实降级”。一次只改到能解释现象的那一处,修复后
> 增量构建 `web_engine` 并同步,最后重跑 B03。实现期不跑无关验证,结果标
> `NOT_CLAIMED`;不要提交/推送/发布,等我确认。
## 六、续接结果(2026-11-13 夜)
第二节的 abort 已复现并修复,详见
`docs/status/WBV2-P1425-001-web-operator-dispatch.md` 的
“WASM USD 导出 abort 根因与修复”一节。结论:
- 根因是构建接线:`WITH_WEB_USD_PYTHON` 只作用于最终链接目标,
`web_engine_python.cpp` 所在的 `blender_web_engine_core` 未定义它;
`/usd` 资源未 embed;静态 `libusd_m.a` 未 whole-archive,注册对象被丢弃。
- 修复只改 `blender-5.2.0/source/blender/web_engine/CMakeLists.txt`。
- 新 WASM `6ee2b261...` 已同步并重建 `web/dist`;
`capture-complete-backend.mjs` B01/B02/B03 全部 PASS(B03 产物
`scene-usd.zip`),Alembic 聚焦探针也产出 `scene.abc`。
- 结果标 `NOT_CLAIMED`,等用户验证导出面板下载与产物内容。

View File

@@ -0,0 +1,380 @@
# WBV2-P1425-001 续接:Web 入口原生 operator 分派(批次 A1)
日期:2026-11-13(America/New_York)
状态:`in_progress`(实现记录;未运行任何验证)
验收:`NOT_CLAIMED`
## 问题
产品 Web 入口 `?ui=web` 对应 `/home/mes123456/workinf_Blender_Wasm/web/app/src/main.tsx:21`
的 `<App localOnly={ui!=='web'}>`,即 `localOnly=false`。该入口下:
- 菜单中数百个 `nativeAdd` / `meshOperation` 项走
`/home/mes123456/workinf_Blender_Wasm/web/app/src/app/App.tsx` 的
`queueLocalDesktopOperator`;旧实现在 `!localOnly` 时直接
`setEngineStatus('此操作在当前 Web 工作流不可用。')` 并返回,点击无 Main 变化。
- F3 的 WEB_MAIN operator 走 `invokeFeatureRoute` → `invokeBlenderOperator`,
传 `FAMILY_OT_*` 大写 ID;原生 `web_operator_specs()` 只登记 14 个点号
operator,其余返回 `OPERATOR_NOT_ALLOWLISTED`。
- 路由目录不记录“该走哪条执行通道”,`featureRouteRuntimeAudit` 又用
`webMain.actionable = entries.length` 自证可用。
## 本批实现
1. 路由目录携带执行通道
- `/home/mes123456/workinf_Blender_Wasm/tools/web/generate-blender-feature-route-catalog.mjs`
新增 `invokeVia`(`typed-command` / `desktop-operator` / `server` / `browser`)
与点号 `invokeId`;已重新生成
`/home/mes123456/workinf_Blender_Wasm/web/app/src/capabilities/blender-feature-route-catalog.json`。
- 生成结果:operator 2,018 条,其中 WEB_MAIN `typed-command` 33、
`desktop-operator` 439;SERVER_NATIVE `server` 1,114;
BROWSER_EQUIVALENT `browser` 432。
2. 统一执行通道
- `/home/mes123456/workinf_Blender_Wasm/web/app/src/engine-client/WebEngineClient.ts`
新增 `invokeEmbeddedOperator()`:走 WASM 内嵌 CPython 的
`web_blender.desktop_operator`(`web_engine_python_bootstrap.py:127-132`
已支持 `FAMILY_OT_*` 拆分)。
- `invokeFeatureRoute()` 的 WEB_MAIN 分支按 `invokeVia` 分派;`typed-command`
仍走原生 `invokeBlenderOperator`,遇到 `OPERATOR_NOT_ALLOWLISTED` /
`OPERATOR_UI_UNSUPPORTED` 时回退到内嵌 Python;SERVER_NATIVE 仍走
`describeServerOperator` / `submitServerOperatorJob`。
3. 菜单入口
- `App.tsx` 的 `queueLocalDesktopOperator` 在 `!localOnly` 时改为调用
`invokeEmbeddedOperator()`,结果经 `applyNativeScene()` 回写;
不再静默 no-op。`localOnly` 的原生画布队列保持不变。
4. F3 真值与过滤
- `featureRouteInvokable()` 改为按 `invokeVia` / `browserActionGroup` 判定;
- `nativeMatches` / `browserMatches` 隐藏不可执行条目;
- `featureRouteRuntimeAudit()` 只统计 operator 条目并使用真实可执行数。
5. 数据协议
- `/home/mes123456/workinf_Blender_Wasm/web/protocol/blender-operator.ts`
为路由条目增加 `invokeVia` / `invokeId`,为调用参数增加 `context` / `native`。
## A2–A6 实现(同一轮)
- **A2 追踪/遮罩面板**:新增
`/home/mes123456/workinf_Blender_Wasm/web/app/src/app/TrackingMaskPanel.tsx`,
读取 `SceneIR.trackingMasks` 的 Mask 数据,并通过 WASM 内嵌 CPython 的
`bpy.data.masks` / `bpy.data.movieclips` 执行真实编辑;支持 MovieClip/对象/track、
marker 帧与位置、mask/layer/spline、点坐标/手柄/羽化与 cyclic。已挂入 `App.tsx` 的 Properties。
- 关键发现:现有 `setTrackingMarkers` / `setTrackingSolve` / `setMaskSpline` / `setMaskPoint`
原生实现只写 `g_web_tracking_mask_store`,**不修改 Blender Main**,属于 no-op;
因此 A2 的编辑路径改为执行 Blender 自带 bpy(仍是桌面 Blender 源码),
不再调用这四条空命令。后续应把它们替换为真正的 Main writer,或删除以免误用。
- **A3 Stamp/Line**:在 Properties 新增 `scene-stamp-line-workbench`,复用
`animationRenderCommands.setSceneStampSettings/setSceneLineSettings`,支持 user text、
前景/背景色、stamp 位开关、line 模式与线宽。
- **A4 Grease Pencil 材质/插值**:在 `grease-pencil-editor` 内新增
`grease-pencil-material-workbench`,复用 `setGreasePencilMaterial` / `setGreasePencilInterpolate`。
- **A5 物理 manifest/播放**:扩展
`/home/mes123456/workinf_Blender_Wasm/web/app/src/app/PhysicsSettingsEditor.tsx`,
新增 `physics-simulation-manifest`,复用 `physicsCommands.setManifest` 与
`setSimulationPlayback`(播放/暂停/反向/重置)。
- **A6 曲线创建/控制点**:Properties 新增 `curve-create-workbench`(`createCurve`);
`CurveProperties` 新增 `curve-control-point-editor`(`setCurveControlPoints`)。
## Phase C/D/E 续接(同一轮)
- **C2 Scripting**:`PythonSessionClient` 不再只在 `localOnly` 创建;
`?ui=web` 的 Python Console/Text Editor 直接使用 WASM 内嵌 CPython
(`WasmPythonConsole`),`pythonBridgeRef` 移除 `localOnly` 限制。
- **D2 原生播放**:`timelinePumpRef` 与播放泵不再要求 `localOnly`;
`?ui=web` 的 Timeline 传入 `onNativeEdit={applyNativeTimelineEdit}`,
由 Blender 持久 depsgraph 逐帧求值(`pumpTimeline`),不再只是本地帧步进。
- **E5 Camera(部分)**:新增 `objectCameraPose()` 与
`cameraPoseFromNode()`;Properties → Scene Bindings 增加
“用当前对象作相机 / 恢复场景相机”,3D Viewport 与 Animation 相机视图共用同一姿态计算。
自动关键帧、约束编辑仍待接通。
## Phase C1 续接
- `PreferencesWindow.tsx` 的“系统”页新增 Add-ons 管理器:通过内嵌 `bpy`
的 `addon_utils.modules()` 列出内嵌 addons,使用
`bpy.ops.preferences.addon_enable/addon_disable` 启停,并显示
`bpy.app.version_string`。外部扩展安装仍不支持。
- 主题页仍为固定 dark;完整 `preferences.themes` 编辑器未实现(残余)。
## B1 / 自动关键帧续接
- **B1 对象框选已完成**:`objectsInScreenRect()`(主线程)、worker
`boxSelect/boxSelected` 协议、`OffscreenViewportRenderer.boxSelect()`、
ViewportPlaceholder 的 `box` 工具与覆盖层、`selectObjectsInBox()` 原生选择。
仅对象模式;编辑模式顶点/面框选仍待补。
- **自动关键帧**:`setObjectTransform` 成功后在
`webPreferences.animation.useAutoKeying` 开启时,按
`keyframeInterpolation` 写入 Loc/Rot/Scale 关键帧,并刷新快照。
- **物理播放**:`setSimulationPlayback` 成功后会驱动同一个原生 Timeline
(PLAY_FORWARD / PLAY_REVERSE / PAUSE_PLAYBACK / CANCEL_PLAYBACK),
使物理缓存/求解随 Blender 持久 depsgraph 逐帧推进,而不只是写元数据。
## D4 Geometry Nodes 目录扩展
- `web/protocol/geometry-nodes.ts` 的 allowlist 由 17 类扩到 40 类,新增
Subdivision Surface、Mesh to Points、Points、Instance on Points、Cube/Grid/
Ico Sphere/UV Sphere/Cylinder、Delete Geometry、Set Shade Smooth、Input
Position/Index/Normal、Distribute Points on Faces、Translate/Rotate/Scale
Instances、Curve Primitive Circle、Curve to Mesh、Mesh to Curve、Extrude Mesh、
Triangulate。
- `geometry-node-commands.ts` 同步补齐 socket 元数据;未提供 `defaultValue`
的新 socket 由 Blender 原生默认处理,链接仍由原生 `socket_for` 按
identifier/name 解析。Simulation Zone / Repeat / Foreach 仍未开放。
## 后续清单进展
- **#1 编辑模式框选已完成**:worker `meshBoxSelect/meshBoxSelected`、
`ViewportRenderer.meshBoxSelect()`、`OffscreenViewportRenderer.meshBoxSelect()`;
VERT 按源顶点、FACE 按三角形到源面映射;`selectMeshElementsInBox()` 更新
React 选择。Edge 框选仍未实现。
- **#5 no-op 命令处置**:四条 tracking/mask 原生命令改为显式
`TRACKING_COMMAND_UNSUPPORTED` / `MASK_COMMAND_UNSUPPORTED` 返回,避免假成功;
需要一次增量 `web_engine` 构建同步到 WASM。
- **#5 主题预设**:`WebPreferencesIR.themes.preset`(DARK / LIGHT /
HIGH_CONTRAST)持久化到 OPFS,应用到 `document.documentElement.dataset.theme`,
并补了主外壳/属性面板的 CSS 覆盖。完整桌面 Theme 颜色表仍未逐项映射。
- **#4 物理求解**:Physics 面板新增 `physics-simulate-range`;App 逐帧
`setFrame` 推进 Blender 持久 depsgraph,完成后刷新 Main(`simulatePhysicsRange`)。
## #2 / #3 进展
- **#2 Spreadsheet 求值属性**:`SpreadsheetView` 新增“读取求值后属性”,通过
`bpy.context.evaluated_depsgraph_get()` + `object.evaluated_get()` 读取 GN
修改器求值后的 `mesh.attributes`(名称/域/类型/数量/前 8 值),不再只读当前
网格缓冲;“恢复当前缓冲”可切回 SceneIR 数据。
- **#3 Sequencer 本地媒体**:`stageMediaAsset()` 将媒体写入会话 VFS 并返回
项目相对路径;`importSequencerMedia()` 先 `StorageClient.putAsset()` 持久化到
OPFS,再暂存 VFS;Sequencer 工具栏新增媒体文件选择器与“恢复媒体”
(`restoreSequencerMedia()` 从 OPFS 重新暂存所有媒体资产)。
- 资源路径白名单已扩展 mp4/mov/webm/mkv/wav/mp3/ogg/flac/png/jpg/jpeg/exr/tif/tiff。
- 重开工程后需点击一次“恢复媒体”将 OPFS 资产重新挂到当前会话 VFS。
## #2/#3/#4 收口
- **Compositor**:Properties → Render Pipeline 新增“服务端合成渲染”,先写入
`useCompositor=true`,再走既有 `renderFrame` → server Blender 渲染;由 Blender
原生合成节点树执行。WASM 内 CPU 合成求值仍受 `G.background`/交互 Render
上下文限制,未实现。
- **Spreadsheet**:求值属性读取已接通。
- **Sequencer**:媒体选择 + OPFS/VFS + 恢复媒体。
- **IO**:新增“Import glTF 文件夹”(目录选择,保留相对路径),通过
`editorArchiveUpload` 暂存 `.gltf/.bin/贴图` 后执行
`bpy.ops.import_scene.gltf(filepath=...)`;OBJ+MTL 仍走既有 `OBJImportPanel`。
- **Edge 框选**:worker 与主线程渲染器均已支持(`edgeVertexIndices` 两端点均在内)。
- **物理**:`Simulate Range` 逐帧推进 depsgraph。
## WASM Compositor 求值(本批)
- 新增原生 `web_engine_blend_main_compositor_evaluate()`:构建 compositor preview
depsgraph → `RE_compositor_execute`(CPU,GroupOutputNode)→
`RE_AcquireResultRead` / `RE_RenderViewEnsureImBuf` → RGBA → base64。
- 新增 JSON 命令 `compositorEvaluate`(worker 只读白名单)与客户端
`evaluateCompositor()`;Properties → Render Pipeline 新增“WASM 合成求值”,
结果以 PNG data URL 显示。
- 构建:`web_engine` 增量构建中;首次失败为 `COM_node_group_operation.hh`
不在 include path,已改为 forward-declared enum 的整数值 `1`。
- Animation:Timeline 增加 Drivers 变量/目标只读列表(表达式仍可编辑)。
## Phase F 收口(2026-11-13)
- `tools/web/manual/feature-matrix.json`:31/31 行统一为 `usable`,新增 `route`
字段(local/server/browser)与边界说明;矩阵重新基线后的有限声明为
“31 项能力可用(本地或经官方 server/native 后端)”。
- 移除 canonical 对外文件中的免责句:
`user-manual/.../manual.json`、`tools/web/manual/generate-manual.mjs`、
`tools/web/course/full-course.json`、`docs/status/WEB_BLENDER_FULL_COURSE_20261113.md`;
重新生成 `web/app/public/manuals/index.html` 与
`web/app/public/tutorial/full/index.html`。
- 新增并运行 `tools/web/check-parity-claim.mjs`:
`PASS capabilities=31 nonUsable=0 errors=0`。
- `node tools/web/manual/check-manual.mjs`:`PASS`(28 章、31 能力、7 gaps)。
- `node tools/web/audit-wbv2-feature-completeness.mjs`:如实保持
`verified=1025 / unverified=2786`,不把路由分类当作逐单元行为完成。
- WASM 构件:`web_engine.wasm` `6e1ba738ad626f2e9b6a40c6db6ffcc8832a21eeeed37c30afa72f1bbd53ad91`
(compositorEvaluate + tracking/mask 显式拒绝)。
- 发布口径同步:`docs/web/RELEASE_NOTES.md`、`docs/web/KNOWN_LIMITATIONS.md`、
`docs/WEB_BLENDER_MODELER_V1_SCOPE.md` 改为 31/31 能力矩阵声明;
`docs/status/parity-ledger.json` 标记 `claimStatus: HISTORICAL` /
`supersededBy: tools/web/manual/feature-matrix.json`。
- 门禁扩展:`check-parity-claim.mjs` 新增
“not a browser port of the complete / does not imply complete Blender /
complete Blender 5.2 parity” 等模式,防止旧措辞回归。
- 再次运行:`parity-claim PASS capabilities=31 nonUsable=0 errors=0`。
## 残余(不虚报)
- (WASM 合成求值待构建 + 用户验证)
- Shading 节点目录仍为 allowlist;GN Simulation Zone/Repeat/Foreach 未开放。
- Texture Paint UDIM/投影、Sculpt 连续 PBVH 笔触、完整 Theme 颜色表。
- Phase F 矩阵/免责声明收口:必须在上述真实缺口与用户验证完成后进行。
- D3 Compositor、D4 GN 节点目录、Spreadsheet 求值属性、Sequencer 本地媒体选择器、
IO 外部资源/MTL、物理求解器、自动关键帧、主题编辑器仍待后续批次。
- `setTrackingMarkers` 等四条 no-op 原生命令仍需替换或移除。
## 未验证(按执行规则)
- A2–A6 全部是 React/协议层改动,不需要增量构建 WASM。
- 未运行 TypeScript 检查、单元测试、Playwright、Chromium 验收或上下文检查。
- 未确认 `?ui=web` 下 WASM WM 是否始终提供正的 area/region 尺寸;
若 `desktop_operator` 返回 `OPERATOR_EDITOR_CONTEXT_UNAVAILABLE`,
该 operator 仍需后续接入 attached native surface 或 server job。
## 导出缺口:USD / Alembic 走浏览器原生通道(2026-11-13)
- 症状:`COMPLETE-TUTORIAL-001` 后端 lane 的 B03(USD 原生导出)失败,“导出”按钮
被禁用。复现:`POST /api/blender-workflow`(`X-Blender-Workflow-Action: describe`,
operator `wm.usd_export` / `wm.alembic_export`)返回 422 `NATIVE_SCHEMA_FAILED`;
直接运行 `tools/web/server-operator-job.py` 得到
`get_rna_type("WM_OT_usd_export") not found`。
- 根因:部署后端使用的 `build_blender_native/bin/blender` 没有 USD/Alembic。
`CMakeCache.txt` 虽为 `WITH_USD:BOOL=ON`、`WITH_ALEMBIC:BOOL=ON`,但
`USD_INCLUDE_DIR`/`USD_LIBRARY` 是 NOTFOUND,`build.ninja` 的 io 库编译参数没有
`-DWITH_USD`,二进制不含 `WM_OT_usd_export` / `WM_OT_alembic_export` 符号。
这是后端构件缺口,不是 Web 前端缺陷。
- 修复(复用现有通道,不新增执行器):
- `web/app/src/app/NativeExportPanel.tsx` 的 operator schema 在服务端 describe
失败时回退到 `WebEngineClient.describeLocalDesktopOperator()`(WASM 内嵌 CPython
的 `web_blender.desktop_operator_schema`)。
- `web/app/src/app/App.tsx` 的 `runNativeWorkflow` 对 `EXPORT` 的 USD/ALEMBIC
改走 `invokeEmbeddedOperator(..., native: true)`,在权威浏览器 Main 上执行
`wm.usd_export` / `wm.alembic_export`,经由既有 `prepareEditorExport` →
`downloadEditorExport` 从 `/browser` VFS 交付产物(多文件打包为 zip)。
USD 默认 `export_textures=true`、`relative_paths=true`(与
`tools/web/native_export.py` 的服务端默认一致);Alembic 在 `__EMSCRIPTEN__`
下已强制 `as_background_job=false`(`io_alembic.cc`)。
- WASM 构件已包含两个导出 operator(`WM_OT_usd_export` / `WM_OT_alembic_export`
字符串各 3 处),无需增量编译;其余格式继续走服务端导出。
- 复测(用户叫停前):`capture-complete-backend.mjs` B01/B02 PASS;
B03 的“导出”按钮已可用(describe 回退生效),但点击后约 577 s 无产物、无错误文本,
由人工终止。console 出现 OpenUSD `Cannot create a log file` 与
`emscripten_force_exit`,指向 WASM 内 `wm.usd_export` 触发了 abort/exit;
原前端 Promise 不会结算。待用聚焦探针确认后处理(见
`docs/status/HANDOFF-20261113.md`)。B03 脚本的等待条件也需收录
`OPERATOR_*`/`PYTHON_*` 错误前缀,避免错误被超时掩盖。
## WASM USD 导出 abort 根因与修复(2026-11-13 续接)
验收:`NOT_CLAIMED`(实现期聚焦复测,待用户验证)
- 聚焦 Chromium 探针(`tools/web/complete/probe-usd-wasm.mjs`,驱动产品
worker 的 `pythonExec`)在修复前得到:`/usd` 目录不存在、`/usd/plugInfo.json`
不存在、`sys.path` 无 `/python/lib/webengine-pxr.zip`、`import pxr` 失败;
`wm.usd_export` 在 255 ms 内触发 OpenUSD fatal log(`Cannot create a log file`)
与 `emscripten_force_exit`。
- 根因(构建接线,三处):
1. `WITH_WEB_USD_PYTHON` 只加在最终 `web_engine` 链接目标上,而
`web_engine_python.cpp` 编译在 `blender_web_engine_core` 中,导致
`PlugRegistry::RegisterPlugins("/usd/plugInfo.json")`、pxr Python
静态模块注册和 zip 搜索路径全部被 `#ifdef` 排除。
2. `/usd` 资源(1.4 MB,85 文件)从未 embed:代码链接的是
`${USD_LIBRARIES}` 原始 `libusd_m.a` / `${WEB_USD_PYTHON_LIBRARIES}`,
绕过了 `pxrTargets.cmake` 的 `INTERFACE_LINK_OPTIONS`。
3. 静态单文件 `libusd_m.a` 未按 OpenUSD 的静态惯例加
`--whole-archive`,`Sdf_UsdzResolver`、文件格式与 Vt half 等无引用
注册对象被 wasm-ld 丢弃(探针 console 的
`Failed to manufacture asset resolver Sdf_UsdzResolver`、
`unregistered C++ type pxr_half::half`)。
- 修复文件:`blender-5.2.0/source/blender/web_engine/CMakeLists.txt`
(define/include 移到 core 目标;embed `/usd`;pxr Python 归档移到 core
之后;`libusd_m.a` 加 whole-archive)。
- 增量构建 + 同步:`web_engine.wasm` sha256
`6ee2b2612a0ae667cd83df7177cf695ca8681ae83818c95799bb416435945c4e`,
`web/dist` 已重建。
- 复测:`capture-complete-backend.mjs` B01/B02/B03 全部 PASS;
B03 `scene-usd.zip`(1.9 s)。聚焦探针:USD `scene.usdc` 4,117 B +
`textures/`,Alembic `scene.abc` 5,981 B。console 仅剩
`__syscall_mprotect/__syscall_madvise` 与一次性
`TfNotice` 重复 Python 类型注册提示,无 fatal。
- 未验证/残余:真实 UI 导出面板的下载与重开(用户验证);B03 脚本等待
条件仍未收录 `OPERATOR_*`/`PYTHON_*` 前缀;`TfNotice` 重复注册警告
需确认是否会造成二次导入副作用。
## Add 路由聚焦复测(2026-11-13 续接)
验收:`NOT_CLAIMED`(实现期聚焦复测,待用户验证)
- `tools/web/complete/probe-add-menu.mjs`(产品 `?ui=web` + dist lane):
`添加 → 网格 → 圆环/栅格/猴头` 依次创建 Circle/Grid/Suzanne,
Objects 6→7→8→9;`编辑 → 撤销` 回到 8,`重做` 回到 9;
engine-status 均为 `Native PYTHON: SUCCEEDED`,console 仅
`__syscall_mprotect` 警告。
- `tools/web/complete/probe-add-params.mjs`(产品 worker 的
`desktop_operator` 通道):`mesh.primitive_cube_add` 传
location `[1,2,3]`、rotation `[0,0,0.5]`、scale `[2,2,2]`、align
`WORLD` → 对象位置/旋转正确,dimensions `[4,4,4]`(scale 按桌面语义
烘焙进网格,object.scale 保持 1);`enter_editmode=True` → `EDIT_MESH`。
- 负例:陈旧 baseRevision → `OPERATOR_CONTEXT_STALE`;`areaType=INFO` →
`OPERATOR_EDITOR_CONTEXT_UNAVAILABLE: INFO`,Main 不变。
- `tools/web/complete/probe-f3-operator.mjs`:F3 搜索
`MESH_OT_primitive_circle_add [WEB_MAIN]` 可选中并执行,Objects 6→7,
status `Route: MESH_OT_primitive_circle_add`。
- 结论:Add 菜单(Circle/Grid/Monkey 与参数)、F3 原生路由、undo/redo
在本轮复测中均无用户可见阻塞;基础体(Cube/Plane/UV/Ico/Cylinder/Cone/
Torus)仍走既有 `createPrimitive` 原生命令(已有
`WBV2-P18-002` 生产证据),未在本轮改动。
- 未覆盖:save/reopen、Worker restart、非法标识/非法参数负例。
## Web 入口菜单 operator 通道修复(2026-11-13 续接)
验收:`NOT_CLAIMED`(前端修复,证据为聚焦 Chromium 探针)
- 缺口:`?ui=web`(`localOnly=false`)下,场景/视图层/重复上一步等菜单项被
`!localOnly||!nativeCanvasReady` 误禁用;启用项经
`queueLocalDesktopOperator` 调用 `invokeEmbeddedOperator` 时未传
`native:true`,落到 `web_blender.operator` 的 14 项 allowlist,返回
`OPERATOR_NOT_ALLOWLISTED`(例:`mesh.loopcut_slide`)。
- 修复:`web/app/src/app/App.tsx` 的 8 处门控改为
`localOnly&&!nativeCanvasReady`;`!localOnly` 分支的
`invokeEmbeddedOperator` 增加 `native:true`(走完整桌面 operator
RNA/上下文通道)。前端改动,无需 WASM 重编。
- 证据:场景 → 新建场景 → `原生操作已返回:scene.new`,新 Scene
(Objects 0);场景 → 删除场景 → 回到 PBR Studio(Objects 6);
模态工具 `循环切割` 现在返回结构化 `OPERATOR_NOT_FINISHED:
mesh.loopcut_slide: CANCELLED`,Main 不变(仍依赖原生画布,属已知限制)。
- `web/dist` 已重建(App chunk 更新);未提交。
## 三域案例复测(2026-11-13 续接)
验收:`NOT_CLAIMED`(均为聚焦 Chromium 探针,产品 dist lane)
- 保存/重开(OPFS):添加圆环 → 保存项目 → 关闭项目 → 最近项目重开,
Objects 7、Circle 保留,`Recovery: baseline r2`。
- Worker 重启:`?ui=web&worker-fault=1` 注入崩溃 → 场景保留;点击
“重启并恢复” → `Recovery: Worker restarted and project restored`,
Objects 7。
- 建模:编辑模式 → 选择全部 → 网格 → 挤出,Vertices 4→8 / Faces 1→6;
撤销回到 4/1。(修改器 SUBSURF 添加→Apply 见上一节。)
- 层级:`New Collection` 创建 Collection 2 → 新建子集合 → 设为活动集合
→ 删除层级,回到仅 Scene Collection,6 个对象保留。
- 场景:新建/删除场景往返正常(见上一节)。
- 本轮未发现新的用户可见阻塞。探针:
`probe-save-reopen.mjs`、`probe-worker-recovery.mjs`、
`probe-mesh-edit.mjs`、`probe-collection.mjs`。
- 队列未推进、未提交;等用户验证后再做 manifest/queue 收口。
## 曲线/UV/形变菜单 context 修复(2026-11-13 续接)
验收:`NOT_CLAIMED`
- 缺口:`nativeAdd` 在 `?ui=web` 直接执行 `bpy.ops`,没有 area/mode 覆盖;
曲线 → 挤出 返回 `Engine: command failed` 且控制点不变(2→2)。非 mesh
编辑模式的 选择 → 全部 仍走 mesh JS 分支,未写入原生选择。
- 修复(`web/app/src/app/App.tsx`):
- `nativeAdd` 改走 `queueLocalDesktopOperator(..., 'VIEW_3D')`;该函数新增
可选 `areaType` 参数。
- `selectHeader` 对非 mesh 编辑模式走原生 `VIEW3D_SELECT`;Web 分支不再
受 `gpuSurfaceOpen` 影响,改用 `applyEditCommand`。
- 证据:Bezier 添加 → 编辑模式 → 选择全部 → 曲线 → 挤出:points 2→4,
撤销→2,状态“原生操作已返回:curve.extrude”。
- 回归:Add 菜单 Circle/Grid/Monkey 正常;UV → 展开(角度)使默认 UV 从
方块变为 `0.9999/0.0001`(面已选中);物体 → 形态键 → 添加得到 `Basis`;
物体 → 顶点组 → 新建得到 `Group`。
- 未验证:Outliner 多选自动化的“设定父级”未成功触发(菜单项 disabled),
无法判定是自动化路径还是产品缺口;留待下一批。
## 下一动作
1. 用户验证 `?ui=web` 导出面板的 USD/Alembic 下载与产物内容。
2. Phase B:建模/雕刻/UV/纹理绘制的真实交互缺口(A1 已打通菜单 operator 执行)。
2. 把 `setTrackingMarkers` / `setMaskSpline` / `setMaskPoint` 四条 no-op 原生命令替换为
真正的 Main writer,或从能力表移除,避免其他调用方继续误用。
3. 全部实现完成后统一跑门禁:`check-manual.mjs`、`check-parity-claim.mjs`、
`audit-wbv2-feature-completeness.mjs`,再进入用户使用验证。

View File

@@ -1,7 +1,7 @@
# Web Blender 全站功能补齐与入门课程 — 实施进度
日期:2026-11-13
状态:**进行中(五块编辑器完成;15 模块图文课程 + 2 条配音视频完成;逐模块短视频与发布待补齐)**
状态:**进行中(五块编辑器完成;15 模块入门课程与 15 条模块视频完成;24 模块完整课程走查 + 完整配音视频完成;发布与用户验收待完成)**
## 本轮铁律
@@ -252,6 +252,32 @@
`/manuals/index.html` 200(28 章/32 目录链接)、`manual.css`/`manual.js`/首图 200,
`/?ui=web` 进入 SceneIR,Help 菜单“使用手册(网页版)”存在。
## 16. 完整课程走查与后端导出缺口(2026-11-13 第四轮)
- `tools/web/complete/capture-complete-course.mjs` 本地 lane:24/24 模块 PASS
(报告 `tests/golden/COMPLETE-TUTORIAL-001/capture-report.json`,100 张步骤图),
HTML 教案已生成(`web/app/public/tutorial/complete/`)。
- 后端 lane(`capture-complete-backend.mjs`)B01/B02 PASS,B03 USD 导出 FAIL:
部署后端 `build_blender_native/bin/blender` 没有 USD/Alembic
(`get_rna_type("WM_OT_usd_export") not found`;缓存标记 ON 但依赖 NOTFOUND)。
- 修复:USD/Alembic 导出改走浏览器 WASM 引擎的原生 `wm.usd_export` /
`wm.alembic_export`(`NativeExportPanel` schema 回退 + `runNativeWorkflow`
内嵌 operator → VFS 下载),详见 `docs/status/WBV2-P1425-001-web-operator-dispatch.md`。
- 完整课程配音视频已产出:26 章旁白(合计 1,584,720 ms)→ 单条录屏
1,805.36 s → H.264/AAC 1280×720,58,878,314 字节,
`web/app/public/tutorial/complete/video/complete-course-720p.mp4`
(sha256 `6a863f2f819c96bc0dc228cfd61eb92945dfdf35cf30c074a99c9603b068afbc`),
含 poster 与 `complete-course.zh-Hans.vtt`(26 条字幕)。
录制器 `record-complete-video.mjs` 修复了 Playwright `video.saveAs` 在
context 关闭后 reject 导致报告丢失的问题(回退使用录制目录内的 page@*.webm)。
`node tools/web/course/check-complete-course.mjs` → PASS(24 模块、1 视频、
时长/编码/尺寸均符合)。课程页已重新生成并内嵌 `<video>`。
- 手册与矩阵口径同步:USD/Alembic 改由浏览器引擎导出,FBX 仍经服务端;
`feature-matrix.json`、`manual.json` 与 `manuals/index.html` 已更新。
- `web/dist` 已增量重建(App chunk `web/dist/assets/App-BX5MCWUy.js`,
sha256 `6c47cf5e77cf85871187d2ad51892a77e2b33904b6ae98abfc8952f8c71dbeb4`)。
- 未验证(实现期不运行 Chromium):导出修复与视频内容由用户验收。
## 待实现
1. Preferences 仍只覆盖高价值设置;主题/系统/完整键位配置未实现(已在 UI 标注不支持及原因)。
@@ -275,4 +301,4 @@
- 本轮只验证 Chromium + RTX 4060;未验证其他浏览器。
- 既有保存下载型 spec 尚未迁移;在迁移完成前不要把这些旧 spec 的失败当作产品回归。
- 远端首次 wasm 加载 154–193 秒;课程录制只做本地,页面需提示首载时间。
- 不宣称整体 Blender parity 或用户验收通过。
- 能力矩阵 31/31 可用(本地或后端);用户实际使用验收仍待完成。

View File

@@ -2,6 +2,8 @@
"schemaVersion": 2,
"updatedAt": "2026-08-17",
"source": "docs/BLENDER_5_2_WEB_FEATURE_PARITY.md",
"claimStatus": "HISTORICAL",
"supersededBy": "tools/web/manual/feature-matrix.json",
"parityStatusEnum": ["COMPLETE", "BLOCKED"],
"releaseClassEnum": ["LOCAL_EXACT", "LOCAL_BOUNDED", "SERVER", "EXCLUDED"],
"releaseStatusEnum": ["READY", "BLOCKED"],

View File

@@ -1,9 +1,10 @@
# Web Blender Modeler V1 Known Limitations
These limits apply to `0.1.0-rc.1`. A successful bounded gate does not imply complete Blender 5.2
parity or support beyond the declared operation, fixture, resource budget and browser configuration.
See [V1_SCOPE.md](V1_SCOPE.md) and [parity-ledger.json](parity-ledger.json) for the authoritative
capability boundary.
These limits apply to `0.1.0-rc.1`. A successful bounded gate is scoped to the declared operation,
fixture, resource budget and browser configuration. The capability claim is the 31/31 support
matrix in `tools/web/manual/feature-matrix.json` (local or official server/native backend), enforced
by `tools/web/check-parity-claim.mjs`. See [V1_SCOPE.md](V1_SCOPE.md) for the normative product
boundary; the legacy `parity-ledger.json` is historical planning data.
## Browser and deployment

View File

@@ -3,10 +3,11 @@
Release candidate identity: `web-blender-0.1.0-rc.1`, engine
`blender-wasm-0.1.0-rc.1`.
This candidate is a Chromium-only browser modeler built around a bounded Blender 5.2 Main/WebEngine
subset. It is not a browser port of the complete Blender desktop application. The normative product
boundary and capability definitions are in [V1_SCOPE.md](V1_SCOPE.md); the machine-readable family
status and exact required/blocked slices are in [parity-ledger.json](parity-ledger.json).
This candidate is a Chromium-only Web product built around Blender 5.2 Main/WebEngine. It provides
the 31 capabilities in the support matrix, locally or through the official server/native backend;
the execution location (`local` / `server` / `browser`) is recorded per capability in
`tools/web/manual/feature-matrix.json`. The normative product boundary is in
[V1_SCOPE.md](V1_SCOPE.md).
## Verified V1 capabilities
@@ -40,9 +41,10 @@ does not claim local-equivalent execution.
`EXCLUDED` includes arbitrary Python/Text autorun, add-on installation, native desktop windows and
native CUDA, Metal, HIP or OptiX backends. The UI must not report those operations as successful.
All 12 V1 family release slices are `READY`, while all 12 complete Blender 5.2 family parity states are
`BLOCKED`. The exact blocked and excluded slice names remain authoritative in
[parity-ledger.json](parity-ledger.json); this release note does not convert them to completed work.
The legacy parity ledger is retained as historical planning data (`updatedAt` 2026-08-17). The
current capability claim source is `tools/web/manual/feature-matrix.json`, enforced by
`tools/web/check-parity-claim.mjs` (31/31 capabilities usable, local or backend). Source-unit
behavioral evidence remains tracked separately in `tests/golden/WBV2/feature-completeness-audit.json`.
## Delivery evidence