内容
# GitReins
**Git 原生智能代理协同工具 — 静态防护 + AI 辅助代码评估**
[](https://github.com/totalwindupflightsystems/gitreins/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
[](https://pypi.org/project/gitreins/)
GitReins 作为一个质量保障工具，运行在您的 Git 仓库中。它提供了 MCP 工具用于任务生命周期管理，一个智能评估器用于根据任务定义评估代码完整性，以及确保代码质量的 Git Hook。
> ✅ **v0.10.2** — LSP 诊断（14 种语言），静态分析（9 种工具），提交审计与 CVE 评分，DeepSeek 提示缓存，大型仓库强化，1088 个测试通过。
---
## 快速开始
```bash
pip install gitreins
cd /path/to/your-project
gitreins install # 创建 .gitreins/config.yaml 和 pre-commit Hook
gitreins init # 智能初始化 — 检测语言、大小、优化配置
```
## 工作原理
1. **创建任务** — 通过 CLI 或 MCP 工具定义任务标准
2. **与 AI 代理协作** — 使用 Claude、Hermes、Codex 或 Pi 进行代码生成
3. **完成任务** — `gitreins task complete <id>` 触发自动评估
4. **第一层：静态防护** — 机密检查、构建、代码检查、测试（可配置）
5. **第二层：智能评估器** — LLM 循环读取文件、运行测试、按标准给出通过/失败结果
6. **保存评估结果** — 存储在 `.gitreins/history/` 中，可通过 `gitreins report` 浏览
7. **通过质量保障提交** — pre-commit Hook 运行防护检查，检查失败则阻止提交
## 命令
```
gitreins install # 安装 Hook 和配置
gitreins init # 智能初始化（语言、大小、优化配置）
gitreins guard # 运行第一层静态检查
gitreins report [-n N] [--interactive] # 浏览评估历史
gitreins task create <id> <title> [criteria...] [--depends-on ...]
gitreins task start <id>
gitreins task complete <id> [--force]
gitreins task list [--status pending|in_progress|complete]
gitreins task delete <id>
gitreins judge <id> # 评估任务
gitreins commit <message> # 带防护检查提交
gitreins mcp-server # 运行 MCP 标准输入/输出服务器（用于 AI 代理）
```
---
## 测试模式：`full` vs `diff`
GitReins 支持两种测试模式，取决于 `.gitreins/config.yaml` 中的 `test_mode` 配置。
### `test_mode: "full"` （新项目默认）
每次提交都运行整个测试套件。安全且彻底。
**适合：**
- 新项目，测试套件小且运行快
- 所有测试都可靠通过的项目
- 需要每次提交都最大限度保证安全的项目
**权衡：** 对大型项目较慢。未更改代码中的现有失败会阻塞无关提交。
```yaml
guards:
test_mode: "full"
```
### `test_mode: "diff"` （成熟项目推荐）
仅对实际更改的包运行测试。使用 basename 映射：
| 更改的文件 | 运行的测试 |
|---|---|
| `engine/guard_manager.py` | `tests/test_guard_manager.py` |
| `gitreins/cli.py` | `tests/test_cli.py` |
| `gitreins_mcp/server.py` | `tests/test_mcp_server.py` |
**适合：**
- 包数量 ≥ 5，整个测试套件运行慢的项目
- 存在测试失败的成熟项目（未更改代码）
- 需要对实际更改的代码提供快速反馈的项目
**安全网 — 在以下情况下，diff 模式会回退到完整套件：**
- `pyproject.toml`、` .gitreins/config.yaml`、`Makefile` 或 `setup.cfg` 更改
- 测试文件本身更改（始终包含及其源映射的兄弟文件）
- 更改的文件未映射到任何已知测试文件（未知文件 = 安全）
- 没有暂存文件
- 测试命令不是 `pytest` （自定义运行器无法缩小范围）
**权衡：** 跨包更改的安全性较低。配置更改始终触发完整套件。
```yaml
guards:
test_mode: "diff"
```
### 选择哪种模式？
| 项目状态 | 推荐模式 |
|---|---|
| 全新，< 5 个包 | `full` |
| 成熟，≥ 5 个包，测试通过 | `diff` |
| 成熟，存在测试失败 | `diff` |
| 跨包重构 | `full`（临时）|
| CI / PR 检查 | `full`（安全优先于速度）|
### 输出示例
**完整模式：**
```
第一层防护：通过 （测试模式：完整）
✓ 机密检查 — 清洁
✓ 代码检查 — 通过
✓ 测试 — 通过
```
**差异模式（有针对性）：**
```
第一层防护：通过 （测试模式：差异，3 个测试文件）
✓ 机密检查 — 清洁
✓ 测试 — 通过
```
**差异模式（安全触发 — 完整套件）：**
```
第一层防护：通过 （测试模式：差异，完整套件 — 安全触发）
✓ 机密检查 — 清洁
✓ 测试 — 通过
```
---
## 评估历史
每次 `gitreins task complete` 和 `gitreins judge` 都会将评估结果保存到 `.gitreins/history/`。可在 `.gitreins/config.yaml` 中配置：
```yaml
history:
enabled: true # false = 不保存评估结果
storage: "git" # "git" = 自动提交到 gitreins 分支
# "filesystem" = 仅写入文件，不提交到 Git
max_verdicts: 1000 # 自动清理旧条目
```
浏览历史：
```bash
gitreins report # 最近 10 次评估
gitreins report -n 20 # 最近 20 次
gitreins report --interactive # TUI 界面，支持箭头键导航（需要 textual）
```
## 任务依赖
任务可以依赖于其他任务。在依赖任务通过之前，评估会被阻塞：
```bash
gitreins task create build "项目构建" \
"CGO_ENABLED=0 go build ./cmd/server exits 0"
gitreins task create api-crud "CRUD 端点" --depends-on build \
"POST /api/users 创建用户" \
"GET /api/users 列出用户"
gitreins task complete api-crud
# → "无法完成 'api-crud' — 依赖于：build"
gitreins task complete build # 优先完成依赖任务
gitreins task complete api-crud # 现在可以完成
# 或强制跳过依赖检查：
gitreins task complete api-crud --force
```
## 配置
完整的 `.gitreins/config.yaml` 参考：
```yaml
# ── 全局默认配置 ──────────────────────────────────
defaults:
model: deepseek-v4-flash
max_iterations: 100
check_for_updates: true
# ── 第一层防护 ────────────────────────────────────
guards:
secrets: true
lint: true
tests: true
test_mode: "full" # "full" 或 "diff"
test_command: "pytest -x --tb=short"
# Go 项目（通过 go.mod 自动检测）：
go:
build: true
lint: true
tests: true
# ── 第二层评估器能力 ────────────────────────────
evaluator:
max_iterations: 25 # LLM 推理轮次
max_time: "5m" # 墙上时钟上限
max_input_tokens: "200k"
max_output_tokens: "50k"
tool_calls_weight: 0.1 # 工具调用成本 0.1 轮次
# ── 评估历史 ──────────────────────────────────
history:
enabled: true
storage: "git"
max_verdicts: 1000
```
---
## 技术栈
- **语言：** Python 3.10+
- **依赖：** mcp, pyyaml, requests, packaging （4 个包）
- **MCP 传输：** stdio （26 种工具）
- **配置：** `.gitreins/` 目录下的 YAML
- **评估器默认模型：** DeepSeek V4 Flash（~$0.01/eval）
- **测试套件：** ~1088 个测试，分布在 28 个测试文件中（与 pytest-xdist 并行化）
## 架构与文档
| 文档 | 内容 |
|---|---|
| [完整架构](docs/architecture.md) | 系统设计与数据流 |
| [组件地图](docs/component-map.md) | 模块清单，含路径和行数 |
| [智能评估器设计](docs/evaluator-loop.md) | 评估器循环工作原理 |
## 许可证
MIT
