code-review

# 代码审查框架 **审查原则**：理性、客观、实际、真实、不恭维、实事求是 ## 概述 基于模块化设计的代码审查框架： 1. **通用审查流程**：所有语言通用的审查步骤和原则 2. **语言规则引用**：按需加载语言特定审查规则 3. **组合审查支持**：支持多语言混合项目 **优势**：减少LLM上下文负担（按需加载）、维护简单、扩展灵活、复用性强。 ## 语言支持 ### 直接源码文件 | 语言 | 文件类型 | 编码规范 | 审查规则 | |------------|-------------------------------|-------------------|----------------------| | Java | `*.java` | `spec.java.md` | `review.java.md` | | Python | `*.py` | `spec.python.md` | `review.python.md` | | C++ | `*.cpp *.hpp *.cxx *.hxx *.h` | `spec.cpp.md` | `review.cpp.md` | | Rust | `*.rs` | `spec.rust.md` | `review.rust.md` | | Kotlin | `*.kt *.kts` | `spec.kotlin.md` | `review.kotlin.md` | | ANSI C | `*.c *.h` | `spec.ansi_c.md` | `review.ansi_c.md` | | JavaScript | `*.js *.mjs *.cjs` | `spec.js.md` | `review.js.md` | | TypeScript | `*.ts *.tsx *.mts *.cts` | `spec.js.md` | `review.js.md` | | Shell | `*.sh *.bash *.zsh` | `spec.shell.md` | `review.shell.md` | **加载指令**： ```text Read ${AI_SPEC_ROOT}/lang-spec/spec.{lang}.md Read ${AI_SPEC_ROOT}/lang-spec/review.{lang}.md ``` ### SQL 来源（需拼接提取） | 来源类型 | 文件/位置 | 审查要点 | |----------------|------------------|--------------------| | SQL文件 | `*.sql` | SQL注入、性能、索引| | MyBatis Mapper | `**/*Mapper.xml` | `$`符号拼接风险 | | 内嵌SQL | 各种源码 | 正则匹配审查 | ## 审查模式 ### 1. 全量审查（默认） 遍历项目所有源代码文件，自动识别语言并加载对应规则。 ### 2. 增量审查 根据 git/svn diff 进行增量审查。 ### 3. 混合语言审查 对于多语言项目，按文件类型加载不同规则。 ## 审查流程 1. **项目分析**：识别技术栈、主要语言、项目结构 2. **规则加载**：根据语言加载对应规则集，应用通用审查框架 3. **代码遍历**：遍历所有源代码文件，理解代码结构和意图 4. **执行审查**：应用通用规则 + 语言特定规则，记录问题和建议 5. **生成报告**：汇总结果，输出审查报告 ## 严重度分级 所有语言审查规则、报告模板统一使用以下三级口径，语言文件中的等价表述按此映射： | 级别 | 别名 | 判定标准 | 处理要求 | |------|------|----------|----------| | P0 | 严重 / 必须修正 / 高优先级 | 安全漏洞、数据错误、崩溃、资源泄漏、主流程阻塞 | 本次修改必须修复 | | P1 | 警告 / 应当修正 / 中优先级 | 性能隐患、可维护性问题、边界处理缺失 | 下次迭代修复并登记 | | P2 | 建议 / 建议改进 / 低优先级 | 风格、命名、可读性、可选优化 | 选择性修复 | 判定原则： 1. 同一问题命中多个级别时取最高级。 2. 严重度只由问题影响决定，不由修复难度决定。 3. 报告必须给出级别，模糊表述（如"建议关注"）不允许作为级别。 ## 通用审查规则 ### 安全规则 - **敏感信息泄露**：硬编码的密码、密钥、API Key - **SQL注入风险**：字符串拼接的SQL语句 - **XSS漏洞**：用户输入未转义 - **敏感数据内存残留**：内存中敏感数据未安全清除 ### 中间件消息追踪规则（强制） - **消息通道清单**：检索所有中间件的 Topic/Group/Queue 名称 - **跨应用数据流**：追踪数据在应用间的流动路径（生产者→消费者） - **幽灵通道检测**：只有生产者没有消费者的 Topic/Queue - **孤儿通道检测**：只有消费者没有生产者的 Topic/Queue - **消息体格式记录**：记录消息体关键字段和结构 ### 性能规则 - **资源泄漏**：文件句柄、数据库连接、网络连接未关闭 - **内存泄漏**：动态分配的内存未释放 - **循环性能**：嵌套循环、N+1查询 - **对象创建**：循环中不必要的对象实例化 ### 代码质量规则 - **重复代码**、**方法长度**（> 50行）、**圈复杂度**、**命名规范** - **变量声明**（高优先级）：禁止单行多声明（如 `int a, b;`、`const a = 1, b = 2;`），每个变量独占一行；适用于所有语言 - **文件长度**（建议 > 500 行拆分，强制 > 1000 行必须拆分）；若存在结构性阻碍（如强耦合的状态共享），需在报告中明确说明原因 ### 并发安全规则 - **线程安全**、**死锁风险**、**优雅退出** ### 坏味道分类 详见 [templates/code-smells.md](templates/code-smells.md)：8 大类 50+ 种。 ### AI 生成代码特有审查 **必查项**：安全漏洞、零测试覆盖、性能陷阱 **建议项**：代码规范、错误处理、配置管理 **可忽略项**：个人风格差异 关键检查点：零测试覆盖、过度复杂化、魔法字符串/数字、缺少错误处理、性能陷阱、安全漏洞、硬编码配置、不符合团队规范、注释质量、过度抽象。 ### 数据库审查规则 详见 [templates/database-review.md](templates/database-review.md)：SQL安全性、SQL性能、表结构设计、数据库架构。 ## 审查输出 > 本文件中的 `templates/...` 均指本技能目录下的 `templates/` 子目录。 ### 文件命名规范 ```text docs/review/code-review-{yyyymmdd}-{seq%000}-{lang}.md ``` ### 报告模板 详见 [templates/report-full.md](templates/report-full.md) ### 语言规则文件模板 详见 [templates/lang-rule.md](templates/lang-rule.md) ## 审查执行器 ### 单语言项目 1. 加载语言规则：`Read ${AI_SPEC_ROOT}/lang-spec/spec.{lang}.md` 与 `Read ${AI_SPEC_ROOT}/lang-spec/review.{lang}.md` 2. 应用通用框架（安全/性能/代码质量审查） 3. 应用语言特定规则（语法/最佳实践/并发模式） 4. 生成报告：`docs/review/code-review-{yyyymmdd}-{seq%000}.md` ### 多语言项目 按文件类型分组，每组加载对应语言规则后执行审查。 ## 扩展和维护 ### 新增语言支持 1. 创建规则文件：`${AI_SPEC_ROOT}/lang-spec/spec.{new_lang}.md` 2. 更新本文件"语言支持"部分 ### 规则更新 - 语言规则独立更新，互不影响 - 通用框架独立更新，所有语言受益 - 向后兼容 ## 最佳实践 - **上下文优化**：按需加载语言规则，缓存常用规则 - **规则设计**：语言规则聚焦特有内容，通用规则放框架 - **审查效率**：优先严重问题，批量处理相同模式 - **报告质量**：问题定位到文件路径:行号，区分严重等级 ## AST 自动审查 具体规则不在本框架重复维护，按场景选择入口： | 场景 | 入口 | 说明 | | :--- | :--- | :--- | | 提交/合并门禁、批量扫描 | skill `ast-grep-block` | code-checklist 规则集、分级统计、CI 退出码 | | 交互式抽查、单规则调试 | `ast-grep-mcp` 的 `find_code_by_rule` | 审查过程中查看命中上下文 | | SQL 拼接点抽取 | skill `sql-extract` | MCP 与 CLI 两种模式 | - 规则配方：`${AI_SPEC_ROOT}/skills/ast-grep-block/templates/recipes.md` - MCP 限制：不支持 XML（MyBatis Mapper 用 rg 兜底）；不支持 `--globs` 排除目录；超大项目需分目录搜索或回退 CLI。 - 命中结果必须人工复核，排除误报后按 P0/P1/P2 归级写入报告。 ## 与其他技能集成 | 技能 | 用途 | |----------------------|------------------| | `lets-loop` | 循环性能专项审查 | | `code-detect-dup` | 重复代码专项检测 | | `code-detect-problem`| 项目层面问题检测 | | `sql-extract` | SQL 注入风险点抽取（ast-grep-mcp 联动） |