agent-Specialization/README.md

# Astrion

一个功能完整的 AI 智能体系统，支持多模态交互、子智能体协作、实时终端操作和丰富的工具集成。

## 当前状态（2026-06）

- Web 端仍然是主线入口，基于 Flask + Vue 3；聊天/状态/任务接口已拆分为 `server/chat/`、`server/status/`、`server/tasks/` 子包。
- 新 CLI 端已开始重写，位于 `cli/`，技术栈为 React 19 + Ink 6 + TypeScript。
- 当前 CLI 不是独立后端；它会直接连接本地 `8091` Web API，并复用现有会话、任务、权限、工作区等接口。
- CLI 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。
- 运行态数据（对话、用户库、日志等）默认存放在用户主目录的 `~/.astrion/astrion/<mode>/` 下，不再落在源码树内；源码树内的 `data/`、`logs/`、`users/` 等仅作为 `.gitignore` 防污染保留。

## CLI 快速开始

### 安装与构建

```bash
npm install
npm --prefix cli install
npm run cli:build
```

### 开发启动

```bash
npm run cli
```

或直接：

```bash
npm --prefix cli run dev
```

### 类型检查

```bash
npm --prefix cli run typecheck
```

### 在目标目录启动 CLI

```bash
cd /path/to/your/project
npm --prefix /Users/jojo/Desktop/agents/正在修复中/agents/cli run dev
```

说明：

- CLI 会默认把“当前终端目录”视为目标工作目录。
- 若当前目录尚未加入工作区，启动后会先提示是否将该目录加入工作区。
- CLI 会优先连接 `http://127.0.0.1:8091`；若本地服务未启动，会尝试拉起：

```bash
python3 -m server.app --path <当前目录> --port 8091 --thinking-mode
```

### 当前 CLI 已支持的能力

- 启动即创建会话，不必等首条消息发送后再建会话
- `/new` `/resume` `/model` `/versioning` `/permission` `/execution`
- `/workspace` `/compact` `/tools` `/path` `/skill` `/status` `/help` `/clear` `/exit`
- 基于任务轮询的时间线展示：用户消息、工具调用、模型输出、审批、后台状态
- 宿主机工作区接入、版本控制开关、权限模式与执行环境切换

### 当前 CLI 已知限制

- 默认隐藏思考内容，只显示“思考中 / 思考完成”标题
- 时间线布局、终端输入法光标、长内容换行等细节仍在持续修正
- 目前更适合本地开发与人工交互，不建议当作完全稳定的自动化终端入口

## 核心特性

### 🎯 多模式运行

系统支持三种运行模式，适应不同场景需求：

- **快速模式 (fast)**: 无思考过程，快速响应，适合简单任务
- **思考模式 (thinking)**: 启用推理过程，提供更深入的分析
- **深度思考模式 (deep)**: 最强推理能力，适合复杂问题

### 🌐 双端架构

- **Web 模式**: 基于 Flask + REST 任务轮询 + Vue 3 的现代化 Web 界面（保留 Socket.IO 兼容通道）
  - 实时消息流式传输
  - 多对话管理
  - 可视化文件管理器
  - 终端会话面板
  - 监控仪表板

- **CLI 模式**: 命令行交互界面，适合开发和自动化场景

### 🤖 子智能体系统

支持创建子智能体处理复杂任务：

- **并行执行**: 最多同时运行多个子智能体
- **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史
- **状态追踪**: 实时监控子智能体的执行状态和进度
- **后台运行**: 支持后台模式，主智能体可继续处理其他任务
- **实现方式**: 当前子智能体在主进程内以 `asyncio.Task` 运行，工具调用复用主进程链路；旧版 Node.js 子进程实现保留在 `easyagent/` 但已不再使用

工具接口：
- `create_sub_agent`: 创建并启动子智能体
- `close_sub_agent`: 终止运行中的子智能体
- `terminate_sub_agent`: 强制终止运行中的子智能体

### 🛠️ 丰富的工具集

系统提供分类管理的工具集，可按需启用/禁用：

#### 文件操作
- `read_file`: 读取文件内容
- `write_file`: 写入文件
- `edit_file`: 精确编辑文件内容
- `list_files`: 列出目录内容
- `search_files`: 搜索文件

> 说明：目录创建/重命名/删除等通用文件管理建议统一使用 `run_command`；需要 Python 时先探测并选择合适解释器。

#### 终端操作

**实时终端会话**:
- `terminal_session`: 创建持久化终端会话
- `terminal_input`: 向终端发送命令
- `terminal_snapshot`: 获取终端输出快照
- `sleep`: 等待命令执行完成

**快速命令执行**:
- `run_command`: 执行 Shell 命令；需要 Python 时通过命令探测并调用合适解释器

#### 网络检索
- `web_search`: 网络搜索
- `extract_webpage`: 提取网页内容
- `save_webpage`: 保存网页到本地

#### 多模态能力
- `vlm_analyze`: 视觉语言模型分析图片
- `ocr_image`: OCR 文字识别
- `view_image`: 查看图片内容
- `view_video`: 查看视频内容

#### 记忆与任务管理
- `update_memory`: 更新长期记忆
- `todo_create`: 创建待办任务
- `todo_update_task`: 更新任务状态

#### 自定义工具
- 支持管理员定义自定义工具
- 工具注册和执行框架
- 动态工具加载

### 💾 对话持久化

完整的对话管理系统：

- **多对话支持**: 创建、切换、删除多个独立对话
- **自动保存**: 对话历史实时持久化
- **对话搜索**: 按标题和内容搜索历史对话
- **对话复制**: 快速复制现有对话作为新起点
- **元数据追踪**: 记录创建时间、消息数、Token 使用等

命令：
- `/new`: 创建新对话
- `/load <id>`: 加载指定对话
- `/conversations`: 列出所有对话
- `/clear`: 清空当前对话

### 🔒 运行环境模式

系统支持两种运行环境模式，各有优势：

#### 宿主机模式 (Host Mode)

直接在宿主机上执行命令和操作，适合开发和个人使用：

- **原生性能**: 无虚拟化开销，执行速度最快
- **完整访问**: 可访问宿主机所有资源和工具
- **开发友好**: 直接使用本地环境和配置
- **简单部署**: 无需 Docker，降低部署复杂度
- **灵活操作**: 支持所有系统命令和工具
- **路径透明**: 文件路径与实际系统一致

适用场景：
- 个人开发环境
- 可信用户场景
- 需要完整系统访问权限
- 性能敏感的任务

配置：
```bash
TERMINAL_SANDBOX_MODE=host
HOST_WORKSPACES_FILE=./config/host_workspaces.json
```

宿主机模式下的安全机制（新增）：

- **执行环境（Execution Mode）**
  - `sandbox`（默认）：命令在系统级沙箱执行（macOS: `sandbox-exec`，Linux: `bwrap + seccomp`，Windows: `WSL2`）
  - `direct`：宿主机直接执行（仅建议临时用于必须操作）
  - 仅宿主机管理员可切换，支持会话级 TTL 自动回退到 `sandbox`
- **权限模式（Permission Mode）**
  - `readonly`：`run_command` 在只读沙箱执行；写入会被系统拒绝
  - `approval`：`run_command` 先按只读沙箱执行；若遇权限拒绝，再触发前端审批；审批通过后仅该次命令以可写沙箱重试
  - `auto_approval`：工作区内 `write_file/edit_file` 直通；高风险操作由后台审批智能体自动审核。`run_command` 仍先只读执行，遇权限拒绝后再自动审批
  - `unrestricted`：不做权限模式拦截（仍受执行环境约束）
- **路径授权（Path Authorization）**
  - 可配置两类路径：`可读可写` 与 `仅可读`
  - 语义：`可读集合 = 可读可写 + 仅可读`；`可写集合 = 可读可写`
  - 默认建议：仅工作区 + 临时目录可写，其余按需白名单

- **自动审批智能体（Auto Approval Agent）**
  - 配置文件：`config/auto_approval.json`
  - 核心字段：`name` / `url` / `key` / `model` / `extra_params`
  - 调试记录：可在 `modules/approval_agent.py` 打开 `DEBUG_SAVE_APPROVAL_AGENT_TRANSCRIPT`，输出到 `logs/approval_agent/`

`HOST_WORKSPACES_FILE` 对应 JSON 示例：

```json
{
  "default_workspace_id": "default",
  "workspaces": [
    { "workspace_id": "default", "label": "默认工作区", "path": "./project" },
    { "workspace_id": "my-repo", "label": "我的仓库", "path": "/Users/you/code/my-repo" }
  ]
}
```

#### Docker 容器模式 (Docker Mode)

在隔离的 Docker 容器中执行，适合多用户和生产环境：

- **环境隔离**: 每个用户独立的容器环境
- **资源限制**: CPU、内存、存储配额管理
- **安全执行**: 代码在隔离环境中运行，保护宿主机
- **持久化存储**: 项目文件挂载到容器
- **网络控制**: 可配置网络访问策略
- **环境一致**: 统一的运行环境，避免依赖问题

适用场景：
- 多用户共享服务
- 生产环境部署
- 需要安全隔离
- 资源配额管理

配置：
```bash
TERMINAL_SANDBOX_MODE=docker
TERMINAL_SANDBOX_IMAGE=ubuntu:22.04
TERMINAL_SANDBOX_CPUS=2
TERMINAL_SANDBOX_MEMORY=4g
TERMINAL_SANDBOX_MOUNT_PATH=/workspace
```

#### 模式对比

| 特性 | 宿主机模式 | Docker 模式 |
|------|-----------|------------|
| 性能 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 安全隔离 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 资源控制 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 部署复杂度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 环境一致性 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 工具访问 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |

### 🔐 宿主机安全边界总览

在宿主机模式下，安全边界分两层：

1. **权限模式（产品层）**：决定是否允许执行、是否需要审批、是否使用只读沙箱优先策略。  
2. **执行环境（系统层）**：决定命令最终在 `sandbox` 还是 `direct` 运行。  

推荐默认：
- 执行环境：`sandbox`
- 权限模式：`approval`（通用）或 `readonly`（高保守）

详细机制文档见：`docs/host_sandbox_and_permission_model.md`

### 👥 多用户管理

完整的用户系统：

- **用户认证**: 基于 Session 的身份验证
- **权限管理**: 普通用户 / 管理员角色
- **配额控制**: 按用户限制 API 调用次数
- **工作空间隔离**: 每个用户独立的数据目录
- **使用统计**: 追踪用户活动和资源使用

### 🎨 个性化配置

用户可自定义智能体行为：

- **身份设定**: 自定义智能体名称和用户称呼
- **语气风格**: 健谈、幽默、直言不讳、鼓励性等预设
- **工具偏好**: 选择性启用/禁用工具类别
- **模型选择**: 切换不同的 AI 模型
- **思考间隔**: 调整思考模式的输出频率
- **图片压缩**: 控制图片上传质量

### 📊 监控与统计

实时系统监控：

- **Token 统计**: 输入/输出 Token 使用量
- **工具调用**: 各工具使用频率统计
- **文件操作**: 读写操作记录
- **记忆使用**: 记忆系统活动追踪
- **性能指标**: 响应时间、错误率等

## 架构设计

### 后端架构

```
agents/
├── 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 任务轮询）
├── 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/         # API 客户端（已拆分为子包）
│   ├── tool_result_formatter/# 工具结果格式化（已拆分为子包）
│   ├── context_manager/    # 上下文管理（已拆分为子包）
│   ├── conversation_manager/# 对话持久化（已拆分为子包）
│   ├── log_rotation.py     # 日志轮转
│   └── ...
├── config/                 # 配置拆分
│   ├── __init__.py         # 主配置（聚合并加载 .env）
│   ├── paths.py            # 路径解析与运行态目录
│   ├── api.py              # API 配置
│   ├── limits.py           # 限制配置
│   ├── terminal.py         # 终端配置
│   └── ...
├── easyagent/              # 旧版 Node.js 子智能体实现，暂时保留但已不再使用
└── _experiments/           # 本地实验残留与历史文档归档（不纳入 git）
```

### 前端架构

```
static/src/
├── App.vue                 # 主应用组件
├── main.ts                 # 入口文件
├── app/                    # 应用逻辑
│   ├── state.ts            # 状态管理
│   ├── methods/            # 方法模块
│   │   ├── conversation.ts # 对话管理
│   │   ├── message.ts      # 消息处理
│   │   ├── tooling.ts      # 工具调用
│   │   └── ...
│   └── ...
├── components/             # UI组件
│   ├── ConversationSidebar.vue
│   ├── MessageList.vue
│   ├── ToolCallDisplay.vue
│   └── ...
├── composables/            # 组合式函数
│   ├── useMarkdownRenderer.ts
│   ├── useScrollControl.ts
│   └── ...
└── stores/                 # Pinia状态管理
    └── ...
```

### 数据流

1. **用户输入** → REST API（Web）/CLI
2. **消息处理** → ContextManager 构建上下文
3. **API 调用** → DeepSeekClient 发送请求
4. **流式响应** → 实时解析工具调用
5. **工具执行** → 各模块处理具体操作
6. **结果返回** → 流式输出到前端
7. **持久化** → ConversationManager 保存历史

## 使用方法

### Web 界面

安装后端依赖：

```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）

#### 基本操作

1. **发送消息**: 在输入框输入内容，按 Enter 或点击发送按钮
2. **创建对话**: 点击侧边栏的"新建对话"按钮
3. **切换对话**: 在侧边栏点击历史对话
4. **删除对话**: 右键对话项选择删除
5. **搜索对话**: 使用侧边栏搜索框

#### 工作区面板

- **文件管理器**: 浏览和管理项目文件
- **终端面板**: 查看和交互终端会话
- **监控面板**: 查看系统统计信息

#### 快捷键

- `Ctrl/Cmd + Enter`: 发送消息
- `Ctrl/Cmd + K`: 聚焦输入框
- `Esc`: 停止生成

### CLI 模式

通过环境变量设置 `WEB_MODE=false` 启用 CLI 模式

#### 命令

- `help`: 显示帮助信息
- `exit`: 退出系统
- `status`: 显示系统状态
- `memory`: 管理记忆
- `clear`: 清空当前对话
- `history`: 查看对话历史
- `files`: 显示文件列表
- `mode`: 切换运行模式
- `terminals`: 显示终端列表
- `conversations`: 列出所有对话
- `load <id>`: 加载指定对话
- `new`: 创建新对话

### 工具使用示例

#### 文件操作
```
请帮我创建一个 Python 脚本 hello.py，内容是打印 Hello World
```

#### 终端操作
```
请在终端中运行 npm install 安装依赖
```

#### 网络搜索
```
搜索一下 Python 3.12 的新特性
```

#### 子智能体
```
请创建一个子智能体帮我分析这个项目的代码结构
```

## 模型支持

系统不再内置任何固定供应商模型。可用模型由 `config/custom_models.json`（或后续 API 扩展配置）动态注册，前后端均通过 `/api/v1/models` 获取当前模型列表。

每个模型配置应提供 API 地址、密钥、模型 ID、上下文窗口、输出 token 上限、多模态能力和思考模式参数等信息；需要额外请求参数时，通过配置中的 `extra_parameter` / `thinkmode_status.*_extra_parameter` 注入。


## 配置说明

主要配置项（通过环境变量或 `.env` 文件）：

### API 配置
- `config/custom_models.json`: 动态模型注册文件（生产环境建议放到 `~/.astrion/astrion/config/custom_models.json`，host/web 共享）
- `AGENT_DEFAULT_MODEL`: 可选，指定默认模型 key；未设置时使用第一个可见动态模型
- 模型配置中的 `url` / `apikey` 支持 `${ENV_NAME}`、`env:ENV_NAME`、`$ENV_NAME` 等环境变量引用

### 服务配置
- `WEB_SERVER_PORT`: Web 服务器端口（默认 8091）
- `DEFAULT_PROJECT_PATH`: 默认项目路径

### 运行态路径配置
- `DATA_DIR`: 数据目录（对话、记忆、子智能体等）
- `LOGS_DIR`: 日志目录
- `USER_SPACE_DIR`: Web 用户工作区目录
- `API_USER_SPACE_DIR`: API 用户工作区目录
- `ASTRION_DATA_ROOT`: 运行态数据根目录（默认 `~/.astrion/astrion`，host/web 两个模式共享该根）
- `DEPLOY_CONFIG_DIR`: 部署级配置目录（默认 `<ASTRION_DATA_ROOT>/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）

### 运行环境配置

**宿主机模式**:
- `TERMINAL_SANDBOX_MODE=host`: 启用宿主机模式
- `HOST_WORKSPACES_FILE`: 宿主机工作区 JSON 配置文件路径
- `LINUX_SAFETY`: Linux 安全保护开关

**Docker 模式**:
- `TERMINAL_SANDBOX_MODE=docker`: 启用容器模式
- `TERMINAL_SANDBOX_IMAGE`: Docker 镜像（如 ubuntu:22.04）
- `TERMINAL_SANDBOX_CPUS`: CPU 限制（如 2）
- `TERMINAL_SANDBOX_MEMORY`: 内存限制（如 4g）
- `TERMINAL_SANDBOX_MOUNT_PATH`: 容器内挂载路径
- `TERMINAL_SANDBOX_NETWORK`: 网络模式
- `TERMINAL_SANDBOX_BINDS`: 额外挂载目录

## 数据存储

运行态数据默认存放在用户主目录的 `~/.astrion/astrion/<mode>/` 下（按 `TERMINAL_SANDBOX_MODE` 自动分流）：

- **宿主机模式**（`TERMINAL_SANDBOX_MODE=host`）→ `~/.astrion/astrion/host`
- **其它模式**（默认 docker / web）→ `~/.astrion/astrion/web`

### 目录结构

```
~/.astrion/astrion/            # 数据根目录（可通过 ASTRION_DATA_ROOT 覆盖）
├── settings.json            # 唯一配置文件
├── config/                  # 部署级配置（custom_models/host_workspaces/auto_approval 等，host/web 共享）
├── host/                    # 宿主机模式运行态
│   ├── data/                # 数据目录
│   │   ├── conversations/   # 对话历史
│   │   │   └── <conversation_id>.json
│   │   ├── memory/          # 记忆文件
│   │   │   ├── main_memory.md
│   │   │   └── task_memory.md
│   │   ├── personalization.json
│   │   ├── sub_agents.json  # 子智能体注册表
│   │   └── sub_agent_tasks/ # 子智能体任务数据
│   │       └── <task_id>/
│   │           ├── task.txt
│   │           ├── output.json
│   │           └── progress.jsonl
│   └── logs/                # 日志目录
│       ├── tasks/
│       ├── errors/
│       ├── approval_agent/
│       └── *.log
└── web/                     # web/docker 模式运行态
    ├── data/
    ├── users/               # Web 多用户工作区
    │   └── <username>/
    │       ├── data/
    │       ├── project/
    │       └── ...
    ├── api/users/           # API 用户工作区
    └── logs/
```

### 路径解析优先级（从高到低）

1. **具体目录环境变量**：`DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR`（单独覆盖某个目录）
2. **数据根目录环境变量**：`ASTRION_DATA_ROOT`（整体搬迁运行态数据根目录，默认 `~/.astrion/astrion`）
3. **兜底默认**：`~/.astrion/astrion/<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
```

## 扩展开发

### 添加自定义工具

1. 在 `modules/custom_tool_registry.py` 注册工具
2. 实现工具执行逻辑
3. 在 `core/tool_config.py` 添加工具定义
4. 重启系统加载新工具

### 添加新模型

1. 在 `config/custom_models.json`（生产环境建议放到 `~/.astrion/astrion/config/custom_models.json`）注册模型配置
2. 在 `utils/api_client/` 中实现或复用 API 调用逻辑
3. 通过环境变量或 `.env` 注入密钥等敏感信息

### 创建技能包

1. 在 `agentskills/` 目录创建技能文件夹
2. 编写技能定义和提示词
3. 在前端注册技能

## 性能优化

- **流式输出**: 实时显示生成内容
- **增量上下文**: 仅发送必要的上下文
- **工具结果缓存**: 避免重复操作
- **对话压缩**: 自动总结长对话
- **并发处理**: 子智能体并行执行
- **资源池化**: 复用终端会话和容器

## 故障排查

### 常见问题

1. **连接失败**: 检查 API 密钥和网络连接
2. **工具调用失败**: 查看日志文件定位错误
3. **容器启动失败**: 检查 Docker 配置和权限
4. **文件操作失败**: 确认路径权限和存储空间
5. **对话加载失败**: 检查数据目录完整性

### 日志位置

运行态日志默认位于 `~/.astrion/astrion/<mode>/logs/`：

- 主日志: `~/.astrion/astrion/<mode>/logs/main.log`
- 错误日志: `~/.astrion/astrion/<mode>/logs/errors/`
- 任务日志: `~/.astrion/astrion/<mode>/logs/tasks/`
- Web 服务器: `~/.astrion/astrion/<mode>/logs/web_server.log`
- 自动审批智能体调试记录: `~/.astrion/astrion/<mode>/logs/approval_agent/`

## 版本信息

当前版本: 4.1.0

主要更新（2026-06）：
- 后端接口拆分为 `server/chat/`、`server/status/`、`server/tasks/` 子包
- 运行态数据默认迁移到 `~/.astrion/astrion/<mode>/`，支持 host/web 双路径读取
- 子智能体改为主进程内 `asyncio.Task` 实现，工具调用复用主进程链路
- 新增宿主机权限模式（readonly/approval/auto_approval/unrestricted）与执行环境（sandbox/direct）双层控制
- 新增日志轮转、API dump 可控、部署级配置外置等运维能力
- 完整的对话持久化系统、多模型支持、容器沙箱隔离、个性化配置、监控仪表板

---

**注意**: 本系统仅供学习和研究使用，请遵守相关 API 服务商的使用条款。