148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# QQnote-skill
|
|
|
|
QQnote-skill is a Zotero + Obsidian literature-note tool for Codex. It generates
|
|
AI literature notes from Zotero items, writes them as Zotero child notes, audits
|
|
missing generated notes, and maintains Obsidian literature-note views.
|
|
|
|
QQnote is intentionally narrow: it prepares literature-note inputs. It does not
|
|
decide manuscript novelty, target-journal positioning, strong/weak related-paper
|
|
status, reviewer risk, or citation necessity. Those decisions belong to QQsci
|
|
when QQnote is used inside the QQsci workflow.
|
|
|
|
## Core Workflows
|
|
|
|
### Initialize Private Config
|
|
|
|
Use local-only config for Zotero and DeepSeek/AwesomeGPT keys:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\init_private_config.py"
|
|
```
|
|
|
|
The committed template is:
|
|
|
|
```text
|
|
config/config.template.json
|
|
```
|
|
|
|
The real local file is:
|
|
|
|
```text
|
|
config/config.local.json
|
|
```
|
|
|
|
Do not commit `config/config.local.json`, print secrets, or paste API keys into
|
|
chat.
|
|
|
|
### Generate Zotero Child Notes
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
|
|
```
|
|
|
|
Use this when a Zotero item needs an AI-generated child note. For long runs,
|
|
prefer small batches and rerun with `--skip-existing` after interruptions.
|
|
|
|
For deeper notes, use the full-detail mode supported by the installed script,
|
|
for example:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --mode deep --fulltext-chars 80000 --max-tokens 12000 --replace-existing
|
|
```
|
|
|
|
### Audit Missing Generated Notes
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
|
```
|
|
|
|
Use deterministic audit scripts for library state. Do not ask DeepSeek to decide
|
|
which Zotero items are missing notes.
|
|
|
|
## Relationship With QQsci
|
|
|
|
When used by QQsci:
|
|
|
|
1. QQsci identifies which literature inputs are needed.
|
|
2. QQnote generates or refreshes Zotero child notes.
|
|
3. QQsci performs keyword extraction, strong/weak related-paper screening,
|
|
target-journal positioning, comparative audit, manuscript revision, and Word
|
|
DOI-only citation comments.
|
|
|
|
QQnote should not decide whether a paper is strongly related, weakly related,
|
|
required for citation, or sufficient as reviewer evidence.
|
|
|
|
QQsci may call QQnote through a wrapper that injects QQsci-level DeepSeek and
|
|
Zotero configuration into QQnote's expected environment variables.
|
|
|
|
## Standalone Configuration
|
|
|
|
QQnote must also remain usable independently. In standalone mode it reads:
|
|
|
|
- process environment variables
|
|
- local private config
|
|
- vault `.env`, if supported by the installed script
|
|
- AwesomeGPT/Zotero profile preferences
|
|
|
|
Expected environment variables include:
|
|
|
|
- `AWESOMEGPT_API_KEY`
|
|
- `AWESOMEGPT_BASE_URL`
|
|
- `AWESOMEGPT_MODEL`
|
|
- `ZOTERO_API_KEY` for Zotero Web API writes
|
|
- `ZOTERO_USER_ID` when needed
|
|
|
|
Never store API keys in `SKILL.md`, references, committed files, zip files,
|
|
terminal output, or chat. If keys appear in chat or logs, rotate them.
|
|
|
|
## Obsidian Notes
|
|
|
|
Read these references before modifying Obsidian behavior:
|
|
|
|
- `references/obsidian-integration.md`
|
|
- `references/obsidian-literature-maintenance.md`
|
|
|
|
Default vault:
|
|
|
|
```text
|
|
C:\Users\qyh15\Documents\Obsidian Vault
|
|
```
|
|
|
|
Default organization includes:
|
|
|
|
- `00 Templater`: source templates, prompts, and audit cache
|
|
- literature-note folders exported or linked from Zotero
|
|
- Dataview dashboards for browsing literature
|
|
|
|
## Repository Contents
|
|
|
|
```text
|
|
.
|
|
|-- SKILL.md
|
|
|-- README.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
|
|
```
|
|
|
|
## Installed Location
|
|
|
|
For Codex discovery, install under:
|
|
|
|
```text
|
|
C:\Users\qyh15\.codex\skills\QQnote-skill
|
|
```
|
|
|
|
Keep source and installed copies synchronized when updating scripts or
|
|
documentation.
|