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