AI Agent 系统

一个功能完整的 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 已实现“启动即连接后端并新建会话”的流程，但仍处于持续打磨阶段，输入法、光标、时间线裁剪等终端细节仍在迭代。
• 运行态数据（对话、用户库、日志等）默认存放在用户主目录的 ~/.agents/agents/<mode>/ 下，不再落在源码树内；源码树内的 data/、logs/、users/ 等仅作为 .gitignore 防污染保留。

CLI 快速开始

安装与构建

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

开发启动

npm run cli

或直接：

npm --prefix cli run dev

类型检查

npm --prefix cli run typecheck

在目标目录启动 CLI

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

说明：

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

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，降低部署复杂度
• 灵活操作: 支持所有系统命令和工具
• 路径透明: 文件路径与实际系统一致

适用场景：

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

配置：

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 示例：

{
  "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、内存、存储配额管理
• 安全执行: 代码在隔离环境中运行，保护宿主机
• 持久化存储: 项目文件挂载到容器
• 网络控制: 可配置网络访问策略
• 环境一致: 统一的运行环境，避免依赖问题

适用场景：

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

配置：

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

安装后端依赖：

pip install -r requirements.txt

启动 Web 服务：

python -m server.app

或带参数启动：

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: 动态模型注册文件（生产环境建议放到 ~/.agents/agents/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 用户工作区目录
• AGENTS_DATA_ROOT: 运行态数据根目录（默认 ~/.agents/agents，host/web 两个模式共享该根）
• DEPLOY_CONFIG_DIR: 部署级配置目录（默认 <AGENTS_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: 额外挂载目录

数据存储

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

• 宿主机模式（TERMINAL_SANDBOX_MODE=host）→ ~/.agents/agents/host
• 其它模式（默认 docker / web）→ ~/.agents/agents/web

目录结构

~/.agents/agents/            # 数据根目录（可通过 AGENTS_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. 数据根目录环境变量：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 最小可复现验证：

npm --prefix cli run typecheck
npm --prefix cli run build

若改动 server/chat/、server/status/、server/tasks/ 等后端接口适配，建议补充：

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

创建技能包

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

性能优化

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

故障排查

常见问题

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

日志位置

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

• 主日志: ~/.agents/agents/<mode>/logs/main.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

主要更新（2026-06）：

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

---

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