前言¶
在 DeepSeek Harness（DSH）中使用 PDF 时，右侧文件预览区域仅提供基础翻页和缩放功能。打开有目录结构的 PDF 时，无法快速定位章节；阅读过程中无法记录当前阅读位置，切换任务或重启桌面版后需要重新查找。现有文档工具或浏览器扩展难以直接与 DSH 侧边栏集成。
dsh-pdf-bookmarks 在 DSH 右侧文件预览中增加 PDF 书签查看器，提供文档目录（outline）与本地阅读书签。插件以 dsh bundle 机制运行，不修改 PDF 文件本身，不把书签数据发送到模型请求或账号配置中。
插件定位¶
dsh-pdf-bookmarks 是 DSH 的客户端插件，由维护者 woody-dx 开发。它只增强已有工作区 PDF 的右侧预览，提供内嵌目录与个人阅读书签，不增加模型工具或会话持久状态。社区目录中的会话书签与文件路径收藏也不等同于 PDF 页内阅读位置。
核心功能¶
文档目录（outline）¶
打开 PDF 后，在文件头部的查看器菜单选择「PDF 书签」。工具栏的「☰」开关导航，侧栏以覆盖面板形式显示文档自带章节，可展开层级并点击跳转。
对于没有内置目录的 PDF，侧栏会显示说明，仍可添加个人书签。
个人阅读书签¶
点击工具栏的「☆ 书签」收藏当前阅读位置，可直接输入名称并保存。「我的书签」支持点击跳转、行内改名和删除。重开同一 PDF、切换任务或重启桌面版后仍可读取。
书签数据保存在桌面应用自身 origin 的 localStorage 中，键前缀为 dsh-pdf-bookmarks:v1:。只保存文档内容 SHA-256、名称、页码、页内相对位置和创建时间。同一内容的 PDF 副本共用书签；内容变更后使用新的集合。
侧栏与正文操作¶
较窄的侧栏以覆盖面板显示导航，点击目标后自动收起。工具栏提供页码跳转、适应宽度和固定缩放；正文支持连续滚动和文字选取。
安装与启用¶
当前仅验证 dsh Desktop 0.2.1-rc.2 在 macOS Apple Silicon 上的可用性。其他版本默认禁用此查看器。
从源码安装¶
从 GitHub 仓库下载源码 ZIP 并解压，在桌面版「插件 → 添加插件」中输入解压后的插件目录绝对路径，然后在「已安装插件」中启用 dsh-pdf-bookmarks。
从 Release 安装¶
从 GitHub Release 下载 .tgz，在桌面版添加插件时填写该文件的绝对路径。
插件遵循 dsh.bundle 组合包机制，启动保护从当前 profile 的包解析找到自身，不要求源码位于特定用户名或 ~/.dsh/plugins 路径。在「插件 → 已安装插件」中可启停和卸载；列表未更新时点击「刷新」。
禁用与卸载¶
停用可在 dsh 插件列表中禁用本插件，或在 profile patch 最后增加：
- id: pdf-bookmarks
disabled: true
再次启用前删除这条手工禁用覆盖。停用或使用查看器菜单切回「PDF」后，内置查看器继续工作。删除本地源码目录前应先停用并移除 profile 引用。
卸载插件不清空书签；清除桌面应用的全部网站存储则会移除这些书签。
兼容性与故障回退¶
启用条件位于 cordis.patch.yml：在加载插件入口前，调用 guard.cjs 核对精确版本白名单以及两个构建文件的 SHA-256。检查异常、版本未验证、文件缺失或哈希不匹配均仅禁用本插件。
Host 入口 index.js 无运行时依赖、不提供或替换任何核心服务。正式插件不安装 dsh-tools、Cordis 或其他 dsh 核心包。客户端接口注册异常会被捕获；PDF 引擎在打开 PDF 时才加载，加载失败会移除增强预览定义并交回内置查看器；正文错误边界提供「使用内置 PDF 预览」。
适用场景¶
适合需要在 DSH 侧边栏中快速浏览 PDF 目录、记录阅读进度的开发者与研究者。插件仅运行在桌面版进程内，不涉及网络请求或模型调用。
使用前应确认本地已安装 dsh Desktop 0.2.1-rc.2，并从官方渠道获取插件源码或 Release 文件，核对 LICENSE 与 THIRD_PARTY_NOTICES.md。
总结¶
dsh-pdf-bookmarks 在 DSH 右侧侧栏提供 PDF 目录与本地阅读书签，支持点击跳转、行内改名和删除，书签数据本地持久化，重启任务或桌面版后仍可读取。插件以 dsh bundle 机制运行，对已验证版本提供故障回退，不修改 PDF 文件本身。
- 插件目录页：https://www.skillhub.cn/plugins/woody-dx/dsh-pdf-bookmarks
- GitHub 仓库：https://github.com/woody-dx/dsh-pdf-bookmarks
