docs: 中级3篇 + 高级5篇 — 文档改造核心完成

新增中级 (3篇):
- Topic 06: 性能基准套件 (23个DSL用例 + 自动回归检测)
- Topic 14: 常量加载合并 (lui+addi合并 + 冗余lui消除 + 符号扩展)
- Topic 20: 代码规范 (Black/isort/Ruff/mypy + pre-commit钩子)

新增高级 (5篇):
- Topic 21: IR验证器 (7条规则: SSA/def-before-use/label/block-term等)
- Topic 22: Standalone LLVM编译器 (float32路径 + GEP + --compare)
- Topic 23: Cache模型 (组相联+LRU + I$/D$ + compulsory/conflict miss)
- Topic 28: 扩展指令选择 (sqrt/abs/branchless min + float64 D扩展)
- Topic 30: CI Dashboard (编排器 + 纯静态HTML + 两层粒度 + badge评分)

清理:
- backend_const_merge/inst_select_ext/standalone_llvm_compiler 归档到 archive
- topics/INDEX.md 全量同步 (中级11/14 ✅ + 高级5/9 ✅)

文档总进度: 5篇总文档 + 23篇topic (入门7+中级11+高级5) = 28篇 ✅
剩余: 中级3篇(10,15,27预留) + 高级4篇(24,25,26,29预留)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: k1nsom

docs/topics/06-性能基准套件.md

@@ -0,0 +1,182 @@
+# Topic 06 — 编译器性能测试套件
+
+> **难度**: 中级 | **源文件**: `benchmarks/bench_runner.py`, `benchmarks/cases/`
+
+---
+
+## 是什么？
+
+性能基准套件（Benchmark Suite）自动化测试 ScratchV 编译器的**正确性**和**性能**。它收集了 23 个 DSL 测试用例，覆盖算术、神经网络算子、控制流等各类场景，每次运行自动生成 JSON/HTML/Markdown 报告。
+
+---
+
+## 为什么？
+
+编译器每次改动都可能引入 bug 或性能衰退。手工测试既不全面也不可靠。自动化的基准测试套件让你：
+- **回归检测**：改了代码后跑一遍，立即知道有没有破坏现有功能
+- **性能追踪**：记录每次运行的时间，发现性能衰退
+- **CI 集成**：每次 push 自动运行，阻止有问题的代码合入
+
+---
+
+## 核心概念
+
+### 测试用例格式
+
+每个测试用例最多 3 个文件（放在 `benchmarks/cases/`）：
+```
+001_simple_add.dsl        ← DSL 源代码（必需）
+001_simple_add.expected   ← 期望输出（可选）
+001_simple_add.desc       ← 简短描述（可选）
+```
+
+### 23 个用例覆盖范围
+
+| 类别 | 数量 | 示例 |
+|------|------|------|
+| 算术 | 5 | add, mul, sub, div, chained |
+| 神经网络 | 6 | relu, gelu, softmax, matmul, dot, maxpool |
+| 控制流 | 7 | for-loop, if/else, while, nested |
+| 复杂场景 | 3 | NN pipeline, large chain |
+| 常量 | 1 | constant propagation |
+
+### 报告格式
+
+| 格式 | 用途 |
+|------|------|
+| **终端输出** | 开发时快速查看 |
+| **JSON** | CI dashboard 数据源 |
+| **Markdown** | 文档、PR review |
+| **HTML** | 可视化展示 |
+
+---
+
+## 一步步
+
+### 运行全部测试
+
+```bash
+# 基础运行
+python benchmarks/bench_runner.py
+
+# 指定用例目录
+python benchmarks/bench_runner.py benchmarks/cases
+
+# 生成报告
+python benchmarks/bench_runner.py \
+    --output-json benchmark_reports/dsl_bench.json \
+    --output-html benchmark_reports/dsl_bench.html
+
+# 性能基准模式（多次重复取平均）
+python benchmarks/bench_runner.py --repeat 3
+```
+
+### 用 Makefile 一键运行
+
+```bash
+make bench    # 等价于上面的完整流程
+```
+
+### 添加新测试用例
+
+```bash
+cat > benchmarks/cases/024_my_test.dsl << 'EOF'
+a = const(10)
+b = const(20)
+c = add(a, b)
+return c
+EOF
+
+echo "30" > benchmarks/cases/024_my_test.expected
+echo "My custom test: 10 + 20 = 30" > benchmarks/cases/024_my_test.desc
+
+# 运行确认
+python benchmarks/bench_runner.py
+```
+
+---
+
+## 代码走读
+
+### BenchmarkRunner 核心
+
+```python
+class BenchmarkRunner:
+    def discover_cases(self):
+        """扫描目录，找到所有 .dsl 文件"""
+        cases = []
+        for f in sorted(self.test_dir.glob("*.dsl")):
+            name = f.stem
+            expected = self.test_dir / f"{name}.expected"
+            desc = self.test_dir / f"{name}.desc"
+            cases.append({
+                "name": name,
+                "dsl_path": str(f),
+                "expected_path": str(expected) if expected.exists() else None,
+                "desc": desc.read_text().strip() if desc.exists() else "",
+            })
+        return cases
+
+    def run_case(self, case):
+        """编译 DSL → IR → 汇编 → 仿真执行 → 对比期望输出"""
+        result = BenchmarkResult(name=case["name"])
+        # 1. 解析 DSL
+        t0 = time.perf_counter()
+        program = self.parser.parse_file(case["dsl_path"])
+        result.parse_time = time.perf_counter() - t0
+        # 2. 编译
+        machine_instrs = compile_pipeline(program)
+        # 3. 仿真执行
+        output = self.simulator.run(machine_instrs)
+        # 4. 对比期望
+        if case["expected_path"]:
+            expected = Path(case["expected_path"]).read_text().strip()
+            result.passed = (output.strip() == expected)
+        return result
+```
+
+### CI 回归检测
+
+```python
+# 生成 baseline
+baseline = json.load(open("baseline.json"))
+current = json.load(open("current.json"))
+
+if current["pass_rate"] < baseline["pass_rate"]:
+    print("REGRESSION DETECTED!")
+    exit(1)
+```
+
+---
+
+## 动手练习
+
+### 练习 1: 添加一个新测试用例
+
+为你正在开发的编译器功能写一个测试用例，跑通并确认通过。
+
+### 练习 2: 故意引入 bug
+
+修改代码引入一个 bug（比如把 `ADD` 映射成 `SUB`），跑 benchmark 看看哪些测试会失败。
+
+### 练习 3: 分析性能趋势
+
+连续跑 3 次 benchmark，对比 JSON 输出，看编译时间是否有波动。
+
+---
+
+## 常见坑
+
+| 坑 | 说明 |
+|----|------|
+| **expected 文件格式** | .expected 文件应该是纯文本，末尾不要有多余换行 |
+| **超时** | 某些测试可能死循环，BenchmarkRunner 有 timeout 保护 |
+| **仿真器差异** | 不同仿真器的结果可能略有不同（尤其是浮点），expected 应基于同一仿真器 |
+
+---
+
+## 进阶阅读
+
+- [03-指标解读指南](../03-指标解读指南.md) — 如何解读 benchmark 数据
+- pytest 文档：[pytest](https://docs.pytest.org/) — Python 测试框架
+- 相关 topic: [Topic 19 — Standalone RISC-V 编译器](19-Standalone-RISC-V编译器.md) | [Topic 30 — CI Dashboard](30-CI-Dashboard.md)

docs/topics/14-常量加载合并.md

@@ -0,0 +1,143 @@
+# Topic 14 — 常量加载合并优化
+
+> **难度**: 中级 | **源文件**: `scratchv/backend/const_merge.py`
+
+---
+
+## 是什么？
+
+常量加载合并（`const_merge.py`）在汇编层面优化 RISC-V 加载 32 位常量的指令序列。RISC-V 要加载一个 32 位常数需要两条指令（`lui` + `addi`），这个优化器做了两件事：
+
+1. **lui+addi 合并**：把相邻的 `lui rd, hi` + `addi rd, rd, lo` 合并为一条 `li rd, full_value`
+2. **冗余 lui 消除**：删除连续两次加载相同高位立即数的 `lui`
+
+---
+
+## 为什么？
+
+RISC-V 指令都是 32 位定长，无法在一条指令里编码 32 位立即数。所以加载常数需要：
+```asm
+lui t0, 0x12345     # t0 = 0x12345 << 12 = 0x12345000
+addi t0, t0, 0x678  # t0 = t0 + 0x678 = 0x12345678
+```
+
+编译器简单翻译时可能产生不必要的冗余。这个优化器在汇编生成后做"post-pass"清理。
+
+---
+
+## 核心概念
+
+### RISC-V 32 位常数加载
+
+```
+最终值 = (imm_hi << 12) + sign_extend_12(imm_lo)
+```
+
+关键细节：`addi` 的 12 位立即数会被**符号扩展**。`0x800` → `-2048`（不是 `+2048`）。
+
+### 两遍优化
+
+**Pass 1: lui+addi 合并**
+```
+lui t0, 0x12345     →    li t0, 0x12345678
+addi t0, t0, 0x678
+```
+条件：两条指令相邻，目标寄存器相同，addi 源寄存器与 lui 目标相同。
+
+**Pass 2: 冗余 lui 消除**
+```
+lui t0, 0x12345     →    （删除）
+... （t0 未修改）
+lui t0, 0x12345          lui t0, 0x12345（第一次已加载）
+```
+
+---
+
+## 一步步
+
+### 使用
+
+```python
+from scratchv.backend.const_merge import merge_constants
+
+asm = """
+    lui t0, 0x12345
+    addi t0, t0, 0x678
+    lui t0, 0x12345
+    addi t0, t0, 256
+"""
+
+optimized, changes = merge_constants(asm)
+print(optimized)
+print(f"Changes: {changes}")
+```
+
+### 命令行
+
+```bash
+python -m scratchv.backend.const_merge input.s -o output.s -v
+```
+
+---
+
+## 代码走读
+
+### 合并逻辑
+
+```python
+def _merge_lui_addi(self, lines):
+    """找到相邻的 lui+addi 对并合并"""
+    for i in range(len(lines) - 1):
+        if lines[i].opcode == "lui" and lines[i+1].opcode == "addi":
+            if lines[i].operands[0] == lines[i+1].operands[0]:  # 同目标
+                if lines[i+1].operands[1] == lines[i].operands[0]:  # addi 读同一寄存器
+                    hi = int(lines[i].operands[1], 16) << 12
+                    lo = self._sign_extend_12(int(lines[i+1].operands[2]))
+                    full = (hi + lo) & 0xFFFFFFFF
+                    lines[i] = AsmLine(opcode="li", operands=[
+                        lines[i].operands[0], str(full)
+                    ])
+                    lines[i+1] = None  # 标记删除
+```
+
+### 符号扩展处理
+
+```python
+def _sign_extend_12(self, imm):
+    if imm & 0x800:   # 第11位是1 → 负数
+        return imm - 0x1000
+    return imm
+```
+
+---
+
+## 动手练习
+
+### 练习 1: 观察合并效果
+
+编译 CNN 模型，对输出汇编运行 `const_merge`，统计合并了多少对 lui+addi。
+
+### 练习 2: 手动计算
+
+手工计算 `lui t0, 0x12345` + `addi t0, t0, 0x800` 的最终值（注意符号扩展）。
+
+### 练习 3: 扩展优化
+
+添加对 `li` 后紧跟 `addi` 的合并（`li x, N; addi x, x, M` → `li x, N+M`）。
+
+---
+
+## 常见坑
+
+| 坑 | 说明 |
+|----|------|
+| **符号扩展陷阱** | `addi` 的 12 位立即数会被符号扩展，`0x800` = `-2048`，不是 `+2048` |
+| **寄存器被修改** | 两次 `lui` 之间如果目标寄存器被其他指令修改了，就不能消除 |
+| **li 是伪指令** | `li rd, imm` 是汇编器伪指令，实际可能被展开为 `lui+addi` 或单条 `addi` |
+
+---
+
+## 进阶阅读
+
+- RISC-V 指令集手册：第 2.4 节（Immediate Encoding）
+- 相关 topic: [Topic 13 — 窥孔优化器](13-窥孔优化器.md) | [Topic 12 — 指令计数统计器](12-指令计数统计器.md)