OpenAlex → Web of Science 格式导出

把 OpenAlex 的检索结果批量导出成能被 EndNote / CiteSpace / VOSviewer / bibliometrix
读取的 ISI tagged 文件（savedrecs.txt），并带上每篇论文的参考文献列表。

输出文件夹规范（按数据源分文件夹，务必遵守）

同一工作区可能同时用 Scopus / OpenAlex / WoS 等多个数据源导出，所有导出和派生产物必须按数据源分文件夹存放，避免混在一个目录里：

<工作目录>/                  # 默认当前工作区根目录，或用户指定的目录
├── scopus/                  # Scopus 检索导出的原始数据（CSV/JSON）
├── openalex/                # OpenAlex 检索导出的原始数据（JSON/savedrecs.txt）
├── vosviewer/
│   ├── scopus/              # 基于 Scopus 数据生成的 map/network/截图
│   └── openalex/            # 基于 OpenAlex 数据生成的 map/network/截图
└── scripts/                 # 一次性转换脚本（可选）

• 两个脚本的默认 --outdir 都指向当前工作目录下对应数据源的子文件夹（本脚本 → openalex/）。
• 用户显式给了输出路径时以用户为准；没给时按上面的规范落位，并向用户说明文件放哪了。
• VOSviewer 建图产物（map/network/GML/截图）放 vosviewer/<数据源>/，不要和数据混放。

三条官方硬规则（2026-10 文档核对，务必照做）

1. 认证与额度 — https://help.openalex.org/api/authentication/

• key 走 api_key 查询参数，或 Authorization: Bearer <key>，两者等价；pyalex 用前者。
• 无 key：$0.1/天 ≈ 1,000 credits；免费 key：$1/天 = 10,000 credits（10×）。
• 端点计价：singleton $0 / list $0.0001（1 credit）/ search $0.001（10 credits）。
  一次 filter=... 列表查询 = 1 credit，所以"每批 100 个 ID 批量回查"是最省的用法。
• 限速：无 key 10 rps；免费 key 30 rps；检索式含 >5 个 OR/AND/NOT 时降到 5 rps。
  超速的 429 不扣费，等一会儿重试即可。
• 429 要指数退避（脚本内置 2^n 秒 + pyalex max_retries=5）。
• 查余额：curl "https://api.openalex.org/rate-limit?api_key=KEY"，
  或看响应头 X-RateLimit-Remaining / X-RateLimit-Remaining-USD / X-RateLimit-Reset。

key 的取法（脚本已实现三层优先级）：--api-key > 环境变量 OPENALEX_API_KEY >
.env 文件。默认会依次找
~/.env、~/Desktop/.env、脚本同目录 .env，
键名兼容 OPENALEX_API_KEY / OpenAlexApi_key / OPENALEX_KEY（大小写、下划线都会归一化）。

用户第一次用 OpenAlex、没有账户时：agent 可一键代办。 一次 POST 即可代用户申请
（无需用户先注册、无需复制粘贴）：

curl -X POST https://api.openalex.org/api-keys \
  -H "Content-Type: application/json" \
  -d '{"email": "<用户的真实邮箱>"}'

要点：必须先向用户要真实邮箱，绝不能编造（占位邮箱、agent 命名的邮箱会被拒；
已有账户会返回 409，让用户去 Settings → API key 自取）；OpenAlex 会发激活邮件，
用户点了链接 key 才生效（$1/天，7 天内有效，过期可重发），未激活时调用返回
403 key_not_activated；建议带 Idempotency-Key 头（UUID）让重试拿到同一把 key。
完整流程、全部响应码与轮换规则见
references/api-authentication.md。

2. 分页 — https://help.openalex.org/api/paging/

• per_page 最大 100（200 是已废弃的旧行为，别依赖）。
• 基础分页（page=N&per_page=100）：page × per_page ≤ 10,000，再深就报错。
• cursor 分页：cursor=* 起步，之后用 meta.next_cursor；无深度上限，但第二页起必须有 key
  （无 key 跟 next_cursor 直接 401）。
• 因此：有 key → cursor 分页；无 key → 退回 page 分页并提示 1 万条上限。
• 不要用 cursor 去"下载整个 /works 库"，那是几天的量，该用 OpenAlex snapshot。

3. 表达式与字段限制

• 单个 filter 的 OR 取值上限 100 个 → 批量查 ID 时每批最多 100 个：
  filter=ids.openalex:W1|W2|...（本脚本 CHUNK = 100）。
• 用 select= 只要需要的字段，响应更快、也少踩上下文超限。

快速使用

PY=python    

# 默认：近5年电化学 Top100，含参考文献，输出到桌面
$PY {SKILL_DIR}/scripts/export_openalex_wos.py

# 自定义检索式 / 年份 / 条数
$PY {SKILL_DIR}/scripts/export_openalex_wos.py \
    --query "electrocatalysis OR electrocatalyst" --years 2016-2026 --total 500

常用开关：

直接喂 bibliometrix：WoS txt 就够了（不必再出 bib）

本脚本导出的 WoS 纯文本 bibliometrix 5.x 可以直读，做 bibliometrix 分析时用默认
--format wos 即可，不需要 bib（bib 只在需要 Scopus 风格 BibTeX 的其他工具时有意义）：

# 5.x 格式名是 plaintext（4.x 及旧教程写作 plain-text，5.x 会报错）
M <- bibliometrix::convert2df("openalex/xxx.txt", dbsource = "wos", format = "plaintext")
# 国家分析必须显式抽一次（convert2df 不会自动填 AU_CO）
M <- bibliometrix::metaTagExtraction(M, Field = "AU_CO")

实测 1000 条 txt 直读：CR 非空 584、DE 非空 999、AU_CO 命中 503，与 bib 路径（516/971）等价。

国家/地区标注已内置：脚本把机构所在国家（ISO2→英文名）追加在机构名后写入
C1/RP/affiliation（如 Harvard University, USA），bibliometrix 的国家分布与国家合作网络
开箱即用。两个硬约束（实测踩坑）：
- 国名必须全大写——metaTagExtraction("AU_CO") 用 gregexpr(fixed=TRUE) 对
data(countries) 词表（202 项，全大写）做大小写敏感子串匹配，混合大小写一个都匹配不上；
- 韩国写 KOREA——词表里没有 "SOUTH KOREA"。

导出 bib（给需要 Scopus 风格 BibTeX 的场景）

OpenAlex 没有 BibTeX 端点，所以脚本按 Scopus BibTeX 的字段规范自己生成——字段名逐条对齐
bibliometrix 的 data/bibtag.rda 映射，不是随手起的名：

# 只出 bib
$PY {SKILL_DIR}/scripts/export_openalex_wos.py --query "..." --total 500 --format bib

# 两个格式都要（共用同一次检索与参考文献回查，不额外扣额度）
$PY {SKILL_DIR}/scripts/export_openalex_wos.py --query "..." --total 500 --format both

M <- bibliometrix::convert2df("openalex/xxx.bib", dbsource = "scopus", format = "bibtex")

注意：
- OpenAlex 的 referenced_works 里查不回来的条目仍会写成 [未解析:Wxxxx]，会进 CR 字段（与 WoS 版一致）。
- bib 与 txt 使用同一次检索结果与同一份参考文献回查结果，--format both 不会多花一分钱。
- 因为 convert2df 对 scopus+bibtex 用 TI 去重，标题完全相同的两条会被并成一条，属预期行为。

原始 JSON 批量抓取（fetch_openalex_raw.py）

不转 WoS，要 OpenAlex API 默认 JSON 全记录（53 个字段，含摘要倒排索引、
referenced_works、locations、topics 等）时用这个。一次下载最后合并保存为一个结果文件：

$PY {SKILL_DIR}/scripts/fetch_openalex_raw.py                       # 电化学 2021-2026 前 2000 条（相关度降序）
$PY {SKILL_DIR}/scripts/fetch_openalex_raw.py --total 5000 \
    --query "electrocatalysis" --years 2016-2026 --outdir D:/tmp --name "openalex_ecat"

# 排序选项（--sort）：用户可能要求按相关度 / 被引次数 / 出版年取文献
$PY {SKILL_DIR}/scripts/fetch_openalex_raw.py \
    --query "sustainable development|sustainability" --total 1000 --sort cited   # 被引降序 Top1000
$PY {SKILL_DIR}/scripts/fetch_openalex_raw.py --sort year --total 500            # 出版年降序（最新在前）

• --sort 排序选项（默认 relevance）：
• relevance 相关度降序（依赖 .search 过滤器，默认行为）
• cited 被引次数降序 —— 「导出被引最高的 N 篇」场景必选；跨页基本无重复
• cited_asc 被引升序；year 出版年降序（最新在前）；year_asc 出版年升序
• 非 relevance 排序时返回的是全库该排序下的前 N 条；配合 --years 限定时间窗
• 实际排序值会写进 meta.export.sort，便于溯源
• 输出单个 {"meta":..., "results":[全部记录按页序拼接]} 文件：
  meta 取第一页，并追加 meta.export 块（检索式、年份、条数、页数、抓取时间），便于溯源。
• 输出目录：默认写到当前工作目录下的 openalex/ 子文件夹（数据源分文件夹规范，
  见下）；也可用 --outdir 显式指定。
• 默认只留合并文件；--keep-pages 可额外保留逐页原始响应体（存到 outdir/pages/）。
• cursor 分页 + per_page=100 + 429 指数退避；key 自动从 .env 读。
• 成本：search 端点 10 credits/页 → 2000 条 ≈ 200 credits（$0.02）。
• 实测 2000 条约 33 MB、90 秒；相关性排序下跨页偶有少量重复（约 0.4%），
  下游按 id 去重即可。

实测成本（100 篇 + 6,320 条参考文献回查）：84 credits ≈ $0.0084，17 秒。

字段映射（WoS 标签）

排版规则（用户明确要求，别改回去）

• 所有多值字段一条目一行：AU / C1 / DE / CR / EM / RI / OI / FU。
• group（默认）：仅首行带字段名，后续每条缩进 3 空格（正好 XX 的宽度），正文上下对齐。
• repeat：每行都带字段名，标准 ISI 写法，喂 EndNote / CiteSpace / VOSviewer 时用这个，
  否则整块会被当成一条引用吞掉。
• 单值长文本（TI / AB / AF / RP）超过 110 字符按 3 空格缩进折行。
• 文件：UTF-8、CRLF、FN/VR 1.0 开头、ER 逐条分隔、EF 结尾。

已知数据缺口

• referenced_works 只给 ID 不给题录，必须二次回查；被删除/合并的 ID 查不回来，
  会写成 [未解析:Wxxxx]（100 篇里通常 40 条左右）。
• 不是每篇都有参考文献：book-chapter、preprint、dataset 常缺（实测 100 篇里 56 篇有）。
• 期刊缩写 J9/JI 没有缩写库，填的是全称。
• UT 放 OpenAlex ID 属于借用字段位：自用追溯没问题，但严格按 WoS 语义去重的工具
  会把它当入藏号，届时用 --ut-format id 之外的方式处理或直接抽掉。

离线排版互转（不耗额度）

已经导出的 txt 想换排版，不用重跑检索：

$PY {SKILL_DIR}/scripts/wos_group_fields.py "文件.txt"                       # → group（默认）
$PY {SKILL_DIR}/scripts/wos_group_fields.py "文件.txt" --style repeat -o out.txt
$PY {SKILL_DIR}/scripts/wos_group_fields.py out.txt --input-style group --style group

脚本会先备份 .bak，幂等（group → group 输出与输入完全一致）。

踩过的坑

• pyalex paginate() 返回的是页（OpenAlexResponseList），要双层 for page: for w。
• pyalex.config 是 dict 子类，api_key 直接赋值即可；max_retries / retry_backoff_factor
  也在 config 里，别自己再包一层重试墙。
• WoS 里 CR 被拆行后极难还原（要靠"作者, 缩写, 年份, " 结构 + 贪心折行宽度倒推），
  所以脚本对 CR 永不折行，一条文献一行。
• add() 必须判 None，否则会写出 VL None 这种脏行。

参考文档（references/）

其他常用官方页面（均在 llms.md 索引内）：
分页、
过滤语法、
计费示例、
数据快照（超大数据量请用快照，别用 cursor 硬翻）。