[docs][Topic12] Add design documents and development documents

[kaishaoshao]

目前先用ai生成出版文档，后期等待人工核对

[github-actions]

🤖 AI Code Review

共审查 2 个变更文件

📁 docs/topics/12-指令计数统计器-开发文档.md

这是一份文档变更（新增 701 行），以下是发现的问题：

---

🔴 缺少 --fail-on-unknown 退出码定义 — Section 11.2 要求 main() 返回整数，Section 21.3 说"进程返回专用非零码"，但全文未定义具体值（如 EXIT_UNKNOWN = 2）。实现者将自行发明，导致 CLI 契约不可预测。

🟡 analyze_file() 错误处理未覆盖 — Section 8.1 定义了 analyze_file() 但未说明文件不存在、权限拒绝、非 UTF-8 编码时的行为。count_instructions_file() 作为 legacy wrapper 同样缺失。

🟡 Section 12.1 option 2 缺少条件守卫 — 建议的"在后处理之后单独调用 analyze_instructions()"应明确加 if args.count_instr: 条件，否则统计会在关闭 --count-instr 时也被执行。

🟡 Section 21.3 与 11.1 的流程契约需显式链接 — "JSON 仍被写入"依赖于 11.1 中 "render files → evaluate strict" 的顺序。建议在 21.3 加注释指向 11.1，否则实现者可能先检查 strict 再渲染。

🟡 未区分 --compare 模式下多 renderer 的 baseline 选择 — Section 21.2 说"delta 以第一份为 baseline"，但 Section 9.1 的 compare_stats 有 baseline: str | None 参数。需明确 CLI 层如何传递第一份输入为 baseline，以及 --compare --json --html --chart 同时使用时是否共用同一 baseline。

🟡 Section 14.6 性能测试未指定内存基线 — 只记录"中位耗时和峰值内存"但未给出任何通过/不通过标准。建议至少定义线性增长的可接受偏离范围（如 ±1.5x 于理想线性模型）。

💭 Section 7.4 的 custom.foo fixture 建议改为更清晰的占位 — 虽然 custom.foo 足够作为 unknown 测试，但 RISC-V 自定义指令空间的标准格式是 custom-0 到 custom-3。如果将来有人把 custom-0.foo 加入注册表，当前 fixture 不会暴露问题。建议用一个与 ISA 命名风格完全无关的 token，如 ZZunknown。

💭 12 周计划 (Section 19) 对单人开发偏紧 — P0-P9 涵盖解析修复、分类注册表、数据模型、比较层、5 种渲染器、CLI 重构、CompilerDriver 集成、benchmark/CI。如果任一阶段遇到阻塞性设计问题，W12 的回归+文档会挤压。建议将 W11-W12 预留 20% buffer 或标注哪些可并行。

---

📁 docs/topics/12-指令计数统计器-设计文档.md

设计文档 Review

---

🔴 Blockers

1. ComparisonResult 数据模型自相矛盾 — Section 7.4

baseline_label 是单独字段，但 stats 包含了 baseline 自身的 InstructionStats；category_deltas 只含非 baseline 文件的差值，但 stats 含全部文件。渲染端必须猜测哪些 stats 是 baseline、哪些 delta 缺省。建议：

• stats 只存非 baseline 的，baseline 单独字段；或
• stats 含全部，category_deltas 也含 baseline 行（全 0），靠 baseline_label 标识。

当前形态会让调用方做不必要的防御逻辑。

2. 伪操作（directive）识别完全未定义 — Section 8.1

解析步骤写了 "if first token is directive: skip"，但全文没有任何关于什么是 directive 的定义。^\.[a-zA-Z_]+ 的 regex 是合理默认，但文档必须明确写出。不写的话，.L1:（本地标签）vs .word（数据伪操作）vs .text（节切换）的区分逻辑只能靠实现者猜，C-01 的修复也会被绕过。

3. 多文件 JSON schema 缺失 — Section 12.2

单文件 JSON 给了完整示例，但多文件比较的 schema 只说"在顶层增加 baseline、files 和 deltas"，没有结构定义。这是 CI 接入的核心接口（Section 15.1 要求存 baseline delta），不可留白。建议补完整示例，并说明嵌套深度、排序规则和 schema_version 兼容策略。

---

🟡 Suggestions

4. ISA 字段来源未指定 — Section 3.2 / Section 13

isa 出现在 InstructionStats 和 CLI 参数中，但文档没说明：是纯用户指定（--isa rv32im）？还是从文件头 .option rvc 或指令集推断？默认 unknown 意味着不指定时分类表可能不全。建议在 Section 8 或 Section 13 补一段 ISA 确定逻辑，至少说明"仅用户指定，不从汇编推断"。

5. percent 精度/舍入未定义 — Section 7.4

CategoryDelta.percent 是 float，JSON 序列化时会出现 8.200000000000001 之类的浮点噪声。建议在 Section 7.4 或 Section 12.2 明确：保留小数点后几位、是否用 round()、是否用 Decimal。CI 基线比较如果依赖 JSON diff，精度不一致会导致误报。

6. 分类版本迁移路径不完整 — Section 7.2 / Section 20

文档说 j/ret/call/tail 从 PSEUDO 改到 JUMP 需升级 classification_version，但 Section 20 的迁移步骤只说"升级 classification_version"，没有说明：

• 旧版本分类表是否保留？是否双写？
• analyze_instructions() 是否能接受 classification_version 参数来指定用哪版表？
• JSON 文件中 classification_version 是字符串还是整数？Section 7.1 是 str = "1"，Section 21 验收标准提到"分类版本"但未说明格式。

建议在 Section 20 补一条"旧分类表保留至 N+1 版本"之类的明确政策。

7. Section 15.2 回归阈值缺乏可操作定义

"稳定小程序：允许经审核的小范围" — 范围多大？1%？5 条指令？这个阈值如果是项目级配置，应该有一个默认值和配置入口。否则 CI 接入门槛含糊，不同人实现不同。

8. source 字段语义模糊 — Section 7.1

source: str | None 是什么？绝对路径？相对路径？显示用 basename？Section 11.2 说"结构化数据中同时保存 label 和 source path"，暗示 label 和 source 是独立字段，但 source 的路径形式（abs/rel/display）未定义。建议明确为"调用方传入的原始路径，不做标准化"。

---

💭 Nits

9. Section 10.1 说 O(N) 时间复杂度，但 Section 9.1 步骤 3 "受控模式"如果涉及 regex 扫描扩展指令，单条指令的分类可能不是 O(1)。实际影响可忽略，但精确说法应为 O(N × K)（K 为匹配模式数）。

10. Section 8.1 的示例表包含 .L1: bnez t0, .L1，很好。建议再加一个多标签同行的例子（如 foo: bar: add a0, a1, a2）来验证 "zero or more leading labels" 的行为。

11. Section 13.2 退出码表说"如项目已有统一 CLI 退出码约定，以全局约定为准"，但 Section 21 验收标准引用了这些码。如果项目约定不同，验收标准需要同步更新。建议在 Section 21 的对应条目中加括注。

12. Section 7.1 不变式说 category_counts 始终包含所有标准类别，但 Section 12.2 JSON 示例只展示了 {"ALU": 3, "MEM": 2}。虽然注释说"示例仅为简写"，但读者容易复制粘贴。建议在示例中用 "ALU": 3, "MEM": 2, "FP": 0, "BRANCH": 0, "JUMP": 0, "ATOMIC": 0, "SYSTEM": 0, "PSEUDO": 0, "MISC": 0 展示完整形态，或改用 <...> 占位符。

---

总结

文档结构完整、问题定义清晰、边界意识好（静态 vs 动态、textual vs expanded、RISC-V vs LLVM）。主要问题集中在 ComparisonResult 模型自洽性、directive 识别规则缺失 和 多文件 JSON schema 空白 三处——这三个都是实现和 CI 接入的阻塞点，建议在实现前补齐。分类版本迁移和 percent 精度属于"实现时容易踩坑"的灰色地带，补一段定义能省掉后续讨论。

---