Zotero CiteFlow 13.2.4

Zotero CiteFlow 13.2.4

发布日期：2026-11-06
适用版本：Zotero 10.0 - 12.*

架构守护与工程标杆对齐（v13.2.4）

• 全自动 13 项架构守卫与 360 行红线卡点（scripts/architecture-guard.mjs）：
  • 建立对标 MetaFlow 与 MindFlow 的第一梯队工程守卫，涵盖 §5.9 单文件 360 行上限、§5.2 TS 纯度与零正则切片、§5.2 编译器严格模式、§3 Fluent 本地化双语对称与 preferences.xhtml 100% data-l10n-id 驱动、§3 文件名治理、§4.1 设置项覆盖、§4.2 16px/24px/40px 网格规范、§5.3 废弃 Gecko API 拦截、§6 与 §9 版本及 SHA-512 更新源校验；
• 零债务冻结与消减基线（scripts/architecture-baseline.json）：
  • 全量 34 个 TypeScript 模块严格通过行长扫描（最大模块 328 行），基线声明 debtCleared: true 与 oversized: {}；
• 编译打包流水线前置守卫卡点（package.json）：
  • 构建命令重构为 npm run typecheck && npm run guard && node scripts/build-source.mjs，在任何代码超限或类型错误时直接阻断打包构建，保障产物严密性；
• 底层引用插入测试比对修复（tests/reference-citation.test.cjs）：
  • 修复类型擦除比对中的空行空白字符匹配，确保与底层原生 Word 引用行为验证完全吻合。

Zotero CiteFlow 13.2.3

Changes

• Migrate runtime and preferences sources to TypeScript with strict type checking and esbuild.
• Replace build-time class slicing with typed descriptor composition and collision guards.
• Restore stacked host method patches in reverse order and improve lifecycle cleanup.

Validation

• Type check, 62 automated tests and package verification passed.
• Zotero 10.0.7 isolated settings and library checks: 36 passed.
• Isolated Word COM citation-field checks: 14 passed; OS pointer dragging was not automated.

Zotero CiteFlow 13.2.2

Zotero CiteFlow 13.2.2

发布日期：2026-11-04
适用版本：Zotero 10.0 - 12.*

细节打磨与多窗口事件解绑加固（v13.2.2）

• 设置页第 4 卡片主控件与第 3 卡片从属控件层级精确区分（preferences.css）：
  • 第 4 卡片（刷新调度与性能控制）内的 4 个数值输入行（.zoterocitation-number-row）属于该卡片的一级内容主控件（上方无父级复选框），将其 margin-inline-start 修正为 0（严格贴合卡片 16px 内容起始线，与上方概述说明左边缘垂直对齐）；
  • 第 3 卡片（文集呈现与标签管理）内从属于「引用后自动维护标签」复选框的「引用标签文本」输入行（.zoterocitation-number-row.zoterocitation-subordinate-row）保持 margin-inline-start: 24px（精准对齐 40px 黄金基准线）。
• 多窗口拖拽事件 dragend 精确宿主文档解绑（views/drag-cite.mjs / views.mjs）：
  • 在 dragCite() 绑定 dragend 监听器时显式保存目标文档引用 this._dragDocument，并在 dispose() 与异常回滚时优先从 this._dragDocument 解绑，防止多窗口焦点切换后 this.document 动态 getter 指向其他窗口导致事件监听器残留。

Zotero CiteFlow 13.2.1

Zotero CiteFlow 13.2.1

发布日期：2026-11-04
适用版本：Zotero 10.0 - 12.*

执行逻辑与并发时序深度加固（v13.2.1）

• 窗口并发挂载与中途关闭自清理（src/hooks.mjs）：
  • attachWindow(win) 引入 binding.readyPromise 幂等锁，防止 onStartup() 与 onMainWindowLoad(win) 并发调用时提前返回未完成初始化的窗口绑定；
  • 在 prepareWindow、patchIcon、dragCite 各异步阶段增加 win.closed || binding.closed || !addon.data.alive 检查并自动执行 detachWindow(win)，杜绝窗口在初始化中途关闭时残留半挂载补丁。
• 集合创建事务与会话关闭/开关切换的异步竞态闭环（collections.mjs / formatting.mjs）：
  • initCollection() 在 await collection.saveTx() 返回后，新增对 session.closing 及 collections.enable === false 的二次核验；若事务等待期间会话进入关闭流程或用户关闭了临时集合开关，立即回滚擦除该集合并清理 _temporaryCollectionKeys；
  • clearSession() 将 this._initializationTasks?.get?.(sessionID) 纳入前置 Promise.allSettled 等待队列，彻底消除会话销毁与集合初始化并发导致的孤儿集合。
• 多文档前台窗口标题防误抢（document-naming.mjs）：
  • _resolveFallbackDocumentId() 在读取 probed.foregroundTitle 前先行计算已被其他活动会话占用的文档名集合 claimedByOthers；当用户切换焦点至已识别文档 A.docx 时，未识别的后台新会话 S2 绝不误抢 A.docx 的标题，而是精准匹配唯一未被占用的可见 Word 窗口标题。
• Word 命令完成后零节流即时刷新（word-integration.mjs）：
  • _handlePostExecCommand() 在调用 refreshSessionCitations() 前清除 this._lastRefreshAt[sessionID]，确保用户插入或编辑引文后的显式刷新永不被前序后台轮询的 500ms 节流窗口推迟。
• 空文档确认后的排序签名缓存同步驱逐（formatting.mjs）：
  • _handleEmptyCitationSnapshot() 在二次确认文档引文已清空时，同步驱逐 _sortedCacheBySession 中该会话的旧排序签名缓存，保持缓存与 session.idData 绝对一致。

Zotero CiteFlow 13.2.0

Zotero CiteFlow 13.2.0

发布日期：2026-11-04
适用版本：Zotero 10.0 - 12.*

13.2.0 里程碑特性与全链路架构升级汇总

1. 全链路数据处理与容错加固

• 临时集合开关与核心管线彻底解耦（word-integration.mjs）：
  • 关闭 collections.enable（不生成 Word 临时集合）时，ensureSession()、_syncActiveWordSessions() 与 _handlePostExecCommand() 仍完整驱动主列表「Citation」列（session.idData）、自动标签（_sessionCitedIDs）及后台文档名称识别（session.docId）；
  • 重新开启 collections.enable 时，新建集合立即根据 session.idData 同步回填已引用的条目，关闭时严格在 await col.eraseTx() 成功后才移除持久化追踪键。
• 全回收站文档自动清空与脏键防护（order-cache.mjs / formatting.mjs）：
  • 新增 _hasOnlyTrashedCitationItems(citationsByIndex)，精确区分「畸形快照」与「文档内所有引文均已移入 Zotero 回收站/删除」，后者自动清空 session.idData、移除临时集合成员并清理会话引用标签；
  • 对 citationsByItemID 的键统一经由 _parseValidItemID 过滤非正安全整数，拒绝脏键进入 session.idData。
• 底层 cite.mjs 直通守卫与多窗口自愈（cite.mjs / hooks.mjs / views.mjs）：
  • 在 src/modules/cite.mjs 核心函数中直接内聚多窗口聚焦解析（Zotero.getMainWindow() 优先）与 deleted / inTrash 拦截；
  • src/hooks.mjs 实现 rebindGlobalWindow()，任意主窗口卸载时自动将 globalThis.window / document / ZoteroPane / Zotero_Tabs 重绑定至其余未关闭的活动主窗口；
  • ViewsSessionIndex 显式过滤 closing: true 的正在销毁会话。
• 回收站条目标签治理与设置页状态精准判定（tag-governance.mjs）：
  • 曾被打上管理标签的条目移入回收站后，严格跳过写入并保留管理记录（便于恢复后自动清理），且不触发 complete: false 误报。

2. 模块化设置面板与排版规范

• 四卡片模块化设置页架构（preferences.xhtml / preferences.css / preferences.mjs）：
  • 按业务流划分为「核心引用追踪与主列表视图」「Word 文档联动与自动标记」「性能调优与同步节流」「版本信息與运行诊断」四个单层折叠分组，仅默认展开首组；
  • 严格对齐 16px / 40px 三级边缘距离标准规范，消除全部内联硬编码中文，在初始化、变更、外部同步与恢复默认设置时全量联动子项启用状态；
  • 在线更新源 update.json 全面采用 sha512: 校验哈希。

Zotero CiteFlow 13.0.13

Zotero CiteFlow 13.0.13

发布日期：2026-11-04
适用版本：Zotero 10.0 - 12.*

全链路数据处理深度加固（v13.0.13）

• 解耦临时集合开关与核心数据同步管线（word-integration.mjs）：
  • 修复当用户关闭 collections.enable（不生成 Word 临时集合）时，ensureSession()、_syncActiveWordSessions() 与 _handlePostExecCommand() 因检查 !tracked.collection 而提前中断、导致主列表「Citation」列（session.idData）与自动标签（_sessionCitedIDs）停止更新的链路阻断问题；
  • 即使关闭临时集合，后台 _syncSessionDocumentName() 仍正常解析并记录 session.docId，确保后续随时开启临时集合时无需重新等待文档名识别。
• 文档全部引文移入回收站时的残留状态自动清空（order-cache.mjs / formatting.mjs）：
  • 新增 _hasOnlyTrashedCitationItems(citationsByIndex) 精确区分「损坏/畸形快照」与「文档内所有引文均已移入 Zotero 回收站或删除」；
  • 当文档内引用的条目全部移入回收站导致 sortedItemIDs 为空时，不再提前退出，而是立即清空该会话的 session.idData、从临时集合移除回收站条目并清除对应会话的引用标签集合。
• _applyCitations 脏键清洗与防污染（formatting.mjs）：
  • 对 citationsByItemID 的键统一通过 _parseValidItemID 校验正安全整数，彻底拦截 "0"、"-1"、"NaN" 等非法键进入 session.idData。
• 回收站条目标签同步状态精准判定（tag-governance.mjs）：
  • 当曾被打上 /Citations 管理标签的条目被移入回收站时，严格遵循只读防护跳过写入并保留管理记录（便于从回收站恢复后自动清理），同时不再将其误判为写入失败（skipped = true / complete: false），消除设置面板误报「应用当前更改失败」的问题。
• 会话关闭过渡期的视图索引隔离（views/session-index.mjs）：
  • _getSessionIndex() 与 getCitationText() 显式过滤 session.closing === true 的正在销毁会话，防止会话异步关闭期间主列表「Citation」列读取到过期缓存。

Zotero CiteFlow 13.0.12

Zotero CiteFlow 13.0.12

发布日期：2026-11-04
适用版本：Zotero 10.0 - 12.*

深度加固与审计完善（v13.0.12）

• 底层 src/modules/cite.mjs 原生守卫直通加固：
  • 将多窗口聚焦解析（优先 Zotero.getMainWindow()，平滑回退 globalThis.window 与 Zotero.getMainWindows()[0]）与回收站/已删除条目拦截（item.deleted !== true && item.inTrash !== true）直接内聚至底层 src/modules/cite.mjs 的 citeItems() 核心函数中，同时在 tests/reference-citation.test.cjs 中建立显式结构断言与 SHA-256 归一化校验，确保无论通过 addon.api.citeItems 还是直接加载 cite.mjs 模块均具备 100% 防护。
• 多窗口生命周期与 Views.document 对称重绑定：
  • src/hooks.mjs 新增 rebindGlobalWindow(closingWin) 机制：即使某窗口在未启用跟踪状态下关闭，只要其曾绑定在 globalThis.window，卸载时都会自动探测并重绑定到其余未关闭的活动主窗口（!w.closed）；
  • src/modules/views.mjs 的 document getter 与 window getter 完全对齐，优先返回 this._window?.document ?? Zotero.getMainWindow?.()?.document ?? globalThis.document。
• 临时集合开关切换的事务原子性与重开即时回填：
  • 在 src/modules/citation/preferences-sync.mjs 中，关闭 collections.enable 时严格在 await col.eraseTx() 成功后才从 _temporaryCollectionKeys 移除对应 key，若底层事务异常则保留 key 供后续自愈清理；
  • 重新开启 collections.enable 时，为活动会话创建集合后立即根据 session.idData 同步填充已引用的文献条目（syncCollectionItems），并刷新会话索引。

Zotero CiteFlow 13.0.11

Zotero CiteFlow v13.0.11 Release Notes

Release Date: 2026-11-04
Version: 13.0.11
Compatibility: Zotero 10.0 – 12.*

Highlights

1. Multi-Window Unload Fallback & Trashed Item Guard (src/hooks.mjs, src/addon.mjs):
   • detachWindow gracefully falls back to remaining active windows in windowBindings and Zotero.getMainWindows() rather than unconditionally setting global window variables to undefined, preventing TypeError when closing secondary main windows.
   • addon.api.citeItems encapsulates safe item resolution and strictly rejects deleted or inTrash items before dispatching Word citation injection.
2. Temporary Collection Teardown Ordering & Key Hygiene (src/modules/citation/preferences-sync.mjs):
   • Inverted and properly awaited collection destruction when collections.enable is toggled off: detaches active session references and invalidates indexes first, awaits eraseTx(), cleans up _temporaryCollectionKeys, saves preferences, and executes clearStaleArtifacts(), eradicating orphaned collection keys.
3. Preferences Interlocking, Single-Group Accordion & Typography Alignment (preferences.mjs, preferences.xhtml, preferences.css):
   • Invokes updateDependencies() on panel initialization and settings reset so control dependencies take effect immediately.
   • Accordion cards strictly follow the single open-group standard (only Module 1 opens by default).
   • Removed hardcoded Chinese text from version info in preferences.xhtml, allowing clean Fluent localization.
   • Fixed Level 1 top overview description in Module 4 to remain flush with the 16px content line (0px offset).
4. SHA-512 Update Manifest Compliance (scripts/build.ps1, tests/package.test.cjs, update.json):
   • Updated package builder, tests, and feed manifest to use standard sha512: hash prefixes as mandated by AGENTS.md 205/227.

Verification

• Automated Test Suite: 100% passed (npm test).
• Tag & Version Validation: python scripts/release-tags.py --self-test passed.

Zotero CiteFlow 13.0.10

Zotero CiteFlow v13.0.10 Release Notes

Release Date: 2026-11-03
Version: 13.0.10
Compatibility: Zotero 10.0 – 12.*

Highlights

1. Modular Preferences Architecture & 40px Golden Alignment (chrome/content/preferences.xhtml, chrome/content/preferences.css):
   • Refactored settings panel into 5 distinct business workflow modules: Core Tracking Service, Writing Interaction & Quick Cite, Collections & Tag Governance, Scheduling & Performance, and Diagnostics & Maintenance, plus an authoritative Version Card.
   • Strictly conforms to AGENTS.md 4.1 & 4.2 typography and alignment standards: standard 14px control font size, 16px horizontal card padding, and exact 40px vertical golden alignment line for secondary controls and tertiary subordinate descriptions/inputs.
2. Dedicated Temporary Collections Toggle & Dependency Interlocking (prefs.js, src/modules/preferences.mjs, src/modules/citation/collections.mjs, src/modules/citation/preferences-sync.mjs):
   • Added extensions.zotero.zoterocitation.collections.enable preference and setting checkbox, granting users full control over whether Word document temporary collection trees are generated.
   • Implemented dynamic dependency protection (updateDependencies): disabling "Maintain citation tags" automatically disables and visually dims the subordinate tag text input field, preventing invalid or ambiguous configurations.
   • Robust live preference updates: toggling collection creation dynamically cleans up or re-initializes temporary collections for active editing sessions.
3. Comprehensive Localization (locale/zh-CN, locale/en-US):
   • Full bilingual coverage across all 5 setting modules, section summaries, and help tooltips with complete consistency.
4. Source Code Cleanliness:
   • Strictly maintained all 27 source modules under <= 360 lines of code.

Verification

• Automated Test Suite: 53/53 top-level tests passed (npm test).
• Tag & Version Validation: python scripts/release-tags.py --self-test passed.

Zotero CiteFlow 13.0.9

Zotero CiteFlow v13.0.9 Release Notes

Release Date: 2026-11-03
Version: 13.0.9
Compatibility: Zotero 10.0 – 12.*

Highlights

1. Multi-Window Tree Enumeration & Dynamic Expand Self-Healing (src/modules/views/icon-patch.mjs):
   • _getAllCollectionsViews enumerates across all active main and detached windows to guarantee that CiteFlow Word collections remain positioned immediately above My Publications in every visible tree view.
   • Enhanced _expandRow monkey-patch to immediately invoke _refreshRowMap() and tree.invalidate() upon slice reordering, preventing row-index drift when expanding collapsed libraries.
2. Academic Citation Text Sanitization & Deduplication (src/modules/citation/formatting.mjs):
   • Strips Unicode zero-width formatting characters (\u200B-\u200F, \uFEFF) and invisible control codes from plain citation text.
   • Automatically collapses repeated identical citation labels for items cited multiple times within composite fields.
3. Transactional Membership Robustness & Library Isolation (src/modules/citation/collections.mjs, src/modules/citation/formatting.mjs):
   • Guards syncCollectionItems transactional DB executions with isolated try/catch and error logging, preventing intermittent DB locks from stalling session refresh cycles.
   • Aligns top-level item member filtering with collection.libraryID to preserve strict library boundary isolation.
4. Source Code Cleanliness:
   • Strictly maintained all 27 source modules under <= 360 lines of code.

Verification

• Automated Test Suite: 53/53 top-level tests passed (npm test).
• Tag & Version Validation: python scripts/release-tags.py --self-test passed.