ARIS 论文速取指南：用 `/arxiv` 技能完成 arXiv 检索、PDF 下载与研究 Wiki 归档

ARIS 论文速取指南用/arxiv技能完成 arXiv 检索、PDF 下载与研究 Wiki 归档【免费下载链接】Auto-claude-code-research-in-sleepARIS ⚔️ (Auto-Research-In-Sleep) — Lightweight Markdown-only skills for autonomous ML research: cross-model review loops, idea discovery, and experiment automation. No framework, no lock-in — works with Claude Code, Codex, OpenClaw, or any LLM agent.项目地址: https://gitcode.com/gh_mirrors/au/Auto-claude-code-research-in-sleep本文以 ARISAuto-Research-In-Sleep开源仓库中的skills/arxiv/SKILL.md为骨架系统讲解 arXiv 技能在 Claude Code / Codex 等 Agent 环境下的完整用法从参数解析、API 搜索、按 ID 拉取详情、PDF 批量下载与校验到论文摘要模板与 Research Wiki 自动归档。读完本文你将能直接指挥 Agent 以/arxiv attention mechanism - max: 20 - download: all这类命令完成一次从检索到入库的完整文献获取闭环并理解底层arxiv_fetch.py的限流退避、PDF 防伪校验等工程细节。一、技能定位与核心常量/arxiv是 ARIS 众多 Markdown 技能之一职责明确搜索、下载并总结 arXiv 学术论文。它不是一个框架而是一份给任意 LLM AgentClaude Code、Codex CLI、OpenClaw 等执行的指令文档——这一点从 SKILL.md 的 frontmatter 就能看出name: arxiv、allowed-tools: Bash(*), Read, Write即技能只依赖 Shell、文件读写三类工具即可完成全部工作。技能内置两个核心常量常量默认值含义PAPER_DIRpapers/当前项目目录下PDF 本地保存目录不存在时自动创建MAX_RESULTS10单次搜索默认返回的最大结果数第三个关键变量是ARXIV_FETCHER它是tools/arxiv_fetch.py这个标准辅助脚本的“解析名”。为什么需要动态解析而不是直接写死python3 tools/arxiv_fetch.py因为 ARIS 在安装时会通过tools/install_aris.sh把技能和辅助脚本以符号链接的形式部署到用户项目.aris/tools/目录用户项目里未必存在tools/目录直接写死路径正是历史上导致/research-wiki一周无数据的真实故障根因详见下文解析链。参数覆写Overrides在$ARGUMENTS中追加以下指令即可调整行为/arxiv attention mechanism - max: 20最多返回 20 条结果/arxiv 2301.07041 - download列出后直接下载该论文/arxiv query - dir: literature/把 PDF 保存到自定义目录/arxiv query - download: all下载全部结果对应的 PDF其中- max:覆盖MAX_RESULTS- dir:覆盖PAPER_DIR- download下载第一条- download: all下载全部。二、Step 1 参数解析查询词还是 arXiv ID技能第一步是解析$ARGUMENTS判定输入属于两类主题查询词如attention mechanism、diffusion models走搜索流程裸 arXiv ID新版格式2301.07041YYMM.NNNNN或旧版格式cs/0601001category/NNNNNNN一旦命中 ID 正则跳过搜索直接进入 Step 3 详情拉取。底层脚本对 ID 的处理比技能文档描述得更细致。看 tools/arxiv_fetch.py 中的_normalize_id()与_looks_like_arxiv_id()正则^\d{4}\.\d{4,5}(v\d)?$匹配新版 ID兼容v1版本后缀正则^[A-Za-z.-]/\d{7}(v\d)?$匹配旧版 ID_normalize_id()会剥掉 URL 前缀/abs/之后的部分、id:前缀以及版本号vN得到一个干净 ID。也就是说即使你粘贴了https://arxiv.org/abs/2301.07041v3这类完整 URL 或带版本号的 ID脚本也能正确归一化。此外脚本在构建 API 参数时_api_url()对id:前缀和裸 ID 一律走id_list参数对普通查询词才走search_query全字段检索。三、Step 2 搜索标准助手解析链与内联 Python 双保险解析链Policy D1技能文档明确要求通过integration-contract.md定义的“主辅助脚本 首次成功级联”Policy D1来解析$ARXIV_FETCHER其解析块如下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 $1repo_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_FETCHERtools/arxiv_fetch.py [ -f $ARXIV_FETCHER ] || { [ -n ${ARIS_REPO:-} ] ARXIV_FETCHER$ARIS_REPO/tools/arxiv_fetch.py; } [ -f $ARXIV_FETCHER ] || ARXIV_FETCHER这对应 skills/shared-references/integration-contract.md §2 的四层解析层级路径适用场景L1.aris/tools/arxiv_fetch.pyinstall_aris.sh符号链接安装后的默认位置L2tools/arxiv_fetch.py在 ARIS 仓库内运行或手动拷贝到用户项目L3$ARIS_REPO/tools/arxiv_fetch.py环境变量显式设置或从.aris/installed-skills.txt的repo_root字段自动解析L4$ARIS_REPO/tools/arxiv_fetch.py经~/.aris/repo全局安装~/.claude/skills/时由安装/更新脚本写入的全局指针文件解析块必须采用“strict-safe”写法|| true吞掉 awk 非零退出码、[ -f ]判断而非chmod x这样即使调用方开启了set -e也不会提前退出。集成契约文档还特别警告解析块不应被包在set -e/set -eu中因为${ARIS_REPO:-$(awk ...)}会把内层 awk 的退出码传播给set -e在常见的“尚无.aris/installed-skills.txt”场景下会以码 2 静默退出掩盖真实的失败原因。标准调用与内联回退解析成功后执行python3 $ARXIV_FETCHER search QUERY --max MAX_RESULTS如果$ARXIV_FETCHER为空级联链耗尽技能文档提供了完整的内联 Python 回退直接用urllib请求http://export.arxiv.org/api/querysearch_querymax_resultssortByrelevancesortOrderdescending解析 Atom 流并输出 JSON。这意味着即使辅助脚本在任何位置都找不到技能依然能完成检索——这是 Policy D1“主辅助脚本 首成功级联”的典型体现主路径失败不阻塞任务而是降级到零依赖的纯标准库实现。结果展示格式无论走哪条路径结果都以表格呈现arXiv ID 必须醒目展示| # | arXiv ID | Title | Authors | Date | Category | |---|------------|---------------------|----------------|------------|----------| | 1 | 2301.07041 | Attention Is All... | Vaswani et al. | 2017-06-12 | cs.LG |四、底层实现的工程细节限流、UA 与防伪校验tools/arxiv_fetch.py不只是文档里那几行命令的简单封装它在请求层做了大量可靠性设计这些细节在 tests/test_arxiv_fetch.py 中有完整测试锁定。1. 描述性 User-Agent进入宽松限流池arXiv 对默认的Python-urllib/x.y代理的限流远比具名客户端激进。_arxiv_user_agent()因此构造arxiv-skill/1.0 (https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep)这样的描述性 UA如果设置了环境变量ARIS_VERIFY_EMAIL与tools/research_wiki.py、tools/verify_papers.py共用还会追加(mailto:contact)让请求进入 arXiv 的宽松限流池。测试test_user_agent_includes_contact_when_env_set验证了这一点。2. 三重退避重试_fetch_atom()最多重试 3 次覆盖四类失败HTTP 429每次等待5 * attempt秒后重试临时网络错误URLError/TimeoutError/OSError等待2 * attempt秒重试明文Rate exceeded.响应体arXiv 偶尔会以 200 OK 返回纯文本限流提示脚本会识别该特征并按 429 同等退避3 次耗尽后抛出RuntimeError。PDF 下载路径download()对 429 同样执行5 * attempt退避网络错误则2 * attempt。3. PDF 防伪双重校验_validate_pdf()是下载链路的守护闸门同时检查两项文件大小≥ 10 KB_MIN_PDF_BYTES 10_240——更小几乎必然是错误 HTML 页前 1024 字节包含%PDF-魔数——排除“体积够大但不是 PDF”的伪文件。更有意思的是缓存中毒自愈逻辑若目标路径已存在同名.pdf脚本会先校验已有文件一旦发现是无效文件例如旧版本脚本误存的 HTML主动删除该坏缓存并重新下载而不是永远失败。测试test_download_rejects_cached_non_pdf_response验证了坏缓存被驱逐的行为。4. 命令别名与防御式设计CLI 子命令除了search和download还注册了get、fetch作为search的防御性别名——这是针对 LLM 模型经常幻觉出不存在的子命令名而设计的无论模型说“get”还是“fetch”调用都能成功。download子命令支持--dir默认papers和--delay默认 1.0 秒下载后休眠用于避免连续请求触发限流。五、Step 3-4单篇详情与 PDF 下载单篇 ID 详情直接命中 ID 或从 Step 2 选中单篇时python3 $ARXIV_FETCHER search id:ARXIV_ID --max 1 # 或回退 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_listARXIV_ID with urllib.request.urlopen(url, timeout30) as r: root ET.fromstring(r.read()) # print full details ... 输出必须包含标题、全部作者、分类、完整摘要、发布日期、PDF 链接、摘要页链接。底层_parse_entry()还会额外解析出updated更新时间字段并把pdf_url/abs_url一并构好返回 JSON供后续步骤直接消费。PDF 下载与校验# 标准脚本路径 python3 $ARXIV_FETCHER download ARXIV_ID --dir PAPER_DIR下载后必须执行三项纪律技能文档的 Key Rules 与源码双重强调校验大小 10 KB否则视为错误页并告警删除限流间隔连续下载之间等待 1 秒脚本侧--delay 1.0默认值即此不覆盖已存在文件目标路径已存在则跳过并报告already exists同时复用缓存校验逻辑确认存量文件合法。文件名中的/会被替换为_safe_id clean_id.replace(/, _)因此旧版 IDcs/0601001会落盘为papers/cs_0601001.pdf避免路径歧义。六、Step 5-6摘要模板与研究 Wiki 归档标准化摘要每篇论文无论来自搜索还是详情按统一 Markdown 模板总结保证跨技能的信息结构一致## [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)研究 Wiki 自动归档Variant B当项目存在research-wiki/目录时技能触发 Step 6 的 wiki 归档。解析$WIKI_SCRIPT遵循skills/shared-references/wiki-helper-resolution.md的 Variant Bwarn-and-skip辅助脚本缺失时告警但跳过主输出不受影响解析链与$ARXIV_FETCHER同构.aris/tools/→tools/→$ARIS_REPO/tools/→~/.aris/repo。归档核心命令是python3 $WIKI_SCRIPT ingest_paper research-wiki/ --arxiv-id arxiv_idresearch_wiki.py的ingest_paper子命令见 tools/research_wiki.py 头部用法说明在一个调用内完成arXiv 元数据抓取、slug 生成、去重、页面创建、索引重建与日志追加。技能文档特别强调不要手写papers/slug.md——页面 schema 由统一辅助脚本生成任何技能都不复制这套逻辑这正是集成契约“canonical helper一份实现而非复制粘贴”的落地。若某次归档因故遗漏可事后批量回填python3 $WIKI_SCRIPT sync research-wiki/ --arxiv-ids id1,id2,... # 或从文件读取 python3 $WIKI_SCRIPT sync research-wiki/ --from-file ids.txt值得注意的细节research_wiki.py的 slug 生成slugify()对非 ASCII 论文标题做了专门处理——保留非 ASCII 字母而非粗暴剔除避免中文论文全部塌缩成year_untitled导致同年同作者的论文因 slug 撞车被静默去重。七、Step 7 收尾与跨技能衔接最终输出技能要求以可验证的清单收尾Found N papers for queryDownloaded: 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这条衔接不是随便写的research-lit技能内部skills/research-lit/SKILL.md把arxiv_fetch.py作为多源聚合Policy D2的一个数据源——它用同样的四层解析链解析$ARXIV_FETCHER成功则纳入sources_used聚合清单失败则告警并继续用 WebSearch 兜底。也就是说/arxiv的产出既是终点本地论文库也是/research-lit综述、/novelty-check查新等下游流程的输入。八、Key Rules 速查与边界行为技能文档的最后一部分是必须始终遵守的硬性规则也是 Agent 执行时的行为底线arXiv ID 必须醒目展示——它是引用与复现的锚点PDF 校验 10 KB过小文件告警并删除限流纪律连续下载间隔 1 秒HTTP 429 后等待 5 秒重试一次绝不覆盖已有 PDF跳过并报告already exists兼容双 ID 格式新版2301.07041与旧版cs/0601001PAPER_DIR自动创建API 不可达时明确报错并建议改用/research-lit - sources: web作为替代文献源。九、快速上手示例将 ARIS 技能安装到项目后bash tools/install_aris.sh详见 tools/install_aris.sh 的用法说明即可直接对 Agent 下达如下指令/arxiv mixture of experts - max: 20 /arxiv 2301.07041 - download /arxiv retrieval augmented generation - download: all - dir: literature/r4g/执行链路依次是参数解析 → ID 判定 → 解析$ARXIV_FETCHER→ API 搜索或id_list详情→ 结果表格展示 → PDF 下载与双重校验 → 摘要模板输出 →research-wiki/存在时自动归档。全过程不依赖任何第三方框架纯标准库 Python 加 Bash这正是 ARIS“Lightweight Markdown-only skills”设计哲学的缩影——技能即文档文档即可执行。十、进一步阅读skills/arxiv/SKILL.md本文的骨架文档技能的权威行为定义tools/arxiv_fetch.py搜索/下载辅助脚本的完整源码含 UA、重试、防伪校验tests/test_arxiv_fetch.pyUA 与 429 重试行为的测试用例skills/shared-references/integration-contract.md跨技能集成契约§2 解析链、Policy D1/D2 失败策略skills/shared-references/wiki-helper-resolution.mdResearch Wiki 辅助脚本解析链Variant B warn-and-skiptools/research_wiki.pyingest_paper/sync等 wiki 归档子命令tools/install_aris.sh技能与.aris/tools/符号链接的安装器【免费下载链接】Auto-claude-code-research-in-sleepARIS ⚔️ (Auto-Research-In-Sleep) — Lightweight Markdown-only skills for autonomous ML research: cross-model review loops, idea discovery, and experiment automation. No framework, no lock-in — works with Claude Code, Codex, OpenClaw, or any LLM agent.项目地址: https://gitcode.com/gh_mirrors/au/Auto-claude-code-research-in-sleep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考