docs: refresh README and guidelines

AGENTS.md

@@ -7,6 +7,7 @@
 - `utils/` provides API clients, context helpers, and logging; import from here instead of adding globals.
 - `prompts/`, `data/`, and `project/` bundle prompt templates, fixtures, and demos used primarily for reference.
 - `test/` stores integration helpers (`api_interceptor_server.py`, `test_deepseek_output.py`); add new suites alongside them.
+- 前端：`static/src/components/chat/monitor` 是虚拟显示器动画层；涉及新场景请在 `MonitorDirector`/`monitor store` 内对齐数据与动画的状态同步。
 
 ## Build, Test, and Development Commands
 - `pip install -r requirements.txt` installs Python dependencies.
@@ -14,12 +15,13 @@
 - `python web_server.py` serves the web UI at `http://localhost:8091`.
 - `python test/api_interceptor_server.py` starts the mock proxy that logs traffic to `api_logs/`.
 - `python test_deepseek_output.py` exercises streaming tool-calls; populate `config.py` with valid API credentials first.
+- `npm install` then `npm run build` builds the Vue frontend to `static/dist`; `npm run dev` watches; `npm run lint` for TS/Vue linting.
 
 ## Coding Style & Naming Conventions
-- Target Python 3.8+, 4-space indentation, `snake_case` functions, and `PascalCase` classes.
+- Target Python 3.11+, 4-space indentation, `snake_case` functions, and `PascalCase` classes.
-- Add type hints and concise docstrings that follow the existing bilingual tone.
+- TypeScript 5 / Vue 3 单文件组件，保持 `<script setup lang="ts">` 风格；新增资源放入 `static/src` 对应子目录。
-- Use `utils.logger.setup_logger` for diagnostics; reserve `print` for intentional terminal output.
+- Add type hints和简短双语 docstring；日志统一用 `utils.logger.setup_logger`，仅在需要时使用 `print`。
-- Keep modules focused: add new features in dedicated `modules/` files with descriptive names.
+- 模块聚焦：新增能力优先放 `modules/`（或 `static/src/components/chat/monitor` 对应区域）而非入口脚本。
 
 ## Testing Guidelines
 - Prefer `pytest` for automation and name files `test/test_<feature>.py`, reusing assets in `data/` when relevant.

README.md

@@ -1,20 +1,20 @@
-# AI Agent 系统（v2）
+# AI Agent 系统（v5.x）
 
-多用户、多终端的智能开发助手。每位登录用户都会获得一个独立 Docker 容器，所有终端、一次性命令以及文件操作都在容器内完成；宿主机仅提供挂载和备份，配合实时监控界面可以随时观察容器 CPU/内存/网络/磁盘配额的使用情况。
+多用户、多终端的智能开发助手。每位登录用户都会获得一个独立 Docker 容器，所有终端、一次性命令以及文件操作都在容器内完成；宿主机负责挂载与备份。配合 **虚拟显示器** 与资源面板，可实时回放工具动作并观察 CPU / 内存 / 网络 / 磁盘配额。
 
 > ⚠️ **定位**：学习与实验用项目，主要用于探索“智能体 + 真实 Dev Workflow”。代码大量由 AI 生成，尚未达到生产级别，请谨慎部署。
 
 ---
 
-## 近期亮点
+## 近期亮点（v5）
 
 | 能力 | 说明 |
 | --- | --- |
-| **单用户-单容器** | `modules/user_container_manager.py` 会在登录时启动专属容器，并在退出或空闲超时后自动销毁。CLI/Web/Toolbox 复用同一容器，资源配额（默认 0.5 vCPU / 1GB RAM / 2GB 磁盘）由 `.env` 控制。 |
+| **虚拟显示器回放** | `static/src/components/chat/monitor` 提供指针/窗口/右键菜单动画，可回放创建文件、终端执行等工具场景，并展示进度气泡。 |
-| **容器内文件代理** | `modules/container_file_proxy.py` 通过 `docker exec` 调用内置 Python 脚本，对 `create/read/search/write/modify` 等操作进行沙箱化处理，宿主机不再直写用户代码。 |
+| **单用户-单容器** | `modules/user_container_manager.py` 登录即拉起专属容器，退出或空闲自动销毁；CLI/Web/工具共用同一容器，配额在 `.env` 设置。 |
-| **实时监控面板** | Web “用量统计”抽屉实时展示 Token 消耗、容器 CPU/内存、网络上下行速率（0.5s 刷新）以及项目存储占用（5s 刷新）。CLI `/status` 命令也会附带容器状态。 |
+| **容器内文件代理** | `modules/container_file_proxy.py` 通过 `docker exec` 沙箱化 `create/read/search/write/modify`，宿主机不直接写用户代码。 |
-| **管理员监控面板** | 管理员身份可在「个人空间」中打开 `/admin/monitor`，集中查看用户用量、容器状态、项目存储与上传审计，支持一键刷新与自动轮询。 |
+| **实时资源与管理员面板** | 用量抽屉实时展示 Token / CPU / 内存 / 网络 / 存储；管理员可在 `/admin/monitor` 查看全局用量与上传审计。 |
-| **联网能力 + 最小工具集** | 终端镜像改为 `bridge` 网络并预装 `iputils-ping`，方便验证网络连通性；遇到受限环境可以随时在 `.env` 中切换网络模式。 |
+| **子代理与多工具链路** | 支持子代理启动/终止，待办、记忆、阅读、终端等工具协同；前端可随时切换聊天/显示器视图。 |
 
 ---
 
@@ -29,13 +29,14 @@
                       └────────────────┘           ▼
                                                  Container
                                                  ├─ PersistentTerminal / Toolbox
-                                                 └─ Container File Proxy
+                                                 ├─ Container File Proxy
+                                                 └─ Sub Agent / Tool Runtime
 ```
 
 - **core/**：`MainTerminal` / `WebTerminal` 负责命令路由、上下文管理与工具调度。
-- **modules/**：终端管理、FileManager、容器调度、搜索、记忆等独立能力模块。
+- **modules/**：终端管理、文件代理、容器调度、搜索、记忆等独立能力模块。
 - **utils/**：模型 API 客户端、上下文压缩、日志、终端工厂等辅助工具。
-- **static/**：Vue + Socket.IO 单页应用，负责对话流/终端输出/资源监控。
+- **static/**：Vue + Socket.IO 单页应用；`chat/monitor` 为虚拟显示器动画层。
 - **docker/**：终端镜像 Dockerfile 及工具容器依赖清单。
 
 更多目录说明请查阅 `tree -L 2` 或仓库内注释。
@@ -48,12 +49,14 @@
 
 - Python 3.11+
 - Docker 20+（需启用 cgroup v1/v2 任一，默认通过 `bridge` 网络运行容器）
-- Node/Vue 非必需，前端为静态文件
+- Node 18+（仅在需要本地构建/开发前端时）
 
 ### 2. 安装依赖
 
 ```bash
 pip install -r requirements.txt
+# 前端开发/构建时可选
+npm install
 ```
 
 ### 3. 配置
@@ -79,6 +82,14 @@ python web_server.py
 
 首次启动会在 `users/<username>/` 下初始化个人工作区与容器。
 
+### 5. 构建前端（可选）
+
+```bash
+npm run build     # 产物输出到 static/dist
+# 开发监听（仅构建，不启动服务）
+npm run dev
+```
+
 ---
 
 ## 监控与调试