Repository navigation
[W2] 分块评审与独立验收指南 #100
Description
验收指南，2026-10-06。已核对 PR #94 的当前提交与对应 CI 运行结果；代码评审、独立复现和团队签认分别记录。
目的、范围与固定版本
为 W2 PR #94 按职责认领评审和验收；这是四个评审块，不是拆 PR 的执行方案，也不要求每个人跑全部内容。W1 PR #93 的两层报告/参考测试修复单独归属，不能混入 W2 的证据。
- 比较基线：
3bb88e81498d6d9293aed70e25a4e5a2104465d0（PR feat(qwen3): 跑通 W1 两层 RISC-V 仿真，补齐精度、计时与独立复现验收 #91 合并提交）。 - 本次待验收 HEAD：
2d07ccc42936dcfde19d552bca02a324cd33821c，分支codex/w2-qwen3-acceptance。 - 差异：45 文件，新增 7892 行、删除 39 行；其中测试 15 文件、新增 3147 行。
- 以下代码与测试路径均相对固定版本源码的仓库根目录；请在自己的 checkout 中核对完整 SHA 后执行。
快速分工
每块连同自身测试和 README 一起审查；代码评审、独立执行和团队签认是三种证据，不能互相代替。人员可分别认领，执行范围按本表与回复模板说明。
代码评审者说明检查了哪些失败路径；执行者附自己生成的报告；团队签认者确认该块结论、边界与问题归属。只认领角色或回复“已看”不代表通过。发现跨块问题时标注受影响块，修复后由相应负责人补充复验，不必让所有人员重复运行。
| 块 / 规模 | 负责人 | 代码 review | 独立执行 | 团队签认 |
|---|---|---|---|---|
| A 完整前端审计：7 文件 | 待认领 | ☐ 待认领 | ☐ 待认领 | ☐ 待认领 |
| B 四模式与基础后端：9 文件 | 待认领 | ☐ 待认领 | ☐ 待认领 | ☐ 待认领 |
| C Host 运行时与单步集成：14 文件 | 待认领 | ☐ 待认领 | ☐ 待认领 | ☐ 待认领 |
| D 统一验收与 CI：15 文件 | 待认领 | ☐ 待认领 | ☐ 待认领 | ☐ 待认领 |
| W2 整体七门禁独立复现 | 待认领 | ☐ 汇总核对 | ☐ 待认领 | ☐ 出口确认 |
A：完整前端审计
源码 / 文档： probes/w2_qwen3_parse/{validation,audit,run}.py 与该目录 README.md。
对应测试： tests/test_qwen3_full_{structure,audit,parse}.py。
审查问题： 层数是否由真实数据流证明？同形状权重替换、错误残差、缺节点或错误绑定能否被拒绝？审计是否独立于 parser 自身判断？资产哈希、verifier、失败上下文、超时及报告发布是否可信？
通过条件： 相关测试通过；固定完整模型的 full-parse 实际完成，28 层、节点/绑定审计与 verifier 均通过，报告可追溯到本次源码。完整解析不证明完整模型 IR 数值正确，也不证明完整模型 QEMU 前向。
B：四模式与基础后端
源码 / 文档： probes/w2_backend_ops/{cases,run}.py 及 README；scratchv/backend/tensor_c_codegen.py、scratchv/runtime/riscv_tensor.py。
对应测试： tests/test_qwen3_frontend_patterns.py、tests/test_w2_backend_ops_gate.py、tests/test_tensor_c_codegen.py、tests/test_riscv_tensor_runtime.py。
审查问题： RMSNorm/RoPE/SwiGLU/GQA 是否有独立公式和语义反例？none/all 是否都运行？外部绑定能否覆盖标量 IR 常量？编译/QEMU 主错误会否被日志异常遮蔽，取消是否遗留自有子进程？
通过条件： 对应测试及文档核对完成；frontend 22 项与 backend 16 小图 × 两档优化共 32 次实际 QEMU 通过，数值保持 max_abs < 1e-5、rtol=0。mock 成功不代替目标执行；Linux 清理行为须取得 Linux 证据。
C：Host 运行时与单步集成
源码 / 文档： scratchv/runtime/{qwen3_tokenizer,llm_inputs}.py；probes/w2_runtime/ 的 runner、语料与 README；probes/w2_runtime_model/；pyproject.toml 的可选依赖声明。
对应测试： tests/test_{qwen3_tokenizer,llm_inputs}.py，以及 tests/test_w2_runtime_{gate,metadata,reporting,model}.py。
审查问题： 官方配置、基础词表/实际 ID/模型宽度是否区分？特殊 token、规范化、空/超长输入、mask、最后有效位置、greedy 平局与停止原因是否一致？是否保留原始 token ID 和完整 logits，报告失败是否阻止 PASS？
通过条件： 对应测试、runtime 官方语料对照和 runtime-model 单步集成通过，附本次资产身份、误差与采样结果。模型集成是完整词表、两层随机小配置，不是完整预训练模型、完整词表 QEMU 或多步生成验收。
D：统一验收与 CI
源码 / 文档： scripts/{run_w2_acceptance,check_w2_ci_results}.py、.github/workflows/llm-deploy.yml；W2 指南/发布说明、W1 状态与接口文档、总开发计划、两层探测 README 的相关增量。
对应测试： tests/test_w2_acceptance.py、tests/test_w2_ci_results.py。
审查问题： 子门禁零退出但缺报告、skip、NaN、旧目录、运行中源码变化能否拒绝？取消后能否清理嵌套会话并保留主错误？CI 汇总是否拒绝失败/取消/跳过/缺失，完整解析是否真正进入必需依赖？
通过条件： 对应测试通过，Linux 取消/嵌套会话回归实际执行；工作流结构、调用与文档一致，取得固定 SHA 的实际远端 CI 证据。仅有 YAML 或本机通过不能签认远端成功。
依赖与执行边界
A、B、C 可并行评审；D 的整体验收依赖前三块。前端模式测试直接导入 w2_backend_ops，应留在 B；单步模型依赖 w2_runtime，留在 C；D 的真实取消回归依赖 B 的 SIGTERM 清理协议。
统一入口自动补入 runtime-model → runtime、small-qemu → small-ir。分块执行可用 --gates 选择相关门禁；即使选中项目全通过，也只能得到 PARTIAL / 退出 2。失败/阻断为 FAIL / 1，只有七门禁完整通过才是 PASS / 0。各块不必重复完整七门禁；另由一位独立复现负责人提供完整结果。
统一复现入口与源码身份
在独立环境取得上述固定 SHA，使用现有固定依赖和已校验资产。下列占位路径须替换，每次输出目录必须不存在。先按W2 复现说明准备固定 Python 环境、工具链和资产；下列命令只使用已有环境与资产。
Set-Location '<固定 SHA 的独立源码目录>'
git rev-parse HEAD
git status --short
$w2Python = '<固定环境的 python.exe>'
& $w2Python -B -X utf8 scripts/run_w2_acceptance.py `
--python $w2Python --output-dir '<全新输出目录>' `
--tokenizer-dir '<官方 Tokenizer 目录>' --tokenizer-mode verify `
--model-dir '<固定完整 ONNX 目录>' --model-mode verify `
--cc '<Zig 或编译器路径>' --qemu '<QEMU RV64 路径>'
$LASTEXITCODE保存命令、环境/工具版本、退出码、总报告和子报告；核对 HEAD、dirty 状态及源码 SHA256。源码包没有 .git 时须明确未知 Git 身份，附与固定 SHA 的文件清单核对，不能继承父仓库身份。本机新源码副本不等于第二人独立复现；修改源码后须更新验收版本并重跑受影响范围。
已有证据与尚未验收
发布时已核对 PR #94 仍为 open，HEAD 为 2d07ccc42936dcfde19d552bca02a324cd33821c。以下三次运行均为同一 HEAD、状态 completed、结论 success：
PR #94 正文的“全流程 review 后的修复与重验（2026-10-05）”记录了本提交取消清理修复、作者重新执行七项验收 7/7 PASS，以及 Linux 回归结果。分支发布说明中的初始交付记录和 W1+W2 历史整合报告仍按各自源码归属，不能混作当前提交的新执行结果。
本次发布核对了远端运行状态与提交身份，没有重新执行模型或逐项重验原始产物。以上属于作者验证及 CI 证据，不代表模块代码评审、第二人独立复现或团队签认已完成，因此认领表与关闭清单仍待填写。Windows 跳过的 Linux 专属用例不能计为通过；W1 接口冻结继续由 Issue #92 跟踪。
可复制回复模板
认领块 / 角色：A/B/C/D/整体；代码 review / 独立执行 / 团队签认
人员、日期、固定 HEAD：
环境与独立性（机器、依赖、工具、资产身份）：
审查路径与测试/门禁范围：
完整命令、退出码、通过/失败/跳过数及原因：
证据链接（报告、日志、源码指纹；整体另附七门禁总报告）：
发现的问题、处置链接与复验范围：
结论：通过 / 有条件通过 / 未通过；未覆盖边界：
团队签认依据（仅相应角色填写）：
关闭条件
- 四块负责人已认领，代码评审、对应执行证据和团队结论齐备。
- 阻断问题已处理并复验；无未解释失败或把跳过计作通过的情况。
- 固定 SHA 的 Linux 清理回归及实际 CI 证据已核对。
- 第二人独立环境的一份七门禁完整结果为 PASS / 0，源码与资产身份可追溯。
- 团队确认本 Issue 的验收边界和遗留事项归属；没有据此声称完整模型数值/QEMU、生成循环或 W1 接口已冻结。
Activity