AI Agent 系统

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

当前状态（2026-05）

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

CLI 快速开始

安装与构建

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

开发启动

npm run cli

或直接：

npm --prefix cli run dev

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

🤖 子智能体系统

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

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

工具接口：

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

适用场景：

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

配置：

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                 # 程序入口
├── 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 服务商的使用条款。