跳到主要内容

ZotFlow 1.6.0

这个版本把 ZotFlow 的内嵌阅读器更新到了 Zotero 10，并为 PDF 和保存的网页快照加入 了阅读模式（Reading Mode）。阅读模式依赖一个可选的配套插件 ZotFlow Enhancement Pack，让体积较大的离线资源不必全部塞进 ZotFlow 主插件。

升级 ZotFlow 本身不需要迁移数据或重置设置。即使不安装 Enhancement Pack，普通的 PDF、EPUB 和网页快照阅读、标注、Source Note 与同步也会照常工作。

Enhancement Pack 是可选的

只有需要阅读模式时，才需要从 Obsidian 社区插件安装 ZotFlow Enhancement Pack。 安装后可以让它保持关闭：ZotFlow 会直接读取其中的离线资源容器，不会把它作为插件 执行。

亮点​

  • PDF 和保存的网页快照现在支持阅读模式。 文档会以可重排的结构化版式显示， 同时保留回到原文位置的对应关系。
  • 安装可选 Pack 后，阅读模式可以完全离线工作。 使用过程中不会再下载模型或 其他资源。
  • 内嵌阅读器已更新到 Zotero 10.0.0。 PDF 集成也迁移到了 Zotero 目前使用的 Document Worker 架构。
  • 外部 PDF 标注可以更安全地增量更新。 提取失败时不再丢掉上一次成功的标注 快照。
  • Local Source Note 现在会正确处理 ?? frontmatter 默认值。 模板默认值不再 覆盖你自己维护的字段。
  • 搜索会忽略常见拉丁字母变音符号。 不带重音符号的查询也能匹配带重音符号的 标题、作者、标签、分类和文库名称。
  • Android 上重新打开已有阅读器时能可靠回到原标签页。 清理重复标签页后， ZotFlow 会确保已经打开的阅读器最后获得焦点。

阅读模式与 ZotFlow Enhancement Pack​

Zotero 10 阅读器为 PDF 和保存的网页快照加入了 Reading Mode 按钮。启用后， ZotFlow 会根据当前阅读器已经打开的那一份文档快照生成 Structured Document Text （SDT），再把识别出的标题、段落、列表、表格、图片、公式等结构显示成可重排的 语义化阅读界面。

生成 SDT 所需的资源远大于普通插件，因此它们现在放在独立的 ZotFlow Enhancement Pack 中：

  • Pack 使用被动式的离线资源容器协议（2.0 版），不提供运行时资源 API，也不依赖 全局注册表。
  • 仅仅打开文档不会加载 Pack、生成 SDT 或弹出安装提示；只有真正使用阅读模式时 才会开始这些工作。
  • 如果尚未安装 Pack，ZotFlow 会说明原因，并提供直接打开其社区插件页面的链接。 安装后保持关闭即可，然后重新尝试阅读模式。
  • 生成过程在 ZotFlow 现有的 Worker 中本地完成；处理当前文档时，Reading Mode 按钮会显示进度。
  • ZotFlow 会检查 Pack 是否与当前版本指定的 Document Worker 和 SDT 格式完全 匹配。请求到的资源还会经过大小限制和内容校验；版本不兼容或文件损坏时会明确 失败。
  • 同时发起的请求会共用正在进行的处理和同一份资源快照。关闭或重连阅读器后，迟到 的进度与结果会被丢弃，相关资源也会释放。
  • 阅读器正在使用资源时，即使 Pack 恰好被更新，也不会在当前会话中途替换资源； 新请求才会使用新安装的版本。

SDT 目前按需生成，不会持久化到仓库。因此，新打开一个阅读器后第一次请求阅读模式 可能需要一些时间，较长或结构复杂的 PDF 会更明显。

Zotero 10 阅读器与 Document Worker​

内嵌阅读器已经迁移到 Zotero Reader 10.0.0。ZotFlow 的 PDF 操作不再使用旧的 PDF 处理 Worker，而是改用 Zotero 的 Document Worker。这个共享服务负责导入和 导出外部标注、旋转页面、读取识别数据，以及为 Source Note 渲染图片和手写标注。

Document Worker 构建版本及其资源由同一份 lock 文件固定。插件构建时还会检查 阅读器的 SDT 格式是否符合 Enhancement Pack 协议，避免几个独立更新的组件静默 生成彼此不兼容的数据。

更安全的外部 PDF 标注​

直接嵌入 PDF 的外部标注在 ZotFlow 中仍然是只读的，但最近一次成功提取的状态现在 会作为本地快照保存在数据库中。下次提取时，Document Worker 会收到这份快照，并 只返回需要新增、更新或删除的标注。

  • 只有提取成功后，标注变化和 PDF 内容哈希才会在同一个数据库事务中一起提交。
  • Worker 失败时，ZotFlow 会同时保留旧标注和上一次成功的哈希，不会先清空数据， 之后仍可安全重试。
  • Worker 只能删除已经确认属于外部标注的记录；异常结果不能误删普通 Zotero 标注。
  • 外部标注发生变化后会触发 Source Note 刷新，让笔记和阅读器看到同一个版本。
  • 对本地或 Linked File，判断是否需要重新提取时以实际读取字节的哈希为准，不再让 过期的服务器元数据盖过本机文件内容。
  • 新提取的标注 ID 会避开该附件下所有已有标注，防止冲突。
  • 图片和手写标注只有在 PNG 成功写入仓库后，才会被标记为已经渲染。

Local Source Note 的 frontmatter 默认值​

Local Source Note 现在与 Library Source Note 使用相同的 frontmatter 合并规则。 在模板字段前加 ??，即可提供默认值，同时不覆盖笔记中已经存在的值：

---
??rating: unrated
status: reviewed
---

第一次渲染时会写入 rating: unrated。如果笔记已经有 rating，即使值是 false、 0、空字符串或 null，也会原样保留。?? 前缀本身不会写进 Source Note。没有 前缀的字段维持原有行为，每次渲染时仍由模板刷新。

以前 Local Source Note 会把 ??rating 当成字段名本身，并可能覆盖用户维护的 rating。修复后，同一份模板可以在两种 Source Note 之间一致使用。

搜索与阅读器标签页修复​

  • 自由文本搜索现在会同时规范化查询和待搜索文本中的常见拉丁字母变音符号。例如 Lammermann 可以匹配 Lämmermann，反过来带变音符号的查询也能匹配普通字母。
  • creator:、tag:、collection:、library: 和 type: 过滤条件，包括取反 过滤，也采用相同行为。数据库中保存和界面显示的原文不会改变，中文等非拉丁文字 的搜索也不受影响。
  • 文档已经打开时，ZotFlow 现在会先关闭刚创建的重复标签页，再显示并聚焦已有的 阅读器。这个顺序修复了 Android 清理重复标签页后跳到无关标签页的问题，并统一 用于本地文件和 Zotero 附件的打开入口。

启动诊断与内部维护​

  • 普通打开阅读器时不再预取 SDT、读取 Enhancement Pack 数据或提示安装 Pack。 Pack 资源只在实际使用相关功能时加载和解压。
  • 活动中心的 debug 日志现在会记录主线程启动、Worker 初始化、内嵌阅读器资源解码、 后台 Tree/CSL 工作和 Enhancement Pack 加载的分阶段耗时。这些记录用于定位启动 缓慢问题，不会增加遥测或网络上报。
  • 发布工作流现在会核对 Git tag、package.json、manifest.json 与 versions.json 的版本是否一致，执行完整 CI 构建，为产物附加来源证明，并创建 包含三个 Obsidian 发布文件的 GitHub draft release。
  • 版本更新脚本现在会把每一个发布版本写入 versions.json，即使多个版本要求相同 的最低 Obsidian 版本也不会跳过；缺失的 1.5.2 映射已经补回。
  • Document Worker 更新现在由归档文件与资源元数据锁定，并可通知 Enhancement Pack 仓库准备匹配的更新。
  • 不再使用的 note-editor submodule 已移除，仓库中的位置由 Enhancement Pack submodule 取代；内部设计文档也不再作为发布源码跟踪。
  • 针对 Pack 解析与生命周期、Document Worker 资源、SDT 请求、外部标注事务、 阅读器标签页跳转、frontmatter 默认值和忽略变音符号的搜索补充了回归测试。