docs: 重写README.md，详细介绍系统架构和使用方法

- 添加完整的功能特性说明（多模式运行、双端架构、子智能体等） - 详细说明宿主机模式和Docker模式的特点和适用场景 - 补充工具集、对话管理、个性化配置等核心功能 - 添加架构设计、数据流、目录结构说明 - 提供使用方法、配置说明、扩展开发指南 - 强调两种运行模式同等重要，各有优势 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-04-05 02:01:32 +08:00 · 2026-04-05 02:01:32 +08:00 · 7496d8a3c6
commit 7496d8a3c6
parent df28c44c22
1 changed files with 555 additions and 130 deletions
--- a/README.md
+++ b/README.md
@ -1,165 +1,590 @@
-# AI Agent 系统（v5.x）
+# AI Agent 系统

-多用户、多终端的智能开发助手。每位登录用户都会获得一个独立 Docker 容器，所有终端、一次性命令以及文件操作都在容器内完成；宿主机负责挂载与备份。配合 **虚拟显示器** 与资源面板，可实时回放工具动作并观察 CPU / 内存 / 网络 / 磁盘配额。
+一个功能完整的 AI 智能体系统，支持多模态交互、子智能体协作、实时终端操作和丰富的工具集成。

-> ⚠️ **定位**：学习与实验用项目，主要用于探索“智能体 + 真实 Dev Workflow”。代码大量由 AI 生成，尚未达到生产级别，请谨慎部署。
+## 核心特性

---
+### 🎯 多模式运行

-## 近期亮点（v5）
+系统支持三种运行模式，适应不同场景需求：

-| 能力 | 说明 |
-| --- | --- |
-| **虚拟显示器回放** | `static/src/components/chat/monitor` 提供指针/窗口/右键菜单动画，可回放创建文件、终端执行等工具场景，并展示进度气泡。 |
-| **单用户-单容器** | `modules/user_container_manager.py` 登录即拉起专属容器，退出或空闲自动销毁；CLI/Web/工具共用同一容器，配额在 `.env` 设置。 |
-| **容器内文件代理** | `modules/container_file_proxy.py` 通过 `docker exec` 沙箱化 `create/read/search/write/modify`，宿主机不直接写用户代码。 |
-| **实时资源与管理员面板** | 用量抽屉实时展示 Token / CPU / 内存 / 网络 / 存储；管理员可在 `/admin/monitor` 查看全局用量与上传审计。 |
-| **子代理与多工具链路** | 支持子代理启动/终止，待办、记忆、阅读、终端等工具协同；前端可随时切换聊天/显示器视图。 |
+- **快速模式 (fast)**: 无思考过程，快速响应，适合简单任务
+- **思考模式 (thinking)**: 启用推理过程，提供更深入的分析
+- **深度思考模式 (deep)**: 最强推理能力，适合复杂问题

---
+### 🌐 双端架构

-## 架构概览
+- **Web 模式**: 基于 Flask + Socket.IO + Vue 3 的现代化 Web 界面
+  - 实时消息流式传输
+  - 多对话管理
+  - 可视化文件管理器
+  - 终端会话面板
+  - 监控仪表板

-```
-┌─────────────┐      ┌────────────────┐      ┌────────────────────────┐
-│  Browser    │◀───▶│ Flask + Socket  │◀───▶│ UserContainerManager    │
-│ (Vue 前端) │ Web │  Web Server     │调度 │  (管理 Docker 容器)      │
-└─────────────┘      │  ├─ WebTerminal │      └────┬───────────────────┘
-                      │  └─ REST APIs   │           │
-                      └────────────────┘           ▼
-                                                 Container
-                                                 ├─ PersistentTerminal / Toolbox
-                                                 ├─ Container File Proxy
-                                                 └─ Sub Agent / Tool Runtime
-```
+- **CLI 模式**: 命令行交互界面，适合开发和自动化场景

- **core/**：`MainTerminal` / `WebTerminal` 负责命令路由、上下文管理与工具调度。
- **modules/**：终端管理、文件代理、容器调度、搜索、记忆等独立能力模块。
- **utils/**：模型 API 客户端、上下文压缩、日志、终端工厂等辅助工具。
- **static/**：Vue + Socket.IO 单页应用；`chat/monitor` 为虚拟显示器动画层。
- **docker/**：终端镜像 Dockerfile 及工具容器依赖清单。
+### 🤖 子智能体系统

-重构后的主链路分层（2026-03）：
- `core/main_terminal.py` + `core/main_terminal_parts/`（主终端入口 + 功能 mixin）
- `server/chat_flow.py` + `server/chat_flow_runner.py` + `server/chat_flow_helpers.py`
- `server/conversation.py` + `server/conversation_stats.py`
+支持创建独立的子智能体处理复杂任务：

-更多目录说明请查阅 `tree -L 2` 或仓库内注释。
+- **并行执行**: 最多同时运行多个子智能体
+- **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史
+- **任务隔离**: 子智能体在独立进程中运行，互不干扰
+- **状态追踪**: 实时监控子智能体的执行状态和进度
+- **后台运行**: 支持后台模式，主智能体可继续处理其他任务

---
+工具接口：
+- `create_sub_agent`: 创建并启动子智能体
+- `wait_sub_agent`: 等待子智能体完成并获取结果
+- `close_sub_agent`: 终止运行中的子智能体

-## 快速开始
+### 🛠️ 丰富的工具集

-### 1. 环境需求
+系统提供分类管理的工具集，可按需启用/禁用：

- Python 3.11+
- Docker 20+（需启用 cgroup v1/v2 任一，默认通过 `bridge` 网络运行容器）
- Node 18+（仅在需要本地构建/开发前端时）
+#### 文件操作
+- `read_file`: 读取文件内容
+- `create_file` / `write_file`: 创建和写入文件
+- `edit_file`: 精确编辑文件内容
+- `delete_file` / `rename_file`: 文件管理
+- `create_folder`: 创建目录
+- `list_files`: 列出目录内容
+- `search_files`: 搜索文件

-### 2. 安装依赖
+#### 终端操作

+**实时终端会话**:
+- `terminal_session`: 创建持久化终端会话
+- `terminal_input`: 向终端发送命令
+- `terminal_snapshot`: 获取终端输出快照
+- `sleep`: 等待命令执行完成
+
+**快速命令执行**:
+- `run_command`: 执行 Shell 命令
+- `run_python`: 执行 Python 代码
+
+#### 网络检索
+- `web_search`: 网络搜索
+- `extract_webpage`: 提取网页内容
+- `save_webpage`: 保存网页到本地
+
+#### 多模态能力
+- `vlm_analyze`: 视觉语言模型分析图片
+- `ocr_image`: OCR 文字识别
+- `view_image`: 查看图片内容
+- `view_video`: 查看视频内容
+
+#### 记忆与任务管理
+- `update_memory`: 更新长期记忆
+- `todo_create`: 创建待办任务
+- `todo_update_task`: 更新任务状态
+
+#### 自定义工具
+- 支持管理员定义自定义工具
+- 工具注册和执行框架
+- 动态工具加载
+
+### 💾 对话持久化
+
+完整的对话管理系统：
+
+- **多对话支持**: 创建、切换、删除多个独立对话
+- **自动保存**: 对话历史实时持久化
+- **对话搜索**: 按标题和内容搜索历史对话
+- **对话复制**: 快速复制现有对话作为新起点
+- **元数据追踪**: 记录创建时间、消息数、Token 使用等
+
+命令：
+- `/new`: 创建新对话
+- `/load <id>`: 加载指定对话
+- `/conversations`: 列出所有对话
+- `/clear`: 清空当前对话
+
+### 🔒 运行环境模式
+
+系统支持两种运行环境模式，各有优势：
+
+#### 宿主机模式 (Host Mode)
+
+直接在宿主机上执行命令和操作，适合开发和个人使用：
+
+- **原生性能**: 无虚拟化开销，执行速度最快
+- **完整访问**: 可访问宿主机所有资源和工具
+- **开发友好**: 直接使用本地环境和配置
+- **简单部署**: 无需 Docker，降低部署复杂度
+- **灵活操作**: 支持所有系统命令和工具
+- **路径透明**: 文件路径与实际系统一致
+
+适用场景：
+- 个人开发环境
+- 可信用户场景
+- 需要完整系统访问权限
+- 性能敏感的任务
+
+配置：
 ```bash
-pip install -r requirements.txt
-# 前端开发/构建时可选
-npm install
+TERMINAL_SANDBOX_MODE=host
+HOST_PROJECT_PATH=/path/to/project  # 可选，指定项目路径
 ```

-### 3. 配置
+#### Docker 容器模式 (Docker Mode)

-1. 复制 `.env.example` → `.env`，填入以下关键变量：  
-   - `AGENT_API_*`：兼容 OpenAI API 的模型服务
-   - `WEB_SECRET_KEY`：Flask session 密钥
-   - `TERMINAL_SANDBOX_*`：容器镜像/资源/网络（默认 `my-agent-shell:latest` + `bridge`）
-2. 若需定制终端镜像：  
-   ```bash
-   docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .
-   ```
+在隔离的 Docker 容器中执行，适合多用户和生产环境：

-### 4. 运行
+- **环境隔离**: 每个用户独立的容器环境
+- **资源限制**: CPU、内存、存储配额管理
+- **安全执行**: 代码在隔离环境中运行，保护宿主机
+- **持久化存储**: 项目文件挂载到容器
+- **网络控制**: 可配置网络访问策略
+- **环境一致**: 统一的运行环境，避免依赖问题

+适用场景：
+- 多用户共享服务
+- 生产环境部署
+- 需要安全隔离
+- 资源配额管理
+
+配置：
 ```bash
-# CLI 模式
-python main.py
-
-# Web 模式（默认 8091）
-python -m server.app   # 推荐
-# 兼容旧命令（启动时会提示已弃用）
-python web_server.py
+TERMINAL_SANDBOX_MODE=docker
+TERMINAL_SANDBOX_IMAGE=ubuntu:22.04
+TERMINAL_SANDBOX_CPUS=2
+TERMINAL_SANDBOX_MEMORY=4g
+TERMINAL_SANDBOX_MOUNT_PATH=/workspace
 ```

-首次启动会在 `users/<username>/` 下初始化个人工作区与容器。
+#### 模式对比

-### 5. 构建前端（可选）
+| 特性 | 宿主机模式 | Docker 模式 |
+|------|-----------|------------|
+| 性能 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| 安全隔离 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| 资源控制 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| 部署复杂度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
+| 环境一致性 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| 工具访问 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |

-```bash
-npm run build     # 产物输出到 static/dist
-# 开发监听（仅构建，不启动服务）
-npm run dev
+### 👥 多用户管理
+
+完整的用户系统：
+
+- **用户认证**: 基于 Session 的身份验证
+- **权限管理**: 普通用户 / 管理员角色
+- **配额控制**: 按用户限制 API 调用次数
+- **工作空间隔离**: 每个用户独立的数据目录
+- **使用统计**: 追踪用户活动和资源使用
+
+### 🎨 个性化配置
+
+用户可自定义智能体行为：
+
+- **身份设定**: 自定义智能体名称和用户称呼
+- **语气风格**: 健谈、幽默、直言不讳、鼓励性等预设
+- **工具偏好**: 选择性启用/禁用工具类别
+- **模型选择**: 切换不同的 AI 模型
+- **思考间隔**: 调整思考模式的输出频率
+- **图片压缩**: 控制图片上传质量
+
+### 📊 监控与统计
+
+实时系统监控：
+
+- **Token 统计**: 输入/输出 Token 使用量
+- **工具调用**: 各工具使用频率统计
+- **文件操作**: 读写操作记录
+- **记忆使用**: 记忆系统活动追踪
+- **性能指标**: 响应时间、错误率等
+
+## 架构设计
+
+### 后端架构
+
+```
+agents/
+├── main.py                 # 程序入口
+├── core/                   # 核心模块
+│   ├── main_terminal.py    # 主终端（CLI模式）
+│   ├── web_terminal.py     # Web终端
+│   ├── tool_config.py      # 工具配置
+│   └── ...
+├── server/                 # Web服务器
+│   ├── app.py              # Flask应用
+│   ├── chat_flow_*.py      # 对话流程处理
+│   ├── conversation.py     # 对话管理
+│   ├── socket_handlers.py  # WebSocket处理
+│   └── ...
+├── modules/                # 功能模块
+│   ├── file_manager.py     # 文件管理
+│   ├── terminal_manager.py # 终端管理
+│   ├── sub_agent_manager.py# 子智能体管理
+│   ├── memory_manager.py   # 记忆管理
+│   ├── search_engine.py    # 搜索引擎
+│   └── ...
+├── utils/                  # 工具函数
+│   ├── api_client.py       # API客户端
+│   ├── context_manager.py  # 上下文管理
+│   ├── conversation_manager.py # 对话持久化
+│   └── ...
+└── config/                 # 配置文件
+    ├── __init__.py         # 主配置
+    ├── model_profiles.py   # 模型配置
+    ├── limits.py           # 限制配置
+    └── ...
 ```

---
+### 前端架构

-## 监控与调试
+```
+static/src/
+├── App.vue                 # 主应用组件
+├── main.ts                 # 入口文件
+├── app/                    # 应用逻辑
+│   ├── state.ts            # 状态管理
+│   ├── methods/            # 方法模块
+│   │   ├── conversation.ts # 对话管理
+│   │   ├── message.ts      # 消息处理
+│   │   ├── tooling.ts      # 工具调用
+│   │   └── ...
+│   └── ...
+├── components/             # UI组件
+│   ├── ConversationSidebar.vue
+│   ├── MessageList.vue
+│   ├── ToolCallDisplay.vue
+│   └── ...
+├── composables/            # 组合式函数
+│   ├── useMarkdownRenderer.ts
+│   ├── useScrollControl.ts
+│   └── ...
+└── stores/                 # Pinia状态管理
+    └── ...
+```

- **Web 用量面板**：点击右下角「用量统计」可查看 Token/CPU/内存/网络/存储实时状态。
- **CLI `/status`**：显示当前会话、上下文大小、容器资源等，日志位于 `logs/debug_stream.log`。
- **容器日志**：`logs/container_stats.log` 存储 `docker stats/inspect` 样本，可配合 `tail -f` 或外部监控系统。
+### 数据流
+
+1. **用户输入** → WebSocket/CLI
+2. **消息处理** → ContextManager 构建上下文
+3. **API 调用** → DeepSeekClient 发送请求
+4. **流式响应** → 实时解析工具调用
+5. **工具执行** → 各模块处理具体操作
+6. **结果返回** → 流式输出到前端
+7. **持久化** → ConversationManager 保存历史
+
+## 使用方法
+
+### Web 界面
+
+启动后访问 `http://localhost:8091`（默认端口）
+
+#### 基本操作
+
+1. **发送消息**: 在输入框输入内容，按 Enter 或点击发送按钮
+2. **创建对话**: 点击侧边栏的"新建对话"按钮
+3. **切换对话**: 在侧边栏点击历史对话
+4. **删除对话**: 右键对话项选择删除
+5. **搜索对话**: 使用侧边栏搜索框
+
+#### 工作区面板
+
+- **文件管理器**: 浏览和管理项目文件
+- **终端面板**: 查看和交互终端会话
+- **监控面板**: 查看系统统计信息
+
+#### 快捷键
+
+- `Ctrl/Cmd + Enter`: 发送消息
+- `Ctrl/Cmd + K`: 聚焦输入框
+- `Esc`: 停止生成
+
+### CLI 模式
+
+通过环境变量设置 `WEB_MODE=false` 启用 CLI 模式
+
+#### 命令
+
+- `help`: 显示帮助信息
+- `exit`: 退出系统
+- `status`: 显示系统状态
+- `memory`: 管理记忆
+- `clear`: 清空当前对话
+- `history`: 查看对话历史
+- `files`: 显示文件列表
+- `mode`: 切换运行模式
+- `terminals`: 显示终端列表
+- `conversations`: 列出所有对话
+- `load <id>`: 加载指定对话
+- `new`: 创建新对话
+
+### 工具使用示例
+
+#### 文件操作
+```
+请帮我创建一个 Python 脚本 hello.py，内容是打印 Hello World
+```
+
+#### 终端操作
+```
+请在终端中运行 npm install 安装依赖
+```
+
+#### 网络搜索
+```
+搜索一下 Python 3.12 的新特性
+```
+
+#### 子智能体
+```
+请创建一个子智能体帮我分析这个项目的代码结构
+```
+
+## 模型支持
+
+系统支持多个 AI 模型提供商：
+
+### Kimi (月之暗面)
+- `kimi-k2`: K2 系列模型
+- `kimi-k2.5`: K2.5 最新模型
+- 支持 256K 上下文窗口
+
+### DeepSeek
+- `deepseek-chat`: 快速模式
+- `deepseek-reasoner`: 推理模式
+
+### Qwen (通义千问)
+- `qwen3-max`: 最大模型
+- `qwen3.5-plus`: 增强版本
+- `qwen3-vl-plus`: 视觉语言模型
+
+### MiniMax
+- `MiniMax-M2.5`: M2.5 模型
+- 支持 204K 上下文窗口
+
+## 技能系统 (AgentSkills)
+
+可扩展的技能包系统，提供预定义的工作流：
+
+- **agent-build-standard**: 标准构建流程
+- **docx**: 文档处理
+- **frontend-design**: 前端设计辅助
+- **skill-creator**: 技能创建工具
+- **sub-agent-guide**: 子智能体使用指南
+- **terminal-guide**: 终端操作指南
+
+### 安全特性
+
+#### 宿主机模式安全
+
+- **路径白名单**: 禁止访问系统敏感目录
+- **路径遍历防护**: 防止 `..` 等路径攻击
+- **根路径保护**: 禁止操作根目录和系统目录
+- **符号链接检查**: 防止符号链接逃逸
+- **Linux 安全模式**: 可选的额外安全限制
+
+#### Docker 模式安全
+
+- **完全隔离**: 容器级别的进程和文件系统隔离
+- **资源配额**: 强制的 CPU、内存、存储限制
+- **网络隔离**: 可配置的网络访问控制
+- **只读挂载**: 支持只读文件系统挂载
+- **用户映射**: 容器内外用户权限映射
+
+#### 通用安全
+
+### 上传安全
+- 文件类型白名单
+- 文件大小限制
+- 恶意文件扫描
+- 压缩包安全检查
+
+### 路径安全
+- 禁止访问系统目录
+- 路径遍历防护
+- 符号链接检查
+
+### API 安全
+- CSRF 保护
+- 速率限制
+- Token 验证
+- Session 管理
+
+### API 安全
+- CSRF 保护
+- 速率限制
+- Token 验证
+- Session 管理
+
+## 使用场景建议
+
+### 宿主机模式适用场景
+
+1. **个人开发环境**
+   - 本地开发和测试
+   - 需要访问本地工具链
+   - 频繁的文件系统操作
+
+2. **可信环境**
+   - 单用户使用
+   - 内网环境
+   - 完全可控的代码执行
+
+3. **性能优先**
+   - 大量文件操作
+   - 编译构建任务
+   - 需要原生性能的场景
+
+4. **特殊工具依赖**
+   - 需要特定系统工具
+   - 硬件设备访问
+   - 系统级操作
+
+### Docker 模式适用场景
+
+1. **多用户服务**
+   - 公共服务部署
+   - 多租户环境
+   - 需要用户隔离
+
+2. **生产环境**
+   - 对外提供服务
+   - 需要稳定性保证
+   - 资源配额管理
+
+3. **安全优先**
+   - 执行不可信代码
+   - 需要严格隔离
+   - 防止恶意操作
+
+4. **环境标准化**
+   - 统一运行环境
+   - 依赖管理
+   - 可复现的执行环境
+
+## 配置说明
+
+主要配置项（通过环境变量或 `.env` 文件）：
+
+### API 配置
+- `API_BASE_KIMI`: Kimi API 地址
+- `API_KEY_KIMI`: Kimi API 密钥
+- `API_BASE_DEEPSEEK`: DeepSeek API 地址
+- `API_KEY_DEEPSEEK`: DeepSeek API 密钥
+
+### 服务配置
+- `WEB_SERVER_PORT`: Web 服务器端口（默认 8091）
+- `DEFAULT_PROJECT_PATH`: 默认项目路径
+
+### 限制配置
+- `MAX_ITERATIONS_PER_TASK`: 单任务最大迭代次数
+- `MAX_TOTAL_TOOL_CALLS`: 总工具调用次数限制
+- `MAX_UPLOAD_SIZE`: 最大上传文件大小
+- `PROJECT_MAX_STORAGE_MB`: 项目存储限制
+
+### 运行环境配置
+
+**宿主机模式**:
+- `TERMINAL_SANDBOX_MODE=host`: 启用宿主机模式
+- `HOST_PROJECT_PATH`: 指定项目路径（可选）
+- `LINUX_SAFETY`: Linux 安全保护开关
+
+**Docker 模式**:
+- `TERMINAL_SANDBOX_MODE=docker`: 启用容器模式
+- `TERMINAL_SANDBOX_IMAGE`: Docker 镜像（如 ubuntu:22.04）
+- `TERMINAL_SANDBOX_CPUS`: CPU 限制（如 2）
+- `TERMINAL_SANDBOX_MEMORY`: 内存限制（如 4g）
+- `TERMINAL_SANDBOX_MOUNT_PATH`: 容器内挂载路径
+- `TERMINAL_SANDBOX_NETWORK`: 网络模式
+- `TERMINAL_SANDBOX_BINDS`: 额外挂载目录
+
+## 数据存储
+
+### 目录结构
+
+```
+data/                       # 数据目录
+├── conversations/          # 对话历史
+│   └── <conversation_id>.json
+├── memory/                 # 记忆文件
+│   ├── main_memory.md
+│   └── task_memory.md
+└── personalization.json    # 个性化配置
+
+logs/                       # 日志目录
+├── tasks/                  # 任务日志
+├── errors/                 # 错误日志
+└── *.log
+
+sub_agent/                  # 子智能体数据
+└── tasks/                  # 任务目录
+    └── <task_id>/
+        ├── task.txt
+        ├── output.json
+        └── progress.jsonl
+
+users/                      # 用户数据
+└── <username>/
+    ├── data/
+    ├── project/
+    └── ...
+```
+
+## 扩展开发
+
+### 添加自定义工具
+
+1. 在 `modules/custom_tool_registry.py` 注册工具
+2. 实现工具执行逻辑
+3. 在 `core/tool_config.py` 添加工具定义
+4. 重启系统加载新工具
+
+### 添加新模型
+
+1. 在 `config/model_profiles.py` 添加模型配置
+2. 在 `utils/api_client.py` 实现 API 调用
+3. 配置环境变量
+
+### 创建技能包
+
+1. 在 `agentskills/` 目录创建技能文件夹
+2. 编写技能定义和提示词
+3. 在前端注册技能
+
+## 性能优化
+
+- **流式输出**: 实时显示生成内容
+- **增量上下文**: 仅发送必要的上下文
+- **工具结果缓存**: 避免重复操作
+- **对话压缩**: 自动总结长对话
+- **并发处理**: 子智能体并行执行
+- **资源池化**: 复用终端会话和容器
+
+## 故障排查
+
+### 常见问题
+
+1. **连接失败**: 检查 API 密钥和网络连接
+2. **工具调用失败**: 查看日志文件定位错误
+3. **容器启动失败**: 检查 Docker 配置和权限
+4. **文件操作失败**: 确认路径权限和存储空间
+5. **对话加载失败**: 检查数据目录完整性
+
+### 日志位置
+
+- 主日志: `logs/main.log`
+- 错误日志: `logs/errors/`
+- 任务日志: `logs/tasks/`
+- Web 服务器: `web_server.log`
+
+## 版本信息
+
+当前版本: 4.1.0
+
+主要更新：
+- 完整的对话持久化系统
+- 子智能体并行执行
+- 多模型支持
+- 容器沙箱隔离
+- 个性化配置
+- 监控仪表板

 ---

-## 常见命令
-
-| 命令 | 说明 |
-| --- | --- |
-| `/help` | CLI 指令列表 |
-| `/status` | 查看系统/容器资源状态 |
-| `read_file` / `write_file` / `edit_file` | 读写项目文件（自动通过容器代理） |
-| `terminal_session` / `terminal_input` | 管理多终端会话 |
-| `run_command` / `run_python` | 工具容器快速执行命令/Python 代码 |
-| `todo_*`, `update_memory` | 维护待办与长期记忆 |
-
---
-
-## 配置速览
-
-`config/terminal.py` 支持以下常用变量：
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `TERMINAL_SANDBOX_IMAGE` | `my-agent-shell:latest` | 终端容器镜像 |
-| `TERMINAL_SANDBOX_NETWORK` | `bridge` | 容器网络模式（`none`/`bridge`/`host` 等） |
-| `TERMINAL_SANDBOX_CPUS` | `0.5` | 上限 CPU |
-| `TERMINAL_SANDBOX_MEMORY` | `1g` | 上限内存 |
-| `TERMINAL_SANDBOX_REQUIRE` | `0` | 若容器启动失败是否降级宿主机模式 |
-| `PROJECT_MAX_STORAGE_MB` | `2048` | 每个工作区的磁盘配额 |
-| `MAX_ACTIVE_USER_CONTAINERS` | `8` | 并发容器数量 |
-
-更多配置请查阅 `.env.example`。
-
---
-
-## 开发建议
-
-1. **安全**：新增模块前请优先考虑是否可以在容器中实现，避免回退宿主机；如需联网，务必评估外部依赖。上传检测现阶段默认关闭 ClamAV（`UPLOAD_CLAMAV_ENABLED=0`），以免 1GB+ 的常驻内存占用，必要时可以在环境变量中显式打开。
-2. **日志**：尽量使用 `utils.logger.setup_logger`，便于统一收集。
-3. **测试**：`users/<username>/project/test_scripts/` 提供内存压测脚本，可验证容器限制是否生效；可在 `test/` 下添加更多集成测试。
-4. **文档**：第二阶段总结见 `doc/phases/phase2_summary.md`，安全基线更新见 `doc/security/security_review.md`。
-5. **前端组件化**：`doc/frontend/phase1_setup.md` 与 `doc/frontend/phase2_sidebar.md` 记录了脚手架与侧栏改造，可用以下命令构建体验版 UI；执行 `localStorage.setItem('useNewFrontend','1')` 或设置 `window.__USE_NEW_FRONTEND__ = true` 可加载新入口，移除该键即回退 legacy UI：
-
-   ```bash
-   npm install
-   npm run dev   # watch 构建 static/dist
-   npm run build # 生产包
-   ```
-
---
-
-## Roadmap
-
- [ ] CSRF / 防爆破 / 会话绑定设备指纹
- [ ] 文件上传内容扫描与白名单策略
- [ ] 用户/会话数据迁移到数据库并加密备份
- [ ] 自动化测试与 CI（含容器镜像构建）
- [ ] Skeleton Web UI（组件化、国际化、Dark Mode）
-
-欢迎通过 Issue/PR 贡献。
+**注意**: 本系统仅供学习和研究使用，请遵守相关 API 服务商的使用条款。