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

[yuki-328]

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

本 PR 直接基于已合并主干 3bb88e8。W1 两层报告与固定 ORT 参考用例修复为独立 PR #93；两笔 PR 的修改文件不重叠，本分支已不依赖 #93 重新执行七项技术验收。共享后端/运行时的常量绑定、日志与取消清理加固随本 PR 交付。

修改

• 完整 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/linux-reproduction-docs.yml

🔴 Possibly broken: pytest==9.1.1 — pytest 9.x did not exist on PyPI at the time of writing (8.x was current). If this version doesn't exist, pip install fails hard and the workflow is red on every PR.
Suggestion: Verify the version exists; consider pinning to a known-good release, or drop the pin and use a requirements-test.txt in the repo so dependency drift is reviewed like code.

🟡 Inconsistent supply-chain pinning — setup-python is pinned to a full commit SHA, but actions/checkout@v4 floats on a tag.
Suggestion: Pin checkout to a SHA too, or (if you prefer tag-level) apply the same policy to setup-python. The inconsistency signals that the pinning convention isn't documented or enforced.

🟡 No push trigger — The check only runs on pull_request. A force-push or admin push directly to main bypasses it entirely.
Suggestion:

on:
  push:
    branches: [main]
  pull_request:
    # ...

🟡 set -euo pipefail only in one of two run steps — The check_linux_repro_docs.py step has no explicit error handling. GitHub's default shell does set -e, but pipefail and nounset are not set by default.
Suggestion: Either add a reusable shell preamble, or use shell: bash + a common env setup. This matters if the script ever uses pipelines or references an unset variable.

💭 Consider cache: pip in setup-python — Even for a small test suite, it avoids re-downloading on every PR. Negligible here, but it's a one-liner that becomes valuable as the test suite grows.

---

📁 .github/workflows/llm-deploy.yml

🟡 full-qwen3-frontend downloads ~1.24GB on every PR — No caching. Each PR pays full bandwidth and time for the model download. Consider actions/cache on output/qwen3-full-model/, or gating this job to pull_request only for path-filtered changes and running it on workflow_dispatch/schedule otherwise.

🟡 w2-acceptance needs correct skipped-handling — if: always() + toJSON(needs) means check_w2_ci_results.py receives full-qwen3-frontend.result as "skipped" when path filters don't match. If that script treats "skipped" as "success", a PR touching only docs could pass W2 acceptance without any actual gate executing. Verify it requires "success" not just "not failure."

🟡 Mixed execution styles for unit gates — unit:frontend-ops runs pytest, unit:backend-ops runs python3 probes/.../run.py directly. The probe produces a report file but no JUnit XML. If the probe script fails silently (non-zero exit but incomplete report), the gate could mask a real failure. Ensure run.py exits non-zero on assertion failures.

💭 unit:runtime (step) has no per-step timeout — Job timeout is 60 min total; add timeout-minutes to the step too for faster feedback on hangs.

💭 Unnecessary quotes on env values — OMP_NUM_THREADS: "1" etc. GitHub Actions always stores env as strings; bare 1 is equivalent and slightly cleaner.

---

📁 .gitignore

💭 Redundant entry — .venv-linux/ 已被下一行的 .venv-*/ 通配符覆盖，可以移除以避免维护时重复。

---

📁 CONTRIBUTING.md

🟡 Suggestion — This bullet conflates two distinct policies (platform requirements + historical data preservation). Splitting them improves scannability and makes it easier to update one without touching the other:

- Qwen3 deployment (W1+) requires Linux (Ubuntu 24.04, Bash, Python 3.12,
  Linux tool paths) in all public guides, PR instructions, and CI.
  See [Linux reproduction contract](docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md).
- Preserve the actual platform and commit identity of historical measurements;
  personal dev environments are not acceptance evidence.

💭 Nit — Confirm docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md exists at the referenced path before merging, or the link will be dead.

---

📁 benchmarks/test_regalloc/regalloc.md

🟡 Windows 指令被完全移除 — 原先的 PowerShell 命令 (Windows PowerShell) 被替换而非保留为备选。如果仓库仍有 Windows 用户，建议在注释中提一句"Windows 用户请参考 X 路径或 pwsh"。

🟡 pip install -e ".[all]" 无前置校验 — 如果用户没在仓库根目录执行（文档虽写了但容易忽略），这步会静默失败。建议加一行 test -f setup.py -o -f pyproject.toml 或类似守卫，避免后续 python -m ... 报错让人误以为是 benchmark 本身有问题。

💭 新增目录无 .gitignore 提示 — .venv-regalloc/ 和 benchmark_reports/ 容易误提交。可在段落末加一句提醒 # 建议将 .venv-regalloc/ 和 benchmark_reports/ 加入 .gitignore。

💭 llvmlite 安装方式未说明 — 文档提到 llvm_available=false 的含义，但没说如何装 llvmlite。如果用户想完整对比，需要 pip install llvmlite，建议补一句。

---

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

🔴 Missing redirect for removed platforms — 删除了 macOS/Windows 全部安装说明，但没有留下任何迁移指引。macOS 用户打开此页面会直接死路。建议至少加一行：macOS 用户请参考 [macOS 指南](../path/to/mac-guide.md) 或联系项目维护者，明确告知本项目是否仍支持 macOS。

🔴 Broken reference risk — 新增链接 ../llm-deploy-v1.0/LINUX_REPRODUCTION.md，请确认该路径存在且拼写无误，否则点击即 404。

🟡 Reproduction requirement is buried — "复现记录须保存发行版、CPU、Python 和工具版本" 这条硬性要求嵌在 apt install 段落末尾，容易被读者忽略。建议独立成段或用 > ⚠️ blockquote 突出，并说明 如何 保存（例如 uname -a && python3 --version && gcc --version > repro-env.txt），否则要求等于没写。

🟡 Scope policy misplaced — "个人开发环境不作为 Linux 验收依据" 是验收政策，不是环境搭建步骤。放在"环境搭建指南"的开头会让只想装环境的人困惑。考虑移到项目根目录的 CONTRIBUTING.md 或验收文档中，此页仅留一句摘要 + 链接。

💭 WSL removal may strand existing users — 原指南明确推荐 WSL 给 Windows 用户，现在完全移除没有任何说明。如果确实不再支持 Windows/WSL，建议在删除处加一句 changelog note 或脚注解释原因，避免已有用户困惑。

💭 # Linux / macOS / WSL comment removal — 正确且一致，无需修改。

---

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

💭 Nit: 占位符语义退化 — path/to/resolved-file 看起来像实际路径，用户可能直接复制粘贴，而 <冲突文件> 用尖括号明确表示"请替换"的意图更强。

Suggestion: 改为 git add <冲突文件路径> 或 git add ./resolved-file.txt，保持占位符可辨识。

---

📁 docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md

🔴 PyYAML pin 可能不可解析 — 第 2 节：PyYAML==6.0.3。上游稳定线目前到 6.0.2，若 6.0.3 不存在，pip install -e . ziglang==0.14.1 PyYAML==6.0.3 会直接失败，而这是整份文档第一个真正执行安装的地方。建议在合并前实跑一次 pip index versions PyYAML 确认；否则换成 6.0.2 或用 >= 加 pip check 兜底。

🔴 SCRATCHV_CC 的推导路径可能拿不到二进制 — 第 2 节：Path(ziglang.__file__).parent / "zig" 假设 zig 可执行文件与包的 __init__.py 同级。较新的 ziglang wheel 把它放在 ziglang/bin/zig。建议改为显式查找：

for c in "$B/zig" "$B/bin/zig"; do [[ -x "$c" ]] && { export SCRATCHV_CC="$c"; break; }; done

或在文档中固定 ziglang 的具体版本布局并加 -e 校验 [[ -x "$SCRATCHV_CC" ]]。

🟡 各代码块不共享环境变量，单独复制会报 unbound variable — 第 3、4 节都用了 $SCRATCHV_PYTHON，但每块以 set -euo pipefail 独立开始，set -u 下未 export 即报错。文中"重新设置环境变量"只覆盖了新终端场景。建议抽一个 env.sh（或 scripts/linux_repro_env.sh）让每块首行 source，既去重也让 CI 复现同一套导出。

🟡 用 FETCH_HEAD 切换削弱了"记录实际 SHA"这条硬约束 — 第 1 节：PR ref 会移动，git switch --detach FETCH_HEAD 靠人自觉记录 SHA。建议改为显式输入：

COMMIT_SHA=<期望的完整 SHA>
git fetch origin "pull/$PR_NUMBER/head"
git switch --detach "$COMMIT_SHA"

并把"与 PR 页面对核"这一步从文档要求升级为命令本身的行为。

🟡 qemu-system-riscv64 缺失时静默退出 — set -e 下 export SCRATCHV_QEMU="$(command -v qemu-system-riscv64)" 失败会直接中断，但没有任何提示，首次安装的用户难以定位。加一行 command -v ... || { echo "...install qemu-system-misc"; exit 1; }。

💭 git lfs install 会写全局 ~/.gitconfig — 在容器/CI 上无感，但个人机器上是有副作用的操作。可考虑 git lfs install --skip-smudge 并在文档里注明这一点。

💭 "W3（含 W3 的版本）" 表头略拗口，建议写成"W3 及后续包含 W3 入口的提交"。

💭 第 2 节 pip install -e . ziglang==0.14.1 PyYAML==6.0.3 把仓库依赖与 pin 混在一条命令里：若 pyproject.toml 也声明了 ziglang/PyYAML 且约束不同，pip 的解析结果与预期不符。建议分开两步安装，并把项目自身的依赖约束作为唯一来源。

---

📁 docs/llm-deploy-v1.0/W1/IR解释器-使用说明.md

🟡 **文档结构：段落位置打断元数据块** — 新增段落插入在标题和元数据（日期、输入）之间，破坏了标题→元数据的阅读节奏。
建议：将此段移到元数据块之后，或独立为 `## 环境要求` 小节。

🟡 **相对路径需确认** — `../LINUX_REPRODUCTION.md` 相对于当前文件 `docs/llm-deploy-v1.0/W1/` 解析到 `docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md`。请确认该文件确实存在于该路径。

💭 **激活说明可更明确** — "已激活的 `.venv-linux/bin/python`" 对首次阅读者不够自洽，可补一句 `source .venv-linux/bin/activate` 或直接统一写成绝对虚拟环境路径。

---

📁 docs/llm-deploy-v1.0/W1/IR解释器-开发文档.md

🔴 **可能失效的相对链接** — 新增行：`../LINUX_REPRODUCTION.md`

文档位于 `docs/llm-deploy-v1.0/W1/`，`..` 只回退一层，实际解析到
`docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md`。若该文件放在 `docs/` 根下，
应为 `../../LINUX_REPRODUCTION.md`。
建议：确认目标路径并在 CI 里加 linkcheck，文档链接是本轮唯一新增内容，断了会直接影响交付可信度。

🟡 **`python` 的定义依赖未说明的前置步骤** — 新增行："已激活的 `.venv-linux/bin/python`"

Ubuntu 24.04 默认没有 `python`（需 `python-is-python3`），所以"激活 venv 后才有 `python`"是隐含前提，但本 diff 未给出 `source .venv-linux/bin/activate` 之类命令。
建议：明确写成"以下命令假设已执行 `source .venv-linux/bin/activate`（`.venv-linux` 构建方式见复现约定）"，避免读者在裸 shell 下执行全文失败。

🟡 **"交付 v1.0"与文内元数据 v0.1 冲突** — 第 5 行：`> 版本：v0.1，开发说明；本轮实现已落地`

新段落把适用范围声明为"正式交付、CI"，但目录是 `llm-deploy-v1.0`、文内仍写 v0.1 且"开发说明"。交付物出现版本号不一致会让复现者不确定以哪个为准。
建议：既然指向正式交付，同步把版本行改为 v1.0（或在版本行注明"目录版本 v1.0，本文档 v0.1"）。

🟡 **环境要求只约束了三样，边界不清** — 新增行：Ubuntu 24.04 x86_64 / Bash / Python 3.12

未说明 Python 是否要求具体补丁版本（3.12.x）、pip 依赖锁文件位置、GPU/CUDA 是否必需。若 IR 解释器是纯 CPU 的，建议在句尾加一句"不依赖 GPU"，否则读者会误判资源要求。
建议：补充 `requirements.txt`/锁文件路径与 GPU 依赖结论，或把这些内容下沉到复现约定并在本行只留一句指引。

💭 **新增段落插在元数据块之前，破坏原有可读性约定**

原文结构是标题 → 元数据（版本/日期/依据）→ 正文。新段落在标题后立即出现，把元数据挤到第二位，元数据反而不如开头那段环境说明醒目。
建议：移到元数据 blockquote 之后，或独立成"## 环境要求"小节，既保留元数据位置，也让环境信息有可跳转锚点。

💭 **一句话混了两个概念，建议拆分**

"正式交付、CI 和他人复现使用 ……；命令中的 `python` 指 ……"前半句是适用范围，后半句是命令约定，两者无必然联系。
建议：拆为两条，命令约定更适合放在每节命令示例首次出现处或"## 环境要求"里，而不是文档顶部。

---

---

⚠️ 未审查的文件

• 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/topics/06-性能基准套件/06-性能测试套件使用说明.md
• docs/topics/06-性能基准套件/06-性能测试套件设计文档.md
• docs/topics/09-DSL错误提示美化器/09-DSL错误提示美化器-CI与Benchmark.md
• docs/topics/09-DSL错误提示美化器/09-DSL错误提示美化器-开发文档.md
• docs/topics/17-寄存器分配/17-寄存器分配-Benchmark设计文档.md