GitHub doc agent

智能文档代理

一个多代理人工智能系统，为GitHub存储库自动生成自适应的多级文档。它采用谷歌的Gemini API和三代理架构构建，可根据不同的体验级别生成初级、中级和高级文档。

📺 视频演示

在YouTube上观看完整演示

查看系统运行情况：为Express.js生成文档，探索三个级别（初级/中级/高级），并展示黑暗模式功能！

特性

• 多级文档： 生成三个不同的文档级别：

- 初学者： 友好的解释，包括示例和故障排除 - 中级： 架构概述和集成模式 - 高级： 技术深度潜水和贡献指南

• 智能分析： 使用AI代理来：

- 分析代码结构和复杂性 - 收集相关背景和最佳实践 - 为每个级别生成量身定制的文档

• 快速高效：

- 并行代理执行 - 智能存储库遍历（深度受限） - 文件过滤以跳过二进制文件

• 自由奔跑：

- 使用免费的Gemini API层 - 使用GitHub的公共API（60次请求/小时） - 可选的GitHub令牌，用于更高的速率限制

建筑

Frontend (React) → Backend (FastAPI) → Agent Orchestrator
                                            ↓
                    ┌───────────────────────┼───────────────────────┐
                    ↓                       ↓                       ↓
            Code Analyzer           Context Gatherer       Doc Generator
                    ↓                       ↓                       ↓
                    └───────────────────────┴───────────────────────┘
                                            ↓
                                    GitHub MCP Server

多代理系统

1. 代码分析器代理： 分析存储库结构，检测框架，计算指标
2. 上下文收集器代理： 检索文档标准和最佳实践
3. 文档生成器代理： 并行生成三个级别的文档

设计模式

• 编排器模式： 中央协调器管理代理生命周期
• 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_agent

2.获取API密钥

1. 访问https://aistudio.google.com/apikey
2. 单击“创建API密钥”
3. 复制密钥（以开头 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.试试看

1. 打开http://localhost:5173
2. 输入GitHub存储库URL（例如。， https://github.com/expressjs/express)
3. 点击“生成文档”
4. 等待30-60秒
5. 查看三个级别的文档！

使用示例

网络界面

只需粘贴任何公共GitHub存储库URL：

• https://github.com/facebook/react
• https://github.com/microsoft/vscode
• https://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=8000

GitHub令牌（可选）：

• 仅适用于私人回购或更高的利率限制
• 生成时间：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令牌添加到 .env 5000次请求/小时
• 生成时间：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

未来的增强功能

1. 后台处理： 异步处理的作业队列
2. 缓存层： Redis用于存储结果
3. 流动： 实时文档流
4. 数据库： 保存生成的文档
5. 身份验证： 用户帐户和API密钥
6. Webhooks： 生成完成时通知
7. 更多代理： 代码质量、安全分析

贡献

这是一个为演示目的而构建的MVP项目。要扩展它：

1. 分叉存储库
2. 创建要素分支
3. 添加您的更改
4. 提交拉取请求

主要贡献领域：

• 附加代理（安全分析器、代码质量检查器）
• 更多MCP服务器（GitLab、Bitbucket支持）
• UI改进
• 性能优化

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 内置于 Google Gemini API
• 用途 用于GitHub集成
• 受多智能体AI系统设计模式的启发

______________________________________________________________________

注： 这是一个MVP（最小可行产品），旨在演示多智能体AI系统设计。它完全在本地运行，并使用免费层API。非常适合学习、实验和投资组合项目。