# dsh-reader

**Repository Path**: laoliuspace/dsh-reader

## Basic Information

- **Project Name**: dsh-reader
- **Description**: DSH 摸鱼阅读插件 dsh-plugin：底栏一行小说，快捷键翻页，本地 TXT/EPUB 与在线阅读。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: dsh-plugin, deepseek-harness, dsh, Reader, novel

## README

# 摸鱼阅读 · dsh-reader

> 在 DeepSeek Harness（DSH）Web 界面的底部状态栏，推送一行小说正文。
> 键盘翻页、自动翻页、老板键一键隐藏；本地 TXT / EPUB 与在线阅读都支持。

一个给 DSH 用的「摸鱼看小说」插件：正文出现在会话底部 token 用量右侧，只有一行、
只有正文，不显示书名/章节/页码，鼠标悬停也不会有任何提示。设置、书架、书源都在
DSH 设置页的「阅读」分区里。

> 本项目是参考 IDEA 插件 **chapter_reader** 的功能重写，内置站点库也来自它。
> 请先读 [出处与致谢](#出处与致谢)。

---

## 截图

### 阅读效果

底栏 token 用量右侧的一行正文；老板键隐藏时只显示 `···`。

![阅读效果](dsh-reader/docs/images/reading.png)

### 设置页

书籍文件 → 公共书架 → 来源（本地 / 在线）→ 显示 → 章节列表 / 快捷键（折叠）→ 操作条。

![设置页](dsh-reader/docs/images/settings.png)

> 截图由项目作者提供并授权用于本 README 与 npm 包内 README；图中的书名、进度与用量只是示例阅读状态。

## 功能

- **底栏一行纯正文**：无书名、章节名、页码、tooltip 或 hover 浮层；无书/加载中自动隐藏。
- **老板键**：默认 `Alt + Shift + H`，按一次只显示 `···`，正文完全不进 DOM；
  翻页/翻章快捷键会自动恢复显示；自动翻页静默推进、不解除隐藏。
- **本地书**：TXT（UTF-8 / UTF-16 BOM / GB18030）与 EPUB（ZIP + OPF/NCX，无第三方依赖）。
- **三种阅读模式**：章节模式（可配置章节正则）/ 按字数 / 按换行。
- **公共书架**：本地与在线共用一个书架，最近 20 本，每本独立进度；移除只删记录不删文件。
- **选书器**：设置页「浏览…」调用宿主原生目录选择器，列出目录下的 `.txt` / `.epub`，
  点选即打开（DSH 只提供目录选择器，没有文件选择器）。
- **在线阅读**：粘贴「章节目录 URL」→ 抓目录 → 抓正文 → 分页；支持多页章节合并、
  自定义书源、节点调试、3000+ 条内置站点规则、正文缓存与离线回退。
- **快捷键**：8 个动作全部可在设置页录制/清除/恢复默认，按 `event.code` 精确匹配。
- **安全**：抓取仅 http/https，每一跳做 DNS 解析 + 私有网段拦截 + DNS pinning；
  请求总超时、正文/缓存大小上限、正则回溯防护。

## 环境要求

- DeepSeek Harness **0.2.1-rc.2** 或兼容版本，Web profile（需要 `webServer`）。
- 零第三方依赖，不需要 `pnpm install`。
- 插件作用于当前 profile 的所有会话；刷新页面后生效。

## 安装

### 方式 A：npm 包名（推荐）

插件已发布到 npm：**`dsh-reader`**。

1. 打开 DSH Web → 左侧 **插件 / Plugins** → **添加插件**。
2. 包名填 `dsh-reader`（可带版本，如 `dsh-reader@1.0.0`）。
3. 如果默认 registry 是 npmmirror 且刚发布搜不到，把安装对话框里的 **Registry** 切到官方 npm，或等镜像同步几分钟。
4. 安装完成后刷新页面。

也可以直接让 DSH 里的 AI 装：

> 用 plugin_manager 把 `dsh-reader@1.0.0` 作为 bundle 安装并启用。

对应工具参数：

```json
{ "action": "install_bundle", "target": "dsh-reader@1.0.0" }
```

返回 `application: applied` 即生效。

### 方式 B：本地目录

适合改代码/离线使用：

1. 插件管理页 → 添加插件 → 选择「本地目录 / 安装第三方插件」。
2. 填本仓库 `dsh-reader/` 目录的**绝对路径**。
3. 安装完成后刷新页面。

### 方式 C：手动

把 `dsh-reader/` 放到任意位置，在 profile 的 `cordis.patch.yml` 中插入：

```yaml
- insert:
    - id: dsh-reader
      name: 'dsh-reader'
```

重启 DSH。

安装后 **设置 → 阅读** 出现即成功；没有配置书时底栏不显示任何内容。

## 快速开始

1. 刷新页面，打开 **设置 → 阅读**。
2. **本地书**：点「浏览…」选目录 → 点 `.txt` / `.epub`；或直接填绝对路径后「打开」。
3. **在线书**：切到「在线」→ 填章节目录 URL →「解析并阅读」。
4. 焦点留在页面任意位置，按快捷键翻页。

### 默认快捷键

| 动作 | 默认绑定 |
|---|---|
| 下一页 / 上一页 | `Alt + ]` / `Alt + [` |
| 下一章 / 上一章 | `Alt + Shift + ]` / `Alt + Shift + [` |
| 本章第一页 / 最后一页 | 未绑定（可录制） |
| 自动翻页开关 | `Alt + \` |
| 老板键（只隐藏） | `Alt + Shift + H` |

录制规则：必须带 `Alt`/`Ctrl`/`Meta`；`Esc` 取消；`Delete`/`Backspace` 清空；
同一组合不能绑定两个动作。快捷键按物理键位（`event.code`）匹配。

### 老板键说明

- 按一次 → 底栏只显示 `···`，正文从 DOM 移除。
- 再按老板键 **不会** 恢复（防止误触暴露）。
- 按下一页/上一页/翻章/章首页末页 → **先恢复再执行**。
- 自动翻页在后台推进，但不会解除隐藏。
- 隐藏态只在内存，刷新页面默认显示正文。
- 绑定保存在浏览器 `localStorage['dsh-reader.bossKey']`：仅当前 DSH Web origin，
  换端口/浏览器、无痕模式或清站点数据会回默认 `Alt + Shift + H`；`settings.json` 不含它。

## 在线阅读

1. 「来源」切到「在线」（只切配置面板，不会切书）。
2. 填目录 URL（`http` / `https`），点「解析并阅读」。首次解析需要几秒。
3. 翻页/翻章与本地书一致；跨章时才抓新章，失败保留当前页并在设置页红字提示。
4. 内置 3000+ 站点规则；规则不匹配时回退启发式，仍失败可用「节点调试」自定义。
5. 正文缓存到 `$DSH_HOME/reader/cache/`，最多 200 章；离线时回退缓存。

已知限制：
- 只抓静态 HTML；JS 渲染站、验证码、Cloudflare 会明确报错。
- 部分站点用字体混淆（Unicode 私用区）反爬，正文会缺字，这不是编码 bug。
- 内置规则可能随站点改版过期；可在「自定义书源」覆盖。

## 数据与卸载

运行数据在 `$DSH_HOME/reader/`（Windows 默认 `%USERPROFILE%\.dsh\reader` 或 DSH 安装目录下）：

| 文件 | 内容 |
|---|---|
| `settings.json` | 书路径、模式、正则、字数/字号/自动翻页、7 个宿主快捷键 |
| `shelf.json` | 书架（≤20）与每本书进度 |
| `sources.json` | 自定义书源 |
| `cache/` | 在线正文缓存（≤200 章） |
| `progress.json` | 旧版进度（仅首次迁移读取，保留不写） |

- 书本身不会复制进数据目录，始终读原路径。
- 卸载插件不会删除这些文件；手动删除会丢失进度/书架/自定义书源/缓存（书不受影响）。
- 插件源码不含任何用户数据；`data/site-config.json` 是公开的站点选择器库。

## 出处与致谢

本项目的**功能目标、交互思路和内置站点规则库**来自 IDEA 插件 **chapter_reader**：

- 作者：**wind**
- 仓库：<https://gitee.com/wind_invade/chapter_reader>
- 插件页：<https://plugins.jetbrains.com/plugin/16544-chapter-reader>
- 许可证：木兰宽松许可证第 2 版（MulanPSL2）

`dsh-reader/data/site-config.json` 由该项目的 `chapter_config-v1.json` 裁剪而来
（只保留阅读所需字段、规范 host、合并重复），站点适配的功劳属于 wind 和所有提交配置的道友。
`third-party/chapter_reader/` 保留了原始 LICENSE 与 NOTICE。

**谢谢 wind，也谢谢每一位适配网站的道友。** 如果没有原项目，这个插件不会存在。

本项目的 DSH 适配、HTML 解析器、选择器引擎、在线阅读/缓存、UI 与测试为独立实现。

## 免责声明

- 仅供个人学习与阅读便利，请遵守目标网站的服务条款与当地法律。
- 不要用本插件传播、复制或商业利用受版权保护的内容。
- 站点规则由第三方社区维护，本项目不保证任何站点的可用性、合法性或内容准确性。
- 使用抓取功能产生的任何后果由使用者自行承担。

## 许可证

本仓库代码与文档采用 **木兰宽松许可证，第 2 版（MulanPSL2）**，见 [LICENSE](LICENSE)。
来自 `chapter_reader` 的站点库数据同样遵循 MulanPSL2，署名见 [NOTICE.md](NOTICE.md)。

## 给 AI 的使用说明

如果你是把本仓库交给 AI 来安装/配置：先读 [AGENTS.md](AGENTS.md) 与
[docs/AI-USAGE.md](docs/AI-USAGE.md)，里面有安装、HTTP API、设置 Schema 和排错步骤。

## 目录

```
README.md                 本文件
LICENSE                   MulanPSL2
NOTICE.md                 第三方出处与致谢
AGENTS.md                 AI 快速上手
docs/AI-USAGE.md          AI 详细使用手册（安装/API/配置/排错）
dsh-reader/               插件源码
  index.js                宿主：HTTP 路由、设置/书架/章节、抓取编排
  client.js               浏览器：底栏一行、设置页、快捷键、老板键
  book.js / epub.js       本地书解析与分页
  online.js               在线抓取/缓存/SSRF
  html.js / selector.js / xpath.js / sources.js
  data/site-config.json   站点库（来自 chapter_reader）
  third-party/            上游 LICENSE 与 NOTICE
  tests/                  node --test 测试
```