# PicoBot PicoBot 是一个用 Rust 构建的多通道 Agent 网关。它把消息接入、LLM 调用、工具执行、会话持久化、长期记忆、技能系统和计划任务整合到同一个运行时里，适合做本地 Agent、团队机器人或带长期上下文的自动化助手。 当前代码库已经实现以下核心能力： - 基于 Gateway 的统一消息入口，支持 WebSocket CLI 与飞书通道 - 面向工具调用的 Agent 循环，支持多轮 tool calling - SQLite 持久化会话、消息、长期记忆、技能事件和调度任务 - 基于用户维度的长期记忆检索与写入机制 - 基于 SKILL.md 的项目级 / 用户级技能加载与运行时管理 - 定时任务系统，支持延迟、周期、绝对时间和 cron 调度 - 超长上下文压缩与历史摘要 - 持久化 Agent 配置文件注入与周期性重注入 ## 1. 项目定位 PicoBot 的设计目标不是“只会聊天”的单进程 Bot，而是一个可持续运行的 Agent 基础设施： - 消息从不同渠道进入统一总线 - SessionManager 负责会话路由、上下文恢复、工具执行和回复生成 - SQLite 作为事实来源保存跨重启状态 - Agent 在每轮推理时可以读取文件、执行命令、发 HTTP 请求、读写记忆、管理技能和调度任务 如果你需要一个“带长期记忆、可调用工具、可接入飞书、可计划执行任务”的机器人，这个项目的实现面基本够用。 ## 2. 核心架构 整体链路可以概括为： 1. Channel 接收外部消息 2. MessageBus 将消息送入统一的 inbound 队列 3. Gateway 启动的 inbound processor 调用 SessionManager 处理消息 4. SessionManager 加载持久化历史、注入系统提示、运行 AgentLoop、执行工具调用 5. 生成的 assistant / tool / system 消息写入 SQLite 6. OutboundDispatcher 将结果投递到目标通道 主要模块如下： - src/gateway：网关入口、HTTP 健康检查、WebSocket 服务、Session 管理 - src/bus：消息总线与消息结构定义 - src/agent：AgentLoop 与上下文压缩器 - src/providers：不同 LLM Provider 的统一抽象，当前支持 openai 和 anthropic - src/tools：内置工具集合 - src/storage：SQLite 持久化实现 - src/channels：渠道适配层，当前已有飞书通道 - src/scheduler：数据库驱动的计划任务调度器 - src/skills：技能发现、加载与运行时管理 - src/client / src/cli：本地 CLI 客户端和交互命令 ## 3. 消息机制 PicoBot 的消息不是简单的“用户文本 + 助手文本”，而是完整的会话事件流。 ### 3.1 消息类型 系统中的 ChatMessage 至少包含以下角色： - user：用户输入 - assistant：模型回复 - system：系统提示、Agent Prompt、调度附加提示、历史压缩摘要 - tool：工具执行结果 此外，assistant 消息还能携带： - tool_calls：本轮准备调用哪些工具 - reasoning_content：模型的补充推理文本 用户消息也支持附带媒体引用，当前消息结构中已经支持文本与图片 URL 形式的多模态块，以及本地媒体文件路径引用。 ### 3.2 消息总线 MessageBus 维护两条异步队列： - inbound：Channel -> Agent - outbound：Agent -> Dispatcher -> Channel 这样做的好处是： - 渠道接入和 Agent 执行解耦 - 可在网关内部统一处理重试、记录、路由和扩展 - 后续增加新渠道时不需要改动核心 Agent 流程 ### 3.3 工具调用消息流 当模型发起工具调用时，PicoBot 会按顺序保存： 1. 一条 assistant 消息，记录 tool_calls 2. 一条或多条 tool 消息，记录每个工具返回结果 3. 最终 assistant 汇总回复 这意味着即使进程重启，系统仍然可以恢复： - 当时模型调用了什么工具 - 工具入参和返回结果是什么 - 最终结论如何形成 ## 4. 会话与上下文机制 ### 4.1 会话标识 PicoBot 为不同渠道统一维护持久化会话： - CLI：session_id 等于 chat_id - 非 CLI 渠道：session_id = channel_name:chat_id 这样可以让： - CLI 显式创建、切换和管理多个会话 - 飞书等渠道把同一个 chat 稳定映射到同一条持久化会话 ### 4.2 Agent Prompt 注入 PicoBot 会在 ~/.picobot/agent/AGENT.md 维护一份持久化 Agent 画像文件。 行为规则： - 如果目录不存在会自动创建 - 如果文件不存在会自动写入默认内容 - 当前活动对话为空或刚 reset 时，会先把 AGENT.md 作为第一条 system 消息注入 - 每经过指定数量的 user 轮次，会在下一条用户消息进入前重新注入最新 AGENT.md 相关配置： - gateway.agent_prompt_reinject_every：默认 100 - 设为 0 可关闭周期性重注入 ### 4.3 上下文压缩 上下文压缩不是在每次请求前同步执行，而是在一轮消息处理完成、assistant / tool 消息已经按真实顺序落库之后，再异步安排后台压缩任务。这样可以先保证当前回复链路完成，再处理历史瘦身。 完整机制如下： 1. 系统先对当前活动历史做一个近似 token 估算。 估算规则不是调用 tokenizer，而是按“约每 4 个字符约等于 1 token，并再乘以 1.2 安全系数”计算。 2. 当估算结果超过模型上下文窗口的 50% 时，压缩器才认为“需要压缩”。 这里的上下文窗口来自 agent 对应模型配置里的 token_limit。 3. 即使超过阈值，如果当前历史里的 user turn 数量不超过保留阈值，也不会压缩。 当前默认会完整保留最近 3 个 user turn。 4. 一旦满足条件，压缩器会先按 user 消息切分 turn，再确定“旧历史”和“最近保留段”的分界点。 5. 在旧历史里，不是所有 system 消息都会被折叠： 带有 agent_prompt 和 scheduled_system_prompt 标记的 system 消息会被原样保留，避免丢失 Agent 基本设定和调度任务附加约束。 6. 除这些必须保留的 system 消息外，分界点之前的其余消息会被整理成一段待摘要 transcript。 transcript 会保留角色信息；tool 消息还会带上工具名，方便摘要时保留关键操作和结果。 7. 如果 transcript 本身已经过长，会先按 context_summary_max_chars 截断，再交给模型总结。 8. 摘要调用和主对话使用同一个 provider，提示词明确要求保留： 用户请求、关键标识符、文件路径、URL、工具调用、命令、结果、错误、决策、偏好和当前任务状态。 如果摘要调用失败，会退化为直接截断 transcript，而不会中断主流程。 9. 摘要结果会被包装成一条新的 system 消息，并打上 SYSTEM_CONTEXT_HISTORY_COMPACTION 标记，内容前缀为 [Compressed History]。 10. 后台提交阶段不会直接修改旧消息，而是向消息表尾部追加一段“新的活动段”： 依次写入保留的关键 system 消息、压缩摘要消息、最近保留的消息，以及在压缩快照之后新产生的 delta 消息。 11. 提交成功后，sessions.reset_cutoff_seq 会被推进到压缩前的最大 seq。 这样旧消息仍然留在数据库里用于审计或全量导出，但默认恢复到运行时上下文时，只会加载新的活动段。 12. 为避免并发覆盖，压缩提交前会检查快照是否过期： 如果 reset_cutoff_seq 已变化，或者压缩期间又有更新导致快照不再匹配，本次压缩会跳过，不会覆盖较新的上下文。 13. 压缩提交成功后，Session 会重新加载当前 chat 的活动历史，后续轮次看到的就是“关键 system 消息 + 压缩摘要 + 最近若干完整 turn”的新上下文。 这套机制的目标不是简单删历史，而是把“远端历史变成可恢复摘要”，同时保证： - Agent Prompt 和调度提示不丢 - 最近对话细节仍然完整 - 工具调用形成的重要事实被保留下来 - 数据库里仍有完整原始消息流水 ## 5. 持久化与存储机制 PicoBot 目前使用 SQLite 作为主要持久化后端，默认数据库路径为： - ~/.picobot/storage/sessions.db 数据库会保存以下核心实体： - sessions：会话元数据 - messages：消息流水 - memories：长期记忆 - skill_events：技能发现与使用事件 - scheduler_jobs：计划任务定义与运行状态 设计原则是： - 内存对象负责运行时性能与临时状态 - SQLite 负责跨重启、跨进程恢复 详细表结构和持久化说明可参考 docs/PERSISTENCE.md。 ## 6. 长期记忆机制 长期记忆是 PicoBot 和普通聊天机器人最不一样的部分之一。 ### 6.1 记忆存储模型 每条记忆至少包含这些维度： - scope_kind：当前实现为 user - scope_key：由 channel_name:sender_id 组成 - namespace：记忆命名空间，例如 profile、preferences、tasks - memory_key：命名空间内的键 - content：记忆正文 - source_session_id / source_message_id / source_message_seq：来源追踪信息 这意味着记忆默认按“渠道中的某个用户”隔离，而不是按单个 chat 隔离。 ### 6.2 记忆读取与写入工具 内置了两类记忆工具： - memory_search：只读检索，支持 search / get / list - memory_manage：写操作，支持 put / update / delete 推荐模式是： 1. 先用 memory_search 回忆用户长期信息 2. 只在确实识别到高价值长期信息时，再用 memory_manage 写入或更新 ### 6.3 记忆机制的时机 长期记忆不会像会话历史那样在每轮请求开始时自动拼进上下文；它的使用时机是显式、按需、分阶段发生的。 完整时序如下： 1. 用户新消息到达后，系统先恢复当前 chat 的活动历史、system 消息和 Agent Prompt。 这一步恢复的是会话上下文，不会自动把 memories 表里的所有长期记忆直接注入本轮请求。 2. AgentLoop 开始推理后，如果模型判断当前问题依赖用户历史，例如语言偏好、长期任务、身份事实、历史决策或稳定工作方式，就应主动调用 memory_search。 因此“读记忆”的时机通常发生在本轮推理前段或中段，而不是网关层强制预加载。 3. memory_search 的作用域不是当前 chat，而是当前 channel_name:sender_id 对应的用户范围。 这意味着同一个用户在同一渠道下的不同 chat，可以共享长期记忆。 4. 当模型已经确认某条信息值得跨会话保留时，才调用 memory_manage。 因此“写记忆”的时机通常发生在本轮推理中后段：先理解当前问题，再决定是否沉淀为长期记忆。 5. memory_manage 写入时会记录当前工具上下文中的 session_id、message_id、message_seq、channel_name 和 chat_id。 所以一旦写入成功，这条记忆会立刻持久化到 SQLite，并能追溯来源。 6. 已写入的记忆不会自动回流到“当前这一轮”已经构建好的提示上下文。 它主要影响后续轮次中模型再次调用 memory_search 的结果，以及后续记忆维护后生成的托管摘要。 可以把两类上下文区分为： - 会话历史：默认参与当前 chat 的直接推理 - 长期记忆：只有模型主动检索时才进入推理过程 ### 6.4 记忆维护机制 PicoBot 不只是“把记忆存进去”，还内置了记忆整理逻辑。 系统会把长期记忆粗分为几类： - 用户事实 - 偏好 - 行为模式 - 其他信息 随后通过记忆维护流程： - 去重低价值记忆 - 合并重复或可归并的记忆项 - 识别冲突信息 - 生成一份受控的“用户记忆摘要” Markdown 维护时机和生效方式是： 1. SessionManager 会先按 scope_key 取出该用户范围下的全部长期记忆。 2. 然后把候选记忆整理成结构化计划，交给模型做归纳和裁剪。 3. 模型输出会包含用户事实、偏好、行为模式、需要合并的条目、低价值条目，以及一份 managed_markdown 摘要。 4. 系统据此回写 memories 表： 合并项会重新 put_memory，低价值项会 delete_memory，自动整理产生的记录会标记 source_type = memory_maintenance。 5. 所有 scope 的 managed_markdown 会再被合并，并写入 ~/.picobot/agent/AGENT.md 的托管记忆区块。 这意味着记忆维护不是为了立刻改变当前一轮回复，而是为了影响后续新对话、后续 reset 后的新活动段，以及未来每次重新注入的 Agent Prompt。 ### 6.5 定时记忆维护 Scheduler 默认内置一个任务： - builtin.memory_maintenance_daily - 每天本地时间 03:00 运行 这个任务以 internal_event 的方式触发 memory_maintenance 事件。触发后，系统会遍历所有已有用户 scope，逐个执行记忆维护，并在全部处理完成后统一更新 AGENT.md 中的“用户记忆摘要”托管区块。 ## 7. 技能机制 PicoBot 支持基于文件系统的技能系统，用来给 Agent 注入某一类任务的专门说明。 ### 7.1 技能发现位置 - 项目级技能：.picobot/skills/*/SKILL.md - 用户级技能：~/.picobot/skills/*/SKILL.md ### 7.2 最小 SKILL.md 格式 ```md --- description: 用于总结 Rust 项目架构 --- 这里写详细说明。 ``` 约束： - frontmatter 中必须有 description - name 可省略，省略时使用目录名 - 非法技能文件会被跳过，并记录 warning 日志 ### 7.3 技能注入方式 运行时会发生两件事： - AgentLoop 动态注入“技能索引”系统提示，列出当前可用技能的名称和描述 - 模型可以通过工具读取具体技能内容并按技能说明执行任务 ### 7.4 技能管理工具 内置工具： - skill_list：只读列出技能 - skill_manage：运行时创建、更新、删除、读取和重载技能 skill_manage 支持的 action： - list - get - create - update - delete - reload skills 配置示例： ```json { "skills": { "enabled": true, "sources": ["project", "user"], "max_index_chars": 4000, "max_listed_skills": 32 } } ``` ## 8. 工具机制 PicoBot 的 Agent 是围绕工具调用构建的。当前默认注册的工具包括： - calculator：简单数学计算 - file_read：读取文件 - file_write：写文件 - file_edit：编辑文件 - memory_search：读取长期记忆 - memory_manage：写入 / 更新 / 删除长期记忆 - scheduler_manage：管理调度任务 - skill_list：列出技能 - skill_manage：管理技能 - bash：执行 shell 命令 - http_request：发起 HTTP 请求 - web_fetch：抓取网页正文 其中： - 文件工具适合做代码库和文档操作 - 记忆工具适合维持长期用户画像 - scheduler_manage 允许 Agent 自主创建后续计划任务 - bash / http_request / web_fetch 让 Agent 具备更强的外部交互能力 ## 9. 调度器机制 PicoBot 带有一个基于 SQLite 的调度器，而不是纯内存或 JSON 文件驱动的任务系统。 ### 9.1 支持的调度类型 - delay：延迟执行一次 - interval：固定间隔执行 - at：某个绝对时间执行一次 - cron：cron 表达式调度 ### 9.2 支持的任务类型 - internal_event：内部事件 - outbound_message：直接向目标通道发消息 - agent_task：构造一次合成用户输入，复用完整 Agent 流程执行 agent_task 会复用正常链路中的这些能力： - 历史加载 - Agent Prompt 注入 - 工具调用 - 会话持久化 - 渠道消息下发 ### 9.3 运行时管理 通过 scheduler_manage 可以进行： - list - get - put - delete - pause - resume 任务定义和状态都会写进 SQLite，所以重启后仍可恢复。 调度器配置示例： ```json { "scheduler": { "enabled": true, "tick_resolution_ms": 1000, "misfire_policy": "skip", "jobs": [ { "id": "session.cleanup", "kind": "internal_event", "schedule": { "type": "interval", "seconds": 300 }, "payload": { "event": "session_cleanup" } }, { "id": "agent.daily_summary", "kind": "agent_task", "schedule": { "type": "cron", "expression": "30 18 * * *" }, "target": { "channel": "feishu", "chat_id": "oc_xxx" }, "payload": { "prompt": "请总结今天的项目进展，并列出明天的优先事项", "agent": "default", "fresh_session": true, "system_prompt": "你是日报助手，输出时先给摘要，再给待办。", "sender_id": "scheduler-daily-summary", "metadata": { "job_type": "daily_summary", "source": "scheduler" } } } ] } } ``` ## 10. 渠道与运行方式 ### 10.1 当前支持的通道 - WebSocket CLI 客户端 - 飞书通道 ### 10.2 Gateway 接口 网关当前暴露： - /health：健康检查 - /ws：CLI 客户端连接入口 ### 10.3 CLI 使用方式 程序提供两个主命令： ```bash cargo run -- gateway cargo run -- agent ``` 含义： - gateway：启动网关服务 - agent：以 WebSocket 方式连接网关，进入本地 CLI 会话 CLI 中已实现的交互命令包括： - /new [title] - /reset - /sessions - /use - /rename - /archive - /delete - /clear - /quit ## 11. 配置说明 配置默认从以下位置加载： 1. ~/.picobot/config.json 2. 如果不存在，则回退到当前工作目录下的 config.json 配置加载前还会先读取环境变量，并替换配置中的占位符。 最小可运行配置示例： ```json { "providers": { "default": { "type": "openai", "base_url": "<OPENAI_BASE_URL>", "api_key": "<OPENAI_API_KEY>", "extra_headers": {} } }, "models": { "default": { "model_id": "<OPENAI_MODEL_NAME>", "temperature": 0.2 } }, "agents": { "default": { "provider": "default", "model": "default", "tool_result_max_chars": 20000, "context_summary_max_chars": 20000, "context_tool_result_trim_chars": 2000 } }, "gateway": { "host": "0.0.0.0", "port": 19876, "agent_prompt_reinject_every": 100 }, "scheduler": { "enabled": true, "tick_resolution_ms": 1000, "misfire_policy": "skip", "jobs": [] } } ``` 常用配置项： - providers：Provider 连接信息 - models：模型参数 - agents：Agent 级别的工具轮次、token 上限和上下文裁剪参数 - gateway：监听地址、端口、工具结果展示、会话 TTL、Prompt 重注入策略 - scheduler：调度器开关和任务列表 - channels：飞书等通道配置 - skills：技能来源与索引限制 - time.timezone：时区，默认应使用 IANA 时区名，例如 Asia/Shanghai ## 12. 快速开始 ### 12.1 准备配置 1. 复制并修改 config.json，或把配置放到 ~/.picobot/config.json 2. 配置好 Provider 的 base_url、api_key、model_id 3. 如果要接飞书，再补充 channels.feishu 配置 ### 12.2 启动网关 ```bash cargo run -- gateway ``` ### 12.3 启动本地 CLI ```bash cargo run -- agent ``` 默认会连接： ```text ws://127.0.0.1:19876/ws ``` 也可以手动指定： ```bash cargo run -- agent --gateway-url ws://127.0.0.1:19876/ws ``` ### 12.4 检查服务状态 ```bash curl http://127.0.0.1:19876/health ``` ## 13. 目录结构 ```text PicoBot/ ├── src/ │ ├── agent/ # AgentLoop、上下文压缩 │ ├── bus/ # 消息总线与消息结构 │ ├── channels/ # 渠道适配 │ ├── cli/ # CLI 输入命令 │ ├── client/ # WebSocket CLI 客户端 │ ├── config/ # 配置解析 │ ├── gateway/ # Gateway、SessionManager、WS/HTTP │ ├── providers/ # OpenAI / Anthropic Provider │ ├── scheduler/ # 定时任务系统 │ ├── skills/ # 技能运行时 │ ├── storage/ # SQLite 持久化 │ └── tools/ # 内置工具集合 ├── docs/ │ ├── IMPLEMENTATION_LOG.md │ └── PERSISTENCE.md ├── tests/ └── config.json ``` ## 14. 测试与维护建议 当前 tests 目录中已经包含 Provider 集成测试和工具调用相关测试，但部分测试依赖外部 API Key，需要先准备 tests/test.env。 建议维护时重点关注： - docs/PERSISTENCE.md：持久化结构是否与代码一致 - src/gateway/session.rs：消息流、工具注册、记忆维护、会话恢复主逻辑 - src/storage/mod.rs：SQLite schema 变更 - src/config/mod.rs：配置项变更是否同步到 README ## 15. 总结 PicoBot 当前已经具备一个可长期运行 Agent 系统的关键组件： - 有入口：Gateway + Channel - 有状态：SQLite + Session 恢复 - 有能力：工具调用 + 技能系统 - 有记忆：长期记忆 + 自动维护摘要 - 有计划：Scheduler + agent_task 如果后续继续演进，比较自然的方向会是： - 增加更多渠道 - 增强多模态能力 - 完善记忆检索排序与冲突消解 - 为不同 Agent 提供更清晰的配置和权限隔离