16 KiB
16 KiB
AI Agent 系统技术文档（v5.x）
定位：多用户、多终端的智能开发助手，用于实验/学习真实开发工作流中的“智能体 + 工具链”。默认每个登录用户拥有独立 Docker 容器，CLI 与 Web 共用同一后端核心与工具体系。
说明：本文基于对仓库主要代码 (>80%) 的通读梳理，强调设计意图与实现路径，尽量少贴代码，多用描述/流程/表格呈现。路径均相对仓库根目录agents/。
目录
- 系统概览与设计目标
- 后端架构
- 前端架构
- 板块分类（目录/角色）
- 上下文构建
- 工具实现
- 安全与权限模型
- 部署与运行时架构
- API 与协议
- 前端状态管理与路由
- 工具/能力目录
- 监控与日志
- 性能与容量
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
- CLI：
- 层次拆分
- 会话与工具编排：
core/main_terminal.py负责运行模式切换、工具分发、对话生命周期、聚焦文件管理。 - 能力模块：
modules/提供容器、文件、终端、搜索、记忆、待办、子代理、上传安全、个性化、管理员策略、平衡查询等。 - 通用工具：
utils/（上下文/对话持久化、日志、工具结果格式化、终端工厂、API 客户端）。 - 配置：
config/按域拆分（terminal/model/security/uploads/limits/ui/...），环境变量优先于默认。
- 会话与工具编排：
2.2 请求与执行链路
- HTTP/Socket 请求由
web_server.py路由，完成鉴权、限流、CSRF、请求体校验。 - 转交
WebTerminal（继承MainTerminal）处理：统一的工具指令、对话上下文管理。 MainTerminal根据工具名调用modules/*实际执行，绝大多数操作通过容器代理在用户专属容器内完成。- 结果写回上下文（
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 扩展流程（新增工具）
- 在
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
- CLI：
- 容器拓扑
- 宿主机运行 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/conversationsCRUD、搜索、压缩、统计、复制、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 载荷示例、时序图、部署脚本、常见故障排查），可在此文档基础上增补对应章节。