4 层组件#

• 通道层 (Channels) — TelegramChannel (python-telegram-bot v22+ async, polling 120s watchdog) + WebChannel (aiohttp 嵌入式服务器, SSE 流式 + JSON 双形态)。Bearer 令牌认证, 24 小时 TTL, 内存字典存 session。
• 核心脊柱 (Core spine) — EventBus (asyncio pub/sub, 同步 handler + 错误隔离) + ConversationManager (LangGraph StateGraph + AsyncSqliteSaver, 4 小时压缩一次活跃 thread 的旧消息成 summary, 存 memories.db) + MessageHandler (双模式路由: 话题模式直接走 pi RPC, 默认模式走 IntentRouter)。
• Worker / Actor — 7 个后台工作者, 5 个由 cron 驱动, 2 个由事件驱动 (见下表)。
• 存储层 — SQLite 多库 (检查点 / memories / todos / schedules) + 日复一日的 rotated 日志 (chat-YYYY-MM-DD.log, result-YYYY-MM-DD.log)。

事件契约：EventBus 上跑的 6 种事件#

EventBus 是项目的中央神经, 但它不是匿名广播——handler 订阅的是具体事件类型, 这才是路由契约。

记住这一点就不会把 EventBus 误当成”什么事件都往里扔的总线”——它是强类型路由表, 每条事件都有明确的 producer / consumer 配对。

Worker / Actor 模型：7 个后台工作者#

1
cron 驱动 (5 个 TaskActor, 注册在 CronDispatcher):
2
  ├── TodoReminderActor            ── cron ── todo 提醒推送
3
  ├── ScheduledMessageActor        ── cron ── 按 cron 表达式发定时消息
4
  ├── MemoryConsolidationActor     ── 每 4h ── 压缩活跃 thread 旧消息成 summary
5
  ├── DailyDigestActor             ── 每天 08:00 ── aihot AI 资讯 (调 pi)
6
  └── SyncTodosSchedulesActor      ── 每天 11:00 ── 双向同步 (仅本地端注册)
7

8
事件驱动 (2 个 Worker, 不走 cron):
9
  ├── BlogSyncTask                 ── file_changed ── git add/commit/pull --rebase/push
10
  └── CodeTaskExecutor             ── /task /query ── pi RPC (默认) 或 claude CLI (回退)

为什么 BlogSyncTask 不归 cron 管 — 这是个关键设计。文件系统事件 (inotify) 比 cron 更实时更准确, 而且 watchdog 与 scheduler.enabled 解耦, 意味着云端关掉调度器时, BlogSyncTask 仍然在推 git。这是 dual-instance 推送能成立的根本。

为什么 SyncTodosSchedulesActor 只在本地注册 — 同步是单点责任, 两端都发起会撞 LWW (last-write-wins) 竞态。云端 sync.enabled=false, 这个 Actor 根本不注册到 CronDispatcher, 而不是注册了不干活。

5 个配置开关切角色#

同一份代码, 同一个 config.yaml 模板, 通过 5 个布尔 / 字段切出两种运行姿态:

注: BlogSyncTask 不受 scheduler.enabled 控制——它 watchdog 驱动。这是云端关闭调度器时 dual-push 仍能成立的关键。

本地独有 vs 云端独有 vs 两端共有#

1. 不是 HA, 是单向容错#

云端不是本地的热备。本地死了, Telegram / cron / 同步发起全部停。云端只覆盖”反向代理 + 静态博客 + Web 入口”这一层。把它当 HA 会得出错误的容量规划——它的存在是为了给公网 API 一个稳定的入口, 同时维持博客可用性。

2. cron 单点 (本地)#

cron 只在本地跑, 云端 scheduler.enabled=false。这是为了避免 dual-write 竞态——SyncTodosSchedulesActor 两端都跑的话, 同一时刻两端都向对方 POST, LWW 策略下谁赢取决于网络延迟, 不可预测。单点发起 + 双向复制是更可控的模型。

3. BlogSyncTask 与 scheduler 解耦#

这是 dual-push 能成立的关键。BlogSyncTask 订阅的是 watchdog 的 file_changed 事件, 不走 cron_tick。云端 scheduler.enabled=false 时, EventBus 仍然有 file_changed 流过 (因为 watchdog 不依赖 scheduler), BlogSyncTask 仍然推 git。

两端都向同一个 GitHub 仓库 push, 用 git pull --rebase 避免竞争——第二端 push 前先把第一端的 commit rebase 到本地, 然后快进 push。失败时重试。

4. 双 LLM 后端: DeepSeek + 百炼#

不是冗余, 是分工:

• DeepSeek (默认 chat 模型) — ConversationManager 的对话主引擎, 走 OpenAI 兼容 API
• 百炼 qwen3.6-flash (意图分类) — IntentRouter 专用, 独立 base_url (token-plan 计费), 用更便宜更快的模型做分类粗筛

意图分类调用很频繁 (每条消息都要分类), 用贵模型烧钱; 用快模型降低延迟。get_intent_model(config) 走单独的 backend section, 不会回退到 chat backend。

5. CodeTaskExecutor 双后端: pi RPC + claude CLI#

默认走 pi RPC (子进程 JSONL 协议, 20 分钟超时, stateless — 每次新 subprocess, 匹配老 claude --print 行为)。task_backend 配置 claude 时回退到 claude CLI。

CodeTaskExecutor 传 cwd=pi_workspace (默认 ./pi-workspace) 给 pi——软隔离, 防 pi 把 /query 误解为任务时顺手改了 mini-agent 自己的源码。pi 仍然是同 user 子进程, 能 cd 任何地方, 这是软屏障不是硬安全边界。

6. 静默错误模式 (云端专属)#

web.silent_errors=true 时, WebChannel 的认证失败和坏 origin CORS preflight 返 HTTP 444, 让 nginx error_page 444 =444; 静默断连。扫描器拿不到任何信号——既没有 JSON 错误体, 也没有 nginx 默认错误页。通过沉默实现的纵深防御, 对公网暴露的服务尤其重要。