Skip to content

Commit 4e21feb

Browse files
Gil2015Gil2015
committed
feat: 正式版本 v1.0.5 发布
1 parent 7a5b8dc commit 4e21feb

63 files changed

Lines changed: 4741 additions & 929 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 224 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,228 @@
1-
# code-gate
2-
3-
AI 助力的提交时代码 Review 工具，支持本地 Ollama 或 DeepSeek API，审查 `git commit` 的 `staged diff`，并以 GitHub Diff 风格在本地页面展示结果。
4-
5-
## 安装
6-
- `npm i -D code-gate`
7-
8-
## 初始化与集成
9-
- 推荐使用 `init` 命令，选择初始化方式并自动生成配置文件：
10-
- 原生 Git Hooks：`npx code-gate init -m git`
11-
- Husky：`npx code-gate init -m husky`
12-
- simple-git-hooks：`npx code-gate init -m simple`
13-
- 跳过配置文件生成：`npx code-gate init --no-config`
14-
- 仍支持旧方式：
15-
- 原生 Git Hooks 快速安装：`npx code-gate setup`
16-
- 该命令会创建 `.githooks/pre-commit` 并设置 `core.hooksPath`
17-
18-
## 手动初始化（不覆盖现有钩子）
19-
- Husky：
20-
- 编辑 `.husky/pre-commit`，在原有内容后追加一行：
21-
- `npx code-gate hook`
22-
- 确认 `git config core.hooksPath` 输出 `.husky`
23-
- 原生 Git Hooks：
24-
- 在项目根创建 `.githooks/pre-commit`，内容示例：
25-
- `#!/usr/bin/env sh`
26-
- `npx code-gate hook`
27-
- 设置 `core.hooksPath`：
28-
- `git config core.hooksPath .githooks`
29-
- 配置文件生成：
30-
- 在项目根新建 `code-gate.config.json`（可从下文示例复制并按需调整）
31-
- 如使用 DeepSeek，请在环境变量设置 `DEEPSEEK_API_KEY`
32-
33-
## 命令
34-
- `npx code-gate init` 交互式初始化（可选择 git/husky/simple，并生成配置文件）
35-
- `npx code-gate setup` 快速安装原生 Git Hook
36-
- `npx code-gate hook` 在 Hook 中执行交互式 Review
37-
38-
## 本地开发（link 调试）
39-
- 在 `code-gate` 仓库：
40-
- `npm install`
41-
- `npm run build:watch`
42-
- `npm link`
43-
- 在目标项目：
44-
- `npm link code-gate`
45-
- `npx code-gate init -m git`（或 `husky`/`simple`）
46-
- `git add` + `git commit` 时触发审查流程
47-
48-
## 配置文件
49-
- 推荐使用 `.codegate.js`（支持注释与更灵活的写法），兼容旧的 `code-gate.config.json/.yaml`、`.code-gaterc.{json,yaml}`。
50-
- 示例（`.codegate.js`）：
51-
```js
52-
// provider: 选择使用的 AI 审查引擎，可选值: 'ollama' | 'deepseek'
53-
// review: 审查相关设置
54-
// - enabled: 是否启用审查
55-
// - provider: 覆盖顶层 provider，支持按需切换，可选值: 'ollama' | 'deepseek'
56-
// - mode: 审查展示模式，可选值: 'aggregate'（整合输出）| 'per_file'（按文件 Tab 展示）
57-
// ollama: 本地 Ollama 设置
58-
// - baseURL: Ollama 服务地址，默认 'http://localhost:11434'
59-
// - model: 模型名称，例如 'qwen3:8b'、'deepseek-r1:14b'
60-
// deepseek: DeepSeek 云端设置
61-
// - baseURL: API 地址，默认 'https://api.deepseek.com'
62-
// - apiKeyEnv: 存放密钥的环境变量名，默认 'DEEPSEEK_API_KEY'
63-
// - model: 模型名称，默认 'deepseek-chat'
64-
// fileTypes: 需要审查的文件类型扩展名列表
65-
// scope: 审查范围，可选值: 'staged' | 'allChanged' | { include?: string[], exclude?: string[] }
66-
// ui: 页面与交互设置
67-
// - openBrowser: 是否自动打开浏览器
68-
// - theme: 主题，目前仅 'github'
69-
// - port: 预览服务端口
70-
// limits: 限制项
71-
// - maxDiffLines: 最大 diff 行数
72-
// - maxFiles: 最大审查文件数
73-
// rules: 审查关注点，可选值: 'security' | 'performance' | 'style' | 'tests'
74-
// prompt: 通用提示词
75-
// output: 输出目录配置
76-
// - dir: 本地输出目录
1+
<div align="center">
2+
<img src="assets/logo_text.png" alt="Code Gate Logo" width="120" />
3+
</div>
4+
5+
[English](./README.md) | [简体中文](./README_ZH.md)
6+
7+
# Code Gate
8+
9+
**Your Lightweight Local AI Code Review Assistant**
10+
11+
Code Gate is an intelligent code review tool seamlessly integrated into your Git workflow. When you run `git commit`, it automatically analyzes staged code changes, utilizing local LLMs (Ollama) or cloud AI services to provide instant feedback on code quality, security suggestions, and optimization plans.
12+
13+
<div align="left">
14+
<img src="assets/review.png" alt="Code Gate example" width="100%" />
15+
</div>
16+
17+
## ✨ Features
18+
19+
- **🔒 Privacy First**: Native support for Ollama local models.
20+
- **☁️ Multi-Model Support**: Seamlessly integrates with DeepSeek, OpenAI, Anthropic, Aliyun Qwen, Doubao, and more.
21+
- **🌍 Multi-Language**: Built-in support for English, Chinese (Simplified & Traditional), Japanese, Korean, German, and French.
22+
- **⚡️ High Performance**: Intelligent concurrent processing for faster reviews across multiple files.
23+
- **🛠️ Highly Customizable**: Custom prompts, file filtering rules, and review strategies.
24+
- **📊 Visual Reports**: Generates intuitive HTML review reports with clear diffs and AI suggestions.
25+
- **📜 Review Logs**: Automatically archives review history for easy reference and tracking.
26+
27+
## 🚀 Quick Start
28+
29+
### 1. Installation
30+
31+
Install `code-gate` as a development dependency:
32+
33+
```bash
34+
npm i -D code-gate
35+
```
36+
37+
### 2. Initialization
38+
39+
We provide a one-click initialization command to configure Git Hooks.
40+
41+
**Automatic Init (Recommended)**
42+
43+
```bash
44+
# Interactive selection for Git Hooks or Husky
45+
npx code-gate init
46+
```
47+
48+
You can also specify arguments if you prefer a specific hook manager:
49+
50+
- **Native Git Hooks**: `npx code-gate init -m git`
51+
- **Husky**: `npx code-gate init -m husky`
52+
53+
> After initialization, you can choose to add the generated config file to `.gitignore`.
54+
55+
### 3. Usage
56+
57+
Just commit your code as usual:
58+
59+
```bash
60+
git add .
61+
git commit -m "feat: new feature"
62+
```
63+
64+
Code Gate intercepts the commit:
65+
1. Analyzes code changes.
66+
<div align="left" style="margin-left: 20px">
67+
<img src="assets/step1.png" width="300" />
68+
</div>
69+
70+
2. Starts a local server and generates a review report.
71+
72+
3. Automatically opens the report in your browser.
73+
74+
4. You choose to **Confirm Commit** or **Cancel** in the terminal.
75+
<div align="left" style="margin-left: 20px">
76+
<img src="assets/step3.png" width="300" />
77+
</div>
78+
79+
---
80+
81+
## ⚙️ Configuration
82+
83+
The `code-gate.config.js` in your project root controls all behaviors.
84+
85+
### Basic Configuration
86+
87+
```javascript
88+
export default {
89+
provider: 'ollama',
90+
providerOptions: {
91+
ollama: {
92+
baseURL: 'http://localhost:11434',
93+
model: 'qwen2.5-coder',
94+
concurrencyFiles: 1
95+
},
96+
deepseek: {
97+
baseURL: 'https://api.deepseek.com',
98+
apiKeyEnv: 'DEEPSEEK_API_KEY',
99+
model: 'deepseek-chat',
100+
concurrencyFiles: 4
101+
}
102+
// openai: { baseURL: 'https://api.openai.com/v1', apiKeyEnv: 'OPENAI_API_KEY', model: 'gpt-4o-mini' },
103+
// anthropic: { baseURL: 'https://api.anthropic.com', apiKeyEnv: 'ANTHROPIC_API_KEY', model: 'claude-3-5-sonnet' },
104+
// azureOpenAI: { endpoint: 'https://your-endpoint.openai.azure.com', apiKeyEnv: 'AZURE_OPENAI_KEY', deployment: 'gpt-4o-mini', apiVersion: '2024-08-01-preview' },
105+
// aliyun: { baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1', apiKeyEnv: 'DASHSCOPE_API_KEY', model: 'qwen-plus' },
106+
// volcengine: { baseURL: 'https://ark.cn-beijing.volces.com/api/v3', apiKeyEnv: 'VOLCENGINE_API_KEY', model: 'doubao-pro-32k' },
107+
// zhipu: { baseURL: 'https://open.bigmodel.cn/api/paas/v4', apiKeyEnv: 'ZHIPU_API_KEY', model: 'glm-4' }
108+
},
109+
language: 'en',
110+
fileTypes: ['ts', 'tsx', 'css'],
111+
ui: {
112+
openBrowser: true,
113+
port: 5175
114+
},
115+
limits: {
116+
maxDiffLines: 10000,
117+
maxFiles: 100
118+
},
119+
prompt: 'as a senior code reviewer, please review the code changes and provide feedback on security, performance, code style, and test coverage. Highlight any issues or areas for improvement, and offer concrete suggestions with code examples if possible.',
120+
output: {
121+
dir: '.review-logs'
122+
},
123+
}
124+
```
125+
126+
### API Key Configuration
127+
128+
Choose the appropriate configuration scheme based on your project needs. Taking deepseek as an example.
129+
For security, avoid hardcoding API Keys in the config file.
130+
131+
**Option A: Config File**
132+
133+
Set in `.code-gate.js`:
134+
135+
```javascript
77136
export default {
78-
provider: 'deepseek',
79-
review: { enabled: true, mode: 'aggregate' },
80-
deepseek: { baseURL: 'https://api.deepseek.com', apiKeyEnv: 'DEEPSEEK_API_KEY', model: 'deepseek-chat' },
81-
ollama: { baseURL: 'http://localhost:11434', model: 'qwen3:8b' },
82-
fileTypes: ['ts', 'tsx', 'js', 'jsx', 'json', 'md', 'py', 'go', 'rs'],
83-
scope: 'staged',
84-
ui: { openBrowser: true, theme: 'github', port: 5175 },
85-
limits: { maxDiffLines: 10000, maxFiles: 100 },
86-
rules: { focus: ['security', 'performance', 'style', 'tests'] },
87-
prompt: '作为资深代码审查工程师，从安全、性能、代码风格与测试覆盖角度审查本次变更，指出问题与改进建议，并给出必要的示例补丁。',
88-
output: { dir: '.code-gate' }
137+
providerOptions: {
138+
deepseek: {
139+
// ...other config
140+
apiKey: 'your-deepseek-api-key'
141+
}
142+
}
89143
}
90144
```
91145

92-
## 使用流程
93-
- 运行 `git commit` 时会询问是否进行 Review：
94-
- 选择否：正常提交。
95-
- 选择是：抓取 `staged diff` 调用 AI 审查，生成本地页面并打印预览 URL，再询问是否继续提交。
96-
- 非交互环境会自动跳过。
97-
- 如需在非交互环境强制执行，可在 `.husky/pre-commit` 中使用：`npx code-gate hook -f`
98-
- 页面顶部会显示 AI 状态（是否参与、Provider、Model、错误信息）
99-
- 支持按文件 Tab 展示：在配置中设置 `"review": { "mode": "per_file" }`，每个文件一个 Tab，Tabs 超出视野时横向滚动，每个文件顶部展示该文件的审查内容
100-
101-
## 故障排查
102-
- 页面只有 diff、没有 AI 审查内容：
103-
- DeepSeek：确保设置了环境变量 `DEEPSEEK_API_KEY`，并且 `provider` 为 `deepseek`；可在 shell 中 `export DEEPSEEK_API_KEY="your_key"`
104-
- Ollama：确保本地 Ollama 正在运行（默认 `http://localhost:11434`），并且模型已安装；例如 `ollama list` 查看，`ollama pull qwen2.5-coder`
105-
- 可在 `code-gate.config.json` 中切换 `provider`，调整 `prompt` 与 `ui.port`
106-
- 出错时页面顶部会显示原因与解决建议
107-
108-
## DeepSeek 集成
109-
- 使用 OpenAI 兼容接口 `https://api.deepseek.com`，需在环境变量设置密钥：`DEEPSEEK_API_KEY`。
110-
- 参考文档：https://api-docs.deepseek.com/
111-
112-
## Ollama 集成
113-
- 通过本地 HTTP 接口调用，不内置安装；需用户自行安装与启动 Ollama。
114-
- 默认地址：`http://localhost:11434`
115-
116-
## 注意
117-
- 不会将密钥写入仓库；配置建议走环境变量。
118-
- 大 Diff 会消耗模型 token，可通过 `limits` 控制。
146+
**Option B: Git Hook Injection**
147+
148+
Export temporarily in `.githooks/pre-commit` or `.husky/pre-commit`:
149+
150+
```bash
151+
#!/bin/sh
152+
export DEEPSEEK_API_KEY=[your-deepseek-api-key]
153+
./node_modules/.bin/code-gate-hook
154+
```
155+
156+
**Option C: Environment Variables (Recommended)**
157+
158+
Set in your `.env` file or system environment:
159+
160+
```bash
161+
export DEEPSEEK_API_KEY=[your-deepseek-api-key]
162+
```
163+
164+
## 📖 Configuration Details
165+
166+
| Parameter | Type | Default | Description |
167+
| :--- | :--- | :--- | :--- |
168+
| `provider` | `string` | `'ollama'` | AI Provider. Supports `ollama`, `deepseek`, `openai`, `anthropic`, `aliyun`, `volcengine`, `zhipu`, etc. |
169+
| `providerOptions` | `object` | `{}` | Specific configurations for each Provider (see table below) |
170+
| `fileTypes` | `string[]` | `[]` | List of file extensions to review (whitelist). Reviews all files if empty or undefined. |
171+
| `exclude` | `string[]` | `['**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml']` | List of files or directories to ignore (blacklist), supports glob patterns (e.g., `node_modules/**`). Higher priority than `fileTypes`. |
172+
| `ui.openBrowser` | `boolean` | `true` | Auto-open browser for report preview |
173+
| `ui.port` | `number` | `5175` | Preview server port |
174+
| `limits.maxDiffLines` | `number` | `10000` | Max diff lines per review. Exceeding may cause incomplete review or excessive token usage. |
175+
| `limits.maxFiles` | `number` | `100` | Max number of files to review |
176+
| `reviewMode` | `string` | `'files'` | Review Mode: `'summary'` (summary only), `'files'` (file details only), `'both'` (both) |
177+
| `language` | `string` | `'en'` | UI & Prompt Language. Options: `'en'`, `'zh-CN'`, `'zh-TW'`, `'ja'`, `'ko'`, `'de'`, `'fr'` |
178+
| `prompt` | `string` | `...` | Universal system prompt sent to AI |
179+
| `output.dir` | `string` | `'.review-logs'` | Output directory for local reports and static assets |
180+
181+
### providerOptions Configuration
182+
183+
Each Provider supports the following fields, with `request` option for timeout and retry control.
184+
185+
**Key Parameters:**
186+
- `baseURL`: API base URL (e.g., `https://api.deepseek.com` or `http://localhost:11434`)
187+
- `apiKey`: API Key (specified directly in config, not recommended for committing)
188+
- `apiKeyEnv`: Environment variable name storing the API Key (Recommended, e.g., `DEEPSEEK_API_KEY`)
189+
- `model`: Model name to use (e.g., `deepseek-chat`, `qwen2.5-coder`)
190+
- `concurrencyFiles`: Number of concurrent file reviews (Recommended: Cloud API 4-8, Local Model 1)
191+
- `request`: Advanced request configuration (see "Advanced Configuration" below)
192+
193+
| Provider | Configurable Parameters |
194+
| :--- | :--- |
195+
| **deepseek** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `concurrencyFiles`, `request` |
196+
| **ollama** | `baseURL`, `model`, `concurrencyFiles`, `request` |
197+
| **openai** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `request` |
198+
| **anthropic** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `request` |
199+
| **aliyun** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `request` |
200+
| **volcengine** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `request` |
201+
| **zhipu** | `baseURL`, `apiKey`, `apiKeyEnv`, `model`, `request` |
202+
| **azureOpenAI** | `endpoint`, `apiKey`, `apiKeyEnv`, `deployment`, `apiVersion`, `request` |
203+
204+
#### Advanced Configuration (request)
205+
206+
Configure in `providerOptions.<provider>.request` to control request behavior:
207+
208+
| Parameter | Type | Default | Description |
209+
| :--- | :--- | :--- | :--- |
210+
| `timeout` | `number` | `undefined` | Request timeout (ms). Recommended to set higher for Ollama (e.g., 15000+) |
211+
| `retries` | `number` | `0` | Number of retries on request failure |
212+
| `backoffMs` | `number` | `300` | Retry interval (ms) |
213+
214+
> **Note**: `concurrencyFiles` controls the number of concurrent file reviews (Default: DeepSeek=4, Ollama=1, Others=4).
215+
216+
## ❓ FAQ
217+
218+
**Q: Report shows diffs but no AI suggestions?**
219+
- Check `provider` configuration.
220+
- If using Ollama, ensure local service is running (`ollama serve`) and model is pulled (`ollama pull qwen2.5-coder`).
221+
- If using Cloud API, check API Key validity and network connection.
222+
223+
**Q: How to skip review in CI/CD?**
224+
Code Gate detects non-interactive environments and skips automatically. To force skip, use `git commit --no-verify`.
225+
226+
## 📄 License
227+
228+
MIT

0 commit comments

Comments
 (0)