QuickQuip — QQ 群聊妙语机器人

基于 NoneBot2 + OneBot V11 的 QQ 群聊互动机器人，用妙语让群聊更有趣。

QuickQuip（双 Q 谐音 = QQ + Quip/妙语）是一个轻量级、规则驱动优先的 QQ 群聊机器人。它通过精心设计的正则匹配和状态机自动给出幽默回复，同时支持按群启用 LLM 扩展，可通过指令或艾特触发多模型对话。

---

功能亮点

• 时区作息猜测 — 根据“早安”“晚安”等关键词反推全球时区，幽默揭穿群友真实所在地
• 复读检测与互动 — 检测群内复读行为，自动跟读、变体复读或刷屏警告
• 文字彩蛋规则 — 内置 25+ 条基于正则的趣味回复规则，支持优先级和加权随机，开箱即用《新三国》全套梗文。详见 docs/user/three-kingdoms-memes.md
• 语境感知回复 — 支持 regex_context（正则二次判定）和 llm_context（LLM yes/no 裁决）两种模式
• 群内小游戏 — Session 型对战：数字炸弹 / 21 点（Blackjack）/ 俄罗斯轮盘；持久 RPG：牛牛大作战（注册/打胶/击剑/排行）。全部接入金币经济系统，详见 docs/user/group-games.md
• 金币经济系统 — 每日签到累加连击、好感度成长、金币排行，所有对战游戏共用下注和结算。参数集中在 config/games.toml 配置
• 节日自动化 — 内置 6 个节日（公历+农历），自动切换 bot 语气并发送 persona 口吻问候
• 轻娱乐与互动 — /roll 掷骰子、/choose 随机选择、/fortune 每日运势、/vote 投票、/quote 语录收藏、/find 群聊搜索、/tell 离线留言
• 词云生成 — /wordcloud 按 today/week/month/year 四档生成群聊词云图片
• STS 公式化回复 — 《杀戮尖塔》梗能力：消息命中“xxx了”时按卡牌名公式回复，/turmfluch 一次性生成诅咒文案（v1.10）。详见 docs/dev/sts-formula.md
• LLM 扩展 — 兼容 OpenAI / Claude / Gemini / OpenAI Responses 四类协议，按群切换 provider/model/persona，支持工具调用、MCP 桥接、Skill 扩展包（部署者安装、AI 遇匹配请求自主激活）、图片理解、语音消息转写、联网搜索、故障机器人转写。详见 docs/dev/llm-module.md
• 思考档位控制 — /llm effort 按群或私聊切换思考档位，四协议统一适配；Web Admin 支持 provider 默认档与会话覆盖配置
• 请求身份与客户端 Profile — 会话身份跨轮和重启延续，四协议采用可编辑的客户端请求模板，支持渠道选择与本地覆盖；HTTP 调用追踪帮助关联请求。详见 请求指纹 Profile
• 群聊引用与艾特 — LLM 回复引用触发消息，@名字 可解析为真实艾特；按群开关、身份唯一解析与通知冷却共同控制互动
• 回复分段 — 可按群或私聊开启工具调用中的过程回复，以及最终长回复的自然段拆分；用 /llm delivery 设置发送方式
• 低频唤醒 — 按群配置唤醒延长、兴趣话题、相关性/答疑判定、无聊冒泡和兜底概率，所有入口受规则开关与限流保护
• LLM 用量/成本看板 — 全链路 token 计量与成本估算，按 provider/功能/模型/群/人格五维归因，Web Admin 提供用量面板与定价状态展示
• 每日播报与总结 — 按群开启早/中/晚报和每日 2000 字小作文，模型级联失败自动降级
• 群周报与月报 — 每周/每月自动生成上一周期的群聊回顾，周报压缩全周期聊天记录，月报按周分配输入预算，提炼热词趋势与群内大事记
• 多贴吧随机搬运 — 多来源帖子池维护，支持随机抽取和定时同步
• 多模态能力 — 图片生成、语音合成、语音识别、歌词创作与音乐生成、SVG 矢量图本地渲染（LLM draw_svg 工具）；模型在对话中生成的图片也会直接送达群聊。统一收口 config/generation.toml
• Web 管理后台 — LLM 配置数据库与分区工作台，草稿独立应用、保存时间与备注标记、Bot 实际加载状态，以及按渠道管理的模型价格；Vue 3 SPA 仪表板：统计、规则开关、唤醒管理、记忆编辑、对话浏览、配置在线编辑、Skill 管理、词云生成、用量看板、诊断工具、日志浏览。详见 docs/admin/web-admin.md
• 频率限制 — 滑动窗口限流保护，支持按群独立分桶（scope = "group"）或全局合并（scope = "global"）

完整命令速查：群聊见 docs/user/group-commands.md，私聊见 docs/user/private-commands.md。全部文档索引见 docs/index.md。

---

快速开始

环境要求

• Python ≥ 3.11
• NoneBot2 + OneBot V11 适配器
• OneBot V11 协议实现端（当前部署模板默认 LLBot 7.3.2；各适配器状态与选择见 docs/admin/onebot-adapters.md）

安装步骤

1. 克隆仓库

   git clone https://github.com/3aKHP/QuickQuip.git QuickQuip
   cd QuickQuip

2. 创建虚拟环境并安装依赖

   Linux／macOS（Bash）：

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install -e .

   Windows（PowerShell）：

   python -m venv .venv
   .venv/Scripts/python.exe -m pip install -r requirements.txt
   .venv/Scripts/python.exe -m pip install -e .

   后续示例使用 python。Windows 下可使用 .venv/Scripts/python.exe，或先激活 .venv/Scripts/Activate.ps1。

3. 配置环境变量

   参考 .env.example 在项目根目录创建 .env，按部署指南配置 OneBot 连接。以下是本机运行的基础配置片段：

   DRIVER=~fastapi+~websockets
   HOST=0.0.0.0
   PORT=8080
   SEARXNG_BASE_URL=http://127.0.0.1:8888

4. 可选：启动项目内置 SearXNG

   需先在 .env 中设置 SEARXNG_SECRET（compose 启动时必填）：

   docker compose -f docker-compose.example.yml up -d searxng

   注意：compose 解析时 QQ_ACCOUNT 为必填插值（llbot 服务 ${QQ_ACCOUNT:?}）；若 .env 未设置（仅本机源码跑 bot 的场景），需临时设置或注释掉 llbot 服务。

   默认暴露到 http://127.0.0.1:8888，开启 JSON 搜索接口。

5. 可选：准备 LLM 人格与密钥

   首次安装将 config/personas.example/ 复制为 config/personas/，可以先使用其中的默认人格。在 .env 中填写所选渠道的 API key；下面列出常用变量名，按选用的渠道填写：

   OPENAI_API_KEY=your_key
   ANTHROPIC_API_KEY=your_key
   GEMINI_API_KEY=your_key
   DEEPSEEK_API_KEY=your_key

   运行 python -m quickquip.llm.config_cli init 初始化 data/llm_config.db；已有 config/llm.toml 时会执行一次迁移并保留原文件和资产备份。首次启用在第 11 步进行，此时后台和 Bot 都已运行。旧配置升级与 JSON 导入见 LLM 配置管理。

6. 可选：启用图片/语音/音乐生成和语音识别

   复制 config/generation.toml.example 为 config/generation.toml，按注释填入 provider 和模型。旧多模态配置在首次迁移时提取到此文件；文件缺失时使用关闭状态的默认配置。

7. 可选：启用群聊唤醒

   复制 config/awakening.toml.example 为 config/awakening.toml，按群设置唤醒延长、兴趣话题、相关性判定、答疑判定和无聊唤醒参数。群内可用 /awakening status 查看生效状态。

8. 可选：启用多贴吧搬运

   安装 Playwright 浏览器：

   python -m playwright install chromium

   在 .env 中配置：

   TIEBA_ENABLED=true
   TIEBA_FORUM_KEYWORDS=贴吧名1,贴吧名2
   TIEBA_SYNC_INTERVAL_SECONDS=900
   TIEBA_BROWSER_HEADLESS=true

   首次使用前运行 python -m quickquip.tieba.login，或按 部署指南 完成贴吧登录态导出。

9. 可选：启动 Web 管理后台

   # 先构建前端（需 Node.js + pnpm）
   cd frontend && pnpm install && pnpm build && cd ..
   
   # 在 .env 中设置管理口令
   # WEB_ADMIN_PASSWORD=your-password
   
   # 启动管理 API
   python web_api.py

   访问 http://127.0.0.1:5104/ops/。详见 docs/admin/web-admin.md。

   保持后台进程运行，另开一个终端执行下一步；新终端也需使用第 2 步的虚拟环境，并进入项目根目录。

10. 启动机器人

python bot.py

保持此终端运行。在测试群发送“早安”，收到规则回复后即可继续设置 LLM。

11. 可选：在后台启用 LLM 并验证第一条回复

    用根 .env 中的 WEB_ADMIN_PASSWORD 登录后台，按首次启用 LLM添加一个渠道和模型、选择默认人格，保存草稿并应用到 Bot。等待状态条显示 Bot 已加载刚发布的版本，再由群管理员发送 /llm on，随后发送 /ai 请回复“测试成功”。收到 AI 回答即完成首次配置；该提问会调用所选模型 API，按渠道计费。

Windows 懒人包

Release 中的 QuickQuip-*-windows-x64.zip 内置 Python、依赖、Web Admin 前端和 Playwright Chromium。解压后运行 start.bat，首次运行会从示例文件生成 .env、常用 config/*.toml、config/personas/ 与资料文件并暂停，LLM 数据库由初始化／迁移流程创建；请至少在 .env 中填写 WEB_ADMIN_PASSWORD、OneBot 连接配置和需要的 API key，再次运行 start.bat 启动。

保持启动窗口运行，浏览器打开 http://127.0.0.1:5104/ops/，输入刚设置的管理口令。启用 AI 对话时接着按首次启用 LLM操作。懒人包中的 Python 命令使用解压目录内的 python\python.exe。

首次运行注意：

• SmartScreen 提示：浏览器下载的 ZIP 带 Mark-of-the-Web，解压后首次运行 start.bat（或内嵌 python）可能弹出“Windows 已保护你的电脑”——点“更多信息”→“仍要运行”即可；用命令行 tar 解压则不会传播该标记。
• 停止方式：前台控制台（QQ Bot）按 Ctrl+C；Web Admin 是后台进程，关掉管理窗口不会带走它，需在 PowerShell 执行 Get-CimInstance Win32_Process -Filter "Name='pythonw.exe'" | Where-Object { $_.CommandLine -match 'web_api.py' } | ForEach-Object { Stop-Process -Id $_.ProcessId }。
• 运行期间任务栏会有一个最小化的“QuickQuip Admin”cmd 窗口（Web Admin 的启动壳），属正常现象，随 Web Admin 退出自动关闭；Web Admin 运行日志追加在 data\web-admin.log（无轮转）。

升级涉及旧 data/daily_msgs/、data/wordcloud_msgs/ 历史时，在解压目录运行 python\python.exe scripts\backfill_chat_archive.py --dry-run 预览，再去掉 --dry-run 回灌。脚本分别统计新增、归因回填、已存在、跳过和写入失败；存在写入失败时返回非零。确认失败为零、归档数量符合预期后再清理旧 JSONL。

生产部署模板位于 prod.example/；公开分发镜像位于 ghcr.io/3akhp/quickquip。如需使用私有 compose、部署脚本和巡检脚本，先复制为 gitignore 的 prod/，应用密钥仍统一维护在根目录 .env。详见 docs/admin/deployment.md。

运行测试

pip install -r requirements-dev.txt   # 测试依赖（首次）
pytest -n auto

---

架构

src/
├── quickquip/
│   ├── adapters/nonebot/ ← 生命周期、消息入口、命令注册
│   ├── app/              ← 应用级消息管线与共享状态装配
│   │   └── web/          ← Web 管理后台 FastAPI + Vue 3 SPA
│   ├── chat/             ← 规则回复（复读、接龙、彩蛋、节日、时区、统计）
│   ├── games/            ← 游戏模块（registry、scores、economy、各游戏实现）
│   ├── llm/              ← LLM 运行时（provider、MCP、Skill 扩展、工具调用、记忆）
│   ├── generation/       ← 多模态产出（图片、语音、音乐、SVG 渲染）
│   ├── tieba/            ← 贴吧爬虫与帖子池
│   ├── search/           ← 联网搜索后端
│   ├── sts/              ← 杀戮尖塔公式化回复（词表 + 公式）
│   └── common/           ← 限流、去重、持久化、消息缓冲
└── plugins/              ← NoneBot2 插件入口（re-export 薄层）

消息流：bot.py → plugins（NoneBot2 发现）→ adapters/nonebot（matcher 分发）→ app（管线装配）→ chat / games / llm 等子系统。

回复优先级从高到低：复读 → 好姐姐接龙 → 自定义接龙 → Session 游戏 → 彩蛋规则 → 语境规则 → 时区猜测 → STS card_le（链尾）。每个环节受群级规则开关和滑动窗口限流保护。

目录约定：源码位于 src/（src layout），包路径 quickquip.* 不变；src/plugins/ 是 NoneBot2 插件发现入口，只做 re-export；开发时需 pip install -e .（可编辑安装）。config/ 下 .example 文件入版本控制，无后缀为部署私有配置。游戏参数集中在 config/games.toml。

详细结构见 docs/dev/architecture.md。

---

文档

文档	说明
docs/index.md	文档总导航
docs/user/group-commands.md	群内指令速查
docs/user/private-commands.md	私聊指令速查
docs/admin/deployment.md	云端部署指南
docs/admin/onebot-adapters.md	OneBot 适配器状态与选择
docs/admin/configuration.md	完整配置参考
docs/admin/web-admin.md	Web 管理后台
docs/admin/skills.md	Skill 系统部署与安全模型
docs/admin/mcp-servers.md	MCP Server 接入指南
docs/admin/sensitive-filter.md	敏感词过滤器
docs/admin/migration-napcat-to-llbot.md	NapCat → LLBot 历史迁移记录
docs/dev/llm-module.md	LLM 模块详解
docs/dev/regex-tutorial.md	正则表达式教程
ROADMAP.md	演进路线
CHANGELOG.md	变更记录

---

许可证

本项目基于 WTFPL 发布 — Do What The F*ck You Want To。Copyright © 2026 3aKHP。

---

贡献

欢迎提交 Issue 和 Pull Request！添加新的回复规则只需编辑 config/chat_rules.toml（参见 config/chat_rules.toml.example 了解格式），无需改动消息管线本身。