From 4a6ee9422daf32a6b828d883f0885309e9e4cedf Mon Sep 17 00:00:00 2001 From: qyh15 Date: Tue, 9 Jun 2026 10:23:32 +0800 Subject: [PATCH] Initialize qqcites skill --- SKILL.md | 87 ++++++++++++++++++++++++++++++++++ agents/openai.yaml | 4 ++ references/citation-ranking.md | 83 ++++++++++++++++++++++++++++++++ 3 files changed, 174 insertions(+) create mode 100644 SKILL.md create mode 100644 agents/openai.yaml create mode 100644 references/citation-ranking.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..5d6ee4d --- /dev/null +++ b/SKILL.md @@ -0,0 +1,87 @@ +--- +name: qqcites +description: Find and rank reference candidates for manuscript sentences by using the user's QQnote-skill, Zotero/Obsidian literature notes, and DeepSeek-assisted local literature screening. Use when the user sends article sentences, claims, paragraphs, or Chinese/English manuscript text and asks for references, citations, supporting papers, related literature, Obsidian-note matches, review-first citation suggestions, or locally grounded citation ranking. +--- + +# QQcites + +Use this skill to turn a manuscript sentence or claim into a ranked list of citation candidates from the user's existing literature notes. Treat QQnote-skill as the first source of local literature context, and use DeepSeek for semantic screening when searching or judging local literature relevance. + +## Workflow + +1. Identify the citation need. + - Split long input into one claim per search unit. + - Extract mechanism, material system, method, performance metric, disease/application, and comparison terms. + - Preserve the user's wording so the final answer can map references back to the exact sentence. + +2. Check the current manuscript citation ledger before searching. + - If a manuscript-specific `used_references.md`, `used_references.csv`, or extracted citation list is available, read it before ranking candidates. + - Treat DOI, Zotero item key, title, and normalized first-author/year as duplicate-detection keys. + - If no ledger exists, infer recent used references from the current conversation and recommend creating a ledger rather than relying on memory. + - Zotero and Obsidian identify candidate papers; the ledger or manuscript citation fields identify papers already used in this manuscript. + +3. Load QQnote-skill before searching. + - Read `C:\Users\qyh15\.codex\skills\QQnote-skill\SKILL.md` if available. + - If that installed path is unavailable, read the project copy at `E:\11 AI\01 Codex\01 Skills\QQnote-skill\SKILL.md`. + - Use QQnote's documented Zotero/Obsidian workflow and scripts rather than inventing a separate literature-note pipeline. + +4. Search local Obsidian literature notes first. + - Default vault: `C:\Users\qyh15\Documents\Obsidian Vault`. + - Prefer generated literature notes under QQnote's literature-note folders. + - Use exact keywords, translated Chinese/English equivalents, acronyms, material names, and mechanism terms. + - Prefer `rg` for text search when the vault is accessible. + +5. Use web search only when local literature is insufficient. + - Default to local QQnote/Obsidian/Zotero evidence first. + - If local notes produce too few or weak candidates, supplement with web literature search and clearly label web-only candidates. + - Do not replace strong local evidence with web results unless the web result is clearly more relevant or more authoritative. + +6. Use DeepSeek for local semantic screening. + - When deciding which local notes or papers are relevant, send the manuscript claim plus candidate note snippets to DeepSeek through the user's configured QQnote/AwesomeGPT/DeepSeek route. + - Ask DeepSeek to classify each candidate as direct support, partial support, background/review support, contradictory/weak, or unrelated. + - Do not use DeepSeek to fabricate citations. It may rank and explain local candidates only from supplied note text, Zotero metadata, abstracts, or extracted local PDF text. + - If DeepSeek access is unavailable, report that screening was not run and provide the best deterministic local-search ranking. + +7. Rank candidates by manuscript usefulness. + - Rank by direct claim support first. + - Within similar relevance, put review articles before primary research when the user needs background, broad motivation, mechanism overview, or field status. + - Put primary research before reviews when the sentence makes a specific experimental, material, performance, or mechanistic claim that needs original evidence. + - Force review-only or review-priority ranking only when the user explicitly asks for reviews, "需要综述", or "综述优先". + - Apply citation-ledger duplicate control before final ranking: when the user says "不要重复", "不重复", or flags a repeated item, exclude previously used DOI/Zotero keys unless the item is explicitly unavoidable. + - When repetition is allowed but discouraged, demote previously used papers and prefer unused local candidates with comparable relevance. + - Penalize papers that only match broad keywords without supporting the sentence. + +8. Verify citation metadata. + - Prefer Zotero metadata from QQnote/Zotero when available. + - Include DOI when available. + - Do not invent missing DOI, year, journal, or title. + - Mark uncertain metadata as `metadata incomplete`. + +9. Update or propose updates to the citation ledger after recommending references. + - For every recommended paper, record sentence/claim, DOI, Zotero key, title, year, type, source (`local`, `web`, or `uncertain`), and why it was used. + - If file editing is not requested or the ledger path is unknown, include a compact "used-reference log" block in the answer so it can be appended later. + - Keep the ledger manuscript-specific; do not globally ban papers across unrelated manuscripts or projects. + +## Output + +For each user sentence, return: + +- `Sentence`: the exact sentence or claim being supported. +- `Best citations`: ranked candidates with title, year, journal, DOI if available, and source note path or Zotero key when available. +- `Why relevant`: one concise reason tied to the sentence. +- `Type`: `review`, `primary research`, `method`, `dataset`, or `unclear`. +- `Strength`: `direct`, `partial`, `background`, or `weak`. +- `Suggested citation use`: where the paper should be cited in the sentence or paragraph. + +Read [references/citation-ranking.md](references/citation-ranking.md) when the task involves multiple sentences, many candidate notes, tie-breaking, or final table formatting. +Also read it when the user asks for performance comparison tables, literature tables, parameter extraction from original papers, unit normalization, graph-derived values, or inclusion/exclusion decisions for main-table versus supplemental-table references. + +## Operating Rules + +- For manuscript citation work, avoid duplicate references by checking a manuscript-specific ledger or citation-field extraction before ranking. Zotero library membership alone is not evidence that a paper has already been cited in the manuscript. +- Default duplicate policy: exact DOI/Zotero-key repeats are disallowed when the user asks for non-repetition; otherwise they are allowed only when the repeated paper is clearly the best or only support, and must be labeled as repeated. +- Keep results grounded in local QQnote/Obsidian/Zotero evidence first; if local notes are insufficient, supplement with web literature search and label those candidates as web-sourced. +- Only force review articles when the user explicitly says "需要综述", "综述优先", or otherwise asks for reviews; otherwise rank by the citation need and allow primary research to outrank reviews for specific experimental or mechanistic claims. +- If local notes are thin, say so and suggest generating or refreshing QQnote notes for the relevant Zotero items. +- Never expose API keys, AwesomeGPT settings, Zotero API keys, or private vault contents unrelated to the user's query. +- When citing Word manuscripts later, keep Word comments DOI-only if the user asks for inline citation comments; put explanations in Markdown. diff --git a/agents/openai.yaml b/agents/openai.yaml new file mode 100644 index 0000000..a0c80f8 --- /dev/null +++ b/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "QQcites" + short_description: "Find ranked citation candidates from QQnote and Obsidian notes" + default_prompt: "Use QQcites to find reference candidates for this manuscript sentence from QQnote/Obsidian notes, prioritize reviews, and rank by relevance." diff --git a/references/citation-ranking.md b/references/citation-ranking.md new file mode 100644 index 0000000..af43091 --- /dev/null +++ b/references/citation-ranking.md @@ -0,0 +1,83 @@ +# QQcites Citation Ranking + +Use this reference when a request has more than one claim, many local-note hits, or ambiguous citation choices. + +## Candidate Search Pattern + +Search each claim with four groups of terms: + +1. Core nouns: material, molecule, device, disease, target, method, or phenomenon. +2. Mechanism verbs: drives, activates, suppresses, coordinates, adsorbs, transports, degrades, detects, heals, oxidizes, reduces. +3. Performance words: sensitivity, stability, conductivity, capacity, selectivity, efficiency, biocompatibility, degradation, response time. +4. Synonyms and translations: Chinese terms, English terms, abbreviations, chemical formulas, and common aliases. + +Use several narrow searches instead of one broad search. Example: + +```powershell +rg -n -i "MXene|Ti3C2|conductivity|electromagnetic shielding" "C:\Users\qyh15\Documents\Obsidian Vault\01 文献阅读" +``` + +Adjust the vault subfolder if QQnote-skill documents a different current literature-note folder. + +## DeepSeek Screening Prompt + +When DeepSeek is available, pass only the manuscript claim and candidate snippets needed for ranking: + +```text +Task: Rank local literature-note candidates for supporting one manuscript sentence. + +Manuscript sentence: + + +Candidate notes: + + +For each candidate, judge: +1. relevance: direct, partial, background/review, weak, unrelated +2. article type: review, primary research, method, unclear +3. whether it truly supports the sentence or only shares keywords +4. one-sentence reason + +Return a ranked list. Prefer review articles for broad background claims, but prefer primary evidence for specific experimental or mechanistic claims. +Do not invent metadata or references not present in the candidates. +``` + +## Tie-Breaking + +Rank candidates using this order: + +1. Direct support for the exact claim. +2. Stronger article type for the sentence purpose: + - review first for broad field status, motivation, classification, mechanisms overview, or "recent advances" wording. + - primary research first for exact material composition, synthetic method, measurement, performance number, biological effect, or device result. +3. Newer review if two reviews provide similar background coverage. +4. Higher-quality note evidence: abstract plus detailed AI note beats title-only or metadata-only matches. +5. DOI and complete Zotero metadata available. + +## Final Table Template + +Use this compact table for most answers: + +| Rank | Citation candidate | Type | Strength | Why it fits | Suggested use | +|---:|---|---|---|---|---| +| 1 | Title. Journal, Year. DOI: ... | review | direct/background | ... | Cite after clause ... | + +If a sentence has no strong local match, write `No strong local match found` and list the closest weak candidates separately. + +## Performance Comparison Tables + +When the user asks for a literature performance table, define hard inclusion criteria before recommending papers. Typical criteria include material family, stimulus type, whether the paper is primary research, whether the target metric is reported, whether units can be normalized, and whether the item is present in local Zotero/Obsidian. Put only papers that satisfy the table criteria in the main table. Papers that report only angle, displacement, speed, demonstration photos, or concept-level behavior should be listed as supplemental or non-comparable unless the user explicitly wants them. + +Extract performance parameters from the local Zotero PDF whenever possible. Record the evidence level for every number: `main text`, `figure caption`, `supporting information`, `graph digitization`, `abstract only`, or `calculated`. If a value requires graph reading, label it as `needs digitization` until the figure has actually been digitized. Do not present graph-estimated values as directly reported values. + +Normalize units before comparison. Use `cm^-1` for curvature (`1 mm^-1 = 10 cm^-1`) and `mW cm^-2` for light intensity (`1 W cm^-2 = 1000 mW cm^-2`). If the paper reports total optical power rather than power density, label it as `total power, not normalized` and do not convert it to `mW cm^-2` without the illuminated area. Keep maximum temperature, temperature rise, and photothermal conversion efficiency as separate metrics. + +For angle-only actuator data, convert to curvature only when the effective bending length is known and the geometry makes the conversion defensible. Use `kappa = theta(rad) / L(cm)` and record the length and source. If the effective length is missing, write `not convertible from main text` rather than forcing a number. + +Default table triage: + +- `main-table usable`: primary research, target material/stimulus, directly reports the target metric or supports a defensible unit conversion. +- `supplemental comparison`: relevant material/stimulus but reports a different metric such as angle, speed, displacement, or application behavior. +- `not recommended`: review, wrong stimulus, non-target material family, no performance metric, or only broad background relevance. + +Maintain a manuscript-specific performance-table ledger in addition to the citation ledger. Track table name, DOI, Zotero key, title, material system, metric values, evidence level, whether it was used in the main or supplemental table, and any caveats such as `figure only`, `angle-only`, or `total power`.