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. 安装依赖

pip install -r requirements.txt
# 前端开发/构建时可选
npm install

3. 配置

复制 .env.example → .env，填入以下关键变量：
- AGENT_API_*：兼容 OpenAI API 的模型服务
- WEB_SECRET_KEY：Flask session 密钥
- TERMINAL_SANDBOX_*：容器镜像/资源/网络（默认 my-agent-shell:latest + bridge）

若需定制终端镜像：

docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .

4. 运行

# CLI 模式
python main.py

# Web 模式（默认 8091）
python web_server.py

首次启动会在 users/<username>/ 下初始化个人工作区与容器。

5. 构建前端（可选）

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。

开发建议

安全：新增模块前请优先考虑是否可以在容器中实现，避免回退宿主机；如需联网，务必评估外部依赖。上传检测现阶段默认关闭 ClamAV（UPLOAD_CLAMAV_ENABLED=0），以免 1GB+ 的常驻内存占用，必要时可以在环境变量中显式打开。
日志：尽量使用 utils.logger.setup_logger，便于统一收集。
测试：users/<username>/project/test_scripts/ 提供内存压测脚本，可验证容器限制是否生效；可在 test/ 下添加更多集成测试。
文档：第二阶段总结见 doc/phases/phase2_summary.md，安全基线更新见 doc/security/security_review.md。
前端组件化：doc/frontend/phase1_setup.md 与 doc/frontend/phase2_sidebar.md 记录了脚手架与侧栏改造，可用以下命令构建体验版 UI；执行 localStorage.setItem('useNewFrontend','1') 或设置 window.__USE_NEW_FRONTEND__ = true 可加载新入口，移除该键即回退 legacy UI：
```
npm install
npm run dev   # watch 构建 static/dist
npm run build # 生产包
```

Roadmap

CSRF / 防爆破 / 会话绑定设备指纹
文件上传内容扫描与白名单策略
用户/会话数据迁移到数据库并加密备份
自动化测试与 CI（含容器镜像构建）
Skeleton Web UI（组件化、国际化、Dark Mode）

欢迎通过 Issue/PR 贡献。

6.9 KiB Raw Blame History Unescape Escape