# 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。它不是单一写作工具，而是负责调度论文项目中的文献、写作、图表、投稿包检查、引用批注和返修相关流程。

当前重点面向材料科学论文，尤其适合处理：

- `Manuscript.docx` 主稿
- `Supplementary Information.docx` 补充信息
- `Figures.pptx` 主图
- `Supplementary Information.pptx` 补充图
- `Highlights.docx`
- `CoverLetter.docx`
- `TOC.pptx`
- Zotero 文献和 QQnote 生成的 AI 文献笔记
- AFM 等材料期刊的投稿要求和整包质控

## 核心定位

```text
科研论文工作流总调度器
```

QQsci 负责判断当前任务应该交给哪个模块，如何传递输入输出，以及最后如何把所有结果合并为一个可投稿的论文包。

## 当前已经具备的能力

- 从主题、初稿、图注、SI 或 cover material 中提取关键词
- 根据文献笔记筛选强相关和弱相关论文
- 使用强相关论文对比检查创新性、机制证据、控制实验和 benchmark
- 检查主稿、SI、Figures、Highlights、Cover Letter、TOC 的整包一致性
- 检查图表逻辑、图注、单位、样品名、术语、拼写和格式问题
- 生成 Markdown 版 reviewer report
- 在 Word 主稿中添加原生批注，批注内容只包含 DOI，一行一个 DOI
- 管理 DeepSeek、Zotero、Obsidian 和 QQnote 的配置继承
- 将 Word 模板化排版任务转交给 QQwrite

QQsci 不直接插入 Zotero Word citation field。对于 Word 主稿，QQsci 只用 Word 原生批注标出 DOI；正式插入引用仍建议使用 Zotero Word 插件。

## QQnote 的角色

QQnote 是 QQsci 的文献输入工具。

QQnote 负责：

- 从 Zotero 条目生成 AI 文献笔记
- 将结果写入 Zotero child note
- 将选中文献总结成 Markdown 对比表
- 审计哪些 Zotero 条目缺少 AI 笔记

QQnote 不负责判断哪篇文献强相关、哪篇文献必须引用、文章创新性是否足够或投稿包是否达标。这些判断都由 QQsci 完成。

当 QQsci 调用 QQnote 时，推荐使用：

```powershell
py "$env:USERPROFILE\.codex\skills\qqsci\scripts\run_qqnote_with_qqsci_config.py" --script summarize_zotero_table -- --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627"
```

这个 wrapper 会读取 QQsci 的本地配置，并把 DeepSeek/Zotero 配置注入为 QQnote 需要的环境变量。

## 配置方式

公开模板：

```text
config/config.template.json
```

真实本地配置：

```text
config/config.local.json
```

不要提交 `config/config.local.json`，不要在聊天、README、日志或终端输出中泄露 API key。

QQsci 会把自己的配置映射到 QQnote 所需环境变量：

| QQsci 配置 | QQnote 环境变量 |
|---|---|
| `deepseek.api_key` | `AWESOMEGPT_API_KEY` |
| `deepseek.base_url` | `AWESOMEGPT_BASE_URL` |
| `deepseek.model` | `AWESOMEGPT_MODEL` |
| `zotero.web_api_key` | `ZOTERO_API_KEY` |
| `zotero.user_id` | `ZOTERO_USER_ID` |

QQnote 单独运行时仍然可以使用自己的环境变量、vault `.env` 或 AwesomeGPT/Zotero preferences。

## 投稿整包检查顺序

对于完整投稿包，QQsci 默认按以下顺序检查：

1. `Manuscript.docx`
2. `Figures.pptx`
3. `Supplementary Information.docx`
4. `Supplementary Information.pptx`
5. `Highlights.docx`
6. `CoverLetter.docx`
7. `TOC.pptx`

主稿和主图决定故事线，SI、Highlights、Cover Letter 和 TOC 必须与它们保持一致。

## 写作模板

QQsci 不再保存 Word 模板资产。Word 模板库和模板化 `.docx` 调整由 QQwrite 负责。

当前 AFM Word 模板位于：

```text
QQwrite/assets/templates/afm/article-template.docx
```

推荐流程：

1. QQsci 先完成证据链、文献定位、目标期刊定位和投稿包风险检查。
2. QQwrite 使用选定 Word 模板调整主稿格式和结构。
3. QQsci 再对调整后的整包做一致性复查。

## 未来模块规划

QQsci 会逐步发展成调度多个专一 skill 的工作流中心：

| 模块 | 规划职责 |
|---|---|
| QQnote | 文献笔记、Zotero child notes、文献对比表 |
| QQwrite | 正文写作、章节重写、Word 模板化成稿 |
| QQfigure | 材料图表、机制图、TOC、图像质控 |
| QQppt | 组会、论文汇报、投稿展示 PPT |
| academic-humanizer | 学术语言去 AI 味、自然化和风格统一 |

在这些模块成熟之前，QQsci 内置的质控模块继续承担论文审稿、证据链检查和整包一致性检查。

## 安装位置

Codex 识别路径：

```text
C:\Users\qyh15\.codex\skills\qqsci
```

源仓库：

[QQsci-skill](https://git.qyhhh.top/Skills/QQsci-skill)

## 依赖和协作 skill

QQsci 当前或未来会依赖/协作以下 skill：

- [QQnote-skill](https://git.qyhhh.top/Skills/QQnote-skill)：Zotero + DeepSeek 文献笔记和文献对比表输入
- [QQwrite-skill](https://git.qyhhh.top/Skills/QQwrite-skill)：Word 模板库和模板化 `.docx` 调整
- `nature-citation`：高质量 DOI 候选和 claim-reference 支撑
- `nature-data`：Data availability、source data、FAIR 和数据仓库检查
- `nature-response`：审稿意见回复和返修信
- `nature-figure`：投稿级科学图表生成和质量检查
- `nature-paper2ppt`：论文到汇报 PPT
- `nature-writing` / `nature-polishing`：Nature 风格写作结构和语言策略参考
- `QQfigure`：未来用于材料图表、TOC 和机制图工作流
- `QQppt`：未来用于组会、论文汇报和投稿展示
- `academic-humanizer`：未来用于学术文本去 AI 味和风格自然化