commit-ai-guardian 0.2.0__tar.gz → 0.2.2__tar.gz

{commit_ai_guardian-0.2.0 → commit_ai_guardian-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commit-ai-guardian
-Version: 0.2.0
+Version: 0.2.2
 Summary: Git Pre-commit Hook AI 代码审核系统
 Project-URL: Homepage, https://github.com/yourusername/commit-ai-guardian
 Project-URL: Issues, https://github.com/yourusername/commit-ai-guardian/issues
@@ -31,6 +31,7 @@ Description-Content-Type: text/markdown
 
 ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)
 ![License MIT](https://img.shields.io/badge/license-MIT-green)
+[![PyPI](https://img.shields.io/pypi/v/commit-ai-guardian)](https://pypi.org/project/commit-ai-guardian/)
 
 > **📚 学习笔记**：[STUDY.md](STUDY.md) — 设计原理与常见问题解答（适合初学者）  
 > **🔧 技术细节**：[TECHNICAL.md](TECHNICAL.md) — 架构设计、实现原理、Prompt 工程等（适合开发者）
@@ -53,35 +54,33 @@ Description-Content-Type: text/markdown
 
 ### 安装
 
-#### 从 GitLab 安装（推荐，公司内部）
+#### 从 PyPI 安装（推荐）
 
 ```bash
-uv tool install git+ssh://git@124.223.189.152:7022/gaoq/ai-review.git
+uv tool install commit-ai-guardian
 ```
 
-#### 从 GitHub 安装（Python 版本）
+#### 从 GitHub 安装
 
 ```bash
 uv tool install git+https://github.com/tingkl/ai-review.git
 ```
 
-#### 从 PyPI 安装（暂未发布）
-
-> ⏳ **尚未发布到 PyPI**，发布后可用：
+#### 从 GitLab 安装（公司内部）
 
 ```bash
-uv tool install commit-ai-guardian
+uv tool install git+ssh://git@124.223.189.152:7022/gaoq/ai-review.git
 ```
 
 ### 三种方式对比
 
-| | GitLab | GitHub | PyPI |
+| | PyPI | GitHub | GitLab |
 |---|---|---|---|
-| 安装源 | 内部 GitLab | 公开 GitHub | 公开包仓库 |
-| 协议 | SSH | HTTPS | HTTPS |
-| 代码版本 | 最新 main 分支 | 最新 main 分支 | 发布的稳定版 |
-| 适用场景 | 公司内部开发 | 外部开发者贡献 | 生产环境用户 |
-| 当前状态 | ✅ 可用 | ✅ 可用 | ⏳ 待发布 |
+| 安装源 | 公开包仓库 | 公开 GitHub | 内部 GitLab |
+| 协议 | HTTPS | HTTPS | SSH |
+| 代码版本 | 发布的稳定版 | 最新 main 分支 | 最新 main 分支 |
+| 适用场景 | 普通用户、生产环境 | 外部开发者贡献 | 公司内部开发 |
+| 当前状态 | ✅ **推荐** | ✅ 可用 | ✅ 可用 |
 
 ### 升级
 
@@ -143,7 +142,7 @@ cag 在 hook 文件中写入特定的 marker 标记来识别：
 
 | hook 文件 | cag 的 marker 标记 |
 |-----------|-------------------|
-| `.git/hooks/pre-commit` | `# AI Code Review Hook — generated by commit-ai-guardian` |
+| `.git/hooks/pre-commit` | `# === commit-ai-guardian ===` |
 | `.husky/pre-commit` | `# === commit-ai-guardian ===` |
 
 判断逻辑：文件存在但 **不含上述 marker** → 视为"有其他自定义 hook"（如 lint-staged、husky 默认模板、用户手写脚本等）。
@@ -198,7 +197,7 @@ cag 在 hook 文件中写入特定的 marker 标记来识别：
 | `diff_mode` | 审核范围（`full` 全部文件 / `diff` 仅变更） | `full` |
 | `use_cache` | 是否启用结果缓存 | `true` |
 | `include_patterns` | 审核文件范围（glob 数组） | `["*"]` |
-| `case_format` | 案例输出格式（`default` / `compact` / `minimal`） | `default` |
+| `case_format` | 案例输出格式（`default` / `compact` / `minimal`） | `compact` |
 | `max_tokens` | AI 最大返回长度（token 数） | `8192` |
 | `max_file_size` | 最大审核文件大小，**单位 KB** | `500` |
 | `temperature` | AI 随机性（0=最保守, 0.3=平衡, 0.7=灵活） | `0.3` |
@@ -231,17 +230,28 @@ include_patterns:
 
 `max_tokens` 限制的是 **AI 输出长度**（JSON 响应），不是输入。不同模型默认值差异很大，建议显式配置：
 
-| 模型 | 默认 max_tokens | 最大可设 | 建议值 |
-|------|----------------|---------|--------|
-| **MiniMax M3** | 很小（不设会截断） | 131,072 (128K) | 16,384 (16K) |
-| **MiniMax M2.x** | 很小 | 131,072 (128K) | 16,384 (16K) |
-| **DeepSeek** | **4,096** | **8,192** (8K) | 8,192 (8K) |
-| **Kimi K2.x** | **32,768** | 128K | 16,384 (16K) |
-| **GPT-4o** | ~4,096 | 16,384 (16K) | 8,192 (8K) |
-
-> **为什么要配置**：MiniMax 如果不设 max_tokens，默认很小，JSON 几乎一定会被截断。默认值 `8192` 覆盖 95% 场景，使用 MiniMax 时可适当提高。
+| 服务商 | 模型 | 默认 max_tokens | 最大可设 | 建议值 |
+|--------|------|----------------|---------|--------|
+| **DeepSeek** | deepseek-v4-pro | 4,096 | 1,048,576 (1M) | **16K** |
+| **DeepSeek** | deepseek-v4-flash | 4,096 | 1,048,576 (1M) | **16K** |
+| **DeepSeek** | deepseek-chat | 4,096 | 8,192 (8K) | **8K** |
+| **DeepSeek** | deepseek-reasoner | 4,096 | 8,192 (8K) | **8K** |
+| **Kimi** | kimi-k2.6 | 32,768 | 262,144 (256K) | **16K** |
+| **Kimi** | kimi-k2 | 32,768 | 262,144 (256K) | **16K** |
+| **Kimi** | kimi-k2-thinking | 32,768 | 262,144 (256K) | **16K** |
+| **MiniMax** | MiniMax-M3 | 很小（不设会截断） | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.7 | 很小 | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.5 | 很小 | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.1 | 很小 | 131,072 (128K) | **16K** |
+| **OpenAI** | gpt-4o | ~4,096 | 16,384 (16K) | **8K** |
+| **OpenAI** | gpt-4o-mini | ~4,096 | 16,384 (16K) | **8K** |
+| **OpenAI** | gpt-3.5-turbo | ~4,096 | 4,096 (4K) | **4K** |
+
+> **模型推荐**：DeepSeek 请用 `deepseek-v4-pro`（1M 上下文，最强代码能力），`deepseek-chat` 将于 2026/07/24 停用。Kimi 请用 `kimi-k2.6`（最新版本）。
+>
+> **为什么要配置**：MiniMax 如果不设 max_tokens，默认很小，JSON 几乎一定会被截断。默认值 `8192` 覆盖 95% 场景，使用 MiniMax 或 DeepSeek V4 时可适当提高。
 >
-> **支持简写**：`8K` = 8192，`16k` = 16384，纯数字 `8192` 也可以。
+> **支持简写**：`4K` = 4096，`8K` = 8192，`16k` = 16384，纯数字也可以。
 
 ### 查看配置状态
 
@@ -318,6 +328,38 @@ git remote add github https://github.com/your/project.git
 git push origin main && git push github main
 ```
 
+### 配置网络代理（HTTP Proxy）
+
+如果你的网络需要代理才能访问 AI API（例如公司内网、或 Clash/V2Ray 规则模式），可以配置代理地址。
+
+**怎么判断是否需要配 proxy：**
+
+先不配 proxy 直接运行 `cag review`，能正常返回结果就不需要；如果报连接超时 / `Connection refused`，再配置。
+
+**配置方式：**
+
+```bash
+# 方式一：交互式配置
+cag configure
+# 提示输入 proxy 时填写：http://127.0.0.1:7890
+
+# 方式二：直接编辑配置文件
+vim ~/.commit_ai_guardian/config.yaml
+# proxy: "http://127.0.0.1:7890"
+```
+
+**常见代理地址：**
+
+| 工具 | 默认地址 |
+|------|----------|
+| Clash | `http://127.0.0.1:7890` |
+| V2RayN | `http://127.0.0.1:10809` |
+| Surge | `http://127.0.0.1:6152` |
+
+> 如果你的 Clash 开了**全局/TUN 模式**，系统所有流量自动走代理，不需要额外配置。只在**规则模式**下需要配置 proxy，因为 Python 不会自动读取系统代理设置。
+>
+> proxy 只影响命令行工具，不影响 Git hook（hook 继承 shell 环境变量）。
+
 ---
 
 ## 常见问题

{commit_ai_guardian-0.2.0 → commit_ai_guardian-0.2.2}/README.md

@@ -4,6 +4,7 @@
 
 ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)
 ![License MIT](https://img.shields.io/badge/license-MIT-green)
+[![PyPI](https://img.shields.io/pypi/v/commit-ai-guardian)](https://pypi.org/project/commit-ai-guardian/)
 
 > **📚 学习笔记**：[STUDY.md](STUDY.md) — 设计原理与常见问题解答（适合初学者）  
 > **🔧 技术细节**：[TECHNICAL.md](TECHNICAL.md) — 架构设计、实现原理、Prompt 工程等（适合开发者）
@@ -26,35 +27,33 @@
 
 ### 安装
 
-#### 从 GitLab 安装（推荐，公司内部）
+#### 从 PyPI 安装（推荐）
 
 ```bash
-uv tool install git+ssh://git@124.223.189.152:7022/gaoq/ai-review.git
+uv tool install commit-ai-guardian
 ```
 
-#### 从 GitHub 安装（Python 版本）
+#### 从 GitHub 安装
 
 ```bash
 uv tool install git+https://github.com/tingkl/ai-review.git
 ```
 
-#### 从 PyPI 安装（暂未发布）
-
-> ⏳ **尚未发布到 PyPI**，发布后可用：
+#### 从 GitLab 安装（公司内部）
 
 ```bash
-uv tool install commit-ai-guardian
+uv tool install git+ssh://git@124.223.189.152:7022/gaoq/ai-review.git
 ```
 
 ### 三种方式对比
 
-| | GitLab | GitHub | PyPI |
+| | PyPI | GitHub | GitLab |
 |---|---|---|---|
-| 安装源 | 内部 GitLab | 公开 GitHub | 公开包仓库 |
-| 协议 | SSH | HTTPS | HTTPS |
-| 代码版本 | 最新 main 分支 | 最新 main 分支 | 发布的稳定版 |
-| 适用场景 | 公司内部开发 | 外部开发者贡献 | 生产环境用户 |
-| 当前状态 | ✅ 可用 | ✅ 可用 | ⏳ 待发布 |
+| 安装源 | 公开包仓库 | 公开 GitHub | 内部 GitLab |
+| 协议 | HTTPS | HTTPS | SSH |
+| 代码版本 | 发布的稳定版 | 最新 main 分支 | 最新 main 分支 |
+| 适用场景 | 普通用户、生产环境 | 外部开发者贡献 | 公司内部开发 |
+| 当前状态 | ✅ **推荐** | ✅ 可用 | ✅ 可用 |
 
 ### 升级
 
@@ -116,7 +115,7 @@ cag 在 hook 文件中写入特定的 marker 标记来识别：
 
 | hook 文件 | cag 的 marker 标记 |
 |-----------|-------------------|
-| `.git/hooks/pre-commit` | `# AI Code Review Hook — generated by commit-ai-guardian` |
+| `.git/hooks/pre-commit` | `# === commit-ai-guardian ===` |
 | `.husky/pre-commit` | `# === commit-ai-guardian ===` |
 
 判断逻辑：文件存在但 **不含上述 marker** → 视为"有其他自定义 hook"（如 lint-staged、husky 默认模板、用户手写脚本等）。
@@ -171,7 +170,7 @@ cag 在 hook 文件中写入特定的 marker 标记来识别：
 | `diff_mode` | 审核范围（`full` 全部文件 / `diff` 仅变更） | `full` |
 | `use_cache` | 是否启用结果缓存 | `true` |
 | `include_patterns` | 审核文件范围（glob 数组） | `["*"]` |
-| `case_format` | 案例输出格式（`default` / `compact` / `minimal`） | `default` |
+| `case_format` | 案例输出格式（`default` / `compact` / `minimal`） | `compact` |
 | `max_tokens` | AI 最大返回长度（token 数） | `8192` |
 | `max_file_size` | 最大审核文件大小，**单位 KB** | `500` |
 | `temperature` | AI 随机性（0=最保守, 0.3=平衡, 0.7=灵活） | `0.3` |
@@ -204,17 +203,28 @@ include_patterns:
 
 `max_tokens` 限制的是 **AI 输出长度**（JSON 响应），不是输入。不同模型默认值差异很大，建议显式配置：
 
-| 模型 | 默认 max_tokens | 最大可设 | 建议值 |
-|------|----------------|---------|--------|
-| **MiniMax M3** | 很小（不设会截断） | 131,072 (128K) | 16,384 (16K) |
-| **MiniMax M2.x** | 很小 | 131,072 (128K) | 16,384 (16K) |
-| **DeepSeek** | **4,096** | **8,192** (8K) | 8,192 (8K) |
-| **Kimi K2.x** | **32,768** | 128K | 16,384 (16K) |
-| **GPT-4o** | ~4,096 | 16,384 (16K) | 8,192 (8K) |
-
-> **为什么要配置**：MiniMax 如果不设 max_tokens，默认很小，JSON 几乎一定会被截断。默认值 `8192` 覆盖 95% 场景，使用 MiniMax 时可适当提高。
+| 服务商 | 模型 | 默认 max_tokens | 最大可设 | 建议值 |
+|--------|------|----------------|---------|--------|
+| **DeepSeek** | deepseek-v4-pro | 4,096 | 1,048,576 (1M) | **16K** |
+| **DeepSeek** | deepseek-v4-flash | 4,096 | 1,048,576 (1M) | **16K** |
+| **DeepSeek** | deepseek-chat | 4,096 | 8,192 (8K) | **8K** |
+| **DeepSeek** | deepseek-reasoner | 4,096 | 8,192 (8K) | **8K** |
+| **Kimi** | kimi-k2.6 | 32,768 | 262,144 (256K) | **16K** |
+| **Kimi** | kimi-k2 | 32,768 | 262,144 (256K) | **16K** |
+| **Kimi** | kimi-k2-thinking | 32,768 | 262,144 (256K) | **16K** |
+| **MiniMax** | MiniMax-M3 | 很小（不设会截断） | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.7 | 很小 | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.5 | 很小 | 131,072 (128K) | **16K** |
+| **MiniMax** | MiniMax-M2.1 | 很小 | 131,072 (128K) | **16K** |
+| **OpenAI** | gpt-4o | ~4,096 | 16,384 (16K) | **8K** |
+| **OpenAI** | gpt-4o-mini | ~4,096 | 16,384 (16K) | **8K** |
+| **OpenAI** | gpt-3.5-turbo | ~4,096 | 4,096 (4K) | **4K** |
+
+> **模型推荐**：DeepSeek 请用 `deepseek-v4-pro`（1M 上下文，最强代码能力），`deepseek-chat` 将于 2026/07/24 停用。Kimi 请用 `kimi-k2.6`（最新版本）。
+>
+> **为什么要配置**：MiniMax 如果不设 max_tokens，默认很小，JSON 几乎一定会被截断。默认值 `8192` 覆盖 95% 场景，使用 MiniMax 或 DeepSeek V4 时可适当提高。
 >
-> **支持简写**：`8K` = 8192，`16k` = 16384，纯数字 `8192` 也可以。
+> **支持简写**：`4K` = 4096，`8K` = 8192，`16k` = 16384，纯数字也可以。
 
 ### 查看配置状态
 
@@ -291,6 +301,38 @@ git remote add github https://github.com/your/project.git
 git push origin main && git push github main
 ```
 
+### 配置网络代理（HTTP Proxy）
+
+如果你的网络需要代理才能访问 AI API（例如公司内网、或 Clash/V2Ray 规则模式），可以配置代理地址。
+
+**怎么判断是否需要配 proxy：**
+
+先不配 proxy 直接运行 `cag review`，能正常返回结果就不需要；如果报连接超时 / `Connection refused`，再配置。
+
+**配置方式：**
+
+```bash
+# 方式一：交互式配置
+cag configure
+# 提示输入 proxy 时填写：http://127.0.0.1:7890
+
+# 方式二：直接编辑配置文件
+vim ~/.commit_ai_guardian/config.yaml
+# proxy: "http://127.0.0.1:7890"
+```
+
+**常见代理地址：**
+
+| 工具 | 默认地址 |
+|------|----------|
+| Clash | `http://127.0.0.1:7890` |
+| V2RayN | `http://127.0.0.1:10809` |
+| Surge | `http://127.0.0.1:6152` |
+
+> 如果你的 Clash 开了**全局/TUN 模式**，系统所有流量自动走代理，不需要额外配置。只在**规则模式**下需要配置 proxy，因为 Python 不会自动读取系统代理设置。
+>
+> proxy 只影响命令行工具，不影响 Git hook（hook 继承 shell 环境变量）。
+
 ---
 
 ## 常见问题

commit_ai_guardian-0.2.2/docs/article-promotion.md

@@ -0,0 +1,182 @@
+# AI 代码审核工具 commit-ai-guardian：让每次提交都经得起审查
+
+> **一句话介绍**：在 git commit 前自动调用 AI 审查代码，发现问题直接阻断提交，帮你把 Bug 挡在代码库门外。
+
+---
+
+## 01 为什么做这个工具
+
+我在一个 20 人的研发团队带项目。Code Review 是有的，但大家都忙，CR 往往流于形式——扫两眼就过了。结果上线后 Bug 频出，低级错误反复出现：
+
+- 空指针没判，生产环境炸了
+- SQL 拼接没转义，差点被注入
+- 函数改了签名，调用方没同步改，编译都没过就合进去了
+- 重复代码复制粘贴了七八份，重构时想死
+
+这些问题，**AI 比人更适合发现**。AI 不会累，不会敷衍，不会"这行代码一看就没问题"。
+
+所以我做了 `commit-ai-guardian`（简称 `cag`）：**每次 git commit 前，自动让 AI 审查代码，有问题直接阻断提交**。
+
+---
+
+## 02 它怎么工作
+
+安装只要一行：
+
+```bash
+uv tool install commit-ai-guardian
+```
+
+进入你的 Git 仓库，初始化：
+
+```bash
+cag install
+```
+
+配置 API Key（支持 OpenAI、MiniMax、DeepSeek、Kimi 等）：
+
+```bash
+cag configure
+```
+
+然后正常写代码、git add、git commit。在 commit 前，工具会自动：
+
+1. **采集 diff** —— 获取暂存区的代码变更
+2. **调用 AI 审查** —— 把代码 + 审核维度发给大模型
+3. **解析结果** —— AI 返回 JSON 格式的问题列表
+4. **阻断或放行** —— 有问题就阻断 commit，没问题直接通过
+
+```
+$ git commit -m "feat: add login"
+
+🔍 AI 代码审核报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌─ src/auth.ts ──────────────────────────────┐
+│  有警告                                       │
+│                                               │
+│  ⚠️  警告  🔒 安全  src/auth.ts:45           │
+│       >> SQL 拼接存在注入风险                 │
+│       💡 使用参数化查询：                     │
+│          db.query("SELECT * FROM users WHERE  │
+│          id = ?", [userId])                   │
+│       📍  const sql = `SELECT * FROM users   │
+│          WHERE id = ${req.params.id}`         │
+└──────────────────────────────────────────────┘
+
+❌ 审核未通过
+1 个文件存在问题，请修复后重试
+```
+
+修复后重新 commit，通过了：
+
+```
+✅ 审核通过
+所有文件符合代码质量标准
+```
+
+---
+
+## 03 核心能力
+
+### 🔍 5 大审核维度
+
+| 维度 | 检查内容 |
+|------|----------|
+| Bug 检测 | 逻辑错误、边界条件、资源泄漏、并发问题 |
+| 代码风格 | 命名规范、代码格式、注释质量、代码组织 |
+| 性能问题 | 算法复杂度、内存泄漏、不必要的计算 |
+| 最佳实践 | 设计模式、代码复用、错误处理、日志规范 |
+| 文档完整 | 函数文档、参数说明、复杂逻辑注释 |
+
+### 📝 自定义案例系统
+
+每个团队的规范不同。你可以在 `.ai-review/cases/` 下放 Markdown 案例文件，AI 会参考这些案例来审核：
+
+```yaml
+---
+title: "SQL 注入防护规范"
+category: "安全"
+severity: "error"
+---
+
+## 场景描述
+用户输入直接拼接到 SQL 查询中...
+
+## 正确做法
+使用参数化查询...
+
+## 错误示例
+```python
+cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+```
+```
+
+案例按编程语言分类，支持 JS/TS、Java、Python、Vue 等。
+
+### ⚡ 缓存机制
+
+同一个文件的相同内容不会重复审核，命中缓存直接跳过，省时间省钱。
+
+### 🔧 灵活配置
+
+- **severity_threshold**：设置阻断阈值（info/warning/error）
+- **diff_mode**：审核完整文件或只审变更
+- **json_fix_history_mode**：JSON 修复 AI 的上下文策略
+- **case_format**：案例注入格式（default/compact/minimal）
+
+---
+
+## 04 技术亮点
+
+### 四层容错，JSON 解析不死
+
+AI 返回的 JSON 经常有问题：引号没转义、括号没闭合、字段缺失、类型错误……工具内置了四层容错：
+
+1. **本地修复** —— 多种策略提取 JSON（过滤 think 标签、代码块匹配、括号补全）
+2. **AI 修复** —— 本地修不好时，调用专门的 JSON 修复 AI，带完整对话历史
+3. **Schema 校验** —— 校验字段名、类型、必填项
+4. **兜底通过** —— 所有修复都失败时，记录日志但不阻断提交（避免卡死）
+
+### 两级配置
+
+全局配置 `~/.commit-ai-guardian/config.yaml` + 项目配置 `.ai-review/config.yaml`，项目配置覆盖全局。方便不同项目用不同模型、不同规则。
+
+---
+
+## 05 适合谁用
+
+- **小团队** —— 没有专人做 CR，AI 替代 80% 的审查工作
+- **大团队** —— CR 流于形式，AI 做第一道把关，人审更有针对性
+- **个人开发者** —— 提交前自检，避免低级错误
+- **开源项目** —— 保证贡献代码的质量底线
+
+---
+
+## 06 安装使用
+
+```bash
+# 安装
+uv tool install commit-ai-guardian
+
+# 进入项目，初始化
+cd your-project
+cag install
+
+# 配置 API Key
+cag configure
+
+# 完成！以后每次 git commit 自动审查
+```
+
+项目地址：[github.com/tingkl/ai-review](https://github.com/tingkl/ai-review)
+
+PyPI：[pypi.org/project/commit-ai-guardian](https://pypi.org/project/commit-ai-guardian)
+
+---
+
+## 07 写在最后
+
+这个工具不是替代人工 CR，而是**把低级、重复的问题交给 AI，让人去关注架构、业务逻辑、设计决策**。
+
+用完你会发现：AI 比同事更仔细，而且不会嫌你代码写得烂。