deepbot

DeepBot 系统架构图（来源：项目 README）

---

一款能让 AI 真正"打工"的系统级助手

想象一下：你对 AI 说一句"帮我整理本周的项目进展报告"，它就能自动读取飞书文档、调取聊天记录、分析数据表格、生成图文报告——整个过程你无需手动复制粘贴任何一个字。这就是 DeepBot 想要实现的目标。

DeepBot 是由独立开发者 K Luo（GitHub: kevinluosl）于 2026 年 1 月开源的系统级 AI 助手，定位介于"聊天机器人"和"企业 OA 系统"之间。它不只是一个对话界面，而是一个能驱动 AI 在真实企业环境中执行多步骤复杂任务的 Agent 平台。截至分析时，该项目已在 GitHub 获得 2,349 Stars，在同类企业级 AI Agent 项目中增长势头强劲。

为什么企业需要 DeepBot

传统的 AI 助手（ChatGPT、Claude 等）在回答问题方面表现出色，但在"干活"方面存在明显短板：无法操作文件、无法访问内部系统、无法跨平台协作。DeepBot 通过引入 20+ 工具 + 多 Agent 协作机制，让 AI 从"能说会道"升级为"能干活"。

举个例子：在 DeepBot 的多 Agent 模式下，销售 Agent 可以将客户需求推送给解决方案 Agent，后者分析后形成的技术方案再自动同步给项目管理 Agent——整个跨部门协作流程由 AI 自动串联，无需人工介入。

---

技术架构：Gateway 驱动的多 Agent 系统

DeepBot 的技术架构采用分层设计，核心分为四层：

1. Gateway 层（会话路由中枢）

Gateway 是整个系统的核心，负责管理所有 Session（会话）。每个浏览器 Tab 对应一个独立 Session，支持消息队列、连接器管理和跨 Tab 消息路由。这意味着不同 Tab 中的 Agent 可以互相通信，共同完成复杂任务。

2. Agent Runtime 层（每个 Session 一个）

基于 @mariozechner/pi-agent-core 框架实现，负责智能决策和工具编排。每个 Agent Runtime 内置：

• 自动继续机制：当任务未完成时，Agent 自动规划下一步（最多 100 次循环）
• 操作追踪：防止重复执行同一操作（最多 3 次）
• 独立记忆：每个 Session 有独立的上下文和记忆文件
• 跨 Tab 调用：通过 cross-tab-call-tool 实现跨 Agent 通信

3. 系统提示词动态组装层

DeepBot 没有使用静态 system prompt，而是将提示词拆分为多个可插拔的模块：

• AGENT.md — 基础 Agent 行为定义
• TOOLS.md — 工具使用说明（动态加载）
• CUSTOM-TOOLS.md — 用户自定义工具说明
• MEMORY.md — 全局记忆
• memory-<tab-id>.md — Session 级记忆
• SKILL.md — Skills 指令

这种设计让 Agent 能够实时感知上下文变化，比如用户修改了某个记忆文件，Agent 下一次调用时会自动读取最新内容。

4. 工具层（Tool Registry + Handlers）

DeepBot 内置 36 个工具，涵盖文件操作、命令执行、浏览器控制、图片生成、图片/视频分析、文档解析、AI 对话、网页抓取、飞书/微信/企业微信消息、飞书云文档操作、日历管理、定时任务等。其中工具通过 registry 目录统一注册，handlers 目录处理各工具的具体逻辑。

---

核心技术栈

DeepBot 是一款全栈 TypeScript 项目，主语言占比 100%：

• 桌面端：Electron 28+（macOS/Windows 原生应用）
• Web 端：Express（后端）+ Vite（前端）+ React
• 核心框架：@mariozechner/pi-agent-core（AI Agent 运行时）、@mariozechner/pi-ai（AI 接口封装）
• 外部集成：飞书 SDK（@larksuiteoapi/node-sdk）、微信/企业微信机器人 SDK
• 前端 UI：Tailwind CSS、Headless UI、React
• 构建工具：pnpm workspace、electron-builder

值得注意的是，DeepBot 同时维护了桌面版（Electron）和 Web 版（Express+Vite）两套前端，构建系统需要通过 dist:mac/dist:win/dist:web 分别打包。

---

上手体验：桌面版 vs Web 版

桌面版（Electron）：适合个人用户直接在 macOS/Windows 上使用。首次安装后通过 UI 配置 AI API Key（支持通义千问、OpenAI、Claude、DeepSeek 等），界面直观，但 macOS 本地构建未签名，首次启动需要手动绕过安全警告。

Web 版（Docker 部署）：适合团队共享或服务器长期运行。通过 docker-compose 一键部署，数据持久化到宿主机目录，支持多用户通过密码+JWT 认证访问。Web 版部署需要配置 AI API Key（通过 .env 文件或 UI 界面），不支持本地大模型推理，必须依赖第三方 AI 服务。

---

外部 API：让其他系统调用 DeepBot

DeepBot 提供了一套完整的外部 REST API，允许其他 AI Agent 或自动化程序通过 HTTP 请求调用 DeepBot 的能力：

• 基础地址：http://<host>:3000
• 认证方式：请求头 X-Secret = JWT_SECRET
• 核心接口：
  • POST /api/external/message — 向指定 Tab 发送消息，等待 AI 完整回复（最长 5 分钟同步阻塞）
  • 支持附件（图片、文件 base64 上传）
  • 支持图片生成结果获取

这套 API 让 DeepBot 可以作为企业 AI 能力中台，供其他系统调用，而无需暴露 AI 账号密码。

---

优势与局限

优势：

• 企业场景覆盖完整，从文件操作到飞书文档到消息发送，一条链路全覆盖
• 多 Agent 协作架构支持复杂业务流程的自动化编排
• Docker 部署开箱即用，技术门槛低
• 全程 TypeScript，代码质量有保障

局限：

• AI 模型必须自备：无论是桌面版还是 Web 版，都需要用户提供通义千问/OpenAI/Claude 等 API Key，项目本身不含模型推理能力
• 安全门槛需要手动配置：路径白名单、JWT 密钥等安全参数依赖用户正确配置，对于非技术用户有一定门槛
• 微信/企业微信机器人依赖第三方非官方 SDK，微信平台政策变化可能导致功能失效

---

行业意义

DeepBot 代表了 AI Agent 从"对话"向"执行"演进的趋势。随着大模型工具调用能力（Function Calling / Tool Use）的成熟，像 DeepBot 这样将大量工具注册为 Agent 能力的框架正在成为企业 AI 落地的主流范式。相比 LangChain、AutoGPT 等通用框架，DeepBot 的差异化在于深度集成飞书/微信生态，这对于国内企业用户具有显著的本土化优势。

截至分析时，DeepBot 仍处于活跃开发阶段（v0.9.0），文档显示未来规划包括更多平台集成和技能扩展。

---

分析数据来源：GitHub 仓库（kevinluosl/deepbot）、项目 README（README.md、README_ZH.md）、external-api.md 及源码结构。