Spaces:
Sleeping
Sleeping
| title: astrbot-help | |
| emoji: 🤖 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| app_file: app.py | |
| pinned: false | |
| # Read Agent - AI 代码读取与分析助手 | |
| ## 项目简介 | |
| Read Agent 是一个基于 AI 的技术支持助手，专门帮助开发人员读取、搜索和分析代码仓库。它使用 OpenAI 兼容的 API 和 ReAct（Reasoning + Acting）模式进行迭代代码探索，并通过内存管理控制多步骤分析过程中的令牌使用。 | |
| ## 核心功能 | |
| - **智能代码分析**：使用 LLM 分析代码结构和功能 | |
| - **代码搜索**：支持正则表达式搜索和文件内容读取 | |
| - **仓库管理**：自动同步和管理 GitHub 代码仓库 | |
| - **会话管理**：支持多用户并发会话，每个会话有独立的记忆 | |
| - **流式响应**：提供实时的思考过程和答案输出 | |
| - **内存优化**：使用 Memory 机制替代完整文件内容，防止上下文膨胀 | |
| - **多 API Key 随机选择**：支持配置多个 API Key，自动随机选择分发请求，提升并发能力和稳定性 | |
| ## 架构设计 | |
| ```mermaid | |
| graph TD | |
| A[CLI 入口<br/>main.py] --> B[ReadAgent<br/>src/agent.py] | |
| C[Web 入口<br/>app.py] --> B | |
| B --> D[工具执行器<br/>ToolExecutor] | |
| D --> E[搜索工具<br/>src/searcher.py] | |
| D --> F[仓库管理器<br/>src/repo_manager.py] | |
| B --> G[会话存储<br/>app.py] | |
| B --> H[内存管理<br/>Memory 类] | |
| B --> I[LLM API<br/>OpenAI 兼容接口] | |
| ``` | |
| ## 核心组件 | |
| ### 1. ReadAgent (src/agent.py) | |
| - 实现 ReAct 模式的核心代理 | |
| - 管理思考过程、工具执行和结果观察 | |
| - 控制多步骤分析流程 | |
| - 处理内存管理和上下文压缩 | |
| ### 2. 工具执行器 (ToolExecutor) | |
| - 注册和管理可用工具 | |
| - 解析 LLM 响应中的动作指令 | |
| - 执行 read_file、search_code 等操作 | |
| - 提供统一的工具调用接口 | |
| ### 3. 搜索工具 (src/searcher.py) | |
| - read_file：读取文件内容 | |
| - search_code：正则表达式搜索 | |
| - find_files：查找文件 | |
| - find_by_ext：按扩展名搜索 | |
| - list_dir：列出目录内容 | |
| - get_file_info：获取文件信息 | |
| - get_directory_tree：获取目录树 | |
| ### 4. 仓库管理器 (src/repo_manager.py) | |
| - 从 GitHub 下载仓库（ZIP 格式） | |
| - 自动同步多个仓库 | |
| - 支持并行同步（线程） | |
| - 管理仓库存储和更新 | |
| ### 5. 会话管理 (app.py) | |
| - 管理多个并发会话 | |
| - 每个会话有独立的 Agent 实例 | |
| - 支持会话的创建、清除和查询 | |
| - 线程安全的会话存储 | |
| ## 运行方式 | |
| ### 1. 环境变量配置 | |
| 复制 `.env.example` 为 `.env` 并配置： | |
| ```bash | |
| # API Key（支持单个或多个，多Key时会自动轮询） | |
| OPENAI_API_KEY=sk-xxx1,sk-xxx2,sk-xxx3 | |
| OPENAI_BASE_URL=https://api.openai.com/v1 | |
| OPENAI_MODEL=gpt-4 | |
| CODE_DIR=./repos | |
| MAX_STEPS=10 | |
| TREE_DEPTH=3 | |
| STREAM_OUTPUT=true | |
| WEB_PORT=7860 | |
| REPO_SYNC_ON_STARTUP=true | |
| # 仓库配置 | |
| REPO_1_URL=https://github.com/owner/repo1 | |
| REPO_1_NAME=repo1 | |
| REPO_1_BRANCH=main | |
| ``` | |
| ### 2. 安装依赖 | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| ### 3. 启动方式 | |
| #### 命令行模式 | |
| ```bash | |
| # 交互式终端 | |
| python main.py | |
| # 指定代码目录 | |
| python main.py --code-dir /path/to/code | |
| ``` | |
| #### Web 服务模式 | |
| ```bash | |
| python app.py | |
| ``` | |
| #### Docker 容器化 | |
| ```bash | |
| # 使用 Docker Compose | |
| docker-compose up -d | |
| # 或单独构建镜像 | |
| docker build -t read-agent . | |
| docker run -p 7860:7860 read-agent | |
| ``` | |
| ## API 接口 | |
| ### 1. 问答接口 | |
| **POST /api/ask** | |
| ```json | |
| { | |
| "question": "代码的核心功能是什么？", | |
| "stream": true, | |
| "session_id": "optional_session_id" | |
| } | |
| ``` | |
| ### 2. 会话管理 | |
| - **POST /api/session/new**：创建新会话 | |
| - **POST /api/session/clear**：清除会话 | |
| - **GET /status**：获取服务状态 | |
| ### 3. 仓库管理 | |
| - **GET /api/repos**：获取仓库列表 | |
| - **POST /api/repos/sync**：同步仓库 | |
| - **GET /api/repos/config**：获取仓库配置 | |
| - **POST /api/repos/clear**：清空仓库 | |
| ### 4. API Key 管理 | |
| - **GET /api/api-keys/stats**：获取 API Key 统计信息 | |
| ```json | |
| { | |
| "total_keys": 3, | |
| "keys": [ | |
| { | |
| "key_hash": "a1b2c3d4", | |
| "total_requests": 10, | |
| "success_count": 9, | |
| "error_count": 1, | |
| "success_rate": "90.00%", | |
| "last_used": 1704067200.0, | |
| "last_error": "HTTP 429: Rate limit exceeded" | |
| } | |
| ] | |
| } | |
| ``` | |
| - **POST /api/api-keys/reset-stats**：重置 API Key 统计信息 | |
| ### 5. 健康检查 | |
| **GET /health** | |
| ```json | |
| { | |
| "status": "ok", | |
| "message": "Read Agent 服务运行中" | |
| } | |
| ``` | |
| ## 工作流程 | |
| ```mermaid | |
| graph LR | |
| A[用户提问] --> B[构建信息需求树] | |
| B --> C[按优先级搜索<br/>文档→配置→代码] | |
| C --> D[执行工具操作<br/>read_file/search_code] | |
| D --> E[分析结果<br/>交叉验证] | |
| E --> F{是否有最终答案?} | |
| F -- 是 --> G[生成 Memory<br/>优化上下文] | |
| F -- 否 --> C | |
| G --> H[输出答案] | |
| ``` | |
| ## 内存管理 | |
| Read Agent 使用 Memory 机制优化上下文： | |
| ```python | |
| @dataclass | |
| class Memory: | |
| file_path: str # 文件路径 | |
| overview: str # 一句话概述 | |
| key_definitions: List[str] # 关键函数/类名 | |
| core_logic: str # 核心逻辑 | |
| dependencies: List[str] # 依赖模块 | |
| needed_info: str # 待验证信息 | |
| ``` | |
| 每次读取文件后，会创建 Memory 对象替代完整内容，防止上下文膨胀。 | |
| ## 技术特点 | |
| - **无外部依赖**：仅使用 Python 标准库和少数轻量级库（Flask, python-dotenv） | |
| - **流式处理**：支持 token 级别的实时响应 | |
| - **正则搜索**：使用 re 模块实现强大的搜索功能 | |
| - **会话隔离**：每个用户会话完全独立 | |
| - **线程安全**：使用锁机制确保并发安全 | |
| - **自动同步**：启动时自动同步配置的仓库 | |
| ## 使用场景 | |
| - **代码理解**：快速了解陌生代码库的功能和架构 | |
| - **问题定位**：通过搜索和分析找到 bug 的根源 | |
| - **文档生成**：自动生成代码文档和架构说明 | |
| - **代码审查**：辅助进行代码质量评估和审查 | |
| - **学习工具**：帮助开发者学习新代码和技术 | |
| ## 配置说明 | |
| ### 环境变量 | |
| | 变量名 | 默认值 | 说明 | | |
| |--------|--------|------| | |
| | OPENAI_API_KEY | 必填 | LLM API 密钥（支持多个，逗号分隔） | | |
| | OPENAI_BASE_URL | https://api.openai.com/v1 | API 端点 | | |
| | OPENAI_MODEL | gpt-4 | 模型名称 | | |
| | CODE_DIR | ./repos | 仓库存储目录 | | |
| | MAX_STEPS | 10 | 最大推理步数 | | |
| | TREE_DEPTH | 3 | 目录树预加载深度 | | |
| | STREAM_OUTPUT | true | 启用流式输出 | | |
| | WEB_PORT | 7860 | Web 服务端口 | | |
| | REPO_SYNC_ON_STARTUP | true | 启动时自动同步仓库 | | |
| | MAX_RETRIES | 3 | API 调用最大重试次数 | | |
| | RETRY_DELAYS | 1,2,4 | 重试延迟策略（秒，逗号分隔） | | |
| ### 多 API Key 配置 | |
| 支持配置多个 API Key 以实现请求轮询，提升并发能力和稳定性： | |
| ```bash | |
| # 单个 Key | |
| OPENAI_API_KEY=sk-xxx | |
| # 多个 Key（逗号分隔） | |
| OPENAI_API_KEY=sk-xxx1,sk-xxx2,sk-xxx3 | |
| # 通过命令行参数（CLI） | |
| python main.py --api-key "sk-xxx1,sk-xxx2,sk-xxx3" | |
| ``` | |
| 当配置多个 Key 时，系统会自动随机选择： | |
| - 每次请求时随机使用不同的 Key（分散负载） | |
| - 记录每个 Key 的使用统计（请求数、成功率等） | |
| - 可通过 `/api/api-keys/stats` API 查看统计信息 | |
| - 可通过 `/api/api-keys/reset-stats` API 重置统计 | |
| ### 重试配置 | |
| 系统支持 API 调用失败时自动重试： | |
| ```bash | |
| # 最大重试次数（默认: 3） | |
| MAX_RETRIES=3 | |
| # 重试延迟策略，单位：秒（默认: 1,2,4） | |
| # 指数退避策略：第1次重试等1秒，第2次等2秒，第3次等4秒 | |
| RETRY_DELAYS=1,2,4 | |
| ``` | |
| **重试机制：** | |
| - 可重试的 HTTP 状态码：`429, 500, 502, 503, 504`（速率限制、服务器错误） | |
| - 可重试的网络错误：超时、连接错误 | |
| - 重试时仍然会随机使用不同的 API key | |
| - 可通过命令行参数配置：`--max-retries 5 --retry-delays 1,2,4,8,16` | |
| **示例配置：** | |
| ```bash | |
| # 激进重试（5次，更长的退避时间） | |
| MAX_RETRIES=5 | |
| RETRY_DELAYS=1,3,9,27,81 | |
| # 快速重试（2次，短延迟） | |
| MAX_RETRIES=2 | |
| RETRY_DELAYS=0.5,1 | |
| ``` | |
| ### 仓库配置 | |
| 可以配置多个仓库： | |
| ```bash | |
| REPO_1_URL=https://github.com/owner/repo1 | |
| REPO_1_NAME=repo1 | |
| REPO_1_BRANCH=main | |
| REPO_2_URL=https://github.com/owner/repo2 | |
| REPO_2_NAME=repo2 | |
| REPO_2_BRANCH=dev | |
| ``` | |
| ## 开发 | |
| ### 项目结构 | |
| ``` | |
| ├── app.py # Flask Web 应用 | |
| ├── main.py # CLI 入口 | |
| ├── prompts.py # 提示词配置 | |
| ├── requirements.txt # 依赖文件 | |
| ├── Dockerfile # Docker 构建文件 | |
| ├── docker-compose.yml # Docker 组合配置 | |
| ├── src/ # 核心代码 | |
| │ ├── agent.py # ReadAgent 实现 | |
| │ ├── searcher.py # 搜索工具 | |
| │ ├── repo_manager.py # 仓库管理器 | |
| │ └── index.py # 工具索引 | |
| ├── static/ # 前端资源 | |
| │ └── index.html # 主页面 | |
| └── tests/ # 测试文件 | |
| ``` | |
| ### 提示词配置 | |
| 提示词在 `prompts.py` 中定义，包含： | |
| - **ReAct 格式说明**：指导 LLM 输出格式 | |
| - **系统提示词**：包含角色、搜索策略、验证协议等 | |
| - **答案提示词**：用于生成最终答案 | |
| ### 调试 | |
| 启用调试模式： | |
| ```bash | |
| DEBUG=true python app.py | |
| ``` | |
| ## 许可证 | |
| [MIT License](LICENSE) | |
| ## 贡献 | |
| 欢迎提交 Issue 和 Pull Request！ | |
| --- | |
| **Read Agent** - 让 AI 帮助你更好地理解代码！ |