dsh-qqbot-muu

dsh-qqbot-muu

@zaofan/dsh-qqbot 的扩展包 + 补丁集：把社区插件补成一个能长期养的 QQ 助手 —— 记得住人、分得清群、能自己写口播视频、有一个不会长歪的 2D 鲸鱼娘，还有一个主人说了算的 B 站运营流程。

_{界面截图含真实群名/昵称，默认不随仓库发布；需要市场截图时用本地脱敏版。}

Node ≥ 22.5 · MIT · DSH 桌面端插件

这是什么

一个跑在你自己机器上的 QQ 助手能力包。它不训练模型、不上传数据， 只是把「记忆、语气、出片、运营」这四件事用本地 SQLite + 本地小模型 + 云端算力拼成一条能跑的流水线：

• 记忆：两层记忆（个人层跨群统一 / 群层物理隔离）+ 类海马体的检索与巩固层
• 说话：人格与世界书注入、本地小模型代答与单脑仲裁、TTS 发件箱、表情包准入
• 出片：文案 → 分镜 → 出图质检 → 配音 → 字幕 → 拼片 → 草稿，主人一句「通过」才发
• 运营：B 站扫码、单条分享卡片、AI 写评论草稿、审核后发送、数据留档

它不是：托管服务、SaaS、也不需要你的账号密码 —— 只有本机 Cookie 和本机数据库。

功能

记忆与认知

说话与分发

聊天目标列表也吃同一份台账：known-chats 除了 known-chats.jsonl / memory.db / local-answer-log.jsonl， 还会扫 .qqbot/msg-history/ 下的每个 group_* / c2c_* 目录，把「台账里有历史、但 known-chats 里没有」的人和群补进浮窗的下拉列表—— 所以登录后打开浮窗，之前记过的私聊和特别关心对象都能直接选到，不用等它再发一条消息。

⚠️ 但有件事补不了：机器人离线期间别人发的消息。QQ 官方机器人接口没有「拉历史消息」的 API， 收不到就是没收过，本地也不会有副本。想让那段也不丢，只能让 QQ 自己保持登录（手机上把机器人号挂着）， 或者事后用「消息管理器 → 导出消息记录」把那段 .txt 导进来（见下方 .bak 一节）。

视频创作

运营

安装

从插件市场 / GitHub 装壳（让 DSH 能识别并加载本包）：

dsh plugin add github:wuwo1979/dsh-qqbot-muu#main

装扩展本体（把能力文件铺进 bot 数据根）：

node install.mjs --data-root "D:\你的bot数据目录"
ollama pull qwen2.5vl:3b        # 表情打标 / 识图
ollama pull nomic-embed-text    # 向量检索（可选，缺了自动退回 lexical）

打客户端补丁（可选，按需）：

node qqbot-mod/patches/add-memory-panel.mjs --apply   # 记忆页
node qqbot-mod/patches/ui-theme-v2.mjs      --apply   # 设计令牌 / 深色 / 记忆页卡片化
node qqbot-mod/patches/merge-group-tabs.mjs --apply   # 群组管理子标签
node qqbot-mod/patches/unify-fam-ui.mjs     --apply   # 熟识度统一入口

每个补丁都支持 --check（只看会改什么）、--apply、--revert，并且是幂等的。 客户端补丁改完在 DSH 里按 Ctrl+R 重载；服务端补丁重启桌面端。

升级后补丁被冲掉？用 overlay 一键装回（推荐）：

@zaofan/dsh-qqbot 自动升级会生成新的 generation 目录，里面是干净的官方文件 —— 之前打的补丁全部消失，表现为"记忆页没了、浮窗切 tab 会跳大小"。 qqbot-mod/patches/live-overlay/ 保存了「官方同版本原文件 + 我们的定制版」并做三路合并，只在上游真正改到同一行时才冲突：

node qqbot-mod/patches/live-overlay/install.mjs --check   # 看完再装
node qqbot-mod/patches/live-overlay/install.mjs --apply   # 装进当前 live generation
node qqbot-mod/patches/live-overlay/capture.mjs           # 定制有更新后，把 live 回写成新的 ours/

装完 / 升级完都要重启宿主（/bot-restart 或重启 DSH 桌面端），再在页面上 Ctrl+F5；只刷新页面的话，服务端路由还是旧的。

依赖：

• Node.js ≥ 22.5（用到内置 node:sqlite）
• DSH 桌面端，已安装 @zaofan/dsh-qqbot
• Python + Pillow（只有文字动效 / 角色动效 / 出图质检需要；缺了会自动降级并如实记一条 warning）
• ffmpeg（音效合成与拼片；找不到会静默降级为静音）

配置速查

{ "defaultTier": "normal", "priority": ["群openid"], "priorityPeople": ["用户openid"], "normal": [], "profileInNormal": false, "digestNormal": false }

隐私

仓库内不包含任何真实 openid / 群号 / 聊天记录、B 站 Cookie、DeepSeek Key、 memory.db、运营产物、表情包图库与索引、模型缓存与日志。

.gitignore 是白名单式的（* 起手再 ! 放行），只有源码、补丁、脚本、文档与截图能进仓库； install.mjs 也只复制代码与默认配置，不复制 data/、.state/、*.bak。

导入历史聊天记录时，脱敏发生在入库之前（不是事后补救）：手机号保留前 3 后 4、身份证前 6 后 4、 邮箱只留首字符、银行卡只留后 4 位、裸数字串按 QQ 号打码（年份与小额金额不受影响）。 可以先用 --dry-run 看筛出来哪些句子，确认后再写库。

# 只看报告，不写库
node qqbot-mod/scripts/qq-import.mjs --file 聊天记录.txt --dry-run

# 只导入和某个人的对话（QQ 号最准，不会和同昵称的人串号）
node qqbot-mod/scripts/qq-import.mjs --file 全部消息.txt --peer 123456789 --self-uin 987654321 --dry-run

# 完整归档：整段对话原样进聊天台账，再用本地模型重建这个人的历史印象卡
node qqbot-mod/scripts/qq-import.mjs --file 全部消息.txt --peer 123456789 --self-uin 987654321 --archive --digest

导入会同时产出三种东西，粒度不同、互不替代：

1. chat 台账 —— 原话，可重放、可事后换模型重建记忆；
2. person:<id> 记忆 —— 筛掉寒暄后的句子 + 一条 impression（TA 是什么人）；
3. person:<id> 里的 relation —— 一条"我们怎么相处"：轮次、谁先开口、回得多快、共同话题。 只靠"TA 说了什么"看不出关系，这一条是双方视角。

归档进台账的 src='import' 行不吃 60 天保留窗。否则导进来的旧记录下次日维护就被当过期数据删掉。

node qqbot-mod/scripts/graph-enrich.mjs --scope person:qq12345 --dry-run  # 看还有多少条待补图
node qqbot-mod/scripts/graph-enrich.mjs --scope person:qq12345 --limit 50 # 本地模型补三元组

补图只往图谱加边、不改正文，全在本机跑（local-llm 的 Ollama / OpenAI 兼容端点）， 聊天记录不出机器。模型没开时脚本会立刻退出并说明原因，不会空转。 彻底删除一个 scope 的全部记忆用 purgeScope（代码接口，含索引与画像）， 导出用 exportScope，两者都会在 {dataRoot}/.qqbot/memory/_audit.jsonl 留痕。

为什么导不进 .bak？—— 密钥根本拿不到

QQ NT 的聊天库是 nt_msg.db（外加若干同族库），SQLCipher 加密。密钥不是写死在文件里的常量： 它在 QQ 登录时由服务端下发，只存在 QQ 进程内存里，而且随版本/账号变化。要"拿到密钥"等于去 dump 运行中的 QQ 进程内存再逆出派生逻辑 —— 这既不稳定（一升级就废），也不该由本插件做。所以本插件不解密 .bak / nt_msg.db，也没有任何"密钥获取"功能：这不是没做完，是这个方向本身不通。

能走通的只有官方导出这条路：

1. PC 版 QQ → 左下角 ≡ / 设置 → 消息管理器（老版本在「工具 → 消息管理器」）；
2. 左侧选中群或好友，等它把历史同步下来（首次打开会转一会儿）；
3. 右上角 导出消息记录 → 选 .txt（推荐，纯文本最稳）或 .mht；
4. 浮窗 → 记忆 → 「📥 导入历史」，把导出文件的绝对路径填进去（带空格要加引号）。

找不到"导出消息记录"？多半是这个会话还没落到本地库 —— 在消息管理器里点开它、往下翻到底， 再试；仍没有就是精简版/渠道版 QQ，换官方 PC 版 NT 再导。手机端可以先「聊天记录迁移」到电脑。

--file 除了 .txt / .mht，也吃任意 .json；面板里的 --peer 输入框用来只捞某一段对话。

本地语音（GPT-SoVITS / Breeze TTS 2 / IndexTTS-2.5）

默认走 edge-tts（在线、零本机占用、音色稳定，但音色是"播音腔"）。想换成自己训练的模型或 本地推理，改用 provider:"http"——插件只认 OpenAI 形状的 POST /v1/audio/speech， skills/local-tts/adapter/server.py 就是那层适配（纯标准库，零第三方依赖），把 GPT-SoVITS 的参数式 /tts、Breeze 的多部分上传、IndexTTS 的 /tts 全部翻译成同一个接口， 并保证吐出真 mp3。

先看这张表再选（浮窗「设置」页的引擎表就是它的实时版：端口亮不亮、模型多大、现在选的是哪套）：

分工建议：聊天走 gsv，视频配音走 index（narrate_footage.py --voice xiaolan_emo 已直通）。

# 1) 起服务（显存 6GB 只能二选一，默认 breeze）
powershell -ExecutionPolicy Bypass -File skills\local-tts\scripts\start-services.ps1 -Backend breeze
powershell -ExecutionPolicy Bypass -File skills\local-tts\scripts\start-services.ps1 -Backend gsv
#    停止：同一个脚本加 -Stop

# 2) 换引擎有两条路
#    a. 浮窗「设置」页 → 引擎表 → 点「用这个方案」（走 POST /api/qqbot-settings/tts-engines，直接改 voice-config.json）
#    b. 手改 dshqqbot\.qqbot-extensions\voice-config.json（改一次就行）
#       "provider": "http",
#       "endpoint": "http://127.0.0.1:9881/v1/audio/speech",
#       "model":    "gsv",              ← gsv / breeze / index
#       "voice":    "xiaolan"           ← gsv: xiaolan|gentle；breeze: breeze|breeze_design；index: xiaolan_emo|xiaolan_emo_soft

几个必须知道的点：

• Breeze 也吃 OpenAI JSON：POST /v1/audio/speech + response_format:"mp3" 会直接回 64kbps / 24kHz 的真 mp3（裸 24k s16le PCM 只出现在 multipart 路径）。它缺的是克隆音色注册—— 想用自己的参考音得先 POST /v1/voices（ref_audio + ref_text + name），之后用 voice:"<name>"。 适配层把这两步都做了，所以插件侧还是填一个 endpoint 就够。
• Breeze 慢：q8_0 在 3060 上约 0.10× 实时（≈820ms/帧，瓶颈是 depth decoder 的 15 次串行小 matmul）， 适合"生成一段展示音频"，不适合聊天随口回。日常对话用 GPT-SoVITS 或先留 edge。
• 探活口径：Breeze 是 GET /health（/v1/model 是 404），GPT-SoVITS 是 /tts； 适配层的 /health 会分别探这些上游，reachable:false 只代表上游没起，不代表适配层坏了。
• 合成失败会往 .qqbot/tts/failures.log 记一行（含 bytes / exit code / 原因）， 0 字节不再"悄悄删掉"。
• voiceProfiles 里的 size 写的是在线合成、本地无模型——别把它当成"模型 0MB"。
• 9881 不用手动起：插件每次合成前先探端口，没开就自己 detached 拉起 adapter/server.py --manage（空闲 3 分钟回收显存）。群里再也不会出现「tts-http: fetch failed」。
• 显存被聊天模型占着怎么办：6GB 卡上 qwen2.5:7b 常驻能吃掉 4.2GB，GSV 要 3.4GB 就起不来。 插件遇到「显存不够」会先让 Ollama 把模型吐出来（keep_alive:0，下次聊天它自己会重载，几秒）， 再重试一次；要是还腾不出来（浏览器 + QQ + 桌面端能占掉 3GB 多），就临时回退 edge 在线语音把这句话说出来， 并在 failures.log 记 local-vram-short → 已回退在线语音。人在群里听到的是声音，不是报错。
• 工具/语音报错不进群：失败的原文只写 .qqbot/tool-errors.jsonl，群里由她自己用一句人话圆过去。 想恢复"把报错直接发到群里"的旧行为，设环境变量 QQBOT_TOOL_ERRORS_ON_QQ=1。

本地模型什么时候在显存里？

默认策略是平时不在：聊天回复、向量化（nomic-embed-text 那个 274MB）都带 keep_alive:0， 生成完就离开显存；看门狗每 20s 看一眼，没 pin 且闲置超过 60s 就把 Ollama 里的模型整体卸载。 需要用的时候再冷启（qwen2.5:7b 约 5~6s，qwen2.5:1.5b 约 2s）。

要「借住」一段时间的场景用 pin：

配置在 dshqqbot/.qqbot-extensions/local-llm-config.json：

{
  "model": "qwen2.5:7b",
  "gameModel": "",          // 给游戏单独指定模型；留空=跟 model 同一个
  "keepAlive": "0",         // 单次请求的 keep_alive，0 = 用完就走
  "residency": {
    "enabled": true,
    "idleUnloadSec": 60,    // 没 pin 又闲置多久就整体卸载
    "pinnedKeepAlive": "10m", // 有 pin 期间单次请求的 keep_alive
    "looseKeepAlive": "0",
    "watchMs": 20000        // 看门狗间隔
  }
}

想让游戏又快又不太笨："gameModel": "qwen2.5:1.5b"（986MB，冷启 2s，出题偶尔跑偏但有本地题库兜底）； 想让它更会聊：留空走 qwen2.5:7b。显存只有 6GB 时别同时让别的程序占着。

库体检与维护

记忆库有几种"不报错、只悄悄变差"的坏法：索引表没建上（关键词/实体/图谱三路召回全哑， 只剩向量）、WAL 没检查点（备份可能是残的）、prune 删了行但文件不缩小、一直没备份。 一个脚本全查一遍：

node qqbot-mod/scripts/mem-maintain.mjs --data-root <数据目录>              # 只体检，只读
node qqbot-mod/scripts/mem-maintain.mjs --data-root <数据目录> --fix        # 检查点 + 备份 + 补索引
node qqbot-mod/scripts/mem-maintain.mjs --data-root <数据目录> --fix --vacuum --keep 5

体检会明确回答「倒排覆盖 487/489」「缺表: mem_edge」「碎片率 34%」这类问题， 而不是给一个"正常"。日常备份不用手动：chatlog.dailyBackup 会在每日维护窗口 把库 VACUUM INTO 到 .qqbot/backups/，保留 backupKeep 份。

目录

dshqqbot/.qqbot-extensions/   扩展本体（inbound / outbound / hooks / tools / lib）
qqbot-mod/patches/            客户端与服务端补丁（--check / --apply / --revert）
qqbot-mod/patches/live-overlay/  官方原文件 + 定制版 + 三路合并安装器（扛插件自动升级）
qqbot-mod/scripts/            自检脚本（`node qqbot-mod/scripts/run-all-tests.mjs` 一把跑完 51 个套件，失败详情落 tmp/test-failures/）
qqbot-mod/persona/            人格与世界书（唯一事实源）
assets/char/pose/             鲸鱼娘五姿态（720×980 透明 PNG + sprite.json，video.character 直接用）
assets/char/src/              出图原图（带底色，供重抠/换姿态）
assets/char/whale/            同配色纯鲸鱼本体（贴纸/小图标用）
skills/video-frame-render/    逐帧拼视频的 skill（Pillow 画帧 + ffmpeg 编码，省 token）
skills/local-tts/             本地 TTS 适配层（OpenAI 形状 /v1/audio/speech → GPT-SoVITS / Breeze / IndexTTS）
skills/voice-sing/            唱歌换声（Demucs 拆轨 → RVC 换声 → 混音；带 sources.json 出处台账）
docs/publish-flow.md          第一条视频从选题到投稿的完整流程（首跑记录，含踩过的坑与验收口径）
assets/                       README 截图与图标
submission/                   插件市场提交条目
install.mjs                   把扩展装进任意 bot 数据根

市场收录

• 条目：submission/wuwo1979__dsh-qqbot-muu.yml（category: usage）
• 截图：screenshots.json（仓库根，相对路径，最多 8 张）
• 本地预检：node scripts/check-submission.mjs —— 校验 YAML 字段、dsh.bundle 声明、图标与截图规则，提交前先跑一遍就不会再被 CI 打回来

致谢与许可

• 基础插件：@zaofan/dsh-qqbot（客户端 client/qqbot-settings.js、dist/features/*）
• 本项目在其之上补扩展与补丁，与插件作者无隶属关系
• MIT