workinf_Blender_Wasm/docs/TASK_BREAKDOWN.md

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

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

拆分参考（归档）：本文件不进入默认任务上下文。当前任务和依赖只由 print-task-context 与 parent manifest 提供；这里只在需要设计新的子任务门时读取对应小节。

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

1. 30 秒入口

每轮只按下面顺序读取：

1. docs/EXECUTION_QUEUE.md：确认唯一当前 nextTask、Chromium-only 规则和专项命令。
2. node tools/web/print-task-context.mjs：取得已经裁剪的单任务 JSON；不要读取 plan、gap audit 或 parity map。
3. docs/tasks/<task>.md：读取目标、输入、范围、验收和回滚。
4. tests/golden/<parent>/manifest.json：确认 parent hash、依赖、运行时和下一任务。
5. 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。

3.2 生成 gap 的细分协议

M16 及后续全域 gap 采用“一条 gap、一个任务、五扇证据门”的固定粒度。任务 ID、gap、owner 和 实现类别由机器 catalog 提供；任务卡只补充该条 gap 的真实 fixture、生产入口和边界，不复制全量 计划字段。

门	唯一交付	失败时的状态
C	字段/稳定 ID/错误边界契约	in_progress，不得写入成功报告
D	desktop fixture 和可重跑报告	blocked 或 in_progress，不得接 WASM
W	WASM/Main 消费同一 fixture	in_progress，不得声称 parity
R	save/reopen 或 revision 稳定性	in_progress，不得推进队列
E	comparator、manifest、status、rollback	只有 E 完成才允许 parent nextTask

生成目录中的 next-task-plan.json 是盘点输入，不是执行上下文。generate-task-index.mjs 将其切成 带源 hash 的 task-index.json 和一行一个任务的 task-catalog.jsonl；执行工具按 offset 读取单条 记录，并由任务卡恢复命令模板。索引失效、任务卡缺失、parent 指针不一致或单卡超过 8 KiB 时， 领取门直接失败。

新任务卡使用 node tools/web/generate-task-card.mjs --task <task-id> 按 catalog 单条记录生成；生成器拒绝未知 ID、没有 parent 的首项和已有卡覆盖，除非显式传入 --force。生成后必须重新运行上下文门禁。

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、可访问性	已归档；后续只按 manifest 回归
M15	全域审计	Blender 5.2 inventory、operator/node/editor/format gap	已完成计划/审计门；产出 6,900 条 M16-M22 原子 gap
M16-M22	原子 parity gap	每条 gap 独立 fixture、desktop/WASM 对标、重开和 hash 证据	只按 parent manifest 顺序推进；当前任务不在本表缓存

状态轴必须分开：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 和可回滚路径。