JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: update runtime data paths and project status to 2026-06

Browse Source
This commit is contained in:
JOJO 2026-06-21 22:46:25 +08:00
parent b76708de13
commit b4080f3880
3 changed files with 200 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
AGENTS.md
View File

@ -37,28 +37,28 @@
## 1.5) 运行态数据目录与路径变量（2026-06 更新） ## 1.5) 运行态数据目录与路径变量（2026-06 更新）
> 设计目标：运行态数据（对话、用户工作区、日志等）默认存放在用户主目录的 `~/.agents` 下，对齐 `~/.claude`、`~/.codex` 惯例，**不落在源码树内**。配置实现见 `config/paths.py`。 > 设计目标：运行态数据（对话、用户工作区、日志等）默认存放在用户主目录的 `~/.agents/agents/` 下，对齐 `~/.claude`、`~/.codex` 惯例，**不落在源码树内**。配置实现见 `config/paths.py`。
### 1.5.1 默认位置与模式分流 ### 1.5.1 默认位置与模式分流
运行态根目录按运行模式自动分流（由 `TERMINAL_SANDBOX_MODE` 决定）： 运行态数据根目录（`data_root`）默认为 `~/.agents/agents`，可通过 `AGENTS_DATA_ROOT` 整体搬迁。在该根目录下，按运行模式自动分流（由 `TERMINAL_SANDBOX_MODE` 决定）：
- 宿主机模式（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/host` - 宿主机模式（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/agents/host`
- 其它模式（默认 docker / web）→ `~/.agents/web` - 其它模式（默认 docker / web）→ `~/.agents/agents/web`
每个模式根下包含：`data/`（对话、用户库、记忆、sub_agents.json、sub_agent_tasks 等）、`users/`（web 多用户工作区）、`api/users/`（API 用户工作区）、`logs/`（日志）。 数据根目录下还包含：`settings.json`（唯一配置文件）、`config/`（部署级配置，host/web 共享）。每个模式目录下包含：`data/`（对话、用户库、记忆、sub_agents.json、sub_agent_tasks 等）、`users/`（web 多用户工作区）、`api/users/`（API 用户工作区）、`logs/`（日志）。
### 1.5.2 路径解析优先级（从高到低） ### 1.5.2 路径解析优先级（从高到低）
1. **具体目录环境变量**：`DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某个目录，最高优先级） 1. **具体目录环境变量**：`DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某个目录，最高优先级）
2. **模式根目录环境变量**：`AGENTS_HOST_HOME` 或 `AGENTS_WEB_HOME`（整体搬迁该模式下全部运行态数据） 2. **数据根目录环境变量**：`AGENTS_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.agents/agents`）
3. **兜底默认**：`~/.agents/<mode>` 3. **兜底默认**：`~/.agents/agents/<mode>`
具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 `~`。 具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 `~`。
> 注意：`config/*.json` 分两类： > 注意：`config/*.json` 分两类：
> - **程序能力**（`docker_risk_markers.json`、`skill_hints.json`）：是程序行为的一部分，随版本演进，仍锚定源码树。`prompts/`、`agentskills/` 同理。 > - **程序能力**（`docker_risk_markers.json`、`skill_hints.json`）：是程序行为的一部分，随版本演进，仍锚定源码树。`prompts/`、`agentskills/` 同理。
> - **部署级配置**（`custom_models`、`host_workspaces`、`auto_approval`、`goal_review`、`forbidden_commands`、`host_sandbox_policy`）：因部署/机器而异或含密钥，外置到 `~/.agents/<mode>/config/`（即 `DEPLOY_CONFIG_DIR`，可单独用该环境变量覆盖）。读取走 `config.resolve_deploy_config(name)`，回退链：部署目录 → 源码树 `.json` → 源码树 `.json.example`，因此开发环境不必先跑 setup 也能用源码树种子。含密钥/机器特定的 5 个（除 `forbidden_commands`）不纳入 git，仓库仅留 `.example`。 > - **部署级配置**（`custom_models`、`host_workspaces`、`auto_approval`、`goal_review`、`forbidden_commands`、`host_sandbox_policy`）：因部署/机器而异或含密钥，外置到 `~/.agents/agents/config/`（即 `DEPLOY_CONFIG_DIR`，可单独用该环境变量覆盖，host/web 共享）。读取走 `config.resolve_deploy_config(name)`，回退链：部署目录 → 源码树 `.json` → 源码树 `.json.example`，因此开发环境不必先跑 setup 也能用源码树种子。含密钥/机器特定的 5 个（除 `forbidden_commands`）不纳入 git，仓库仅留 `.example`。
### 1.5.3 Host / Web 双路径机制（2026-06 新增） ### 1.5.3 Host / Web 双路径机制（2026-06 新增）
@ -234,7 +234,7 @@ AI 执行以下流程时，每一步都要向用户说明在做什么：
## 7) 安全与仓库卫生 ## 7) 安全与仓库卫生
- 严禁提交真实密钥（`.env`、token、cookie、用户隐私）。 - 严禁提交真实密钥（`.env`、token、cookie、用户隐私）。
- 运行态数据默认在 `~/.agents/<mode>/`（`data/`、`users/`、`logs/`、`api/`），不在源码树内；详见 §1.5。`.gitignore` 仍忽略源码树内的 `logs/`、`data/`、`users/`、`api/`、`project/` 等，以防通过具体变量指回源码树或历史遗留产生污染。分享前需脱敏。 - 运行态数据默认在 `~/.agents/agents/<mode>/`（`data/`、`users/`、`logs/`、`api/`），不在源码树内；详见 §1.5。`.gitignore` 仍忽略源码树内的 `logs/`、`data/`、`users/`、`api/`、`project/` 等，以防通过具体变量指回源码树或历史遗留产生污染。分享前需脱敏。
- **`_experiments/` 用途**：归档本地实验残留与历史文档（调试记录、旧变更日志、模型测试脚本、翻译资料、旧子智能体文档等）。该目录**不纳入 git**（已在 `.gitignore`）。需要保留但不属于当前主线、又不想直接删的零散文件，统一放这里，不要散落在根目录。 - **`_experiments/` 用途**：归档本地实验残留与历史文档（调试记录、旧变更日志、模型测试脚本、翻译资料、旧子智能体文档等）。该目录**不纳入 git**（已在 `.gitignore`）。需要保留但不属于当前主线、又不想直接删的零散文件，统一放这里，不要散落在根目录。
- 不要把本地构建产物（如 `static/dist/`、`node_modules/`）纳入提交。 - 不要把本地构建产物（如 `static/dist/`、`node_modules/`）纳入提交。

36
CLAUDE.md
View File

@ -137,12 +137,12 @@ npm --prefix cli run build
# 查看容器状态 # 查看容器状态
docker ps -a | grep agent-term docker ps -a | grep agent-term
# 查看调试日志（运行态日志默认在 ~/.agents/<mode>/logs/） # 查看调试日志（运行态日志默认在 ~/.agents/agents/<mode>/logs/）
tail -f ~/.agents/host/logs/debug_stream.log # host 模式 tail -f ~/.agents/agents/host/logs/debug_stream.log # host 模式
tail -f ~/.agents/web/logs/debug_stream.log # web/docker 模式 tail -f ~/.agents/agents/web/logs/debug_stream.log # web/docker 模式
# 查看容器统计 # 查看容器统计
tail -f ~/.agents/web/logs/container_stats.log tail -f ~/.agents/agents/web/logs/container_stats.log
``` ```
## Configuration ## Configuration
@ -168,12 +168,12 @@ tail -f ~/.agents/web/logs/container_stats.log
**数据目录与路径变量** (`config/paths.py`，2026-06 更新): **数据目录与路径变量** (`config/paths.py`，2026-06 更新):
运行态数据默认存放在 `~/.agents/<mode>`（对齐 `~/.claude`、`~/.codex`），**不落在源码树**。模式由 `TERMINAL_SANDBOX_MODE` 决定：`host` → `~/.agents/host`，其它（默认 docker/web）→ `~/.agents/web`。每个模式根下含 `data/`（对话、用户库、记忆、sub_agents.json、sub_agent_tasks）、`users/`、`api/users/`、`logs/`。 运行态数据默认存放在 `~/.agents/agents/<mode>`（对齐 `~/.claude`、`~/.codex`），**不落在源码树**。数据根目录（`data_root`）默认为 `~/.agents/agents`，可通过 `AGENTS_DATA_ROOT` 整体搬迁；模式由 `TERMINAL_SANDBOX_MODE` 决定：`host` → `~/.agents/agents/host`，其它（默认 docker/web）→ `~/.agents/agents/web`。数据根目录下还包含 `settings.json`（唯一配置文件）和 `config/`（部署级配置，host/web 共享）。每个模式目录下含 `data/`（对话、用户库、记忆、sub_agents.json、sub_agent_tasks）、`users/`、`api/users/`、`logs/`。
路径解析优先级（高→低）： 路径解析优先级（高→低）：
1. 具体目录变量 `DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某目录） 1. 具体目录变量 `DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某目录）
2. 模式根变量 `AGENTS_HOST_HOME` / `AGENTS_WEB_HOME`（整体搬迁该模式数据） 2. 数据根目录变量 `AGENTS_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.agents/agents`）
3. 兜底 `~/.agents/<mode>` 3. 兜底 `~/.agents/agents/<mode>`
**Host / Web 双路径机制（2026-06）**: **Host / Web 双路径机制（2026-06）**:
- `paths.py` 新增 `IS_HOST_MODE`、`WEB_DATA_DIR`、`WEB_USER_SPACE_DIR` 三个固定变量 - `paths.py` 新增 `IS_HOST_MODE`、`WEB_DATA_DIR`、`WEB_USER_SPACE_DIR` 三个固定变量
@ -181,14 +181,14 @@ tail -f ~/.agents/web/logs/container_stats.log
- 已有 web 工作区直接复用（保持旧数据可访问），新工作区写入 host/ - 已有 web 工作区直接复用（保持旧数据可访问），新工作区写入 host/
- web 模式：仅读取 web/ 数据，无变化 - web 模式：仅读取 web/ 数据，无变化
> `config/*.json` 分两类：**程序能力**（`docker_risk_markers.json`、`skill_hints.json`）与 `prompts/`、`agentskills/` 一样锚定源码树；**部署级配置**（`custom_models`、`host_workspaces`、`auto_approval`、`goal_review`、`forbidden_commands`、`host_sandbox_policy`）外置到 `~/.agents/<mode>/config/`（`DEPLOY_CONFIG_DIR`），读取走 `config.resolve_deploy_config(name)`，回退链：部署目录 → 源码树 `.json` → 源码树 `.json.example`。含密钥/机器特定的 5 个不进 git，仓库仅留 `.example`。 > `config/*.json` 分两类：**程序能力**（`docker_risk_markers.json`、`skill_hints.json`）与 `prompts/`、`agentskills/` 一样锚定源码树；**部署级配置**（`custom_models`、`host_workspaces`、`auto_approval`、`goal_review`、`forbidden_commands`、`host_sandbox_policy`）外置到 `~/.agents/agents/config/`（`DEPLOY_CONFIG_DIR`，host/web 共享），读取走 `config.resolve_deploy_config(name)`，回退链：部署目录 → 源码树 `.json` → 源码树 `.json.example`。含密钥/机器特定的 5 个不进 git，仓库仅留 `.example`。
**日志策略**: **日志策略**:
- API 请求体 dump 默认**关闭**，`AGENT_API_DUMP_ENABLED=1` 开启。 - API 请求体 dump 默认**关闭**，`AGENT_API_DUMP_ENABLED=1` 开启。
- 混合轮转（`utils/log_rotation.py`）：追加型单文件按大小轮转（默认 20MB×3 份），dump 目录按份保留（默认 30 个）。阈值变量：`AGENT_LOG_ROTATE_MAX_BYTES` / `AGENT_LOG_ROTATE_BACKUPS` / `AGENT_DUMP_KEEP`。 - 混合轮转（`utils/log_rotation.py`）：追加型单文件按大小轮转（默认 20MB×3 份），dump 目录按份保留（默认 30 个）。阈值变量：`AGENT_LOG_ROTATE_MAX_BYTES` / `AGENT_LOG_ROTATE_BACKUPS` / `AGENT_DUMP_KEEP`。
**数据迁移**: **数据迁移**:
- `scripts/migrate_runtime_data.py`：源码树 → `~/.agents/<mode>`，复制+备份+可回滚+幂等，`logs/` 丢弃不迁。脚本复用 config 路径解析（模式由 `.env` 决定），执行前先 `--dry-run` 确认目标。 - `scripts/migrate_runtime_data.py`：源码树 → `~/.agents/agents/<mode>`，复制+备份+可回滚+幂等，`logs/` 丢弃不迁。脚本复用 config 路径解析（模式由 `.env` 决定），执行前先 `--dry-run` 确认目标。
## Important Implementation Details ## Important Implementation Details
@ -346,14 +346,20 @@ agents/
└── _experiments/ # 本地实验残留与历史文档归档（gitignored，不进仓库） └── _experiments/ # 本地实验残留与历史文档归档（gitignored，不进仓库）
运行态数据（不在源码树）： 运行态数据（不在源码树）：
~/.agents/<mode>/ # mode = host 或 web，由 TERMINAL_SANDBOX_MODE 决定 ~/.agents/agents/ # 数据根目录（可通过 AGENTS_DATA_ROOT 覆盖）
├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态） ├── settings.json # 唯一配置文件
├── users/ # web 多用户工作区 ├── config/ # 部署级配置（host/web 共享）
├── api/users/ # API 用户工作区 ├── host/ # mode = host，由 TERMINAL_SANDBOX_MODE 决定
└── logs/ # 日志文件 │ ├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态）
│ └── logs/ # 日志文件
└── web/ # mode = web/docker
├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态）
├── users/ # web 多用户工作区
├── api/users/ # API 用户工作区
└── logs/ # 日志文件
``` ```
> 历史说明：`data/`、`users/`、`logs/`、`project/` 等过去曾在源码树内，现已默认迁至 `~/.agents/<mode>/`。详见 Configuration 节「数据目录与路径变量」。 > 历史说明：`data/`、`users/`、`logs/`、`project/` 等过去曾在源码树内，现已默认迁至 `~/.agents/agents/<mode>/`。详见 Configuration 节「数据目录与路径变量」。
## Development Tips ## Development Tips

237
README.md
View File

@ -2,12 +2,13 @@
一个功能完整的 AI 智能体系统，支持多模态交互、子智能体协作、实时终端操作和丰富的工具集成。 一个功能完整的 AI 智能体系统，支持多模态交互、子智能体协作、实时终端操作和丰富的工具集成。
## 当前状态（2026-05） ## 当前状态（2026-06）
- Web 端仍然是主线入口，基于 Flask + Vue 3。 - Web 端仍然是主线入口，基于 Flask + Vue 3；聊天/状态/任务接口已拆分为 `server/chat/`、`server/status/`、`server/tasks/` 子包。
- 新 CLI 端已开始重写，位于 `cli/`，技术栈为 React 19 + Ink 6 + TypeScript。 - 新 CLI 端已开始重写，位于 `cli/`，技术栈为 React 19 + Ink 6 + TypeScript。
- 当前 CLI 不是独立后端；它会直接连接本地 `8091` Web API，并复用现有会话、任务、权限、工作区等接口。 - 当前 CLI 不是独立后端；它会直接连接本地 `8091` Web API，并复用现有会话、任务、权限、工作区等接口。
- CLI 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。 - CLI 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。
- 运行态数据（对话、用户库、日志等）默认存放在用户主目录的 `~/.agents/agents/<mode>/` 下，不再落在源码树内；源码树内的 `data/`、`logs/`、`users/` 等仅作为 `.gitignore` 防污染保留。
## CLI 快速开始 ## CLI 快速开始
@ -31,6 +32,12 @@ npm run cli
npm --prefix cli run dev npm --prefix cli run dev
``` ```
### 类型检查
```bash
npm --prefix cli run typecheck
```
### 在目标目录启动 CLI ### 在目标目录启动 CLI
```bash ```bash
@ -85,17 +92,18 @@ python3 -m server.app --path <当前目录> --port 8091 --thinking-mode
### 🤖 子智能体系统 ### 🤖 子智能体系统
支持创建独立的子智能体处理复杂任务： 支持创建子智能体处理复杂任务：
- **并行执行**: 最多同时运行多个子智能体 - **并行执行**: 最多同时运行多个子智能体
- **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史 - **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史
- **任务隔离**: 子智能体在独立进程中运行，互不干扰
- **状态追踪**: 实时监控子智能体的执行状态和进度 - **状态追踪**: 实时监控子智能体的执行状态和进度
- **后台运行**: 支持后台模式，主智能体可继续处理其他任务 - **后台运行**: 支持后台模式，主智能体可继续处理其他任务
- **实现方式**: 当前子智能体在主进程内以 `asyncio.Task` 运行，工具调用复用主进程链路；旧版 Node.js 子进程实现保留在 `easyagent/` 但已不再使用
工具接口： 工具接口：
- `create_sub_agent`: 创建并启动子智能体 - `create_sub_agent`: 创建并启动子智能体
- `close_sub_agent`: 终止运行中的子智能体 - `close_sub_agent`: 终止运行中的子智能体
- `terminate_sub_agent`: 强制终止运行中的子智能体
### 🛠️ 丰富的工具集 ### 🛠️ 丰富的工具集
@ -305,35 +313,45 @@ TERMINAL_SANDBOX_MOUNT_PATH=/workspace
``` ```
agents/ agents/
├── main.py # 程序入口 ├── main.py # 统一启动入口（当前默认走 Web 模式 + thinking_mode=True）
├── core/ # 核心模块 ├── server/ # Flask 业务主线
│ ├── main_terminal.py # 主终端（CLI模式） │ ├── app.py # 推荐的 Web 服务入口（封装并转发到 app_legacy.py）
│ ├── web_terminal.py # Web终端 │ ├── app_legacy.py # 原有 Flask 应用主体
│ ├── tool_config.py # 工具配置 │ ├── chat/ # 聊天相关接口子包（approval/files/misc/permission/settings/terminal）
│ └── ... │ ├── status/ # 状态相关接口子包（app/base/docker/file_open/git/host_workspace）
├── server/ # Web服务器 │ ├── tasks/ # 任务相关接口子包（api/helpers/media/models/skills）
│ ├── app.py # Flask应用
│ ├── chat_flow_*.py # 对话流程处理
│ ├── conversation.py # 对话管理 │ ├── conversation.py # 对话管理
│ ├── socket_handlers.py # Socket.IO 连接与兼容事件处理（聊天主链路已迁移到 REST 任务轮询） │ └── socket_handlers.py # Socket.IO 兼容通道（聊天主链路已迁移到 REST 任务轮询）
│ └── ... ├── core/ # 终端与工具编排
├── modules/ # 功能模块 │ ├── main_terminal.py # 主终端（CLI模式）
│ ├── file_manager.py # 文件管理 │ ├── web_terminal.py # Web 终端
│ ├── terminal_manager.py # 终端管理 │ ├── main_terminal_parts/# 终端功能拆分（context/、tools_definition/ 等）
│ ├── sub_agent_manager.py# 子智能体管理 │ └── tool_config.py # 工具配置
├── modules/ # 可复用能力模块
│ ├── file_manager/ # 文件管理（已拆分为子包）
│ ├── persistent_terminal/# 持久化终端（已拆分为子包）
│ ├── terminal_ops/ # 终端操作（已拆分为子包）
│ ├── sub_agent/ # 子智能体执行逻辑（creation/manager/prompts/state/stats/task/toolkit/tools）
│ ├── mcp_client_manager/ # MCP 客户端管理（已拆分为子包）
│ ├── memory_manager.py # 记忆管理 │ ├── memory_manager.py # 记忆管理
│ ├── search_engine.py # 搜索引擎 │ ├── search_engine.py # 搜索引擎
│ └── ... │ └── ...
├── utils/ # 工具函数 ├── utils/ # 工具函数
│ ├── api_client.py # API客户端 │ ├── api_client/ # API 客户端（已拆分为子包）
│ ├── context_manager.py # 上下文管理 │ ├── tool_result_formatter/# 工具结果格式化（已拆分为子包）
│ ├── conversation_manager.py # 对话持久化 │ ├── context_manager/ # 上下文管理（已拆分为子包）
│ ├── conversation_manager/# 对话持久化（已拆分为子包）
│ ├── log_rotation.py # 日志轮转
│ └── ... │ └── ...
└── config/ # 配置文件 ├── config/ # 配置拆分
├── __init__.py # 主配置 │ ├── __init__.py # 主配置（聚合并加载 .env）
├── model_profiles.py # 模型配置 │ ├── paths.py # 路径解析与运行态目录
├── limits.py # 限制配置 │ ├── api.py # API 配置
└── ... │ ├── limits.py # 限制配置
│ ├── terminal.py # 终端配置
│ └── ...
├── easyagent/ # 旧版 Node.js 子智能体实现，暂时保留但已不再使用
└── _experiments/ # 本地实验残留与历史文档归档（不纳入 git）
``` ```
### 前端架构 ### 前端架构
@ -377,7 +395,25 @@ static/src/
### Web 界面 ### Web 界面
启动后访问 `http://localhost:8091`（默认端口） 安装后端依赖：
```bash
pip install -r requirements.txt
```
启动 Web 服务：
```bash
python -m server.app
```
或带参数启动：
```bash
python -m server.app --path ./project --port 8091 --debug --thinking-mode
```
启动后访问 `http://localhost:8091`（默认端口 8091）
#### 基本操作 #### 基本操作
@ -452,7 +488,7 @@ static/src/
主要配置项（通过环境变量或 `.env` 文件）： 主要配置项（通过环境变量或 `.env` 文件）：
### API 配置 ### API 配置
- `config/custom_models.json`: 动态模型注册文件 - `config/custom_models.json`: 动态模型注册文件（生产环境建议放到 `~/.agents/agents/config/custom_models.json`，host/web 共享）
- `AGENT_DEFAULT_MODEL`: 可选，指定默认模型 key；未设置时使用第一个可见动态模型 - `AGENT_DEFAULT_MODEL`: 可选，指定默认模型 key；未设置时使用第一个可见动态模型
- 模型配置中的 `url` / `apikey` 支持 `${ENV_NAME}`、`env:ENV_NAME`、`$ENV_NAME` 等环境变量引用 - 模型配置中的 `url` / `apikey` 支持 `${ENV_NAME}`、`env:ENV_NAME`、`$ENV_NAME` 等环境变量引用
@ -460,12 +496,26 @@ static/src/
- `WEB_SERVER_PORT`: Web 服务器端口（默认 8091） - `WEB_SERVER_PORT`: Web 服务器端口（默认 8091）
- `DEFAULT_PROJECT_PATH`: 默认项目路径 - `DEFAULT_PROJECT_PATH`: 默认项目路径
### 运行态路径配置
- `DATA_DIR`: 数据目录（对话、记忆、子智能体等）
- `LOGS_DIR`: 日志目录
- `USER_SPACE_DIR`: Web 用户工作区目录
- `API_USER_SPACE_DIR`: API 用户工作区目录
- `AGENTS_DATA_ROOT`: 运行态数据根目录（默认 `~/.agents/agents`，host/web 两个模式共享该根）
- `DEPLOY_CONFIG_DIR`: 部署级配置目录（默认 `<AGENTS_DATA_ROOT>/config/`，host/web 共享）
### 限制配置 ### 限制配置
- `MAX_ITERATIONS_PER_TASK`: 单任务最大迭代次数 - `MAX_ITERATIONS_PER_TASK`: 单任务最大迭代次数
- `MAX_TOTAL_TOOL_CALLS`: 总工具调用次数限制 - `MAX_TOTAL_TOOL_CALLS`: 总工具调用次数限制
- `MAX_UPLOAD_SIZE`: 最大上传文件大小 - `MAX_UPLOAD_SIZE`: 最大上传文件大小
- `PROJECT_MAX_STORAGE_MB`: 项目存储限制 - `PROJECT_MAX_STORAGE_MB`: 项目存储限制
### 日志策略
- `AGENT_API_DUMP_ENABLED`: API 请求体落盘开关（`1/true/yes/on` 开启）
- `AGENT_LOG_ROTATE_MAX_BYTES`: 单日志文件大小阈值（默认 20MB）
- `AGENT_LOG_ROTATE_BACKUPS`: 日志轮转保留份数（默认 3）
- `AGENT_DUMP_KEEP`: 按请求落盘的 dump 文件保留数量（默认 30）
### 运行环境配置 ### 运行环境配置
**宿主机模式**: **宿主机模式**:
@ -484,34 +534,84 @@ static/src/
## 数据存储 ## 数据存储
运行态数据默认存放在用户主目录的 `~/.agents/agents/<mode>/` 下（按 `TERMINAL_SANDBOX_MODE` 自动分流）：
- **宿主机模式**（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/agents/host`
- **其它模式**（默认 docker / web）→ `~/.agents/agents/web`
### 目录结构 ### 目录结构
``` ```
data/ # 数据目录 ~/.agents/agents/ # 数据根目录（可通过 AGENTS_DATA_ROOT 覆盖）
├── conversations/ # 对话历史 ├── settings.json # 唯一配置文件
│ └── <conversation_id>.json ├── config/ # 部署级配置（custom_models/host_workspaces/auto_approval 等，host/web 共享）
├── memory/ # 记忆文件 ├── host/ # 宿主机模式运行态
│ ├── main_memory.md │ ├── data/ # 数据目录
│ └── task_memory.md │ │ ├── conversations/ # 对话历史
└── personalization.json # 个性化配置 │ │ │ └── <conversation_id>.json
│ │ ├── memory/ # 记忆文件
logs/ # 日志目录 │ │ │ ├── main_memory.md
├── tasks/ # 任务日志 │ │ │ └── task_memory.md
├── errors/ # 错误日志 │ │ ├── personalization.json
└── *.log │ │ ├── sub_agents.json # 子智能体注册表
│ │ └── sub_agent_tasks/ # 子智能体任务数据
sub_agent/ # 子智能体数据 │ │ └── <task_id>/
└── tasks/ # 任务目录 │ │ ├── task.txt
└── <task_id>/ │ │ ├── output.json
├── task.txt │ │ └── progress.jsonl
├── output.json │ └── logs/ # 日志目录
└── progress.jsonl │ ├── tasks/
│ ├── errors/
users/ # 用户数据 │ ├── approval_agent/
└── <username>/ │ └── *.log
└── web/ # web/docker 模式运行态
├── data/ ├── data/
├── project/ ├── users/ # Web 多用户工作区
└── ... │ └── <username>/
│ ├── data/
│ ├── project/
│ └── ...
├── api/users/ # API 用户工作区
└── logs/
```
### 路径解析优先级（从高到低）
1. **具体目录环境变量**：`DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某个目录）
2. **数据根目录环境变量**：`AGENTS_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.agents/agents`）
3. **兜底默认**：`~/.agents/agents/<mode>`
### Host / Web 双路径机制
在宿主机模式下，系统同时可读 web 模式数据：
- `WEB_DATA_DIR` 固定指向 `<data_root>/web/data`
- `WEB_USER_SPACE_DIR` 固定指向 `<data_root>/web/users`
- 用户列表合并 `host/data/users.json` + `web/data/users.json`
- 写操作（创建/删除/重命名）始终走 host 路径
> 源码树内的 `data/`、`logs/`、`users/`、`api/`、`project/` 等目录已被 `.gitignore` 忽略，仅在通过环境变量显式指回源码树或历史遗留时才会出现，不参与默认数据存放。
## 测试现状
当前仓库内可见的自动化冒烟测试：
- `test/test_server_refactor_smoke.py`（基于 `unittest`）
- 运行方式：`python -m unittest test.test_server_refactor_smoke`
- `test/test_system_message.py` 依赖外部 `MOONSHOT_API_KEY` 与网络，不属于离线稳定 CI 用例。
CLI 最小可复现验证：
```bash
npm --prefix cli run typecheck
npm --prefix cli run build
```
若改动 `server/chat/`、`server/status/`、`server/tasks/` 等后端接口适配，建议补充：
```bash
python3 -m py_compile server/chat/*.py server/status/*.py server/tasks/*.py
python -m unittest test.test_server_refactor_smoke
``` ```
## 扩展开发 ## 扩展开发
@ -525,9 +625,9 @@ users/ # 用户数据
### 添加新模型 ### 添加新模型
1. 在 `config/model_profiles.py` 添加模型配置 1. 在 `config/custom_models.json`（生产环境建议放到 `~/.agents/agents/config/custom_models.json`）注册模型配置
2. 在 `utils/api_client.py` 实现 API 调用 2. 在 `utils/api_client/` 中实现或复用 API 调用逻辑
3. 配置环境变量 3. 通过环境变量或 `.env` 注入密钥等敏感信息
### 创建技能包 ### 创建技能包
@ -556,22 +656,25 @@ users/ # 用户数据
### 日志位置 ### 日志位置
- 主日志: `logs/main.log` 运行态日志默认位于 `~/.agents/agents/<mode>/logs/`：
- 错误日志: `logs/errors/`
- 任务日志: `logs/tasks/` - 主日志: `~/.agents/agents/<mode>/logs/main.log`
- Web 服务器: `web_server.log` - 错误日志: `~/.agents/agents/<mode>/logs/errors/`
- 任务日志: `~/.agents/agents/<mode>/logs/tasks/`
- Web 服务器: `~/.agents/agents/<mode>/logs/web_server.log`
- 自动审批智能体调试记录: `~/.agents/agents/<mode>/logs/approval_agent/`
## 版本信息 ## 版本信息
当前版本: 4.1.0 当前版本: 4.1.0
主要更新： 主要更新（2026-06）：
- 完整的对话持久化系统 - 后端接口拆分为 `server/chat/`、`server/status/`、`server/tasks/` 子包
- 子智能体并行执行 - 运行态数据默认迁移到 `~/.agents/agents/<mode>/`，支持 host/web 双路径读取
- 多模型支持 - 子智能体改为主进程内 `asyncio.Task` 实现，工具调用复用主进程链路
- 容器沙箱隔离 - 新增宿主机权限模式（readonly/approval/auto_approval/unrestricted）与执行环境（sandbox/direct）双层控制
- 个性化配置 - 新增日志轮转、API dump 可控、部署级配置外置等运维能力
- 监控仪表板 - 完整的对话持久化系统、多模型支持、容器沙箱隔离、个性化配置、监控仪表板
--- ---