feat(w2): 完整 Qwen3 前端解析、基础后端与运行时验收

[yuki-328]

PR CI 入口合并（2026-10-11）

普通 PR 更新现在只自动触发 CI + AI Code Review 两个工作流。本次统一 CI 运行页 包含通用测试、编译器与 Topic 06 benchmark、按路径选择的部署验收和文档检查；查看 CI overview 和同页各项 Summary，详细 benchmark 报告折叠，完整产物继续保留。

路径筛选保留删除、改名与公共 CI 配置改动的覆盖；选中的任务失败、取消、跳过或结果缺失都会阻止统一验收。AI Review 保持原有独立权限，普通测试不获得仓库密钥或评论权限。同一 PR 的旧 CI 会被新提交取消。

完整 W3 IR 与完整 W4 QEMU 仍需手动明确选择。本次只调整编排、报告与回归测试，未改数值计算或阈值；下文历史完整运行数据仍对应各自记录的实际提交，不改标为本次 CI 的完整模型结果。具体配置见 CI 使用说明。

Actions Summary 更新（2026-10-11）

回补 W2 精简报告：两层 IR/QEMU、基础算子、Tokenizer 和运行时默认显示结果与关键数据，逐项详情折叠。未运行的步骤不读取残留报告；报告缺失明确提示，不宣称数值通过。新增相对 L2、余弦观察指标，不改变既有 MaxAbs 门槛。

已合并最新主干并保留原子报告发布、来源记录保护；同时修复文档重名及 Bash 示例语法。摘要、报告及相关解析回归 492 passed / 0 skipped，Linux 文档语法全扫通过。此处是报告与 CI 展示更新，没有增加 W3/W4 功能，也没有重新宣称完整模型验收。

最新提交与远端验证见本 PR 的 Checks。

为 W2 建立可独立复现的完整 Qwen3 前端、基础后端和 Host 运行时验收。完整模型不再仅由小 fixture 代表：逐项审计固定 28 层 ONNX 的实际节点、IR 和权重绑定；PR 必须实际运行完整前端任务，汇总检查拒绝失败、取消、跳过和缺失结果。

本分支已合并主干 149ae475，保留主干报告原子发布与来源校验，同时回补精简摘要。W1 报告可靠性修复已由 #93 合并；本 PR 保持 W2 验收范围，完整 IR 与完整 QEMU 分别由 #96、#104 交付。

修改

• 完整 28 层前端：结构校验、生产 parser、IR verifier、逐节点和真实权重绑定审计，失败保留上下文与日志。
• RMSNorm/RoPE/SwiGLU/GQA 前端模式测试；MatMul/逐元素/Softmax/RMSNorm/RoPE/SwiGLU/GQA 共 7 类、16 小图，在 none/all 下执行 32 次 RV64 QEMU。
• 固定官方 Tokenizer 和输入/mask/最后有效位置 greedy/停止边界；完整词表 151936 的两层随机小配置单步模型集成，原始 token ID 不裁剪或取模。
• 七项统一验收：拒绝旧输出、缺失报告、部分执行、非有限值及源码运行中变化；记录源码与资产哈希、原始命令、误差和仿真时长。
• Linux 顶层超时先通知探测清理独立编译器/QEMU 会话；补充实际进程中断和 Linux 嵌套会话回归。
• PR 上独立必跑完整前端任务；保留 W1 Linux 超时 20 次回归和三项显式产物优化集成，完整 ONNX ORT 仍为手动/夜间独立任务。文档与发布状态同步。

Linux 交付与复现（2026-10-06）

正式交付、CI 和第二人复现统一使用 Ubuntu 24.04 / Bash / Python 3.12。Linux 是运行编译器、ORT、IR 解释器和 QEMU 的 Host；目标程序仍使用 RV64 裸机 ABI。

该次交付提交 f7ebbfa745ca5be31aea857425b0e97e5ce614c2；相对 22bd3b58b5eed5f43bd43f334c9ba45b4c8bf3cb 仅补齐通用环境安装文档，执行代码与 CI 配置未变。此次更新将 W1/W2、探测及相关 benchmark 指南统一为 Linux：

• Linux 环境总入口提供依赖、虚拟环境、Linux Zig/QEMU、固定资产和交付约定。
• W2 七项统一复现使用固定资产和全新输出目录，入口为 scripts/run_w2_acceptance.py。
• LLM CI 固定 Ubuntu 24.04；新增轻量 Linux 文档 CI，检查所有公开 docs/probes/benchmarks 与根指南的指令和 Bash 语法，单独修改指南也触发检查。
• 原个人环境测量保留固定提交归档，当前页面只引用准确归属的 Linux 记录。原 benchmark 页面改为 Linux 复跑入口，原始数据仍可追溯，不将旧数据改名为 Linux 数据。
• 内部跨平台清理和路径安全检查保留，正式复现不需要其他平台工具。

执行代码提交 22bd3b5 的 Linux 文档 CI 与 Topic06 已成功；CI 和 LLM Deploy 也均已成功。最新文档提交的 Linux 文档检查 已成功；其余工作流按当前 head 的 Checks 记录。本次改动不调整模型或数值算法。

已有 Linux 验证与边界

下面属于历史提交 2d07ccc42936dcfde19d552bca02a324cd33821c，不能冒充本次更新的新运行：

• 远端 CI、LLM Deploy、Topic06 全部成功。通用测试 2927 passed / 7 skipped；test_w2_acceptance.py 在 Linux 55/55 通过、0 跳过，包含新增 SIGINT/SIGTERM 实际取消测试。LLM 确认 32/32 基础后端、28/28 两层 QEMU、3/3 显式产物集成及 20/20 次超时清理通过；两层诊断最大误差 1.7285346984863281e-6 < 1e-5。完整 ONNX release 任务按 PR 条件跳过，不能算作完整 ORT 重验。

数值门槛保持严格最大绝对误差与 rtol=0。完整前端解析不等于完整 0.6B IR/QEMU 前向，单步随机模型不等于可用文本生成。源码交付不包含模型、ELF、缓存或个人依赖。

W1 报告可靠性修复已由 PR #93 合并。作者 Linux CI 不替代第二人的七项实际执行；团队接口确认、评审与阶段出口仍待按记录完成，关联 #92。后续完整 IR 工作由 PR #96 交付。

[github-actions]

🤖 AI Code Review

共审查 10 个变更文件
⚠️ 另有 20 个文件超过上限（最多 10 个）未审查

📁 .github/workflows/ci.yml

🔴 Bug: acceptance job needs includes conditionally-skipped jobs — The docs and llm jobs are gated by if: github.event_name == 'pull_request' && .... When those conditions are false (e.g., on pushes to main, or when scope doesn't match), the jobs are skipped, not failed. The acceptance job consumes toJSON(needs) via summarize_ci.py — if that script doesn't explicitly treat skipped as pass, it will either crash or incorrectly report failure. Worse, acceptance has no if guard itself, so it runs on pushes to main too, creating a confusing red X on main even though deployment already succeeded.
Fix: Add if: github.event_name == 'pull_request' to acceptance, or ensure summarize_ci.py handles skipped results as pass. Verify both paths.

🔴 Bug: unused w4 output — w4 is declared in scope.outputs but no downstream job references it. Dead code that implies a gate that doesn't exist. Remove it or wire it to a job.

🟡 topic06 runs unconditionally on every PR and push — llm and docs are scope-gated, but topic06 has no if or needs: scope. If this is intentional, add a comment explaining why topic06 always runs. Otherwise, gate it via scope like the others.

🟡 PyYAML pinned inline, not in project deps — PyYAML==6.0.3 is installed only for topic04 CI. Local developers won't get the same version, risking CI-only test failures. Add it to pyproject.toml test dependencies (or at minimum document the discrepancy).

💭 Empty <details> block when no benchmark reports exist — The opening <details> tag is written unconditionally; if all if [ -f ... ] checks fail, you get an empty collapsible section in the summary. Minor cosmetic issue.

---

📁 .github/workflows/linux-reproduction-docs.yml

🔴 Bug: Likely non-existent pytest version — Line 25: pytest==9.1.1. Pytest 9.x doesn't exist on PyPI (latest is 8.x as of early 2025). This install will fail, and since it's in the same step as the test run with set -e, the entire job fails on every run.
Suggestion: Verify the version exists on PyPI, or use pytest==8.3.* (or pin to whatever the repo's requirements specify).

🟡 Inconsistent action pinning — Line 15: actions/checkout@v4 is pinned by tag, but line 18: actions/setup-python@<sha> is pinned by full SHA. Pick one strategy — ideally both pinned by SHA for supply chain integrity.

🟡 Missing shell strict mode — Line 22: python scripts/check_linux_repro_docs.py --check-bash runs without set -euo pipefail. If the script silently exits non-zero or a pipe in the script fails, you won't catch it. Add strict mode or wrap in bash -e -o pipefail.

💭 Nit — Line 25: Consider extracting pip install to its own step. If install fails, the step name "Exercise invalid-input rejection" is misleading — the failure isn't in the rejection logic, it's in dependency setup.

---

📁 .github/workflows/llm-deploy.yml

🔴 Bug: Dead event guard on full-qwen3-onnx — The job filters on if: github.event_name != 'pull_request', but the only trigger is now workflow_call. github.event_name will always be "workflow_call", so the 1.24 GB download / 2.38 GB FP32 model will run on every PR through ci.yml, undoing the original optimization described in the header comment. Suggestion: declare workflow_call.inputs with e.g. is_pr: true|false, pass it from ci.yml, and gate on that instead. Same logic applies if you rely on github.event_name anywhere else for caller-context decisions.

🔴 Bug: Missing workflow_call inputs block — The file declares workflow_call: with no inputs:. Once you pass a caller-context flag (see above) ci.yml must be able to do so; without a declared input the caller gets an error and every PR call breaks.

🟡 Duplicate test execution — test_llm_inputs.py, test_w2_runtime_gate.py, test_w2_runtime_metadata.py, test_w2_runtime_reporting.py appear in both the general "Tensor compiler and runtime regressions" step and the new "Runtime unit regressions in pinned environment" step (different Python envs, different junit xmls). That's ~2× runtime for those files and two sets of artifacts with overlapping coverage. Pick one location (the pinned-env one is the more correct place for W2 runtime semantics) and drop the other.

🟡 Inconsistent interpreter for W2 unit gates — unit:frontend-ops and unit:backend-ops use python3 (system Python) while every numeric probe and the new unit:runtime / integration:runtime-model use "$QWEN3_PY" (pinned venv). If those test files depend on onnx/onnxruntime/numpy versions pinned in QWEN3_PY, they'll silently diverge or fail on the system env. Switch both to "$QWEN3_PY" for parity.

🟡 frontend:parse-qwen3 downloads ~1.24 GB on every PR — This job has no if: gate and is a mandatory needs: of w2-acceptance. Confirm the probe is truly parse-only (no ORT session execution) and that the 30-min timeout is realistic given a cold Hugging Face cache on ubuntu-24.04. If nightly full downloads can be reused, add an artifact cache or a github.event_name == 'workflow_call' && !inputs.is_pr guard.

🟡 w2-acceptance gate semantics — needs: [llm-deploy, full-qwen3-frontend] means a W1-only regression inside llm-deploy (e.g. probe:small-transformer) blocks the W2 acceptance result. If W2 gates are supposed to be evaluated independently of W1, either split llm-deploy into llm-deploy-w1 and llm-deploy-w2 jobs, or have check_w2_ci_results.py explicitly inspect only the W2 step outcomes from GITHUB_STEP_SUMMARY/artifacts rather than job-level needs.

🟡 Thread env inconsistency — integration:runtime-model sets OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, and MKL_NUM_THREADS; frontend:parse-qwen3 sets only the first two. Add MKL_NUM_THREADS: "1" (and consider NUMEXPR_NUM_THREADS) for deterministic CPU timing.

💭 w2-acceptance uses if: always() — Good for surfacing partial results, but confirm scripts/check_w2_ci_results.py explicitly handles failure, cancelled, skipped, and success from toJSON(needs), and that it exits non-zero when any required W2 gate is not success. Without a hard exit the whole point of the gate is lost.

💭 persist-credentials: false — Applied to full-qwen3-frontend and w2-acceptance checkouts but not to llm-deploy or qwen3-full-onnx. If none of those scripts need token-authenticated git fetch, apply consistently for defense-in-depth.

💭 Naming drift — Job renamed to "LLM Deploy v1.0 / W1 + W2" but the workflow name is still "LLM Deploy v1.0" and the top comment still references "W1". Bump the header comment so readers don't think the W2 gates are optional.

---

📁 .github/workflows/topic06-benchmark.yml

🔴 Behavioral change: trigger removal — Removing push/pull_request means this workflow will never auto-run on code changes. Confirm a calling workflow exists that triggers it via workflow_call, or this workflow becomes dead code.

🟡 <details> placement — The opening <details> is only added when the report file exists, but </details> is too. If the report file is missing, the else branch writes to summary without wrapping — this is fine, but consider whether the "not generated" message should also be collapsible for consistency.

Everything else looks good — permissions: contents: read is the correct least-privilege addition, and the <details> syntax is valid GitHub Step Summary markdown.

---

📁 .gitignore

🟡 Redundancy — .venv-linux/ is already matched by .venv-*/. Remove the specific line or remove the glob.

💭 Order — venv/ and .venv/ precede the new patterns; consider grouping all venv-related patterns together for readability:

venv/
.venv/
.venv-*/

No blockers.

---

📁 CONTRIBUTING.md

🔴 Broken doc reference — docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md is cited but not verifiable from this diff. If that file isn't added in the same PR, this is a dead link that will fail on push.

🟡 Wrong file — CONTRIBUTING.md is for contributors. "Qwen3 deployment is delivered," "W1 and later," "independently reproduced," "acceptance evidence" are release notes / decision-record language, not contributor guidance. Move this to docs/ or a decision log; leave CONTRIBUTING.md about how to write code and open PRs.

🟡 Over-prescriptive stack pin — Hard-coding Ubuntu 24.04 / Bash / Python 3.12 / "Linux tool paths" as the public-guide mandate may conflict with existing multi-platform support (macOS/Windows, other Python minors). If the project really only supports Linux now, say so explicitly elsewhere too; otherwise contributors will assume cross-platform is dropped.

🟡 Vague claims — "W1 and later" and "independently reproduced" are unverifiable without a CI run link, PR number, or artifact. Either link them or drop the claim — CONTRIBUTING.md shouldn't carry marketing-grade status assertions.

💭 Markdown consistency — Rest of the list is single-line items; this one wraps across 5 lines with mixed indentation. Either keep it one line, or indent continuation lines by 2 spaces to match standard markdown.

💭 Process rule placement — "Personal development environments are not acceptance evidence" is a governance/culture rule. Better fit: docs/ACCEPTANCE_CRITERIA.md or .github/CODEOWNERS policy, not a bullet in the contributing style section.

---

Net: This addition mixes three concerns (deployment status, environment policy, measurement integrity) into a contributor style guide. Suggest splitting: keep only the environment-mandate bullet (if truly universal) in CONTRIBUTING.md, and move the rest to a dedicated docs/llm-deploy-v1.0/ doc that the bullet links to.

---

📁 benchmarks/test_regalloc/regalloc.md

🟡 **Over-broad install** — `pip install -e ".[all]"` pulls everything (CUDA, extra backends, etc.) just to run benchmarks. If a subset extra (e.g. `[bench]` or `[dev]`) exists or can be added, prefer it to avoid friction for contributors who only need benchmarks.

🟡 **Missing system prerequisites** — If the project compiles C++/CUDA extensions during install, the setup section should mention system deps (compiler toolchain, cmake, etc.) or point to a prerequisites doc. Otherwise first-time users will hit opaque build failures.

💭 **`--repeats` inconsistency** — Full-suite run uses `--repeats 30` but individual `bench_simple`/`bench_dense` use 100/50. Cross-comparing full-run vs individual-run numbers is misleading. Consider aligning to 30 across the board, or add a comment explaining the different iteration counts are intentional.

---

📁 docs/CI.md

Review: docs/CI.md

🟡 Branch protection gap is under-emphasized — Last paragraph mentions checking old check names for branch protection rules, but this is an operational risk that could let PRs merge without CI. Consider promoting this to its own ⚠️ callout or adding it to the table as an action item. If the name changes silently and protection isn't updated, CI acceptance becomes bypassable.

🟡 Scope-detection failure behavior is unspecified — "范围判断失败不能默认为无需验收" states the rule but not the consequence. Should the job fail outright? Run all scopes as a fallback? Print a warning and require manual confirmation? An implementer reading this doc has no unambiguous behavior to code against.

🟡 Cancel-on-push interaction with AI Review workflow — The doc says two workflows trigger per PR update and that new commits cancel old CI. Is cancel-on-push scoped to only the CI workflow, or does it also cancel the AI Review workflow (which reads from the base branch and has different inputs)? If both get cancelled, a late AI Review comment on a force-pushed PR could be lost silently.

💭 Table row descriptions mix status and content — The CI overview row mentions "选中的任务失败、取消或跳过都会使总验收失败" (gating behavior), while other rows describe what data is shown. Consider separating "where to look" from "how it gates" so a reader can quickly distinguish informational summaries from the acceptance gate.

💭 Acronym/link gaps for onboarding — "Qwen3 IR", "QEMU 前向", "Topic 06", "W4" are used without links or inline definitions. If this doc is meant as a reference for contributors, a brief pointer to each would reduce context-switching.

---

📁 docs/guide/00-环境搭建指南.md

🔴 Bug: 链接指向的文件是否存在未确认 — 引用了 ../llm-deploy-v1.0/LINUX_REPRODUCTION.md，如果该文件不存在或路径错误，读者会遇到 404。确认路径正确且目标文件已提交。

🟡 信息缺失：移除 macOS/Windows 说明后无替代指引 — 仅删除了两平台的安装命令和 WSL 提示，没有说明 macOS/Windows 用户去哪里找等效指南（即使 Linux 环境指南里也没有覆盖这两个平台）。如果这是有意为之（项目只支持 Linux），建议在删除位置留一行说明"本项目仅支持 Linux 环境，其他平台请参考 Linux 固定环境指南"，避免读者误以为遗漏。

🟡 注释不一致：W1 阶段术语突然出现 — 新增文字提到"W1 及后续阶段"和"ScratchV"，但上下文（环境搭建）对未读其他文档的读者而言缺少解释。建议加一句话说明 W1 是什么（如"第 1 周实验"），或链接到相关页面。

💭 nit: source 注释简化过于彻底 — 原来标注 "Linux / macOS / WSL" 是提醒用户跨平台通用性；现在收窄到 Linux-only 合理，但如果未来 macOS 支持回来需要回退，可以考虑改为 # Linux (Bash) 而非完全删除注释。

---

📁 docs/guide/04-故障排除FAQ.md

🟡 Placeholder ambiguity — The original <冲突文件> clearly signaled "replace this", while path/to/resolved-file looks like a literal path a reader might copy-paste without substituting.

Suggestion: Use angle brackets to preserve placeholder semantics:

-git add path/to/resolved-file
+git add <resolved-file>

---

---

⚠️ 未审查的文件

• docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md
• docs/llm-deploy-v1.0/W1/IR解释器-使用说明.md
• docs/llm-deploy-v1.0/W1/IR解释器-开发文档.md
• docs/llm-deploy-v1.0/W1/IR解释器-设计文档.md
• docs/llm-deploy-v1.0/W1/README.md
• docs/llm-deploy-v1.0/W1/W1-执行计划.md
• docs/llm-deploy-v1.0/W1/W1-探测方案.md
• docs/llm-deploy-v1.0/W1/W1-本地收尾与审查报告.md
• docs/llm-deploy-v1.0/W1/interfaces.md
• docs/llm-deploy-v1.0/W1/risks.md
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.html
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.json
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.md
• docs/llm-deploy-v1.0/W1/算子补齐与单测报告.txt
• docs/llm-deploy-v1.0/W2/README.md
• docs/llm-deploy-v1.0/W2/W1修复与W2本地验收报告.md
• docs/llm-deploy-v1.0/W2/W2-分支验收与发布说明.md
• docs/llm-deploy-v1.0/开发计划.md
• docs/reference/ARCHITECTURE_DESIGN.md
• docs/topics/06-性能基准套件/06-性能测试套件使用说明.md