Guzhou2002/Fairy-DSH-Optimized

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 个：视觉浮层 + 朗读 + 余额 | ✅ 推荐，绝大多数人用这个 |
| install_full.cmd | 装全部 5 个（多装启动画面 + 截图 Dock，有已知风险） | ⚠️ 清楚后果、确实想要的人 |
| uninstall.cmd | 卸：卸掉插件与预设，并把你改过的「默认预设」还原回去 | 🧹 不用了、想清干净的人 |

📦 即装即卸

- 装（推荐）：下 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。

🟡 会敲命令 → 一条就够

markdown
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 删掉。

⚠️ 装之前先看这张表

| 插件 | 干什么 | 建议 |
| --- | --- | --- |
| dsh-fairy-visual | 核心。宠物浮层、HDD 主题、界面重绘、设置里的 Fairy 面板 | ✅ 推荐 |
| dsh-fairy-voice | 朗读回复（可接本机 GPT-SoVITS，也可用浏览器自带语音） | ✅ 可用，朗读需额外配置 |
| dsh-balance-meter | 侧栏显示 DeepSeek 余额 | ✅ 可用 |
| dsh-fairy-startup | 启动画面 | ⚠️ 谨慎：每次启动都会清空会话选择并自动开新会话，你上次没结束的对话可能就找不回来了 |
| dsh-browser-dock | 截图 Dock | ❌ 不建议：控制 token 会交给任何能访问 Web 端口的程序；页面截图会落盘；takeover 功能还硬编码了 macOS 路径，Windows 上根本用不了 |

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

装完做什么

| 步骤 | 做什么 |
| --- | --- |
| 1 | 重启 DSH（关掉再打开） |
| 2 | 设置 → Fairy → 把最上面的「启用」打开 |
| 3 | （可选）想把 Fairy 当默认人设：同一个设置页里打开「Fairy 人设预设」 |
| 4 | （可选）想用朗读：点「开始自检」，看能不能出声 |

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

需要什么

| 项 | 说明 |
| --- | --- |
| DSH | 已装好、能正常启动 |
| Node.js | ≥ 20。install.cmd 会检查；缺了它会告诉你去哪装 |
| pnpm | ⚠️ 装 DSH 时不会自带它。用 install.cmd 会自动帮你装；手动装是 npm install -g pnpm |
| 网络 | 要能连上 GitHub Releases 和 npm 仓库。国内建议挂代理，否则可能卡在下载那一步 |
| GPT-SoVITS | 只有用朗读功能才需要。不装也能用其他部分 |

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

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

| 引擎 | 需要什么 | 适合谁 |
| --- | --- | --- |
| GPT-SoVITS（默认，上游原路） | 本机跑 SoVITS（127.0.0.1:9880）+ 参考音频。流式：边合成边播 | 有显卡、想要最好的音色 |
| MOSS-TTS-Nano | 装一套 MOSS（本机 127.0.0.1:18083）+ 同一个参考音频。CPU 就能跑，不要显卡 | 没显卡、不想折腾 SoVITS |

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

⚠️ MOSS 那条路要自己先装：在仓库目录跑一条命令即可（坑都写死了，可重复运行）
powershell
.\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 这条路的具体要求

| 项 | 要求 |
| --- | --- |
| TTS 服务 | 默认本机 http://127.0.0.1:9880；可在设置里改成别的端口或另一台机器 |
| 参考音频 | ~/.dsh/fairy-voice/reference/fairy_ref.wav（路径可在设置里改）；建议 3–10 秒干净人声。该目录插件启动时自动创建 |
| 参考文本 | 同目录 fairy_ref.txt（缺失时用内置回落文案，不影响出声） |

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

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

| | 路径 | 说明 |
| --- | --- | --- |
| 插件代码 | 源码装：你 clone 的目录 / ~/.dsh/plugins/…dsh plugin add 装：profile 下的 node_modules | 随时可能被重装、清掉、换版本 |
| 你的数据 | ~/.dsh/fairy-voice/ | reference/（音色）、runtime/config.json（设置）、voice-brain.json（语音简报密钥） |
为什么必须分开：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 不会再动那个块，遇到重复注册请手动清理。

环境要求

| 项 | 要求 |
| --- | --- |
| 系统 | Windows（脚本为 PowerShell；插件本身跨平台） |
| DSH | 0.1.2-rc.1 实测通过；上游在 0.1.1-rc.2 验收 |
| Node.js | ≥ 20 |
| pnpm | 安装时需要，用于装插件依赖 |
| 浏览器 | 自检时需要 Chrome 或 Edge（脚本会自动探测） |

首次安装需要联网（从 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）
One-sentence version: The presentation layer (persona corpus / layout / styles) has not changed by a single byte from start to finish;
Everything changed is the installation and distribution, the settings panel, the reading adaptation layer, and the engine branch — each place has a [local patch] comment, corresponding one by one to the document above.

License and Attribution

- Upstream original code: Apache License 2.0, author 橙汁本色, see LICENSE / NOTICE / UPSTREAM-README.md
- Third-party dependencies: their respective licenses, see THIRD_PARTY_NOTICES.md
- This integration package: only organizes and packages, does not change upstream code logic (for exceptions see "Local Changes")
- Author of this branch: 孤舟蓑笠 ｜ Communication group 1124349108

⚠️ This is an unofficial branch; if there are problems, please do not contact the upstream author

The upstream author (橙汁本色) did not participate in any changes in this branch. The installation script, settings bar merge, reading self-check,
and one-click persona defaults were all added by this branch. Contacting him cannot solve them, and will also needlessly disturb him.

- Problems with this branch → file them at this repository's Issues or ask in the group
- The relationship between this branch and upstream, and how to merge upstream updates → see docs\仓库与上游.md

More Documentation

| File | Content |
| --- | --- |
| AGENTS.md | For AI Agents: standard installation instructions, installable/non-installable checklist, fault determination table (including the "stop and ask a human" checklist) |
| docs\本地改动.md | What this branch changed relative to upstream, and why (distribution method / message recognition adaptation / diagnostic panel / MOSS engine / settings bar merge) |
| docs\接手-v0.3.2.md | Read this first when taking over this repository: what was done last round, what remains undone, lessons learned this round |
| docs\交接摘要.md | Full archive: current status, to-dos, all pitfall records (including the .cmd encoding trap) |
| docs\Release正文模板.md | For filling in the Release body when publishing (includes a "pre-submit self-check" checklist, to prevent again omitting "which to download / what to do after installation / SHA256") |
| docs\安装机制实测.md | Actual test records of various forms of dsh plugin add |
| docs\仓库与上游.md | How to merge upstream updates |
| docs\改动清单.md | File classification list relative to upstream (added / modified / renamed / deleted) |
| docs\install-moss.md | Task brief for AI Agents: install MOSS-TTS-Nano (the second engine for reading, can run on CPU) |
| docs\调研-同源项目Fairy-DSH-Exp.md | Cognate projects in the ecosystem + DSH runtime contract (including "same-named group id will freeze the event loop") |
| docs\调研-CPU音色克隆引擎.md | Research on voice cloning engines playable without a graphics card (MOSS-TTS-Nano, etc.) |
| docs\旧版说明-v0.2.3.md | Archive of old documentation for v0.2.3 and earlier (no longer applicable, for reference only) |
| legacy\README.md | Description of deprecated old scripts |

Something wrong?

🔎 Read this first: if it is just "reading produces no sound", no need to dig through logs —
Settings → Fairy → click "Start Self-Check", and it will tell you item by item which layer is stuck and give a fix.

Below, check by symptom groups. Each row states "how to recognize it" and "what to do".

A. Cannot install

| Symptom | How to recognize / what to do |
| --- | --- |
| Double-clicking .cmd flashes and disappears | The window vanishes instantly, nothing seen. Run it once from the command line to see what it says: Win+R → type cmd → Enter → drag the .cmd file into the black window → Enter |
| Stuck downloading for a long time without moving | Network problem. Try again with a proxy; you can also use install.cmd (it has built-in network self-check) |
| A bunch of garbled text at the start + 'xx' is not recognized as an internal or external command, but the title and some prompts display normally | ⚠️ This is the installer's encoding being broken, not your operation problem. Type chcp in the command line: if it shows 936, your machine will be affected. Download the installer again; if it still fails, ask in the group |
| Reports dsh: pnpm failed | pnpm is not installed. Run npm install -g pnpm, then retry |
| Prompts 404 / cannot download the file | You used an old link with a version number. Use the two latest/download links above in this document — they always point to the latest version |
| Prompts missing Node / pnpm | Node must be ≥ 20; for pnpm use npm install -g pnpm (it is not bundled when installing DSH) |

B. Installed, but nothing appears in the interface

| Symptom | What to do |
| --- | --- |
| No change at all | 99% it is these two steps not done: ① Restart DSH (close and reopen) ② Settings → Fairy → turn on "Enable" at the top. After the plugin is installed, it is off by default; this is intentional, not broken |
| Restarted and enabled, still nothing | Run dsh --profile web --dump-config, and check whether the output contains fairy-visual |
| Cannot find "Fairy" in settings at all | Same as above; and confirm you installed dsh-fairy-visual (it is the one that provides the settings panel) |
| Reports settingsNamespace does not exist | Dependencies were resolved incorrectly — see the "Compatibility" section above. Never "unify versions" yourself |

C. Reading produces no sound / button is grayed out

| Symptom | What to do |
| --- | --- |
| The reading button is gray | First confirm: is GPT-SoVITS running locally (127.0.0.1:9880). If not, the button is gray — this is upstream design, not a fault |
| SoVITS is running but still no sound | Settings → Fairy → click "Start Self-Check". The 7 items will tell you item by item which layer is stuck: plugin host / local reading service / reference audio / actually synthesizing one sentence / browser audio capability / reading control / message recognition |
| 自检说缺参考音频 | 放一段 3–10 秒干净人声到 ~/.dsh/fairy-voice/runtime/reference/fairy_ref.wav（路径也能在设置里改）。同目录的 fairy_ref.txt 缺失不影响出声（有内置回落文案） |
| 朗读控件整个不见 | 有三个前提：装的是 fairy-visual、HDD 视觉模式已开、而且必须停在真实会话页面 —— 首页和刚建的空白会话就是不显示，这是 DSH 自身的设计 |
| "输入框左边那个是不是麦克风？" | 不是。 fairy-voice 完全没有语音输入功能。那个控件是「自动朗读开关 / 音量」，而且只在 HDD 模式开启时出现 |

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

| 症状 | 怎么办 |
| --- | --- |
| 界面元素错位、被挤掉 | Fairy 会和改界面的插件抢 DOM。先禁用其他同类插件，再启用 Fairy：beauticode、whale-widget、live2d-companion、liang-slider、ui-task-board |
| 用久了变卡 | 已知未覆盖项：Fairy 含页面级动画与监听（document.body 级监听 + rAF 动画 + 定时器），没有做过长时间压测。卡的话先关掉「启用」开关，再进群反馈 |

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。