Yuuyuko-uu/dsh-fish-buddy

桌面上一只小鲸鱼挂件 + 一个 DSH 插件。挂件负责听、看、说（语音、陪看字幕、游戏弹幕、截图）， 插件负责把它和你绑定的一间会话接起来 —— 挂件说的话进那间会话，那边的回话再递回挂件。

这个仓库里两半都在：

目录	是什么
app/	桌面挂件（Python + tkinter，打包成单文件 exe）
lib/	DSH 插件（宿主半边 + 设置页）
tests/	插件与程序的测试

⚠️ 两套版本号，别混：app/ 是挂件程序，lib/ 是 DSH 插件，各自独立涨（不是同一个数）。

• 当前是多少：看 app/version.py 和 package.json（README 里故意不写死，免得每发一版改一次）
• 改了什么：看 CHANGELOG.md，条目开头会写「程序」还是「插件」
• 下载：看 Releases（exe 的资产名带版本号）

插件这半边干什么

1. 在本机开一个口子（默认 127.0.0.1:8777），收挂件发来的话；
2. 把这句话送进你绑定的那间会话（相当于你在那间里说了一句）；
3. 她那间回完一轮 → 把回话递回挂件（POST 到你填的回调地址）；
4. 收到截图/游戏画面时，把图片本身发进会话（先存成附件再引用）；
5. 设置页里能看到：口子通不通、发来几条、最近发生了什么、她最近说的一句。

素材说明

app/assets/ 里的角色图、气泡框、弹幕框是随程序一起分发的素材，不单独授权二次使用。 app/assets/ocr/ 里是 PP-OCRv6 的检测/识别模型（Apache-2.0），app/assets/字体/ 里是站酷快乐体（免费商用）。

装好之后怎么配

先把插件装上（已经发布到 npm，不用 git）：

dsh plugin --profile desktop add dsh-fish-buddy

也可以在 npm 上直接看到这个包（含历史版本）：https://www.npmjs.com/package/dsh-fish-buddy

装完重启一次 DSH；挂件那个 exe 另外去 Releases 下。

DSH 设置 → 鱼搭子（第一栏）：

项	填什么
开着	默认开。关掉之后挂件发什么都不往里送
送到哪一间	从下拉里选你那间会话（没选就送不进去）
本机口子	端口，默认 8777。改端口要重启 DSH 才生效
回话递回	挂件那边留的接收地址，例如 http://127.0.0.1:8778/hands/reply
标一句来源	塞进会话时前面加「（挂件里说的话）」，方便你分清是打字的还是说的
截图留几天 / 最多几张	插件自己攒的截图按这两条清（默认 30 天 / 800 张，填 0 = 那一条不限）；只删它自己目录里的图
检查更新	点「查一下」：同时查插件本身（对比仓库 main 上的版本）和挂件 exe（对比最新 release）

挂件设置 → 游戏：

项	填什么
截图怎么送	每张都说一遍：截一张就发一轮；攒着，说话时一起看：只存着，你说话（或她主动看一眼）时全部带过去
她主动看一眼	每 N 分钟自己开口一次（只在「攒着」那一档生效；「每张都说」时截图本来就叫醒她，再叠一层就是白花钱）
组合键	退出游戏模式 / 锁解锁弹幕框，默认 Alt+G / Alt+H，写法 Ctrl+Alt+G、F9 都行
锁住弹幕框	锁上就是真穿透（鼠标穿到游戏里），解锁用右键菜单或这一项

语音识别模型怎么选

挂件 设置 → 语音 → 识别模型，三档选一个，装的时候只下选中的那一档：

档	大小	什么样
小	228MB	默认。省 CPU，平时说话够用 —— 拿不准就选它
大	894MB	识别最准，也最吃 CPU 和内存；机器一般的话，别的程序会跟着变慢
最快	78MB	最省，但不出标点，字幕会连成一片

• 每档后面标着「已装 / 没装」，下载按钮只下当前选中的那一档；换档不用重下别的档。
• 电话、陪看、按住说话用的是同一档。换完，陪看要点一下「开始听」、电话要挂断重打一次，才用新的。
• 机器上已经有一档装好的，不会被当成「没装」：默认值变了，也还是先用那份能用的。
• 老版本放错地方的模型（models\sensevoice-fp32\、models\ 根上的 model.int8.onnx） 第一次启动会自动搬到该在的目录，不用重下。
• 目录约定：models\ 根上是「大」，models\int8\ 是「小」，models\paraformer\ 是「最快」； 每档目录里都叫 model.onnx + tokens.txt。

下不动的时候：2026-10-30 凌晨实测，国内镜像 hf-mirror.com 在限流 / 跳转，官方 huggingface.co 直连不通，那一刻确实下不了。下载本身（按档选仓库、按档落目录、断点续传、失败重试）是验过的， 网络好了再点一次就行；已经下到一半的部分不会作废。

插件自己攒的截图会自己清

陪看抽的帧、她主动开口那张、按住说话带的那张，插件都在 ~\.dsh\fish-buddy-frames 留一份。 以前只进不出，用久了能堆几十上百 MB —— 现在按两条清：

• 留几天（默认 30）、最多几张（默认 800），在 DSH 设置 → 鱼搭子 → 第一栏里调；填 0 = 那一条不限。
• 插件一起来先清一次，之后每写一张图顺带看一眼（十分钟最多查一次目录，不会一直扫盘）。
• 只删这个目录里的图片（.jpg / .png），别的地方一概不碰；删了会在设置页「最近发生了什么」里记一行。

协议（挂件那边照这个对接）

挂件 → DSH

POST http://127.0.0.1:8777/hands/say        {"text": "说了什么"}
POST http://127.0.0.1:8777/hands/talk       {"text": "说了什么", "图片": "<base64，可省>"}
POST http://127.0.0.1:8777/hands/frame      {"图片": "<base64>", "立即": 1|0, "存档": 1|0, "来源": "游戏"}
POST http://127.0.0.1:8777/hands/mode       {"游戏": true|false}
POST http://127.0.0.1:8777/hands/subtitle   {"字幕": [{"文本": "…", "ts": 1690000000}]}
POST http://127.0.0.1:8777/hands/watch      {"watch": true|false}

• /hands/talk 会把攒着的截图一起带过去（图片 可省）
• /hands/frame 的 存档=1：只存不叫醒（「攒着」用）；立即=1：立刻发一轮
• /hands/say 也可以带 "session": "session-xxx" 指定这一次送进哪间
• 回：{"ok": true, "说": "送进去了"}；没绑会话 / 会话没开 / 总开关关着 → 409 + 一句人话

DSH → 挂件

POST <设置页里填的回调地址>      {"text": "她那句", "session": "session-xxx"}
GET  http://127.0.0.1:8778/hands/devices    → {"ok": true, "设备": [...], "版本": "<挂件版本>"}

• 只递「挂件叫起来的那一轮」：你自己在 DSH 里聊的，不会往挂件推
• 回调没填就什么都不发（不会报错）

已知边界

• 端口是启动时定死的：改端口要重启 DSH。
• 会话得在 DSH 里打开过一次，否则 agents.get() 找不到它（会回一句「那间会话没开着」）。
• 每送一句话 = 一轮模型请求 = 花额度。上下文越长越贵：同一个上下文每轮都要重读一遍， 所以「一小时说了多少次话」直接决定账单（实测：一小时 111 次、每次约 60 万 token 上下文 → 几十块）。
• 游戏截图会制造轮次：「每张都说」一小时能叫醒她几十轮；「攒着」只在你说话 / 主动看一眼时花一次。 攒着的图不删、不重复发，但攒得越多，那一次带过去的图越多、越贵。
• 回话只取那一轮里最后一段文字；纯图轮的没有文字，不递。
• 攒图队列在内存里：DSH 重启就清空。图本身分两处：挂件自己在 %LOCALAPPDATA%\鱼搭子\frames 留最近 20 张，插件收下的在 ~\.dsh\fish-buddy-frames（按天数和张数自己清，见上面那节）。

自测

node tests/宿主半边.mjs        # 75 项：真的起一个 http 口子发请求，不碰真实 DSH
node tests/网页半边.mjs        # 设置页那半边
node tests/inbound-batching.mjs   # 群消息攒批
node tests/inbound-lifecycle.mjs  # 收消息生命周期
node tests/inbound-singleflight.mjs

挂件那边：python ball.py --selftest（108 项，含热区、气泡、弹幕、快捷键）。

一起看（字幕白板）

挂件的陪看在放视频/直播时，每出一句定稿字幕就推给插件（POST /hands/subtitle）。 插件按会话留最近 90 秒、最多 40 句，每轮用 systemPrompt.context 现拼一段「【你正在看的】…」（挂在消息尾部，不动系统提示词的前缀，缓存才不掉）——

• 不写进对话历史，所以不会越看越厚；没字幕时是空串，不占上下文；
• 她一眼看完，想说的时候再说，不用每句都应；
• 另外可开「随机搭话」（随机搭话分钟）：每隔这么久掷一次骰子，中了就让 DSH 开一轮让她自己说一句。

打游戏

进游戏模式之后：悬浮球收起来，桌面只剩飘的弹幕（它说的话横着飞过去）和弹幕框（攒着最近几句）。

• 弹幕 / 弹幕框 / 气泡都做了「缺字换字体」：主字体（站酷）没有的颜文字、符号自动换系统字体补，不出方块；
• 截图按设定间隔抓，三种送法见上面「挂件设置 → 游戏」（每张都说 / 攒着）；
• 主动看一眼：攒着那一档里，隔 N 分钟她自己开口一次，顺带把攒的图带上；
• 锁定：弹幕框锁住后是真穿透，全屏游戏里鼠标不会被它接住；解锁走右键菜单 / 设置 / 组合键；
• 弹幕框可以拖到副屏；弹幕本身只在主屏横飞（跨屏会两边各一半）。

已经能用的

• 插件：接线、回话递回、字幕白板、随机搭话、游戏截图三种送法、主动看一眼、检查更新、设置页
• 挂件：电话（语音识别）、一起看（字幕）、游戏模式（弹幕 + 弹幕框 + 截图）、气泡、 多显示器摆位、颜文字混排、组合键、锁定穿透

（各版本改了什么、最新是多少 —— 见 CHANGELOG.md 和 Releases。）

---

许可

Yuuyuko-uu 插件许可 1.0：允许使用、修改、商用； 再分发时要在 README 第一屏注明原仓库和原作者；禁止把本项目说成自己的原创。 这份许可不是 OSI 认证的开源许可，用之前请读一遍全文。