PocketBot 是基于 LangGraph 原生 ReAct 流程构建、可私有化部署的长期运行AI智能体。
不同于仅能即时应答的对话机器人,PocketBot 主打持久任务执行、目标自动拆解、定时本地自动化,内置长期记忆、系统工具集,运行环境一体化无额外依赖。
项目在保证智能体内核精简易读、易于二次修改的前提下,提供一套完整可用的自动化能力。
- ReAct 循环:基于 langgraph
StateGraph(agent 节点 + ToolNode + 条件边) - 23 个内置工具:覆盖 9 个类别(文件、Shell、Web、记忆、目标、自动化、媒体、子agent、工具)
- 流式输出:SSE 逐 token 响应 + 工具调用事件
- 长期记忆:SQLite FTS5 全文搜索(Dream 风格)
- 目标分解:LLM 驱动的目标拆解为步骤
- 定时自动化:基于 APScheduler(cron + 固定间隔)
- OpenAI 兼容 API:供集成使用
- WebSocket 实时聊天端点
- 聊天 — 流式响应、工具调用卡片、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) │
│ • 目标 │
│ • 自动化 │
│ • 审计日志 │
└─────────────────┘
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 │
└─────────────────┘
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 流式
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_search、page_reader、image 图像生成) |
| 语音 | 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 路由的反向代理) |
| 类别 | 工具 | 描述 |
|---|---|---|
| 文件 | 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 命令代替 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 服务器以扩展 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
cd mini-services/pocketbot-agent
pip install langgraph langchain langchain-openai langchain-community \
fastapi uvicorn httpx apscheduler pydantic openaicd mini-services/pocketbot-agent
# 交互式向导 — 选择你的 LLM 提供商(DeepSeek、OpenAI、Anthropic 等)
python pocketbot onboard --wizard
# 或使用默认配置(Z-AI glm-4-plus)
python pocketbot onboard向导会引导你:
- 选择提供商:DeepSeek、OpenAI、Anthropic、OpenRouter、Ollama、Z-AI 或自定义
- 输入 API Key(Ollama 不需要)
- 确认 API 地址(已预填提供商默认值)
- 选择模型(如
deepseek-v4-flash、gpt-4o、claude-sonnet-4) - 设置温度和最大 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
# 单次消息
python pocketbot agent -m "现在几点了?"
# 交互模式(输入 exit 或 Ctrl+C 退出)
python pocketbot agent
# 检查状态
python pocketbot status| 提供商 | 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.json 在 modelPresets 下添加条目。
# 从项目根目录
安装: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在浏览器中打开 http://localhost:81(通过 Caddy 网关)。
注意: Next.js 代理路由(
/api/pb/*)会自动启动并管理 Python 后端为子进程,所以只需启动前端 — 后端按需启动。
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 <名称> |
提供商登出(暂未实现)。 |
| 命令 | 描述 |
|---|---|
/new |
开始新对话(清空会话) |
/status |
显示模型、会话信息、消息计数 |
/model |
显示当前模型预设 |
/model <预设> |
切换到其他模型预设 |
/history [N] |
显示最近 N 条消息(默认 10) |
/stop |
取消当前工作(CLI 中暂未实现) |
/help |
打印命令参考 |
exit |
退出交互模式 |
# 引导式初始化
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- 点击新建聊天或按 ⌘/
- 输入消息并按 Enter(或 ⌘Enter)
- Agent 流式返回响应,按需调用工具
- 悬停消息可看到复制、编辑、重新生成、TTS、点赞/踩
- 通过记忆面板添加,或让 agent "记住..."
- FTS5 全文搜索
- 导入导出 JSON
- 创建目标(标题 + 描述)
- 手动添加步骤或点击用 AI 分解进行 LLM 拆解
- 勾选步骤跟踪进度(自动计算百分比)
- 创建基于 cron 的自动化(5 字段 UTC cron 或 "every N seconds")
- 开关切换启用/禁用
- 浏览沙盒工作区
- 上传文件(拖拽或按钮)
- 搜索文件内容(全文搜索)
- 最近查看文件快速访问芯片
- 快速导航到任何面板
- 新建聊天、导出、切换主题
- 打开任意最近会话
- 统计仪表盘 — 会话、消息、工具调用、记忆、目标、自动化、反馈
- 备份恢复 — 完整数据导出/导入(JSON)
- 危险区域 — 清除会话/记忆/目标/自动化(带确认)
- 暗色模式切换
| 快捷键 | 功能 |
|---|---|
⌘P / Ctrl+P |
打开命令面板 |
⌘K / Ctrl+K |
聚焦会话搜索 |
⌘/ / Ctrl+/ |
新建聊天 |
⌘Enter / Ctrl+Enter |
发送消息 |
- 点击聊天输入框的麦克风图标录音
- 音频通过 ASR 转录并添加到输入框
- 点击助手消息的朗读按钮进行 TTS 播放
| 方法 | 路径 | 描述 |
|---|---|---|
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 聊天 |
(与英文版结构一致,路径相同)
{"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.jsoncurl -X POST http://localhost:81/api/pb/api/restore \
-H "Content-Type: application/json" \
-d @backup.json进入 设置 → 备份恢复 → "创建备份" / "从文件恢复"。
Apache2.0 许可证。
🐈 pocketbot — 轻量本地自动化智能体




