# QQnote-skill

QQnote-skill 是一个面向 Zotero + Obsidian 文献工作流的 Codex skill。它的核心任务是使用 DeepSeek/AwesomeGPT 从 Zotero 文献条目生成 AI 文献笔记，并将结果写入 Zotero child note，或者把选中文献整理成 Markdown 对比表。

QQnote 的定位很窄：它只负责生成和维护文献笔记输入，不负责论文层面的判断。

## 核心职责

QQnote 负责：

- 读取 Zotero 文献元数据、摘要、附件全文或可用的本地全文
- 调用 DeepSeek/AwesomeGPT 生成 AI 文献笔记
- 将笔记写入 Zotero child note
- 批量处理多个 Zotero 条目
- 跳过或替换已有 AI 笔记
- 审计哪些 Zotero 条目缺少 AI 笔记
- 维护 Obsidian 文献笔记和 Dataview 相关辅助内容

QQnote 不负责判断某篇文献是否强相关、是否必须引用、论文创新性是否足够、reviewer 是否会接受某个证据链，也不检查投稿包、图表、SI、Cover Letter 或 TOC。这些论文层面的判断应交给 QQsci。

## 初始化本地配置

公开配置模板：

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

真实本地配置：

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

可以用脚本初始化：

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\init_private_config.py"
```

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

## 生成 Zotero child note

单篇文献：

```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
```

多篇文献：

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --limit 0 --skip-existing --fulltext-chars 4000
```

深度精读或满血版本：

```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
```

批量运行时建议每次处理 20-30 篇，并使用 `--skip-existing` 或 `--replace-existing` 避免重复写入 Zotero child note。

## 审计缺失笔记

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
```

文献库状态、缺失笔记和重复检测应使用确定性脚本完成，不要让 DeepSeek 自由判断。

## 文献对比表

如果安装版本包含 `summarize_zotero_table.py`，可以用它把选中文献整理成 Markdown 表格：

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\summarize_zotero_table.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627" --batch-size 3 --out "C:\Users\qyh15\Documents\Obsidian Vault\99 misc\literature-comparison-table.md"
```

这个表格只是给 QQsci 或作者使用的结构化输入，不等于最终论文判断。

## 与 QQsci 的关系

当 QQnote 被 QQsci 调用时：

1. QQsci 决定需要哪些文献输入。
2. QQnote 生成 Zotero child note 或 Markdown 文献表。
3. QQsci 使用这些笔记和表格进行关键词提取、强弱相关筛选、目标期刊定位、比较式审稿、正文修改和 Word DOI-only 批注。

QQnote 可以单独使用；QQsci 调用 QQnote 时，也可以通过 wrapper 注入 QQsci 级别的 DeepSeek/Zotero 配置。

## 独立运行配置

QQnote 独立运行时可以读取：

- 进程环境变量
- 本地私有配置
- vault `.env`
- AwesomeGPT/Zotero profile preferences

常用环境变量包括：

- `AWESOMEGPT_API_KEY`
- `AWESOMEGPT_BASE_URL`
- `AWESOMEGPT_MODEL`
- `ZOTERO_API_KEY`
- `ZOTERO_USER_ID`

## Obsidian 相关文件

修改 Obsidian 模板、Dataview 或文献库维护逻辑前，先阅读：

- `references/obsidian-integration.md`
- `references/obsidian-literature-maintenance.md`

默认 vault：

```text
C:\Users\qyh15\Documents\Obsidian Vault
```

## 安装位置

Codex 识别路径：

```text
C:\Users\qyh15\.codex\skills\QQnote-skill
```

远程仓库：

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

## 依赖和协作 skill

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

- [QQsci-skill](https://git.qyhhh.top/Skills/QQsci-skill)：科研论文工作流总调度器，消费 QQnote 生成的文献笔记和文献表格
- `zotero`：Zotero 本地 API、Zotero Web API、BibTeX/条目读取等底层能力
- `google-drive`：当文献 PDF 或论文库位于 Google Drive 时，用于定位和读取文件
- `nature-reader`：未来可用于将新文献做全文阅读、图表定位和中英对照，再交给 QQnote 生成笔记
- `nature-citation`：未来可用于把 QQnote 文献结果进一步转成 DOI 候选和 claim-reference 支撑
- `QQwrite`：未来可消费 QQnote 的文献笔记，用于正文写作和段落重写