248 lines
16 KiB
Markdown
248 lines
16 KiB
Markdown
# 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 载荷示例、时序图、部署脚本、常见故障排查），可在此文档基础上增补对应章节。
|