Skip to content

jackhoward24/git-test-doc

BranchesTags

Repository files navigation

Git 提测文档生成工具

根据 Git commit 自动生成结构化的提测文档，借助 AI 分析代码变更，输出 Markdown 格式文档。

✨ 功能特性

  • 🔍 自动获取 Git commit 的完整信息和 diff 内容
  • 🤖 调用 AI 分析代码变更，智能提取功能点
  • 📝 生成结构化提测文档（Markdown 格式）
  • 🎯 自动评估影响域和风险等级
  • 💡 智能生成测试建议（含具体验证示例，以业务场景和用户操作为主）
  • 🧠 AI 代码分类：智能区分业务变更和代码优化（Sonar/NPE 修复等）
  • 🔄 多 Agent 协作：开发专家 + 测试专家双 Agent 模式
  • 🔁 Reflexion 机制：自我反思，迭代优化文档质量
  • 👥 交互式 Review：支持用户审阅和修改生成的文档
  • 🧹 智能上下文过滤：自动过滤测试文件、import 语句等无关内容，降低 AI 处理成本
  • 🔗 飞书工作项关联：自动从 commit message 提取飞书工作项链接
  • 📋 配置说明 JSON 示例：配置变更自动生成 JSON 示例展示新旧结构对比
  • 🔬 代码元素具体化：技术实现描述包含具体的类名、函数名、常量名

📦 安装

Python 3.10-3.12（推荐，安装最简单）

# 克隆项目
git clone <repository-url>
cd git-test-doc

# 一键安装
pip install -e .

Python 3.13+

由于 camel-ai 依赖的 tiktoken 版本限制，Python 3.13+ 需要分步安装：

# 克隆项目
git clone <repository-url>
cd git-test-doc

# 1. 先安装兼容 Python 3.13 的 tiktoken
pip install tiktoken>=0.8.0

# 2. 安装项目（跳过依赖检查）
pip install -e . --no-deps

# 3. 安装其他依赖
pip install openai typer pydantic-settings python-dotenv openpyxl javalang

# 4. 安装 camel-ai（跳过其 tiktoken 版本限制）
pip install camel-ai --no-deps

说明：camel-ai 当前限制 tiktoken<0.8，但 tiktoken 0.7.x 没有 Python 3.13 预编译包，需要 Rust 编译器。上述步骤通过先安装 tiktoken>=0.8.0 来绕过此问题。

卸载

# 卸载 git-test-doc
pip uninstall git-test-doc

# 如需同时卸载依赖（可选）
pip uninstall git-test-doc camel-ai tiktoken openai typer pydantic-settings python-dotenv openpyxl javalang

⚙️ 配置

方式一：环境变量

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-xxx"

# Windows CMD
set OPENAI_API_KEY=sk-xxx

# Linux/macOS
export OPENAI_API_KEY="sk-xxx"

方式二：.env 文件

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=qwen3-coder-plus

配置项说明

基础配置

配置项 环境变量 默认值 说明
API Key OPENAI_API_KEY （必需） OpenAI API 密钥
Base URL OPENAI_BASE_URL https://api.openai.com/v1 API 地址
Model OPENAI_MODEL qwen3-coder-plus AI 模型名称
超时时间 TIMEOUT 60 AI 调用超时时间（秒）

Multi-Agent 配置

配置项 环境变量 默认值 说明
开发专家模型 DEVELOPER_MODEL qwen3-coder-plus 开发专家 Agent 使用的模型
测试专家模型 TESTER_MODEL qwen3-coder-plus 测试专家 Agent 使用的模型

Reflexion 配置

配置项 环境变量 默认值 说明
启用 Reflexion ENABLE_REFLEXION true 是否启用自我反思机制
最大循环次数 REFLEXION_MAX_LOOPS 3 Reflexion 最大循环次数
质量阈值 REFLEXION_THRESHOLD 8.5 质量评分阈值（0-10 分）

上下文工程配置

配置项 环境变量 默认值 说明
启用上下文压缩 ENABLE_CONTEXT_COMPRESSION true 是否启用上下文压缩
最大 Diff 长度 MAX_DIFF_LENGTH 30000 最大 diff 长度（字符数）
单文件最大长度 MAX_FILE_LENGTH 6000 单个文件最大长度（字符数）
启用关联文件 ENABLE_RELATED_FILES true 是否获取关联文件
最大关联文件数 MAX_RELATED_FILES 5 最大关联文件数量
关联文件最大长度 MAX_RELATED_FILE_LENGTH 3000 单个关联文件最大长度（字符数）
上下文行数 CONTEXT_LINES 20 变更位置前后各取多少行
调用链深度 RELATED_FILE_DEPTH 1 关联文件调用链深度（1=直接，2=间接）

Memory 配置（Camel-AI 记忆管理）

配置项 环境变量 默认值 说明
启用 Memory ENABLE_MEMORY true 是否启用 Camel Memory 功能管理上下文
Token 上限 MEMORY_TOKEN_LIMIT 16000 Memory token 上限，超过会自动截断
消息窗口大小 MEMORY_MESSAGE_WINDOW_SIZE 10 保留最近的 N 条消息

AI 代码分类配置

配置项 环境变量 默认值 说明
启用 AI 分类 ENABLE_AI_CLASSIFICATION true 是否启用 AI 代码分类
分类模型 CLASSIFICATION_MODEL qwen3-coder-plus 代码分类使用的模型
置信度阈值 CLASSIFICATION_CONFIDENCE_THRESHOLD 0.5 AI 分类置信度阈值（低于此值回退到规则匹配）

交互与重试配置

配置项 环境变量 默认值 说明
启用交互 Review ENABLE_INTERACTIVE_REVIEW true 是否启用交互式审阅
最大重试次数 MAX_RETRIES 3 API 调用最大重试次数
重试延迟 RETRY_DELAY 2 重试延迟时间（秒）

日志配置

配置项 环境变量 默认值 说明
日志级别 LOG_LEVEL INFO 日志输出级别
记录 Agent 交互 LOG_AGENT_INTERACTIONS true 是否记录 Agent 交互日志
保存到文件 LOG_TO_FILE true 是否将日志保存到文件
日志目录 LOG_DIR .logs 日志文件目录

🚀 使用方法

# 进入你的 Git 项目目录
cd /path/to/your/git/repo

# 基本用法 - 生成指定 commit 的提测文档
git-test-doc <commit_id>

# 指定输出目录
git-test-doc <commit_id> -o ./docs/

# 指定 AI 模型
git-test-doc <commit_id> -m gpt-4o

# 生成后自动打开文件
git-test-doc <commit_id> --open

# 查看帮助
git-test-doc --help

# 查看版本
git-test-doc --version

使用示例

$ git-test-doc a1b2c3d4

🔍 正在验证 Git 仓库...
✅ 正在分析 commit: a1b2c3d4
📁 变更文件: 5 个
📝 提交信息: feat: 新增用户登录功能
🤖 正在生成提测文档...
╭──────────────────── 生成完成 ────────────────────╮
│ ✅ 文档生成成功！                                 │
│                                                   │
│ 📄 文件名: 提测文档_a1b2c3d4_20260108_1430.md    │
│ 📁 保存路径: D:\projects\docs\提测文档_xxx.md    │
│ 🌿 分支: feature/login                           │
│ 🔖 Commit: a1b2c3d4                              │
╰───────────────────────────────────────────────────╯

📄 输出文档结构

生成的提测文档包含以下章节：

# 提测文档

## 提测需求
## 提测功能点
## 项目相关配置说明
## 代码审核通过截图
## 提测分支
## 影响域分析
## 技术实现
## 测试建议
## 提测时间
## 附录

🛠️ 开发

项目结构

git-test-doc/
├── pyproject.toml           # 项目配置
├── README.md                # 说明文档
├── src/
│   └── git_test_doc/
│       ├── __init__.py      # 包初始化 + 异常类
│       ├── cli.py           # CLI 入口
│       ├── git_utils.py     # Git 操作封装
│       ├── config.py        # 配置管理
│       ├── renderer.py      # Markdown 渲染
│       ├── agents/          # Multi-Agent 模块
│       │   ├── __init__.py
│       │   ├── base_agent.py      # Agent 基类
│       │   ├── developer_agent.py # 开发专家 Agent
│       │   ├── orchestrator.py    # Agent 编排器
│       │   └── reflexion.py       # 自我反思机制
│       ├── context/         # 上下文处理模块
│       │   ├── __init__.py
│       │   ├── call_analyzer.py       # 调用链分析
│       │   ├── change_classifier.py   # 代码变更分类
│       │   ├── context_builder.py     # 上下文构建
│       │   ├── context_compressor.py  # 上下文压缩
│       │   ├── diff_parser.py         # Diff 解析
│       │   ├── git_context.py         # Git 上下文获取
│       │   ├── git_filter.py          # 文件/内容过滤
│       │   └── git_processor.py       # Git 处理器
│       ├── interactive/     # 交互式 Review 模块
│       │   ├── __init__.py
│       │   ├── modifier.py        # 文档修改器
│       │   └── reviewer.py        # 交互式审阅器
│       └── prompts/         # Prompt 模板
│           ├── __init__.py
│           ├── classification_prompt.py  # 代码分类 Prompt
│           └── developer_prompt.py       # 开发专家 Prompt
├── tests/
│   ├── test_call_analyzer.py      # 调用链分析测试
│   ├── test_change_classifier.py  # 代码分类测试
│   ├── test_diff_parser.py        # Diff 解析测试
│   ├── test_git_filter.py         # 过滤模块测试
│   ├── test_git_processor.py      # Git 处理器测试
│   ├── test_git_utils.py          # Git 工具测试
│   └── test_renderer.py           # 渲染模块测试

运行测试

# 安装测试依赖
pip install pytest

# 运行所有测试
pytest tests/ -v

本地开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v --cov=git_test_doc

📋 依赖

  • Python >= 3.10
  • openai >= 1.0.0
  • typer >= 0.9.0
  • pydantic-settings >= 2.0.0
  • python-dotenv >= 1.0.0
  • camel-ai >= 0.2.0 （Multi-Agent 框架）
  • openpyxl >= 3.1.0 （Excel 导出支持）
  • javalang >= 0.13.0 （Java 代码解析）

🧹 智能上下文过滤

为减少 AI 处理成本并提高分析精准度，工具会自动过滤以下无关内容：

过滤的文件类型

类型 匹配模式
测试文件 *Test.java, test_*.py, *.test.js, *.spec.js, **/test/**, **/tests/**
构建文件 pom.xml, package.json, build.gradle, requirements.txt, go.mod 等
文档文件 *.md, README*, LICENSE, .gitignore
Office 文档 *.xlsx, *.docx, *.pptx

过滤的代码内容

  • Import 语句：Java import、Python from...import、ES6 import、Go package、Rust use、C++ #include 等
  • 过滤在以下场景自动生效：
    • Diff 内容压缩前
    • 变更上下文（前后 20 行代码）提取时

🔗 飞书工作项关联

工具会自动从 commit message 中提取飞书工作项链接：

feat(订单模块): 新增订单取消功能

关联飞书工作项：https://project.feishu.cn/blsp/task/detail/123456

提取的链接会自动填充到生成文档的附录章节，格式为：

## 附录
关联飞书工作项：https://project.feishu.cn/blsp/task/detail/123456

📋 配置说明 JSON 示例

当代码变更涉及配置文件时，生成的文档会自动包含 JSON 示例展示配置结构变化：

## 项目相关配置说明

配置项 `displayConfig` 结构从 level→effects 映射改为 effect→levels 反向映射：

旧结构：
​```json
{
  "displayConfig": {
    "critical": ["topbar", "strongHint"],
    "serious": ["topbar"]
  }
}

新结构：

{
  "displayConfig": {
    "topbar": ["critical", "serious", "warning"],
    "modelRed": {
      "robot": {"critical": "red", "serious": "orange"}
    }
  }
}



## ⚠️ 注意事项

1. **必须在 Git 仓库中运行**：工具需要读取 Git 信息
2. **需要配置 API Key**：首次使用前请配置 `OPENAI_API_KEY`
3. **Diff 截断**：超过 30000 字符的 diff 会被截断，保留末尾内容，如果不想被截断，需要开启Memory功能
4. **网络要求**：需要能够访问 OpenAI API
5. **上下文过滤**：测试文件和 import 语句会被自动过滤，无需配置

## 📜 License

MIT License

About

根据 Git commit 自动生成结构化的提测文档，借助 AI 分析代码变更，输出 Markdown 格式文档。

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages