release: v2.1.1

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "deeppapernote",
   "description": "Academic paper reading and Obsidian note generation skills for building a research WIKI.",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "author": {
     "name": "917Dhj"
   },

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deeppapernote",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Academic paper reading and Obsidian note generation skills for building a research WIKI.",
   "author": {
     "name": "917Dhj",

CHANGELOG.md

@@ -12,6 +12,20 @@ Add an entry here when the project meaningfully changes for users, for example:
 
 ## Unreleased
 
+## v2.1.1
+
+### Added
+
+- Added a built-in, read-only Zotero Local API integration with local attachment discovery, explicit `auto` / `off` / `required` resolution policies, and environment diagnostics.
+
+### Fixed
+
+- Enforced a canonical paper-identity boundary across metadata collection, PDF acquisition, evidence extraction, and synthesis so conflicting or ambiguous identities fail closed.
+
+### Contributors
+
+- Added the Zotero Local API integration from PR #13 by [@KumamuKuma](https://github.com/KumamuKuma).
+
 ## v2.1.0
 
 ### Added

README.md

@@ -132,6 +132,16 @@ None of these are required for ordinary digital PDFs.
 | Semantic Scholar API | Improves metadata lookup for papers that are difficult to resolve |
 | OCR tooling | Recovers page text from scanned or low-quality PDFs |
 
+### Zotero Local API
+
+The built-in, read-only Zotero Local API integration supports three resolution modes:
+
+- `auto` (default): prefer a unique local item and retain web fallback
+- `off`: skip Zotero lookup
+- `required`: stop unless Zotero uniquely resolves the reference
+
+An ambiguous local match always fails closed instead of selecting an arbitrary item. Compatible agent-runtime or MCP integrations remain optional alternatives.
+
 When one of these capabilities is needed, ask your agent to inspect the current environment and guide the setup for that machine.
 
 ## 🧭 Inspirations

README.zh-CN.md

@@ -132,6 +132,16 @@ export DEEPPAPERNOTE_OBSIDIAN_VAULT="/你的/Obsidian/库/绝对路径"
 | Semantic Scholar API | 改善部分难以识别论文的元数据获取 |
 | OCR 工具 | 从扫描版或文本质量较差的 PDF 中恢复页面文字 |
 
+### Zotero Local API
+
+内置的只读 Zotero Local API 集成提供三种解析模式：
+
+- `auto`（默认）：优先使用唯一的本地条目，同时保留联网回退
+- `off`：跳过 Zotero 查询
+- `required`：只有 Zotero 唯一解析出目标论文时才继续
+
+本地匹配存在歧义时，流程会明确失败，而不是任意选择条目。Agent runtime 或 MCP 提供的兼容集成仍可作为可选替代路线。
+
 实际需要其中某项能力时，可以让 Agent 检查当前环境，并针对这台机器引导配置。
 
 ## 🧭 致谢与灵感

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deeppapernote"
-version = "2.1.0"
+version = "2.1.1"
 description = "An agent-neutral skill for turning one research paper into a high-quality Obsidian note."
 readme = "README.md"
 requires-python = ">=3.10"

skills/deeppapernote/SKILL.md

@@ -116,14 +116,15 @@ Prefer the strongest available source in this order:
 4. arXiv or open-access PDF sources
 5. Semantic Scholar or OpenAlex for metadata backfill
 
-Before resolving the paper, actively check Zotero integration: attempt to call the Zotero MCP tool (for example, search for the paper title or list libraries). If the tool responds without error, Zotero is available and the local-library-first rule below applies. If the call fails or the tool is not present, record "Zotero not available" and proceed without it. Do not skip this check — the check itself determines whether local-library-first applies.
+Before web resolution, use the bundled `scripts/resolve_paper.py` Zotero Local API path to check the desktop library. Its default `--zotero-mode auto` prefers a unique local match and falls back to the existing providers when Zotero is unavailable or has no match. An explicit Zotero key has no safe web fallback and must be verified locally. Use `off` to make no Local API request, or `required` when the reference must resolve through Zotero. A trusted JSON artifact or explicit local PDF remains authoritative and bypasses this lookup. A compatible session-scoped Zotero/MCP integration may still provide a trusted input artifact when available, but it is not required for the built-in path.
 
-Local-library-first rule (applies only when the Zotero check above succeeds):
-- search the local Zotero library first using the paper title, DOI, or arXiv id
+Local-library-first rule:
+- search the local Zotero library first using the paper title, DOI, arXiv id, or exact Zotero item key
 - If Zotero finds the paper, treat that result as the canonical identity resolution step.
-- If the attachment path is not exposed by the integration, use `scripts/locate_zotero_attachment.py` with the attachment key and filename to find the local PDF under the user's Zotero storage.
+- Prefer the safe local attachment path returned by the built-in Local API. If another compatible integration exposes only an attachment key and filename, use `scripts/locate_zotero_attachment.py` to find the PDF under the user's Zotero storage.
 - If a local attachment path is available, pass it forward as the preferred PDF source.
 - If no local attachment is found, still use the library-resolved metadata to avoid title ambiguity, then fall back to network PDF acquisition only for the file itself.
+- If multiple local items are equally plausible, fail closed and request a DOI, arXiv id, or exact Zotero key rather than selecting one arbitrarily.
 - Do not let a weaker title-only internet match override a confident local-library hit.
 
 ## Output Rules

skills/deeppapernote/references/metadata-sources.md

@@ -32,8 +32,10 @@ Use the strongest available source first, but backfill aggressively.
 
 ## Rules
 
-- If the paper is already in the local Zotero library, treat Zotero as the identity anchor before doing title-based web resolution.
+- Use the bundled read-only Zotero Local API client first when the desktop API is enabled; compatible runtime or MCP integrations may provide the same trusted local metadata as an optional alternative.
+- If the paper is already in the local Zotero library, treat a unique Zotero match as the identity anchor before doing title-based web resolution.
 - If Zotero resolves the paper but does not expose a local attachment path, still use the Zotero metadata to avoid title ambiguity.
+- Distinguish an ambiguous local identity from an unavailable attachment: never guess between equally plausible items, but keep a uniquely resolved parent item's metadata even when no local PDF is accessible.
 - Do not let a weaker internet title match override a confident Zotero hit.
 - Do not invent missing metadata.
 - If a Chinese title is assistant-generated, mark it as a translation.