Add topic 06 benchmark test suite

[2813183274-cloud]

本次更新

• 增加 DSLInterpreter 与真实 TinyFive 双后端独立验证，禁止后端结果互相回退
• 覆盖 23 个 DSL 用例，包括 activation、branch、elementwise、loop、reduction 和 tensor
• 为每个用例生成独立 Markdown/JSON 报告，并生成 Markdown、JSON、HTML 汇总报告和指令数图表
• 使用真实 TinyFive 动态执行指令数作为主要性能指标，维护 15 个可稳定执行用例的性能基线
• 增加编译 30 秒、TinyFive 模拟 5 秒超时保护
• 增加失败原因分类、按类别/名称筛选和可配置性能退化阈值
• CI 自动生成完整报告，并上传 topic06-benchmark-reports Artifact
• 精简报告字段，删除无实际区分作用的报告版本、运行模式和重复 Benchmark 数据

当前结果

• DSL 用例总数：23
• TinyFive：15 PASS，8 UNSUPPORTED
• 性能基线用例：15
• 性能退化：0
• reduction/tensor 共 8 个用例：DSLInterpreter 可得到预期结果，TinyFive 因非标量输入 ABI 尚未接通而标记为 UNSUPPORTED
• branch/loop 共 6 个用例：TinyFive 执行通过，DSLInterpreter 因暂不支持控制流语义而标记为 UNSUPPORTED

报告与性能指标

• 汇总报告展示双后端状态、失败类型、TinyFive 动态指令数、基线变化率和两端输出
• 单用例报告保留完整汇编、后端状态、核心性能指标和耗时诊断
• JSON 报告保留完整结构化诊断数据，供 CI 和后续工具读取
• 固定输入下 TinyFive 动态指令数具有确定性，因此每个用例只执行一次，不再重复三次计算均值和置信区间
• CI 使用仓库中的既有基线进行回归比较，不会自动覆盖基线

已知限制

• TinyFive 当前没有接通数组和矩阵输入所需的非标量输入 ABI，因此 reduction/tensor 用例暂不参与 TinyFive 性能基线
• DSLInterpreter 当前不支持 if 和 for 等控制流语义，因此 branch/loop 用例仅由 TinyFive 完成真实编译执行验证

[github-actions]

🤖 AI Code Review

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

📁 .github/workflows/topic06-benchmark.yml

Code Review

🔴 upload-artifact 在无文件时会导致步骤失败

Line 51–64: if: always() 使得该步骤在先前步骤失败时仍执行，但 actions/upload-artifact@v4 在 path 中列出的文件不存在时会返回失败。这会掩盖真正的失败原因，且在 CI 日志中产生额外噪音。

建议：加 continue-on-error: true，或在上传前检查目录是否存在：

      - name: Upload Topic 06 reports
        if: always()
        continue-on-error: true
        uses: actions/upload-artifact@v4

---

🟡 正确性门禁中断后续类别执行

Line 28–30: 三行串行执行，若 --category activation 失败，shell 默认 set -e 会终止后续 elementwise 和 loop 类别，导致诊断不完整。

建议：若意图是"全部跑完再汇总"，加 set +e；若意图是快速失败，当前行为可接受但应在注释中说明。

      - name: Run supported correctness gates
        run: |
          set +e
          python scripts/run_topic06_benchmarks.py --category activation --fail-on-test-failure
          python scripts/run_topic06_benchmarks.py --category elementwise --fail-on-test-failure
          python scripts/run_topic06_benchmarks.py --category loop --fail-on-test-failure

---

🟡 重复执行 benchmark 脚本

Line 28–30 vs Line 33–34: correctness gates 与 full diagnostic 均调用 run_topic06_benchmarks.py，导致基准测试执行两次。建议合并为一次运行，通过参数同时输出正确性门禁与诊断报告。

---

🟡 缺少 concurrency 控制

同一分支的快速连续 push/PR 更新会并行触发多次 workflow，浪费 CI 配额且可能产生竞态。

concurrency:
  group: topic06-benchmark-${{ github.ref }}
  cancel-in-progress: true

---

💭 artifact 路径不一致

Line 64: benchmarks/topic06/baseline.json 与其他 benchmark_reports/topic06/ 路径不同源，需确认是否为有意为之（baseline 从 benchmarks/ 目录读取）。

---

💭 建议显式声明 permissions

permissions:
  contents: read

默认权限因仓库设置不同可能不一致，显式声明更安全且意图清晰。

---

📁 Makefile

🟡 Sequential scripts without dependency awareness — Lines 68-69: If run_topic06_benchmarks.py produces output consumed by generate_topic06_report.py, consider combining into a single script or using a temp file pattern. Right now the coupling is implicit — a failed intermediate step yields a misleading "success" report generation (empty/garbage input).

💭 Missing script existence guard — Other targets in this file don't have it, but these are new scripts. A common failure mode is python3: can't open file 'scripts/run_topic06_benchmarks.py' with no guidance on the expected repo state.

💭 Target name inconsistency — Existing bench targets are bench and bench-cnn (no numeric suffix). Consider bench-tinyfive or bench-dsl-correctness for discoverability and consistency with the existing naming convention.

---

📁 README.md

🟡 命名/定位不一致 — 新增的 bench-topic06 描述为"性能测试套件"，但文档链接描述为"正确性验证、Benchmark 与回归报告"。两处应统一，建议都改为涵盖正确性验证 + 性能基准 + 回归的全称。

🟡 计数不一致 — 原来 benchmarks/ 标注"23 个 DSL 基准用例"，现在改成了"通用基准与课题 06 性能基线"（无数量），而 tests/ 新增了"课题 06 的 23 个 DSL 用例"。确认一下：这 23 个 DSL 用例确实从 benchmarks/ 移到了 tests/ 下？如果是，更新准确；如果两边都有，benchmarks/ 缺失了数量说明。

🟡 目录描述混入课程上下文 — 三处目录说明都加入了"课题 06"前缀，而该 README 同时面向通用项目使用者。如果这是面向公众的项目 README，建议把课题特定信息移到文档表格（已有入口链接），目录树保持中性。

💭 make target 排序 — bench-topic06 放在 bench-cnn 前面，打破了 bench-* 字母序（topic06 < cnn 按字母序不成立，按语义也不如通用到专用排列自然）。建议放到 bench-cnn / bench-ci 之后。

---

📁 benchmarks/topic06/baseline.json

Code Review

🔴 Bug: dynamic_instructions 与分项之和不一致（系统性差值 +1）

每一组 cost_model 中，dynamic_instructions 都等于 dynamic_load + dynamic_store + dynamic_mul + dynamic_add + dynamic_madd + dynamic_branch + 1，而非等于其和：

case	分项之和	声明值	差
add_relu_relu	6	7	+1
relu_only	3	5	+2
if_else	16	18	+2
add_chain	3	4	+1
loop_add_4	39	44	+5

这说明要么存在未被拆分的指令类别（如 cmp、mov），要么计量逻辑有 off-by-one。请确认并补充说明或修正。

---

🟡 Timestamp 无时区且为未来日期

"generated_at": "2026-09-21T16:51:35" 缺少时区偏移，且 2026 年当前尚未到达——请确认不是测试环境时钟配置错误，建议改用 ISO 8601 完整格式如 2024-XX-XXT16:51:35+08:00。

---

🟡 缺少 schema version 和 toolchain 标识

文件本身没有版本号字段（如 "schema_version": "1.0"），也没有记录产出该 baseline 的编译器/优化器版本。后续对比时无法判断基线是否在同一工具链下生成。

---

🟡 dynamic_instruction_count 字段冗余

每个 case 顶层的 dynamic_instruction_count 与 cost_model.dynamic_instructions 始终相同。要么去掉顶层冗余字段，要么在顶层存放聚合结果（如 total），避免数据不同步风险。

---

💭 add_reuse 与 add_chain 指标完全一致

两者 cost_model 所有字段均相同（4 instructions, 3 add, 16 bytes…）。如果 graph 结构不同但优化后相同，建议在 case 中加注释或 expected_optimized 标记说明这是预期行为，否则 reviewer 无法区分是 bug 还是 coincidence。

---

📁 docs/topics/06-双后端未通过用例分析.md

整体文档质量很高，数据自洽、问题归属清晰、建议可操作。仅有少量细节问题：

---

🟡 Section 2.2 标题与内容不完全匹配 — if_then 用例通常只有 if/endif（无 else），但 2.2 标题写"分支类"并在解释器原因中统一写"没有实现 if/else/endif 条件语义"。如果 if_then 确实不含 else，建议区分描述，避免让读者误以为该用例也测试了 else 分支。

🟡 Section 2.1 表述易产生歧义 — "循环体只会运行一次"描述的是一种假设情况（若不做前置检查），但紧接着又说测试套件已标记 UNSUPPORTED。建议在句首加"若不做前置检查"之类的限定词，明确这是描述解释器当前缺陷而非实际执行路径。

💭 超时阈值未在结论区说明 — 正文 3.1 提到"5 秒超时"，但读者在结论摘要中无法直接看到这是默认值还是可配置值。建议在结论区或表格旁加注一行，方便快速定位。

💭 Section 3.2 dot_relu_4 期望值分析 — 提到期望值 0 与观测值 0 偶然相等，并标记 UNSUPPORTED。逻辑正确，但建议在表格的"期望输出"列加个脚注标记（如 ⁰），与正文说明呼应，方便扫表时立即感知该行需特别关注。

---

数据交叉验证全部通过：9 个可比用例 + 14 个至少一端失败 = 23 总数 ✓；DSLInterpreter 失败 6 + TinyFive 失败 11 − 分支重叠 3 = 14 唯一失败用例 ✓。

---

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

🔴 文档内容被大量删除但未看到替代内容 — 原文件约 200 行，包含背景说明、DSL 语法示例、使用教程、代码走读、动手练习、常见坑等教学章节，现在压缩为 ~25 行纯状态描述。如果内容拆分到了链接的三个子文档中，这三个文件是否在本次 PR 中同时新增？如果没有，读者将失去所有入门指导。

🟡 标题编号格式不一致 — # 课题 06 与旧版 # 课题6 不同，空格规则是否与仓库内其他 docs/topics/*.md 一致？如果不一致，建议统一，避免搜索和交叉引用混乱。

🟡 缺少读者指引 — 新文档只列了文件路径和结果摘要，没有告诉读者"你应该先看哪个文件"或"如果你想做 X 该去哪里"。作为课题入口页，缺少导航。

🟡 CI 门禁描述含糊 — "将 activation、elementwise 和 loop 类别作为阻塞门禁，其余用例保留在全量诊断报告中"。没有说明：哪些类别被排除了、为什么排除、被排除的类别何时会被重新纳入门禁。这会在 PR review 时导致反复讨论。

🟡 pip install -e ".[topic06]" 缺少 Windows 注意事项 — 如果使用 cmd.exe，外层引号对 glob 的保护行为可能与 bash 不同。如果项目支持 Windows CI，建议补充说明或使用引号包裹整个 extra。

💭 结果数字未注明来源运行时间或 commit — "DSLInterpreter 17 通过 / TinyFive 12 通过"等数据应标注生成日期或对应 commit hash，否则无法判断数据是否过期。

💭 三个链接的子文档标题使用了破折号 — 而非连字符 - — Markdown 标题中的 — 在某些渲染器/搜索引擎中可能影响可发现性。

---

📁 docs/topics/06-性能测试套件使用说明.md

Code Review: docs/topics/06-性能测试套件使用说明.md

File: New documentation — 264 lines, well-structured, covers a broad surface area. A few issues:

---

🟡 Timeout values undocumented as configurable vs hardcoded — Lines mentioning "30 秒" and "5 秒" timeouts are stated as facts. If these are CLI-configurable, add the flag; if hardcoded, note the source location so maintainers know where to change them.

🟡 Inconsistent code block language tags — Most shell commands use powershell but --fail-on-test-failure (line ~143) and the DSL example (line ~173) use text. Standardize: shell → powershell or bash, DSL → dsl.

🟡 CI blocking categories lack context — Line ~238: only activation/elementwise/loop are blocking, yet the intro (line ~15) documents known failures in branch/reduction/tensor. A brief parenthetical — e.g., "（branch/reduction/tensor 已知不支持，见前文）" — would prevent reader confusion about why these are excluded.

🟡 test_integration.py mentioned but not documented — Directory structure lists it and CI references "pytest 集成契约", but the doc never explains what these tests cover, how to run them standalone, or what contract they enforce. Either add a subsection or link to existing docs.

🟡 course_report_instructions.png name is opaque — Line ~215: this filename appears in the full-report output list with no explanation. What does it contain? Why "course"? Readers can't infer purpose.

🟡 --update-baseline + no-match interaction unclear — Line ~136 documents subset baseline update correctly, but doesn't say what happens when --category/--filter matches zero cases and --update-baseline is passed. The exit-code-2 behavior is documented for the general case (line ~140) but the baseline-write path should be called out explicitly.

💭 PowerShell-only examples — All commands use powershell. GitHub Actions runs bash. If the project is cross-platform, consider at least noting bash equivalents or using language-neutral tags for portable commands.

💭 Relative link at bottom — Line 263: [06-性能测试套件设计文档.md](06-性能测试套件设计文档.md) — verify this resolves correctly from docs/topics/ in your target static site generator or renderer.

---

Summary: No blockers. The doc is thorough and well-organized. Main gaps are (1) undocumented configurability of timeout values, (2) pytest integration tests referenced but never explained, and (3) opaque filename course_report_instructions.png. The inconsistent code-block tags and missing CI-exclusion context are minor but easy to fix.

---

📁 docs/topics/06-性能测试套件设计文档.md

🔴 矛盾：branch 用例不可能同时"超时"又"在基线中" — Section 八 说 3 个 branch 用例 TinyFive 模拟 5s 超时，Section 四.7 和 P2 明确说 timeout 用例"不写入性能基线"、"只有真实 TinyFive 执行成功且输出正确才能写入基线"。但 Section 十一 P2 却写"目前基线包含 activation、branch、elementwise 和 loop 共 15 个稳定用例"。branch 3 个用例全部超时，不可能进入基线，"15 个稳定用例"应为 12 个（仅 activation + elementwise + loop）。

🟡 缺少 CLI 选项文档 — Section 十一 P0 新增 --verification-backend both|tinyfive|interpreter，Section 九 CI 使用 --fail-on-test-failure，但 Section 六（运行方式）完全未收录这两个选项。用户按文档操作时无法发现这些能力。

🟡 缺少完整用例清单 — 文档反复提及"23 个 DSL 测试用例"，但从未列出完整清单。Section 八只列出了失败用例。建议在 Section 一或三补充完整列表（名称、类别、状态），方便读者验证覆盖度。

🟡 无基线时的退化判断行为未说明 — Section 4.4 的 PASS 条件包含 not regression["regressed"]，Section 4.5 说 baseline_instr_count 无基线时为 null。但文档未说明此时 regressed 的值（推断为 false）。首次运行无基线时，所有用例应默认为"未退化"，建议在 4.5 或 4.7 明确写出。

💭 P2 未给出 baseline.json 结构示例 — P2 列出了 cost model 各字段名，但文档中缺少 baseline.json 的 JSON 示例。Section 三给了 .meta.json 示例，建议对称补充基线文件示例，降低新成员理解成本。

---

📁 docs/topics/INDEX.md

💭 NIT: 文件名与课题列命名不一致 — 文件改为 06-性能测试套件使用说明.md，但课题列仍写"编译器性能测试套件"。文件名多了"使用说明"，两者语义略有偏差，不影响功能，看是否有意为之。

---

📁 pyproject.toml

🟡 Dependency duplication — topic06-report repeats tinyfive and pytest instead of referencing topic06.
Suggestion: topic06-report = ["topic06", "jinja2", "matplotlib"] — avoids drift if either dep's version/pin changes later.

🟡 pytest in a runtime extra — pytest is a test dependency; placing it in a user-facing optional extra means end users might accidentally install it in production.
Suggestion: Put pytest in a dedicated dev or test extra, and have topic extras reference that.

💭 Naming — topic06 looks like an internal/temporary identifier. If this is a tutorial/experiment branch, fine; if it ships, a descriptive name (e.g. topic06-visualize) would be clearer to future readers.

---

---

⚠️ 未审查的文件

• scratchv/backend/register_alloc.py
• scratchv/compiler.py
• scratchv/main.py
• scratchv/simulator/tinyfive.py
• scripts/generate_topic06_report.py
• scripts/run_topic06_benchmarks.py
• tests/test_simulator.py
• tests/topic06/cases/activation/add_relu_relu.dsl
• tests/topic06/cases/activation/add_relu_relu.meta.json
• tests/topic06/cases/activation/relu_add.dsl
• tests/topic06/cases/activation/relu_add.meta.json
• tests/topic06/cases/activation/relu_only.dsl
• tests/topic06/cases/activation/relu_only.meta.json
• tests/topic06/cases/activation/relu_twice.dsl
• tests/topic06/cases/activation/relu_twice.meta.json
• tests/topic06/cases/branch/if_else.dsl
• tests/topic06/cases/branch/if_else.meta.json
• tests/topic06/cases/branch/if_relu.dsl
• tests/topic06/cases/branch/if_relu.meta.json
• tests/topic06/cases/branch/if_then.dsl

[2813183274-cloud]

topic06 pr