159 lines
6.9 KiB
Markdown
159 lines
6.9 KiB
Markdown
# AI Agent 系统（v5.x）
|
||
|
||
多用户、多终端的智能开发助手。每位登录用户都会获得一个独立 Docker 容器，所有终端、一次性命令以及文件操作都在容器内完成；宿主机负责挂载与备份。配合 **虚拟显示器** 与资源面板，可实时回放工具动作并观察 CPU / 内存 / 网络 / 磁盘配额。
|
||
|
||
> ⚠️ **定位**：学习与实验用项目，主要用于探索“智能体 + 真实 Dev Workflow”。代码大量由 AI 生成，尚未达到生产级别，请谨慎部署。
|
||
|
||
---
|
||
|
||
## 近期亮点（v5）
|
||
|
||
| 能力 | 说明 |
|
||
| --- | --- |
|
||
| **虚拟显示器回放** | `static/src/components/chat/monitor` 提供指针/窗口/右键菜单动画，可回放创建文件、终端执行等工具场景，并展示进度气泡。 |
|
||
| **单用户-单容器** | `modules/user_container_manager.py` 登录即拉起专属容器，退出或空闲自动销毁；CLI/Web/工具共用同一容器，配额在 `.env` 设置。 |
|
||
| **容器内文件代理** | `modules/container_file_proxy.py` 通过 `docker exec` 沙箱化 `create/read/search/write/modify`，宿主机不直接写用户代码。 |
|
||
| **实时资源与管理员面板** | 用量抽屉实时展示 Token / CPU / 内存 / 网络 / 存储；管理员可在 `/admin/monitor` 查看全局用量与上传审计。 |
|
||
| **子代理与多工具链路** | 支持子代理启动/终止，待办、记忆、阅读、终端等工具协同；前端可随时切换聊天/显示器视图。 |
|
||
|
||
---
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
┌─────────────┐ ┌────────────────┐ ┌────────────────────────┐
|
||
│ Browser │◀───▶│ Flask + Socket │◀───▶│ UserContainerManager │
|
||
│ (Vue 前端) │ Web │ Web Server │调度 │ (管理 Docker 容器) │
|
||
└─────────────┘ │ ├─ WebTerminal │ └────┬───────────────────┘
|
||
│ └─ REST APIs │ │
|
||
└────────────────┘ ▼
|
||
Container
|
||
├─ PersistentTerminal / Toolbox
|
||
├─ Container File Proxy
|
||
└─ Sub Agent / Tool Runtime
|
||
```
|
||
|
||
- **core/**：`MainTerminal` / `WebTerminal` 负责命令路由、上下文管理与工具调度。
|
||
- **modules/**：终端管理、文件代理、容器调度、搜索、记忆等独立能力模块。
|
||
- **utils/**：模型 API 客户端、上下文压缩、日志、终端工厂等辅助工具。
|
||
- **static/**：Vue + Socket.IO 单页应用；`chat/monitor` 为虚拟显示器动画层。
|
||
- **docker/**：终端镜像 Dockerfile 及工具容器依赖清单。
|
||
|
||
更多目录说明请查阅 `tree -L 2` 或仓库内注释。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境需求
|
||
|
||
- Python 3.11+
|
||
- Docker 20+（需启用 cgroup v1/v2 任一，默认通过 `bridge` 网络运行容器）
|
||
- Node 18+（仅在需要本地构建/开发前端时）
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
# 前端开发/构建时可选
|
||
npm install
|
||
```
|
||
|
||
### 3. 配置
|
||
|
||
1. 复制 `.env.example` → `.env`，填入以下关键变量：
|
||
- `AGENT_API_*`：兼容 OpenAI API 的模型服务
|
||
- `WEB_SECRET_KEY`：Flask session 密钥
|
||
- `TERMINAL_SANDBOX_*`：容器镜像/资源/网络（默认 `my-agent-shell:latest` + `bridge`）
|
||
2. 若需定制终端镜像：
|
||
```bash
|
||
docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .
|
||
```
|
||
|
||
### 4. 运行
|
||
|
||
```bash
|
||
# CLI 模式
|
||
python main.py
|
||
|
||
# Web 模式（默认 8091）
|
||
python web_server.py
|
||
```
|
||
|
||
首次启动会在 `users/<username>/` 下初始化个人工作区与容器。
|
||
|
||
### 5. 构建前端（可选）
|
||
|
||
```bash
|
||
npm run build # 产物输出到 static/dist
|
||
# 开发监听（仅构建，不启动服务）
|
||
npm run dev
|
||
```
|
||
|
||
---
|
||
|
||
## 监控与调试
|
||
|
||
- **Web 用量面板**：点击右下角「用量统计」可查看 Token/CPU/内存/网络/存储实时状态。
|
||
- **CLI `/status`**：显示当前会话、上下文大小、容器资源等，日志位于 `logs/debug_stream.log`。
|
||
- **容器日志**：`logs/container_stats.log` 存储 `docker stats/inspect` 样本，可配合 `tail -f` 或外部监控系统。
|
||
|
||
---
|
||
|
||
## 常见命令
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `/help` | CLI 指令列表 |
|
||
| `/status` | 查看系统/容器资源状态 |
|
||
| `read_file` / `modify_file` | 读写项目文件（自动通过容器代理） |
|
||
| `terminal_session` / `terminal_input` | 管理多终端会话 |
|
||
| `run_command` / `run_python` | 工具容器快速执行命令/Python 代码 |
|
||
| `todo_*`, `update_memory` | 维护待办与长期记忆 |
|
||
|
||
---
|
||
|
||
## 配置速览
|
||
|
||
`config/terminal.py` 支持以下常用变量：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `TERMINAL_SANDBOX_IMAGE` | `my-agent-shell:latest` | 终端容器镜像 |
|
||
| `TERMINAL_SANDBOX_NETWORK` | `bridge` | 容器网络模式（`none`/`bridge`/`host` 等） |
|
||
| `TERMINAL_SANDBOX_CPUS` | `0.5` | 上限 CPU |
|
||
| `TERMINAL_SANDBOX_MEMORY` | `1g` | 上限内存 |
|
||
| `TERMINAL_SANDBOX_REQUIRE` | `0` | 若容器启动失败是否降级宿主机模式 |
|
||
| `PROJECT_MAX_STORAGE_MB` | `2048` | 每个工作区的磁盘配额 |
|
||
| `MAX_ACTIVE_USER_CONTAINERS` | `8` | 并发容器数量 |
|
||
|
||
更多配置请查阅 `.env.example`。
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
1. **安全**：新增模块前请优先考虑是否可以在容器中实现，避免回退宿主机；如需联网，务必评估外部依赖。上传检测现阶段默认关闭 ClamAV（`UPLOAD_CLAMAV_ENABLED=0`），以免 1GB+ 的常驻内存占用，必要时可以在环境变量中显式打开。
|
||
2. **日志**：尽量使用 `utils.logger.setup_logger`，便于统一收集。
|
||
3. **测试**：`users/<username>/project/test_scripts/` 提供内存压测脚本，可验证容器限制是否生效；可在 `test/` 下添加更多集成测试。
|
||
4. **文档**：第二阶段总结见 `doc/phases/phase2_summary.md`，安全基线更新见 `doc/security/security_review.md`。
|
||
5. **前端组件化**：`doc/frontend/phase1_setup.md` 与 `doc/frontend/phase2_sidebar.md` 记录了脚手架与侧栏改造，可用以下命令构建体验版 UI；执行 `localStorage.setItem('useNewFrontend','1')` 或设置 `window.__USE_NEW_FRONTEND__ = true` 可加载新入口，移除该键即回退 legacy UI：
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # watch 构建 static/dist
|
||
npm run build # 生产包
|
||
```
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
- [ ] CSRF / 防爆破 / 会话绑定设备指纹
|
||
- [ ] 文件上传内容扫描与白名单策略
|
||
- [ ] 用户/会话数据迁移到数据库并加密备份
|
||
- [ ] 自动化测试与 CI（含容器镜像构建）
|
||
- [ ] Skeleton Web UI（组件化、国际化、Dark Mode）
|
||
|
||
欢迎通过 Issue/PR 贡献。
|