Skip to content

Repository files navigation

🐈 PocketBot — 轻量本地自动化智能体

PocketBot 是基于 LangGraph 原生 ReAct 流程构建、可私有化部署的长期运行AI智能体。

不同于仅能即时应答的对话机器人,PocketBot 主打持久任务执行、目标自动拆解、定时本地自动化,内置长期记忆、系统工具集,运行环境一体化无额外依赖。

项目在保证智能体内核精简易读、易于二次修改的前提下,提供一套完整可用的自动化能力。

README:中文 | English

Image

Image

Image

Image

Image


✨ 功能特性

Agent 核心(Python langgraph)

  • ReAct 循环:基于 langgraph StateGraph(agent 节点 + ToolNode + 条件边)
  • 23 个内置工具:覆盖 9 个类别(文件、Shell、Web、记忆、目标、自动化、媒体、子agent、工具)
  • 流式输出:SSE 逐 token 响应 + 工具调用事件
  • 长期记忆:SQLite FTS5 全文搜索(Dream 风格)
  • 目标分解:LLM 驱动的目标拆解为步骤
  • 定时自动化:基于 APScheduler(cron + 固定间隔)
  • OpenAI 兼容 API:供集成使用
  • WebSocket 实时聊天端点

WebUI(Next.js 16 + shadcn/ui)

  • 聊天 — 流式响应、工具调用卡片、Markdown 渲染、语法高亮
  • 记忆 — FTS 搜索、增删、类型过滤、导入导出
  • 目标 — 步骤编辑器 + 自动进度、AI 分解、导入导出
  • 自动化 — cron 调度、启用/禁用、下次运行时间
  • 文件 — 沙盒工作区、上传、全文搜索、最近查看
  • 技能 — 运行时统计、工具使用条形图、全部工具目录
  • 设置 — 统计仪表盘、备份恢复、危险区域、反馈历史
  • 命令面板(⌘P)— 快速导航和操作
  • 通知铃铛 — 自动化运行、数据操作、系统事件
  • 语音输入(ASR)+ TTS 朗读
  • 暗色模式(翡翠青色主题)
  • 键盘快捷键(⌘K、⌘/、⌘Enter)
  • 消息复制/编辑/重新生成点赞/踩反馈
  • 每会话统计(消息数、工具调用数、时长)
  • 会话搜索置顶导出(markdown/JSON)
  • 完整备份恢复(会话 + 记忆 + 目标 + 自动化)
  • 数据清除(两步确认)

🏗️ 架构

系统总览

                          ┌──────────────────────────────────┐
                          │           用户                    │
                          │  浏览器 / CLI / API 客户端        │
                          └──────────┬───────────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │         Caddy 网关 (:81)         │
                    │  反向代理 + XTransformPort       │
                    │  路由 /api/pb/* → :8765          │
                    │  其他请求 → :3000                │
                    └──────┬──────────────────┬────────┘
                           │                  │
            ┌──────────────▼──┐         ┌─────▼──────────────┐
            │  Next.js 16      │         │  Python 后端        │
            │  WebUI (:3000)   │         │  (:8765)            │
            │                  │         │                     │
            │  ┌─────────────┐ │  启动   │  ┌────────────────┐ │
            │  │ /api/pb/*   │─┼────────►│  │  FastAPI 应用  │ │
            │  │ 代理路由     │ │  & 管理 │  │  (app.py)      │ │
            │  └─────────────┘ │         │  └───────┬────────┘ │
            │                  │         │          │          │
            │  React 组件      │         │  ┌───────▼────────┐ │
            │  shadcn/ui (40+) │         │  │ langgraph      │ │
            │  Tailwind CSS 4  │         │  │ ReAct Agent    │ │
            │  next-themes     │         │  │ (agent.py)     │ │
            │                  │         │  └───┬───────┬────┘ │
            └──────────────────┘         │      │       │      │
                                         │  ┌───▼──┐ ┌─▼────┐ │
                                         │  │工具   │ │ LLM  │ │
                                         │  │(23+)  │ │ 路由 │ │
                                         │  └──┬───┘ └──┬───┘ │
                                         │     │        │     │
                                         │  ┌──▼──┐ ┌───▼───┐ │
                                         │  │SQLite│ │Z-AI / │ │
                                         │  │存储  │ │DeepSeek│
                                         │  │      │ │/OpenAI│
                                         │  └─────┘ └───────┘ │
                                         └─────────────────────┘

数据流

用户发送消息
    │
    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  WebUI / CLI │────►│  FastAPI     │────►│  langgraph      │
│  (聊天输入)  │     │  /api/chat   │     │  ReAct 循环     │
└─────────────┘     │  (SSE 流式)  │     │                 │
                    └──────────────┘     │  ┌───────────┐  │
                                         │  │ agent 节点│  │
                                         │  │ (LLM调用) │  │
                                         │  └─────┬─────┘  │
                                         │        │        │
                                         │   有tool_calls? │
                                         │   ├─是→ tool    │
                                         │   │     节点    │
                                         │   │     │       │
                                         │   └─否 → 结束   │
                                         └────────┬────────┘
                                                  │
                                         ┌────────▼────────┐
                                         │  SQLite 存储    │
                                         │  • 会话         │
                                         │  • 消息         │
                                         │  • 记忆 (FTS5)  │
                                         │  • 目标         │
                                         │  • 自动化       │
                                         │  • 审计日志     │
                                         └─────────────────┘

LLM 提供商路由

config.json
┌─────────────────────────────────────────────────────┐
│ providers:                                          │
│   deepseek: {apiKey, apiBase}                       │
│   openai:   {apiKey, apiBase}                       │
│   zai:      {apiKey, apiBase, token, ...}           │
│                                                     │
│ modelPresets:                                       │
│   primary:  {provider: "deepseek", model: "deepseek-v4-flash"} │
│   fast:     {provider: "openai", model: "gpt-4o-mini"}     │
└──────────────────┬──────────────────────────────────┘
                   │
          ┌────────▼────────┐
          │  resolve_preset()│
          │  (config.py)     │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  get_chat_model()│
          │  (llm.py)        │
          │                  │
          │  if Z-AI:        │──► 添加 X-Z-AI-from, X-Token 头
          │  if 其他:        │──► 标准 Bearer 认证
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  ChatOpenAI      │
          │  (langchain)     │
          │  streaming=True  │
          └─────────────────┘

后端(Python,端口 8765)

mini-services/pocketbot-agent/
├── index.py                  # uvicorn 入口(启动 FastAPI)
├── pocketbot                 # CLI 可执行入口(链接到 cli.py)
├── package.json              # bun dev 脚本
├── data/                     # 运行时自动创建
│   ├── pocketbot.db            # SQLite:会话、消息、记忆、目标、自动化、审计
│   └── config.json           # 提供商、模型预设、Web工具、安全、MCP服务器
├── workspace/                # 沙盒文件工作区
│   └── skills/               # 动态技能目录(自动发现)
│       └── example/          # 示例技能(含 hello_example 工具)
└── pocketbot_agent/          # Python 包(agent 核心)
    ├── __init__.py
    ├── config.py             # AppConfig, PROVIDER_TEMPLATES(7个提供商), 模型预设
    ├── llm.py                # ChatOpenAI 绑定, 提供商路由(Z-AI/DeepSeek/OpenAI/...), 流式
    ├── store.py              # SQLite 存储:会话、消息、记忆(FTS5)、目标、自动化、审计
    ├── workspace.py          # 沙盒文件系统(路径锁定, 列表/读/写/删/树)
    ├── tools.py              # 23个内置工具(文件/shell/web/记忆/目标/自动化/媒体/子agent/工具)
    ├── skills.py             # 动态技能系统(自动发现 skill.json, Python/shell handler)
    ├── mcp.py                # MCP(模型上下文协议)服务器支持(stdio 传输)
    ├── prompts.py            # pocketbot 系统提示词(主动、自主、工具优先)
    ├── agent.py              # langgraph StateGraph:ReAct 循环(agent 节点 → ToolNode → 条件边)
    ├── scheduler.py          # APScheduler:cron + 间隔自动化
    ├── cli.py                # 完整 CLI:onboard/agent/gateway/serve/status/channels/plugins/provider
    └── app.py                # FastAPI 应用:REST API + WebSocket + OpenAI兼容 + SSE 流式

前端(Next.js,端口 3000)

src/
├── app/
│   ├── layout.tsx            # 根布局(ThemeProvider, Toaster, 元数据)
│   ├── page.tsx              # 主页面(侧边栏 + 7个面板 + 命令面板 + 通知铃铛)
│   ├── globals.css           # 翡翠青色主题, prose 样式, 动画, 滚动条
│   └── api/
│       └── pb/[...path]/route.ts  # 代理路由(启动并管理 Python 后端为子进程)
├── lib/
│   ├── pocketbot-api.ts        # 类型化 API 客户端(40+ 端点)
│   ├── backend-manager.ts    # 后端进程管理器(启动, 健康检查, 自动重启)
│   └── utils.ts              # cn() Tailwind 辅助函数
└── components/
    ├── ui/                   # shadcn/ui 组件(40+:button, card, dialog, select 等)
    └── pocketbot/            # 应用组件
        ├── chat-view.tsx          # 聊天:流式, 会话, 搜索, 导出, 模型切换, 统计
        ├── message-bubble.tsx     # 气泡, 工具卡片(diff/image/shell), 复制/编辑/重新生成/反馈/TTS
        ├── memory-panel.tsx       # 记忆增删查, FTS搜索, 类型过滤, 导入导出
        ├── goals-panel.tsx        # 目标 + 步骤编辑器, 自动进度, AI分解, 导入导出
        ├── automations-panel.tsx  # cron 调度, 启用/禁用, 下次运行显示
        ├── files-panel.tsx        # 文件浏览器, 上传, 全文搜索, 最近查看, 图片预览
        ├── skills-panel.tsx       # 工具目录, 使用条形图, 动态技能, MCP服务器, 重新加载
        ├── settings-panel.tsx     # 统计仪表盘, 备份恢复, 危险区域, 反馈历史
        ├── command-palette.tsx    # ⌘P 快速导航 + 操作
        ├── notification-bell.tsx  # 自动化运行, 数据操作, 系统事件
        ├── voice-input.tsx        # ASR 麦克风输入 + TTS 朗读按钮
        ├── file-uploader.tsx      # 拖拽上传(multipart)
        └── theme-provider.tsx     # next-themes 包装(明/暗)

🔧 技术栈

层级 技术
Agent 核心 Python 3.12, langgraph 1.2, langchain 1.3, langchain-openai
后端 API FastAPI, uvicorn, httpx, APScheduler
数据库 SQLite(WAL 模式, FTS5 记忆搜索)
LLM Z-AI glm-4-plus(OpenAI 兼容端点)
Web 工具 Z-AI CLI(web_searchpage_readerimage 图像生成)
语音 Z-AI CLI(asr 语音转文字、tts 文字转语音)
前端 Next.js 16, React, TypeScript 5
UI shadcn/ui (New York), Tailwind CSS 4, Lucide 图标
Markdown react-markdown, remark-gfm, rehype-highlight
网关 Caddy(带 XTransformPort 路由的反向代理)

📦 23+ Agent 工具

内置工具

类别 工具 描述
文件 file_list, file_read, file_write, file_delete 沙盒工作区文件操作
Shell shell_exec 执行 shell 命令(限时、黑名单)
Web web_search, web_fetch 实时网页搜索 + 页面内容提取
记忆 memory_add, memory_search, memory_list, memory_delete 长期记忆(FTS5 搜索)
目标 goal_create, goal_list, goal_update, goal_decompose 目标跟踪 + AI 驱动步骤分解
自动化 automation_create, automation_list, automation_delete, cron_list cron 调度 + 任务管理
媒体 image_generate 文字生成 AI 图像
子agent subagent_spawn 委派子任务到独立会话
工具 current_time, calculator 时间 + 安全数学表达式

动态技能系统

技能是从 workspace/skills/ 加载的外部工具包。每个技能是一个包含 skill.json 的目录,定义一个或多个工具。

创建技能

mkdir -p workspace/skills/my-skill

创建 workspace/skills/my-skill/skill.json

{
  "name": "my-skill",
  "description": "我的自定义技能",
  "tools": [{
    "name": "my_tool",
    "description": "做些有用的事",
    "parameters": {
      "type": "object",
      "properties": {"input": {"type": "string"}},
      "required": ["input"]
    },
    "handler": "handler.py:my_function",
    "category": "Custom"
  }]
}

创建 workspace/skills/my-skill/handler.py

async def my_function(input: str) -> dict:
    """做些有用的事。"""
    return {"result": f"已处理: {input}"}

技能在启动时自动发现。使用技能面板中的重新加载技能按钮或调用 POST /api/skills/reload 可热重载。

在mini-services/pocketbot-agent/workspace/skills/ppt-master已集成ppt生成skill,

测试生成的ppt案例在mini-services/pocketbot-agent/workspace/projects下

Shell 命令技能

也可以用 shell 命令代替 Python handler:

{
  "name": "disk_usage",
  "tools": [{
    "name": "du",
    "description": "检查磁盘使用",
    "parameters": {"type": "object", "properties": {"path": {"type": "string", "default": "/"}}},
    "command": "du -sh {path}",
    "category": "System"
  }]
}

禁用技能

在 config.json 中添加技能名到 disabledSkills

{
  "agents": {
    "defaults": {
      "disabledSkills": ["example", "web-browsing"]
    }
  }
}

MCP(模型上下文协议)支持

连接外部 MCP 服务器以扩展 agent 的工具。MCP 工具通过 tools/list 方法自动发现并注册。

配置

在 config.json 中添加 MCP 服务器:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

MCP 工具注册为 mcp_<服务器>_<工具>,在技能面板的 MCP/<服务器> 分类下显示。


🚀 快速开始

前置条件

  • Python 3.11+(测试于 3.12)
  • Node.js 18+ / bun

选项 A:CLI 模式(仅终端)

1. 安装后端依赖

cd mini-services/pocketbot-agent
pip install langgraph langchain langchain-openai langchain-community \
    fastapi uvicorn httpx apscheduler pydantic openai

2. 初始化并配置 LLM

cd mini-services/pocketbot-agent

# 交互式向导 — 选择你的 LLM 提供商(DeepSeek、OpenAI、Anthropic 等)
python pocketbot onboard --wizard

# 或使用默认配置(Z-AI glm-4-plus)
python pocketbot onboard

向导会引导你:

  1. 选择提供商:DeepSeek、OpenAI、Anthropic、OpenRouter、Ollama、Z-AI 或自定义
  2. 输入 API Key(Ollama 不需要)
  3. 确认 API 地址(已预填提供商默认值)
  4. 选择模型(如 deepseek-v4-flashgpt-4oclaude-sonnet-4
  5. 设置温度和最大 token 数

示例 — 配置 DeepSeek:

  Choose your LLM provider:
    1. deepseek — DeepSeek (deepseek-v4-flash, deepseek-v4-pro)
    2. openai — OpenAI (GPT-4o, GPT-4o-mini, etc.)
    ...
  Select provider (1-7) [1]: 1
  → Selected: deepseek
  API Key for deepseek: sk-your-deepseek-api-key
  API Base [https://api.deepseek.com/v1]:
  Available models: deepseek-v4-flash, deepseek-v4-pro
  Model [deepseek-v4-flash]:
  Temperature [0.4]:
  Max tokens [8192]:
  ✓ Config: data/config.json
  ✓ Provider: deepseek
  ✓ Model: deepseek-v4-flash

3. 使用 Agent

# 单次消息
python pocketbot agent -m "现在几点了?"

# 交互模式(输入 exit 或 Ctrl+C 退出)
python pocketbot agent

# 检查状态
python pocketbot status

支持的 LLM 提供商

提供商 API 地址 模型 需要 API Key
DeepSeek https://api.deepseek.com/v1 deepseek-v4-flash, deepseek-v4-pro
OpenAI https://api.openai.com/v1 gpt-4o, gpt-4o-mini, gpt-4-turbo
Anthropic https://api.anthropic.com/v1 claude-sonnet-4, claude-3.5-sonnet
OpenRouter https://openrouter.ai/api/v1 anthropic/claude-sonnet-4, openai/gpt-4o
Ollama http://127.0.0.1:11434/v1 llama3, qwen2, mistral
Z-AI https://internal-api.z.ai/v1 glm-4-plus
自定义 (任意) (任意)

手动配置

也可以直接编辑 data/config.json

{
  "providers": {
    "deepseek": {
      "apiKey": "sk-your-deepseek-api-key",
      "apiBase": "https://api.deepseek.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "deepseek",
      "model": "deepseek-v4-flash",
      "maxTokens": 8192,
      "temperature": 0.4
    }
  },
  "agents": {
    "modelPreset": "primary"
  }
}

运行时切换模型

在交互模式中使用 /model 命令:

You: /model
🧠 Active model: primary
   Available presets: primary

You: /model primary
🧠 Switched to model preset: primary

要添加更多预设,编辑 config.jsonmodelPresets 下添加条目。

选项 B:WebUI 模式(浏览器)

1. 启动前端

# 从项目根目录
安装:npm install(下载安装node,https://nodejs.org/zh-cn/download)

运行:npm run dev

或者 bun run dev(需安装bun,下载安装https://github.com/oven-sh/bun/releases)

# 前端运行在 http://localhost:3000

2. 访问 WebUI

在浏览器中打开 http://localhost:81(通过 Caddy 网关)。

注意: Next.js 代理路由(/api/pb/*)会自动启动并管理 Python 后端为子进程,所以只需启动前端 — 后端按需启动。


💻 CLI 参考

pocketbot CLI 提供完整的命令行界面。从 mini-services/pocketbot-agent/ 运行:

cd mini-services/pocketbot-agent
python pocketbot <命令> [选项]

命令

命令 描述
pocketbot onboard 生成 config.json 和工作区。加 --wizard 进行引导设置。
pocketbot agent 与 agent 对话(交互模式)。
pocketbot agent -m "消息" 单次消息(非交互)。
pocketbot gateway 启动网关 — REST API + WebSocket + 调度器。
pocketbot serve 启动 OpenAI 兼容 API 服务器(:8900)。
pocketbot status 快速健康检查 — 配置、工作区、模型、数据计数。
pocketbot channels status 显示频道状态(暂未实现,请使用 WebUI/REST API)。
pocketbot plugins list 列出内置插件。
pocketbot provider login <名称> 提供商登录(暂未实现,请在 config.json 中配置 API Key)。
pocketbot provider logout <名称> 提供商登出(暂未实现)。

聊天内命令(pocketbot agent 交互模式中)

命令 描述
/new 开始新对话(清空会话)
/status 显示模型、会话信息、消息计数
/model 显示当前模型预设
/model <预设> 切换到其他模型预设
/history [N] 显示最近 N 条消息(默认 10)
/stop 取消当前工作(CLI 中暂未实现)
/help 打印命令参考
exit 退出交互模式

CLI 示例

# 引导式初始化
python pocketbot onboard --wizard

# 单次提问
python pocketbot agent -m "北京天气怎么样?"

# 交互式聊天
python pocketbot agent

# 恢复之前的会话
python pocketbot agent -s sess_abc123

# 检查系统状态
python pocketbot status

# 启动 API 服务器
python pocketbot gateway --port 8765

📖 使用指南

聊天

  1. 点击新建聊天或按 ⌘/
  2. 输入消息并按 Enter(或 ⌘Enter
  3. Agent 流式返回响应,按需调用工具
  4. 悬停消息可看到复制编辑重新生成TTS点赞/踩

记忆

  • 通过记忆面板添加,或让 agent "记住..."
  • FTS5 全文搜索
  • 导入导出 JSON

目标

  • 创建目标(标题 + 描述)
  • 手动添加步骤或点击用 AI 分解进行 LLM 拆解
  • 勾选步骤跟踪进度(自动计算百分比)

自动化

  • 创建基于 cron 的自动化(5 字段 UTC cron 或 "every N seconds")
  • 开关切换启用/禁用

文件

  • 浏览沙盒工作区
  • 上传文件(拖拽或按钮)
  • 搜索文件内容(全文搜索)
  • 最近查看文件快速访问芯片

命令面板(⌘P)

  • 快速导航到任何面板
  • 新建聊天、导出、切换主题
  • 打开任意最近会话

设置

  • 统计仪表盘 — 会话、消息、工具调用、记忆、目标、自动化、反馈
  • 备份恢复 — 完整数据导出/导入(JSON)
  • 危险区域 — 清除会话/记忆/目标/自动化(带确认)
  • 暗色模式切换

键盘快捷键

快捷键 功能
⌘P / Ctrl+P 打开命令面板
⌘K / Ctrl+K 聚焦会话搜索
⌘/ / Ctrl+/ 新建聊天
⌘Enter / Ctrl+Enter 发送消息

语音

  • 点击聊天输入框的麦克风图标录音
  • 音频通过 ASR 转录并添加到输入框
  • 点击助手消息的朗读按钮进行 TTS 播放

🔌 API 参考

REST API(基础路径:/api/pb

会话

方法 路径 描述
GET /api/sessions 列出所有会话
POST /api/sessions 创建会话
GET /api/sessions/{sid} 获取会话 + 消息
PATCH /api/sessions/{sid} 重命名 / 置顶
DELETE /api/sessions/{sid} 删除会话
GET /api/sessions/{sid}/export 导出为 markdown/JSON
GET /api/sessions/{sid}/stats 会话统计

聊天

方法 路径 描述
POST /api/chat SSE 流式聊天
WS /ws/chat WebSocket 聊天

记忆 / 目标 / 自动化 / 文件 / 工具 / 系统

(与英文版结构一致,路径相同)

SSE 事件类型

{"type": "token", "content": "..."}        // 流式文本
{"type": "tool_call", "name": "...", "args": {...}}
{"type": "tool_result", "name": "...", "result": {...}}
{"type": "final", "content": "...", "session_id": "..."}
{"type": "error", "message": "..."}

🎨 设计

  • 配色方案: 翡翠青色主色(无靛蓝/蓝色)
  • 主题: 明暗模式(next-themes)
  • 字体: Geist Sans + Geist Mono
  • 组件: shadcn/ui (New York 风格)
  • 图标: Lucide React
  • 响应式: 移动优先,粘性页脚,触控友好

🔒 安全

  • 工作区锁定: 所有文件操作限制在工作区目录内
  • Shell 黑名单: 阻止破坏性命令(如 rm -rf /
  • Shell 超时: 命令限时(默认 30 秒)
  • 沙盒执行: Agent 工具在受控环境中运行

📊 数据存储

所有数据存储在 SQLite(data/pocketbot.db):

用途
sessions 聊天会话(标题、置顶状态)
messages 所有消息(用户、助手、工具)含 tool_calls
memory 长期记忆(FTS5 搜索)
memory_fts FTS5 虚拟表
goals 目标(步骤、进度、状态)
automations 定时自动化(cron 表达式)
audit_log 审计日志(自动化触发、反馈、上传等)

🔄 备份恢复

完整备份

curl http://localhost:81/api/pb/api/backup -o backup.json

恢复

curl -X POST http://localhost:81/api/pb/api/restore \
  -H "Content-Type: application/json" \
  -d @backup.json

通过 UI

进入 设置 → 备份恢复 → "创建备份" / "从文件恢复"。


📝 许可证

Apache2.0 许可证。


🙏 致谢


🐈 pocketbot — 轻量本地自动化智能体

About

PocketBot 是基于 LangGraph 原生 ReAct 流程构建、可私有化部署的长期运行AI智能体。PocketBot is a long-running AI agent that is built on LangGraph’s native ReAct framework and can be deployed privately.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Packages

Contributors

Languages