VOSviewer 命令行技能

用命令行参数驱动 VOSviewer：启动时自动打开/创建地图、跑布局聚类、保存地图文件或导出截图；
也能从 Scopus/OpenAlex 取数或读任意题录文件，建好共现网络后直接出图（一条命令，见
scripts/vosviewer_pipeline.py）。

> v1.5.0 变更：-json 结论定案——按 VOSviewer Online 规范生成的 JSON 也读不了；决定性证据是
> 官方 -save_json 自产 JSON 回灌同样零输出，exe 与 jar 表现一致 → 参数实现失效，非格式问题。
> 新增"手上是 VOSviewer JSON 网络文件怎么办"：转 map/network 再出图（
> vosviewer-online-local/scripts/json_to_map_network.py，已实测出图）或走网页版 ?json=。
> v1.4.0 变更：脚本合并——make_vos_networks.py 与 openalex_to_vosviewer.py 合并为
> 单一入口 scripts/vosviewer_pipeline.py，同时具备「多数据源取数（OpenAlex/Scopus）+ 读文件
> （Scopus CSV/OpenAlex JSON/通用 CSV-TSV）+ 建网（作者/机构/关键词/引文）+ 运行 VOSviewer + 保存
> 地图与截图」能力；内置中文路径自动中转与静默失败检测。旧两个脚本已删除，等价能力见下文。
> v1.3.0 变更：新增"输出目录约定"——所有网络文件与导出截图统一存 <工作目录>\vosviewer_out\；
> Resources 新增跨技能链接 vosviewer-online-local（VOSviewer Online 本地版/网页版，交互可视化）。
> v1.2.0 变更：接入 openalex-wos-export 技能作为取数首选；移除 openalexnet 推荐（已停维护，
> 由"OpenAlex API + NetworkX"替代）；引用网络（--kind citations）、--api-key、
> per-page ≤ 100 与 429 退避；实测并记录 NetworkX write_gml/write_pajek 两个坑。

实测行为（在 Windows + VOSviewer.exe 1.6.21 上验证）

这些是手册没写、但实测确认的关键事实，写脚本前必须知道：

1. 带 -save_* 参数 → VOSviewer 完成启动动作后自动退出（退出码 0），输出文件落盘。实测耗时：打开地图+截图约 24–29 s；corpus 生成 term 地图 + 保存约 16 s。
2. 不带任何 -save_* 参数 → GUI 一直开着不退出，脚本会挂住。此时需要超时后杀进程。
3. 必须用绝对路径，输入输出都是。实测两种失败模式：
   - 相对路径输入（即使工作目录正确）：地图加载失败，GUI 保持打开、无任何输出；
   - 相对路径输出：VOSviewer 以退出码 0"正常"退出，但输出文件根本没写——这是最危险的静默失败，务必靠"预期文件是否存在"来校验，不能只看退出码。
4. VOSviewer 不向 stdout/stderr 输出日志，成败只能靠"退出码 + 预期输出文件是否存在"判断。
5. 截图是 VOSviewer 当前渲染的画面（白底，左下角带 VOSviewer 水印），分辨率取决于窗口大小；PNG 实测约 1080×590、0.5–2.8 MB。
6. -run_layout / -run_clustering 配合 -save_map 可以对已有坐标的地图强制重算布局和聚类，产出的 map 文件含新的 x/y/cluster 列。

快速开始

REM 1) 打开地图并导出 PNG 截图（结束后自动退出）
"C:\...\VOSviewer.exe" -map "C:\data\journal_map.txt" -network "C:\data\journal_network_sparse.txt" -save_screenshot_png "C:\out\map.png"

REM 2) 密度可视化 + 放大（手册示例）
"C:\...\VOSviewer.exe" -map "C:\data\map.txt" -density_visualization -zoom_level 2.5

REM 3) corpus 文本 → term 共现地图，保存结果
"C:\...\VOSviewer.exe" -corpus "C:\data\corpus.txt" -counting_method 2 -min_n_occurrences 3 -n_terms 50 -run_layout -run_clustering -save_map "C:\out\term_map.txt"

REM 4) 重算已有地图的布局与聚类
"C:\...\VOSviewer.exe" -map "C:\data\m.txt" -network "C:\data\n.txt" -run_layout -run_clustering -resolution 1.5 -min_cluster_size 5 -save_map "C:\out\m_new.txt"

REM 5) JAR 方式（需自备 Java，可调内存）
java -Xmx4000m -jar "C:\...\VOSviewer.jar" -map "C:\data\map.txt" -save_screenshot_png "C:\out\map.png"

批量/脚本场景建议用本技能自带的封装脚本（自动等待、校验输出、超时杀进程）：

python scripts/run_vosviewer.py \
  --exe "C:\Documents\VOSviewer_1.6.21_exe\VOSviewer.exe" \
  --expect "C:\out\map.png" --timeout 300 \
  -- -map "C:\data\journal_map.txt" -network "C:\data\journal_network_sparse.txt" \
     -save_screenshot_png "C:\out\map.png" -density_visualization

脚本输出 JSON：{"ok":..., "stage":"exited|timeout_killed|...", "exit_code":..., "expected":{文件:字节}, "missing":[...]}。退出码：0 成功、2 超时、3 预期文件缺失、4 启动失败、1 其他。

输出目录约定（务必遵守）

每次对话生成的所有 VOSviewer 相关产物——网络文件（map/network/GML/nodes/edges）、
导出截图（PNG/PDF/SVG）——统一保存到 <当前工作目录>\vosviewer_out\<数据源>\，
目录不存在就先创建。 不要散落在工作目录根、临时目录或桌面。

按数据源分二级子文件夹（同一工作区常有多数据源对比，产物必须隔离）：

<当前工作目录>\vosviewer_out\
├── scopus\      # 基于 Scopus 数据的 map/network/截图
├── openalex\    # 基于 OpenAlex 数据的 map/network/截图
└── wos\         # 基于 WoS 数据的 map/network/截图

• 无法确定数据源（如用户自备地图文件）时放 vosviewer_out\ 根下即可
• 本文档示例中的 C:\out\... 一律替换为 <当前工作目录>\vosviewer_out\<数据源>\...
• vosviewer_pipeline.py 的默认 --out-dir 就是 <cwd>\vosviewer_out\<数据源>\，无需手填
• 出图时脚本自动用 ASCII 临时目录中转（规避中文/空格路径的静默失败），跑完把产物拷回规范目录并校验
• 输入数据文件（-map/-network 等）通常来自对应数据源的导出目录（如 <工作目录>\scopus\）
• 这样约定的原因：vosviewer-online-local 技能的网页版 dev server 默认挂载
  <工作目录>\vosviewer_out\，产物放这里即可被网页版直接通过 URL 加载，无需挪文件

工作流决策

按输入数据类型选择入口参数（全部细节见 references/command-line-parameters.md，文件格式见 references/file-formats.md）：

输入格式实测结论（务必照此选格式）

手上是 VOSviewer JSON 网络文件怎么办？

桌面版的 -json 走不通（见上表），两条可用路线：

路线 1：转成 map/network 再出图（推荐，纯文本、还能继续 -run_layout）

python "~\.workbuddy\skills\vosviewer-online-local\scripts\json_to_map_network.py" \
  --json "<工作目录>\vosviewer_out\xxx_network.json" --outdir "<工作目录>\vosviewer_out"
# 产出 xxx_network_map.txt + xxx_network_network.txt，然后照常：
# VOSviewer.exe -map "...\xxx_network_map.txt" -network "...\xxx_network_network.txt" -save_screenshot_png "...\x.png"

实测：156 节点 / 799 连线的 JSON 转出后 exe 正常出图（截图 2.0MB，与直接读 map/network 一致）。

路线 2：只在浏览器里看 → 用 vosviewer-online-local 技能，?json= 直接可用，无需转换。

⚠️ 两种"JSON"别搞混：-json 参数指的是 VOSviewer 网络 JSON（上表那行）；
而 pipeline 的 --input xxx.json 指的是 OpenAlex works 原始响应，作为题录数据输入，两者完全不同，后者不受此问题影响。

> 生成本技能可直接消费的数据文件时，优先输出 map + network 文本文件；需要取数或转换，一律走
> scripts/vosviewer_pipeline.py（一站式：取数/读文件 → 建网 → 出图 → 存图），不要再现场写临时脚本。

一站式流水线（scripts/vosviewer_pipeline.py，主线唯一入口）

任何"从文献数据做共现/引用网络并出图"的需求，第一步就是跑它。 四个环节任意组合，
取数（OpenAlex 在线 / Scopus 在线）与读文件（Scopus 43列CSV / OpenAlex works JSON / 任意CSV-TSV）二选一：

# A. 取数 + 建网 + 出图（OpenAlex，被引降序前 1000 → 作者合作网络）
python scripts/vosviewer_pipeline.py --query "sustainable development|sustainability" \
    --source openalex --rows 1000 --sort cited --kind author \
    --exe "C:\...\VOSviewer.exe"

# B. Scopus 在线取数（复用 scopus-api-toolkit 的客户端：凭据/配额/重试全接管）
python scripts/vosviewer_pipeline.py --query 'TITLE-ABS-KEY(sustainability)' \
    --source scopus --rows 1000 --sort cited --kind keyword

# C. 只读已有文件建网（不出图）
python scripts/vosviewer_pipeline.py --input "<工作目录>\scopus\top1000.csv" --kind institution --min-weight 5
python scripts/vosviewer_pipeline.py --input "<工作目录>\openalex\top1000.json" --kind author --corpus

# D. 文献引用网络（节点=论文、边=数据集内互引，产出 GML）
python scripts/vosviewer_pipeline.py --query "bibliometric mapping" --source openalex \
    --rows 1000 --kind citations --exe "C:\...\VOSviewer.exe"

# E. 任意来源表格（WoS/Dimensions 导出、自整理两列表）：--columns 指定实体列
python scripts/vosviewer_pipeline.py --input any.csv --kind keyword --columns "Keywords" --sep ";"

关键参数：

行为要点：

• 实体身份优先用规范 ID（Scopus Author(s) ID / OpenAlex author·institution ID），同名作者不混淆，ID 缺失回退姓名；
  关键词自动大小写/空格归一；Scopus 输入会提示 Index Keywords 覆盖情况（--no-refs 导出时该列为空）
• 产物默认落 <cwd>\vosviewer_out\<数据源>\（分文件夹规范）；原始题录落 <cwd>\<数据源>\（--no-save-raw 可关）
• 运行 VOSviewer 时自动用 ASCII 临时目录中转：中文/空格输出路径不再静默失败，跑完自动拷回并校验文件是否存在
• 网络为空（节点<2 或无边）时不写空文件，返回码 4 并提示调阈值/加数据量
• map/network 格式见 references/file-formats.md 铁律（BOM+CRLF、network 无表头）
• 实测：Scopus/OpenAlex 各 1000 条 × 三种网络 + 引用网络 + 通用表格 + 中文路径出图，全部一次通过

组合约束（写命令前自查）

• -map 不能与 -pajek_network 同用；-map 不能与 -corpus 同用。
• -pajek_partition 只能与 -pajek_network 同用；-counting_method 只能与 -corpus 同用。
• -scores 只与 -corpus 配套；-thesaurus 在语料/文献建图时用于合并或忽略词条。
• network 文件中每个 item ID 必须在 map 文件中有对应 ID。
• corpus 文本必须是英文；map 文件中 x/y 成对，weight 与 normalized weight 互斥，score 与 red/green/blue 互斥。
• 布局参数取值：attraction -9~+10，repulsion -10~+9 且必须小于 attraction；推荐起点 2/1。

排错清单

获取数据（VOSviewer 自己不能联网取数）

68 个命令行参数中没有任何联网参数，-corpus 等只读本地文件；API 下载仅存在于 GUI 的 Create Map wizard。命令行路线需外部工具取数落盘，按优先级：

路线 A：openalex-wos-export 技能（首选，本机已装）

位置：~\.workbuddy\skills\openalex-wos-export\（下称 <owx>）

• <owx>\scripts\fetch_openalex_raw.py — 批量抓取含 referenced_works 的原始 JSON（cursor 分页、429 退避、key 从 --api-key > 环境变量 OPENALEX_API_KEY > .env 三层自动获取），单文件合并输出，是 NetworkX 建图的最佳输入
• <owx>\scripts\export_openalex_wos.py — 导出 WoS 格式 savedrecs.txt。⚠️ 只能被 GUI 的 Create Map wizard 消化，不能直接喂 CLI（CLI 只吃纯文本 -corpus）；喂 EndNote/CiteSpace 用 --field-style repeat
• 没有 API key 时可按 <owx>\references\api-authentication.md 一键代办（POST https://api.openalex.org/api-keys，必须用用户真实邮箱，用户点激活邮件后生效）
• OpenAlex 现行硬规则（per-page ≤ 100、无 key page 分页 ≤ 1 万条、filter 单值 OR ≤ 100、免费 key 30 rps / 10k credits 每天）以 <owx>\SKILL.md 与 <owx>\references\llm-quick-reference.md 为准，不必重查

python "~\skills\openalex-wos-export\scripts\fetch_openalex_raw.py" \
  --query "your topic" --years 2016-2026 --total 2000 --outdir "C:\out"
# 产出 C:\out\openalex_raw.json → 走路线 B/C 建图

路线 B：本技能脚本一条命令（推荐日常用）

vosviewer_pipeline.py 自带 OpenAlex 客户端（per-page ≤ 100、cursor 分页、429 退避、key 自动读取），
取数→建网→出图一次完成：

# 关键词共现地图
python scripts/vosviewer_pipeline.py --query "bibliometric mapping" --source openalex \
  --rows 200 --kind keyword --exe "C:\...\VOSviewer.exe"

# 作者合作 / 机构合作
python scripts/vosviewer_pipeline.py --query "bibliometric mapping" --source openalex \
  --rows 500 --kind author --exe "C:\...\VOSviewer.exe"
python scripts/vosviewer_pipeline.py --query "bibliometric mapping" --source openalex \
  --rows 500 --kind institution --exe "C:\...\VOSviewer.exe"

# 引用网络：取 1000 篇 → 极简 GML（带论文标题标签）→ 直接出图
# ⚠️ rows 至少 1000，单页 100 篇内部引用几乎为 0
python scripts/vosviewer_pipeline.py --query "bibliometric mapping" --source openalex \
  --rows 1000 --kind citations --top 120 --exe "C:\...\VOSviewer.exe"

author/institution/keyword 产出 <prefix>_map.txt + <prefix>_network.txt（加 --corpus 再带 corpus/scores）；
citations 产出 <prefix>.gml。Scopus 同样支持：把 --source 换成 scopus、--query 换成 Scopus 检索式即可（复用 scopus-api-toolkit 客户端）。

路线 C：NetworkX 手动转换（任意 API 数据）

用 NetworkX 建图后手写极简 GML（只含 id/label/weight）喂给 -gml，完整模板见 references/data-sourcing.md。两个实测坑，别踩：

• nx.write_gml() 会把节点 label 覆盖成节点 ID（图上全是数字）
• nx.write_pajek() 的输出 VOSviewer 不认（静默失败），需要 Pajek 就手写 *Vertices N + 1 "label"

其他与禁区

• OpenAlex API 直连（免费、含 referenced_works）适合轻量场景；Europe PMC / Crossref / PubMed E-utilities REST 可自建 map/network 或 corpus
• WoS / Scopus / Dimensions / Lens 无免费 CLI（WoS、Scopus API 需订阅），命令行路线基本只能靠 OpenAlex
• ⚠️ openalexnet 已淘汰（多年未维护），其"一条命令出 GML"的能力由路线 B 的 --network citations 接管，不要再引入

三条完整链路、NetworkX 转换模板、以及 VOSviewer 原生 JSON schema 见 references/data-sourcing.md。

Resources

• scripts/run_vosviewer.py — 运行 VOSviewer 并校验输出（等待退出、超时杀进程、JSON 汇报）。
• scripts/vosviewer_pipeline.py — 主线唯一入口。多数据源取数（OpenAlex 内置客户端 / Scopus 复用 scopus-api-toolkit）+ 读文件（Scopus 43列CSV / OpenAlex works JSON / 任意CSV-TSV）+ 建网（author/institution/keyword/citations）+ 运行 VOSviewer + 保存 map/network/截图/corpus/scores。输出格式字节级对齐随包示例；内置中文路径自动中转、静默失败检测、空网络保护。用法见上方"一站式流水线"。
• scripts/run_vosviewer.py — 仅运行与校验（等待退出、超时杀进程、JSON 汇报），适合已有 map/network 只要出图的场景。
• 跨技能依赖：~\.workbuddy\skills\vosviewer-online-local\（SKILL.md、scripts/vosviewer-open.py、scripts/map_network_to_json.py、scripts/json_to_map_network.py）— VOSviewer Online 本地版使用：本机部署网页版 VOSviewer（localhost:8600），在浏览器中交互式浏览网络。当用户要"网页打开/浏览器查看"可视化结果时用它；其 dev server 默认挂载本技能的输出目录 <工作目录>\vosviewer_out\，产物可直接通过 URL 参数（?map=...&network=... / ?json=...）或 python scripts/vosviewer-open.py <map> <network> 一键加载，无需挪文件。JSON 互转：map_network_to_json.py（map/network → 单文件 JSON，供网页版）、json_to_map_network.py（JSON → map/network，供桌面版绕过失效的 -json）。
• 跨技能依赖：~\.workbuddy\skills\openalex-wos-export\（SKILL.md、scripts/fetch_openalex_raw.py、scripts/export_openalex_wos.py、references/api-authentication.md、references/llm-quick-reference.md）— OpenAlex 认证/额度/分页的权威规则来源，取数首选。
• NetworkX（pip install networkx，本机 venv 已装）— 仅作建图/图算法中间层，导出一律手写极简 GML，不用其 write_gml/write_pajek。

随包示例数据

安装目录 data/ 下自带可用的示例文件（journal_map.txt、journal_network_sparse.txt、corpus.txt、scores.txt、thesaurus_*.txt、*_colors.txt、Pajek/GML 示例等），验证命令行流程时可直接使用，清单见 references/file-formats.md 末尾。

参考文件

• references/command-line-parameters.md — 全部 68 个参数的语义、取值范围、默认值、组合约束、已废弃参数、JVM 内存/栈参数。
• references/file-formats.md — map/network/corpus/scores/thesaurus/配色文件的格式规则与示例。
• references/data-sourcing.md — 命令行取数工具链（含 openalex-wos-export 对接）、实测可用输入格式、NetworkX 建图模板与实测坑、三条推荐数据链路、原生 JSON schema。