#13 docs: add peephole benchmark development and design docs

[DavidIt-coder]

提交了课题13的开发文档和设计文档，位于docs/feat/下。

[github-actions]

🤖 AI Code Review

共审查 2 个变更文件

📁 docs/feat13#suai/开发文档.md

🔴 指标定义矛盾 — "计数和重复运行规则"说"排除空行、注释、标签及 .text、.data、.globl 等汇编指示符"，但"风险缓解措施"中却说"排除标签、注释和指示符，主要报告静态指令数"——两者一致，但 "使用汇编行数代替指令数" 的风险描述误导：缓解措施是计数指令而非行数，建议统一表述并明确"指令数"的定义（如是否包含伪指令）。

🟡 缺失接口契约 — 文档描述上游依赖，但未定义 asm_peephole.py 的输入/输出签名（如接收字符串列表还是 AST 对象）、inst_counter.py 的计数函数名、以及如何控制 peephole 开关。建议在 2.3 节补充伪接口或预期函数签名，避免实现时理解偏差。

🟡 重复运行规则不完整 — 提到"默认运行 5 次，记录中位数"，但未说明多次运行中是否复用同一输入（如果输入是随机生成的，应固定种子或只生成一次）。建议明确：每次重复使用同一输入，或生成输入时固定种子确保一致。

💭 异常处理清单可精简 — 3.3 节列出了 11 条边界条件，但部分已隐含在验收标准中（如 "空输入不除零" 可合并到单元测试覆盖）。建议移入 4.1 单元测试列表，避免文档冗余。

💭 参数示例未确定 — 2.1 节展示了 CLI 参数，但注明"以上参数是初步规划"。建议在实现前确定最终参数名（如 --repeats 是否与现有脚本风格一致），并考虑使用 argparse 的 add_argument 片段示例。

---

📁 docs/feat13#suai/设计文档.md

🔴 设计遗漏：instruction_total() 对 _detailed 字段类型假设不明确
第 2.3 节中 _detailed 被假定为可被 sum 过滤的值，但若其类型为 dict 或 list，则 isinstance(value, int) 会跳过，但 sum 会尝试迭代 dict 的键（字符串），导致 TypeError。建议：在 count_instructions() 返回值规范中明确 _detailed 的格式，或在 instruction_total() 中增加类型检查（如 if isinstance(value, int) else 0）。

🟡 归一化比较可能因注释/标签不同而误判不一致
第 2.7 节 normalize_asm() 仅去除空白，不删除注释和标签。若编译器在开启/关闭 peephole 时生成不同注释（如时间戳、规则名称），直接回放结果与编译器 ON 输出将不一致，导致 pipeline_mismatch。建议：归一化前统一去除注释（# 后内容），或确认编译器保证注释一致。

🟡 verification_status 应使用枚举而非字符串
第 2.2 节中 PeepholeCaseResult.verification_status 定义为 str，但后续四类状态（passed/failed/unavailable/skipped）是固定的。使用字符串容易因拼写错误导致逻辑问题。建议：定义 VerificationStatus 枚举类，并在 dataclass 中引用。

🟡 CompilerConfig 是否为 dataclass？dataclasses.replace() 是否可用？
第 2.6 节建议使用 dataclasses.replace() 复制配置，但未确认 CompilerConfig 是否实际为 dataclass。若为普通类，此方法会失败。建议：在实现中显式复制或使用 copy.deepcopy，并确保配置对象可安全复制。

💭 JSON 示例缺少 timing 字段
第 5.1 节 JSON 示例的 case 对象中未包含 timing 字段（TimingStats），而 PeepholeCaseResult 中明确包含该字段。示例应加上 timing 以反映真实结构，避免误导。

💭 建议尽早提取公共模块，而非“重复明显后再提取”
第 4.3 节将共享逻辑的提取推迟到“重复明显后”。但两个脚本（bench_asm_peephole.py 和 compare_peephole.py）已共享数据结构和报告函数，提取到 peephole_benchmark_common.py 可减少重复、便于单测。建议：在初始实现中即提取公共部分。

💭 --verify 参数 auto 的默认行为文档未明确
第 2.1 节描述了 --verify 的三个模式，但未说明当 auto 时，如何判断后端是否可用（例如检查模拟器导入）。建议在实现中增加文档注释或功能说明，确保行为一致。

---