AOS/skills/aminer-deep-search/SKILL.zh.md

name, version, author, contact, description, metadata

name	version	author	contact	description	metadata
aminer-deep-search	2.0.0	AMiner	report@aminer.cn	当用户需要为综述或文献回顾做深度、多轮的学术论文收集时激活本 skill。 由宿主模型（正在运行本 skill 的模型）亲自驱动循环：扩展查询、判断相关性、做引用滚雪球、决定何时终止。 附带脚本只是纯工具命令，调用 AMiner 开放平台的正规接口并只输出 JSON tool-result，无需配置任何额外 LLM。 适用于大范围主题探索、综述参考文献构建、收集数百篇带 AMiner ID 与标题的候选论文。 不适用于单篇论文查询或轻量推荐，请分别使用 aminer-free-academic 或 aminer-daily-paper。	openclaw requires primaryEnv bins env python3 AMINER_API_KEY AMINER_API_KEY

AMiner 深度收集

宿主模型直驱的综述文献收集。你（正在读这份文档的模型）就是控制器：运行工具脚本、阅读 JSON 输出、自己判断相关性、迭代直到达成收集目标。

适用边界

• 适用：综述级文献收集（数百篇）、关键词扩展、后向引用滚雪球。
• 不适用：单篇查询或问答（走 aminer-free-academic）、个性化推荐（走 aminer-daily-paper）。

Pre-flight

1. 检查 key（不打印值）：

[ -z "${AMINER_API_KEY:-}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"

缺失时停止并让用户设置 AMINER_API_KEY（控制台：https://open.aminer.cn/open/board?tab=control）。绝不打印 key。

2. 确认 topic 和 target-size（默认 400）。若轮次计划预估费用 ≥¥5，先告知用户并获得确认再开始。

工具

两个脚本都在本 skill 目录的 scripts/ 下。stdout 只输出一个 JSON 文档（即 tool-result）；诊断信息与 [cost] 费用行走 stderr。脚本不做任何相关性打分——那是你的工作。

scripts/aminer_api.py — AMiner 接口调用

子命令	端点	价格
search --query Q [--size 20] [--year YYYY] [--order n_citation|year] [--max-pages 3]	GET /api/paper/search/pro + 免费 paper/info 补全	¥0.01/页
qa-search [--query "自然语言问题"] [--topic-high '[["词A","词B"],["词C"]]'] [--size 20] [--year-from Y] [--year-to Y] [--citation-sort]	POST /api/paper/qa/search（固定 use_topic=true：use_topic=false 时后端忽略 query）+ 免费补全	¥0.05/次
info --ids id1 id2 ...	POST /api/paper/info（≤100 个 id 分批）	免费
references --ids id1 id2 ... [--per-seed 20]	每个 seed 调 GET /api/paper/relation + 免费补全	¥0.10/篇 seed

输出形状：search/qa-search/info 输出 [{id, title, year?, venue?, abstract_slice?}]；references 额外带 source_paper_ids（哪些 seed 引用了该论文），且结果中排除 seed 本身。

scripts/paper_set.py — 跨轮状态文件（无网络）

状态文件默认是工作目录下的 outputs/paper_set.json。

# 把保留的结果管道进去（可直接接在搜索后面），按 id 去重
python3 scripts/aminer_api.py search --query "..." | python3 scripts/paper_set.py add
# → {"added": N, "duplicates": M, "total": T}

python3 scripts/paper_set.py stats     # 总量、expanded_seeds、按年分布
python3 scripts/paper_set.py mark-expanded --ids id1 id2   # 记录已滚雪球的 seed
python3 scripts/paper_set.py export -o outputs/final_papers.json

add 也接受 --ids id1 id2 ... 直接加裸 id。带 source_paper_ids 的条目（来自 references）会自动把对应 seed 记为已扩展。

如需先筛选再入库，先阅读搜索输出，再只把保留的条目管道进去：

printf '%s' '[{"id":"...","title":"..."}]' | python3 scripts/paper_set.py add

每轮协议（核心）

第 0 轮 — 规划

• 从 topic 派生 4–8 个种子查询：同义词、子领域、方法名、数据集/基准、常用英文缩写。
• 预估轮数与费用（搜索约 ¥0.01–0.05/次，references 约 ¥0.10/seed）。预估 ≥¥5 时先向用户确认。

每一轮（默认最多 12 轮），固定五步

1. 搜索：对待查队列执行 1–4 个 search / qa-search。优先用 search（更便宜）；查询是自然语言问题时用 qa-search。
2. 筛选入库：阅读 stdout 结果，自己判断与主题的相关性，只把保留的条目管道进 paper_set.py add。绝不入库你认为跑题的论文。
3. 查看进度：跑 stats 查看总量与本轮增量。
4. 滚雪球：从本轮新增的相关论文里挑 ≤5 个强种子（高相关、--order n_citation 排前、不在 expanded_seeds 中），跑 references --ids ...。对输出再做相关性筛选后入库。没有可入库产出的 seed 用 mark-expanded 记录。
5. 决策下一轮：
   • 某个搜索结果 <5 条或质量差 → 换一个改写后的查询（每个方向最多试 2 个变体，之后转滚雪球）；
   • references 持续产出大量相关论文 → 继续从新 seed 滚雪球；
   • 达到 target-size、结果枯竭、或连续 2 轮新增 <5 篇 → 终止。

收尾

跑 export，然后报告：最终篇数、总费用（累加 stderr 的 [cost] 行）、输出文件路径。

规则

1. 绝不编造论文 ID 或标题；只引用工具实际返回的数据。
2. 免费优先：元数据一律来自免费的 paper/info（脚本已内置）；绝不为批量元数据调付费的 paper/detail。
3. 不要把原始工具输出塞进最终回答；只报告数量与导出文件路径。
4. 绝不打印或记录 AMINER_API_KEY。
5. 如果 AMiner 返回的论文少于目标，如实报告实际数量，不要编造。