Zotero-Obsidian 文献工作流 Skill

这是一个用于管理 Zotero 到 Obsidian 文献阅读流程的 Codex skill。

它主要用于把 AI 生成的文献阅读笔记写入 Zotero 子笔记，检查哪些条目还没有生成笔记，维护 Obsidian 文献笔记，并生成 Dataview 仪表盘。同时，它会把 Zotero、DeepSeek 或 AwesomeGPT 的真实密钥保存在本地忽略文件中，避免提交到 Git 仓库。

功能

• 将 AI 文献笔记生成到 Zotero 子笔记中。
• 使用目标 Obsidian 库中的模板和提示词文件。
• 支持单篇文献、指定多个 Zotero 条目，或在明确确认后批量处理整个文库。
• 检查 Zotero 中还没有生成 AI 笔记的条目。
• 将 Zotero 和 DeepSeek/AwesomeGPT 凭据保存在本地私有配置中。
• 提供 Obsidian、Dataview 和 Markdown 维护相关的工作流说明。

仓库结构

.
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
|-- config/
|   `-- config.template.json
|-- references/
|   |-- obsidian-integration.md
|   |-- obsidian-literature-maintenance.md
|   |-- upgrade-plan.md
|   `-- upstream-obsidian-skills.md
`-- scripts/
    |-- audit_zotero_ai_notes.py
    |-- generate_zotero_ai_note.py
    `-- init_private_config.py

使用前提

• Zotero Desktop 已打开。
• Zotero Local API 已启用，地址为 http://127.0.0.1:23119。
• Windows 中可使用 Python 启动器 py。
• 默认 Obsidian 库路径为 C:\Users\qyh15\Documents\Obsidian Vault。
• Obsidian 库中 00 Templater 目录下有对应模板和提示词。
• 已准备 Zotero Web API key，用于写入 Zotero 笔记。
• DeepSeek 或其他 OpenAI 兼容接口已通过 AwesomeGPT 设置、环境变量或本地私有配置完成配置。

私有配置

不要提交真实 API key。

仓库中只提交模板文件：

config/config.template.json

使用下面的命令创建本地私有配置：

py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\init_private_config.py"

该命令会生成：

config/config.local.json

config/config.local.json 已被 Git 忽略。不要把它的内容粘贴到聊天、日志、README 或任何会提交到仓库的示例文件中。

常用命令

为单个 Zotero 条目生成笔记：

py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing

为指定多个 Zotero 条目生成笔记：

py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --limit 0 --skip-existing --fulltext-chars 4000

检查哪些条目缺少已生成的 AI 笔记：

py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only

重建检查缓存：

py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --rebuild

批处理安全

整库生成会向 Zotero 写入大量子笔记。只有在明确确认目标文库和写入范围后，才使用整库批处理。

长任务建议每批处理 20-30 个条目，并保持 --skip-existing 开启。这样即使中途中断，也可以重新运行并跳过已经生成过的笔记，避免重复写入。

Git

当前远程仓库：

git@git.qyhhh.top:Skills/MYwirte-skill.git

当前环境推荐的推送命令：

git push

如果新终端还不能直接识别 git，可以临时使用完整路径：

& "$env:USERPROFILE\.codex\tools\mingit\cmd\git.exe" push