跳到主要内容

ZotFlow 1.5.0

这个版本以一次大范围的 Obsidian ESLint 清理为主，处理了 ZotFlow 长期积累的大量 warning。大部分改动属于内部整理，但消除这些 warning 也触及了同步、阅读器、内嵌 编辑器、设置、Worker 和文件操作，并带来了下文记录的行为变化。

升级是安全的，不需要迁移数据或重置设置；相关修复会在下次执行对应操作时生效。

需要 Obsidian 1.13.4

ZotFlow 1.5.0 将最低支持的 Obsidian 版本从 1.11.4 提升到 1.13.4。旧版 Obsidian 不会加载这个版本；请先更新 Obsidian，再安装 ZotFlow 1.5.0。

大范围的 Obsidian ESLint 清理​

这次更新消除了大量 Obsidian ESLint warning，并用全仓库 lint 检查取代了过去只检查 部分已清理文件的机制。在这个过程中，ZotFlow 收紧了不安全的类型边界，明确处理异 步失败，在合适的位置改用兼容移动端和弹出窗口的 Obsidian API，并以持续维护的 typings 取代旧的手写 Obsidian 类型声明。

下文只列出可能影响实际行为的变化；纯类型、格式和 lint 配置调整没有写入发布说明。

升级后请留意

关键行为路径已有针对性的回归测试，完整测试套件和插件生产构建也全部通过。但测试 无法覆盖每一种仓库、平台、弹出窗口、PDF、WebDAV 服务器和 Obsidian 内部状态。 即使有测试用例约束，升级后仍可能出现意想不到的问题；请留意异常行为，并在反馈问 题时附上活动中心日志。

亮点​

  • Obsidian lint 积压已基本清除。 现在会检查整个仓库，而不再只检查一份已清理 文件列表。
  • 桌面端可以直接读取 Zotero 本地存储的附件。 已存储的附件可直接从 Zotero 本机的 storage 目录打开，无需再通过 Zotero Storage 或 WebDAV 下载一份副本。
  • 被拒绝的同步写入不会再改动本地数据。 构造上传内容时，不会在 Zotero 接受 数据前提前修改数据库里保存的条目。
  • 外部 PDF 标注会保留标签和日期。 提取出的标注不再经过一次有损的 Zotero 条目数据转换，而是直接交给阅读器。
  • 后台失败会留下记录。 阅读器加载、标注更新、笔记保存和设置写入所拒绝的 Promise 现在会写入活动中心日志，不再悄悄消失。
  • 删除文件时遵循 Obsidian 的偏好。 当仓库设置了其他删除方式时，ZotFlow 不 再强制把生成的文件送进系统回收站。

更安全的同步失败处理​

ZotFlow 以前在准备上传条目时，只浅拷贝条目外层，内部的 data 对象仍与数据库中 保存的记录共用。给上传内容写入版本号和修改时间时，因此会在 Zotero 接受数据之前 就修改本地条目。

上传成功时，服务器响应会替换整条记录，所以问题被掩盖了；上传被拒绝或出现冲突 时则不会。一次失败的尝试可能会改掉本地修改时间，并移除 annotationIsExternal 标记。现在构造上传内容时也会复制内部数据，所以失败或冲突 的写入会保留原来的本地状态。

PDF 与标注可靠性​

  • 外部标注的标签会被保留。 标签不再以阅读器无法识别的中间字段名传入。
  • 外部标注的日期会被保留。 PDF 提供的修改时间会原样保留；如果 PDF 没有创建 时间，也会用它补上创建时间。
  • PDF Worker 的合法空结果会被接受。 成功响应中的 0、false 或其他空值不 会再被误判为 Worker 错误。
  • 异常 PDF Worker 消息会明确失败。 无效的 CMap、字体和标注图片请求现在会给 出受控错误，而不是稍后抛出一个无关异常。

直接从 Zotero 本地存储读取附件​

在同一台电脑上运行 Zotero 与 Obsidian 的桌面端用户，现在可以让 ZotFlow 直接从 Zotero 本机的 storage 目录读取已存储附件。在 General → Source Notes → Library Source Note 中开启 Use Zotero Storage Directory，再填写 storage 目录的完整 绝对路径。

该模式不要求开启 Zotero File Syncing。ZotFlow 仍需要 Zotero Data Sync 来获取条目 和附件元数据，但没有跨设备附件需求的用户无需再专门为 ZotFlow 配置 Zotero Storage 或 WebDAV，可以只保留本机文件。

该功能适用于由 Zotero 管理的 imported_file 和 imported_url 附件。ZotFlow 会在 检查附件缓存或已配置的同步服务之前直接读取磁盘，并且不会再创建一份 ZotFlow 缓存 副本。Linked file 仍使用自己的绝对路径或 Linked Attachment Base Directory。移动端 会忽略这个仅限桌面端的选项，继续使用已配置的 Zotero Storage 或 WebDAV 路径。

如果 Zotero 尚未在本机下载附件，直接读取会给出明确错误，而不会静默改为网络下载。 请先在 Zotero 中下载文件、修正配置路径，或关闭该选项以恢复通常的同步服务读取路径。

该功能的初始实现由 David Crandall（@Triquetra） 通过 PR #102 贡献，源自 Feature Request #101。感谢 David 为 ZotFlow 带来这项功能。

可靠性与兼容性​

  • 阅读器加载、渲染、跳转、标注保存与删除，以及实时刷新中的异步失败，现在都会 连同具体失败操作一起记入日志。
  • 笔记的防抖保存与刷新、可编辑区域同步、阅读器重连、阅读位置保存和活动中心刷新 现在使用 Obsidian 对窗口安全的计时器模式，改善弹出窗口兼容性。
  • 阅读器 iframe 和其他界面元素会在需要时由正确的所属 document 创建；Android 也会通过该 document 的 window 加载内联阅读器页面。
  • 外部链接文件仍然只支持桌面端，但在移动端尝试使用时，现在会给出明确的“不支持” 错误，而不是调用不可用的 Node.js API。
  • 格式错误的 zotero-key 或 zotflow-local-attachment frontmatter 值会被安全忽略， 不会再进入索引或链接解析。

原生且可搜索的设置页​

ZotFlow 设置页现已迁移到 Obsidian 1.13 的声明式设置 API。原来的横向标签栏被 General、Sync、WebDAV、Cache、Citation 和 CSL Render 六个原生设置子页面取代， 所有设置现在都可以通过 Obsidian 的全局设置搜索找到。

无需迁移或重置现有设置。ZotFlow 仍沿用原有的数据结构保存普通设置、阅读状态和 自定义主题；API Key 与 WebDAV 凭据仍保存在 Obsidian SecretStorage 中。

Sync、WebDAV、Cache 和 CSL Render 等动态页面会先立即创建界面，再在后台填充 Worker 数据，避免设置页卡顿，同时保留“验证成功后才保存凭据”的行为。

界面修复​

  • 批注评论编辑器兼容不同主题。 启用 Minimal Theme 时，点击评论编辑区的任意位置 现在都能正常聚焦，不再只有 “Add comment” 占位文字附近可以获取焦点。
  • Citation 模板示例与实际 Liquid 上下文一致。 示例现在正确使用根级 notePath 和 annotations，Zotero 元数据位于 item 下，并在 item.citationKey 缺失时回退到 item.key。
  • Citation 模板编辑框有更多空间。 模板文本框在桌面端更宽，同时在较窄的设置 窗口中保持响应式布局。
  • 缓存上限能正确处理无限模式。 0 会继续显示为无限制，空值或非整数会被拒绝。
  • ZotFlow Callout 适配 Obsidian 1.13 的颜色格式。 自定义 Callout 颜色现在使用 有效 CSS 颜色，避免升级 Obsidian 后显示异常。
  • 只有复制成功才会提示成功。 活动中心会等剪贴板写入完成后再显示“已复制”； 失败则会写入日志。
  • 图片提取按正确顺序启动。 “Extract annotation images”现在会先等待源笔记创建 或更新完成，再启动提取任务，避免两个操作相互竞速。
  • 命令面板名称更简洁。 “Open ZotFlow Activity Center”改为“Open Activity Center”，因为 Obsidian 已经会在命令旁显示插件名称。
  • Insert Citation 默认不再绑定快捷键。 之前的 Alt+C 默认绑定已移除，避免与 用户或 Obsidian 的其他快捷键冲突；如有需要，可在 Settings → Hotkeys 中自行设置。

其他修复​

  • 生成源笔记路径时，现在会与其他不适合文件名的控制字符一起移除 DEL 字符 （U+007F）。
  • 加载阅读器、验证 Zotero/WebDAV 设置或处理 ZotFlow 链接时，即使被拒绝的值不是 标准 JavaScript Error 对象，错误信息也能被完整保留。