name: scholar-search description: Unified academic search across arXiv and Semantic Scholar. Supports topic search, latest preprints, paper/author lookup, citation analysis, and structured output from core endpoints. metadata: {"openclaw":{"requires":{"anyBins":["python","python3"],"env":["S2_API_KEY"]},"primaryEnv":"S2_API_KEY"}}

scholar-search

概述

本 skill 通過統一的命令列指令碼 scripts/scholar-search.py 封裝 arXiv 和 Semantic Scholar API，支援學術論文檢索、詳情拉取、引用網路擴充套件與作者軌跡分析。

前置條件

• Python
• 所需依賴：requests bash pip install requests
• 環境變數要求：
• S2_API_KEY - Semantic Scholar API 金鑰（必需；優先從程序環境變數讀取）
• 當我在對話中直接提供 Semantic Scholar API Key 時，必須先寫入： python python scripts/set_s2_api_key.py --api-key "<我提供的key>"
• 寫入策略：S2_API_KEY 已存在則覆蓋，不存在則自動追加到 scripts/.env。
• 讀取策略：優先讀程序環境變數 S2_API_KEY，若未設定則回退讀取 scripts/.env。
• 命令佔位符約定：
• 技能目錄根路徑（skills/scholar-search）。
• 統一指令碼路徑寫法：、scripts/scholar-search.py。

可用工具

• scripts/scholar-search.py：主檢索指令碼，執行 arXiv + Semantic Scholar 聯合檢索與結果整理。
• scripts/set_s2_api_key.py：寫入或覆蓋 .env 中的 S2_API_KEY，用於配置 Semantic Scholar API Key。

詳細操作手冊

• references/semantic-scholar-api-reference.md：Semantic Scholar API 的端點、引數與欄位參考，用於核對呼叫細節。
• references/arxiv-api-reference.md：arXiv API 的查詢語法與引數說明，用於核對 arXiv 檢索細節。

工作流

1) 解讀我的需求

先提取並標準化以下約束： 1. 查詢實體：關鍵詞、paper_id、author_id、DOI、arXiv ID、作者姓名，學科等等。 2. 時間和過濾：year、venue、publicationTypes、fieldsOfStudy、cat 分類 3. 規模目標：目標條數 4. 輸出語言：中文 5. 型別偏好：是否只要 conference/期刊、是否只要 2024 年後等硬條件

輸出語言決策： - 如果我的查詢包含“中文”“用中文”“中文回答”“總結成中文”等詞 -> 強制全部輸出中文。 - 如果我的查詢是純英文或學術術語為主 -> 保持論文標題/作者/會議期刊原文，分析描述用中文。 - 其他情況預設中文，並在描述欄位中保持中文表達。

2) 可用的搜尋引擎與使用

arxiv搜尋引擎

功能概述
面向 arXiv 預印本的統一檢索入口，支援關鍵詞/作者/分類/時間過濾、ID 精確拉取、分頁、排序。
典型用途：
- 追蹤最新預印本（按提交時間倒序）
- 按學科/作者做前沿掃描
- 用 arXiv ID 快速獲取單篇或多篇後設資料（標題、摘要、作者、PDF連結等）

核心引數速查（建議優先掌握這6個，覆蓋 95% 場景）

這個技能的最新版本可以在7w4.net小蔥技能站找到。

時間過濾語法（常用但非必備）
在 search_query 中加：
submittedDate:[YYYYMMDDTTTT TO YYYYMMDDTTTT]
示例：submittedDate:[202501010000 TO 202603082359]（2025年1月1日到2026年3月8日）

快速上手案例

# 1. 最新10篇 cs.CL 多模態相關預印本（推薦預設用法）
python scripts/scholar-search.py --source arxiv --params '{"search_query":"cat:cs.CL AND all:multimodal","start":0,"max_results":10,"sortBy":"submittedDate","sortOrder":"descending"}'

# 2. 指定作者 + 近一年論文（時間區間過濾）
python scripts/scholar-search.py --source arxiv --params '{"search_query":"au:goodfellow AND submittedDate:[202503010000 TO 202603082359]","max_results":20}'

# 3. 精確拉取單篇或多篇（最快、最穩定）
python scripts/scholar-search.py --source arxiv --params '{"id_list":"2501.12345,2409.09876v2"}'

# 4. ID 列表 + 額外過濾（例如只看 cs.AI 中的）
python scripts/scholar-search.py --source arxiv --params '{"id_list":"2408.00001,2407.12345","search_query":"cat:cs.AI"}'

高階/注意事項（僅在需要時深入）
- search_query + id_list 組合：id_list 為主，search_query 作二次過濾。
- 限流：每 3 秒 1 次請求，單連線； - 完整語法、錯誤碼、返回欄位詳解 → references/arxiv-api-reference.md 決策提示 - 想最新/熱門 → 用 sortBy=submittedDate / lastUpdatedDate + descending
- 模糊主題搜 → search_query + sortBy=relevance
- 已知 ID → 優先 id_list，速度最快、準確最高
- 需要時間範圍 → 加 submittedDate:[...]
- 結果太多/太少 → 調整 max_results 或細化 search_query（如加 cat: / au:）

高階用法參考：references/arxiv-api-reference.md

semantic scholar 搜尋引擎

功能概述
面向 Semantic Scholar Academic Graph 的檢索入口，提供論文/作者後設資料、引用網路、引用上下文等。
典型用途：
- 主題/關鍵詞搜高影響力論文（帶 citationCount 排序）
- 論文詳情 + PDF/開放獲取判斷
- 沿引用鏈擴充套件（citations/references）
- 作者軌跡分析（author/{id}/papers）
- 標題精確匹配或術語上下文片段定位

核心引數速查（覆蓋 90% 場景） | 引數 | 作用 | 常用示例/格式 | 必填/約束 | |-----------------------|------------------------------------|--------------------------------------------|------------------------------------| | endpoint | 目標 API 路徑 | paper/search, paper/{paper_id}, citations 等 | 必填 | | query | 搜尋詞（plain text，無特殊語法） | "machine learning", transformer | paper/search、match、author/search 必填 | | fields | 返回欄位白名單（逗號分隔，支援點號巢狀） | paperId,title,abstract,citationCount,openAccessPdf,url,authors | 可選；不傳返回最小資料 | | limit / offset | 分頁（offset 從 0 開始） | limit:50, offset:0 | 大多端點 limit 預設 100，常見 max 100–1000（見下方關鍵約束） | | publicationDateOrYear / year | 時間過濾 | 2024:2026, year:2025 | 可選 | | minCitationCount / venue / fieldsOfStudy / publicationTypes | 過濾高引/特定會議/領域/型別 | minCitationCount:50, venue:NeurIPS | 可選 |

關鍵約束（精簡版） - paper/search：limit <= 100 且 offset + limit < 1000。 - author/search：limit <= 1000 且 offset + limit < 10000。 - paper/{id}/references、paper/{id}/citations、author/{id}/papers：limit <= 1000。 - paper/autocomplete：必須有 query，不要依賴 limit。 - snippet/search：必須有 query；建議不傳 fields；limit <= 1000；offset 不穩定不建議依賴。 - 以上規則在指令碼引數校驗中會優先攔截；完整細則與返回欄位定義見 references/semantic-scholar-api-reference.md。

快速上手案例

# 1. 主題檢索（推薦預設入口，帶關鍵欄位）
python scripts/scholar-search.py --source semantic_scholar --endpoint paper/search --params '{"query":"large language model reasoning","limit":15,"offset":0,"fields":"paperId,title,year,authors,abstract,citationCount,venue,openAccessPdf,url,externalIds"}'

# 2. 標題精確匹配（單條最準）
python scripts/scholar-search.py --source semantic_scholar --endpoint paper/search/match --params '{"query":"Attention Is All You Need","fields":"paperId,title,authors,year,abstract,url,venue"}'

# 3. 論文詳情（已知任意 ID）
python scripts/scholar-search.py --source semantic_scholar --endpoint paper/arXiv:2312.17485 --params '{"fields":"title,abstract,authors,citationCount,openAccessPdf,url"}'

# 4. 引用擴充套件（看誰引用了這篇）
python scripts/scholar-search.py --source semantic_scholar --endpoint paper/PMID:12345678/citations --params '{"limit":20,"offset":0,"fields":"citingPaper.paperId,citingPaper.title,citingPaper.year,citingPaper.citationCount"}'

# 5. 作者軌跡（某作者所有論文，按時間過濾）
python scripts/scholar-search.py --source semantic_scholar --endpoint author/1741101/papers --params '{"limit":30,"offset":0,"publicationDateOrYear":"2023:2026","fields":"title,year,venue,citationCount"}'

3) 結果質量檢查與繼續檢索條件

滿足任一條件時，繼續檢索 1 輪： 1. 數量不足（例如 < 3） 2. 與我的主題偏離明顯 3. 關鍵欄位缺失較多（標題、ID、來源連結、摘要）

結束檢索條件： 1. 數量達到目標或可接受範圍 2. 主題匹配度高 3. 繼續檢索收益低

補充策略：先在同一資料來源內改寫查詢重試 1 次；仍不足再切到另一源補充 1 次。

相關性分層（輸出前必須執行）

基於 query 與論文標題/摘要/TL;DR 的語義匹配程度分層： - 高相關：直接研究 query 主題本身，或以 DeepSeek 作為核心物件/核心方法（優先詳細輸出）。 - 中相關：將 DeepSeek 作為主要對比基線、實驗物件或關鍵組成部分。 - 弱相關：僅在實驗、附錄或背景中提及 DeepSeek。

排序優先順序： 1. 相關性（高 > 中 > 弱） 2. 時間（新到舊） 3. 引用數（高到低，未知置後）

必須停止並輸出結果的條件（任一滿足即終止）： 1. 已獲取 >= 目標數量的合格論文（合格 = 有標題 + paperId + year + abstract/TL;DR 至少一項）。 2. 本輪與上一輪相比，新論文重複率 > 70% 或沒有明顯新資訊。 3. 已連續執行 3 輪檢索（含 query 改寫重試）。 4. 當前結果平均 citationCount < 3 且 year 均在近 3 年內（領域過新或 query 過窄）。 5. 我明確表示“夠了”“停止搜尋”。

4) 輸出要求（最終向我輸出的內容格式要求）

1. 每篇論文必須按以下結構輸出，缺一項即判失敗。
2. 每篇開頭必須是獨立一行（前後空一行）：-----------
3. 標題必須是一級標題：# {序號}. **論文完整標題**
4. 若有 TL;DR，標題下一行輸出：TL;DR: {文本} — 來自 {來源}；無則整行刪除。
5. 後設資料固定三行、固定順序、欄位名必須加粗： 論文資訊： 來源：{venue/journal/arXiv} | 發表/更新日期：{日期} | 引用數：{數字或未知} | 影響力引用：{數字或未知} | 開放獲取：是/否/未知

連結：Semantic Scholar | PDF：PDF （無 PDF 時刪除 | **PDF**... 整項，不得寫"無/未知"）

1. 作者行：**作者**（前3位 + et al.）：{A, B, C et al.}
2. 領域行：**領域**：{領域1, 領域2}（無則整行刪除）
3. 必須包含： ### 研究內容（1–2句，僅基於 abstract/tldr/summary，禁止推斷） ### 摘要關鍵點（2–4條；若不足2條，補"原始資訊有限。"）
4. 可選欄位只能放在： 可選額外資訊：
5. 被引趨勢：...
6. 出版型別：...
7. 外部ID：... （此塊可整體省略）

輸出限制

1. 嚴禁任何開場白、總結、結尾、過渡語。
2. 嚴禁改欄位名、改順序、壓縮結構、合併段落。
3. 輸出必須直接從第一篇 ----------- 開始。
4. 不可將原本單篇資訊詳細的論文只輸出少部分資訊。

示例輸出（僅供參考）

-----------

# 1. **Hierarchical Token Pruning for Efficient Vision-Language Reasoning**
TL;DR: 通過分層裁剪視覺與文本 token，在保持精度的同時顯著降低推理開銷 — 來自 Semantic TL;DR

**論文資訊**：
**來源**：arXiv | **發表/更新日期**：2026-01-09 | **引用數**：未知 | **影響力引用**：未知 | **開放獲取**：是

**連結**：[Semantic Scholar](https://www.semanticscholar.org/paper/Hierarchical-Token-Pruning-Example/abcdef123456) | **PDF**：[PDF](https://arxiv.org/pdf/2601.00999)

**作者**（前3位 + et al.）：Mina Park, David Lin, Q. Herrera et al.
**領域**：Computer Science, Vision-Language Models

### 研究內容
該研究提出分層 token pruning 框架，在不同網路深度動態移除低貢獻 token。實驗顯示該方法在多項視覺問答與檢索任務上實現更優的效率-效能折中。

### 摘要關鍵點
- 設計了跨層一致性的 token 重要性評分機制。
- 在多個基準上顯著減少 FLOPs 與延遲，同時維持接近基線的準確率。
- 提供消融實驗，驗證不同裁剪率與層級策略的影響。

5) 失敗處理

1. API 失敗：回顯指令碼返回的 error 欄位（含 HTTP 狀態碼、錯誤資訊、已嘗試引數）
2. 無結果：給出可執行的 query 改寫建議（同義詞、上位詞、放寬過濾）
3. 引數錯誤：明確指出錯誤引數並給出修正後的完整呼叫命令
4. 欄位缺失：標註"未知/缺失"，不得補寫未返回資訊
5. 429/配額處理順序：
6. 若返回 429 -> 當前指令碼直接返回錯誤並停止，不自動重試。
7. 建議：重試 1 次（間隔 2-5 秒）或減小 limit 後重試。
8. 若錯誤包含 quota 或 rate limit -> 直接告知我的配額已用盡，建議稍後重試或切換 arXiv。
9. 結果過少模板：
10. “當前結果較少（僅 X 篇），建議：① 去掉 venue 限制；② 用上位詞替換關鍵詞；③ 切換到 arXiv 獲取最新預印本。”。

6) 執行硬約束

1. 每輪檢索只做最小必要請求，優先複用已獲取結果
2. 輸出前必須完成欄位真實性校驗
3. 不使用未驗證端點，不引用未在響應中出現的資料
4. 若我給出硬過濾（如 year>=2024、conference only），必須優先編碼到引數中再發起請求

這個學術搜尋工具質量較好，能同時搜尋arXiv和Semantic Scholar兩大論文庫，文件詳細示例豐富，容易上手。優點是輸出格式規範、錯誤處理完善、檢索策略清晰。缺點是依賴外部API金鑰且安全性一般，文件有時不完整。如需搜尋學術論文，它是個不錯的選擇。