agent-Specialization/README.md

# AI Agent 系统

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

## 当前状态（2026-05）

- Web 端仍然是主线入口，基于 Flask + Vue 3。
- 新 CLI 端已开始重写，位于 `cli/`，技术栈为 React 19 + Ink 6 + TypeScript。
- 当前 CLI 不是独立后端；它会直接连接本地 `8091` Web API，并复用现有会话、任务、权限、工作区等接口。
- CLI 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。

## CLI 快速开始

### 安装与构建

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

### 开发启动

```bash
npm run cli
```

或直接：

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

### 在目标目录启动 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 模式**: 命令行交互界面，适合开发和自动化场景

### 🤖 子智能体系统

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

- **并行执行**: 最多同时运行多个子智能体
- **独立上下文**: 每个子智能体拥有独立的工作空间和对话历史
- **任务隔离**: 子智能体在独立进程中运行，互不干扰
- **状态追踪**: 实时监控子智能体的执行状态和进度
- **后台运行**: 支持后台模式，主智能体可继续处理其他任务

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

### 🛠️ 丰富的工具集

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

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

> 说明：目录创建/重命名/删除等通用文件管理建议统一使用 `run_command` 或 `run_python`。

#### 终端操作

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

**快速命令执行**:
- `run_command`: 执行 Shell 命令
- `run_python`: 执行 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                 # 程序入口
├── core/                   # 核心模块
│   ├── main_terminal.py    # 主终端（CLI模式）
│   ├── web_terminal.py     # Web终端
│   ├── tool_config.py      # 工具配置
│   └── ...
├── server/                 # Web服务器
│   ├── app.py              # Flask应用
│   ├── chat_flow_*.py      # 对话流程处理
│   ├── conversation.py     # 对话管理
│   ├── socket_handlers.py  # Socket.IO 连接与兼容事件处理（聊天主链路已迁移到 REST 任务轮询）
│   └── ...
├── modules/                # 功能模块
│   ├── file_manager.py     # 文件管理
│   ├── terminal_manager.py # 终端管理
│   ├── sub_agent_manager.py# 子智能体管理
│   ├── memory_manager.py   # 记忆管理
│   ├── search_engine.py    # 搜索引擎
│   └── ...
├── utils/                  # 工具函数
│   ├── api_client.py       # API客户端
│   ├── context_manager.py  # 上下文管理
│   ├── conversation_manager.py # 对话持久化
│   └── ...
└── config/                 # 配置文件
    ├── __init__.py         # 主配置
    ├── model_profiles.py   # 模型配置
    ├── limits.py           # 限制配置
    └── ...
```

### 前端架构

```
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 界面

启动后访问 `http://localhost: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 的新特性
```

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

## 模型支持

系统支持多个 AI 模型提供商：

### Kimi (月之暗面)
- `kimi-k2`: K2 系列模型
- `kimi-k2.5`: K2.5 最新模型
- 支持 256K 上下文窗口

### DeepSeek
- `deepseek-chat`: 快速模式
- `deepseek-reasoner`: 推理模式

### Qwen (通义千问)
- `qwen3-max`: 最大模型
- `qwen3.5-plus`: 增强版本
- `qwen3-vl-plus`: 视觉语言模型

### MiniMax
- `MiniMax-M2.5`: M2.5 模型
- 支持 204K 上下文窗口

## 技能系统 (AgentSkills)

可扩展的技能包系统，提供预定义的工作流：

- **agent-build-standard**: 标准构建流程
- **docx**: 文档处理
- **frontend-design**: 前端设计辅助
- **skill-creator**: 技能创建工具
- **sub-agent-guide**: 子智能体使用指南
- **terminal-guide**: 终端操作指南

### 安全特性

#### 宿主机模式安全

- **路径白名单**: 禁止访问系统敏感目录
- **路径遍历防护**: 防止 `..` 等路径攻击
- **根路径保护**: 禁止操作根目录和系统目录
- **符号链接检查**: 防止符号链接逃逸
- **Linux 安全模式**: 可选的额外安全限制

#### Docker 模式安全

- **完全隔离**: 容器级别的进程和文件系统隔离
- **资源配额**: 强制的 CPU、内存、存储限制
- **网络隔离**: 可配置的网络访问控制
- **只读挂载**: 支持只读文件系统挂载
- **用户映射**: 容器内外用户权限映射

#### 通用安全

### 上传安全
- 文件类型白名单
- 文件大小限制
- 恶意文件扫描
- 压缩包安全检查

### 路径安全
- 禁止访问系统目录
- 路径遍历防护
- 符号链接检查

### API 安全
- CSRF 保护
- 速率限制
- Token 验证
- Session 管理

### API 安全
- CSRF 保护
- 速率限制
- Token 验证
- Session 管理

## 使用场景建议

### 宿主机模式适用场景

1. **个人开发环境**
   - 本地开发和测试
   - 需要访问本地工具链
   - 频繁的文件系统操作

2. **可信环境**
   - 单用户使用
   - 内网环境
   - 完全可控的代码执行

3. **性能优先**
   - 大量文件操作
   - 编译构建任务
   - 需要原生性能的场景

4. **特殊工具依赖**
   - 需要特定系统工具
   - 硬件设备访问
   - 系统级操作

### Docker 模式适用场景

1. **多用户服务**
   - 公共服务部署
   - 多租户环境
   - 需要用户隔离

2. **生产环境**
   - 对外提供服务
   - 需要稳定性保证
   - 资源配额管理

3. **安全优先**
   - 执行不可信代码
   - 需要严格隔离
   - 防止恶意操作

4. **环境标准化**
   - 统一运行环境
   - 依赖管理
   - 可复现的执行环境

## 配置说明

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

### API 配置
- `API_BASE_KIMI`: Kimi API 地址
- `API_KEY_KIMI`: Kimi API 密钥
- `API_BASE_DEEPSEEK`: DeepSeek API 地址
- `API_KEY_DEEPSEEK`: DeepSeek API 密钥

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

### 限制配置
- `MAX_ITERATIONS_PER_TASK`: 单任务最大迭代次数
- `MAX_TOTAL_TOOL_CALLS`: 总工具调用次数限制
- `MAX_UPLOAD_SIZE`: 最大上传文件大小
- `PROJECT_MAX_STORAGE_MB`: 项目存储限制

### 运行环境配置

**宿主机模式**:
- `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`: 额外挂载目录

## 数据存储

### 目录结构

```
data/                       # 数据目录
├── conversations/          # 对话历史
│   └── <conversation_id>.json
├── memory/                 # 记忆文件
│   ├── main_memory.md
│   └── task_memory.md
└── personalization.json    # 个性化配置

logs/                       # 日志目录
├── tasks/                  # 任务日志
├── errors/                 # 错误日志
└── *.log

sub_agent/                  # 子智能体数据
└── tasks/                  # 任务目录
    └── <task_id>/
        ├── task.txt
        ├── output.json
        └── progress.jsonl

users/                      # 用户数据
└── <username>/
    ├── data/
    ├── project/
    └── ...
```

## 扩展开发

### 添加自定义工具

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

### 添加新模型

1. 在 `config/model_profiles.py` 添加模型配置
2. 在 `utils/api_client.py` 实现 API 调用
3. 配置环境变量

### 创建技能包

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

## 性能优化

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

## 故障排查

### 常见问题

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

### 日志位置

- 主日志: `logs/main.log`
- 错误日志: `logs/errors/`
- 任务日志: `logs/tasks/`
- Web 服务器: `web_server.log`

## 版本信息

当前版本: 4.1.0

主要更新：
- 完整的对话持久化系统
- 子智能体并行执行
- 多模型支持
- 容器沙箱隔离
- 个性化配置
- 监控仪表板

---

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