🤖 AI Quality

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

---

✨ 核心价值

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

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

---

🚀 快速开始 (3 步)

`bash


1️⃣ 安装为开发依赖

npm install -D @basic-genomics/ai-quality

2️⃣ 初始化 (配置 API Key + npm scripts)

npx aiq init

3️⃣ 安装 Hook

npx aiq hook install
`

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

---

📖 日常使用

$3

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

`bash
git add .
git commit -m "feat: add new feature"


→ AI 自动审查，有问题会阻止提交


`

$3

`bash


审查暂存文件

npm run aiq:staged

或

npx aiq review --staged

审查所有修改

npm run aiq:review

或

npx aiq review --diff
`

$3

`yaml


.github/workflows/ai-review.yml


- uses: basic-genomics/ai-quality-action@v1
with:
gemini-api-key: ${{ secrets.GEMINI_API_KEY }}
`

---

⚙️ 配置详解

$3

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

$3

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

$3

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| 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 模式) |

$3

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

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

$3

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

---

🎯 严重等级

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

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

---

💡 常用命令

`bash


初始化

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 中添加以下脚本：

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

然后可以直接运行：

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

---

🛠️ 故障排查

$3

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

$3

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

`bash


方法 1: 先暂存文件

git add .
npx aiq review --staged

方法 2: 审查所有修改 (包括未暂存)

npx aiq review --diff
`

$3

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

$3

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

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

---

Built with ❤️ by @basic-genomics