@zhuxb-clouds/ai-code-review 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,8 @@
 # AI Code Reviewer & Commit Generator
 
-基于 Node.js 和 OpenAI API 的 Git Hooks 集成方案。在执行 `git commit` 时自动进行代码审查，并根据 Diff 自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的提交信息。
+基于 Node.js 和 OpenAI-compatible API 的 Git Hooks 集成方案。在执行 `git commit` 时自动进行代码审查，并根据 Diff 自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的提交信息。
+
+**支持的 AI 提供商**: OpenAI, DeepSeek
 
 ## 🚀 核心特性
 
@@ -9,13 +11,15 @@
 - **无感集成**：通过 Git Hooks 实现，无需改变原有开发习惯
 - **成本可控**：支持 Diff 大小限制，避免 Token 浪费
 - **一键安装**：作为 npm 包安装到任何项目
+- **多提供商支持**：支持 OpenAI、DeepSeek 等兼容 API
+- **代理支持**：支持 HTTP/HTTPS/SOCKS5 代理
 
 ---
 
 ## 🛠️ 技术架构
 
 ```
-git commit → Husky (prepare-commit-msg) → ai-review-hook → OpenAI API
+git commit → Husky (prepare-commit-msg) → ai-review-hook → AI API (OpenAI/DeepSeek)
                                                 ↓
                                     ✅ 通过：自动填充 Commit Message
                                     ❌ 失败：拦截提交并输出建议
@@ -43,11 +47,26 @@ npx ai-review init
 cp .env.example .env
 ```
 
-编辑 `.env`：
+#### 使用 OpenAI
+
+```bash
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-your-openai-key-here
+OPENAI_MODEL=gpt-4o-mini
+```
+
+#### 使用 DeepSeek
+
+```bash
+AI_PROVIDER=deepseek
+DEEPSEEK_API_KEY=sk-your-deepseek-key-here
+# OPENAI_MODEL=deepseek-chat  # 可选，默认 deepseek-chat
+```
+
+#### 使用代理
 
 ```bash
-OPENAI_API_KEY=sk-your-api-key-here
-OPENAI_BASE_URL=https://api.openai.com/v1  # 可选，用于自定义 API 地址
+HTTPS_PROXY=http://127.0.0.1:7890
 ```
 
 > ⚠️ **安全提示**：`.env` 已自动添加到 `.gitignore`，请勿手动提交！
@@ -112,13 +131,34 @@ 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_PROVIDER`      | `openai` | AI 提供商：`openai` 或 `deepseek`                                |
+| `OPENAI_API_KEY`   | -        | OpenAI API Key（使用 OpenAI 时必填）                             |
+| `DEEPSEEK_API_KEY` | -        | DeepSeek API Key（使用 DeepSeek 时必填）                         |
+| `OPENAI_BASE_URL`  | 自动设置 | 自定义 API 地址（可覆盖默认）                                    |
+| `OPENAI_MODEL`     | 自动设置 | 模型名称（OpenAI 默认 gpt-4o-mini，DeepSeek 默认 deepseek-chat） |
+
+### 网络配置
+
+| 环境变量      | 默认值 | 说明                       |
+| ------------- | ------ | -------------------------- |
+| `HTTPS_PROXY` | -      | HTTP/HTTPS/SOCKS5 代理地址 |
+| `HTTP_PROXY`  | -      | 同上，备选                 |
+
+### 行为配置
+
+| 环境变量                  | 默认值          | 说明                       |
+| ------------------------- | --------------- | -------------------------- |
+| `AI_REVIEW_MAX_DIFF_SIZE` | `15000`         | 最大 Diff 字符数，超出截断 |
+| `AI_REVIEW_TIMEOUT`       | `30000`         | API 请求超时时间（毫秒）   |
+| `AI_REVIEW_MAX_RETRIES`   | `3`             | 失败时最大重试次数         |
+| `AI_REVIEW_RETRY_DELAY`   | `1000`          | 重试间隔时间（毫秒）       |
+| `AI_REVIEW_VERBOSE`       | `false`         | 启用详细日志               |
+| `AI_REVIEW_SKIP_BUILD`    | `false`         | 跳过构建检查               |
+| `AI_REVIEW_BUILD_COMMAND` | `npm run build` | 构建命令                   |
 
 ---
 

package/bin/cli.mjs

@@ -31,14 +31,28 @@ const HOOK_CONTENT = `#!/bin/sh
 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
+const ENV_EXAMPLE = `# AI 提供商选择 (openai / deepseek)
+# AI_PROVIDER=openai
 
-# 可选配置
+# OpenAI API 配置
+OPENAI_API_KEY=sk-your-openai-api-key-here
+# OPENAI_BASE_URL=https://api.openai.com/v1
 # OPENAI_MODEL=gpt-4o-mini
-# AI_REVIEW_MAX_DIFF_SIZE=15000
+
+# DeepSeek API 配置 (使用 AI_PROVIDER=deepseek)
+# DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here
+
+# 代理配置 (可选)
+# HTTPS_PROXY=http://127.0.0.1:7890
+
+# 其他可选配置
 # AI_REVIEW_TIMEOUT=30000
+# AI_REVIEW_MAX_DIFF_SIZE=15000
+# AI_REVIEW_MAX_RETRIES=3
+# AI_REVIEW_RETRY_DELAY=1000
+# AI_REVIEW_VERBOSE=false
+# AI_REVIEW_SKIP_BUILD=false
+# AI_REVIEW_BUILD_COMMAND=npm run build
 `;
 
 function showHelp() {

package/bin/hook.mjs

@@ -5,6 +5,7 @@ import path from "path";
 import { execSync } from "child_process";
 import { fileURLToPath } from "url";
 import OpenAI from "openai";
+import { HttpsProxyAgent } from "https-proxy-agent";
 
 // 查找项目根目录（包含 package.json 的目录）
 function findProjectRoot(startDir) {
@@ -41,15 +42,110 @@ const projectRoot = findProjectRoot(process.cwd());
 loadEnv(path.join(projectRoot, ".env"));
 loadEnv(path.join(process.cwd(), ".env"));
 
+// AI 提供商预设配置
+const AI_PROVIDERS = {
+  openai: {
+    baseURL: "https://api.openai.com/v1",
+    defaultModel: "gpt-4o-mini",
+    envKey: "OPENAI_API_KEY",
+  },
+  deepseek: {
+    baseURL: "https://api.deepseek.com",
+    defaultModel: "deepseek-chat",
+    envKey: "DEEPSEEK_API_KEY",
+  },
+  // 可扩展更多提供商
+};
+
+// 获取当前 AI 提供商配置
+function getAIConfig() {
+  const provider = (process.env.AI_PROVIDER || "openai").toLowerCase();
+  const preset = AI_PROVIDERS[provider] || AI_PROVIDERS.openai;
+
+  // 优先使用专用 API Key，否则使用通用 OPENAI_API_KEY
+  const apiKey = process.env[preset.envKey] || process.env.OPENAI_API_KEY;
+  const baseURL = process.env.OPENAI_BASE_URL || preset.baseURL;
+  const model = process.env.OPENAI_MODEL || preset.defaultModel;
+
+  return { provider, apiKey, baseURL, model };
+}
+
+const aiConfig = getAIConfig();
+
 // 配置
 const CONFIG = {
-  model: process.env.OPENAI_MODEL || "gpt-4o-mini",
+  model: aiConfig.model,
   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",
+  verbose: process.env.AI_REVIEW_VERBOSE === "true",
+  maxRetries: parseInt(process.env.AI_REVIEW_MAX_RETRIES) || 3,
+  retryDelay: parseInt(process.env.AI_REVIEW_RETRY_DELAY) || 1000,
 };
 
+// 日志函数
+function log(msg) {
+  console.log(msg);
+}
+
+function logVerbose(msg) {
+  if (CONFIG.verbose) {
+    console.log(`[DEBUG] ${msg}`);
+  }
+}
+
+function logTime(label) {
+  if (CONFIG.verbose) {
+    return { start: Date.now(), label };
+  }
+  return null;
+}
+
+function logTimeEnd(timer) {
+  if (timer && CONFIG.verbose) {
+    console.log(`[DEBUG] ${timer.label}: ${Date.now() - timer.start}ms`);
+  }
+}
+
+// 延迟函数
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// 带重试的 API 调用
+async function callWithRetry(fn, retries = CONFIG.maxRetries) {
+  let lastError;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // 不可重试的错误
+      if (error.status === 401 || error.status === 403) {
+        throw error;
+      }
+
+      // 速率限制，等待更长时间
+      if (error.status === 429) {
+        const waitTime = CONFIG.retryDelay * attempt * 2;
+        logVerbose(`速率限制，等待 ${waitTime}ms 后重试...`);
+        await sleep(waitTime);
+        continue;
+      }
+
+      // 网络错误或服务器错误，重试
+      if (attempt < retries) {
+        const waitTime = CONFIG.retryDelay * attempt;
+        logVerbose(`请求失败 (${error.message})，${waitTime}ms 后重试 (${attempt}/${retries})...`);
+        await sleep(waitTime);
+      }
+    }
+  }
+  throw lastError;
+}
+
 const commitMsgFile = process.argv[2];
 const commitSource = process.argv[3]; // message, template, merge, squash, commit
 
@@ -59,44 +155,99 @@ if (["merge", "squash", "commit"].includes(commitSource)) {
   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");
+if (!aiConfig.apiKey) {
+  console.error(`❌ 未找到 API Key，请在项目根目录创建 .env 文件`);
+  console.error(`   当前提供商: ${aiConfig.provider}`);
+  console.error(
+    `   需要设置: ${AI_PROVIDERS[aiConfig.provider]?.envKey || "OPENAI_API_KEY"}=sk-your-api-key-here`,
+  );
+  console.error(`   可选提供商: ${Object.keys(AI_PROVIDERS).join(", ")}`);
   console.log("⚠️  跳过 AI Review，允许提交");
   process.exit(0);
 }
 
+// 获取代理配置
+function getProxyAgent() {
+  const proxyUrl =
+    process.env.HTTPS_PROXY ||
+    process.env.HTTP_PROXY ||
+    process.env.https_proxy ||
+    process.env.http_proxy;
+
+  if (proxyUrl) {
+    logVerbose(`使用代理: ${proxyUrl}`);
+    return new HttpsProxyAgent(proxyUrl);
+  }
+
+  return undefined;
+}
+
+// 创建 OpenAI 客户端（支持自定义配置和代理）
+const httpAgent = getProxyAgent();
 const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-  baseURL: process.env.OPENAI_BASE_URL,
+  apiKey: aiConfig.apiKey,
+  baseURL: aiConfig.baseURL,
   timeout: CONFIG.timeout,
+  maxRetries: 0, // 我们自己处理重试
+  httpAgent: httpAgent,
 });
 
-const SYSTEM_PROMPT = `你是一个资深代码审查员。请分析以下 Git Diff，执行两个任务：
+logVerbose(`AI 提供商: ${aiConfig.provider}`);
+logVerbose(`API Base URL: ${aiConfig.baseURL}`);
+logVerbose(`模型: ${aiConfig.model}`);
+
+const SYSTEM_PROMPT = `
+你是一个拥有 20 年经验的资深代码架构师。请分析提供的 Git Diff，执行以下任务：
 
-1. **代码审查**：检查是否存在明显的 Bug、安全漏洞或严重的代码规范问题
-2. **生成提交信息**：按照 Conventional Commits 规范生成提交信息
+1. **代码审计 (Critique)**：
+   - 检查是否存在逻辑错误、安全漏洞（如敏感信息泄露）、或会导致 Crash 的严重隐患。
+   - 评估代码是否简洁，并提出改进建议（如变量命名、冗余代码）。
+   - 决策标准：
+     - 如果存在阻断性问题（Bug/安全），*is_passed* 返回 false。
+     - 如果只是优化建议或代码完美，*is_passed* 返回 true。
 
-返回 JSON 格式：
-- 如果代码通过审查：{"is_passed": true, "message": "type(scope): description"}
-- 如果代码有问题：{"is_passed": false, "reason": "问题描述和修复建议"}
+2. **生成提交信息 (Commit Message)**：
+   - 严格遵循 Conventional Commits 规范。
+   - 格式：<type>(<scope>): <description>
+   - 类型范围：feat, fix, docs, style, refactor, perf, test, chore, ci。
+   - 描述：使用中文，精准概括实质性变动。
 
-提交类型：feat, fix, docs, style, refactor, perf, test, chore, ci
-注意：只有严重问题才返回 is_passed: false，代码风格建议可以在 reason 中提及但仍然通过`;
+3. **输出要求**：
+   - 必须严格返回 JSON 格式，不得包含任何 Markdown 格式说明或其他解释文字。
+   - 语言：*reason* 部分使用中文。
+
+`;
 
 async function runAIReview() {
+  const totalTimer = logTime("总耗时");
+
+  logVerbose(`项目根目录: ${projectRoot}`);
+  logVerbose(`模型: ${CONFIG.model}`);
+  logVerbose(`最大 Diff 大小: ${CONFIG.maxDiffSize}`);
+  logVerbose(`超时时间: ${CONFIG.timeout}ms`);
+  logVerbose(`跳过构建: ${CONFIG.skipBuild}`);
+  if (process.env.OPENAI_BASE_URL) {
+    logVerbose(`API Base URL: ${process.env.OPENAI_BASE_URL}`);
+  }
+
   try {
     // 1. 获取暂存区 Diff
+    logVerbose("正在获取暂存区 Diff...");
+    const diffTimer = logTime("获取 Diff");
     const diff = execSync("git diff --cached", { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 });
+    logTimeEnd(diffTimer);
 
     if (!diff.trim()) {
       console.log("ℹ️  没有暂存的更改");
       process.exit(0);
     }
 
+    logVerbose(`Diff 大小: ${(diff.length / 1000).toFixed(2)}KB`);
+
     // 2. 运行构建检查
     if (!CONFIG.skipBuild) {
       console.log(`🔨 正在运行构建检查: ${CONFIG.buildCommand}`);
+      const buildTimer = logTime("构建检查");
       try {
         execSync(CONFIG.buildCommand, {
           cwd: projectRoot,
@@ -104,11 +255,14 @@ async function runAIReview() {
           encoding: "utf-8",
         });
         console.log("✅ 构建通过");
+        logTimeEnd(buildTimer);
       } catch (buildError) {
         console.error("❌ 构建失败，请修复后重新提交");
         console.error("\n使用 git commit --no-verify 可跳过检查");
         process.exit(1);
       }
+    } else {
+      logVerbose("跳过构建检查 (AI_REVIEW_SKIP_BUILD=true)");
     }
 
     // 3. 检查 Diff 大小
@@ -120,19 +274,49 @@ async function runAIReview() {
 
     // 4. 调用 OpenAI
     console.log("🔍 正在进行 AI 代码审查...");
+    logVerbose(`发送 Diff 大小: ${(truncatedDiff.length / 1000).toFixed(2)}KB`);
+    logVerbose(`最大重试次数: ${CONFIG.maxRetries}`);
+    const apiTimer = logTime("API 调用");
 
-    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 completion = await callWithRetry(() =>
+      openai.chat.completions.create({
+        model: CONFIG.model,
+        messages: [
+          { role: "system", content: SYSTEM_PROMPT },
+          {
+            role: "user",
+            content: `
+              任务：审计以下 Diff 并生成 commit message。
+
+              Diff 内容：
+              ${truncatedDiff}
+
+              请按此 JSON 结构返回：
+              {
+                "is_passed": boolean,
+                "reason": "此处填写改进建议或未通过的具体原因，如无建议可为空字符串",
+                "message": "此处填写生成的 Conventional Commit 消息"
+              }
+            `,
+          },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0.3,
+      }),
+    );
+
+    logTimeEnd(apiTimer);
 
     const result = JSON.parse(completion.choices[0].message.content);
 
+    // 输出 token 使用情况
+    if (completion.usage) {
+      logVerbose(
+        `Token 使用: 总计 ${completion.usage.total_tokens} (prompt: ${completion.usage.prompt_tokens}, completion: ${completion.usage.completion_tokens})`,
+      );
+    }
+    logVerbose(`使用模型: ${completion.model}`);
+
     // 5. 处理结果
     if (result.is_passed) {
       fs.writeFileSync(commitMsgFile, result.message);
@@ -141,24 +325,29 @@ async function runAIReview() {
       if (result.suggestions) {
         console.log(`💡 建议: ${result.suggestions}`);
       }
+      logTimeEnd(totalTimer);
     } else {
       console.error("❌ AI Review 未通过");
       console.error(`📋 原因: ${result.reason}`);
       console.error("\n使用 git commit --no-verify 可跳过检查");
+      logTimeEnd(totalTimer);
       process.exit(1);
     }
   } catch (error) {
     if (error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
       console.error("❌ 无法连接到 OpenAI API，请检查网络");
+      logVerbose(`Base URL: ${process.env.OPENAI_BASE_URL || "https://api.openai.com/v1"}`);
     } 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);
+      logVerbose(`错误详情: ${JSON.stringify(error, null, 2)}`);
     }
     // 出错时允许提交，避免阻塞开发流程
     console.log("⚠️  跳过 AI Review，允许提交");
+    logTimeEnd(totalTimer);
     process.exit(0);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxb-clouds/ai-code-review",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "基于 OpenAI API 的 Git Hooks 集成方案，自动代码审查并生成 Conventional Commits 提交信息",
   "type": "module",
   "bin": {
@@ -8,7 +8,12 @@
     "ai-review-hook": "./bin/hook.mjs"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "echo '无构建步骤'",
+    "test": "node test/test.mjs",
+    "test:cli": "node bin/cli.mjs",
+    "test:hook": "node bin/hook.mjs .git/COMMIT_EDITMSG",
+    "test:link": "npm link && echo '已全局链接，可在其他项目使用 npx ai-review'",
+    "test:unlink": "npm unlink -g @zhuxb-clouds/ai-code-review"
   },
   "keywords": [
     "git",
@@ -21,6 +26,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "https-proxy-agent": "^7.0.6",
     "openai": "^4.0.0"
   },
   "peerDependencies": {

package/test/test.mjs

@@ -0,0 +1,534 @@
+#!/usr/bin/env node
+
+/**
+ * 本地测试脚本
+ * 用于测试 AI Code Review 的各项功能
+ */
+
+import fs from "fs";
+import path from "path";
+import { execSync, spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+
+// 颜色输出
+const colors = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+function log(msg, color = "reset") {
+  console.log(`${colors[color]}${msg}${colors.reset}`);
+}
+
+function logSection(title) {
+  console.log("\n" + "=".repeat(50));
+  log(`📋 ${title}`, "cyan");
+  console.log("=".repeat(50));
+}
+
+function logVerbose(msg) {
+  // 在测试中始终启用 verbose 日志
+  console.log(`[DEBUG] ${msg}`);
+}
+
+// 从 OpenAI 错误提取诊断信息
+function analyzeOpenAIError(error) {
+  const errorInfo = {
+    code: error.code,
+    status: error.status,
+    message: error.message,
+    type: error.type || error.constructor?.name,
+  };
+
+  // 尝试获取原始错误信息
+  if (error.response?.data?.error) {
+    const apiError = error.response.data.error;
+    errorInfo.apiError = {
+      type: apiError.type,
+      message: apiError.message,
+      param: apiError.param,
+      code: apiError.code,
+    };
+  }
+
+  // 检查底层错误
+  if (error.cause) {
+    errorInfo.cause = {
+      code: error.cause.code,
+      errno: error.cause.errno,
+      syscall: error.cause.syscall,
+      hostname: error.cause.hostname,
+      port: error.cause.port,
+    };
+  }
+
+  return errorInfo;
+}
+
+// 测试用例
+const tests = {
+  // 测试环境变量加载
+  async testEnvLoading() {
+    logSection("测试环境变量加载");
+
+    const envPath = path.join(projectRoot, ".env");
+    if (fs.existsSync(envPath)) {
+      log("✅ .env 文件存在", "green");
+
+      const content = fs.readFileSync(envPath, "utf-8");
+      const hasApiKey = content.includes("OPENAI_API_KEY");
+
+      if (hasApiKey) {
+        log("✅ OPENAI_API_KEY 已配置", "green");
+      } else {
+        log("⚠️  OPENAI_API_KEY 未配置", "yellow");
+      }
+    } else {
+      log("⚠️  .env 文件不存在，请从 .env.example 复制", "yellow");
+    }
+  },
+
+  // 测试 CLI 命令
+  async testCLI() {
+    logSection("测试 CLI 命令");
+
+    try {
+      const helpOutput = execSync("node bin/cli.mjs help", {
+        cwd: projectRoot,
+        encoding: "utf-8",
+      });
+      log("✅ ai-review help 命令正常", "green");
+      console.log(helpOutput);
+    } catch (error) {
+      log("❌ CLI 命令失败: " + error.message, "red");
+    }
+  },
+
+  // 测试 Git Diff 获取
+  async testGitDiff() {
+    logSection("测试 Git Diff 获取");
+
+    try {
+      const diff = execSync("git diff --cached", {
+        cwd: projectRoot,
+        encoding: "utf-8",
+      });
+
+      if (diff.trim()) {
+        log(`✅ 检测到暂存区变更 (${(diff.length / 1000).toFixed(1)}KB)`, "green");
+        console.log("前 500 字符预览:");
+        console.log(diff.slice(0, 500) + (diff.length > 500 ? "\n..." : ""));
+      } else {
+        log("ℹ️  暂存区没有变更", "blue");
+        log("   提示: 使用 git add <file> 添加文件后再测试", "yellow");
+      }
+    } catch (error) {
+      log("❌ Git Diff 获取失败: " + error.message, "red");
+    }
+  },
+
+  // 测试构建命令
+  async testBuild() {
+    logSection("测试构建命令");
+
+    const packageJsonPath = path.join(projectRoot, "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+
+    if (packageJson.scripts?.build) {
+      log("ℹ️  发现 build 脚本，尝试运行...", "blue");
+      try {
+        execSync("npm run build", { cwd: projectRoot, stdio: "inherit" });
+        log("✅ 构建成功", "green");
+      } catch (error) {
+        log("❌ 构建失败", "red");
+      }
+    } else {
+      log("ℹ️  没有 build 脚本（这是正常的，此项目不需要构建）", "blue");
+    }
+  },
+
+  // 模拟 Hook 调用（不实际调用 AI）
+  async testHookDryRun() {
+    logSection("测试 Hook 逻辑（模拟运行）");
+
+    // 检查必要文件
+    const hookPath = path.join(projectRoot, "bin/hook.mjs");
+    if (fs.existsSync(hookPath)) {
+      log("✅ hook.mjs 文件存在", "green");
+    } else {
+      log("❌ hook.mjs 文件不存在", "red");
+      return;
+    }
+
+    // 检查依赖
+    try {
+      await import("openai");
+      log("✅ openai 依赖已安装", "green");
+    } catch {
+      log("❌ openai 依赖未安装，请运行 npm install", "red");
+    }
+  },
+
+  // AI 提供商预设配置
+  AI_PROVIDERS: {
+    openai: {
+      baseURL: "https://api.openai.com/v1",
+      defaultModel: "gpt-4o-mini",
+      envKey: "OPENAI_API_KEY",
+    },
+    deepseek: {
+      baseURL: "https://api.deepseek.com",
+      defaultModel: "deepseek-chat",
+      envKey: "DEEPSEEK_API_KEY",
+    },
+  },
+
+  // 获取当前 AI 配置
+  getAIConfig() {
+    const provider = (process.env.AI_PROVIDER || "openai").toLowerCase();
+    const preset = this.AI_PROVIDERS[provider] || this.AI_PROVIDERS.openai;
+    const apiKey = process.env[preset.envKey] || process.env.OPENAI_API_KEY;
+    const baseURL = process.env.OPENAI_BASE_URL || preset.baseURL;
+    const model = process.env.OPENAI_MODEL || preset.defaultModel;
+    return { provider, apiKey, baseURL, model };
+  },
+
+  // 测试 API 连接
+  async testAPI() {
+    logSection("测试 AI API 连接");
+
+    // 加载环境变量
+    const envPath = path.join(projectRoot, ".env");
+    if (!fs.existsSync(envPath)) {
+      log("⏭️  跳过：未找到 .env 文件", "yellow");
+      return;
+    }
+
+    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 aiConfig = this.getAIConfig();
+
+    if (!aiConfig.apiKey) {
+      log(`⏭️  跳过：未配置 API Key`, "yellow");
+      log(`   当前提供商: ${aiConfig.provider}`, "yellow");
+      log(
+        `   需要设置: ${this.AI_PROVIDERS[aiConfig.provider]?.envKey || "OPENAI_API_KEY"}`,
+        "yellow",
+      );
+      return;
+    }
+
+    log(`🔗 正在测试 ${aiConfig.provider.toUpperCase()} API 连接...`, "blue");
+    const timeout = parseInt(process.env.AI_REVIEW_TIMEOUT) || 30000;
+    const proxyUrl =
+      process.env.HTTPS_PROXY ||
+      process.env.HTTP_PROXY ||
+      process.env.https_proxy ||
+      process.env.http_proxy;
+
+    log(`   提供商: ${aiConfig.provider}`, "blue");
+    log(`   Base URL: ${aiConfig.baseURL}`, "blue");
+    log(`   模型: ${aiConfig.model}`, "blue");
+    log(`   超时: ${timeout}ms`, "blue");
+    if (proxyUrl) {
+      log(`   代理: ${proxyUrl}`, "blue");
+    } else {
+      log(`   代理: 未配置 (设置 HTTPS_PROXY 环境变量启用)`, "yellow");
+    }
+
+    try {
+      const OpenAI = (await import("openai")).default;
+
+      // 创建代理 agent
+      let httpAgent = undefined;
+      if (proxyUrl) {
+        httpAgent = new HttpsProxyAgent(proxyUrl);
+        logVerbose(`   已创建代理 agent`);
+      }
+
+      // 创建 OpenAI 客户端实例
+      log("\n   1️⃣  初始化 AI 客户端...", "blue");
+      const openai = new OpenAI({
+        apiKey: aiConfig.apiKey,
+        baseURL: aiConfig.baseURL,
+        timeout: timeout,
+        maxRetries: 0, // 禁用自动重试，由我们控制
+        httpAgent: httpAgent,
+      });
+
+      logVerbose(`   客户端初始化成功`);
+
+      // 测试 API 连接 - 发送轻量级请求
+      log("   2️⃣  测试 API 连接...", "blue");
+      const startTime = Date.now();
+
+      try {
+        const completion = await openai.chat.completions.create({
+          model: aiConfig.model,
+          messages: [
+            {
+              role: "user",
+              content: "Say 'OK' only.",
+            },
+          ],
+          max_tokens: 10,
+          temperature: 0,
+        });
+
+        const elapsed = Date.now() - startTime;
+
+        log("   3️⃣  解析响应...", "blue");
+        const response = completion.choices[0]?.message?.content || "";
+
+        log("\n✅ OpenAI API 连接成功！", "green");
+        log(`   实际模型: ${completion.model}`, "blue");
+        log(`   响应内容: ${response}`, "blue");
+        log(`   响应时间: ${elapsed}ms`, "blue");
+
+        if (completion.usage) {
+          log(`   📊 Token 使用:`, "blue");
+          log(`      • Prompt tokens: ${completion.usage.prompt_tokens}`, "blue");
+          log(`      • Completion tokens: ${completion.usage.completion_tokens}`, "blue");
+          log(`      • Total tokens: ${completion.usage.total_tokens}`, "blue");
+        }
+
+        log(`\n✨ 所有检查通过，API 连接正常！`, "green");
+      } catch (apiError) {
+        // API 调用失败，但客户端创建成功说明基本连接没问题
+        throw apiError;
+      }
+    } catch (error) {
+      log("❌ API 测试失败", "red");
+
+      // 获取错误详情
+      const errorInfo = analyzeOpenAIError(error);
+
+      logVerbose(`\n错误对象分析:`);
+      logVerbose(`  Code: ${errorInfo.code}`);
+      logVerbose(`  Status: ${errorInfo.status}`);
+      logVerbose(`  Type: ${errorInfo.type}`);
+      logVerbose(`  Message: ${errorInfo.message}`);
+      if (errorInfo.apiError) {
+        logVerbose(`  API Error: ${JSON.stringify(errorInfo.apiError)}`);
+      }
+      if (errorInfo.cause) {
+        logVerbose(`  Cause: ${JSON.stringify(errorInfo.cause)}`);
+      }
+
+      log("\n🔍 诊断和修复建议：", "yellow");
+
+      // 详细的错误诊断
+      if (error.code === "ECONNREFUSED" || errorInfo.cause?.code === "ECONNREFUSED") {
+        log("\n  错误：无法连接到服务器", "red");
+        log("  可能原因：", "blue");
+        log("    • Base URL 错误或服务器无法访问", "blue");
+        log("    • 网络连接问题", "blue");
+        log("    • 防火墙或代理阻止了请求", "blue");
+        log(
+          `\n  当前 Base URL: ${process.env.OPENAI_BASE_URL || "https://api.openai.com/v1"}`,
+          "yellow",
+        );
+        log("  修复步骤：", "blue");
+        log("    1. 测试网络: ping api.openai.com", "blue");
+        log("    2. 检查代理: 如需代理，设置 HTTP_PROXY 或 HTTPS_PROXY", "blue");
+        log("    3. 检查防火墙设置", "blue");
+      } else if (error.code === "ETIMEDOUT" || errorInfo.cause?.code === "ETIMEDOUT") {
+        log("\n  错误：请求超时", "red");
+        log("  可能原因：", "blue");
+        log("    • 网络延迟过高", "blue");
+        log("    • API 响应缓慢", "blue");
+        log("    • 超时时间设置过短", "blue");
+        log(`\n  当前超时: ${process.env.AI_REVIEW_TIMEOUT || 30000}ms`, "yellow");
+        log("  修复步骤：", "blue");
+        log("    1. 增加超时: 设置 AI_REVIEW_TIMEOUT=60000", "blue");
+        log("    2. 检查网络延迟: ping api.openai.com", "blue");
+        log("    3. 稍后重试", "blue");
+      } else if (error.code === "ENOTFOUND" || errorInfo.cause?.code === "ENOTFOUND") {
+        log("\n  错误：DNS 解析失败", "red");
+        log("  可能原因：", "blue");
+        log("    • DNS 配置错误", "blue");
+        log("    • 域名拼写错误", "blue");
+        log("    • 网络无法访问 DNS 服务", "blue");
+        log(
+          `\n  当前 Base URL: ${process.env.OPENAI_BASE_URL || "https://api.openai.com/v1"}`,
+          "yellow",
+        );
+        log("  修复步骤：", "blue");
+        log("    1. 检查 DNS 设置", "blue");
+        log("    2. 尝试使用公共 DNS 8.8.8.8", "blue");
+        log("    3. 检查 Base URL 拼写", "blue");
+      } else if (error.status === 401 || errorInfo.apiError?.code === "invalid_api_key") {
+        log("\n  错误：API Key 无效或已过期", "red");
+        log("  可能原因：", "blue");
+        log("    • API Key 不正确或已删除", "blue");
+        log("    • API Key 已过期", "blue");
+        log("    • API Key 权限不足", "blue");
+        log("\n  修复步骤：", "blue");
+        log("    1. 检查 .env 中的 OPENAI_API_KEY 是否正确", "blue");
+        log("    2. 访问 https://platform.openai.com/api-keys 重新生成 Key", "blue");
+        log("    3. 等待 60 秒后重试", "blue");
+      } else if (error.status === 429 || errorInfo.apiError?.code === "rate_limit_exceeded") {
+        log("\n  错误：请求频率超限或配额不足", "red");
+        log("  可能原因：", "blue");
+        log("    • 请求过于频繁", "blue");
+        log("    • API 配额已用尽", "blue");
+        log("    • 账户余额不足", "blue");
+        log("\n  修复步骤：", "blue");
+        log("    1. 等待几分钟后重试", "blue");
+        log("    2. 检查账户余额: https://platform.openai.com/account/billing/overview", "blue");
+        log("    3. 检查使用配额: https://platform.openai.com/account/rate-limits", "blue");
+      } else if (error.status === 404 || errorInfo.apiError?.code === "model_not_found") {
+        log("\n  错误：模型不存在或无权访问", "red");
+        log("  可能原因：", "blue");
+        log("    • 模型名称错误或不存在", "blue");
+        log("    • 模型已下线", "blue");
+        log("    • 账户无权使用该模型", "blue");
+        log(`\n  当前模型: ${process.env.OPENAI_MODEL || "gpt-4o-mini"}`, "yellow");
+        log("  修复步骤：", "blue");
+        log("    1. 检查模型名称: https://platform.openai.com/docs/models", "blue");
+        log("    2. 修改 OPENAI_MODEL 为有效的模型名", "blue");
+        log("    3. 检查账户权限", "blue");
+      } else if (error.status === 500 || error.status === 502 || error.status === 503) {
+        log(`\n  错误：OpenAI 服务器错误 (${error.status})`, "red");
+        log("  可能原因：", "blue");
+        log("    • OpenAI 服务暂时不可用", "blue");
+        log("    • 服务器故障", "blue");
+        log("    • 服务器维护中", "blue");
+        log("\n  修复步骤：", "blue");
+        log("    1. 稍后重试", "blue");
+        log("    2. 检查 OpenAI 状态: https://status.openai.com", "blue");
+        log("    3. 查看官方通告", "blue");
+      } else {
+        log(`\n  错误: ${error.message}`, "yellow");
+        log(`  错误类型: ${errorInfo.type}`, "yellow");
+        log(`  错误代码: ${errorInfo.code || "未知"}`, "yellow");
+        if (error.status) {
+          log(`  HTTP 状态: ${error.status}`, "yellow");
+        }
+        log("\n  通用排查步骤：", "blue");
+        log("    1. 启用详细日志: AI_REVIEW_VERBOSE=true", "blue");
+        log("    2. 检查 .env 配置文件中的所有参数", "blue");
+        log("    3. 验证 API Key 和 Base URL", "blue");
+        log("    4. 测试网络连接: curl https://api.openai.com/v1/models", "blue");
+        log("    5. 查看完整错误信息（使用 AI_REVIEW_VERBOSE=true）", "blue");
+      }
+    }
+  },
+
+  // 测试完整流程（需要 API Key）
+  async testFullFlow() {
+    logSection("测试完整流程（需要暂存的更改和 API Key）");
+
+    const envPath = path.join(projectRoot, ".env");
+    if (!fs.existsSync(envPath)) {
+      log("⏭️  跳过：未配置 .env", "yellow");
+      return;
+    }
+
+    try {
+      const diff = execSync("git diff --cached", {
+        cwd: projectRoot,
+        encoding: "utf-8",
+      });
+
+      if (!diff.trim()) {
+        log("⏭️  跳过：暂存区没有变更", "yellow");
+        log("   要测试完整流程，请先 git add 一些文件", "blue");
+        return;
+      }
+
+      log("🚀 运行完整 Hook 测试...", "blue");
+      log("   这将调用 OpenAI API（会产生费用）", "yellow");
+      log("   按 Ctrl+C 可取消\n", "yellow");
+
+      // 创建临时 commit msg 文件
+      const tmpMsgFile = path.join(projectRoot, ".git/COMMIT_EDITMSG_TEST");
+      fs.writeFileSync(tmpMsgFile, "");
+
+      try {
+        execSync(`node bin/hook.mjs "${tmpMsgFile}" message`, {
+          cwd: projectRoot,
+          stdio: "inherit",
+          env: { ...process.env },
+        });
+
+        const generatedMsg = fs.readFileSync(tmpMsgFile, "utf-8");
+        if (generatedMsg) {
+          log("\n✅ 完整流程测试成功！", "green");
+          log(`📝 生成的提交信息: ${generatedMsg}`, "cyan");
+        }
+      } finally {
+        // 清理临时文件
+        if (fs.existsSync(tmpMsgFile)) {
+          fs.unlinkSync(tmpMsgFile);
+        }
+      }
+    } catch (error) {
+      log("❌ 完整流程测试失败: " + error.message, "red");
+    }
+  },
+};
+
+// 运行所有测试
+async function runTests() {
+  console.log("\n🧪 AI Code Review 本地测试\n");
+
+  const testName = process.argv[2];
+
+  if (testName && tests[testName]) {
+    // 运行指定测试
+    await tests[testName]();
+  } else if (testName === "full") {
+    // 运行完整流程测试
+    await tests.testFullFlow();
+  } else {
+    // 运行所有基础测试
+    await tests.testEnvLoading();
+    await tests.testCLI();
+    await tests.testGitDiff();
+    await tests.testBuild();
+    await tests.testHookDryRun();
+
+    console.log("\n" + "=".repeat(50));
+    log("💡 提示", "cyan");
+    console.log("=".repeat(50));
+    console.log(`
+测试 API 连接（会调用 API，消耗少量 token）：
+  npm test testAPI
+
+运行完整流程测试（会调用 API）：
+  npm test full
+
+单独运行某个测试：
+  npm test testEnvLoading
+  npm test testCLI
+  npm test testGitDiff
+  npm test testAPI
+  npm test testFullFlow
+
+本地链接测试（在其他项目中使用）：
+  npm run test:link
+  cd ../other-project
+  npx ai-review init
+`);
+  }
+}
+
+runTests().catch(console.error);