从零搭一个会记事、会主动找你的 QQ AI 陪聊机器人

admin

一、它和“调个 API 转发消息”有什么不同

如果你只是想让 QQ 里有个东西能回话，网上现成的转发脚本很多：收消息 → 拼 prompt → 调 DeepSeek → 发回去，一百行代码就能跑。
但真用起来，很快就会遇到三个问题：

• 它记不住你。 每次对话都是白纸，昨天说过的过敏、前天提过的考试，全靠你重复。
• 它不是“一个人”。 说话没有固定语气，一会儿像客服一会儿像 GPT，半夜还在问你“早安”。
• 它不会主动找你。 你不说话它就永远沉默——而这恰恰是“陪聊”和“问答”最大的区别。
  

暖屿补的就是这三件事：人设、记忆、主动性。模型只负责“说话”，剩下的交给业务层。

---

二、它能做什么

• 像微信一样聊天：回复拆成 1–3 条短句，带打字延迟，不发小作文。
• 长期记忆：每天中午自动把对话提炼成「事实卡 + 每日摘要」，下次聊天自动带上；按「机器人账号 × 聊天对象」隔离，不会串台。
• 主动消息：早安、晚安、沉默 6 小时、跟进你提过的事；默认 23:30–08:00 静默，每天最多 3 条，两条间隔不少于 2 小时。
• 人设：每个机器人账号可以启用不同人设；也能上传小说/聊天记录，自动提炼说话风格。
• 表情包：聊天中自动收集、打标签，按情绪和时段发送；支持按关键词现场搜图。
• 语音条：MiMo TTS 合成，支持音色克隆、概率发送、每日上限；对方发语音会自动转文字进上下文。
• 图片理解：本地 CLIP/NSFW/OCR 预筛，通过后再送视觉模型；敏感图不下载、不上传。
• 多机器人账号：每个号独立 NapCat 容器、独立 SQLite，可扫码、切换、下线、删除。
• 双协议端：新建账号时可选 NapCat 或 SnowLuma，业务层不用改。
• 知识库 / 每日复盘 / 成本统计 / 关系与心情 / 后台扫码登录。
  

---

三、整体架构

你的手机 QQ    │  私聊消息    ▼┌─────────────┐   OneBot v11    ┌──────────────────┐│ NapCat      │ ◄─────────────► │ 暖屿 Warm Isle   ││ 或 SnowLuma │   WebSocket     │ Spring Boot      │└─────────────┘                 └────────┬─────────┘                                         │                    ┌────────────────────┼────────────────────┐                    ▼                    ▼                    ▼              DeepSeek API         SQLite（记忆）      imageguard（本地预筛）

• 协议端：登录真实 QQ，把消息翻译成 OneBot v11 的 JSON；
• 暖屿：负责人设、记忆、主动消息、表情、语音、图片；
• DeepSeek：只负责“根据上下文生成一句话”。
  

协议端和业务层解耦：今天用 NapCat，明天换 SnowLuma，业务代码不用动。

---

四、你需要准备什么

项说明
服务器Ubuntu 22.04/24.04，2C4G 起（2G 能跑，但图片预筛容易 OOM）
QQ 小号强烈建议用小号，别拿主号；机房 IP 有风控概率
DeepSeek API Keyplatform.deepseek.com，充 10 块钱能聊很久
域名（可选）有域名才能自动上 HTTPS；没有就先 IP + 强密码，别长期裸奔
Linux 基础会 ssh、会改文件、会看 docker logs安全组只开 22 / 80 / 443。后台 8080、协议端 3001、预筛 8081 都不要对公网开放。

---

五、部署：跟着复制就行

1. 安装 Docker

服务器内存小、构建容易 OOM，也可以在自己电脑上构建好，再 scp target/qqbot.jar 传到服务器。

4. 配置 .env

说话像发微信，短句为主，可以分几条发；对方说得少你就更少；不要用书面语、不要用列表、不要"作为 AI"；不确定就说"不太确定"，别编。2. 设置可聊天的 QQ

「机器人账号」→ 卡片里的「可聊天的 QQ」→ 从好友列表选择或直接输入 QQ → 保存。
留空 = 不限制，仅建议在试运行时短时间使用。
3. 记忆与主动消息

• 记忆：每天 12:00 自动抽取，后台可看事实卡、摘要、待确认项；
• 主动消息：「主动消息」页可开关、改时段和频率；
• 主人 QQ：在账号页填你自己的号，只有这个号能让机器人改昵称/换头像。
  

七、进阶玩法

多账号

每个账号独立容器、独立库、独立人设。后台「机器人账号」→ 添加，可选：

• 全新账号：空库；
• 复制当前账号：带记忆/人设的副本；
• 迁移旧账号数据：旧号删除，数据搬过去。
  

单机内存有限，3.6G 的机器建议不超过 3 个号；开新号前先看「关于」页的内存。
切换协议端

账号卡片 →「切换接入」→ NapCat ↔ SnowLuma。会重建协议端容器，聊天记录和记忆不动，切换后重新扫码即可。
知识库

「知识库」→ 上传文件 → 选择解析类型：

• persona：生成人设；
• style：只学说话风格；
• raw：仅入库供检索。
  

解析只在每天 00:05–06:05 跑，内存低于 500MB 会自动暂停。
语音与表情

• 语音：配置 MIMO_API_KEY 后，可在聊天里说“发条语音”，也可设置概率自动发；
• 表情：聊天中收到的图会自动入库，后台审核；机器人按情绪和时段挑选发送。
  

---

八、常见问题

现象排查
页面打不开docker compose ps 看 caddy/qqbot 是否 Up；80 端口是否放行
扫码后离线看 napcat 日志；账号可能被风控，换号或等一会
机器人不回白名单是否包含该 QQ；看 docker compose logs qqbot
图片不理解imageguard 是否 OOM；模型文件是否齐全；curl 127.0.0.1:8081/health
语音发不出MIMO_API_KEY 是否配置；日志搜「语音发送失败」
更新代码git pull → cd deploy/linux && docker compose up -d --build qqbot
数据备份tar czf qqbot-$(date +%F).tar.gz -C deploy/linux/data qqbot

---

九、安全与合规（请务必看）

• QQ 风控：NapCat / SnowLuma 都是第三方非官方客户端，违反 QQ 用户协议，有封号风险。请用小号、别群发、别做营销，项目仅供学习与技术研究。
• 协议端授权：NapCat 与 SnowLuma 并非 AGPL 开源许可，商业使用需单独获得授权。
• AGPL-3.0：你可以自用、修改、部署；如果把修改版作为网络服务对外提供，需要公开修改后的源码。
• 后台安全：强密码、.env 权限 600、不要长期开“一键放通”、尽量上 HTTPS。
• 数据：聊天记录和记忆都在 deploy/linux/data/ 的 SQLite 里，务必定期备份到另一台机器。