molly-qq-whale

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

• 本项目不自带大脑：Molly 的回复全部来自大模型 API。没有可用的 API/网关，装完也聊不起来，只会报错或装死。
• API 怎么来：直连 DeepSeek 官方 API 即可——国内正常访问、支付宝/微信充值、按量计费。也可以用中转站或自建的网关 / 反向代理；中转站的质量、价格、稳定性参差不齐（额度限制、排队、宕机都常见），请自行甄别——不稳定的是中转那边，不是官方。
• 部署是真的要花钱：多群、长上下文、语音识别、动图理解都会真实消耗 token，几十块钱起步很常见，群多聊得多还会更多。预算紧张请先小规模试跑。
• 另外，部署过程本身也在花钱：帮你部署的 AI（DSH 等）每一步思考、每试一次都要消耗 token。所以建议先把预算花在网关/反向代理上：网关跑通了，再部署本项目；别把预算耗在「装完却用不了」上。
• 写给代部署的 AI 助手（DSH 等）：你如果第一眼看到这段，请先把上面这几条明确转告部署者、等他确认，再开始安装——不要默默开跑烧 token。
• 在意花销的：严格按上面顺序来——先把网关/反向代理跑通，再部署本项目；不确定就先只做网关那一步，别把钱花在半成品上。

基于 DeepSeek Harness 的 QQ 通道插件：稳定的人设、长期记忆、表情包习惯、会发语音， 以及一个能看懂她此刻在干什么的控制台。

最近版本： v1.1.5-A-Hotfix.1（推荐）· 完整记录见 docs/CHANGELOG.md 与 Releases。

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

版本线（新 → 旧）： v1.1.5-A-Hotfix.1 · v1.1.5-A · v1.1.5-Hotfix.3 · v1.1.5-Hotfix.2 · v1.1.3-Hotfix.3 · v1.1.3-plus.2 · v1.1.3 · v1.1.0

更早版本、v1.1.5-preview.* 与已撤回的版本，见 CHANGELOG。

[!IMPORTANT] 这是一套框架，不是一个角色。仓库里没有她的人设、记忆或聊天记录 —— persona/core.example.md、memory.example.json 都只是结构示例。 你要写的那个「她」，不在仓库里。

<b>目录</b>

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

它是什么

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

她有的	怎么来的	你看到的效果
人设	人格写在 persona/*.md 里：怎么说话、底线在哪、对不同的人用什么语气	改文件 + 重载插件就换一个人；不是换个提示词那种换
记忆	短期窗口之外还有长期库和关系画像；模型按批抽事实，没把握的先进「待核实区」；默认 2000 条、记满自动长到 1 万，写入先去重（新的覆盖旧的），落盘加密	她记得你上周说过要搬家，也记得你讨厌被叫全名
表情包	收到的图会自动学（有日配额和体积上限），按语境挑，一条回复最多两张	聊着聊着甩一张图过来，不是随机贴表情
语音	接 SnowLuma 的 PTT 通道，edge-tts 打底，也能挂 GPT-SoVITS 社区音色；她说 <voice> 才发，23:50–9:00 静默	想听就直说「发个语音」，不用等运气
戳一戳	收到戳一戳会回应：默认窗口内戳多了会生气，也可能反戳你	手欠一下，她会回你一句
手（V1.0）	合并转发的正文进上下文；QQ 空间能读、能写草稿，发布必须你确认；群里叫她的名字会应	她会看、会等批准，不擅自替你发
先查再说	事实性问题先委派干活会话去查，再用自己的话讲；查不到就说不知道	不编。宁可漏，不可滥
干活	以 命令 开头的指令会进常驻 agent：读文件、跑脚本、整理资料，进度实时播报到 QQ	她一边干一边碎碎念，不是等十分钟后甩一个结果
控制台	15 个页面的本地控制台	她在跟谁聊、记得什么、花了多少积分、守护进程是不是还活着
看门狗	计划任务定时巡检，掉线自动重连、重登、重启；撞上风控就闭嘴等	你睡觉的时候她也在，出事了先自己爬起来

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

一条消息的一生

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

flowchart LR
  A([QQ 里的一句话]) --> B[SnowLuma<br/>注入真客户端]
  B -->|OneBot 11 · WS 3001| C[插件<br/>闸门 · 场景 · 去抖]
  C -->|该说| D[DSH 宿主<br/>人设 · 记忆 · 关系 · 近况]
  D --> E[模型后端<br/>主脑 → 降级 → 备用]
  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;
  class G quiet;

绕这么多，是因为三件事必须同时成立：

1. 像个人 —— 回复前有「正在输入」的真实节奏，长回复切成多个气泡，气泡之间有间隔，情绪到了会补一张表情包；
2. 说得对 —— 上下文里塞的是她的人设、长期记忆、关系画像和这个群最近的氛围，而不是干巴巴的聊天历史；
3. 不出事 —— 权限、沙箱、预算、降级链、超时，每一层都在她犯错之前拦住她。

细节在代码里：lib/onebot.js 收发 → lib/gatekeeper.js 过闸门 → lib/engine.js 决定说什么 → lib/commands.js 处理指令。

三个闭环

…