docs: refresh README and guidelines
This commit is contained in:
parent
760fae4920
commit
7f7a7e9f94
10
AGENTS.md
10
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.
|
||||
- Add type hints and concise docstrings that follow the existing bilingual tone.
|
||||
- Use `utils.logger.setup_logger` for diagnostics; reserve `print` for intentional terminal output.
|
||||
- Keep modules focused: add new features in dedicated `modules/` files with descriptive names.
|
||||
- Target Python 3.11+, 4-space indentation, `snake_case` functions, and `PascalCase` classes.
|
||||
- TypeScript 5 / Vue 3 单文件组件，保持 `<script setup lang="ts">` 风格；新增资源放入 `static/src` 对应子目录。
|
||||
- Add type hints和简短双语 docstring；日志统一用 `utils.logger.setup_logger`，仅在需要时使用 `print`。
|
||||
- 模块聚焦：新增能力优先放 `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.
|
||||
|
||||
35
README.md
35
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` 控制。 |
|
||||
| **容器内文件代理** | `modules/container_file_proxy.py` 通过 `docker exec` 调用内置 Python 脚本，对 `create/read/search/write/modify` 等操作进行沙箱化处理，宿主机不再直写用户代码。 |
|
||||
| **实时监控面板** | Web “用量统计”抽屉实时展示 Token 消耗、容器 CPU/内存、网络上下行速率（0.5s 刷新）以及项目存储占用（5s 刷新）。CLI `/status` 命令也会附带容器状态。 |
|
||||
| **管理员监控面板** | 管理员身份可在「个人空间」中打开 `/admin/monitor`，集中查看用户用量、容器状态、项目存储与上传审计，支持一键刷新与自动轮询。 |
|
||||
| **联网能力 + 最小工具集** | 终端镜像改为 `bridge` 网络并预装 `iputils-ping`，方便验证网络连通性；遇到受限环境可以随时在 `.env` 中切换网络模式。 |
|
||||
| **虚拟显示器回放** | `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` 查看全局用量与上传审计。 |
|
||||
| **子代理与多工具链路** | 支持子代理启动/终止，待办、记忆、阅读、终端等工具协同；前端可随时切换聊天/显示器视图。 |
|
||||
|
||||
---
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 监控与调试
|
||||
|
||||
Loading…
Reference in New Issue
Block a user