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

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

[!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 空间能读、能写草稿，发布必须你确认；群里叫她的名字会应	她会看、会等批准，不擅自替你发
先查再说	事实性问题先委派干活会话去查，再用自己的话讲；查不到就说不知道	不编。宁可漏，不可滥
干活	以 命令 开头的指令会进常驻 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 处理指令。

三个闭环

• 记忆 —— 规则层先抓「我叫 / 我喜欢 / 我住在 / 我养了…」，模型层再按批抽；进库前过质量闸门，没把握的先进「待核实」。 边界：不全存；上限默认 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 步）

十分钟跑起来

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

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

1 · 把 QQ 接成通道

装好 SnowLuma（OneBot 11 框架，要求 Node ≥ 22、与 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

# 假设仓库在 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 兼容接口（推荐）

先在宿主里注册这个 provider（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	从零装起来，以及三档回滚（关插件 / 还原 profile / 整目录退回）
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（控制台视觉语言）。