文章目录
- 一、她是谁：先学会不说话
- 二、一条消息的一生
- 三、她手里的 35 个工具
- 四、两层提示词：把她换成你自己的角色
- 五、记忆、关系和黑话
- 六、不止文字：图片、语音、表情
- 七、她有自己的生活
- 八、私聊即控制台
- 九、私聊里让她改进和开发
- 十、看着她：/live 与控制台
- 十一、架构、可靠性与成本
- 十二、安全与隐私
- 十三、怎么把它跑起来
- 十四、已知限制
- 十五、开源地址与许可
项目地址：https://github.com/Frostyume/xiaojingyu
技术栈：Node.js / DSH / SnowLuma（OneBot v11）/ SQLite
当前版本：0.0.0 开发快照，MIT 协议
小鲸鱼是一个住在 QQ 里的陪伴型 AI。群聊和私聊都能找到她，但她不是那种收到消息就立刻回复的机器人。
大多数时候她只是在看：谁在说话、气氛怎么样、这个话题接不接得上。真开口的时候，她会记得你上周提过的事，也会在你说「今天有点撑不住」的时候，先问一句项目是不是周五交。
用起来不用装新 App，也不用改群友的习惯。她只是那个偶尔冒泡、说话像人的成员。
仓库自带的「小鲸鱼」只是默认角色。名字、性格、说话习惯和群里的分寸都能换，这部分后面单独讲。
一、她是谁：先学会不说话
大多数 QQ 机器人是「命中即回」：命令、关键词、正则，一条一条对。小鲸鱼不是。消息进来先过确定性规则，值不值得叫醒她另算；醒来之后，回不回、回几条、还是看完继续潜水，由她自己判断。
差别最大的是「不回」。群聊里大部分消息不值得接，硬回反而像客服。这个项目把「不说话」当成一个正常动作，而不是异常。
| 她有 | 她没有 |
|---|---|
| 人设：两层提示词，一层管行为边界，一层管性格语气，都能在控制台改 | 不会接管账号：她只是一个没有管理权限的普通成员 |
| 记忆：话题、挂念、群友印象、跨会话记忆，能看也能删 | 不会刷屏：唤醒频率、夜间静默、黏人次数都有硬上限 |
| 节奏：自己决定看、等、说，还是继续潜水 | 不会越权：群友再怎么诱导，也碰不到本机文件和命令 |
| 工具箱：读消息、发语音、发表情、查资料、定提醒，逐项可关 | 不自建云：本地组件只走127.0.0.1；消息仍会经 DSH 交给你选定的模型 |
她不做的事也很明确：QQ 注入和 SnowLuma 部署归 SnowLuma 自己管，她只连它的 OneBot 接口；消息只发给白名单里的人，禁言、踢人、上传下载一概没有；出错时群里只会看到一句人话，原始报错留在日志；语音默认关着，要用去控制台打开。
几个典型场景：
群里，她不抢话。一天几百条消息，她只在被叫到、被问到，或者话题正好落在她熟悉的地方时抬头。看到 7 条未读，回一句就够；接不上就继续潜水。她记得这个群谁爱开玩笑、谁最近在忙什么，所以接的话不会像天气预报。
私聊里，她记得你。「今天有点撑不住」不需要前情提要。她知道你周五要交项目，也知道你交完想去海边待两天。这些不是每次现问的，是跨会话留下来的记忆，可以在控制台里翻看、修改、删掉任何一条。
要她干活，她真会做。排值日表、查资料、定提醒、整理聊天记录，她会先读群历史、查成员，必要时联网，再把结果分条发出来。碰到隐私或者超出权限的事，她会先问一句，而不是先做了再说。
不好用，就在私聊里直说。「语音结尾总被截断，修一下」「能不能加个每周一早上的群摘要」，她会把需求写成代码提案排进开发待办，由你自己的开发 agent 实现、测试、回报，你确认之后才合并。
二、一条消息的一生
默认的simulation模式下，消息进来后不会立刻变成一次模型调用。它要先过两道完全不同的判断。
第一道是规则，不花 token。白名单决定「能不能进来看」，唤醒条件决定「值不值得叫醒她」：@、叫名字、关键词、提问、拍一拍、概率，命中哪条算哪条。/reset、/status这类明确命令和挂起审批走快路径，不进模型；群里大部分闲聊只进未读队列。
第二道是语义。只有命中条件她才会醒。醒来也不是逐条处理：8 秒内的消息合并成一次唤醒，忙的时候一次最多带 12 条未读、6000 字。她读的是一个快照，可以决定回、等、标记已读，或者继续潜水。
最后才是「说」。回复不直接发出去，而是回到统一出口：再过一遍白名单与审计，按 QQ 的节奏分条、限频、分段，然后才出现在群里。
一条消息在她这里要走五步：收下、两级判断、合并、执行、统一出口。至于这次说不说、说几句，还是她说了算。
三、她手里的 35 个工具
工具按用途分几类，覆盖读、说、等、节奏、记忆、黑话和生活技能。
| 类别 | 能做什么 |
|---|---|
| 读 | 未读、最近消息、单条详情、消息图片、合并转发、活跃成员、自己最近发过什么（避免重复接话） |
| 说 | 统一发送、分条发送、引用回复、拍一拍、收藏表情、语音条；间隔按真人节奏打散 |
| 等 | qq_wait_for_messages短暂等待新消息，有新消息立即返回，超时则回来继续判断 |
| 节奏 | qq_set_wake_config设置下次唤醒方式（无限期 / 指定时间 / @ / 名字 / 关键词 / 提问 / 拍一拍 / 概率）；qq_mark_read表示「看过但决定不回」；qq_social_state查看未读与唤醒状态 |
| 记忆 | qq_memory_append/qq_memory_query记录话题、想说的话、群友印象与跨会话个人记忆 |
| 黑话 | qq_slang_query查已确认词条，qq_slang_submit把陌生表达交给管理员筛选 |
| 生活技能 | 天气、猜拳 / 骰子 / 今日鲸鱼运势、定时提醒（只在你指定的会话里发） |
35 个工具在控制台「群聊剧场」里逐项开关。关掉之后，它会直接从模型的工具清单里消失，而不是等调用时才拒绝。语音、贴纸、收集、发送类工具都能单独关。
工具之外还有一套硬边界，防止她越用越「上头」：
- 唤醒硬限制：最小 / 最大潜水时长、每分钟 / 每小时最多唤醒、合并窗口、无行动兜底次数、唤醒收尾提醒次数、沉睡前强制等待；
- 夜间静默：可配置时间窗，窗口内不主动发言；
- 黏人追发：主人在私聊里没回时，按配置的间隔与次数补一句，不会无限刷屏；
- 主动检查：长时间空闲后按概率决定要不要找话题，而不是固定频率推送；
- 群独立配置：每个群可设初始提示词、群画像、风格备注与是否允许主动发言；
- 发送边界：所有发送命中白名单；敏感路径、令牌、Cookie 等会被审计层拦截；QQ / SnowLuma / DSH 的内部错误只进日志，不进群。
四、两层提示词：把她换成你自己的角色
项目把提示词拆成两层，改人设和改行为互不干扰。
仿真提示词管她怎么干活：工具协议、怎么分条、怎么潜水、什么时候用表情、哪些操作不能做。人格提示词管她是谁：身份、性格、语气、雷点，放在personas/下的角色卡里。
这样拆的好处是换角色不用动工具协议。角色卡可以在控制台增删改查，也能按运行模式筛选注入，注入有字数上限（默认 10000 字符）。群友在群里口头要求改人设不会生效，人格只在桥接侧注入。
换成你自己的她，大致四步：
- 先分清两层：改人设只动人格提示词，别把工具用法写进角色卡；
- 换角色：把
personas/小鲸鱼.md复制成personas/<新名字>.md再改内容，或在控制台「人格与角色」新建角色卡；之后在控制台点选，或在群里说进入角色扮演：<名字>切换； - 给每个群留不同的分寸：在「群聊剧场」为单个群写初始提示词、群画像和风格备注，让她在不同场合的说法不一样；
- 小步验证：先在私聊里聊几句，再放进一个群观察一天；不满意就改文件或在控制台保存，下一条消息即生效，不用重启 DSH。
人格卡只写人设，不要写工具用法。行为边界（不越权、不刷屏、不冒充主人）建议保留。
五、记忆、关系和黑话
记忆分几层：当前话题、没说完的想法（pending thoughts）、对群友的印象、跨会话的个人记忆。这些都能在控制台查看、修改、删除，记忆只存在本机。
关系不是喊口号。群友关系有数值，加上活跃成员、群画像和群日报预览，构成所谓「群聊洞察」。日报默认关闭，想用再开。
黑话是另一条线：从群聊里自动抽候选，人工确认含义、用法和风险之后才写进词库；确认过的词条会注入提示词。阈值和注入量都可调。遇到陌生表达，她也可以主动提交给管理员筛选，而不是自己瞎猜。
情绪也不是随机数。心情按真实时间半衰期衰减，精力跟着北京时间走，每小时和每天都有变化上限，不会一句话就从开心变成崩溃。反思只更新状态，不往群里发消息。
六、不止文字：图片、语音、表情
图片、表情、动图会进入上下文；贴纸库有备注和标签，她认得自己收藏过什么。表达上支持引用回复、拍一拍、分条发送，以及语音库 + TTS 情绪音色。
语音这块默认是关的，两个开关分别控制入站 ASR 和 AI 发语音。要用的话，先把音频放进audio/，再到控制台打开开关——她只能发语音库里有的文件，不能凭空合成任意内容。
这些能力都可以单独关。不想让她发表情，或者不想让她发语音，在「群聊剧场」里关掉对应工具即可。
七、她有自己的生活
没有消息的时候她也在。会反思，会好奇，刷到有意思的东西想分享，深夜会安静下来。
- 定时反思：按配置的间隔随机醒来（示例配置为每 1–8 小时一次），回看最近的聊天、关系和自己的状态，更新心情、精力、兴趣、学到的东西与口癖；
- 好奇浏览：按配置的来源和频次浏览（示例配置为每天 5–12 次；B 站热门、某个赛事、RSS 都只是内置示例源），形成候选见闻；
- 情绪有惯性：心情按真实时间衰减，精力跟着北京时间走；
- 反思不说话：它只更新状态，不往群里发消息；要不要分享是另一件事。
需要说明的是，反射间隔、浏览来源、频次都是默认机制和示例配置，以你自己的config.json为准。换成你的资讯源、减少来源或者整个关掉都可以。
主动分享是另一套东西，同样可以单独开关：
| 能力 | 做什么 | 默认边界 |
|---|---|---|
| 群分享 | 从候选见闻里挑一条发到指定群 | 每天最多 20 条、每群间隔 15 分钟、群内至少安静 2 分钟才发，夜间静默不发；没配目标群或候选为空就不硬发 |
| QQ 空间说说 | 发说说，可设置「先审后发」 | 默认好友可见，每天最多 2 条 |
| 分享模块 | 内置 9 种模板（科普、资讯、趣闻、实用技巧、自定义等）；主人可在私聊里创建 / 修改 / 暂停 / 删除 | 新模块有「验证期」：前几条先私聊给你草稿，你回「验证通过 」之后才会自动发 |
| AI 小知识 | 只是「分享模块」里的一个可选示例 | 默认关闭；打开后示例配置为每天 2–5 条、只在 9–22 点 |
所有主动发言都受每日上限、间隔与静默时段约束，触发不了就继续潜水。
八、私聊即控制台
不少日常操作不用打开网页，在主人私聊里说一句就行。只认主人 QQ，只在私聊生效。
| 你说 | 她会做 |
|---|---|
内心状态 | 报当前心情、精力、兴趣和接下来想做什么 |
发/不发 | 对刚生成的说说草稿表态 |
跑一次说说/跑一次分享/反思一下 | 立刻执行一次对应任务 |
发分享 <id>/不发分享 <id>/暂停分享 <id>/恢复分享 <id> | 管理候选见闻 |
验证通过 <id> | 让处于验证期的分享模块转正 |
关说说/开说说/关AI分享/开AI分享 | 开关对应能力 |
预览三个AI知识/用第N种 | 仅「AI 小知识」示例模块启用时：挑选小知识的写法 |
删说说/改签名/收藏表情 | 日常维护 |
修一下/加个功能 | 生成代码提案并排入主控待办；她不自己开发、不合并 |
你能做什么 | 列出当前可配置 / 可开发的能力、状态与示例 |
规则/频率是多少 | 读真实配置值回答；明确要改时会要求你确认 |
| 其他文字 | 当作对当前待审草稿的修改意见 |
高危动作（跨会话发送、敏感操作）会要求你在私聊回/确认 <6 位码>。
这套私聊指令不是完整的后台：改配置、重启进程、执行命令仍然只能在控制台或本机做。
九、私聊里让她改进和开发
她不会自己写代码。但她能把一句「不好用」整理成一份可执行的开发任务，交给你自己的 coding agent，并盯完「实现 → 测试 → 你确认 → 合并 → 失败回滚」整条链路。
具体流程：先把需求拆成带现状、期望、证据和验收标准的提案，按内容哈希生成稳定 id，写进state/dev-proposals/与state/orchestrator/；你的 agent 在隔离副本里实现并跑npm run verify；你回「合并<id>」之后，桥接逐文件备份、复制、再跑一次 verify，失败自动回滚。她只负责记录、排队、转达，不创建开发会话、不写业务代码、不合并；群聊里的人触发不了。
仓库自带 Qoder 唤醒适配，也可以换成 Codex、Claude Code、Cursor、Aider 或自写脚本。
除了改代码，还有一套「主人功能中心」：qq_capabilities_list看能力，qq_feature_preview预览排期与文案，确认后用qq_feature_apply应用定时消息、自动回复、说说、语音消息。预览确认之后才写入。
想扩能力也可以走插件路线：personas/放一张人格卡，features/<id>/放一个插件，mcp/扩工具，或者直接改 preset。插件和主程序同进程加载，只加载你信任的代码。控制台页面暂时没有插件注册点，加页面需要改主程序。
十、看着她：/live 与控制台
/live是一个只读实时状态页，SSE 自动刷新，适合挂在副屏。面板包括：像素小鲸鱼（挥手 / 待机 / 兴奋 / 疲惫 / 嘟嘴）、羁绊、心情与精力罗盘加 7 天曲线、兴趣与成长、内心生活、此刻动向、会话与活动、服务健康、累计用量、长期记忆与资源库。
本地控制台默认在http://127.0.0.1:3100，13 个任务页：运行总览、功能总览、会话与审批、人格与角色、群聊剧场、群聊洞察、资源库、黑话词库、令牌与花费、访问与安全、调试与运维、可靠性与配置、工具参考。浅色 / 深色主题、响应式、草稿保护，不引用任何外部字体或统计脚本。
两个页面默认都只监听127.0.0.1，访问需要令牌。
十一、架构、可靠性与成本
整条链路只有两种角色。接线层收 QQ 事件、做白名单与唤醒准入、把短时间内的消息合并成一次、维护会话映射与记忆，并统一负责对外发送；思考层（DSH agent）每次被唤醒时在隔离上下文里读消息、查记忆、决定说什么，结果回到接线层，由同一个出口发出去。
QQ 客户端 │ 扫码登录 SnowLuma（OneBot v11 网关） │ WebSocket / HTTP 小鲸鱼桥接（Node.js） │ 会话路由、白名单、审计、队列 DSH agent（模型与工具调用） │ SQLite（WAL）几个关键点：
- 桥接和 DSH 都在本机，默认只走回环地址；每个群、每个私聊有独立上下文，不会互相串；
- 数据在
state/db/bridge.db，SQLite WAL 模式，不需要额外数据库服务； - 消息出站有 outbox 幂等与重放，入站有 inbox 去重，还有任务队列；DSH 掉线时按会话排队，恢复后补投；
- 进程有守护和重连，崩溃自动重启，掉线重连，没送出的消息排队重放；
- 队列有上限，进程退出会丢内存队列——这是刻意保留的边界，不是「无限可靠」的承诺。
成本方面有独立看板：按 DeepSeek 官方峰谷价目折算，按群 / 好友 / 轮次下钻，缓存命中单独拆分，走势从 24 小时看到 30 天。规则层能减少无效唤醒，但不能把调用降到零。
项目按 DSH 0.2.0-rc.2 适配，包括~/.dsh持久密钥离线铸造 Cookie、slash RPC +/api/remote.mux、preset bundle patch、三个受限 MCP server，以及一键安装脚本install-dsh.mjs。
十二、安全与隐私
- 群友没有本地权限：
qq-chat不挂载 bash / 文件读写 / 子代理 / 工作流，群友怎么诱导都无法操作本机； - QQ 动作是安全子集：只允许三个 MCP 命名空间加
ask_user_question/todo_write，发送类工具强制命中白名单；语音只能发语音库里的文件； - 高风险动作要确认：跨会话指令、敏感操作会在 owner 私聊里要求
/确认 <6 位码>； - 人格由桥接注入：角色来自
personas/与控制台，群友口头要求改人设无效； - 不把内部错误发进群：DSH / SnowLuma / QQ 的原始报错只留在日志和
GET /api/status； - 仓库不含密钥：真实
config.json、state/、audio/都不会进入仓库，只提供脱敏模板。
默认值也偏保守：
| 默认行为 | 意味着什么 |
|---|---|
| 空白名单不响应 | 没填号码就谁都不理 |
| 群聊 preset 无本地工具 | 不挂 bash / 文件读写 / 子代理 |
| 发送强制白名单 + 审计 | 敏感路径、令牌、Cookie 会被拦截 |
| 高危动作要确认码 | 跨会话发送、敏感操作需要主人确认 |
| 不默认发语音 | 先放音频到audio/，再手动开开关 |
数据出机方面，本地组件只走127.0.0.1，但消息仍会经 DSH 交给使用者选定的模型，具体范围取决于模型提供方。例如黑话学习可能把词条交给搜索后端，这个可以关闭。
十三、怎么把它跑起来
先说清楚：它不是双击安装包。
| 组件 | 要求 |
|---|---|
| 系统 | Windows 10 / 11 x64 |
| Node.js | ≥ 22.13，推荐 24（使用内置node:sqlite） |
| DSH | 按 0.2.0-rc.2 适配，http://127.0.0.1:3080 |
| SnowLuma | OneBot v11，需自行安装并扫码登录；WS 默认 3001，HTTP 默认 3000 |
| 数据库 | SQLite（WAL），无需额外服务 |
部署分三阶段，只有两步需要本人动手。
阶段一，准备环境。一台 Windows 电脑和一个 QQ 号；从官方渠道装好 DSH 并启动；准备一个会执行命令的 agent（Codex、Claude Code、Qoder、DSH 都行）。Node.js、Git、依赖、配置、preset 都可以交给 agent。
阶段二，把一句话发给 agent。
帮我在 Windows 上部署 https://github.com/Frostyume/xiaojingyu：先读仓库里的
docs/guides/AGENT_DEPLOY.md并严格照着做，自己检查环境、装依赖、写配置、跑install-dsh和doctor，直到全部通过；除了 SnowLuma 扫码登录和提供 QQ 号 / 群号，其余都自己完成；不要打印或上传config.json、state/里的任何令牌、Cookie 和号码。
它会按顺序问四件事：主人 QQ 号、允许哪些私聊和群（至少各填一个）、SnowLuma 的端口和 token、用哪个模型。空白名单时她不回复任何人，这一点要特别注意。
阶段三，亲手扫码并验收。从 SnowLuma Releases 下载SnowLuma-v<版本>-win-x64.zip，解压后双击launcher.bat，用启动日志里的地址打开 WebUI，同意条款、设置密码、扫码登录 QQ，然后在 WebUI 里开启WebSocket 服务端与HTTP API。这两件事必须本人做，因为 SnowLuma 的许可不允许脚本代装、代登录、代启动。之后 agent 会安装 DSH 端 preset 与 MCP，完整重启 DSH（不是刷新页面），再启动桥接并跑体检。
验收清单：
npm run doctor没有[FAIL]，DSH / SnowLuma / preset / 端口都是 OK；- 日志出现「SnowLuma 已连接」；
- 白名单内的 QQ 私聊能收到她的回复；
- 控制台
http://127.0.0.1:3100能打开，「运行总览」双健康； http://127.0.0.1:3100/live能看到状态页；- 没有向任何群聊发送测试消息（私聊验证就够了）。
部署完的第一小时，建议先做四件事：在「人格与角色」确认角色和两层提示词；到「群聊剧场」调唤醒频率、夜间静默和工具开关；只放行一个群、一个好友观察一天；在私聊里说「内心状态」「跑一次分享」试试生活功能。最后记得备份config.json、state/与personas/。
卡住了就把 agent 输出的「卡在哪一步 / 报错原文 / 已尝试什么」整段贴回给它，让它按AGENT_DEPLOY.md的故障表继续。不要删state/、关白名单或关鉴权来绕过问题——那不是修复，只是把门打开。
愿意手动来也行，docs/guides/MANUAL_DEPLOY.md的六步和 agent 执行的是同一套流程。
十四、已知限制
这些不是客套话，是会实际影响使用的地方：
- 开发版：版本号还是 0.0.0，没有 tag、没有 Release；
- 和 DSH 版本绑定：按 0.2.0-rc.2 适配，DSH 换大版本要先跑
npm run verify:adaptation； - 只有 Windows：QQ 和 SnowLuma 都是 Windows 程序，Linux / macOS 没有官方支持；
- 非流式回复：agent 回复在回合结束时一次性发送，按句分段，不做流式逐字转发；
- 视频只占位：图片、表情、合并转发能进上下文，入站语音要开 ASR，视频消息目前只占位；
- Markdown 转纯文本：回复里的链接会变成
文字 (url)的形式； - 没有按话题拆会话：同一个群里的多条话题共享一条上下文；
- 没有任务级进展看护：只有进程 / 端口 / 租约探活和「连续无行动」计数；
- 单机部署：不做跨设备同步、多租户或公网高可用；
- 有模型成本：规则能减少无效唤醒，但不能把调用降到零，长文和图片会明显增加 token；
- 不适合直接放大群：建议先只放行一个群、一个好友，观察一天再扩大白名单。
适合谁：有自己的群、想要一个「像群友」的 AI 而不是命令机器人；能接受 Windows 本地部署，愿意跑体检和看文档；在意数据落在自己机器上。不适合谁：想要一键安装开箱即用、需要 Linux 高可用、想要全天候营销号或自动客服。
十五、开源地址与许可
GitHub：https://github.com/Frostyume/xiaojingyu
文档在docs/下，部署、排查、能力清单、内心生活、代码提案、二次开发都有单独页面。项目基于上游 Derpyu520/qq-bridge（基线v0.2.0-r4）继续开发，MIT 协议，上游版权声明保留在LICENSE和UPSTREAM.md里。
如果只是想看看它长什么样，仓库里有控制台的离线预览，不需要连 DSH 或 QQ。
