Skip to content

happysnaker/qq-ai-bot

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

127 Commits
.github
.github
 
 
assets
assets
 
 
deploy
deploy
 
 
docs
docs
 
 
examples
examples
 
 
scripts
scripts
 
 
src
src
 
 
.dockerignore
.dockerignore
 
 
.env.docker.example
.env.docker.example
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
.npmrc
.npmrc
 
 
ARCHITECTURE.md
ARCHITECTURE.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Dockerfile
Dockerfile
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
ROADMAP.md
ROADMAP.md
 
 
SECURITY.md
SECURITY.md
 
 
SUPPORT.md
SUPPORT.md
 
 
docker-compose.arm64.yml
docker-compose.arm64.yml
 
 
docker-compose.demo.yml
docker-compose.demo.yml
 
 
eslint.config.js
eslint.config.js
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 
vitest.config.ts
vitest.config.ts
 
 

Repository files navigation

qq-ai-bot

CI Release Stars OneBot 11 Use this template Project Page Support Umbrel App Store

💛 这个项目完全免费开源。如果它帮你省了时间，请考虑 请我喝杯咖啡（¥9.9 起，微信/支付宝）。不确定该打赏、看 proof、买 deploy-read，还是资助 qq-ai-bot #26 arm64 真机验证？先走 10-second support router；如果你是 homelab tester / bot builder / curator / sponsor，先看 sponsor prospect pipeline 选对 proof、CTA、support note 和 guardrail，再用 sponsor conversion scorecard 判断 Hot / Warm / Nurture / No-send，避免泛泛 donation bump。

一个面向实际部署的 QQ ↔ AI 机器人项目。

qq-ai-bot 基于 OneBot 11 接入 QQ，基于 ACP 对接本地 agent，并将结果、会话状态和处理中进度返回到 QQ。它不绑定某一个特定 agent：只要你的 agent 能以 ACP 方式启动和通信，就可以挂到这个机器人后面。

常见接法包括：把 DeepSeek 或其他本地 / 自托管模型能力，封装在一个 ACP-compatible agent runtime 后面，再由 qq-ai-bot 负责 QQ / OneBot 接线、会话管理和进度回传。

English pitch: A production-grade, self-hosted QQ ↔ AI bridge for OneBot 11 / NapCat / LLOneBot and ACP-compatible agents, with persistent sessions and progress streaming.

qq-ai-bot architecture overview

💰 这个项目帮你省了搭建时间？ 别光 star — 请作者喝杯咖啡 ☕（¥9.9 起，微信/支付宝）。或者买一份 ¥29.9 快速评审 帮你自己的项目做同样级别的包装。

💰 支持作者 / Support

如果这个项目帮你省了 OneBot / ACP 接线时间，欢迎请我喝杯咖啡：

微信支付 支付宝

付款时请备注 ，让我知道是哪个项目帮到了你。

也提供付费服务：

  • ¥29.9 — 快速评审你的 GitHub profile / README / 项目页面
  • ¥99 — 异步深度评审 + 具体改法建议
  • ¥199 — 捆绑评审：GitHub profile + 一个 repo README + 一个落地页

支付后发邮件到 happysnaker@foxmail.com，附上链接+截图即可。

→ 更多支持方式

🎯 赞助众筹 / Sponsorware

以下是计划中的功能。每个功能标了开发成本——凑够赞助就开工。

功能 目标金额 进度 状态
Postgres session store ¥50 100% ✅ 已发布
多实例部署指南 ¥30 100% ✅ 已发布
端到端延迟 histograms ¥80 100% ✅ 已发布
arm64 / CasaOS 真实安装报告 ¥50 80% 🧪 QEMU smoke 已过，等真机报告
微信通知集成 ¥100 0% 🚧 等待赞助
Web Dashboard (管理面板) ¥150 0% 🚧 等待赞助

怎么赞助？ 扫码支付后在该功能 Issue 下留言，附上截图即可。

微信支付 支付宝
扫码请备注功能名，比如 Redis 或 Dashboard

💡 为什么用 Sponsorware？ 开源不意味着免费劳动。赞助众筹让你用一杯咖啡的钱换来你需要的功能，也让我有动力持续维护。

核心能力

qq-ai-bot progress streaming demo

  • OneBot 11 forward / reverse WebSocket
  • 兼容 NapCat / LLOneBot
  • 私聊、群聊独立会话
  • 群聊支持仅 @机器人 触发
  • 每个群独立 systemPrompt
  • /help /status /prompt /reset /ping
  • ACP 会话复用与持久化
  • 处理中进度回传到 QQ
  • 入站图片下载后转给 agent
  • 对暂未自动直传的语音 / 文件 / 视频等 richer media，显式告诉 agent“当前未读到附件”，避免静默丢失
  • Prometheus 风格 /metrics、runtime counters 与 turn / agent / reply latency histograms
  • /readyz / /status 中暴露 build / version 信息
  • 可插拔 session store（默认 file，支持 Redis）
  • 轻量入站消息去重，降低 OneBot 重放导致的重复 ACP 调用
  • macOS 下提供 NapCat 接入辅助脚本

快速开始

1. 准备环境

  • Node.js 22+
  • 一个 OneBot 11 实现（推荐 NapCatQQ 或 LLOneBot）
  • 一个 ACP 兼容 agent

如果你还没决定接哪个 agent，先看 ACP Agent 接入。里面给了三种可直接用的方式：仓库自带 mock agent、traex 示例、以及自定义 agent 配置。

2. 拉代码并准备配置

git clone https://github.com/happysnaker/qq-ai-bot.git
cd qq-ai-bot
npm install
cp .env.example .env
cp examples/group-rules.example.json examples/group-rules.local.json

项目启动时会自动读取项目根目录下的 .env。

你真正要修改的是：

  • 项目根目录下的 .env
  • 项目根目录下的 examples/group-rules.local.json

如果你先想跑通仓库默认链路，.env.example 已经给了一个可直接工作的 mock agent 配置。先不要急着改 ACP_AGENT_*，先把链路跑通。

如果你要接自己的 agent，最重要的 ACP 配置是这三项：

ACP_AGENT_COMMAND=your-acp-agent-command
ACP_AGENT_ARGS_JSON=["arg1","arg2"]
ACP_AGENT_WORKDIR=/path/to/your/workdir

3. 先测 agent，再接 QQ

先确认 bot 能拉起你配置的 ACP agent：

npm run smoke:agent

看到输出里包含 ACP_SMOKE_OK 后，再启动 bot：

npm run dev

如果这时你接的是 traex，推荐 .env 至少写成：

ACP_AGENT_COMMAND=traex
ACP_AGENT_ARGS_JSON=["acp","serve"]
ACP_AGENT_WORKDIR=/path/to/your/workdir

4. 再接 QQ / NapCat

如果你在 macOS + 本机 QQ + NapCat 上跑，推荐顺序：

npm run status:napcat:macos
npm run setup:napcat:macos -- --token change-me --ws-url ws://127.0.0.1:16700/onebot/v11/ws
npm run launch:napcat:macos -- --restart

然后：

  1. 打开 http://127.0.0.1:6099/webui
  2. WebUI token 填 change-me
  3. 在 WebUI 里登录 QQ
  4. 再执行：
curl http://127.0.0.1:8080/status

如果你不是用 macOS helper，而是自己配置 OneBot 11，也至少要保证 reverse WebSocket 指到：

ws://127.0.0.1:16700/onebot/v11/ws

并且 OneBot 侧 token 与 .env 里的 ONEBOT_ACCESS_TOKEN 一致。

5. 在 QQ 中验证

建议顺序：

  1. 私聊机器人发一句普通文本
  2. 发送 /ping
  3. 发送 /status
  4. 群聊里 @机器人 再发一句文本

文档

命令

  • /help
  • /status
  • /prompt
  • /reset
  • /ping

外部项目 / 协议

平台说明

  • macOS：仓库内置了 NapCat 辅助脚本。
  • Windows：提供接入说明，但当前标记为 未验证。
  • Linux：bot 侧本身没有特殊限制。

Roadmap / Help wanted

如果你想看这个仓库下一步会往哪走，或者想直接认领一个更偏工程化的贡献方向，先看：

当前优先方向：

  • richer media / 附件处理
  • tracing / 更细的 observability 信号
  • 多实例部署与更多外部存储路径
  • 更多 channel / transport 演进

当前已经挂出的可认领入口：

如果你准备提 PR，建议先看 CONTRIBUTING.md。

Community

Public promo / sponsor kit

Promo kit / 转发文案

如果你想把这个项目转到群里、论坛、周刊、awesome list 或发给朋友，直接复制下面这些就够了。

最短一句话：

OneBot 11 + ACP + persistent sessions + progress streaming

中文一段版：

qq-ai-bot 是一个面向 OneBot 11 / NapCat / LLOneBot 的 QQ ↔ AI 自托管脚手架。它把 QQ 消息入口、ACP agent bridge、会话持久化和进度回传整理成了一个更像 bot 基础设施的仓库，而不是只会聊天的玩具 demo。

English one-paragraph version:

qq-ai-bot is a self-hosted QQ ↔ AI bot scaffold for OneBot 11 / NapCat / LLOneBot and ACP-compatible agents, with persistent sessions and progress streaming. It is positioned as bot infrastructure / integration glue rather than another toy chat UI.

最有用的 3 个链接：

如果对方是周刊 / awesome list / 维护者：

  • 最好突出：OneBot 11、NapCat / LLOneBot、ACP-compatible agents
  • 最好强调：persistent sessions、progress streaming
  • 最好避免只写成“又一个 QQ 聊天机器人”，因为这个项目更偏 bridge / scaffold / bot infrastructure

Operational notes

  • 对 OneBot 重连 / 重放导致的重复入站事件，仓库现在会做一层轻量入站去重，尽量避免重复命令处理和重复 ACP prompt
  • 当前是单实例内存级 replay guard，目标是先减少明显重复触发，而不是承诺严格 exactly-once
  • 单轮交互现在会派生一个 correlation ID，并贯穿到 receive / dedupe / ACP dispatch / progress / final reply 相关日志里，便于排查“这一次到底发生了什么”
  • 建议 grep correlationId=（或 JSON 日志里的 correlationId 字段）把一次消息相关的接收、去重、进度和回复串起来看
  • richer media 当前仍然是分阶段演进：文本和图片是稳定主链路；语音 / 文件 / 视频等媒体现在会被显式标记为“未直传媒体”，并通过 prompt 附加说明告知 agent 不要假装已经读取附件
  • 相关配置与说明见 配置说明

Support

如果这个仓库帮你省掉了 OneBot 接线、会话管理或 ACP bridge 的搭建时间：

  • 给仓库点个 star
  • 提 issue / PR 补充更多 channel、session store 或 observability 能力
  • 直接支持我的开源维护：happysnaker.github.io/support
  • 如果你愿意顺手帮我传播，最好直接转这句：OneBot 11 + ACP + persistent sessions + progress streaming
  • 如果你想把它发到群里 / 论坛 / 朋友那，最短链接组合是：仓库首页 + 项目页 + 快速开始
  • 如果你是因为这个项目来的，付款备注最有用的是：qq-ai-bot
  • 如果你卡在部署、README 定位、项目页包装这类问题，最快的付费入口其实是 ¥29.9 quick read：我会先 blunt 地告诉你最该改的 3 件事，而不是让你继续在仓库里瞎试
  • 如果你更像是卡在 NapCat / LLOneBot / token / reverse WS / Docker / landing page 这一整条 deploy story 上，可直接用这个标题发邮件：Deploy read | qq-ai-bot inbound | repo link
  • 如果你想先看一下这种 deploy read 到底会长什么样，可先看公开样例：Deploy read sample
  • 如果你想让我先 blunt 地看一眼你自己的 bot / agent / infra 仓库，可直接发这个模板：¥29.9 Quick read | repo link
  • 如果你想要更完整的 GitHub / README / landing-page 包装 pass，可直接发这个模板：¥99 Async review | repo link
  • 如果你就是从 qq-ai-bot 进来的，邮件标题直接写：Quick read | qq-ai-bot inbound | repo link 或 Async review | qq-ai-bot inbound | repo link，我能更快识别上下文
  • 不要在 public issue 里贴 private logs、credentials、QR codes、payment screenshots、internal URLs 或 raw live integration output；先用 sponsor conversion scorecard 做 Hot / Warm / Nurture / No-send 判断，再用 sponsor / paid-support intake replies 选正确入口。
  • 如果你想把自己的 bot / agent / infra 仓库也整理成这种更像成品的状态，可看轻量付费反馈：happysnaker.github.io/review

About

Self-hosted QQ ↔ AI bridge for OneBot 11 / NapCat / LLOneBot and ACP agents, with sessions, progress streaming, metrics, Docker, and sponsorware docs.

happysnaker.github.io/qq-ai-bot/

Topics

docker metrics chatbot prometheus self-hosted acp observability homelab onebot multi-instance qq-bot sponsorware ai-agent casaos llonebot napcat agent-bridge agent-client-protocol onebot-11 bot-infrastructure

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 8

qq-ai-bot v0.1.7 Latest
Jul 8, 2026
+ 7 releases

Packages

 
 
 

Contributors

Languages