智能文档代理
一个多代理人工智能系统，为GitHub存储库自动生成自适应的多级文档。它采用谷歌的Gemini API和三代理架构构建，可根据不同的体验级别生成初级、中级和高级文档。
📺 视频演示
查看系统运行情况：为Express.js生成文档，探索三个级别（初级/中级/高级），并展示黑暗模式功能！
特性
- 多级文档： 生成三个不同的文档级别：
- 初学者： 友好的解释，包括示例和故障排除 - 中级： 架构概述和集成模式 - 高级： 技术深度潜水和贡献指南
- 智能分析： 使用AI代理来：
- 分析代码结构和复杂性 - 收集相关背景和最佳实践 - 为每个级别生成量身定制的文档
- 快速高效：
- 并行代理执行 - 智能存储库遍历（深度受限） - 文件过滤以跳过二进制文件
- 自由奔跑：
- 使用免费的Gemini API层 - 使用GitHub的公共API（60次请求/小时） - 可选的GitHub令牌，用于更高的速率限制
建筑
Frontend (React) → Backend (FastAPI) → Agent Orchestrator
↓
┌───────────────────────┼───────────────────────┐
↓ ↓ ↓
Code Analyzer Context Gatherer Doc Generator
↓ ↓ ↓
└───────────────────────┴───────────────────────┘
↓
GitHub MCP Server多代理系统
- 代码分析器代理： 分析存储库结构，检测框架，计算指标
- 上下文收集器代理： 检索文档标准和最佳实践
- 文档生成器代理： 并行生成三个级别的文档
设计模式
- 编排器模式： 中央协调器管理代理生命周期
- MCP模式： 外部服务抽象为“服务器”以实现灵活性
- 并行执行： 代理1和2同时运行以提高速度
- 错误隔离： 代理故障不会使系统崩溃
快速开始
先决条件
- Python 3.11+
- Node.js 18+
- Gemini API密钥（免费 谷歌AI工作室)
1.克隆和设置
git clone https://github.com/yourusername/github_doc_agent.git
cd github_doc_agent2.获取API密钥
- 访问https://aistudio.google.com/apikey
- 单击“创建API密钥”
- 复制密钥（以开头
AI...)
3.后端设置
cd backend
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
# Create .env file
cp .env.example .env
# Edit .env and add: GEMINI_API_KEY=your_key_here# Run the backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000后端可在http://localhost:8000
4.前端设置
在新终端中：
cd frontend
npm install
npm run dev前端可在http://localhost:5173
5.试试看
- 打开http://localhost:5173
- 输入GitHub存储库URL（例如。，
https://github.com/expressjs/express) - 点击“生成文档”
- 等待30-60秒
- 查看三个级别的文档！
使用示例
网络界面
只需粘贴任何公共GitHub存储库URL：
https://github.com/facebook/reacthttps://github.com/microsoft/vscodehttps://github.com/django/django
API使用
curl -X POST http://localhost:8000/api/v1/generate \
-H "Content-Type: application/json" \
-d '{"repo_url": "https://github.com/expressjs/express"}'答复：
{
"success": true,
"repo_name": "express",
"documentation": {
"beginner": "# Beginner Documentation\n\n...",
"intermediate": "# Intermediate Documentation\n\n...",
"advanced": "# Advanced Documentation\n\n..."
},
"metadata": {
"analysis": { ... },
"rate_limit_remaining": 4998
}
}交互式API文档
FastAPI提供自动交互式文档：
- Swagger用户界面： http://localhost:8000/docs
- 重新记录： http://localhost:8000/redoc
API 参考
端点
生成文档
- 发布
/api/v1/generate - 主体：
{"repo_url": "https://github.com/owner/repo"} - 答复： 初级、中级和高级文档对象
健康检查
- 获取
/api/v1/health - 答复：
{"status": "healthy", "service": "smart-docs-agent"}
速率限制
- GitHub（无令牌）： 60个请求/小时
- GitHub（带令牌）： 5000次请求/小时
- 响应包括
rate_limit_remaining在元数据中
配置
环境变量
创建 backend/.env:
GEMINI_API_KEY=your_gemini_api_key_here
GITHUB_TOKEN=optional_for_private_repos
ENVIRONMENT=development
FRONTEND_URL=http://localhost:5173
BACKEND_PORT=8000GitHub令牌（可选）：
- 仅适用于私人回购或更高的利率限制
- 生成时间：https://github.com/settings/tokens
- 将限制从60/小时增加到5000/小时
Docker部署
# Set environment variables
export GEMINI_API_KEY=your_key_here
export GITHUB_TOKEN=your_token_here # Optional
# Start services
docker-compose up --build- 后端：http://localhost:8000
- 前端：http://localhost:5173
技术栈
后端
- 快速API -支持异步的现代Python web框架
- Google Gemini API -LLM用于文档生成
- PyGithub -GitHub API包装器
- 派丹蒂克 -数据验证
前端
- 反应 -UI库
- 维特 -构建工具
- Tailwind CSS -造型
- 阿西奥斯 -HTTP客户端
基础设施
- 码头工人 -集装箱化
- Docker Compose -多容器编排
故障排除
“超过了GitHub API速率限制”
- 将GitHub令牌添加到
.env5000次请求/小时 - 生成时间：https://github.com/settings/tokens
“后端无法访问”
- 验证后端是否正在运行：
curl http://localhost:8000/api/v1/health - 检查端口8000是否未使用
“无效的API密钥”
- 验证
GEMINI_API_KEY在backend/.env - 测试地点https://aistudio.google.com/apikey
模块导入错误
# Make sure virtual environment is activated
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
pip install -r requirements.txt前端构建错误
cd frontend
rm -rf node_modules package-lock.json
npm install端口已在使用中
# Find and kill process on port 8000
lsof -i :8000 # macOS/Linux
kill -9
# Or use different port
uvicorn app.main:app --port 8001演出
典型响应时间
- 小型存储库（\<50个文件）： 20-40秒
- 中等存储库（50-200个文件）： 40-70秒
- 大型存储库（200+个文件）： 60-90秒
优化
- ✅ 并行代理执行
- ✅ 深度受限的存储库遍历
- ✅ 文件过滤（仅限代码文件）
- ✅ 异步I/O贯穿始终
限制（MVP）
- 仅限公共仓库： 私有仓库需要GitHub令牌
- 费率限制： 60个GitHub请求/小时，无令牌
- 处理时间： 每个存储库30-90秒
- 无缓存： 每个请求都会重新生成文档
- 同步： 一次处理一个请求
项目结构
看 项目_TREE.md 有关详细的文件结构和导航指南。
发展
后端开发
cd backend
source venv/bin/activate
python -m uvicorn app.main:app --reload交互式API文档：http://localhost:8000/docs
前端开发
cd frontend
npm run dev已启用热模块更换。
运行测试
cd backend
pytest未来的增强功能
- 后台处理： 异步处理的作业队列
- 缓存层： Redis用于存储结果
- 流动： 实时文档流
- 数据库： 保存生成的文档
- 身份验证： 用户帐户和API密钥
- Webhooks： 生成完成时通知
- 更多代理： 代码质量、安全分析
贡献
这是一个为演示目的而构建的MVP项目。要扩展它：
- 分叉存储库
- 创建要素分支
- 添加您的更改
- 提交拉取请求
主要贡献领域：
- 附加代理（安全分析器、代码质量检查器）
- 更多MCP服务器（GitLab、Bitbucket支持）
- UI改进
- 性能优化
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
- 内置于 Google Gemini API
- 用途 用于GitHub集成
- 受多智能体AI系统设计模式的启发
______________________________________________________________________
注： 这是一个MVP（最小可行产品），旨在演示多智能体AI系统设计。它完全在本地运行，并使用免费层API。非常适合学习、实验和投资组合项目。