# AI Agent 系统技术文档（v5.x） > **定位**：多用户、多终端的智能开发助手，用于实验/学习真实开发工作流中的“智能体 + 工具链”。默认每个登录用户拥有独立 Docker 容器，CLI 与 Web 共用同一后端核心与工具体系。 > **说明**：本文基于对仓库主要代码 (>80%) 的通读梳理，强调设计意图与实现路径，尽量少贴代码，多用描述/流程/表格呈现。路径均相对仓库根目录 `agents/`。 --- ## 目录 1. 系统概览与设计目标 2. 后端架构 3. 前端架构 4. 板块分类（目录/角色） 5. 上下文构建 6. 工具实现 7. 安全与权限模型 8. 部署与运行时架构 9. API 与协议 10. 前端状态管理与路由 11. 工具/能力目录 12. 监控与日志 13. 性能与容量 --- ## 1. 系统概览与设计目标 - **设计目标**：为多用户提供可隔离的智能开发环境，覆盖聊天、代码编辑、文件/终端操作、子代理并行、可观测性与上传安全；探索不同运行模式（fast/thinking/deep）的智能体工作方式。 - **核心卖点**： - 单用户独立容器：隔离命令和文件操作。 - 工具链丰富：终端、文件、搜索、OCR/VLM、Todo/记忆、子代理。 - 虚拟显示器：前端可回放指针/窗口/右键/进度动画。 - 资源用量面板：实时 CPU/内存/网速/磁盘配额与 token 统计。 - **非生产声明**：安全基线（密钥治理、CORS、日志脱敏、数据库权限等）尚未完全落地，仍属实验性。 --- ## 2. 后端架构 ### 2.1 技术栈与层次 - **语言/框架**：Python 3.11，Flask + Socket.IO；局部使用 asyncio（搜索等）。 - **入口** - CLI：`main.py` → `core/main_terminal.py` - Web：`web_server.py` → `core/web_terminal.py` - **层次拆分** 1) **会话与工具编排**：`core/main_terminal.py` 负责运行模式切换、工具分发、对话生命周期、聚焦文件管理。 2) **能力模块**：`modules/` 提供容器、文件、终端、搜索、记忆、待办、子代理、上传安全、个性化、管理员策略、平衡查询等。 3) **通用工具**：`utils/`（上下文/对话持久化、日志、工具结果格式化、终端工厂、API 客户端）。 4) **配置**：`config/` 按域拆分（terminal/model/security/uploads/limits/ui/...），环境变量优先于默认。 ### 2.2 请求与执行链路 1. HTTP/Socket 请求由 `web_server.py` 路由，完成鉴权、限流、CSRF、请求体校验。 2. 转交 `WebTerminal`（继承 `MainTerminal`）处理：统一的工具指令、对话上下文管理。 3. `MainTerminal` 根据工具名调用 `modules/*` 实际执行，绝大多数操作通过容器代理在用户专属容器内完成。 4. 结果写回上下文（`ContextManager`），经 Socket.IO 推送或 HTTP 响应返回前端。 ### 2.3 容器隔离与生命周期 - **创建/复用**：`modules/user_container_manager.py` 在用户登录时调用 `ensure_container`，基于 `.env`/`config/terminal.py` 的镜像、网络、CPU/内存配置启动容器；达到并发上限返回“资源繁忙”。 - **文件/命令入口**：所有文件操作走 `container_file_proxy.py`，命令执行走 `terminal_ops.py`/`toolbox_container.py`；宿主机只做卷挂载与日志。 - **回收**：退出或空闲时 `release_container` 杀掉容器；监控采样写入 `logs/container_stats.log`。 - **配额**：CPU/内存、磁盘（`PROJECT_MAX_STORAGE_MB`），并发容器数 `MAX_ACTIVE_USER_CONTAINERS`。 ### 2.4 数据与状态 - 用户与工作区：`modules/user_manager.py` 将账号、邀请码、工作区目录记录到 `data/users.json`、`data/invite_codes.json`。 - 对话持久化：`utils/conversation_manager.py` -> `data/conversations/*.json` + `index.json`。 - 日志：`logs/`（运行、容器监控、上传扫描等）。 - 个性化/策略：`data/personalization.json`、`config/paths.py` 定位的策略文件等。 --- ## 3. 前端架构 ### 3.1 技术栈 - Vite + Vue 3 + TypeScript，Pinia 状态管理，SCSS 样式；无前端路由库，由后端多路径挂载同一 SPA。 ### 3.2 入口与构建 - `static/src/main.ts` 创建应用与 Pinia；`App.vue` 为根组件。 - 构建：`npm run build` → 产物 `static/dist`，由 Flask `/static/*` 提供；开发监听 `npm run dev`。 ### 3.3 关键组件/目录 - `components/chat/*`：聊天区、消息渲染、动作/工具反馈。 - `components/chat/monitor/*`：`MonitorDirector.ts` 驱动虚拟显示器，重放指针/窗口/右键/进度气泡。 - `components/files` / `panels` / `sidebar` / `input`：文件树、资源抽屉、侧栏、输入区。 - 样式/主题：`styles/` 与 `utils/theme.ts`。 - 管理与实验：`components/admin`, `components/experiments`。 ### 3.4 前后端协同 - Socket.IO：用于消息流、终端输出、工具进度、监控数据。 - HTTP：用于文件列表/上传、对话 CRUD、状态/配额、策略、个性化等。 --- ## 4. 板块分类（目录/角色） - `core/`：终端编排、工具路由、模式控制（`main_terminal.py`, `web_terminal.py`, `tool_config.py`）。 - `modules/`：容器、终端、文件、搜索、记忆、Todo、子代理、上传安全、OCR/VLM、管理员策略、平衡查询、个性化、用量统计。 - `utils/`：上下文与对话持久化、日志、工具结果格式化、终端工厂。 - `config/`：领域配置（terminal/model/security/uploads/limits/ui/...）。 - `static/`：前端源码与构建产物；`chat/monitor` 是虚拟显示器核心。 - `doc/`：安全评审、前端改造记录等。 - `docker/`：终端容器镜像 Dockerfile。 - `data/`、`users/`、`logs/`：运行时数据、用户工作区、日志与监控样本。 --- ## 5. 上下文构建 - **核心组件**：`utils/context_manager.py` - 维护对话历史、聚焦文件缓存、Todo/记忆状态、图片存在标记、token 统计。 - 通过 `ConversationManager` 读写 `data/conversations/` 并维护 `index.json` 完整性。 - 支持文件备注与临时文件缓存；聚焦文件内容用于 prompt 聚合。 - 提供 token 累计写入 `data/token_totals.json`，并向前端资源面板提供统计。 - **模型 profile 替换**：`config/model_profiles.py` 定义不同模型的系统提示、占位符替换；`MainTerminal` 在初始化时套用，并支持管理员禁用模型。 - **上下文限制**：`config/limits.py` 设定最大上下文、文件读取大小、行前后文、匹配条数等，防止大文件压垮模型。 --- ## 6. 工具实现 ### 6.1 工具分类与开关 - 定义于 `core/tool_config.py`，九类：网络检索、文件编辑、阅读聚焦、实时终端、终端指令、记忆、待办、子智能体、彩蛋。 - 默认启用状态可被管理员策略 (`admin_policy_manager.py`) 或个性化配置覆盖；禁用时可选择静默或提示。 ### 6.2 典型工具链路 - **终端类**（实时 / 一次性命令） - 模块：`modules/terminal_ops.py`, `modules/terminal_manager.py`, `modules/persistent_terminal.py`, `modules/toolbox_container.py`。 - 特性：危险命令检测、超时与输出裁剪 (`config/limits.py`)、动态选择 python 命令、容器/主机模式切换；交互式终端会话可订阅输出，快照支持行/字符上限。 - 工具容器：`toolbox_container` 为 `run_command/run_python` 维护独立容器，命令前自动 `cd` 到目标路径。 - **文件类** - 模块：`modules/file_manager.py` 调用 `modules/container_file_proxy.py`，后者在容器内执行安全脚本，验证路径、限制大小、阻止根目录写入与路径越界。 - 支持创建/删除/重命名/移动/读文件片段/行编辑、计算项目体积（配额检查）。 - **搜索类** - 模块：`modules/search_engine.py` 调 Tavily，支持 topic（general/news/finance）、时间范围、天数、国家过滤；格式化结果并返回。 - **记忆/Todo** - 模块：`modules/memory_manager.py`, `modules/todo_manager.py`，JSON 持久化，生成指导文本注入上下文。 - **子智能体** - 模块：`modules/sub_agent_manager.py`，可创建/等待/关闭子代理任务，前端并行查看。 - **OCR/VLM** - 模块：`modules/ocr_client.py`，调用 OpenAI 兼容接口；大小上限 10MB，自动推断 MIME，支持 VLM 分析与 OCR。 - **上传安全** - 模块：`modules/upload_security.py`，上传先落地隔离目录，校验大小/后缀，选配 ClamAV 扫描，审计日志按用户分文件记录。 - **管理员策略 / 模型余额** - `modules/admin_policy_manager.py`：按 global/role/user/invite 合并策略，控制工具类别、模型禁用、UI 开关；持久化到 `config.paths.ADMIN_POLICY_FILE`。 - `modules/balance_client.py`：读取 `.env`/环境变量查询 Kimi/DeepSeek/Qwen 余额，用于管理面板。 ### 6.3 扩展流程（新增工具） 1) 在 `modules/` 实现功能；2) 在 `core/main_terminal.py` 注册调用；3) 在 `core/tool_config.py` 分组；4) 若需前端入口，扩展对应 store/UI；5) 在 `.env.example` / `config/*` 补充配置。 --- ## 7. 安全与权限模型 - **鉴权/账户**：`modules/user_manager.py` 使用 JSON 存储用户与邀请码，密码 PBKDF2 哈希；角色字段支持 admin/user。 - **会话与 CSRF**：Flask session；`/api/csrf-token` 提供 token；写操作校验 CSRF。 - **速率限制**：`web_server.py` 对关键接口/登录失败计数做限制（依赖自定义计数器）。 - **上传隔离**：`upload_security.py` 强制暂存+扫描+审计；可选启用 ClamAV。 - **容器隔离**：单用户单容器，命令/文件均在容器中执行；镜像、网络、CPU、内存、卷绑定受配置限制。 - **管理员策略**：可禁用工具类别、模型、UI 区块；前端根据策略隐藏/禁用。 - **已知风险（需生产前修复）**：硬编码密钥/SECRET_KEY、CORS 过宽、本地 JSON 无加密/并发保护、缺少数据库与权限细粒度、日志/上传脱敏不足。详见 `doc/security/security_review.md`。 --- ## 8. 部署与运行时架构 - **启动流程** - CLI：`python main.py`（交互式选择项目路径/模式） - Web：`python web_server.py`（默认 8091） - 前端静态：Flask `/static/*` 直接服务 `static/dist` - **容器拓扑** - 宿主机运行 Flask + Socket.IO；登录即创建用户容器，挂载用户工作区；命令/文件/工具均走容器；监控采样写日志并推前端。 - **关键配置**（均可由 `.env` 覆盖）： - 终端/容器：`TERMINAL_SANDBOX_IMAGE/NETWORK/CPUS/MEMORY/MOUNT_PATH/MAX_ACTIVE_USER_CONTAINERS/TERMINAL_SANDBOX_REQUIRE` - 磁盘：`PROJECT_MAX_STORAGE_MB`（及字节版） - 上传：`MAX_UPLOAD_SIZE`、`UPLOAD_ALLOWED_EXTENSIONS`、`UPLOAD_CLAMAV_*` - 模型/API：`config/api.py` 中的 AGENT_API_* / 各模型 key - 安全：`config/security.py` 中的 CORS/安全头；`config/auth.py` 的管理员默认凭据 - **前端构建**：`npm install && npm run build`，可 `npm run dev` 监听但不启 Web 服务器。 --- ## 9. API 与协议 ### 9.1 REST（主要路由分组） - 鉴权：`/login` `/register` `/logout` `/api/csrf-token` - 状态/资源：`/api/status` `/api/container-status` `/api/project-storage` `/api/usage` `/api/thinking-mode` - 配置/策略/个性化：`/api/tool-settings` `/api/model` `/api/personalization` `/api/admin/policy` `/api/admin/balance` `/api/effective-policy` - 文件与上传：`/api/files` `/api/gui/files/*`（列表/创建/删除/重命名/复制/移动/上传/下载/批量下载/文本读写） - 对话：`/api/conversations` CRUD、搜索、压缩、统计、复制、review 导出、token 统计 - Todo/记忆/聚焦：`/api/todo-list` `/api/memory` `/api/focused` - 监控：`/api/gui/monitor_snapshot` - 静态/工作区：`/workspace/*` `/user_upload/*` `/static/*` - 管理面板：`/admin/monitor` `/admin/assets/*` ### 9.2 Socket.IO 事件 - 连接/断开：`connect` / `disconnect` - 消息与命令：`send_message`（聊天流）、`send_command`（终端输入） - 终端订阅：`terminal_subscribe` / `terminal_unsubscribe` / `get_terminal_output` - 任务控制：`stop_task` - 客户端日志：`client_chunk_log` / `client_stream_debug_log` ### 9.3 返回格式与约定 - REST 多数返回 `{success, data|error}`，错误含 code/message。 - 终端输出/工具进度通过房间广播，通常按用户/会话分组。 - 对话导出使用 `build_review_lines` 生成简化文本（含 tool_call/结果）。 --- ## 10. 前端状态管理与路由 - **Pinia stores（按域）** - 消息/会话：`chat`, `conversation`, `chatActions` - 工具/显示器：`tool`, `monitor` - 资源：`resource`（容器状态、token 统计、存储配额，带退避轮询） - 连接：`connection`（Socket 连接/重连） - 文件/上传：`file`, `upload` - 其他：`subAgent`, `personalization`, `policy`, `ui`, `input`, `focus` - **视图切换**：无 vue-router，由状态决定显示聊天/虚拟显示器/资源抽屉/文件面板等；后端不同 URL 挂载同一 SPA，减少刷新与路由复杂度。 - **显示器动画**：`MonitorDirector` 接收工具/终端事件流，驱动鼠标指针、窗口、右键菜单、进度气泡，配合 `progressMap` 映射不同工具的动效。 --- ## 11. 工具/能力目录（快速清单） - 网络检索：`web_search`, `extract_webpage`, `save_webpage` - 文件编辑：`create_file`, `append_to_file`, `modify_file`, `delete_file`, `rename_file`, `create_folder` - 阅读聚焦：`read_file`, `focus_file`, `unfocus_file`, `vlm_analyze`, `ocr_image`, `view_image` - 实时终端：`terminal_session`, `terminal_input`, `terminal_snapshot`, `terminal_reset`, `sleep` - 终端指令：`run_command`, `run_python` - 记忆：`update_memory` - 待办：`todo_create`, `todo_update_task`, `todo_finish`, `todo_finish_confirm` - 子智能体：`create_sub_agent`, `wait_sub_agent`, `close_sub_agent` - 彩蛋实验：`trigger_easter_egg`（默认禁用，可静默） --- ## 12. 监控与日志 - **容器监控**：`modules/container_monitor.py` 采集 `docker stats/inspect`，写 `logs/container_stats.log`，经 `/api/container-status` 推送；前端计算网速/CPU/内存并呈现资源抽屉。 - **存储配额**：`/api/project-storage` 返回已用/上限/百分比，前端定时退避轮询。 - **对话/工具日志**：`data/conversations/` 持久化会话与工具调用；`logs/` 记录运行/调试；上传隔离审计按用户写独立日志。 - **虚拟显示器**：无需额外文件，基于实时事件重建动画。 - **平衡查询**：`modules/balance_client.py` 提供模型账户余额，用于管理面板。 --- ## 13. 性能与容量 - **默认配额**：CPU 0.5 / 内存 1GB（容器），磁盘 `PROJECT_MAX_STORAGE_MB` 默认 2048MB，并发容器 `MAX_ACTIVE_USER_CONTAINERS` 默认 8；命令超时/输出大小在 `config/limits.py`。 - **瓶颈与优化建议**： - Flask/Socket.IO 单进程在高并发下受限，可用多 worker 或拆分执行层（FastAPI + 任务队列）。 - Tavily/模型为外部依赖，需缓存、降级与重试策略。 - 卷 IO 与容器冷启动在高频文件/命令场景会拉长延迟，可预热容器/镜像、缓存依赖。 - 监控轮询与虚拟显示器事件在弱网下需扩大间隔；前端已实现退避策略但可进一步按可见性暂停。 - 缺失 CI/CD 与自动化测试，建议补充 lint+pytest+Docker build pipeline 以防回归。 --- ### 附：容器基础镜像 - 终端/工具容器镜像使用 `python:3.11-slim`（Debian Bookworm 精简版）为基底，详见 `docker/terminal.Dockerfile:1`。系统包安装了 bash/git/build-essential/ssh/zip/unzip/locales/tzdata/iputils-ping 等，虚拟环境位于 `/opt/agent-venv` 并通过 `PATH` 暴露。该镜像可按需重建以适配额外工具。 --- ### 结语 本文覆盖系统结构、运行机制、工具链路、前后端协同、安全与运维要点。若需进一步细化（如 API 载荷示例、时序图、部署脚本、常见故障排查），可在此文档基础上增补对应章节。