Fairy-DSH

给 DSH 加一只看着您的 Fairy —— 浮层、HDD 视觉主题、朗读（可以不依赖显卡！）、余额、截图 Dock。

🔗 上游血缘：本项目整理自 橙汁本色 的 Fairy-DSH， 是它的分支优化版（对外叫 孤舟版）—— 在橙汁的代码上做分发：一条命令装完、出问题能自己查。

🤝 友情链接 · 生态里的三家（同一个源头，各干一段，别装重）

谁	仓库	是什么
🍊 橙汁本色（原作者）	Chengzhibense/Fairy-DSH	上游原始仓库。作者的最终目标是独立的 Electron 桌宠应用，这里是他的开发仓库，不含安装器、外人装不上
⛵ 孤舟版（本仓库）	Guzhou2002/Fairy-DSH-Optimized	在橙汁代码上做分发与排障：install.cmd 一条命令、Release + SHA256、朗读自检面板、面向新手的文档
☁️ 云朵版	addsas222/Fairy-DSH-Exp	另一套独立分发的功能深度实验版：人格包引擎、多会话模式、搜索枢纽、长期记忆、角色扮演+去 AI 味、多 TTS 引擎与语音输入

⚠️ 孤舟版与云朵版没有代码血缘、互不同步，而且装的东西会互相覆盖 —— 只装一个。 想折腾功能面，可以去看看云朵版；想装上就能用、出问题能自己查，留在这儿。

⚠️ 这是非官方整理分支。 基于 橙汁本色 的 Fairy-DSH 源代码整理而成， 上游原创代码按 Apache-2.0 发布。本分支只做安装分发和少量本地增强。

有问题请提到本仓库 Issues 或交流群 1124349108，请不要打扰上游作者。

📌 当前版本 v0.3.8 —— 版本号见仓库根 VERSION； 发布页 · 本版修了什么见 RELEASE-NOTES.md

装起来

🤖 让 Agent 帮你装

把下面这段话丢给你的 DSH Agent：

从 https://github.com/Guzhou2002/Fairy-DSH-Optimized 安装 dsh-fairy-visual 和 dsh-balance-meter和dsh-fairy-voice 到我的 web profile，不要装 dsh-fairy-startup 和 dsh-browser-dock。 更完整的说明见 AGENTS.md。 装完执行 dsh --profile web --dump-config 确认已经挂载。

🟢 完全不懂技术 → 下载、双击

📦 即装即卸

• 装（推荐）：下 install.cmd，双击 —— 自动装 3 个安全插件（视觉浮层 / 朗读 / 余额）
• 装全部 5 个：下 install_full.cmd，双击（装前会先把风险讲清楚并要求确认）
• 卸：下 uninstall.cmd，双击 —— ⚠️ uninstall.ps1 要一起下，两个放同一个文件夹里（那个 .cmd 只是启动器，真正的逻辑在 .ps1 里）
• 不想用安装器：直接下 5 个 .tgz，用 dsh plugin --profile web add <文件路径> 装

下载完 双击它，按屏幕上的中文提示走就行。缺什么它会自己装、自己说人话，失败了也会告诉你卡在哪一步、该怎么办。

🔒 卸载不删你的数据：参考音频、朗读设置、语音简报的 API Key 都在 ~/.dsh/fairy-voice/， 卸载脚本一个字节都不动 —— 要彻底清干净，脚本会在最后把这个路径打给你，删不删由你自己决定。

💡 这几个链接永远指向最新版 —— 收藏起来，想更新时重新下载再双击一次就行。

⚠️ 如果你是从 Releases 页面进来的，会看到一堆 .tgz 文件 —— 那些不用管，只需要下载里面的 install.cmd（或 install_full.cmd）；卸载则用 uninstall.cmd + uninstall.ps1。

🟡 会敲命令 → 一条就够

dsh plugin --profile web add `
  https://github.com/Guzhou2002/Fairy-DSH-Optimized/releases/latest/download/dsh-fairy-visual.tgz `
  https://github.com/Guzhou2002/Fairy-DSH-Optimized/releases/latest/download/dsh-fairy-voice.tgz `
  https://github.com/Guzhou2002/Fairy-DSH-Optimized/releases/latest/download/dsh-balance-meter.tgz

用的是别的 profile？把 web 换成你的 profile 名。 想装某几个而不是全部？把不要的那几行 URL 删掉。

⚠️ 装之前先看这张表

install.cmd 只装前 3 个。 后两个必须显式用 install_full.cmd 安装，它会先把风险讲清楚再问你。

装完做什么

💡 第 2 步不做的话，视觉和朗读都不会出现 —— 插件装好后默认是关着的，这是故意的。

需要什么

朗读功能：两条路线（GPT-SoVITS / MOSS-TTS-Nano）

dsh-fairy-voice 的朗读有两个引擎，默认仍是上游设计的本机 GPT-SoVITS：

在 设置 → Fairy → 朗读设置 → 朗读引擎 里切换，改完即时生效、不用重启； 两个引擎各自记住自己的地址，来回切换不会丢。参考音频两份共用，不用配两遍。

⚠️ MOSS 那条路要自己先装：在仓库目录跑一条命令即可（坑都写死了，可重复运行）

.\tools\install-moss.ps1

不想自己动手的：设置 → Fairy → 朗读设置 里有「复制安装说明」按钮， 把复制到的那段话发给你的 AI Agent，它会照着一份写好的说明去装。 装好后本仓库配套的 tools\moss-tts-server\server.py 就是它的服务端 —— 它为什么存在、为什么不用官方的 app_onnx.py，见下面「本地改动」里的说明。

⚠️ MOSS 是整句合成完再出声（不像 SoVITS 那样流式），所以按了朗读要等几秒才开始响， 这是设计如此、不是卡住了。本机实测约 0.45× 实时（10.5 秒合成 4.7 秒语音）。

GPT-SoVITS 这条路的具体要求

没跑 GPT-SoVITS 时：朗读按钮是灰色的、不会出声 —— 这是上游设计，不是故障。

你的东西放在哪（和插件代码是分开的）

为什么必须分开：dsh plugin add <包> 会把包解进 profile 的 node_modules， 而那是 pnpm 随时会重建的目录 —— 把音色和 API Key 放进去，升一次版本就没了。

所以你的东西一律留在 ~/.dsh/fairy-voice/：它由插件运行时自己创建， 跟插件装在哪、怎么装、装几次都无关。

先点一次「开始自检」（强烈建议）

群友最常见的困惑是"朗读不好使"，却看不出卡在哪一层。设置 → Fairy → 朗读自检 → 点「开始自检」， 会逐项给出结论与修法（7 项）：插件宿主 / 本地朗读服务 / 参考音频 / 真实合成一句话 / 浏览器音频能力 / 朗读控件是否挂上 / 消息识别。

面板底部的「复制诊断信息」会把结果写进剪贴板（不含任何聊天内容），直接粘到群里即可，不用截图、不用看日志。

自检面板里也写明了：朗读按钮与自动朗读开关只在真实会话页面出现， 首页和刚建的空白会话不显示 —— 这是 DSH 自身的设计。

设置里只有一个 Fairy 入口

原来有「HDD 视觉与 Fairy 身份」和「语音简报」两个入口，现在合并为一个：设置 → Fairy。里面还有：

• 朗读设置：SoVITS 地址（或 MOSS 地址）、参考音频路径 可直接改并保存，改完即时生效、无需重启
• 语音简报（可选）：原「语音简报」的 API Key 表单搬到了这里

说明：fairy-voice 没有语音输入功能。输入框左侧那个控件是「自动朗读开关 / 音量」， 不是麦克风；而且它只在 HDD 模式开启时出现。

自检工具

双击根目录的 verify.cmd，它会在临时目录里新建一套完全独立的 DSH 环境 → 启动 → 无头浏览器探针 → 自动清理。不会碰你现有的 profile。

DSH 升级后建议先跑一次（上游依赖官方 DOM 选择器与私有 slot 契约，升级后可能静默降级）。

兼容性：为什么它能跑在你的版本上

请勿自行"统一版本"。 dsh-fairy-visual 的宿主侧第一行是：

import { settingsNamespace } from '@deepseek-ai/dsh-settings';

该导出在 0.1.1-rc.2 存在，但在 0.1.2-rc.1 已被移除（改为 installSettingsSection）。 插件把依赖精确 pin 到 0.1.1-rc.2，因此 pnpm 会为它安装一份自己的副本； 而 settingsNamespace 只是「校验命名空间格式后原样返回字符串」，与宿主的 settings.register(ns, schema) 完全兼容。

一旦把这个依赖提升/覆盖成宿主的 0.1.2-rc.1，插件会在导入阶段直接失败。

升级提醒：上游设计依赖官方 DOM 选择器、ARIA 锚点与 slot 私有契约。 DSH 升级后若界面元素变化，插件会静默降级（有 capability 上报机制，不会崩）。

部署机制：dsh.bundle

每个插件包在 package.json 里声明了：

"dsh": { "bundle": { "patch": "./cordis.patch.yml" }, "client": { "platform": "web" } }

并各自带一个 cordis.patch.yml（只有一条 insert 行）。DSH CLI 在 plugin add 之后会把 声明了 dsh.bundle 的依赖自动追加进 dsh.profile.bundles，于是插件自动成为 profile 的一层。

0.1.x 的老写法已废弃：那时靠脚本往 profile 的 cordis.patch.yml 里写一个「Fairy-DSH managed block」。 现在如果你是从很老的版本升级上来的，install.cmd 不会再动那个块，遇到重复注册请手动清理。

环境要求

首次安装需要联网（从 GitHub 和 npm 拉取），装好后离线可用。

已知限制与注意

1. 会和别的 UI 插件抢 DOM：若你已装了其他改界面的插件（如 beauticode、whale-widget、 live2d-companion、liang-slider、ui-task-board），建议先禁用一部分再启用 Fairy。
2. fairy-startup 每次加载都会清空会话选择，谨慎启用（默认不装）。
3. fairy-voice 的长回答（≥260 字）会发往 api.deepseek.com 做语音简报， 密钥明文存于 ~/.dsh/fairy-voice/voice-brain.json。
4. browser-dock 会暴露控制 token、缓存页面截图，不建议安装（默认不装）。
5. 上游仓库自带的测试 profile 使用 danger-full-access + approval: never，本整合包未采用。
6. 上游仓库不含完整世界观语料、TTS 模型与用户数据；《绝区零》相关素材不随包分发， 本项目不授予相关版权、商标或官方关联权利。

本地改动（相对上游）

上游文件的所有改动都用 [local patch 0.x.x] 注释标注（Apache-2.0 §4(b) 对 modified files 的要求）。

完整说明已挪到独立文档（内容太长，放 README 里会喧宾夺主）：

📄 docs/本地改动.md

朗读引擎可切换 MOSS-TTS-Nano（0.3.2）· 消息识别适配（0.3.1）· 诊断信息与异常提示（0.3.1） · 分发方式（0.3.0）· 朗读自检与地址可配置（0.2.3）· 设置栏合并（0.2.0）

一句话版本：表现层（人设语料 / 布局 / 样式）自始至终一个字节没动； 改的都是安装分发、设置面板、朗读的读取适配层与引擎分支 —— 每处都有 [local patch] 注释，上面那份文档逐条对应。

许可与归属

• 上游原创代码：Apache License 2.0，作者 橙汁本色，见 LICENSE / NOTICE / UPSTREAM-README.md
• 第三方依赖：各自许可，见 THIRD_PARTY_NOTICES.md
• 本整合包：仅做整理与打包，不改变上游代码逻辑（例外见「本地改动」）
• 本分支作者：孤舟蓑笠 ｜ 交流群 1124349108

⚠️ 这是非官方分支，出问题请不要找上游作者

上游作者（橙汁本色）没有参与本分支的任何改动。安装脚本、设置栏合并、朗读自检、 人设一键默认这些都是本分支加的，找他解决不了，还会平白打扰人家。

• 本分支的问题 → 提到 本仓库 Issues 或进群说
• 本分支与上游的关系、如何合并上游更新 → 见 docs\仓库与上游.md

更多文档

出问题了？

🔎 先看这条：如果只是"朗读不出声"，不用翻日志 —— 设置 → Fairy → 点「开始自检」，它会逐项告诉你卡在哪一层，并给出修法。

下面按症状分组查。每行都写了「怎么认出来」和「怎么办」。

A. 装不上

B. 装上了，但界面上什么都没出现

C. 朗读不出声 / 按钮是灰的

D. 界面乱 / 变慢 / 和别的插件打架

E. 卸载 / 彻底重来

不会打命令？双击 uninstall.cmd （记得把 uninstall.ps1 一起下下来，放同一个文件夹）。

它会做七件事：备份 profile 与设置 → 卸掉装过的 Fairy 插件 → 把你改过的「新会话默认预设」还原回去 → 删掉人设预设目录 → 扫描历史版本残留 → 校验 profile → 把保留的用户数据路径打给你。

🔴 为什么一定要还原默认预设：不还原的话，settings.yaml 里还写着"新会话默认用 Fairy"， 而预设已经被删了 —— 结果就是**「点新建会话没反应」**。卸载反而把机器弄坏，这个脚本专治它。

会打命令就这样：

# 想手工卸（脚本也走同一条路）
dsh plugin --profile web remove dsh-fairy-visual dsh-fairy-voice dsh-balance-meter

# 老版本（0.2.x）可能留过受管块、或 package.json 里有残留行，加开关让脚本一起清（会先备份）
.\uninstall.ps1 -CleanBundle

🔒 卸载不删用户数据：~/.dsh/fairy-voice/（参考音频 / 朗读设置 / 语音简报 API Key）原样保留。 要彻底清干净就自己删那个目录 —— 删了就找不回来。

也可以双击根目录的 install.cmd 重装一遍 —— 它同时是安装器和修复器。

F. 要把问题发到群里

别截图、别贴日志 —— 设置 → Fairy → 面板最底部点「复制诊断信息」， 把结果直接粘进群里就行。它不含任何聊天内容，只有字段名和状态。

🤖 让 AI Agent 帮你排查：本仓库的 AGENTS.md 里有一份更细的故障判定表 —— 每一行都写了"看到什么信号 = 卡在哪一层 = 该做什么、什么时候必须停下来问人"。 可以把那份文件直接喂给你的 DSH Agent。