Upload 28 files

.env

@@ -0,0 +1,63 @@
+# OpenAI API Key（必需）
+OPENAI_API_KEY=your-api-key-here
+
+# API 基础 URL（可选，默认值：https://api.openai.com/v1）
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 模型名称（可选，默认值：gpt-4）
+OPENAI_MODEL=gpt-4
+
+# 代码目录路径（仓库根目录）
+CODE_DIR=./repos
+
+# 预加载目录树深度（可选，默认值：3，0 表示不限制）
+TREE_DEPTH=3
+
+
+# 最大步骤数（可选，默认值：10）
+MAX_STEPS=50
+
+# 是否启用流式输出（可选，默认值：true）
+STREAM_OUTPUT=true
+
+# ============ 仓库自动同步配置 ============
+
+# 方式1：逗号分隔的 URL 列表
+# REPO_URLS=https://github.com/user/repo1.git,https://github.com/user/repo2.git
+
+# 方式2：带编号的配置（推荐）
+
+# 仓库1 - AstrBot-docs
+REPO_1_URL=https://github.com/AstrBotDevs/AstrBot-docs.git
+REPO_1_NAME=AstrBot-docs
+REPO_1_BRANCH=v4
+REPO_1_AUTO_UPDATE=true
+
+# 仓库2 - AstrBot
+REPO_2_URL=https://github.com/AstrBotDevs/AstrBot.git
+REPO_2_NAME=AstrBot
+REPO_2_BRANCH=master
+REPO_2_AUTO_UPDATE=true
+
+# 仓库3 - NapCatDocs
+REPO_3_URL=https://github.com/NapNeko/NapCatDocs.git
+REPO_3_NAME=NapCatDocs
+REPO_3_BRANCH=main
+REPO_3_AUTO_UPDATE=true
+
+# 仓库4 - NapCatQQ
+REPO_4_URL=https://github.com/NapNeko/NapCatQQ.git
+REPO_4_NAME=NapCatQQ
+REPO_4_BRANCH=main
+REPO_4_AUTO_UPDATE=true
+
+# 启动时自动同步（可选，默认值：true）
+# REPO_SYNC_ON_STARTUP=true
+
+
+# ============ 重试配置 ============
+# API 调用最大重试次数（可选，默认值：3）
+MAX_RETRIES=5
+
+# 重试延迟策略（可选，默认值：1,2,4，单位：秒）
+RETRY_DELAYS=0,0,1,2,4

.env.example

@@ -0,0 +1,63 @@
+# Read Agent 环境变量配置
+# 复制此文件为 .env 并填写实际值
+
+# ============ API 配置（必需） ============
+# API Key（单个或多个，支持逗号分隔的多Key随机选择）
+# 单个Key: OPENAI_API_KEY=sk-xxx
+# 多个Key: OPENAI_API_KEY=sk-xxx1,sk-xxx2,sk-xxx3
+OPENAI_API_KEY=your-api-key-here
+
+# API 基础 URL（可选，默认值：https://api.openai.com/v1）
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 模型名称（可选，默认值：gpt-4）
+OPENAI_MODEL=gpt-4
+
+# ============ 仓库自动下载配置 ============
+# 代码目录路径（可选，默认值：./repos）
+CODE_DIR=./repos
+
+# 方式1：逗号分隔的 URL 列表
+# REPO_URLS=https://github.com/user/repo1.git,https://github.com/user/repo2.git
+
+# 方式2：带编号的配置（推荐）
+# 仓库1
+REPO_1_URL=https://github.com/AstrBotDevs/AstrBot-docs.git
+REPO_1_NAME=AstrBot-docs  # 可选，不指定则自动从URL提取
+REPO_1_BRANCH=v4          # 可选，默认 main
+
+# 仓库2
+REPO_2_URL=https://github.com/AstrBotDevs/AstrBot.git
+REPO_2_NAME=AstrBot
+REPO_2_BRANCH=master
+
+# 仓库3
+REPO_3_URL=https://github.com/NapNeko/NapCatQQ.git
+REPO_3_NAME=NapCatQQ
+REPO_3_BRANCH=main
+
+# 启动时是否自动同步仓库（可选，默认值：true）
+REPO_SYNC_ON_STARTUP=true
+
+# ============ 其他配置 ============
+# 最大步骤数（可选，默认值：10）
+MAX_STEPS=10
+
+# 预加载目录树深度（可选，默认值：3，0 表示不限制）
+TREE_DEPTH=3
+
+# 是否启用流式输出（可选，默认值：true）
+STREAM_OUTPUT=true
+
+# Web 服务器端口（可选，默认值：7860）
+WEB_PORT=7860
+
+# 调试模式（可选，默认值：false）
+DEBUG=false
+
+# ============ 重试配置 ============
+# API 调用最大重试次数（可选，默认值：3）
+MAX_RETRIES=3
+
+# 重试延迟策略（可选，默认值：1,2,4，单位：秒）
+RETRY_DELAYS=1,2,4

.gitignore

@@ -0,0 +1,46 @@
+# 环境变量文件
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# 虚拟环境
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# 代码目录
+code/
+
+# 日志
+*.log
+
+# 操作系统
+.DS_Store
+Thumbs.db

CLAUDE.md

@@ -0,0 +1,230 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Read Agent is an AI-powered code analysis assistant that uses OpenAI-compatible APIs with the ReAct (Reasoning + Acting) pattern for iterative code exploration. It provides both CLI and Web interfaces.
+
+## Common Commands
+
+### Running the Application
+
+```bash
+# CLI interface (interactive terminal)
+python main.py
+
+# CLI with specific code directory
+python main.py --code-dir /path/to/code
+
+# CLI with multiple API keys (comma-separated)
+python main.py --api-key "key1,key2,key3"
+
+# Web server (default port 7860)
+python app.py
+
+# Web server with debug mode
+DEBUG=true python app.py
+```
+
+### Docker
+
+```bash
+# Using docker-compose
+docker-compose up -d
+
+# Build and run manually
+docker build -t read-agent .
+docker run -p 7860:7860 read-agent
+```
+
+### Testing
+
+```bash
+pytest                    # Run tests
+pytest --cov            # Run with coverage
+```
+
+### Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## Architecture
+
+### Core Pattern: ReAct Loop
+
+The ReadAgent (src/agent.py) implements a ReAct (Reasoning + Acting) pattern:
+1. LLM generates a "thought" about what to do next
+2. LLM specifies an "action" using available tools (read_file, search_code, etc.)
+3. ToolExecutor executes the action and returns observations
+4. Loop continues until the LLM decides it has enough information
+5. Final answer is generated based on accumulated observations
+
+This pattern enables iterative exploration without requiring all context upfront.
+
+### Multi API Key Rotation (ApiKeyManager)
+
+**src/api_key_manager.py** - ApiKeyManager class
+- Manages multiple API keys for load balancing and reliability
+- Round-robin rotation across keys
+- Thread-safe operations with locks
+- Tracks statistics: request count, success rate, errors
+- Global singleton pattern via `get_global_manager()` or `init_manager()`
+
+**Usage:**
+```python
+from src.api_key_manager import ApiKeyManager
+
+# Single key
+manager = ApiKeyManager("sk-xxx")
+
+# Multiple keys (comma-separated)
+manager = ApiKeyManager("sk-key1,sk-key2,sk-key3")
+
+# Get next key (round-robin)
+key = manager.get_key()
+
+# Record results
+manager.record_success(key)
+manager.record_error(key, "Error message")
+
+# Get statistics
+stats = manager.get_stats()
+```
+
+**Integration with ReadAgent:**
+- ReadAgent accepts `api_key_manager` parameter
+- If provided, uses ApiKeyManager to get keys via rotation
+- Records success/failure statistics automatically
+- Falls back to legacy single-key mode if no manager provided
+
+### Memory Management
+
+To prevent context expansion across multiple steps, the agent uses a Memory dataclass:
+
+```python
+@dataclass
+class Memory:
+    file_path: str          # File being analyzed
+    overview: str           # One-sentence summary
+    key_definitions: List[str]  # Key function/class names
+    core_logic: str         # Core logic description
+    dependencies: List[str] # Dependencies
+    needed_info: str        # Information to verify
+```
+
+After reading a file, the agent creates a Memory object instead of keeping full file content. Subsequent tool calls can reference previously analyzed files without re-reading them.
+
+### Key Components
+
+**src/agent.py** - ReadAgent class
+- Main orchestration of ReAct loop
+- Manages Memory objects to optimize context
+- Supports streaming output via `ask(stream=True)`
+- Batch action support for parallel independent operations
+- Integrates with ApiKeyManager for multi-key rotation
+
+**src/searcher.py** - CodeSearcher class
+- Provides all file/code interaction tools
+- Integrates with CodeIndex for fast keyword/symbol search
+- Tools: read_file, find_files, search_code, find_by_ext, list_dir, get_file_info, get_dir_tree
+
+**src/index.py** - CodeIndex class
+- Inverted index for fast code search
+- Lazy building: builds on first search if not exists
+- Supports both keyword search and symbol extraction
+- Tokenization handles camelCase, PascalCase, snake_case
+
+**src/repo_manager.py** - RepoManager class
+- Downloads GitHub repos as ZIP files
+- Skip detection: won't re-download existing repos unless forced
+- Parallel sync support (threading)
+- Configured via environment variables (REPO_1_URL, REPO_2_URL, etc.)
+
+**src/session_storage.py** - SessionStorage class
+- SQLite-based persistent storage for sessions
+- Thread-safe with locks
+- Stores: session metadata, conversation history, memories
+- Cleanup of old sessions
+
+**prompts.py** - Prompt configuration
+- ReAct format instructions
+- Information need tree construction strategy
+- Priority-based search (docs → config → code)
+- Recursive validation protocol
+
+### Entry Points
+
+1. **main.py** - CLI interface with interactive commands (quit, clear, status, help)
+2. **app.py** - Flask web application with REST APIs
+
+### Session Isolation
+
+Each user session (web) has:
+- Independent ReadAgent instance
+- Separate Memory objects
+- Isolated conversation history
+- SQLite persistence (can be restored)
+- Shared ApiKeyManager instance (for efficient key rotation)
+
+### Streaming Support
+
+The agent supports streaming responses (`STREAM_OUTPUT=true`):
+- Thoughts and actions stream in real-time
+- Final answer detection via special tokens
+- Provides immediate feedback during long-running analysis
+
+## Environment Variables
+
+### API Configuration
+- `OPENAI_API_KEY` - Required (can be multiple keys separated by commas)
+- `OPENAI_BASE_URL` - Default: https://api.openai.com/v1
+- `OPENAI_MODEL` - Default: gpt-4
+
+### Repository Configuration
+- `CODE_DIR` - Default: ./repos
+- `REPO_SYNC_ON_STARTUP` - Default: true
+- `REPO_1_URL`, `REPO_2_URL`, etc. - GitHub repo URLs
+- `REPO_1_NAME`, `REPO_1_BRANCH`, etc. - Per-repo settings
+
+### Agent Configuration
+- `MAX_STEPS` - Maximum reasoning steps (default: 10)
+- `TREE_DEPTH` - Directory tree preload depth (default: 3)
+- `STREAM_OUTPUT` - Enable streaming (default: true)
+- `WEB_PORT` - Web server port (default: 7860)
+- `DEBUG` - Debug mode (default: false)
+
+## API Endpoints (app.py)
+
+### Question API
+- `POST /api/ask` - Main question endpoint (supports streaming via query param or JSON field)
+
+### Session Management
+- `POST /api/session/new` - Create new session
+- `POST /api/session/clear` - Clear session(s)
+- `GET /status` - Service status
+
+### Repository Management
+- `GET /api/repos` - List repositories
+- `POST /api/repos/sync` - Sync repositories
+- `GET /api/repos/config` - Get repository configuration
+- `POST /api/repos/clear` - Clear all repositories
+
+### API Key Management
+- `GET /api/api-keys/stats` - Get API key usage statistics
+- `POST /api/api-keys/reset-stats` - Reset API key statistics
+
+### Health Check
+- `GET /health` - Health check
+- `GET /prompt` - Return system prompt
+
+## Technical Notes
+
+- **Pure Python** - Uses only standard library (urllib) and minimal dependencies (Flask, python-dotenv)
+- **No async/await** - Uses threading for parallel operations
+- **SQLite** for session persistence (file-based, no external DB required)
+- **Symbol extraction** for Python and JavaScript in CodeIndex (AST-based)
+- **ReAct format** - LLM outputs structured JSON with "thought" and "action" fields
+- **Thread-safe API Key Management** - Uses locks for concurrent access to ApiKeyManager

Dockerfile

@@ -0,0 +1,32 @@
+# Read Agent 容器镜像
+FROM python:3.11-slim
+
+# 设置工作目录
+WORKDIR /app
+
+# 设置环境变量
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# 复制依赖文件并安装
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 复制应用代码
+COPY . .
+
+# 创建代码目录
+RUN mkdir -p /app/code
+
+# 暴露端口
+EXPOSE 7860
+
+# 启动命令 - 使用 Flask 内置服务器
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,371 @@
----
-title: Astrbot Help
-emoji: 🏆
-colorFrom: green
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+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 帮助你更好地理解代码！

app.py

@@ -0,0 +1,1039 @@
+#!/usr/bin/env python3
+"""
+Read Agent Web 服务
+
+Flask Web 应用，提供 API 接口供前端调用
+"""
+
+import os
+import sys
+import json
+import logging
+import queue
+import threading
+import uuid
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+from flask import Flask, request, jsonify, send_from_directory, Response
+from dotenv import load_dotenv
+
+from src.agent import ReadAgent, Memory
+from src.repo_manager import RepoManager
+from src.api_key_manager import init_manager, get_global_manager
+from src.session_storage import SessionStorage
+from prompts import get_system_prompt, get_react_format_prompt
+
+# 加载环境变量
+load_dotenv()
+
+# 配置日志
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# 创建 Flask 应用
+app = Flask(__name__, static_folder='static')
+
+# API Key 管理器（全局共享）
+key_manager = None
+
+# 仓库管理器（全局共享）
+repo_manager = None
+
+# 会话持久化存储
+session_storage = SessionStorage("./data/sessions.db")
+
+# 会话存储：{session_id: agent_instance}
+sessions = {}
+
+# 线程安全锁
+sessions_lock = threading.Lock()
+repo_manager_lock = threading.Lock()
+key_manager_lock = threading.Lock()
+
+# 仓库同步标志（避免重复同步）
+_repo_synced = False
+_repo_sync_lock = threading.Lock()
+
+# 弹窗配置文件路径
+POPUP_CONFIG_PATH = os.path.join(os.path.dirname(__file__), 'config', 'popup.json')
+
+# 弹窗配置缓存
+_popup_config_cache = None
+_popup_config_cache_lock = threading.Lock()
+
+
+def get_env(key: str, default: str = "") -> str:
+    """获取环境变量"""
+    return os.getenv(key, default)
+
+
+def get_env_bool(key: str, default: bool = False) -> bool:
+    """获取布尔型环境变量"""
+    value = get_env(key, "").lower()
+    if value in ("true", "1", "yes", "on"):
+        return True
+    elif value in ("false", "0", "no", "off"):
+        return False
+    return default
+
+
+def load_popup_config():
+    """加载弹窗配置（带缓存）"""
+    global _popup_config_cache
+
+    with _popup_config_cache_lock:
+        if _popup_config_cache is not None:
+            return _popup_config_cache
+
+        try:
+            if os.path.exists(POPUP_CONFIG_PATH):
+                with open(POPUP_CONFIG_PATH, 'r', encoding='utf-8') as f:
+                    config = json.load(f)
+                _popup_config_cache = config
+                logger.info(f"加载弹窗配置: {POPUP_CONFIG_PATH}")
+                return config
+            else:
+                logger.warning(f"弹窗配置文件不存在: {POPUP_CONFIG_PATH}")
+                return None
+        except Exception as e:
+            logger.error(f"加载弹窗配置失败: {e}")
+            return None
+
+
+def reload_popup_config():
+    """重新加载弹窗配置"""
+    global _popup_config_cache
+
+    with _popup_config_cache_lock:
+        _popup_config_cache = None
+        return load_popup_config()
+
+
+def format_action_args(action_args: dict) -> str:
+    """格式化 action_args 为字符串"""
+    if not action_args:
+        return ""
+    return ", ".join(f'{k}="{v}"' for k, v in action_args.items())
+
+
+def get_repo_manager():
+    """获取或创建仓库管理器（线程安全）"""
+    global repo_manager
+    with repo_manager_lock:
+        if repo_manager is None:
+            code_dir = get_env("CODE_DIR", "./code")
+            repo_manager = RepoManager(code_dir)
+        return repo_manager
+
+
+def get_key_manager():
+    """获取或创建 API Key 管理器（线程安全）"""
+    global key_manager
+    with key_manager_lock:
+        if key_manager is None:
+            api_keys = get_env("OPENAI_API_KEY", "")
+            if api_keys:
+                key_manager = init_manager(api_keys)
+                logger.info(f"API Key 管理器初始化完成，共 {key_manager.key_count} 个 Key")
+            else:
+                logger.warning("未配置 OPENAI_API_KEY")
+        return key_manager
+
+
+def get_agent(session_id: str = None):
+    """获取或创建会话的 Agent，返回 (agent, session_id)（线程安全）"""
+    with sessions_lock:
+        # 如果没有 session_id 或会话不存在，创建新的
+        if not session_id or session_id not in sessions:
+            # 生成 session_id（如果未提供）
+            session_id = session_id or str(uuid.uuid4())
+
+            # 在锁外获取环境变量和初始化耗时操作
+            # 注意：这里先释放锁，然后再重新获取锁进行 sessions 写入
+            # 但为了避免竞态条件，我们在创建完成前保持 session_id 的唯一性
+        else:
+            return sessions[session_id], session_id
+
+    # 释放锁后执行耗时操作（避免阻塞其他线程）
+
+    # 首先尝试从存储恢复会话
+    if session_id:
+        saved_session = session_storage.load_session(session_id)
+        if saved_session:
+            # 恢复会话
+            agent = ReadAgent(
+                code_dir=saved_session["code_dir"],
+                base_url=saved_session["base_url"],
+                model=saved_session["model"],
+                max_steps=saved_session["max_steps"],
+                stream_output=saved_session["stream_output"],
+                tree_depth=saved_session["tree_depth"],
+                api_key_manager=get_key_manager()
+            )
+            # 恢复状态
+            agent.conversation_history = saved_session["conversation_history"]
+            for m in saved_session["memories"]:
+                agent.memories.append(Memory(
+                    file_path=m["file_path"],
+                    overview=m["overview"],
+                    key_definitions=m["key_definitions"],
+                    core_logic=m["core_logic"],
+                    dependencies=m["dependencies"],
+                    needed_info=m["needed_info"]
+                ))
+
+            # 重新获取锁并写入 sessions（防止重复创建）
+            with sessions_lock:
+                if session_id not in sessions:
+                    sessions[session_id] = agent
+                    logger.info(f"恢复会话: {session_id}")
+                else:
+                    agent = sessions[session_id]
+
+            return agent, session_id
+
+    # 没有找到已保存的会话，创建新的
+    # 获取 API Key 管理器
+    key_manager = get_key_manager()
+    if not key_manager or not key_manager.has_keys:
+        logger.warning("OPENAI_API_KEY 未设置")
+
+    base_url = get_env("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    model = get_env("OPENAI_MODEL", "gpt-4")
+    code_dir = get_env("CODE_DIR", "./code")
+    max_steps = int(get_env("MAX_STEPS", "10"))
+    stream_output = get_env_bool("STREAM_OUTPUT", True)
+    tree_depth = int(get_env("TREE_DEPTH", "3"))
+
+    # 初始化仓库管理器
+    repo_manager = get_repo_manager()
+    # 仓库同步已在启动时完成，无需再次同步
+
+    # 创建代码目录
+    Path(code_dir).mkdir(parents=True, exist_ok=True)
+
+    agent = ReadAgent(
+        code_dir=code_dir,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        stream_output=stream_output,
+        tree_depth=tree_depth,
+        api_key_manager=key_manager
+    )
+
+    # 保存新会话到持久化存储
+    session_storage.save_session(
+        session_id=session_id,
+        model=model,
+        base_url=base_url,
+        code_dir=code_dir,
+        max_steps=max_steps,
+        stream_output=stream_output,
+        tree_depth=tree_depth,
+        conversation_history=agent.conversation_history,
+        memories=[m.to_dict() for m in agent.memories]
+    )
+
+    # 重新获取锁并写入 sessions（防止重复创建）
+    with sessions_lock:
+        # 再次检查，可能在创建过程中另一个线程已经创建了
+        if session_id not in sessions:
+            sessions[session_id] = agent
+            logger.info(f"创建新会话: {session_id}, model={model}")
+        else:
+            # 如果已存在，使用现有的 agent
+            agent = sessions[session_id]
+            logger.info(f"使用现有会话: {session_id}")
+
+    return agent, session_id
+
+
+def save_agent_state(session_id: str, agent: ReadAgent):
+    """保存 Agent 状态到持久化存储"""
+    try:
+        session_storage.save_session(
+            session_id=session_id,
+            model=agent.model,
+            base_url=agent.base_url,
+            code_dir=str(agent.searcher.root_dir),
+            max_steps=agent.max_steps,
+            stream_output=agent.stream_output,
+            tree_depth=agent.tree_depth,
+            conversation_history=agent.conversation_history,
+            memories=[m.to_dict() for m in agent.memories]
+        )
+    except Exception as e:
+        logger.warning(f"保存会话状态失败: {e}")
+
+
+@app.route('/')
+def index():
+    """主页"""
+    return send_from_directory('static', 'index.html')
+
+
+@app.route('/static/<path:filename>')
+def static_files(filename):
+    """静态文件"""
+    return send_from_directory('static', filename)
+
+
+@app.route('/prompt')
+def prompt():
+    """返回提示词"""
+    from src.agent import ReadAgent
+    from prompts import get_system_prompt
+    
+    # 获取 Agent 的工具信息
+    agent = ReadAgent()
+    tools_info = agent.tool_executor.get_available_tools()
+    max_steps = agent.max_steps
+    
+    # 使用 prompts.py 中的函数生成提示词
+    return get_system_prompt(tools_info, max_steps)
+
+
+@app.route('/use_document')
+def use_document():
+    """返回参考文档"""
+    # 可以扩展为返回实际文档内容
+    return ""
+
+
+@app.route('/api/ask', methods=['POST'])
+def ask():
+    """Read Agent 问答 API"""
+    data = request.json
+    if not data:
+        return jsonify({"error": "请求体不能为空"}), 400
+
+    question = data.get('question', '')
+    stream = data.get('stream', True)  # 默认启用流式输出
+    session_id = data.get('session_id')  # 获取会话 ID
+    if not question:
+        return jsonify({"error": "问题不能为空"}), 400
+
+    # 获取或创建会话的 Agent
+    agent, session_id = get_agent(session_id)
+
+    if stream:
+        # 流式响应 - 真正的 token 级别流式输出
+        def generate():
+            try:
+                import sys
+                
+                # 发送会话 ID
+                yield "data: " + json.dumps({"type": "session_id", "session_id": session_id}) + "\n\n"
+                sys.stdout.flush()
+                
+                # 发送开始信号
+                yield "data: " + json.dumps({"type": "start"}) + "\n\n"
+                sys.stdout.flush()
+                
+                # 发送问题
+                yield "data: " + json.dumps({"type": "question", "content": question}) + "\n\n"
+                sys.stdout.flush()
+                
+                # 初始化当前会话的 Agent
+                agent.steps = []
+                agent.conversation_history.append({"role": "user", "content": question})
+                full_answer = ""
+                current_step = 0
+                
+                for step in range(1, agent.max_steps + 1):
+                    current_step = step
+                    
+                    # 创建流式回调来实时发送 LLM 响应
+                    msg_queue = queue.Queue()
+                    
+                    def stream_callback(chunk):
+                        msg_queue.put(("chunk", chunk))
+                    
+                    def done_callback():
+                        msg_queue.put(("done", None))
+                    
+                    # 在后台线程中调用 LLM（支持重试）
+                    def call_llm():
+                        import time
+
+                        # 使用 agent 的重试配置
+                        max_retries = agent.max_retries
+                        retry_delays = agent.retry_delays
+
+                        # 可重试的 HTTP 状态码
+                        retryable_status_codes = [401, 429, 500, 502, 503, 504]
+
+                        for attempt in range(max_retries):
+                            try:
+                                # 使用 http.client 实现真正的流式读取
+                                import http.client
+
+                                # 从 ApiKeyManager 获取 key（随机选择）
+                                api_key = None
+                                if agent.api_key_manager:
+                                    api_key = agent.api_key_manager.get_key()
+
+                                if not api_key:
+                                    raise Exception("未配置 API Key")
+
+                                # 解析 base_url
+                                parsed_url = urlparse(agent.base_url)
+                                host = parsed_url.hostname or "api.openai.com"
+                                port = parsed_url.port or 443
+                                # 拼接 path 和 endpoint
+                                api_path = parsed_url.path.strip() if parsed_url.path else "/v1"
+                                endpoint = "/chat/completions"
+                                path = f"{api_path}{endpoint}"
+
+                                headers = {
+                                    "Content-Type": "application/json",
+                                    "Authorization": f"Bearer {api_key}",
+                                    "Host": host
+                                }
+
+                                messages = [
+                                    {"role": "system", "content": agent._build_system_prompt()}
+                                ]
+                                for msg in agent.conversation_history:
+                                    messages.append(msg)
+                                messages.append({
+                                    "role": "user",
+                                    "content": f"用户问题：{question}\n\n{get_react_format_prompt()}"
+                                })
+
+                                body = json.dumps({
+                                    "model": agent.model,
+                                    "messages": messages,
+                                    "temperature": 0.3,
+                                    "stream": True
+                                })
+
+                                conn = http.client.HTTPSConnection(host, port, timeout=60)
+                                conn.request("POST", path, body, headers)
+
+                                response = conn.getresponse()
+
+                                if response.status != 200:
+                                    # 检查是否可重试
+                                    if response.status in retryable_status_codes and attempt < max_retries - 1:
+                                        conn.close()
+                                        if agent.api_key_manager and api_key:
+                                            agent.api_key_manager.record_error(api_key, f"HTTP {response.status} (重试 {attempt + 1}/{max_retries})")
+
+                                        # 获取延迟（如果超出数组长度，使用最后一个值）
+                                        delay = retry_delays[min(attempt, len(retry_delays) - 1)]
+                                        msg_queue.put(("retry", delay, response.status, attempt + 1, max_retries))
+                                        time.sleep(delay)
+                                        continue
+                                    else:
+                                        # 最后一次重试或不可重试的错误
+                                        conn.close()
+                                        if agent.api_key_manager and api_key:
+                                            agent.api_key_manager.record_error(api_key, f"HTTP {response.status}")
+                                        raise Exception(f"API 错误: {response.status}")
+
+                                # 真正流式读取响应
+                                llm_response = ""
+                                while True:
+                                    line = response.readline()
+                                    if not line:
+                                        break
+
+                                    line = line.decode("utf-8").strip()
+                                    if not line.startswith("data: "):
+                                        continue
+                                    if line == "data: [DONE]":
+                                        break
+
+                                    data_str = line[6:]
+                                    try:
+                                        chunk = json.loads(data_str)
+                                        if chunk.get("choices") and len(chunk["choices"]) > 0:
+                                            delta = chunk["choices"][0].get("delta", {})
+                                            content = delta.get("content", "")
+                                            if content:
+                                                stream_callback(content)
+                                    except json.JSONDecodeError:
+                                        continue
+
+                                conn.close()
+
+                                # 记录成功
+                                if agent.api_key_manager and api_key:
+                                    agent.api_key_manager.record_success(api_key)
+
+                                done_callback()
+                                return
+
+                            except Exception as e:
+                                # 网络错误，可重试
+                                if attempt < max_retries - 1 and ("timeout" in str(e).lower() or "connection" in str(e).lower()):
+                                    if agent.api_key_manager and api_key:
+                                        agent.api_key_manager.record_error(api_key, f"网络错误: {str(e)} (重试 {attempt + 1}/{max_retries})")
+
+                                    # 获取延迟（如果超出数组长度，使用最后一个值）
+                                    delay = retry_delays[min(attempt, len(retry_delays) - 1)]
+                                    msg_queue.put(("retry", delay, "网络错误", attempt + 1, max_retries))
+                                    time.sleep(delay)
+                                    continue
+                                else:
+                                    # 最后一次重试或不可重试的错误
+                                    if agent.api_key_manager and api_key:
+                                        agent.api_key_manager.record_error(api_key, str(e))
+                                    msg_queue.put(("error", str(e)))
+                                    return
+                    
+                    llm_thread = threading.Thread(target=call_llm)
+                    llm_thread.start()
+                    
+                    # 收集 LLM 响应（支持超时后重试当前步骤）
+                    llm_timeout_retries = int(os.getenv("LLM_TIMEOUT_RETRIES", "2"))
+                    llm_timeout_delay = int(os.getenv("LLM_TIMEOUT_DELAY", "2"))
+
+                    for timeout_attempt in range(llm_timeout_retries + 1):
+                        llm_response = ""
+                        received_done = False
+                        try:
+                            while True:
+                                msg = msg_queue.get(timeout=60)
+                                msg_type = msg[0]
+
+                                if msg_type == "error":
+                                    raise Exception(msg[1])
+                                elif msg_type == "done":
+                                    received_done = True
+                                    break
+                                elif msg_type == "retry":
+                                    # 重试消息: (retry, delay, status_or_error, attempt, max_retries)
+                                    delay, status_or_error, attempt, max_retries = msg[1], msg[2], msg[3], msg[4]
+                                    yield "data: " + json.dumps({
+                                        "type": "retry",
+                                        "delay": delay,
+                                        "status": status_or_error,
+                                        "attempt": attempt,
+                                        "max_retries": max_retries
+                                    }, ensure_ascii=False) + "\n\n"
+                                    sys.stdout.flush()
+                                else:  # chunk - (msg_type, content)
+                                    content = msg[1]
+                                    llm_response += content
+                                    # 发送思考内容流式输出
+                                    yield "data: " + json.dumps({
+                                        "type": "chunk",
+                                        "step": step,
+                                        "content": content,
+                                        "stream_type": "thought"
+                                    }, ensure_ascii=False) + "\n\n"
+                                    sys.stdout.flush()
+                            break  # 成功获取响应，退出重试循环
+                        except queue.Empty:
+                            if timeout_attempt < llm_timeout_retries:
+                                logger.warning(f"步骤 {step} 等待 LLM 响应超时，{llm_timeout_delay} 秒后重试 ({timeout_attempt + 1}/{llm_timeout_retries + 1})")
+                                yield "data: " + json.dumps({
+                                    "type": "step_timeout",
+                                    "step": step,
+                                    "retry_delay": llm_timeout_delay,
+                                    "attempt": timeout_attempt + 1,
+                                    "max_retries": llm_timeout_retries + 1,
+                                    "message": f"等待 LLM 响应超时，{llm_timeout_delay} 秒后重试..."
+                                }, ensure_ascii=False) + "\n\n"
+                                sys.stdout.flush()
+                                time.sleep(llm_timeout_delay)
+                                # 等待 LLM 线程结束
+                                if llm_thread.is_alive():
+                                    llm_thread.join(timeout=1)
+                                # 重新启动 LLM 调用
+                                llm_thread = threading.Thread(target=call_llm)
+                                llm_thread.start()
+                            else:
+                                logger.error(f"步骤 {step} 等待 LLM 响应超时，已达最大重试次数")
+                                break
+                    
+                    llm_thread.join()
+
+                    # 调试日志
+                    logger.info(f"步骤 {step} LLM 响应: done={received_done}, length={len(llm_response)}, response_preview={llm_response[:200]}...")
+
+                    # 如果没有收到有效响应，触发重试
+                    if not llm_response:
+                        if timeout_attempt < llm_timeout_retries:
+                            logger.warning(f"步骤 {step} 收到空响应，{llm_timeout_delay} 秒后重试 ({timeout_attempt + 1}/{llm_timeout_retries + 1})")
+                            yield "data: " + json.dumps({
+                                "type": "step_empty_response",
+                                "step": step,
+                                "retry_delay": llm_timeout_delay,
+                                "attempt": timeout_attempt + 1,
+                                "max_retries": llm_timeout_retries + 1,
+                                "message": f"LLM 返回空响应，{llm_timeout_delay} 秒后重试..."
+                            }, ensure_ascii=False) + "\n\n"
+                            sys.stdout.flush()
+                            time.sleep(llm_timeout_delay)
+                            # 重新启动 LLM 调用（继续外层重试循环）
+                            llm_thread = threading.Thread(target=call_llm)
+                            llm_thread.start()
+                            continue
+                        else:
+                            logger.error(f"步骤 {step} 收到空响应，已达最大重试次数")
+                            # 发送错误信号
+                            yield "data: " + json.dumps({"type": "error", "error": "LLM 未返回有效响应"}) + "\n\n"
+                            return
+
+                    # 处理 LLM 响应（支持批量 Actions）
+                    thought, actions_list = agent._extract_thought_action(llm_response)
+                    final_answer, memory_data = agent._extract_final_answer(llm_response)
+
+                    # 获取第一个 action 用于日志
+                    first_action = None
+                    if actions_list and len(actions_list) > 0:
+                        # actions_list 的每个元素是 (action_name, args_dict)
+                        first_action_tuple = actions_list[0]
+                        if first_action_tuple and len(first_action_tuple) > 0:
+                            first_action = first_action_tuple[0]  # action_name
+
+                    logger.info(f"步骤 {step} 解析: thought={thought[:30] if thought else 'None'}..., action={first_action}, has_final={bool(final_answer)}, actions_count={len(actions_list)}")
+                    
+                    # 发送完成当前步骤的思考
+                    yield "data: " + json.dumps({
+                        "type": "step_thought_done",
+                        "step": step,
+                        "thought": thought,
+                        "has_action": len(actions_list) > 0
+                    }, ensure_ascii=False) + "\n\n"
+                    sys.stdout.flush()
+
+                    # 如果有 Memory，保存
+                    if memory_data:
+                        path = memory_data.get("file", "")
+                        if path:
+                            existing = [m for m in agent.memories if m.file_path == path]
+                            if existing:
+                                agent.memories.remove(existing[0])
+                            # 使用 src.agent 中定义的 Memory 类
+                            from src.agent import Memory
+                            memory = Memory(
+                                file_path=path,
+                                overview=memory_data.get("overview", ""),
+                                key_definitions=memory_data.get("key_definitions", []),
+                                core_logic=memory_data.get("core_logic", ""),
+                                dependencies=memory_data.get("dependencies", []),
+                                needed_info=memory_data.get("needed_info", "")
+                            )
+                            agent.memories.append(memory)
+
+                    if final_answer:
+                        # 发送最终答案流式输出
+                        for char in final_answer:
+                            yield "data: " + json.dumps({
+                                "type": "chunk",
+                                "step": step,
+                                "content": char,
+                                "stream_type": "answer"
+                            }, ensure_ascii=False) + "\n\n"
+                            sys.stdout.flush()
+
+                        # 发送完成信号
+                        yield "data: " + json.dumps({
+                            "type": "step",
+                            "step": step,
+                            "final_answer": final_answer
+                        }, ensure_ascii=False) + "\n\n"
+                        sys.stdout.flush()
+
+                        yield "data: " + json.dumps({"type": "done"}) + "\n\n"
+                        sys.stdout.flush()
+                        return
+
+                    # 执行工具调用（支持批量）
+                    if actions_list:
+                        # 如果是批量执行
+                        if len(actions_list) > 1:
+                            batch_results = []
+
+                            # 发送批量执行提示
+                            yield "data: " + json.dumps({
+                                "type": "batch_start",
+                                "step": step,
+                                "count": len(actions_list)
+                            }, ensure_ascii=False) + "\n\n"
+                            sys.stdout.flush()
+
+                            # 批量执行所有 Actions
+                            for i, (action, action_args) in enumerate(actions_list, 1):
+                                # 使用 ** 解包字典作为关键字参数
+                                tool_result = agent.tool_executor.execute_tool(action, **action_args)
+                                batch_results.append({
+                                    "index": i,
+                                    "action": f"{action}({format_action_args(action_args)})",
+                                    "result": tool_result
+                                })
+
+                                # 发送单个 Action 结果
+                                yield "data: " + json.dumps({
+                                    "type": "batch_item",
+                                    "step": step,
+                                    "index": i,
+                                    "action": f"{action}({format_action_args(action_args)})",
+                                    "observation": tool_result
+                                }, ensure_ascii=False) + "\n\n"
+                                sys.stdout.flush()
+
+                            # 发送批量完成信号
+                            yield "data: " + json.dumps({
+                                "type": "batch_done",
+                                "step": step,
+                                "results": batch_results
+                            }, ensure_ascii=False) + "\n\n"
+                            sys.stdout.flush()
+
+                            # 将批量观察结果添加到对话
+                            agent.conversation_history.append({
+                                "role": "user",
+                                "content": f"Observation: {json.dumps(batch_results, ensure_ascii=False)}"
+                            })
+                        else:
+                            # 单个 Action
+                            action, action_args = actions_list[0]
+                            tool_result = agent.tool_executor.execute_tool(action, **action_args)
+
+                            # 发送工具调用
+                            yield "data: " + json.dumps({
+                                "type": "step",
+                                "step": step,
+                                "thought": thought,
+                                "action": f"{action}({action_args})",
+                                "observation": tool_result
+                            }, ensure_ascii=False) + "\n\n"
+                            sys.stdout.flush()
+
+                            # 将观察结果添加到对话
+                            agent.conversation_history.append({
+                                "role": "user",
+                                "content": f"Observation: {json.dumps(tool_result, ensure_ascii=False)}"
+                            })
+                
+                # 超时
+                yield "data: " + json.dumps({"type": "done"}) + "\n\n"
+                sys.stdout.flush()
+                
+            except Exception as e:
+                logger.error(f"流式响应错误: {e}")
+                yield "data: " + json.dumps({"type": "error", "error": str(e)}) + "\n\n"
+                sys.stdout.flush()
+            finally:
+                # 保存会话状态
+                save_agent_state(session_id, agent)
+
+        response = Response(generate(), mimetype='text/event-stream')
+        response.headers['Cache-Control'] = 'no-cache'
+        response.headers['X-Accel-Buffering'] = 'no'
+        return response
+    else:
+        # 非流式响应
+        try:
+            agent.stream_output = False
+            agent.ask(question)
+
+            # 保存会话状态
+            save_agent_state(session_id, agent)
+
+            # 构建响应
+            steps = []
+            final_answer = ""
+
+            for step_info in agent.steps:
+                step = {
+                    "step": step_info.get("step"),
+                    "thought": step_info.get("thought", ""),
+                    "action": step_info.get("action_str", ""),
+                    "observation": step_info.get("observation"),
+                    "final_answer": step_info.get("final_answer", "")
+                }
+                steps.append(step)
+
+                if step_info.get("final_answer"):
+                    final_answer = step_info["final_answer"]
+
+            return jsonify({
+                "success": True,
+                "question": question,
+                "answer": final_answer or "未找到答案",
+                "steps": steps
+            })
+        except Exception as e:
+            logger.error(f"响应错误: {e}")
+            return jsonify({"success": False, "error": str(e)}), 500
+
+
+@app.route('/health')
+def health():
+    """健康检查"""
+    return jsonify({"status": "ok", "message": "Read Agent 服务运行中"})
+
+
+@app.route('/status')
+def status():
+    """获取服务状态"""
+    session_id = request.args.get('session_id')
+    agent, _ = get_agent(session_id)
+    stats = agent.get_stats()
+    return jsonify({
+        "status": "running",
+        "stats": stats
+    })
+
+
+# ============ 会话管理 API ============
+
+@app.route('/api/session/clear', methods=['POST'])
+def clear_session():
+    """清除指定会话（线程安全）"""
+    data = request.json or {}
+    session_id = data.get('session_id')
+
+    with sessions_lock:
+        if session_id and session_id in sessions:
+            del sessions[session_id]
+            # 同时删除持久化存储
+            session_storage.delete_session(session_id)
+            return jsonify({
+                "success": True,
+                "message": f"会话已清除: {session_id}"
+            })
+        elif not session_id:
+            # 清除所有会话
+            count = len(sessions)
+            sessions.clear()
+            # 同时清除持久化存储
+            session_storage.clear_all()
+            return jsonify({
+                "success": True,
+                "message": f"已清除 {count} 个会话"
+            })
+        else:
+            return jsonify({
+                "success": False,
+                "error": "会话不存在"
+            }), 404
+
+
+@app.route('/api/session', methods=['GET'])
+def get_or_create_session():
+    """获取或创建会话（前端页面加载时自动调用）"""
+    session_id = request.args.get('session_id')
+    agent, session_id = get_agent(session_id)
+
+    return jsonify({
+        "success": True,
+        "session_id": session_id,
+        "model": agent.model,
+        "code_dir": str(agent.searcher.root_dir),
+        "max_steps": agent.max_steps,
+        "tree_depth": agent.tree_depth
+    })
+
+
+@app.route('/api/session/new', methods=['POST'])
+def new_session():
+    """创建新会话"""
+    _, session_id = get_agent(None)
+    return jsonify({
+        "success": True,
+        "session_id": session_id
+    })
+
+
+@app.route('/api/sessions', methods=['GET'])
+def list_sessions():
+    """列出所有会话（从持久化存储）"""
+    sessions_list = session_storage.list_sessions()
+    return jsonify({
+        "success": True,
+        "sessions": sessions_list,
+        "count": len(sessions_list)
+    })
+
+
+# ============ 仓库管理 API ============
+
+@app.route('/api/repos', methods=['GET'])
+def list_repos():
+    """获取已同步的仓库列表（线程安全）"""
+    repo_manager = get_repo_manager()
+    repos = repo_manager.get_repo_list()
+    return jsonify({
+        "repos": repos,
+        "count": len(repos)
+    })
+
+
+@app.route('/api/repos/sync', methods=['POST'])
+def sync_repos():
+    """手动触发仓库同步（线程安全）"""
+    data = request.json or {}
+    force = data.get('force', False)
+    
+    repo_manager = get_repo_manager()
+    results = repo_manager.sync_all(parallel=True, force=force)
+    return jsonify({
+        "success": results["success"],
+        "skipped": results.get("skipped", []),
+        "failed": results["failed"],
+        "message": f"同步完成: 成功 {len(results['success'])}, 跳过 {len(results.get('skipped', []))}, 失败 {len(results['failed'])}"
+    })
+
+
+@app.route('/api/repos/config', methods=['GET'])
+def get_repo_config():
+    """获取仓库配置（线程安全）"""
+    repo_manager = get_repo_manager()
+    repos = repo_manager.load_from_env()
+    return jsonify({
+        "repos": [
+            {
+                "name": r.name,
+                "url": r.url,
+                "branch": r.branch,
+                "auto_update": r.auto_update
+            }
+            for r in repos
+        ],
+        "count": len(repos)
+    })
+
+
+@app.route('/api/repos/clear', methods=['POST'])
+def clear_repos():
+    """清空所有仓库（线程安全）"""
+    repo_manager = get_repo_manager()
+    count = repo_manager.clear_all()
+    return jsonify({
+        "message": f"已清空 {count} 个仓库",
+        "count": count
+    })
+
+
+# ============ API Key 管理 API ============
+
+@app.route('/api/api-keys/stats', methods=['GET'])
+def get_api_keys_stats():
+    """获取 API Key 统计信息（线程安全）"""
+    key_manager = get_key_manager()
+    if not key_manager:
+        return jsonify({
+            "error": "未配置 API Key"
+        }), 404
+
+    return jsonify(key_manager.get_stats())
+
+
+@app.route('/api/api-keys/reset-stats', methods=['POST'])
+def reset_api_keys_stats():
+    """重置 API Key 统计信息（线程安全）"""
+    key_manager = get_key_manager()
+    if not key_manager:
+        return jsonify({
+            "error": "未配置 API Key"
+        }), 404
+
+    key_manager.reset_stats()
+    return jsonify({
+        "success": True,
+        "message": "统计信息已重置"
+    })
+
+
+# ============ 弹窗管理 API ============
+
+@app.route('/api/popup/config', methods=['GET'])
+def get_popup_config():
+    """获取弹窗配置"""
+    config = load_popup_config()
+
+    if not config:
+        return jsonify({
+            "enabled": False,
+            "message": "弹窗配置未找到"
+        })
+
+    return jsonify({
+        "enabled": config.get("enabled", False),
+        "id": config.get("id", ""),
+        "display": config.get("display", {}),
+        "content": config.get("content", {}),
+        "buttons": config.get("buttons", []),
+        "storage": config.get("storage", {}),
+        "showRules": config.get("showRules", {})
+    })
+
+
+@app.route('/api/popup/reload', methods=['POST'])
+def reload_popup():
+    """重新加载弹窗配置（管理接口）"""
+    try:
+        config = reload_popup_config()
+        return jsonify({
+            "success": True,
+            "message": "弹窗配置已重新加载",
+            "config": config
+        })
+    except Exception as e:
+        logger.error(f"重新加载弹窗配置失败: {e}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+
+def initialize_app():
+    """启动时预初始化全局组件"""
+    global key_manager, repo_manager, _repo_synced
+
+    logger.info("=" * 60)
+    logger.info("Read Agent 初始化中...")
+
+    # 初始化 API Key 管理器
+    logger.info("初始化 API Key 管理器...")
+    key_manager = get_key_manager()
+    if key_manager and key_manager.has_keys:
+        logger.info(f"  ✓ 已加载 {key_manager.key_count} 个 API Key")
+    else:
+        logger.warning("  ⚠ 未配置 API Key")
+
+    # 初始化仓库管理器
+    logger.info("初始化仓库管理器...")
+    repo_manager = get_repo_manager()
+    logger.info(f"  ✓ 代码目录: {repo_manager.base_dir}")
+
+    # 预同步仓库（如果配置启用）
+    sync_on_startup = get_env_bool("REPO_SYNC_ON_STARTUP", True)
+    if sync_on_startup:
+        logger.info("预同步仓库...")
+        results = repo_manager.sync_all(parallel=True)
+        success_count = len(results['success'])
+        skipped_count = len(results.get('skipped', []))
+        failed_count = len(results['failed'])
+        logger.info(f"  ✓ 同步完成: 成功 {success_count}, 跳过 {skipped_count}, 失败 {failed_count}")
+        with _repo_sync_lock:
+            _repo_synced = True
+    else:
+        logger.info("  ✓ 跳过仓库同步 (REPO_SYNC_ON_STARTUP=false)")
+
+    logger.info("=" * 60)
+    logger.info("初始化完成，等待请求...")
+
+
+if __name__ == '__main__':
+    port = int(get_env("WEB_PORT", "7860"))
+    debug = get_env_bool("DEBUG", False)
+
+    # 启动时预初始化
+    initialize_app()
+
+    logger.info(f"启动 Read Agent Web 服务，端口: {port}")
+    logger.info(f"MAX_STEPS={get_env('MAX_STEPS', '10')}")
+    app.run(host='0.0.0.0', port=port, debug=debug)

config/popup.json

@@ -0,0 +1,37 @@
+{
+  "enabled": true,
+  "id": "welcome-popup",
+  "display": {
+    "delay": 500,
+    "autoCloseAfter": 0,
+    "closeOnOutsideClick": true,
+    "closeOnEscapeKey": true,
+    "showCloseButton": true
+  },
+  "content": {
+    "title": "友情链接",
+    "html": "<p>以下是一些优质的公益站点推荐：</p><ul style=\"list-style: none; padding: 0;\"><li style=\"margin-bottom: 10px;\"><a href=\"https://proxy.pieixan.icu/\" target=\"_blank\" style=\"color: var(--primary); text-decoration: none; font-weight: 500;\">🔗 piexian的公益站</a></li><li style=\"margin-bottom: 10px;\"><a href=\"https://91vip.futureppo.top/\" target=\"_blank\" style=\"color: var(--primary); text-decoration: none; font-weight: 500;\">🔗 futureppo的公益站</a></li><li style=\"margin-bottom: 10px;\"><a href=\"https://ai.amethyst.ltd/\" target=\"_blank\" style=\"color: var(--primary); text-decoration: none; font-weight: 500;\">🔗 amethyst的公益站</a></li></ul>",
+    "icon": "fas fa-link"
+  },
+  "buttons": [
+    {
+      "text": "我知道了",
+      "type": "primary",
+      "action": "close"
+    },
+    {
+      "text": "不再显示",
+      "type": "secondary",
+      "action": "dismiss"
+    }
+  ],
+  "storage": {
+    "type": "localStorage",
+    "key": "popup_dismissed",
+    "expiresIn": 0
+  },
+  "showRules": {
+    "maxShows": 0,
+    "frequency": "once"
+  }
+}

docker-compose.yml

@@ -0,0 +1,25 @@
+# Read Agent Docker Compose 配置
+version: '3.8'
+
+services:
+  read-agent:
+    build: .
+    container_name: read-agent-web
+    ports:
+      - "${WEB_PORT:-8080}:8080"
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL}
+      - OPENAI_MODEL=${OPENAI_MODEL}
+      - CODE_DIR=${CODE_DIR:-./code}
+      - MAX_STEPS=${MAX_STEPS:-10}
+      - STREAM_OUTPUT=${STREAM_OUTPUT:-true}
+      - DEBUG=${DEBUG:-false}
+    volumes:
+      - ${CODE_DIR:-./code}:/app/code
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3

main.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+代码阅读智能助手
+
+使用方法：
+    python main.py
+    python main.py --code-dir /path/to/code
+"""
+
+import os
+import sys
+import argparse
+import re
+from pathlib import Path
+
+from src.agent import ReadAgent
+from src.api_key_manager import init_manager, ApiKeyManager
+
+
+def load_env_file(env_path: str = ".env") -> dict:
+    """
+    使用标准库加载 .env 文件
+    """
+    env_vars = {}
+    env_file = Path(env_path)
+
+    if env_file.exists():
+        with open(env_file, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                # 跳过注释和空行
+                if not line or line.startswith("#"):
+                    continue
+                # 解析 KEY=VALUE 格式
+                match = re.match(r'^([A-Za-z_][A-Za-z0-9_]*)=(.*)$', line)
+                if match:
+                    key = match.group(1)
+                    value = match.group(2).strip('"').strip("'")
+                    env_vars[key] = value
+
+    return env_vars
+
+
+def get_env(key: str, default: str = "") -> str:
+    """获取环境变量，优先使用系统环境变量，其次使用 .env 文件"""
+    value = os.getenv(key)
+    if value is not None:
+        return value
+
+    # 尝试从 .env 加载
+    if not hasattr(get_env, "_env_cache"):
+        get_env._env_cache = load_env_file()
+
+    return get_env._env_cache.get(key, default)
+
+
+def get_env_bool(key: str, default: bool = False) -> bool:
+    """获取布尔型环境变量"""
+    value = get_env(key, "").lower()
+    if value in ("true", "1", "yes", "on"):
+        return True
+    elif value in ("false", "0", "no", "off"):
+        return False
+    return default
+
+
+def parse_args():
+    """解析命令行参数"""
+    parser = argparse.ArgumentParser(
+        description="Read Agent - 代码阅读智能助手",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+    python main.py
+    python main.py --code-dir /path/to/your/code
+    python main.py --api-key sk-xxx
+        """
+    )
+    parser.add_argument(
+        "--code-dir", "-d",
+        default=get_env("CODE_DIR", "."),
+        help="代码目录路径 (默认: 当前目录)"
+    )
+    parser.add_argument(
+        "--api-key", "-k",
+        default=get_env("OPENAI_API_KEY", ""),
+        help="OpenAI API Key"
+    )
+    parser.add_argument(
+        "--base-url", "-b",
+        default=get_env("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+        help="API 基础 URL"
+    )
+    parser.add_argument(
+        "--model", "-m",
+        default=get_env("OPENAI_MODEL", "gpt-4"),
+        help="模型名称"
+    )
+    parser.add_argument(
+        "--max-steps", "-s",
+        type=int,
+        default=int(get_env("MAX_STEPS", "10")),
+        help="最大步骤数"
+    )
+    parser.add_argument(
+        "--stream-output", "--stream",
+        action="store_true",
+        default=get_env_bool("STREAM_OUTPUT", True),
+        help="启用流式输出（每步实时显示）"
+    )
+    parser.add_argument(
+        "--no-stream",
+        action="store_true",
+        default=False,
+        help="禁用流式输出"
+    )
+    parser.add_argument(
+        "--tree-depth",
+        type=int,
+        default=int(get_env("TREE_DEPTH", "3")),
+        help="预加载目录树深度（默认: 3）"
+    )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=int(get_env("MAX_RETRIES", "3")),
+        help="API 调用最大重试次数（默认: 3）"
+    )
+    parser.add_argument(
+        "--retry-delays",
+        type=str,
+        default=get_env("RETRY_DELAYS", "1,2,4"),
+        help="重试延迟策略，逗号分隔，单位：秒（默认: 1,2,4）"
+    )
+    return parser.parse_args()
+
+
+def print_welcome():
+    """打印欢迎信息"""
+    print("""
+╔════════════════════════════════════════════════════════════╗
+║                    Read Agent v1.0.0                       ║
+╠════════════════════════════════════════════════════════════╣
+║  命令:                                                     ║
+║    quit / exit / q  - 退出                                 ║
+║    clear              - 清空对话历史                       ║
+║    status             - 查看状态                           ║
+║    help               - 显示帮助                           ║
+╚═══════════════════════════════════════════════════════════��╝
+    """)
+
+
+def print_help():
+    """打印帮助信息"""
+    print("""
+可用命令:
+  quit / exit / q   - 退出程序
+  clear             - 清空对话历史和 Memory
+  status            - 查看当前状态（对话轮数、Memory数量等）
+  help              - 显示此帮助信息
+
+示例问题:
+  🤔 这个项目是做什么的？
+  🤔 用户认证是如何实现的？
+  🤔 找到处理 API 请求的代码
+  🤔 这个函数的作用是什么？
+  🤔 数据库连接是怎么配置的？
+    """)
+
+
+def main():
+    """主函数"""
+    # 解析参数
+    args = parse_args()
+
+    # 初始化 API Key 管理器
+    api_keys = args.api_key or get_env("OPENAI_API_KEY", "")
+    if api_keys:
+        key_manager = init_manager(api_keys)
+        print(f"✅ API Key 管理器已初始化，共 {key_manager.key_count} 个 Key")
+    else:
+        print("❌ 错误: 请设置 OPENAI_API_KEY 环境变量或使用 --api-key 参数")
+        print("\n设置方式:")
+        print("  方式1: echo 'OPENAI_API_KEY=your-api-key' > .env")
+        print("  方式2: export OPENAI_API_KEY=your-api-key")
+        print("  方式3: python main.py --api-key your-api-key")
+        print("\n支持多 key（逗号分隔）:")
+        print("  OPENAI_API_KEY=key1,key2,key3")
+        print("  python main.py --api-key 'key1,key2,key3'")
+        sys.exit(1)
+
+    # 创建 Agent
+    stream_output = args.stream_output and not args.no_stream
+    # 解析重试延迟配置（支持浮点数）
+    retry_delays = [float(d.strip()) for d in args.retry_delays.split(",")] if args.retry_delays else [1, 2, 4]
+
+    agent = ReadAgent(
+        code_dir=args.code_dir,
+        base_url=args.base_url,
+        model=args.model,
+        max_steps=args.max_steps,
+        stream_output=stream_output,
+        tree_depth=args.tree_depth,
+        api_key_manager=key_manager,
+        max_retries=args.max_retries,
+        retry_delays=retry_delays
+    )
+
+    # 打印欢迎信息
+    print_welcome()
+    print(f"📁 代码目录: {agent.searcher.root_dir}")
+    print(f"🤖 使用模型: {agent.model}")
+    print(f"📝 最大步骤: {agent.max_steps}")
+    print(f"🌳 目录树深度: {agent.tree_depth}")
+    print()
+
+    # 初始化提示
+    print("💡 输入问题开始对话，输入 help 查看帮助")
+    print()
+
+    # 主循环
+    while True:
+        try:
+            user_input = input("🤔 ").strip()
+
+            # 处理空输入
+            if not user_input:
+                continue
+
+            # 处理命令
+            if user_input.lower() in ["quit", "exit", "q"]:
+                print("👋 再见！")
+                break
+            elif user_input.lower() == "clear":
+                agent.clear_history()
+                print("✅ 已清空对话历史和 Memory")
+                continue
+            elif user_input.lower() == "status":
+                stats = agent.get_stats()
+                print(f"\n📊 状态统计:")
+                print(f"   对话轮数: {stats['conversation_length']}")
+                print(f"   Memory 数量: {stats['memory_count']}")
+                print(f"   总步骤数: {stats['total_steps']}")
+                print(f"   代码目录: {stats['code_dir']}")
+                continue
+            elif user_input.lower() == "help":
+                print_help()
+                continue
+
+            # 处理问题
+            print()
+            response = agent.ask(user_input)
+            print(response)
+
+        except KeyboardInterrupt:
+            print("\n👋 再见！")
+            break
+        except Exception as e:
+            print(f"\n❌ 错误: {e}")
+            print("💡 提示: 检查 API Key 和网络连接")
+
+
+if __name__ == "__main__":
+    main()

prompts.py

@@ -0,0 +1,273 @@
+"""
+提示词配置 - 包含系统提示词和 Memory 提示词
+"""
+
+import json
+from typing import List, Dict
+
+
+def get_react_format_prompt() -> str:
+    """获取 ReAct 格式说明 prompt（JSON 格式）"""
+    return """你必须按照以下 JSON 格式输出（不要重复这些指令）：
+
+【格式一：单步执行】
+需要读取单个文件或搜索代码时：
+{"thought": "我需要读取 xxx 文件来了解 xxx", "action": {"tool": "read_file", "args": {"path": "xxx/xxx.py"}}}
+
+【格式二：批量执行】
+当你需要同时执行多个相关操作时（如读取多个相关文件）：
+{"thought": "我需要读取这几个文件来了解完整流程", "actions": [{"tool": "read_file", "args": {"path": "xxx/xxx.py"}}, {"tool": "read_file", "args": {"path": "yyy/yyy.py"}}]}
+
+【何时使用批量执行】
+✅ 适用场景：
+- 读取多个相关文件（如同时看配置文件和对应的代码）
+- 搜索多个相关关键词
+- 查看同一目录下的多个文件
+
+❌ 不适用场景：
+- 需要根据前一个文件的结果决定下一步操作
+- 不同操作之间有依赖关系
+
+【已有足够信息回答时】
+{"thought": "我已经收集到足够的信息来回答用户的问题", "final_answer": "这是具体的答案..."}
+
+如果读取了文件，在 final_answer 后添加 memory：
+{"thought": "...", "final_answer": "...", "memory": {"file": "文件路径", "overview": "一句话概述文件功能", "key_definitions": ["关键函数名1", "关键函数名2"], "core_logic": "核心逻辑简述", "dependencies": ["依赖模块1", "依赖模块2"], "needed_info": ""}}
+
+重要规则：
+1. 不要重复或解释这些格式指令
+2. 直接执行，不要说"我将..."或"我打算..."
+3. 使用工具：read_file, find_files, search_code, find_by_ext, list_dir, get_file_info
+4. 批量 actions 中所有操作应该相互独立，不需要等待上一个结果
+5. 必须输出合法的 JSON 格式"""
+
+
+def get_system_prompt(tools_info: List[Dict], max_steps: int = 10, memories: str = "", dir_tree: str = "") -> str:
+    """获取格式化后的系统提示词"""
+    tools_json = json.dumps(tools_info, ensure_ascii=False, indent=2)
+    return f"""## 角色与背景
+你是一个 astrbot 的技术支持助手，专门帮助新手解决问题。你的目标是高效、准确地提供解决方案。
+
+## 核心指令
+1. **时刻记得你的对象是新手**
+2. **参考文档**：你的所有回答都必须严格基于提供的文档知识（不是丢一个文档链接让用户看），不编造不幻觉
+3. **优先Web方案**：尽可能引导用户通过Web管理界面解决问题，因为这对新手更友好。只有当Web界面无法操作时，才提及配置文件或命令
+4. **追问信息**：如果用户信息不足以判断问题，主动索要关键信息（如日志、配置文件、报错截图描述）
+5. **保持质疑**：如果用户的前提不明确或听起来有问题，可以提出质疑。例如，用户说"命令没用"，你可以问"你输入的完整命令是什么？"
+6. **请尽可能建议简单的方案**：如win一键部署等简单方案
+7. **你的能力限制**：你只有对话能力，无法执行命令、安装软件、操作文件系统等
+8. **输出规范**：不要输出混乱的文字，保持回答简洁清晰
+9. **你看到的不能代表用户环境**：你所看到的内容使现场从github拉取下来的，不能够代表用户环境
+
+---
+
+## 搜索规划阶段
+
+**重要：在执行任何文件搜索之前，你必须先构建信息需求树。**
+
+### 需求拆解
+把用户问题拆解成 5 个核心子问题：
+- 子问题1：用户具体想知道什么？
+- 子问题2：需要什么上下文才能回答？
+- 子问题3：有哪些边缘情况需要考虑？
+- 子问题4：依赖哪些其他部分？
+- 子问题5：可能缺失什么信息？
+
+### 术语映射
+列出将帮助搜索的技术术语：
+- 术语1：可能的函数名/类名
+- 术语2：可能的配置键名
+- 术语3：可能出现的错误信息
+
+### 搜索策略
+对每个子问题，列出 3 个具体的搜索方向：
+- 子问题1的搜索方向：
+  * 先找文档说明（docs/、README.md）
+  * 再找配置模板（.env.example、config/）
+  * 最后找代码实现（src/）
+
+### 执行顺序
+按以下优先级执行搜索：
+1. **文档优先** → docs/、README.md、CHANGELOG.md
+2. **配置文件** → config/、.env.example、settings.py
+3. **主入口** → main.py、app.py、index.js
+4. **核心模块** → 具体实现文件
+
+---
+
+## 信息源优先级
+
+当你在多个文件中找到相关信息时，按以下权重处理：
+
+| 层级 | 类型 | 示例 | 权重 |
+|------|------|------|------|
+| Tier 1 | 官方文档 | README.md、docs/、CHANGELOG.md | ★★★★★ |
+| Tier 2 | 配置文件 | .env.example、config/、settings.py | ★★★☆☆ |
+| Tier 3 | 主代码 | main.py、app.py、核���模块 | ★★★☆☆ |
+| Tier 4 | 辅助代码 | 工具函数、测试代码、utils/ | ★★☆☆☆ |
+
+### 冲突解决规则
+- 文档说 A，代码是 B → 明确指出差异，以代码为准，说明文档可能过时
+- 文档说 A，配置默认是 B → 解释差异可能的原因（如版本变化）
+- 多个代码文件不一致 → 追溯调用关系，找到最终执行的位置
+
+---
+
+## 递归验证协议
+
+当你找到信息后，必须执行以下验证：
+
+### 交叉验证
+- 文档说明了，检查代码实现是否一致
+- 代码里这么写，检查测试是否覆盖
+- 配置定义了，检查是否有实际使用
+
+### 发现矛盾时
+- 不要忽视矛盾，标记为"⚠️ 注意：XXX 与 XXX 不一致"
+- 搜索是否有相关的 issue 或说明
+- 根据实际代码行为给出结论，同时说明文档的差异
+
+### 补充验证
+- 如果只看到配置，去搜索实际使用场景
+- 如果只看到函数调用，去搜索函数定义
+- 如果只看到代码片段，搜索完整上下文
+
+### 示例流程
+**用户问**："这个功能怎么用？"
+
+正确的递归搜索：
+1. 找到函数定义
+2. 验证是否有文档说明 → 搜索 docs/
+3. 验证是否有使用示例 → 搜索 tests/
+4. 验证默认配置是什么 → 搜索 .env.example
+5. 综合这些信息回答
+
+---
+
+## 模糊信息处理流程
+
+当用户描述不够具体时：
+
+### 第一步：识别模糊点
+- 用户说"报错了"，但没有说错误消息
+- 用户说"不工作"，没有说具体现象
+- 用户说"配置怎么改"，没有说哪个配置
+
+### 第二步：主动澄清
+在 Final Answer 中明确询问：
+```
+为了准确回答您的问题，我需要更多信息：
+
+1. 错误发生在哪个阶段？
+   - [ ] Docker 启动
+   - [ ] 依赖安装
+   - [ ] 数据库连接
+   - [ ] 服务启动
+
+2. 您看到的错误消息是什么？（请复制粘贴完整错误）
+
+3. 您使用的是什么部署方式？
+   - [ ] docker-compose
+   - [ ] Docker
+   - [ ] 直接运行
+```
+
+### 第三步：模糊搜索（如果用户无法提供）
+- 用关键词模糊搜索相关文件
+- 列出可能匹配的多个选项
+- 让用户确认哪个是正确的
+
+---
+
+## 综合输出格式
+
+当你从多个文件收集到信息后，按以下结构输出：
+
+### 核心答案
+直接回答用户的问题（1-2段话）
+
+### 详细说明
+| 来源 | 内容 | 可信度 |
+|------|------|--------|
+| docs/guide.md | 官方说明... | 高 |
+| config/defaults.py | 默认配置... | 高 |
+| src/core.py | 代码实现... | 中 |
+
+### 注意事项
+- ⚠️ 注意事项1
+- ⚠️ 注意事项2
+
+### 相关文件
+已查看的文件：
+- docs/guide.md:12-18
+- config/defaults.py:45-50
+- src/core.py:123-145
+
+### 后续建议
+如果问题未完全解决：
+- 建议1：检查...
+- 建议2：尝试...
+
+---
+
+## 工作流程
+1. 构建信息需求树（**必须步骤**）
+2. 按优先级执行搜索（文档 → 配置 → 代码）
+3. 交叉验证信息（文档vs代码、测试vs实现）
+4. 观察结果
+5. 如果读取了文件，请在 <final_answer> 后添加该文件的 <memory>
+6. 后续步骤使用 Memory 替代原文，避免上下文膨胀
+7. 综合输出答案
+
+## 可用工具
+{tools_json}
+
+## 输出前的自我检查
+
+在给出 Final Answer 前，问自己：
+
+### 准确性检查
+- [ ] 我的回答直接解决了用户的问题吗？
+- [ ] 我引用的代码行号准确吗？
+- [ ] 我说的配置项确实存在吗？
+
+### 完整性检查
+- [ ] 有没有遗漏重要的前置条件？
+- [ ] 有没有忽略可能的失败原因？
+- [ ] 有没有说明依赖关系？
+
+### 一致性检查
+- [ ] 文档、代码、配置之间有冲突吗？
+- [ ] 如果有冲突，我明确指出了吗？
+
+### 实用性检查
+- [ ] 如果我是用户，看了这个回答能解决问题吗？
+- [ ] 我提供的信息是当前代码库的实际状态吗？
+
+如果有不确定的地方，用 ⚠️ 明确标注。
+
+## 重要规则
+- **必须先构建信息需求树**，再开始搜索
+- 只在当前步骤使用读取的文件原文进行分析
+- 分析完成后在 Final Answer 中生成 Memory（包含文件概述、关键定义、核心逻辑、依赖关系、待验证信息）
+- 不要额外调用 LLM 提取 Memory
+- 后续步骤使用 Memory 替代原文
+- 最多使用 {max_steps} 步完成一个问题
+- 始终用中文回答
+- 回答要简洁明了，优先给出具体步骤
+{memories}{dir_tree}"""
+
+
+def get_answer_prompt(question: str, memories: str, file_contents: str) -> str:
+    """获取格式化后的回答提示词"""
+    return f"""基于以下信息回答用户的问题：
+
+问题：{question}
+
+已收集的 Memory：
+{memories}
+
+原始文件内容：
+{file_contents}
+
+请用清晰、简洁的中文回答问题。如果信息不足，请明确说明需要进一步了解什么。"""

requirements.txt

@@ -0,0 +1,8 @@
+# Read Agent Web 依赖
+flask>=2.3.0
+python-dotenv>=1.0.0
+gunicorn>=21.0.0
+
+# 测试依赖
+pytest>=7.4.0
+pytest-cov>=4.1.0

src/__init__.py

@@ -0,0 +1,5 @@
+"""
+Read Agent - 纯 Python 标准库实现的代码阅读智能助手
+"""
+
+__version__ = "1.0.0"

src/agent.py

@@ -0,0 +1,706 @@
+"""
+Agent 核心逻辑 - 实现 ReAct 模式和 Memory 机制
+"""
+
+import json
+import os
+import re
+from typing import List, Dict, Optional, Any, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from src.searcher import CodeSearcher
+from src.api_key_manager import ApiKeyManager
+from prompts import get_system_prompt, get_react_format_prompt
+
+
+@dataclass
+class Memory:
+    """记忆结构"""
+    file_path: str
+    overview: str = ""
+    key_definitions: List[str] = field(default_factory=list)
+    core_logic: str = ""
+    dependencies: List[str] = field(default_factory=list)
+    needed_info: str = ""
+
+    def to_dict(self) -> Dict:
+        return {
+            "file": self.file_path,
+            "overview": self.overview,
+            "key_definitions": self.key_definitions,
+            "core_logic": self.core_logic,
+            "dependencies": self.dependencies,
+            "needed_info": self.needed_info
+        }
+
+    def to_string(self) -> str:
+        parts = [f"📄 {self.file_path}"]
+        if self.overview:
+            parts.append(f"概述: {self.overview}")
+        if self.key_definitions:
+            parts.append(f"关键定义: {'; '.join(self.key_definitions)}")
+        if self.core_logic:
+            parts.append(f"核心逻辑: {self.core_logic}")
+        if self.dependencies:
+            parts.append(f"依赖: {' -> '.join(self.dependencies)}")
+        if self.needed_info:
+            parts.append(f"待验证: {self.needed_info}")
+        return "\n".join(parts)
+
+
+class ToolExecutor:
+    """工具执行器"""
+
+    def __init__(self, searcher: CodeSearcher):
+        self.searcher = searcher
+        self._tool_registry: Dict[str, Callable] = {}
+
+    def register_tools(self):
+        """注册可用工具"""
+        self._tool_registry = {
+            "read_file": self._read_file,
+            "find_files": self._find_files,
+            "search_code": self._search_code,
+            "find_by_ext": self._find_by_ext,
+            "list_dir": self._list_dir,
+            "get_file_info": self._get_file_info,
+        }
+
+    def execute_tool(self, tool_name: str, **kwargs) -> Dict:
+        """执行工具"""
+        if tool_name not in self._tool_registry:
+            return {"error": f"未知工具: {tool_name}"}
+
+        try:
+            result = self._tool_registry[tool_name](**kwargs)
+            return {"success": True, "tool": tool_name, "result": result}
+        except Exception as e:
+            return {"success": False, "tool": tool_name, "error": str(e)}
+
+    def _read_file(self, path: str, max_lines: int = 500, start_line: int = 1) -> Dict:
+        return self.searcher.read_file(path, max_lines, start_line)
+
+    def _find_files(self, pattern: str = "*", path: str = ".", max_results: int = 20) -> List[str]:
+        return self.searcher.find_files(pattern, path, max_results)
+
+    def _search_code(self, keyword: str, extensions: str = "*", max_results: int = 20) -> List[Dict]:
+        return self.searcher.search_code(keyword, extensions, max_results)
+
+    def _find_by_ext(self, extensions: str = "py", max_results: int = 20) -> List[str]:
+        return self.searcher.find_by_ext(extensions, max_results)
+
+    def _list_dir(self, path: str = ".") -> Dict:
+        return self.searcher.list_dir(path)
+
+    def _get_file_info(self, path: str) -> Dict:
+        return self.searcher.get_file_info(path)
+
+    def get_available_tools(self) -> List[Dict]:
+        """获取可用工具列表"""
+        return [
+            {
+                "name": "read_file",
+                "description": "读取文件内容",
+                "params": {
+                    "path": {"type": "string", "description": "文件路径"},
+                    "max_lines": {"type": "integer", "description": "最大行数", "default": 500},
+                    "start_line": {"type": "integer", "description": "起始行号", "default": 1}
+                }
+            },
+            {
+                "name": "find_files",
+                "description": "按文件名模式查找文件",
+                "params": {
+                    "pattern": {"type": "string", "description": "文件名模式，如 *.py"},
+                    "max_results": {"type": "integer", "description": "最大结果数", "default": 20}
+                }
+            },
+            {
+                "name": "search_code",
+                "description": "搜索代码内容",
+                "params": {
+                    "keyword": {"type": "string", "description": "搜索关键词"},
+                    "extensions": {"type": "string", "description": "文件扩展名", "default": "*"},
+                    "max_results": {"type": "integer", "description": "最大结果数", "default": 20}
+                }
+            },
+            {
+                "name": "find_by_ext",
+                "description": "按扩展名查找文件",
+                "params": {
+                    "extensions": {"type": "string", "description": "扩展名，如 py,js"},
+                    "max_results": {"type": "integer", "description": "最大结果数", "default": 20}
+                }
+            },
+            {
+                "name": "list_dir",
+                "description": "列出目录内容",
+                "params": {
+                    "path": {"type": "string", "description": "目录路径", "default": "."}
+                }
+            },
+            {
+                "name": "get_file_info",
+                "description": "获取文件信息",
+                "params": {
+                    "path": {"type": "string", "description": "文件路径"}
+                }
+            }
+        ]
+
+
+class ReadAgent:
+    """Read Agent 主类"""
+
+    def __init__(
+        self,
+        code_dir: str = "./repos",
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        model: str = "gpt-4",
+        max_steps: int = 10,
+        stream_output: bool = True,
+        tree_depth: int = 3,
+        api_key_manager=None,
+        max_retries: int = None,
+        retry_delays: list = None
+    ):
+        self.searcher = CodeSearcher(code_dir, use_index=True, lazy_index=True)
+        self.tool_executor = ToolExecutor(self.searcher)
+        self.tool_executor.register_tools()
+
+        self.base_url = base_url or os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+        self.model = model or os.getenv("OPENAI_MODEL", "gpt-4")
+        self.max_steps = max_steps
+        self.stream_output = stream_output
+        self.tree_depth = tree_depth
+
+        # 重试配置
+        self.max_retries = max_retries or int(os.getenv("MAX_RETRIES", "3"))
+        self.retry_delays = retry_delays or [float(d.strip()) for d in os.getenv("RETRY_DELAYS", "1,2,4").split(",")]
+
+        # API Key 管理器（支持多 key 随机选择）
+        self.api_key_manager = api_key_manager
+        if self.api_key_manager is None:
+            # 如果没有提供 ApiKeyManager，创建一个单 key 的
+            key = api_key or os.getenv("OPENAI_API_KEY")
+            if key:
+                from src.api_key_manager import ApiKeyManager
+                self.api_key_manager = ApiKeyManager(key)
+            else:
+                self.api_key_manager = None
+                self.api_key = None
+
+        self.conversation_history: List[Dict] = []
+        self.memories: List[Memory] = []
+        self.steps: List[Dict] = []
+
+        # 预加载目录树（延迟化，需要时才生成）
+        self._dir_tree_cached = None
+        self.tree_depth = tree_depth
+
+    def _extract_thought_action(self, response: str) -> tuple:
+        """从响应中提取 Thought 和 Action（JSON 格式）
+
+        Returns:
+            (thought, actions_list) 其中 actions_list 是 [(action_name, args_dict), ...]
+            如果是单个 action，actions_list 长度为 1
+            如果是批量 actions，actions_list 长度 > 1
+            如果没有 action，actions_list 为空列表
+        """
+        import logging
+        logger = logging.getLogger(__name__)
+
+        thought = ""
+        actions_list = []
+
+        # 检查响应是否为空
+        if not response or not response.strip():
+            logger.warning("[_extract_thought_action] LLM 返回空响应")
+            return thought, actions_list
+
+        # 尝试提取 JSON 块
+        json_match = re.search(r'\{.*\}', response, re.DOTALL)
+        if not json_match:
+            logger.warning("[_extract_thought_action] 未能找到 JSON 格式")
+            return thought, actions_list
+
+        try:
+            data = json.loads(json_match.group())
+        except json.JSONDecodeError as e:
+            logger.warning(f"[_extract_thought_action] JSON 解析失败: {e}")
+            return thought, actions_list
+
+        # 提取 thought
+        thought = data.get("thought", "")
+        if len(thought) > 5000:
+            logger.warning(f"[_extract_thought_action] Thought 过长 ({len(thought)} chars)，截断到 5000")
+            thought = thought[:5000]
+
+        valid_tools = set(self.tool_executor._tool_registry.keys())
+
+        # 检查批量 actions
+        if "actions" in data and isinstance(data["actions"], list):
+            for action_item in data["actions"]:
+                tool = action_item.get("tool")
+                args = action_item.get("args", {})
+                if tool and tool in valid_tools:
+                    actions_list.append((tool, args))
+                elif tool:
+                    logger.warning(f"[_extract_thought_action] 未知的 Action: '{tool}'")
+            logger.debug(f"[_extract_thought_action] 批量提取了 {len(actions_list)} 个 Actions")
+        # 检查单个 action
+        elif "action" in data:
+            action_item = data.get("action", {})
+            tool = action_item.get("tool")
+            args = action_item.get("args", {})
+            if tool and tool in valid_tools:
+                actions_list.append((tool, args))
+            elif tool:
+                logger.warning(f"[_extract_thought_action] 未知的 Action: '{tool}'")
+
+        return thought, actions_list
+
+    def _extract_final_answer(self, response: str) -> tuple:
+        """提取最终答案和 Memory（JSON 格式）"""
+        import logging
+        logger = logging.getLogger(__name__)
+
+        answer = ""
+        memory_data = None
+
+        # 检查响应是否为空
+        if not response or not response.strip():
+            logger.warning("[_extract_final_answer] 响应为空")
+            return answer, memory_data
+
+        # 尝试提取 JSON 块
+        json_match = re.search(r'\{.*\}', response, re.DOTALL)
+        if not json_match:
+            logger.warning("[_extract_final_answer] 未能找到 JSON 格式")
+            return answer, memory_data
+
+        try:
+            data = json.loads(json_match.group())
+        except json.JSONDecodeError as e:
+            logger.warning(f"[_extract_final_answer] JSON 解析失败: {e}")
+            return answer, memory_data
+
+        # 提取 final_answer
+        if "final_answer" in data:
+            answer = data.get("final_answer", "")
+            if len(answer) > 10000:
+                logger.warning(f"[_extract_final_answer] Final Answer 过长 ({len(answer)} chars)，截断到 10000")
+                answer = answer[:10000]
+
+        # 提取 memory
+        if "memory" in data:
+            memory = data.get("memory", {})
+            if "file" in memory:
+                memory_data = {
+                    "file": memory.get("file", ""),
+                    "overview": memory.get("overview", ""),
+                    "key_definitions": memory.get("key_definitions", []),
+                    "core_logic": memory.get("core_logic", ""),
+                    "dependencies": memory.get("dependencies", []),
+                    "needed_info": memory.get("needed_info", "")
+                }
+
+        return answer, memory_data
+
+    def _call_llm(self, messages: List[Dict]) -> str:
+        """调用 LLM API（支持流式输出和自动重试）"""
+        import urllib.request
+        import urllib.error
+        import time
+
+        # 使用实例的重试配置
+        max_retries = self.max_retries
+        retry_delays = self.retry_delays
+
+        # 可重试的 HTTP 状态码
+        retryable_status_codes = [401, 429, 500, 502, 503, 504]
+
+        for attempt in range(max_retries):
+            # 从管理器获取 API key（轮询）
+            api_key = None
+            if self.api_key_manager:
+                api_key = self.api_key_manager.get_key()
+            else:
+                api_key = self.api_key
+
+            if not api_key:
+                raise Exception("未配置 API Key")
+
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {api_key}"
+            }
+
+            data = {
+                "model": self.model,
+                "messages": messages,
+                "temperature": 0.3,
+                "stream": True  # 启用流式输出
+            }
+
+            full_content = ""
+            try:
+                req = urllib.request.Request(
+                    f"{self.base_url}/chat/completions",
+                    headers=headers,
+                    data=json.dumps(data).encode("utf-8"),
+                    method="POST"
+                )
+
+                with urllib.request.urlopen(req, timeout=60) as response:
+                    for line in response:
+                        line = line.decode("utf-8").strip()
+                        if not line.startswith("data: "):
+                            continue
+                        if line == "data: [DONE]":
+                            break
+
+                        data_str = line[6:]  # 移除 "data: " 前缀
+                        try:
+                            chunk = json.loads(data_str)
+                            if chunk.get("choices") and len(chunk["choices"]) > 0:
+                                delta = chunk["choices"][0].get("delta", {})
+                                content = delta.get("content", "")
+                                if content:
+                                    # 流式输出思考内容
+                                    if self.stream_output:
+                                        print(content, end="", flush=True)
+                                    full_content += content
+                        except json.JSONDecodeError:
+                            continue
+
+                # 流式输出完成后换行
+                if self.stream_output:
+                    print()
+
+                # 记录成功
+                if self.api_key_manager:
+                    self.api_key_manager.record_success(api_key)
+
+                return full_content
+
+            except urllib.error.HTTPError as e:
+                error_body = e.read().decode("utf-8") if e.fp else ""
+
+                # 检查是否可重试
+                if e.code in retryable_status_codes and attempt < max_retries - 1:
+                    # 记录失败但不立即抛出
+                    if self.api_key_manager:
+                        self.api_key_manager.record_error(api_key, f"HTTP {e.code}: {error_body} (重试 {attempt + 1}/{max_retries})")
+
+                    # 获取延迟（如果超出数组长度，使用最后一个值）
+                    delay = retry_delays[min(attempt, len(retry_delays) - 1)]
+                    if self.stream_output:
+                        print(f"\n\n⏳ API 返回 {e.code}，{delay} 秒后重试... ({attempt + 1}/{max_retries})", flush=True)
+                    else:
+                        import logging
+                        logging.getLogger(__name__).warning(f"API 返回 {e.code}，{delay} 秒后重试... ({attempt + 1}/{max_retries})")
+
+                    time.sleep(delay)
+                    continue
+                else:
+                    # 最后一次重试或不可重试的错误
+                    if self.api_key_manager:
+                        self.api_key_manager.record_error(api_key, f"HTTP {e.code}: {error_body}")
+                    raise Exception(f"API 错误: {e.code} - {error_body}")
+
+            except urllib.error.URLError as e:
+                # 网络错误，可重试
+                if attempt < max_retries - 1:
+                    if self.api_key_manager:
+                        self.api_key_manager.record_error(api_key, f"网络错误: {str(e)} (重试 {attempt + 1}/{max_retries})")
+
+                    # 获取延迟（如果超出数组长度，使用最后一个值）
+                    delay = retry_delays[min(attempt, len(retry_delays) - 1)]
+                    if self.stream_output:
+                        print(f"\n\n⏳ 网络错误，{delay} 秒后重试... ({attempt + 1}/{max_retries})", flush=True)
+                    else:
+                        import logging
+                        logging.getLogger(__name__).warning(f"网络错误，{delay} 秒后重试... ({attempt + 1}/{max_retries})")
+
+                    time.sleep(delay)
+                    continue
+                else:
+                    if self.api_key_manager:
+                        self.api_key_manager.record_error(api_key, f"网络错误: {str(e)}")
+                    raise Exception(f"网络错误: {str(e)}")
+
+            except Exception as e:
+                # 避免在错误信息中泄露敏感信息
+                error_msg = str(e)
+                if "sk-" in error_msg:
+                    error_msg = "API 配置错误: OPENAI_BASE_URL 设置不正确"
+
+                # 记录失败（不重试其他类型的错误）
+                if self.api_key_manager:
+                    self.api_key_manager.record_error(api_key, error_msg)
+                raise Exception(f"请求错误: {error_msg}")
+
+    def _build_system_prompt(self) -> str:
+        """构建系统提示词"""
+        tools_info = self.tool_executor.get_available_tools()
+
+        memories_info = ""
+        if self.memories:
+            memories_info = "\n\n已读取文件的 Memory:\n" + "\n".join(
+                [m.to_string() for m in self.memories]
+            )
+
+        # 目录树信息（延迟化，只在第一次调用时生成）
+        dir_tree_info = ""
+        if self._dir_tree_cached is None and self.tree_depth > 0:
+            # 第一次需要时才生成，之后缓存起来
+            import logging
+            logger = logging.getLogger(__name__)
+            logger.info("正在生成目录树...")
+            self._dir_tree_cached = self.searcher.get_dir_tree(self.tree_depth)
+            logger.info(f"目录树生成完成，共 {len(self._dir_tree_cached)} 个节点")
+        elif self._dir_tree_cached:
+            dir_tree_info = f"\n\n代码目录结构（{self.tree_depth}层）:\n{self._dir_tree_cached}"
+
+        # 使用 prompts.py 中的函数生成系统提示词
+        return get_system_prompt(
+            tools_info=tools_info,
+            max_steps=self.max_steps,
+            memories=memories_info,
+            dir_tree=dir_tree_info
+        )
+
+    def _format_step(self, step: Dict) -> str:
+        """格式化步骤显示（支持批量执行）"""
+        parts = [f"\n🔄 步骤 {step['step']}"]
+
+        if step.get("thought"):
+            parts.append(f"💭 思考: {step['thought']}")
+
+        if step.get("action"):
+            parts.append(f"🔧 行动: {step['action']}")
+
+        # 处理批量执行结果
+        if step.get("batch_results"):
+            parts.append(f"🔧 批量执行完成 ({step['batch_actions']} 个操作)")
+            for item in step['batch_results']:
+                idx = item.get('index', 0)
+                action_str = item.get('action', '')
+                result = item.get('result', {})
+                parts.append(f"  [{idx}] {action_str}")
+                if isinstance(result, dict):
+                    if result.get("success"):
+                        parts.append(f"      ✅ 成功: {str(result.get('result', ''))[:200]}")
+                    else:
+                        parts.append(f"      ❌ 错误: {result.get('error', 'Unknown')}")
+                else:
+                    parts.append(f"      📋 结果: {str(result)[:200]}")
+        elif step.get("observation"):
+            # 单个执行结果
+            obs = step['observation']
+            if isinstance(obs, dict) and not obs.get('batch'):
+                if obs.get("success"):
+                    parts.append(f"✅ 结果: {json.dumps(obs.get('result'), ensure_ascii=False, indent=2)[:500]}")
+                else:
+                    parts.append(f"❌ 错误: {obs.get('error')}")
+            else:
+                parts.append(f"📋 结果: {str(obs)[:500]}")
+
+        return "\n".join(parts)
+
+    def _think_and_act(self, user_question: str) -> str:
+        """思考并执行行动"""
+        # 构建消息
+        messages = [
+            {"role": "system", "content": self._build_system_prompt()}
+        ]
+
+        # 添加对话历史
+        for msg in self.conversation_history:
+            messages.append(msg)
+
+        # 添加当前问题
+        messages.append({
+            "role": "user",
+            "content": f"用户问题：{user_question}\n\n{get_react_format_prompt()}"
+        })
+
+        return self._call_llm(messages)
+
+    def ask(self, question: str) -> str:
+        """
+        询问关于代码库的问题
+
+        Args:
+            question: 用户问题
+
+        Returns:
+            Agent 的回答
+        """
+        self.steps = []
+        self.conversation_history.append({"role": "user", "content": question})
+
+        # 确保索引已构建（首次调用时）
+        self.searcher._ensure_index()
+
+        # 流式模式下输出标题
+        if self.stream_output:
+            print(f"\n{'='*60}")
+            print(f"🤔 问题: {question}")
+            print(f"\n📝 分析过程:")
+
+        for step in range(1, self.max_steps + 1):
+            # 获取思考和行动
+            response = self._think_and_act(question)
+
+            # 记录步骤
+            step_info = {"step": step, "raw_response": response}
+            thought, actions_list = self._extract_thought_action(response)
+            step_info["thought"] = thought
+
+            # 检查是否有最终答案和 Memory
+            final_answer, memory_data = self._extract_final_answer(response)
+
+            # 如果有 Memory，保存到列表
+            if memory_data:
+                path = memory_data.get("file", "")
+                if path:
+                    # 检查是否已存在
+                    existing = [m for m in self.memories if m.file_path == path]
+                    if existing:
+                        self.memories.remove(existing[0])
+                    # 创建新的 Memory 对象
+                    memory = Memory(
+                        file_path=path,
+                        overview=memory_data.get("overview", ""),
+                        key_definitions=memory_data.get("key_definitions", []),
+                        core_logic=memory_data.get("core_logic", ""),
+                        dependencies=memory_data.get("dependencies", []),
+                        needed_info=memory_data.get("needed_info", "")
+                    )
+                    self.memories.append(memory)
+
+            if final_answer:
+                step_info["final_answer"] = final_answer
+                self.steps.append(step_info)
+                self.conversation_history.append({"role": "assistant", "content": final_answer})
+
+                # 流式输出最终答案
+                if self.stream_output:
+                    print(f"\n{'='*60}")
+                    print(f"💡 回答:\n{final_answer}")
+                    return ""
+                else:
+                    return self._format_output(question, final_answer)
+
+            # 执行工具调用（支持批量）
+            # 注意：actions_list 可能是空列表（只有 Thought，没有 Action）
+            if actions_list:
+                # 如果是批量执行
+                if len(actions_list) > 1:
+                    step_info["batch_actions"] = len(actions_list)
+                    step_info["action"] = f"批量执行 {len(actions_list)} 个操作"
+                    batch_results = []
+
+                    # 流式输出批量执行提示
+                    if self.stream_output:
+                        print(f"\n🔄 步骤 {step}")
+                        print(f"💭 思考: {thought}")
+                        print(f"🔧 批量执行 {len(actions_list)} 个操作:")
+
+                    # 批量执行所有 Actions
+                    for i, (action, action_args) in enumerate(actions_list, 1):
+                        tool_result = self.tool_executor.execute_tool(action, **action_args)
+                        batch_results.append({
+                            "index": i,
+                            "action": f"{action}({action_args})",
+                            "result": tool_result
+                        })
+
+                        # 流式输出单个 Action 结果
+                        if self.stream_output:
+                            print(f"  [{i}/{len(actions_list)}] {action}({action_args})")
+                            if tool_result.get("success"):
+                                print(f"    ✅ 完成")
+                            else:
+                                print(f"    ❌ 错误: {tool_result.get('error', 'Unknown')}")
+
+                    step_info["batch_results"] = batch_results
+                    step_info["observation"] = {"batch": True, "results": batch_results}
+
+                    # 将批量观察结果添加到对话（纯文本）
+                    obs_text = "结果: " + "; ".join([
+                        f"{r['action']}: {r['result'].get('success') and '成功' or r['result'].get('error', '完成')}"
+                        for r in batch_results
+                    ])
+                    self.conversation_history.append({
+                        "role": "user",
+                        "content": obs_text
+                    })
+                else:
+                    # 单个 Action
+                    action, action_args = actions_list[0]
+                    step_info["action"] = f"{action}({action_args})"
+                    tool_result = self.tool_executor.execute_tool(action, **action_args)
+                    step_info["observation"] = tool_result
+
+                    # 流式输出当前步骤
+                    if self.stream_output:
+                        print(self._format_step(step_info))
+
+                    # 将观察结果添加到对话（纯文本）
+                    if tool_result.get("success"):
+                        result = tool_result.get("result", "")
+                        obs_text = f"结果: {str(result)[:500]}"
+                    else:
+                        obs_text = f"错误: {tool_result.get('error', '未知错误')}"
+                    self.conversation_history.append({
+                        "role": "user",
+                        "content": obs_text
+                    })
+
+            self.steps.append(step_info)
+
+        # 超时，返回最后的结果
+        if self.stream_output:
+            print(f"\n{'='*60}")
+            print(f"💡 回答:\n已达到最大步骤数限制，请尝试更具体的问题。")
+            return ""
+        else:
+            return self._format_output(question, "已达到最大步骤数限制，请尝试更具体的问题。")
+
+    def _format_output(self, question: str, answer: str) -> str:
+        """格式化输出"""
+        output = [f"\n{'='*60}"]
+        output.append(f"🤔 问题: {question}")
+        output.append(f"\n📝 分析过程:")
+
+        for step_info in self.steps:
+            output.append(self._format_step(step_info))
+
+        output.append(f"\n{'='*60}")
+        output.append(f"💡 回答:\n{answer}")
+
+        return "\n".join(output)
+
+    def clear_memory(self):
+        """清空 Memory"""
+        self.memories = []
+
+    def clear_history(self):
+        """清空对话历史"""
+        self.conversation_history = []
+        self.memories = []
+        self.steps = []
+
+    def get_stats(self) -> Dict:
+        """获取统计信息"""
+        return {
+            "conversation_length": len(self.conversation_history),
+            "memory_count": len(self.memories),
+            "total_steps": len(self.steps),
+            "code_dir": str(self.searcher.root_dir)
+        }

src/api_key_manager.py

@@ -0,0 +1,192 @@
+"""
+API Key Manager - 多Key随机管理器
+支持线程安全的Key随机选择，提供良好的负载分散
+"""
+
+import os
+import random
+import threading
+from typing import List, Optional
+from dataclasses import dataclass, field
+from collections import defaultdict
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class KeyStats:
+    """单个Key的统计信息"""
+    key_hash: str  # Key的hash（用于日志，不泄露真实Key）
+    total_requests: int = 0
+    success_count: int = 0
+    error_count: int = 0
+    last_used: Optional[float] = None
+    last_error: Optional[str] = None
+
+    @property
+    def success_rate(self) -> float:
+        """成功率"""
+        if self.total_requests == 0:
+            return 1.0
+        return self.success_count / self.total_requests
+
+
+class ApiKeyManager:
+    """API Key 管理器 - 支持多Key随机选择"""
+
+    def __init__(self, api_keys: Optional[str | List[str]] = None):
+        """
+        初始化API Key管理器
+
+        Args:
+            api_keys: 可以是单个key、逗号分隔的字符串，或key列表
+        """
+        self._keys: List[str] = []
+        self._lock = threading.Lock()  # 线程安全锁
+        self._stats: dict[str, KeyStats] = {}  # key_hash -> KeyStats
+        self._key_to_hash: dict[str, str] = {}  # key -> key_hash
+
+        # 加载keys
+        if api_keys:
+            self._load_keys(api_keys)
+        else:
+            # 从环境变量加载
+            env_keys = os.getenv("OPENAI_API_KEY", "")
+            if env_keys:
+                self._load_keys(env_keys)
+
+        if not self._keys:
+            logger.warning("未配置任何API Key")
+
+        logger.info(f"API Key管理器初始化完成，共加载 {len(self._keys)} 个Key")
+
+    def _load_keys(self, keys: str | List[str]):
+        """加载API Keys"""
+        if isinstance(keys, str):
+            # 支持逗号分隔的多个key
+            keys_list = [k.strip() for k in keys.split(",") if k.strip()]
+        else:
+            keys_list = keys
+
+        # 去重
+        seen = set()
+        unique_keys = []
+        for key in keys_list:
+            if key and key not in seen:
+                seen.add(key)
+                unique_keys.append(key)
+
+        self._keys = unique_keys
+
+        # 初始化统计信息
+        import time
+        import hashlib
+        for key in self._keys:
+            key_hash = hashlib.sha256(key.encode()).hexdigest()[:8]
+            self._key_to_hash[key] = key_hash
+            self._stats[key_hash] = KeyStats(key_hash=key_hash)
+
+    @property
+    def key_count(self) -> int:
+        """获取Key数量"""
+        return len(self._keys)
+
+    @property
+    def has_keys(self) -> bool:
+        """是否有可用的Key"""
+        return len(self._keys) > 0
+
+    def get_key(self) -> Optional[str]:
+        """
+        获取下一个可用的API Key（随机选择）
+
+        Returns:
+            API Key字符串，如果没有可用Key返回None
+        """
+        if not self._keys:
+            return None
+
+        with self._lock:
+            # 随机选择一个 key
+            key = random.choice(self._keys)
+
+            # 更新统计
+            import time
+            key_hash = self._key_to_hash[key]
+            stats = self._stats[key_hash]
+            stats.total_requests += 1
+            stats.last_used = time.time()
+
+            return key
+
+    def record_success(self, key: str):
+        """记录请求成功"""
+        if key not in self._key_to_hash:
+            return
+
+        with self._lock:
+            key_hash = self._key_to_hash[key]
+            self._stats[key_hash].success_count += 1
+
+    def record_error(self, key: str, error: str):
+        """记录请求失败"""
+        if key not in self._key_to_hash:
+            return
+
+        with self._lock:
+            key_hash = self._key_to_hash[key]
+            stats = self._stats[key_hash]
+            stats.error_count += 1
+            stats.last_error = error[:200]  # 限制错误信息长度
+
+    def get_stats(self) -> dict:
+        """获取所有Key的统计信息"""
+        with self._lock:
+            return {
+                "total_keys": len(self._keys),
+                "keys": [
+                    {
+                        "key_hash": stats.key_hash,
+                        "total_requests": stats.total_requests,
+                        "success_count": stats.success_count,
+                        "error_count": stats.error_count,
+                        "success_rate": f"{stats.success_rate:.2%}",
+                        "last_used": stats.last_used,
+                        "last_error": stats.last_error,
+                    }
+                    for stats in self._stats.values()
+                ],
+            }
+
+    def reset_stats(self):
+        """重置统计信息"""
+        with self._lock:
+            for stats in self._stats.values():
+                stats.total_requests = 0
+                stats.success_count = 0
+                stats.error_count = 0
+                stats.last_used = None
+                stats.last_error = None
+
+
+# 全局单例实例
+_global_manager: Optional[ApiKeyManager] = None
+_global_lock = threading.Lock()
+
+
+def get_global_manager() -> ApiKeyManager:
+    """获取全局单例"""
+    if _global_manager is None:
+        with _global_lock:
+            if _global_manager is None:
+                _global_manager = ApiKeyManager()
+    return _global_manager
+
+
+def init_manager(api_keys: Optional[str | List[str]] = None) -> ApiKeyManager:
+    """初始化全局管理器"""
+    global _global_manager
+    with _global_lock:
+        _global_manager = ApiKeyManager(api_keys)
+    return _global_manager

src/index.py

@@ -0,0 +1,286 @@
+"""
+代码索引 - 提供高性能的代码搜索功能
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+from dataclasses import dataclass, field
+from collections import defaultdict
+import time
+
+
+@dataclass
+class IndexEntry:
+    """索引条目"""
+    file_path: str
+    line: int
+    context: str  # 行内容上下文
+
+
+class CodeIndex:
+    """代码索引器 - 使用倒排索引加速搜索"""
+
+    def __init__(self, root_dir: Path):
+        self.root_dir = root_dir
+        self._keyword_index: Dict[str, List[IndexEntry]] = defaultdict(list)
+        self._symbol_index: Dict[str, List[IndexEntry]] = defaultdict(list)
+        self._indexed_files: Set[str] = set()
+        self._last_build_time = 0
+
+    def build_index(self, extensions: str = "*") -> Dict:
+        """构建或重建索引
+
+        Args:
+            extensions: 要索引的文件扩展名，"*" 表示全部
+
+        Returns:
+            构建统计信息
+        """
+        import os
+
+        start_time = time.time()
+        self._keyword_index.clear()
+        self._symbol_index.clear()
+        self._indexed_files.clear()
+
+        ext_list = extensions.split(',') if extensions != "*" else None
+
+        files_processed = 0
+        files_skipped = 0
+
+        # 使用 os.walk 而不是 Path.rglob 来避免符号链接循环
+        # followlinks=False 表示不跟随符号链接
+        for dirpath, dirnames, filenames in os.walk(self.root_dir, followlinks=False):
+            for filename in filenames:
+                file_path = Path(dirpath) / filename
+
+                # 跳过符号链接文件
+                if file_path.is_symlink():
+                    files_skipped += 1
+                    continue
+
+                if not file_path.is_file():
+                    continue
+
+                # 检查扩展名
+                if ext_list and file_path.suffix.lstrip('.') not in ext_list:
+                    continue
+
+                try:
+                    rel_path = str(file_path.relative_to(self.root_dir))
+                    self._index_file(file_path, rel_path)
+                    files_processed += 1
+                except (ValueError, OSError):
+                    # 处理无法计算相对路径的情况（符号链接到外部）
+                    files_skipped += 1
+                    continue
+
+        build_time = time.time() - start_time
+        self._last_build_time = time.time()
+
+        stats = {
+            "files_processed": files_processed,
+            "files_skipped": files_skipped,
+            "keyword_entries": sum(len(entries) for entries in self._keyword_index.values()),
+            "symbol_entries": sum(len(entries) for entries in self._symbol_index.values()),
+            "unique_keywords": len(self._keyword_index),
+            "unique_symbols": len(self._symbol_index),
+            "build_time_seconds": round(build_time, 2)
+        }
+
+        return stats
+
+    def _index_file(self, file_path: Path, rel_path: str):
+        """索引单个文件"""
+        try:
+            with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                content = f.read()
+
+            lines = content.split('\n')
+
+            # 提取符号（函数、类、变量定义）
+            # Python: def foo(), class Bar:, VAR = value
+            # JavaScript: function foo(), class Bar {}, const x = ...
+            symbol_patterns = [
+                # Python
+                r'\bdef\s+(\w+)\s*\(',
+                r'\bclass\s+(\w+)\s*[:\(]',
+                r'^\s*(\w+)\s*=\s*[\'"\w\[]',
+                # JavaScript/TypeScript
+                r'\bfunction\s+(\w+)\s*\(',
+                r'\bclass\s+(\w+)\s*\{',
+                r'\bconst\s+(\w+)\s*=',
+                r'\blet\s+(\w+)\s*=',
+                r'\bvar\s+(\w+)\s*=',
+            ]
+
+            for i, line in enumerate(lines, 1):
+                # 索引符号
+                for pattern in symbol_patterns:
+                    matches = re.finditer(pattern, line)
+                    for match in matches:
+                        symbol = match.group(1)
+                        self._symbol_index[symbol].append(IndexEntry(
+                            file_path=rel_path,
+                            line=i,
+                            context=line.strip()[:100]
+                        ))
+
+                # 索引关键词
+                # 分词为单词（标识符）和保留部分特殊字符
+                words = self._tokenize(line)
+                for word in words:
+                    if len(word) >= 2:  # 忽略单个字符
+                        self._keyword_index[word].append(IndexEntry(
+                            file_path=rel_path,
+                            line=i,
+                            context=line.strip()[:100]
+                        ))
+
+            self._indexed_files.add(rel_path)
+
+        except Exception:
+            pass
+
+    def _tokenize(self, text: str) -> List[str]:
+        """将文本分词为关键词
+
+        返回标识符、数字和保留特定连接符的词
+        """
+        # 匹配标识符、数字和一些常见的组合词
+        # 包括：snake_case, camelCase, PascalCase, 数字, 单词
+        tokens = []
+
+        # 拆分 camelCase 和 PascalCase
+        # 例如: MyFunction -> My Function
+        def split_camel_case(s):
+            # 在大写字母前插入空格（连续大写作为整体）
+            s1 = re.sub(r'(.)([A-Z][a-z]+)', r'\1 \2', s)
+            return re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', s1)
+
+        # 提取标识符和数字
+        matches = re.finditer(r'\b[a-zA-Z_][a-zA-Z0-9_]*\b|\b\d+\b', text)
+        for match in matches:
+            word = match.group()
+
+            # 拆分驼峰命名
+            subwords = split_camel_case(word).lower().split()
+            tokens.extend(subwords)
+
+        return tokens
+
+    def search_keywords(self, keyword: str, max_results: int = 20) -> List[Dict]:
+        """搜索关键词（使用索引）
+
+        Args:
+            keyword: 搜索关键词
+            max_results: 最大结果数
+
+        Returns:
+            匹配结果列表
+        """
+        # 如果没有构建索引，返回空
+        if not self._keyword_index:
+            return []
+
+        # 分词并搜索
+        keywords = self._tokenize(keyword)
+        if not keywords:
+            return []
+
+        # 收集所有匹配的条目
+        all_entries: List[Tuple[int, IndexEntry]] = []
+
+        for kw in keywords:
+            if kw in self._keyword_index:
+                for entry in self._keyword_index[kw]:
+                    # 计算匹配得分（关键词数量）
+                    score = sum(1 for k in keywords if k in entry.context.lower())
+                    all_entries.append((score, entry))
+
+        # 按得分排序
+        all_entries.sort(key=lambda x: x[0], reverse=True)
+
+        # 去重（同一行只返回一次）
+        seen: Set[Tuple[str, int]] = set()
+        results = []
+
+        for score, entry in all_entries:
+            key = (entry.file_path, entry.line)
+            if key not in seen:
+                seen.add(key)
+                results.append({
+                    "file": entry.file_path,
+                    "line": entry.line,
+                    "content": entry.context,
+                    "score": score
+                })
+                if len(results) >= max_results:
+                    break
+
+        return results
+
+    def search_symbols(self, symbol: str, max_results: int = 20) -> List[Dict]:
+        """搜索符号定义（函数、类、变量）
+
+        Args:
+            symbol: 符号名称
+            max_results: 最大结果数
+
+        Returns:
+            匹配的符号定义
+        """
+        if not self._symbol_index:
+            return []
+
+        results = []
+        seen: Set[Tuple[str, int]] = set()
+
+        # 精确匹配
+        if symbol in self._symbol_index:
+            for entry in self._symbol_index[symbol]:
+                key = (entry.file_path, entry.line)
+                if key not in seen:
+                    seen.add(key)
+                    results.append({
+                        "file": entry.file_path,
+                        "line": entry.line,
+                        "content": entry.context,
+                        "type": "definition"
+                    })
+                    if len(results) >= max_results:
+                        return results
+
+        # 模糊匹配（包含）
+        for sym, entries in self._symbol_index.items():
+            if symbol.lower() in sym.lower():
+                for entry in entries:
+                    key = (entry.file_path, entry.line)
+                    if key not in seen:
+                        seen.add(key)
+                        results.append({
+                            "file": entry.file_path,
+                            "line": entry.line,
+                            "content": entry.context,
+                            "type": "definition"
+                        })
+                        if len(results) >= max_results:
+                            return results
+
+        return results
+
+    def get_stats(self) -> Dict:
+        """获取索引统计信息"""
+        return {
+            "indexed_files": len(self._indexed_files),
+            "keyword_entries": sum(len(entries) for entries in self._keyword_index.values()),
+            "symbol_entries": sum(len(entries) for entries in self._symbol_index.values()),
+            "unique_keywords": len(self._keyword_index),
+            "unique_symbols": len(self._symbol_index),
+            "last_build_time": self._last_build_time
+        }
+
+    def is_built(self) -> bool:
+        """检查索引是否已构建"""
+        return len(self._indexed_files) > 0

src/repo_manager.py

@@ -0,0 +1,310 @@
+"""
+仓库管理器 - 自动下载 Git 仓库
+
+功能：
+- 从环境变量读取仓库列表
+- 自动下载并解压 ZIP 文件
+- 支持多个仓库并行处理
+"""
+
+import os
+import shutil
+import threading
+import zipfile
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import List
+from dataclasses import dataclass
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RepoConfig:
+    """仓库配置"""
+    name: str  # 仓库名称（目录名）
+    url: str  # Git URL (支持 GitHub HTTPS)
+    branch: str = "main"  # 分支名
+    auto_update: bool = True  # 是否自动更新
+
+
+class RepoManager:
+    """仓库管理器"""
+
+    def __init__(self, base_dir: str = "./repos"):
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.repos: List[RepoConfig] = []
+        self._lock = threading.Lock()
+
+    def load_from_env(self):
+        """从环境变量加载仓库配置
+
+        环境变量格式：
+        REPO_URLS=repo1,repo2,repo3
+        REPO_1_URL=https://github.com/user/repo1.git
+        REPO_2_URL=https://github.com/user/repo2.git
+        """
+        self.repos = []
+
+        # 方式1：逗号分隔的 URL 列表
+        repo_urls = os.getenv("REPO_URLS", "")
+        if repo_urls:
+            for url in repo_urls.split(","):
+                url = url.strip()
+                if url:
+                    name = self._extract_repo_name(url)
+                    self.repos.append(RepoConfig(name=name, url=url))
+
+        # 方式2：带编号的配置
+        idx = 1
+        while True:
+            url_key = f"REPO_{idx}_URL"
+            url = os.getenv(url_key, "")
+            if not url:
+                break
+
+            name = os.getenv(f"REPO_{idx}_NAME", "")
+            if not name:
+                name = self._extract_repo_name(url)
+
+            branch = os.getenv(f"REPO_{idx}_BRANCH", "main")
+            auto_update = os.getenv(f"REPO_{idx}_AUTO_UPDATE", "true").lower() == "true"
+
+            self.repos.append(RepoConfig(
+                name=name,
+                url=url,
+                branch=branch,
+                auto_update=auto_update
+            ))
+
+            idx += 1
+
+        logger.info(f"加载了 {len(self.repos)} 个仓库配置")
+        return self.repos
+
+    def _extract_repo_name(self, url: str) -> str:
+        """从 URL 提取仓库名称"""
+        # 统一处理 URL
+        url = url.replace("git@github.com:", "https://github.com/")
+        url = url.rstrip("/")
+
+        # 提取最后一部分
+        if "/" in url:
+            name = url.split("/")[-1]
+            # 去除 .git 后缀
+            if name.endswith(".git"):
+                name = name[:-4]
+            return name
+        return url
+
+    def _get_repo_dir(self, name: str) -> Path:
+        """获取仓库目录路径"""
+        return self.base_dir / name
+
+    def _get_zip_url(self, url: str, branch: str) -> str:
+        """将 Git URL 转换为 ZIP 下载 URL"""
+        # git@github.com:user/repo.git -> https://github.com/user/repo/archive/refs/heads/branch.zip
+        # https://github.com/user/repo.git -> https://github.com/user/repo/archive/refs/heads/branch.zip
+
+        url = url.replace("git@github.com:", "https://github.com/")
+        url = url.removesuffix(".git")
+
+        # 提取 owner/repo
+        parts = url.rstrip("/").split("/")
+        if len(parts) >= 2:
+            owner = parts[-2]
+            repo = parts[-1]
+            return f"https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.zip"
+
+        raise ValueError(f"无法解析仓库 URL: {url}")
+
+    def download_repo(self, repo: RepoConfig, force: bool = False) -> bool:
+        """下载并解压仓库
+        
+        Args:
+            repo: 仓库配置
+            force: 是否强制重新下载
+        
+        Returns:
+            bool: 是否成功
+        """
+        repo_dir = self._get_repo_dir(repo.name)
+        
+        # 检查仓库是否已存在且有效（无需重新下载）
+        if not force and repo_dir.exists() and any(repo_dir.iterdir()):
+            logger.info(f"仓库已存在，跳过下载: {repo.name}")
+            return True
+
+        try:
+            # 删除已存在的目录
+            if repo_dir.exists():
+                logger.info(f"删除旧版本: {repo.name}")
+                shutil.rmtree(repo_dir)
+
+            repo_dir.mkdir(parents=True, exist_ok=True)
+
+            # 下载 ZIP
+            zip_url = self._get_zip_url(repo.url, repo.branch)
+            zip_path = repo_dir / "repo.zip"
+
+            logger.info(f"下载仓库: {repo.name} ({zip_url})")
+
+            headers = {"User-Agent": "Mozilla/5.0"}
+            req = urllib.request.Request(zip_url, headers=headers)
+
+            with urllib.request.urlopen(req, timeout=120) as response:
+                with open(zip_path, 'wb') as f:
+                    f.write(response.read())
+
+            # 解压
+            logger.info(f"解压仓库: {repo.name}")
+            with zipfile.ZipFile(zip_path, 'r') as zip_ref:
+                zip_ref.extractall(repo_dir)
+
+            # ZIP 包会多一层目录，需要移动内容
+            extracted_dir = repo_dir / f"{repo.name}-{repo.branch}"
+            if extracted_dir.exists():
+                for item in extracted_dir.iterdir():
+                    item.rename(repo_dir / item.name)
+                extracted_dir.rmdir()
+
+            # 删除 ZIP 文件
+            zip_path.unlink()
+
+            logger.info(f"仓库 {repo.name} 下载成功")
+            return True
+
+        except Exception as e:
+            logger.error(f"下载仓库 {repo.name} 失败: {e}")
+            # 清理失败的目录
+            if repo_dir.exists():
+                shutil.rmtree(repo_dir)
+            return False
+
+    def sync_all(self, parallel: bool = True, force: bool = False) -> dict:
+        """同步所有仓库
+        
+        Args:
+            parallel: 是否并行下载
+            force: 是否强制重新下载所有仓库
+        
+        Returns:
+            dict: { "success": [成功列表], "skipped": [跳过列表], "failed": [失败列表] }
+        """
+        if not self.repos:
+            self.load_from_env()
+
+        if not self.repos:
+            logger.warning("没有配置任何仓库")
+            return {"success": [], "skipped": [], "failed": []}
+
+        results = {"success": [], "skipped": [], "failed": []}
+
+        if parallel:
+            # 并行下载
+            threads = []
+            for repo in self.repos:
+                t = threading.Thread(target=self._sync_single, args=(repo, results, force))
+                t.start()
+                threads.append(t)
+
+            for t in threads:
+                t.join()
+        else:
+            # 顺序下载
+            for repo in self.repos:
+                self._sync_single(repo, results, force)
+
+        logger.info(f"仓库同步完成: 成功 {len(results['success'])}, 跳过 {len(results['skipped'])}, 失败 {len(results['failed'])}")
+        return results
+
+    def _sync_single(self, repo: RepoConfig, results: dict, force: bool = False):
+        """同步单个仓库（线程安全）"""
+        # 先检查是否已存在且有效（非强制模式）
+        if not force:
+            repo_dir = self._get_repo_dir(repo.name)
+            if repo_dir.exists() and any(repo_dir.iterdir()):
+                with self._lock:
+                    results["skipped"].append(repo.name)
+                return
+        
+        if self.download_repo(repo, force):
+            with self._lock:
+                results["success"].append(repo.name)
+        else:
+            with self._lock:
+                results["failed"].append(repo.name)
+
+    def get_repo_list(self) -> List[dict]:
+        """获取已下载的仓库列表"""
+        repos = []
+        for item in self.base_dir.iterdir():
+            if item.is_dir():
+                repos.append({
+                    "name": item.name,
+                    "path": str(item)
+                })
+        return repos
+
+    def remove_repo(self, name: str) -> bool:
+        """删除仓库"""
+        repo_dir = self._get_repo_dir(name)
+        if repo_dir.exists():
+            try:
+                shutil.rmtree(repo_dir)
+                logger.info(f"删除仓库: {name}")
+                return True
+            except Exception as e:
+                logger.error(f"删除仓库 {name} 失败: {e}")
+                return False
+        return False
+
+    def clear_all(self) -> int:
+        """清空所有仓库"""
+        count = 0
+        for item in self.base_dir.iterdir():
+            if item.is_dir():
+                try:
+                    shutil.rmtree(item)
+                    count += 1
+                except Exception as e:
+                    logger.warning(f"删除 {item.name} 失败: {e}")
+        logger.info(f"清空仓库: 删除 {count} 个")
+        return count
+
+
+def sync_repos_on_startup():
+    """启动时同步仓库"""
+    manager = RepoManager()
+    repos = manager.load_from_env()
+
+    if repos:
+        logger.info(f"启动同步 {len(repos)} 个仓库...")
+        results = manager.sync_all(parallel=True)
+        return results
+    else:
+        logger.info("未配置仓库，跳过同步")
+        return {"success": [], "failed": []}
+
+
+if __name__ == "__main__":
+    # 测试
+    logging.basicConfig(level=logging.INFO)
+
+    # 示例：设置环境变量后测试
+    os.environ["REPO_1_URL"] = "https://github.com/psyche/astronomy.git"
+    os.environ["REPO_1_NAME"] = "astronomy"
+    os.environ["REPO_1_BRANCH"] = "main"
+
+    manager = RepoManager("./test-code")
+    manager.load_from_env()
+
+    print(f"配置了 {len(manager.repos)} 个仓库:")
+    for repo in manager.repos:
+        print(f"  - {repo.name}: {repo.url}")
+
+    results = manager.sync_all()
+    print(f"\n同步结果: 成功 {len(results['success'])}, 失败 {len(results['failed'])}")

src/searcher.py

@@ -0,0 +1,257 @@
+"""
+代码搜索器 - 提供文件搜索和读取功能
+"""
+
+import os
+import glob
+import re
+import time
+import threading
+from pathlib import Path
+from typing import List, Dict, Optional
+
+from src.index import CodeIndex
+
+# 全局目录树缓存
+_dir_tree_cache: Dict[str, tuple] = {}  # {cache_key: (tree, timestamp)}
+_dir_tree_lock = threading.Lock()
+_CACHE_TTL = 3600  # 缓存有效期（秒）
+
+
+class CodeSearcher:
+    """初始化代码搜索器
+    
+    Args:
+        root_dir: 代码根目录
+        use_index: 是否使用索引
+        lazy_index: 是否延迟构建索引（首次使用时才构建）
+    """
+    def __init__(self, root_dir: str, use_index: bool = True, lazy_index: bool = False):
+        self.root_dir = Path(root_dir).resolve()
+        self.use_index = use_index
+        self.index: Optional[CodeIndex] = None
+
+        if use_index:
+            self.index = CodeIndex(self.root_dir)
+            if not lazy_index:
+                # 立即构建索引
+                self._build_index()
+            else:
+                # 延迟构建索引，在第一次调用时才构建
+                self._index_built = False
+
+    def _build_index(self, extensions: str = "*") -> Dict:
+        """构建代码索引"""
+        if not self.index:
+            return {"error": "索引未启用"}
+
+        return self.index.build_index(extensions)
+
+    def rebuild_index(self, extensions: str = "*") -> Dict:
+        """重建索引（强制）"""
+        self._index_built = True  # 重置延迟标志
+        return self._build_index(extensions)
+
+    def _ensure_index(self, extensions: str = "*") -> Dict:
+        """确保索引已构建（如果是首次则构建）"""
+        if not self._index_built:
+            return self._build_index(extensions)
+        return {"status": "索引已构建"}
+    
+    def read_file(self, path: str, max_lines: int = 500, start_line: int = 1) -> Dict:
+        """读取文件内容"""
+        try:
+            file_path = self.root_dir / path
+            if not file_path.exists():
+                return {"error": f"文件不存在: {path}"}
+            
+            with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                lines = f.readlines()
+            
+            total_lines = len(lines)
+            end_line = min(start_line + max_lines - 1, total_lines)
+            content = ''.join(lines[start_line-1:end_line])
+            
+            return {
+                "path": str(file_path.relative_to(self.root_dir)),
+                "total_lines": total_lines,
+                "start_line": start_line,
+                "end_line": end_line,
+                "content": content
+            }
+        except Exception as e:
+            return {"error": str(e)}
+    
+    def find_files(self, pattern: str = "*", path: str = ".", max_results: int = 20) -> List[str]:
+        """按文件名模式查找文件"""
+        try:
+            search_dir = self.root_dir / path
+            if not search_dir.exists():
+                return [f"错误: 路径不存在: {path}"]
+            matches = list(search_dir.glob(pattern))
+            results = []
+            for m in matches[:max_results]:
+                if m.is_file():
+                    results.append(str(m.relative_to(self.root_dir)))
+            return results
+        except Exception as e:
+            return [f"错误: {str(e)}"]
+    
+    def search_code(self, keyword: str, extensions: str = "*", max_results: int = 20) -> List[Dict]:
+        """搜索代码内容（优先使用索引）"""
+        # 如果启用了索引且索引已构建，使用索引搜索
+        if self.use_index and self.index and self.index.is_built():
+            try:
+                # 尝试判断是否为符号搜索
+                # 如果是单个单词且匹配符号模式，使用符号索引
+                if re.match(r'^\w+$', keyword):
+                    symbol_results = self.index.search_symbols(keyword, max_results)
+                    if symbol_results:
+                        return symbol_results
+
+                # 使用关键词索引
+                return self.index.search_keywords(keyword, max_results)
+            except Exception as e:
+                # 索引搜索失败，回退到线性扫描
+                pass
+
+        # 线性扫描（回退方案）
+        results = []
+        ext_list = extensions.split(',') if extensions != "*" else None
+
+        try:
+            for file_path in self.root_dir.rglob("*"):
+                if file_path.is_file():
+                    # 检查扩展名
+                    if ext_list and file_path.suffix.lstrip('.') not in ext_list:
+                        continue
+
+                    try:
+                        with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                            content = f.read()
+
+                        lines = content.split('\n')
+                        for i, line in enumerate(lines, 1):
+                            if re.search(keyword, line):
+                                results.append({
+                                    "file": str(file_path.relative_to(self.root_dir)),
+                                    "line": i,
+                                    "content": line.strip()
+                                })
+                                if len(results) >= max_results:
+                                    return results
+                    except Exception:
+                        continue
+        except Exception as e:
+            return [{"error": str(e)}]
+
+        return results
+    
+    def find_by_ext(self, extensions: str = "py", max_results: int = 20) -> List[str]:
+        """按扩展名查找文件"""
+        results = []
+        ext_list = [e.strip() for e in extensions.split(',')]
+        
+        try:
+            for file_path in self.root_dir.rglob("*"):
+                if file_path.is_file() and file_path.suffix.lstrip('.') in ext_list:
+                    results.append(str(file_path.relative_to(self.root_dir)))
+                    if len(results) >= max_results:
+                        break
+        except Exception as e:
+            return [f"错误: {str(e)}"]
+        
+        return results
+    
+    def list_dir(self, path: str = ".") -> Dict:
+        """列出目录内容"""
+        try:
+            # 处理 path 参数，避免 JSON 双重序列化问题
+            if isinstance(path, dict):
+                # 如果 path 已经是 dict（被 JSON 序列化过了），直接使用
+                path = path.get('path', path)
+                logger.debug(f"[list_dir] path 参数已经是 dict: {path}")
+
+            dir_path = self.root_dir / path
+            if not dir_path.exists():
+                return {"error": f"目录不存在: {path}"}
+            
+            items = []
+            for item in dir_path.iterdir():
+                items.append({
+                    "name": item.name,
+                    "type": "directory" if item.is_dir() else "file",
+                    "path": str(item.relative_to(self.root_dir))
+                })
+            
+            return {
+                "path": str(dir_path.relative_to(self.root_dir)),
+                "items": items
+            }
+        except Exception as e:
+            return {"error": str(e)}
+    
+    def get_file_info(self, path: str) -> Dict:
+        """获取文件信息"""
+        try:
+            file_path = self.root_dir / path
+            if not file_path.exists():
+                return {"error": f"文件不存在: {path}"}
+
+            stat = file_path.stat()
+            return {
+                "path": str(file_path.relative_to(self.root_dir)),
+                "name": file_path.name,
+                "size": stat.st_size,
+                "created": stat.st_ctime,
+                "modified": stat.st_mtime,
+                "extension": file_path.suffix
+            }
+        except Exception as e:
+            return {"error": str(e)}
+
+    def get_dir_tree(self, max_depth: int = 3) -> str:
+        """获取目录树结构（使用全局缓存）
+
+        Args:
+            max_depth: 最大深度，0 表示不限制
+
+        Returns:
+            目录树字符串
+        """
+        cache_key = f"{self.root_dir}:{max_depth}"
+        current_time = time.time()
+
+        # 检查缓存
+        with _dir_tree_lock:
+            if cache_key in _dir_tree_cache:
+                tree, timestamp = _dir_tree_cache[cache_key]
+                if current_time - timestamp < _CACHE_TTL:
+                    return tree
+
+        # 生成新的目录树
+        lines = []
+        self._build_tree(self.root_dir, "", 0, max_depth, lines)
+        tree = "\n".join(lines)
+
+        # 缓存结果
+        with _dir_tree_lock:
+            _dir_tree_cache[cache_key] = (tree, current_time)
+
+        return tree
+
+    def _build_tree(self, path: Path, prefix: str, depth: int, max_depth: int, lines: List[str]):
+        """递归构建目录树"""
+        try:
+            items = sorted(path.iterdir(), key=lambda x: (not x.is_dir(), x.name))
+        except Exception:
+            return
+
+        for i, item in enumerate(items):
+            is_last = i == len(items) - 1
+            current_prefix = "└── " if is_last else "├── "
+            lines.append(f"{prefix}{current_prefix}{item.name}")
+
+            if item.is_dir() and (max_depth == 0 or depth < max_depth - 1):
+                next_prefix = prefix + ("    " if is_last else "│   ")
+                self._build_tree(item, next_prefix, depth + 1, max_depth, lines)

src/session_storage.py

@@ -0,0 +1,375 @@
+"""
+会话持久化存储
+
+使用 SQLite 存储会话状态，支持服务器重启后恢复会话
+"""
+
+import sqlite3
+import json
+import threading
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SessionStorage:
+    """会话存储管理器"""
+
+    def __init__(self, db_path: str = "./sessions.db"):
+        """
+        初始化会话存储
+
+        Args:
+            db_path: SQLite 数据库文件路径
+        """
+        self.db_path = Path(db_path)
+        self._lock = threading.Lock()
+
+        # 确保数据库目录存在
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 初始化数据库表
+        self._init_db()
+
+    def _init_db(self):
+        """初始化数据库表结构"""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+
+            # 会话表：存储会话元数据和配置
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS sessions (
+                    session_id TEXT PRIMARY KEY,
+                    model TEXT NOT NULL,
+                    base_url TEXT NOT NULL,
+                    code_dir TEXT NOT NULL,
+                    max_steps INTEGER NOT NULL,
+                    stream_output INTEGER NOT NULL,
+                    tree_depth INTEGER NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL,
+                    last_active TEXT
+                )
+            """)
+
+            # 对话历史表：存储会话的对话记录
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS conversation_history (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    role TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    FOREIGN KEY (session_id) REFERENCES sessions (session_id) ON DELETE CASCADE
+                )
+            """)
+
+            # 记忆表：存储 Memory 对象
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    overview TEXT,
+                    key_definitions TEXT,  -- JSON 数组
+                    core_logic TEXT,
+                    dependencies TEXT,  -- JSON 数组
+                    needed_info TEXT,
+                    FOREIGN KEY (session_id) REFERENCES sessions (session_id) ON DELETE CASCADE
+                )
+            """)
+
+            # 创建索引
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_session_conversation
+                ON conversation_history (session_id)
+            """)
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_session_memories
+                ON memories (session_id)
+            """)
+
+            conn.commit()
+
+    def save_session(
+        self,
+        session_id: str,
+        model: str,
+        base_url: str,
+        code_dir: str,
+        max_steps: int,
+        stream_output: bool,
+        tree_depth: int,
+        conversation_history: List[Dict],
+        memories: List[Dict]
+    ) -> bool:
+        """
+        保存会话完整状态
+
+        Args:
+            session_id: 会话ID
+            model: LLM 模型名称
+            base_url: API 基础URL
+            code_dir: 代码目录
+            max_steps: 最大步骤数
+            stream_output: 是否流式输出
+            tree_depth: 目录树深度
+            conversation_history: 对话历史列表
+            memories: Memory 对象列表
+
+        Returns:
+            是否保存成功
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    cursor = conn.cursor()
+                    now = datetime.now().isoformat()
+
+                    # 检查会话是否已存在
+                    cursor.execute("SELECT session_id FROM sessions WHERE session_id = ?", (session_id,))
+                    exists = cursor.fetchone() is not None
+
+                    # 更新或插入会话元数据
+                    if exists:
+                        cursor.execute("""
+                            UPDATE sessions
+                            SET model = ?, base_url = ?, code_dir = ?,
+                                max_steps = ?, stream_output = ?, tree_depth = ?,
+                                updated_at = ?, last_active = ?
+                            WHERE session_id = ?
+                        """, (
+                            model, base_url, code_dir,
+                            max_steps, 1 if stream_output else 0, tree_depth,
+                            now, now, session_id
+                        ))
+                    else:
+                        cursor.execute("""
+                            INSERT INTO sessions
+                            (session_id, model, base_url, code_dir, max_steps,
+                             stream_output, tree_depth, created_at, updated_at, last_active)
+                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        """, (
+                            session_id, model, base_url, code_dir, max_steps,
+                            1 if stream_output else 0, tree_depth, now, now, now
+                        ))
+
+                    # 删除旧的对话历史和记忆
+                    cursor.execute("DELETE FROM conversation_history WHERE session_id = ?", (session_id,))
+                    cursor.execute("DELETE FROM memories WHERE session_id = ?", (session_id,))
+
+                    # 插入对话历史
+                    for msg in conversation_history:
+                        cursor.execute("""
+                            INSERT INTO conversation_history (session_id, role, content)
+                            VALUES (?, ?, ?)
+                        """, (session_id, msg["role"], msg["content"]))
+
+                    # 插入记忆
+                    for memory in memories:
+                        cursor.execute("""
+                            INSERT INTO memories
+                            (session_id, file_path, overview, key_definitions,
+                             core_logic, dependencies, needed_info)
+                            VALUES (?, ?, ?, ?, ?, ?, ?)
+                        """, (
+                            session_id,
+                            memory["file"],
+                            memory.get("overview", ""),
+                            json.dumps(memory.get("key_definitions", []), ensure_ascii=False),
+                            memory.get("core_logic", ""),
+                            json.dumps(memory.get("dependencies", []), ensure_ascii=False),
+                            memory.get("needed_info", "")
+                        ))
+
+                    conn.commit()
+                    logger.debug(f"[SessionStorage] 保存会话: {session_id}")
+                    return True
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 保存会话失败: {e}")
+                return False
+
+    def load_session(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """
+        加载会话状态
+
+        Args:
+            session_id: 会话ID
+
+        Returns:
+            会话数据字典，如果不存在返回 None
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    conn.row_factory = sqlite3.Row
+                    cursor = conn.cursor()
+
+                    # 查询会话元数据
+                    cursor.execute("""
+                        SELECT * FROM sessions WHERE session_id = ?
+                    """, (session_id,))
+                    session_row = cursor.fetchone()
+
+                    if not session_row:
+                        return None
+
+                    # 加载对话历史
+                    cursor.execute("""
+                        SELECT role, content FROM conversation_history
+                        WHERE session_id = ? ORDER BY id
+                    """, (session_id,))
+                    conversation_history = [
+                        {"role": row["role"], "content": row["content"]}
+                        for row in cursor.fetchall()
+                    ]
+
+                    # 加载记忆
+                    cursor.execute("""
+                        SELECT * FROM memories WHERE session_id = ?
+                    """, (session_id,))
+                    memories = [
+                        {
+                            "file_path": row["file_path"],
+                            "overview": row["overview"],
+                            "key_definitions": json.loads(row["key_definitions"]) if row["key_definitions"] else [],
+                            "core_logic": row["core_logic"],
+                            "dependencies": json.loads(row["dependencies"]) if row["dependencies"] else [],
+                            "needed_info": row["needed_info"]
+                        }
+                        for row in cursor.fetchall()
+                    ]
+
+                    return {
+                        "session_id": session_row["session_id"],
+                        "model": session_row["model"],
+                        "base_url": session_row["base_url"],
+                        "code_dir": session_row["code_dir"],
+                        "max_steps": session_row["max_steps"],
+                        "stream_output": bool(session_row["stream_output"]),
+                        "tree_depth": session_row["tree_depth"],
+                        "created_at": session_row["created_at"],
+                        "updated_at": session_row["updated_at"],
+                        "last_active": session_row["last_active"],
+                        "conversation_history": conversation_history,
+                        "memories": memories
+                    }
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 加载会话失败: {e}")
+                return None
+
+    def delete_session(self, session_id: str) -> bool:
+        """
+        删除会话
+
+        Args:
+            session_id: 会话ID
+
+        Returns:
+            是否删除成功
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    cursor = conn.cursor()
+                    cursor.execute("DELETE FROM sessions WHERE session_id = ?", (session_id,))
+                    conn.commit()
+                    logger.debug(f"[SessionStorage] 删除会话: {session_id}")
+                    return cursor.rowcount > 0
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 删除会话失败: {e}")
+                return False
+
+    def list_sessions(self) -> List[Dict[str, Any]]:
+        """
+        列出所有会话（不含详细内容）
+
+        Returns:
+            会话列表
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    conn.row_factory = sqlite3.Row
+                    cursor = conn.cursor()
+
+                    cursor.execute("""
+                        SELECT session_id, model, code_dir, created_at, updated_at, last_active,
+                               (SELECT COUNT(*) FROM conversation_history WHERE session_id = s.session_id) as message_count,
+                               (SELECT COUNT(*) FROM memories WHERE session_id = s.session_id) as memory_count
+                        FROM sessions s
+                        ORDER BY updated_at DESC
+                    """)
+
+                    return [
+                        {
+                            "session_id": row["session_id"],
+                            "model": row["model"],
+                            "code_dir": row["code_dir"],
+                            "created_at": row["created_at"],
+                            "updated_at": row["updated_at"],
+                            "last_active": row["last_active"],
+                            "message_count": row["message_count"],
+                            "memory_count": row["memory_count"]
+                        }
+                        for row in cursor.fetchall()
+                    ]
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 列出会话失败: {e}")
+                return []
+
+    def clear_all(self) -> bool:
+        """
+        清空所有会话
+
+        Returns:
+            是否清空成功
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    cursor = conn.cursor()
+                    cursor.execute("DELETE FROM sessions")
+                    conn.commit()
+                    logger.info(f"[SessionStorage] 清空所有会话")
+                    return True
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 清空会话失败: {e}")
+                return False
+
+    def cleanup_old_sessions(self, days: int = 30) -> int:
+        """
+        清理超过指定天数未活跃的会话
+
+        Args:
+            days: 天数阈值
+
+        Returns:
+            删除的会话数
+        """
+        with self._lock:
+            try:
+                with sqlite3.connect(self.db_path) as conn:
+                    cursor = conn.cursor()
+
+                    # 删除超过 N 天未活跃的会话
+                    cursor.execute("""
+                        DELETE FROM sessions
+                        WHERE datetime(last_active) < datetime('now', '-' || ? || ' days')
+                    """, (days,))
+
+                    count = cursor.rowcount
+                    conn.commit()
+                    logger.info(f"[SessionStorage] 清理了 {count} 个旧会话")
+                    return count
+
+            except Exception as e:
+                logger.error(f"[SessionStorage] 清理旧会话失败: {e}")
+                return 0

static/index.html

@@ -0,0 +1,1337 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>astrbot-问题帮助助手</title>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+    <style>
+        :root {
+            --primary: #4361ee;
+            --primary-light: #4895ef;
+            --secondary: #3f37c9;
+            --accent: #f72585;
+            --light: #ffffff;
+            --light-gray: #f8f9fa;
+            --gray: #e9ecef;
+            --dark-gray: #6c757d;
+            --dark: #212529;
+            --shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+            --shadow-hover: 0 8px 24px rgba(0, 0, 0, 0.12);
+        }
+
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+            font-family: 'Inter', 'Segoe UI', 'Microsoft YaHei', sans-serif;
+        }
+
+        body {
+            background: linear-gradient(135deg, #f5f7fa 0%, #e4edf5 100%);
+            color: var(--dark);
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            padding: 20px;
+        }
+
+        .container {
+            max-width: 900px;
+            width: 100%;
+        }
+
+        .chat-card {
+            background: var(--light);
+            border-radius: 20px;
+            box-shadow: var(--shadow);
+            overflow: hidden;
+            height: 85vh;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .chat-header {
+            padding: 20px;
+            border-bottom: 1px solid var(--gray);
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            background: var(--light);
+        }
+
+        .header-title {
+            font-size: 1.5rem;
+            font-weight: 600;
+            color: var(--primary);
+            letter-spacing: -0.5px;
+        }
+
+        .header-actions {
+            display: flex;
+            gap: 10px;
+        }
+
+        .clear-btn {
+            background: transparent;
+            border: 1px solid var(--gray);
+            color: var(--dark-gray);
+            border-radius: 8px;
+            padding: 8px 12px;
+            cursor: pointer;
+            font-size: 0.85rem;
+            transition: all 0.3s;
+        }
+
+        .clear-btn:hover {
+            background: #ffebee;
+            border-color: #ef5350;
+            color: #c62828;
+        }
+
+        .chat-messages {
+            flex: 1;
+            padding: 20px;
+            overflow-y: auto;
+            display: flex;
+            flex-direction: column;
+            gap: 15px;
+            background: var(--light-gray);
+        }
+
+        .message {
+            max-width: 80%;
+            padding: 12px 18px;
+            border-radius: 18px;
+            position: relative;
+            animation: messageAppear 0.3s ease;
+        }
+
+        @keyframes messageAppear {
+            from { opacity: 0; transform: translateY(10px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+
+        .user-message {
+            align-self: flex-end;
+            background: var(--primary);
+            color: white;
+            border-bottom-right-radius: 5px;
+        }
+
+        .bot-message {
+            align-self: flex-start;
+            background: var(--light);
+            color: var(--dark);
+            border-bottom-left-radius: 5px;
+            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+        }
+
+        .chat-input-container {
+            padding: 20px;
+            border-top: 1px solid var(--gray);
+            display: flex;
+            flex-direction: column;
+            gap: 15px;
+            background: var(--light);
+        }
+
+        .input-row {
+            display: flex;
+            gap: 10px;
+        }
+
+        .chat-input {
+            flex: 1;
+            padding: 15px;
+            background: var(--light-gray);
+            border: 1px solid var(--gray);
+            border-radius: 12px;
+            font-size: 1rem;
+            color: var(--dark);
+            outline: none;
+            transition: all 0.3s;
+        }
+
+        .chat-input:focus {
+            border-color: var(--primary);
+            box-shadow: 0 0 0 2px rgba(67, 97, 238, 0.1);
+        }
+
+        .chat-input::placeholder {
+            color: var(--dark-gray);
+        }
+
+        .send-button {
+            background: var(--primary);
+            color: white;
+            border: none;
+            border-radius: 12px;
+            padding: 0 25px;
+            cursor: pointer;
+            font-weight: 600;
+            transition: all 0.3s;
+            display: flex;
+            align-items: center;
+            gap: 8px;
+        }
+
+        .send-button:hover {
+            background: var(--secondary);
+            transform: translateY(-2px);
+        }
+
+        .send-button:disabled {
+            opacity: 0.6;
+            cursor: not-allowed;
+            transform: none;
+        }
+
+        .typing-indicator {
+            display: flex;
+            align-items: center;
+            gap: 5px;
+            padding: 15px;
+            background: var(--light);
+            border-radius: 18px;
+            align-self: flex-start;
+            width: fit-content;
+            margin-bottom: 10px;
+            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+        }
+
+        .typing-dot {
+            width: 8px;
+            height: 8px;
+            background: var(--dark-gray);
+            border-radius: 50%;
+            animation: typing 1.4s infinite ease-in-out;
+        }
+
+        .typing-dot:nth-child(1) { animation-delay: -0.32s; }
+        .typing-dot:nth-child(2) { animation-delay: -0.16s; }
+
+        @keyframes typing {
+            0%, 80%, 100% { transform: scale(0.8); opacity: 0.5; }
+            40% { transform: scale(1); opacity: 1; }
+        }
+
+        /* 步骤容器样式 */
+        .step-container {
+            margin: 8px 0;
+            background: rgba(67, 97, 238, 0.05);
+            border: 1px solid rgba(67, 97, 238, 0.2);
+            border-radius: 8px;
+            overflow: hidden;
+        }
+
+        .step-header {
+            padding: 8px 12px;
+            background: rgba(67, 97, 238, 0.1);
+            cursor: pointer;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            font-weight: 600;
+            color: var(--primary);
+            transition: background 0.3s;
+            font-size: 0.9rem;
+        }
+
+        .step-header:hover {
+            background: rgba(67, 97, 238, 0.15);
+        }
+
+        .step-toggle {
+            font-size: 0.7rem;
+            transition: transform 0.3s;
+        }
+
+        .step-toggle.expanded {
+            transform: rotate(180deg);
+        }
+
+        .step-content {
+            max-height: 300px;
+            overflow: auto;
+            transition: max-height 0.3s ease, padding 0.3s ease;
+            padding: 12px;
+            background: var(--light);
+            border-top: 1px solid rgba(67, 97, 238, 0.1);
+            font-size: 0.9rem;
+            line-height: 1.4;
+        }
+
+        .step-content.collapsed {
+            max-height: 0 !important;
+            padding: 0 !important;
+            border-top: none !important;
+        }
+
+        .step-item {
+            margin-bottom: 10px;
+            padding: 8px;
+            background: var(--light-gray);
+            border-radius: 6px;
+        }
+
+        .step-item:last-child {
+            margin-bottom: 0;
+        }
+
+        .step-thought {
+            color: var(--primary);
+            font-weight: 500;
+            margin-bottom: 5px;
+        }
+
+        .step-action {
+            color: var(--secondary);
+            font-family: monospace;
+            font-size: 0.85rem;
+            margin-bottom: 5px;
+        }
+
+        .step-observation {
+            color: var(--dark-gray);
+            font-size: 0.85rem;
+            white-space: pre-wrap;
+            word-break: break-word;
+        }
+
+        .step-observation.success {
+            color: #2e7d32;
+        }
+
+        .step-observation.error {
+            color: #c62828;
+        }
+
+        /* 最终答案样式 */
+        .final-answer {
+            margin-top: 10px;
+            padding: 12px;
+            border-radius: 8px;
+        }
+
+        .final-answer-title {
+            font-weight: 600;
+            margin-bottom: 8px;
+        }
+
+        .final-answer-content {
+            line-height: 1.5;
+        }
+
+        @media (max-width: 768px) {
+            .chat-card {
+                height: 100vh;
+                border-radius: 0;
+            }
+
+            .message {
+                max-width: 90%;
+            }
+        }
+
+        .disclaimer {
+            font-size: 0.75rem;
+            color: var(--dark-gray);
+            text-align: center;
+            margin-top: 8px;
+        }
+
+        .page-footer {
+            font-size: 0.75rem;
+            color: var(--dark-gray);
+            text-align: center;
+            margin-top: 12px;
+        }
+
+        /* 弹窗样式 */
+        .modal-overlay {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: rgba(0, 0, 0, 0.5);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            z-index: 9999;
+            opacity: 0;
+            visibility: hidden;
+            transition: all 0.3s ease;
+        }
+
+        .modal-overlay.active {
+            opacity: 1;
+            visibility: visible;
+        }
+
+        .modal-overlay.fade-out {
+            opacity: 0;
+            visibility: hidden;
+        }
+
+        .modal-container {
+            background: var(--light);
+            border-radius: 16px;
+            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+            max-width: 500px;
+            width: 90%;
+            max-height: 80vh;
+            overflow: auto;
+            transform: scale(0.9) translateY(20px);
+            transition: all 0.3s cubic-bezier(0.68, -0.55, 0.265, 1.55);
+        }
+
+        .modal-overlay.active .modal-container {
+            transform: scale(1) translateY(0);
+        }
+
+        .modal-header {
+            padding: 20px 24px;
+            border-bottom: 1px solid var(--gray);
+            display: flex;
+            align-items: center;
+            gap: 12px;
+        }
+
+        .modal-header-icon {
+            font-size: 1.5rem;
+            color: var(--primary);
+        }
+
+        .modal-header-title {
+            font-size: 1.25rem;
+            font-weight: 600;
+            color: var(--dark);
+            flex: 1;
+        }
+
+        .modal-close-button {
+            background: transparent;
+            border: none;
+            color: var(--dark-gray);
+            font-size: 1.5rem;
+            cursor: pointer;
+            padding: 4px 8px;
+            border-radius: 4px;
+            transition: all 0.2s;
+            line-height: 1;
+        }
+
+        .modal-close-button:hover {
+            background: var(--light-gray);
+            color: var(--dark);
+        }
+
+        .modal-content {
+            padding: 24px;
+            line-height: 1.6;
+            color: var(--dark);
+        }
+
+        .modal-content p {
+            margin-bottom: 12px;
+        }
+
+        .modal-content p:last-child {
+            margin-bottom: 0;
+        }
+
+        .modal-footer {
+            padding: 16px 24px;
+            border-top: 1px solid var(--gray);
+            display: flex;
+            gap: 12px;
+            justify-content: flex-end;
+            flex-wrap: wrap;
+        }
+
+        .modal-button {
+            padding: 10px 20px;
+            border-radius: 8px;
+            font-size: 0.95rem;
+            font-weight: 500;
+            cursor: pointer;
+            transition: all 0.2s;
+            border: none;
+            outline: none;
+        }
+
+        .modal-button-primary {
+            background: var(--primary);
+            color: white;
+        }
+
+        .modal-button-primary:hover {
+            background: var(--secondary);
+            transform: translateY(-1px);
+        }
+
+        .modal-button-secondary {
+            background: var(--light-gray);
+            color: var(--dark);
+            border: 1px solid var(--gray);
+        }
+
+        .modal-button-secondary:hover {
+            background: var(--gray);
+        }
+
+        .modal-button-link {
+            background: transparent;
+            color: var(--primary);
+            padding: 10px 16px;
+        }
+
+        .modal-button-link:hover {
+            background: rgba(67, 97, 238, 0.1);
+        }
+
+        @media (max-width: 600px) {
+            .modal-container {
+                width: 95%;
+                max-height: 90vh;
+            }
+
+            .modal-footer {
+                flex-direction: column;
+            }
+
+            .modal-button {
+                width: 100%;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="chat-card">
+            <div class="chat-header">
+                <div class="header-title">astrbot-问题帮助助手</div>
+                <div class="header-actions">
+                    <button class="clear-btn" id="clearBtn" title="开始新对话">
+                        <i class="fas fa-plus"></i> 新对话
+                    </button>
+                </div>
+            </div>
+
+            <div class="chat-messages" id="chatMessages">
+                <div class="message bot-message">
+                    您好！我是astrbot帮助助手，一个智能帮助助手。<br><br>
+                    💡 我可以帮您：<br>
+                    • 了解astrbot<br>
+                    • 协助安装<br>
+                    • 解决遇到的问题<br>
+                    请直接输入您的问题！
+                </div>
+            </div>
+
+            <div class="chat-input-container">
+                <div class="input-row">
+                    <input type="text" class="chat-input" id="questionInput" placeholder="输入关于代码的问题...">
+                    <button class="send-button" id="sendButton">
+                        <i class="fas fa-paper-plane"></i>
+                    </button>
+                </div>
+            </div>
+        </div>
+        <div class="page-footer">
+            ⚠️ AI 回复仅供参考，请自行鉴别准确性
+        </div>
+    </div>
+
+    <!-- 弹窗容器 -->
+    <div id="modalOverlay" class="modal-overlay">
+        <div class="modal-container" id="modalContainer">
+            <div class="modal-header">
+                <i id="modalHeaderIcon" class="modal-header-icon"></i>
+                <h3 id="modalHeaderTitle" class="modal-header-title"></h3>
+                <button id="modalCloseButton" class="modal-close-button" aria-label="关闭">
+                    <i class="fas fa-times"></i>
+                </button>
+            </div>
+            <div id="modalContent" class="modal-content"></div>
+            <div id="modalFooter" class="modal-footer"></div>
+        </div>
+    </div>
+
+    <script>
+        // 会话管理
+        const SESSION_KEY = 'astrbot_session_id';
+        
+        function getSessionId() {
+            let sessionId = localStorage.getItem(SESSION_KEY);
+            if (!sessionId) {
+                sessionId = generateSessionId();
+                localStorage.setItem(SESSION_KEY, sessionId);
+            }
+            return sessionId;
+        }
+        
+        function generateSessionId() {
+            return 'session_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+        }
+        
+        function clearSession() {
+            localStorage.removeItem(SESSION_KEY);
+        }
+        
+        function setSessionId(sessionId) {
+            localStorage.setItem(SESSION_KEY, sessionId);
+        }
+        
+        // 消息历史记录
+        let messageHistory = [];
+        const MAX_HISTORY_LENGTH = 20;
+
+        // 防止重复发送的标志
+        let isSending = false;
+
+        // 获取DOM元素
+        const chatMessages = document.getElementById('chatMessages');
+        const questionInput = document.getElementById('questionInput');
+        const sendButton = document.getElementById('sendButton');
+        const clearBtn = document.getElementById('clearBtn');
+
+        // 新建会话
+        clearBtn.addEventListener('click', async function() {
+            if (!confirm('确定要开始新对话吗？当前对话将被清除。')) {
+                return;
+            }
+            
+            try {
+                const sessionId = getSessionId();
+                await fetch('/api/session/clear', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ session_id: sessionId })
+                });
+            } catch (e) {
+                console.error('清除会话失败:', e);
+            }
+            
+            // 生成新的会话 ID
+            const newSessionId = generateSessionId();
+            setSessionId(newSessionId);
+            
+            // 清除聊天记录
+            chatMessages.innerHTML = `
+                <div class="message bot-message">
+                    您好！我是astrbot帮助助手。（非官方）<br><br>
+                    💡 我可以帮您：<br>
+                    • 了解astrbot<br>
+                    • 协助安装<br>
+                    • 解决遇到的问题<br>
+                    请直接输入您的问题！
+                </div>
+            `;
+            messageHistory = [];
+        });
+
+        // 发送消息
+        async function sendMessage() {
+            // 防止重复发送
+            if (isSending) {
+                return;
+            }
+
+            const message = questionInput.value.trim();
+
+            if (!message) {
+                return;
+            }
+
+            // 设置发送标志
+            isSending = true;
+            sendButton.disabled = true;
+            sendButton.style.opacity = '0.6';
+
+            // 添加用户消息
+            addMessage(message, 'user');
+            messageHistory.push({ role: 'user', content: message });
+
+            // 清空输入
+            questionInput.value = '';
+
+            // 显示机器人正在输入
+            showTypingIndicator();
+
+            try {
+                console.log('发送请求到 /api/ask...');
+                
+                // 获取会话 ID
+                const sessionId = getSessionId();
+                
+                // 调用 Read Agent API（流式）
+                const response = await fetch('/api/ask', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({
+                        question: message,
+                        stream: true,
+                        session_id: sessionId
+                    })
+                });
+
+                console.log('���应状态:', response.status);
+                
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    console.error('API 错误:', response.status, errorText);
+                    throw new Error(`API请求失败: ${response.status} - ${errorText}`);
+                }
+
+                console.log('开始读取流式响应...');
+                console.log('response.body:', response.body);
+                
+                if (!response.body) {
+                    console.error('response.body is null!');
+                    throw new Error('响应体为空');
+                }
+
+                // 创建消息容器（但不移除 loading，等收到第一个数据再移除）
+                const messageDiv = document.createElement('div');
+                messageDiv.classList.add('message', 'bot-message');
+                chatMessages.appendChild(messageDiv);
+
+                // 创建步骤容器
+                const stepContainer = document.createElement('div');
+                stepContainer.className = 'step-container';
+                stepContainer.style.display = 'none';
+                
+                const stepHeader = document.createElement('div');
+                stepHeader.className = 'step-header';
+                
+                const stepTitle = document.createElement('span');
+                stepTitle.textContent = '分析过程';
+                
+                const stepToggle = document.createElement('span');
+                stepToggle.className = 'step-toggle';
+                stepToggle.textContent = '▼';
+                
+                const stepContent = document.createElement('div');
+                stepContent.className = 'step-content';
+                
+                stepHeader.appendChild(stepTitle);
+                stepHeader.appendChild(stepToggle);
+                stepContainer.appendChild(stepHeader);
+                stepContainer.appendChild(stepContent);
+                
+                // 添加点击事件
+                stepHeader.onclick = function() {
+                    const isCollapsing = stepContent.classList.contains('collapsed');
+                    stepContent.classList.toggle('collapsed');
+                    stepToggle.classList.toggle('expanded');
+                    // 展开时滚动到底部
+                    if (isCollapsing) {
+                        requestAnimationFrame(() => {
+                            stepContent.scrollTop = stepContent.scrollHeight;
+                        });
+                    }
+                };
+                
+                messageDiv.appendChild(stepContainer);
+
+                // 创建最终答案容器（打字机效果）
+                const finalAnswerDiv = document.createElement('div');
+                finalAnswerDiv.className = 'final-answer';
+                finalAnswerDiv.style.display = 'none';
+                
+                const answerTitle = document.createElement('div');
+                answerTitle.className = 'final-answer-title';
+                answerTitle.textContent = '';
+                answerTitle.style.display = 'none';
+                
+                const answerContent = document.createElement('div');
+                answerContent.className = 'final-answer-content';
+                
+                finalAnswerDiv.appendChild(answerTitle);
+                finalAnswerDiv.appendChild(answerContent);
+                messageDiv.appendChild(finalAnswerDiv);
+
+                let currentThoughtDiv = null;
+                let currentThoughtText = '';
+                let currentStepItem = null;
+                let finalAnswer = '';
+                let hasSteps = false;
+                let isThinking = false;
+                let isAnswering = false;
+                let hasReceivedData = false;  // 标记是否收到数据
+
+                // 处理流式响应
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                
+                console.log('开始读取流式响应...');
+
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        console.log('流式响应结束');
+                        break;
+                    }
+
+                    const chunk = decoder.decode(value);
+                    console.log('收到数据:', chunk);
+                    
+                    const lines = chunk.split('\n');
+
+                    for (const line of lines) {
+                        if (line.startsWith('data: ')) {
+                            const data = line.slice(6);
+                            if (data === '[DONE]') {
+                                continue;
+                            }
+
+                            try {
+                                const dataObj = JSON.parse(data);
+                                
+                                if (dataObj.type === 'session_id') {
+                                    // 更新本地会话 ID
+                                    if (dataObj.session_id) {
+                                        setSessionId(dataObj.session_id);
+                                    }
+                                    continue;
+                                } else if (dataObj.type === 'start') {
+                                    // 开始
+                                    continue;
+                                } else if (dataObj.type === 'question') {
+                                    // 问题
+                                    continue;
+                                } else if (dataObj.type === 'chunk') {
+                                    // 收到第一个数据时移除 loading
+                                    if (!hasReceivedData) {
+                                        hasReceivedData = true;
+                                        removeTypingIndicator();
+                                    }
+                                    
+                                    // 打字机效果 - 逐字输出
+                                    if (dataObj.stream_type === 'thought') {
+                                        // 思考输出
+                                        if (!isThinking) {
+                                            isThinking = true;
+                                            hasSteps = true;
+                                            stepContainer.style.display = 'block';
+                                            // 确保展开状态
+                                            stepContent.classList.remove('collapsed');
+                                            stepToggle.classList.add('expanded');
+                                            
+                                            currentStepItem = document.createElement('div');
+                                            currentStepItem.className = 'step-item';
+                                            stepContent.appendChild(currentStepItem);
+                                            requestAnimationFrame(() => {
+                                                console.log('滚动前 - scrollHeight:', stepContent.scrollHeight, 'scrollTop:', stepContent.scrollTop, 'clientHeight:', stepContent.clientHeight, 'collapsed:', stepContent.classList.contains('collapsed'));
+                                                stepContent.scrollTop = stepContent.scrollHeight;
+                                                console.log('滚动后 - scrollHeight:', stepContent.scrollHeight, 'scrollTop:', stepContent.scrollTop);
+                                            });
+
+                                            currentThoughtDiv = document.createElement('div');
+                                            currentThoughtDiv.className = 'step-thought';
+                                            currentThoughtDiv.textContent = '💭 ';
+                                            currentStepItem.appendChild(currentThoughtDiv);
+                                            
+                                            chatMessages.scrollTop = chatMessages.scrollHeight;
+                                        }
+                                        currentThoughtText += dataObj.content;
+                                        currentThoughtDiv.textContent = '💭 ' + currentThoughtText;
+                                        chatMessages.scrollTop = chatMessages.scrollHeight;
+                                        requestAnimationFrame(() => {
+                                            stepContent.scrollTop = stepContent.scrollHeight;
+                                        });
+                                    } else if (dataObj.stream_type === 'answer') {
+                                        // 最终答案输出
+                                        if (!isAnswering) {
+                                            isAnswering = true;
+                                            finalAnswerDiv.style.display = 'block';
+                                        }
+                                        finalAnswer += dataObj.content;
+                                        answerContent.innerHTML = renderMarkdown(finalAnswer);
+                                        chatMessages.scrollTop = chatMessages.scrollHeight;
+                                    }
+                                } else if (dataObj.type === 'step_thought_done') {
+                                    // 思考完成，准备行动
+                                    isThinking = false;
+                                    currentThoughtText = '';
+                                    currentThoughtDiv = null;
+                                    
+                                    if (dataObj.has_action) {
+                                        const actionDiv = document.createElement('div');
+                                        actionDiv.className = 'step-action';
+                                        actionDiv.textContent = '🔧 正在执行工具...';
+                                        currentStepItem.appendChild(actionDiv);
+                                        requestAnimationFrame(() => {
+                                            stepContent.scrollTop = stepContent.scrollHeight;
+                                        });
+                                    }
+                                    chatMessages.scrollTop = chatMessages.scrollHeight;
+                                } else if (dataObj.type === 'step') {
+                                    // 步骤完成（工具调用结果）
+                                    hasSteps = true;
+                                    stepContainer.style.display = 'block';
+                                    
+                                    const stepItem = document.createElement('div');
+                                    stepItem.className = 'step-item';
+                                    
+                                    if (dataObj.thought) {
+                                        const thoughtDiv = document.createElement('div');
+                                        thoughtDiv.className = 'step-thought';
+                                        thoughtDiv.textContent = `💭 ${dataObj.thought}`;
+                                        stepItem.appendChild(thoughtDiv);
+                                    }
+                                    
+                                    if (dataObj.action) {
+                                        const actionDiv = document.createElement('div');
+                                        actionDiv.className = 'step-action';
+                                        actionDiv.textContent = `🔧 ${dataObj.action}`;
+                                        stepItem.appendChild(actionDiv);
+                                    }
+                                    
+                                    if (dataObj.observation) {
+                                        const obsDiv = document.createElement('div');
+                                        obsDiv.className = 'step-observation';
+                                        if (dataObj.observation.success) {
+                                            obsDiv.classList.add('success');
+                                            obsDiv.textContent = `✅ ${JSON.stringify(dataObj.observation.result, null, 2)}`;
+                                        } else {
+                                            obsDiv.classList.add('error');
+                                            obsDiv.textContent = `❌ ${dataObj.observation.error}`;
+                                        }
+                                        stepItem.appendChild(obsDiv);
+                                    }
+                                    
+                                    if (dataObj.final_answer) {
+                                        finalAnswer = dataObj.final_answer;
+                                        isAnswering = true;
+                                        finalAnswerDiv.style.display = 'block';
+                                        answerContent.innerHTML = renderMarkdown(finalAnswer);
+                                    }
+
+                                    stepContent.appendChild(stepItem);
+                                    // 确保展开状态再滚动
+                                    stepContent.classList.remove('collapsed');
+                                    stepToggle.classList.add('expanded');
+                                    requestAnimationFrame(() => {
+                                        stepContent.scrollTop = stepContent.scrollHeight;
+                                    });
+                                    chatMessages.scrollTop = chatMessages.scrollHeight;
+                                } else if (dataObj.type === 'done') {
+                                    // 完成，自动折叠分析过程
+                                    if (hasSteps) {
+                                        stepContent.classList.add('collapsed');
+                                        stepToggle.classList.remove('expanded');
+                                    }
+                                    chatMessages.scrollTop = chatMessages.scrollHeight;
+                                } else if (dataObj.type === 'error') {
+                                    throw new Error(dataObj.error);
+                                }
+                            } catch (e) {
+                                // 忽略解析错误
+                            }
+                        }
+                    }
+                }
+
+                // 如果没有步骤，隐藏步骤容器
+                if (!hasSteps) {
+                    stepContainer.style.display = 'none';
+                } else if (finalAnswer) {
+                    // 有步骤且有最终答案时，折叠分析过程
+                    stepContent.classList.add('collapsed');
+                    stepToggle.classList.remove('expanded');
+                }
+                
+                // 如果没有最终答案，但有内容
+                if (finalAnswer && finalAnswerDiv.style.display === 'none') {
+                    finalAnswerDiv.style.display = 'block';
+                }
+
+                // 添加到历史记录
+                messageHistory.push({ role: 'assistant', content: finalAnswer });
+
+                // 限制历史记录长度
+                if (messageHistory.length > MAX_HISTORY_LENGTH) {
+                    messageHistory = messageHistory.slice(-MAX_HISTORY_LENGTH);
+                }
+            } catch (error) {
+                console.error('Error:', error);
+                removeTypingIndicator();
+                addMessage('抱歉，获取帮助时出现错误。请检查配置后重试。', 'bot', true);
+            } finally {
+                isSending = false;
+                sendButton.disabled = false;
+                sendButton.style.opacity = '1';
+            }
+        }
+
+        // 简单的Markdown渲染函数
+        function renderMarkdown(text) {
+            // 处理代码块
+            text = text.replace(/```(\w+)?\n([\s\S]*?)```/g, '<pre><code>$2</code></pre>');
+            text = text.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+            // 处理标题
+            text = text.replace(/^### (.*$)/gim, '<h3>$1</h3>');
+            text = text.replace(/^## (.*$)/gim, '<h2>$1</h2>');
+            text = text.replace(/^# (.*$)/gim, '<h1>$1</h1>');
+
+            // 处理粗体和斜体
+            text = text.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+            text = text.replace(/\*(.+?)\*/g, '<em>$1</em>');
+
+            // 处理链接
+            text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" target="_blank">$1</a>');
+
+            // 处理列表
+            text = text.replace(/^\* (.+)/gim, '<li>$1</li>');
+            text = text.replace(/^\- (.+)/gim, '<li>$1</li>');
+            text = text.replace(/^(\d+)\. (.+)/gim, '<li>$2</li>');
+
+            // 处理换行
+            text = text.replace(/\n/g, '<br>');
+
+            return text;
+        }
+
+        // 添加消息到聊天区域
+        function addMessage(text, sender, isError = false) {
+            const messageDiv = document.createElement('div');
+            messageDiv.classList.add('message');
+            if (isError) {
+                messageDiv.style.background = '#ffebee';
+                messageDiv.style.color = '#c62828';
+                messageDiv.style.border = '1px solid #ef5350';
+            } else {
+                messageDiv.classList.add(sender === 'user' ? 'user-message' : 'bot-message');
+            }
+
+            let formattedText;
+            if (sender === 'bot' && !isError) {
+                formattedText = renderMarkdown(text);
+            } else {
+                formattedText = text.replace(/\n/g, '<br>');
+            }
+            messageDiv.innerHTML = formattedText;
+
+            chatMessages.appendChild(messageDiv);
+            chatMessages.scrollTop = chatMessages.scrollHeight;
+        }
+
+        // 显示正在输入指示器
+        function showTypingIndicator() {
+            const typingDiv = document.createElement('div');
+            typingDiv.classList.add('typing-indicator');
+            typingDiv.id = 'typingIndicator';
+            typingDiv.innerHTML = `
+                <div class="typing-dot"></div>
+                <div class="typing-dot"></div>
+                <div class="typing-dot"></div>
+            `;
+            chatMessages.appendChild(typingDiv);
+            chatMessages.scrollTop = chatMessages.scrollHeight;
+        }
+
+        // 移除正在输入指示器
+        function removeTypingIndicator() {
+            const typingIndicator = document.getElementById('typingIndicator');
+            if (typingIndicator) {
+                typingIndicator.remove();
+            }
+        }
+
+        // 事件监听
+        sendButton.addEventListener('click', sendMessage);
+
+        questionInput.addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                sendMessage();
+            }
+        });
+
+        // ===== 弹窗管理 =====
+        const ModalManager = {
+            config: null,
+            overlay: null,
+            container: null,
+            storageKey: null,
+
+            async init() {
+                this.overlay = document.getElementById('modalOverlay');
+                this.container = document.getElementById('modalContainer');
+
+                if (!this.overlay || !this.container) {
+                    console.warn('弹窗元素未找到');
+                    return;
+                }
+
+                await this.loadConfig();
+
+                if (this.shouldShow()) {
+                    const delay = this.config.display?.delay || 500;
+                    setTimeout(() => this.show(), delay);
+                }
+
+                this.bindEvents();
+            },
+
+            async loadConfig() {
+                try {
+                    const response = await fetch('/api/popup/config');
+                    const data = await response.json();
+                    this.config = data;
+                    this.storageKey = data.storage?.key || 'popup_dismissed';
+                    console.log('弹窗配置加载成功:', this.config);
+                } catch (error) {
+                    console.error('加载弹窗配置失败:', error);
+                    this.config = { enabled: false };
+                }
+            },
+
+            shouldShow() {
+                if (!this.config || !this.config.enabled) {
+                    return false;
+                }
+
+                // 检查用户是否已选择"不再显示"
+                const dismissed = this.getStorageValue();
+                if (dismissed) {
+                    return false;
+                }
+
+                // 检查显示规则
+                const showRules = this.config.showRules || {};
+                const maxShows = showRules.maxShows || 0;
+                const frequency = showRules.frequency || 'once';
+
+                if (maxShows > 0) {
+                    const showCount = this.getShowCount();
+                    if (showCount >= maxShows) {
+                        return false;
+                    }
+                }
+
+                if (frequency === 'daily') {
+                    const lastShowDate = this.getLastShowDate();
+                    const today = new Date().toDateString();
+                    if (lastShowDate === today) {
+                        return false;
+                    }
+                }
+
+                return true;
+            },
+
+            show() {
+                if (!this.config || !this.config.enabled) {
+                    return;
+                }
+
+                this.renderContent();
+                this.overlay.classList.add('active');
+                this.incrementShowCount();
+                this.setLastShowDate();
+                console.log('弹窗已显示');
+            },
+
+            hide() {
+                this.overlay.classList.remove('active');
+                this.overlay.classList.add('fade-out');
+
+                setTimeout(() => {
+                    this.overlay.classList.remove('fade-out');
+                }, 300);
+
+                console.log('弹窗已隐藏');
+            },
+
+            dismiss() {
+                this.setStorageValue(true);
+                this.hide();
+                console.log('用户选择不再显示弹窗');
+            },
+
+            renderContent() {
+                const content = this.config.content || {};
+                const display = this.config.display || {};
+
+                document.getElementById('modalHeaderTitle').textContent = content.title || '提示';
+                const icon = document.getElementById('modalHeaderIcon');
+                icon.className = 'modal-header-icon ' + (content.icon || 'fas fa-info-circle');
+
+                const contentDiv = document.getElementById('modalContent');
+                contentDiv.innerHTML = content.html || '';
+
+                this.renderButtons();
+
+                const closeButton = document.getElementById('modalCloseButton');
+                closeButton.style.display = display.showCloseButton !== false ? 'block' : 'none';
+            },
+
+            renderButtons() {
+                const footer = document.getElementById('modalFooter');
+                footer.innerHTML = '';
+
+                const buttons = this.config.buttons || [];
+
+                buttons.forEach(button => {
+                    const btn = document.createElement('button');
+                    btn.textContent = button.text || '确定';
+
+                    const buttonClass = 'modal-button';
+                    switch (button.type) {
+                        case 'primary':
+                            btn.className = buttonClass + ' modal-button-primary';
+                            break;
+                        case 'secondary':
+                            btn.className = buttonClass + ' modal-button-secondary';
+                            break;
+                        case 'link':
+                            btn.className = buttonClass + ' modal-button-link';
+                            break;
+                        default:
+                            btn.className = buttonClass + ' modal-button-secondary';
+                    }
+
+                    btn.addEventListener('click', () => this.handleButtonClick(button));
+                    footer.appendChild(btn);
+                });
+            },
+
+            handleButtonClick(button) {
+                switch (button.action) {
+                    case 'close':
+                        this.hide();
+                        break;
+                    case 'dismiss':
+                        this.dismiss();
+                        break;
+                    case 'url':
+                        if (button.url) {
+                            window.open(button.url, '_blank');
+                            this.hide();
+                        }
+                        break;
+                    default:
+                        this.hide();
+                }
+            },
+
+            bindEvents() {
+                const display = this.config.display || {};
+
+                const closeButton = document.getElementById('modalCloseButton');
+                if (closeButton) {
+                    closeButton.addEventListener('click', () => this.hide());
+                }
+
+                if (display.closeOnOutsideClick !== false) {
+                    this.overlay.addEventListener('click', (e) => {
+                        if (e.target === this.overlay) {
+                            this.hide();
+                        }
+                    });
+                }
+
+                if (display.closeOnEscapeKey !== false) {
+                    document.addEventListener('keydown', (e) => {
+                        if (e.key === 'Escape' && this.overlay.classList.contains('active')) {
+                            this.hide();
+                        }
+                    });
+                }
+
+                const autoCloseAfter = display.autoCloseAfter || 0;
+                if (autoCloseAfter > 0) {
+                    setTimeout(() => {
+                        if (this.overlay.classList.contains('active')) {
+                            this.hide();
+                        }
+                    }, autoCloseAfter);
+                }
+            },
+
+            getStorageValue() {
+                const storageType = this.config.storage?.type || 'localStorage';
+                const key = this.storageKey;
+
+                if (storageType === 'cookie') {
+                    return this.getCookie(key);
+                } else {
+                    return localStorage.getItem(key) === 'true';
+                }
+            },
+
+            setStorageValue(value) {
+                const storageType = this.config.storage?.type || 'localStorage';
+                const key = this.storageKey;
+                const expiresIn = this.config.storage?.expiresIn || 0;
+
+                if (storageType === 'cookie') {
+                    let expires = '';
+                    if (expiresIn > 0) {
+                        const date = new Date();
+                        date.setTime(date.getTime() + expiresIn);
+                        expires = '; expires=' + date.toUTCString();
+                    }
+                    document.cookie = key + '=' + value + expires + '; path=/';
+                } else {
+                    localStorage.setItem(key, String(value));
+                }
+            },
+
+            getCookie(name) {
+                const value = '; ' + document.cookie;
+                const parts = value.split('; ' + name + '=');
+                if (parts.length === 2) {
+                    return parts.pop().split(';').shift();
+                }
+                return null;
+            },
+
+            getShowCount() {
+                return parseInt(localStorage.getItem(this.storageKey + '_count') || '0');
+            },
+
+            incrementShowCount() {
+                const count = this.getShowCount() + 1;
+                localStorage.setItem(this.storageKey + '_count', String(count));
+            },
+
+            getLastShowDate() {
+                return localStorage.getItem(this.storageKey + '_last_date') || '';
+            },
+
+            setLastShowDate() {
+                localStorage.setItem(this.storageKey + '_last_date', new Date().toDateString());
+            },
+
+            async reload() {
+                await this.loadConfig();
+                return this.config;
+            },
+
+            reset() {
+                localStorage.removeItem(this.storageKey);
+                localStorage.removeItem(this.storageKey + '_count');
+                localStorage.removeItem(this.storageKey + '_last_date');
+                console.log('弹窗设置已重置');
+            }
+        };
+
+        // 页面加载完成后初始化弹窗
+        document.addEventListener('DOMContentLoaded', () => {
+            ModalManager.init();
+        });
+
+        // 暴露到全局，方便调试
+        window.ModalManager = ModalManager;
+    </script>
+</body>
+</html>