对topic5增加了设计与开发文档

[SCOFRD]

No description provided.

[github-actions]

🤖 AI Code Review

共审查 2 个变更文件

📁 docs/topic5汇编代码美化器开发文档.md

🟡 接口描述矛盾 — 2.3节：“依赖 scratchv/backend/asm_parser.py 提供的单行字段解析结果，这里采用自己新编写的 asm_parser_for_beautifier。” 前后不一致，应明确最终依赖的文件名，避免混淆。

🟡 验收标准引用未定义内容 — 4.2节：“四类段标题和函数标题的文本、60个 = 分隔线均与设计文档第2.2节一致。” 但本文档第2.2节未提供具体标题文本，应内联或明确引用外部文档。

💭 缺失 ParsedAsmLine 类型定义 — 2.1节 parse_asm_line 返回该类型，但未给出完整字段描述，仅在2.2节提到保存的字段。建议在API处明确列出数据类结构。

💭 beautify_file() 签名缺失 — 2.1节只列出了 beautify_asm 的签名，但后续提到 beautify_file() 暴露三个选项，建议补充其参数和返回类型。

💭 测试文件数量描述不一致 — 4.1节：“统一集中在以下三个文件中”，但只列出 test_asm_line_parser.py 和 test_asm_beautifier.py 两个测试文件，第三个是 benchmark 文件，不属于测试用例。应改为“两个测试文件”或明确说明包含 benchmark。

💭 BNF 中操作数拆分未体现括号深度 — 2.1节 BNF 中 operands ::= operand { "," operand } 未说明括号内逗号不作为分隔符，虽然后文有解释，但 BNF 本身可能误导读者。建议在 BNF 后加注。

---

📁 docs/topic5汇编代码美化器设计文档.md

🔴 不一致：元数据标签匹配规则在 BNF 与实现中不统一
BNF 中 metadata_label 定义为 _op_/ 后跟 metadata_path（任意非冒号空白字符），而实现中匹配 ^_op_/[^:\s]+$，排除了冒号。但 BNF 中 metadata_path 允许除冒号外的任意字符，包括 : 本身？实际上冒号被排除，但 BNF 说法“any non-whitespace character except ":"”与正则一致，但 BNF 中 metadata_path 定义为 metadata_char { metadata_char }，而 metadata_char 定义明确排除冒号，所以没问题。但存在矛盾：_op_/ 后是否允许包含 /？BNF 仅允许 metadata_char，但 / 在 metadata_char 中（不是空格也不是冒号），所以允许。但实现中 [^:\s]+ 也允许 /，没问题。但 BNF 中 _op_/ 后直接跟 metadata_path，而 metadata_path 本身可以包含 /，所以像 _op_/layer1.0/Conv_5 是合法的。但实现中匹配 ^_op_/[^:\s]+$，会匹配整个字符串 _op_/layer1.0/Conv_5，包括内部的 /，所以一致。但建议在 BNF 中明确 metadata_path 可以包含 /，避免歧义。
🟡 缺少函数入口标签的识别规则
文档未定义哪些标签应触发函数标题（# --- Function: ... ---）。示例中仅 main: 被识别，但普通内部标签（如 .L1:）或 .globl 声明外的标签是否应触发？需明确规则，例如：仅全局标签（.globl 声明）或非点号开头的标签？否则实现可能不一致，影响测试预期。
🟡 输出格式定义未说明段标题与原始 directive 行的位置关系
2.2 节的 BNF 仅定义了 section_mark，但未说明 .text 等原始 directive 行如何放置。示例中 .text 出现在 CODE SECTION 标题之后，但设计文档未明确要求。应补充：段标题插入在对应 directive 行之前，且 directive 行本身保留原样输出。
🟡 数据定义行的列对齐规则不明确
约束规则说“数据定义行只允许进行保守的列级排版”，但未说明是否参与列对齐的扫描与格式化。若参与，则可能改变数据定义行中操作数字段的宽度，但要求“内部空格、逗号、# 原样保留”。需明确：数据定义行应被当作 valid 行参与列对齐，但操作数字段仅作整体对齐，不修改内部格式。
🟡 命令行选项未完整列出
文档提到 --abi-register-names 和 --no-align，但未在单独的章节汇总命令行接口。建议在 4.1 或 4.4 后增加 CLI 说明，包括默认值、是否支持配置等。
💭 文档日期 “2026-07-23” 可疑
通常设计文档日期应为当前或过去日期，未来日期可能是笔误，建议修正。
💭 使用 “美化器” 与 “美化物” 混用
查全文，统一为“美化器”即可。
💭 示例中 ret 注释为 # return，但伪指令模板中 ret 应展开为 jalr x0, ra, 0？
文档未列举 ret 的注释模板，仅提到“单独提供模板”。示例中 ret 注释为 return，合理。但若按语义，ret 等价于 jalr zero, ra, 0，注释可为 return from function 或 pc = ra。建议在附录或模板说明中补充。

---