From 7496d8a3c62f66d9343a2b667fef3e64565b9f0f Mon Sep 17 00:00:00 2001 From: JOJO <1498581755@qq.com> Date: Sun, 5 Apr 2026 02:01:32 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99README.md=EF=BC=8C?= =?UTF-8?q?=E8=AF=A6=E7=BB=86=E4=BB=8B=E7=BB=8D=E7=B3=BB=E7=BB=9F=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E5=92=8C=E4=BD=BF=E7=94=A8=E6=96=B9=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加完整的功能特性说明（多模式运行、双端架构、子智能体等） - 详细说明宿主机模式和Docker模式的特点和适用场景 - 补充工具集、对话管理、个性化配置等核心功能 - 添加架构设计、数据流、目录结构说明 - 提供使用方法、配置说明、扩展开发指南 - 强调两种运行模式同等重要，各有优势 Co-Authored-By: Claude Sonnet 4.5 --- README.md | 685 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 555 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index d9e2421..399f9ac 100644 --- 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 `: 加载指定对话 +- `/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//` 下初始化个人工作区与容器。 +#### 模式对比 -### 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 `: 加载指定对话 +- `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/ # 对话历史 +│ └── .json +├── memory/ # 记忆文件 +│ ├── main_memory.md +│ └── task_memory.md +└── personalization.json # 个性化配置 + +logs/ # 日志目录 +├── tasks/ # 任务日志 +├── errors/ # 错误日志 +└── *.log + +sub_agent/ # 子智能体数据 +└── tasks/ # 任务目录 + └── / + ├── task.txt + ├── output.json + └── progress.jsonl + +users/ # 用户数据 +└── / + ├── 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//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 服务商的使用条款。