• 项目地址：https://github.com/happysnaker/qq-ai-bot
• 项目主页：https://happysnaker.github.io/qq-ai-bot/
• Docker 演示：https://github.com/happysnaker/qq-ai-bot/blob/main/docs/docker-quickstart.md
• 部署矩阵：https://github.com/happysnaker/qq-ai-bot/blob/main/docs/deployment-matrix.md
• 许可证：MIT

项目简介

qq-ai-bot 是一个把 QQ / OneBot 11 接到 本地 AI agent 的自托管脚手架。

它前面兼容 NapCat / LLOneBot 这类 OneBot 11 实现，后面接 ACP-compatible agent。重点不是做一个新的聊天 UI，而是把消息入口、会话状态、进度回传、Docker 演示和部署文档整理成一个可以直接跑起来的 QQ ↔ AI 基础设施仓库。

如果你已经有本地 agent，或者想验证一条完整的 QQ -> OneBot -> bot bridge -> agent runtime 链路，这个项目会比纯 demo 型聊天机器人更实用一些。

主要功能

• 兼容 OneBot 11 / NapCat / LLOneBot
• 私聊、群聊独立会话，群聊支持仅 @机器人 触发
• ACP session 复用与持久化恢复
• 把 agent 的处理中进度实时回传到 QQ
• 图片可自动转给 agent
• 对文件 / 语音 / 视频等暂未直传的 richer media，会显式告诉 agent “当前未读到附件”，避免静默丢失
• 提供 /metrics、/readyz、/status 等偏运维能力
• 内置轻量入站去重、correlation ID 等排障信号
• 仓库自带 NapCat + qq-ai-bot + mock ACP agent 的最小 Docker demo

这个项目比较特别的地方

1. 更像消息入口层 / bot 脚手架，而不是另一个聊天玩具。
   核心定位是 OneBot transport 和本地 agent runtime 之间的桥接层。

2. 可以先用 mock agent 跑通全链路，再替换成自己的 agent。
   对想验证接线、WS 模式、会话状态和进度回传的人比较友好。

3. 文档相对完整。
   项目介绍、特性、快速开始、Docker demo、FAQ、部署矩阵、架构说明、Roadmap、Contributing、Security 都已经补齐。

4. 不是只会“能跑”，也补了一些工程化细节。
   比如 session persistence、progress streaming、observability、轻量去重、richer-media fallback 这些更接近真实部署痛点的部分。

5. 已经进入 OneBot 生态页。
   所以它更像一个可复用的 bot 基础设施项目，而不是纯自娱自乐的小作品。

截图

架构图：

进度回传示意：

如果一句话概括，我会把它介绍成：

一个基于 OneBot 11 + ACP 的 QQ ↔ AI 自托管脚手架，带 persistent sessions、progress streaming、Docker demo，更像 bot 基础设施而不是聊天玩具。