Nth-5620/dsh-readwrite-hub

dsh-readwrite-hub（读写字间）

一个面向 DeepSeek Harness 的读写字间插件，提供「文件管理 + 码字 + 小说阅读」一体的工作区。

在编辑器工具栏点「码字」进入写作模式，点「阅读」进入书籍模式，同一个文件两种形态，排版偏好共享。

English

功能一览

小说阅读模式

- 按字分页：CJK 字宽校准 + 字符切片，段落可跨页、页面始终填满（实测每页底部仅留一行安全余量），只在新章节另起一页。
- 左右翻页 / 滚动翻页进度共享：两种方式共用同一份进度书签，切换翻页方式后自动重定位。
- 进度自动记忆：翻页即写盘（~/.dsh/readwrite-hub/state.json），关闭应用 / 切换文件 / 重开 Harness 都不丢进度；重新打开自动续读。
- 排版：工具栏「排版」按钮可调字体（衬线 / 楷体 / 无衬线 / 等宽）、字号（A- / A+）、行距、左右边距与纸张背景（默认 / 米色 / 浅绿 / 蓝色），与码字模式共享同一套排版偏好，实时生效。
- 书签：
- 进度书签：自动记录，始终排在书签面板最前（不可删除），显示记录时间（如 2026-08-21 15:33）——用于续读与「返回原进度」。
- 用户书签：点「书签」可一键添加 / 删除当前页书签，菜单内点击即跳转到对应位置。
- 章节目录：自动解析「第一章」「序章」「番外」「Chapter N」「纯数字行」「## 标题」等十余种章节格式，目录内点击直达。
- 跳页输入框：底部输入页码回车直达。
- 进度条：点击任意位置跳转，即时反馈；键盘翻页 / 滚动（PageUp / PageDown / ↑ / ↓ / Home / End / 空格）。
- 「返回原进度」胶囊：跳页 / 点进度条 / 搜索后出现，一键回到原位置；连续 3 次自然翻页后自动确认新位置。
- 流畅滚动：滚动模式下段落启用 content-visibility: auto，视口外段落跳过 layout/paint，长文档拖动宽度、上下滚动流畅。

书架

- 读过并产生进度书签的文本自动登架；顶栏图标一键在「书架 ↔ 文件树」间切换。
- 按最近阅读时间排序，可置顶、可搜索、可移除；点一本书自动以阅读模式打开并续读。
- 文件被移动 / 删除后标记「无法打开」，可一键从书架移除。

EPUB 阅读（只读）

- 在文件树中打开 .epub 文件自动进入只读阅读（不提供码字 / 编辑），由
foliate-js 在浏览器内直接解压渲染。
- 目录：自动读取 EPUB 的导航目录（book.toc），目录弹层内点击直达。
- 进度记忆：按 EPUB 的 CFI（章内精确位置）记录进度，写盘到
~/.dsh/readwrite-hub/state.json，重开自动续读——与文本阅读共用同一进度字段，互不干扰。
- 排版：工具栏可切换滚动 / 分页、放大 / 缩小字号、行距与深浅色主题（与码字 / 阅读共享字号行距偏好）。
- 书签：点「书签」添加当前 CFI 位置，书签列表内点击跳转、可删除。
- 安全边界：EPUB 属第三方可执行内容（可能含脚本），本插件通过 CSP 阻断非本域脚本；
请只读取来源可信的 EPUB。请只读取来源可信的 EPUB。 详见下方「安全说明」。

码字模式

- 字体：衬线（宋体）/ 楷体 / 无衬线（黑体）/ 等宽，字号 A- / A+；行距、左右边距可调。
- 背景：默认 / 米色 / 浅绿 / 蓝色（深浅色主题各有适配）。
- 自动软换行：超宽长行自动换行（含无空格长串 overflow-wrap: anywhere），横向无滚动条。
- 自动保存：停止输入 3 秒自动落盘；横线格：单层 CSS 渐变绘制，随文字原生滚动、零卡顿。
- 「格式化段落」：一键去除行首缩进、段落间自动空行。

文件管理

- 固定右侧侧边栏：底部「工作区文件」按钮打开可拖宽度的常驻侧栏（替代弹窗双栏面板），左侧文件树 + 右侧编辑器，拉出 / 收回带平滑动画。
- 单工作区文件树：只显示当前会话所属工作区，切换会话时文件树自动跟随。
- 「添加到对话」→ 输入框 @ 引用：通过 DSH 框架原生 slash/input-insert-reference 机制插入 @ 文件引用，发送时还原为完整绝对路径。
- 对话内文件链接 → 插件内打开：AI 消息中的产物文件 / 文件提及 / 工具调用行参数点击后在插件编辑器内打开，相对路径按工作区根解析。
- 右键菜单增强：在资源管理器中打开（Windows + WSL）、复制完整 / 相对路径、复制 / 粘贴条目、删除（带确认）、添加到对话。

安装

GitHub 安装（推荐）
dsh plugin --profile web add github:Nth-5620/dsh-readwrite-hub

安装后重启 dsh web，并硬刷新浏览器（Ctrl+Shift+R）。侧边栏底部出现「工作区文件」按钮即加载成功。

开发版：将本仓库 lib/ 放入 ~/.dsh/profiles/web/node_modules/dsh-readwrite-hub/ 并注册 bundle 即可，无需构建。

使用

1. 在侧边栏文件面板打开文本文件（.txt / .md）。
2. 点「码字」进入写作模式，或点「阅读」进入书籍模式。
3. 阅读模式下：进度条点击跳转、键盘翻页、输入框跳页、「目录」直达章节、「书签」查看 / 跳转 / 删除；进度自动按文件保存。
4. 顶栏「书架」图标按钮：开=书架，关=文件树。书架里点书自动续读；星标置顶、垃圾桶移除（弹窗二选一）；顶部搜索框按书名过滤。

安全声明

信任边界

- 本插件完全在本地运行，不发起任何出站网络连接，不上传任何文件内容。
- 文件读写全部通过插件自建的本地 HTTP API（/readwrite-hub-api/）完成，仅由 DSH 进程内的宿主插件提供。

EPUB 只读安全边界

- EPUB 是可包含脚本的第三方内容格式（ / onerror 等）。本插件对 foliate-js 静态资源
（/readwrite-hub-foliate/）与 raw 文件流（/readwrite-hub-api/raw）的响应设置
Content-Security-Policy（default-src 'self'; script-src 'self'; ...），阻断任何非本域来源的脚本，
并仅放行允许 EPUB 自身排版所需的 data: / blob: 资源。
- 只读边界：EPUB 阅读模式不提供码字 / 编辑，不把 EPUB 内容写回文件。
- ⚠️ 请只读取来源可信的 EPUB。CSP 能大幅降低但无法百分之百消除复杂脚本绕过风险；
恶意 EPUB 仍可能在极少数情况下尝试利用浏览器漏洞。

访问范围

- 暴露面 = DSH Web GUI 的绑定地址：dsh web 默认仅绑定回环 127.0.0.1，插件 API 只有本机浏览器可访问。
- ⚠️ 若自行将 dsh web 绑定到非回环地址，插件 API 将无独立鉴权地与 DSH 一起暴露；切勿将带本插件的 DSH 直接暴露到公网。

路径与操作防护

| 防护 | 实现 |
| --- | --- |
| 路径校验 | 所有操作要求绝对路径，拒绝相对路径与空路径 |
| 名称校验 | 新建 / 重命名仅接受单一路径段，拒绝空名、./.. 与含 /\ 的名称 |
| 目录列举 | 单层封顶 1000 条目 |
| 文件读取 | 默认 256 KiB、硬顶 8 MiB；只读文件头 |
| 文件写入 | 8 MiB 上限；请求体 64 KiB 上限 |
| 资源释放 | 所有文件句柄 try/finally 关闭；无缓存、无后台任务 |

数据与隐私

- 不收集、不记录、不传输任何文件内容或操作日志；前端对文件内容做 HTML 转义后渲染，无法注入脚本。

架构

- 宿主面（lib/index.js）：Cordis 插件，注册 /readwrite-hub-api/* REST 接口（list/read/write/rename/mkdir/newfile/copy/move/delete/reveal/state/shelf/shelf-remove/shelf-pin），state 原子读写 ~/.dsh/readwrite-hub/state.json（含书架 shelf 字段）；提供 rc.2 设置槽。
- 客户端面（lib/client.js）：__ModuleLoader__ 单文件浏览器 bundle，注册侧边栏入口与设置面板；阅读模式为 ReadingView 组件（字符级分页 = CJK 字宽校准 + 字符切片，页面与渲染严格一致），EPUB 只读为 EpubView 组件（动态加载 foliate-js 渲染），书架为 ShelfView 组件。

兼容性与版本

- DeepSeek Harness 0.1.1-rc.2+（稳定版） 与 0.1.2-alpha.1+（开发者 / ALPHA 版） 均兼容，
Node.js 20+。同一份源码无需修改即可在两个通道打开运行。
- ⚠️ 插件 API 在 v0.1.2 alpha 有少量破坏性调整：宿主端无需改动；客户端「用系统应用打开外部文件」
在 alpha 上需走 ctx.remote.session.openWorkspacePath（其余功能如文件树 / 浏览器、码字、阅读、
EPUB、书架均无需改动）。若在 alpha 通道使用该按钮，请按此适配（见 docs/ 与 CHANGELOG）。
- 纯前端无原生依赖；Windows / WSL / macOS 均可运行（「在资源管理器中打开」依赖 WSL 环境）。

Roadmap

- [x] 码字模式（字体 / 字号 / 行距 / 边距 / 背景 / 横线格 / 自动保存）
- [x] 阅读模式（按字分页 / 进度记忆 / 书签 / 目录 / 跳页 / 滚动模式）
- [x] 进度书签置顶 + 「返回原进度」胶囊 + 滚动 / 翻页进度共享
- [x] 书架系统（多书管理、最近阅读列表、置顶、搜索、移除、失效检测）
- [x] EPUB 只读阅读（集成 foliate-js；CFI 进度记忆 / 目录 / 书签，详见上文）
- [ ] 老板键（一键隐藏窗口 / 快速切换界面）
- [ ] 阅读统计（时长、字数）

关于 PDF：本项目定位是网络小说的读写字间，不打算支持 PDF（偏严肃办公排版、体积大、与码字定位不符）。因此 PDF 阅读不在计划内，仅保留 EPUB 一种电子书格式。

致谢与许可

本插件的基础文件树、编辑器与「@ 文件引用」联动来自并集成了
3911ee/dsh-workspace-explorer（MIT License），
在此尊重并感谢原作者的贡献。

本插件的EPUB 阅读引擎来自并集成了
johnfactotum/foliate-js（MIT License，© John Factotum），
随插件以 lib/foliate/ 静态资源形式分发并保留其原始 LICENSE，由浏览器动态加载以渲染 EPUB 只读书，
在此尊重并感谢原作者的贡献。

本插件在继承上述基础能力之外，自行新增了码字模式（字体 / 字号 / 行距 / 边距 / 纸张背景 /
自动软换行 / 横线格 / 自动保存 / 段落格式化）、小说阅读模式（按字分页 / 进度记忆 / 书签 / 目录 /
滚动与翻页进度共享）、EPUB 只读阅读（见上文「EPUB 阅读」节）、书架，以及重新设计的固定右侧侧边栏与单工作区文件树。

本插件以 MIT 协议发布（见 LICENSE），同时保留上游版权声明并额外标注本插件版权；
foliate-js 仍遵循其自身 MIT 许可（见 lib/foliate/LICENSE）。

English

A read-write studio plugin for the DeepSeek Harness Web GUI: file management, writing mode,
and a novel-reading mode, all in one workspace. Click Write for the drafting view or
Read to turn the same file into a book layout; typography preferences are shared.

Feature highlights：
- 阅读模式：字符精确分页，共享的滚动/分页进度在切换翻页模式时重新定位，自动保存进度（按文件、翻页时和关闭时），排版（字体、字号、行距、页边距、纸张背景——与写作模式共享），书签（列表顶部固定一个自动进度书签，加上用户书签的添加/删除/跳转），一个“返回进度”标签，章节目录，页码跳转输入，即时响应的进度条，键盘翻页/滚动，以及通过 content-visibility: auto 实现的平滑滚动。
- 书架：阅读过的文本会自动上架；顶栏图标可在书架 ↔ 文件树之间切换；可按最近阅读排序、可固定、可搜索、可移除；点击一本书即可继续阅读。
- EPUB 阅读（只读）：在文件树中打开 .epub 会进入只读阅读器（不可编辑），由 foliate-js（MIT）在浏览器中渲染。它会读取 EPUB 导航目录，按 CFI 记住进度（重新打开时恢复，与文本阅读器共享 state.progress 字段），并支持滚动/分页布局、字体缩放和 CFI 书签。EPUB 会像其他书籍一样自动上架。
- 写作模式：字体、字号、行距、页边距、纸张背景、自动软换行、自动保存、横线、段落格式。
- 文件管理：固定的右侧边栏，带有可调整大小的单工作区文件树，通过框架的 slash/input-insert-reference 插入“@ 文件引用”，在编辑器内打开聊天文件链接，更丰富的上下文菜单。

兼容性：DeepSeek Harness 0.1.1-rc.2+（稳定版）和 0.1.2-alpha.1+（开发者 / ALPHA）均受支持——同一份源代码可在任一渠道上运行，无需更改代码。在 v0.1.2 alpha 中，一些插件 API 发生了变化：宿主端无需任何改动，而客户端“用系统应用打开外部文件”操作应使用 ctx.remote.session.openWorkspacePath（文件树 / 编辑器、写作、阅读、EPUB 和书架均照常工作）。参见 docs/ 和 CHANGELOG。

安装：dsh plugin --profile web add github:Nth-5620/dsh-readwrite-hub

lib/ 作为运行时捆绑包发布——无需构建步骤。

署名与许可

本插件的基础文件树、编辑器和“@ 文件引用”集成来自 3911ee/dsh-workspace-explorer（MIT 许可证）。我们尊重并感谢原作者的贡献。

EPUB 渲染引擎是 johnfactotum/foliate-js（MIT 许可证，© John Factotum）。它随本仓库发布在 lib/foliate/ 下，并附带其原始 LICENSE，由浏览器动态加载以只读方式渲染 EPUB 书籍。我们感谢该库的作者。

在这些继承的基础之上，本插件新增了写作模式（字体、字号、行
间距、页边距、纸张背景、自动软换行、标尺线、自动保存、段落格式），
小说阅读模式（字符精确分页、进度记忆、书签、目录、共享
滚动/分页进度），EPUB 阅读（通过 foliate-js），书架，以及重新设计的固定
右侧边栏和单一工作区文件树。

本插件在 MIT 许可证下发布（见 LICENSE），保留上游
版权声明，并额外注明本插件。foliate-js 仍在其自身的 MIT
许可证下；见 lib/foliate/LICENSE。

有关部署、安全和限制，请参见上文的中文部分。