pyzotero

pyzotero 技能概覽

pyzotero 是做什麼的

pyzotero 是 Zotero Web API v3 的 Python 用戶端。這個 pyzotero 技能可以幫你讀取、建立、更新、刪除 Zotero 的項目、集合、標籤、附件，以及引用匯出，而不用自己手動拼 API 呼叫。

適合誰使用

它最適合做自動化參考文獻管理、文獻工作流程，或 Zoterosync 風格資料庫維護的人——尤其是用在 Academic Research 的 pyzotero、腳本化的書目清理，以及需要穩定 Zotero 整合的研究流程。

為什麼值得安裝這個技能

pyzotero 技能的核心價值，是把 Zotero 變成可程式化的資料庫後端。你不再只是接一個一次性的提示詞，而是有一套可重複使用的方法來查詢中繼資料、管理群組或個人資料庫、抓取附件，並以較少 API 錯誤匯出引用格式。

如何使用 pyzotero 技能

安裝 pyzotero

直接安裝 Python 套件即可；只有在你需要本機 Zotero 桌面版搜尋時，才加上 CLI 額外功能：

uv add pyzotero
uv add "pyzotero[cli]"

如果你正在評估 pyzotero 的安裝選項，CLI 只在你想搜尋正在執行的本機 Zotero App 時才有用；遠端 API 工作不需要它。

先準備正確的輸入

一個好的 pyzotero 使用需求，最好包含：

• 資料庫類型：user 或 group
• 操作：讀取、建立、更新、刪除、匯出或搜尋
• 目標物件：項目 key、集合 key、標籤、附件或已儲存搜尋
• 輸出格式：Python objects、JSON、BibTeX、CSL-JSON 或 HTML citations

提示詞範例：

Use pyzotero to list items in my group library, filter to journal articles tagged reviewed, and export the results as CSL-JSON.

依這個順序閱讀檔案

實作時，先讀 SKILL.md，再依照你的任務對應到下列重點參考文件：

• references/authentication.md：API keys、user IDs 與 local mode
• references/read-api.md 和 references/search-params.md：擷取與篩選
• references/write-api.md：建立／更新／刪除流程
• references/files-attachments.md 和 references/full-text.md：PDF 與索引
• references/exports.md：BibTeX、CSL-JSON 與引用輸出
• references/error-handling.md：rate limits、衝突與無效欄位

更順手的 pyzotero 使用流程

1. 先確認你需要的是遠端 API 存取，還是僅限本機搜尋。
2. 在呼叫方法前，先為正確的資料庫設定憑證。
3. 先測一個讀取呼叫，再擴展到批次操作。
4. 更新和刪除時要用 keys，不要用標題。
5. 儘早加入分頁或輸出數量限制，讓結果真的可用。

pyzotero 技能 FAQ

pyzotero 只適合程式設計師嗎？

不是。它在 Python 工作流程中最有用，但只要你能照著簡短安裝步驟並提供結構化輸入，非專家也能上手。如果你只是偶爾手動匯出引用，一般的 Zotero 提示可能更簡單。

pyzotero 可以同時支援個人和群組資料庫嗎？

可以。pyzotero 技能同時支援兩者，但單一 Zotero instance 只會綁定一個資料庫。當你需要在個人資料庫和共享的實驗室或團隊資料庫之間切換時，這點尤其重要。

什麼時候不該用 pyzotero？

如果你只想在 Zotero 裡快速做一次性的引用格式化，或是你需要在沒有本機 Zotero 桌面版的情況下做全文搜尋，就不要用 pyzotero。CLI 依賴本機 Zotero；API 並不提供相同的本機全文搜尋行為。

pyzotero 適合 Academic Research 嗎？

適合，特別是用在批次文獻管理、參考文獻清理、附件處理，以及可重現的匯出。若你的工作主要是閱讀論文，而不是整理或轉換 Zotero 資料，它就沒有那麼幫得上忙。

如何改進 pyzotero 技能

先把缺少的資料庫資訊補齊

提升品質最有效的方法，就是一開始就講清楚資料庫情境。對 pyzotero 來說，請包含 library ID、是 user 還是 group，以及你要 local mode 還是 remote API。少了這些，輸出常常會太泛，或選到錯的存取路徑。

明確說出你要的資料形狀

直接說你要單一項目、項目清單、集合樹、附件中繼資料，還是匯出檔。好的 pyzotero 輸入會像這樣：

• “return only keys and titles”
• “update the abstractNote for these item keys”
• “export the top 50 results as BibTeX”
• “find PDFs whose full text mentions gene editing”

留意常見失敗模式

最常見的 pyzotero 錯誤，是拿標題代替 keys、跳過認證設定，以及一次嘗試批次寫入太多資料。另一個常見問題，是誤以為只靠 API 就能做本機全文搜尋。如果結果不對，先檢查查詢應該用的是項目中繼資料、全文，還是集合篩選。

第一次跑完後再迭代

如果第一次輸出太廣，就加上項目類型、標籤邏輯、集合 key 或日期區間來收斂。若第一次寫入或更新風險太高，可以請 pyzotero 先 dry-run payload，或在套用變更前先顯示實際的項目欄位。這是把 pyzotero 用在真實研究工作流程時，最快的改進方式。