11 KiB
FreeCAD Web 任务系统总览
本文件是任务拆分、上下文控制和恢复操作的总览。执行者不需要把整个项目装入上下文：先读交接页，再用机器清单得到当前卡的有限读取集。
后台 WASM 铁律
所有后台、内核、计算、文档处理和持久化能力，必须以相关 FreeCAD 源码为依据移植到 WASM 中执行。JavaScript/TypeScript 仅可用于 Worker、Facade、消息编排和界面适配；纯 JS 模拟、静态假数据或绕过相关源码的替代逻辑，不得作为后台能力验收结论。
规范入口
| 目的 | 唯一入口 | 说明 |
|---|---|---|
| 立即续接 | FREECAD_WEB_HANDOFF.md |
只含一个 active_task |
| 生成读取集 | python3 FreeCAD/tools/prepare_web_task_context.py |
生成 docs/current/context/<task>.json |
| 增量预算与一致性 | python3 FreeCAD/tools/validate_incremental_context.py |
只检查当前活动批次；失败即修复后再领取 |
| 全量最终验证 | python3 FreeCAD/tools/validate_web_context.py |
仅全部移植完成且用户明确指令后执行 |
| 状态变更 | python3 FreeCAD/tools/sync_web_task_state.py |
task-state.json 是唯一状态源 |
| 任务导航 | FREECAD_WEB_EXECUTION_PLAN.md、../tasks/INDEX.md |
只用于找卡，不作为执行上下文 |
| 详细协议 | FREECAD_WEB_CONTEXT_PROTOCOL.md |
规则解释和证据约束 |
| 持续执行提示词 | 可复制的持续执行提示词 | 自动完成后续任务并保持真实证据；独立文件仅作便携副本 |
上下文分层
一张卡的实际启动上下文由 prepare_web_task_context.py 计算，不能凭经验追加文件。
| 层 | 允许内容 | 硬上限 |
|---|---|---|
| L0 | 当前交接页 | 4 KiB |
| L1 | 当前卡 + 直接前置卡；最多一层 | 单卡 8 KiB；前置最多 6 张 |
| L2 | 卡片明确列出的 JSON/摘要 | 合计 12 KiB、最多 6 个文件 |
| 总计 | L0 + L1 + L2 | 16 KiB，约 4,096 token |
上下文清单记录每个文件的角色、大小和 SHA-256。mode=read 才能读取；excluded 中的路径即使卡片提到也不能装入对话。移植阶段的增量校验只检查当前活动卡、批次和 manifest；全量任务卡闭包扫描保留给最终验证。
证据文件在生成清单时按文件大小从小到大选择，并同时受总上下文字节数、证据字节数和文件数量限制；未选中的文件会在 excluded 中记录具体原因。这样超大的证据不会先进入读取清单再由校验器事后拦截。
自动排除：原始 *.log/trace、freecad-source/ 源码树、完整 workbench/object/format/dependency inventory、矩阵全文、归档和超过单文件上限的证据。源码只按卡片命令定点查看，日志只取首个错误片段，完整结果保留在磁盘。
任务分解 DAG
已完成里程碑
P0 基础闭包、P1 查看器、P2 参数化核心、P3 源码对标、P4 Python 生态和 P5 发布质量均已由各自 gate 关闭。它们的历史卡和大日志只用于审计，不进入新任务上下文。
P6 共享前置
按顺序执行 FW-P6-000（锁定基线）→ FW-P6-001（模块加载/类型注册）→ FW-P6-002（Worker/Facade envelope）→ FW-P6-003（Chrome harness）。共享合同只实现一次，模块卡只引用其 JSON 产物。
每个工作台包
P3 矩阵中的每个工作台各自拥有独立队列：
A 源码边界 → B 运行时注册 → C 一个主要内核动作 → D 错误/重算/恢复 → E Facade → F Chrome → G 持久化或适用边界 → X 首切片 gate。
首切片通过只说明一个动作可运行，不能把模块标为完成。其余动作各有一张 ACT-n 合同卡，再依次执行 ACT-n-C → D → E → F → G。所有动作完成后，Y 完整动作 gate 才能改变矩阵中的模块状态。
失败只新增同一目录的 R1/R2 恢复卡，记录首个错误、输入 hash、最小修复和重放命令；不覆盖成功证据、不复制原卡正文。
状态机
状态唯一保存在 docs/current/task-state.json；卡片、交接页、nextTask.md 和上下文摘要都是投影。合法状态为 planned、in_progress、blocked、completed，同时只能有一个可执行 in_progress。
实现与验证分层：批次实现阶段按同一 module+tier+family 聚合 24 条纯函数/只读记录或 16 条对象契约记录，最多 32 条；每批只执行源码接线、dispatcher schema、资源释放、重复/取消和最小 native fixture。完整 Python API、对象/格式矩阵、Chrome、性能和安全验证在功能族或模块收口时集中运行。未验证记录仍保持 planned/not_implemented，不能因批次实现成功而直接升级为 Full Parity。
执行去重：外层 scheduler 每回合只调用一次 continue_web_task_cycle.py。批次已在 checkpoint 的 latestBatch.completed 中时强制 planner 选择下一批；批次未变时复用 manifest，上下文输入的 bytes+mtime_ns 未变时复用 packet。失败账本在 Codex 回合内使用内存快照并在回合结束集中写入，重启只导入尚未登记且带 cycle.completed 的日志。实现阶段历史失败只保留证据并显示为 deferred，不注入回合重放。
源码检索分层：优先运行 python3 tools/fast_source_search.py 'Pattern'，只搜索当前批次 manifest 指定的源文件；runtime 适配搜索必须显式使用 --runtime，其它源码必须用受控 --path 指定。禁止从仓库根目录递归扫描完整源码树或将全量源码读入上下文。
领取：校验通过后用 sync_web_task_state.py --set ID=in_progress --active ID；ID 必须是模块目录下的叶子任务，不能是模块包父任务；工具会自动清理旧活动投影并刷新 nextTask.md。活动卡内部先运行 prepare_full_parity_module_batch.py，按 module+tier+family 选取 4-32 条记录，使用一个 native/dispatcher/Facade/Worker 链一次处理多个 unresolved records。完成：卡片只追加一个短 ## 结果，再用账本工具关闭并指向下一卡，不能停在已完成卡。阻断：保留首个失败证据并创建恢复卡，原卡保持 blocked，然后立即领取不依赖该阻断的下一卡；blocked 卡不能无恢复动作直接重新激活。模块状态只能由 Y gate 改变，不能按已完成卡数量推断。
证据合同
每张卡只产生一个可观察合同和一个主 JSON。JSON 至少包含 schema、task_id、status、source_revision、input_sha256、result_sha256、commands、artifacts、boundaries 和 generated_at。大日志不粘贴进 Markdown，只在 JSON 中保存路径、大小、hash 和首个错误摘要。
功能批次补充：主 JSON 还应包含 batchId、module、tier、family、records[]、dispositionCounts 和 nextBatch；records 数量必须大于 1（单记录模块需明确 single-record boundary），每条记录必须能回溯到源码路径和 native handler。
浏览器证据只使用固定 Google Chrome 版本、模式、viewport 和 DPR；外部请求、控制台异常和截图 hash 必须可判定。Firefox、WebKit、Safari 不执行也不作为当前验收替代。
标准操作
# 从工作区根目录
# 单次续接入口：按账本状态决定是否需要 batch/context prepare，并执行增量校验
python3 FreeCAD/tools/continue_web_task_cycle.py
# 只读取 manifest 中 mode=read 的文件，然后执行当前卡命令；结果由 scheduler 下一回合继续
# 全量验证仅在全部实现完成且收到明确指令后运行
若上下文包超限，正确动作是先拆分卡或生成更小的摘要 JSON；不得把预算改大、读取归档、复制源码或把完整日志粘入任务卡。
可复制的持续执行提示词
将下面代码块完整复制给 Codex，用于从当前检查点持续推进。它引用本页定义的入口、状态机和证据合同，不改变任务系统的权限或真实性边界。
接续当前工作区中的任务并持续执行，直到所有可执行任务完成或明确阻断。
执行规则：
1. 从当前任务账本和最小上下文检查点继续，不重复已完成工作。
2. 每完成一个批次，立即验证产物和测试结果，更新任务卡、task-state.json、交接页和上下文摘要；由外层 scheduler 在下一回合一次性领取下一个 pending 批次，禁止回合内重复轮换。
3. 不要等待确认，不要询问是否继续，不要在任务之间停顿。
4. 同时只能有一个 in_progress 任务，严禁并行领取多个任务。
5. 开始任务前只运行单一入口：
python3 FreeCAD/tools/continue_web_task_cycle.py
该入口仅在批次/上下文指纹变化时调用 prepare，并始终执行增量校验；然后只读取 manifest 中 mode=read 的文件。
6. 所有后台、内核、计算、文档和持久化能力必须由真实 FreeCAD/WASM 源码执行；不得用纯 JavaScript、静态数据或假结果替代。
7. 按任务卡完成源码边界、WASM/runtime、内核动作、错误恢复、Facade/Worker、Chrome 回放和持久化/不适用边界。
8. 浏览器测试只使用 Google Chrome，固定 headless-new、1440x900、DPR 1；记录版本、网络请求、异常和截图 hash。
9. 每张卡必须保留可复现命令、输入 hash、结果 hash、产物路径和边界说明。
10. 失败时只记录首个可复现错误、命令、输入 hash 和恢复尝试；新增 R1 恢复卡，不覆盖已有成功证据。
11. 不得把未实现、未验证或不适用的能力写成 pass；不适用必须写明原因。
12. 构建或测试失败时先自行排查和修复，再继续执行；不要跳过失败步骤。
13. 如果遇到远程 compact、代理或网络流中断，保留本地进度，从当前检查点继续，不要重做无关任务。
14. 如果一个外部依赖阻断当前卡，记录为 blocked，并继续领取不依赖该阻断的其他任务；不要伪造结果。
15. 只有在所有可执行任务完成、同一外部阻断连续三次无法解决，或确实需要用户提供本地无法发现的凭据/决策时才暂停并报告。
16. 模块状态只能由对应 Y gate 改变，不能按已完成卡数量推断；完成模块后立即领取下一个 pending 模块。
最终报告当前完成任务、阻断任务、测试结果、证据路径和下一个活动任务。
便携副本见 FREECAD_WEB_CONTINUOUS_EXECUTION_PROMPT.md；规则发生变化时，以本节和本任务系统的状态/证据约定为准，并同步更新副本。