paper-search：检索执行规程

目的

为上层技能（literature-search 等）提供可执行的检索规程：如何构建 query、 如何调用 scripts/search_papers.py、如何遵守各数据源的请求礼仪、 如何解读与排序结果、如何处理失败。

脚本约定（scripts/search_papers.py，纯 Python 标准库实现，无第三方依赖）：

• 参数：--query（必填）、--provider {openalex,crossref,arxiv}（必填）、 --limit N（默认 10，上限 50，超出自动截断）、--format json。
• 成功：stdout 输出 PaperDocument JSON 数组，退出码 0。
• 失败：stdout 输出 {"error": {"provider", "type", "message"}}， type ∈ network | rate_limited | parse，退出码 1；永不抛栈崩溃。
• 内置礼仪：请求间隔 ≥0.5s、单请求超时 30s、UA 携带联系邮箱占位。

前置检查

1. scripts/search_papers.py 存在；python --version 可用（3.8+）。
2. 网络可用；目标 provider 可达。
3. 已按上层路由确定 provider 与 query。

操作规程

1. query 构建

• 关键词以英文为主（三个 provider 对英文支持最好）；专业术语保留原文。
• 布尔与字段限定（按 provider 方言）：
  • OpenAlex：search 参数支持 AND / OR 与引号短语，如 "large language model" AND agent；复杂字段过滤（年份、类型）由上层 在结果上后置处理，当前脚本只暴露 search。
  • Crossref：query 为自由文本，偏题录精确匹配；查单篇文献时直接把标题 或 DOI 作为 query 效果最佳。
  • arXiv：search_query 自动加 all: 前缀；需要字段限定时可在 query 中 直接使用 ti:（标题）、abs:（摘要）、au:（作者），组合用 +AND+ / +OR+。
• 单次 query 控制在 2-6 个核心词；过长的 query 会显著降低命中率。

2. 执行

python scripts/search_papers.py --query "large language model agents" \
  --provider openalex --limit 20 --format json

• 多个 provider 时逐次串行调用，不要并发轰炸同一数据源。
• 结果较大时重定向到临时文件再解析，避免终端输出截断。

3. 请求礼仪（politeness）

• 频率 ≤2 req/s；脚本已内置 ≥0.5s 请求间隔，上层批量调用时仍应串行执行。
• UA 中的联系邮箱是占位 you@example.com：正式使用前提醒用户替换为真实 邮箱（OpenAlex polite pool 与 Crossref 均以此为诚信标识，提供更稳定服务）。
• 收到 rate_limited 时按指数退避重试：2s → 4s → 8s，最多 3 次； 仍失败则把结构化 error 原样交还上层，不无限重试。

4. 结果解读与排序建议

• 各源默认相关性排序；解读时注意：
  • OpenAlex 结果元数据丰富，适合按「相关性 + 被引 + 年份」二次排序；
  • Crossref 偏题录精确匹配，前排结果通常就是目标文献；
  • arXiv 偏最新成果，注意区分预印本与正式发表版（条目含 journal_ref 时 优先引用正式版）。
• 建议上层保留原始顺序，另存「建议阅读顺序」，不要在 papers.json 里原地重排。

5. 失败处理

• 逐字保留脚本输出的 error JSON，原样写入上层 manifest；
• parse 类错误记录响应片段（≤200 字符）便于排查；
• 任何失败都不改写成「0 条结果」。

6. provider 查询方言速查

--limit 与各源单页上限：脚本上限 50，三源单页均可满足；需要更多结果时 由上层分批翻页（当前脚本不暴露 start / cursor 参数）。

7. 常见失败与对策

任何重试都不更换 query 内容；换 query 属于上层 literature-search 的决策。 脚本单请求超时固定 30s，超时归入 network 类错误；不要为「快一点」 而调小间隔或并发请求——被封 IP 的代价远大于多等几秒。

输出模板

PaperDocument（stdout，成功时）

[
  {
    "id": "https://doi.org/10.xxxx/yyyy",
    "title": "...",
    "authors": ["..."],
    "year": 2024,
    "venue": "...",
    "doi": "10.xxxx/yyyy",
    "url": "https://doi.org/10.xxxx/yyyy",
    "abstract": "...",
    "source": "crossref",
    "retrieved_at": "2026-08-18T00:00:00+00:00"
  }
]

错误对象（stdout，失败时，退出码 1）

{"error": {"provider": "crossref", "type": "rate_limited", "message": "HTTP 429 ..."}}

本技能不做什么

• 不做多源合并与去重（交给 literature-search）。
• 不评价文献质量、不做证据提取（交给 literature-survey）。
• 不抓取付费墙全文；只取 API 公开的元数据与摘要。
• 不支持 openalex / crossref / arxiv 之外的源（扩展需先修改脚本）。
• 不缓存历史检索结果充当新结果。

收尾与下一步

1. 把 PaperDocument 数组或 error JSON 原样交还调用方。
2. 提示命中数与建议的二次排序方式。
3. 若连续 rate_limited，建议上层降低频率、稍后再试，或更换 provider。
4. 结果为空数组时区分「源站确实无命中」与「检索被静默截断」， 后者按失败处理并留痕。