qq-ai-bot

qq-ai-bot 是一个面向实际部署的 QQ ↔ AI 自托管脚手架：前面接 OneBot 11 / NapCat / LLOneBot，后面接 ACP-compatible agent。它重点解决的不是“再做一个聊天 UI”，而是把 QQ 消息入口、会话状态、进度回传、部署路径和工程化文档整理成一个能直接跑起来的 bot 基础设施仓库。

项目地址：

• 仓库：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
• 架构说明：https://github.com/happysnaker/qq-ai-bot/blob/main/ARCHITECTURE.md
• OneBot 生态：https://onebot.dev/ecosystem

核心能力

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

跟同类项目不太一样的点

1. 更像 消息入口层 / bot 基础设施脚手架，而不是又一个纯聊天界面。
2. 文档相对完整：项目介绍、特性、快速开始、Docker demo、FAQ、部署矩阵、架构、Roadmap、Contributing、Security 都补齐了。
3. 可以先用仓库自带 mock agent 把 QQ → OneBot → qq-ai-bot → agent 全链路跑通，再替换成自己的本地 agent。
4. 当前已经补了会话持久化、进度 streaming、可观测性、去重和 richer-media fallback 这类更偏工程化的能力，比较适合消息通道、bot 平台和自托管 AI 接入场景。

截图

架构图：

进度回传示意：