workinf_Blender_Wasm/docs/TASK_BREAKDOWN.md

项目任务分解与最小上下文指南

更新时间：2026-08-19（America/New_York）

本文件是“如何拆任务、如何领取任务、如何交接”的规划索引，不是实现状态事实源。当前状态仍以 docs/EXECUTION_QUEUE.md、当前任务的 manifest.json、对应 docs/status/<task>.md 和可复验命令为准。 本文件的目标是让一次任务只加载必要上下文，不要求阅读整份路线图或历史接续日志。

1. 30 秒入口

每轮只按下面顺序读取：

1. docs/EXECUTION_QUEUE.md：确认唯一当前 nextTask、Chromium-only 规则和专项命令。
2. docs/tasks/<task>.md：读取目标、输入、范围、验收和回滚。
3. tests/golden/<parent>/manifest.json：确认 parent hash、依赖、运行时和下一任务。
4. docs/status/<parent>.md：只读取上一项的证据摘要和已知风险。

只有遇到以下问题才继续读取：

问题	追加读取
不确定产品是否承诺	WEB_BLENDER_MODELER_V1_SCOPE.md
不确定实现事实或已有命令	PROJECT_STATUS_AND_NEXT_WORK.md 的相关小节
不确定长期依赖或全域差距	BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md 的对应 M/F 小节
不确定 family 状态	status/parity-ledger.json 和 release-evidence.json
不确定协议字段	任务卡列出的 web/protocol/* 文件，不扫描整个 web/

不要把 README.md、后续工作.txt、完整路线图和全部 status 日志作为每轮默认上下文。 根目录路线图与历史接续记录仅用于背景；它们不能覆盖机器 manifest 的指针。

2. 文档职责和冲突处理

层级	唯一职责	可以回答	不能回答
产品契约	WEB_BLENDER_MODELER_V1_SCOPE.md	V1 承诺、非目标、发布门	当前领取哪一项
短周期入口	EXECUTION_QUEUE.md	当前任务、parent、专项命令	实现是否真的通过
任务卡	tasks/<task>.md	单项范围、最小输入、验收、回滚	历史实现日志
机器事实	tests/golden/*/manifest.json、status/*.json	hash、依赖、运行时、状态轴	人类意图
完成证据	status/<task>.md	实际命令、退出码、报告、风险	下一任务的推导顺序
长期规划	BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md	M12-M23/F 域规划	当前队列指针
覆盖参考	BLENDER_5_2_FULL_PARITY_WBS.md	Blender 全域检查表	独立完成证明

冲突时使用以下优先级：

可复验命令输出 > manifest/evidence > 当前任务卡 > 执行队列描述 > 长期规划/历史日志

如果 manifest、status 和命令互相矛盾，先标记 blocked，不要修改 checkbox 或手工推进 nextTask。

3. 原子任务规则

一个任务只能有一个主要行为变化，或一个独立证据变化。把“实现、浏览器接线、发布证据”混在一项 会导致上下文过大，也会让测试文件存在被误判成生产能力完成。

每项任务都要能回答以下六个问题：

字段	最小内容
输入	parent manifest、一个最小 fixture、生产入口
行为	一个可观察的状态/数据/错误变化
边界	至少一个非法、取消、超限或重复事件
产物	一个协议/实现改动 + 一个 focused test/checker
验收	一条首选命令，必要时追加 typecheck/build
交接	report、manifest、status、下一任务、回滚点

3.1 建议的子任务门

复杂能力按以下门拆开，每个门都可独立复验：

门	交付内容	常见文件
C 契约	schema、稳定 ID、预算、错误码、revision 规则	web/protocol/*
P 生产路径	Main/Worker/App/viewport 真正消费契约	web/app/src/*、web/engine/*
N 负例	非法、重复、取消、迟到、超限不改已提交状态	web/tests/unit/*
B 浏览器	Chromium 真实用户路径和可见状态	tools/web/check-*.mjs、web/tests/e2e/*
R 资源	dispose、取消、Worker 重启、OPFS/ GPU 预算归零	Worker、storage、viewport
E 证据	报告、SHA-256、manifest、status、回滚	tests/golden/*、docs/status/*

任务卡可以把 C/P/N/B/R/E 写成子任务，但只有所有适用门通过后，主任务才可变为 done。

4. 项目阶段分解

下面是导航级分解；具体领取仍由短周期队列决定。

阶段	主题	交付边界	当前使用方式
M0	范围与状态模型	V1 契约、双轴 ledger、P0 用户闭环	已完成，持续回归
M1	工作区收口	静态门、VDB 基线、P0 一致性	已完成，持续回归
M2	大几何	10M geometry、LOD、取消、释放、恢复	已完成，持续回归
M3	长媒体	索引、seek、取消、缓存、重开	已完成，持续回归
M4	OOM/fault	WASM、OPFS、GPU、VDB 确定性恢复	已完成，持续回归
M5-M6	V1/可部署 RC	离线包、SBOM、CI、部署、升级、回滚	已完成，持续回归
M7	核心体验	action/dirty/save/restart/recent projects/input 基础	已完成，持续回归
M8	VDB 自动分页	range/OPFS/LRU/双视口/device loss	已完成，持续回归
M9	非 Mesh/GP/Paint	有界 reader/writer、Main、保存重开、故障	已完成的 V1 slice；全域仍可能 BLOCKED
M10	GN/Shader/NLA/Simulation	allowlist、compile/cache、错误与恢复	已完成的 V1 slice；完整 evaluator 仍排除
M11	Render/Compositor/Media	bounded local、server route、codec/revision/audio	已完成的 V1 slice
M12	Asset/IO/Editors	资产库、GLB/OBJ/STL/PLY、编辑器上下文	按 manifest 继续领取，不能按总百分比判断
M13	Scripting/Security	metadata-only、default-deny、sandbox、server isolation、CSP	每个安全门独立验收；execution 默认禁用
M14	Chromium 设备与输入	capability、预算、DPR、pointer、IME、keymap、modal、可访问性	当前短周期在 M14-04F
M15	全域审计	Blender 5.2 inventory、operator/node/editor/format gap	未开始；不阻断已限定 V1

状态轴必须分开：V1 releaseStatus=READY 不等于 Blender 全域 parityStatus=COMPLETE。

5. 当前 M14-04F 细分

5.1 当前已知上下文

• parent：M14-04E，状态页已记录 keymap fixture 的成功证据。
• 当前任务：M14-04F，任务卡为 docs/tasks/M14-04F.md。
• 协议：web/protocol/input-modal.ts。
• 单测：web/tests/unit/input-modal.test.mjs。
• Chromium 检查器：tools/web/check-chromium-input-modal.mjs。
• 报告/manifest：tests/golden/M14-04F/。
• focused command：npm --prefix web run test:chromium-input-modal。

当前命令已经能证明协议单测通过，并能在 Chromium 页面派发 touch/pen 事件；完成主任务前还要 确认事件确实进入生产输入状态和 Main transaction，而不是只在 checker 内构造事件并写入固定 保证值。

5.2 子任务清单

子任务	唯一目标	最小改动面	必须证明
F-C	冻结 InputModalState schema 和状态转移	web/protocol/input-modal.ts	pointer ID 非法时稳定拒绝；状态转移确定
F-T	触控 modal 取消	protocol + 生产 pointer cancel 入口	cancel 后 kind=NONE、无 Main commit、活动 pointer 清零
F-2T	双指导航 session 去重	protocol + navigation dispatch	从 1 到 2 个 pointer 只增加一次 navigationRevision；重复 down 不增加
F-P	笔 stroke 单次提交	protocol + pen pointerup/cancel 入口	第一个合法 up 最多一个 Main commit；late up/cancel 无二次提交
F-W	主线程/Offscreen 生产接线	App、viewport、Worker 输入边界	两条生产视口消费同一状态规则；cancel/late result 不污染 revision
F-B	Chromium 真实断言	checker/e2e + 最小 fixture	读取 DOM/诊断/Main revision 的真实结果，而不是只检查派发数量
F-E	证据和交接	report、manifest、status	命令退出 0、artifact hash 非空、风险/回滚清楚

5.3 完成门

主任务只有同时满足以下条件才可标记 done：

1. F-C、F-T、F-2T、F-P 的 Node 单测通过。
2. F-W 在生产 App/viewport 中有实际 import 和事件消费路径。
3. F-B 对至少 touch cancel、双指 session、pen late-up/cancel 做真实正负例断言。
4. 取消或重复事件不产生迟到 Main commit，且 revision/commit counter 可观测。
5. focused Chromium 命令、必要的 typecheck/build 和 git diff --check 通过。
6. docs/status/M14-04F.md、tests/golden/M14-04F/manifest.json 和代码 hash 一致。

如果只有协议和测试通过，状态应保持 in_progress，不得提前领取 M14-04G。

6. M14 后续任务草案

这些是领取前的拆分草案；正式任务仍须由 parent manifest 生成任务卡。

M14-04G：响应式布局无重叠/溢出

• 输入：M14-04F manifest、App shell、viewport CSS、四档 Chromium viewport。
• 正例：1440x900、1280x720、834x1112、390x844。
• 检查：scrollWidth <= clientWidth；topbar/sidebar/viewport/timeline/status 不互相覆盖；文字不被裁切；触控目标仍可操作。
• 负例：窄视口、长项目名、错误提示、打开进度、面板展开、DPR 2。
• 产物：布局 checker、4 档报告、截图或 bounding-box 摘要、manifest、status。
• 不做：Firefox/WebKit；完整响应式重设计；新增 Blender 功能。

M14-04H：键盘无障碍与焦点恢复

• 输入：M14-04G manifest、现有菜单/操作搜索/文件对话入口。
• 正例：Tab 顺序、Escape 关闭 modal、Enter 提交、焦点回到触发器、按钮有 name/role。
• 负例：modal 打开时快捷键穿透、焦点丢失、隐藏元素进入 tab 顺序、IME 期间提交 operator。
• 产物：Chromium keyboard-only checker、焦点轨迹报告、必要的 ARIA/DOM 修复、manifest/status。
• 不做：screen reader 的浏览器兼容性声明；Firefox/WebKit 证据。

M15-01A 至 M15-01F：全域清单审计

1. 从 Blender 5.2 RNA 生成 data-block inventory。
2. 生成 operator、poll context 和 property inventory。
3. 生成 modifier、constraint、shader/GN/compositor node inventory。
4. 生成 sequencer、physics、import/export inventory。
5. 生成 editor/space/region/workspace/keymap inventory。
6. 将 inventory ID 映射到 parity-ledger.json，拒绝未分类新增项并固定总 hash。

每一项都只产出一个稳定 inventory 或映射证据；不要在 M15 直接实现功能。

7. 交接格式

完成任务后，status 页只保留可审计摘要：

status: done | blocked
task: <ID>
updated: <timezone>
scope: 一句话行为变化
evidence: 命令、退出码、关键结果
artifacts: report/manifest/代码 SHA-256
nextTask: 仅复制 manifest.nextTask
knownRisk: 仍未覆盖的边界
rollback: 删除本任务产物并恢复 parent 队列尾

不要把完整终端日志、实现过程或下一阶段设想复制进 status 页；长日志留在构件目录，任务卡只留 最小输入和验收入口。

8. 领取前检查表

• 当前 task 与 parent manifest 的 nextTask 一致。
• parent status 为 done，或明确写出允许并行的 enablingTask。
• 任务卡只有一个主要行为。
• focused command 已存在，或任务明确包含创建该命令。
• 生产入口和测试入口分别列出，没有只写“相关代码”。
• 至少一个负例、取消或重复事件已列出。
• 任务状态不会误改 parityStatus/releaseStatus 另一条轴。
• 完成后能生成 report、manifest、status 和可回滚路径。