鱼搭子 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 认证的开源许可，用之前请读一遍全文。