CountBot 架构设计与技术解析
市面上做 AI Agent 框架的不少，但真正适合个人用户的不多。大多数框架面向企业场景，代码量动辄几十万行，配置复杂，对中文用户和国产大模型的支持也不够友好。
CountBot 的目标很明确：用最少的代码，做一个功能完整、开箱即用、中文优先的个人 AI Agent。
最终成果：约 21,000 行 Python 代码，涵盖了记忆系统、多渠道接入、技能插件、消息队列、安全认证等完整的 Agent 基础设施。
一、整体架构设计
采用模块化设计，每个模块职责清晰，耦合度低。新增 LLM 提供商、消息渠道、工具或技能，只需在对应目录下添加文件。
countbot/
├── backend/ # 后端核心（~21K 行）
│ ├── modules/
│ │ ├── agent/ # Agent 核心（ReAct 循环、记忆、上下文）
│ │ ├── messaging/# 消息队列（优先级调度、令牌桶限流）
│ │ ├── cron/ # Cron 调度器（精确按需唤醒）
│ │ ├── auth/ # 安全认证（渐进式安全模型）
│ │ ├── channels/ # 渠道管理（飞书/钉钉/QQ/Telegram）
│ │ ├── providers/# LLM 提供商（基于 LiteLLM）
│ │ └── tools/ # 工具系统（13 个内置工具）
├── frontend/ # 前端（Vue 3 + TypeScript）
├── skills/ # 技能插件（10 种）
└── docs/ # 完整文档（11 篇）
二、Agent 核心与智能记忆
1. ReAct 循环
Agent 的核心是一个标准的 ReAct（Reasoning + Acting）循环，逻辑如下：
- 接收用户消息
- 构建上下文（系统提示 + 记忆 + 对话历史 + 工具描述）
- 调用 LLM 推理
- 如果 LLM 返回工具调用 → 执行工具 → 将结果反馈给 LLM → 继续循环
- 如果 LLM 返回文本 → 输出给用户
关键设计在于上下文构建时会自动进行滚动压缩。当对话历史超出窗口时，早期对话会被 LLM 总结为摘要，大幅降低 Token 消耗。
2. 智能记忆系统
这是 CountBot 最核心的差异化特性。记忆系统分为两层：
短期记忆（对话上下文）
- 滚动窗口内的完整对话
- 超出窗口时自动压缩为摘要
长期记忆（持久化存储）
- LLM 自动判断何时需要记忆
- 通过
memory_write工具写入 - 通过
memory_search关键词检索 - 行式文件存储，简单可靠
例如，用户说'我叫张三，住在北京'，LLM 判断这是重要信息后自动调用 memory_write 存储。三天后用户问'帮我推荐附近的餐厅'，LLM 自动调用 memory_search("用户偏好") 检索到'喜欢火锅'，结合地址'北京'即可精准推荐。
三、安全与调度机制
1. 渐进式安全模型
核心思路是：安全等级随访问距离递增。
- 本地访问（127.0.0.1）：零摩擦，直接使用。个人电脑上用，没必要每次输密码。
