dsh-novel-reader

dsh-novel-reader

在 DeepSeek Harness（DSH）右侧栏阅读本地 TXT 小说：书架、章节目录、分页翻页、阅读进度记忆与阅读主题设置。只读本机文件，不联网、不内置任何内容源。

• 安装（GitHub，公开仓库建好后）：dsh plugin --profile <profile> add LaoganR/dsh-novel-reader
• 安装（本地 profile）：dsh plugin --profile <profile> add link:E:/dsh-booktool，并把包名加入该 profile 的 dsh.profile.bundles
• 许可：MIT
• 数据：全部留在本机 ~/.dsh/novel-reader/（可用 dataDir 改写）

功能特性

• 书架：三种导入——「选择文件」用系统文件对话框直接挑 .txt（可多选）、「浏览选择」打开原生目录对话框后在内置浏览器里逐层点选、或粘贴本地绝对路径。展示标题、编码、体积、章节数与阅读进度；支持继续阅读与移除（移除只删书架记录，不动原文件；直选导入的副本随移除清理）
• 编码识别：BOM → 严格 UTF-8 探测 → GBK 回退（Node 内置 TextDecoder('gbk')，零额外依赖）；超限（>100MB）明确拒绝
• 章节目录：第X章/回/节 + 序章/楔子/引子/尾声/后记/终章/大结局/番外 规则切章；无命中降级为单章「全文」，首章前的引言自动归入「开篇」伪章
• 分页阅读：两种翻页方式（设置里随时切换）——点击翻页（横向多列分页，列版式由测量值注入）与上下滚动（原生纵向滚动）；点击左右区域 / 滚轮 / 方向键 / PageUp·PageDown / 空格翻页，翻到本章尽头自动跨章（回上一章落末页）
• 进度记忆：章 / 页 / 百分比随翻页防抖写入，重启后回到上次位置；页面关闭前有 sendBeacon 兜底
• 阅读主题：字号（14–30px）、行距（1.3–2.6）、浅色 / 羊皮纸 / 夜间三主题、翻页方式（点击翻页 / 上下滚动），存本机 localStorage，随书签隔离
• 目录抽屉：大目录增量渲染（每次 400 条），点章跳转

安装

插件装进哪个 profile，就在那个 profile 里生效。

# GitHub（公开仓库，CI 收录后可直接用）
dsh plugin --profile <profile> add LaoganR/dsh-novel-reader

# 源码目录（开发期，link: 只建链接、不触碰对端，也不会替你构建）
dsh plugin --profile <profile> add link:E:/path/to/dsh-novel-reader

然后把 "dsh-novel-reader" 加进该 profile package.json 的 dsh.profile.bundles 数组，重启宿主。

从 GitHub 源码安装时 prepare 脚本会自动构建 lib/；pnpm ≥10 可能拦下构建脚本（依赖装了但 lib/ 没生成，宿主会以 ERR_MODULE_NOT_FOUND 拒绝挂载），先在 profile 目录执行 pnpm approve-builds --all 再重跑。

使用

1. 重启宿主后，右侧栏引导页（＋）出现「小说书架」入口，点即打开 sidebar://dsh-novel-reader
2. 三种导入方式（都只支持 .txt）：
   • 选择文件（最直接）：点「选择文件」→ 弹出系统文件对话框直接选 .txt（可多选，逐个导入）。浏览器拿不到文件路径时（Electron ≥32 已移除 File.path）自动改走字节上传：宿主把内容按 SHA-256 哈希存到插件数据目录 imported/（同内容重复导入幂等、不会存两份）；能拿到路径则仍为零复制
   • 浏览选择：点「浏览目录」→ 系统目录对话框挑文件夹（Electron preload 真桥）→ 内置浏览器列出子文件夹与 .txt（可点「上级/主目录」导航）→ 点文件即导入，可连续导入。环境没有原生对话框时自动从主目录起步，不会空转
   • 手动路径：输入 txt 的绝对路径（如 E:\books\novel.txt）→「导入」 三种都会自动识别编码（UTF-8/GBK）并切章入架。
3. 「继续阅读」进入阅读器：点目录跳章、点「Aa 设置」调字号行距主题与翻页方式（点击翻页 / 上下滚动），左右方向键或点击页面左右区域翻页
4. 返回书架即刷新进度；再次进入自动回到上次读到的章与页

翻页与点击区约定：点击视口左侧 40% 上一页、右侧 60% 下一页；←/PageUp/↑ 上一页，→/PageDown/↓/空格 下一页；点击翻页模式下滚轮也翻页（带惯性冷却），上下滚动模式下滚轮原生滚动；本章尽头自动进下一章，反向翻页回到上一章末页。

配置

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

键	缺省	说明
dataDir	$DSH_HOME/novel-reader/	书架数据目录（$DSH_HOME 缺省 ~/.dsh）

HTTP API

所有路由以 /novel-reader-api 为前缀（本机 loopback），响应为统一信封 {ok:true, value} / {ok:false, error:{code,message}}，错误码 BAD_REQUEST|NOT_FOUND|NOT_TXT|TOO_LARGE|IO_ERROR|INTERNAL。契约定义在 src/shared/wire.ts（双端共用）。

方法	路由	用途
GET	/ping	健康检查
GET	/list	书架（含进度）
POST	/import	{path} 导入 txt（绝对路径 + .txt 校验、编码探测、切章）
POST	/import-upload?name=	直选文件导入（raw body = 文件字节）：文件名消毒 → SHA-256 前 16 位落 dataDir/imported/<hash>-<name>.txt（原子写、同内容幂等）→ 同编码/切章管线
GET	/scan?path=	浏览导航：列目录的子文件夹（≤200）+ .txt 文件（≤500、按名排序、带 size）；path 缺省 → 用户主目录。平台目录服务只列子目录不列文件，故文件枚举由本插件宿主自扫
POST	/remove	{id} 移出书架（不删源文件）
GET	/chapters?id=	章节目录
GET	/chapter?id=&index=	章正文（UTF-8）
POST	/progress	{id,chapterIndex,pageIndex,pages,percent} 存进度

数据存储

~/.dsh/novel-reader/
├── state.json   # 书架与阅读进度（原子写：tmp + rename；损坏时转存 .bak 并让装载响亮失败）
└── imported/    # 仅「选择文件」且拿不到文件路径时的副本（内容哈希命名，同内容只存一份；移出书架时清理）

经路径/目录导入的书籍本体不复制，书架只记路径与元数据；文件被移动或修改后，下次打开会重新探测编码并重扫章节。

开发

pnpm install        # 装依赖（prepare 自动双端构建 lib/）
pnpm build          # 重建 lib/（host ESM + client CJS）
pnpm typecheck      # tsc --noEmit
node scripts/smoke.mjs   # 双端产物冒烟：function-plugin 四元组 / ModuleLoader 外壳 / id 纪律

• src/host/：HTTP 路由、编码探测、切章、原子存储
• src/client/：右栏注册（tab 类型 + keyed slot）、书架、阅读页、分页 hook、主题
• src/shared/wire.ts：双端共用的 API 契约（唯一主人）
• 改动 Node 半需重启宿主；浏览器半重建后，宿主的客户端热更新（lib/client.js 变更）会接手

上架

市场条目为 awesome-dsh-plugin 仓库的 data/plugins/<owner>__<repo>.yml 单文件 PR（格式见 docs/_awesome-contributing.md），仓库侧需要 dsh.bundle manifest（package.json ✓）、cordis.patch.yml（✓）、dsh-plugin topic 与 screenshots.json（声明于本仓根目录，图片入库后生效）。

License

MIT