README.md

---

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