---
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 帮助你更好地理解代码！