dsh-zotero 0.14.1 → 1.0.0

package/README.en.md

@@ -3,7 +3,7 @@
 # dsh-zotero
 
 <img
-  src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=18&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Search%2C+read%2C+and+cite+papers+from+local+Zotero."
+  src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=18&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Search%2C+read%2C+and+trace+citations+from+local+Zotero.%3B%3E+Audit+every+source+and+passage+in+the+Literature+Trail.%3B%3E+Browse+collections+and+cite+instantly+in+the+Literature+Panel."
   alt="dsh-zotero"
 />
 <p align="center">
@@ -11,8 +11,9 @@
   <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.1-rc.3"><img src="https://img.shields.io/badge/dsh-0.2.1--rc.3-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.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://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>
 </div>
 
@@ -40,19 +41,28 @@ All operations interact with Zotero through its local API (`127.0.0.1:23119`). R
   - 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.
 
-See the [product model](docs/product-model.en.md) for how the two entry points and three components divide the work.
+For details on interaction patterns, UI roles, and runtime boundaries, see the [product model](docs/product-model.en.md).
 
 ## Install
 
-From npm (recommended):
+### Desktop app (Plugin Manager)
+
+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`
+- GitHub prebuilt branch: `github:Vncntvx/dsh-zotero#release`
+
+### Command line
 
 ```sh
+# Install latest from npm (recommended)
 dsh plugin --profile <name> add dsh-zotero
-```
 
-From GitHub prebuilt branch:
+# Install a specific version
+dsh plugin --profile <name> add dsh-zotero@<version>
 
-```sh
+# Install from GitHub prebuilt branch
 dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 ```
 
@@ -65,50 +75,57 @@ Start a new session after installation. Open the **dsh-zotero** detail page in t
 1. Zotero 7 or newer desktop app installed (writes require Zotero 10).
 2. Enable the local API in Zotero: **Settings → Advanced → check "Allow other applications on this computer to communicate with Zotero"**.
 
-## Usage example
+## Usage examples
 
-Search first, then check:
+### 1. Research and trace citations in conversation
 
-```text
-User: Find papers about Risk
-Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
-       Returns 5 matches; the literature trail at the top of the session shows the same 5 papers
+Ask questions about your research topics directly in chat. The agent automatically retrieves items from your local Zotero library, reads full texts, and extracts passages with original page numbers:
 
-User: Find the methodology discussion in this paper
-Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology",
-                        sources: ["annotation", "fulltext"])
-       Returns ranked passages with source labels (annotations carry original page numbers)
+- **Literature search & QA**: Ask the agent about a research direction; the agent searches your local library and synthesizes answers using abstracts and metadata.
+  ```text
+  Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
+  ```
+- **Locate original passages**: Ask deeper questions about paper details; the agent extracts relevant passages from local PDF full text and annotations, with original page numbers attached.
+  ```text
+  Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology", sources: ["annotation", "fulltext"])
+  ```
+- **Generate formatted citations**: Ask for formatted outputs; the agent generates BibTeX entries or CSL citations in your requested style.
+  ```text
+  Agent → zotero_export(refs: ["zotero://user/0/item/ABCD1234"], format: "bibtex")
+  ```
 
-User: Export these three as BibTeX
-Agent → zotero_export(refs: [...], format: "bibtex")
-       Generates BibTeX entries, which can be copied or downloaded from the exports view
-       of the literature trail
-```
+### 2. Verify sources and export in the literature trail
 
-To use the literature while writing: find an item in the literature panel, click "Copy citation" or "Copy BibTeX" in the action row, and paste the citation text or entry into your paper's source file. To bring the agent in, click "Ask" or "Add to chat"; the content is prefilled into the session draft.
+After a conversation, click the **Literature Trail** tab at the top of the session to inspect and verify all references used in that session:
 
-## Tools
+- **Review search criteria**: The overview screen displays every query term, search scope (whole library, collection, or saved search), filter conditions, and hit count invoked during the session.
+- **Inspect sources item by item**: Check extracted passages against original page numbers and annotations in the item inspector to ensure every cited point is grounded in the source.
+- **Deduplicated export aggregation**: Review all citations and BibTeX entries produced during the session in the Export view, automatically deduplicated across items and ready for one-click copying or downloading.
 
-The plugin provides eight read tools and fifteen write tools. Write tools are off by default; turn on `writeEnabled` in configuration to enable them.
+### 3. Browse, read, and cite in the literature panel
+
+When writing papers or organizing literature independently, use the **Literature Panel** in the right sidebar without going through chat:
+
+- **Independent browsing & filtering**: Browse the collection tree, tag system, saved searches, and Trash, with combined filtering by publication year and item type.
+- **Inspect details & read PDFs**: Click any item to inspect metadata and associated notes, or open the local PDF directly in the reading pane.
+- **Instant citations & chat handoff**: Click "Copy BibTeX" or "Copy citation" in the action row to paste directly into your manuscript; click "Ask" or "Add to chat" to send selected references into the chat draft for targeted discussions.
 
-| Tool                | Purpose                                                                                                            |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `zotero_search`     | Search papers by title, author, year, tag, or full text, with collection and tag filters                           |
-| `zotero_browse`     | Browse the library structure, including the collection tree, tag list, and saved searches                          |
-| `zotero_get`        | Read the metadata detail, abstract, attachments, and note list of a single paper                                   |
-| `zotero_children`   | View the child items associated with a paper, including standalone notes, PDF attachments, and reading annotations |
-| `zotero_retrieve`   | Find passages relevant to a question in full text, notes, and annotations (annotations keep page numbers)          |
-| `zotero_changes`    | Check recent additions, modifications, and deletions in the library                                                |
-| `zotero_attachment` | Get the local PDF file path associated with a paper                                                                |
-| `zotero_export`     | Generate formatted citations or a bibliography, or export BibTeX, RIS, or CSL JSON                                 |
+## Tools
 
-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 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.
 
-## Security and privacy
+| Tool                      | Purpose                                                                                                   |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `zotero_search`           | Search papers by title, author, year, tag, or full text, with collection and tag filters                  |
+| `zotero_browse`           | Browse the library structure, including the collection tree, tag list, and saved searches                 |
+| `zotero_get`              | Read the metadata detail, abstract, attachments, and note list of a single paper                          |
+| `zotero_get_batch`        | Read known paper refs in order and report each result independently                                       |
+| `zotero_match_references` | Reconcile DOI, BibTeX, and reference fields against local items                                           |
+| `zotero_retrieve`         | Find passages relevant to a question in full text, notes, and annotations (annotations keep page numbers) |
+| `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 plugin sends requests only to the local Zotero API and does not call Zotero cloud services. External requests come only from the scholarly retrieval component, which is off by default.
-- Write tools are disabled by default. Once enabled, every library modification shows an approval and plan review card and runs only after the user confirms it. Writes are not retried automatically.
-- The plugin only resolves and validates local attachment paths. It runs no system commands and starts no background resident process.
+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.
 
 ## Documentation
 
@@ -117,8 +134,9 @@ The fifteen write tools (notes, tags and collection membership, collections, ite
 | 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, three concepts, three components, and four boundaries                                |
+| [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                                                          |
 
 ### Maintenance
@@ -130,8 +148,6 @@ The fifteen write tools (notes, tags and collection membership, collections, ite
 | [Configuration reference](docs/configuration.en.md) | Fields, defaults, and hot-reload behavior of each settings namespace                    |
 | [Development guide](docs/development.en.md)         | Build, test, debug, and release workflow                                                |
 
-The acceptance scenarios ([docs/scenarios.en.md](docs/scenarios.en.md)) are for maintainers.
-
 ## License
 
-[MIT](./LICENSE)
+This project is licensed under the [MIT License](./LICENSE).

package/README.md

@@ -3,7 +3,7 @@
 # dsh-zotero
 
 <img
-  src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=20&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Search%2C+read%2C+and+cite+papers+from+local+Zotero."
+  src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=18&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Search%2C+read%2C+and+trace+citations+from+local+Zotero.%3B%3E+Audit+every+source+and+passage+in+the+Literature+Trail.%3B%3E+Browse+collections+and+cite+instantly+in+the+Literature+Panel."
   alt="dsh-zotero"
 />
 <p align="center">
@@ -11,8 +11,9 @@
   <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.1-rc.3"><img src="https://img.shields.io/badge/dsh-0.2.1--rc.3-blue" alt="dsh 版本" 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://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>
 </div>
 
@@ -20,39 +21,48 @@
   <a href="README.en.md"><b>English</b></a> · <b>中文</b>
 </p>
 
-dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。Agent 在对话里检索、阅读、引用并按需修改文献库；你在文献面板里浏览整个库并复制引用；文献轨迹则集中展示 Agent 在当前会话中查到的文献、提取的原文片段与导出内容，方便对照核对。
+dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。Agent 在对话里检索、阅读、引用并按需修改文献库；你在文献面板里浏览整个库并复制引用；文献轨迹展示 Agent 在当前会话中查到的文献、原文片段与导出内容，方便核对。
 
 所有操作均通过 Zotero 本地 API（`127.0.0.1:23119`）与桌面端交互，读取无需配置 API Key。
 
 ## 主要功能
 
 - **对话检索**
-  - 检索与阅读：按标题、作者、年份或全文搜索文献，读取元数据、个人笔记与本地 PDF 全文。
-  - 原文片段定位：围绕具体问题从全文、批注和笔记中提取相关段落，PDF 批注附带原始页码。
-  - 引用与导出：按 CSL 样式生成行内引用或参考文献表，支持导出 BibTeX、RIS 与 CSL-JSON。
-  - 写入与扩展（可选）：开启后可创建笔记、修改标签与合集（每次均需会话审批）；启用学术检索组件后可跨 7 个外部索引检索文献并核验引用。
+  - 检索阅读：按标题、作者、年份或全文搜索文献，读取元数据、个人笔记与本地 PDF 全文。
+  - 原文定位：围绕具体问题从全文、批注和笔记中提取相关段落，PDF 批注附带原始页码。
+  - 引用导出：按 CSL 样式生成行内引用或参考文献表，支持导出 BibTeX、RIS 与 CSL-JSON。
+  - 写入扩展（可选）：开启后可创建笔记、修改标签与合集（每次均需会话审批）；启用学术检索组件后可跨 7 个外部索引检索文献并核验引用。
 - **文献轨迹**
   - 检索记录：会话顶部首屏显示每次调用的查询词、范围、筛选条件与命中数。
   - 原文核对：按文献条目整理提取出的段落与批注，标明出处与原始页码，方便核对。
   - 导出汇总：跨条目汇总当前会话生成的所有引用与 BibTeX，自动去重，可直接复制或下载。
 - **文献面板**
-  - 全库浏览：在右侧边栏浏览合集树、标签、保存的搜索与回收站，支持多条件组合筛选。
+  - 全库浏览：在右侧边栏浏览 Zotero 合集树、标签、保存的搜索与回收站，支持多条件组合筛选。
   - 详情与阅读：查看条目元数据、关联笔记与附件列表，支持在右侧阅读栏直接打开本地 PDF。
   - 引用与联动：动作行直接复制 BibTeX、CSL 引用或条目信息；支持将选中文献一键填入对话输入框。
 
-两个入口与三个组件的分工见[产品模型](docs/product-model.md)。
+交互方式、界面分工与运行边界详见[产品模型](docs/product-model.md)。
 
 ## 安装
 
-从 npm 安装（推荐）：
+### 桌面端安装（插件管理器）
+
+在 DeepSeek Harness 桌面端打开侧栏的**插件**，点击**添加插件**，输入对应标识：
+
+- 最新版（推荐）：`dsh-zotero`
+- 指定版本：`dsh-zotero@0.14.1`
+- GitHub 预构建分支：`github:Vncntvx/dsh-zotero#release`
+
+### 命令行安装
 
 ```sh
+# npm 安装最新版（推荐）
 dsh plugin --profile <name> add dsh-zotero
-```
 
-从 GitHub 预构建分支安装：
+# 安装指定版本
+dsh plugin --profile <name> add dsh-zotero@<version>
 
-```sh
+# 从 GitHub 预构建分支安装
 dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 ```
 
@@ -67,47 +77,55 @@ dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release
 
 ## 使用示例
 
-先检索，再核对：
+### 1. 在对话中研读与定位出处
 
-```text
-用户：帮我找 Risk 相关的论文
-Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
-       返回 5 篇匹配结果；会话顶部的文献轨迹同步出现这 5 篇
+在日常会话中直接围绕研究问题提问，Agent 会自动调取本地文献库检索、精读全文并抓取带页码的原文段落：
 
-用户：这篇里关于方法论的讨论，帮我找出来
-Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology",
-                        sources: ["annotation", "fulltext"])
-       返回排序段落与来源标注（批注附带原始页码）
+- **文献检索与问答**：向 Agent 询问某个研究方向，Agent 检索本地文献库，结合文献摘要与元数据生成回答。
+  ```text
+  Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
+  ```
+- **定位原文段落**：深入追问论文细节，Agent 从本地 PDF 全文与批注中提取相关段落，并附带原始页码标注。
+  ```text
+  Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology", sources: ["annotation", "fulltext"])
+  ```
+- **生成标准引用**：要求格式化输出时，Agent 直接生成 BibTeX 条目或指定样式的 CSL 引用。
+  ```text
+  Agent → zotero_export(refs: ["zotero://user/0/item/ABCD1234"], format: "bibtex")
+  ```
 
-用户：把这三篇导出为 BibTeX
-Agent → zotero_export(refs: [...], format: "bibtex")
-       生成 BibTeX 条目，可在文献轨迹的导出视图复制或下载
-```
+### 2. 在文献轨迹中核对出处与导出
 
-写论文时直接取用：在文献面板找到条目，动作行点「复制引用」或「复制 BibTeX」，把引用文本或词条粘贴到论文源文件中；需要 Agent 参与时点「提问」或「加入对话」，内容会预填进会话草稿。
+对话结束后，点击会话顶部的**文献轨迹**标签页，集中查看与核验本次对话调用的所有文献：
 
-## 工具一览
+- **查看检索条件**：首屏展示 Agent 在当前会话中每次调用的查询词、检索范围（全库/合集/保存搜索）、筛选条件与命中篇数。
+- **逐条核对出处**：在条目检查器中核对引用的原文段落，比对原始页码与批注，确认论据真实无误。
+- **去重汇总导出**：在「导出」视图中集中查看本轮会话生成的全部引用与 BibTeX，跨条目自动去重，支持一键批量复制或下载。
 
-插件提供 8 个读取工具与 15 个写入工具。写入工具默认关闭，可在配置中开启 `writeEnabled`。
+### 3. 在文献面板中自主查阅与即时引用
+
+写论文或独立整理文献时，直接在右侧边栏使用**「文献面板」**，无需通过 Agent 对话：
+
+- **自主翻阅与筛选**：浏览 Zotero 分类合集树、标签体系、保存的搜索与回收站，支持按年份与条目类型组合筛选。
+- **检视详情与阅读 PDF**：点击条目查看详细元数据与关联笔记，在右侧阅读栏直接打开本地 PDF。
+- **一键引用与对话联动**：在动作行点击「复制 BibTeX」或「复制引用」直接粘贴到论文源文件；点击「提问」或「加入对话」可将选中文献一键送入会话草稿，展开定向讨论。
 
-| 工具                | 用途                                                         |
-| ------------------- | ------------------------------------------------------------ |
-| `zotero_search`     | 按标题、作者、年份、标签或全文搜索文献，支持按分类与标签筛选 |
-| `zotero_browse`     | 浏览文献库结构，包括分类合集树、标签列表和保存的搜索         |
-| `zotero_get`        | 读取单篇文献的元数据详情、摘要、附件与笔记列表               |
-| `zotero_children`   | 查看文献关联的子条目，包括独立笔记、PDF 附件和阅读批注       |
-| `zotero_retrieve`   | 围绕问题从全文、笔记与批注中检索相关段落（批注保留页码）     |
-| `zotero_changes`    | 检查文献库最近的新增、修改或删除记录                         |
-| `zotero_attachment` | 获取文献关联的本地 PDF 文件路径                              |
-| `zotero_export`     | 生成格式化引用、参考文献列表，或导出 BibTeX、RIS、CSL JSON   |
+## 工具一览
 
-15 个写入工具（笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签、批量操作）默认关闭，开启后仅写入个人库，且每次写入都需要审批。全部 23 个工具的完整契约见[工具参考](docs/tools.md)。
+插件提供 8 个读取工具与 15 个写入工具。写入工具默认关闭，可在配置中开启 `writeEnabled`。
 
-## 安全与隐私
+| 工具                      | 用途                                                         |
+| ------------------------- | ------------------------------------------------------------ |
+| `zotero_search`           | 按标题、作者、年份、标签或全文搜索文献，支持按分类与标签筛选 |
+| `zotero_browse`           | 浏览文献库结构，包括分类合集树、标签列表和保存的搜索         |
+| `zotero_get`              | 读取单篇文献的元数据详情、摘要、附件与笔记列表               |
+| `zotero_get_batch`        | 按顺序批量读取已知文献 ref，逐条报告结果                     |
+| `zotero_match_references` | 将 DOI/BibTeX/文献字段与本地条目对账                         |
+| `zotero_retrieve`         | 围绕问题从全文、笔记与批注中检索相关段落（批注保留页码）     |
+| `zotero_changes`          | 检查文献库最近的新增、修改或删除记录                         |
+| `zotero_export`           | 生成格式化引用、参考文献列表，或导出 BibTeX、RIS、CSL JSON   |
 
-- 插件只向本机 Zotero 接口发请求，不调用 Zotero 云端服务。外部请求只来自默认关闭的学术检索组件。
-- 写入工具默认禁用。开启后每次修改文献库都会展示审批与计划审查卡，用户确认后才执行；写入不自动重试。
-- 插件只解析和校验本地附件路径，不执行系统命令，也不启动后台常驻进程。
+15 个写入工具（笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签、批量操作）默认关闭，开启后仅写入个人库，且每次写入都需要审批。全部 23 个本地工具的完整契约见[工具参考](docs/tools.md)。
 
 ## 说明文档
 
@@ -116,8 +134,9 @@ Agent → zotero_export(refs: [...], format: "bibtex")
 | 文档                                | 内容                                         |
 | ----------------------------------- | -------------------------------------------- |
 | [快速入门](docs/getting-started.md) | 安装、连接验证与第一个任务                   |
-| [产品模型](docs/product-model.md)   | 两个入口、三个概念、三个组件与四条边界       |
+| [产品模型](docs/product-model.md)   | 两个入口、两大视图、组件分工与系统边界       |
 | [功能概览](docs/features.md)        | 对话能力、文献轨迹、文献面板、写入与学术检索 |
+| [研究 SOP 技能](docs/skills.md)     | 七个按需研究流程、批处理预算与证据边界       |
 | [故障排查](docs/troubleshooting.md) | 常见问题、诊断步骤与处理方法                 |
 
 ### 维护
@@ -129,8 +148,6 @@ Agent → zotero_export(refs: [...], format: "bibtex")
 | [配置参考](docs/configuration.md) | 各设置命名空间的字段、默认值与热更新机制           |
 | [开发指南](docs/development.md)   | 构建、测试、调试与发布流程                         |
 
-验收场景（[docs/scenarios.md](docs/scenarios.md)）供维护者使用。
-
 ## 许可证
 
-[MIT](./LICENSE)
+本项目遵循 [MIT 许可证](./LICENSE)。

package/lib/citation-key.d.ts

@@ -0,0 +1,18 @@
+/** Structured citation-key facts shared by search, detail, and export views. */
+export type CitationKeySource = 'native' | 'extra';
+export interface CitationKeyConflict {
+    readonly native: string;
+    readonly extra: string;
+}
+export interface CitationKeyInfo {
+    readonly citationKey?: string;
+    readonly citationKeySource?: CitationKeySource;
+    readonly citationKeyConflict?: CitationKeyConflict;
+}
+/** Parse the citekey convention used by Better BibTeX and legacy exports. */
+export declare function citekeyOf(extra?: string): string | undefined;
+/** Resolve Zotero's native field first, while retaining an explicit conflict. */
+export declare function citationKeyInfoOf(data: Record<string, unknown> | undefined): CitationKeyInfo;
+/** Format a citation-key conflict as `native=<native>; extra=<extra>`. */
+export declare function formatCitationKeyConflict(conflict: CitationKeyConflict): string;
+//# sourceMappingURL=citation-key.d.ts.map

package/lib/citation-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-key.d.ts","sourceRoot":"","sources":["../src/citation-key.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAA;AAElD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IAC9C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACnD;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5D;AAQD,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,eAAe,CAa5F;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAE/E"}

package/lib/citation-key.js

@@ -0,0 +1,34 @@
+/** Structured citation-key facts shared by search, detail, and export views. */
+/** Parse the citekey convention used by Better BibTeX and legacy exports. */
+export function citekeyOf(extra) {
+    if (typeof extra !== 'string' || extra === '')
+        return undefined;
+    const value = /(?<![A-Za-z0-9_])(?:Citation Key|citekey):\s*([^\r\n\s,]+)/i.exec(extra)?.[1];
+    return value !== undefined && value !== '' ? value : undefined;
+}
+function clean(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Resolve Zotero's native field first, while retaining an explicit conflict. */
+export function citationKeyInfoOf(data) {
+    const native = clean(data?.citationKey);
+    const extra = citekeyOf(clean(data?.extra));
+    if (native !== undefined) {
+        return {
+            citationKey: native,
+            citationKeySource: 'native',
+            ...(extra !== undefined && extra !== native
+                ? { citationKeyConflict: { native, extra } }
+                : {}),
+        };
+    }
+    return extra === undefined ? {} : { citationKey: extra, citationKeySource: 'extra' };
+}
+/** Format a citation-key conflict as `native=<native>; extra=<extra>`. */
+export function formatCitationKeyConflict(conflict) {
+    return `native=${conflict.native}; extra=${conflict.extra}`;
+}
+//# sourceMappingURL=citation-key.js.map

package/lib/citation-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-key.js","sourceRoot":"","sources":["../src/citation-key.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAehF,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IAC/D,MAAM,KAAK,GAAG,6DAA6D,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5F,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAChE,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAA;AAC7C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,IAAyC;IACzE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IACvC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO;YACL,WAAW,EAAE,MAAM;YACnB,iBAAiB,EAAE,QAAQ;YAC3B,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM;gBACzC,CAAC,CAAC,EAAE,mBAAmB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;gBAC5C,CAAC,CAAC,EAAE,CAAC;SACR,CAAA;IACH,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAA;AACtF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,yBAAyB,CAAC,QAA6B;IACrE,OAAO,UAAU,QAAQ,CAAC,MAAM,WAAW,QAAQ,CAAC,KAAK,EAAE,CAAA;AAC7D,CAAC"}