@zhuxb-clouds/ai-code-review 1.0.1

package/README.md

@@ -0,0 +1,149 @@
+# AI Code Reviewer & Commit Generator
+
+基于 Node.js 和 OpenAI API 的 Git Hooks 集成方案。在执行 `git commit` 时自动进行代码审查，并根据 Diff 自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的提交信息。
+
+## 🚀 核心特性
+
+- **自动化审查**：在代码提交前拦截潜在 Bug 或不规范实践
+- **语义化提交**：自动撰写符合 Conventional Commits 规范的提交信息
+- **无感集成**：通过 Git Hooks 实现，无需改变原有开发习惯
+- **成本可控**：支持 Diff 大小限制，避免 Token 浪费
+- **一键安装**：作为 npm 包安装到任何项目
+
+---
+
+## 🛠️ 技术架构
+
+```
+git commit → Husky (prepare-commit-msg) → ai-review-hook → OpenAI API
+                                                ↓
+                                    ✅ 通过：自动填充 Commit Message
+                                    ❌ 失败：拦截提交并输出建议
+```
+
+---
+
+## 📦 快速开始
+
+### 1. 安装到你的项目
+
+```bash
+# 安装为开发依赖
+npm install ai-code-review -D
+
+# 初始化（自动安装 Husky 并配置 Git Hook）
+npx ai-review init
+```
+
+### 2. 配置环境变量
+
+复制生成的 `.env.example` 为 `.env` 并填入你的 API Key：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`：
+
+```bash
+OPENAI_API_KEY=sk-your-api-key-here
+OPENAI_BASE_URL=https://api.openai.com/v1  # 可选，用于自定义 API 地址
+```
+
+> ⚠️ **安全提示**：`.env` 已自动添加到 `.gitignore`，请勿手动提交！
+
+### 3. 开始使用
+
+```bash
+# 正常开发并暂存更改
+git add .
+
+# 发起提交（推荐不带 -m，让 AI 生成）
+git commit
+
+# AI 会自动审查并生成提交信息
+# 🔍 正在进行 AI 代码审查...
+# ✅ AI Review 通过
+# 📝 生成的提交信息: feat(auth): add JWT token validation
+```
+
+---
+
+## 📂 安装后的目录结构
+
+```
+your-project/
+├── .husky/
+│   └── prepare-commit-msg    # Git Hook（自动创建）
+├── .env                      # API Key（自己创建，不要提交！）
+├── .env.example              # 配置示例（自动创建）
+├── .gitignore                # 已包含 .env
+└── package.json              # 包含 ai-code-review 依赖
+```
+
+---
+
+## ⌨️ CLI 命令
+
+```bash
+# 完整初始化（安装 Husky + 配置 Hook）
+npx ai-review init
+
+# 仅配置 Hook（如果 Husky 已安装）
+npx ai-review setup
+
+# 显示帮助
+npx ai-review help
+```
+
+### 特殊情况
+
+```bash
+# 跳过 AI 审查（紧急情况）
+git commit --no-verify -m "hotfix: urgent fix"
+
+# 带 -m 提交时仍会进行审查，但会使用你提供的消息
+git commit -m "your message"
+```
+
+---
+
+## ⚙️ 配置选项
+
+通过环境变量配置：
+
+| 环境变量                  | 默认值                      | 说明                                    |
+| ------------------------- | --------------------------- | --------------------------------------- |
+| `OPENAI_API_KEY`          | -                           | **必填**，OpenAI API Key                |
+| `OPENAI_BASE_URL`         | `https://api.openai.com/v1` | 自定义 API 地址                         |
+| `OPENAI_MODEL`            | `gpt-4o-mini`               | 模型，可选 `gpt-4o`、`gpt-3.5-turbo` 等 |
+| `AI_REVIEW_MAX_DIFF_SIZE` | `15000`                     | 最大 Diff 字符数，超出将被截断          |
+| `AI_REVIEW_TIMEOUT`       | `30000`                     | API 请求超时时间（毫秒）                |
+
+---
+
+## 🔄 替代方案对比
+
+| 方案                                              | 优点                              | 缺点                   |
+| ------------------------------------------------- | --------------------------------- | ---------------------- |
+| **本方案 (ai-code-review)**                       | 一键安装、代码审查 + 提交信息生成 | 需要 OpenAI API Key    |
+| [aicommits](https://github.com/Nutlope/aicommits) | 开箱即用的 CLI                    | 不含代码审查功能       |
+| [cz-git](https://cz-git.qbb.sh/) + AI             | 交互式提交、规范完善              | 配置较复杂             |
+| GitHub Copilot                                    | IDE 集成、体验好                  | 需要订阅、无 Hook 集成 |
+
+---
+
+## ⚠️ 注意事项
+
+1. **网络环境**：确保可访问 OpenAI API（或配置代理/自定义 Base URL）
+2. **成本控制**：
+   - 默认使用 `gpt-4o-mini`，成本约为 GPT-4 的 1/10
+   - 大改动建议分批 `git add` 提交
+3. **安全**：`.env` 文件绝对不要提交到仓库
+4. **容错**：脚本在 API 出错时会允许提交，不阻塞开发
+
+---
+
+## 📄 License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// 查找项目根目录
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return startDir;
+}
+
+const projectRoot = findProjectRoot(process.cwd());
+const command = process.argv[2];
+
+const HOOK_CONTENT = `#!/bin/sh
+
+# AI Code Review Hook
+# 将 Git 提供的参数传递给脚本
+# $1: 提交消息文件路径
+# $2: 提交来源 (message, template, merge, squash, commit)
+npx ai-review-hook "$1" "$2"
+`;
+
+const ENV_EXAMPLE = `# OpenAI API 配置
+OPENAI_API_KEY=sk-your-api-key-here
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 可选配置
+# OPENAI_MODEL=gpt-4o-mini
+# AI_REVIEW_MAX_DIFF_SIZE=15000
+# AI_REVIEW_TIMEOUT=30000
+`;
+
+function showHelp() {
+  console.log(`
+AI Code Review CLI
+
+用法:
+  ai-review init       初始化 Husky 并配置 Git Hook
+  ai-review setup      仅配置 Git Hook（假设 Husky 已安装）
+  ai-review help       显示帮助信息
+
+初始化后:
+  1. 在项目根目录创建 .env 文件并配置 OPENAI_API_KEY
+  2. 正常使用 git add && git commit 即可
+
+跳过检查:
+  git commit --no-verify -m "your message"
+`);
+}
+
+function initHusky() {
+  console.log("🚀 初始化 AI Code Review...\n");
+
+  // 检查是否在 Git 仓库中
+  try {
+    execSync("git rev-parse --git-dir", { cwd: projectRoot, stdio: "ignore" });
+  } catch {
+    console.error("❌ 当前目录不是 Git 仓库，请先执行 git init");
+    process.exit(1);
+  }
+
+  // 检查 husky 是否已安装
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+  const hasHusky = packageJson.devDependencies?.husky || packageJson.dependencies?.husky;
+
+  if (!hasHusky) {
+    console.log("📦 安装 Husky...");
+    try {
+      execSync("npm install husky -D", { cwd: projectRoot, stdio: "inherit" });
+    } catch {
+      console.error("❌ Husky 安装失败");
+      process.exit(1);
+    }
+  }
+
+  // 初始化 husky
+  console.log("\n🔧 初始化 Husky...");
+  try {
+    execSync("npx husky init", { cwd: projectRoot, stdio: "inherit" });
+  } catch {
+    // husky init 可能已经执行过，继续
+  }
+
+  setupHook();
+}
+
+function setupHook() {
+  const huskyDir = path.join(projectRoot, ".husky");
+
+  // 确保 .husky 目录存在
+  if (!fs.existsSync(huskyDir)) {
+    fs.mkdirSync(huskyDir, { recursive: true });
+  }
+
+  // 创建 prepare-commit-msg hook
+  const hookPath = path.join(huskyDir, "prepare-commit-msg");
+  fs.writeFileSync(hookPath, HOOK_CONTENT);
+  fs.chmodSync(hookPath, "755");
+  console.log("✅ 创建 Git Hook: .husky/prepare-commit-msg");
+
+  // 创建 .env.example
+  const envExamplePath = path.join(projectRoot, ".env.example");
+  if (!fs.existsSync(envExamplePath)) {
+    fs.writeFileSync(envExamplePath, ENV_EXAMPLE);
+    console.log("✅ 创建配置示例: .env.example");
+  }
+
+  // 更新 .gitignore
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+  let gitignoreContent = "";
+  if (fs.existsSync(gitignorePath)) {
+    gitignoreContent = fs.readFileSync(gitignorePath, "utf-8");
+  }
+  if (!gitignoreContent.includes(".env")) {
+    fs.appendFileSync(gitignorePath, "\n# Environment variables\n.env\n.env.local\n");
+    console.log("✅ 更新 .gitignore: 添加 .env");
+  }
+
+  console.log(`
+🎉 配置完成！
+
+下一步:
+  1. 复制 .env.example 为 .env 并填入你的 OpenAI API Key:
+     cp .env.example .env
+
+  2. 正常提交代码即可:
+     git add .
+     git commit
+
+  跳过检查:
+     git commit --no-verify -m "your message"
+`);
+}
+
+// 主逻辑
+switch (command) {
+  case "init":
+    initHusky();
+    break;
+  case "setup":
+    setupHook();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    showHelp();
+    break;
+  default:
+    showHelp();
+    break;
+}

package/bin/hook.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import OpenAI from "openai";
+
+// 查找项目根目录（包含 package.json 的目录）
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return startDir;
+}
+
+// 加载 .env 文件
+function loadEnv(envPath) {
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, "utf-8");
+    envContent.split("\n").forEach((line) => {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#")) {
+        const [key, ...vals] = trimmed.split("=");
+        if (key && vals.length) {
+          process.env[key.trim()] = vals.join("=").trim();
+        }
+      }
+    });
+  }
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = findProjectRoot(process.cwd());
+
+// 尝试从多个位置加载 .env
+loadEnv(path.join(projectRoot, ".env"));
+loadEnv(path.join(process.cwd(), ".env"));
+
+// 配置
+const CONFIG = {
+  model: process.env.OPENAI_MODEL || "gpt-4o-mini",
+  maxDiffSize: parseInt(process.env.AI_REVIEW_MAX_DIFF_SIZE) || 15000,
+  timeout: parseInt(process.env.AI_REVIEW_TIMEOUT) || 30000,
+  skipBuild: process.env.AI_REVIEW_SKIP_BUILD === "true",
+  buildCommand: process.env.AI_REVIEW_BUILD_COMMAND || "npm run build",
+};
+
+const commitMsgFile = process.argv[2];
+const commitSource = process.argv[3]; // message, template, merge, squash, commit
+
+// 如果是 merge/squash 或已有 message，跳过处理
+if (["merge", "squash", "commit"].includes(commitSource)) {
+  console.log("ℹ️  跳过 AI Review（merge/squash/amend 提交）");
+  process.exit(0);
+}
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error("❌ 未找到 OPENAI_API_KEY，请在项目根目录创建 .env 文件");
+  console.error("   示例: OPENAI_API_KEY=sk-your-api-key-here");
+  console.log("⚠️  跳过 AI Review，允许提交");
+  process.exit(0);
+}
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: process.env.OPENAI_BASE_URL,
+  timeout: CONFIG.timeout,
+});
+
+const SYSTEM_PROMPT = `你是一个资深代码审查员。请分析以下 Git Diff，执行两个任务：
+
+1. **代码审查**：检查是否存在明显的 Bug、安全漏洞或严重的代码规范问题
+2. **生成提交信息**：按照 Conventional Commits 规范生成提交信息
+
+返回 JSON 格式：
+- 如果代码通过审查：{"is_passed": true, "message": "type(scope): description"}
+- 如果代码有问题：{"is_passed": false, "reason": "问题描述和修复建议"}
+
+提交类型：feat, fix, docs, style, refactor, perf, test, chore, ci
+注意：只有严重问题才返回 is_passed: false，代码风格建议可以在 reason 中提及但仍然通过`;
+
+async function runAIReview() {
+  try {
+    // 1. 获取暂存区 Diff
+    const diff = execSync("git diff --cached", { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 });
+
+    if (!diff.trim()) {
+      console.log("ℹ️  没有暂存的更改");
+      process.exit(0);
+    }
+
+    // 2. 运行构建检查
+    if (!CONFIG.skipBuild) {
+      console.log(`🔨 正在运行构建检查: ${CONFIG.buildCommand}`);
+      try {
+        execSync(CONFIG.buildCommand, {
+          cwd: projectRoot,
+          stdio: "inherit",
+          encoding: "utf-8",
+        });
+        console.log("✅ 构建通过");
+      } catch (buildError) {
+        console.error("❌ 构建失败，请修复后重新提交");
+        console.error("\n使用 git commit --no-verify 可跳过检查");
+        process.exit(1);
+      }
+    }
+
+    // 3. 检查 Diff 大小
+    if (diff.length > CONFIG.maxDiffSize) {
+      console.warn(`⚠️  Diff 过大 (${(diff.length / 1000).toFixed(1)}KB)，建议分批提交`);
+      console.warn(`   当前限制: ${CONFIG.maxDiffSize / 1000}KB，超出部分将被截断`);
+    }
+    const truncatedDiff = diff.slice(0, CONFIG.maxDiffSize);
+
+    // 4. 调用 OpenAI
+    console.log("🔍 正在进行 AI 代码审查...");
+
+    const completion = await openai.chat.completions.create({
+      model: CONFIG.model,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: truncatedDiff },
+      ],
+      response_format: { type: "json_object" },
+      temperature: 0.3,
+    });
+
+    const result = JSON.parse(completion.choices[0].message.content);
+
+    // 5. 处理结果
+    if (result.is_passed) {
+      fs.writeFileSync(commitMsgFile, result.message);
+      console.log("✅ AI Review 通过");
+      console.log(`📝 生成的提交信息: ${result.message}`);
+      if (result.suggestions) {
+        console.log(`💡 建议: ${result.suggestions}`);
+      }
+    } else {
+      console.error("❌ AI Review 未通过");
+      console.error(`📋 原因: ${result.reason}`);
+      console.error("\n使用 git commit --no-verify 可跳过检查");
+      process.exit(1);
+    }
+  } catch (error) {
+    if (error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+      console.error("❌ 无法连接到 OpenAI API，请检查网络");
+    } else if (error.status === 401) {
+      console.error("❌ API Key 无效，请检查 .env 配置");
+    } else if (error.status === 429) {
+      console.error("❌ API 请求频率超限，请稍后重试");
+    } else {
+      console.error("❌ AI Review 出错:", error.message);
+    }
+    // 出错时允许提交，避免阻塞开发流程
+    console.log("⚠️  跳过 AI Review，允许提交");
+    process.exit(0);
+  }
+}
+
+runAIReview();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zhuxb-clouds/ai-code-review",
+  "version": "1.0.1",
+  "description": "基于 OpenAI API 的 Git Hooks 集成方案，自动代码审查并生成 Conventional Commits 提交信息",
+  "type": "module",
+  "bin": {
+    "ai-review": "./bin/cli.mjs",
+    "ai-review-hook": "./bin/hook.mjs"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "git",
+    "hooks",
+    "code-review",
+    "openai",
+    "conventional-commits",
+    "husky"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "openai": "^4.0.0"
+  },
+  "peerDependencies": {
+    "husky": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "husky": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}