---
name: blade-audit
description: BladeX 专业代码审计工具。从资深架构师视角对代码进行全方位审计，涵盖代码质量、架构合规、框架规范、安全漏洞、逻辑健壮性、性能隐患六大维度。支持三种审计输入：Git commit 记录审计、设计文档与实现对比审计、工程目录全量审计。自动生成包含严重级别、定位信息、修复建议的专业审计报告。当用户需要进行代码审查、代码审计、质量检查、安全扫描、架构评审、设计合规检查、或使用 /blade-audit 时触发。即使用户只是说"帮我审查下代码"、"看看这几个提交有没有问题"、"检查下代码质量"、"这个模块写得怎么样"、"有没有安全隐患"、"review 一下"、"帮我把把关"等模糊表述也应触发。
---

# BladeX 专业代码审计工具

## 铁律

以下规则在任何情况下都不可违反：

1. **只读不写**：审计过程中绝不修改任何源代码文件、配置文件或 Git 历史。审计工具是观察者，不是参与者
2. **有据可查**：每一条审计发现必须附带精确的文件路径和行号定位，不允许模糊描述如"某处存在问题"
3. **不做臆断**：对无法确定的问题标注为「待确认」而非直接定性，宁可漏报不可误报严重级别
4. **全量覆盖**：在指定审计范围内，不跳过任何文件，不因文件数量多而省略检查
5. **分级客观**：严格按照严重级别定义进行分级，不因为发现数量少而人为提升级别，也不因数量多而降级

## 严重级别定义

| 级别 | 标记 | 含义 | 判定标准 |
|------|------|------|----------|
| 严重 | 🔴 | 必须在上线前修复 | 存在安全漏洞、数据损坏风险、或生产事故隐患 |
| 重要 | 🟠 | 当前迭代应修复 | 影响系统稳定性、可维护性、或违反核心架构原则 |
| 建议 | 🟡 | 建议改进 | 提升代码质量、可读性、或符合最佳实践 |
| 提示 | 🟢 | 参考信息 | 最佳实践建议、风格偏好、优化思路 |

## 使用方式

### 模式一：Commit 审计（审查特定提交的变更）

```
/blade-audit --commit [commit-range]
```

**参数说明：**
- `commit-range`：Git commit 范围，支持以下格式：
  - 单个 commit：`abc1234`
  - 范围：`abc1234..def5678`
  - 最近 N 个：`HEAD~3..HEAD`
  - 省略时默认审计最近一次提交

**适用场景：** Code Review、合并前检查、提交后回顾

### 模式二：设计审计（对比设计文档与实际实现）

```
/blade-audit --design <design-doc-path> [code-path]
```

**参数说明：**
- `design-doc-path`：设计文档路径（Markdown / 文本文件 / blade-spec 输出的规范文档）
- `code-path`：对应的实现代码路径（省略时在当前工程中自动定位）

**适用场景：** 设计评审、实现完整性检查、规范驱动开发的验收环节

### 模式三：目录审计（对工程或模块进行全量审计）

```
/blade-audit [path] [options]
```

**参数说明：**
- `path`：审计目标路径（省略时为当前工程根目录）
- `--module <module-name>`：仅审计指定模块（如 `blade-auth`、`blade-system`）
- `--focus <dimension>`：聚焦特定审计维度（见下方六大维度）
- `--depth <shallow|standard|deep>`：审计深度，默认 `standard`
  - `shallow`：快速扫描，仅检查高优先级项
  - `standard`：标准审计，覆盖全部维度的核心检查项
  - `deep`：深度审计，包含交叉分析、依赖链追踪、数据流分析

**适用场景：** 新人接手项目、版本发布前全面检查、技术债务评估

## 六大审计维度

审计从以下六个维度展开，每个维度的详细检查项见 `references/audit-checklist.md`：

### 1. 代码质量（quality）

关注代码的可读性、可维护性和工程规范：
- **命名规范**：类名、方法名、变量名是否语义清晰且符合 Java/BladeX 约定
- **方法复杂度**：单方法是否过长（>80行）、圈复杂度是否过高（>10）
- **代码重复**：是否存在明显的复制粘贴代码（同模块内 / 跨模块）
- **异常处理**：是否吞掉异常、是否捕获过宽（catch Exception）、是否缺少关键异常处理
- **资源管理**：流、连接等资源是否正确关闭（try-with-resources）
- **注释质量**：关键业务逻辑是否有注释、注释是否与代码一致

### 2. 架构合规（architecture）

从架构师视角审视系统结构的合理性：
- **分层纪律**：Controller→Service→Mapper 的调用链是否被打破（如 Controller 直接调用 Mapper）
- **模块耦合**：业务模块之间是否存在不合理的直接依赖（应通过 Feign/API 解耦）
- **依赖方向**：是否存在下层依赖上层的反向依赖
- **职责单一**：类和方法是否承担了过多职责（God Class / God Method）
- **API 设计**：接口是否符合 RESTful 规范、是否存在过度暴露的内部接口
- **包结构**：包的组织是否符合 BladeX 的 controller/service/mapper/pojo 分包规范

### 3. 框架规范（convention）

检查是否遵循 BladeX 框架的特定约定和最佳实践：
- **实体规范**：Entity/DTO/VO 的使用是否规范，是否在该用 VO 的地方用了 Entity
- **服务接口**：Service 是否定义了 I 前缀接口（IXxxService）
- **统一返回**：Controller 是否统一使用 `R<T>` 返回
- **MyBatis-Plus**：是否正确使用 LambdaQueryWrapper、是否有硬编码字段名
- **租户隔离**：多租户场景下是否正确处理 tenant_id
- **数据库规范**：表设计是否包含必要字段（id、tenant_id、create_user、create_time、is_deleted 等）

### 4. 安全审计（security）

识别潜在的安全风险和漏洞：
- **SQL 注入**：是否使用了 `${}` 拼接或手动拼接 SQL
- **XSS**：用户输入是否未经转义直接输出
- **权限漏洞**：接口是否缺少鉴权注解（@PreAuth）、数据权限是否缺失
- **敏感数据**：密码、密钥等是否明文存储或日志输出
- **输入校验**：外部输入是否缺少参数校验（@Valid / @NotNull）
- **CSRF/SSRF**：是否存在跨站请求伪造或服务端请求伪造风险
- **依赖安全**：是否引入了已知存在漏洞的第三方库版本

### 5. 逻辑健壮性（robustness）

审查业务逻辑的正确性和边界处理：
- **空指针风险**：链式调用是否有 NPE 隐患、Optional 使用是否合理
- **并发安全**：共享状态是否有线程安全问题、锁使用是否正确
- **事务管理**：@Transactional 的使用是否正确（传播机制、回滚规则、是否覆盖了关键写操作）
- **边界条件**：分页、数量限制、空集合、极端值等边界是否处理
- **数据一致性**：跨表 / 跨服务操作是否保证一致性
- **幂等性**：关键写接口是否具备幂等能力

### 6. 性能隐患（performance）

发现可能导致性能问题的代码模式：
- **N+1 查询**：循环内是否存在数据库查询（应批量查询）
- **全表扫描**：查询条件是否可能绕过索引
- **大对象**：是否在循环中创建大量临时对象、是否有内存泄漏风险
- **连接/资源池**：数据库连接、Redis 连接、HTTP 连接是否正确归还
- **缓存策略**：热点数据是否使用缓存、缓存是否有过期和更新策略
- **批量操作**：大量数据操作是否使用了批处理（saveBatch）而非逐条操作

## 执行流程

### Phase 1：环境准备与范围确定

根据用户输入的模式进行初始化：

**1.1 解析输入参数**
- 识别审计模式（commit / design / directory）
- 验证路径或 commit 范围的有效性
- 若路径不存在或 commit 无效，立即报错并终止

**1.2 识别工程类型**
- 通过 pom.xml、模块结构判断工程类型：Boot 单体 / Cloud 微服务 / Links IoT
- 记录工程的关键元信息：Java 版本、Spring Boot 版本、BladeX 版本、模块列表

**1.3 确定审计范围**
- **commit 模式**：提取涉及变更的文件列表
- **design 模式**：读取设计文档，解析出涉及的模块和功能点，定位对应的实现文件
- **directory 模式**：扫描目标目录，构建待审计文件清单（排除 target/、.git/、node_modules/ 等）
- 若指定了 `--module` 或 `--focus`，收窄审计范围

**1.4 向用户确认审计范围**

输出审计范围摘要，等待用户确认后再继续：

```
📋 审计范围确认
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
审计模式：目录审计
工程类型：Cloud 微服务
目标模块：blade-auth
审计深度：standard
文件范围：Java 文件 42 个，XML 文件 8 个，配置文件 3 个
审计维度：全部六维度
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
确认开始审计？(Y/n)
```

### Phase 2：代码采集与预分析

**2.1 代码采集**

根据审计模式采集代码：

- **commit 模式**：
  - 执行 `git show` / `git diff` 获取每个 commit 的变更内容
  - 同时读取变更文件的完整内容（理解上下文）
  - 提取 commit message 作为变更意图的参考

- **design 模式**：
  - 完整读取设计文档
  - 从文档中提取：功能列表、接口定义、数据模型、业务流程、非功能性要求
  - 定位并读取对应的实现代码文件

- **directory 模式**：
  - 按模块分组读取所有待审计文件
  - 优先级：Controller → Service → Mapper → Entity/DTO/VO → Config → 其他

**2.2 结构预分析**

在正式审计前，先建立对代码的整体认知：

- 构建模块依赖图（谁依赖谁）
- 梳理接口调用链（Controller → Service → Mapper → DB）
- 识别核心业务实体和它们之间的关系
- 统计基础指标：文件数、代码行数、类数量、方法数量

输出预分析摘要供审计阶段参考，不必展示给用户。

### Phase 3：逐维度深度审计

这是核心阶段。读取 `references/audit-checklist.md` 中对应维度的检查清单，逐项进行检查。

**执行原则：**

- **逐文件过审**：对每个文件，依次检查该维度下的所有适用检查项
- **上下文理解**：不孤立看单行代码，结合调用链和业务语义判断。例如一个看似多余的 null 检查，如果上游确实可能传 null，就不是问题
- **记录现场**：对每个发现记录：
  - 所属维度
  - 严重级别
  - 文件路径 + 行号
  - 问题描述（是什么）
  - 影响分析（为什么有问题）
  - 修复建议（怎么修）
  - 相关代码片段

**维度执行顺序：**

按风险影响从高到低排序执行：
1. 安全审计 → 2. 逻辑健壮性 → 3. 架构合规 → 4. 框架规范 → 5. 性能隐患 → 6. 代码质量

这个顺序确保最危险的问题最先被发现。如果用户通过 `--focus` 指定了维度，则只执行指定维度。

### Phase 4：交叉分析与风险评估

单维度审计完成后，进行跨维度的关联分析：

**4.1 关联分析**
- 同一文件在多个维度上出现的问题，是否存在共同根因
- 例如：一个方法既有安全问题（未校验输入）又有健壮性问题（NPE），根因可能是缺少统一的参数校验层

**4.2 模式识别**
- 是否存在同类问题在多处重复出现（系统性问题 vs 个别疏忽）
- 系统性问题应提升关注度并给出统一解决方案

**4.3 风险聚合**
- 多个低级别问题集中在同一个关键路径上时，组合风险可能高于单个问题
- 对关键业务路径（如认证、支付、数据变更）上的问题进行重点标注

**4.4 合规评分**

按维度计算合规分数：

```
维度合规分 = (通过检查项数 / 适用检查项总数) × 100

综合评分 = 各维度加权平均
  安全审计：权重 25%
  逻辑健壮性：权重 20%
  架构合规：权重 20%
  框架规范：权重 15%
  性能隐患：权重 10%
  代码质量：权重 10%
```

评分等级：
- **A (90-100)**：优秀，可放心上线
- **B (75-89)**：良好，建议修复重要问题后上线
- **C (60-74)**：合格，需修复所有 🔴🟠 问题
- **D (40-59)**：不合格，需较大范围整改
- **F (<40)**：严重不合格，建议重新设计

### Phase 5：报告生成

读取 `references/report-template.md` 获取报告模板，生成最终审计报告。

**5.1 生成报告**

按照报告模板的结构，填充所有审计发现。报告以 Markdown 格式输出，结构如下：

1. **审计概览**：一段话总结审计结果，包含关键数字和最重要的发现
2. **审计信息**：审计时间、范围、模式、深度、工程类型
3. **评分总览**：六维度雷达图（文本表示）+ 综合评分
4. **审计发现**：按维度分组，每组内按严重级别降序排列
5. **关键风险**：提取所有 🔴 和 🟠 问题形成集中清单
6. **系统性问题**：交叉分析中识别出的模式性问题
7. **改进路线图**：按优先级排列的修复建议，分为"立即修复"、"短期改进"、"长期优化"

**5.2 输出报告**

将报告输出到对话中展示给用户。如果用户需要，可以保存为文件。

**5.3 后续建议**

根据审计结果，给出后续操作建议：
- 如果有 🔴 问题：明确指出哪些必须在上线前修复
- 如果发现系统性问题：建议使用 `/blade-spec` 规划整改方案
- 如果需要跨工程对比：建议使用 `/blade-compare` 对比参考实现
- 如果需要同步修复到其他工程：建议使用 `/blade-sync` 同步变更

## Design 模式特殊流程

设计审计模式除了执行上述六维度检查外，还增加以下对比分析：

### D.1 设计完整性检查

对照设计文档逐项检查：
- **功能覆盖度**：设计文档中定义的每个功能点，是否都有对应实现
- **接口一致性**：实际 API 的 URL、参数、返回值是否与设计一致
- **数据模型一致性**：实际表结构/实体字段是否与设计匹配
- **业务规则一致性**：代码中的业务逻辑是否与设计文档描述一致

### D.2 偏差分析

对每个偏差点记录：
- 设计文档中的描述
- 实际实现的情况
- 偏差是合理的演进（标注为「已演进」）还是遗漏/错误（标注为「待修正」）
- 如果是遗漏，评估影响范围和修复建议

### D.3 设计审计专项报告

在标准报告之外，额外输出设计对比矩阵：

```
| 设计项 | 设计要求 | 实现状态 | 偏差说明 |
|--------|----------|----------|----------|
| 用户列表接口 | GET /user/list, 支持分页 | ✅ 已实现 | — |
| 角色权限校验 | 基于 RBAC | ⚠️ 部分实现 | 缺少数据权限控制 |
| 审计日志 | 所有写操作记录审计日志 | ❌ 未实现 | 关键功能缺失 |
```

## Commit 模式特殊流程

### C.1 变更影响分析

对每个 commit 进行变更影响评估：
- 变更涉及的模块和功能域
- 变更类型（新功能 / 重构 / Bug 修复 / 配置变更）
- 变更是否可能引入回归风险
- 变更与 commit message 描述是否一致

### C.2 增量审计策略

- 对**新增代码**：执行全量六维度审计
- 对**修改代码**：重点审计变更部分及其直接上下游调用
- 对**删除代码**：检查是否有其他地方仍在引用被删除的代码

### C.3 Commit 质量评估

除代码审计外，额外评估提交本身的质量：
- Commit message 是否清晰描述了变更意图
- 单次提交的变更范围是否合理（过大的提交难以 Review）
- 是否存在无关变更混入同一提交

## 审计深度说明

### shallow（快速扫描）
- 仅检查 🔴 严重级别的高优先级项
- 跳过代码质量和提示级别的检查
- 适合日常开发中的快速自检
- 预期耗时较短

### standard（标准审计）
- 覆盖全部六维度的核心检查项
- 检查 🔴🟠🟡 三个级别
- 适合 Code Review 和迭代交付前的质量把关
- 这是默认深度

### deep（深度审计）
- 在 standard 基础上增加：
  - 完整的数据流分析（追踪输入从 Controller 到 DB 的完整路径）
  - 依赖链深度追踪（检查间接依赖的影响）
  - 交叉维度关联分析
  - 🟢 提示级别的最佳实践检查
- 适合版本发布前的全面审计或技术债务评估
- 预期耗时较长

## 与其他 Skill 的协作

| 场景 | 推荐组合 |
|------|----------|
| 先设计后审计 | `/blade-spec` → 开发 → `/blade-audit --design` |
| 审计后修复同步 | `/blade-audit` → 修复 → `/blade-sync` 同步到镜像工程 |
| 审计前先对比 | `/blade-compare` 发现差异 → `/blade-audit` 深入审计差异代码 |
| 审计后提交 | `/blade-audit --commit HEAD~1..HEAD` → 修复 → `/blade-commit` |
| 方案讨论 | `/blade-storm` 讨论架构 → 落地 → `/blade-audit` 验证实现 |