123 lines
11 KiB
Markdown
123 lines
11 KiB
Markdown
# FreeCAD Web 任务系统总览
|
||
|
||
本文件是任务拆分、上下文控制和恢复操作的总览。执行者不需要把整个项目装入上下文：先读交接页，再用机器清单得到当前卡的有限读取集。
|
||
|
||
## 后台 WASM 铁律
|
||
|
||
所有后台、内核、计算、文档处理和持久化能力，必须以相关 FreeCAD 源码为依据移植到 WASM 中执行。JavaScript/TypeScript 仅可用于 Worker、Facade、消息编排和界面适配；纯 JS 模拟、静态假数据或绕过相关源码的替代逻辑，不得作为后台能力验收结论。
|
||
|
||
## 规范入口
|
||
|
||
| 目的 | 唯一入口 | 说明 |
|
||
|---|---|---|
|
||
| 立即续接 | [`FREECAD_WEB_HANDOFF.md`](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`](FREECAD_WEB_EXECUTION_PLAN.md)、[`../tasks/INDEX.md`](../tasks/INDEX.md) | 只用于找卡，不作为执行上下文 |
|
||
| 详细协议 | [`FREECAD_WEB_CONTEXT_PROTOCOL.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 不执行也不作为当前验收替代。
|
||
|
||
## 标准操作
|
||
|
||
```sh
|
||
# 从工作区根目录
|
||
# 单次续接入口：按账本状态决定是否需要 batch/context prepare，并执行增量校验
|
||
python3 FreeCAD/tools/continue_web_task_cycle.py
|
||
# 只读取 manifest 中 mode=read 的文件，然后执行当前卡命令；结果由 scheduler 下一回合继续
|
||
# 全量验证仅在全部实现完成且收到明确指令后运行
|
||
```
|
||
|
||
若上下文包超限，正确动作是先拆分卡或生成更小的摘要 JSON；不得把预算改大、读取归档、复制源码或把完整日志粘入任务卡。
|
||
|
||
## 可复制的持续执行提示词
|
||
|
||
将下面代码块完整复制给 Codex，用于从当前检查点持续推进。它引用本页定义的入口、状态机和证据合同，不改变任务系统的权限或真实性边界。
|
||
|
||
```text
|
||
接续当前工作区中的任务并持续执行，直到所有可执行任务完成或明确阻断。
|
||
|
||
执行规则：
|
||
|
||
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`](FREECAD_WEB_CONTINUOUS_EXECUTION_PROMPT.md)；规则发生变化时，以本节和本任务系统的状态/证据约定为准，并同步更新副本。
|