---
name: obsidian-literature-base
description: Build and refresh an Obsidian Base and optional topic Wiki for OmniScholar MinerU publications and Zotero reading records, including bibliographic views, prefixed or AI-assisted topics, cover images, foldable image galleries, and preserved topic synthesis pages. Use when organizing multiple OmniScholar literature outputs in an Obsidian vault; do not use for reading-status workflows or modifying Zotero.
license: MIT
---

# Build an Obsidian literature base

Create a browse-focused catalogue over existing OmniScholar publications. Do not upload PDFs, re-run MinerU, or write to Zotero for this workflow.

## Workflow

1. Confirm the Obsidian vault root that contains OmniScholar publication folders and their `metadata.json` files.
2. Discover valid publication sidecars (`schemaVersion: 1` with `publication` and `zotero` objects). Treat the MinerU Markdown, Zotero reading record, and images in one publication directory as one paper.
3. Derive topics in this order:
   - Extract Zotero tags prefixed with `topic/` or `主题/`, stripping the prefix.
   - Only for papers without prefixed topics, optionally assign 1–3 concise AI topics from title and abstract. Read the MinerU body only when those fields are insufficient.
   - Never write AI topics back to Zotero.
4. When AI topics are needed, save a temporary JSON mapping described in [references/schema.md](references/schema.md). Then run `scripts/build_literature_base.py` with the vault root and optional mapping.
5. When the user wants a knowledge Wiki, add `--wiki`. Generate topic pages only for topics shared by at least two papers unless the user chooses another threshold.
6. Verify the generated `.base` is valid YAML and each generated `literature-index.md` links to the correct MinerU document, Zotero reading record, cover, image assets, and eligible topic pages.
7. Report the Base path, indexed paper count, topic-source counts, Wiki page count, stale Wiki pages, and any papers without topics or images.

Resolve the deterministic script relative to this `SKILL.md`; do not assume the user's current directory is the Skill directory. Use it instead of reconstructing index notes or Base YAML manually:

```sh
python <skill-dir>/scripts/build_literature_base.py <vault-root>
python <skill-dir>/scripts/build_literature_base.py <vault-root> --ai-topics <topics.json>
python <skill-dir>/scripts/build_literature_base.py <vault-root> --wiki
```

The script creates one generated `literature-index.md` beside each publication and `Literature.base` at the vault root. The index is a presentation page, not a reading-state record. It contains source-derived properties and a collapsed gallery of every MinerU image. Re-running the script refreshes only files marked as generated by this Skill.

## Optional topic Wiki

With `--wiki`, also generate:

- `文献知识库.md`, which embeds the `按主题` and `文献总表` Base views and links every eligible topic page.
- `Literature Wiki/Topics/<主题>.md` for topics shared by at least two papers.
- Topic Wikilinks in each related `literature-index.md`, so Backlinks and Graph connect papers to concepts.

Each topic page has an automatically refreshed `相关文献` section and a separately marked manual section for `定义与边界`, `核心研究问题`, `当前共识`, `尚存争议`, `研究空白`, and `相关主题`. Preserve the manual section, aliases, and review status during refreshes. AI may draft that section only from reviewed evidence and must link claims to supporting literature-index notes. Do not present title/abstract-only synthesis as established consensus.

Do not delete generated topic pages that fall below the current threshold. Stop listing them in the hub, report them as stale, and leave deletion to an explicit user request.

## Required views

Generate exactly these browse-oriented views unless the user asks for a change:

- `文献总表`
- `原始产物`
- `按年份`
- `按作者`
- `按期刊`
- `按主题`
- `按标签`

`按主题` is a Cards view with one cover image per paper. Native Base cards do not provide a collapsible multi-image region; the card opens the generated index page, where `全部图片` is a collapsed callout containing all previewable images.

Read [references/schema.md](references/schema.md) before changing generated properties, topic precedence, view definitions, or overwrite behavior.

## Safety and update behavior

- Treat MinerU Markdown, `metadata.json`, assets, copied PDFs, and `source/zotero-reading-record.md` as managed source artifacts. Do not edit them.
- Do not create `research-state.md` or workflow properties such as reading status, priority, or rating.
- Refuse to overwrite an existing Base, index note, Wiki hub, or topic page that lacks this Skill's generated marker. Use `--force-base` only when the user explicitly asks to replace a hand-authored Base.
- Preserve source tags separately from normalized topics. Prefixed Zotero topics take precedence over AI suggestions.
- Keep English property keys and Chinese `displayName` labels for stable formulas and a Chinese interface.