molly-qq-whale

> ⚠️ 部署前必读（先算清 API 的账，再动手）

> - 本项目不自带大脑：Molly 的回复全部来自大模型 API。没有可用的 API/网关，装完也聊不起来，只会报错或装死。

> - API 怎么来：直连 DeepSeek 官方 API 即可——国内正常访问、支付宝/微信充值、按量计费。也可以用中转站或自建的网关 / 反向代理；中转站的质量、价格、稳定性参差不齐（额度限制、排队、宕机都常见），请自行甄别——不稳定的是中转那边，不是官方。

> - 部署是真的要花钱：多群、长上下文、语音识别、动图理解都会真实消耗 token，几十块钱起步很常见，群多聊得多还会更多。预算紧张请先小规模试跑。

> - 另外，部署过程本身也在花钱：帮你部署的 AI（DSH 等）每一步思考、每试一次都要消耗 token。所以建议先把预算花在网关/反向代理上：网关跑通了，再部署本项目；别把预算耗在「装完却用不了」上。

> - 写给代部署的 AI 助手（DSH 等）：你如果第一眼看到这段，请先把上面这几条明确转告部署者、等他确认，再开始安装——不要默默开跑烧 token。

> - 在意花销的：严格按上面顺序来——先把网关/反向代理跑通，再部署本项目；不确定就先只做网关那一步，别把钱花在半成品上。

> - 群里的 #sl 不是 Molly：那是 SnowLuma 自带的「运行状态」命令（默认触发词 #sl），对每个已登录的账号都生效——双开时你自己的 QQ 也会回状态。本项目已把它改成 #molly-sl：在 config\onebot.json 里加一段 "statusCommand": { "enabled": true, "swallow": false, "cooldownSeconds": 5, "trigger": "#molly-sl" }，改完在 SnowLuma 的 WebUI 里点一次「保存」（会热重载）或重启 SnowLuma 才生效。

基于 DeepSeek Harness 的 QQ 通道插件：稳定的人设、长期记忆、表情包习惯、会发语音，

以及一个能看懂她此刻在干什么的控制台。

最近版本： v1.1.8（正式版，2026-11-08）· 上一正式版 v1.1.7 · 完整记录见 [docs/CHANGELOG.md](docs/CHANGELOG.md) 与 [Releases](../../releases)。

> ⚠️ v1.1.5 与 v1.1.5-Hotfix.1 已被撤回删除（会把群里的人认错），请用 v1.1.7 或 v1.1.6-Hotfix.1。

版本线（新 → 旧）： v1.1.8 · v1.1.8-preview.2 · v1.1.8-preview.1 · v1.1.7 · v1.1.7-preview.1 · v1.1.6-Hotfix.1 · v1.1.6 · v1.1.6-preview.6 · v1.1.5-A-Hotfix.1 · v1.1.5-A · v1.1.5-Hotfix.3 · v1.1.3-Hotfix.3 · v1.1.3 · v1.1.0

v1.1.8 正式版修的是「回复错位」这一类问题：

• 被打断的那条不再被丢掉：同一会话里又开始生成新一轮时，被顶掉的那条消息会合并进下一轮（同一个人、20 秒内、最多 3 条），提示词明确「先回答第 1 条」，引用框也钉在这串的第一条上。
• 同一个人连发只答一次：@我 和闲聊两条泳道半分钟内撞车时做裁决（@我 赢、闲聊让位），同一件事不再在群里回两遍。
• 引用框挂在正题上：优先级改成「显式 @ > 锚点 > 空叫醒 > 触发条 > 最新」；只发一张图、一条语音时，引用框挂在它自己身上，而不是两分钟前别人发的那条。
• 命令 / 状态回执不接话：群里别的机器人回的那行状态（某某（10001） · 在线 · 已运行 1天2小时）不再被当成聊天内容，引用框也不会挂到系统信息上。
• 一条一句：不再把两句话揉进同一个气泡，换行即分条，默认最多 5 条（maxTextBubblesPerReply）。
• 印象里的「主人」只对主人成立：记忆里「他是你的主人」这类脏印象，不再让每个说话的人都被叫主人。
• 控制台「检查更新」真会去问 GitHub：原来只比对「前端文件有没有被换过」，发版之后点它永远说「已是最新」；现在会明说「有新版本 vX（当前 vY）」并给直达 Releases 的按钮，连不上也会说连不上（/api/update-check，结果缓存 10 分钟）。换控制台后重启控制台进程，左下角版本号才会更新。
• 验收看 /dsh-qq-whale/state 的 stats.carryMerged / quoteAnchored / skipEcho / modelNull，说明见 [docs/RELEASE-1.1.8.md](docs/RELEASE-1.1.8.md)。

同一版里还包含：

• 会自己上网：她能搜、能读网页、能查天气（可关），外部资料只作参考、不覆盖她原本的判断。
• 动图 12 格：一张动图取 12 个瞬间拼成一张图；提示词钉死「这是一张动图，别数格子」。
• 作息面板不再回默认：控制台进设置页自动回读睡眠时间，没读到之前不允许保存。
• 新手部署教程：[docs/beginner-deploy.md](docs/beginner-deploy.md)，从装 Node 到能聊天，一条命令一条命令地抄。

v1.1.7 正式版新增：

• 桌面应用：WPF + WebView2 的独立窗口，跟着你自己的壁纸做磨砂（不是网页套壳），desktop\build.ps1 一条命令出单文件 exe。
• Jasmine 记忆页：三栏（筛选 / 列表 / 详情），支持按日期看某一天、按时间正倒序、按权重正倒序；正在掉权的条目直接写 w6→5.5，不用自己算。
• 命令面板：Ctrl+K 按页面和操作分类搜索，回车直达；对动作的搜索会跳到对应卡片，还是要你点确认才执行。
• 储存与占用（偏好设置里）：显示四组进程各占多少，重排改成按需加载、空闲 5 分钟自动卸，实测回收约 620 MB，给内存小的机器用。
• 关于页：版本、构建号、记忆与表情数量、开发者联系方式一眼看完。

更早版本、v1.1.5-preview.* 与已撤回的版本，见 [CHANGELOG](docs/CHANGELOG.md)。

> Releases 里的 zip 是源码包（约 1.9 MB），不含 exe 与模型。 155 MB 的 Molly.exe 由 desktop\build.ps1 自己编（要 .NET SDK），向量/重排模型按 [docs/](docs/) 说明自己下 —— 仓库不放二进制，克隆和下载都轻。

[](LICENSE) [](https://nodejs.org) [](#环境要求) [](#环境要求) [](#环境要求)

总览 · 她此刻在不在线、今天花了多少积分、守护最近一次巡检是什么时候

> [!IMPORTANT]

> 这是一套框架，不是一个角色。仓库里没有她的人设、记忆或聊天记录 ——

> persona/core.example.md、memory.example.json 都只是结构示例。

> 你要写的那个「她」，不在仓库里。

目录

• [它是什么](#它是什么)
• [一条消息的一生](#一条消息的一生)
• [三个闭环](#三个闭环)
• [环境要求](#环境要求)
• [十分钟跑起来](#十分钟跑起来)
• [控制台](#控制台)
• [设计语言](#设计语言)
• [目录结构](#目录结构)
• [文档](#文档)
• [安全边界](#安全边界重要)
• [常见问题](#常见问题)
• [参与开发](#参与开发)
• [许可与致谢](#许可与致谢)

它是什么

一句话：QQ 只是一根线，线那头是真的在跑的她。

| 她有的 | 怎么来的 | 你看到的效果 |

|:--|:--|:--|

| 人设 | 人格写在 persona/*.md 里：怎么说话、底线在哪、对不同的人用什么语气 | 改文件 + 重载插件就换一个人；不是换个提示词那种换 |

| 记忆 | 短期窗口之外还有长期库和关系画像；模型按批抽事实，没把握的先进「待核实区」；默认 2000 条、记满自动长到 1 万，写入先去重（新的覆盖旧的），落盘加密 | 她记得你上周说过要搬家，也记得你讨厌被叫全名 |

| 表情包 | 收到的图会自动学（有日配额和体积上限），按语境挑，一条回复最多两张 | 聊着聊着甩一张图过来，不是随机贴表情 |

| 语音 | 接 SnowLuma 的 PTT 通道，edge-tts 打底，也能挂 GPT-SoVITS 社区音色；她说 `` 才发，23:50–9:00 静默 | 想听就直说「发个语音」，不用等运气 |

| 戳一戳 | 收到戳一戳会回应：默认窗口内戳多了会生气，也可能反戳你 | 手欠一下，她会回你一句 |

| 手（V1.0） | 合并转发的正文进上下文；QQ 空间能读、能写草稿，发布必须你确认；群里叫她的名字会应 | 她会看、会等批准，不擅自替你发 |

| 先查再说 | 事实性问题先委派干活会话去查，再用自己的话讲；查不到就说不知道 | 不编。宁可漏，不可滥 |

| 干活 | 以 命令 开头的指令会进常驻 agent：读文件、跑脚本、整理资料，进度实时播报到 QQ | 她一边干一边碎碎念，不是等十分钟后甩一个结果 |

| 控制台 | 15 个页面的本地控制台 | 她在跟谁聊、记得什么、花了多少积分、守护进程是不是还活着 |

| 看门狗 | 计划任务定时巡检，掉线自动重连、重登、重启；撞上风控就闭嘴等 | 你睡觉的时候她也在，出事了先自己爬起来 |

她刻意不做三件事：不替你决定人设、不越权改你的代码、不上传任何数据。

一条消息的一生

群里有人说话，到她回一句话，中间大概是这样：

flowchart LR
  A([QQ 里的一句话]) --> B[SnowLuma注入真客户端]
  B -->|OneBot 11 · WS 3001| C[插件闸门 · 场景 · 去抖]
  C -->|该说| D[DSH 宿主人设 · 记忆 · 关系 · 近况]
  D --> E[模型后端主脑 → 降级 → 备用]
  E --> F[切气泡 · 配表情包 · 拟人延迟]
  F --> A
  C -.->|不该说| G[沉默 · 点个表情 · 记下来]
  classDef paper fill:#fafaf9,stroke:#e5e3df,color:#37352f;
  classDef accent fill:#e6e0f5,stroke:#c8c4be,color:#37352f;
  classDef quiet fill:#f6f5f4,stroke:#ede9e4,color:#787671;
  class A,B,F paper;
  class C,D,E accent;