229 lines
6.9 KiB
Markdown
229 lines
6.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
多用户 AI Agent 系统，为每个登录用户提供独立的 Docker 容器环境。支持终端交互、文件操作、对话管理和实时监控。主要用于学习和实验"智能体 + 真实 Dev Workflow"，代码大量由 AI 生成。
|
||
|
||
## Core Architecture
|
||
|
||
### Entry Points
|
||
- **CLI模式**: `python main.py` - 启动命令行交互式 Agent
|
||
- **Web模式**: `python web_server.py` - 启动 Flask + Socket.IO Web 服务器 (默认端口 8091)
|
||
|
||
### Key Components
|
||
|
||
**core/**
|
||
- `MainTerminal` - CLI 主终端，处理用户输入和 AI 对话循环
|
||
- `WebTerminal` - Web 终端，继承 MainTerminal，增加实时推送和对话持久化
|
||
- `tool_config.py` - 定义所有工具的配置和分类
|
||
|
||
**modules/**
|
||
- `user_container_manager.py` - 单用户-单容器管理，负责容器生命周期
|
||
- `container_file_proxy.py` - 容器内文件代理，通过 `docker exec` 沙箱化文件操作
|
||
- `terminal_manager.py` - 管理多个持久化终端会话
|
||
- `file_manager.py` - 文件 CRUD，包含搜索、替换和 append/modify streaming 功能
|
||
- `conversation_manager.py` - 对话历史持久化
|
||
- `context_manager.py` - 上下文构建、token统计、对话管理
|
||
- `memory_manager.py` - 长期记忆管理
|
||
- `todo_manager.py` - 待办事项管理
|
||
- `sub_agent_manager.py` - 子智能体任务调度
|
||
- `user_manager.py` - 用户认证和工作区管理
|
||
- `upload_security.py` - 上传文件隔离扫描
|
||
|
||
**utils/**
|
||
- `api_client.py` - 与 OpenAI-compatible API 交互，支持 thinking mode（首次思考，后续快速）
|
||
- `terminal_factory.py` - 终端类型工厂
|
||
|
||
**static/**
|
||
- Vue + Socket.IO 前端，包含对话流、终端输出、资源监控面板
|
||
|
||
**docker/**
|
||
- `terminal.Dockerfile` - 终端容器镜像构建配置
|
||
|
||
## Development Commands
|
||
|
||
### Build & Run
|
||
```bash
|
||
# 安装依赖（需要在项目根目录创建 requirements.txt）
|
||
pip install flask flask-socketio flask-cors openai python-dotenv tiktoken lxml
|
||
|
||
# 构建终端镜像
|
||
docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .
|
||
|
||
# CLI 模式
|
||
python main.py
|
||
|
||
# Web 模式
|
||
python web_server.py
|
||
# 或指定端口和思考模式
|
||
python web_server.py --port 8091 --thinking-mode
|
||
```
|
||
|
||
### Testing & Debugging
|
||
```bash
|
||
# 查看容器状态
|
||
docker ps -a | grep agent-term
|
||
|
||
# 查看调试日志
|
||
tail -f logs/debug_stream.log
|
||
|
||
# 查看容器统计
|
||
tail -f logs/container_stats.log
|
||
```
|
||
|
||
## Configuration
|
||
|
||
主要配置文件：`.env`（复制 `.env.example`）
|
||
|
||
**必填变量**:
|
||
- `AGENT_API_BASE_URL` - OpenAI-compatible API 端点
|
||
- `AGENT_API_KEY` - API 密钥
|
||
- `AGENT_MODEL_ID` - 模型 ID (例如 deepseek-chat)
|
||
- `WEB_SECRET_KEY` - Flask session 密钥
|
||
|
||
**容器配置** (`config/terminal.py`):
|
||
- `TERMINAL_SANDBOX_MODE` - docker/host
|
||
- `TERMINAL_SANDBOX_IMAGE` - 容器镜像 (默认 python:3.11-slim)
|
||
- `TERMINAL_SANDBOX_NETWORK` - 网络模式 (bridge/none/host)
|
||
- `TERMINAL_SANDBOX_CPUS` - CPU 限制
|
||
- `TERMINAL_SANDBOX_MEMORY` - 内存限制
|
||
|
||
**资源限制**:
|
||
- `PROJECT_MAX_STORAGE_MB` - 单用户磁盘配额 (默认 2048MB)
|
||
- `MAX_ACTIVE_USER_CONTAINERS` - 并发容器数量 (默认 8)
|
||
|
||
## Important Implementation Details
|
||
|
||
### File Operations with Streaming
|
||
|
||
**append_to_file** 和 **modify_file** 使用特殊的流式输出格式：
|
||
|
||
```
|
||
<<<APPEND:path/to/file>>>
|
||
文件内容...
|
||
<<<END_APPEND>>>
|
||
|
||
<<<MODIFY:path/to/file>>>
|
||
[replace:1]
|
||
<<OLD>>原文内容<<END>>
|
||
<<NEW>>新内容<<END>>
|
||
[/replace]
|
||
<<<END_MODIFY>>>
|
||
```
|
||
|
||
处理逻辑在 `web_server.py` 的 `handle_task_with_sender` 中，通过检测标记并在流式输出中即时执行。
|
||
|
||
### Container Architecture
|
||
|
||
每个用户登录时：
|
||
1. `UserContainerManager` 创建专属容器
|
||
2. 容器挂载 `users/<username>/project/` 到 `/workspace`
|
||
3. 所有文件操作通过 `ContainerFileProxy` 在容器内执行
|
||
4. 终端会话通过 `docker exec` 运行
|
||
5. 空闲超时或登出后自动销毁容器
|
||
|
||
### Context Management
|
||
|
||
`ContextManager` 负责：
|
||
- 动态构建上下文（系统提示 + 工具 + 对话历史 + 聚焦文件 + 记忆）
|
||
- Token 统计和限制检查
|
||
- 对话历史保存和加载
|
||
- 自动保存机制（每次 API 调用后增量保存）
|
||
|
||
### Thinking Mode
|
||
|
||
支持"思考模式"（需配置 `AGENT_THINKING_MODEL_ID`）：
|
||
- 首次调用使用 reasoning 模型（如 deepseek-reasoner）
|
||
- 后续调用使用快速模型
|
||
- 可通过 `THINKING_FAST_INTERVAL` 控制切换频率
|
||
- 失败时自动回退到思考模式
|
||
|
||
### Web Socket Events
|
||
|
||
主要事件：
|
||
- `send_message` - 发送用户消息
|
||
- `thinking_start/chunk/end` - 思考过程
|
||
- `text_start/chunk/end` - 文本响应
|
||
- `tool_preparing/start/update_action` - 工具执行状态
|
||
- `conversation_list_update` - 对话列表更新
|
||
- `terminal_output` - 终端输出
|
||
|
||
## Common Patterns
|
||
|
||
### Adding New Tools
|
||
|
||
1. 在 `MainTerminal` 添加 `handle_<tool_name>` 方法
|
||
2. 在 `core/tool_config.py` 的 `define_tools()` 中注册工具
|
||
3. 如果需要在流式输出中处理，在 `web_server.py` 添加特殊逻辑
|
||
|
||
### Working with Containers
|
||
|
||
使用 `ContainerHandle`:
|
||
```python
|
||
# 文件操作
|
||
result = container_handle.execute_file_op("read", path="/workspace/file.txt")
|
||
|
||
# 执行命令
|
||
result = container_handle.run_command("ls -la /workspace")
|
||
|
||
# 终端会话
|
||
result = container_handle.start_terminal(session_name="main", working_dir="/workspace")
|
||
```
|
||
|
||
### Managing Conversations
|
||
|
||
```python
|
||
# 创建新对话
|
||
terminal.create_new_conversation(thinking_mode=True)
|
||
|
||
# 加载对话
|
||
terminal.load_conversation(conversation_id)
|
||
|
||
# 搜索对话
|
||
terminal.search_conversations(query="bug fix")
|
||
|
||
# 删除对话
|
||
terminal.delete_conversation(conversation_id)
|
||
```
|
||
|
||
## Security Considerations
|
||
|
||
- 所有用户操作在独立容器中执行，与宿主机隔离
|
||
- 文件操作路径验证在 `FileManager._validate_path`
|
||
- 上传文件经过 `UploadQuarantineManager` 隔离和扫描
|
||
- CSRF 保护在 Web 端启用
|
||
- 登录失败次数限制和临时锁定
|
||
|
||
## Known Limitations
|
||
|
||
- 代码大量由 AI 生成，未达到生产级别
|
||
- 容器资源配额依赖 Docker cgroups
|
||
- 前端处于改造中，部分功能可能不稳定
|
||
- Token 统计基于 tiktoken，可能与实际 API 有偏差
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
agents/
|
||
├── core/ # 核心终端和工具配置
|
||
├── modules/ # 独立功能模块
|
||
├── utils/ # 辅助工具
|
||
├── config/ # 配置文件
|
||
├── static/ # Web 前端
|
||
├── docker/ # 容器镜像
|
||
├── prompts/ # 系统提示词
|
||
├── users/ # 用户工作区
|
||
├── data/ # 全局数据
|
||
└── logs/ # 日志文件
|
||
```
|
||
|
||
## Development Tips
|
||
|
||
- 修改系统提示词：编辑 `prompts/main_system.txt`
|
||
- 调整工具限制：修改 `config/limits.py`
|
||
- 容器镜像定制：编辑 `docker/terminal.Dockerfile` 并重新构建
|
||
- 前端开发：`npm install && npm run dev` (在 `static/` 目录)
|
||
- 查看详细执行流程：监控 `logs/debug_stream.log`
|