21K 行代码实现一个生产级 AI Agent 框架 — CountBot 架构设计与技术解析 | 今日正式开源

Ne0inhk

15 Mar 2026 — 6 min read

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 模式	✅ 可用
QQ	官方 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