21K 行代码实现一个生产级 AI Agent 框架 — CountBot 架构设计与技术解析 | 今日正式开源
CountBot 是一个轻量级、可扩展的 AI Agent 框架，专为中文用户和国内大模型优化。今天（2026.2.21）正式开源。
GitHub：https://github.com/countbot-ai/CountBot
桌面版下载：https://github.com/countbot-ai/CountBot/releases（支持 Windows / macOS / Linux）
一、项目背景
做 AI Agent 的框架不少，但真正适合个人用户的不多。大多数框架面向企业场景，代码量动辄几十万行，配置复杂，对中文用户和国产大模型的支持也不够友好。
CountBot 的目标很明确：用最少的代码，做一个功能完整、开箱即用、中文优先的个人 AI Agent。
最终成果：约 21,000 行 Python 代码，涵盖了记忆系统、多渠道接入、技能插件、消息队列、安全认证等完整的 Agent 基础设施。
二、架构设计
2.1 整体架构
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 篇） 模块化设计，每个模块职责清晰，耦合度低。新增 LLM 提供商、消息渠道、工具或技能，只需在对应目录下添加文件。
2.2 Agent 核心：ReAct 循环
Agent 的核心是一个标准的 ReAct（Reasoning + Acting）循环：
- 接收用户消息
- 构建上下文（系统提示 + 记忆 + 对话历史 + 工具描述）
- 调用 LLM 推理
- 如果 LLM 返回工具调用 → 执行工具 → 将结果反馈给 LLM → 继续循环
- 如果 LLM 返回文本 → 输出给用户
关键设计：上下文构建时会自动进行滚动压缩，当对话历史超出窗口时，早期对话会被 LLM 总结为摘要，大幅降低 Token 消耗。
2.3 智能记忆系统
这是 CountBot 最核心的差异化特性。记忆系统分为两层：
短期记忆（对话上下文）：
- 滚动窗口内的完整对话
- 超出窗口时自动压缩为摘要
长期记忆（持久化存储）：
- LLM 自动判断何时需要记忆
- 通过
memory_write工具写入 - 通过
memory_search关键词检索 - 行式文件存储，简单可靠
# 记忆系统的工作流程 用户:"我叫张三，住在北京，喜欢吃火锅"# → LLM 判断这是重要信息 → 自动调用 memory_write 存储# 三天后... 用户:"帮我推荐附近的餐厅"# → LLM 自动调用 memory_search("用户偏好") → 检索到"喜欢火锅"# → 结合用户地址"北京" → 推荐北京的火锅店2.4 渐进式安全模型
这个设计我个人比较满意。核心思路是：安全等级随访问距离递增。
- 本地访问（127.0.0.1）：零摩擦，直接使用。个人电脑上用，没必要每次输密码。
- 远程访问（192.168.x.x）：首次访问自动引导设置密码，后续需要登录。
API 密钥使用 Fernet 对称加密存储在 SQLite 中，运行时自动解密。命令执行有沙箱保护，包括工作空间隔离、路径穿越检测、空字节注入阻断。
2.5 Cron 调度器：精确按需唤醒
没有用传统的每秒轮询方式，而是计算所有启用任务的下次执行时间，取最近的一个，精确 sleep 到那个时刻：
next_wake =min([job.next_run for job in enabled_jobs])await asyncio.sleep((next_wake - now).total_seconds())配合信号量控制并发、超时保护、独立 Session、SQLite 锁重试，是一个生产级的调度实现。
2.6 消息队列
四级优先级调度、消息去重、死信处理。令牌桶算法做限流，按用户维度控制。对于多渠道同时接入的场景，这套队列系统保证了消息处理的可靠性。
三、技能插件系统
CountBot 内置了 10 个技能插件，覆盖日常使用的主要场景：
| 技能 | 说明 | 是否需要配置 |
|---|---|---|
| 百度搜索 | 网页搜索、百科、AI 智能生成 | 需要 API Key |
| 高德地图 | 路线规划、POI 搜索 | 需要 API Key |
| 邮件管理 | QQ/163 邮箱收发 | 需要授权码 |
| 图片分析 | 智谱/千问视觉模型 | 需要 API Key |
| 图片生成 | ModelScope 文生图 | 需要 API Token |
| 天气查询 | wttr.in 全球天气 | 无需配置 |
| 新闻聚合 | 中文新闻 + AI 资讯 | 无需配置 |
| 定时任务 | 聊天式创建管理 | 无需配置 |
| 网页设计 | HTML 生成 + Cloudflare 部署 | 需要 API Token |
| 浏览器自动化 | 网页操作、截图、数据提取 | 需手动安装 |
技能插件的设计是松耦合的，每个技能是一个独立目录，包含配置文件和脚本，不影响核心代码。
四、国产大模型适配
通过 LiteLLM 统一接口层，CountBot 兼容 OpenAI / Anthropic / Gemini 协议，原生支持：
国产大模型： 智谱 AI（GLM-5、免费的 GLM-4.7-Flash）、千问（Qwen3.5-Plus）、Moonshot（Kimi K2.5）、MiniMax（M2.5）、DeepSeek、豆包、文心、混元、零一万物、百川
国际大模型： OpenAI、Anthropic、Gemini、Groq、Mistral 等
本地部署： Ollama、vLLM、LM Studio
零成本上手方案： 注册智谱 AI → 获取免费 API Key → 在 CountBot 设置页面填入 → 开始使用。
五、多渠道接入
| 渠道 | 连接方式 | 状态 |
|---|---|---|
| Web UI | 内置 | ✅ 可用 |
| 飞书 | WebSocket 长连接 | ✅ 可用 |
| 钉钉 | Stream 模式 | ✅ 可用 |
| 官方 SDK | ✅ 可用 | |
| Telegram | Long Polling | ✅ 可用 |
| 微信 | 公众号 API | 🔜 即将上线 |
| Discord | Gateway | 🔜 即将上线 |
所有渠道共享同一套记忆系统，在飞书上聊的内容，切到 QQ 上 AI 也记得。
六、快速开始
方式一：Python 运行
git clone https://github.com/countbot-ai/countbot.git cd countbot pip install -r requirements.txt python start_app.py 方式二：下载桌面版
前往 https://github.com/countbot-ai/CountBot/releases 下载对应平台的安装包，支持 Windows、macOS、Linux。
启动后访问 http://localhost:8000，在设置页面配置 LLM 提供商即可。全 Web 界面管理，不需要编辑任何配置文件。
七、总结
CountBot 的定位很清晰：一个为个人用户设计的、轻量的、中文优先的 AI Agent 框架。
- 21K 行代码，易读易扩展
- 智能记忆 + 主动问候，不只是工具，更像伙伴
- 国产大模型深度适配，零成本可上手
- 多渠道统一，一套代码服务所有平台
- MIT 协议，完全开源
项目今天正式开源，欢迎 Star、Fork、Issue、PR。
GitHub：https://github.com/countbot-ai/CountBot
