arXiv 检索（以元数据为先）

收集一批初始论文，确保其包含足够丰富的元数据，以支撑下游的排序、分类体系构建及参考文献生成。

在线状态下，优先采用高质量的 arXiv 元数据（如分类标签、arxiv_id、pdf_url、published/updated 时间等）；离线状态下，则接受用户提供的导出文件，并完成干净、规范的格式转换。

加载顺序

始终需阅读：

• references/domain_pack_overview.md —— 域包（domain pack）如何驱动特定主题的行为逻辑

域包（依据主题匹配自动加载）：

• assets/domain_packs/llm_agents.json —— 预设论文 ID 列表、LLM agent 相关主题的查询重写规则

脚本边界

仅在以下场景中使用 scripts/run.py：

• 调用 arXiv API 获取数据并解析 XML 响应
• 离线导出文件转换（对 CSV/JSON/JSONL 进行标准化归一）
• 通过 id_list 回填方式增强元数据

请勿将 run.py 用作以下用途：

• 硬编码的主题检测或查询重写（应使用 domain pack 实现）
• 领域专属的预设论文列表（须外置至 assets/domain_packs/ 目录下）

输入

• queries.md（含关键词、排除项、时间窗口等配置）

输出

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

决策：在线 vs 离线

• 若具备网络访问能力：执行 arXiv API 检索。
• 若无网络：导入用户提供的导出文件（CSV/JSON/JSONL），并对字段进行标准化处理。
• 混合模式：若先以离线方式导入，后续恢复网络连接后，可通过 arXiv id_list 对缺失字段（如 abstract/authors/categories）进行元数据增强，启用方式为指定 --enrich-metadata 参数，或在 queries.md 中设置 enrich_metadata: true。

工作流（启发式）

1. 读取 queries.md 并展开为具体查询字符串。
2. 在线模式下执行检索；离线模式下导入导出文件。
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/ 目录写入任何正文内容。

脚本

快速开始

• python scripts/run.py --help
• 在线模式：python scripts/run.py --workspace --query "" --max-results 200
• 离线导入：python scripts/run.py --workspace --input

全部参数选项

• --query ：可重复使用；多个 --query 将被合并为并集查询
• --exclude ：可重复使用；排除规则在检索完成后应用
• --max-results ：限制总检索数量上限
• --input ：离线模式（支持 CSV/JSON/JSONL）
• --enrich-metadata：尽力通过 arXiv id_list 增强元数据（需联网）
• queries.md 同样支持如下字段：keywords、exclude、time window、max_results、enrich_metadata

示例

• 在线模式（多查询 + 排除项）：
  • python scripts/run.py --workspace --query "LLM agent" --query "tool use" --exclude "survey" --max-results 300
• 按 arXiv ID 直接获取单篇论文（直接使用 id_list 查询）：
  • python scripts/run.py --workspace --query 2509.02547 --max-results 1
• 离线模式自动识别（无需显式参数）：
  • 将 papers/import.csv（或 .json/.jsonl）置于 workspace 目录下，然后运行：python scripts/run.py --workspace
• 离线导入 + 时间窗口（通过 queries.md 配置）：
  • 在 queries.md 中设置 - time window: { from: 2022, to: 2025 }，再正常执行离线导入

故障排查

常见问题

问题：papers/papers_raw.jsonl 为空

现象：

• 脚本退出时提示 “No results returned …”，或输出文件为空。

可能原因：

• 网络被阻断（在线模式下）。
• 查询条件过于严苛，或 queries.md 为空。

解决方案：

• 改用离线导入：将 papers/import.csv|json|jsonl 放入 workspace，或显式传入 --input 参数。
• 放宽关键词范围，减少 queries.md 中的排除项。
• 使用显式的 --query 参数运行脚本，验证查询解析逻辑是否正常。

问题：离线导入记录缺失关键字段

现象：

• 下游流程因记录缺失 authors/year/abstract/url 字段而失败。

可能原因：

• 导出文件列名与预期字段不匹配；上游导出数据本身不完整。

解决方案：

• 确保导出文件至少包含 title、authors、year、url、abstract 字段。
• 若后续恢复网络连接，可使用 --enrich-metadata 尽力回填缺失字段。

恢复检查清单

• 确认 queries.md 中 keywords 非空（或已通过 --query 显式传入）。
• 若为离线模式：确认 workspace 中存在 papers/import.* 文件，并重新运行脚本。
• 抽样检查 3–5 行 JSONL 记录：确认每行为合法 JSON，且包含所有必需字段。