Add source map workflow

2026-06-09 14:58:20 +08:00 · 2026-06-09 14:58:20 +08:00 · c0f445e4b1
parent 9a5b2e21a9
commit c0f445e4b1
3 changed files with 159 additions and 3 deletions
--- 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。它不是单一写作工具，而是负责调度论文项目中的文献、写作、图表、投稿包检查、引用批注和返修相关流程。

 当前重点面向材料科学论文，尤其适合处理：
--- 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

--- a/references/source-map.md
+++ 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.