鱼搭子

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

这个仓库里两半都在：

> ⚠️ 两套版本号，别混：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 上直接看到这个包（含历史版本）：

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

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

挂件设置 → 游戏：

语音识别模型怎么选

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

• 每档后面标着「已装 / 没装」，下载按钮只下当前选中的那一档；换档不用重下别的档。
• 电话、陪看、按住说话用的是同一档。换完，陪看要点一下「开始听」、电话要挂断重打一次，才用新的。
• 机器上已经有一档装好的，不会被当成「没装」：默认值变了，也还是先用那份能用的。
• 老版本放错地方的模型（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": "说了什么", "图片": ""}
POST http://127.0.0.1:8777/hands/frame      {"图片": "", "立即": 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 认证的开源许可，用之前请读一遍全文。