小鲸鱼 Xiaojingyu

一个住在 QQ 里的陪伴型 AI。
她像群友一样在场：看气氛接话，记得你说过的事，需要的时候真的会动手。

GitHub · Gitee 镜像 · English · 文档索引 · 权限规则 · 安全 · 上游说明

[!NOTE]
当前是 0.0.0 开发快照，逐项适配 DSH 0.2.0-rc.2（npm run verify:adaptation）。
本仓库不打 tag、不发 Release；你看到的 v0.1.x / v0.2.x 标签都属于上游
Derpyu520/qq-bridge。

目录

• 认识她：她是谁 · 她为什么不像一个聊天窗口 · 使用场景 · 一条消息的一生 · 她有自己的生活
• 把她装上：快速部署 · 手动部署 · 运行模式 · 设计你自己的她
• 看着她：实时状态页 /live · 本地控制台 · 架构
• 能力与边界：代码提案 · 能力地图 · 完整能力清单 · 安全与隐私 · 已知限制
• 进阶：排查手册 · 兼容性与二次开发 · 文档 · 目录结构 · 上游与许可

她是谁

小鲸鱼住在一个 QQ 号里，群聊和私聊都能找到她。

她不会每条消息都接。大多数时候她只是在看：谁在说话、气氛怎么样、这个话题她接不接得上。
真开口的时候，她会记得你上周提过的事，也会在你说「今天有点撑不住」的时候，先问一句项目是不是周五交。

用起来不用装新 App，也不用改习惯。群友照常聊天，她只是那个偶尔冒泡、说话像人的成员。

她不做的事也很明确：

• QQ 注入和 SnowLuma 部署归 SnowLuma 自己管，她只连它的 OneBot 接口；
• 消息只发给白名单里的人，禁言、踢人、上传下载这些群管理动作一概没有；
• 出错时群里只会看到一句人话，原始报错留在日志；
• 语音默认关着，要用就去控制台打开。

她为什么不像一个聊天窗口

大多数 AI 聊天是一次性的：发一句，回一句，关掉页面就归零。小鲸鱼长在 QQ 里，更像一个长期在线的群友。

你今天在群里聊到一半的话题，明天可以在私聊里接着讲，不用先交代前情。她也不会每来一条消息就弹一次：
规则先筛掉不值得惊动她的事，再由她判断要不要抬头。你看到的是「她刚好在」，看不到的是大多数时候她选择不说话。

她还有自己的日程。会反思，会好奇，会在深夜安静下来，也会自己安排下一次醒来。守护窗口开着的时候她整日在线，
崩溃了自动重启，掉线了重连，没送出的消息排队重放。这些都跑在你自己的机器上。

快速部署（完全不懂编程也能用）

_{三段流程：准备环境 → 交给 agent → 扫码上线并验收}

你不需要读懂 Node、DSH 或 OneBot。整个部署只有三个阶段：准备一个 agent、把一句话交给它、亲手扫码并验收。
按下面的顺序做，每一步都有明确的成功标志。

阶段一：准备三样东西

只有 DSH 需要你自己安装；Node.js、Git、依赖、配置、preset 都交给 agent。
如果 DSH 还没装，先装完再往下走——后面所有步骤都依赖它。

阶段二：把这句话原样发给 agent

帮我在 Windows 上部署 https://github.com/Frostyume/xiaojingyu（国内访问 GitHub 慢就用
Gitee 镜像 https://gitee.com/frostyume/xiaojingyu）：先读仓库里的
docs/guides/AGENT_DEPLOY.md 并严格照着做，自己检查环境、装依赖、写配置、跑
install-dsh 和 doctor，直到全部通过；除了 SnowLuma 扫码登录和提供 QQ 号 / 群号，
其余都自己完成；不要打印或上传 config.json、state/ 里的任何令牌、Cookie 和号码。

发出去之后，它会先检查环境、克隆仓库、安装依赖，然后按顺序问你四件事。照着回答即可：

它中途会要求你亲手做 SnowLuma 的部分——这就是阶段三。

阶段三：亲手扫码，然后验收

只有两件事必须你本人做，因为 SnowLuma 的许可不允许脚本代装、代登录、代启动：

1. 装 SnowLuma 并扫码登录
   从 SnowLuma Releases 下载
   SnowLuma-v<版本>-win-x64.zip → 解压 → 双击 launcher.bat → 用启动日志里的地址打开
   WebUI → 同意条款、设置密码、扫码登录 QQ → 在 WebUI 里开启 WebSocket 服务端 与 HTTP API。
2. 把 QQ 号 / 群号 / 端口 / token 告诉 agent，它负责写进 config.json。

之后 agent 会安装 DSH 端 preset 与 MCP，完整重启 DSH（不是刷新页面），再启动桥接并跑体检。
看到日志 SnowLuma 已连接，就用白名单里的 QQ 私聊机器人发一句「在吗」。

验收清单（全部打勾才算部署成功）：

• npm run doctor 没有 [FAIL]，DSH / SnowLuma / preset / 端口都是 OK；
• 日志出现「SnowLuma 已连接」；
• 白名单内的 QQ 私聊能收到她的回复；
• 控制台 http://127.0.0.1:3100 能打开，「运行总览」双健康；
• http://127.0.0.1:3100/live 能看到她的状态页；
• 没有向任何群聊发送测试消息（私聊验证就够了）。

部署完成后的第一小时

1. 打开控制台「人格与角色」，确认角色是小鲸鱼，读一遍两层提示词；
2. 到「群聊剧场」把唤醒频率、夜间静默、工具开关调成你想要的样子；
3. 先只放行一个群、一个好友，观察一天再扩大白名单；
4. 在私聊里说「内心状态」「跑一次分享」试水她的生活功能；
5. 备份 config.json、state/ 与 personas/——换电脑时一起带走。

卡住了怎么办

把 agent 输出的「卡在哪一步 / 报错原文 / 已尝试什么」整段贴回给它，让它按
AGENT_DEPLOY.md 的故障表继续。不要让它删 state/、
关闭白名单或关闭鉴权来绕过问题——那不是修复，只是把门打开。

更愿意手动来？手动部署 的六步和 agent 执行的是同一套流程。

设计你自己的她

小鲸鱼只是仓库自带的默认角色。名字、性格、说话习惯和群里的分寸，都可以换成你自己的。

1. 先分清两层提示词：「人格提示词」管她是谁——身份、性格、语气、雷点；「仿真提示词」管她怎么干活——工具、分条、潜水与唤醒。改人设只动前者；
2. 换角色：把 personas/小鲸鱼.md 复制成 personas/<新名字>.md 再改内容，或在控制台「人格与角色」新建角色卡；之后在控制台点选，或在群里说 进入角色扮演：<名字> 切换；
3. 给每个群留不同的分寸：在「群聊剧场」为单个群写初始提示词、群画像和风格备注，让她在不同场合的说法不一样；
4. 小步验证：先在私聊里聊几句，再放进一个群观察一天；不满意就改文件或在控制台保存，下一条消息即生效，不用重启 DSH。

人格卡只写人设，不要写工具用法；行为边界（不越权、不刷屏、不冒充主人）建议保留。
模板、按模式注入和字符上限见 personas/README.md，机制细节见
完整能力清单。

使用场景

_{三种最常见的场景（示意对话）：群里接话、私聊记得你、要她干活时真去做}

① 群里，她不抢话。
一天几百条消息，她只在被叫到、被问到，或者话题正好落在她熟悉的地方时抬头。
看到 7 条未读，回一句就够；接不上就继续潜水。
她记得这个群谁爱开玩笑、谁最近在忙什么，所以接的话不会像天气预报。

② 私聊里，她记得你。
「今天有点撑不住」不需要前情提要。她知道你周五要交项目，也知道你交完想去海边待两天。
这些不是每次现问的，是跨会话留下来的记忆，你可以在控制台里翻看、修改、删掉任何一条。

③ 要她干活，她真会做。
排值日表、查资料、定提醒、整理聊天记录，她会先读群历史、查成员，必要时联网，
再把结果分条发出来。碰到隐私或者超出权限的事，她会先问一句，而不是先做了再说。

④ 不好用，就在私聊里直说。
「语音结尾总被截断，修一下」「能不能加个每周一早上的群摘要」，她会把需求写成代码提案
排进开发待办，由你的开发 agent 实现、测试、回报，你确认之后才合并。
原理和接入方式见 代码提案。

还能交给她的日常：

一条消息的一生

在 simulation 模式（默认）里，消息进来后不会立刻变成一次模型调用，它要先过两道很不一样的判断。

第一道是规则，不花 token。 白名单决定「能不能进来看」，唤醒条件决定「值不值得叫醒她」：
@、叫名字、关键词、提问、拍一拍、概率，命中哪条算哪条。/reset、/status 这类明确命令和挂起审批
走快路径，不进模型；群里大部分闲聊只进未读队列。

第二道是语义。 只有命中条件她才会醒，醒了也不是逐条处理：8 秒内的消息合并成一次唤醒，
忙的时候一次最多带 12 条未读、6000 字。她读的是一个快照，可以决定回、等、标记已读，或者继续潜水。

最后才是「说」。 回复不直接发出去，而是回到统一出口：再过一遍白名单与审计，
按 QQ 的节奏分条、限频、分段，然后才出现在群里。

_{触发 → 判断 → 行动：决定「说什么」之前，先决定「要不要说」}

一条消息在她这里要走五步：收下、两级判断、合并、执行、统一出口。至于这次说不说、说几句，还是她说了算。

她手里的 35 个工具、唤醒与发送的硬限制，见 完整能力清单。

她有自己的生活

没有消息的时候她也在。会反思，会好奇，刷到有意思的东西想分享，深夜会安静下来。

• 定时反思：回看最近的聊天和关系，更新心情、精力、兴趣和口癖；
• 好奇浏览：从你配置的来源里形成候选见闻，要不要分享是另一件事；
• 情绪有惯性：心情按真实时间衰减，精力跟着北京时间走，不会一句话从开心变成崩溃；
• 分享有上限：群分享、QQ 空间说说、分享模块都受每日条数、间隔和夜间静默约束。

私聊里也能管这些：内心状态、跑一次分享、反思一下、发 / 不发、验证通过 <id>。
完整指令表、示例频率和验证期规则见 内心生活与主动分享。

代码提案：私聊里让她改进和开发

她不会自己写代码。但她能把一句「不好用」整理成一份可执行的开发任务，交给你自己的
coding agent，并盯完「实现 → 测试 → 你确认 → 合并 → 失败回滚」整条链路。

_{四段闭环：你说需求 → 她落成提案 → agent 在隔离副本实现 → 你确认合并}

她先把需求拆成带现状、期望、证据和验收标准的提案，按内容哈希生成稳定 id，写进
state/dev-proposals/ 与 state/orchestrator/；你的 agent 在隔离副本里实现并跑 npm run verify；
你回「合并 <id>」之后，桥接逐文件备份、复制、再跑一次 verify，失败自动回滚。
她只负责记录、排队、转达，不创建开发会话、不写业务代码、不合并；群聊里的人触发不了。

仓库自带 Qoder 唤醒适配，也可以换成 Codex、Claude Code、Cursor、Aider 或自写脚本。
完整流程、三条私聊回执的样例、接入契约和常见坑见 代码提案闭环。

能力地图

说一句，她自己排开发

她不会直接写代码，而是把你的一句话整理成带现状、期望、证据和验收标准的提案，
排进开发待办；真正实现的是你自己的 coding agent，合并权始终在你手里。

她决定说不说

群聊里没有「收到就回」的自动回复。每条消息先进未读队列，她按唤醒条件、夜间静默、
频率上限和当前精力决定：这次要不要看、看完要不要说、说几条、还是继续潜水。
35 个工具逐项可关；关掉后工具直接从她的清单里消失，而不是调用时才拒绝。

记忆，还有她自己的日程

她记得话题、挂念和群友印象，也记得跨会话的个人记忆；你可以在控制台翻看、修改、删除。
没有消息时她也不会停摆：定时反思、好奇浏览、心情与精力按真实时间演化，
想分享时再受每日上限、间隔和夜间静默约束。

工具清单、节奏边界、分门别类的能力表和安全默认值见 完整能力清单。

实时状态页 /live

_{只读实时状态页（离线演示数据），不含真实账号}

挂在副屏上，看她的心情、精力、羁绊、兴趣、内心生活和此刻动向，也能看到每个会话的未读与活动。
只读，SSE 自动刷新，独立令牌，默认只听 127.0.0.1。
面板逐项说明见 状态页与控制台。

本地控制台

_{运行总览 · 浅色主题（离线演示数据；深色主题见 console-dark.png）}

默认在 http://127.0.0.1:3100，13 个任务页：运行总览、功能总览、会话与审批、人格与角色、群聊剧场、
群聊洞察、资源库、黑话词库、令牌与花费、访问与安全、调试与运维、可靠性与配置、工具参考。
浅色 / 深色主题、响应式、草稿保护，不引用任何外部字体或统计脚本。
逐页说明见 状态页与控制台。

架构

_{她住在哪里：整条链路都在你自己的机器上}

整条链路只有两种角色。接线层收 QQ 事件、做白名单与唤醒准入、把短时间内的消息合并成一次、
维护会话映射与记忆，并统一负责对外发送；思考层（DSH agent）每次被唤醒时在隔离上下文里
读消息、查记忆、决定说什么，结果回到接线层，由同一个出口发出去。

所以会话是内部实现，你面对的是「一个群里的她」。为什么这样拆、上下文怎么按预算取用，
见 架构与设计取舍。

安全与隐私

• 群友没有本地权限：qq-chat 不挂载 bash / 文件读写 / 子代理 / 工作流，
  群友怎么诱导都无法操作本机；
• QQ 动作是安全子集：只允许三个 MCP 命名空间 + ask_user_question / todo_write，
  发送类工具强制命中白名单；语音只能发语音库里的文件；
• 高风险动作要确认：跨会话指令、敏感操作会在 owner 私聊里要求 /确认 <6 位码>；
• 人格由桥接注入：角色来自 personas/ 与控制台，群友口头要求改人设无效；
• 不把内部错误发进群：DSH / SnowLuma / QQ 的原始报错只留在日志和 GET /api/status；
• 仓库不含密钥：真实 config.json、state/、audio/ 都不会进入仓库，只提供脱敏模板。

隐私相关的数据出机清单（例如黑话学习会把词条交给搜索后端，可关闭）见
docs/guides/PRIVACY.md；权限边界见 RULES.md。
发现安全问题请按 SECURITY.md 私密报告，不要开公开 issue。

已知限制

• 仅支持 Windows 10 / 11；单机常驻，不做跨设备同步；
• agent 回复在回合结束时一次性发送，不做流式逐字转发；
• 没有按话题拆分执行会话，同一个群里的多条话题共享一条上下文；
• 没有任务级进展看护，只有进程 / 端口 / 租约探活和「连续无行动」计数。

完整清单（入站语音、视频消息、语音默认开关、Markdown 转纯文本等）见
排查手册与已知限制。

文档

上游与许可

起点是 MIT 许可的 Derpyu520/qq-bridge（基线 v0.2.0-r4）。
上游的名称、版权行与 MIT 许可完整保留；具体分叉点与跟进规则见 UPSTREAM.md。

本仓库与上游均以 MIT 发布，感谢 Derpyu520/qq-bridge、
SnowLuma 和 DeepSeek Harness；
第三方组件与许可说明见 NOTICE。

SnowLuma 是独立第三方项目，与腾讯 / QQ 无隶属关系；本项目仅供学习与技术研究，
使用前请阅读 SnowLuma 的 EULA 与《QQ 用户协议》。