QQ 人格聊天框架 3150481853/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.7-preview.1（预览，2026-10-30）· 上一个稳定版 v1.1.6-Hotfix.1 · 完整记录见 docs/CHANGELOG.md 与 Releases。

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

版本线（新 → 旧）： 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

这一版新增：

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

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

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

目录

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

它是什么

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

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

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

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

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

三个闭环

- 记忆 —— 规则层先抓「我叫 / 我喜欢 / 我住在 / 我养了…」，模型层再按批抽；进库前过质量闸门，没把握的先进「待核实」。
边界：不全存；上限默认 2000 条（记满自动扩到 1 万）；写入先去重，同一件事不重复存；落盘 AES-256-GCM 加密，密钥默认 keys/memory.key、可与数据分开放；tools/backup-memory.ps1 定时备份到两块盘。
- 表情 —— 群里别人发的图自动入库（体积 + 每日配额双重限制），轮到她就按语境挑一张。
边界：学来的图有上限；觉得不像她会用的，控制台里删掉。
- 自愈 —— 掉线 30 秒重连；群名片被改成「（在想…）」会自己撕回去；积分额度状态落盘，重启不丢。
边界：只修复自己造成的状态，不碰别人的名片。

版本与发版规则

一条版本线长这样：preview 迭代 → 正式版收口 → 正式版之后分 Hotfix（修 bug）/ Plus（加功能），二者并列、可互相继承；下个版本的 preview 会带着它们的改动继续往前。

flowchart LR
P["1.2.0-preview.1 → .2 → .3"] -->|合并全部 preview| R["1.2.0 正式版"]
R -->|只修 bug| H["1.2.0-Hotfix.1"]
R -->|只加功能| A["1.2.0-Plus.1"]
H -.-> A
H --> N["1.3.0-preview.1"]
A --> N
N -->|合并全部 preview| R2["1.3.0 正式版"]
classDef rel fill:#e8f7ee,stroke:#1aae39,color:#0b3d1f
classDef fix fill:#fff4e5,stroke:#d97706,color:#5b3700
classDef feat fill:#e8f0ff,stroke:#2563eb,color:#0b2559
classDef pre fill:#f3f4f6,stroke:#9ca3af,color:#374151
class R,R2 rel
class H fix
class A feat
class P,N pre

图中虚线 = Hotfix 与 Plus 的并列关系：地位相同，可互相继承。

| 版本 | 命名 | 什么时候发 | 必须包含 |
| 正式版 | 1.2.0 | 一条版本线收口 | 该版本全部 preview 的内容 |
| preview | 1.2.0-preview.1/.2/.3 | 正式版之前的迭代 | 上一个正式版的 Hotfix / Plus 改动（若期间发过） |
| Hotfix | 1.2.0-Hotfix.1 | 正式版之后只修 bug | 先前的 Hotfix / Plus 改动 |
| Plus | 1.2.0-Plus.1 | 正式版之后只加功能 | 先前的 Hotfix / Plus 改动 |

几条硬规则：

- 正式版独立于其他版本，但它不是从零开始——发布时会整合同一版本号之前的所有 preview。
- Hotfix 与 Plus 是并列替换关系，地位相同、互不替代；但后发的那个必须继承先发的改动。
- 下个版本的 preview 跟着更新：老版本线又发了 Hotfix / Plus，新版本线的 preview 要把这些修复和功能同步进来。
- 版本号由维护者定：不确定就问，别自己起版本号。

发版前三问：

1. 这次是「修 bug」还是「加功能」？→ 决定 Hotfix 还是 Plus。
2. 版本号是谁定的？→ 不确定先问。
3. 这份代码带上先前的 Hotfix / Plus 了吗？→ 没有就先合进来，再发。

规则原文与历次实操记录在仓库 docs/STATE.md §10，发布流程（构建、脱敏、tag、Release、附件）见 §9。

环境要求

| 你需要 | 说明 |
| Windows 10 / 11 | 主目标平台。插件与控制台是纯 Node，但运维脚本（守护、计划任务、快捷方式）是 Windows 的 |
| Node.js ≥ 22 | DSH 自带运行时也行；仓库里的 43 个自测脚本用它跑 |
| DeepSeek Harness | 宿主。插件以 dsh.bundle 的形式挂进 profile |
| 一个 QQ 号 | 建议小号。Molly 会用这个号登录、说话、发图 |
| SnowLuma | 把真 QQ 客户端接成 OneBot 11 通道（HTTP 3000 / WS 3001）。许可为源码可见、非商业，商用前先确认。本仓库不含 SnowLuma，去上游下 |
| 一个模型接口 | 任意 OpenAI 兼容接口即可，也可以接 WorkBuddy 的免费额度（见第 3 步） |

十分钟跑起来

完全没装过、只想照着抄？ 直接看 docs/beginner-deploy.md：那篇是写给「第一次装」的人的——每一步都写清了下载哪个文件、放到哪个目录、点哪个按钮、看到什么算成功、失败了怎么修。

下面四步能让她在你自己的 QQ 里说话。卡住了先看对应的那篇文档。

先把仓库放到本机（git clone 或下载 zip），下文假设它在 D:\molly-qq-whale。

1 · 把 QQ 接成通道

装好 SnowLuma（OneBot 11 框架，要求 Node ≥ 24.22.1：Node 22 启动会直接报 requires Node.js ^24.22.1 || >=26.12.1；且要与 QQ 同权限，右键「以管理员身份运行」），解压后编辑它目录里的 config\onebot.json，在 networks 里开一对本机 HTTP + WebSocket：

{
"networks": {
"httpServers": [{
"name": "http-local", "enabled": true, "host": "127.0.0.1", "port": 3000,
"accessToken": "自己定一个", "messageFormat": "array", "reportSelfMessage": true }],
"wsServers": [{
"name": "dsh-qq-whale", "enabled": true, "host": "127.0.0.1", "port": 3001,
"role": "Universal", "accessToken": "自己定一个", "messageFormat": "array", "reportSelfMessage": true }] } }

然后跑 launcher.bat，扫码登录你的小号——SnowLuma 的 WebUI 在 http://127.0.0.1:5099。HTTP 3000 给看门狗探活、WS 3001 给插件收发；两处 Token 要一致，等会儿填进 onebotToken。

SnowLuma 的版本、Hook 与 QQ 客户端的匹配关系与 DSH 无关，按它自己的说明走。

2 · 把插件挂进 DSH profile

最快的一条路：不用 clone 仓库，直接从 GitHub 装源码（DSH 桌面版的 profile 默认叫 desktop）：

dsh plugin --profile desktop add "github:3150481853/molly-qq-whale#path:/plugin/dsh-qq-whale"

装完仍需写好 cordis.patch.yml（见下面第 2 点）。不想用命令行的话，照下面的手动做法走。

假设仓库在 D:\molly-qq-whale，profile 名为 desktop（DSH 桌面版默认叫这个） $pdir = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules" Copy-Item .\plugin\dsh-qq-whale $pdir -Recurse -Force Copy-Item .\plugin\dsh-qq-pest $pdir -Recurse -Force # 可选：嘴臭模式，装法同主插件

然后改 profile 里的两个文件：

1. package.json —— dependencies 里加一行 "dsh-qq-whale": "file:D:/molly-qq-whale/plugin/dsh-qq-whale"，dsh.profile.bundles 数组末尾加 "dsh-qq-whale"；
2. cordis.patch.yml —— 把 config/cordis.patch.example.yml 改好（QQ 号、群号、Token、目录、模型），追加到文件末尾。

重启 DSH 宿主。插件只在宿主启动时合并补丁，热重载只对 lib/*.js 的改动生效。

排错：插件加载失败是静默的。检查 package.json 里那个 file: 路径是否真的存在，以及 profile 的 node_modules\dsh-qq-whale\ 里是不是有 lib/boot.js。完整步骤与三档回滚见 docs/INSTALL-AND-ROLLBACK.md。

3 · 接上模型

两种接法，选一种： A. 用你自己的 OpenAI 兼容接口（推荐）

先在宿主里注册这个服务商（baseURL 只写到 /v1），再让 Molly 指向它：

config:
modelBackend: dsh # wbai（直连）| wb-proxy（本地多账号池）| dsh（走宿主） provider: my-openai # 宿主 providers 里的 key，不是模型名 model: my-model-id

B. 用 WorkBuddy 的免费额度

modelBackend: wbai 直连桌面端凭据；modelBackend: wb-proxy 走本地多账号池网关。

两条链路（聊天 / 干活）的区别、模型降级顺序、常见 404 与 403 的坑，见 docs/llm-adapter.md。

4 · 写她

Copy-Item .\persona\core.example.md .\persona\core.md
然后把 cordis.patch.yml 里的 personaDir 指向这个目录： D:/molly-qq-whale/persona

改完重载插件就生效。示例文件里写的是结构，不是人 —— 照抄只会得到一个不像任何人的机器人。写法见 docs/persona-guide.md。

控制台

控制台是给人看的，不是给她用的：读的数据来自本机，写操作全部走插件，前端不直接碰文件。

源码模式：先写 tools\console.json，再启服务
node tools\console-server.mjs # 或直接双击 .\console.cmd

然后打开 http://127.0.0.1:19392。tools\console.json 至少要有这几项（默认值指向作者本机的目录，换成你的）：

{
"root": "D:\\molly-qq-whale",
"dataDir": "D:\\molly-data\\qq-whale",
"nodeExe": "C:\\Program Files\\nodejs\\node.exe"
}

- 15 个页面：总览 · 会话与消息 · 记忆 · 待核实 · 表情包 · 发言开关 · 预算 · 干活 · 守护 · 运维 · 外部服务 · 通道（SnowLuma）· 登录 · 执行块 · 设置
- 只监听 127.0.0.1；宿主端口每次重启都会换，服务端自己探。
- 打包成单文件 exe 见 docs/deploy.md。

设计语言

控制台不是随手拼的界面。视觉规范写在 docs/console-design.md，来源是 VoltAgent/awesome-design-md 里的 Notion DESIGN.md。

整套只做浅色，像一张白纸：安静、可读、不发光。

- 一个强调色 —— 只有主操作是紫色，其余全是黑灰文字；
- 1px 发丝线代替阴影 —— 卡片默认没有阴影，靠边框分层；
- 粉彩只做背景 —— 记忆是薰衣草、表情是薄荷、预算天蓝、守护奶油，颜色只承担归类；
- 数字等宽 —— 所有指标用等宽字体 + tabular-nums，扫一眼就能比大小。

| 用途 | 值 |
| 画布 / 卡片 | #ffffff / #fafaf9 |
| 分隔线 | #e5e3df，更浅一档 #ede9e4 |
| 文字四级 | #1a1a1a · #37352f · #5d5b54 · #787671 |
| 唯一强调 | 紫 #5645d4，按下时 #4534b3 |
| 状态 | 成功 #1aae39 · 警告 #dd5b00 · 错误 #e03131 |
| 圆角 | 6 / 8 / 12 / 9999 px |
| 间距 | 4px 基数：4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 |
| 字号 | 22 标题 · 15 卡片标题 · 13 正文 · 11 微标签 |

不做：深色模式、发光、玻璃拟态、外部字体与 CDN。

目录结构

molly-qq-whale/
├─ plugin/
│ ├─ dsh-qq-whale/ 主插件：37 个模块，QQ 收发的全部逻辑 │ └─ dsh-qq-pest/ 可选的「嘴臭模式」，独立状态机，可单独卸载 ├─ console/ 控制台前端（零依赖静态页） ├─ tools/ 控制台服务端 + 守护 + 打包 + 43 个自测脚本 ├─ persona/ core.example.md：人设模板（不含真实人设） ├─ config/ cordis.patch.example.yml 等挂载与配置样例 ├─ docs/ 16 篇文档：安装、契约、设计、部署、记忆、人设…
├─ assets/ README 插图 ├─ memory.example.json 记忆库结构示例 └─ console.cmd 双击开控制台（Windows）

文档

上手

| 文档 | 讲什么 |
| INSTALL-AND-ROLLBACK.md | 从零装起来，以及三档回滚（关插件 / 还原配置档 / 整目录退回） |
| llm-adapter.md | 接自己的 OpenAI 兼容 API，两条链路的区别 |
| persona-guide.md | 人设怎么写，为什么要拆成几个文件 |
| memory-guide.md | 记忆怎么长出来、怎么审、怎么删 |
| adm-usage.md | 管理员能做什么，不能做什么 |

内部契约

| 文档 | 讲什么 |
| console-contract.md | 控制台接口契约 v1，唯一事实来源 |
| console-crud-contract.md | 记忆与表情包的 CRUD 契约 |
| console-design.md | 视觉规范：token、组件、Do / Don't |
| patch-quote-engine.md | 「被引用消息的正文」怎么接进 engine |

部署与运维

| 文档 | 讲什么 |
| deploy.md | 控制台打包成单文件 exe 并部署 |
| server-deploy-plan.md | 放到服务器上：域名、443、反代 |
| gateway-workbuddy.md | 网关接入协议（可选链路） |
| blackwindow-fix.md | 后台黑窗口闪烁的根因与修法 |
| g-migration-contract.md | 搬迁预演契约（生产环境一个字都不能动） |
| github-upload.md | 从零上传 GitHub，以及哪些文件绝对不能进仓库 |

变更

| 文档 | 讲什么 |
| CHANGELOG.md | 症状 → 根因 → 修法 → 怎么退回 |

安全边界（重要）

[!WARNING]
Molly 是真的能动手的：她能读文件、跑脚本、发消息。下面几条不是建议，是默认行为，别在不理解的情况下关掉。

- 只听本机 —— 控制台、插件接口、通道后端全部绑定 127.0.0.1，不对外开端口；
- 三级角色 —— owner > adm（指令、工坊）> guest（只能聊天），谁是谁写在配置里，运行期不可改；
- 命令要批准 —— 改代码会写成 pending-code.json 等你回「1」；群名片被改会自己撕回原样；同一时间只跑一个，其余排队；
- 受保护路径 DENY —— 人设、记忆、凭据目录默认不允许命令会话碰；
- 沙箱 cwd —— 干活会话固定在 workSandboxDir 里，不落在你的项目目录；
- 硬超时 —— 单轮 180 秒，没有 ask_user_question：她不会弹窗等你，超时就放弃，然后说一句人话；
- 不上传 —— 唯一的出站流量是模型接口本身。

常见问题

能换成我自己的模型吗？

能。聊天和干活是两条独立的链路，可以把聊天接到你的 OpenAI 兼容接口，同时让干活继续用别的模型。见 llm-adapter.md。

她会不会乱说话、乱执行？

默认不会执行：命令要人批、路径有白名单、目录有沙箱、单轮有超时。但请把它当成一个能动手的实习生，而不是一个沙盒里的玩具。

支持 Linux / macOS 吗？

插件和控制台是纯 Node，能跑；但守护、计划任务、快捷方式这些运维脚本是 Windows 专用。别指望在服务器上一键部署。

为什么 README 里没有她的照片？

因为人设不在仓库里。这是有意的：你的鲸鱼应该是你的。

她占多少资源？

一个 Node 进程（插件跑在 DSH 宿主里）+ 一个控制台进程 + SnowLuma 拉起的 QQ。没有数据库，没有容器。

参与开发

这是个能跑的东西，不是框架设计稿。它长得像「一个人的项目长起来的样子」：有重复、有历史包袱、部分模块还在重写。但它跑在生产环境里 —— 真 QQ、真群、真限流，CHANGELOG 里每一条修复背后都是一次线上事故。

- 改之前先看 CONTRIBUTING.md；
- 自测是纯 Node 脚本，没有测试框架：node tools\test-memory.mjs；
- 提交前跑一次 node tools\scan-secrets.mjs，别把凭据带进来。

许可与致谢

MIT，见 LICENSE。

致谢：DeepSeek Harness（宿主）· SnowLuma（QQ 通道后端，OneBot 11 实现；源码可见、非商业许可）· VoltAgent/awesome-design-md（控制台视觉语言）。

她记得你说过的话 —— 至于怎么记得的，看 memory-guide.md。