@local/dsh-pdf

使用方式

默认 PDF 打开方式

插件使用 documentPreviews.register() 注册 .pdf，优先级为 extension，通过 sidebar.right.tab.document 提供阅读界面。启用后参与 DSH 的默认 PDF 渲染器选择，优先于内置基础 PDF 渲染器；这不是操作系统的 PDF 文件关联。多个第三方插件同时处理 .pdf 时，最终选择仍遵循 DSH 的渲染器规则。

标注与保存

• 默认直接选择文字；选中文字后，选区旁显示浮动工具条，可复制、高亮、添加下划线、删除线或便笺。点击工具条不会丢失已捕获的选区；通过“工具 → 便笺”也可在页面上放置批注。
• 新增高亮会立即预览，编辑提交失败时移除预览并显示错误。
• 直接点击页面上的原生标注即可选中，浮动工具栏提供颜色修改、删除和批注入口；Delete 删除选中标注，Escape 取消选中。点击页面或查看器空白、查看器外部会隐藏选区和标注工具条、关闭未提交的便笺编辑。拖动选字和双击选字仍用于文字选择。
• 原有的受支持原生标注也会出现在标注列表中，可以修改颜色、批注内容或删除。创建与修改时间按本地时区显示。
• 标注、便笺、翻译和搜索集中在右侧阅读辅助栏，切换功能视图不改变 PDF 内容区宽度；辅助栏可以折叠和调宽。
• 页面、标注及搜索面板采用浮动滚动条：滚动、悬停或拖动时显示，停止滚动且未悬停时约 1.1 秒后隐藏。滚动条不占用页面宽度。
• PDF 链接悬停只显示手形光标，不覆盖交互框；可直接拖选链接文字。单击稍作延迟后跳转，双击选词会取消待执行的跳转。
• 编辑会显示未保存状态，并进入插件工作副本。新增、修改、删除、撤销和重做只更新标注投影与操作记录；点击“保存”时才将有效操作写成新 PDF，“另存为”写入指定副本。
• 点击“丢弃全部修改”立即恢复到上次成功保存或首次打开的基线，清空撤销、重做及草稿，不再弹确认框；不依赖源文件仍存在，也不改写源文件。
• 切换当前会话时关闭旧会话的 PDF 标签，并直接丢弃其未保存修改和草稿。清理等待打开中的请求返回，新的打开请求等待清理完成，避免迟到请求恢复已丢弃的修改。设置面板的显示/隐藏不被当作切换会话。尚未挂载的恢复标签通过宿主公开 inventory 处理；旧会话 Sidebar 未挂载时保留关闭任务，在下次挂载时关闭。
• 同一会话中手动关闭 PDF、断线或重启仍可恢复草稿。草稿将基线 PDF 和编辑操作分开存入 DSH 的宿主存储：首次编辑保存基线，后续只更新操作记录；会话切换和显式丢弃会删除相应草稿。
• 源文件发生变化时会报告冲突，保留工作副本，提供另存副本或重新加载源文件的选择。

数字签名 PDF 为只读。允许直接打开的加密 PDF 使用 PDF.js 只读兼容方式加载，可阅读、搜索、跳转和查看原有标注；当前不支持编辑或保存加密 PDF。需要输入密码的文件会显示明确提示，交互式解锁属于后续范围。锁定、只读或无法安全编辑的原生标注会显示原因。扫描图像或页面内容中已被压平的高亮不是可编辑的 PDF 标注，无法恢复成原来的高亮对象。

扫描件、图像页和 OCR

所有页面先按 PDF 的实际画面渲染，包括扫描图像、普通文字和嵌入图片。原有文字层直接用于选择和搜索。通过“工具 → 区域截图”在单页内拖出矩形，完成后自动恢复文字选择；Escape 或取消按钮可退出截图。预览可以复制图片、下载 PNG 或识别区域文字；整页识别通过“工具 → 识别本页”执行。

截图渲染 PDF 基线的选定区域，并合成未保存的标注操作；保留页面图像、可见标注和当前显示旋转，不包含界面控件。清晰度独立于 Sidebar 缩放，上限为 2 倍和 1600 万像素。此操作只在本地生成图像，不发送到会话或模型。原生标注被删除或改色时，预览会修补其旧外观；修补区域若与未知或自定义外观重叠，该交叠部分可能无法完整保留。

默认引擎是 NoneOCR：不执行识别，仍可阅读页面图像。在 DSH 设置页的 PDF 卡片中选择 LocalOCR 并保存设置后，使用本地 Tesseract.js 识别。随包提供 eng 和 chi_sim，默认语言配置为 eng+chi_sim；也可单独使用其中一种。

LocalOCR 的 worker、WASM、语言数据全部随插件提供，经 /api/pdf-assets/ 的同源资源路由加载，运行时不使用公共 CDN、不向 OCR 厂商发送页面。首次安装依赖需要取得软件包；资源准备完成后，本地识别本身不依赖外部服务。

当前 LocalOCR 资源地址只接受同源 HTTP / HTTPS。Web profile 是当前实现的目标；Desktop 等使用自定义 URL scheme 的承载方式尚未确认兼容，不能据此视为已支持离线 OCR。

识别产生临时文字层，保留引擎、覆盖区域和置信度信息。结果可以选择和搜索，并用于定位标注；OCR 本身不会把文字层写回 PDF。尚未识别的扫描区域不在文字搜索范围内，识别质量取决于页面质量和语言配置。

跳转返回

成功跳转后，“返回”恢复上一次位置。连续跳转按栈回退；失败、取消及无实际位移的跳转不新增记录。普通滚动不建立跳转记录。历史属于当前 PDF 标签；重新加载不同内容后会清除旧内容的历史。

选区翻译与原生查询

选择文字后点击浮动工具条的“翻译”，进入右侧阅读辅助栏的翻译视图，显示原文、页码和译文。默认采用 PDF 所属会话当前选择的 DSH 模型（尚未选择时采用 DSH 默认模型），复用宿主已有凭据，源语言自动检测、目标语言为中文。可以切换目标语言后再次翻译、取消、重试或复制译文；翻译不修改 PDF。

单次选区最多 8192 个 UTF-16 字符，默认超时 30 秒，模型输出上限为 4096 tokens，统一输出上限为 32768 个字符。输入不会被静默截断；模型达到输出限制时保留部分译文并显示未完成提示。切换文档、明确关闭译文或改变翻译配置会取消旧请求；切换右栏视图或折叠辅助栏不会取消请求或清空译文。

“查询”功能要求 macOS 选区旁的原生词典浮窗。当前 DSH 0.2.0-rc.1 没有向插件开放主窗口 showDefinitionForSelection() 对应接口，因此此功能尚未接通：Windows/Linux 不显示按钮，macOS 显示禁用按钮及原因。插件仅提供 pdfDictionary 能力注册接口，等待真实宿主桥接；不会改用词典应用或联网查询来冒充浮窗。

设置

PDF 配置卡片提供 OCR 引擎、识别语言、超时、翻译引擎、原文/目标语言、翻译超时、默认标注颜色、跳转历史容量和 PDF 大小上限。设置修改需要手动保存；“恢复默认”移除当前层的覆盖值，重新采用宿主配置组合的默认值，保存后生效。

OCR 默认超时为 120 秒，翻译默认超时为 30 秒，跳转历史容量为 100，文件大小上限为 64 MiB（可设置为 1～256 MiB）。大文件、复杂页面和 OCR 会增加内存占用。

阅读标签复用 PDF.js worker；未保存标注操作保持 PDF 基线字节不变，连续编辑更新标注投影，撤销重放有效操作。保存时才序列化 PDF；首次编辑持久化基线、首次打开复杂文档和扫描件仍可能耗时。