Skip to content
Back to search

Zotero-Analytical-Workflow-Skills

主要是用于zotero论文导入obsidian的转换和管理,包括论文精读和精读模板

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cheneternity--zotero-analytical-workflow-skills/badge.svg)](/listings/cheneternity--zotero-analytical-workflow-skills)

HTML

<a href="/listings/cheneternity--zotero-analytical-workflow-skills"><img src="/api/listings/cheneternity--zotero-analytical-workflow-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills.git
cd Zotero-Analytical-Workflow-Skills
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python tools/init_vault.py --vault-root "E:\ResearchVault"

On macOS/Linux, use:

python3.11 -m venv .venv
source .venv/bin/activate
python tools/init_vault.py --vault-root "$HOME/ResearchVault"

`init_vault.py` creates only missing directories, copies only missing bundled templates, and creates a local `config.toml` only if it does not exist. It does not modify existing research files or Zotero data.

Set the Zotero and MinerU locations in the generated, git-ignored `config.toml` (format shown below), then check the setup:

python tools/check_environment.py

The checker is read-only. Zotero, MinerU and `rg` are optional capabilities and show `WARN` when not configured; missing Python, Vault folders or bundled tools show `FAIL`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Zotero Analytical Workflow Skills
  2. A portable set of agent Skills and local tools for the workflow:
  3. ```text
  4. Zotero → MinerU Fulltext → Analytical Notes → Knowledge → Literature Retrieval
  5. ```
  6. The repository is the canonical source for the complete workflow and for the Literature Retrieval Skill. New Vault content uses one layout: `01knowledge/`, `02vault/`, `03fulltext/`, and `模板/`. No tool requires the author's drive letters or private scripts.
  7. ## Requirements
  8. - Python 3.11 or newer. The bundled tools use only the Python standard library.
  9. - Zotero Desktop if reading the local Zotero database or attachments.
  10. - MinerU is optional; install it separately if PDF conversion is required. The conversion runner accepts the executable path in configuration.
  11. - Obsidian is optional for editing and navigating Markdown. Dataview is optional for users whose own index pages use Dataview.
  12. - `rg` (ripgrep) is optional. The Skills can use the agent's available project search tools when it is absent.
  13. No Zotero database, PDF, private Vault content, API package, or credential is included.
  14. ## Installation
  15. ```powershell
  16. git clone https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills.git
  17. cd Zotero-Analytical-Workflow-Skills
  18. py -3.11 -m venv .venv
  19. .\.venv\Scripts\Activate.ps1
  20. python tools/init_vault.py --vault-root "E:\ResearchVault"
  21. ```
  22. On macOS/Linux, use:
  23. ```sh
  24. python3.11 -m venv .venv
  25. source .venv/bin/activate
  26. python tools/init_vault.py --vault-root "$HOME/ResearchVault"
  27. ```
  28. `init_vault.py` creates only missing directories, copies only missing bundled templates, and creates a local `config.toml` only if it does not exist. It does not modify existing research files or Zotero data.
  29. Set the Zotero and MinerU locations in the generated, git-ignored `config.toml` (format shown below), then check the setup:
  30. ```powershell
  31. python tools/check_environment.py
  32. ```
  33. The checker is read-only. Zotero, MinerU and `rg` are optional capabilities and show `WARN` when not configured; missing Python, Vault folders or bundled tools show `FAIL`.
  34. ## Configuration
  35. Copy [`config.example.toml`](config.example.toml) or let the initializer create `config.toml`. Paths are local filesystem paths; use TOML strings and forward slashes for portable examples:
  36. ```toml
  37. [paths]
  38. vault_root = "E:/ResearchVault"
  39. zotero_data_dir = "C:/Users/alex/Zotero"
  40. mineru_executable = "C:/Tools/MinerU/mineru.exe"
  41. archive_root = "E:/ResearchVault/_staging/mineru"
  42. ```
  43. Any value can be overridden per process with `RESEARCHVAULT_ROOT`, `ZOTERO_DATA_DIR`, `MINERU_EXECUTABLE`, or `RESEARCHVAULT_ARCHIVE_ROOT`. `RESEARCHVAULT_CONFIG` selects another TOML config file. CLI flags override configuration where offered. Do not commit your local `config.toml`.
  44. ## Canonical Vault layout
  45. ```text
  46. <VAULT_ROOT>/
  47. ├── 01knowledge/
  48. │ ├── index.md
  49. │ ├── log.md
  50. │ ├── _index/
  51. │ └── .meta/ # claims and gaps; machine metadata only
  52. ├── 02vault/
  53. │ ├── _index/ # four literature indexes
  54. │ └── <collection>/<paper>.md
  55. ├── 03fulltext/
  56. │ └── <collection>/<zotero_key>.md
  57. └── 模板/
  58. ├── 论文精读模板.md
  59. └── 知识库模板/ # six canonical Knowledge templates
  60. ```
  61. New Analytical Notes go only to `02vault/`; new Fulltext goes only to `03fulltext/`. Obsidian links use `/` and paths relative to the Vault root. Historical `note/`, `论文库/`, `fulltext/`, `knowledge/`, and root-level indexes are migration inputs, not new-write destinations.
  62. ## Quick start
  63. ### Read Zotero metadata and attachments
  64. ```powershell
  65. python tools/zotero_readonly_fetch.py --key ABCD1234
  66. ```
  67. The helper uses Zotero's local SQLite database in read-only mode and emits JSON with parent `zotero_key`, PDF attachment `pdf_key`, title, authors, year, DOI, collections, annotations, PDF path when resolvable, and `.zotero-ft-cache` path when present. It never edits the Zotero database. It discovers common Windows, macOS and Linux data directories; use `--data-dir` or `ZOTERO_DATA_DIR` if the Zotero profile is elsewhere. A locked/upgrading database returns a clear failure; retry after Zotero finishes syncing or use the Zotero API/export route.
  68. ### Convert one PDF with MinerU (optional)
  69. ```powershell
  70. python tools/run_mineru_production.py --input "E:\Papers\paper.pdf" --output "E:\ResearchVault\_staging\mineru\ABCD1234-run1"
  71. ```
  72. The output directory must not already exist. The runner preserves the source PDF, writes a hashed working copy, logs the MinerU command, enforces a timeout, and reports success only when MinerU exits cleanly and produces non-empty Markdown. It does not promote output into the Vault; inspect it and use the Fulltext Archiver Skill to create a canonical `03fulltext/...` file. MinerU's CLI must be installed separately. Conversion should work on Windows, macOS or Linux when the selected MinerU executable supports that platform. On Windows, keep the MinerU executable and staging path accessible to the current account; if a specific MinerU build cannot handle non-ASCII paths, choose an ASCII-only `archive_root`.
  73. ### Validate local Vault files
  74. ```powershell
  75. python skills/research-vault-knowledge-maintainer/scripts/validate_research_vault_knowledge.py --vault "E:\ResearchVault"
  76. python tools/validate_research_vault_literature_links.py --vault "E:\ResearchVault"
  77. ```
  78. Both validators are read-only and accept any Vault root. The Knowledge validator checks the frozen page schema and source links. The link validator checks `zotero_key`, `pdf_key`, Note ↔ Fulltext paths, canonical placement and legacy `fulltext/` read fallback.
  79. ### Agent Skills workflow
  80. The repository's Skills guide the agent through paper-level ingestion, analysis, Knowledge decisions, and retrieval. These stages are not one undocumented all-in-one CLI: use the installed Skills from a Codex/compatible agent. A minimal run is: fetch one Zotero parent item → archive/convert its PDF when needed → write its Note from the bundled template → decide whether Knowledge merits an update → run both validators. The Retrieval Skill is Note-first and follows selected evidence through Fulltext to the original Zotero PDF when needed.
  81. Install the standalone Retrieval Skill from [Research-Vault-Literature-Retrieval](https://github.com/cheneternity/Research-Vault-Literature-Retrieval). Its published Skill files mirror the canonical implementation at `skills/research-vault-literature-retrieval/` in this repository; the mirror includes a synchronization check and must be updated with the canonical source.
  82. ## Migration from older Vault layouts
  83. The tools never reorganize an existing Vault automatically. Back up the Vault, then move or copy old files only after confirming their identity and links:
  84. - `论文库/<collection>/` and `note/<collection>/` → `02vault/<collection>/`
  85. - `fulltext/<collection>/<zotero_key>.md` → `03fulltext/<collection>/<zotero_key>.md`
  86. - root literature indexes → `02vault/_index/`
  87. - old `knowledge/` → `01knowledge/` after reviewing `.meta/` sidecars and links
  88. - prior absolute Vault paths (including `D:\ResearchVault`) → relative Vault paths
  89. The validators and retrieval instructions can read historical `fulltext/` links during transition. Update `note_path`, `fulltext_path`, reciprocal links, images, and indexes when files are migrated. Do not create new content in both old and canonical directories.
  90. ## Troubleshooting
  91. | Symptom | What to check |
  92. |---|---|
  93. | Zotero PDF not found | Confirm the parent `zotero_key`, the attachment's `pdf_key`, `storage/<pdf_key>/`, and whether the attachment is linked externally. The helper reports only files that exist. |
  94. | MinerU missing | Configure `paths.mineru_executable` or `MINERU_EXECUTABLE`; verify that it is an executable supported by your MinerU installation. |
  95. | `rg` missing | Optional dependency; use the agent's built-in file search or install ripgrep using your OS package manager. |
  96. | Vault path error | Check `paths.vault_root` or `RESEARCHVAULT_ROOT`; run `python tools/init_vault.py --vault-root <your-path>` to create missing structure. |
  97. | Template missing | Re-run the initializer; it copies only missing templates and leaves existing versions untouched. |
  98. | Knowledge validator fails | Read each `ERROR` code; page `evidence_status` is `fulltext_verified`, `note_only`, or `mixed`. Claim `note_supported` belongs in claim metadata, not page frontmatter. |
  99. | Note ↔ Fulltext validation fails | Check reciprocal `note_path` and `fulltext_path`, key equality, and `03fulltext/` canonical placement. Legacy `fulltext/` may be read during migration. |
  100. | Chinese path / Windows conversion issue | Confirm Python and MinerU have access to the path. If the installed MinerU backend fails on non-ASCII paths, set an ASCII-only `archive_root`; the source PDF remains unchanged. |
  101. | Zotero database is locked | Let Zotero finish sync/upgrade, close Zotero, then retry. The helper never switches to write access. |
  102. ## Tests and CI
  103. Run the dependency-free release smoke tests with `python -m unittest discover -s tests -v`. GitHub Actions runs those tests and Python syntax compilation without requiring a live Zotero profile, MinerU installation, PDF, or private Vault.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.