arxiv

arXiv 论文搜索与下载

搜索主题或 arXiv 论文 ID：$ARGUMENTS

常量

• PAPER_DIR — 用于保存已下载 PDF 的本地目录。默认值：当前项目目录中的 papers/。
• MAX_RESULTS = 10 — 默认搜索结果数量。
• ARXIV_FETCHER — 规范名称为 arxiv_fetch.py，根据 shared-references/integration-contract.md §2 进行解析 （Policy D1 — 主链 + 回退级联）。若无法解析（规范解析链已耗尽），则回退到 Step 2 中记录的内嵌 Python 替代方案。

覆盖选项（追加到参数中）：

• /arxiv "attention mechanism" - max: 20 - 最多返回 20 条结果
• /arxiv "2301.07041" - download - 下载指定 ID 的论文
• /arxiv "query" - dir: literature/ - 将 PDF 保存到自定义目录
• /arxiv "query" - download: all - 下载所有结果的 PDF

工作流

Step 1：解析参数

解析 $ARGUMENTS 中的指令：

• 查询词或 ID：主要搜索词，或裸 arXiv ID，例如 2301.07041 或 cs/0601001
• - max: N：覆盖 MAX_RESULTS（例如 - max: 20）
• - dir: PATH：覆盖 PAPER_DIR（例如 - dir: literature/）
• - download：列出结果后下载第一条结果的 PDF
• - download: all：下载所有结果的 PDF

如果参数符合 arXiv ID 格式（YYMM.NNNNN 或 category/NNNNNNN），则跳过搜索，直接进入 Step 3。

Step 2：搜索 arXiv

通过规范的严格安全解析链解析 $ARXIV_FETCHER（参见 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=""

如果 $ARXIV_FETCHER 非空，则运行：

python3 "$ARXIV_FETCHER" search "QUERY" --max MAX_RESULTS

如果 $ARXIV_FETCHER 为空（Policy D1 级联），则回退到内嵌 Python：

python3 - <<'PYEOF'
import json
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET

NS = "http://www.w3.org/2005/Atom"
query = urllib.parse.quote("QUERY")
url = (f"http://export.arxiv.org/api/query"
       f"?search_query={query}&start=0&max_results=MAX_RESULTS"
       f"&sortBy=relevance&sortOrder=descending")
with urllib.request.urlopen(url, timeout=30) as r:
    root = ET.fromstring(r.read())
papers = []
for entry in root.findall(f"{{{NS}}}entry"):
    aid = entry.findtext(f"{{{NS}}}id", "").split("/abs/")[-1].split("v")[0]
    title = (entry.findtext(f"{{{NS}}}title", "") or "").strip().replace("\n", " ")
    abstract = (entry.findtext(f"{{{NS}}}summary", "") or "").strip().replace("\n", " ")
    authors = [a.findtext(f"{{{NS}}}name", "") for a in entry.findall(f"{{{NS}}}author")]
    published = entry.findtext(f"{{{NS}}}published", "")[:10]
    cats = [c.get("term", "") for c in entry.findall(f"{{{NS}}}category")]
    papers.append({
        "id": aid,
        "title": title,
        "authors": authors,
        "abstract": abstract,
        "published": published,
        "categories": cats,
        "pdf_url": f"https://arxiv.org/pdf/{aid}.pdf",
        "abs_url": f"https://arxiv.org/abs/{aid}",
    })
print(json.dumps(papers, ensure_ascii=False, indent=2))
PYEOF

将结果整理为表格：

| # | arXiv ID   | Title               | Authors        | Date       | Category |
|---|------------|---------------------|----------------|------------|----------|
| 1 | 2301.07041 | Attention Is All... | Vaswani et al. | 2017-06-12 | cs.LG    |

Step 3：获取指定 ID 的详细信息

请求单篇论文 ID 时（直接指定或来自 Step 2）：

python3 "$ARXIV_FETCHER" search "id:ARXIV_ID" --max 1
# or fallback:
python3 -c "
import urllib.request, xml.etree.ElementTree as ET
NS = 'http://www.w3.org/2005/Atom'
url = 'http://export.arxiv.org/api/query?id_list=ARXIV_ID'
with urllib.request.urlopen(url, timeout=30) as r:
    root = ET.fromstring(r.read())
# print full details ...
"

显示：标题、所有作者、类别、完整摘要、发表日期、PDF URL、摘要 URL。

Step 4：下载 PDF

请求下载时，对每个要下载的论文 ID：

# Using fetch script:
python3 "$ARXIV_FETCHER" download ARXIV_ID --dir PAPER_DIR

# Fallback:
mkdir -p PAPER_DIR && python3 -c "
import pathlib
import sys
import urllib.request

out = pathlib.Path('PAPER_DIR/ARXIV_ID.pdf')
if out.exists():
    print(f'Already exists: {out}')
    sys.exit(0)
req = urllib.request.Request(
    'https://arxiv.org/pdf/ARXIV_ID.pdf',
    headers={'User-Agent': 'arxiv-skill/1.0'},
)
with urllib.request.urlopen(req, timeout=60) as r:
    out.write_bytes(r.read())
print(f'Downloaded: {out} ({out.stat().st_size // 1024} KB)')
"

每次下载后：

• 确认文件大小 > 10 KB（若文件较小则拒绝——很可能是错误 HTML 页面）
• 连续下载之间间隔 1 秒，以避免触发速率限制
• 报告：Downloaded: papers/2301.07041.pdf (842 KB)

Step 5：总结

对每篇论文（已下载或通过 API 获取）：

## [Title]

- **arXiv**: [ID] - [abs_url]
- **Authors**: [full author list]
- **Date**: [published]
- **Categories**: [cs.LG, cs.AI, ...]
- **Abstract**: [full abstract]
- **Key contributions** (extracted from abstract):
  - [contribution 1]
  - [contribution 2]
  - [contribution 3]
- **Local PDF**: papers/[ID].pdf (if downloaded)

Step 6：更新 Research Wiki（如果已启用）

当项目中存在 research-wiki/ 时必须执行；否则静默跳过。如果 wiki 目录存在，则根据 shared-references/wiki-helper-resolution.md 中的规范解析链解析 $WIKI_SCRIPT（Variant B — 警告并跳过），然后将本次调用返回的每篇论文导入：

if [ -d research-wiki/ ]; then
  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; arxiv results delivered, wiki ingest 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=""
  }
  if [ -n "$WIKI_SCRIPT" ]; then
    for each arxiv_id in results:
        python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
            --arxiv-id "<arxiv_id>"
  fi
fi

该辅助脚本会在一次调用中处理元数据获取、slug、去重、页面创建、索引重建和日志追加——不要手动编写 papers/<slug>.md。规范辅助脚本规则参见 shared-references/integration-contract.md。 遗漏的导入之后可以通过以下命令补齐：先按上述方式解析 $WIKI_SCRIPT，再运行 python3 "$WIKI_SCRIPT" sync research-wiki/ --arxiv-ids <id1>,<id2>,...。

Step 7：最终输出

总结已完成的工作：

• Found N papers for "query"
• Downloaded: papers/2301.07041.pdf (842 KB)（针对每次下载）
• Wiki-ingested N papers（如果存在 research-wiki/）
• 任何警告（触发速率限制、文件过小、已存在）

建议后续技能：

/research-lit "topic"     - multi-source review: Zotero + Obsidian + local PDFs + web
/novelty-check "idea"     - verify your idea is novel against these papers

关键规则

• 始终醒目地显示 arXiv ID——用户需要它来引用和复现结果
• 验证下载的 PDF：文件必须大于 10 KB；若文件较小，则发出警告并删除
• 速率限制：连续下载 PDF 之间等待 1 秒；收到 HTTP 429 时，等待 5 秒后重试一次
• 绝不覆盖同一路径下已有的 PDF——跳过并报告“已存在”
• 处理两种 arXiv ID 格式：新版（2301.07041）和旧版（cs/0601001）
• 如果 PAPER_DIR 不存在，则自动创建
• 如果无法访问 arXiv API，请清楚报告错误，并建议将 /research-lit 与 - sources: web 配合使用作为备用方案