# AI Agent 系统 一个功能完整的 AI 智能体系统，支持多模态交互、子智能体协作、实时终端操作和丰富的工具集成。 ## 核心特性 ### 🎯 多模式运行 系统支持三种运行模式，适应不同场景需求： - **快速模式 (fast)**: 无思考过程，快速响应，适合简单任务 - **思考模式 (thinking)**: 启用推理过程，提供更深入的分析 - **深度思考模式 (deep)**: 最强推理能力，适合复杂问题 ### 🌐 双端架构 - **Web 模式**: 基于 Flask + REST 任务轮询 + Vue 3 的现代化 Web 界面（保留 Socket.IO 兼容通道） - 实时消息流式传输 - 多对话管理 - 可视化文件管理器 - 终端会话面板 - 监控仪表板 - **CLI 模式**: 命令行交互界面，适合开发和自动化场景 ### 🤖 子智能体系统 支持创建独立的子智能体处理复杂任务： - **并行执行**: 最多同时运行多个子智能体 - **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史 - **任务隔离**: 子智能体在独立进程中运行，互不干扰 - **状态追踪**: 实时监控子智能体的执行状态和进度 - **后台运行**: 支持后台模式，主智能体可继续处理其他任务 工具接口： - `create_sub_agent`: 创建并启动子智能体 - `wait_sub_agent`: 等待子智能体完成并获取结果 - `close_sub_agent`: 终止运行中的子智能体 ### 🛠️ 丰富的工具集 系统提供分类管理的工具集，可按需启用/禁用： #### 文件操作 - `read_file`: 读取文件内容 - `create_file` / `write_file`: 创建和写入文件 - `edit_file`: 精确编辑文件内容 - `delete_file` / `rename_file`: 文件管理 - `create_folder`: 创建目录 - `list_files`: 列出目录内容 - `search_files`: 搜索文件 #### 终端操作 **实时终端会话**: - `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 TERMINAL_SANDBOX_MODE=host HOST_PROJECT_PATH=/path/to/project # 可选，指定项目路径 ``` #### Docker 容器模式 (Docker Mode) 在隔离的 Docker 容器中执行，适合多用户和生产环境： - **环境隔离**: 每个用户独立的容器环境 - **资源限制**: CPU、内存、存储配额管理 - **安全执行**: 代码在隔离环境中运行，保护宿主机 - **持久化存储**: 项目文件挂载到容器 - **网络控制**: 可配置网络访问策略 - **环境一致**: 统一的运行环境，避免依赖问题 适用场景： - 多用户共享服务 - 生产环境部署 - 需要安全隔离 - 资源配额管理 配置： ```bash TERMINAL_SANDBOX_MODE=docker TERMINAL_SANDBOX_IMAGE=ubuntu:22.04 TERMINAL_SANDBOX_CPUS=2 TERMINAL_SANDBOX_MEMORY=4g TERMINAL_SANDBOX_MOUNT_PATH=/workspace ``` #### 模式对比 | 特性 | 宿主机模式 | Docker 模式 | |------|-----------|------------| | 性能 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | | 安全隔离 | ⭐⭐ | ⭐⭐⭐⭐⭐ | | 资源控制 | ⭐⭐ | ⭐⭐⭐⭐⭐ | | 部署复杂度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | | 环境一致性 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | 工具访问 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ### 👥 多用户管理 完整的用户系统： - **用户认证**: 基于 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 # Socket.IO 连接与兼容事件处理（聊天主链路已迁移到 REST 任务轮询） │ └── ... ├── 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状态管理 └── ... ``` ### 数据流 1. **用户输入** → REST API（Web）/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 主要更新： - 完整的对话持久化系统 - 子智能体并行执行 - 多模型支持 - 容器沙箱隔离 - 个性化配置 - 监控仪表板 --- **注意**: 本系统仅供学习和研究使用，请遵守相关 API 服务商的使用条款。