dsh-companion · DSH 陪玩插件
在 Windows 上玩游戏、看视频或写代码时，让 DSH 定时观察屏幕，结合你设置的人格说几句，并通过本机语音朗读。面板支持暂停、手动“看一眼”、文字聊天、节奏设置、世界书、双色桌面字幕，以及最多三个角色一人分饰多角。语音链路默认使用本机 RVC 增强；没有增强包时会退回 Windows 系统语音。
当前版本：1.9.8（正式版）。欢迎通过 Issues 反馈问题。
使用条件
- Windows 10/11，安装并启动过 DSH 0.2.x。
- 在 DSH 中配置可用模型；识图模型需要支持图片输入，可在插件设置里单独选择。
- 基础插件不要求另装 Python、显卡或 RVC：截图可使用 PowerShell 兜底，朗读可使用 Windows 系统语音。
- RVC 语音为可选增强功能。可直接从陪玩设置中一键安装 CPU 运行环境；使用国内 npm、PyPI 和 PyTorch 镜像，模型需自行下载。
安装
在 DSH「插件 → 添加插件」中输入：
@jyddwy/dsh-companion@1.9.8
安装源可选择「中国大陆镜像源」。该镜像需要先同步本包的对应版本；安装成功后按 DSH 提示刷新或重启，打开右侧「陪玩」并点「看一眼」验证。
命令行等价方式：
dsh plugin --profile desktop add @jyddwy/dsh-companion@1.9.8
包名中的 @jyddwy/ 用于区分同名项目；面板和用户数据目录仍使用「陪玩」和 dsh-companion。完整说明见 INSTALL.md。
更新版本
插件不能自我更新，更新入口来自 DSH 插件管理：
- 在 DSH「插件 → 添加插件」里重新输入精确版本，例如
@jyddwy/dsh-companion@1.9.8，按提示覆盖安装后刷新/重启；
- 装了带「检查更新」的插件管理器 UI（如
@linxin666/dsh-web-all）时，插件详情页会多出「更新」区块；
DSH 自带/市场详情页不一定提供升级操作，需要手动输入版本；
- 命令行等价：
dsh plugin --profile desktop add @jyddwy/dsh-companion@1.9.8。
- 发布新版本时，维护者需要同步把 npm
latest 指向新版本，否则「检查更新」会按旧的 latest 判断：
npm dist-tag add @jyddwy/dsh-companion@<新版本> latest
可选：RVC 语音增强
先确认基础插件能正常使用，再打开「陪玩 → 设置 → 声音」，点击 下载并安装语音增强（CPU）。
- 安装器从国内源获取独立 Python、语音服务、RVC 推理代码和 CPU 依赖，无需访问 GitHub，无需手动安装 Python 或使用命令行。
- 需下载数百 MB，并预留约 3 GB 空间。面板显示安装状态和日志，支持取消、失败重试；退出 DSH 会取消安装。
- 不包含任何角色声线、HuBERT 或 RMVPE 模型权重，也不会自动下载模型。 环境装好后点击「打开模型目录」，按 模型指南 放置文件。
- 增强环境和模型存放于 DSH 用户数据目录的
dsh-companion/voice/，更新主插件会保留它们。主插件卸载后也保留这些用户数据。
- 如果之前装过旧语音运行时，设置页会提示「语音运行时较旧」；点「更新语音运行时」即可换到新版（模型保留）。情绪语调修复需要更新到这个版本。
- 如果本机已经有正在运行的本地语音服务（例如手动部署的开发环境），设置页会提示「已检测到本地语音服务」，不需要再点一键安装；一键安装只用于没有 Python/RVC 环境的机器。
- 此入口先提供 CPU 版，实际推理速度取决于硬件；已有手动配置的语音环境仍可使用。
日常使用
- 默认开启自动观察，观察间隔为 45 秒；设置里可调整间隔、连拍数量、画面大小和每小时观察上限。
- 前台场景可识别为游戏、看视频、写代码，也可以调整场景开关和游戏白名单。
- “暂停”停止自动观察；“看一眼”是用户主动发起的一轮观察，可在暂停状态下使用。
- 设置里的声线栏始终是下拉框：一键安装环境只列出实际已下载的声线模型（服务内置声线表里未下载的不会显示）；自定义外部语音服务仍用它返回的列表。
- 打开设置、语音增强安装完成、重启语音后会自动刷新声线；服务未启动或没有模型时会给出对应提示和「刷新声线」按钮，不需要刷新整个 DSH。
- 当前保存的声线暂时不可用（未下载/服务未启动）时会明确标注，但配置会保留，不会静默改成第一个声线。
- 使用 Windows 系统语音时会明确提示：RVC 声线/音调设置不生效。
- 情绪化语调已按 march7 实测收敛为「温和档」：保留语速和停顿的差别，音高偏移限幅，分句拼接处加淡入淡出和低电平底噪，减少之前那种忽高忽低、像换了人的感觉。
- 语音语言支持中文 / English / 日本語 / 한국어：字幕仍显示中文，TTS/RVC 用所选语言朗读。RVC 不需要语言包；Windows 系统语音后端需要在系统里安装对应语言。
- 设置里可切换语音后端、关闭朗读、调整人格与内置提示词。
- 桌面字幕支持：自定义延时、蓝白等双色渐变、字体下拉选择、鼠标穿透（默认不挡游戏瞄准；按住 Ctrl 临时拖动字幕调整位置）。字幕会等语音真正开始后再显示；正数延时表示“开口后额外等待”，RVC 较慢或多角色排队时会跟着实际开口时间一起推迟。
- 竞技游戏想彻底避开 RVC：在「语音后端」里直接选「只用 Windows 系统语音」；声线和音调会变成系统语音，但不会再因为 RVC 推理抢 CPU 卡游戏。
- RVC 低负载模式：限制 RVC worker 的 CPU 线程，语音可能晚半拍，但显著减少和游戏抢核心；多角色、多声线仍然保留。修改后建议重启语音服务生效。
- 一人分饰多角：原来的「人格」配置就是角色 1（主角色），打开总开关后可以在下面额外加入角色 2、3；每个额外角色有自己的角色卡、声线、名字、额外人设、语音语言和是否沿用 AGENTS.md。每名角色都有自己的开口概率，每轮独立掷骰，至少保底一个角色开口；接话顺序可随机。面板聊天由角色 1 回答。不同语言会让每个角色各多一次翻译模型调用，三语混用会增加延迟和 token 消耗。
- 角色越多，TTS/RVC 队列越长，低配机器越容易卡顿；建议先开 2 个。多人声线需要 RVC 语音服务，系统语音下所有角色会是同一个声音。
- 可在面板里打字聊天，或“开新对话”归档历史；游戏世界书支持生成和编辑。
- 没有本地语音增强服务时，语音后端保持“自动”或选择“系统语音”。
截图、数据与模型调用
截图会发送给 DSH 中配置的模型服务商，并非只在本机进行识图。 使用前请留意屏幕上可能被截入的内容，以及所选模型服务商的数据政策。
- 截图、配置、聊天历史、世界书和日志保存在
%USERPROFILE%\.dsh\dsh-companion\；设置了 DSH_HOME 时使用对应目录。
- 默认会自动观察识别出的陪伴场景；不希望自动观察时，请在面板中暂停或关闭总开关。
- 一轮观察通常包含识图和生成台词两次模型调用，重写台词可能增加调用。模型用量按你自己的服务商账户计算。
- 自动世界书调研会调用 DSH 的网页搜索与模型能力，查询游戏资料。
- 截图缓存可设置保留轮数、容量和时长，并可手动清理。
语音链路的隐私差异： edge-tts 会把要朗读的台词文本发送到微软的在线语音服务；Windows SAPI 在本机合成；RVC 变声在本机进行。不想让台词离开本机时，可选择“系统语音”后端，或关闭语音只留文字/字幕。
已知问题
- 多人模式会按角色数增加模型输出和 TTS/RVC 队列；角色越多越容易卡顿。先开 2 个、确认机器吃得消再开第 3 个。
- 情绪化语调已按 march7 实测收敛为温和档；不同声线、语速和文本下仍可能有听感差异，觉得不自然可以在声音设置里关闭，关闭后走 neutral 单请求。
- 字幕自动对齐依赖语音服务的
/status；系统 SAPI 下按子进程启动时刻估算，仍可能偏早或偏晚，可把“字幕延时”调大一点手动校准。
- 独占全屏、HDR 或受保护画面的捕获效果依赖具体程序与系统环境；遇到异常可尝试无边框窗口。正式版已在本机验证，但不同 Windows/显卡环境仍可能存在差异。
反馈时请提供：插件版本、DSH 版本、操作步骤、报错文字。日志在数据目录的 companion.log 和 services/ 中；分享日志、截图前请检查其中的私人信息。
开发与验证
插件代码无需构建。index.js 为宿主入口，client.js 为面板，宿主实现位于 src/host/，截图服务位于 services/，Windows 助手位于 win/。
本地验证可使用 Node.js 22 或更新版本：
node --test test/unit.test.mjs
node test/regressions.mjs cast
node test/fallback-regression.mjs
regressions.mjs 还包含截图缓存、世界书、模型用量、系统语音和多人角色等隔离场景。当前 125 项单元断言、18 个隔离回归场景和 19 个语音安装/设置渲染测试通过；这不代替真实设备验收。
许可与致谢
本项目代码使用 MIT License。参考与改编来源见 THIRD_PARTY_NOTICES.md。使用前请阅读 免责声明。
