diff --git a/README.md b/README.md index ac93fed..d565f6f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,34 @@ # QQsci +## Source map 证据来源地图 + +QQsci 现在加入 `source map` 规则，用来记录论文写作中每个 claim、参数、性能表数值、引用建议或 Word 批注建议的原始来源。 + +它解决的问题是：不能只说“这篇文献相关”，而要说明“这篇文献支撑哪句话、哪个参数、来自正文还是 SI、来自图读数还是表格直接报道、是否需要换算、是否只是背景综述”。 + +典型字段包括： + +| 字段 | 含义 | +|---|---| +| ID | 稳定编号，例如 `SM001` | +| Target | 对应的句子、段落、图表行或 Word 批注位置 | +| Claim/value | 被支撑的 claim 或参数 | +| Source | DOI、Zotero key、题名或文件 | +| Location | 页码、章节、Fig.、Table、Scheme、SI Figure/Table | +| Evidence type | 正文直接报道、表格值、图读数、SI 值、计算值、综述背景 | +| Support | strong、partial、background、limiting、contradictory、metadata_only | +| Caveat | 近似读数、单位换算、缺原文、重复引用风险等 | + +使用场景： + +- 写作时追踪 claim-evidence。 +- 做性能对比表时记录参数出处。 +- 查原文时保留 Fig./Table/SI 坐标。 +- 给 Word 加 DOI-only 批注时，把解释放在 Markdown source map 里。 +- 把候选文献交给 qqcites 排序前，先说明每篇文献支撑什么。 + +详细模板见 `references/source-map.md`。 + QQsci 是面向科研论文项目的 Codex 工作流总控 skill。它不是单一写作工具，而是负责调度论文项目中的文献、写作、图表、投稿包检查、引用批注和返修相关流程。 当前重点面向材料科学论文，尤其适合处理： diff --git a/SKILL.md b/SKILL.md index 34fa25e..f742dc4 100644 --- a/SKILL.md +++ b/SKILL.md @@ -45,6 +45,7 @@ screened papers, then have QQsci check the brief before passing it to QQwrite. | [references/review-audit.md](references/review-audit.md) | User asks for reviewer-style critique, rejection-risk audit, novelty check, claim-evidence map, or pre-submission self-review | | [references/comparative-review-audit.md](references/comparative-review-audit.md) | User wants a Nature-response-like pre-review based on comparison with strongly related papers, including missing experiments, format, figures, spelling, and terminology consistency | | [references/submission-package-audit.md](references/submission-package-audit.md) | User provides or mentions a submission package with manuscript, Supporting Information, highlights, cover letter, figures, SI figures, TOC, graphical abstract, or related Word/PPT files | +| [references/source-map.md](references/source-map.md) | User asks where evidence, parameters, figure-derived values, citation suggestions, or manuscript claims came from; use when building performance tables, tracing original-paper data, revising claims with citations, or producing a manuscript evidence map | | [references/literature-routing.md](references/literature-routing.md) | User wants Zotero/Obsidian/DeepSeek note search, strong/weak related-paper screening, keyword extraction, or literature-grounded rewriting | | [references/qqwrite-brief.md](references/qqwrite-brief.md) | DeepSeek screening results need to be converted into a QQwrite writing brief or checked before QQwrite consumes them | | [references/word-citation-comments.md](references/word-citation-comments.md) | User wants citation insertion guidance in Word, reference placement, DOI-only comments, or annotated `.docx` citation suggestions | @@ -95,7 +96,31 @@ placeholders. `enable`, `may`, `could`. 6. Run an overclaim check for novelty, universality, mechanism causality, durability, scalability, and practical relevance. -7. Return polished prose plus concise notes on assumptions and missing inputs. +7. When evidence, citations, parameters, or figure-derived values are involved, + open `references/source-map.md` and keep a source map linking each claim or + value to its original location. +8. Return polished prose plus concise notes on assumptions and missing inputs. + +## Source map requirement + +A `source map` is the evidence-location table for QQsci work. It records which +manuscript claim, parameter, comparison value, or citation suggestion came from +which source and where it appears in that source. + +Use a source map whenever the task involves: + +- citation-supported writing or citation placement +- performance comparison tables +- original-paper parameter extraction +- figure/SI/table-derived values +- reviewer-risk audits that depend on missing or weak evidence +- Word manuscript comments that need DOI-only comments plus a separate Markdown + explanation + +Open `references/source-map.md` for the output schema. Do not cite or reuse a +number only because it appears in a note; preserve the source location, evidence +type, extraction method, and caveat. If the value comes from figure reading or +unit conversion, mark it as approximate and keep the conversion rule. ## Word manuscript editing defaults @@ -158,8 +183,8 @@ DeepSeek/AwesomeGPT Zotero notes generated by QQnote or equivalent sources. 9. For Word manuscript citation suggestions, open `references/word-citation-comments.md` and add native Word comments that contain DOI strings only. -10. Return a source map before or with the manuscript revision. Never cite a - paper only because the title seems similar. +10. Open `references/source-map.md` and return a source map before or with the + manuscript revision. Never cite a paper only because the title seems similar. ## Comparative pre-review workflow diff --git a/references/source-map.md b/references/source-map.md new file mode 100644 index 0000000..61dbd6f --- /dev/null +++ b/references/source-map.md @@ -0,0 +1,102 @@ +# Source Map + +Use this reference when QQsci must explain where a claim, parameter, citation +suggestion, or comparison value came from. + +## Purpose + +A source map is an evidence-location table. It prevents QQsci from treating a +paper, note, or figure as a vague supporting source. Each entry must connect one +manuscript claim or extracted value to a specific source and location. + +Use source maps for: + +- manuscript claim-evidence checks +- citation-supported writing and DOI-only Word comments +- performance comparison tables +- original-paper parameter extraction +- figure, table, and Supporting Information values +- reviewer-risk audits based on missing evidence +- follow-up questions such as `where did this number come from?` + +## Minimum Schema + +| Field | Meaning | +|---|---| +| `source_id` | Stable local ID such as `SM001`, `CIT002`, or `TAB003` | +| `manuscript_target` | Sentence, paragraph, figure claim, table row, or Word comment target | +| `claim_or_value` | The claim, parameter, or citation point being supported | +| `source` | Paper title, Zotero key, DOI, uploaded file, note, or URL | +| `source_location` | Page, section, figure, table, scheme, equation, caption, or SI location | +| `evidence_type` | `direct_text`, `table_value`, `figure_reading`, `SI_value`, `calculated`, `background_review`, `metadata_only` | +| `extraction_method` | Direct quote/paraphrase, manual reading, plot digitization, unit conversion, formula calculation, or note-derived candidate | +| `support_grade` | `strong`, `partial`, `background`, `limiting`, `contradictory`, or `metadata_only` | +| `caveat` | Missing page, approximate value, figure-only reading, unit conversion, reused citation risk, or needs original PDF | +| `next_action` | Use directly, verify original PDF, send to qqcites, ask qqzot, add DOI-only Word comment, or exclude | + +## Compact Output Template + +Use this table by default: + +| ID | Target | Claim/value | Source | Location | Evidence type | Support | Caveat | +|---|---|---|---|---|---|---|---| +| SM001 | Fig. 4 table row | Maximum curvature = xxx cm-1 | DOI / Zotero key | Fig. 4c / SI Note S3 | figure_reading | partial | approximate; needs digitization | + +## Evidence Types + +- `direct_text`: the paper directly states the claim or value in prose. +- `table_value`: the value is directly reported in a table. +- `figure_reading`: the value is read from a plot or image. Mark approximate. +- `SI_value`: the value is in Supporting Information. Give SI figure/table/note. +- `calculated`: QQsci calculated the value from reported data. Keep the formula + and units. +- `background_review`: review article supports broad field context but not a + specific experimental value. +- `metadata_only`: only title, abstract, DOI, or note metadata is available. + Do not use as final support for a specific claim. + +## Routing Rules + +- If the task is citation ranking, send the source map candidates to `qqcites`. +- If the source needs Zotero metadata, item keys, child notes, or local PDF + lookup, use `qqzot`. +- If the output must be organized in Obsidian, use `QQnote-skill` after Zotero + retrieval. +- If Word comments are needed, QQsci decides the citation logic, then QQwrite or + the Word-comment workflow adds DOI-only comments. + +## Rules For Values + +- Preserve the original unit and the normalized unit. +- For curvature, explicitly record whether the source reports `cm-1`, radius, + bending angle, displacement, or a figure-only value. +- For light intensity, keep the original unit such as `mW cm-2`, `W m-2`, or + `sun`. +- For humidity actuation, record RH range, humidity step, maximum curvature, + minimum curvature, and calculated curvature change. +- If a value was converted, show the conversion rule in `caveat` or a short note. +- If the value cannot be verified in the original paper, mark `metadata_only` or + `needs original PDF`; do not present it as confirmed. + +## Rules For Citations + +- One manuscript sentence can map to several source-map rows when it contains + several claims. +- Do not let one paper support unrelated claims only because it is broadly + relevant. +- Mark reused papers when the same DOI has already been assigned to another + nearby sentence. +- Review articles can support background, field status, material families, and + general challenges. Primary papers are preferred for exact experimental + methods, parameters, mechanisms, and performance values. +- Contradictory or limiting evidence should be kept in the map instead of hidden. + +## Final Response Pattern + +For normal manuscript work, return: + +1. Revised or drafted text. +2. Source map table. +3. Missing evidence or verification needs. +4. Handoff notes for `qqcites`, `qqzot`, `QQnote-skill`, or `qqwrite` when + needed.