分享一个基于 OneBot 11 / NapCat / LLOneBot 的 QQ ↔ AI 自托管脚手架：qq-ai-bot

[happysnaker]

最近做了一个偏工程化的 OneBot 侧项目，想放到社区里给需要把 QQ / OneBot 接到本地 agent 的同学参考：

• 仓库：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/ARCHITECTURE.md

它的定位不是再做一个聊天 UI，而是把：

• OneBot transport（NapCat / LLOneBot）
• ACP-compatible local agent
• session persistence / progress streaming / deployment docs

整理成一个可以直接跑起来的 QQ ↔ AI scaffold / bridge。

目前这条路径已经补了这些：

• NapCat / LLOneBot 接入说明
• NapCat + qq-ai-bot + mock ACP agent 的最小 Docker demo
• FAQ / deployment matrix / architecture docs
• /metrics、/readyz、correlation ID、轻量入站去重
• richer media 的显式 fallback，避免 agent 假装“已经读到附件”

这个项目已经进了 OneBot 生态页，所以我也想继续收集一些真实部署反馈，看看社区里大家更常用哪些组合。

如果这里有人已经实际跑过类似链路，欢迎分享一下：

• NapCat 还是 LLOneBot
• reverse WS 还是 forward WS
• Docker 还是直接本机跑
• 后面接的是 DeepSeek / 其他本地模型 / 自定义 ACP agent
• 最容易踩坑的是 token、WS path、媒体处理，还是 session / prompt 边界

如果有价值，我会把这些真实组合和坑点继续沉淀回公开文档。

[happysnaker]

如果有人已经实际跑过这条链路，最有用的补充格式其实很简单：\n\n- OneBot side：NapCat / LLOneBot\n- WS mode：reverse / forward\n- Runtime shape：Docker / local / other\n- Agent side：mock ACP / traecli / custom ACP agent / other\n- Model side：none / DeepSeek / Ollama / other\n- One thing that bit you once：token / WS path / container networking / media handling / session boundary / other\n- One thing that felt surprisingly smooth：...\n\n哪怕只有 5 行也有价值。我会把好的真实组合和踩坑点继续沉淀回公开文档，而不是只停留在“README 里说支持”。