Skip to content
dsh marketplace

dsh-novel

Verified

@xrn1997/dsh-novel · v0.1.2 · Apache-2.0 · Web UI

在 DeepSeek Harness Web GUI 里读网络小说：legado 书源导入、书架与连续滚动阅读，附五个 AI 助手工具

Install

dsh plugin add @xrn1997/dsh-novel

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

@xrn1997/dsh-novel

在 DeepSeek Harness（DSH）的 Web GUI 里读网络小说：导入 legado 书源 → 搜索 → 加书架 → 连续滚动阅读。AI 助手同时获得五个小说工具，一句「帮我找本书并读第 N 章」就能在对话里完成搜索与阅读。

功能特性

  • 书源导入：粘贴 legado 书源 JSON（支持多源数组、多文件批量），导入即自动探针实测——坏源不挡好源，失败原因精确到规则段
  • 阅读体验：封面网格书架（带阅读进度）、分批搜索（进度可见、失败源折叠）、连续滚动阅读（滚动到底自动预取下一章）、目录抽屉跳章、字号 / 行距 / 纸张色可调、深浅主题自适应
  • AI 助手工具：搜索、读章、导入书源、试跑书源、查书架五个工具，与 UI 共用同一条链路
  • 整本导出：一键导出全书 TXT（流式下载、显示进度、可随时取消）
  • 本地 TXT 导入：本地小说文件（GBK / UTF-8 自动识别）解析章节后入架阅读
  • 书源管理：状态徽章、单源试跑、批量删除、登录支持（cookie 录入或 loginUrl 脚本执行）

快速开始

安装

dsh plugin --profile web add @xrn1997/dsh-novel

然后重启 dsh web，对话区顶部视图环会出现「小说」tab。

npm 安装使用预构建产物，秒装、无需构建授权。也可从 GitHub 源码安装（dsh plugin --profile web add github:xrn1997/dsh-novel）：prepare 脚本会自动构建，但 pnpm ≥10 首次安装可能报构建脚本被拦截（依赖已装但 lib/ 未生成），需先在 profile 目录执行 pnpm approve-builds --all 再重跑安装命令。

卸载：

dsh plugin --profile web remove @xrn1997/dsh-novel

首次使用

  1. 导入书源：DSH 设置 →「小说」→ 粘贴 legado 书源 JSON。导入时自动逐条探针，可用性一目了然。
  2. 找书读：「小说」tab 首页搜索书名 / 作者 → 点封面进入阅读器。阅读进度自动记住。
  3. 让 AI 助手干活：在对话里直接说「帮我找一本《XX》读第三章」「看看 XX 书源为什么坏了」。

AI 助手工具

工具 用途
novel_search_books 在已启用的书源中聚合搜索，结果逐源分组（单个源失败不影响其他源）；返回的 url 字段可作为其他工具的 bookKey
novel_read_chapter 获取某本书第 N 章（0 起）的正文纯文本（含章名）
novel_add_source 导入 legado 书源 JSON（对象或数组）；导入不因探针失败而拒绝，逐条返回 ok / missing / probe 结果
novel_probe_source 对已有书源实际发起一次搜索请求，返回实测结论与失败定位
novel_shelf 查询书架与阅读进度（当前仅 list；加书 / 更新进度走阅读器 UI）

配置

插件配置位于 cordis.yml 插件行的 config 字段（schemastery 校验，全部可选）：

键 缺省 说明
dataDir $DSH_HOME/novel/ 数据根目录（见「数据存储」）
searchTimeoutMs 15000 单源搜索超时（毫秒）
searchParallel 5 搜索并发源数
cacheMaxBytes 209715200（200MB） 目录 / 正文缓存上限（字节，LRU 淘汰）
exportDelayMs 300 整本导出的章节间抓取间隔（毫秒，串行限速以避免给站点造成压力）
localImportMaxBytes 52428800（50MB） 本地 TXT 导入大小上限（字节）
proxyUrl 自动探测 出站代理，见常见问题；'direct' 强制直连，或显式指定如 'http://127.0.0.1:7897'

HTTP API

所有路由以 /novel-api 为前缀（仅接受本机 loopback 且同源的请求），响应为统一信封 { ok, value | error }，错误附带 code 与可选的规则段级定位。共 17 条路由：

面 路由
健康检查 GET /novel-api
书源 GET / POST /sources（导入上限 32MB）、POST /sources/batch-delete、POST /sources/:id/probe、POST /sources/:id/auth、DELETE /sources/:id
阅读 GET /search、GET /book、GET /toc、GET /chapter（?refresh=1 绕过缓存）
书架 GET /shelf、PUT /shelf/:key（带 title 加书 / 带 progress 更新进度）、DELETE /shelf/:key
导出 GET /export（流式 TXT，响应头 X-Novel-Total-Chapters 为总章数，连接断开即停止抓取）
本地书 POST /local/import?name=…、DELETE /local?id=…

数据存储

数据存于 ~/.dsh/novel/（可用 dataDir 配置改写），与项目目录分离——阅读数据是跨项目、跨仓库的：

~/.dsh/novel/
├── sources.json   # 书源清单（含登录态，仅存本机、不会外传）
├── shelf.json     # 书架与阅读进度
├── cache/         # 目录 / 正文缓存（LRU，默认上限 200MB）
└── local/         # 导入的本地 TXT（原文 + 元数据与章节偏移表）

兼容哪些书源

兼容 legado 书源的声明式子集：取值链 / 组合符 / ## 替换 / AllInOne / JSONPath / XPath 子集 / @put / @get / @js 沙箱 / 对象形态方言 / url,{json} POST 请求 / 相对 URL / 隐式 CSS 选择器（#id / .class / 裸 tag）/ ! 排除语法，以及 @js 宿主垫片（java.log / getElement / setContent / cookie / source 等对象）。

遇到不认识的语法，本插件选择报错而不是猜测——错误信息精确定位到出错的规则段，而不是产出错误的结果。依赖安卓 WebView 或加解密 API 的书源无法在本环境仿真，会明确报告不支持。

项目带有可离线复算的兼容性回放测试（真实源快照 → 搜索 / 目录 / 正文全链路），详见 compat/README.md。

常见问题

搜索结果全是「网络错误」，或正文显示为空白？

多半是代理问题。DSH 的 Node 进程使用 undici 发请求，不会读取系统代理设置；对代理才可达的站点（如部分小说站），直连会被重定向或重置。解决办法：在配置中显式设置 proxyUrl（如 Clash 常用端口 'http://127.0.0.1:7897'）。缺省的自动探测顺序为：环境变量 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY → Windows 系统代理 → 直连。

某条书源报「不支持 xx」的错误？

本插件只实现 legado 规则的声明式子集（见上节），对无法仿真或不认识的语法会明确报错并定位到规则段，而不会静默给出错误结果。可以尝试换用不依赖 WebView / 加密的同类书源。

安装后对话区没有出现「小说」tab？

重启 dsh web 后生效。如果你是从源码目录安装的，确认已先执行 pnpm build 生成 lib/（浏览器半的构建产物缺失会导致插件拒绝挂载）。

开发

git clone https://github.com/xrn1997/dsh-novel.git
cd dsh-novel
pnpm install
pnpm build        # 构建 lib/（Node 半 + 浏览器半）；改动源码后、重启 dsh web 前必须执行

也可以把本地目录直接装进 profile 调试：dsh plugin --profile web add <本地路径>。

测试

pnpm test          # 常规测试（引擎 / 服务 / API / 工具 / 入口 / 前端逻辑与 smoke）
pnpm test:compat   # 兼容性回放（投放真实源 → 采集快照 → 离线复算跑通率）
pnpm test:pack     # 构建 + 产物自检
pnpm typecheck     # tsc --noEmit

真机全量重探（改动抓取 / 规则引擎后实测书源可用率；会真实访问网络，耗时数分钟）：

$env:DSH_REPROBE='1'; pnpm vitest run tests/reprobe.test.ts

架构速览

src/
├── engine/     # legado 规则引擎（纯函数：解析 → 求值；段级错误追踪；@js 沙箱）
├── services/   # 业务门面：抓取（编码检测 / 代理）/ 书源注册表 / 书架 / 缓存 / 本地书
├── api/        # /novel-api/* HTTP 路由
├── tools/      # AI 助手五工具（与 HTTP 共用同一 service 层）
├── index.ts    # Node 侧插件入口（Cordis）
└── client/     # 浏览器侧：「小说」阅读视图 + 设置页书源管理

UI、AI 工具、探针三个面共用同一个 service 层，不存在第二套实现。

贡献

欢迎 Issue 与 PR。提交改动前请确保 pnpm test 与 pnpm typecheck 通过；若扩展了书源语法，请优先补充对应的回放测试 fixture（脱敏规程见 compat/README.md）。提交即表示你同意以 Apache-2.0 协议授权你的贡献。

说明

本项目不提供、不内置任何书源，仅用于学习插件开发。

License

Apache-2.0