dsh-zotero 1.0.0 → 1.1.0

package/README.en.md

@@ -11,7 +11,7 @@
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version" style="max-width:100%;"></a>
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads" style="max-width:100%;"></a>
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/l/dsh-zotero" alt="license" style="max-width:100%;"></a>
-  <a href="https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.1"><img src="https://img.shields.io/badge/dsh-0.2.2--rc.1-blue" alt="dsh version" style="max-width:100%;"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.2"><img src="https://img.shields.io/badge/dsh-0.2.2--rc.2-blue" alt="dsh version" style="max-width:100%;"></a>
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
   <a href="https://github.com/hashgraph-online/hol-guard"><img src="https://img.shields.io/badge/HOL%20Guard-passing-00a67e" alt="HOL Guard Scanner"></a>
 </p>
@@ -27,19 +27,30 @@ All operations interact with Zotero through its local API (`127.0.0.1:23119`). R
 
 ## Features
 
-- **Conversation & Retrieval**
-  - Search & reading: Search papers by title, author, year, or full text, and read bibliographic metadata, notes, and local PDF full text.
-  - Passage extraction: Locate relevant passages across full text, notes, and annotations for specific research questions, with original page numbers preserved on PDF annotations.
-  - Citation & export: Generate in-text citations or bibliographies in specified CSL styles, and export BibTeX, RIS, or CSL-JSON.
-  - Writing & extensions (optional): With write access enabled, create notes and update tags or collections (each write requires approval); with the scholarly component enabled, search across seven external indexes and verify references.
-- **Literature Trail**
-  - Search history: The session header shows query terms, scopes, filter conditions, and hit counts for every tool call on the first screen.
-  - Passage review: Review extracted passages and annotations grouped by paper, complete with source tags and page numbers for easy verification.
-  - Export collection: Review all citations and BibTeX entries generated in the conversation, deduplicated across items and ready to copy or download.
-- **Literature Panel**
-  - Library browsing: Browse collection trees, tags, saved searches, and the Trash in the right sidebar, with multi-field filtering.
-  - Details & reading: Inspect metadata, notes, and attachment lists, and open local PDFs directly in the reading pane.
-  - Citations & handoff: Copy BibTeX entries, CSL citations, or item details directly from the action row, or send selected items into the chat draft with one click.
+The agent searches, reads, and cites the library with tools in conversation; the literature trail checks what it did in this session; the literature panel is yours to browse the whole library.
+
+- **Conversation**
+  - Search and browsing: Search by title, author, year, tag, or full text, scoped to the whole library, My Publications, one collection, or one saved search. Read collection trees, tags, and saved searches, and batch-read known refs with a separate result for each one.
+  - Passage location: Pull passages from full text, notes, and annotations for a specific question. Every passage names its source, annotations keep their Zotero page numbers, and the result reports full-text coverage and the sources it skipped.
+  - Ranking and matches: BM25 lexical ranking by default. Optional local semantic ranking runs six CPU-only embedding tiers and fuses them with BM25 through RRF, with every passage reporting a lexical, semantic, or hybrid match. Up to four query variants are scored separately and each passage keeps its best score; an empty result says whether nothing overlapped or no source was available.
+  - Citations and export: Generate in-text citations or a merged bibliography in CSL styles, and export BibTeX, BibLaTeX, RIS, or CSL-JSON. Style and locale follow the configured defaults.
+  - Reconciliation and changes: Reconcile DOIs, BibTeX keys, or bibliographic fields against the library and get back refs, citation keys, confidence, and a reviewable field diff. Report additions, modifications, and deletions from the library version, with the Trash counted separately.
+  - Research SOPs: Eight phased workflows loaded on demand, with only their names and short descriptions resident in the prompt and each carrying stage budgets and stop conditions. The core component ships four (paper digest, evidence synthesis, manuscript audit, library governance) and the scholarly component adds four (research landscape, citation lineage, publication integrity, literature intake).
+- **Literature trail (session header)**
+  - Search conditions: Every call lists its query, scope (library, My Publications, collection, saved search), mode (metadata or full text), filters, and hit count, with the total and note hits counted separately.
+  - Passage review: Passages and annotations are grouped by item with their source, page number, and coverage; refused or cancelled calls are recorded too.
+  - Export summary: Every citation and BibTeX entry from the session is collected across items, split by format, and deduplicated, ready to copy or download; failed exports are listed on their own.
+  - Long sessions: History-window truncation leaves early items intact. Long lists page, and switching to the trail reads the existing result.
+- **Literature panel (right sidebar)**
+  - Browsing and filtering: Switch libraries, expand the collection tree on demand, and open saved searches, My Publications, and the Trash. The item list searches metadata or full text, sorts by several fields, and filters by type, tag, year, and attachment presence.
+  - Details and reading: Metadata, collections and tags, and the notes, attachments, and annotations sub-collections page independently. Local PDFs open in the right reading pane, and with `allowUrlPdfRead` enabled the panel also reads URL attachments already in the library.
+  - Citations and handoff: Copy a citation, bibliography, or BibTeX entry from the action row, and send selected items into the chat draft. The composer's Zotero button and bibliography deliverables both open the panel.
+  - State restoration: Per Zotero instance, the panel remembers the selected item, the active section, and expanded collection branches, along with the scroll position and child pagination.
+  - Parsed results: With the document parsing component enabled, an item's action row opens a parsed tab named after the paper (full text, figures, selection actions), and the toolbar's Manage parsed docs page lists every artifact, with state and keyword filters, per-row open or reparse, and page-wide batch discard.
+- **Optional capabilities (off by default)**
+  - Library writes: Enabling `writeEnabled` registers 15 tools that write only to the personal library, covering notes, tags and collection membership, collections, items, saved searches, Trash restore, library-wide tags, and batch operations. Every write passes a capability check, a session approval, and a plan-review card; a commit that cannot be verified reports "committed but unverified".
+  - Scholarly retrieval (`dsh-zotero/scholarly`): Seven tools cover arXiv, OpenAlex, Crossref, Semantic Scholar, PubMed, Europe PMC, and DBLP, fuse and deduplicate the results, and mark what the library already holds. They read open-access full text by DOI, arXiv ID, PMID, or PMCID, follow citation networks, fetch authoritative citations from the DOI registry, verify references and retraction status (verified, needs review, registry says none, or unverifiable), and save results into the personal library when you ask for it.
+  - Document parsing and semantic ranking (`dsh-zotero/enrichment`): Enabling the document parsing component accepts MinerU document egress for documents you submit yourself, and a parse still needs you to submit one specific Zotero PDF attachment or public PDF URL. Once it succeeds, ordinary reads and scholarly full-text reads reuse the Markdown artifact and keep its figures; the six semantic tiers can be downloaded, verified, and deleted here.
 
 For details on interaction patterns, UI roles, and runtime boundaries, see the [product model](docs/product-model.en.md).
 
@@ -50,7 +61,7 @@ For details on interaction patterns, UI roles, and runtime boundaries, see the [
 In the DeepSeek Harness desktop app, open **Plugins** in the sidebar, click **Add Plugin**, and enter the package identifier:
 
 - Latest version (recommended): `dsh-zotero`
-- Specific version: `dsh-zotero@0.14.1`
+- Specific version: `dsh-zotero@1.0.1`
 - GitHub prebuilt branch: `github:Vncntvx/dsh-zotero#release`
 
 ### Command line
@@ -68,7 +79,7 @@ dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 
 Start a new session after installation. Open the **dsh-zotero** detail page in the plugin manager; its configuration section carries the full configuration form.
 
-> Note: Installing directly from the `main` source branch needs a local build. pnpm blocks dependency builds by default, so use the `#release` branch to skip build configuration and install directly.
+> Note: installing directly from the `main` source branch needs a local `prepare` build plus an `allowBuilds` entry for `dsh-zotero` in the profile's `pnpm-workspace.yaml`; the `#release` branch or the npm package skips that step. Separately, npm, `#release`, and local tarball installs need a one-time approval for the transitive `protobufjs` install script on pnpm 11 — see [Getting Started](docs/getting-started.en.md).
 
 ## Prerequisites
 
@@ -112,7 +123,9 @@ When writing papers or organizing literature independently, use the **Literature
 
 ## Tools
 
-The plugin provides eight read tools and fifteen write tools. Write tools are off by default; turn on `writeEnabled` in configuration to enable them.
+The plugin registers 23 local tools (8 read + 15 write) and 7 scholarly retrieval tools. Local write tools are off by default; turn on `writeEnabled` in configuration to enable them. Scholarly tools become available when the `dsh-zotero/scholarly` component is enabled.
+
+### Local read tools (8)
 
 | Tool                      | Purpose                                                                                                   |
 | ------------------------- | --------------------------------------------------------------------------------------------------------- |
@@ -125,19 +138,31 @@ The plugin provides eight read tools and fifteen write tools. Write tools are of
 | `zotero_changes`          | Check recent additions, modifications, and deletions in the library                                       |
 | `zotero_export`           | Generate formatted citations or a bibliography, or export BibTeX, RIS, or CSL JSON                        |
 
-The fifteen write tools (notes, tags and collection membership, collections, items, saved searches, Trash restore, library-wide tags, and batch operations) are off by default. Once enabled they write only to the personal library, and every write needs approval. See the [tool reference](docs/tools.en.md) for the full contract of all 23 local tools.
+### Scholarly retrieval tools (7, optional component `dsh-zotero/scholarly`)
+
+| Tool                       | Purpose                                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `scholarly_search`         | Search across arXiv, OpenAlex, Crossref, S2, PubMed, Europe PMC, and DBLP with RRF fusion         |
+| `scholarly_get`            | Retrieve full bibliographic metadata and open-access PDF links for external papers                |
+| `scholarly_citations`      | Follow forward citation and backward reference networks                                           |
+| `scholarly_read`           | Open-access PDF reading and passage extraction (supports outline, section, and query modes)       |
+| `scholarly_cite`           | Fetch authoritative BibTeX, RIS, or formatted citations directly from DOI registration agencies   |
+| `scholarly_verify`         | Verify reference list authenticity, DOI matches, and retraction notices against Crossref          |
+| `scholarly_save_to_zotero` | Save externally retrieved papers to the personal Zotero library (write operation, needs approval) |
+
+The fifteen write tools (notes, tags and collection membership, collections, items, saved searches, Trash restore, library-wide tags, and batch operations) are off by default. Once enabled they write only to the personal library, and every write needs approval. See the [tool reference](docs/tools.en.md) for the full contract of all 23 local tools and 7 scholarly tools.
 
 ## Documentation
 
 ### Usage
 
-| Document                                      | Covers                                                                                                 |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| [Getting started](docs/getting-started.en.md) | Installation, connection verification, and the first task                                              |
-| [Product model](docs/product-model.en.md)     | Two entry points, two UI surfaces, component division, and system boundaries                           |
-| [Features](docs/features.en.md)               | Conversation capabilities, the literature trail, the literature panel, writes, and scholarly retrieval |
-| [Research SOP skills](docs/skills.en.md)      | Seven on-demand research workflows, batching budgets and evidence boundaries                           |
-| [Troubleshooting](docs/troubleshooting.en.md) | Common issues, diagnostic steps, and remedies                                                          |
+| Document                                      | Covers                                                                                                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [Getting started](docs/getting-started.en.md) | Installation, connection verification, and the first task                                                                |
+| [Product model](docs/product-model.en.md)     | Two entry points, two UI surfaces, component division, and system boundaries                                             |
+| [Features](docs/features.en.md)               | Conversation capabilities, the literature trail, the literature panel, writes, scholarly retrieval, and document parsing |
+| [Research SOP skills](docs/skills.en.md)      | Eight on-demand research workflows, batching budgets and evidence boundaries                                             |
+| [Troubleshooting](docs/troubleshooting.en.md) | Common issues, diagnostic steps, and remedies                                                                            |
 
 ### Maintenance
 

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version" style="max-width:100%;"></a>
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads" style="max-width:100%;"></a>
   <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/l/dsh-zotero" alt="license" style="max-width:100%;"></a>
-  <a href="https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.1"><img src="https://img.shields.io/badge/dsh-0.2.2--rc.1-blue" alt="dsh 版本" style="max-width:100%;"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.2"><img src="https://img.shields.io/badge/dsh-0.2.2--rc.2-blue" alt="dsh 版本" style="max-width:100%;"></a>
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
   <a href="https://github.com/hashgraph-online/hol-guard"><img src="https://img.shields.io/badge/HOL%20Guard-passing-00a67e" alt="HOL Guard Scanner"></a>
 </p>
@@ -27,19 +27,30 @@ dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。Agent 在对话
 
 ## 主要功能
 
-- **对话检索**
-  - 检索阅读：按标题、作者、年份或全文搜索文献，读取元数据、个人笔记与本地 PDF 全文。
-  - 原文定位：围绕具体问题从全文、批注和笔记中提取相关段落，PDF 批注附带原始页码。
-  - 引用导出：按 CSL 样式生成行内引用或参考文献表，支持导出 BibTeX、RIS 与 CSL-JSON。
-  - 写入扩展（可选）：开启后可创建笔记、修改标签与合集（每次均需会话审批）；启用学术检索组件后可跨 7 个外部索引检索文献并核验引用。
-- **文献轨迹**
-  - 检索记录：会话顶部首屏显示每次调用的查询词、范围、筛选条件与命中数。
-  - 原文核对：按文献条目整理提取出的段落与批注，标明出处与原始页码，方便核对。
-  - 导出汇总：跨条目汇总当前会话生成的所有引用与 BibTeX，自动去重，可直接复制或下载。
-- **文献面板**
-  - 全库浏览：在右侧边栏浏览 Zotero 合集树、标签、保存的搜索与回收站，支持多条件组合筛选。
-  - 详情与阅读：查看条目元数据、关联笔记与附件列表，支持在右侧阅读栏直接打开本地 PDF。
-  - 引用与联动：动作行直接复制 BibTeX、CSL 引用或条目信息；支持将选中文献一键填入对话输入框。
+Agent 在对话里用工具检索、阅读与引用文献；文献轨迹核对它在这个会话做过的事；文献面板由你独立翻阅整个库。
+
+- **对话**
+  - 检索与浏览：按标题、作者、年份、标签或全文检索，范围可限定全库、我的出版物、某个合集或某个保存的搜索；合集树、标签与保存的搜索可直接浏览；已知 ref 支持批量读取，每条结果单独报告。
+  - 原文定位：围绕具体问题从全文、笔记与批注中取回片段。每条片段标明来源，批注保留 Zotero 页码，结果同时报告全文覆盖度与被跳过的来源。
+  - 排序与命中：默认 BM25 词面排序；可选本地语义排序，六档本地嵌入模型在 CPU 上运行，结果与 BM25 经 RRF 融合，每条片段标注词法、语义或混合命中。一次最多给四种问法分别打分，每条片段取最高分；空结果会说明是没有词面重合，还是没有可用来源。
+  - 引用与导出：按 CSL 样式生成行内引用或合并参考文献表，导出 BibTeX、BibLaTeX、RIS 与 CSL-JSON，样式与语言沿用配置默认值。
+  - 对账与变更：用 DOI、BibTeX 键或文献字段与本地库对账，返回 ref、citekey、置信度与可审阅的字段差异；按库版本号报告新增、修改与删除，回收站单列。
+  - 研究 SOP：八个按需加载的分阶段流程，常驻提示词里只有名称与短描述，每个流程都带阶段预算与停止条件。核心组件带四个（单篇速读、证据比较、写作对账、文库治理），启用学术检索组件后另有四个（主题版图、引文脉络、真伪审查、文献入库）。
+- **文献轨迹（会话顶部）**
+  - 检索条件：按调用列出查询词、范围（库、我的出版物、合集、保存搜索）、模式（元数据或全文）、筛选条件与命中数，总数与笔记命中分开计。
+  - 原文核对：按条目聚合读过的片段与批注，带来源、页码与覆盖度；被拒绝或取消的调用同样记录。
+  - 导出汇总：跨条目汇总本轮生成的全部引用与 BibTeX，按格式分段、自动去重，可复制或下载；失败的导出单独列出。
+  - 长会话：历史窗口截断不影响早期条目；长列表分页，切换时直接读已有结果。
+- **文献面板（右侧边栏）**
+  - 浏览与筛选：多库切换、按需展开的合集树、保存的搜索、我的出版物与回收站；条目列表支持元数据与全文两种检索模式、多种排序，并能按类型、标签、年份、有无附件筛选。
+  - 详情与阅读：条目元数据、合集与标签、笔记/附件/批注三个子集合分别分页；本地 PDF 在右侧阅读栏打开，开启 `allowUrlPdfRead` 后也能读取库内已有的 URL 附件。
+  - 引用与联动：动作行复制引用、参考文献表或 BibTeX；选中文献可填入对话草稿；输入框的 Zotero 按钮与书目交付物都能直接打开面板。
+  - 状态恢复：按 Zotero 实例记住选中条目、当前分段与展开的合集分支，滚动位置与子条目分页一并保留。
+  - 解析结果：启用文档解析组件后，条目动作行可打开以论文标题命名的解析标签页（全文、插图、选段解释）；工具栏的「解析文档管理」页列出全部产物，支持筛选、逐行打开或重新解析，以及整页批量删除。
+- **可选能力（默认关闭）**
+  - 写入文献库：开启 `writeEnabled` 后注册 15 个只写个人库的工具，覆盖笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签与批量操作；每次写入都经过能力检查、会话审批与计划审查卡，提交结果未核验时显示「已提交未确认」。
+  - 学术检索（`dsh-zotero/scholarly`）：7 个工具覆盖 arXiv、OpenAlex、Crossref、Semantic Scholar、PubMed、Europe PMC 与 DBLP，结果融合去重并标出「已在本地库」。可按 DOI、arXiv ID、PMID、PMCID 读开放获取全文、追踪引文网络、从 DOI 注册中心取权威引用、核验参考文献与撤稿状态（分为已核实、需人工确认、注册表说没有、无法核验四种结论），并在你明确要求时保存进个人库。
+  - 文档解析与语义排序（`dsh-zotero/enrichment`）：启用即表示接受向 MinerU 外发你主动提交的文档；解析需要你针对一个具体的 Zotero PDF 附件或公开 PDF URL 显式提交，成功后普通检索与学术全文精读自动复用 Markdown 产物，插图一并保留；本地语义排序的六档模型可在这里下载、校验与删除。
 
 交互方式、界面分工与运行边界详见[产品模型](docs/product-model.md)。
 
@@ -50,7 +61,7 @@ dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。Agent 在对话
 在 DeepSeek Harness 桌面端打开侧栏的**插件**，点击**添加插件**，输入对应标识：
 
 - 最新版（推荐）：`dsh-zotero`
-- 指定版本：`dsh-zotero@0.14.1`
+- 指定版本：`dsh-zotero@1.0.1`
 - GitHub 预构建分支：`github:Vncntvx/dsh-zotero#release`
 
 ### 命令行安装
@@ -68,7 +79,7 @@ dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 
 安装完成后新建会话即可使用。在插件管理器中打开 **dsh-zotero** 详情页，其配置区提供完整配置表单。
 
-> 提示：从 `main` 源码分支直接安装需要本地执行构建。pnpm 默认拦截依赖构建，使用 `#release` 分支可免除构建配置直接安装。
+> 提示：从 `main` 源码分支直接安装需要本地执行 `prepare` 构建，并在 profile 的 `pnpm-workspace.yaml` 中允许 `dsh-zotero` 的构建脚本；改用 `#release` 分支或 npm 包可免除这一步。另外，npm、`#release` 与本地 tarball 安装在 pnpm 11 上需要一次性批准传递依赖 `protobufjs` 的安装脚本，详见[快速入门](docs/getting-started.md)。
 
 ## 前置条件
 
@@ -112,7 +123,9 @@ dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 
 ## 工具一览
 
-插件提供 8 个读取工具与 15 个写入工具。写入工具默认关闭，可在配置中开启 `writeEnabled`。
+插件注册 23 个本地工具（8 个读工具 + 15 个写工具）以及 7 个学术检索工具。本地写入工具默认关闭，可在配置中开启 `writeEnabled`；学术检索工具随 `dsh-zotero/scholarly` 组件启用。
+
+### 本地读取工具（8 个）
 
 | 工具                      | 用途                                                         |
 | ------------------------- | ------------------------------------------------------------ |
@@ -125,19 +138,31 @@ dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 | `zotero_changes`          | 检查文献库最近的新增、修改或删除记录                         |
 | `zotero_export`           | 生成格式化引用、参考文献列表，或导出 BibTeX、RIS、CSL JSON   |
 
-15 个写入工具（笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签、批量操作）默认关闭，开启后仅写入个人库，且每次写入都需要审批。全部 23 个本地工具的完整契约见[工具参考](docs/tools.md)。
+### 学术检索工具（7 个，可选组件 `dsh-zotero/scholarly`）
+
+| 工具                       | 用途                                                                      |
+| -------------------------- | ------------------------------------------------------------------------- |
+| `scholarly_search`         | 跨 arXiv、OpenAlex、Crossref、S2、PubMed、Europe PMC、DBLP 检索并融合去重 |
+| `scholarly_get`            | 获取外部文献元数据详情与开放获取全文直链                                  |
+| `scholarly_citations`      | 追踪论文的引用与被引网络                                                  |
+| `scholarly_read`           | 开放获取 PDF 全文精读与段落证据提取（支持 outline/section/query）         |
+| `scholarly_cite`           | 从 DOI 注册中心获取权威 BibTeX、RIS 与格式化引用                          |
+| `scholarly_verify`         | 对照 Crossref 官方数据库核验参考文献真实性与撤稿状态                      |
+| `scholarly_save_to_zotero` | 将外部检索到的文献保存至本地 Zotero 个人库（写操作，需审批）              |
+
+15 个写入工具（笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签、批量操作）默认关闭，开启后仅写入个人库，且每次写入都需要审批。全部 23 个本地工具与 7 个学术工具的完整契约见[工具参考](docs/tools.md)。
 
 ## 说明文档
 
 ### 使用
 
-| 文档                                | 内容                                         |
-| ----------------------------------- | -------------------------------------------- |
-| [快速入门](docs/getting-started.md) | 安装、连接验证与第一个任务                   |
-| [产品模型](docs/product-model.md)   | 两个入口、两大视图、组件分工与系统边界       |
-| [功能概览](docs/features.md)        | 对话能力、文献轨迹、文献面板、写入与学术检索 |
-| [研究 SOP 技能](docs/skills.md)     | 七个按需研究流程、批处理预算与证据边界       |
-| [故障排查](docs/troubleshooting.md) | 常见问题、诊断步骤与处理方法                 |
+| 文档                                | 内容                                                   |
+| ----------------------------------- | ------------------------------------------------------ |
+| [快速入门](docs/getting-started.md) | 安装、连接验证与第一个任务                             |
+| [产品模型](docs/product-model.md)   | 两个入口、两大视图、组件分工与系统边界                 |
+| [功能概览](docs/features.md)        | 对话能力、文献轨迹、文献面板、写入、学术检索与文档解析 |
+| [研究 SOP 技能](docs/skills.md)     | 八个按需研究流程、批处理预算与证据边界                 |
+| [故障排查](docs/troubleshooting.md) | 常见问题、诊断步骤与处理方法                           |
 
 ### 维护
 

package/cordis.patch.yml

@@ -15,7 +15,31 @@
     # It ships off. Its row's switch in the plugin manager's "Included
     # components" list is the only authorization: mounting the component
     # registers its seven tools and permits requests to the allowlisted
-    # external indexes.
+    # external indexes; the open-access PDF fulltext arm is the single
+    # allowlist exception and is guarded by the public-address gates.
     - id: scholarly
       name: dsh-zotero/scholarly
       disabled: true
+    # The enrichment component makes three independent capabilities available:
+    # user-submitted MinerU document parsing, read-only reuse of existing
+    # parsed artifacts, and local semantic passage ranking with its pinned
+    # embedding models. It ships off. Mounting the row registers no model
+    # tools and injects no prompt section. Enabling the component is the
+    # deployment's acceptance of document egress to MinerU; it starts no work.
+    # Ordinary reads use the core's read-only FulltextEnhancer.lookup slot to
+    # reuse valid Markdown for the same source; a miss continues through the
+    # existing Zotero fulltext index or authorized local PDF extraction. Only
+    # an explicit user submission of one specific Zotero PDF attachment or one
+    # public PDF URL starts a MinerU parse, with remote-action and session
+    # access checks. PDF opening, settings saves, and service startup never
+    # submit, resume, or upload a MinerU task.
+    # Local semantic ranking needs no MinerU call or upload permission. With
+    # semantic search enabled but its model missing, corrupt, or its runtime
+    # unavailable, a read fails explicitly with
+    # ZOTERO_ENRICHMENT_SEMANTIC_UNAVAILABLE; it never falls back to BM25.
+    # Model downloads are separate operations from the component's own service
+    # and vanish on unmount. No legacy component, config, cache-format, or
+    # interface aliases are provided.
+    - id: enrichment
+      name: dsh-zotero/enrichment
+      disabled: true

package/docs/plugin-detail.en.md

@@ -1,3 +1,4 @@
 - Core component (`dsh-zotero`): the local Zotero connection, 8 read tools and 15 write tools (off by default; once enabled, every write needs confirmation on the plan review card), the literature trail, and the settings page.
 - Literature panel (`dsh-zotero/library`): a right-sidebar tab covering whole-library navigation (collection tree, saved searches, My Publications, Trash), item list filters, item inspection, citation copying (CSL citation, BibTeX, bibliography, BibLaTeX, RIS, CSL-JSON, and item info), and approved controlled writes.
-- Scholarly search (`dsh-zotero/scholarly`): the external literature retrieval component, off by default; mounting the component is what authorizes requests to the external academic indexes. It covers arXiv, OpenAlex, Crossref, Semantic Scholar, PubMed, Europe PMC, and DBLP, with full-text reading, citation graphs, reference verification, and saving to Zotero.
+- Scholarly search (`dsh-zotero/scholarly`): the external literature retrieval component, off by default; mounting the component is what authorizes requests to the external academic indexes, and the client discloses the request scope while the component is served until this browser acknowledges the current enable; turning the component off and on again discloses again. It covers arXiv, OpenAlex, Crossref, Semantic Scholar, PubMed, Europe PMC, and DBLP, with full-text reading, citation graphs, reference verification, and saving to Zotero.
+- Document parsing (`dsh-zotero/enrichment`): optional and off by default; enabling it accepts MinerU document egress, and the client discloses it while the component is served until this browser acknowledges the current enable; turning the component off and on again discloses again. It provides explicit parsing, artifact reuse, and local semantic ranking / model management, and registers no model tools or prompt section. It supports token-free `free` and token-gated `pro` parsing, and saves Markdown artifacts to a configurable directory.

package/docs/plugin-detail.md

@@ -1,3 +1,4 @@
 - **核心组件**（`dsh-zotero`）：本机 Zotero 连接、8 个读工具与 15 个写工具（默认关闭，启用后每次写入都需在计划审查卡中确认）、文献轨迹与设置页。
 - **文献面板**（`dsh-zotero/library`）：右侧边栏标签页，覆盖全库导航（合集树、保存的搜索、我的出版物、回收站）、条目列表筛选、条目检视、复制引用（CSL 引文、BibTeX、参考文献表、BibLaTeX、RIS、CSL-JSON 与条目信息）以及经审批的受控写入。
-- **学术检索**（`dsh-zotero/scholarly`）：外部文献检索组件，默认关闭；组件挂载即授权对外部学术索引的请求。覆盖 arXiv、OpenAlex、Crossref、Semantic Scholar、PubMed、Europe PMC 与 DBLP，支持全文读取、引文网络、参考文献核验与保存到 Zotero。
+- **学术检索**（`dsh-zotero/scholarly`）：外部文献检索组件，默认关闭；组件挂载即授权对外部学术索引的请求，客户端在组件处于已启用状态且本机尚未确认时提示请求范围，确认只覆盖当前这次启用，组件关闭后再启用会重新提示。覆盖 arXiv、OpenAlex、Crossref、Semantic Scholar、PubMed、Europe PMC 与 DBLP，支持全文读取、引文网络、参考文献核验与保存到 Zotero。
+- **文档解析**（`dsh-zotero/enrichment`）：可选组件，默认关闭；启用即接受 MinerU 文档外发；客户端在组件处于已启用状态且本机尚未确认时提示外发范围，确认只覆盖当前这次启用，组件关闭后再启用会重新提示。提供主动解析、已有产物复用和本地语义检索 / 模型管理，不注册模型工具或提示词段。支持免 Token 的 `free` 和需 Token 的 `pro`，Markdown 产物保存到可配置目录。

package/lib/artifact-images.d.ts

@@ -0,0 +1,10 @@
+/** Canonical names and media types shared by extraction, persistence and wire codecs. */
+import type { ZoteroArtifactImageMediaType } from './contract.js';
+export declare const ARTIFACT_IMAGE_NAME_PATTERN: RegExp;
+/** Resolve a Markdown destination without admitting nested or encoded escaping paths. */
+export declare function artifactImageName(destination: string): string | undefined;
+export declare function artifactImageMediaType(name: string): ZoteroArtifactImageMediaType | undefined;
+export declare const ARCHIVE_MAX_IMAGES = 512;
+export declare const ARCHIVE_MAX_IMAGE_BYTES: number;
+export declare const ARCHIVE_MAX_IMAGE_TOTAL_BYTES: number;
+//# sourceMappingURL=artifact-images.d.ts.map

package/lib/artifact-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-images.d.ts","sourceRoot":"","sources":["../src/artifact-images.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAEjE,eAAO,MAAM,2BAA2B,QACmC,CAAA;AAW3E,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQzE;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,4BAA4B,GAAG,SAAS,CAI7F;AAED,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,uBAAuB,QAAkB,CAAA;AACtD,eAAO,MAAM,6BAA6B,QAAoB,CAAA"}

package/lib/artifact-images.js

@@ -0,0 +1,29 @@
+export const ARTIFACT_IMAGE_NAME_PATTERN = /^images\/[A-Za-z0-9][A-Za-z0-9._-]{0,110}\.(?:png|jpe?g|gif|webp|bmp)$/u;
+const MEDIA_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    bmp: 'image/bmp',
+};
+/** Resolve a Markdown destination without admitting nested or encoded escaping paths. */
+export function artifactImageName(destination) {
+    let name;
+    try {
+        name = decodeURIComponent(destination).replace(/^\.\//u, '');
+    }
+    catch {
+        return undefined;
+    }
+    return ARTIFACT_IMAGE_NAME_PATTERN.test(name) ? name : undefined;
+}
+export function artifactImageMediaType(name) {
+    return ARTIFACT_IMAGE_NAME_PATTERN.test(name)
+        ? MEDIA_TYPES[name.slice(name.lastIndexOf('.') + 1)]
+        : undefined;
+}
+export const ARCHIVE_MAX_IMAGES = 512;
+export const ARCHIVE_MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+export const ARCHIVE_MAX_IMAGE_TOTAL_BYTES = 128 * 1024 * 1024;
+//# sourceMappingURL=artifact-images.js.map

package/lib/artifact-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-images.js","sourceRoot":"","sources":["../src/artifact-images.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,2BAA2B,GACtC,yEAAyE,CAAA;AAE3E,MAAM,WAAW,GAA2D;IAC1E,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;CACjB,CAAA;AAED,yFAAyF;AACzF,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAClE,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3C,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AACrC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AACtD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA"}

package/lib/artifact-reader-preferences.d.ts

@@ -0,0 +1,14 @@
+/** Deployment limits for complete parsed-document preparation. */
+export interface ArtifactReaderPreferences {
+    readonly maxOpen: number;
+    readonly maxBytes: number;
+    readonly preparedMaxBytes: number;
+    readonly idleTimeoutMs: number;
+    readonly maxLifetimeMs: number;
+    readonly concurrency: number;
+    readonly archiveConcurrency: number;
+    readonly archiveQueueLimit: number;
+}
+export declare const ARTIFACT_READER_DEFAULTS: ArtifactReaderPreferences;
+export declare function artifactReaderPreferencesOf(value: unknown): ArtifactReaderPreferences;
+//# sourceMappingURL=artifact-reader-preferences.d.ts.map

package/lib/artifact-reader-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-reader-preferences.d.ts","sourceRoot":"","sources":["../src/artifact-reader-preferences.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC;AAED,eAAO,MAAM,wBAAwB,EAAE,yBASrC,CAAA;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,CAcrF"}

package/lib/artifact-reader-preferences.js

@@ -0,0 +1,28 @@
+export const ARTIFACT_READER_DEFAULTS = Object.freeze({
+    maxOpen: 8,
+    maxBytes: 256 * 1024 * 1024,
+    preparedMaxBytes: 512 * 1024 * 1024,
+    idleTimeoutMs: 120_000,
+    maxLifetimeMs: 600_000,
+    concurrency: 4,
+    archiveConcurrency: 2,
+    archiveQueueLimit: 8,
+});
+export function artifactReaderPreferencesOf(value) {
+    if (value === undefined)
+        return ARTIFACT_READER_DEFAULTS;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid artifact reader limits');
+    const input = value;
+    const result = { ...ARTIFACT_READER_DEFAULTS };
+    for (const key of Object.keys(input)) {
+        if (!Object.hasOwn(result, key))
+            throw new Error(`Unknown artifact reader limit: ${key}`);
+        const number = input[key];
+        if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < 1)
+            throw new Error(`Invalid artifact reader limit: ${key}`);
+        result[key] = number;
+    }
+    return Object.freeze(result);
+}
+//# sourceMappingURL=artifact-reader-preferences.js.map

package/lib/artifact-reader-preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-reader-preferences.js","sourceRoot":"","sources":["../src/artifact-reader-preferences.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,wBAAwB,GAA8B,MAAM,CAAC,MAAM,CAAC;IAC/E,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAC3B,gBAAgB,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IACnC,aAAa,EAAE,OAAO;IACtB,aAAa,EAAE,OAAO;IACtB,WAAW,EAAE,CAAC;IACd,kBAAkB,EAAE,CAAC;IACrB,iBAAiB,EAAE,CAAC;CACrB,CAAC,CAAA;AAEF,MAAM,UAAU,2BAA2B,CAAC,KAAc;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,wBAAwB,CAAA;IACxD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IACnD,MAAM,KAAK,GAAG,KAAgC,CAAA;IAC9C,MAAM,MAAM,GAAG,EAAE,GAAG,wBAAwB,EAAE,CAAA;IAC9C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,EAAE,CAAC,CAAA;QACzF,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;QACzB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,EAAE,CAAC,CAAA;QAC1D,MAAM,CAAC,GAAsC,CAAC,GAAG,MAAM,CAAA;IACzD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC"}

package/lib/browse-rows.d.ts

@@ -29,13 +29,13 @@ import type { ZoteroBrowseKind } from './types.js';
  * `src/tools/browse.ts`, `browseRowView` in the Chat card) have no `default` arm,
  * so an arm with no renderer fails to build.
  */
-export declare const BROWSE_ROW_ARMS: readonly ["library", "collection", "savedSearch", "tag", "itemType", "field", "creatorType"];
+export declare const BROWSE_ROW_ARMS: readonly ['library', 'collection', 'savedSearch', 'tag', 'itemType', 'field', 'creatorType'];
 /**
  * Browse listing kinds (`zotero_browse`'s `kind`), as a runtime list both
  * halves share. The type authority stays `ZoteroBrowseKind` in `types.ts`; the
  * `Exclude` pin below fails the build if this list falls behind it.
  */
-export declare const BROWSE_KINDS: readonly ["libraries", "collections", "savedSearches", "tags", "itemTypes", "itemFields"];
+export declare const BROWSE_KINDS: readonly ['libraries', 'collections', 'savedSearches', 'tags', 'itemTypes', 'itemFields'];
 /** Runtime membership test for a browse kind string. */
 export declare function isBrowseKind(value: string | undefined): value is ZoteroBrowseKind;
 /** One classified browse row. Which arm a row lands in says which field identified it. */

package/lib/browse-rows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browse-rows.d.ts","sourceRoot":"","sources":["../src/browse-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,8FAQlB,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,YAAY,2FAOf,CAAA;AAMV,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,IAAI,gBAAgB,CAEjF;AAeD,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GACjB;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,CAAA;AAUL;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAiDrD"}
+{"version":3,"file":"browse-rows.d.ts","sourceRoot":"","sources":["../src/browse-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,YAC1B,SAAS,EACT,YAAY,EACZ,aAAa,EACb,KAAK,EACL,UAAU,EACV,OAAO,EACP,aAAa,CACL,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,YAAY,YACvB,WAAW,EACX,aAAa,EACb,eAAe,EACf,MAAM,EACN,WAAW,EACX,YAAY,CACJ,CAAA;AAMV,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,IAAI,gBAAgB,CAEjF;AAeD,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GACjB;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,CAAA;AAUL;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAiDrD"}

package/lib/cause-chain.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounded walk of an error's cause chain.
+ *
+ * `Error.cause` and `AggregateError.errors` can nest, cycle, and fan out. Both
+ * `errnoCodeOf` (`errors.ts`) and the public-address rejection lookup
+ * (`public-url.ts`) need the same walk, so the bound lives here once: a node
+ * budget, a separate chain-depth budget for `cause` links, and a fan-out cap
+ * for aggregate members. A `seen` set makes a cyclic cause harmless.
+ * @module dsh-zotero/cause-chain
+ */
+/**
+ * Walk the cause chain breadth-first and return the first value a visitor
+ * accepts. A visitor returns `undefined` to keep walking; any other value ends
+ * the walk, so a caller that wants a boolean produces `true` explicitly.
+ * @param error - any thrown value.
+ * @param visit - classify one node; `undefined` means "keep looking".
+ * @returns the accepted value, or undefined when the bounded walk ends.
+ */
+export declare function findInCauseChain<T>(error: unknown, visit: (current: object) => T | undefined): T | undefined;
+//# sourceMappingURL=cause-chain.d.ts.map

package/lib/cause-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cause-chain.d.ts","sourceRoot":"","sources":["../src/cause-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,GACxC,CAAC,GAAG,SAAS,CAyBf"}

package/lib/cause-chain.js

@@ -0,0 +1,52 @@
+/**
+ * Bounded walk of an error's cause chain.
+ *
+ * `Error.cause` and `AggregateError.errors` can nest, cycle, and fan out. Both
+ * `errnoCodeOf` (`errors.ts`) and the public-address rejection lookup
+ * (`public-url.ts`) need the same walk, so the bound lives here once: a node
+ * budget, a separate chain-depth budget for `cause` links, and a fan-out cap
+ * for aggregate members. A `seen` set makes a cyclic cause harmless.
+ * @module dsh-zotero/cause-chain
+ */
+/** How many nodes, cause links, and aggregate members one walk may visit. */
+const MAX_NODES = 64;
+const MAX_CAUSE_DEPTH = 10;
+const MAX_AGGREGATE_MEMBERS = 32;
+/**
+ * Walk the cause chain breadth-first and return the first value a visitor
+ * accepts. A visitor returns `undefined` to keep walking; any other value ends
+ * the walk, so a caller that wants a boolean produces `true` explicitly.
+ * @param error - any thrown value.
+ * @param visit - classify one node; `undefined` means "keep looking".
+ * @returns the accepted value, or undefined when the bounded walk ends.
+ */
+export function findInCauseChain(error, visit) {
+    const seen = new Set();
+    const queue = [{ value: error, depth: 0 }];
+    let visited = 0;
+    while (queue.length > 0 && visited < MAX_NODES) {
+        const entry = queue.shift();
+        if (entry === undefined)
+            break;
+        const current = entry.value;
+        if (typeof current !== 'object' || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        visited += 1;
+        const found = visit(current);
+        if (found !== undefined)
+            return found;
+        if (entry.depth < MAX_CAUSE_DEPTH) {
+            if (current instanceof Error && current.cause !== undefined) {
+                queue.push({ value: current.cause, depth: entry.depth + 1 });
+            }
+            if (current instanceof AggregateError) {
+                for (const member of current.errors.slice(0, MAX_AGGREGATE_MEMBERS)) {
+                    queue.push({ value: member, depth: entry.depth + 1 });
+                }
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=cause-chain.js.map

package/lib/cause-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cause-chain.js","sourceRoot":"","sources":["../src/cause-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6EAA6E;AAC7E,MAAM,SAAS,GAAG,EAAE,CAAA;AACpB,MAAM,eAAe,GAAG,EAAE,CAAA;AAC1B,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAOhC;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,KAAyC;IAEzC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,KAAK,GAAiB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;IACxD,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,GAAG,SAAS,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAA;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAK;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAA;QAC3B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAQ;QAClF,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACjB,OAAO,IAAI,CAAC,CAAA;QACZ,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAA;QAC5B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACrC,IAAI,KAAK,CAAC,KAAK,GAAG,eAAe,EAAE,CAAC;YAClC,IAAI,OAAO,YAAY,KAAK,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAA;YAC9D,CAAC;YACD,IAAI,OAAO,YAAY,cAAc,EAAE,CAAC;gBACtC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,EAAE,CAAC;oBACpE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAA;gBACvD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/lib/changes-contract.d.ts

@@ -1,41 +1,41 @@
 /** Shared pure wire descriptors for the `zotero_changes` projection. */
 export declare const CHANGE_SECTIONS: readonly [{
-    readonly key: "items";
-    readonly label: "toolChangesItems";
+    readonly key: 'items';
+    readonly label: 'toolChangesItems';
 }, {
-    readonly key: "childItems";
-    readonly label: "toolChangesChildItems";
+    readonly key: 'childItems';
+    readonly label: 'toolChangesChildItems';
 }, {
-    readonly key: "trashedItems";
-    readonly label: "toolChangesTrashedItems";
+    readonly key: 'trashedItems';
+    readonly label: 'toolChangesTrashedItems';
 }, {
-    readonly key: "collections";
-    readonly label: "toolChangesCollections";
+    readonly key: 'collections';
+    readonly label: 'toolChangesCollections';
 }, {
-    readonly key: "savedSearches";
-    readonly label: "toolChangesSavedSearches";
+    readonly key: 'savedSearches';
+    readonly label: 'toolChangesSavedSearches';
 }, {
-    readonly key: "fulltextAttachments";
-    readonly label: "toolChangesFulltext";
+    readonly key: 'fulltextAttachments';
+    readonly label: 'toolChangesFulltext';
 }];
 export declare const DELETION_SECTIONS: readonly [{
-    readonly key: "items";
-    readonly label: "toolDeletedItems";
-    readonly totalKey: "deletedItems";
+    readonly key: 'items';
+    readonly label: 'toolDeletedItems';
+    readonly totalKey: 'deletedItems';
 }, {
-    readonly key: "collections";
-    readonly label: "toolDeletedCollections";
-    readonly totalKey: "deletedCollections";
+    readonly key: 'collections';
+    readonly label: 'toolDeletedCollections';
+    readonly totalKey: 'deletedCollections';
 }, {
-    readonly key: "savedSearches";
-    readonly label: "toolDeletedSavedSearches";
-    readonly totalKey: "deletedSavedSearches";
+    readonly key: 'savedSearches';
+    readonly label: 'toolDeletedSavedSearches';
+    readonly totalKey: 'deletedSavedSearches';
 }, {
-    readonly key: "tags";
-    readonly label: "toolDeletedTags";
-    readonly totalKey: "deletedTags";
+    readonly key: 'tags';
+    readonly label: 'toolDeletedTags';
+    readonly totalKey: 'deletedTags';
 }];
-export declare const DELETED_OTHER_TOTAL_KEY: "deletedOther";
+export declare const DELETED_OTHER_TOTAL_KEY: 'deletedOther';
 export type ChangeSectionKey = (typeof CHANGE_SECTIONS)[number]['key'];
 export type DeletionSectionKey = (typeof DELETION_SECTIONS)[number]['key'];
 export type ChangeTotalKey = ChangeSectionKey | (typeof DELETION_SECTIONS)[number]['totalKey'] | typeof DELETED_OTHER_TOTAL_KEY;