From b4080f38800a04ab78e271a938021004e2208f3b Mon Sep 17 00:00:00 2001 From: JOJO <1498581755@qq.com> Date: Sun, 21 Jun 2026 22:46:25 +0800 Subject: [PATCH] docs: update runtime data paths and project status to 2026-06 --- AGENTS.md | 18 ++--- CLAUDE.md | 36 +++++---- README.md | 237 +++++++++++++++++++++++++++++++++++++++--------------- 3 files changed, 200 insertions(+), 91 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ca58307..5ec1ef0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,28 +37,28 @@ ## 1.5) 运行态数据目录与路径变量（2026-06 更新） -> 设计目标：运行态数据（对话、用户工作区、日志等）默认存放在用户主目录的 `~/.agents` 下，对齐 `~/.claude`、`~/.codex` 惯例，**不落在源码树内**。配置实现见 `config/paths.py`。 +> 设计目标：运行态数据（对话、用户工作区、日志等）默认存放在用户主目录的 `~/.agents/agents/` 下，对齐 `~/.claude`、`~/.codex` 惯例，**不落在源码树内**。配置实现见 `config/paths.py`。 ### 1.5.1 默认位置与模式分流 -运行态根目录按运行模式自动分流（由 `TERMINAL_SANDBOX_MODE` 决定）： +运行态数据根目录（`data_root`）默认为 `~/.agents/agents`，可通过 `AGENTS_DATA_ROOT` 整体搬迁。在该根目录下，按运行模式自动分流（由 `TERMINAL_SANDBOX_MODE` 决定）： -- 宿主机模式（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/host` -- 其它模式（默认 docker / web）→ `~/.agents/web` +- 宿主机模式（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/agents/host` +- 其它模式（默认 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. **具体目录环境变量**：`DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某个目录，最高优先级） -2. **模式根目录环境变量**：`AGENTS_HOST_HOME` 或 `AGENTS_WEB_HOME`（整体搬迁该模式下全部运行态数据） -3. **兜底默认**：`~/.agents/` +2. **数据根目录环境变量**：`AGENTS_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.agents/agents`） +3. **兜底默认**：`~/.agents/agents/` 具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 `~`。 > 注意：`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//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 新增） @@ -234,7 +234,7 @@ AI 执行以下流程时，每一步都要向用户说明在做什么： ## 7) 安全与仓库卫生 - 严禁提交真实密钥（`.env`、token、cookie、用户隐私）。 -- 运行态数据默认在 `~/.agents//`（`data/`、`users/`、`logs/`、`api/`），不在源码树内；详见 §1.5。`.gitignore` 仍忽略源码树内的 `logs/`、`data/`、`users/`、`api/`、`project/` 等，以防通过具体变量指回源码树或历史遗留产生污染。分享前需脱敏。 +- 运行态数据默认在 `~/.agents/agents//`（`data/`、`users/`、`logs/`、`api/`），不在源码树内；详见 §1.5。`.gitignore` 仍忽略源码树内的 `logs/`、`data/`、`users/`、`api/`、`project/` 等，以防通过具体变量指回源码树或历史遗留产生污染。分享前需脱敏。 - **`_experiments/` 用途**：归档本地实验残留与历史文档（调试记录、旧变更日志、模型测试脚本、翻译资料、旧子智能体文档等）。该目录**不纳入 git**（已在 `.gitignore`）。需要保留但不属于当前主线、又不想直接删的零散文件，统一放这里，不要散落在根目录。 - 不要把本地构建产物（如 `static/dist/`、`node_modules/`）纳入提交。 diff --git a/CLAUDE.md b/CLAUDE.md index d62f588..eecd6f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -137,12 +137,12 @@ npm --prefix cli run build # 查看容器状态 docker ps -a | grep agent-term -# 查看调试日志（运行态日志默认在 ~/.agents//logs/） -tail -f ~/.agents/host/logs/debug_stream.log # host 模式 -tail -f ~/.agents/web/logs/debug_stream.log # web/docker 模式 +# 查看调试日志（运行态日志默认在 ~/.agents/agents//logs/） +tail -f ~/.agents/agents/host/logs/debug_stream.log # host 模式 +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 @@ -168,12 +168,12 @@ tail -f ~/.agents/web/logs/container_stats.log **数据目录与路径变量** (`config/paths.py`，2026-06 更新): -运行态数据默认存放在 `~/.agents/`（对齐 `~/.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/`（对齐 `~/.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`（单独覆盖某目录） -2. 模式根变量 `AGENTS_HOST_HOME` / `AGENTS_WEB_HOME`（整体搬迁该模式数据） -3. 兜底 `~/.agents/` +2. 数据根目录变量 `AGENTS_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.agents/agents`） +3. 兜底 `~/.agents/agents/` **Host / Web 双路径机制（2026-06）**: - `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 模式：仅读取 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//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` 开启。 - 混合轮转（`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/`，复制+备份+可回滚+幂等，`logs/` 丢弃不迁。脚本复用 config 路径解析（模式由 `.env` 决定），执行前先 `--dry-run` 确认目标。 +- `scripts/migrate_runtime_data.py`：源码树 → `~/.agents/agents/`，复制+备份+可回滚+幂等，`logs/` 丢弃不迁。脚本复用 config 路径解析（模式由 `.env` 决定），执行前先 `--dry-run` 确认目标。 ## Important Implementation Details @@ -346,14 +346,20 @@ agents/ └── _experiments/ # 本地实验残留与历史文档归档（gitignored，不进仓库） 运行态数据（不在源码树）： -~/.agents// # mode = host 或 web，由 TERMINAL_SANDBOX_MODE 决定 -├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态） -├── users/ # web 多用户工作区 -├── api/users/ # API 用户工作区 -└── logs/ # 日志文件 +~/.agents/agents/ # 数据根目录（可通过 AGENTS_DATA_ROOT 覆盖） +├── settings.json # 唯一配置文件 +├── config/ # 部署级配置（host/web 共享） +├── host/ # mode = host，由 TERMINAL_SANDBOX_MODE 决定 +│ ├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态） +│ └── logs/ # 日志文件 +└── web/ # mode = web/docker + ├── data/ # 对话、用户库、记忆、sub_agent_tasks（运行态） + ├── users/ # web 多用户工作区 + ├── api/users/ # API 用户工作区 + └── logs/ # 日志文件 ``` -> 历史说明：`data/`、`users/`、`logs/`、`project/` 等过去曾在源码树内，现已默认迁至 `~/.agents//`。详见 Configuration 节「数据目录与路径变量」。 +> 历史说明：`data/`、`users/`、`logs/`、`project/` 等过去曾在源码树内，现已默认迁至 `~/.agents/agents//`。详见 Configuration 节「数据目录与路径变量」。 ## Development Tips diff --git a/README.md b/README.md index 7d7bb6a..48e450a 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,13 @@ 一个功能完整的 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 不是独立后端；它会直接连接本地 `8091` Web API，并复用现有会话、任务、权限、工作区等接口。 - CLI 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。 +- 运行态数据（对话、用户库、日志等）默认存放在用户主目录的 `~/.agents/agents//` 下，不再落在源码树内；源码树内的 `data/`、`logs/`、`users/` 等仅作为 `.gitignore` 防污染保留。 ## CLI 快速开始 @@ -31,6 +32,12 @@ npm run cli npm --prefix cli run dev ``` +### 类型检查 + +```bash +npm --prefix cli run typecheck +``` + ### 在目标目录启动 CLI ```bash @@ -85,17 +92,18 @@ python3 -m server.app --path <当前目录> --port 8091 --thinking-mode ### 🤖 子智能体系统 -支持创建独立的子智能体处理复杂任务： +支持创建子智能体处理复杂任务： - **并行执行**: 最多同时运行多个子智能体 - **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史 -- **任务隔离**: 子智能体在独立进程中运行，互不干扰 - **状态追踪**: 实时监控子智能体的执行状态和进度 - **后台运行**: 支持后台模式，主智能体可继续处理其他任务 +- **实现方式**: 当前子智能体在主进程内以 `asyncio.Task` 运行，工具调用复用主进程链路；旧版 Node.js 子进程实现保留在 `easyagent/` 但已不再使用 工具接口： - `create_sub_agent`: 创建并启动子智能体 - `close_sub_agent`: 终止运行中的子智能体 +- `terminate_sub_agent`: 强制终止运行中的子智能体 ### 🛠️ 丰富的工具集 @@ -305,35 +313,45 @@ TERMINAL_SANDBOX_MOUNT_PATH=/workspace ``` agents/ -├── main.py # 程序入口 -├── core/ # 核心模块 -│ ├── main_terminal.py # 主终端（CLI模式） -│ ├── web_terminal.py # Web终端 -│ ├── tool_config.py # 工具配置 -│ └── ... -├── server/ # Web服务器 -│ ├── app.py # Flask应用 -│ ├── chat_flow_*.py # 对话流程处理 +├── main.py # 统一启动入口（当前默认走 Web 模式 + thinking_mode=True） +├── server/ # Flask 业务主线 +│ ├── app.py # 推荐的 Web 服务入口（封装并转发到 app_legacy.py） +│ ├── app_legacy.py # 原有 Flask 应用主体 +│ ├── chat/ # 聊天相关接口子包（approval/files/misc/permission/settings/terminal） +│ ├── status/ # 状态相关接口子包（app/base/docker/file_open/git/host_workspace） +│ ├── tasks/ # 任务相关接口子包（api/helpers/media/models/skills） │ ├── conversation.py # 对话管理 -│ ├── socket_handlers.py # Socket.IO 连接与兼容事件处理（聊天主链路已迁移到 REST 任务轮询） -│ └── ... -├── modules/ # 功能模块 -│ ├── file_manager.py # 文件管理 -│ ├── terminal_manager.py # 终端管理 -│ ├── sub_agent_manager.py# 子智能体管理 +│ └── socket_handlers.py # Socket.IO 兼容通道（聊天主链路已迁移到 REST 任务轮询） +├── core/ # 终端与工具编排 +│ ├── main_terminal.py # 主终端（CLI模式） +│ ├── web_terminal.py # Web 终端 +│ ├── main_terminal_parts/# 终端功能拆分（context/、tools_definition/ 等） +│ └── 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 # 记忆管理 │ ├── search_engine.py # 搜索引擎 │ └── ... ├── utils/ # 工具函数 -│ ├── api_client.py # API客户端 -│ ├── context_manager.py # 上下文管理 -│ ├── conversation_manager.py # 对话持久化 +│ ├── api_client/ # API 客户端（已拆分为子包） +│ ├── tool_result_formatter/# 工具结果格式化（已拆分为子包） +│ ├── context_manager/ # 上下文管理（已拆分为子包） +│ ├── conversation_manager/# 对话持久化（已拆分为子包） +│ ├── log_rotation.py # 日志轮转 │ └── ... -└── config/ # 配置文件 - ├── __init__.py # 主配置 - ├── model_profiles.py # 模型配置 - ├── limits.py # 限制配置 - └── ... +├── config/ # 配置拆分 +│ ├── __init__.py # 主配置（聚合并加载 .env） +│ ├── paths.py # 路径解析与运行态目录 +│ ├── api.py # API 配置 +│ ├── limits.py # 限制配置 +│ ├── terminal.py # 终端配置 +│ └── ... +├── easyagent/ # 旧版 Node.js 子智能体实现，暂时保留但已不再使用 +└── _experiments/ # 本地实验残留与历史文档归档（不纳入 git） ``` ### 前端架构 @@ -377,7 +395,25 @@ static/src/ ### 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` 文件）： ### API 配置 -- `config/custom_models.json`: 动态模型注册文件 +- `config/custom_models.json`: 动态模型注册文件（生产环境建议放到 `~/.agents/agents/config/custom_models.json`，host/web 共享） - `AGENT_DEFAULT_MODEL`: 可选，指定默认模型 key；未设置时使用第一个可见动态模型 - 模型配置中的 `url` / `apikey` 支持 `${ENV_NAME}`、`env:ENV_NAME`、`$ENV_NAME` 等环境变量引用 @@ -460,12 +496,26 @@ static/src/ - `WEB_SERVER_PORT`: Web 服务器端口（默认 8091） - `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`: 部署级配置目录（默认 `/config/`，host/web 共享） + ### 限制配置 - `MAX_ITERATIONS_PER_TASK`: 单任务最大迭代次数 - `MAX_TOTAL_TOOL_CALLS`: 总工具调用次数限制 - `MAX_UPLOAD_SIZE`: 最大上传文件大小 - `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//` 下（按 `TERMINAL_SANDBOX_MODE` 自动分流）： + +- **宿主机模式**（`TERMINAL_SANDBOX_MODE=host`）→ `~/.agents/agents/host` +- **其它模式**（默认 docker / web）→ `~/.agents/agents/web` + ### 目录结构 ``` -data/ # 数据目录 -├── conversations/ # 对话历史 -│ └── .json -├── memory/ # 记忆文件 -│ ├── main_memory.md -│ └── task_memory.md -└── personalization.json # 个性化配置 - -logs/ # 日志目录 -├── tasks/ # 任务日志 -├── errors/ # 错误日志 -└── *.log - -sub_agent/ # 子智能体数据 -└── tasks/ # 任务目录 - └── / - ├── task.txt - ├── output.json - └── progress.jsonl - -users/ # 用户数据 -└── / +~/.agents/agents/ # 数据根目录（可通过 AGENTS_DATA_ROOT 覆盖） +├── settings.json # 唯一配置文件 +├── config/ # 部署级配置（custom_models/host_workspaces/auto_approval 等，host/web 共享） +├── host/ # 宿主机模式运行态 +│ ├── data/ # 数据目录 +│ │ ├── conversations/ # 对话历史 +│ │ │ └── .json +│ │ ├── memory/ # 记忆文件 +│ │ │ ├── main_memory.md +│ │ │ └── task_memory.md +│ │ ├── personalization.json +│ │ ├── sub_agents.json # 子智能体注册表 +│ │ └── sub_agent_tasks/ # 子智能体任务数据 +│ │ └── / +│ │ ├── task.txt +│ │ ├── output.json +│ │ └── progress.jsonl +│ └── logs/ # 日志目录 +│ ├── tasks/ +│ ├── errors/ +│ ├── approval_agent/ +│ └── *.log +└── web/ # web/docker 模式运行态 ├── data/ - ├── project/ - └── ... + ├── users/ # Web 多用户工作区 + │ └── / + │ ├── 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/` + +### Host / Web 双路径机制 + +在宿主机模式下，系统同时可读 web 模式数据： + +- `WEB_DATA_DIR` 固定指向 `/web/data` +- `WEB_USER_SPACE_DIR` 固定指向 `/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` 添加模型配置 -2. 在 `utils/api_client.py` 实现 API 调用 -3. 配置环境变量 +1. 在 `config/custom_models.json`（生产环境建议放到 `~/.agents/agents/config/custom_models.json`）注册模型配置 +2. 在 `utils/api_client/` 中实现或复用 API 调用逻辑 +3. 通过环境变量或 `.env` 注入密钥等敏感信息 ### 创建技能包 @@ -556,22 +656,25 @@ users/ # 用户数据 ### 日志位置 -- 主日志: `logs/main.log` -- 错误日志: `logs/errors/` -- 任务日志: `logs/tasks/` -- Web 服务器: `web_server.log` +运行态日志默认位于 `~/.agents/agents//logs/`： + +- 主日志: `~/.agents/agents//logs/main.log` +- 错误日志: `~/.agents/agents//logs/errors/` +- 任务日志: `~/.agents/agents//logs/tasks/` +- Web 服务器: `~/.agents/agents//logs/web_server.log` +- 自动审批智能体调试记录: `~/.agents/agents//logs/approval_agent/` ## 版本信息 当前版本: 4.1.0 -主要更新： -- 完整的对话持久化系统 -- 子智能体并行执行 -- 多模型支持 -- 容器沙箱隔离 -- 个性化配置 -- 监控仪表板 +主要更新（2026-06）： +- 后端接口拆分为 `server/chat/`、`server/status/`、`server/tasks/` 子包 +- 运行态数据默认迁移到 `~/.agents/agents//`，支持 host/web 双路径读取 +- 子智能体改为主进程内 `asyncio.Task` 实现，工具调用复用主进程链路 +- 新增宿主机权限模式（readonly/approval/auto_approval/unrestricted）与执行环境（sandbox/direct）双层控制 +- 新增日志轮转、API dump 可控、部署级配置外置等运维能力 +- 完整的对话持久化系统、多模型支持、容器沙箱隔离、个性化配置、监控仪表板 ---