Zotero RefFlow 13.2.1

Zotero RefFlow 13.2.1

Release date: 2026-11-06
Part of Zotero Flow series.

Major Highlights & Changes (工程架构治理与零欠账达成)

1. 全仓 360 行架构硬约束达标与历史欠账彻底清零 (§5.9 Architecture Debt Cleared)

• 4 大历史遗留超长模块深度领域解耦：将 RefFlow 剩余的 4 个超长模块全量拆解为职责单一、高内聚的子模块，全部降至 360 行基线以下：
  • src/modules/batchImporter.ts（424 行 $\to$ 286 行）：将批量导入事务回滚、遗留 Extra 标记迁移与跨条目关系/文集清理逻辑剥离至 src/modules/batchRollback.ts（202 行）；
  • src/modules/utils.ts（517 行 $\to$ 280 行）：将 DOI/arXiv/URL 正则提取、GB/T 7714 解析分发、作者姓名拆分与 HTML 清理逻辑抽取至 src/modules/referenceParser.ts（241 行）；
  • src/modules/tip.ts（567 行 $\to$ 139 行）：将引文浮层 DOM 节点工厂（标题/标签/操作/摘要）抽离至 src/modules/tipDOM.ts（303 行），视口边界自适应与滚轮缩放抽离至 src/modules/tipView.ts（186 行）；
  • src/modules/api.ts（694 行 $\to$ 320 行）：将知网（CNKI）检索、网页抓取与阅读 API 独立收敛至 src/modules/cnkiProvider.ts（184 lines），将多源引文适配转换器（Crossref/OpenAlex/arXiv/ConnectedPapers 等）抽离至 src/modules/apiMappers.ts（232 行）。
• 72 个源码文件 100% 达成 360 行基准：
  • 扫描全仓 src/ 下全部 72 个 TypeScript 源码模块，超长模块数正式降为 0；
  • scripts/architecture-baseline.json 宣告 debtCleared: true，历史冻结名单清空为 {}；
  • 架构守卫常态化校验 freeze-and-shrink 基线完整性，禁止任何模块反弹反向膨胀。

2. 全系品牌状态标签治理统一 (§3 Status Label Governance)

• 对齐全系规范：docs/brand/product.json 中的 releaseStatus 统一由历史 stable 标签纠正为全系规范的 released；
• 全系合规守卫：在 scripts/architecture-guard.mjs 和 tests/robustness.test.ts 中建立双重守卫，严禁非规范的状态标签。

3. 完整向后兼容与运行时契约保证

• API 原型与单例 100% 兼容：BatchImporter.rollbackBatch、BatchImporter.migrateRecords、Utils 解析方法及 API.cnki 均保留透明代理转发与原型兼容，无破坏性变更；
• 现代 Gecko 运行时稳定：严格保持 Gecko 153+ 冻结内建原型防护，避免任何侵入性原型篡改。

---

验证结论 (Verification)

1. 静态类型守卫：npm run tsc 0 错误通过；
2. 架构合规守卫：npm run guard 8/8 规则 100% 通过（含 360 行全量检查、Fluent 三语对称性、偏好面板对齐等）；
3. 单元自动化测试：npm test 359/359 项单元测试 100% 通过（39 suites，0 失败）；
4. 构建流水线：npm run build 生成生产包 zotero-refflow.xpi 并同步更新 update.json SHA-512 哈希。

v13.2.0

Zotero RefFlow 13.2.0

Release date: 2026-11-04
Part of Zotero Flow series.

Major Highlights & Changes (中等版本重大演进)

1. 架构深度解耦与 360 行守卫落地 (Architectural Decoupling & <=360 Line Guard)

• Connected Papers 图谱模块深度解耦：将原 1,099 行的单体控制器重构拆解为高内聚的领域服务，主协调器精简至 299 行：
  • graphStyles.ts：图谱容器与亮暗主题样式注入；
  • graphViewer.ts：内嵌 iframe 容器初始化与拉伸调整器 (Resizer)；
  • graphVisualState.ts：图谱节点激活与高亮联动状态管理；
  • graphCard.ts：单卡片渲染、拖拽交互与操作；
  • graphPanel.ts：图谱主面板容器、状态行与工具栏构建。
• Views 侧边栏与编排流水线模块深度解耦：将原 1,047 行的单体控制器拆解为专注的领域子服务，主协调器精简至 301 行：
  • referencePaneStyles.ts：item-pane 与卡片样式注入；
  • referenceTip.ts：多源引文元数据悬浮窗渲染；
  • referencePaneDOM.ts：item-pane 容器注册、多窗口自愈与重置；
  • referenceAttachment.ts：PDF 附件有效性检查与缓存安全签名；
  • referenceNeighborhood.ts：Citations / Related 学术网络多步推断；
  • referenceSourceFetchers.ts：Auto / Web / PDF / API 独立检索分支；
  • referenceRefreshDispatcher.ts：刷新队列防抖与取消调度；
  • referenceSettingsAction.ts：首选项动作与条目交互调度；
  • referenceBatchOperations.ts：批量导入关联节点与事务回滚管理；
  • referencePipeline.ts：核心引文流水线编排。
• 自动化架构守卫测试 (tests/architectureGuard.test.ts)：
  • 常态化断言所有重构目标模块行数严格 <= 360 行；
  • 杜绝任何版本号或临时前缀命名，保持干净的语义化命名；
  • 完整保持 Views 与 ConnectedPapers 原型链方法与公开 API 的 100% 向后兼容。

2. Connected Papers 多起点安全解析与来源透传

• 起点解析统一收敛 (graphOriginResolution.ts)：自动校验并过滤空 ID 或破坏 API 请求键的非法分隔符，支持对有效起点正常构建图谱；
• 状态与来源标明 (graphStatus.ts)：图谱状态栏明确呈现 Connected Papers 数据源 Provenance，并准确标注未解析起点数量（如 未解析起点 1），避免信息丢失；
• 异步管线解耦 (connectedPapersPipeline.ts)：起点解析、图谱拉取与本地文献匹配彻底解耦，检索失败或无有效起点时提供清晰本地化提示。

3. 阅读器与本地化鲁棒性加固

• 阅读器失效附件防护：检测并阻断针对已删除、移入回收站或不可访问的 PDF 附件提取，避免错配其他附件；
• Fluent 多语言沙箱作用域穿透定位：修复原生运行环境中全局作用域缺失导致回退字面键名的问题，增加多层穿透与韧性默认值；
• 右键折叠菜单命令委托：二级折叠菜单顶层容器统一委托命令下发，保证异步刷新下的选区快照一致性。

---

验证结论 (Verification)

1. 类型检查：npm run tsc 0 错误通过；
2. 自动化单测：npm test 358/358 项单元测试 100% 通过（39 suites，0 失败）；
3. 真实宿主环境验证（Zotero 10.0.7 隔离 Profile）：
   • 架构与生命周期端到端套件：6/6 全部通过；
   • Connected Papers 多起点解析套件：1/1 全部通过；
4. Gecko 153 打包校验：符合 Firefox 140+ / Gecko 153+ 标准运行时，34 项文件结构校验 100% 通过。

Zotero RefFlow 13.1.10

Zotero RefFlow 13.1.10

Released 2026-11-03. Removal of CNKI credential fields from preferences panel, streamlining online academic service configuration, and updating 3-language localizations.

Highlights & Updates

1. Streamlined Online Academic Services:

   • Removed CNKI username and password credential input fields from the "Online Academic Services & API Keys" preferences group (preferences.xhtml).
   • CNKI public metadata retrieval continues to operate seamlessly without requiring or displaying personal credentials in the settings interface.

2. Clean 3-Language Parity:

   • Purged obsolete CNKI credential keys from Chinese (zh-CN), English (en-US), and Italian (it-IT) localization files with zero key discrepancy.

3. Automated Regression Verification:

   • Updated preference binding tests in tests/robustness.test.ts to ensure 100% test pass rate across all 34 test suites.

Zotero RefFlow 13.1.9

Zotero RefFlow 13.1.9

Released 2026-11-03. Emergency regression fix for main library item detection and sidebar rendering, complete restoration of native Reader resolution, and stabilization of the 5+1 modular preferences layout.

Highlights & Fixes

1. Critical Fix: Main Library Item Selection & Reference List Rendering:

   • Root Cause Identified: In versions 13.1.7 and 13.1.8, an over-engineered multi-tier getReader(win) implementation traversed Zotero.Reader._readers matching topWindow === win. In the main Zotero library pane, background PDF tabs share the main window as their topWindow, causing getReader(win) to mistakenly return background reader instances instead of undefined. Consequently, getItem(win) returned background attachments instead of the currently selected library item, triggering a sameInput() mismatch and preventing reference cards from rendering (resulting in an empty sidebar).
   • Fix Applied: Completely restored the clean, proven native implementation of getReader(win) and getItem(win) from the stable v13.1.6 baseline. When viewing the main library, getReader strictly yields undefined, allowing getItem to directly and reliably query the active selection from ZoteroPane.getSelectedItems().
   • DOM Method Restoration: Reverted synthetic namespace wrappers back to native doc.createXULElement(...) across views.ts, referenceCards.ts, and connectedpapers.ts, preserving native Gecko XUL popup prototypes and menu behaviors.

2. Modular 5+1 Preferences Maintained:

   • Kept the verified 5+1 business-driven settings panel layout (preferences.xhtml): Literature Retrieval & Sources, Reference List & Card Display, Hover Tooltips, Batch Import & OA Fulltext Downloads, Online Academic API Keys, and About RefFlow.
   • Maintained full 3-language parity (zh-CN, en-US, it-IT) with zero missing keys.

3. Regression Test Suite:

   • Verified 344 unit tests passing cleanly with zero regressions.

Zotero RefFlow 13.1.8

Zotero RefFlow 13.1.8

Released 2026-11-03. Comprehensive settings architecture modularization (5+1 business-driven groups), full preference exposure (Open Access batch download, citation graph controls, CNKI credentials), dead locale key cleanup, and automated preference coverage tests.

Highlights & Updates

1. Modular 5+1 Settings Panel Architecture:

   • Reorganized the preferences window (preferences.xhtml) from a scattered layout into a logical top-down flow:
     • Module 1: Literature Retrieval & Sources (open="open" by default): Priority sources, auto-refresh triggers, PDF/API reference persistence, and source completeness details;
     • Module 2: Reference List & Card Display: Library match opacity slider, and Connected Papers citation graph toggle & container height;
     • Module 3: Hover Preview & Tooltips: Floating window trigger delay, Ctrl+click translation, background/title colors, and smooth fade durations;
     • Module 4: Batch Import & Quick Actions: Automatic Open Access (OA) PDF download toggle, and sidebar quick menu action filters;
     • Module 5: Online Academic Services & API Keys: Dedicated credential cards for OpenAlex, Semantic Scholar, Connected Papers, and CNKI;
     • Module 6: About Zotero RefFlow: Version badges, attribution licenses, build timestamps, and release links.

2. Full Core Feature Preference Exposure:

   • Exposed downloadOA (extensions.zotero.refflow.downloadOA) in the settings UI to allow users to toggle automated Unpaywall / OpenAlex OA PDF downloads during batch imports;
   • Exposed graphView.enable and graphView.height to let users control default citation graph visibility and container sizing;
   • Added CNKI username and password credential inputs (CNKI.username / CNKI.password) for Chinese journal retrieval.

3. Locale Key Cleanup & Strict 3-Language Parity:

   • Purged 10 unreferenced legacy keys from zh-CN, en-US, and it-IT localization files;
   • Added complete symmetric translations for all new preference groups and control labels across Chinese, English, and Italian with zero discrepancy.

4. Automated Preference & Grid Coverage Testing:

   • Added automated suite in tests/robustness.test.ts verifying the 6-group modular structure, default-open state, complete 29-preference binding coverage, and 100% symmetric locale key parity.

Zotero RefFlow 13.1.7

Zotero RefFlow 13.1.7

Released 2026-11-03. Modern Gecko architecture enhancement for detached reader windows, resilient main-window library navigation routing, safe XUL namespace fallbacks, and complete regression test coverage.

Highlights & Updates

1. Detached Reader Window Compatibility (Zotero 10 ~ 12 Modern Architecture):

   • Multi-tier Reader Detection (Utils.getReader): Enhanced reader resolution to seamlessly support detached PDF/EPUB reader windows (where win.Zotero_Tabs is absent) by inspecting win.reader, win.ZoteroReaderView.reader, Zotero.Reader.getByWindow(win), and actively traversing Zotero.Reader._readers across frames and top-level detached windows.
   • Active Item & PDF Reference Parsing: Ensured getItem(win), resolveLibraryID(win), and importCollections(parent, win) reliably extract the active parent item and appropriate library context when invoked from detached reader tabs or windows.
   • Resilient Library Navigation (Utils.selectItemInLibrary): Added automated main-window routing and graceful fallback (Zotero.getMainWindow() / Zotero.getActiveZoteroPane()). Clicking "Locate in Library" (cards-show-library) or opening items from a detached reader window safely focuses the main library pane without throwing TypeError: Cannot read properties of undefined (reading 'select').

2. Safe XUL Element Namespace Fallbacks:

   • Implemented Utils.createXULElement(doc, tag) with strict fallback from doc.createXULElement to doc.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", tag) and standard doc.createElement.
   • Updated popup menus and action buttons in ReferenceCards.menu, Views.typeMenu, and ConnectedPapers.registerButton to prevent execution failures in non-XUL / HTML document contexts.

3. Preference Grid & Visual Alignment Verification:

   • Verified that preference panel settings (preferences.xhtml & preferences.css) adhere strictly to the 2026-11-02 3-level indentation standard (margin-inline-start: 24px, card padding 16px, full-bleed headings margin: -16px; padding: 12px 16px;), ensuring smooth responsive wrapping and high contrast theme adaptation.

4. Automated Regression Test Suite:

   • Added unit test cases to tests/robustness.test.ts covering detached reader window resolution, cross-window library item selection routing, and XUL element creation fallbacks under various document implementations.

Zotero RefFlow 13.1.6

Zotero RefFlow 13.1.6

Released 2026-11-03. Comprehensive read-only UI state protection, localized error resolution, ConnectedPapers origin editability guards, and full documentation/version synchronization.

Highlights & Updates

1. Complete Read-Only UI & Context Menu Protection:

   • Quick-Action Context Menu (ReferenceCards.menu): Automatically disables cards-import-selected, cards-import-all, and relatedbox-rollback menu items (disabled="true") when the active parent item or library is read-only (!parent.isEditable() or non-editable library), preventing invalid user actions upfront in addition to execution-level guards.
   • Card Action Button & Library Match Sync: Unified parent.isEditable() and library editability checks in both initial card rendering and asynchronous library match updates (queueLibraryMatch).
   • ConnectedPapers Graph Item Action Guard: Added origin editability validation (originsEditable) so graph candidate import buttons automatically disable and display localized read-only tooltips when any graph origin item belongs to a read-only library or Trash.

2. Localized Read-Only Error Resolution (Views):

   • Fixed Views.importReferences and Views.rollbackReferences to invoke the imported getString('cards-library-readonly') localization helper directly instead of an undefined globalThis.getString lookup, ensuring localized read-only error messages across zh-CN, en-US, and it-IT.

3. Documentation, Release Notes & Version Consistency Gate:

   • Synchronized package.json, addon/manifest.json, update.json, docs/brand/product.json, README.md, and README.en.md to version 13.1.6 (v13.1.6) and Zotero compatibility range 10.0 – 12.*.
   • Added automated regression tests in tests/robustness.test.ts verifying read-only UI menu disabling, localized Views read-only guards, and zero version/documentation drift across repository manifests and READMEs.

Zotero RefFlow 13.1.5

Changes in Zotero RefFlow 13.1.5

• Read-Only Protection: Added native item.isEditable() safety guards to citation import and transaction rollbacks.
• Settings Panel Hierarchy Standard: Refactored preferences.css to workspace Section 4.2 standard 16px/24px/40px grid, collapsible cards, and typography hierarchy.
• Authoritative Manifests: Synchronized package, product, and update manifests across all distribution channels.

Zotero RefFlow 13.1.4

Zotero RefFlow 13.1.4

Released 2026-11-02. UI layout optimization, search placeholder simplification, and Zotero 10-12 forward-looking compatibility range lock.

Highlights & Updates

1. Controls Nested inside Source Details (refflow-source-details):

   • Refactored layout to move reference count, source indicator, and cancellation controls (#reference-num, .header.refflow-status) directly into the <details id="refflow-source-details"> container.
   • Cleans up the top area of the sidebar panel, eliminating duplicate and cluttered status rows between the search box and reference cards.
   • When collapsed, users enjoy a pristine view with only the search input and reference cards list; when expanded, comprehensive source diagnostic details, provider attempts, and status indicators are cleanly presented.

2. Search Placeholder Simplified:

   • Streamlined the search placeholder from verbose multi-word text to concise and standard terminology across all supported locales:
     • Chinese (zh-CN): 搜索
     • English (en-US): Search
     • Italian (it-IT): Cerca

3. Zotero 10 ~ 12 Platform Compatibility:

   • Aligned compatibility declarations across manifest.json, update.json, and update-template.json to the standard Flow Series specification:
     • strict_min_version: "10.0"
     • strict_max_version: "12.*"
   • Provides native coverage and support for current stable Zotero 10.x, development/preview Zotero 11.x, and future Zotero 12.x architectures.

4. Localization Robustness & Zero-Regressions:

   • Enhanced fallback dictionaries to prevent raw Fluent key string leaks.
   • 100% test pass rate across 340 test suites.

Zotero RefFlow 13.1.3

Zotero RefFlow 13.1.3

Released 2026-11-02. Brand alignment release for sidebar section title.

Highlights & Branding Updates

1. Brand Alignment in Sidebar Header:

   • Added product brand Zotero RefFlow prefix to the ItemPane section header title across all supported languages:
     • Chinese (zh-CN): Zotero RefFlow 参考文献 / Zotero RefFlow 参考文献（{ $count }）
     • English (en-US): Zotero RefFlow References / Zotero RefFlow References ({ $count })
     • Italian (it-IT): Zotero RefFlow Riferimenti / Zotero RefFlow Riferimenti ({ $count })
   • Aligns perfectly with Zotero MetaFlow 期刊索引 and established Flow Series branding standards.

2. Native Stability & Verification:

   • Zero intrusive DOM changes; purely driven by Zotero 10's native Fluent localization bindings.
   • Colorful feather icon, section buttons (type menu, refresh, more options), card search, and reference card flows 100% operational.
   • 100% test pass rate across 340 test suites.