literature-engineer

文献工程师（证据收集器）

触发条件与路由

• 触发条件：证据收集器、文献工程师、文献扩充、多路召回、滚雪球、被引用、参考文献、元信息增强、来源溯源。
• 适用场景：工作流需要按照锁定的检索策略扩充候选文献，并补齐可追溯的元数据。

目标：为后续去重、排序、映射、笔记、引文和起草构建一个规模大且可验证的候选池。

这项技能以证据优先为原则：如果无法通过可验证的 ID 和来源溯源达到目标规模，正确的做法是阻止流程并要求提供更多导出文件或启用网络，而不是捏造信息。

加载顺序

始终读取：

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

领域包（按主题匹配加载）：

• assets/domain_packs/llm_agents.json — LLM Agent 主题的固定经典论文和综述 arXiv ID

脚本边界

仅在以下情况下使用 scripts/run.py：

• 多路离线导入、规范化和来源标注
• 在线 arXiv/Semantic Scholar API 检索
• 滚雪球扩展和去重
• 生成检索报告

不要将 run.py 用于：

• 硬编码固定 arXiv ID 列表（使用领域包）
• 硬编码主题检测逻辑（使用领域包）

输入

• queries.md
  • keywords、exclude、max_results、time window
• 可选离线来源（可任意组合；所有来源都会合并）：
  • papers/import.(csv|json|jsonl|bib)
  • papers/arxiv_export.(csv|json|jsonl|bib)
  • papers/imports/*.(csv|json|jsonl|bib)
• 可选滚雪球导出文件（离线）：
  • papers/snowball/*.(csv|json|jsonl|bib)

输出

• papers/papers_raw.jsonl
  • 每行 1 条记录；至少包含以下字段：
    • title（str）、authors（list[str]）、year（int|""）、url（str）
    • 稳定标识符：arxiv_id 和/或 doi
    • abstract（str；离线模式下可以为空）
    • source（str）+ provenance（list[dict]）
• papers/papers_raw.csv（供人工浏览）
• papers/retrieval_report.md（路由计数、缺失元数据统计、后续操作）

工作流（多路）

1. 离线优先合并：导入所有可用的离线导出文件（并按文件标注来源溯源）。
2. 在线检索（可选）：如果已启用，则针对每条关键词查询运行 arXiv API 检索。
3. 滚雪球（可选）：通过参考文献/被引用关系从种子论文扩展（在线），或合并离线滚雪球导出文件。
4. 规范化 + 去重：将 ID/URL 规范化，合并重复记录，同时汇总 provenance。
5. 报告：生成简明的检索报告，其中包含覆盖情况分类和缺失元数据计数。

质量检查清单

• 候选池在不捏造信息的前提下达到当前工作流声明的检索下限。对于包含 retrieval_policy.minimum_records 的工作流，使用该值；综述配置也可以根据 core_size 推导出更严格的候选池目标。
• 每条记录都有稳定标识符（arxiv_id 或 doi，以及 url）。
• 每条记录都有来源溯源信息：由哪个路由/文件/API 提供。

脚本

快速开始

• uv run python .codex/skills/literature-engineer/scripts/run.py --help

所有选项

• 查看 uv run python .codex/skills/literature-engineer/scripts/run.py --help。
• 从 queries.md 读取检索配置。
• 离线输入（如存在则合并）：papers/import.(csv|json|jsonl|bib)、papers/arxiv_export.(csv|json|jsonl|bib)、papers/imports/*.(csv|json|jsonl|bib)。
• 可选的离线滚雪球输入：papers/snowball/*.(csv|json|jsonl|bib)。
• 在线扩展需要网络：使用 --online 和/或 --snowball。
• 在线检索尽力而为：某些环境中的 arXiv API 可能不稳定；必要时，脚本也会尝试使用 Semantic Scholar 路径。
• 对于 LLM Agent 主题，脚本还会尽力通过固定的 arXiv id_list 获取论文（包括 ReAct/Toolformer/Reflexion/Voyager/Tree-of-Thoughts 等经典论文，以及一小组早期综述种子），以便即使关键词检索未找到这些论文，ref.bib 也能包含必须引用的关键文献。
• 如果与外部域名的 HTTPS/TLS 连接不稳定，则通过 r.jina.ai 代理获取 Semantic Scholar 路径的数据，让流水线仍能在无需手动导出的情况下自行启动。
• 如果在线运行因临时网络错误而返回 0 条记录，通常简单重试即可（流水线不应编造记录）。

示例

• 仅使用离线导入：

  • 将导出文件放在 papers/imports/ 下，然后运行：
    • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace>

• 指定离线输入（多路径）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --input path/to/a.bib --input path/to/b.jsonl

• 在线检索 arXiv（需要网络）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --online

• 滚雪球（需要网络，除非你提供离线滚雪球导出文件）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --snowball

故障排除

问题：无法达到当前 Workflow 的候选池目标

症状：

• papers/papers_raw.jsonl 中的记录数低于锁定的 Workflow 声明的明确最低值或根据配置推导出的最低值。

原因：

• 仅提供了少量离线导出文件。
• 网络受限，无法运行在线检索或滚雪球。

解决方案：

• 在 papers/imports/ 下提供更多导出文件（多个路径/查询）。
• 在 papers/snowball/ 下提供滚雪球导出文件。
• 启用网络并使用 --online --snowball 重新运行。

问题：许多记录缺少稳定 ID

症状：

• 报告显示许多条目的 arxiv_id 和 doi 为空。

解决方案：

• 优先使用包含稳定 ID 的 arXiv/OpenReview/ACL 导出文件。
• 如果有网络，请使用 --online 重新运行以补充 arXiv ID。
• 在下游生成引用之前筛除缺少 ID 的条目。