文献检索与下载全流程
概述
端到端学术文献检索与下载自动化。接收用户的研究主题 → 检索文献 → 推荐高价值目标 → 多渠道下载 → 科研通常控监控 → 应助后自动下载 → 通知用户。
环境变量与配置
本技能依赖以下环境变量（需在首次使用前配置）：
| 变量名 | 必需 | 说明 | 示例 |
|---|
LIT_DOWNLOAD_DIR | 是 | 论文下载保存目录 | ~/Downloads |
LIT_PROGRESS_FILE | 是 | 下载进度追踪文件路径 | memory/literature-progress.md |
LIT_CDP_PORT | 否 | 浏览器远程调试端口（默认 9334） | 9334 |
LIT_NOTIFY_CHANNEL | 否 | 通知渠道（如 wechat-access、telegram 等） | wechat-access |
LIT_NOTIFY_USER | 否 | 通知目标用户 ID | your-user-id |
SEMANTIC_SCHOLAR_API_KEY | 否 | Semantic Scholar API 密钥 | your-key |
LIT_UNPAYWALL_EMAIL | 否 | Unpaywall API 所需邮箱 | your-email@example.com |
首次使用时，AI 应检查以上变量是否已配置。若缺失，主动询问用户并引导配置。
若用户未配置通知渠道，跳过通知步骤，仅在对话中告知结果。
流程概览
1. 文献检索 → 2. 结果展示 → 3. 用户确认 → 4a. 直接下载成功
↓ (失败)
4b. 科研通求助
↓
5. 建立Cron监控
↓
6. 应助 → 自动下载 → 通知用户
↓
7. 告知用户 + 更新进度
Step 1：文献检索
必须先读取 academic-literature-search 技能，路径通过以下方式定位：
- 优先查找当前 workspace 下的
skills/academic-literature-search/SKILL.md
- 其次查找
~/.qclaw/skills/academic-literature-search/SKILL.md
- 若均不存在，提示用户先安装 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）
- 参考命令（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 发布求助：
关键参数获取（每次操作前必须从页面重新获取）：
- CSRF Token：从页面
<meta name="csrf-token"> 提取
- Cookie：通过
Network.getAllCookies 获取所有 ablesci.com 域名下的 cookie
- 标签页：每次操作前重新
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 任务检测到新应助时：
- 提取下载 ID：从详情页 HTML 中解析下载链接
- 触发下载：
- 新建标签页打开下载链接
- 执行
Page.setDownloadBehavior(behavior=allow, downloadPath={LIT_DOWNLOAD_DIR})
- 等待文件从
.crdownload 变为 .pdf（通常 5-30 秒）
- 重命名文件：去掉
(科研通-ablesci.com) 等后缀，保留年份信息
- 验证 PDF：文件头为
%PDF，大小 > 50 KB
- 更新进度表：
LIT_PROGRESS_FILE
- 通知用户（若已配置通知渠道）
关键坑点记录（来自实战经验）
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 查不到 → 直接转向科研通
依赖技能
| 技能 | 用途 | 安装方式 |
|---|
| academic-literature-search | Crossref/Semantic Scholar 文献检索 | skillhub install academic-literature-search |
| browser-cdp | CDP 浏览器自动化 | 内置或 skillhub install browser-cdp |
| qclaw-cron-skill | 定时任务管理 | 内置 |
