data-gen-bpu/docs/engineering-checklist.md

140 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 工程收敛清单(2026-09-20)
本文件同时作为实施计划、范围约束和唯一任务清单。基线:`1be8f56`;实施分支:`fix/engineering-convergence-20260920`。只在现有隔离候选修改,不再复制新的长期工程。此前审计位于 `outputs/architecture-audit-20260920/`;本轮执行证据位于 `outputs/convergence-20260920/`(均相对工作区根)。
目标:修已证实的正确性和扩展边界缺口,继续复用 registry → pipeline/scheduler → rollout → 01–08 → verify → export。普通函数和现有模块优先;不新增调度器、业务数据库、插件平台或第二套板端执行流程。保持原本地脏补丁及远端正在运行的程序不变。
“完成”要求代码落地、针对性反例/必要回归通过、另一位 Agent 审查通过。实板、第二机器迁移与离线证据分别记录;未执行就保持待验收,不用测试数量代替结论。不承诺所有未知用例绝对无 bug。
## 总表
| ID | 项目 | 依赖 | 状态 |
|---|---|---|---|
| 0 | 保护基线、清单复核与唯一开发源 | 无 | 已复核 |
| 1 | 同步必须显式目标和基线;统一发布文件规则 | 0 | 已审查,`1ae2811` |
| 2 | HBM 身份贯穿验收与补测 | 0 | 已审查,`a003a1c`;实板归项9 |
| 3 | 归并板端占用探测,支持 S600 四核路径 | 0 | 已审查 `0f814aa`;Linux19项通过;实板归项9 |
| 4 | 保留完整 target,目标资源预览清楚 | 2、3 | 已审查 `855ec2f` |
| 5 | 指标方向成为冻结任务规则 | 2 | 已审查 `a2117e3` |
| 6 | 模型 runtime/任务身份进入相关缓存,补齐 QAT 选择 | 5 | 已审查 `8d324ea` |
| 7 | Runner 注册与 CLI/隔离策略一致 | 0 | 已审查 `a244342`;真实namespace4例/92检查通过 |
| 8 | 迁移预检与运行解析一致,工具链支持范围明确 | 1、6、7 | 路径已审查 `99ea5f7`,说明已整合待最终核对 |
| 9 | 同一主干的真实 S600 验收 | 2、3、4、6、8 | 真实资产/两板认证就绪,进入源码冻结验收 |
| 10 | 最终回归、审查、同一源码发布与回归主线说明 | 1–9 | 进入最终验收 |
同一模块的修改串行;独立文件组可并行,但每项单独 diff、审查和提交。遇到真正的环境阻塞,记录具体缺项并继续无依赖工作,不能把整项伪装成完成。
## 0. 保护与复核
- 记录候选 HEAD、原本地 HEAD/dirty patch 摘要;远端取证仅只读,远端实验只允许在已有独立测试根下进行。
- 三个子任务分别检查清单的正确性、扩展/简洁性、交付/现有环境保护;修正清单后才开始实现。
- 唯一后续开发源是当前候选分支;原项目与远端既有差异保持原样。最终提供按现有基线归并的步骤,不直接覆盖运行中的工作树。
- 禁止:重启/停止既有 collector、强推/重置旧工作树、批量改历史任务/缓存、写入生产配置、对生产执行 sync。
- 完成证据:复核意见、基线记录、归并路径说明。
## 1. 发布与同步入口收敛
- 修改范围:`scripts/sync.sh`、`scripts/sync_patch.py`、`scripts/package_release.py`,必要时一个共享发布清单小模块及针对性测试;文档在最终项统一更新。
- 操作:取消现网默认目的地,默认只预览;显式执行必须有明确目标和该目标的受信基线。缺失/漂移基线要拒绝;首次初始化提供明确只读登记步骤,不能靠 `--force` 默许覆盖。保留原远端生成 `registry/models.csv` 的保护语义。
- 打包、同步和漂移检查复用同一源文件枚举/摘要;允许明确的“只打包/远端生成”例外,不各写一份扩展名白名单。同步错误不得被管道吞掉;不自动提交调用者的所有脏文件。
- 首次使用:无目标 preview 仅本地;显式目标 preview 可以只读保存本地基线材料(目标元组、远端根、受管文件摘要和差异),不自动认为差异已归并。apply 绑定目标与被预览的本地内容并重新校验。`--files` 共用同一入口,旧 `--force` 不得绕过。首版遇到源码删除可明确拒绝 apply,不静默遗留、更不全目录删除。部分失败不推进成功基线。
- 验收:缺目标/缺基线不产生写操作;dry-run 不写远端;目标切换不能复用旧基线;远端漂移拒绝;JSON lock、Docker 文件进入相应集合;生成 registry 与业务目录不被删除;文件名和路径安全引用。
- 非目标:新部署器、自动切换生产、全目录 `rsync --delete`、复制 state/runs/密钥。
## 2. HBM 与评测对应同一产物
- 修改范围:`harness/verify.py`、`harness/pipeline.py` 的 oracle/rejudge/backfill 共用逻辑;需要时调整现有测量记录或 gate 的 provenance 处理;一个针对性测试文件。
- 操作:在公共验收入口核对当前 HBM、06 的 SHA、被采纳的 G3/G4 SHA。缺失/不一致降级对应测量并给出可读原因,必需 gate 不能 PASS;G4 可选时不因其缺少可信性能而新增全局失败;明确对历史无 SHA 记录的兼容读取与重新验收行为。补测判断使用同一规则,不因旧 `source=board` 就跳过。
- 验收:A 精度+B 产物拒绝;同一 SHA 正常通过;缺 SHA 不伪装已验证;文件被换掉能识别;G4-only 及 oracle/rollout/rejudge/backfill 不绕过;原始证据保留、读操作不重写历史。
- 三个裁决点 `verify_rollout`、`pipeline.rejudge`、`pipeline.run_oracle_job` 使用共同校验。历史 06 缺 SHA 的 backfill 明确要求重新执行 06 或返回 `needs_hbm_revalidation`,不能补填历史测量摘要。
- 非目标:第二 verifier、第二状态机、自动重跑旧任务、清空历史测量。
## 3. 一个板端占用读取实现
- 修改范围:`harness/tools/board_bench.py`、`board_perf.py`、`board_guard.py`、`harness/eval/board.py`;必要时一个被共同部署的小辅助模块;相关现有 board tests。
- 操作:共享路径发现与读数函数,支持旧布局和实际 `/sys/devices/system/bpu/bpu0..3/ratio`;保留逐核值与来源,明确聚合口径。缺读数为 unknown,不能按 0 放行。07/08 复用已有 guard/进程生命周期,避免重复 shell 名单独立成长。
- 共同占用检查由 guard 在持有板端锁之后、启动负载之前执行,不能只在主机上提前看一次;08 分块重启的生命周期必须覆盖。
- 验收:旧路径、四核路径、缺失/坏读数、单核繁忙可区分;busy/unknown 不启动本次负载;共享 helper 确实随两条调用路径上传;断连清理及互斥的旧行为保持。只清理自己创建的探针进程。
- 非目标:S600 专用脚本、重写 RemoteSession/SSH、删除主机锁或远端 guard、杀未知进程。
## 4. target 身份和资源提示
- 修改范围:`registry.py`、`pipeline.py`、`cli.py`、现有资源选择入口;相关目标测试。
- 操作:run 已冻结的完整 target 传给 job,不通过 march 反查丢 board_type;同 march 多板型若当前不能正确调度,就明确拒绝,不能悄悄忽略。capabilities/preflight 显示匹配资源数量和缺项,区分依赖检查与实板验收。
- 验收:当前 S100/S100P/S600 不变;同 march 多类型不错误选板;新增同型物理板只加登记项/slot;资源为空清楚提示,不新增运行/写 DB。
- 非目标:提前实现 X5 工具链、按板型复制 pipeline、为未知设备创建通用硬件框架。
## 5. 指标方向明确
- 修改范围:`registry.py` 的 gate snapshot、`gates.py`、必要的 `registry/gates.yaml`,相关 gate tests。
- 操作:新快照冻结显式 higher/lower 方向(多指标各自表达);g3 按每个 metric 消费配置并拒绝测量 metric 与冻结 metric 冲突,旧快照保持有限的现有回退。未知新指标缺方向在准入时拒绝,不默认越大越好。
- 验收:MAE 1→2 不通过、1→0.5 通过;higher 指标行为不变;多指标混合方向;非法/缺方向拒绝;现有 SE/容差及原任务数值结果不被顺带改变。
- 非目标:让 evaluator 自己裁决、改所有历史 gates、引入 gate 插件框架。
## 6. runtime 与缓存的真实对应
- 修改范围:`paths.py`、`stages/s02_baseline.py`、`stages/s03_export.py`、`stages/base.py`(确有必要时)、`backends/qat.py`;相关缓存测试。
- 操作:QAT/ PTQ 的模型导出统一使用 `model_python(job)`;baseline/ONNX 元数据与复用比较包括相关冻结 runtime/task/export 身份;不同相关身份使用不同缓存位置以免并发覆盖,旧 job 继续原位置。以新增冻结 cache 身份版本区分,不能仅靠已存在的 model_runtime/task_contract 字段判断新旧;`cached()` 的直接调用也遵守校验(后续配方切片已移除无生产调用的 `inputs_ready()` 和对应无效 mock)。baseline 与 ONNX 各取真正相关的字段,不把所有 gates/任务配置塞入 ONNX 身份。缓存命中前验证新 job 的运行环境约束;不能给旧缓存贴上新环境标签。
- 验收:A 环境缓存不能作为 B 产物;显式新身份遇到旧无身份缓存不直接命中;相同身份仍复用;QAT 命令使用配置 Python;旧未声明 runtime 的兼容规则清晰。路径身份不是完整二进制/包环境摘要,文档如实限定。
- 非目标:重建全部缓存、删除历史缓存、全量扫描/哈希巨大环境、批量重写模型 adapter。
## 7. Runner 的共同入口
- 修改范围:`harness/runners/__init__.py`、`cli.py`、`scripts/jail_setup.py`、必要的现有 runner 模块;相关 runner/jail tests。
- 操作:CLI choices 从注册处派生;隔离所需 HOME 隐藏/运行环境保留采用共同的可信策略,不继续按 OpenCode 品牌扩展分支;Pi 历史兼容例外保持明确。不得扩大 Agent 的宿主可写范围。
- 验收:临时第三 runner 注册后能力列表与 CLI 一致;相同隔离策略下不会因名字不同漏隐藏 HOME;Pi/OpenCode 现有初始化、预算与会话导出回归;涉及 mount 的改动须在 Linux 宿主上新建独立 unshare user/mount/PID namespace 做真实最小探针,禁止在宿主原 mount namespace 操作。
- 非目标:实现第三个真实 Agent、重写 Pi 所有历史代码、动态插件发现、关闭 jail 以通过 Docker 测试。
## 8. 配置、工具链与迁移一致
- 修改范围:`paths.py` 和 `scripts/migration_inventory.py` 的路径解析;`docs/extensions.md`、`docs/portability.md`;必要的既有 toolchain 测试。
- 操作:清单与 runtime 共用 config/state 解析,显式 `--config` 优先于 `BENCH_CONFIG`、再到所选 root 默认;state 相对路径基准与 runtime 完全一致,报告 resolved 位置。共享解析不得读取秘密、建目录或开数据库。工具链 profile 的范围明确为已实现 backend 协议下的环境版本选择;04 固定配置、06 固定输出解析的边界直接记录,未知 backend/不兼容组合拒绝。不为未获得的第二套专有工具链预写解析器。
- 验收:`BENCH_CONFIG`/`BENCH_STATE_DIR`/显式 `--config` 指向的清单与 CLI 一致;清单只读;05/06 profile Python 正确传播,08 使用模型/板端 runtime 的职责不被破坏;真实第二版本只有提供环境并验收后才列为支持。
- 非目标:第二套配置层、把全部专有环境装进镜像、以离线命令测试宣称跨版本 ABI 兼容。
## 9. S600 业务闭环
- 先由板端执行 Agent 只读核对新端点身份、现有占用、凭据可用性和编译资源;使用隔离测试配置及新板资源,不修改原 `boards.yaml`/现网配置或抢占旧 slot。
- `BENCH_CONFIG` 不切换 registry;隔离部署的 `BENCH_ROOT`、PYTHONPATH、registry 必须指向同版测试源码。访问同一物理板的测试参与者共用 `BENCH_STATE_DIR` 及板端 runtime_dir 锁根,禁止独立锁绕过。
- 使用本次同一 bench 源码的既有命令与 01–08 路径,选择有真实权重/数据/评测依据且成本合适的已支持模型。记录模型、量化条件、工具链、HBM SHA、物理板身份、精度/性能、日志。
- 验收:至少一个 S600 完成真实编译→07→08→verifier;第二同型板仅配置接入并复用同一 HBM 真实推理验证,不重复编译和全套精度;断连后的本次进程回收与多板/同板互斥;S100P 可用且空闲才做真实回归,否则记录未覆盖并保留离线回归。
- 若认证、环境或不干扰现有任务的资源无法满足,记录准确阻塞和已完成覆盖,绝不写“实板通过”。外部需要的配置只在隔离位置准备,不因等待把未验项勾完。
## 10. 最终验证与交付
- 最终代码冻结后跑相关单测集合与一次完整既有回归;测试期间无源码变动。第三方审查检查实际 diff、每项验收证据及范围,而非只读执行者总结。
- 源包和 Docker 从同一版本生成;校验 manifest、配置默认和所需依赖。先保证控制层可运行;完整容器业务因 jail/依赖未通过时如实保留限制,不放宽隔离来换绿灯。
- 在本清单记录每项提交/测试/审查/真实覆盖,更新原有扩展与迁移说明,标注先前发布包仅在后续开发/验证上被新候选替代;实板未验不得称业务 release 已验收,不删除原始证据。
- 写明当前候选如何与原本地/远端既有差异归并为唯一主线、部署时如何核对前像与回退。不部署到原运行目录、不替用户决定停机窗口。
- 最后比对保护基线。该项只验证和记录,不混入新功能;发现实现错误回到对应项修复再复核。
## 审查后的决定与执行记录
三份清单复核:`outputs/convergence-20260920/review/plan-board.md`、`plan-extension.md`、`plan-delivery.md`。已采纳:G4可选语义、三个验收入口、guard锁内探测、实际registry与共享锁域、方向/metric一致、按相关身份隔离缓存、独立namespace、scoped sync保护、首次preview基线及精确删除边界。实施前基线回归:236 tests + 57 subtests通过,日志为 `evidence/baseline-tests.log`;这仅是旧覆盖基线。
实现只修本清单已确认的问题;遇到额外问题先记录其影响和最小改法,由主 Agent 审查是否确有必要,不顺手扩大范围。
项目3/5独立反例确实拦下了“只读日志命令误判推理”和“等价旧方向导致重复展开失败”,修复后各自复审通过。项目5没有改默认 gates.yaml 的源字节,新快照由有限历史表冻结已知方向,新增未知指标仍需声明。项目3最终 helper 在隔离 Linux 再跑19项通过,日志 `evidence/runtime-prep/guard-final-linux.log`;进程名单只覆盖已知入口,不能声称识别任意第三方推理。项目7结果为真实挂载/进程 namespace 检查,不等于真实 Agent+LLM 业务验收;见 `review/runtime-prep.md`。
项目6独立反例拦下了两个venv的Python软链被realpath合为同一缓存身份的问题,也核对了最旧job相对runtime的行为保持。新契约保留实际venv调用路径,旧job继续旧读取语义。最终源码冻结后,本文件保留冻结时状态;9/10的完成、阻塞、包身份和原环境保护结论统一记录在工作区 `outputs/convergence-20260920/DELIVERY.md`,原始证据在同目录evidence/review,不为补写验收结果改变已经实测的源码包字节。
保护观察:本轮开始远端基线包含3个既有collector(按PID+start_ticks保存),不要沿用此前6个的旧口径。原本地 `registry/boards.yaml` 于17:09出现40011 disabled的并发变动,根Agent已向用户澄清来源;本团队核对写路径均为候选/测试目录,尚不归因、绝不回滚。后续保护比对应单列此变动,不能继续写原本地“逐字节完全不变”。
## 11. 任务内配方与可修改 ONNX(本次切片)
依据工作区 `outputs/adapter-plan-20260920/PLAN.md`,仍在同一候选分支实现。原工作树和运行进程不升级。完成状态按代码、测试、真实业务分别列明,不能把 fixture 当官方模型或实板。
| 子项 | 实施范围 | 验收 |
| --- | --- | --- |
| 清理遗留 | 删除无生产调用的 inputs_ready 和无效 mock | 原领取、续跑、缓存回归 |
| 接收配方 | 原 stage client / Worker 显式文件快照;沿原 metadata 入口绕过同名公共 adapter | CLI 到 Worker、路径逃逸、提交后改文件、任务展开 |
| 执行与图迭代 | 受限模型进程;03 同时接收导出和直接 ONNX;参考与候选依赖隔离 | 真实 Linux namespace、导出、ORT、错误头和错误预测反例 |
| 完整产物链 | 原 04–08 与 verifier 核对本次图、校准、编译和 HBM;禁止跨提交拼成绩 | 真实文件漂移、历史父引用可复用、实际字节变化拒绝、新失败不沿用旧成功 |
| 独立评分与校准 | 无标签数组穿过隔离边界;平台保留评分;原 make_calib 训练来源复用 | 固定 T1 评分、T0/T1 排除、前处理身份及校准隔离 |
| 使用入口 | 原 prepare 的 recipe 按需材料/阶段提示;旧模板行为保持 | 新旧任务提示回归 |
| 减法复核 | 不新增队列、数据库、调度器、插件注册或板端流程 | 独立监督 Agent 审查;公共薄 adapter 删除等真实等价验证后再做 |
实际测试结果及剩余验收见工作区 `outputs/adapter-implementation-20260920/REPORT.md`。当前切片支持范围为 PTQ 分割与 CPU 模型执行;真实 SegNeXt、第二变体、04–08 实板及新机器完整迁移不由离线用例自动宣告完成。后续减法边界:03 撤掉基线/等价前置,材料按操作要求;04 允许编译参数试验并复用校准;历史父引用固定;正式隔离调用保留日志并复用单阶段环境/参考核验。新 recipe 复用 private-home,只有真实隔离才放开工作区 shell。实现与独立反例结果见工作区 `outputs/simplification-implementation-20260921/REPORT.md`;不以总代码行数或离线 fixture 冒充 Agent 效果、实板或迁移验收。