QQ 机器人项目方案书
2026-07-10
一、项目概述
目标
搭建一个能模仿廖建军说话风格的 QQ 群聊 AI 机器人，部署在 ARM64 机顶盒上，使用小号 QQ 接入。
整体架构
机顶盒 (ARM64, 8GB RAM)
┌────────────────────────────────────────────┐
│ NapCat (QQ协议层, Node.js) │
│ ↓ WebSocket OneBot V11 (端口3001) │
│ Bot 调度器 (Node.js) │
│ ├── Timing Agent (规则引擎) │
│ ├── RAG 检索 (sqlite-vec, 本地) │
│ └── LLM API 调用 (外部) │
│ │
│ 附: Embedding Server (0.6B GGUF, CPU) │
│ 附: SQLite 向量数据库 (189MB) │
└────────────────────────────────────────────┘
↓
外部 LLM API (DeepSeek/硅基流动等)
二、可行性分析
2.1 技术可行性
| 模块 | 技术方案 | 可行性 | 风险 |
|---|
| QQ 协议接入 | NapCat (NTQQ 无头) | ✅ 成熟 | ⚠️ 小号可能被风控，需准备替补号 |
| 消息收发 | OneBot V11 WebSocket | ✅ 标准协议 | 无 |
| 回复时机决策 | 规则引擎 (基于数据分析) | ✅ 50行 if-else | 可能需要迭代调参 |
| 回复内容生成 | 外部 LLM API | ✅ 通用方案 | 依赖 API 可用性/成本 |
| RAG 检索 | sqlite-vec (本地) | ✅ 已验证 0.09s | 无 |
| 嵌入服务 | Qwen3-Embedding-0.6B GGUF CPU | ✅ 已验证 0.11s | 占用 ~1.2GB RAM |
| 数据存储 | SQLite 向量库 (189MB) | ✅ 已验证 | 无 |
| 部署环境 | ARM64 Linux 机顶盒 8GB | ✅ 资源充足 | 需要确认具体系统版本 |
2.2 资源可行性
| 资源 | 要求 | 说明 |
|---|
| RAM | ~2GB 总占用 | NapCat 60MB + Node.js 30MB + Embedding 1.2GB + DB 200MB |
| 磁盘 | ~300MB | NapCat 80MB + DB 189MB + 模型 610MB (可外置) |
| 网络 | 需访问外网 | 调 LLM API 和 NapCat 登录 |
| CPU | ARM64 无特殊要求 | Embedding CPU 推理可接受 (0.11s/次) |
| LLM API | 需准备 Key | DeepSeek / 硅基流动 / OpenAI 等 |
2.3 风控风险
| 风险 | 等级 | 应对 |
|---|
| QQ 小号被封 | ⚠️ 中高 | 准备 2-3 个备用小号，养号后再用 |
| NapCat 协议被腾讯封堵 | ⚠️ 低 | NapCat 社区活跃，更新及时 |
| LLM API 不稳定/涨价 | ⚠️ 低 | 多备几家的 Key，可切换 |
| 机顶盒硬件故障 | ✅ 低 | SQLite DB 可随时备份迁移 |
三、功能需求清单
P0 - 核心功能 (必须)
- [ ] QQ 协议对接: NapCat 启动 + 扫码登录 + 稳定在线
- [ ] 消息收发: 通过 WebSocket 接收群消息/私聊，发送回复
- [ ] 基本回复: 调用 LLM API 生成回复并发送（无延迟控制）
- [ ] 配置化: API Key、目标群号、QQ 号等通过配置文件管理
P1 - 拟人化 (定时决策)
- [ ] Timing Agent 规则引擎:
- 对方消息长度 → 等待时间映射
- 时间段调整（深夜回复更快）
- 连发模式检测（同人连发则秒跟）
- 长话题疲劳（50条+对话减速）
- 5% 概率忽略/不回复
- [ ] 对话上下文追踪: 记录最近 N 条消息，维护会话状态
- [ ] 多媒体消息处理: 识别图片/文件/表情消息并合理忽略或回复
P2 - 个性化 (RAG + 风格)
- [ ] RAG 检索接入: 查询本地嵌入库，召回相关历史对话
- [ ] 风格 Prompt: 系统提示词融入廖建军说话特征（简短、吼吼、吐槽）
- [ ] RAG 结果注入: 检索到的历史对话作为 Few-shot 示例拼入 Prompt
P3 - 运营保障
- [ ] 心跳保活: NapCat 异常退出自动重启
- [ ] 日志系统: 记录收到的消息、回复、API 调用量
- [ ] 错误处理: API 调用失败重试、降级回复
- [ ] 群白名单: 只回复指定群的消息
P4 - 未来扩展 (可选)
- [ ] 私聊应答: 支持私聊场景
- [ ] 图片生成: 接入 Stable Diffusion API / Flux
- [ ] 命令系统:
/help、/status 等管理命令 - [ ] 群管功能: 签到、关键词回复等
- [ ] Web 管理面板: 查看日志、调整参数
四、组件详情
4.1 NapCat
4.2 Bot 调度器 (Node.js)
依赖 3 个 npm 包：
ws — WebSocket 连接 NapCatbetter-sqlite3 + sqlite-vec — RAG 检索openai — LLM API 调用
核心文件：
| 文件 | 用途 |
|---|
index.js | 入口，WebSocket 连接 + 消息循环 |
config.js | API Key、目标群号、端口等配置 |
timing.js | 定时决策规则引擎 (约 50 行) |
rag.js | RAG 检索封装 |
llm.js | LLM API 调用封装 |
context.js | 对话上下文追踪 |
4.3 Timing Agent 规则 (从数据分析得来)
收到消息 → 判断:
1. 对方消息长度 ≤2字 → wait = 3~7s (P50~P75)
2. 对方消息长度 11~20字 → wait = 22±10s
3. 对方消息长度 21+字 → wait = 60±20s
4. 深夜 23~1点 → wait × 0.5
5. 连发中(同人连续发) → wait = 1~3s
6. 话题已持续 50+条 → wait × 1.5
7. 5% 概率 → ignore (不回)
8. P95 以上延迟 → 随机 2~70 分钟 (模拟忽略/忙)
4.4 RAG 检索
| 项目 | 数值 |
|---|
| 嵌入模型 | Qwen3-Embedding-0.6B |
| 向量维度 | 1024 |
| 检索方式 | ANN (vec0 MATCH), 0.09s |
| 库大小 | 189MB, 17,846 chunks |
| 召回数量 | Top-5 |
4.5 LLM API
推荐选项：
| 平台 | 优势 | 费用 |
|---|
| DeepSeek | 便宜、中文好 | ~¥1/百万 token |
| 硅基流动 | 注册送额度、国内直连 | 免费额度用完即付 |
| OpenAI | 质量最高 | 贵 |
| 通义千问 | 便宜 | 阿里系 |
建议 Prompt 模板：
系统: 你正在模仿廖建军说话。他的特点:
- 说话简短，平均6-7个字
- 常用词: 吼吼、啊这、离谱、妈的、确实
- 爱吐槽、秒回
- 极少问问题，大部分是陈述/吐槽
- 和好友刘剑戈很熟，对话随意
历史相关对话:
{rag_chunks}
刘剑戈说: {message}
廖建军说:
五、实施计划
阶段一：环境准备 (1天)
| 任务 | 时间 |
|---|
| 机顶盒装 Node.js 18+ | 10min |
| 下载 NapCat 源码 + 构建 | 30min |
| 扫码登录 NapCat，确认 WS 正常 | 10min |
| Python 环境 + sqlite-vec 依赖 | 10min |
| 拷贝 Embedding GGUF + DB + 模型到机顶盒 | 30min |
| 启动 Embedding Server 验证 | 5min |
阶段二：调度器开发 (2天)
| 任务 | 时间 |
|---|
| 搭建项目骨架 (package.json + 入口) | 30min |
| WebSocket 连接 NapCat + 心跳 | 1h |
| 消息接收解析 + 过滤 + 上下文追踪 | 1h |
| Timing Agent 规则引擎 | 1h |
| RAG 检索模块 | 1h |
| LLM API 调用模块 | 1h |
| 指令发送 (send_group_msg) | 30min |
| 配置化 (config.js) | 30min |
| 端到端集成调试 | 2h |
阶段三：Prompt 调优 (1天)
| 任务 | 时间 |
|---|
| 基础风格 Prompt 编写 | 1h |
| RAG 上下文注入格式调优 | 1h |
| 不同场景测试 (闲聊/吐槽/问问题) | 2h |
| 回复长度控制调优 | 1h |
| 反复迭代 | 3h |
阶段四：上线打磨 (1天)
| 任务 | 时间 |
|---|
| 实际群聊测试 (加小群试跑) | 半天 |
| 参数调整 (Timing 延迟/忽略概率) | 半天 |
| 错误处理加固 | 1h |
| 日志 + 监控 | 1h |
总计: ~5 天
六、开发周期估算
| 场景 | 新手 | 有经验 | 说明 |
|---|
| 全功能上线 | 7-10天 | 3-5天 | 含调参迭代 |
| 仅基础功能 (无 RAG 无 Timing) | 2-3天 | 1天 | 收发消息 + API 调用 |
| 仅搭建 NapCat + 收发 | 半天 | 1-2小时 | |
能最快跑通 demo 的方案: 装好 NapCat 后，写一个 50 行的 Node.js 脚本 (ws 库连 WebSocket → 收到消息 → 调 LLM API → 发回)，不做 RAG 和 Timing，1-2 小时就能让机器人在群里说话。
七、费用预估
| 项目 | 费用 |
|---|
| NapCat | 免费 (开源) |
| Embedding 本地推理 | 免费 |
| LLM API (DeepSeek) | ~¥1/百万 token，日常聊几乎免费 |
| 机顶盒电费 | 忽略不计 |
| QQ 小号 | 免费 (需自备) |
| 总计 | 几乎零成本 |
八、已有资产清单
已就绪 (可直接使用)
| 资产 | 路径/说明 |
|---|
| 聊天数据 | QQ: 378,044条 / 微信: 362,523条 |
| 嵌入数据库 | workspace/07_rag_embedding/stores/qwen_persona_rag.sqlite (189MB) |
| 嵌入模型 | D:\models\qwen3-embedding-0.6b-q8_0.gguf (610MB) |
| RAG 查询脚本 | scripts/query_rag.py (已修复 ANN 索引) |
| 聊天特征分析 | workspace/90_logs/聊天特征分析.md |
| 数据清理记录 | workspace/90_logs/数据清理记录.md |
| NapCat 源码 | D:\files\qwen-chat\napcat\ (已拉取) |
需准备
| 事项 | 说明 |
|---|
| LLM API Key | DeepSeek / 硅基流动 等 |
| 机顶盒系统确认 | 确认 Linux ARM64 版本 |
| QQ 小号 | 准备 2-3 个备用 |
| Node.js 18+ | 机顶盒上安装 |
九、文件清单 (Bot 代码)
~/qq-bot/
├── package.json # 依赖: ws + better-sqlite3 + sqlite-vec + openai
├── config.js # 配置 (API Key, 群号, 端口等)
├── index.js # 主入口 (约 50 行)
├── timing.js # 定时决策规则 (约 50 行)
├── rag.js # RAG 检索 (约 40 行)
├── llm.js # LLM API 调用 (约 30 行)
├── context.js # 对话上下文追踪 (约 40 行)
└── tools/
└── status.js # 状态检查脚本
十、最终建议
- 先跑通再优化 — 第一天先把 NapCat + 基础 LLM 回复跑起来，能说话再慢慢加 Timing 和 RAG
- 要个 API Key 先 — 没有 Key 什么都干不了，建议现在就去硅基流动注册拿免费额度
- 机顶盒先确认系统 —
uname -m 看是不是 aarch64，apt 能不能用
