research-lit

研究文献综述

研究主题：$ARGUMENTS

常量

• PAPER_LIBRARY — 包含用户论文集（PDF）的本地目录。按以下顺序检查这些路径：
  1. 当前项目目录中的 papers/
  2. 当前项目目录中的 literature/
  3. 用户在 CLAUDE.md 的 ## Paper Library 下指定的自定义路径
• MAX_LOCAL_PAPERS = 20 — 要扫描的本地 PDF 最大数量（每篇读取前 3 页）。如果找到的 PDF 更多，则优先选择文件名与主题相关的文件。
• SOURCES = all — 要搜索的文献来源。选项：zotero、obsidian、local、web、semantic-scholar、deepxiv、exa、gemini、openalex、all。完整来源表和选择规则：参见下方的 ## Data Sources。
• ARXIV_DOWNLOAD = false — 为 true 时，搜索后将相关性最高的 3-5 篇 arXiv PDF 下载到 PAPER_LIBRARY。为 false（默认值）时，仅通过 arXiv API 获取元数据（标题、摘要、作者），不下载文件。
• ARXIV_MAX_DOWNLOAD = 5 — ARXIV_DOWNLOAD = true 时要下载的 PDF 最大数量。

💡 覆盖设置：

• /research-lit "topic" — paper library: ~/my_papers/ — 自定义本地 PDF 路径
• /research-lit "topic" — sources: zotero, local — 仅搜索 Zotero 和本地 PDF
• /research-lit "topic" — sources: web — 仅搜索网络（跳过所有本地来源）
• /research-lit "topic" — sources: web, semantic-scholar — 也搜索 Semantic Scholar 中已在出版渠道发表的论文（IEEE、ACM 等）
• /research-lit "topic" — sources: all, deepxiv — 使用默认来源，并加上 DeepXiv
• /research-lit "topic" — arxiv download: true — 下载相关性最高的 arXiv PDF
• /research-lit "topic" — arxiv download: true, max download: 10 — 最多下载 10 篇 PDF

数据来源

此技能会按优先级顺序检查多个来源。所有来源均为可选项——如果某个来源未配置或未指定，则静默跳过。

来源选择

解析 $ARGUMENTS，查找 — sources: 指令：

• 如果指定了 — sources:：仅搜索列出的来源（以逗号分隔）。有效值：zotero、obsidian、local、web、semantic-scholar、deepxiv、exa、gemini、openalex、all。
• 如果未指定：默认为 all——按优先级顺序搜索所有可用来源（semantic-scholar、deepxiv、exa、gemini 和 openalex 不包含在 all 中；必须明确列出）。

示例：

/research-lit "diffusion models"                                    → all (default, no S2)
/research-lit "diffusion models" — sources: all                     → all (default, no S2)
/research-lit "diffusion models" — sources: zotero                  → Zotero only
/research-lit "diffusion models" — sources: zotero, web             → Zotero + web
/research-lit "diffusion models" — sources: local                   → local PDFs only
/research-lit "topic" — sources: obsidian, local, web               → skip Zotero
/research-lit "topic" — sources: web, semantic-scholar              → web + S2 API (IEEE/ACM venue papers)
/research-lit "topic" — sources: deepxiv                            → DeepXiv only
/research-lit "topic" — sources: all, deepxiv                       → default sources + DeepXiv
/research-lit "topic" — sources: all, semantic-scholar              → all + S2 API
/research-lit "topic" — sources: exa                               → Exa only (broad web + content extraction)
/research-lit "topic" — sources: all, exa                          → default sources + Exa web search
/research-lit "topic" — sources: gemini                            → Gemini only (AI-powered broad discovery)
/research-lit "topic" — sources: all, gemini                       → default sources + Gemini discovery
/research-lit "topic" — sources: gemini, semantic-scholar           → Gemini + S2 (broad discovery + venue metadata)
/research-lit "topic" — sources: openalex                          → OpenAlex only (open citation graph + institutions)
/research-lit "topic" — sources: semantic-scholar, openalex         → S2 + OpenAlex (complementary metadata)

来源表

优先级	来源	ID	检测方法	提供内容
1	Zotero（通过 MCP）	zotero	尝试调用任意 mcp__zotero__* 工具——如果不可用，则跳过	集合、标签、注释、PDF 高亮、BibTeX、语义搜索
2	Obsidian（通过 MCP）	obsidian	尝试调用任意 mcp__obsidian-vault__* 工具——如果不可用，则跳过	研究笔记、论文摘要、带标签的参考文献、维基链接
3	本地 PDF	local	Glob: papers/**/*.pdf, literature/**/*.pdf	PDF 原始内容（前 3 页）
4	网页搜索	web	始终可用（WebSearch）	arXiv、Semantic Scholar、Google Scholar
5	Semantic Scholar API	semantic-scholar	$S2_FETCHER 可解析（规范名称为 semantic_scholar_fetch.py，参见 integration-contract §2）	已发表的会议论文（IEEE、ACM、Springer），包含结构化元数据：引用次数、会议资料、TLDR。仅在通过 — sources: semantic-scholar 或 — sources: web, semantic-scholar 明确请求时运行
6	DeepXiv CLI	deepxiv	$DEEPXIV_FETCHER 可解析（规范名称为 deepxiv_fetch.py，参见 integration-contract §2），并且存在 deepxiv CLI（command -v deepxiv）	渐进式论文检索：搜索、概要、前言、章节、趋势、网页搜索。仅在通过 — sources: deepxiv 或 — sources: all, deepxiv 明确请求时运行
7	Exa Search	exa	$EXA_FETCHER 可解析（规范名称为 exa_search.py，参见 integration-contract §2）；获取器在内部处理 exa-py SDK 和 API 密钥	AI 驱动的广泛网页搜索，并提取内容（重点片段、文本、摘要）。涵盖博客、文档、新闻、公司以及 arXiv/S2 之外的研究论文。仅在通过 — sources: exa 或 — sources: all, exa 明确请求时运行
8	Gemini（MCP / CLI）	gemini	mcp__gemini-cli__ask-gemini 工具可用，或已安装 gemini CLI	AI 驱动的广泛文献发现——将主题拆解为子问题、别名和变体，以扩大检索范围。优先使用 MCP，无法使用时回退到 CLI。仅在通过 — sources: gemini 或 — sources: all, gemini 明确请求时运行
9	OpenAlex	openalex	$OPENALEX_FETCHER 可解析（规范名称为 openalex_fetch.py，参见 integration-contract §2），并且可导入 Python requests 模块	开放的引文图谱，包含机构隶属关系、资助数据以及涵盖 2.5 亿多项成果的全面元数据。完全开放的 API。仅在通过 — sources: openalex 或 — sources: all, openalex 明确请求时运行

优雅降级：如果未配置 MCP 服务，该技能的工作方式与之前完全相同（本地 PDF + 网页搜索）。Zotero 和 Obsidian 只是额外选项。

工作流

步骤 0a：搜索 Zotero 文献库（如果可用）

如果未配置 Zotero MCP，则完全跳过此步骤。

尝试调用 Zotero MCP 工具（例如搜索工具）。如果调用成功：

1. 按主题搜索：使用 Zotero 搜索工具查找与研究主题匹配的论文
2. 查看集合：检查用户是否有与该主题相关的集合或文件夹
3. 提取注释：对于高度相关的论文，提取 PDF 高亮和笔记——这些体现了用户认为重要的内容
4. 导出 BibTeX：获取相关论文的引文数据（稍后用于 /paper-write）
5. 汇总结果：针对每条相关 Zotero 条目，提取：
   • 标题、作者、年份、出版物
   • 用户的注释和高亮（如果有）
   • 用户添加的标签
   • 所属集合

📚 Zotero 注释非常宝贵——它们展示了用户亲自标记为重要的内容，比通用摘要有价值得多。

步骤 0b：搜索 Obsidian 知识库（如果可用）

如果未配置 Obsidian MCP，请完全跳过此步骤。

尝试调用 Obsidian MCP 工具（例如搜索工具）。如果成功：

1. 搜索知识库：搜索与研究主题相关的笔记
2. 检查标签：查找带有相关主题标签的笔记（例如，#diffusion-models、#paper-review）
3. 阅读研究笔记：对于相关笔记，提取用户自己的摘要和见解
4. 跟进链接：如果笔记链接到其他相关笔记（维基链接），请跟进这些链接以获取更多上下文
5. 汇总结果：对于每条相关笔记：
   • 笔记标题和路径
   • 用户的摘要/见解
   • 指向其他笔记的链接（研究图谱）
   • 任何 frontmatter 元数据（论文 URL、状态、评分）

📝 Obsidian 笔记代表用户经过整理的理解——比原始论文内容更能体现用户的观点。

步骤 0c：扫描本地论文库

在线搜索前，先检查用户是否已在本地保存相关论文：

1. 定位论文库：检查 PAPER_LIBRARY 路径中的 PDF 文件

   Glob: papers/**/*.pdf, literature/**/*.pdf
   

2. 与 Zotero 去重：如果步骤 0a 找到了论文，请跳过 Zotero 结果中已包含的本地 PDF（按文件名或标题匹配）。

3. 筛选相关内容：根据文件名和首页内容判断是否与研究主题相关。跳过明显无关的论文。

4. 总结相关论文：对于每篇相关的本地 PDF（最多 MAX_LOCAL_PAPERS 篇）：

   • 阅读前 3 页（标题、摘要、引言）
   • 提取：标题、作者、年份、核心贡献、与主题的相关性
   • 标记论文是直接相关还是间接相关

5. 构建本地知识库：将摘要汇总到“你已有的论文”部分。这将作为起点——外部搜索用于填补空缺。

📚 如果用户拥有全面的本地收藏，外部搜索可以更有针对性（重点关注缺少的内容）。

⚠️ 如果三个 PAPER_LIBRARY 路径都未找到文件，请在继续之前说明这一点——不要默默跳过。否则，PDF 存放在文献管理器（Zotero、Mendeley 等）中的用户可能会以为 — sources: all 已涵盖这些文件。请输出：

WARN: local contributed nothing — no PDFs found in papers/, literature/, or a configured paper library. To include yours, add a "## Paper Library" heading to CLAUDE.md followed by the directory path.

然后继续步骤 1。

步骤 1：搜索（外部）

• 使用 WebSearch 查找该主题的近期论文
• 检查 arXiv、Semantic Scholar、Google Scholar
• 除非研究基础性工作，否则重点关注近 2 年发表的论文
• 去重：跳过已在 Zotero、Obsidian 或本地论文库中找到的论文

arXiv API 搜索（当 — sources: 未设置、包含 web 或 all 时运行；默认不下载——arXiv API 属于上文源列表中的 Priority-4 Web 层）：

Policy D2 跟踪规范（由协调器管理）：执行器（你，即 LLM）在上下文中维护一份有贡献的来源列表。对于由辅助程序支持的 bash 来源（arxiv、semantic-scholar、deepxiv、exa、openalex），如果其 bash 代码块成功运行了辅助程序（找到辅助程序且调用以状态码 0 退出），则该来源有贡献；注意，辅助程序以状态码 0 退出但结果列表为空，仍算作“已运行”——由后续相关性排序决定用户是否实际看到内容。对于非辅助程序来源（zotero / obsidian / 本地 PDF / WebSearch / Gemini），贡献规则见下方的步骤 1 最终处理代码块——这些来源单独跟踪，因为它们不会输出 bash 日志行 D2 contribution:。未通过 — sources: 请求的来源不计入。步骤 1 结束时（“可选 PDF 下载”之前），如果没有任何来源有贡献，则显示 D2 聚合结果为空错误并停止。（参见 integration-contract.md §2 Policy D2——上下文内跟踪取代共享 bash 累加器，因为 SKILL bash 代码块在不同 shell 中执行，状态无法保留。） 通过规范调用链解析 $ARXIV_FETCHER（策略 D2 — 此来源会纳入多来源聚合；失败时警告并继续，绝不终止整个聚合）：

# Canonical strict-safe resolver (see shared-references/integration-contract.md §2).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
ARXIV_FETCHER=".aris/tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER="tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"; }
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER=""

if [ -n "$ARXIV_FETCHER" ]; then
  # Search arXiv API for structured results (title, abstract, authors, categories).
  # Wrap with if/then/else so set -e doesn't abort the SKILL.
  if python3 "$ARXIV_FETCHER" search "QUERY" --max 10; then
    echo "D2 contribution: arxiv (helper invocation exit 0)" >&2
  else
    echo "WARN: arxiv_fetch.py invocation failed; D2 aggregate continues with WebSearch results." >&2
  fi
else
  echo "WARN: arxiv_fetch.py not resolved; falling back to WebSearch for arXiv hits." >&2
fi

记录：跟踪每个来源的 bash 代码块输出的 D2 contribution: … 行。它们构成了参与来源列表，编排器会在下方的步骤 1 最终确认关卡中使用该列表。 对于 WebSearch，只有在满足以下条件时，才视为已参与：用户请求了 WebSearch（未使用 — sources: 筛选，或列表中包含 web 或 all），并且实际调用了 WebSearch；编排器会单独记录这一点。（下方的最终确认代码块会再次以规范形式说明此规则 — 两处内容必须保持一致。）

如果 $ARXIV_FETCHER 为空（D2 优雅降级），则回退到 WebSearch 搜索 arXiv（与之前相同）。

arXiv API 会返回结构化元数据（标题、摘要、完整作者列表、类别、日期），信息比 WebSearch 摘要更丰富。将这些结果与 WebSearch 的发现合并并去重。

Semantic Scholar API 搜索（仅当来源中包含 semantic-scholar 时）：

当用户明确请求 — sources: semantic-scholar（或 — sources: web, semantic-scholar）时，搜索 arXiv 之外已发表在学术刊物上的论文：

# Re-resolve $ARIS_REPO (SKILL bash blocks may run in separate shells).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
# Resolve $S2_FETCHER (Policy D2 — warn-and-skip on missing).
S2_FETCHER=".aris/tools/semantic_scholar_fetch.py"
[ -f "$S2_FETCHER" ] || S2_FETCHER="tools/semantic_scholar_fetch.py"
[ -f "$S2_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && S2_FETCHER="$ARIS_REPO/tools/semantic_scholar_fetch.py"; }
[ -f "$S2_FETCHER" ] || S2_FETCHER=""

if [ -n "$S2_FETCHER" ]; then
  # Search for published CS/Engineering papers with quality filters.
  # Wrap with if/then/else so set -e doesn't abort the SKILL.
  if python3 "$S2_FETCHER" search "QUERY" --max 10 \
      --fields-of-study "Computer Science,Engineering" \
      --publication-types "JournalArticle,Conference"; then
    echo "D2 contribution: semantic_scholar (helper invocation exit 0)" >&2
  else
    echo "WARN: semantic_scholar_fetch.py invocation failed; D2 aggregate continues with remaining sources." >&2
  fi
fi

如果 $S2_FETCHER 为空（规范调用链已耗尽），则静默跳过 — D2 多来源聚合将继续处理其余已解析的来源。

为什么使用 Semantic Scholar？ 许多 IEEE/ACM 期刊论文并未收录在 arXiv 上。S2 可弥补这一缺口，找到仅发表在学术刊物上的论文，并提供引用次数和刊物元数据。

arXiv 与 S2 之间的去重：按 arXiv ID 匹配（S2 会返回 externalIds.ArXiv）：

• 如果同一篇论文同时出现在两者中：检查 S2 的 venue/publicationVenue — 如果论文已发表于期刊或会议（例如 IEEE TWC、JSAC），则使用 S2 的元数据（刊物、引用次数、DOI）作为权威版本，因为已发表版本优先于预印本。保留 arXiv PDF 链接供下载。
• 如果 S2 中匹配到的条目没有刊物信息（仍只是由 S2 索引的预印本）：保留 arXiv 版本，不做更改。
• 没有 externalIds.ArXiv 的 S2 结果是 arXiv 上没有收录的仅刊物论文 — 这是该来源独有的价值。

DeepXiv 搜索（仅当来源中包含 deepxiv 时）：

当用户明确请求 — sources: deepxiv（或在组合来源列表中包含 deepxiv）时，使用 DeepXiv 适配器进行渐进式检索：

# Re-resolve $ARIS_REPO (SKILL bash blocks may run in separate shells).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
# Resolve $DEEPXIV_FETCHER (Policy D2 — warn-and-skip on missing).
DEEPXIV_FETCHER=".aris/tools/deepxiv_fetch.py"
[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER="tools/deepxiv_fetch.py"
[ -f "$DEEPXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && DEEPXIV_FETCHER="$ARIS_REPO/tools/deepxiv_fetch.py"; }
[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER=""

if [ -n "$DEEPXIV_FETCHER" ] && command -v deepxiv >/dev/null 2>&1; then
  # Wrap each adapter call so set -e doesn't abort the SKILL.
  if python3 "$DEEPXIV_FETCHER" search "QUERY" --max 10; then
    echo "D2 contribution: deepxiv (helper invocation exit 0)" >&2

    # Then deepen only for the most relevant papers (sub-calls don't change D2 aggregate count):
    python3 "$DEEPXIV_FETCHER" paper-brief ARXIV_ID \
      || echo "WARN: deepxiv_fetch.py paper-brief failed; skipping deepen step." >&2
    python3 "$DEEPXIV_FETCHER" paper-head ARXIV_ID \
      || echo "WARN: deepxiv_fetch.py paper-head failed; skipping deepen step." >&2
    python3 "$DEEPXIV_FETCHER" paper-section ARXIV_ID "Experiments" \
      || echo "WARN: deepxiv_fetch.py paper-section failed; skipping deepen step." >&2
  else
    echo "WARN: deepxiv_fetch.py search invocation failed; D2 aggregate continues with remaining sources." >&2
  fi
fi

如果 $DEEPXIV_FETCHER 为空或 deepxiv CLI 不可用，则优雅地跳过此来源，并继续处理其余请求的来源（策略 D2 优雅降级）。

为什么使用 DeepXiv？ 当宽泛搜索之后需要分阶段阅读，而不是立即加载整篇论文时，DeepXiv 很有用。它能减少不必要的上下文，同时仍可呈现论文结构、TLDR 和最相关的章节。

与 arXiv 和 S2 去重：

• 优先按 arXiv ID 匹配，其次按 DOI，最后按规范化标题匹配
• 如果 DeepXiv 和 arXiv 指向同一篇预印本，则仅保留一条规范论文记录，并将 deepxiv 记录为附加来源
• 如果 DeepXiv 与 S2 的已发表论文重叠，则在最终表格中优先采用 S2 的刊物和引用元数据，但如果 DeepXiv 得出的章节注释有价值，则予以保留

Exa 搜索（仅当来源中包含 exa 时）：

当用户明确请求 — sources: exa（或在组合来源列表中包含 exa）时，使用 Exa 工具执行广泛的 AI 驱动网络搜索并提取内容：

# Re-resolve $ARIS_REPO (SKILL bash blocks may run in separate shells).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
# Resolve $EXA_FETCHER (Policy D2 — warn-and-skip on missing).
EXA_FETCHER=".aris/tools/exa_search.py"
[ -f "$EXA_FETCHER" ] || EXA_FETCHER="tools/exa_search.py"
[ -f "$EXA_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && EXA_FETCHER="$ARIS_REPO/tools/exa_search.py"; }
[ -f "$EXA_FETCHER" ] || EXA_FETCHER=""

if [ -n "$EXA_FETCHER" ]; then
  # Search for research papers with highlights.
  # Wrap with if/then/else so set -e doesn't abort the SKILL.
  exa_contributed=false
  if python3 "$EXA_FETCHER" search "QUERY" --max 10 --category "research paper" --content highlights; then
    exa_contributed=true
  else
    echo "WARN: exa_search.py research-paper invocation failed; D2 aggregate continues." >&2
  fi
  # Search for broader web content (blogs, docs, news)
  if python3 "$EXA_FETCHER" search "QUERY" --max 10 --content highlights; then
    exa_contributed=true
  else
    echo "WARN: exa_search.py broad-web invocation failed; D2 aggregate continues." >&2
  fi
  [ "$exa_contributed" = "true" ] && echo "D2 contribution: exa (at least one invocation exit 0)" >&2
fi

如果 $EXA_FETCHER 为空或 exa-py SDK 不可用，则优雅地跳过此来源，并继续处理其余请求的来源（策略 D2 优雅降级）。

为什么使用 Exa？ Exa 可通过内置内容提取功能，在更广泛的网络中（博客、文档、新闻、公司页面）进行 AI 驱动的搜索。它能弥补学术数据库（arXiv、S2）与通用 WebSearch 之间的空缺，为每个结果提供更丰富的内容。 与 arXiv、S2 和 DeepXiv 去重：

• 优先按 URL 匹配，然后按规范化标题匹配
• 如果 Exa 返回的 arXiv 论文已由 arXiv/S2 找到，则优先采用这些来源的结构化元数据
• Exa 来自非学术领域（博客、文档、新闻）的结果是其他来源未涵盖的独特价值

Gemini 搜索（仅当 sources 中包含 gemini 时）：

当用户明确请求 — sources: gemini（或在组合来源列表中包含 gemini）时，使用 Gemini 进行 AI 驱动的广泛文献发现。

优先级 1 — Gemini MCP（首选）：调用 mcp__gemini-cli__ask-gemini，并使用以下搜索提示词：

mcp__gemini-cli__ask-gemini({
  prompt: 'You are a research literature scout. Search comprehensively for papers on: "QUERY"

IMPORTANT CONSTRAINTS:
1. Search from MULTIPLE angles — decompose the topic into sub-problems, aliases, neighboring tasks, and common benchmark/settings variants.
2. Prefer papers that are genuinely relevant, not merely keyword-adjacent.
3. Include top venues, journals, surveys, recent preprints, and papers with code when available.
4. Focus on papers from 2022 onward unless older foundational work is necessary.

For EACH paper found, provide ALL of the following:
- Title: [exact title]
- Authors: [full author list]
- Year: [publication year]
- Venue: [exact conference/journal name + year, or "arXiv preprint"]
- arXiv ID: [format 2401.12345, or "N/A"]
- DOI: [if available, or "N/A"]
- Code URL: [GitHub/GitLab link if available, or "No code"]
- Summary: [one-sentence core contribution]

Find at least 15 papers.',
  model: 'auto-gemini-3'
})

优先级 2 — Gemini CLI 回退方案（MCP 不可用时）：通过 Bash 执行 gemini -p "...same prompt..." 2>/dev/null（超时时间：120s）。

如果 MCP 和 CLI 均不可用，则跳过此来源并继续处理其余请求的来源。

为什么使用 Gemini？ Gemini 可进行超越关键词匹配的 AI 驱动发现——它会拆分主题、探索不同命名形式，并找出传统 API 搜索（arXiv、S2）可能遗漏的论文。它能填补结构化数据库查询之外的检索空白。

与 arXiv、S2、DeepXiv 和 Exa 去重：

• 优先按 arXiv ID 匹配，其次按 DOI，最后按规范化标题匹配
• 如果 Gemini 返回的论文已由 S2 找到，则优先采用 S2 的引用次数和会议信息元数据
• 如果 Gemini 返回的论文已由 arXiv 找到，则优先采用 arXiv 的结构化元数据
• Gemini 的独特价值在于发现其他基于关键词的索引未收录的论文
• 不要使用 Gemini 报告的引用次数——这些数据可能不准确。请使用 S2 获取权威引用数据。

OpenAlex 搜索（仅当 sources 中包含 openalex 时）：

当用户明确请求 — sources: openalex（或在组合来源列表中包含 openalex）时，使用 OpenAlex API 获取全面的学术元数据：

# Re-resolve $ARIS_REPO (SKILL bash blocks may run in separate shells).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
# Resolve $OPENALEX_FETCHER (Policy D2 — warn-and-skip on missing).
OPENALEX_FETCHER=".aris/tools/openalex_fetch.py"
[ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER="tools/openalex_fetch.py"
[ -f "$OPENALEX_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"; }
[ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER=""

# Preflight: skip OpenAlex silently if the helper is unresolved OR the
# `requests` Python package is missing. Both checks must pass before
# the script is invoked, so users without `requests` installed never see
# a stack trace from a default `/research-lit` run.
if [ -z "$OPENALEX_FETCHER" ] || ! python3 -c "import requests" >/dev/null 2>&1; then
  echo "OpenAlex source not available (openalex_fetch.py unresolved or 'requests' module missing); skipping." >&2
else
  # Search for papers with comprehensive metadata.
  # Wrap with if/then/else so set -e doesn't abort the SKILL.
  if python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \
      --year "2022-" \
      --type article \
      --sort relevance; then
    echo "D2 contribution: openalex (helper invocation exit 0)" >&2
  else
    echo "WARN: openalex_fetch.py invocation failed; D2 aggregate continues with remaining sources." >&2
  fi
fi

如果未找到 openalex_fetch.py 或缺少 requests 模块，则跳过此来源并继续处理其余请求的来源。

为什么使用 OpenAlex？ 完全开放的引文图谱（无需 API 密钥）、机构隶属关系、资助数据（NSF、NIH）、全面的主题/关键词元数据，以及覆盖所有学科（而不仅仅是 CS）。

与 arXiv、S2、DeepXiv、Exa 和 Gemini 去重：

• 优先按 DOI 匹配（OpenAlex 的大多数作品都有 DOI），然后按 arXiv ID，最后按规范化标题匹配
• 如果 OpenAlex 和 S2 都收录了同一篇论文：
  • 引用次数优先采用 S2（更新更及时）
  • 会议信息元数据优先采用 S2（对 CS/AI 论文更准确）
  • 使用 OpenAlex 提供机构隶属关系和资助数据（独特价值）
  • 合并两者，形成更丰富的记录
• 如果 OpenAlex 和 arXiv 的结果重叠，优先采用 arXiv 的 PDF 链接和元数据，但保留 OpenAlex 的引用和机构数据
• OpenAlex 的独特价值：机构隶属关系、资助来源、全面的主题分类以及跨学科覆盖

D2 聚合最终处理（依据 integration-contract §2 Policy D2）：

协调器（你，LLM）通过读取上文各来源 Bash 块输出的 D2 contribution: <name> 日志行，在上下文中维护贡献来源列表，此外还包括：

• 如果 Step 0a 返回了非空的 Zotero 结果，则包含 zotero。
• 如果 Step 0b 返回了非空的 Obsidian 结果，则包含 obsidian。
• 如果 Step 0c 找到了至少一个相关的本地 PDF，则包含 local。
• 如果请求了 WebSearch（优先级 4）（未设置 — sources: 筛选条件，或列表中包含 web 或 all）且实际调用了 WebSearch，则包含 web。 注意：— sources: all 覆盖默认启用的来源层（zotero、obsidian、local、web）——它不包括需选择启用的抓取器（semantic-scholar、deepxiv、exa、gemini、openalex）。要启用这些来源，请明确添加（例如 — sources: all, semantic-scholar, openalex），遵循本 SKILL 在 L42-43 / L51-63 的现有惯例。
• 如果 Gemini MCP / CLI 至少返回了一篇论文，则包含 gemini。 如果最终的贡献来源列表为空，则显示：

ERROR：D2 汇总为空——所有请求的来源均未解析、未调用、调用失败，或（对于 MCP / 本地 PDF / Gemini 来源）未返回可用结果。（注意：如果请求并调用了 WebSearch，即使结果集为空，也计为贡献。）无法继续进行多来源汇总。建议用户重试，并扩大 — sources: 列表（例如 web, local），或检查辅助工具的解析情况及 SDK 安装情况。

然后在 Step 1.5 之前停止。否则，向用户记录贡献来源列表（例如，“贡献的来源：arxiv、semantic_scholar、web”），然后继续。

可选的 PDF 下载（仅当 ARXIV_DOWNLOAD = true 时）：

搜索完所有来源并按相关性对论文排序后：

# Re-resolve $ARXIV_FETCHER (SKILL bash blocks may run in separate shells).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
ARXIV_FETCHER=".aris/tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER="tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"; }
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER=""

# Download top N most relevant arXiv papers; skip silently if helper unresolved.
[ -n "$ARXIV_FETCHER" ] && python3 "$ARXIV_FETCHER" download ARXIV_ID --dir papers/

• 仅下载按相关性排名位于 ARXIV_MAX_DOWNLOAD 名以内的论文
• 跳过本地库中已有的论文
• 下载间隔为 1 秒（速率限制）
• 确认每个 PDF 大于 10 KB

Step 1.5：核验候选论文（防止幻觉，强制执行）

分析前，对从 Steps 0a-1 收集的所有候选论文进行搜索前核验，以筛除由 LLM 捏造的 arXiv ID / DOI / 标题。辅助工具：verify_papers.py（规范名称；根据 shared-references/integration-contract.md §2 中的 Policy D1 解析，主辅助工具，带降级输出回退机制）。如果此机器上无法解析该辅助工具，SKILL 会生成回退文件 verified_papers.json，为每个候选项标记 [UNVERIFIED]，使后续分析能在降级输出可供审计的情况下继续，而不是悄悄丢弃候选项。

# 1. Resolve $VERIFY_PAPERS via the canonical strict-safe chain (§2).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
VERIFY_PAPERS=".aris/tools/verify_papers.py"
[ -f "$VERIFY_PAPERS" ] || VERIFY_PAPERS="tools/verify_papers.py"
[ -f "$VERIFY_PAPERS" ] || { [ -n "${ARIS_REPO:-}" ] && VERIFY_PAPERS="$ARIS_REPO/tools/verify_papers.py"; }
[ -f "$VERIFY_PAPERS" ] || VERIFY_PAPERS=""

# 2. Emit candidates as JSON. Verification scratch lives under .aris/
#    (NOT under research-wiki/ — Step 6's wiki ingest predicate is
#    "research-wiki/ exists", and we must not trip it from Step 1.5).
mkdir -p .aris/verify-papers
cat > .aris/verify-papers/candidate_papers.json <<'JSON'
[
  {"id": "p1", "arxiv_id": "2307.03172", "doi": null, "title": "Lost in the Middle"},
  {"id": "p2", "arxiv_id": null, "doi": "10.1145/...", "title": "..."},
  {"id": "p3", "arxiv_id": null, "doi": null, "title": "Some Paper Title"}
]
JSON

# 3. Run 3-layer verification (arXiv batch → CrossRef → Semantic Scholar fuzzy).
#    Policy D1: when the helper is unresolved OR its invocation fails, emit
#    a degraded verified set tagging everything [UNVERIFIED] so the user
#    can audit search quality. If python3 itself is missing, we BLOCK
#    rather than hand-roll JSON in shell.
verify_ok=false
if [ -n "$VERIFY_PAPERS" ]; then
  if python3 "$VERIFY_PAPERS" \
        --input  .aris/verify-papers/candidate_papers.json \
        --output .aris/verify-papers/verified_papers.json; then
    verify_ok=true
  else
    echo "WARN: verify_papers.py invocation failed (resolved at $VERIFY_PAPERS); falling back to [UNVERIFIED] tagging." >&2
  fi
else
  echo "WARN: verify_papers.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
  echo "      Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&2
fi
if [ "$verify_ok" = "false" ]; then
  if ! command -v python3 >/dev/null 2>&1; then
    echo "ERROR: python3 unavailable; cannot emit fallback verified_papers.json." >&2
    echo "       Status: BLOCKED. Install python3 or restore the helper to proceed." >&2
    exit 1
  fi
  echo "      Emitting unverified candidate set with [UNVERIFIED] tags." >&2
  python3 - <<'PY'
import json
cands = json.load(open('.aris/verify-papers/candidate_papers.json'))
out = {
  'verdict': 'WARN',
  'reason_code': 'verify_papers_unavailable',
  'summary': 'verify_papers.py helper unresolved or invocation failed; all candidates tagged [UNVERIFIED] for audit visibility.',
  'papers': [dict(p, status='unverified', method='none') for p in cands],
}
with open('.aris/verify-papers/verified_papers.json', 'w') as f:
  json.dump(out, f, indent=2)
PY
fi

# 4. Read verdict + per-paper status from .aris/verify-papers/verified_papers.json;
#    surface warnings to the user.

强制输出规则（完整约定请参见 shared-references/citation-discipline.md § 搜索前核验协议）：

• 为分析列表中的每篇论文标注其状态：✅ verified (via arxiv|crossref|s2) 或 ⚠️ UNVERIFIED (reason) 或 … verify_pending。
• 绝不可悄悄丢弃未核验的论文——在输出中保留这些论文，并标记 [UNVERIFIED]，以便用户审查搜索质量。
• 绝不可凭记忆捏造 DOI 或 arXiv ID。如果某个字段未知，则在 candidate_papers.json 中将其留为 null——辅助工具会改用标题搜索。
• 如果辅助工具返回 WARN，且 high_hallucination_rate，则原样显示警告，并建议使用更具体的查询重新运行。
• 对于标记为 verify_pending 的论文，不要将其升级为 verified——向用户显示待处理状态，并在下一个会话中重试。

可选：在 shell 中设置 [email protected]，以解除 CrossRef 速率限制，使用礼貌请求池。

Step 1.6：冻结叶节点可读取的证据（调度前强制执行）

父级仍负责检索上下文和所有写入操作。在 Step 2 之前，必须在 .aris/verify-papers/research-lit-evidence/ 下为每个分片创建一个只读文件。每个文件仅包含分配给该分片的论文，并记录 paper_id、title、verification_status、abstract、source_excerpt、local_pdf_path、local_note_paths 和 evidence_status。

使用已检索的 API 摘要/摘录、Zotero 或 Obsidian 文本，或可读取的本地 PDF/笔记路径来填充这些字段。仅有身份字段或远程 URL，不足以供仅能使用 Read/Grep/Glob 的叶节点使用。在叶节点提示中传入分片证据文件的绝对路径和分配的 ID；叶节点只能提取该文件所支持的论断。

如果某篇论文没有摘要、来源摘录、可读取的本地 PDF 或可读取的本地笔记，则记录 evidence_status: UNPROCESSABLE_NO_LOCAL_EVIDENCE。不要将其作为已完成的工作进行调度，也不要根据标题推断方法或结果。父级可以使用唯一允许的顺序回退来收集/处理本地证据；否则，应在覆盖情况回执中明确将该论文标记为未覆盖且状态为 UNPROCESSED。

步骤 2：分析每篇论文

有界扇出（感知层级）。 对每篇论文的提取范围受限，但绝不为每篇论文创建一个工作者。冻结步骤 1.5 中的每个规范论文 ID。对这些 ID 排序，并以确定性方式将其划分为不超过 max_shards: 8 个互不重叠的批次。每轮最多运行 max_concurrency: 4 个批次，每个叶节点最多运行 max_turns: 8 轮。

• 层级 1（工作流）：为每个批次明确选择 aris-fanout-leaf。
• 层级 2（Agent）：仅调用 Agent(aris-fanout-leaf)；绝不替换为不受限制的工作者。
• 层级 3：按顺序处理同一组已冻结的批次。如果叶节点失败、返回格式错误的输出或超时，则对该批次最多进行一次由执行器负责的顺序回退，且绝不启动替代 Agent。

每个叶节点都返回 shared-references/fan-out-pattern.md 中定义的提取封装： {shard_id, assigned_unit_ids, covered_unit_ids, status, entries, errors}。 每条记录都将规范 arXiv ID / DOI / 标题哈希保留为 dedup_key，并逐字报告 problem、method、results、relevance、source 和 verification_status。叶节点提示词会重复说明不得委派、只读、不得作出判定以及已分配 ID 的边界，因为工作者不会继承此技能正文。

**覆盖回执：**在唯一一次允许的顺序回退之后，将 covered_unit_ids 与冻结的论文 ID 集合核对，并记录计划处理、已完成、失败和未覆盖的 ID，以及 coverage_complete。任何尚未解决的论文都必须明确标记为 UNPROCESSED；绝不能将论文缺失解读为不相关，也不能悄悄将其从已分析集合中移除。

这里的“陪审团”不是模型，而是步骤 1.5 中确定性的 verify_papers.py 准入门槛。该门槛用于验证身份；覆盖回执则单独验证提取是否完整。叶节点工作者和综合分析都不得将提取缺失重新解释为准入决定。

对于 .aris/verify-papers/verified_papers.json 中的每一篇论文（包括 verified、unverified、verify_pending 和 error——参见上文的保留规则），都要提取：

• 问题：论文要解决什么缺口？

• 方法：核心技术贡献（1-2 句话）

• 结果：关键数据/主张

• 相关性：与我们的工作有何关联？

• 来源：在哪里找到（Zotero/Obsidian/本地/网页）——帮助用户区分已有内容与新内容

• 验证状态（以下之一）：

  • ✅ verified (via arxiv|crossref|s2)
  • ⚠️ UNVERIFIED (verification unavailable: helper unresolved or invocation failed)
  • ⚠️ UNVERIFIED (searched: not found in any source)
  • … VERIFY_PENDING (transient API failure — retry next session)
  • ❌ ERROR (malformed input: no arxiv, no DOI, no title)

  在分析表格中显示状态——绝不能仅因论文状态不是 verified 就悄悄将其丢弃。

步骤 3：综合分析

• 按方法/主题对论文分组
• 找出该领域的共识与分歧
• 找出我们的工作可以填补的空白
• 如果存在 Obsidian 笔记，将用户自己的见解纳入综合分析

步骤 4：输出

以结构化的文献表格呈现：

| Paper | Venue | Method | Key Result | Relevance to Us | Source |
|-------|-------|--------|------------|-----------------|--------|

并附上对研究概况的叙述性总结（3-5 段）。

如果已导出 Zotero BibTeX，则附上可直接用于论文写作的 references.bib 片段。

步骤 5：保存（如有要求）

• 将论文 PDF 保存到 literature/ 或 papers/
• 更新项目记忆中的相关工作笔记
• 如果有 Obsidian，可选择在库中创建一篇文献综述笔记

组合模式——如果调用时传入 — composed: <canonical-report-path>（例如 /idea-discovery 这样的编排器会传入此参数），则不要撰写独立的领域概览 .md 文件。请返回结构化表格和叙述性摘要，供编排器整合到规范报告的“Literature Landscape”章节中；报告可以链接已保存的 PDF/references.bib，但不要创建重复的领域概览文件。步骤 6（研究 Wiki 导入）仍会执行——Wiki 是独立的持久化存储，并非报告的副本。**默认情况（未指定 — composed: 指令）：行为与上述完全相同——独立撰写，并按文档说明写入文件。**切勿仅因磁盘上已有报告文件就推断为组合模式。完整规则见： shared-references/output-composition.md。

步骤 6：更新研究 Wiki

**当 research-wiki/ 存在时必须执行。**如果该目录不存在，则完全跳过（不执行任何操作，也不报错）。根据 shared-references/integration-contract.md， 此步骤遵循规范导入契约——业务逻辑位于 tools/research_wiki.py 中，而非本文说明。

当 research-wiki/ 存在时，按照 shared-references/wiki-helper-resolution.md 中记录的规范链解析 $WIKI_SCRIPT（变体 B——警告并跳过）：

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
  ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
WIKI_SCRIPT=".aris/tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
[ -f "$WIKI_SCRIPT" ] || {
  echo "WARN: research_wiki.py not found; literature synthesis will be reported but wiki ingest will be skipped. Fix: bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or cp <ARIS-repo>/tools/research_wiki.py tools/." >&2
  WIKI_SCRIPT=""
}

📋 Research Wiki ingest (runs once, at end of research-lit):
   [ ] 1. Predicate: `research-wiki/` exists? If no, skip this step.
   [ ] 2. If $WIKI_SCRIPT empty (helper unreachable), skip the rest of this step
          (the warning above already explains why).
   [ ] 3. For each of the top 8–12 relevant papers (arxiv IDs collected above):
          python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
              --arxiv-id <id> [--thesis "<one-line>"] [--tags <t1>,<t2>]
   [ ] 4. For each explicit relationship to an existing wiki entity,
          add an edge:
          python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
              --from "paper:<slug>" --to "<target_node_id>" \
              --type <extends|contradicts|addresses_gap|inspired_by|...> \
              --evidence "<one-sentence quote or reasoning>"
   [ ] 5. Confirm papers/<slug>.md files were created (helper prints
          "Paper ingested: ..."); if any failed with a network error,
          retry or fall back to the --title/--authors/--year manual form.

ingest_paper 会在一次调用中处理 slug 生成、arXiv 元数据获取、去重（按 arXiv id 跳过已有论文）、页面渲染、index.md 重建、query_pack.md 重建和日志追加——不要手动写入 papers/<slug>.md。如果辅助工具不可用（例如在非 ARIS 机器上处于离线状态，或 $WIKI_SCRIPT 为空），请记录这一缺失，并留待之后由 /research-wiki sync --arxiv-ids … 补录。

对于非 arXiv 来源（仅 Semantic Scholar、没有 arXiv 镜像的 IEEE/ACM 期刊、博客文章），请改为传入手动元数据：

python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
    --title "<full title>" --authors "A, B, C" --year <yyyy> \
    --venue "<venue>" [--external-id-doi "<doi>"] [--thesis "..."]

关键规则

• 始终注明论文引用信息（作者、年份、发表场合）
• 区分同行评审论文和预印本
• 如实说明每篇论文的局限性
• 注明论文是否直接与我们的方法竞争或为其提供支持
• 切勿因 MCP 服务未配置而失败——始终平稳回退到下一个数据源
• Zotero/Obsidian 工具的名称可能因用户对 MCP 服务的配置方式而异（例如，mcp__zotero__search 或 mcp__zotero-mcp__search_items）。请尝试最常见的命名模式并灵活调整。