kongbai-shike/dsh-novel-wallpaper

dsh-novel-wallpaper

English | 中文

把 TXT 小说变成 DSH 的「壁纸」。正文垫在整个界面背后，一个会隐身的小浮窗负责遥控。

等模型回话的几十秒，顺手看两页小说 —— 不用多开窗口，不用切标签页，也不占着对话区。 把鼠标挪开，界面就是原来的界面。

---

目录

• 它长什么样
• 安装
• 快速开始
• 阅读控制：滚轮与方向键
• 老板键
• 设置
• 分章规则
• 隐私
• 兼容性
• 设计取舍
• 开发
• 已知限制
• 反馈与贡献
• 许可

---

它长什么样

小说正文渲染成一个铺满窗口的文字层，压在 document.body 的 z-index: -2 上， 并且 pointer-events: none —— 它从不接触鼠标，点击永远落在真正的界面上。

上面盖一层可调浓度的压暗层（z-index: -1），再上面才是 DSH 自己的界面。 对话主区的底色被清成透明，于是文字就「透」出来了。

控制端是一个浮在半空的圆点：

截图待补。 仓库目前没有截图，欢迎你装完后自己截两张放进 assets/，再按 上架规范 加一个 screenshots.json，市场详情页就会用你自己的图。

---

安装

dsh plugin --profile web add github:kongbai-shike/dsh-novel-wallpaper

装完刷新页面即可，多数情况下不需要重启。

其它安装方式

指定 profile： 把 --profile web 换成你的 profile 名（桌面端常见的是 desktop）。

从本地目录开发： 把仓库软链到 profile 的 node_modules 下，再在 profile 的 package.json 里登记 dependencies 与 dsh.profile.bundles。DSH 的 HMR 会在你改完 client.js 后自动重载客户端半区。

卸载： dsh plugin --profile web remove @local/dsh-novel-wallpaper，或直接在 设置 → 插件里移除。

要求： DSH Web 0.1.0-rc.6 或更新版本（用到 shell.overlay 插槽与客户端快捷键服务）。

---

快速开始

1. 把 .txt 文件拖到窗口任意位置，或点浮窗 → 书库 → ＋。
2. 在目录里点一章，按 ▶ 开始自动滚动。
3. 滚轮或方向键随时接管；再按 ▶ / ❚❚ 暂停。

编码是自动识别的：UTF-8、UTF-8 BOM、UTF-16LE、UTF-16BE，都失败则回退 GB18030。 中文 TXT 乱码通常就是缺最后这一步 —— 大部分老书是 GBK/GB18030，不是 UTF-8。

自动滚动到本章结尾会停住，不会自己跳下一章。是刻意的：读到哪里由你决定。

---

阅读控制：滚轮与方向键

一次滚轮 / 一次方向键的位移 = 滚动速度 × 滚轮灵敏度（设置里可调，默认 6×）， 约 180ms 缓动到位。连续快滚会累加，不会每次都从头重新滑 —— 手感上就是一路滑下去， 而不是一格格地跳。

四条刻意设计的行为：

• 滚轮会「让位」。 鼠标停在还能滚动的区域（聊天记录、设置面板、目录列表）时， 滚轮归界面；滚到尽头、或停在空白处时，才轮到小说。所以「把聊天滚到底，接着往下滚」 就自然滑到小说上，不需要切换模式。 这条是必须的：小说垫在整个界面背后，全局霸占滚轮会让你再也滚不动聊天记录。
• 自动播放时滚一下 = 先暂停，转手动。
• 隐身档下滚轮和方向键全部失效 —— 老板键的意义就是把屏幕彻底还回去。
• 方向键必须带 Ctrl + Shift，且在输入框里永不生效。 因为 Ctrl+Shift+←/→ 是打字时「按词选中」，抢过来只会让编辑更难用； 焦点在输入框时光标照常移动。

方向键注册在 DSH 自己的快捷键服务上，不是全局键盘监听。因此它焦点感知、 会和其它插件做冲突检测、也能在 DSH 设置 → 快捷键里改键。命令 id：

novel-wallpaper.scroll-up    novel-wallpaper.scroll-down
novel-wallpaper.prev-chapter novel-wallpaper.next-chapter

方向键在该服务里属于保留键，desktop:windows、desktop:macos、web:windows 三个平台组合能通过校验，因此只声明了这三个默认绑定。其它平台可以在设置里自己绑。

---

老板键

Ctrl + Shift + `

切「隐身档」：文字不透明度降到 10%（即 90% 透明），浮窗淡到几乎看不见， 再按一次恢复。

隐身档的具体数值在设置里可调 —— 把它调成 0，就是彻底还原成原版 DSH 界面。 隐身档不会被记住，刷新后始终回到正常状态，这样浮窗永远找得回来。

---

设置

浮窗 → ⚙。全部设置存在 localStorage，只在本机。

分章正则默认是内置规则表里全部「安全」规则的并集，只匹配行首，所以正文里提到 「第一章」不会被误判成新章节。规则表、自动兜底和实测数据见 分章规则。

「界面清底程度」是反着的：1 = 把对话区底色完全清掉（文字最清楚，界面也最透）。 调低它，界面会重新变实，小说随之被压暗。

---

分章规则

TXT 的分章格式在野外千奇百怪，所以插件内置了一张规则表。默认值就是表里全部 「安全」规则的并集 —— 拿到一本书直接导入，通常就对了。

数字两侧的空格是关键。第 31 章 标题 这种排版在盗版 TXT 里非常常见，而紧贴的 第N章 一个都匹配不上 —— 更糟的是它静默失败：一本 486 章的书会整本变成一章 「全文」，没有任何地方报错。这一条曾经就是本插件的实际 bug。

纯数字标题（12、开端、001.、12、）单列一条规则，但默认不启用：行首 孤零零一个数字偶尔是正文，宁可让你在设置里手动点一下。

自动兜底

如果当前正则在你的书上匹配不到章节（标题少于 2 个），插件会把每条内置规则都试一遍， 按「命中数最多、且标题大多是短行」挑一条最好的，然后：

• 用它重新分章；
• 在状态栏写明用的是哪条规则 —— 不会偷偷无视你手写的正则。

判定时会要求至少一半的命中行是短行（≤ 40 字）——整段正文不可能符合。如果所有规则的 「标题」都是整段正文，它宁可不猜，保持原样：猜错比不分章更糟。

换规则不用重新导入

设置里改完分章正则会立刻按新规则重新分章，并写回书库。正则框下面是一排内置规则， 点一下直接套用；也可以手写任意正则。

显示的标题会先清洗一遍：

• 第 31 章 九叔的二徒弟 → 第31章 九叔的二徒弟（数字与单位之间的空格去掉）；
• 【第12章】标题 → 第12章 标题（拆括号）；
• 标题和正文首段挤在同一行时（第1章 标题　　正文…）只保留标题。

实测

《同穿：我的名字响彻诸天》（3.0 MB / 106 万字）：

那本书章节号编到 486，但第 119 / 166 / 167 / 371 / 439 章源文件里就没有 （盗版 TXT 常见的丢章），不是分章出错。插件分出的 481 章，就是文件里真实存在的全部。

---

隐私

纯客户端插件。 host 侧的 apply() 是空的。

• 正文存在浏览器 IndexedDB（TXT 动辄 5–20MB，localStorage 会直接爆配额）
• 进度和设置存在 localStorage
• 不写 session log、不注册任何工具、不给模型任何入口

也就是说：agent 在结构上读不到你在看什么。 不是「我们承诺不看」，是那条路根本没修。 所有解析、分章、渲染都在浏览器里完成，不经过网络。

---

兼容性

• 面向 DSH Web GUI（浏览器里的 dsh web，以及内嵌同一套界面的桌面客户端）。
• 实际运行验证于 DSH Web 0.1.7-rc.2（React 18.3.1）；最低要求 0.1.0-rc.6。
• 透明效果纯靠 CSS：清空 --dsw-alias-bg-base 这类不透明底色让下层透出来， 不依赖系统亚克力/毛玻璃，所以 Windows 上壳层材质设为 off 也照样工作。
• 和 dsh-plugin-wallpaper-engine 不叠加：本插件不透出图片壁纸。两个都想用， 需要把本层的 z-index 抬到图片壁纸层之上。

---

设计取舍

有些地方看着「不够聪明」，其实是故意的：

为什么滚轮不直接霸占全局？ 因为小说在所有东西背后。一个全局 wheel 监听会把聊天记录、设置面板、目录列表的 滚动全部吃掉 —— 那是不能接受的。所以做的是仲裁：从鼠标下的节点往上走，只要有一层 还能朝那个方向滚，就还给界面；都没得滚了，才轮到小说。代价是多走一次 DOM 链， 收益是两套滚动共存而不打架。

为什么章节读到底不自动进下一章？ 自动跳章意味着你低头回个消息，回来已经读丢了。停在章末，是安全的那一侧。

为什么方向键要带修饰键，而不是直接上下左右？ 不带修饰键的话，聊天框里按 ↑ 会去翻小说而不是翻输入历史，光标也会跳。 窄的收益配宽的破坏，不划算 —— 所以必须组合键，且 editable 区域直接不注册。

为什么快滚要累加而不是重新开始？ 第一版每次滚动都从「上一次动画的起点」重新算，连滚时每一格都在把之前的进度抹掉， 表现为「滚得越快越不动」。现在改从当前已画出来的位置重新瞄准， 所以连续输入会叠成一段连贯的滑动。

---

开发

node test/logic.test.mjs      # 解码 / 分章 / 字典覆盖 / 配色        24 项
node test/apply.smoke.mjs     # 载入 / 壁纸层 / 滚动 / 滚轮 / 快捷键   35 项（带 DOM stub）

两个都是零依赖的 node 脚本，直接跑，不需要装任何东西。 apply.smoke.mjs 自己搭了一套最小 DOM stub，能覆盖透明的绘制路径、滚轮的边界与仲裁、 快捷键注册的形状，以及销毁时是否留下残留。

目录结构：

client.js          # 全部逻辑：壁纸层、浮窗、阅读引擎、设置面板（浏览器半区）
index.js           # host 半区，apply() 为空
cordis.patch.yml   # dsh.bundle 清单，把插件挂进 DSH
test/              # 两个零依赖测试

改动集中在 client.js。它是一个 factory(require) 闭包，React 通过 h = createElement 使用，__internals 导出给无头测试用。

---

已知限制

• 只有对话主区被清成透明；侧边栏保持不透明（更隐蔽，也不影响可读性）。 想让侧栏也透，需要在 LAYER_CSS 里补 .dshDesktopSidebarSurface 的规则。
• 目录一次性渲染全部章节。上万章的巨型文本可能略有卡顿。
• 阅读进度按书 + 章节记，跨设备不同步（本来也不该同步 —— 正文只存在本机）。
• 没有图片/EPUB 支持，只有 TXT。这是取舍：TXT 解析能全在本地跑完，不留任何网络请求。

---

反馈与贡献

• Bug / 功能建议：直接开 issue。 带上你的 DSH 版本、操作系统，以及「怎么复现」。
• PR：欢迎。改动前先跑一遍上面两个测试；新增行为请顺手补一条用例 —— 这个仓库的测试是零依赖的，加一条成本很低。

---

⭐ 如果它对你的胃口

这个插件的起点很朴素：我想在等模型回话的时候，顺手看两页小说，又不想多开一个窗口。

如果你也有过这个念头，那它大概就是为你写的。

我希望能收获你的一颗 Star。 它不会让我赚到什么，但会让我知道 「原来不只我一个人需要这个」—— 也就有理由继续把还欠着的地方磨下去： 更细的滚轮手感、更好的大字排版、多书并行、目录分卷。

一颗星，就是一个「继续做」的理由。谢谢。

---

许可

MIT