From 061ca25b56f025f810e4dd68b1f3f4ea28969f87 Mon Sep 17 00:00:00 2001
From: qyh15 <qyh15@local>
Date: Wed, 20 May 2026 16:35:41 +0800
Subject: [PATCH] Simplify README usage guide

---
 README.md | 158 +++++++++++++++++++++---------------------------------
 1 file changed, 62 insertions(+), 96 deletions(-)

diff --git a/README.md b/README.md
index 43cd917..9ef0487 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,71 @@
 # Zotero-Obsidian 文献工作流 Skill
 
-这是一个用于管理 Zotero 到 Obsidian 文献阅读流程的 Codex skill。
+这是一个用于 Zotero 和 Obsidian 文献阅读流程的 Codex skill。普通使用者不需要手动运行脚本，只需要在 Codex 里用自然语言提出任务，AI 会根据 `SKILL.md` 和配套脚本完成检查、生成、批处理或维护工作。
 
-它主要用于把 AI 生成的文献阅读笔记写入 Zotero 子笔记，检查哪些条目还没有生成笔记，维护 Obsidian 文献笔记，并生成 Dataview 仪表盘。同时，它会把 Zotero、DeepSeek 或 AwesomeGPT 的真实密钥保存在本地忽略文件中，避免提交到 Git 仓库。
+## 适合做什么
 
-## 功能
+- 在 Zotero 中为文献生成 AI 阅读笔记。
+- 把生成结果写成 Zotero 子笔记，而不是直接写到 Obsidian 文件夹。
+- 检查哪些 Zotero 条目还没有生成 AI 笔记。
+- 按指定条目、指定集合或小批量方式继续生成笔记。
+- 维护 Obsidian 文献阅读库、模板和 Dataview 视图。
+- 在不暴露 Zotero、DeepSeek 或 AwesomeGPT 密钥的前提下完成自动化处理。
 
-- 将 AI 文献笔记生成到 Zotero 子笔记中。
-- 使用目标 Obsidian 库中的模板和提示词文件。
-- 支持单篇文献、指定多个 Zotero 条目，或在明确确认后批量处理整个文库。
-- 检查 Zotero 中还没有生成 AI 笔记的条目。
-- 将 Zotero 和 DeepSeek/AwesomeGPT 凭据保存在本地私有配置中。
-- 提供 Obsidian、Dataview 和 Markdown 维护相关的工作流说明。
+## 使用前准备
 
-## 仓库结构
+- 打开 Zotero Desktop。
+- 确认 Zotero Local API 可用。
+- 确认 Obsidian 文献库路径为 `C:\Users\qyh15\Documents\Obsidian Vault`。
+- 确认 Zotero Web API key 和 DeepSeek/AwesomeGPT 配置已经放在本地私有配置中。
+- 不要把真实 API key 发到聊天、README、日志或任何会提交到仓库的文件里。
+
+私有配置模板位于：
+
+```text
+config/config.template.json
+```
+
+真实配置应保存在本地忽略文件：
+
+```text
+config/config.local.json
+```
+
+## 对 AI 的常用指令
+
+可以直接在 Codex 里这样说：
+
+```text
+使用 zotero-obsidian-literature skill，检查我的 Zotero 文库里哪些文献还没有生成 AI 阅读笔记。
+```
+
+```text
+使用 zotero-obsidian-literature skill，为这个 Zotero 条目生成一条 AI 阅读笔记：SXAIQUJT。
+```
+
+```text
+使用 zotero-obsidian-literature skill，给这些 Zotero 条目批量生成 AI 阅读笔记：SXAIQUJT、X7GJZ627、ZCZXGRAM。
+```
+
+```text
+使用 zotero-obsidian-literature skill，从上次中断的位置继续生成文献笔记，跳过已经生成过的条目。
+```
+
+```text
+使用 zotero-obsidian-literature skill，帮我检查 Obsidian 文献阅读库的 Dataview 页面是否能正确展示 Zotero 笔记。
+```
+
+```text
+使用 zotero-obsidian-literature skill，整理我的文献阅读模板，让后续生成的 Zotero 子笔记更适合 Obsidian Dataview 使用。
+```
+
+## 批处理建议
+
+整库生成会向 Zotero 写入大量子笔记。除非已经明确确认目标文库和写入范围，否则不要要求 AI 直接处理整个 Zotero 文库。
+
+更稳妥的方式是每次处理 20-30 篇文献，并要求 AI 跳过已经生成过笔记的条目。这样即使中途失败，也可以继续执行而不会重复写入。
+
+## 仓库内容
 
 ```text
 .
@@ -32,89 +84,3 @@
     |-- 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。
-
-仓库中只提交模板文件：
-
-```text
-config/config.template.json
-```
-
-使用下面的命令创建本地私有配置：
-
-```powershell
-py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\init_private_config.py"
-```
-
-该命令会生成：
-
-```text
-config/config.local.json
-```
-
-`config/config.local.json` 已被 Git 忽略。不要把它的内容粘贴到聊天、日志、README 或任何会提交到仓库的示例文件中。
-
-## 常用命令
-
-为单个 Zotero 条目生成笔记：
-
-```powershell
-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 条目生成笔记：
-
-```powershell
-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 笔记：
-
-```powershell
-py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
-```
-
-重建检查缓存：
-
-```powershell
-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
-
-当前远程仓库：
-
-```text
-git@git.qyhhh.top:Skills/MYwirte-skill.git
-```
-
-当前环境推荐的推送命令：
-
-```powershell
-git push
-```
-
-如果新终端还不能直接识别 `git`，可以临时使用完整路径：
-
-```powershell
-& "$env:USERPROFILE\.codex\tools\mingit\cmd\git.exe" push
-```