arxiv-search

arXiv 搜索（元数据优先）

触发条件与路由

• 触发词：arXiv、arxiv、论文搜索、元数据检索、文献检索、论文检索、拉取元数据、离线导入。
• 适用场景：需要获取一组初始论文（survey/snapshot 的 Stage C1），来源为 arXiv（在线检索或离线导入 export）。

收集一组初始论文，并确保元数据足以支持后续排序、分类体系构建和引用生成。

在线检索时，优先获取丰富的 arXiv 元数据（分类、arxiv_id、pdf_url、发表时间/更新时间等）。离线检索时，接受 export 并进行规范转换。

加载顺序

始终读取：

• references/domain_pack_overview.md — 了解 domain pack 如何驱动特定主题的行为

按主题匹配加载 domain pack：

• assets/domain_packs/llm_agents.json — LLM Agent 主题的固定 ID 和查询改写规则

脚本边界

仅将 scripts/run.py 用于：

• arXiv API 检索和 XML 解析
• 离线 export 转换（CSV/JSON/JSONL 规范化）
• 通过 id_list 补全元数据

不要将 run.py 用作：

• 硬编码主题检测或查询改写（使用 domain pack）
• 特定领域的固定论文列表（移至 assets/domain_packs/）

基于契约的行为

• 对于广泛发现类工作流，默认使用 domain pack 改写查询。
• 专项工作流可以设置 quality_contract.retrieval_policy.domain_pack_query_mode: explicit；在这种 模式下，queries.md 中的查询列表仍为权威依据，domain pack 不得替换其主题焦点。
• quality_contract.retrieval_policy.minimum_records 会将工作流的原始 候选池下限转化为严格的质量门槛检查。

输入

• queries.md（关键词、排除项、时间范围）

输出

• papers/papers_raw.jsonl（JSONL；每行 1 篇论文）
  • 每条记录至少包含：title、authors、year、url、abstract
  • 使用 arXiv API 在线模式时，记录还会包含实用元数据：arxiv_id、pdf_url、categories、primary_category、published、updated、doi、journal_ref、comment
• 便捷索引（可选，但脚本会生成）：
  • papers/papers_raw.csv

决策：在线还是离线

• 如果可以访问网络：运行 arXiv API 检索。
• 如果无法访问网络：导入用户提供的 export（CSV/JSON/JSONL）并规范化字段。
• 混合模式：如果先离线导入，之后仍可访问网络，则可通过 arXiv id_list 补充缺失字段（摘要/作者/分类），使用 --enrich-metadata 或在 queries.md 中设置 enrich_metadata: true。

工作流（启发式）

1. 读取 queries.md 并扩展为具体查询字符串。
2. 检索结果（在线）或导入 export（离线）。
3. 将每条记录规范化，确保至少包含：
   • title、authors（数组）、year、url、abstract
4. 此阶段保留较宽泛的集合；去重和排序将在后续进行。
5. 如有指定，应用时间范围和 max_results。

质量检查清单

• 存在 papers/papers_raw.jsonl。
• 每行都是有效 JSON，且包含 title、authors、year、url。

副作用

• 允许：创建/覆盖 papers/papers_raw.jsonl；在 STATUS.md 中追加备注。
• 不允许：未获批准前在 output/ 中编写正文部分。

脚本

快速开始

• uv run python .codex/skills/arxiv-search/scripts/run.py --help
• 在线：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query "<query>" --max-results 200
• 离线导入：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --input <export.csv|json|jsonl>

全部选项

• --query <q>：可重复指定；多个查询的结果会合并
• --exclude <term>：可重复指定；检索后应用排除项
• --max-results <n>：限制检索结果总数
• --input <export.*>：离线模式（CSV/JSON/JSONL）
• --enrich-metadata：尽力通过 arXiv id_list 补充元数据（需要网络）
• queries.md 还支持：keywords、exclude、time window、max_results、enrich_metadata

示例

• 在线（多查询 + 排除项）：
  • uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query "LLM agent" --query "tool use" --exclude "survey" --max-results 300
• 按 arXiv ID 获取单篇论文（直接获取 id_list）：
  • uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query 2509.02547 --max-results 1
• 离线自动检测（不带标志）：
  • 将 papers/import.csv（或 .json/.jsonl）放在工作区下，然后运行：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace>
• 离线导入 + 时间范围（通过 queries.md）：
  • 设置 - time window: { from: 2022, to: 2025 }，然后正常运行离线导入

故障排除

常见问题

问题：papers/papers_raw.jsonl 为空

症状：

• 脚本退出并显示“未返回任何结果……”或输出文件为空。

原因：

• 网络受阻（在线模式）。
• 查询范围过窄，或 queries.md 为空。

解决方案：

• 使用离线导入：将 papers/import.csv|json|jsonl 放入工作区，或传入 --input。
• 扩大 queries.md 中的关键词范围并减少排除项。
• 使用显式的 --query 运行，以检查解析器是否正常。

问题：离线导入的记录缺少字段

症状：

• 后续步骤失败，因为记录缺少 authors/year/abstract/url。

原因：

• 导出列与预期字段不匹配；上游导出不完整。

解决方案：

• 确保导出内容至少包含 title、authors、year、url、abstract。
• 如果之后可以联网，使用 --enrich-metadata 尽力补全缺失字段。

恢复检查清单

• 确认 queries.md 中的 keywords 非空（或传入 --query）。
• 如果处于离线模式：确认工作区中有 papers/import.*，然后重新运行。
• 抽查 3–5 行 JSONL：确保 JSON 有效且包含必需字段。