🤖 AI Quality

AI 驱动的代码质量工具 - 提交前自动审查，一键修复

✨ 核心价值

在代码提交前自动发现问题，而不是等到 CI 失败才知道。

开发 → [AI 自动审查] → 提交 → 推送 → CI ✅
         ↑
      问题在这里就被发现！

🚀 快速开始 (3 步)

# 1️⃣ 安装为开发依赖
npm install -D @basic-genomics/ai-quality

# 2️⃣ 初始化 (配置 API Key + npm scripts)
npx aiq init

# 3️⃣ 安装 Hook
npx aiq hook install

完成！ 之后每次 git commit 都会自动审查代码 🎉

📖 日常使用

自动模式 (推荐)

安装 Hook 后，正常开发即可：

git add .
git commit -m "feat: add new feature"
# → AI 自动审查，有问题会阻止提交

手动模式

# 审查暂存文件
npm run aiq:staged
# 或
npx aiq review --staged

# 审查所有修改
npm run aiq:review
# 或
npx aiq review --diff

CI 模式

# .github/workflows/ai-review.yml
- uses: basic-genomics/ai-quality-action@v1
  with:
    gemini-api-key: ${{ secrets.GEMINI_API_KEY }}

⚙️ 配置详解

配置文件一览

| 文件 | 用途 | 提交到 Git | |------|------|-----------:| | .ai-quality.local | API Key (敏感信息) | ❌ 不提交 | | .ai-quality.json | 项目配置 | ✅ 可提交 |

.ai-quality.json 完整配置

{
  "language": "zh",
  "severity": "high",
  "exclude": [
    "*.test.ts",
    "*.spec.ts",
    "dist/*",
    "build/*",
    "node_modules/*",
    "*.generated.*"
  ],
  "maxFiles": 20,
  "autoFix": true,
  "prSummary": true
}

配置项说明

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | language | zh | en | zh | 输出语言 | | severity | string | high | 最低报告级别: critical, high, medium, low | | exclude | string[] | 见下方 | 排除的文件模式 (glob) | | maxFiles | number | 20 | 单次最多分析文件数 | | autoFix | boolean | true | 是否提供一键修复建议 | | prSummary | boolean | true | 是否生成 PR 摘要 (CI 模式) |

默认排除文件

以下文件默认不会被审查：

package-lock.json, yarn.lock, pnpm-lock.yaml
*.min.js, *.min.css
dist/*, build/*
*.generated.*

排除规则示例

{
  "exclude": [
    "*.test.ts",           // 所有测试文件
    "*.spec.tsx",          // 所有测试文件
    "__tests__/*",         // 测试目录
    "__mocks__/*",         // Mock 目录
    "*.d.ts",              // 类型声明文件
    "migrations/*",        // 数据库迁移
    "*.config.js"          // 配置文件
  ]
}

🎯 严重等级

| 等级 | 说明 | Hook 行为 | |------|------|----------| | 🔴 critical | 必须修复 (Bug/安全漏洞) | ❌ 阻止提交 | | 🟠 high | 应尽快修复 (逻辑问题) | ❌ 阻止提交 | | 🟡 medium | 影响质量 (最佳实践) | ✅ 允许提交 | | 🟢 low | 代码风格 (建议) | ✅ 允许提交 |

提示: 可通过 severity 配置项控制报告的最低级别。设为 medium 可获得更多建议。

💡 常用命令

# 初始化
npx aiq init                # 交互式初始化

# Hook 管理
npx aiq hook install        # 安装 pre-commit hook
npx aiq hook uninstall      # 卸载 hook

# 代码审查
npx aiq review --staged     # 审查暂存文件 (git add 后的文件)
npx aiq review --diff       # 审查所有修改 (包括未暂存)
npx aiq review --commit abc123  # 审查指定 commit

# 配置
npx aiq config list         # 查看当前配置
npx aiq config set language en
npx aiq config set severity medium

📦 npm scripts

aiq init 会自动在 package.json 中添加以下脚本：

{
  "scripts": {
    "aiq:review": "aiq review --diff",
    "aiq:staged": "aiq review --staged"
  }
}

然后可以直接运行：

npm run aiq:review    # 审查所有修改
npm run aiq:staged    # 审查暂存文件

🛠️ 故障排查

Q: 如何跳过某次提交的审查？

git commit --no-verify -m "skip review"

Q: 提示"没有找到可审查的文件"？

这是因为使用了 --staged 但文件还没有 git add。解决方法：

# 方法 1: 先暂存文件
git add .
npx aiq review --staged

# 方法 2: 审查所有修改 (包括未暂存)
npx aiq review --diff

Q: 如何获取 Gemini API Key？

1. 打开 Google AI Studio
2. 点击 Get API Key
3. 创建并复制 API Key

Q: 后端项目没有 package.json 怎么办？

只需确保项目是 Git 仓库即可。API Key 可通过环境变量设置：

export GEMINI_API_KEY=your-key
npx @basic-genomics/ai-quality review --diff

Built with ❤️ by @basic-genomics