Spaces:

qa1145
/

astrbot_help

Sleeping

App Files Files Community

astrbot_help / README.md

qa1145

Upload 28 files

d347708 verified about 2 months ago

preview code

raw

history blame contribute delete

9.9 kB

metadata

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，自动随机选择分发请求，提升并发能力和稳定性

架构设计

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 并配置：

# 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. 安装依赖

pip install -r requirements.txt

3. 启动方式

命令行模式

# 交互式终端
python main.py

# 指定代码目录
python main.py --code-dir /path/to/code

Web 服务模式

python app.py

Docker 容器化

# 使用 Docker Compose
docker-compose up -d

# 或单独构建镜像
docker build -t read-agent .
docker run -p 7860:7860 read-agent

API 接口

1. 问答接口

POST /api/ask

{
  "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 统计信息

{
  "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

{
  "status": "ok",
  "message": "Read Agent 服务运行中"
}

工作流程

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 机制优化上下文：

@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 以实现请求轮询，提升并发能力和稳定性：

# 单个 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 调用失败时自动重试：

# 最大重试次数（默认: 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

示例配置：

# 激进重试（5次，更长的退避时间）
MAX_RETRIES=5
RETRY_DELAYS=1,3,9,27,81

# 快速重试（2次，短延迟）
MAX_RETRIES=2
RETRY_DELAYS=0.5,1

仓库配置

可以配置多个仓库：

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 输出格式
系统提示词：包含角色、搜索策略、验证协议等
答案提示词：用于生成最终答案

调试

启用调试模式：

DEBUG=true python app.py

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

Read Agent - 让 AI 帮助你更好地理解代码！