name: reference-manager description: > 文献管理 5-in-1 Skill: 领域深度调研 + 系统文献综述 + 全文下载 + 稿件引用插入 + 引用验证。 触发条件: 用户说"/ref research"、"/ref review"、"/ref insert"、"/ref verify"、"/ref download"， 或说"深度调研/文献调研"、"文献综述/系统综述"、"插文献/加引用/补充参考文献"。 domain: 学术管线 triggers:

• /ref research
• /ref review
• /ref insert
• /ref verify
• /ref download neighbors:
• research-strategy（上游: 文献检索辅助新颖性评估）
• manuscript-drafter（下游: 综述结果和引用直接用于稿件）
• paper-pipeline（编排: 管线内可作为背景研究和引用插入步骤） allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch

Reference Manager — 文献管理（5-in-1）

合并自: literature-review + academic-reference-inserter + crossref-verifier + paper-downloader v4.0: 新增 /ref research — 从 manuscript-drafter Phase 0b 迁入，成为 literature 模块的认知层

核心定位

literature 模块 = 稿件的知识地基。 两层能力互补：

• 认知层（/ref research）：Deep Research 理解领域前沿、方法争议、学术演进
• 证据层（/ref review → /ref download → /ref insert → /ref verify）：找到可引用的真实文献，确保零幻觉

两层结合 → manuscript-drafter 拿到的是"前沿认知 + 真实引用"，保证初稿的 Introduction 前沿、Methods 有据、Discussion 深度。

边界声明

本 Skill 覆盖文献相关的五个核心场景:

与其他 Skill 的边界:

• research-strategy: 文献检索结果可辅助 /research idea 的新颖性评估，但综述本身由本 Skill 完成
• manuscript-drafter: 本 Skill 提供 literature_summary.md（知识地基），manuscript-drafter 基于此写稿。Phase 0b 已迁移至本 Skill 的 /ref research

消歧规则

子命令 0: /ref research — 领域深度调研（认知层）

迁移自: manuscript-drafter Phase 0b（v1.1-v1.3）

核心理念

先有结果和故事线，再找文献支撑。 统计结果 + 研究设计已通过 CP-2 审查后，Deep Research 才启动。此时你精确知道需要什么文献：Introduction 的背景、Methods 的方法引用、Discussion 的结果对比。一次到位，不做第二次。

前置条件（硬约束 O6）

必须满足:
  1. statistics 模块已完成 → analysis_results.md 存在
  2. CP-2 已通过 → cp2_decision.md 存在且判定为通过/条件通过
  3. research_design.md 存在

如不满足 → 阻断，提示"请先完成统计分析并通过 CP-2 审查"

架构

Layer 1: Agent Deep Research（学术判断力）
  → 基于已确定的结果和故事线，识别经典文献、梳理学术演进、给出 must-cite 列表
Layer 2: API 验证（元数据补全）
  → CrossRef/Semantic Scholar 验证 DOI、引用量、论文真实性

激活条件

- statistics + CP-2 通过后执行（literature 模块的第一步）
- 已有 outputs/literature_summary.md 且修改时间 < 7 天 → 跳过，提示复用
- Agent 调用失败 → 回退到纯 SS API 搜索（降级模式）

步骤

R.1 提取核心检索主题（3-5 个）

从以下来源提炼检索主题——关键：基于已有的统计结果，而非泛泛的研究方向：

• outputs/analysis_results.md — 主效应方向/大小、有意义的亚组、敏感性分析结论
• outputs/research_design.md — 研究问题、方法选择、协变量策略
• outputs/data_dictionary.md — 变量定义和数据结构
• docs/CLAUDE.md / 客户需求 — 暴露变量、结局变量

提炼维度（每个项目取 3-5 个，去重，由结果驱动）：

[T1] 疾病流行病学   — 疾病名称 + "prevalence" / "burden" / "epidemiology"
[T2] 研究方法引用   — 本研究用的统计方法 + 该方法在本领域的应用（如 "Fine-Gray competing risk heart failure"）
[T3] 同类结果对比   — 暴露变量 + 结局变量 + 效应方向（如 "NT-proBNP tertile mortality HR"）← 从主分析结果来
[T4] 有意义的亚组   — 从亚组分析中有统计显著性或临床意义的结果提取（如 "LVEF subgroup NT-proBNP"）
[T5] 机制解释       — 结果背后的生物学/临床机制（为 Discussion 服务）

R.2 Agent Deep Research（核心步骤）

使用 Agent 工具（subagent_type=deep-research-agent）执行深度文献研究。

Agent 提示词模板：

你是学术文献研究专家。请基于以下已确定的研究结果，进行精准的文献调研：

研究领域: [从 R.1 提取的领域描述]
核心主题: [T1-T5 列表]

本研究已确定的关键结果（供精准检索用）:
- 主效应: [从 analysis_results.md 提取，如 "NT-proBNP 最高三分位 vs 最低: HR=2.15, 95%CI 1.42-3.26"]
- 统计方法: [如 "Cause-specific Cox + Fine-Gray competing risk"]
- 有意义的亚组: [如 "LVEF<40% 亚组中关联更强"]
- Discussion 需对比的维度: [如 "同类研究的 HR 范围、竞争风险方法的应用"]

任务要求:
1. 识别该领域的 **必引经典文献**（奠基论文、里程碑论文、最新权威综述/元分析）
2. 梳理 **学术思想演进脉络**（哪篇论文引出了哪个概念，后续如何发展）
3. **重点寻找可直接与本研究结果对比的论文**（同暴露/同结局/同方法，报告了类似效应量的研究）
4. 对每篇论文标注优先级:
   - ★★★ 必引: 审稿人必定期望看到的论文（领域定义、首次临床证据、权威元分析）
   - ★★☆ 重要: 机制拓展、方法论贡献、关键纵向证据
   - ★☆☆ 背景: 有价值但非必需的补充文献
5. 对每篇标注 **稿件用途**: Introduction背景 / Methods方法引用 / Discussion对比 / Discussion机制
6. 每篇给出: 第一作者、年份、标题、期刊、核心贡献（1句话）
7. 总量控制在 20-30 篇

搜索策略:
- 使用 WebSearch 搜索领域综述和经典引用
- 使用 Semantic Scholar API 补充元数据和引用量
- 优先寻找高引用量的奠基文献，不要偏向最新低引论文
- 交叉验证: 至少从两个来源确认每篇论文的真实存在

输出格式: JSON 数组，每个元素包含:
{
  "first_author": "Barrett",
  "year": 2001,
  "title": "完整标题",
  "journal": "期刊名",
  "doi": "10.xxxx/...",
  "citation_count": 1032,
  "priority": 3,
  "contribution": "情绪分化概念的正式定义",
  "topic": "T1",
  "usage": "Introduction背景",
  "verified_by": "SS+WebSearch"
}

R.3 API 验证与元数据自动修正

对 Agent 返回的每篇论文，调用 CrossRef API 验证，含自动修正机制：

验证逻辑（三步递进）:

Step 1: DOI 直查
  - CrossRef API 查询 DOI → 核对作者+年份
  - 完全匹配 → OK
  - 作者匹配但年份差1年（online-first vs print）→ CORRECTED_YEAR，自动修正年份
  - 作者不匹配（DOI 指向了不同论文）→ 进入 Step 2

Step 2: 标题反查
  - 用标题关键词搜索 CrossRef（query=作者+标题前80字符，rows=5）
  - 用词汇重合度（>=0.6）匹配最佳结果
  - 找到匹配 → CORRECTED_DOI，自动修正 DOI 和年份
  - 未找到 → 用纯标题实义词再搜一次
  - 仍未找到 → UNVERIFIED，需人工检查

Step 3: 分类与处理
  - OK / CORRECTED → 进入最终列表
  - UNVERIFIED → 保留但标记，不自动移除（Agent deep research 的论文极少真幻觉）

验证 URL:

CrossRef DOI查询:   https://api.crossref.org/works/{DOI}
CrossRef 标题搜索:  https://api.crossref.org/works?query={keywords}&rows=5
SS 备用搜索:        https://api.semanticscholar.org/graph/v1/paper/search?query={title}&limit=3&fields=title,authors,year,externalIds,citationCount

R.4 输出 literature_summary.md

将验证通过的结果写入 outputs/literature_summary.md：

# Literature Summary
**Generated**: [date]
**Method**: Agent Deep Research + CrossRef Auto-Correction
**Total References**: [N] (direct OK: [a], auto-corrected: [b], unverified: [c])

---

## 学术演进脉络

[2-3 句话描述该领域的核心学术发展线]

## 必引文献 (★★★)

| 标题 | 作者 | 期刊 | 年份 | 引用数 | DOI | 核心贡献 | 验证状态 |
|------|------|------|------|--------|-----|---------|---------|
| ... | ... | ... | ... | ... | ... | ... | OK/CORRECTED |

## 重要文献 (★★☆)

[同上格式]

## 背景文献 (★☆☆)

[同上格式]

## 验证日志

- 总计研究: [N] 篇
- 直接通过: [a] 篇
- 自动修正: [b] 篇（DOI/年份已修正）
- 未验证: [c] 篇（需人工确认）

R.5 学术演进图生成

基于 R.2 的文献列表，调用 /diagram framework 生成学术演进时间线图：

工具: AiCodeWith Gemini 图片生成 API
端点: POST https://api.with7.cn/api/image/gemini/v1beta/models/gemini-3-pro-image-preview:generateContent
认证: Bearer $AICODEWITH_API_KEY（从 ~/.openclaw/credentials/.env 读取）
输入: 文献列表 + 学术演进脉络描述
输出: outputs/academic_evolution_diagram.png

请求格式:
  {
    "contents": [{"role": "user", "parts": [{"text": "<prompt>"}]}],
    "generationConfig": {"temperature": 0.8, "maxOutputTokens": 8192}
  }

响应: candidates[0].content.parts[] 中包含 inlineData（base64 图片）或 text

Prompt 模板:
  - 水平时间线，从左到右
  - 按学术阶段分色带（pastel 色系）
  - KEY 里程碑论文用大圆点突出
  - 底部附加测量方法演进线和因果方向争论图
  - 风格: 白底、sans-serif、细线、学术出版级

此图可用于:

• 论文 Introduction 的学术背景梳理参考
• 组会/答辩 PPT 的领域概览
• Graphical Abstract 的素材

R.6 降级方案（Agent 不可用时）

如果 Agent 调用失败，回退到纯 Semantic Scholar API 搜索：

• 对 R.1 中的每个主题，调用 SS API（limit=10, sort by citation count）
• 保留 citationCount >= 20 且有 DOI 的论文
• 标注"降级模式: 可能遗漏经典文献，建议人工补充"
• 跳过演进图生成

子命令 1: /ref review — 系统文献综述

原 Skill: ~/.claude/skills/literature-review/SKILL.md

核心工作流（7 阶段）

Phase 1: 规划与范围界定
    - 用 PICO 框架定义研究问题
    - 确定综述类型（叙述性/系统性/范围性/Meta分析）
    - 制定搜索策略: 2-4 核心概念 + 同义词 + Boolean
    - 设定纳入/排除标准

Phase 2: 系统文献检索
    - 多数据库搜索（至少3个）
    - 生物医学: PubMed(gget) + bioRxiv(gget) + Semantic Scholar(API)
    - 通用: OpenAlex + CrossRef + arXiv
    - 记录检索参数: 数据库/日期/检索串/结果数

Phase 3: 筛选与选择
    - 去重（DOI 优先 / 标题备选）
    - 三级筛选: 标题 -> 摘要 -> 全文
    - 生成 PRISMA 流程图
    - 记录每级排除数量和原因

Phase 4: 数据提取与质量评估
    - 提取: 元数据 + 设计方法 + 样本 + 关键发现 + 局限
    - 质量工具: RCT用Cochrane / 观察性用NOS / 系统综述用AMSTAR2
    - 按主题分组（3-5 个主题）

Phase 5: 综合与分析
    - 主题式综合（非逐篇总结）
    - 交叉比较不同研究的方法和结果
    - 识别共识/争议/缺口
    - Discussion: 解释发现 + 临床意义 + 综述局限

Phase 6: 引用验证
    - 用 verify_citations.py 批量验证 DOI
    - 确认作者/标题/期刊/年份元数据一致
    - 支持引用格式: APA / Nature / Vancouver / Chicago / IEEE

Phase 7: 文档生成
    - Markdown 输出（主要）
    - 可选 PDF 输出（pandoc + xelatex）

高影响力论文优先策略

期刊优先级: Tier1(Nature/Science/Cell/NEJM) > Tier2(IF>10专刊) > Tier3(IF 5-10) > Tier4(低分同行评审)

质量检查清单

• 所有 DOI 已通过 verify_citations.py 验证
• 引用格式统一
• PRISMA 流程图已包含（系统综述）
• 检索方法论完整记录
• 纳入/排除标准清晰
• 结果按主题组织（非逐篇）
• 质量评估已完成
• 局限性已声明

路径引用

• 综述模板: ~/.claude/skills/literature-review/assets/review_template.md
• 引用格式指南: ~/.claude/skills/literature-review/references/citation_styles.md
• 数据库策略: ~/.claude/skills/literature-review/references/database_strategies.md
• 脚本:
  • ~/.claude/skills/literature-review/scripts/verify_citations.py — DOI 验证
  • ~/.claude/skills/literature-review/scripts/generate_pdf.py — PDF 生成
  • ~/.claude/skills/literature-review/scripts/search_databases.py — 结果聚合去重

子命令 2: /ref insert — 稿件引用插入

原 Skill: ~/.claude/skills/academic-reference-inserter/SKILL.md

铁律

1. 绝不捏造引用。 每篇论文必须通过至少一个 API 验证
2. 双重交叉验证: 至少两个数据库确认后才插入
3. 保留已有引用: 不删除不修改，除非确认为重复
4. 保守引用: 每个论断 1-3 篇，不过度引用
5. 透明操作: 向用户展示每条新增引用及其理由

核心工作流（6 阶段）

Phase 1: INTAKE — 理解稿件
    - 读取稿件，确定目标期刊和引用格式
    - 统计现有引用数量
    - 提取关键主题和研究领域
    - 加载格式模板: FORMATS.md

Phase 2: SCAN — 扫描缺引用位置
    - 识别需要引用的句型:
      统计论断 / 理论陈述 / 方法引用 / 背景事实 / 比较论断 / 流行病学数据
    - 对每个位置记录: 原文 + 所需引用类型 + 搜索关键词
    - 输出 Citation Needs List 供用户审核

Phase 3: SEARCH — 多数据库搜索
    - 数据库优先级:
      生物医学: PubMed -> OpenAlex -> Semantic Scholar
      计算机科学: Semantic Scholar -> arXiv -> OpenAlex
      综合: OpenAlex -> CrossRef -> PubMed
    - 每个需求构造 2-3 组关键词
    - 优先: 近10年 + 高引用 + 权威期刊

Phase 4: SELECT — 选择并验证
    - 每个需求选 1-3 篇，按 相关性 -> DOI验证 -> 引用数 -> 时效性 -> 期刊质量 排序
    - DOI 验证: CrossRef API 确认元数据一致
    - 可选批量验证: scripts/verify_references.py
    - 呈现候选列表供用户批准

Phase 5: INSERT — 插入引用
    - 按目标期刊格式插入行内引用
    - 构建/扩展参考文献列表
    - 编号式引用: 插入后重新排序
    - 保留所有已有引用

Phase 6: VERIFY — 质量保证
    - 行内引用 <-> 参考文献列表双向匹配
    - 无重复引用
    - 格式一致性
    - DOI 格式正确
    - 输出 Summary Report

自动插入模式（管线集成）

当 paper-pipeline 调用或用户说"自动插入文献"时启用:

评分维度: 相关性(40%) + 引用数(20%) + 时效性(15%) + 期刊质量(15%) + 跨库确认(10%)

使用提示

• 中文稿件用英文技术术语搜索
• 综述文章目标 60-100+ 篇引用，实证文章 30-60 篇
• 用户说"补充到N篇"指总数达到 N
• 相关引用合并: (Author1, Year; Author2, Year; Author3, Year)

路径引用

• 数据库 API 文档: ~/.claude/skills/academic-reference-inserter/DATABASES.md
• 引用格式模板: ~/.claude/skills/academic-reference-inserter/FORMATS.md
• BibTeX 模板: ~/.claude/skills/academic-reference-inserter/bibtex_template.bib
• 引用检查清单: ~/.claude/skills/academic-reference-inserter/citation_checklist.md
• 参考资料: ~/.claude/skills/academic-reference-inserter/references/
  • pubmed_search.md, google_scholar_search.md, metadata_extraction.md 等
• 脚本:
  • ~/.claude/skills/academic-reference-inserter/scripts/verify_references.py — 批量 DOI 验证
  • ~/.claude/skills/academic-reference-inserter/scripts/search_pubmed.py — PubMed 搜索
  • ~/.claude/skills/academic-reference-inserter/scripts/search_google_scholar.py — Google Scholar 搜索
  • ~/.claude/skills/academic-reference-inserter/scripts/extract_metadata.py — 元数据提取
  • ~/.claude/skills/academic-reference-inserter/scripts/doi_to_bibtex.py — DOI 转 BibTeX
  • ~/.claude/skills/academic-reference-inserter/scripts/format_bibtex.py — BibTeX 格式化
  • ~/.claude/skills/academic-reference-inserter/scripts/validate_citations.py — 引用验证

子命令 3: /ref verify — 文献真实性验证

新增于 2026-03-10。对照 CrossRef 权威元数据验证稿件引用。

核心能力

状态定义

验证流程（v2 — 含 CNKI 回退）

Step 1: 提取 DOI → CrossRef API 验证
  ├─ OK/WARN/MISMATCH → 完成
  ├─ DOI_NOT_FOUND → Step 2
  └─ 无 DOI → Step 2

Step 2: 判断是否为中文文献（作者名/期刊名含中文字符）
  ├─ 否 → DOI_NOT_FOUND（维持原判定）
  └─ 是 → Step 3

Step 3: browser-use + Gemini 登录 CNKI 代理，按标题搜索
  ├─ 有匹配结果 → 提取作者/年份交叉核对 → CNKI_VERIFIED 或 MISMATCH
  └─ 无结果 → MANUAL_CHECK_NEEDED

使用方式

# 基础（仅 CrossRef）
python3 verify_references.py references.txt

# 含 CNKI 回退（自动对中文文献启用）
python3 verify_references.py manuscript.md --cnki-fallback -o report.json

脚本路径

• ~/.claude/skills/academic-reference-inserter/scripts/verify_references.py — CrossRef 验证
• ~/ai-research-army/scripts/cnki_browser.py — CNKI browser-use 验证/下载（新增）

在管线中的位置

投稿前质控步骤。在 /ref insert 完成引用插入后、提交前运行。

子命令 4: /ref download — 文献全文获取

新增于 2026-03-11。分层下载文献 PDF，支持中英文。

核心能力

给定文献列表（DOI/PMID/标题），自动下载全文 PDF。

下载分层策略

Layer 1: Unpaywall API — 免费 OA 版（合法，秒级）
  ↓ 无 OA 版
Layer 2: PMC OA Service — 生物医学论文全文（合法，PMID/PMCID）
  ↓ 非 PMC 收录
Layer 3: PyPaperBot — 多源回退（Scholar/CrossRef/SciHub）
  ↓ 仍然失败（或中文文献）
Layer 4: browser-use + Gemini 2.5 Pro — CNKI 代理账号下载

Layer 4 技术栈

# browser-use 0.12.1 + AiCodeWith Gemini 2.5 Pro (主)
from browser_use import Agent, Browser, ChatGoogle
from google.genai import types
llm = ChatGoogle(
    model="gemini-2.5-pro", api_key="placeholder",
    http_options=types.HttpOptions(
        base_url="https://api.with7.cn/gemini_cli",  # 注意: 不含 /v1beta
        headers={"Authorization": f"Bearer {os.getenv('AICODEWITH_API_KEY')}"},
    ),
)
browser = Browser(headless=False, disable_security=True)
# 备选: OpenRouter ChatOpenAI(base_url="https://openrouter.ai/api/v1")

# CNKI 代理站点 — 凭证自动从 ~/.openclaw/credentials/.env 加载
# CNKI_PROXY_URL="https://sss.ccki.top", CNKI_USERNAME, CNKI_PASSWORD

Gemini 控制浏览器的优势:

• 看页面语义而非 CSS 选择器 → 知网改版也能适应
• 自然操作间隔（LLM 推理延迟）→ 不易触发反爬
• 能处理验证码和弹窗

使用方式

# 按 DOI 列表下载
python3 paper_downloader.py --input dois.txt --output ./papers/

# 按标题下载（中文文献）
python3 paper_downloader.py --titles "中文标题1" "中文标题2" --output ./papers/

# manuscript-drafter Phase 4b 自动调用
# 从 literature_summary.md 筛选 Discussion 文献 → 自动分层下载

输出

下载的 PDF 存放在项目的 outputs/discussion_refs/ 目录，文件名格式: {first_author}_{year}.pdf

脚本路径

• ~/ai-research-army/scripts/paper_downloader.py — 分层下载主脚本（新增）
• ~/ai-research-army/scripts/cnki_browser.py — browser-use CNKI 封装（新增）

五个子命令的协作

/ref research  -->  领域深度调研（认知层: 学术演进 + must-cite 列表）
                         |
                         v
/ref review    -->  系统文献综述（证据层: 多库检索 + 筛选 + 质量评估）
                         |
                         v
/ref download  -->  下载关键文献全文（Discussion 对比文献 + 方法学参考）
                         |
                         v
/ref insert    -->  将引用插入稿件正文
                         |
                         v
/ref verify    -->  投稿前验证所有引用（CrossRef + CNKI 回退）

完整管线: /ref research（理解领域）→ /ref review（系统检索）→ /ref download（获取全文）→ /ref insert（嵌入引用）→ /ref verify（投稿前质控）。

最小管线: 只需写稿 → /ref research + /ref insert（深度调研 + 直接插引用）。

五者也可独立使用。

Skill: reference-manager (5-in-1) Version: 4.0 Created: 2026-03-08, Updated: 2026-03-11 合并自: literature-review (K-Dense) + academic-reference-inserter + crossref-verifier + paper-downloader + manuscript-drafter Phase 0b

更新日志

• v4.0 (2026-03-11): 新增 /ref research — 领域深度调研
  • 从 manuscript-drafter Phase 0b 迁入，成为 literature 模块的认知层
  • Agent Deep Research + CrossRef API 验证 = 高覆盖率 + 零幻觉
  • 产出 literature_summary.md（知识地基），manuscript-drafter 改为依赖此产出
  • 新增学术演进图生成（AiCodeWith Gemini 图片 API）
  • 步骤编号从 0b.x 更名为 R.x，保持内容一致
  • manuscript-drafter Phase 0b 简化为依赖声明，不再包含执行逻辑
• v3.0 (2026-03-11): 新增 /ref download + /ref verify CNKI 回退
  • 新增 /ref download 子命令: 四层分层下载（Unpaywall→PMC→PyPaperBot→CNKI+browser-use）
  • /ref verify 增加中文文献 CNKI 回退验证，新增 CNKI_VERIFIED / MANUAL_CHECK_NEEDED 状态
  • browser-use + Gemini 2.5 Pro 控制浏览器，适应知网改版，不易触发反爬
  • 凭证统一存储在 ~/.openclaw/credentials/.env
• v2.0 (2026-03-10): 新增 /ref verify CrossRef 验证
• v1.0 (2026-03-08): 合并 literature-review + academic-reference-inserter