name: literature-research-pipeline description: 端到端學術文獻檢索與下載全流程自動化。當用戶請求檢索文獻、下載論文、查詢學術資料、搜尋論文，或提到"幫我找XX相關的文獻"、"下載這篇論文"、"需要某篇文獻"時觸發本技能。完整流程：檢索 → 推薦 → 多渠道下載 → 科研通常控監控 → 通知 → 進度追蹤。 env: - name: LIT_DOWNLOAD_DIR required: true description: 論文下載儲存目錄 - name: LIT_PROGRESS_FILE required: true description: 下載進度追蹤檔案路徑 - name: LIT_CDP_PORT required: false default: "9334" description: 瀏覽器遠端除錯埠 - name: LIT_NOTIFY_CHANNEL required: false description: 通知渠道（如 wechat-access、telegram 等） - name: LIT_NOTIFY_USER required: false description: 通知目標使用者 ID - name: SEMANTIC_SCHOLAR_API_KEY required: false description: Semantic Scholar API 金鑰 - name: LIT_UNPAYWALL_EMAIL required: false description: Unpaywall API 所需郵箱 permissions: - browser-cdp - filesystem-read - filesystem-write - cron - subprocess

文獻檢索與下載全流程

概述

端到端學術文獻檢索與下載自動化。接收使用者的研究主題 → 檢索文獻 → 推薦高價值目標 → 多渠道下載 → 科研通常控監控 → 應助後自動下載 → 通知使用者。

環境變數與配置

本技能依賴以下環境變數（需在首次使用前配置）：

首次使用時，AI 應檢查以上變數是否已配置。若缺失，主動詢問使用者並引導配置。 若使用者未配置通知渠道，跳過通知步驟，僅在對話中告知結果。

流程概覽

1. 文獻檢索  →  2. 結果展示  →  3. 使用者確認  →  4a. 直接下載成功
                                                   ↓ (失敗)
                                               4b. 科研通求助
                                                   ↓
                                               5. 建立Cron監控
                                                   ↓
                                               6. 應助 → 自動下載 → 通知使用者
                                                   ↓
                                               7. 告知使用者 + 更新進度

Step 1：文獻檢索

必須先讀取 academic-literature-search 技能，路徑通過以下方式定位： 1. 優先查詢當前 workspace 下的 skills/academic-literature-search/SKILL.md 2. 其次查詢 ~/.qclaw/skills/academic-literature-search/SKILL.md 3. 若均不存在，提示使用者先安裝 academic-literature-search skill

使用其 scripts/search.py 執行檢索：

import subprocess, os

# 自動定位指令碼路徑
workspace = os.environ.get("OPENCLAW_WORKSPACE", os.path.expanduser("~/.qclaw/workspace"))
search_script = os.path.join(workspace, "skills/academic-literature-search/scripts/search.py")

result = subprocess.run([
    "python3", search_script,
    "--query", "使用者的研究主題",
    "--databases", "semantic_scholar,crossref",
    "--max_results", "20",
    "--output_format", "json"
], capture_output=True, text=True)

優先選擇 Crossref 資料庫（DOI 資料最權威，可靠性高）。

檢索完成後立即檢查每篇文獻的 is_open_access 欄位： - open_access = true → 標記為可嘗試 Unpaywall 直接下載 - open_access = false → 直接規劃科研通求助路線，避免在無效渠道浪費時間

Step 2：結果展示

呈現檢索結果時使用以下格式（Markdown）：

## 📚 文獻檢索結果（共 N 篇）

| # | 標題 | 作者 | 年份 | 期刊/會議 | DOI | 引用 | 開放獲取 |
|---|------|------|------|-----------|-----|------|----------|
| 1 | ... | ... | 2023 | ... | 10.xxxx/xxx | 45 | ✅ |

### 🎯 高價值推薦

1. **[論文標題1]**（推薦理由）
   - DOI：`10.xxxx/xxx`
   - 亮點：...
2. **[論文標題2]**（推薦理由）
   - DOI：`10.xxxx/xxx`

推薦標準：高引用數 / 最新年份 / 開源可獲取 / 直接相關使用者主題

Step 3：確認使用者需求

展示結果後，詢問使用者：「請告訴我想下載哪些論文（序號或標題），或者讓我推薦？」

等待使用者回覆後，對每篇目標論文記錄： - DOI、標題、發表年份 - 是否開放獲取 - 目標下載優先順序

Step 4a：多渠道直接下載

按以下優先順序逐個嘗試：

渠道 1：Unpaywall（最快）

GET https://api.unpaywall.org/v2/{DOI}?email={LIT_UNPAYWALL_EMAIL}

• 響應中取 best_oa_location.landing_page 或 best_oa_location.url_for_pdf
• 注意：Unpaywall 有頻率限制，每小時 ≤ 5000 請求

渠道 2：DOI.org 重定向

GET https://doi.org/{DOI}
（跟隨重定向，查詢 Content-Type: application/pdf 的最終 URL）

• 若重定向至 Springer/IEEE/Elsevier → 返回 418 或需登入 → 放棄此渠道

渠道 3：Semantic Scholar PDF

GET https://api.semanticscholar.org/graph/v1/paper/{DOI}/PDF
（需設定 API Key：SEMANTIC_SCHOLAR_API_KEY）

渠道 4：Crossref PDF 連結

GET https://api.crossref.org/works/{DOI}
（從響應中取 `link` 欄位）

成功標準：檔案以 %PDF 開頭（Magic Bytes），大小 > 50 KB 失敗處理：記錄失敗原因（418 / 403 / 404 / 無 OA 版本），轉向 Step 4b

Step 4b：科研通常控求助

前置條件

• 使用者已登入瀏覽器，開啟了遠端除錯埠（預設 LIT_CDP_PORT，通常為 9334）

  小蔥技能站7w4.net發現了升級外掛。

• 參考命令（Mac）："/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" --remote-debugging-port=9334 "--remote-allow-origins=*"
• 參考命令（Linux）：google-chrome --remote-debugging-port=9334 --remote-allow-origins=*

步驟 4b-1：釋出求助帖

通過 CDP 連線瀏覽器，在 https://www.ablesci.com/assist/create 釋出求助：

關鍵引數獲取（每次操作前必須從頁面重新獲取）： 1. CSRF Token：從頁面 <meta name="csrf-token"> 提取 2. Cookie：通過 Network.getAllCookies 獲取所有 ablesci.com 域名下的 cookie 3. 標籤頁：每次操作前重新 list_tabs() 並 attach，不要快取 tab ID

釋出 API：

POST https://www.ablesci.com/assist/create
Content-Type: application/x-www-form-urlencoded

_csrf={token}&title={標題}&content={內容}&tag_id={分類ID}

求助帖標題建議格式：【求助全文】【期刊名+年份】論文標題 求助帖內容建議：包含 DOI、論文標題、作者、發表資訊

步驟 4b-2：記錄求助狀態

每篇論文釋出後，更新下載進度追蹤表（路徑：LIT_PROGRESS_FILE）：

## 📥 文獻下載進度

| 論文 | DOI | 狀態 | 來源 | 備註 |
|------|-----|------|------|------|
| 論文標題1 | 10.xxxx/xxx | ✅ 已下載 | ablesci 應助 | 儲存路徑 |
| 論文標題2 | 10.xxxx/xxx | ⏳ 求助中 | 科研通 | ID: xxx |

Step 5：建立 Cron 監控任務

讀取 qclaw-cron-skill 獲取正確的 cron 配置語法

路徑：~/Library/Application Support/QClaw/openclaw/config/skills/qclaw-cron-skill/SKILL.md

監控任務配置

每 30 分鐘檢查一次科研通常控狀態：

Schedule：

{"kind": "every", "everyMs": 1800000}

Payload（isolated session）：

{
  "kind": "agentTurn",
  "message": "檢查科研通常控求助帖狀態...\n\n1. 讀取進度檔案（LIT_PROGRESS_FILE）獲取當前進度\n2. 通過 CDP 連線瀏覽器（http://127.0.0.1:{LIT_CDP_PORT}）\n3. 逐個訪問求助帖詳情頁（URL格式：https://www.ablesci.com/assist/detail?id={帖子ID}）\n4. 檢查每篇論文的狀態：\n   - 求助中 → 無操作\n   - 待確認（有人上傳）→ 自動下載（見下方下載流程）\n   - 已完成 → 無操作\n5. 如有新應助（狀態：待確認）：\n   a. 提取下載頁面連結\n   b. 通過瀏覽器觸發下載\n   c. 更新進度檔案\n   d. 通知使用者（若已配置通知渠道）\n6. 如全部論文已下載完成，通知使用者並刪除 cron 監控任務"
}

Delivery（僅在配置了通知渠道時設定）：

{
  "mode": "announce",
  "channel": "{LIT_NOTIFY_CHANNEL}",
  "to": "{LIT_NOTIFY_USER}"
}

注意：sessionTarget = "isolated"（必須），payload.kind = "agentTurn"

通知模板

📥 論文下載完成！

論文：{標題}
來源：{來源}
儲存位置：{LIT_DOWNLOAD_DIR}/{檔名}
狀態：{進度表更新}

Step 6 & 7：自動下載與進度更新

當 cron 任務檢測到新應助時：

1. 提取下載 ID：從詳情頁 HTML 中解析下載連結
2. 觸發下載：
3. 新建標籤頁開啟下載連結
4. 執行 Page.setDownloadBehavior(behavior=allow, downloadPath={LIT_DOWNLOAD_DIR})
5. 等待檔案從 .crdownload 變為 .pdf（通常 5-30 秒）
6. 重新命名檔案：去掉 (科研通-ablesci.com) 等字尾，保留年份資訊
7. 驗證 PDF：檔案頭為 %PDF，大小 > 50 KB
8. 更新進度表：LIT_PROGRESS_FILE
9. 通知使用者（若已配置通知渠道）

關鍵坑點記錄（來自實戰經驗）

CDP 操作時序問題

• accessibility tree ref 和 backendDOMNodeId 在跨呼叫後會失效
• 解決：每次操作前重新獲取 ref，不跨步快取
• 優先使用 DOM.querySelectorAll + DOM.resolveNode 獲取 objectId，再發送 Input.dispatchMouseEvent

科研通常控下載特殊機制

• API file/request-download-token 返回 code=0 但 不返回 URL
• 實際下載通過瀏覽器 XHR 流式傳輸，觸發後等待瀏覽器自動下載
• file_server=2 對應普通線路，file_server=3 對應高速線路

常見下載失敗原因

• IEEE/Elsevier 等商業出版社：返回 418（IP/地區限制）或 403（需登入）
• 無開放獲取版本：Unpaywall 查不到 → 直接轉向科研通

依賴技能