xiaoxixi 9ac898acbb 扩充定时任务功能、实现类似其他agent软件的heartbeat功能

2026-07-15 16:36:10 +08:00

15 KiB

Raw Blame History

PicoBot

PicoBot 是一个用 Rust 编写的个人 AI 助手运行时。它在本地启动 Gateway，接入 CLI TUI、飞书/Lark 等聊天渠道，把会话、消息、记忆和定时任务持久化到 SQLite，并为 Agent 提供文件、Shell、HTTP、Web、MCP、Skill、记忆、浏览器和子 Agent 等工具能力。

它更像一个可扩展的“个人助手操作系统”：渠道负责收发消息，SessionManager 负责会话和上下文，AgentLoop 负责模型与工具循环，Storage 负责可靠落盘。

完整的组件边界、并发不变量、启动/关停顺序和扩展指南见架构文档。

适合做什么

在终端里和本地 AI 助手持续对话。
在浏览器中聊天，并查看日志、任务和记忆，修改运行配置与助手档案。
将同一套 Agent 能力接入飞书/Lark。
让 Agent 使用本地文件、Shell、搜索、HTTP、浏览器、MCP 工具完成任务。
把长期偏好、事实和历史摘要存成可检索记忆。
用 Cron 定时执行任务，并把结果发回目标渠道。
通过 Skills 为 Agent 注入项目知识和专用操作指南。

快速开始

1. 准备环境

需要：

Rust toolchain，项目使用 edition 2024。
一个可用的 LLM Provider API Key。

2. 构建项目

cargo build

3. 准备配置

PicoBot 按以下顺序加载配置：

~/.picobot/config.json
当前目录 ./config.json

Gateway 首次启动时会把模板释放到 ~/.picobot/config.example.json。模板源文件在 resources/templates/config.example.json。

最小配置示例：

{
  "providers": {
    "openai": {
      "type": "openai",
      "base_url": "https://api.openai.com/v1",
      "api_key": "<OPENAI_API_KEY>",
      "extra_headers": {}
    }
  },
  "models": {
    "gpt-4o": {
      "model_id": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 4096,
      "input_type": ["text", "image"]
    }
  },
  "agents": {
    "default": {
      "provider": "openai",
      "model": "gpt-4o",
      "max_tool_iterations": 99,
      "token_limit": 128000
    }
  },
  "workspace_dir": "~/.picobot/workspace"
}

.env 会由 PicoBot 自己解析。配置里的 <OPENAI_API_KEY> 这类占位符会在 .env 和系统环境变量加载后替换。

4. 启动 Gateway

cargo run -- gateway

默认监听 127.0.0.1:19876。Gateway 启动后会把进程工作目录切到 workspace_dir，默认 SQLite 数据库也会写到该 workspace 下的 picobot.db。

5. 启动 CLI 客户端

另开一个终端：

cargo run -- chat

CLI 默认连接 ws://127.0.0.1:19876/ws。如需指定地址，可使用 --gateway-url。

5.1 使用 WebUI

Gateway 启动后直接打开：

http://127.0.0.1:19876/

WebUI 随二进制嵌入，不需要 Node.js、npm 或单独部署静态文件，提供：

在线聊天、会话创建/切换、历史回放，以及基于 Gateway 实时命令清单的 / 斜杠命令补全。
Cron 定时任务、最近运行记录和后台子任务状态。
Knowledge/Timeline 记忆的分类与全文检索。
本地滚动日志的尾部查看、过滤和自动刷新。
config.json、~/.picobot/USER.md、~/.picobot/AGENTS.md 编辑。

配置接口会掩码 API Key、secret、password 和 token；保留 ******** 再保存不会覆盖原密钥。运行配置采用原子写入并在 Gateway 重启后生效，USER.md 和 AGENTS.md 则会用于后续构建的 Agent 上下文。

WebUI 当前与 Gateway 使用同一信任边界，不额外提供登录认证。默认只监听 127.0.0.1；如果通过 --host 0.0.0.0、反向代理或端口转发暴露 Gateway，必须在外层配置 TLS 和访问认证，否则聊天及管理 API 会对网络访问者开放。

WebUI 开发

WebUI 源码位于 webui/，使用 Svelte 5、Vite 和无样式的 Bits UI 可访问组件原语。运行发布版 PicoBot 不需要 Node.js；从源码编译或修改前端时需要 Node.js 20+：

cd webui
npm ci
npm run check
npm run build

直接运行 npm run build 会在被忽略的 webui/dist/ 生成独立检查产物。正常执行 cargo build 时，build.rs 会监听前端源码和构建配置，只有它们发生变化时才调用 Vite，将生产资源生成到 Cargo OUT_DIR 并嵌入二进制；node_modules 缺失或 package-lock.json 变化时会先自动运行 npm ci。前端产物不提交到仓库。

6. 作为 systemd 用户服务运行（Linux）

安装会把当前 PicoBot 可执行文件注册为 picobot.service 并设置为登录后自动启动；安装本身不会立即启动 Gateway：

picobot service install
picobot service start

服务管理命令：

picobot service status
picobot service restart
picobot service stop
picobot service uninstall

unit 位于 ~/.config/systemd/user/picobot.service，以执行 service install 时的当前目录作为初始工作目录。服务异常退出时由 systemd 自动重启；stop 和 restart 会通过 SIGTERM 触发 Gateway 的有界优雅关停。

TUI 会把一个随机客户端标识保存到 ~/.picobot/tui_client_id，因此关闭并重新打开客户端后会恢复同一组 dialog 和最近使用的会话。界面支持历史回放、会话列表与归档筛选、命令补全、Unicode/中文编辑、括号粘贴和多行输入。

常用快捷键：

快捷键	操作
`F1` / `Ctrl+H`	打开帮助
`Tab` / `Ctrl+S`	切换焦点 / 聚焦会话列表
`Ctrl+N`	新建会话
`Ctrl+R` / `Ctrl+A` / `Ctrl+D`	重命名 / 归档 / 删除所选会话
`Ctrl+L` / `Ctrl+O`	清空历史 / 显示归档会话
`Enter` / `Shift+Enter`	发送 / 换行
`PageUp` / `PageDown`	滚动对话历史
连按两次 `Ctrl+C`	退出客户端

运行时数据流

用户消息进入 PicoBot 后，会被转换为统一的 inbound message，经由 MessageBus 交给 SessionManager。SessionManager 选择当前 dialog、组装上下文、调用 AgentLoop；AgentLoop 调用模型和工具，最终响应通过 outbound bus 回到原渠道。

详细时序和失败语义见架构文档：消息与控制数据流。

同一 session 的普通消息由专属有界队列串行处理，不同 session 可以并发；出站消息按 (channel, chat_id) 分 lane 保序，慢渠道不会阻塞其他目标。Gateway 的长生命周期任务统一由 TaskSupervisor 取消和限时回收。

核心边界：

模块	职责
`channels`	接入外部渠道，只做收发，不直接处理会话或 LLM
`bus`	异步消息队列，承载 inbound、outbound、control 三类消息
`session`	管理会话生命周期、dialog 操作、上下文、记忆召回、压缩和持久化
`agent`	执行无状态 LLM/tool 循环，处理模型响应和工具调用
`providers`	OpenAI 兼容接口和 Anthropic Messages API 客户端
`tools`	Agent 可调用工具集合
`storage`	SQLite schema、CRUD、消息和任务持久化
`scheduler`	领取定时任务，执行普通/巡检 Agent，并按投递策略记录或发送结果
`skills`	加载 Skill，并把 Skill 指南注入系统提示
`mcp`	连接 MCP Server，将远端工具包装成普通 Tool
`task_supervisor`	统一管理 Gateway 后台任务的取消和有界关停

核心能力

渠道

渠道	说明
`cli_chat`	Ratatui 终端客户端，通过 WebSocket 连接 Gateway
`feishu`	飞书/Lark 消息、反应、文件上传下载和媒体引用

会话

Session ID 使用三段式：

<channel>:<chat_id>:<dialog_id>

同一个 channel:chat_id 下可以有多个 dialog。当前支持的 dialog 操作包括创建、列表、切换、重命名、归档、删除、清空历史、压缩、导出、查看信息和停止任务。

常用 slash commands：

命令	说明
`/new`	创建新 dialog
`/sessions`	列出最近 dialog
`/switch <dialog_id>`	切换 dialog
`/rename <title>`	重命名当前 dialog
`/delete`	删除当前 dialog 并创建新 dialog
`/compact`	手动压缩上下文
`/info`	查看当前 dialog 信息
`/dump`	导出当前 dialog 为 Markdown
`/mcp`	查看 MCP 服务器和工具状态
`/stop`	停止当前任务并清空队列
`/?`, `/help`	查看帮助

记忆

PicoBot 有两类记忆：

类型	用途	生命周期
Knowledge	偏好、事实、项目规则、长期可复用信息	长期保留，手动删除
Timeline	长对话压缩后的历史摘要	默认保留 90 天

每轮处理用户消息时，MemoryManager 会按用户输入召回 Knowledge，并作为运行时上下文附加到本轮用户消息。当前召回上限固定为 5；memory.recall_limit 已支持解析但尚未接入 worker。上下文压缩产生的摘要会保存为 Timeline，后续可通过 timeline_recall 工具检索。Scheduler 默认创建一个每日维护巡检，按 memory.timeline_retention_days 清理过期 Timeline；Knowledge 不会被自动删除。

工具

基础工具集：

工具	说明
`calculator`	数学表达式和统计计算
`file_read` / `file_write` / `file_edit`	文件读写和编辑
`file_search` / `content_search`	文件名和内容搜索
`bash`	在 workspace 中执行 Shell 命令
`http_request` / `web_fetch`	HTTP 请求和网页文本抽取
`get_skill`	列出或读取本地 Skill
`memory_store` / `memory_recall` / `timeline_recall` / `memory_forget`	长期记忆操作
`delegate`	启动 inline、background 或 parallel 子 Agent
`send_message`	向指定渠道发送消息
`chat_manager`	查看渠道、会话和历史消息
`cron_add/list/remove/enable/disable/update`	管理定时任务
`routine_maintenance`	安全清理超过保留期的 Timeline，不删除 Knowledge
`browser`	可选 WebDriver 浏览器自动化
MCP tools	从配置的 MCP Server 动态发现并注册

Skills

Skill 是包含 SKILL.md 的目录。加载优先级从高到低：

{workspace}/skills
~/.picobot/skills
~/.agents/skills

同名 Skill 会按高优先级覆盖低优先级。内置 Skill 位于 resources/skills，首次运行时会安装到 ~/.picobot/skills。

配置速查

顶层配置字段：

字段	说明
`providers`	LLM Provider 配置
`models`	模型参数与输入能力
`agents`	Agent 使用哪个 provider/model
`gateway`	HTTP/WebSocket、数据库、调度器、后台任务限制
`client`	CLI 客户端默认 Gateway URL
`channels`	渠道配置，目前主要是飞书/Lark
`memory`	记忆召回、归并和 Timeline 保留策略
`mcp`	MCP Server 配置
`browser`	可选浏览器自动化配置
`workspace_dir`	文件工具、Shell、数据库和 workspace skills 的工作目录

重要默认值：

配置	默认值
`gateway.host`	`127.0.0.1`
`gateway.port`	`19876`
`gateway.max_concurrent_background_tasks`	`10`
`gateway.scheduler.enabled`	`true`
`client.gateway_url`	`ws://127.0.0.1:19876/ws`
`memory.recall_limit`	`5`（当前运行时固定为 5）
`memory.timeline_retention_days`	`90`
`mcp.tool_timeout_secs`	`180`
`browser.enabled`	`false`

更完整的配置字段说明见 resources/skills/about-picobot/references/config.md。

WebSocket API

Gateway 暴露：

Method	Path	说明
`GET`	`/health`	健康检查和版本信息
`GET`	`/ws`	WebSocket 聊天协议

Inbound 消息类型：

Type	主要字段
`user_input`	`content`，可选 `channel`、`chat_id`、`sender_id`
`clear_history`	可选 `chat_id`、`session_id`
`create_session`	可选 `title`
`list_sessions`	`include_archived`
`load_session`	`session_id`
`get_session_history`	`session_id`，可选 `limit`（服务端限制为 1–2000）
`rename_session`	可选 `session_id`，`title`
`archive_session`	可选 `session_id`
`delete_session`	可选 `session_id`
`get_slash_commands`	无
`ping`	无

Outbound 消息类型包括 assistant_response、error、session_established、session_created、session_list、session_loaded、session_history、session_renamed、session_archived、session_deleted、history_cleared、slash_commands_list、pong、command_executed 和 system_notification。其中异步 assistant_response / system_notification 可携带 session_id，客户端应避免把迟到结果显示到其他 dialog。

测试

# 单元测试
cargo test --lib

# 离线集成/协议测试
cargo test --test test_scheduler
cargo test --test test_request_format

# 模型 API 集成测试需要 tests/test.env 中有真实 API key
cp tests/test.env.example tests/test.env
cargo test --test test_integration -- --ignored
cargo test --test test_tool_calling -- --ignored

会真实调用模型 API 的测试标记为 #[ignore]；离线集成测试默认执行。

项目结构

src/
  agent/          LLM loop、上下文压缩、系统提示、媒体处理、子 Agent
  bus/            inbound、outbound、control 消息队列
  channels/       CLI chat 和飞书/Lark 集成
  client/         Ratatui 终端 UI
  config/         配置加载、环境变量替换、路径展开
  gateway/        Axum HTTP/WebSocket server 和 GatewayState 装配
  mcp/            MCP 客户端连接和工具包装
  memory/         记忆管理和记忆类型
  observability/  Agent/tool telemetry observer
  providers/      OpenAI 兼容和 Anthropic provider
  scheduler/      定时任务运行时
  session/        会话生命周期、dialog 命令、持久化集成
  skills/         Skill 加载和内置 Skill 安装
  storage/        SQLite schema 和 CRUD
  tools/          Agent 工具实现
  task_supervisor.rs  Gateway 后台任务的生命周期管理
resources/
  skills/         构建时嵌入的内置 Skills
  templates/      首次运行释放的配置和用户模板
tests/            单元测试和 ignored 集成测试
docs/             面向维护者和 Agent 的架构与开发文档

关键依赖

Crate	用途
`axum`, `tokio`, `tokio-tungstenite`	Gateway 和 WebSocket runtime
`sqlx`	SQLite 持久化
`reqwest`	LLM 和 HTTP 客户端
`ratatui`, `crossterm`, `termimad`	终端 UI
`rmcp`	MCP 客户端
`fantoccini`	可选浏览器自动化
`cron`, `chrono-tz`	定时任务
`jieba-rs`	中文记忆检索分词
`zstd`, `tar`	内置 Skill 打包和释放

15 KiB Raw Blame History Unescape Escape