Rename skill for Zotero Obsidian workflow
This commit is contained in:
qyh15
parent
eadbe975c0
commit
363e8396b7
92
SKILL.md
92
SKILL.md
|
|
@ -1,62 +1,44 @@
|
|||
---
|
||||
name: zotero-ai-notes
|
||||
description: Generate, resume, audit, and maintain AI-generated Zotero child-note literature notes using Zotero Local API metadata, Zotero Web API writes, and AwesomeGPT/DeepSeek-compatible chat settings. Use when the user asks to batch-generate Zotero literature notes, fill Zotero notes from Obsidian templates, use AwesomeGPT or DeepSeek for Zotero papers, skip existing AI notes, resume interrupted Zotero note generation, audit duplicate Zotero AI notes, or package/upgrade this Zotero note workflow.
|
||||
name: zotero-obsidian-literature
|
||||
description: Manage the user's Zotero-to-Obsidian literature workflow: batch-generate Zotero child-note AI literature notes from Obsidian templates, audit missing Zotero notes, clean empty Obsidian literature notes, create and refine Dataview literature dashboards, preserve Obsidian Markdown conventions, and package or back up the workflow skill without exposing API keys. Use when the user asks about Zotero AI notes, AwesomeGPT/DeepSeek literature notes, Obsidian literature-note cleanup, Dataview literature dashboards, Zotero note audit/resume, or upgrading this Zotero-Obsidian workflow.
|
||||
---
|
||||
|
||||
# Zotero AI Notes
|
||||
# Zotero Obsidian Literature
|
||||
|
||||
Use this skill to create Zotero child notes from local Zotero items with the user's literature-note templates.
|
||||
Use this skill for the user's Zotero + Obsidian literature workflow. It covers Zotero child-note generation, deterministic audits, Obsidian literature-note maintenance, Dataview dashboards, and safe packaging/backups.
|
||||
|
||||
This skill is also Obsidian-aware: templates, prompts, and the local audit cache live in the user's Obsidian vault, so preserve Obsidian Flavored Markdown conventions when reading or adapting those materials. Read [references/obsidian-integration.md](references/obsidian-integration.md) before changing template handling, adding vault-facing files, or generating Markdown meant to round-trip through Obsidian. Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before pulling in more ideas from `kepano/obsidian-skills`.
|
||||
|
||||
Core script:
|
||||
Core scripts:
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
|
||||
```
|
||||
|
||||
Fast audit script:
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
||||
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
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Zotero Desktop must be open and Local API enabled at `http://127.0.0.1:23119`.
|
||||
- The vault default is `C:\Users\qyh15\Documents\Obsidian Vault`.
|
||||
- The vault must contain `00 Templater` with:
|
||||
- `01 ...md` research-article template
|
||||
- `02 ...md` review-article template
|
||||
- `03 ...md` AI prompt
|
||||
- `ZOTERO_API_KEY` must be available in the process environment for write access.
|
||||
- LLM settings come from either:
|
||||
- `AWESOMEGPT_API_KEY`, `AWESOMEGPT_BASE_URL`, `AWESOMEGPT_MODEL`, or
|
||||
- AwesomeGPT preferences in the default Zotero profile.
|
||||
- `ZOTERO_API_KEY` must be available in the process environment for Zotero Web API writes.
|
||||
- LLM settings come from `AWESOMEGPT_API_KEY`, `AWESOMEGPT_BASE_URL`, `AWESOMEGPT_MODEL`, or AwesomeGPT preferences in the default Zotero profile.
|
||||
|
||||
Never store API keys in the skill. If keys appear in chat or logs, tell the user to rotate them.
|
||||
Never store API keys in the skill, vault helper files, Git commits, zip files, terminal output, or chat. If keys appear in chat or logs, tell the user to rotate them.
|
||||
|
||||
## Obsidian-Aware Template Rules
|
||||
|
||||
- Treat `00 Templater` as the source of truth for note structure. Do not rewrite the user's templates unless asked.
|
||||
- Preserve Obsidian syntax from templates, including wikilinks, callouts, tags, math, highlights, comments, and YAML frontmatter.
|
||||
- Zotero child notes should remain clean Markdown/HTML note content; do not insert visible AI banners such as `AI Literature Note` or `AI文献笔记`.
|
||||
- If generating any auxiliary `.md` file in the vault, use valid Obsidian properties and internal links as described in [references/obsidian-integration.md](references/obsidian-integration.md).
|
||||
- Keep operational artifacts hidden or clearly tool-scoped: cache/index files should stay under `00 Templater` and begin with a dot when practical.
|
||||
|
||||
## Common Workflows
|
||||
## Zotero Note Workflows
|
||||
|
||||
### Single item
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
|
||||
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
|
||||
```
|
||||
|
||||
Set `ZOTERO_API_KEY` in the current shell before running live writes, but do not print or paste the value into logs or chat.
|
||||
|
||||
### Multiple item keys
|
||||
### Multiple items
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\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
|
||||
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
|
||||
```
|
||||
|
||||
### Whole library
|
||||
|
|
@ -64,44 +46,50 @@ py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_no
|
|||
Use only after the user explicitly approves library-wide writes.
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --all --limit 0 --skip-existing --fulltext-chars 4000
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --all --limit 0 --skip-existing --fulltext-chars 4000
|
||||
```
|
||||
|
||||
For long runs, prefer 20-30 item batches. If a run times out, rerun with `--skip-existing`; the script resumes by checking child notes for the source Zotero item link.
|
||||
|
||||
### Find items missing generated notes
|
||||
### Missing generated notes
|
||||
|
||||
Do this deterministically; do not ask DeepSeek or another LLM to compare library state.
|
||||
|
||||
First build or refresh the cache:
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --rebuild
|
||||
```
|
||||
|
||||
Later fast checks:
|
||||
|
||||
```powershell
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\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
|
||||
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
||||
```
|
||||
|
||||
The cache lives at `<vault>\00 Templater\.zotero-ai-notes-index.json`. Use `--refresh` or `--rebuild` when notes were edited outside this workflow.
|
||||
|
||||
## Obsidian Workflows
|
||||
|
||||
Read [references/obsidian-integration.md](references/obsidian-integration.md) before changing template handling, adding vault-facing files, or generating Markdown meant to round-trip through Obsidian.
|
||||
|
||||
Read [references/obsidian-literature-maintenance.md](references/obsidian-literature-maintenance.md) before cleaning empty notes, creating Dataview dashboards, adding CSS snippets, or changing the `01 文献阅读` organization.
|
||||
|
||||
Default vault organization:
|
||||
|
||||
- `00 Templater`: source templates, prompts, and the hidden Zotero audit cache.
|
||||
- `01 文献阅读/00 AI总结笔记`: Obsidian-exported/generated literature notes.
|
||||
- `01 文献阅读/01 Dataview文献看板`: Dataview dashboards for journal, year, actuator, review, DOI, and material/keyword views.
|
||||
- `.obsidian/snippets/literature-dataview.css`: optional CSS snippet for compact Dataview tables.
|
||||
|
||||
## Operating Rules
|
||||
|
||||
- For live writes, state that Zotero child notes will be created.
|
||||
- For live Zotero writes, state that Zotero child notes will be created.
|
||||
- Use `--dry-run` for first-time validation or template changes.
|
||||
- Use `--fulltext-chars 4000` for cheap, lightweight notes; increase only when the user asks for deeper notes.
|
||||
- Do not add visible machine markers to note bodies. Use the Zotero item link for duplicate detection.
|
||||
- Do not delete duplicate notes unless the user explicitly requests cleanup.
|
||||
- Use `audit_zotero_ai_notes.py` for missing-note checks. Reserve DeepSeek for generating or improving note content.
|
||||
- Do not delete Zotero duplicate notes unless the user explicitly requests cleanup.
|
||||
- For Obsidian cleanup, delete only files that are empty after removing frontmatter, separators, whitespace, and empty HTML placeholders.
|
||||
- Keep Dataview dashboards readable: avoid `GROUP BY` tables that put long `rows.file.link` lists inside one cell; prefer count summaries plus separate one-row-per-paper detail tables.
|
||||
- Reserve DeepSeek for generating or improving note content, not deterministic library comparison or file cleanup.
|
||||
- If PowerShell/cmd output has Unicode issues, set `PYTHONIOENCODING=utf-8` or rely on script UTF-8 reconfiguration.
|
||||
- If PDF full text is unavailable, allow the script to fall back to metadata, abstract, BibTeX, and optional local PDF extraction if a Python PDF library exists.
|
||||
- If PDF full text is unavailable, allow fallback to metadata, abstract, BibTeX, and optional local PDF extraction if a Python PDF library exists.
|
||||
|
||||
## Upgrade Points
|
||||
|
||||
Read [references/upgrade-plan.md](references/upgrade-plan.md) before changing behavior, adding cleanup, adding collection targeting, or improving note quality.
|
||||
Read [references/upgrade-plan.md](references/upgrade-plan.md) before changing behavior, adding cleanup, adding collection targeting, improving note quality, or adding Gitea/GitHub backup steps.
|
||||
|
||||
Read [references/obsidian-integration.md](references/obsidian-integration.md) before adding Obsidian vault exports, Bases views, markdown normalization, or Obsidian CLI integration.
|
||||
|
||||
Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before doing another merge from `kepano/obsidian-skills`.
|
||||
Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before pulling in more ideas from `kepano/obsidian-skills`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "Zotero AI Notes"
|
||||
short_description: "Batch AI notes into Zotero child notes"
|
||||
default_prompt: "Use $zotero-ai-notes to generate Zotero child-note literature notes from my vault templates."
|
||||
display_name: "Zotero Obsidian Literature"
|
||||
short_description: "Manage Zotero AI notes and Obsidian literature dashboards"
|
||||
default_prompt: "Use $zotero-obsidian-literature to manage my Zotero AI notes, Obsidian literature notes, and Dataview dashboards."
|
||||
|
|
|
|||
|
|
@ -0,0 +1,143 @@
|
|||
# Obsidian Literature Maintenance
|
||||
|
||||
Use this reference when working inside the user's Obsidian vault literature area:
|
||||
|
||||
```text
|
||||
C:\Users\qyh15\Documents\Obsidian Vault\01 文献阅读
|
||||
```
|
||||
|
||||
## Empty AI Note Cleanup
|
||||
|
||||
Target folder:
|
||||
|
||||
```text
|
||||
01 文献阅读\00 AI总结笔记
|
||||
```
|
||||
|
||||
Definition of an empty note:
|
||||
|
||||
- Markdown file under the target folder.
|
||||
- After removing YAML frontmatter, standalone `---` separators, whitespace, ` `, `<br>`, empty `<p></p>`, and HTML comments, there is no body content.
|
||||
- A note with any real summary, heading, bullet, Zotero link, DOI text, or manual annotation is not empty.
|
||||
|
||||
PowerShell dry-run pattern:
|
||||
|
||||
```powershell
|
||||
$dir = '01 文献阅读\00 AI总结笔记'
|
||||
$empty = @()
|
||||
Get-ChildItem -LiteralPath $dir -File -Filter '*.md' | ForEach-Object {
|
||||
$text = [System.IO.File]::ReadAllText($_.FullName)
|
||||
$body = $text -replace '^\uFEFF',''
|
||||
$body = [regex]::Replace($body, '(?s)^\s*---\r?\n.*?\r?\n---\s*', '')
|
||||
$body = [regex]::Replace($body, '(?m)^\s*---\s*$', '')
|
||||
$body = [regex]::Replace($body, ' |<br\s*/?>|<p>\s*</p>|<!--.*?-->', '', 'Singleline')
|
||||
if ([string]::IsNullOrWhiteSpace($body)) { $empty += $_ }
|
||||
}
|
||||
$empty | Select-Object Name,Length
|
||||
'EMPTY_COUNT=' + $empty.Count
|
||||
```
|
||||
|
||||
Delete only after inspecting the dry-run count and at least a few representative files:
|
||||
|
||||
```powershell
|
||||
$empty | ForEach-Object { Remove-Item -LiteralPath $_.FullName }
|
||||
```
|
||||
|
||||
After deletion, rerun the dry-run scan and confirm `EMPTY_COUNT=0`.
|
||||
|
||||
## Dataview Dashboard Folder
|
||||
|
||||
Default dashboard folder:
|
||||
|
||||
```text
|
||||
01 文献阅读\01 Dataview文献看板
|
||||
```
|
||||
|
||||
Recommended files:
|
||||
|
||||
- `00 文献总览.md`: journal distribution, recent updates, missing rating/status.
|
||||
- `01 按期刊分类.md`: journal count ranking, one-row-per-paper detail table, high-impact journals, missing journal.
|
||||
- `02 驱动器相关.md`: actuator/robotic/soft robotics keyword views.
|
||||
- `03 综述与进展类.md`: review/recent/advances/progress/emerging/fundamentals/current/strategies views.
|
||||
- `04 按年份分类.md`: year grouping and count summaries.
|
||||
- `05 材料与关键词分类.md`: MXene, MOF, hydrogel/organogel/ionogel, cellulose/PVA/polymer, TENG.
|
||||
- `06 DOI明细.md`: DOI-heavy views separated from the main dashboard to avoid wide tables.
|
||||
|
||||
Dataview source path:
|
||||
|
||||
```dataview
|
||||
FROM "01 文献阅读/00 AI总结笔记"
|
||||
```
|
||||
|
||||
Use `TABLE WITHOUT ID` for cleaner tables.
|
||||
|
||||
Avoid this pattern for visual dashboards:
|
||||
|
||||
```dataview
|
||||
TABLE rows.file.link AS 文章
|
||||
GROUP BY journal
|
||||
```
|
||||
|
||||
It creates one huge list per table cell and makes journal rows look sparse. Prefer:
|
||||
|
||||
```dataview
|
||||
TABLE WITHOUT ID
|
||||
key AS 期刊,
|
||||
length(rows) AS 篇数
|
||||
FROM "01 文献阅读/00 AI总结笔记"
|
||||
WHERE contains(tags, "literature") AND journal
|
||||
GROUP BY journal
|
||||
SORT length(rows) DESC, key ASC
|
||||
```
|
||||
|
||||
Then add a separate detail table:
|
||||
|
||||
```dataview
|
||||
TABLE WITHOUT ID
|
||||
file.link AS 文章,
|
||||
journal AS 期刊,
|
||||
year AS 年份
|
||||
FROM "01 文献阅读/00 AI总结笔记"
|
||||
WHERE contains(tags, "literature") AND journal
|
||||
SORT journal ASC, year DESC, file.name ASC
|
||||
```
|
||||
|
||||
## Dataview Table Width
|
||||
|
||||
Keep main dashboard tables narrow. Put wide fields such as DOI, authors, and file modification times into separate detail pages.
|
||||
|
||||
Optional CSS snippet:
|
||||
|
||||
```text
|
||||
.obsidian\snippets\literature-dataview.css
|
||||
```
|
||||
|
||||
Recommended behavior:
|
||||
|
||||
- `table-layout: fixed`
|
||||
- `width: 100%`
|
||||
- wrap long cell text with `overflow-wrap: anywhere`
|
||||
- first column about `42%`, second about `28%`, third about `10%`
|
||||
|
||||
Enable the snippet in `.obsidian/appearance.json` with:
|
||||
|
||||
```json
|
||||
"enabledCssSnippets": [
|
||||
"literature-dataview"
|
||||
]
|
||||
```
|
||||
|
||||
If Obsidian does not pick it up immediately, use `Settings > Appearance > CSS snippets > Refresh` or restart Obsidian.
|
||||
|
||||
## Rendering Troubleshooting
|
||||
|
||||
If Dataview blocks show as code:
|
||||
|
||||
- Confirm the Dataview community plugin is installed and enabled.
|
||||
- Switch from editing/live-preview into reading view if needed.
|
||||
- Reopen the note or restart Obsidian.
|
||||
- A real Dataview syntax issue usually shows an error, not a raw code block.
|
||||
|
||||
## Encoding Caution
|
||||
|
||||
Some older generated notes may display mojibake in PowerShell output or Obsidian if the original generation used the wrong encoding. Do not bulk rewrite those notes unless the user asks for text repair. Dataview dashboards should primarily rely on frontmatter fields and file names until encoding is repaired.
|
||||
|
|
@ -7,6 +7,8 @@ Keep upgrades backward compatible with the current command line.
|
|||
- Add `--collection` to process one Zotero collection by name or key.
|
||||
- Add `--delete-duplicates` with a dry-run default and explicit confirmation requirement.
|
||||
- Add `--report-out <path>` to save run summaries without dumping full note HTML to terminal.
|
||||
- Add a script option to export or refresh Obsidian Dataview dashboard files under `01 文献阅读\01 Dataview文献看板`.
|
||||
- Add a script option to dry-run and delete empty Obsidian literature notes under `01 文献阅读\00 AI总结笔记`.
|
||||
- Add retry/backoff for Zotero Web API writes and LLM calls.
|
||||
- Add `--provider <name>` to select AwesomeGPT providers other than DeepSeek.
|
||||
- Add incremental audit invalidation based on Zotero item/library version headers, so only changed parents are rescanned after the initial cache build.
|
||||
|
|
@ -23,6 +25,8 @@ Keep upgrades backward compatible with the current command line.
|
|||
- Never log API keys.
|
||||
- Do not write keys into `.env` automatically.
|
||||
- For destructive actions such as duplicate cleanup, require an explicit user request and perform a dry run first.
|
||||
- For Obsidian note deletion, only delete notes that remain empty after frontmatter and placeholder cleanup, and report the count before deletion.
|
||||
- Keep Dataview dashboards and CSS snippets free of secrets and large pasted source content.
|
||||
- Prefer `--skip-existing` for all batch jobs.
|
||||
|
||||
## Known constraints
|
||||
|
|
|
|||
Loading…
Reference in New Issue