{"id":"55d7ebb1-205b-4fb5-8d6b-80baf6a3824d","entityType":"agent","slug":"clawhub-georgechou17-unified-research-finder","name":"Unified Research Finder","canonicalUrl":"https://www.xpersona.co/agent/clawhub-georgechou17-unified-research-finder","canonicalPath":"/agent/clawhub-georgechou17-unified-research-finder","generatedAt":"2026-10-13T18:16:23.507Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":null},"description":"统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用 Skill: Unified Research Finder Owner: georgechou17 Summary: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用 Tags: latest:1.1.1 Version history: v1.1.1 | 2026-07-24T14:","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 980 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s176y064ps888173yfc6zmjp498b0fqn:unified-research-finder","sourceUrl":"https://clawhub.ai/georgechou17/unified-research-finder","homepage":"https://clawhub.ai/georgechou17/skills/unified-research-finder","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/georgechou17/unified-research-finder","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/georgechou17/skills/unified-research-finder","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":null},"stars":null,"forks":null,"downloads":980,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.1.1","tractionLabel":"980 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:00:14.638Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:00:14.703Z","lastCrawledAt":"2026-10-11T23:00:14.638Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:00:14.638Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.1","createdAt":"2026-07-24T14:07:14.554Z","changelog":"# 更新日志 / Changelog ## [v1.1.1] — 2026-07-24 ### 🚀 数据源扩展 **#4 新增 KipHub 学术 + 学术搜索Pro 镜像，修复烂番薯反爬** - **现象**：2026-07-24 起，中国 Scholar 镜像站普遍升级反爬策略，原四源全部不可达（dotaindex API 500、烂番薯 403、hk/google 超时）。 - **修复**： - 新增 **KipHub学术**（`kiphub.com`，自定义 `paper-summary-wrapper` 解析器）和 **学术搜索Pro**（`googlescholar.pro`，`card-title/card-meta/card-text` 解析器）。 - 修复烂番薯：URL 中加入 `hl=zh-CN&as_sdt=0,5&btnG=` 固定参数，绕过 403 反爬墙。 - 底层扩展：SOURCES 新增 `query_param`（如 kiphub 用 `wd`）和 `extra_params` 字段，支持不同镜像的参数约定。 - 优先级更新为 **kiphub → lanfanshu → scholar_pro → dotaindex → hk → google**。 - 全部 Scholar 源失败时，提示中明确建议安装 Playwright 并启用 `--browser` 兜底。 - **实测**：kiphub `积雪草` 返回 10 条；scholar_pro 返回 9 条，含标题/作者/年份/摘要/被引；lanfanshu 固定参数后可正常访问。 ### 📝 文档更新 - `references/scholar-sources.md`：扩展为 6 源技术参考（新增 kiphub/scholar_pro 解析器说明及字段映射）。 - `SKILL.md`：描述 / 触发词 / 用例 / 未找到提示全部更新为 6 源。 - `README.md`：更新项目简介，反映当前 6 源 Scholar 检索能力。","fileCount":11,"zipByteSize":36071},{"version":"1.1.0","createdAt":"2026-07-24T10:50:30.539Z","changelog":"# 更新日志 / Changelog ## [v1.1] — 2026-07-24 ### 🐛 Bug Fixes **#1 沙箱环境下 `unified_search.py` 被 SIGKILL（无任何输出）** - **现象**：在某些受约束的沙箱环境（如 operitAI、WorkBuddy sandbox）中运行 `unified_search.py` 时，进程直接被杀死，不产生 stdout/stderr 任何输出。 - **根因**：旧版使用 `subprocess.run()` 串行执行 PubMed → Scholar。Scholar 需依次尝试 4 个源，每个源 HTTP 超时 25s，全程 2-3 分钟无任何 I/O。沙箱检测到进程长时间零输出后发送 SIGKILL，`print()` 永远走不到。 - **修复**： - 两路子进程改用 `concurrent.futures.ThreadPoolExecutor` 并行启动。 - Scholar 设独立 60s 超时上限（≈ 走完 2-3 个源），超时直接出部分结果，不阻塞输出。 - 所有 `print()` 后追加 `sys.stdout.flush()`，确保管道/沙箱立刻看到 I/O。 - 即使 Scholar 超时，PubMed 结果仍正常合并输出。 **#2 operitAI 加载 skill 时三条启动报错** - **现象**：在 operitAI（Android）加载本 skill 时，控制台出现三条错误： 1. `tool_name must use packageName:toolName format` 2. `Tool not found: unified-research-finder:unified_search` 3. `Tool not found: unified-research-finder:terminal` - **根因**：operitAI 自动扫描 `scripts/` 目录，试图把每个 `.py` 文件按 `{skill_name}:{script_basename}` 格式注册为工具。由于 SKILL.md 缺少显式 `tools` 声明，注册格式校验失败，后续工具查找全部落空。 - **修复**：在 SKILL.md frontmatter 中新增 `tools` 显式声明： ```yaml tools: - unified_search.py - pubmed_search.py - scholar_search.py ``` ### 📝 文档改进 - README.md 项目结构段落地道化：去掉面向维护者的 \"你需要上传/发布\" 措辞，改为中性的「项目结构 / Project Structure」。 - README.md 脚注去掉了 \"提交到 GitHub/SkillHub 时请上传整个文件夹\" 等维护者口吻，改为说明 `__pycache__` 已被 `.gitignore` 自动排除。 --- ## [v1.0] — 2026-07-22 ### ✨ Initial Release - **PubMed 子系统**：基于 NCBI E-utilities 官方 API（`esearch` + `efetch`），返回真实 PMID/摘要/DOI。 - **Scholar 多源回退**：覆盖灯塔（JSON API，最快最省内存）、烂番薯（HTML 服务端渲染）、Google Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港 → 官方」优先级自动回退。 - **双库合并去重**（`unified_search.py`）：同时检索 PubMed + Scholar，以 DOI 或归一化标题为键去重，默认开启。 - **纯标准库**：所有脚本仅用 Python 内置模块，无需 `pip install`，启动快、内存低。 - **开源投稿文件**：MIT-0 License、中英双语 README.md、`.gitignore`。","fileCount":13,"zipByteSize":34175},{"version":"0.1.0","createdAt":"2026-07-22T04:07:39.232Z","changelog":"Unified Research Finder v0.1.0: Initial release of an academic literature search assistant with robust, real-document-only results from both PubMed and Google Scholar (including multiple mirroring sites). - Supports seamless cross-library searches: merges results from PubMed API and multiple Google Scholar mirrors, with automatic deduplication by DOI/title. - Strictly never generates or fabricates paper info; only returns real, verifiable bibliographic entries from data sources. - Clearly indicates when no results are found or sources are inaccessible—no made-up content. - Provides user-friendly, clickable links for original, DOI, PubMed, and PDF sources. - Detailed trigger list covers a wide range of common literature search requests (keywords, impact factor, citation data, etc.). - Explains deduplication status in every search result and allows users to disable it if desired.","fileCount":12,"zipByteSize":30028}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s176y064ps888173yfc6zmjp498b0fqn:unified-research-finder","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-13T18:16:23.506Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-georgechou17-unified-research-finder/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":null},"readme":"Skill: Unified Research Finder\n\nOwner: georgechou17\n\nSummary: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用\n\nTags: latest:1.1.1\n\nVersion history:\n\nv1.1.1 | 2026-07-24T14:07:14.554Z | user\n\n# 更新日志 / Changelog\n\n## [v1.1.1] — 2026-07-24\n\n### 🚀 数据源扩展\n\n**#4 新增 KipHub 学术 + 学术搜索Pro 镜像，修复烂番薯反爬**\n\n- **现象**：2026-07-24 起，中国 Scholar 镜像站普遍升级反爬策略，原四源全部不可达（dotaindex API 500、烂番薯 403、hk/google 超时）。\n- **修复**：\n - 新增 **KipHub学术**（`kiphub.com`，自定义 `paper-summary-wrapper` 解析器）和 **学术搜索Pro**（`googlescholar.pro`，`card-title/card-meta/card-text` 解析器）。\n - 修复烂番薯：URL 中加入 `hl=zh-CN&as_sdt=0,5&btnG=` 固定参数，绕过 403 反爬墙。\n - 底层扩展：SOURCES 新增 `query_param`（如 kiphub 用 `wd`）和 `extra_params` 字段，支持不同镜像的参数约定。\n - 优先级更新为 **kiphub → lanfanshu → scholar_pro → dotaindex → hk → google**。\n - 全部 Scholar 源失败时，提示中明确建议安装 Playwright 并启用 `--browser` 兜底。\n- **实测**：kiphub `积雪草` 返回 10 条；scholar_pro 返回 9 条，含标题/作者/年份/摘要/被引；lanfanshu 固定参数后可正常访问。\n\n### 📝 文档更新\n\n- `references/scholar-sources.md`：扩展为 6 源技术参考（新增 kiphub/scholar_pro 解析器说明及字段映射）。\n- `SKILL.md`：描述 / 触发词 / 用例 / 未找到提示全部更新为 6 源。\n- `README.md`：更新项目简介，反映当前 6 源 Scholar 检索能力。\n\nv1.1.0 | 2026-07-24T10:50:30.539Z | user\n\n# 更新日志 / Changelog\n\n## [v1.1] — 2026-07-24\n\n### 🐛 Bug Fixes\n\n**#1 沙箱环境下 `unified_search.py` 被 SIGKILL（无任何输出）**\n\n- **现象**：在某些受约束的沙箱环境（如 operitAI、WorkBuddy sandbox）中运行 `unified_search.py` 时，进程直接被杀死，不产生 stdout/stderr 任何输出。\n- **根因**：旧版使用 `subprocess.run()` 串行执行 PubMed → Scholar。Scholar 需依次尝试 4 个源，每个源 HTTP 超时 25s，全程 2-3 分钟无任何 I/O。沙箱检测到进程长时间零输出后发送 SIGKILL，`print()` 永远走不到。\n- **修复**：\n - 两路子进程改用 `concurrent.futures.ThreadPoolExecutor` 并行启动。\n - Scholar 设独立 60s 超时上限（≈ 走完 2-3 个源），超时直接出部分结果，不阻塞输出。\n - 所有 `print()` 后追加 `sys.stdout.flush()`，确保管道/沙箱立刻看到 I/O。\n - 即使 Scholar 超时，PubMed 结果仍正常合并输出。\n\n**#2 operitAI 加载 skill 时三条启动报错**\n\n- **现象**：在 operitAI（Android）加载本 skill 时，控制台出现三条错误：\n 1. `tool_name must use packageName:toolName format`\n 2. `Tool not found: unified-research-finder:unified_search`\n 3. `Tool not found: unified-research-finder:terminal`\n- **根因**：operitAI 自动扫描 `scripts/` 目录，试图把每个 `.py` 文件按 `{skill_name}:{script_basename}` 格式注册为工具。由于 SKILL.md 缺少显式 `tools` 声明，注册格式校验失败，后续工具查找全部落空。\n- **修复**：在 SKILL.md frontmatter 中新增 `tools` 显式声明：\n ```yaml\n tools:\n - unified_search.py\n - pubmed_search.py\n - scholar_search.py\n ```\n\n### 📝 文档改进\n\n- README.md 项目结构段落地道化：去掉面向维护者的 \"你需要上传/发布\" 措辞，改为中性的「项目结构 / Project Structure」。\n- README.md 脚注去掉了 \"提交到 GitHub/SkillHub 时请上传整个文件夹\" 等维护者口吻，改为说明 `__pycache__` 已被 `.gitignore` 自动排除。\n\n---\n\n## [v1.0] — 2026-07-22\n\n### ✨ Initial Release\n\n- **PubMed 子系统**：基于 NCBI E-utilities 官方 API（`esearch` + `efetch`），返回真实 PMID/摘要/DOI。\n- **Scholar 多源回退**：覆盖灯塔（JSON API，最快最省内存）、烂番薯（HTML 服务端渲染）、Google Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港 → 官方」优先级自动回退。\n- **双库合并去重**（`unified_search.py`）：同时检索 PubMed + Scholar，以 DOI 或归一化标题为键去重，默认开启。\n- **纯标准库**：所有脚本仅用 Python 内置模块，无需 `pip install`，启动快、内存低。\n- **开源投稿文件**：MIT-0 License、中英双语 README.md、`.gitignore`。\n\nv0.1.0 | 2026-07-22T04:07:39.232Z | auto\n\nUnified Research Finder v0.1.0: Initial release of an academic literature search assistant with robust, real-document-only results from both PubMed and Google Scholar (including multiple mirroring sites).\n\n- Supports seamless cross-library searches: merges results from PubMed API and multiple Google Scholar mirrors, with automatic deduplication by DOI/title.\n- Strictly never generates or fabricates paper info; only returns real, verifiable bibliographic entries from data sources.\n- Clearly indicates when no results are found or sources are inaccessible—no made-up content.\n- Provides user-friendly, clickable links for original, DOI, PubMed, and PDF sources.\n- Detailed trigger list covers a wide range of common literature search requests (keywords, impact factor, citation data, etc.).\n- Explains deduplication status in every search result and allows users to disable it if desired.\n\nArchive index:\n\nArchive v1.1.1: 11 files, 36071 bytes\n\nFiles: CHANGELOG.md (5217b), README.md (9359b), references/pubmed-query-syntax.md (2113b), references/register-api-key.md (3050b), references/scholar-sources.md (5439b), scripts/pubmed_search.py (11904b), scripts/scholar_search.py (21830b), scripts/unified_search.py (9931b), skill-card.md (2685b), SKILL.md (10571b), _meta.json (142b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: unified-research-finder\ndescription: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实\n PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google\n Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google\n 学术/谷歌学术、用学术镜像站、要影响因子或引用数据时启用。找不到就是找不到，绝不编造。\nagent_created: true\nversion: v1.1.1\ntriggers:\n - 找文献\n - 检索论文\n - 搜索文献\n - 查论文\n - 查 PubMed\n - PubMed 检索\n - 医学文献\n - Google 学术\n - 谷歌学术\n - 学术搜索\n - 学术镜像\n - 烂番薯\n - 灯塔学术\n - KipHub\n - 学术搜索Pro\n - 查影响因子\n - 论文引用\n - 相关论文\n - 推荐文献\n - 双库检索\n - 合并去重\n - 跨库检索\n - 多库去重\ndisable: false\ntools:\n - unified_search\n - pubmed_search\n - scholar_search\n---\n\n# 学术文献检索助手 (Unified Research Finder)\n\n## ⚠️ 第一原则：真实、可验证，绝不编造\n\n- ✅ 只返回脚本真实返回的文献（PubMed API / Scholar 镜像真实响应）。\n- ✅ 明确标注「未找到」当检索无果或所有源被拦截。\n- ✅ 提供可点击的链接（PubMed / DOI / 原文 / PDF）。\n- ❌ 绝不生成虚假标题、作者、PMID、引用数或下载链接。\n- ❌ 网络不通或源被拦截时，如实说明，不臆造结果。\n\n## 🔁 默认行为：PubMed + Scholar 多库合并去重（默认开启）\n\n- **默认同时检索两大库**：PubMed（官方 E-utilities API）+ Google Scholar 及镜像站（灯塔 JSON 优先），再合并。\n- **默认开启跨库去重**：以 DOI 或归一化标题为键，剔除 PubMed 与 Scholar 之间的重复文献（同一篇论文不会重复出现）。\n- **⚠️ 每次查找，必须明确告知用户**：「已开启多库去重，可手动关闭」（即 `unified_search.py` 输出里的 `dedup_note`）。\n- **用户要求不去重时**：改用 `unified_search.py --no-dedup`（仍同时检索两库，但保留重复项）；或直接走流程 A / 流程 B 的单库检索。\n- 入口脚本：`scripts/unified_search.py`（详见下方「流程 C」）。\n\n## 何时使用本技能\n\n- 用户要找某主题 / 篇名 / 作者 / 关键词的文献。\n- 用户要查 PubMed（医学、生物、生物医学预印本）。\n- 用户要查 Google Scholar、谷歌学术，或点名「烂番薯 / 灯塔 / 香港镜像 / 官方站」。\n- 用户要影响因子、被引次数、PDF 全文链接、DOI。\n\n## 两大子系统与脚本\n\n| 子系统 | 脚本 | 说明 |\n|--------|------|------|\n| **PubMed（API + 网页）** | `scripts/pubmed_search.py` | 基于 NCBI E-utilities 官方 API，仅用标准库，无需装包。 |\n| **Google Scholar + 镜像** | `scripts/scholar_search.py` | 自动按优先级检索 4 个源，纯标准库；可选 Playwright 兜底。 |\n| **双库合并去重（默认）** | `scripts/unified_search.py` | 同时检索 PubMed + Scholar，合并并按 DOI/标题去重；`--no-dedup` 可关。 |\n\n参考文档：`references/scholar-sources.md`（四源技术细节）、\n`references/pubmed-query-syntax.md`（PubMed 检索语法）、\n`references/register-api-key.md`（NCBI API key 注册引导）。\n\n---\n\n## 流程 A：PubMed 检索（医学 / 生物 / 影响因子）\n\n适用于：医学、生物医学、生命科学，或用户明确提到 PubMed / PMID / DOI / 影响因子。\n\n1. **构造检索式**：将自然语言转为 PubMed 查询。需要复杂式（MeSH、字段、文献类型、日期）时，先读 `references/pubmed-query-syntax.md`。\n - 「最新研究」→ 加 `--sort pub_date`\n - 「最相关 / 权威」→ 默认 `--sort relevance`\n - 「RCT / 系统综述 / Meta」→ 查询串加 `randomized controlled trial[pt]` 等\n - 未指定篇数 → 默认 `--retmax 5`\n - 用户直接给 PMID → 用 `--pmids` 模式\n2. **运行脚本**：\n ```bash\n # 关键词检索（esearch → efetch 自动串联）\n python scripts/pubmed_search.py --query \"metformin AND type 2 diabetes\" --retmax 5\n # 限定年份 + 按日期排序\n python scripts/pubmed_search.py --query \"semaglutide[tiab] AND obesity[mh]\" --sort pub_date --mindate 2023/01/01 --retmax 5\n # 直接按 PMID 获取\n python scripts/pubmed_search.py --pmids 36967777 37397787\n ```\n 脚本向 stdout 输出 JSON：`{ok, query, count, pmids, articles[]}`。每篇含 `pmid, title, authors[], journal, pubdate, abstract, doi, doi_url, pubmed_url`。\n3. **整理为中文报告**（遵循 `references/` 中的模板）：标题（附中文翻译）、作者、期刊、日期、PMID、DOI、摘要中文概述、原文摘要折叠块。\n4. **API key 引导**：当脚本输出 `api_key_hint: true`（批量或限流），读取 `references/register-api-key.md` 并用大白话引导用户注册免费 NCBI API key。key 仅作命令参数 / 环境变量 `NCBI_API_KEY`，不写入文件。\n\n> 网络不通 `eutils.ncbi.nlm.nih.gov` 时如实告知，不编造。纯网页版 PubMed 检索可用浏览器访问 `pubmed.ncbi.nlm.nih.gov` 作为补充。\n\n---\n\n## 流程 B：Google Scholar 及镜像站检索\n\n适用于：全学科文献、引用数据、PDF 全文、用户点名 Scholar / 谷歌学术 / 镜像站。\n\n1. **运行脚本**（默认 auto，按优先级自动回退）：\n ```bash\n # 自动：kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方，取首个有结果的源\n python scripts/scholar_search.py --query \"large language model survey\" --num 10\n # 指定单一源（如用户只要灯塔）\n python scripts/scholar_search.py --query \"...\" --source dotaindex\n # 按日期排序 + 限 2020 年以来\n python scripts/scholar_search.py --query \"...\" --sort date --ylo 2020\n # 分页 / 偏移\n python scripts/scholar_search.py --query \"...\" --num 20 --start 0\n ```\n 输出 JSON：`{ok, source, query, count, results[], note}`。每篇结果含\n `title, url, authors, year, venue, snippet, citations, pdf_url`。\n2. **源优先级与回退**（默认 auto 行为）：\n - **kiphub**（KipHub学术）优先——大陆直连、自定义 HTML 结构（`paper-summary-wrapper`），当前最快最稳。\n - **烂番薯**（lanfanshu）次之——经典 Scholar HTML，添加了 `hl/as_sdt/btnG` 固定参数以绕过反爬墙。\n - **学术搜索Pro**（scholar_pro）再次——card 布局自定义 HTML，含摘要和被引次数。\n - **灯塔**（dotaindex）——JSON API，最快最省内存，但近期后端不稳定（500/超时）。\n - **香港镜像 / 官方站**——经典 HTML，大陆常被网络阻断。\n - 任一源被拦截（403/验证码/超时）自动尝试下一源；全部失败则在 `note` 说明，**不返回虚构文献**。\n3. **浏览器兜底（可选）**：当所有 HTTP 尝试被拦截且用户需要，安装 Playwright 后以 `--browser` 模式启动无头浏览器渲染：\n ```bash\n pip install playwright && playwright install chromium\n python scripts/scholar_search.py --query \"...\" --browser\n ```\n 仅 HTML 源启用浏览器；灯塔 JSON 无需浏览器。此模式较重，按需使用以节省资源。\n4. **整理为中文报告**：逐篇列出 标题、作者、年份、来源(vision)、摘要片段、被引次数、链接（原文 + PDF 全文若有）。\n\n> 设计取舍：默认纯标准库 HTTP，启动快、内存低；Playwright 仅作被拦截时的兜底，避免常驻重进程。详见 `references/scholar-sources.md`。\n\n---\n\n## 流程 C：双库合并去重检索（默认推荐）\n\n适用于绝大多数场景：用户只说「帮我找 XX 的文献」「搜一下 XX」，未限定只用某一库。\n\n1. **运行入口脚本**（默认即开启跨库去重）：\n ```bash\n # 同时检索 PubMed + Scholar，合并并按 DOI / 归一化标题去重（默认）\n python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n # 按日期排序 + 限 2022 以来\n python scripts/unified_search.py --query \"...\" --sort date --ylo 2022\n # 用户要求不去重时（仍同时检索两库，保留重复项）\n python scripts/unified_search.py --query \"...\" --no-dedup\n ```\n 输出 JSON：`{ok, query, dedup_enabled, dedup_note, pubmed_count, scholar_count,\n merged_count, deduped_count, removed_count, pubmed{}, scholar{}, results[]}`。\n 每条统一记录含 `db(pubmed|scholar), title, authors, year, venue, snippet, citations,\n url, pdf_url, doi, doi_url, pmid, pubmed_url`。\n2. **⚠️ 必须告知用户**：无论结果多少，先说一句\n **「已开启多库去重，可手动关闭」**（即输出里的 `dedup_note`）。\n 用户若说「不用去重 / 关掉去重」，则用 `--no-dedup` 重跑。\n3. **整理为中文报告**：逐篇列出（用 `db` 字段标注来自 PubMed 还是 Scholar）：\n 标题、作者、年份、来源、摘要/片段、被引次数、链接（原文 + PDF/DOI + PubMed）。\n 去重计数可附注：「共合并 N 条，去重后 K 条（移除 R 条重复）」。\n4. **单库回退**：当用户明确只要 PubMed 或只要 Scholar 时，分别走流程 A / 流程 B。\n\n---\n\n## 输出格式\n\n### 找到文献时\n\n```\n📄 检索结果 [1/N]\n\n标题：{title}（{中文译名，如有}）\n作者：{authors}\n年份 / 来源：{year} · {venue}\n被引次数：{citations}（{source}）\n🔗 链接：\n- 原文：{url}\n- PDF：{pdf_url}（若有）\n📋 摘要：{snippet 或 PubMed 摘要中文概述}\n---\n```\n\n### 未找到 / 全部源被拦截时\n\n```\n❌ 未找到符合条件的文献 / 全部数据源暂不可达\n\n检索条件：{query}，年份≥{ylo}，排序={sort}\n已开启多库去重：是（--no-dedup 可关）\n尝试数据源：PubMed（官方 API）、KipHub、烂番薯、学术搜索Pro、灯塔、香港镜像、Google 官方\n结果：{note 中的具体原因，如「PubMed 可达但无命中；烂番薯与灯塔均触发限流，香港/官方站网络不可达」}\n建议：稍后重试；或换更宽泛关键词；或 installed Playwright 后用 --browser 模式。\n```\n\n## 相关技能 / 后续\n\n- 读文献、做摘要：可配合阅读类 skill。\n- 引用管理、影响因子核实：Crossref / JCR / 中科院分区。\n\nFile v1.1.1:README.md\n\n# Unified-Research-Finder\n\n**[简体中文](#简体中文) | [English](#english)**\n\n## 目录 / Table of Contents\n\n- [简体中文](#简体中文)\n - [1. 简介](#1-简介)\n - [2. 安装与使用](#2-安装与使用)\n - [3. 技术原理](#3-技术原理)\n - [4. 致谢](#4-致谢)\n- [English](#english)\n - [1. Introduction](#1-introduction)\n - [2. Install & Use](#2-install--use)\n - [3. How It Works](#3-how-it-works)\n - [4. Acknowledgements](#4-acknowledgements)\n\n---\n\n# 简体中文\n\n## 1. 简介\n\n**Unified-Research-Finder** 是一个用于 WorkBuddy / 兼容 SkillHub 的「学术文献一站式检索」技能。它把两套最常用的学术搜索引擎合二为一：\n\n- **PubMed**（生物医学权威数据库）——走官方 E-utilities API，返回真实 PMID、摘要、DOI。\n- **Google Scholar 及其镜像站**——覆盖「KipHub学术」「烂番薯学术」「学术搜索Pro」「灯塔学术」「Google Scholar 香港镜像」「Google Scholar 官方站」**六个源**，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。\n\n默认开启 **PubMed + Scholar 跨库合并去重**：同一篇论文不会在两库里重复出现。所有结果均来自真实网络响应，**找不到就是找不到，绝不编造**。\n\n## 2. 安装与使用\n\n> 给电脑小白的话：别慌，这东西不需要你懂编程，跟着点就行。\n\n**第一步：拿到文件**\n把本仓库（文件夹 `Unified-Research-Finder`）整个下载下来，放到你电脑里 WorkBuddy 的技能目录：\n- Windows：`C:\\Users\\你的用户名\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux：`~/.workbuddy/skills/Unified-Research-Finder/`\n\n（你也可以直接把仓库里的 `Unified-Research-Finder` 文件夹复制过去。）\n\n**第二步：开始用**\n在 WorkBuddy 对话框里直接说人话就行，例如：\n- 「帮我找 CRISPR 基因编辑 的最新文献」\n- 「在 PubMed 上搜 二甲双胍 和 2 型糖尿病」\n- 「用灯塔学术查 大语言模型 综述」\n\n技能会自动同时检索两库、合并去重，并告诉你「已开启多库去重，可手动关闭」。\n如果你不想去重，说一句「不用去重」，它会保留重复项。\n\n> 进阶（可选）：脚本是纯 Python 标准库写的，装好 Python 3.8+ 即可直接在命令行跑：\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**项目结构 / Project Structure：**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # 技能说明（触发词、检索流程、输出模板）\n├── CHANGELOG.md # 更新日志\n├── LICENSE # MIT-0 开源协议\n├── README.md # 本说明文件（中英双语）\n├── .gitignore # 忽略 Python 缓存等无关文件\n├── scripts/\n│ ├── unified_search.py # 双库合并去重入口（默认推荐）\n│ ├── pubmed_search.py # PubMed 官方 API 检索\n│ └── scholar_search.py # Google Scholar 及镜像站检索\n└── references/\n ├── scholar-sources.md # 四个 Scholar 源的技术细节\n ├── pubmed-query-syntax.md # PubMed 检索语法\n └── register-api-key.md # 免费注册 NCBI API key 引导\n```\n\n（运行时自动生成的 `__pycache__` 等缓存已被 `.gitignore` 排除，不会进入仓库。）\n\n## 3. 技术原理\n\n- **纯标准库、零依赖**：所有脚本只用 Python 自带模块（`urllib` / `json` / `re` / `subprocess`），无需 `pip install`，启动快、内存低。\n- **PubMed**：直接调用 NCBI 官方 `esearch` + `efetch` 接口，拿到结构化 JSON（PMID、标题、作者、期刊、摘要、DOI），真实可验证。\n- **Scholar 多源回退**：优先用「灯塔学术」的 JSON API（最快最省内存）；若被限流，自动退回「烂番薯」服务端渲染 HTML（带 Referer 解析）；再不行试香港镜像与官方站。任一源被拦截（403 / 验证码 / 超时）即跳下一源。\n- **跨库合并去重**：`unified_search.py` 用子进程并行调用上面两个脚本，把结果统一字段后，以 **DOI 或归一化标题** 为键去重——同一篇论文在 PubMed 和 Scholar 都出现时只保留一条。\n- **浏览器兜底（可选）**：当所有 HTTP 方式都被拦，可装 Playwright 用 `--browser` 模式做无头渲染；该模式较重，仅按需启用，不常驻。\n\n## 4. 致谢\n\n本技能最初是作为 [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder) 的升级案例而构思的。`paper-finder` 提供了「只返回真实文献、绝不编造」的优良第一原则，以及清晰的技能结构范式，本项目的 PubMed 网页检索思路也受其启发。在此对 `paper-finder` 的作者表达诚挚感谢。\n\n---\n\n# English\n\n## 1. Introduction\n\n**Unified-Research-Finder** is an all-in-one academic literature search skill for WorkBuddy / SkillHub-compatible agents. It unifies two of the most-used scholarly search engines:\n\n- **PubMed** (the authoritative biomedical database) — powered by the official NCBI E-utilities API, returning real PMIDs, abstracts, and DOIs.\n- **Google Scholar and its mirrors** — covering \"KipHub\", \"Lanfanshu\", \"Scholar Pro\", \"Dotaindex\", the Google Scholar Hong Kong mirror, and the official Google Scholar site — **six sources** with auto fallback in priority order.\n\nCross-database **merge + deduplication (PubMed + Scholar) is on by default**: the same paper never appears twice. Every result comes from a real network response — **if nothing is found, we say so; we never fabricate.**\n\n## 2. Install & Use\n\n> Plain-English version for non-technical users: don't panic, you don't need to know any coding.\n\n**Step 1 — Get the files**\nDownload this repository (the `Unified-Research-Finder` folder) and drop it into your WorkBuddy skills directory:\n- Windows: `C:\\Users\\YourName\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux: `~/.workbuddy/skills/Unified-Research-Finder/`\n\n(You can simply copy the `Unified-Research-Finder` folder from the repo.)\n\n**Step 2 — Start using**\nJust talk to WorkBuddy in plain language, e.g.:\n- \"Find me the latest papers on CRISPR gene editing\"\n- \"Search PubMed for metformin and type 2 diabetes\"\n- \"Use Dotaindex to look up large language model surveys\"\n\nThe skill searches both databases, merges and deduplicates, and tells you \"cross-database deduplication is on; you can turn it off.\" If you don't want deduplication, just say so and it keeps the duplicates.\n\n> Advanced (optional): the scripts use only the Python standard library. With Python 3.8+ you can run them directly from the command line:\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**Project Structure:**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # Skill manifest (triggers, search flows, output templates)\n├── CHANGELOG.md # Changelog\n├── LICENSE # MIT-0 license\n├── README.md # This file (bilingual)\n├── .gitignore # Excludes Python caches and unrelated files\n├── scripts/\n│ ├── unified_search.py # Dual-database merge + dedup entry point (recommended)\n│ ├── pubmed_search.py # PubMed official API search\n│ └── scholar_search.py # Google Scholar & mirrors search\n└── references/\n ├── scholar-sources.md # Technical details of the four Scholar sources\n ├── pubmed-query-syntax.md # PubMed query syntax\n └── register-api-key.md # Guide to register a free NCBI API key\n```\n\n(Runtime-generated caches such as `__pycache__` are excluded by `.gitignore` and never enter the repository.)\n\n## 3. How It Works\n\n- **Standard library only, zero dependencies**: every script uses only Python built-ins (`urllib` / `json` / `re` / `subprocess`) — no `pip install` needed; fast startup, low memory.\n- **PubMed**: calls the official NCBI `esearch` + `efetch` endpoints and gets structured JSON (PMID, title, authors, journal, abstract, DOI) — verifiable and real.\n- **Scholar multi-source fallback**: prefers the \"Dotaindex\" JSON API (fastest, lowest memory); if rate-limited, falls back to \"Lanfanshu\" server-rendered HTML (parsed with a `Referer` header); then the HK mirror and the official site. Any blocked source (403 / CAPTCHA / timeout) triggers the next one.\n- **Cross-database merge + dedup**: `unified_search.py` invokes the two scripts as subprocesses, normalizes their fields, then deduplicates by **DOI or normalized title** — so a paper present in both PubMed and Scholar is kept only once.\n- **Browser fallback (optional)**: when every HTTP path is blocked, install Playwright and use `--browser` for headless rendering; this mode is heavy and only used on demand, never resident.\n\n## 4. Acknowledgements\n\nThis skill was originally conceived as an upgraded case study of [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder). `paper-finder` established the excellent first principle of \"return only real literature, never fabricate\" and a clean skill structure; its approach to PubMed web search was also an inspiration. Sincere thanks to the author of `paper-finder`.\n\nFile v1.1.1:_meta.json\n\n{\n \"ownerId\": \"kn71cn3h6s4p3eq2qpvbnxq1k98b1r7b\",\n \"slug\": \"unified-research-finder\",\n \"version\": \"1.1.1\",\n \"publishedAt\": 1784902034554\n}\n\nFile v1.1.1:references/pubmed-query-syntax.md\n\n# PubMed 检索语法速查\n\n构造 `--query` 参数时使用。PubMed 支持完整的布尔检索与字段限定。\n\n## 布尔运算\n\n- `AND`、`OR`、`NOT` 必须**大写**\n- 默认多个词之间按 `AND` 处理（自动术语映射可能介入）\n- 括号控制优先级：`(a OR b) AND c`\n\n## 常用字段标签\n\n| 标签 | 含义 | 示例 |\n|------|------|------|\n| `[MeSH Terms]` / `[mh]` | MeSH 主题词 | `\"Diabetes Mellitus, Type 2\"[MeSH Terms]` |\n| `[Title]` / `[ti]` | 标题 | `metformin[Title]` |\n| `[Title/Abstract]` / `[tiab]` | 标题或摘要 | `semaglutide[tiab]` |\n| `[Author]` / `[au]` | 作者 | `Smith J[Author]` |\n| `[Journal]` / `[jour]` | 期刊 | `\"N Engl J Med\"[Journal]` |\n| `[pdat]` | 发表日期 | `2023:2025[pdat]` |\n| `[Publication Type]` / `[pt]` | 文献类型 | `randomized controlled trial[pt]` |\n| `[la]` | 语言 | `english[la]` |\n| `[free full text]` | 免费全文过滤 | `... AND free full text[Filter]` |\n\n## 常用文献类型 `[pt]`\n\n- `randomized controlled trial[pt]` — RCT\n- `systematic review[pt]` — 系统综述\n- `meta-analysis[pt]` — Meta 分析\n- `review[pt]` — 综述\n- `clinical trial[pt]` — 临床试验\n- `case reports[pt]` — 病例报告\n\n## 日期限定（两种方式）\n\n1. 查询内：`\"covid-19\"[mh] AND 2022:2025[pdat]`\n2. 脚本参数（更推荐）：`--mindate 2022/01/01 --maxdate 2025/12/31`\n\n## 短语检索\n\n- 双引号锁定短语，禁用自动术语映射：`\"blood pressure\"` \n- 截词：`*`（至少 4 个字符后），如 `diabet*`\n\n## 典型查询示例\n\n```\n# 某药治疗某病的 RCT\nsemaglutide[tiab] AND \"Obesity\"[MeSH Terms] AND randomized controlled trial[pt]\n\n# 某作者在某期刊的文章\nWang Y[Author] AND \"Lancet\"[Journal]\n\n# 近 5 年系统综述\n\"Alzheimer Disease\"[MeSH Terms] AND systematic review[pt] AND 2020:2025[pdat]\n\n# 标题含某关键词、英文、有免费全文\nmetformin[Title] AND english[la] AND free full text[Filter]\n```\n\n## 排序说明\n\n- `--sort relevance`（默认）：相关性，适合\"最重要的几篇\"\n- `--sort pub_date`：按发表日期倒序，适合\"最新的几篇\"\n\nFile v1.1.1:references/register-api-key.md\n\n# 小白指南：注册 NCBI 账户并获取免费的 PubMed API Key\n\n> 这个技能**不申请 key 也能用**。只有当你需要\"一次查很多篇\"或\"查得快一点\"时，才需要做下面这一步。\n> 全程免费，不用绑卡、不用付费，5 分钟左右搞定。\n\n## 一、先确认：你到底需不需要？\n\n| 你的使用场景 | 需要申请吗 |\n|------|------|\n| 平时每次查几篇文献（≤20 篇） | 不需要，直接能用 |\n| 想一次抓取几十上百篇、或写批量脚本 | 需要，能明显提速 |\n| 搜索时偶尔报错\"访问太频繁\" | 需要，能避免被限流 |\n\n## 二、第一步：注册一个 NCBI 账户（没有就先注册）\n\n1. 打开网站：\n2. 点 **Register for an NCBI account**（注册账户）。\n3. 可以用**邮箱**注册，也可以直接用 **Google / Microsoft 账号**一键登录（最省事）。\n4. 按提示填邮箱、设密码，收一封验证邮件点链接确认。\n5. 注册完成，记住这个账号即可。\n\n> 小提示：NCBI 是\"美国国立生物技术信息中心\"，PubMed 就是它家的数据库。注册它家账户不会给你发广告。\n\n## 三、第二步：生成一个 API Key（一次性操作）\n\n1. 登录后打开：\n2. 找到 **API Key** 这一栏，点 **Create an API Key**（创建密钥）。\n3. 系统会给你一串类似这样的字符（举例）：\n ```\n 0123456789abcdef0123456789abcdef0123\n ```\n4. **复制保存好这串字符**（建议先贴在记事本里，后面用得到）。\n\n> 这就是你的\"API Key\"。它相当于你的专属通行码，能让你查文献的速度从每秒 3 次提升到每秒 10 次。\n\n## 四、第三步：把这个 Key 告诉本技能（两种方式任选）\n\n### 方式 A：临时用一次（在对话里说）\n直接在对话里告诉我：\n> \"用邮箱 me@example.com 和 API key 0123...ef 帮我查 XX\"\n\n我会把它作为本次命令的参数传给脚本（`--email` 和 `--api-key`）。\n\n### 方式 B：设成环境变量（一劳永逸，推荐）\n把 key 存到电脑的环境变量里，以后不用每次都说：\n\n- **Windows（PowerShell）**：\n ```powershell\n [System.Environment]::SetEnvironmentVariable(\"NCBI_API_KEY\", \"0123...ef\", \"User\")\n ```\n 设置后**重启一下 WorkBuddy** 让它读到新变量。\n- **macOS / Linux**：把下面这行加到 `~/.zshrc` 或 `~/.bashrc`，然后重开终端：\n ```bash\n export NCBI_API_KEY=\"0123...ef\"\n ```\n\n设好后，技能会自动使用它，你无需再手动提供。\n\n## 五、常见问题\n\n- **Key 会过期吗？** 一般不会自动过期，但你随时可以在设置页 **Delete** 后重新生成一个。\n- **Key 能给别人吗？** 不能。它绑定你的账户，相当于密码，别外传。\n- **邮箱填了干嘛？** NCBI 建议填，方便他们在接口出问题时联系你，纯属礼貌字段，不强制。\n- **还是看不懂？** 直接把报错或卡住的地方发给我，我一步步带你点。\n\nFile v1.1.1:references/scholar-sources.md\n\n# Scholar 数据源技术参考\n\n本文件供 WorkBuddy 在执行 `scholar_search.py` 时参考，说明四个数据源的\n请求方式、字段结构与兜底逻辑。**所有内容必须来自脚本真实返回，不得编造。**\n\n## 数据源与优先级\n\n`--source auto`（默认）按以下顺序依次尝试，取第一个返回可用结果的源：\n\n| 优先级 | key | 名称 | 类型 | 检索地址 |\n|--------|-------------|---------------------|------|-----------------------------------------------|\n| 1 | kiphub | KipHub学术 | HTML | `https://www.kiphub.com/search?wd=...` |\n| 2 | lanfanshu | 烂番薯学术搜索 | HTML | `https://scholar.lanfanshu.cn/scholar?hl=zh-CN&as_sdt=0,5&q=...&btnG=` |\n| 3 | scholar_pro | 学术搜索Pro | HTML | `https://www.googlescholar.pro/search_results.php?q=...` |\n| 4 | dotaindex | 灯塔学术搜索 | JSON | `https://www.dotaindex.com/api/scholar/search?q=...` |\n| 5 | hk | Google Scholar 香港镜像 | HTML | `https://scholar.google.com.hk/scholar?q=...` |\n| 6 | google | Google Scholar 官方站 | HTML | `https://scholar.google.com/scholar?q=...` |\n\n> 注意：kiphub 使用 `wd`（而非 `q`）作为查询参数名；烂番薯需携带 `hl=zh-CN&as_sdt=0,5&btnG=` 以绕过反爬墙。\n\n用户也可用 `--source lanfanshu|dotaindex|hk|google` 强制指定单一源。\n\n## 公共检索参数\n\n脚本统一将以下参数拼入 URL：\n\n- `q` — 检索词（必填）\n- `start` — 起始偏移，分页步长 10\n- `hl` — 界面语言，默认 `zh-CN`\n- `as_ylo` — 起始年份下限（`--ylo 2020`）\n- `scisbd=1` — 当 `--sort date` 时附加，表示按日期排序（相关性排序不加）\n\n## 灯塔（dotaindex）JSON API\n\n最稳、最快、内存占用最低，**优先使用**。\n\n- 端点：`GET https://www.dotaindex.com/api/scholar/search`\n- 请求头需带 `Referer: https://www.dotaindex.com/scholar` 与 `Accept: application/json`\n- 响应（顶层字典）：\n - `total` — 命中总数（用于 `count`）\n - `results[]` — 每篇文献，关键字段：\n - `titleHtml` — 含 `` 的标题，解析出 `url` 与标题文本\n - `author` — 作者串，如 `\"K Han, A Xiao, E Wu…\"`\n - `year` / `journal` / `publisher`\n - `abstractHtml` — 摘要片段（去标签）\n - `citationCount` — 被引次数（字符串数字）\n - `openAccessUrl` / `accessLinks[].url` — PDF 全文链接\n- 限流表现：被限流时返回 `results: []` 且 `total: 0`（而非报错）。脚本在首页空结果时退避 1.5s 重试一次。\n\n## KipHub 学术（kiphub）\n\n自定义 Bootstrap 结构的 Scholar 镜像：\n\n- 检索地址：`https://www.kiphub.com/search?wd=QUERY`（注意查询参数名是 `wd` 而非 `q`）\n- 结果容器：`
`\n- 标题/链接：`
` 内的第一个 ``\n- 作者·期刊·年份：`
` 内的文本（格式：`作者, 作者... -期刊, 年份`）\n- 当前不支持摘要片段与被引次数\n\n## 学术搜索Pro（scholar_pro）\n\n自定义 card 布局的 Scholar 镜像：\n\n- 检索地址：`https://www.googlescholar.pro/search_results.php?q=QUERY`\n- 结果容器：`
`\n- 标题/链接：`

` 内的 ``\n- 元信息：`
` 内的文本\n- 摘要：`
` 内的文本\n- 被引次数：card 文本中 `被引用次数 N` / `Cited by N` 模式\n- PDF 链接：`[PDF]` 后的 `` 或 `card-side-links` 内的第一个 ``\n\n## 烂番薯 / 香港镜像 / 官方（经典 Scholar HTML）\n\n三者均为服务端渲染的经典 Google Scholar 结构，由同一个 HTML 解析器处理：\n\n- 结果容器：`
`（顺序无关，模糊匹配）\n- 标题/链接：`

标题

`\n- 作者·来源·年份：`
作者 - 期刊, 年份 - 出版方
`\n- 摘要片段：`
`（若该 class 缺失，则取 `gs_a` 与 `gs_fl` 之间的文本兜底）\n- 被引次数：`gs_fl` 内 `被引用次数 N` / `Cited by N` 等写法\n- PDF 链接：`[PDF]` 之后的 href，或 `gs_ggs` 区域内的 href\n\n**烂番薯特别说明**：需带 `Referer: https://scholar.lanfanshu.cn/`，否则返回 403。\n该站对高频请求会限流（403），脚本会自动回退到下一源。\n\n**香港镜像 / 官方站特别说明**：在中国大陆常被网络阻断（连接超时 / SSL 异常）。\n若 HTTP 方式失败，可让用户安装 Playwright 后以 `--browser` 模式用无头浏览器兜底。\n\n## 拦截 / 验证码检测\n\n- HTTP 403 / 429 → 记为「被拦截」，自动尝试下一源。\n- HTML 中出现 `unusual traffic` / `我们的系统检测到` / `captcha` / `why did this happen` 等标记 → 记为「被拦截」。\n- 全部源均无结果时，`ok` 置为 false（或 results 为空），并在 `note` 中说明原因，**绝不返回虚构文献**。\n\n## 性能与依赖\n\n- 默认纯标准库（`urllib`），**无需安装任何第三方包**，内存占用低、启动快。\n- `--browser` 模式依赖 Playwright（`pip install playwright && playwright install chromium`），\n 仅在 HTTP 被拦截且用户确认启用时作为兜底，避免常驻重进程。\n\nFile v1.1.1:CHANGELOG.md\n\n# 更新日志 / Changelog\n\n## [v1.1.1] — 2026-07-24\n\n### 🚀 数据源扩展\n\n**#4 新增 KipHub 学术 + 学术搜索Pro 镜像，修复烂番薯反爬**\n\n- **现象**：2026-07-24 起，中国 Scholar 镜像站普遍升级反爬策略，原四源全部不可达（dotaindex API 500、烂番薯 403、hk/google 超时）。\n- **修复**：\n - 新增 **KipHub学术**（`kiphub.com`，自定义 `paper-summary-wrapper` 解析器）和 **学术搜索Pro**（`googlescholar.pro`，`card-title/card-meta/card-text` 解析器）。\n - 修复烂番薯：URL 中加入 `hl=zh-CN&as_sdt=0,5&btnG=` 固定参数，绕过 403 反爬墙。\n - 底层扩展：SOURCES 新增 `query_param`（如 kiphub 用 `wd`）和 `extra_params` 字段，支持不同镜像的参数约定。\n - 优先级更新为 **kiphub → lanfanshu → scholar_pro → dotaindex → hk → google**。\n - 全部 Scholar 源失败时，提示中明确建议安装 Playwright 并启用 `--browser` 兜底。\n- **实测**：kiphub `积雪草` 返回 10 条；scholar_pro 返回 9 条，含标题/作者/年份/摘要/被引；lanfanshu 固定参数后可正常访问。\n\n### 📝 文档更新\n\n- `references/scholar-sources.md`：扩展为 6 源技术参考（新增 kiphub/scholar_pro 解析器说明及字段映射）。\n- `SKILL.md`：描述 / 触发词 / 用例 / 未找到提示全部更新为 6 源。\n- `README.md`：更新项目简介，反映当前 6 源 Scholar 检索能力。\n\n---\n\n## [v1.1] — 2026-07-24\n\n### 🐛 Bug Fixes\n\n**#1 沙箱环境下 `unified_search.py` 被 SIGKILL（无任何输出）**\n\n- **现象**：在某些受约束的沙箱环境（如 operitAI、WorkBuddy sandbox）中运行 `unified_search.py` 时，进程直接被杀死，不产生 stdout/stderr 任何输出。\n- **根因**：旧版使用 `subprocess.run()` 串行执行 PubMed → Scholar。Scholar 需依次尝试 4 个源，每个源 HTTP 超时 25s，全程 2-3 分钟无任何 I/O。沙箱检测到进程长时间零输出后发送 SIGKILL，`print()` 永远走不到。\n- **修复**：\n - 两路子进程改用 `concurrent.futures.ThreadPoolExecutor` 并行启动。\n - Scholar 设独立 60s 超时上限（≈ 走完 2-3 个源），超时直接出部分结果，不阻塞输出。\n - 所有 `print()` 后追加 `sys.stdout.flush()`，确保管道/沙箱立刻看到 I/O。\n - 即使 Scholar 超时，PubMed 结果仍正常合并输出。\n\n**#2 operitAI 加载 skill 时三条启动报错**\n\n- **现象**：在 operitAI（Android）加载本 skill 时，控制台出现三条错误：\n 1. `tool_name must use packageName:toolName format`\n 2. `Tool not found: unified-research-finder:unified_search`\n 3. `Tool not found: unified-research-finder:terminal`\n- **根因**：operitAI 自动扫描 `scripts/` 目录，试图把每个 `.py` 文件按 `{skill_name}:{script_basename}` 格式注册为工具。由于 SKILL.md 缺少显式 `tools` 声明，注册格式校验失败，后续工具查找全部落空。\n- **修复**：在 SKILL.md frontmatter 中新增 `tools` 显式声明：\n ```yaml\n tools:\n - unified_search\n - pubmed_search\n - scholar_search\n ```\n > **微调（同日）**：初版 `tools` 声明带了 `.py` 后缀，operitAI 将其原样拼接为 `:unified_search.py` 导致一条残留报错。去掉后缀后彻底消除。\n\n**#3 中国 Scholar 镜像站集体反爬/宕机，HTTP 方式无法获取结果**\n\n- **现象**：2026-07-24 起，原四源全部不可达——dotaindex API 500、烂番薯 403、hk/google 超时。纯 HTTP（`urllib`）方式全面失效。\n- **根因**：镜像站普遍升级反爬策略（CAPTCHA/验证码墙），dotaindex 后端宕机。\n- **修复**：\n - 新增两个 Scholar 源：**KipHub学术**（`kiphub.com`）、**学术搜索Pro**（`googlescholar.pro`）。\n - 修复烂番薯：添加 `hl=zh-CN&as_sdt=0,5&btnG=` 固定参数绕过 403 反爬墙。\n - 新增 `query_param` / `extra_params` 源配置字段，支持不同镜像的 URL 参数约定（kiphub 用 `wd` 而非 `q`）。\n - 新增 `parse_kiphub_html()` / `parse_scholarpro_html()` 自定义 HTML 解析器。\n - 优先级更新为：kiphub → lanfanshu → scholar_pro → dotaindex → hk → google。\n - 全部失败时给出明确的 Playwright `--browser` 兜底建议。\n\n### 📝 文档改进\n\n- 更新 `references/scholar-sources.md`：六源技术细节（新增 kiphub/scholar_pro）。\n- README.md 项目结构段落地道化。\n\n---\n\n## [v1.0] — 2026-07-22\n\n### ✨ Initial Release\n\n- **PubMed 子系统**：基于 NCBI E-utilities 官方 API（`esearch` + `efetch`），返回真实 PMID/摘要/DOI。\n- **Scholar 多源回退**：覆盖灯塔（JSON API，最快最省内存）、烂番薯（HTML 服务端渲染）、Google Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港 → 官方」优先级自动回退。\n- **双库合并去重**（`unified_search.py`）：同时检索 PubMed + Scholar，以 DOI 或归一化标题为键去重，默认开启。\n- **纯标准库**：所有脚本仅用 Python 内置模块，无需 `pip install`，启动快、内存低。\n- **开源投稿文件**：MIT-0 License、中英双语 README.md、`.gitignore`。\n\nFile v1.1.1:skill-card.md\n\n## Description:\n\nUnified Research Finder helps agents search real academic literature across PubMed and Google Scholar or mirror sources, merge and deduplicate results, and report citations, abstracts, DOI/PMID links, PDFs, and no-result status without fabricating records.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[georgechou17](https://clawhub.ai/user/georgechou17)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and research-focused agents use this skill to run PubMed and Google Scholar or mirror searches for academic papers, citations, abstracts, DOI/PMID links, PDFs, and deduplicated cross-database literature reports.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Research queries are sent to PubMed, Google Scholar, and listed Scholar mirror providers.\n\nMitigation: Use only non-sensitive queries or confirm users are comfortable sending queries to those services before running searches.\n\nRisk: Optional NCBI API keys may be exposed if pasted into chat or command history.\n\nMitigation: Use a secret manager or a tightly scoped NCBI_API_KEY environment variable, and rotate any key already shared.\n\nRisk: The optional browser fallback may interact with anti-bot or CAPTCHA controls on target sites.\n\nMitigation: Enable the Playwright/browser fallback only after confirming the target sites permit that access.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/georgechou17/skills/unified-research-finder)\n- [PubMed Query Syntax Quick Reference](artifact/references/pubmed-query-syntax.md)\n- [NCBI API Key Registration Guide](artifact/references/register-api-key.md)\n- [Scholar Sources Technical Reference](artifact/references/scholar-sources.md)\n- [NCBI Account Signup](https://account.ncbi.nlm.nih.gov/signup/)\n- [NCBI Account Settings](https://www.ncbi.nlm.nih.gov/account/settings/)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, JSON, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown literature summaries with JSON script outputs and inline shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs are based on live PubMed and Scholar or mirror responses; no-result and blocked-source cases are reported explicitly.]\n\n## Skill Version(s):\n\nv1.1.1 (source: frontmatter, ClawHub release metadata, CHANGELOG released 2026-07-24)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.0: 13 files, 34175 bytes\n\nFiles: .gitignore (345b), CHANGELOG.md (2829b), LICENSE (907b), README.md (9122b), references/pubmed-query-syntax.md (2113b), references/register-api-key.md (3050b), references/scholar-sources.md (4060b), scripts/pubmed_search.py (11904b), scripts/scholar_search.py (15928b), scripts/unified_search.py (9931b), skill-card.md (3042b), SKILL.md (10332b), _meta.json (142b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: unified-research-finder\ndescription: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实\n PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google\n Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港镜像 → 官方」优先级自动回退（灯塔走 JSON API\n 最省内存最快）。当用户要找文献、查论文、搜 PubMed、查 Google\n 学术/谷歌学术、用学术镜像站、要影响因子或引用数据时启用。找不到就是找不到，绝不编造。\nagent_created: true\nversion: v1.1\ntriggers:\n - 找文献\n - 检索论文\n - 搜索文献\n - 查论文\n - 查 PubMed\n - PubMed 检索\n - 医学文献\n - Google 学术\n - 谷歌学术\n - 学术搜索\n - 学术镜像\n - 烂番薯\n - 灯塔学术\n - 查影响因子\n - 论文引用\n - 相关论文\n - 推荐文献\n - 双库检索\n - 合并去重\n - 跨库检索\n - 多库去重\ndisable: false\ntools:\n - unified_search.py\n - pubmed_search.py\n - scholar_search.py\n---\n\n# 学术文献检索助手 (Unified Research Finder)\n\n## ⚠️ 第一原则：真实、可验证，绝不编造\n\n- ✅ 只返回脚本真实返回的文献（PubMed API / Scholar 镜像真实响应）。\n- ✅ 明确标注「未找到」当检索无果或所有源被拦截。\n- ✅ 提供可点击的链接（PubMed / DOI / 原文 / PDF）。\n- ❌ 绝不生成虚假标题、作者、PMID、引用数或下载链接。\n- ❌ 网络不通或源被拦截时，如实说明，不臆造结果。\n\n## 🔁 默认行为：PubMed + Scholar 多库合并去重（默认开启）\n\n- **默认同时检索两大库**：PubMed（官方 E-utilities API）+ Google Scholar 及镜像站（灯塔 JSON 优先），再合并。\n- **默认开启跨库去重**：以 DOI 或归一化标题为键，剔除 PubMed 与 Scholar 之间的重复文献（同一篇论文不会重复出现）。\n- **⚠️ 每次查找，必须明确告知用户**：「已开启多库去重，可手动关闭」（即 `unified_search.py` 输出里的 `dedup_note`）。\n- **用户要求不去重时**：改用 `unified_search.py --no-dedup`（仍同时检索两库，但保留重复项）；或直接走流程 A / 流程 B 的单库检索。\n- 入口脚本：`scripts/unified_search.py`（详见下方「流程 C」）。\n\n## 何时使用本技能\n\n- 用户要找某主题 / 篇名 / 作者 / 关键词的文献。\n- 用户要查 PubMed（医学、生物、生物医学预印本）。\n- 用户要查 Google Scholar、谷歌学术，或点名「烂番薯 / 灯塔 / 香港镜像 / 官方站」。\n- 用户要影响因子、被引次数、PDF 全文链接、DOI。\n\n## 两大子系统与脚本\n\n| 子系统 | 脚本 | 说明 |\n|--------|------|------|\n| **PubMed（API + 网页）** | `scripts/pubmed_search.py` | 基于 NCBI E-utilities 官方 API，仅用标准库，无需装包。 |\n| **Google Scholar + 镜像** | `scripts/scholar_search.py` | 自动按优先级检索 4 个源，纯标准库；可选 Playwright 兜底。 |\n| **双库合并去重（默认）** | `scripts/unified_search.py` | 同时检索 PubMed + Scholar，合并并按 DOI/标题去重；`--no-dedup` 可关。 |\n\n参考文档：`references/scholar-sources.md`（四源技术细节）、\n`references/pubmed-query-syntax.md`（PubMed 检索语法）、\n`references/register-api-key.md`（NCBI API key 注册引导）。\n\n---\n\n## 流程 A：PubMed 检索（医学 / 生物 / 影响因子）\n\n适用于：医学、生物医学、生命科学，或用户明确提到 PubMed / PMID / DOI / 影响因子。\n\n1. **构造检索式**：将自然语言转为 PubMed 查询。需要复杂式（MeSH、字段、文献类型、日期）时，先读 `references/pubmed-query-syntax.md`。\n - 「最新研究」→ 加 `--sort pub_date`\n - 「最相关 / 权威」→ 默认 `--sort relevance`\n - 「RCT / 系统综述 / Meta」→ 查询串加 `randomized controlled trial[pt]` 等\n - 未指定篇数 → 默认 `--retmax 5`\n - 用户直接给 PMID → 用 `--pmids` 模式\n2. **运行脚本**：\n ```bash\n # 关键词检索（esearch → efetch 自动串联）\n python scripts/pubmed_search.py --query \"metformin AND type 2 diabetes\" --retmax 5\n # 限定年份 + 按日期排序\n python scripts/pubmed_search.py --query \"semaglutide[tiab] AND obesity[mh]\" --sort pub_date --mindate 2023/01/01 --retmax 5\n # 直接按 PMID 获取\n python scripts/pubmed_search.py --pmids 36967777 37397787\n ```\n 脚本向 stdout 输出 JSON：`{ok, query, count, pmids, articles[]}`。每篇含 `pmid, title, authors[], journal, pubdate, abstract, doi, doi_url, pubmed_url`。\n3. **整理为中文报告**（遵循 `references/` 中的模板）：标题（附中文翻译）、作者、期刊、日期、PMID、DOI、摘要中文概述、原文摘要折叠块。\n4. **API key 引导**：当脚本输出 `api_key_hint: true`（批量或限流），读取 `references/register-api-key.md` 并用大白话引导用户注册免费 NCBI API key。key 仅作命令参数 / 环境变量 `NCBI_API_KEY`，不写入文件。\n\n> 网络不通 `eutils.ncbi.nlm.nih.gov` 时如实告知，不编造。纯网页版 PubMed 检索可用浏览器访问 `pubmed.ncbi.nlm.nih.gov` 作为补充。\n\n---\n\n## 流程 B：Google Scholar 及镜像站检索\n\n适用于：全学科文献、引用数据、PDF 全文、用户点名 Scholar / 谷歌学术 / 镜像站。\n\n1. **运行脚本**（默认 auto，按优先级自动回退）：\n ```bash\n # 自动：灯塔 → 烂番薯 → 香港镜像 → 官方站，取首个有结果的源\n python scripts/scholar_search.py --query \"large language model survey\" --num 10\n # 指定单一源（如用户只要灯塔）\n python scripts/scholar_search.py --query \"...\" --source dotaindex\n # 按日期排序 + 限 2020 年以来\n python scripts/scholar_search.py --query \"...\" --sort date --ylo 2020\n # 分页 / 偏移\n python scripts/scholar_search.py --query \"...\" --num 20 --start 0\n ```\n 输出 JSON：`{ok, source, query, count, results[], note}`。每篇结果含\n `title, url, authors, year, venue, snippet, citations, pdf_url`。\n2. **源优先级与回退**（默认 auto 行为）：\n - **灯塔**（dotaindex）优先——走 JSON API，最快最稳、内存占用最低，作为主力首选源。\n - **烂番薯**（lanfanshu）次之——大陆直连、服务端渲染，需带 Referer，高频会 403 限流。\n - **香港镜像**（scholar.google.com.hk）再次——经典 HTML，大陆常被网络阻断。\n - **官方站**（scholar.google.com）最后——经典 HTML，大陆常被网络阻断。\n - 任一源被拦截（403/验证码/超时）自动尝试下一源；全部失败则在 `note` 说明，**不返回虚构文献**。\n3. **浏览器兜底（可选）**：当所有 HTTP 尝试被拦截且用户需要，安装 Playwright 后以 `--browser` 模式启动无头浏览器渲染：\n ```bash\n pip install playwright && playwright install chromium\n python scripts/scholar_search.py --query \"...\" --browser\n ```\n 仅 HTML 源启用浏览器；灯塔 JSON 无需浏览器。此模式较重，按需使用以节省资源。\n4. **整理为中文报告**：逐篇列出 标题、作者、年份、来源(vision)、摘要片段、被引次数、链接（原文 + PDF 全文若有）。\n\n> 设计取舍：默认纯标准库 HTTP，启动快、内存低；Playwright 仅作被拦截时的兜底，避免常驻重进程。详见 `references/scholar-sources.md`。\n\n---\n\n## 流程 C：双库合并去重检索（默认推荐）\n\n适用于绝大多数场景：用户只说「帮我找 XX 的文献」「搜一下 XX」，未限定只用某一库。\n\n1. **运行入口脚本**（默认即开启跨库去重）：\n ```bash\n # 同时检索 PubMed + Scholar，合并并按 DOI / 归一化标题去重（默认）\n python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n # 按日期排序 + 限 2022 以来\n python scripts/unified_search.py --query \"...\" --sort date --ylo 2022\n # 用户要求不去重时（仍同时检索两库，保留重复项）\n python scripts/unified_search.py --query \"...\" --no-dedup\n ```\n 输出 JSON：`{ok, query, dedup_enabled, dedup_note, pubmed_count, scholar_count,\n merged_count, deduped_count, removed_count, pubmed{}, scholar{}, results[]}`。\n 每条统一记录含 `db(pubmed|scholar), title, authors, year, venue, snippet, citations,\n url, pdf_url, doi, doi_url, pmid, pubmed_url`。\n2. **⚠️ 必须告知用户**：无论结果多少，先说一句\n **「已开启多库去重，可手动关闭」**（即输出里的 `dedup_note`）。\n 用户若说「不用去重 / 关掉去重」，则用 `--no-dedup` 重跑。\n3. **整理为中文报告**：逐篇列出（用 `db` 字段标注来自 PubMed 还是 Scholar）：\n 标题、作者、年份、来源、摘要/片段、被引次数、链接（原文 + PDF/DOI + PubMed）。\n 去重计数可附注：「共合并 N 条，去重后 K 条（移除 R 条重复）」。\n4. **单库回退**：当用户明确只要 PubMed 或只要 Scholar 时，分别走流程 A / 流程 B。\n\n---\n\n## 输出格式\n\n### 找到文献时\n\n```\n📄 检索结果 [1/N]\n\n标题：{title}（{中文译名，如有}）\n作者：{authors}\n年份 / 来源：{year} · {venue}\n被引次数：{citations}（{source}）\n🔗 链接：\n- 原文：{url}\n- PDF：{pdf_url}（若有）\n📋 摘要：{snippet 或 PubMed 摘要中文概述}\n---\n```\n\n### 未找到 / 全部源被拦截时\n\n```\n❌ 未找到符合条件的文献 / 全部数据源暂不可达\n\n检索条件：{query}，年份≥{ylo}，排序={sort}\n已开启多库去重：是（--no-dedup 可关）\n尝试数据源：PubMed（官方 API）、灯塔、烂番薯、香港镜像、Google 官方\n结果：{note 中的具体原因，如「PubMed 可达但无命中；烂番薯与灯塔均触发限流，香港/官方站网络不可达」}\n建议：稍后重试；或换更宽泛关键词；或 installed Playwright 后用 --browser 模式。\n```\n\n## 相关技能 / 后续\n\n- 读文献、做摘要：可配合阅读类 skill。\n- 引用管理、影响因子核实：Crossref / JCR / 中科院分区。\n\nFile v1.1.0:README.md\n\n# Unified-Research-Finder\n\n**[简体中文](#简体中文) | [English](#english)**\n\n## 目录 / Table of Contents\n\n- [简体中文](#简体中文)\n - [1. 简介](#1-简介)\n - [2. 安装与使用](#2-安装与使用)\n - [3. 技术原理](#3-技术原理)\n - [4. 致谢](#4-致谢)\n- [English](#english)\n - [1. Introduction](#1-introduction)\n - [2. Install & Use](#2-install--use)\n - [3. How It Works](#3-how-it-works)\n - [4. Acknowledgements](#4-acknowledgements)\n\n---\n\n# 简体中文\n\n## 1. 简介\n\n**Unified-Research-Finder** 是一个用于 WorkBuddy / 兼容 SkillHub 的「学术文献一站式检索」技能。它把两套最常用的学术搜索引擎合二为一：\n\n- **PubMed**（生物医学权威数据库）——走官方 E-utilities API，返回真实 PMID、摘要、DOI。\n- **Google Scholar 及其镜像站**——覆盖「灯塔学术」「烂番薯学术」「Google Scholar 香港镜像」「Google Scholar 官方站」，按稳定性自动回退。\n\n默认开启 **PubMed + Scholar 跨库合并去重**：同一篇论文不会在两库里重复出现。所有结果均来自真实网络响应，**找不到就是找不到，绝不编造**。\n\n## 2. 安装与使用\n\n> 给电脑小白的话：别慌，这东西不需要你懂编程，跟着点就行。\n\n**第一步：拿到文件**\n把本仓库（文件夹 `Unified-Research-Finder`）整个下载下来，放到你电脑里 WorkBuddy 的技能目录：\n- Windows：`C:\\Users\\你的用户名\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux：`~/.workbuddy/skills/Unified-Research-Finder/`\n\n（你也可以直接把仓库里的 `Unified-Research-Finder` 文件夹复制过去。）\n\n**第二步：开始用**\n在 WorkBuddy 对话框里直接说人话就行，例如：\n- 「帮我找 CRISPR 基因编辑 的最新文献」\n- 「在 PubMed 上搜 二甲双胍 和 2 型糖尿病」\n- 「用灯塔学术查 大语言模型 综述」\n\n技能会自动同时检索两库、合并去重，并告诉你「已开启多库去重，可手动关闭」。\n如果你不想去重，说一句「不用去重」，它会保留重复项。\n\n> 进阶（可选）：脚本是纯 Python 标准库写的，装好 Python 3.8+ 即可直接在命令行跑：\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**项目结构 / Project Structure：**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # 技能说明（触发词、检索流程、输出模板）\n├── LICENSE # MIT-0 开源协议\n├── README.md # 本说明文件（中英双语）\n├── .gitignore # 忽略 Python 缓存等无关文件\n├── scripts/\n│ ├── unified_search.py # 双库合并去重入口（默认推荐）\n│ ├── pubmed_search.py # PubMed 官方 API 检索\n│ └── scholar_search.py # Google Scholar 及镜像站检索\n└── references/\n ├── scholar-sources.md # 四个 Scholar 源的技术细节\n ├── pubmed-query-syntax.md # PubMed 检索语法\n └── register-api-key.md # 免费注册 NCBI API key 引导\n```\n\n（运行时自动生成的 `__pycache__` 等缓存已被 `.gitignore` 排除，不会进入仓库。）\n\n## 3. 技术原理\n\n- **纯标准库、零依赖**：所有脚本只用 Python 自带模块（`urllib` / `json` / `re` / `subprocess`），无需 `pip install`，启动快、内存低。\n- **PubMed**：直接调用 NCBI 官方 `esearch` + `efetch` 接口，拿到结构化 JSON（PMID、标题、作者、期刊、摘要、DOI），真实可验证。\n- **Scholar 多源回退**：优先用「灯塔学术」的 JSON API（最快最省内存）；若被限流，自动退回「烂番薯」服务端渲染 HTML（带 Referer 解析）；再不行试香港镜像与官方站。任一源被拦截（403 / 验证码 / 超时）即跳下一源。\n- **跨库合并去重**：`unified_search.py` 用子进程并行调用上面两个脚本，把结果统一字段后，以 **DOI 或归一化标题** 为键去重——同一篇论文在 PubMed 和 Scholar 都出现时只保留一条。\n- **浏览器兜底（可选）**：当所有 HTTP 方式都被拦，可装 Playwright 用 `--browser` 模式做无头渲染；该模式较重，仅按需启用，不常驻。\n\n## 4. 致谢\n\n本技能最初是作为 [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder) 的升级案例而构思的。`paper-finder` 提供了「只返回真实文献、绝不编造」的优良第一原则，以及清晰的技能结构范式，本项目的 PubMed 网页检索思路也受其启发。在此对 `paper-finder` 的作者表达诚挚感谢。\n\n---\n\n# English\n\n## 1. Introduction\n\n**Unified-Research-Finder** is an all-in-one academic literature search skill for WorkBuddy / SkillHub-compatible agents. It unifies two of the most-used scholarly search engines:\n\n- **PubMed** (the authoritative biomedical database) — powered by the official NCBI E-utilities API, returning real PMIDs, abstracts, and DOIs.\n- **Google Scholar and its mirrors** — covering \"灯塔学术 (Dotaindex)\", \"烂番薯学术 (Lanfanshu)\", the Google Scholar Hong Kong mirror, and the official Google Scholar site, with automatic fallback by stability.\n\nCross-database **merge + deduplication (PubMed + Scholar) is on by default**: the same paper never appears twice. Every result comes from a real network response — **if nothing is found, we say so; we never fabricate.**\n\n## 2. Install & Use\n\n> Plain-English version for non-technical users: don't panic, you don't need to know any coding.\n\n**Step 1 — Get the files**\nDownload this repository (the `Unified-Research-Finder` folder) and drop it into your WorkBuddy skills directory:\n- Windows: `C:\\Users\\YourName\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux: `~/.workbuddy/skills/Unified-Research-Finder/`\n\n(You can simply copy the `Unified-Research-Finder` folder from the repo.)\n\n**Step 2 — Start using**\nJust talk to WorkBuddy in plain language, e.g.:\n- \"Find me the latest papers on CRISPR gene editing\"\n- \"Search PubMed for metformin and type 2 diabetes\"\n- \"Use Dotaindex to look up large language model surveys\"\n\nThe skill searches both databases, merges and deduplicates, and tells you \"cross-database deduplication is on; you can turn it off.\" If you don't want deduplication, just say so and it keeps the duplicates.\n\n> Advanced (optional): the scripts use only the Python standard library. With Python 3.8+ you can run them directly from the command line:\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**Project Structure:**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # Skill manifest (triggers, search flows, output templates)\n├── LICENSE # MIT-0 license\n├── README.md # This file (bilingual)\n├── .gitignore # Excludes Python caches and unrelated files\n├── scripts/\n│ ├── unified_search.py # Dual-database merge + dedup entry point (recommended)\n│ ├── pubmed_search.py # PubMed official API search\n│ └── scholar_search.py # Google Scholar & mirrors search\n└── references/\n ├── scholar-sources.md # Technical details of the four Scholar sources\n ├── pubmed-query-syntax.md # PubMed query syntax\n └── register-api-key.md # Guide to register a free NCBI API key\n```\n\n(Runtime-generated caches such as `__pycache__` are excluded by `.gitignore` and never enter the repository.)\n\n## 3. How It Works\n\n- **Standard library only, zero dependencies**: every script uses only Python built-ins (`urllib` / `json` / `re` / `subprocess`) — no `pip install` needed; fast startup, low memory.\n- **PubMed**: calls the official NCBI `esearch` + `efetch` endpoints and gets structured JSON (PMID, title, authors, journal, abstract, DOI) — verifiable and real.\n- **Scholar multi-source fallback**: prefers the \"Dotaindex\" JSON API (fastest, lowest memory); if rate-limited, falls back to \"Lanfanshu\" server-rendered HTML (parsed with a `Referer` header); then the HK mirror and the official site. Any blocked source (403 / CAPTCHA / timeout) triggers the next one.\n- **Cross-database merge + dedup**: `unified_search.py` invokes the two scripts as subprocesses, normalizes their fields, then deduplicates by **DOI or normalized title** — so a paper present in both PubMed and Scholar is kept only once.\n- **Browser fallback (optional)**: when every HTTP path is blocked, install Playwright and use `--browser` for headless rendering; this mode is heavy and only used on demand, never resident.\n\n## 4. Acknowledgements\n\nThis skill was originally conceived as an upgraded case study of [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder). `paper-finder` established the excellent first principle of \"return only real literature, never fabricate\" and a clean skill structure; its approach to PubMed web search was also an inspiration. Sincere thanks to the author of `paper-finder`.\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn71cn3h6s4p3eq2qpvbnxq1k98b1r7b\",\n \"slug\": \"unified-research-finder\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1784890230539\n}\n\nFile v1.1.0:references/pubmed-query-syntax.md\n\n# PubMed 检索语法速查\n\n构造 `--query` 参数时使用。PubMed 支持完整的布尔检索与字段限定。\n\n## 布尔运算\n\n- `AND`、`OR`、`NOT` 必须**大写**\n- 默认多个词之间按 `AND` 处理（自动术语映射可能介入）\n- 括号控制优先级：`(a OR b) AND c`\n\n## 常用字段标签\n\n| 标签 | 含义 | 示例 |\n|------|------|------|\n| `[MeSH Terms]` / `[mh]` | MeSH 主题词 | `\"Diabetes Mellitus, Type 2\"[MeSH Terms]` |\n| `[Title]` / `[ti]` | 标题 | `metformin[Title]` |\n| `[Title/Abstract]` / `[tiab]` | 标题或摘要 | `semaglutide[tiab]` |\n| `[Author]` / `[au]` | 作者 | `Smith J[Author]` |\n| `[Journal]` / `[jour]` | 期刊 | `\"N Engl J Med\"[Journal]` |\n| `[pdat]` | 发表日期 | `2023:2025[pdat]` |\n| `[Publication Type]` / `[pt]` | 文献类型 | `randomized controlled trial[pt]` |\n| `[la]` | 语言 | `english[la]` |\n| `[free full text]` | 免费全文过滤 | `... AND free full text[Filter]` |\n\n## 常用文献类型 `[pt]`\n\n- `randomized controlled trial[pt]` — RCT\n- `systematic review[pt]` — 系统综述\n- `meta-analysis[pt]` — Meta 分析\n- `review[pt]` — 综述\n- `clinical trial[pt]` — 临床试验\n- `case reports[pt]` — 病例报告\n\n## 日期限定（两种方式）\n\n1. 查询内：`\"covid-19\"[mh] AND 2022:2025[pdat]`\n2. 脚本参数（更推荐）：`--mindate 2022/01/01 --maxdate 2025/12/31`\n\n## 短语检索\n\n- 双引号锁定短语，禁用自动术语映射：`\"blood pressure\"` \n- 截词：`*`（至少 4 个字符后），如 `diabet*`\n\n## 典型查询示例\n\n```\n# 某药治疗某病的 RCT\nsemaglutide[tiab] AND \"Obesity\"[MeSH Terms] AND randomized controlled trial[pt]\n\n# 某作者在某期刊的文章\nWang Y[Author] AND \"Lancet\"[Journal]\n\n# 近 5 年系统综述\n\"Alzheimer Disease\"[MeSH Terms] AND systematic review[pt] AND 2020:2025[pdat]\n\n# 标题含某关键词、英文、有免费全文\nmetformin[Title] AND english[la] AND free full text[Filter]\n```\n\n## 排序说明\n\n- `--sort relevance`（默认）：相关性，适合\"最重要的几篇\"\n- `--sort pub_date`：按发表日期倒序，适合\"最新的几篇\"\n\nFile v1.1.0:references/register-api-key.md\n\n# 小白指南：注册 NCBI 账户并获取免费的 PubMed API Key\n\n> 这个技能**不申请 key 也能用**。只有当你需要\"一次查很多篇\"或\"查得快一点\"时，才需要做下面这一步。\n> 全程免费，不用绑卡、不用付费，5 分钟左右搞定。\n\n## 一、先确认：你到底需不需要？\n\n| 你的使用场景 | 需要申请吗 |\n|------|------|\n| 平时每次查几篇文献（≤20 篇） | 不需要，直接能用 |\n| 想一次抓取几十上百篇、或写批量脚本 | 需要，能明显提速 |\n| 搜索时偶尔报错\"访问太频繁\" | 需要，能避免被限流 |\n\n## 二、第一步：注册一个 NCBI 账户（没有就先注册）\n\n1. 打开网站：\n2. 点 **Register for an NCBI account**（注册账户）。\n3. 可以用**邮箱**注册，也可以直接用 **Google / Microsoft 账号**一键登录（最省事）。\n4. 按提示填邮箱、设密码，收一封验证邮件点链接确认。\n5. 注册完成，记住这个账号即可。\n\n> 小提示：NCBI 是\"美国国立生物技术信息中心\"，PubMed 就是它家的数据库。注册它家账户不会给你发广告。\n\n## 三、第二步：生成一个 API Key（一次性操作）\n\n1. 登录后打开：\n2. 找到 **API Key** 这一栏，点 **Create an API Key**（创建密钥）。\n3. 系统会给你一串类似这样的字符（举例）：\n ```\n 0123456789abcdef0123456789abcdef0123\n ```\n4. **复制保存好这串字符**（建议先贴在记事本里，后面用得到）。\n\n> 这就是你的\"API Key\"。它相当于你的专属通行码，能让你查文献的速度从每秒 3 次提升到每秒 10 次。\n\n## 四、第三步：把这个 Key 告诉本技能（两种方式任选）\n\n### 方式 A：临时用一次（在对话里说）\n直接在对话里告诉我：\n> \"用邮箱 me@example.com 和 API key 0123...ef 帮我查 XX\"\n\n我会把它作为本次命令的参数传给脚本（`--email` 和 `--api-key`）。\n\n### 方式 B：设成环境变量（一劳永逸，推荐）\n把 key 存到电脑的环境变量里，以后不用每次都说：\n\n- **Windows（PowerShell）**：\n ```powershell\n [System.Environment]::SetEnvironmentVariable(\"NCBI_API_KEY\", \"0123...ef\", \"User\")\n ```\n 设置后**重启一下 WorkBuddy** 让它读到新变量。\n- **macOS / Linux**：把下面这行加到 `~/.zshrc` 或 `~/.bashrc`，然后重开终端：\n ```bash\n export NCBI_API_KEY=\"0123...ef\"\n ```\n\n设好后，技能会自动使用它，你无需再手动提供。\n\n## 五、常见问题\n\n- **Key 会过期吗？** 一般不会自动过期，但你随时可以在设置页 **Delete** 后重新生成一个。\n- **Key 能给别人吗？** 不能。它绑定你的账户，相当于密码，别外传。\n- **邮箱填了干嘛？** NCBI 建议填，方便他们在接口出问题时联系你，纯属礼貌字段，不强制。\n- **还是看不懂？** 直接把报错或卡住的地方发给我，我一步步带你点。\n\nFile v1.1.0:references/scholar-sources.md\n\n# Scholar 数据源技术参考\n\n本文件供 WorkBuddy 在执行 `scholar_search.py` 时参考，说明四个数据源的\n请求方式、字段结构与兜底逻辑。**所有内容必须来自脚本真实返回，不得编造。**\n\n## 数据源与优先级\n\n`--source auto`（默认）按以下顺序依次尝试，取第一个返回可用结果的源：\n\n| 优先级 | key | 名称 | 类型 | 检索地址 |\n|--------|-------------|---------------------|------|-----------------------------------------------|\n| 1 | dotaindex | 灯塔学术搜索 | JSON | `https://www.dotaindex.com/api/scholar/search?q=...` |\n| 2 | lanfanshu | 烂番薯学术搜索 | HTML | `https://scholar.lanfanshu.cn/scholar?q=...` |\n| 3 | hk | Google Scholar 香港镜像 | HTML | `https://scholar.google.com.hk/scholar?q=...` |\n| 4 | google | Google Scholar 官方站 | HTML | `https://scholar.google.com/scholar?q=...` |\n\n用户也可用 `--source lanfanshu|dotaindex|hk|google` 强制指定单一源。\n\n## 公共检索参数\n\n脚本统一将以下参数拼入 URL：\n\n- `q` — 检索词（必填）\n- `start` — 起始偏移，分页步长 10\n- `hl` — 界面语言，默认 `zh-CN`\n- `as_ylo` — 起始年份下限（`--ylo 2020`）\n- `scisbd=1` — 当 `--sort date` 时附加，表示按日期排序（相关性排序不加）\n\n## 灯塔（dotaindex）JSON API\n\n最稳、最快、内存占用最低，**优先使用**。\n\n- 端点：`GET https://www.dotaindex.com/api/scholar/search`\n- 请求头需带 `Referer: https://www.dotaindex.com/scholar` 与 `Accept: application/json`\n- 响应（顶层字典）：\n - `total` — 命中总数（用于 `count`）\n - `results[]` — 每篇文献，关键字段：\n - `titleHtml` — 含 `` 的标题，解析出 `url` 与标题文本\n - `author` — 作者串，如 `\"K Han, A Xiao, E Wu…\"`\n - `year` / `journal` / `publisher`\n - `abstractHtml` — 摘要片段（去标签）\n - `citationCount` — 被引次数（字符串数字）\n - `openAccessUrl` / `accessLinks[].url` — PDF 全文链接\n- 限流表现：被限流时返回 `results: []` 且 `total: 0`（而非报错）。脚本在首页空结果时退避 1.5s 重试一次。\n\n## 烂番薯 / 香港镜像 / 官方（经典 Scholar HTML）\n\n三者均为服务端渲染的经典 Google Scholar 结构，由同一个 HTML 解析器处理：\n\n- 结果容器：`
`（顺序无关，模糊匹配）\n- 标题/链接：`

标题

`\n- 作者·来源·年份：`
作者 - 期刊, 年份 - 出版方
`\n- 摘要片段：`
`（若该 class 缺失，则取 `gs_a` 与 `gs_fl` 之间的文本兜底）\n- 被引次数：`gs_fl` 内 `被引用次数 N` / `Cited by N` 等写法\n- PDF 链接：`[PDF]` 之后的 href，或 `gs_ggs` 区域内的 href\n\n**烂番薯特别说明**：需带 `Referer: https://scholar.lanfanshu.cn/`，否则返回 403。\n该站对高频请求会限流（403），脚本会自动回退到下一源。\n\n**香港镜像 / 官方站特别说明**：在中国大陆常被网络阻断（连接超时 / SSL 异常）。\n若 HTTP 方式失败，可让用户安装 Playwright 后以 `--browser` 模式用无头浏览器兜底。\n\n## 拦截 / 验证码检测\n\n- HTTP 403 / 429 → 记为「被拦截」，自动尝试下一源。\n- HTML 中出现 `unusual traffic` / `我们的系统检测到` / `captcha` / `why did this happen` 等标记 → 记为「被拦截」。\n- 全部源均无结果时，`ok` 置为 false（或 results 为空），并在 `note` 中说明原因，**绝不返回虚构文献**。\n\n## 性能与依赖\n\n- 默认纯标准库（`urllib`），**无需安装任何第三方包**，内存占用低、启动快。\n- `--browser` 模式依赖 Playwright（`pip install playwright && playwright install chromium`），\n 仅在 HTTP 被拦截且用户确认启用时作为兜底，避免常驻重进程。\n\nFile v1.1.0:CHANGELOG.md\n\n# 更新日志 / Changelog\n\n## [v1.1] — 2026-07-24\n\n### 🐛 Bug Fixes\n\n**#1 沙箱环境下 `unified_search.py` 被 SIGKILL（无任何输出）**\n\n- **现象**：在某些受约束的沙箱环境（如 operitAI、WorkBuddy sandbox）中运行 `unified_search.py` 时，进程直接被杀死，不产生 stdout/stderr 任何输出。\n- **根因**：旧版使用 `subprocess.run()` 串行执行 PubMed → Scholar。Scholar 需依次尝试 4 个源，每个源 HTTP 超时 25s，全程 2-3 分钟无任何 I/O。沙箱检测到进程长时间零输出后发送 SIGKILL，`print()` 永远走不到。\n- **修复**：\n - 两路子进程改用 `concurrent.futures.ThreadPoolExecutor` 并行启动。\n - Scholar 设独立 60s 超时上限（≈ 走完 2-3 个源），超时直接出部分结果，不阻塞输出。\n - 所有 `print()` 后追加 `sys.stdout.flush()`，确保管道/沙箱立刻看到 I/O。\n - 即使 Scholar 超时，PubMed 结果仍正常合并输出。\n\n**#2 operitAI 加载 skill 时三条启动报错**\n\n- **现象**：在 operitAI（Android）加载本 skill 时，控制台出现三条错误：\n 1. `tool_name must use packageName:toolName format`\n 2. `Tool not found: unified-research-finder:unified_search`\n 3. `Tool not found: unified-research-finder:terminal`\n- **根因**：operitAI 自动扫描 `scripts/` 目录，试图把每个 `.py` 文件按 `{skill_name}:{script_basename}` 格式注册为工具。由于 SKILL.md 缺少显式 `tools` 声明，注册格式校验失败，后续工具查找全部落空。\n- **修复**：在 SKILL.md frontmatter 中新增 `tools` 显式声明：\n ```yaml\n tools:\n - unified_search.py\n - pubmed_search.py\n - scholar_search.py\n ```\n\n### 📝 文档改进\n\n- README.md 项目结构段落地道化：去掉面向维护者的 \"你需要上传/发布\" 措辞，改为中性的「项目结构 / Project Structure」。\n- README.md 脚注去掉了 \"提交到 GitHub/SkillHub 时请上传整个文件夹\" 等维护者口吻，改为说明 `__pycache__` 已被 `.gitignore` 自动排除。\n\n---\n\n## [v1.0] — 2026-07-22\n\n### ✨ Initial Release\n\n- **PubMed 子系统**：基于 NCBI E-utilities 官方 API（`esearch` + `efetch`），返回真实 PMID/摘要/DOI。\n- **Scholar 多源回退**：覆盖灯塔（JSON API，最快最省内存）、烂番薯（HTML 服务端渲染）、Google Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港 → 官方」优先级自动回退。\n- **双库合并去重**（`unified_search.py`）：同时检索 PubMed + Scholar，以 DOI 或归一化标题为键去重，默认开启。\n- **纯标准库**：所有脚本仅用 Python 内置模块，无需 `pip install`，启动快、内存低。\n- **开源投稿文件**：MIT-0 License、中英双语 README.md、`.gitignore`。\n\nFile v1.1.0:skill-card.md\n\n## Description:
\nSearches PubMed and Google Scholar-compatible sources, merges and deduplicates literature results, and reports only results returned by the underlying services.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[georgechou17](https://clawhub.ai/user/georgechou17)
\n\n### License/Terms of Use:
\nMIT No Attribution
\n\n\n## Use Case:
\nExternal users, researchers, and developers use this skill to find scholarly literature across PubMed and Scholar-style sources, retrieve article links and identifiers, and avoid duplicate records across databases.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Research queries may be sent to PubMed and third-party Scholar mirror services.
\nMitigation: Avoid sensitive unpublished, patient-related, confidential, or proprietary search terms unless the user accepts that disclosure.
\nRisk: API keys may be exposed if pasted into chat.
\nMitigation: Use an environment variable or another secure secret mechanism for NCBI_API_KEY instead of sharing keys in the conversation.
\nRisk: Scholar mirrors and external services may be rate-limited, blocked, unavailable, or return partial results.
\nMitigation: Report source failures honestly, retry later or with broader terms, and do not fabricate missing literature results.
\n\n\n## Reference(s):
\n- [ClawHub release page](https://clawhub.ai/georgechou17/skills/unified-research-finder)
\n- [Scholar data source reference](references/scholar-sources.md)
\n- [PubMed query syntax reference](references/pubmed-query-syntax.md)
\n- [NCBI API key registration guide](references/register-api-key.md)
\n- [NCBI account signup](https://account.ncbi.nlm.nih.gov/signup/)
\n- [NCBI account settings](https://www.ncbi.nlm.nih.gov/account/settings/)
\n- [Dotaindex Scholar API](https://www.dotaindex.com/api/scholar/search)
\n- [Dotaindex Scholar](https://www.dotaindex.com/scholar)
\n- [Lanfanshu Scholar](https://scholar.lanfanshu.cn/)
\n- [Google Scholar Hong Kong](https://scholar.google.com.hk/scholar?q=...)
\n- [Google Scholar](https://scholar.google.com/scholar?q=...)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, JSON, Shell commands, Configuration instructions, Guidance]
\n**Output Format:** [Markdown reports with optional shell commands and JSON returned from helper scripts]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May include article metadata, links, DOI and PMID fields, deduplication counts, and guidance for handling API keys.]
\n\n## Skill Version(s):
\n1.1.0 (source: server release metadata; SKILL.md frontmatter reports v1.1)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.1.0:LICENSE\n\nMIT No Attribution\n\nCopyright 2026 GeorgeChou17\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nArchive v0.1.0: 12 files, 30028 bytes\n\nFiles: LICENSE (907b), README.md (9122b), references (0b), references/pubmed-query-syntax.md (2113b), references/register-api-key.md (3050b), references/scholar-sources.md (4060b), scripts (0b), scripts/pubmed_search.py (11904b), scripts/scholar_search.py (15928b), scripts/unified_search.py (8272b), SKILL.md (10246b), _meta.json (142b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: unified-research-finder\ndescription: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实\n PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google\n Scholar 香港镜像、Google Scholar 官方站，按「灯塔 → 烂番薯 → 香港镜像 → 官方」优先级自动回退（灯塔走 JSON API\n 最省内存最快）。当用户要找文献、查论文、搜 PubMed、查 Google\n 学术/谷歌学术、用学术镜像站、要影响因子或引用数据时启用。找不到就是找不到，绝不编造。\nagent_created: true\ntriggers:\n - 找文献\n - 检索论文\n - 搜索文献\n - 查论文\n - 查 PubMed\n - PubMed 检索\n - 医学文献\n - Google 学术\n - 谷歌学术\n - 学术搜索\n - 学术镜像\n - 烂番薯\n - 灯塔学术\n - 查影响因子\n - 论文引用\n - 相关论文\n - 推荐文献\n - 双库检索\n - 合并去重\n - 跨库检索\n - 多库去重\ndisable: false\n---\n\n# 学术文献检索助手 (Unified Research Finder)\n\n## ⚠️ 第一原则：真实、可验证，绝不编造\n\n- ✅ 只返回脚本真实返回的文献（PubMed API / Scholar 镜像真实响应）。\n- ✅ 明确标注「未找到」当检索无果或所有源被拦截。\n- ✅ 提供可点击的链接（PubMed / DOI / 原文 / PDF）。\n- ❌ 绝不生成虚假标题、作者、PMID、引用数或下载链接。\n- ❌ 网络不通或源被拦截时，如实说明，不臆造结果。\n\n## 🔁 默认行为：PubMed + Scholar 多库合并去重（默认开启）\n\n- **默认同时检索两大库**：PubMed（官方 E-utilities API）+ Google Scholar 及镜像站（灯塔 JSON 优先），再合并。\n- **默认开启跨库去重**：以 DOI 或归一化标题为键，剔除 PubMed 与 Scholar 之间的重复文献（同一篇论文不会重复出现）。\n- **⚠️ 每次查找，必须明确告知用户**：「已开启多库去重，可手动关闭」（即 `unified_search.py` 输出里的 `dedup_note`）。\n- **用户要求不去重时**：改用 `unified_search.py --no-dedup`（仍同时检索两库，但保留重复项）；或直接走流程 A / 流程 B 的单库检索。\n- 入口脚本：`scripts/unified_search.py`（详见下方「流程 C」）。\n\n## 何时使用本技能\n\n- 用户要找某主题 / 篇名 / 作者 / 关键词的文献。\n- 用户要查 PubMed（医学、生物、生物医学预印本）。\n- 用户要查 Google Scholar、谷歌学术，或点名「烂番薯 / 灯塔 / 香港镜像 / 官方站」。\n- 用户要影响因子、被引次数、PDF 全文链接、DOI。\n\n## 两大子系统与脚本\n\n| 子系统 | 脚本 | 说明 |\n|--------|------|------|\n| **PubMed（API + 网页）** | `scripts/pubmed_search.py` | 基于 NCBI E-utilities 官方 API，仅用标准库，无需装包。 |\n| **Google Scholar + 镜像** | `scripts/scholar_search.py` | 自动按优先级检索 4 个源，纯标准库；可选 Playwright 兜底。 |\n| **双库合并去重（默认）** | `scripts/unified_search.py` | 同时检索 PubMed + Scholar，合并并按 DOI/标题去重；`--no-dedup` 可关。 |\n\n参考文档：`references/scholar-sources.md`（四源技术细节）、\n`references/pubmed-query-syntax.md`（PubMed 检索语法）、\n`references/register-api-key.md`（NCBI API key 注册引导）。\n\n---\n\n## 流程 A：PubMed 检索（医学 / 生物 / 影响因子）\n\n适用于：医学、生物医学、生命科学，或用户明确提到 PubMed / PMID / DOI / 影响因子。\n\n1. **构造检索式**：将自然语言转为 PubMed 查询。需要复杂式（MeSH、字段、文献类型、日期）时，先读 `references/pubmed-query-syntax.md`。\n - 「最新研究」→ 加 `--sort pub_date`\n - 「最相关 / 权威」→ 默认 `--sort relevance`\n - 「RCT / 系统综述 / Meta」→ 查询串加 `randomized controlled trial[pt]` 等\n - 未指定篇数 → 默认 `--retmax 5`\n - 用户直接给 PMID → 用 `--pmids` 模式\n2. **运行脚本**：\n ```bash\n # 关键词检索（esearch → efetch 自动串联）\n python scripts/pubmed_search.py --query \"metformin AND type 2 diabetes\" --retmax 5\n # 限定年份 + 按日期排序\n python scripts/pubmed_search.py --query \"semaglutide[tiab] AND obesity[mh]\" --sort pub_date --mindate 2023/01/01 --retmax 5\n # 直接按 PMID 获取\n python scripts/pubmed_search.py --pmids 36967777 37397787\n ```\n 脚本向 stdout 输出 JSON：`{ok, query, count, pmids, articles[]}`。每篇含 `pmid, title, authors[], journal, pubdate, abstract, doi, doi_url, pubmed_url`。\n3. **整理为中文报告**（遵循 `references/` 中的模板）：标题（附中文翻译）、作者、期刊、日期、PMID、DOI、摘要中文概述、原文摘要折叠块。\n4. **API key 引导**：当脚本输出 `api_key_hint: true`（批量或限流），读取 `references/register-api-key.md` 并用大白话引导用户注册免费 NCBI API key。key 仅作命令参数 / 环境变量 `NCBI_API_KEY`，不写入文件。\n\n> 网络不通 `eutils.ncbi.nlm.nih.gov` 时如实告知，不编造。纯网页版 PubMed 检索可用浏览器访问 `pubmed.ncbi.nlm.nih.gov` 作为补充。\n\n---\n\n## 流程 B：Google Scholar 及镜像站检索\n\n适用于：全学科文献、引用数据、PDF 全文、用户点名 Scholar / 谷歌学术 / 镜像站。\n\n1. **运行脚本**（默认 auto，按优先级自动回退）：\n ```bash\n # 自动：灯塔 → 烂番薯 → 香港镜像 → 官方站，取首个有结果的源\n python scripts/scholar_search.py --query \"large language model survey\" --num 10\n # 指定单一源（如用户只要灯塔）\n python scripts/scholar_search.py --query \"...\" --source dotaindex\n # 按日期排序 + 限 2020 年以来\n python scripts/scholar_search.py --query \"...\" --sort date --ylo 2020\n # 分页 / 偏移\n python scripts/scholar_search.py --query \"...\" --num 20 --start 0\n ```\n 输出 JSON：`{ok, source, query, count, results[], note}`。每篇结果含\n `title, url, authors, year, venue, snippet, citations, pdf_url`。\n2. **源优先级与回退**（默认 auto 行为）：\n - **灯塔**（dotaindex）优先——走 JSON API，最快最稳、内存占用最低，作为主力首选源。\n - **烂番薯**（lanfanshu）次之——大陆直连、服务端渲染，需带 Referer，高频会 403 限流。\n - **香港镜像**（scholar.google.com.hk）再次——经典 HTML，大陆常被网络阻断。\n - **官方站**（scholar.google.com）最后——经典 HTML，大陆常被网络阻断。\n - 任一源被拦截（403/验证码/超时）自动尝试下一源；全部失败则在 `note` 说明，**不返回虚构文献**。\n3. **浏览器兜底（可选）**：当所有 HTTP 尝试被拦截且用户需要，安装 Playwright 后以 `--browser` 模式启动无头浏览器渲染：\n ```bash\n pip install playwright && playwright install chromium\n python scripts/scholar_search.py --query \"...\" --browser\n ```\n 仅 HTML 源启用浏览器；灯塔 JSON 无需浏览器。此模式较重，按需使用以节省资源。\n4. **整理为中文报告**：逐篇列出 标题、作者、年份、来源(vision)、摘要片段、被引次数、链接（原文 + PDF 全文若有）。\n\n> 设计取舍：默认纯标准库 HTTP，启动快、内存低；Playwright 仅作被拦截时的兜底，避免常驻重进程。详见 `references/scholar-sources.md`。\n\n---\n\n## 流程 C：双库合并去重检索（默认推荐）\n\n适用于绝大多数场景：用户只说「帮我找 XX 的文献」「搜一下 XX」，未限定只用某一库。\n\n1. **运行入口脚本**（默认即开启跨库去重）：\n ```bash\n # 同时检索 PubMed + Scholar，合并并按 DOI / 归一化标题去重（默认）\n python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n # 按日期排序 + 限 2022 以来\n python scripts/unified_search.py --query \"...\" --sort date --ylo 2022\n # 用户要求不去重时（仍同时检索两库，保留重复项）\n python scripts/unified_search.py --query \"...\" --no-dedup\n ```\n 输出 JSON：`{ok, query, dedup_enabled, dedup_note, pubmed_count, scholar_count,\n merged_count, deduped_count, removed_count, pubmed{}, scholar{}, results[]}`。\n 每条统一记录含 `db(pubmed|scholar), title, authors, year, venue, snippet, citations,\n url, pdf_url, doi, doi_url, pmid, pubmed_url`。\n2. **⚠️ 必须告知用户**：无论结果多少，先说一句\n **「已开启多库去重，可手动关闭」**（即输出里的 `dedup_note`）。\n 用户若说「不用去重 / 关掉去重」，则用 `--no-dedup` 重跑。\n3. **整理为中文报告**：逐篇列出（用 `db` 字段标注来自 PubMed 还是 Scholar）：\n 标题、作者、年份、来源、摘要/片段、被引次数、链接（原文 + PDF/DOI + PubMed）。\n 去重计数可附注：「共合并 N 条，去重后 K 条（移除 R 条重复）」。\n4. **单库回退**：当用户明确只要 PubMed 或只要 Scholar 时，分别走流程 A / 流程 B。\n\n---\n\n## 输出格式\n\n### 找到文献时\n\n```\n📄 检索结果 [1/N]\n\n标题：{title}（{中文译名，如有}）\n作者：{authors}\n年份 / 来源：{year} · {venue}\n被引次数：{citations}（{source}）\n🔗 链接：\n- 原文：{url}\n- PDF：{pdf_url}（若有）\n📋 摘要：{snippet 或 PubMed 摘要中文概述}\n---\n```\n\n### 未找到 / 全部源被拦截时\n\n```\n❌ 未找到符合条件的文献 / 全部数据源暂不可达\n\n检索条件：{query}，年份≥{ylo}，排序={sort}\n已开启多库去重：是（--no-dedup 可关）\n尝试数据源：PubMed（官方 API）、灯塔、烂番薯、香港镜像、Google 官方\n结果：{note 中的具体原因，如「PubMed 可达但无命中；烂番薯与灯塔均触发限流，香港/官方站网络不可达」}\n建议：稍后重试；或换更宽泛关键词；或 installed Playwright 后用 --browser 模式。\n```\n\n## 相关技能 / 后续\n\n- 读文献、做摘要：可配合阅读类 skill。\n- 引用管理、影响因子核实：Crossref / JCR / 中科院分区。\n\nFile v0.1.0:README.md\n\n# Unified-Research-Finder\n\n**[简体中文](#简体中文) | [English](#english)**\n\n## 目录 / Table of Contents\n\n- [简体中文](#简体中文)\n - [1. 简介](#1-简介)\n - [2. 安装与使用](#2-安装与使用)\n - [3. 技术原理](#3-技术原理)\n - [4. 致谢](#4-致谢)\n- [English](#english)\n - [1. Introduction](#1-introduction)\n - [2. Install & Use](#2-install--use)\n - [3. How It Works](#3-how-it-works)\n - [4. Acknowledgements](#4-acknowledgements)\n\n---\n\n# 简体中文\n\n## 1. 简介\n\n**Unified-Research-Finder** 是一个用于 WorkBuddy / 兼容 SkillHub 的「学术文献一站式检索」技能。它把两套最常用的学术搜索引擎合二为一：\n\n- **PubMed**（生物医学权威数据库）——走官方 E-utilities API，返回真实 PMID、摘要、DOI。\n- **Google Scholar 及其镜像站**——覆盖「灯塔学术」「烂番薯学术」「Google Scholar 香港镜像」「Google Scholar 官方站」，按稳定性自动回退。\n\n默认开启 **PubMed + Scholar 跨库合并去重**：同一篇论文不会在两库里重复出现。所有结果均来自真实网络响应，**找不到就是找不到，绝不编造**。\n\n## 2. 安装与使用\n\n> 给电脑小白的话：别慌，这东西不需要你懂编程，跟着点就行。\n\n**第一步：拿到文件**\n把本仓库（文件夹 `Unified-Research-Finder`）整个下载下来，放到你电脑里 WorkBuddy 的技能目录：\n- Windows：`C:\\Users\\你的用户名\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux：`~/.workbuddy/skills/Unified-Research-Finder/`\n\n（你也可以直接把仓库里的 `Unified-Research-Finder` 文件夹复制过去。）\n\n**第二步：开始用**\n在 WorkBuddy 对话框里直接说人话就行，例如：\n- 「帮我找 CRISPR 基因编辑 的最新文献」\n- 「在 PubMed 上搜 二甲双胍 和 2 型糖尿病」\n- 「用灯塔学术查 大语言模型 综述」\n\n技能会自动同时检索两库、合并去重，并告诉你「已开启多库去重，可手动关闭」。\n如果你不想去重，说一句「不用去重」，它会保留重复项。\n\n> 进阶（可选）：脚本是纯 Python 标准库写的，装好 Python 3.8+ 即可直接在命令行跑：\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**项目结构 / Project Structure：**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # 技能说明（触发词、检索流程、输出模板）\n├── LICENSE # MIT-0 开源协议\n├── README.md # 本说明文件（中英双语）\n├── .gitignore # 忽略 Python 缓存等无关文件\n├── scripts/\n│ ├── unified_search.py # 双库合并去重入口（默认推荐）\n│ ├── pubmed_search.py # PubMed 官方 API 检索\n│ └── scholar_search.py # Google Scholar 及镜像站检索\n└── references/\n ├── scholar-sources.md # 四个 Scholar 源的技术细节\n ├── pubmed-query-syntax.md # PubMed 检索语法\n └── register-api-key.md # 免费注册 NCBI API key 引导\n```\n\n（运行时自动生成的 `__pycache__` 等缓存已被 `.gitignore` 排除，不会进入仓库。）\n\n## 3. 技术原理\n\n- **纯标准库、零依赖**：所有脚本只用 Python 自带模块（`urllib` / `json` / `re` / `subprocess`），无需 `pip install`，启动快、内存低。\n- **PubMed**：直接调用 NCBI 官方 `esearch` + `efetch` 接口，拿到结构化 JSON（PMID、标题、作者、期刊、摘要、DOI），真实可验证。\n- **Scholar 多源回退**：优先用「灯塔学术」的 JSON API（最快最省内存）；若被限流，自动退回「烂番薯」服务端渲染 HTML（带 Referer 解析）；再不行试香港镜像与官方站。任一源被拦截（403 / 验证码 / 超时）即跳下一源。\n- **跨库合并去重**：`unified_search.py` 用子进程并行调用上面两个脚本，把结果统一字段后，以 **DOI 或归一化标题** 为键去重——同一篇论文在 PubMed 和 Scholar 都出现时只保留一条。\n- **浏览器兜底（可选）**：当所有 HTTP 方式都被拦，可装 Playwright 用 `--browser` 模式做无头渲染；该模式较重，仅按需启用，不常驻。\n\n## 4. 致谢\n\n本技能最初是作为 [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder) 的升级案例而构思的。`paper-finder` 提供了「只返回真实文献、绝不编造」的优良第一原则，以及清晰的技能结构范式，本项目的 PubMed 网页检索思路也受其启发。在此对 `paper-finder` 的作者表达诚挚感谢。\n\n---\n\n# English\n\n## 1. Introduction\n\n**Unified-Research-Finder** is an all-in-one academic literature search skill for WorkBuddy / SkillHub-compatible agents. It unifies two of the most-used scholarly search engines:\n\n- **PubMed** (the authoritative biomedical database) — powered by the official NCBI E-utilities API, returning real PMIDs, abstracts, and DOIs.\n- **Google Scholar and its mirrors** — covering \"灯塔学术 (Dotaindex)\", \"烂番薯学术 (Lanfanshu)\", the Google Scholar Hong Kong mirror, and the official Google Scholar site, with automatic fallback by stability.\n\nCross-database **merge + deduplication (PubMed + Scholar) is on by default**: the same paper never appears twice. Every result comes from a real network response — **if nothing is found, we say so; we never fabricate.**\n\n## 2. Install & Use\n\n> Plain-English version for non-technical users: don't panic, you don't need to know any coding.\n\n**Step 1 — Get the files**\nDownload this repository (the `Unified-Research-Finder` folder) and drop it into your WorkBuddy skills directory:\n- Windows: `C:\\Users\\YourName\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux: `~/.workbuddy/skills/Unified-Research-Finder/`\n\n(You can simply copy the `Unified-Research-Finder` folder from the repo.)\n\n**Step 2 — Start using**\nJust talk to WorkBuddy in plain language, e.g.:\n- \"Find me the latest papers on CRISPR gene editing\"\n- \"Search PubMed for metformin and type 2 diabetes\"\n- \"Use Dotaindex to look up large language model surveys\"\n\nThe skill searches both databases, merges and deduplicates, and tells you \"cross-database deduplication is on; you can turn it off.\" If you don't want deduplication, just say so and it keeps the duplicates.\n\n> Advanced (optional): the scripts use only the Python standard library. With Python 3.8+ you can run them directly from the command line:\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**Project Structure:**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # Skill manifest (triggers, search flows, output templates)\n├── LICENSE # MIT-0 license\n├── README.md # This file (bilingual)\n├── .gitignore # Excludes Python caches and unrelated files\n├── scripts/\n│ ├── unified_search.py # Dual-database merge + dedup entry point (recommended)\n│ ├── pubmed_search.py # PubMed official API search\n│ └── scholar_search.py # Google Scholar & mirrors search\n└── references/\n ├── scholar-sources.md # Technical details of the four Scholar sources\n ├── pubmed-query-syntax.md # PubMed query syntax\n └── register-api-key.md # Guide to register a free NCBI API key\n```\n\n(Runtime-generated caches such as `__pycache__` are excluded by `.gitignore` and never enter the repository.)\n\n## 3. How It Works\n\n- **Standard library only, zero dependencies**: every script uses only Python built-ins (`urllib` / `json` / `re` / `subprocess`) — no `pip install` needed; fast startup, low memory.\n- **PubMed**: calls the official NCBI `esearch` + `efetch` endpoints and gets structured JSON (PMID, title, authors, journal, abstract, DOI) — verifiable and real.\n- **Scholar multi-source fallback**: prefers the \"Dotaindex\" JSON API (fastest, lowest memory); if rate-limited, falls back to \"Lanfanshu\" server-rendered HTML (parsed with a `Referer` header); then the HK mirror and the official site. Any blocked source (403 / CAPTCHA / timeout) triggers the next one.\n- **Cross-database merge + dedup**: `unified_search.py` invokes the two scripts as subprocesses, normalizes their fields, then deduplicates by **DOI or normalized title** — so a paper present in both PubMed and Scholar is kept only once.\n- **Browser fallback (optional)**: when every HTTP path is blocked, install Playwright and use `--browser` for headless rendering; this mode is heavy and only used on demand, never resident.\n\n## 4. Acknowledgements\n\nThis skill was originally conceived as an upgraded case study of [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder). `paper-finder` established the excellent first principle of \"return only real literature, never fabricate\" and a clean skill structure; its approach to PubMed web search was also an inspiration. Sincere thanks to the author of `paper-finder`.\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn71cn3h6s4p3eq2qpvbnxq1k98b1r7b\",\n \"slug\": \"unified-research-finder\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1784693259232\n}\n\nFile v0.1.0:references/pubmed-query-syntax.md\n\n# PubMed 检索语法速查\n\n构造 `--query` 参数时使用。PubMed 支持完整的布尔检索与字段限定。\n\n## 布尔运算\n\n- `AND`、`OR`、`NOT` 必须**大写**\n- 默认多个词之间按 `AND` 处理（自动术语映射可能介入）\n- 括号控制优先级：`(a OR b) AND c`\n\n## 常用字段标签\n\n| 标签 | 含义 | 示例 |\n|------|------|------|\n| `[MeSH Terms]` / `[mh]` | MeSH 主题词 | `\"Diabetes Mellitus, Type 2\"[MeSH Terms]` |\n| `[Title]` / `[ti]` | 标题 | `metformin[Title]` |\n| `[Title/Abstract]` / `[tiab]` | 标题或摘要 | `semaglutide[tiab]` |\n| `[Author]` / `[au]` | 作者 | `Smith J[Author]` |\n| `[Journal]` / `[jour]` | 期刊 | `\"N Engl J Med\"[Journal]` |\n| `[pdat]` | 发表日期 | `2023:2025[pdat]` |\n| `[Publication Type]` / `[pt]` | 文献类型 | `randomized controlled trial[pt]` |\n| `[la]` | 语言 | `english[la]` |\n| `[free full text]` | 免费全文过滤 | `... AND free full text[Filter]` |\n\n## 常用文献类型 `[pt]`\n\n- `randomized controlled trial[pt]` — RCT\n- `systematic review[pt]` — 系统综述\n- `meta-analysis[pt]` — Meta 分析\n- `review[pt]` — 综述\n- `clinical trial[pt]` — 临床试验\n- `case reports[pt]` — 病例报告\n\n## 日期限定（两种方式）\n\n1. 查询内：`\"covid-19\"[mh] AND 2022:2025[pdat]`\n2. 脚本参数（更推荐）：`--mindate 2022/01/01 --maxdate 2025/12/31`\n\n## 短语检索\n\n- 双引号锁定短语，禁用自动术语映射：`\"blood pressure\"` \n- 截词：`*`（至少 4 个字符后），如 `diabet*`\n\n## 典型查询示例\n\n```\n# 某药治疗某病的 RCT\nsemaglutide[tiab] AND \"Obesity\"[MeSH Terms] AND randomized controlled trial[pt]\n\n# 某作者在某期刊的文章\nWang Y[Author] AND \"Lancet\"[Journal]\n\n# 近 5 年系统综述\n\"Alzheimer Disease\"[MeSH Terms] AND systematic review[pt] AND 2020:2025[pdat]\n\n# 标题含某关键词、英文、有免费全文\nmetformin[Title] AND english[la] AND free full text[Filter]\n```\n\n## 排序说明\n\n- `--sort relevance`（默认）：相关性，适合\"最重要的几篇\"\n- `--sort pub_date`：按发表日期倒序，适合\"最新的几篇\"\n\nFile v0.1.0:references/register-api-key.md\n\n# 小白指南：注册 NCBI 账户并获取免费的 PubMed API Key\n\n> 这个技能**不申请 key 也能用**。只有当你需要\"一次查很多篇\"或\"查得快一点\"时，才需要做下面这一步。\n> 全程免费，不用绑卡、不用付费，5 分钟左右搞定。\n\n## 一、先确认：你到底需不需要？\n\n| 你的使用场景 | 需要申请吗 |\n|------|------|\n| 平时每次查几篇文献（≤20 篇） | 不需要，直接能用 |\n| 想一次抓取几十上百篇、或写批量脚本 | 需要，能明显提速 |\n| 搜索时偶尔报错\"访问太频繁\" | 需要，能避免被限流 |\n\n## 二、第一步：注册一个 NCBI 账户（没有就先注册）\n\n1. 打开网站：\n2. 点 **Register for an NCBI account**（注册账户）。\n3. 可以用**邮箱**注册，也可以直接用 **Google / Microsoft 账号**一键登录（最省事）。\n4. 按提示填邮箱、设密码，收一封验证邮件点链接确认。\n5. 注册完成，记住这个账号即可。\n\n> 小提示：NCBI 是\"美国国立生物技术信息中心\"，PubMed 就是它家的数据库。注册它家账户不会给你发广告。\n\n## 三、第二步：生成一个 API Key（一次性操作）\n\n1. 登录后打开：\n2. 找到 **API Key** 这一栏，点 **Create an API Key**（创建密钥）。\n3. 系统会给你一串类似这样的字符（举例）：\n ```\n 0123456789abcdef0123456789abcdef0123\n ```\n4. **复制保存好这串字符**（建议先贴在记事本里，后面用得到）。\n\n> 这就是你的\"API Key\"。它相当于你的专属通行码，能让你查文献的速度从每秒 3 次提升到每秒 10 次。\n\n## 四、第三步：把这个 Key 告诉本技能（两种方式任选）\n\n### 方式 A：临时用一次（在对话里说）\n直接在对话里告诉我：\n> \"用邮箱 me@example.com 和 API key 0123...ef 帮我查 XX\"\n\n我会把它作为本次命令的参数传给脚本（`--email` 和 `--api-key`）。\n\n### 方式 B：设成环境变量（一劳永逸，推荐）\n把 key 存到电脑的环境变量里，以后不用每次都说：\n\n- **Windows（PowerShell）**：\n ```powershell\n [System.Environment]::SetEnvironmentVariable(\"NCBI_API_KEY\", \"0123...ef\", \"User\")\n ```\n 设置后**重启一下 WorkBuddy** 让它读到新变量。\n- **macOS / Linux**：把下面这行加到 `~/.zshrc` 或 `~/.bashrc`，然后重开终端：\n ```bash\n export NCBI_API_KEY=\"0123...ef\"\n ```\n\n设好后，技能会自动使用它，你无需再手动提供。\n\n## 五、常见问题\n\n- **Key 会过期吗？** 一般不会自动过期，但你随时可以在设置页 **Delete** 后重新生成一个。\n- **Key 能给别人吗？** 不能。它绑定你的账户，相当于密码，别外传。\n- **邮箱填了干嘛？** NCBI 建议填，方便他们在接口出问题时联系你，纯属礼貌字段，不强制。\n- **还是看不懂？** 直接把报错或卡住的地方发给我，我一步步带你点。\n\nFile v0.1.0:references/scholar-sources.md\n\n# Scholar 数据源技术参考\n\n本文件供 WorkBuddy 在执行 `scholar_search.py` 时参考，说明四个数据源的\n请求方式、字段结构与兜底逻辑。**所有内容必须来自脚本真实返回，不得编造。**\n\n## 数据源与优先级\n\n`--source auto`（默认）按以下顺序依次尝试，取第一个返回可用结果的源：\n\n| 优先级 | key | 名称 | 类型 | 检索地址 |\n|--------|-------------|---------------------|------|-----------------------------------------------|\n| 1 | dotaindex | 灯塔学术搜索 | JSON | `https://www.dotaindex.com/api/scholar/search?q=...` |\n| 2 | lanfanshu | 烂番薯学术搜索 | HTML | `https://scholar.lanfanshu.cn/scholar?q=...` |\n| 3 | hk | Google Scholar 香港镜像 | HTML | `https://scholar.google.com.hk/scholar?q=...` |\n| 4 | google | Google Scholar 官方站 | HTML | `https://scholar.google.com/scholar?q=...` |\n\n用户也可用 `--source lanfanshu|dotaindex|hk|google` 强制指定单一源。\n\n## 公共检索参数\n\n脚本统一将以下参数拼入 URL：\n\n- `q` — 检索词（必填）\n- `start` — 起始偏移，分页步长 10\n- `hl` — 界面语言，默认 `zh-CN`\n- `as_ylo` — 起始年份下限（`--ylo 2020`）\n- `scisbd=1` — 当 `--sort date` 时附加，表示按日期排序（相关性排序不加）\n\n## 灯塔（dotaindex）JSON API\n\n最稳、最快、内存占用最低，**优先使用**。\n\n- 端点：`GET https://www.dotaindex.com/api/scholar/search`\n- 请求头需带 `Referer: https://www.dotaindex.com/scholar` 与 `Accept: application/json`\n- 响应（顶层字典）：\n - `total` — 命中总数（用于 `count`）\n - `results[]` — 每篇文献，关键字段：\n - `titleHtml` — 含 `` 的标题，解析出 `url` 与标题文本\n - `author` — 作者串，如 `\"K Han, A Xiao, E Wu…\"`\n - `year` / `journal` / `publisher`\n - `abstractHtml` — 摘要片段（去标签）\n - `citationCount` — 被引次数（字符串数字）\n - `openAccessUrl` / `accessLinks[].url` — PDF 全文链接\n- 限流表现：被限流时返回 `results: []` 且 `total: 0`（而非报错）。脚本在首页空结果时退避 1.5s 重试一次。\n\n## 烂番薯 / 香港镜像 / 官方（经典 Scholar HTML）\n\n三者均为服务端渲染的经典 Google Scholar 结构，由同一个 HTML 解析器处理：\n\n- 结果容器：`
`（顺序无关，模糊匹配）\n- 标题/链接：`

标题

`\n- 作者·来源·年份：`
作者 - 期刊, 年份 - 出版方
`\n- 摘要片段：`
`（若该 class 缺失，则取 `gs_a` 与 `gs_fl` 之间的文本兜底）\n- 被引次数：`gs_fl` 内 `被引用次数 N` / `Cited by N` 等写法\n- PDF 链接：`[PDF]` 之后的 href，或 `gs_ggs` 区域内的 href\n\n**烂番薯特别说明**：需带 `Referer: https://scholar.lanfanshu.cn/`，否则返回 403。\n该站对高频请求会限流（403），脚本会自动回退到下一源。\n\n**香港镜像 / 官方站特别说明**：在中国大陆常被网络阻断（连接超时 / SSL 异常）。\n若 HTTP 方式失败，可让用户安装 Playwright 后以 `--browser` 模式用无头浏览器兜底。\n\n## 拦截 / 验证码检测\n\n- HTTP 403 / 429 → 记为「被拦截」，自动尝试下一源。\n- HTML 中出现 `unusual traffic` / `我们的系统检测到` / `captcha` / `why did this happen` 等标记 → 记为「被拦截」。\n- 全部源均无结果时，`ok` 置为 false（或 results 为空），并在 `note` 中说明原因，**绝不返回虚构文献**。\n\n## 性能与依赖\n\n- 默认纯标准库（`urllib`），**无需安装任何第三方包**，内存占用低、启动快。\n- `--browser` 模式依赖 Playwright（`pip install playwright && playwright install chromium`），\n 仅在 HTTP 被拦截且用户确认启用时作为兜底，避免常驻重进程。\n\nFile v0.1.0:LICENSE\n\nMIT No Attribution\n\nCopyright 2026 GeorgeChou17\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","readmeExcerpt":"Skill: Unified Research Finder Owner: georgechou17 Summary: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用 Tags: latest:1.1.1 Version history: v1.1.1 | 2026-07-24T14:","codeSnippets":[],"executableExamples":[{"language":"yaml","snippet":"tools:\n - unified_search.py\n - pubmed_search.py\n - scholar_search.py"},{"language":"bash","snippet":"# 关键词检索（esearch → efetch 自动串联）\n python scripts/pubmed_search.py --query \"metformin AND type 2 diabetes\" --retmax 5\n # 限定年份 + 按日期排序\n python scripts/pubmed_search.py --query \"semaglutide[tiab] AND obesity[mh]\" --sort pub_date --mindate 2023/01/01 --retmax 5\n # 直接按 PMID 获取\n python scripts/pubmed_search.py --pmids 36967777 37397787"},{"language":"bash","snippet":"# 自动：kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方，取首个有结果的源\n python scripts/scholar_search.py --query \"large language model survey\" --num 10\n # 指定单一源（如用户只要灯塔）\n python scripts/scholar_search.py --query \"...\" --source dotaindex\n # 按日期排序 + 限 2020 年以来\n python scripts/scholar_search.py --query \"...\" --sort date --ylo 2020\n # 分页 / 偏移\n python scripts/scholar_search.py --query \"...\" --num 20 --start 0"},{"language":"bash","snippet":"pip install playwright && playwright install chromium\n python scripts/scholar_search.py --query \"...\" --browser"},{"language":"bash","snippet":"# 同时检索 PubMed + Scholar，合并并按 DOI / 归一化标题去重（默认）\n python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n # 按日期排序 + 限 2022 以来\n python scripts/unified_search.py --query \"...\" --sort date --ylo 2022\n # 用户要求不去重时（仍同时检索两库，保留重复项）\n python scripts/unified_search.py --query \"...\" --no-dedup"},{"language":"text","snippet":"📄 检索结果 [1/N]\n\n标题：{title}（{中文译名，如有}）\n作者：{authors}\n年份 / 来源：{year} · {venue}\n被引次数：{citations}（{source}）\n🔗 链接：\n- 原文：{url}\n- PDF：{pdf_url}（若有）\n📋 摘要：{snippet 或 PubMed 摘要中文概述}\n---"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: unified-research-finder\ndescription: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实\n PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google\n Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google\n 学术/谷歌学术、用学术镜像站、要影响因子或引用数据时启用。找不到就是找不到，绝不编造。\nagent_created: true\nversion: v1.1.1\ntriggers:\n - 找文献\n - 检索论文\n - 搜索文献\n - 查论文\n - 查 PubMed\n - PubMed 检索\n - 医学文献\n - Google 学术\n - 谷歌学术\n - 学术搜索\n - 学术镜像\n - 烂番薯\n - 灯塔学术\n - KipHub\n - 学术搜索Pro\n - 查影响因子\n - 论文引用\n - 相关论文\n - 推荐文献\n - 双库检索\n - 合并去重\n - 跨库检索\n - 多库去重\ndisable: false\ntools:\n - unified_search\n - pubmed_search\n - scholar_search\n---\n\n# 学术文献检索助手 (Unified Research Finder)\n\n## ⚠️ 第一原则：真实、可验证，绝不编造\n\n- ✅ 只返回脚本真实返回的文献（PubMed API / Scholar 镜像真实响应）。\n- ✅ 明确标注「未找到」当检索无果或所有源被拦截。\n- ✅ 提供可点击的链接（PubMed / DOI / 原文 / PDF）。\n- ❌ 绝不生成虚假标题、作者、PMID、引用数或下载链接。\n- ❌ 网络不通或源被拦截时，如实说明，不臆造结果。\n\n## 🔁 默认行为：PubMed + Scholar 多库合并去重（默认开启）\n\n- **默认同时检索两大库**：PubMed（官方 E-utilities API）+ Google Scholar 及镜像站（灯塔 JSON 优先），再合并。\n- **默认开启跨库去重**：以 DOI 或归一化标题为键，剔除 PubMed 与 Scholar 之间的重复文献（同一篇论文不会重复出现）。\n- **⚠️ 每次查找，必须明确告知用户**：「已开启多库去重，可手动关闭」（即 `unified_search.py` 输出里的 `dedup_note`）。\n- **用户要求不去重时**：改用 `unified_search.py --no-dedup`（仍同时检索两库，但保留重复项）；或直接走流程 A / 流程 B 的单库检索。\n- 入口脚本：`scripts/unified_search.py`（详见下方「流程 C」）。\n\n## 何时使用本技能\n\n- 用户要找某主题 / 篇名 / 作者 / 关键词的文献。\n- 用户要查 PubMed（医学、生物、生物医学预印本）。\n- 用户要查 Google Scholar、谷歌学术，或点名「烂番薯 / 灯塔 / 香港镜像 / 官方站」。\n- 用户要影响因子、被引次数、PDF 全文链接、DOI。\n\n## 两大子系统与脚本\n\n| 子系统 | 脚本 | 说明 |\n|--------|------|------|\n| **PubMed（API + 网页）** | `scripts/pubmed_search.py` | 基于 NCBI E-utilities 官方 API，仅用标准库，无需装包。 |\n| **Google Scholar + 镜像** | `scripts/scholar_search.py` | 自动按优先级检索 4 个源，纯标准库；可选 Playwright 兜底。 |\n| **双库合并去重（默认）** | `scripts/unified_search.py` | 同时检索 PubMed + Scholar，合并并按 DOI/标题去重；`--no-dedup` 可关。 |\n\n参考文档：`references/scholar-sources.md`（四源技术细节）、\n`references/pubmed-query-syntax.md`（PubMed 检索语法）、\n`references/register-api-key.md`（NCBI API key 注册引导）。\n\n---\n\n## 流程 A：PubMed 检索（医学 / 生物 / 影响因子）\n\n适用于：医学、生物医学、生命科学，或用户明确提到 PubMed / PMID / DOI / 影响因子。\n\n1. **构造检索式**：将自然语言转为 PubMed 查询。需要复杂式（MeSH、字段、文献类型、日期）时，先读 `references/pubmed-query-syntax.md`。\n - 「最新研究」→ 加 `--sort pub_date`\n - 「最相关 / 权威」→ 默认 `--sort relevance`\n - 「RCT / 系统综述 / Meta」→ 查询串加 `randomized controlled trial[pt]` 等\n - 未指定篇数 → 默认 `--retmax 5`\n - 用户直接给 PMID → 用 `--pmids` 模式\n2. **运行脚本**：\n ```bash\n # 关键词检索（esearch → efetch 自动串联）\n python scripts/pubmed_search.py --query \"metformin AND type 2 diabetes\" --retmax 5\n # 限定年份 + 按日期排序\n python scripts/pubmed_search.py --query \"semaglutide[tiab] AND obesity[mh]\" --sort pub_date --mindate 2023/01/01 --retmax 5\n # 直接按 PMID 获取\n python scripts/pubmed_search.py --pmids 36967777 37397787\n ```\n 脚本向 stdout 输出 JSON：`{ok, query, count, pmids, articles[]}`。每篇含 `pmid, title, authors[], journal, pubdate, abstract, doi, doi_url, pubmed_url`。\n3. **整理为中文报告**（遵循 `references/` 中的模板）：标题（附中文翻译）、作者、期刊、日期"},{"path":"README.md","content":"# Unified-Research-Finder\n\n**[简体中文](#简体中文) | [English](#english)**\n\n## 目录 / Table of Contents\n\n- [简体中文](#简体中文)\n - [1. 简介](#1-简介)\n - [2. 安装与使用](#2-安装与使用)\n - [3. 技术原理](#3-技术原理)\n - [4. 致谢](#4-致谢)\n- [English](#english)\n - [1. Introduction](#1-introduction)\n - [2. Install & Use](#2-install--use)\n - [3. How It Works](#3-how-it-works)\n - [4. Acknowledgements](#4-acknowledgements)\n\n---\n\n# 简体中文\n\n## 1. 简介\n\n**Unified-Research-Finder** 是一个用于 WorkBuddy / 兼容 SkillHub 的「学术文献一站式检索」技能。它把两套最常用的学术搜索引擎合二为一：\n\n- **PubMed**（生物医学权威数据库）——走官方 E-utilities API，返回真实 PMID、摘要、DOI。\n- **Google Scholar 及其镜像站**——覆盖「KipHub学术」「烂番薯学术」「学术搜索Pro」「灯塔学术」「Google Scholar 香港镜像」「Google Scholar 官方站」**六个源**，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。\n\n默认开启 **PubMed + Scholar 跨库合并去重**：同一篇论文不会在两库里重复出现。所有结果均来自真实网络响应，**找不到就是找不到，绝不编造**。\n\n## 2. 安装与使用\n\n> 给电脑小白的话：别慌，这东西不需要你懂编程，跟着点就行。\n\n**第一步：拿到文件**\n把本仓库（文件夹 `Unified-Research-Finder`）整个下载下来，放到你电脑里 WorkBuddy 的技能目录：\n- Windows：`C:\\Users\\你的用户名\\.workbuddy\\skills\\Unified-Research-Finder\\`\n- macOS / Linux：`~/.workbuddy/skills/Unified-Research-Finder/`\n\n（你也可以直接把仓库里的 `Unified-Research-Finder` 文件夹复制过去。）\n\n**第二步：开始用**\n在 WorkBuddy 对话框里直接说人话就行，例如：\n- 「帮我找 CRISPR 基因编辑 的最新文献」\n- 「在 PubMed 上搜 二甲双胍 和 2 型糖尿病」\n- 「用灯塔学术查 大语言模型 综述」\n\n技能会自动同时检索两库、合并去重，并告诉你「已开启多库去重，可手动关闭」。\n如果你不想去重，说一句「不用去重」，它会保留重复项。\n\n> 进阶（可选）：脚本是纯 Python 标准库写的，装好 Python 3.8+ 即可直接在命令行跑：\n> ```bash\n> python scripts/unified_search.py --query \"CRISPR gene editing\" --num 10\n> ```\n\n**项目结构 / Project Structure：**\n\n```\nUnified-Research-Finder/\n├── SKILL.md # 技能说明（触发词、检索流程、输出模板）\n├── CHANGELOG.md # 更新日志\n├── LICENSE # MIT-0 开源协议\n├── README.md # 本说明文件（中英双语）\n├── .gitignore # 忽略 Python 缓存等无关文件\n├── scripts/\n│ ├── unified_search.py # 双库合并去重入口（默认推荐）\n│ ├── pubmed_search.py # PubMed 官方 API 检索\n│ └── scholar_search.py # Google Scholar 及镜像站检索\n└── references/\n ├── scholar-sources.md # 四个 Scholar 源的技术细节\n ├── pubmed-query-syntax.md # PubMed 检索语法\n └── register-api-key.md # 免费注册 NCBI API key 引导\n```\n\n（运行时自动生成的 `__pycache__` 等缓存已被 `.gitignore` 排除，不会进入仓库。）\n\n## 3. 技术原理\n\n- **纯标准库、零依赖**：所有脚本只用 Python 自带模块（`urllib` / `json` / `re` / `subprocess`），无需 `pip install`，启动快、内存低。\n- **PubMed**：直接调用 NCBI 官方 `esearch` + `efetch` 接口，拿到结构化 JSON（PMID、标题、作者、期刊、摘要、DOI），真实可验证。\n- **Scholar 多源回退**：优先用「灯塔学术」的 JSON API（最快最省内存）；若被限流，自动退回「烂番薯」服务端渲染 HTML（带 Referer 解析）；再不行试香港镜像与官方站。任一源被拦截（403 / 验证码 / 超时）即跳下一源。\n- **跨库合并去重**：`unified_search.py` 用子进程并行调用上面两个脚本，把结果统一字段后，以 **DOI 或归一化标题** 为键去重——同一篇论文在 PubMed 和 Scholar 都出现时只保留一条。\n- **浏览器兜底（可选）**：当所有 HTTP 方式都被拦，可装 Playwright 用 `--browser` 模式做无头渲染；该模式较重，仅按需启用，不常驻。\n\n## 4. 致谢\n\n本技能最初是作为 [`paper-finder`](https://clawhub.ai/wangjinhongmy-pixel/skills/paper-finder) 的升级案例而构思的。`paper-finder` 提供了「只返回真实文献、绝不编造」的优良第一原则，以及清晰的技能结构范式，本项目的 PubMed 网页检索思路也受其启发。在此对 `paper-finder` 的作者表达诚挚感谢。\n\n---\n\n# English\n\n## 1. Introduction\n\n**Unified-Research-Finder** is an all-in-one academic literature search skill for WorkBuddy / SkillHub-compati"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn71cn3h6s4p3eq2qpvbnxq1k98b1r7b\",\n \"slug\": \"unified-research-finder\",\n \"version\": \"1.1.1\",\n \"publishedAt\": 1784902034554\n}"},{"path":"references/pubmed-query-syntax.md","content":"# PubMed 检索语法速查\n\n构造 `--query` 参数时使用。PubMed 支持完整的布尔检索与字段限定。\n\n## 布尔运算\n\n- `AND`、`OR`、`NOT` 必须**大写**\n- 默认多个词之间按 `AND` 处理（自动术语映射可能介入）\n- 括号控制优先级：`(a OR b) AND c`\n\n## 常用字段标签\n\n| 标签 | 含义 | 示例 |\n|------|------|------|\n| `[MeSH Terms]` / `[mh]` | MeSH 主题词 | `\"Diabetes Mellitus, Type 2\"[MeSH Terms]` |\n| `[Title]` / `[ti]` | 标题 | `metformin[Title]` |\n| `[Title/Abstract]` / `[tiab]` | 标题或摘要 | `semaglutide[tiab]` |\n| `[Author]` / `[au]` | 作者 | `Smith J[Author]` |\n| `[Journal]` / `[jour]` | 期刊 | `\"N Engl J Med\"[Journal]` |\n| `[pdat]` | 发表日期 | `2023:2025[pdat]` |\n| `[Publication Type]` / `[pt]` | 文献类型 | `randomized controlled trial[pt]` |\n| `[la]` | 语言 | `english[la]` |\n| `[free full text]` | 免费全文过滤 | `... AND free full text[Filter]` |\n\n## 常用文献类型 `[pt]`\n\n- `randomized controlled trial[pt]` — RCT\n- `systematic review[pt]` — 系统综述\n- `meta-analysis[pt]` — Meta 分析\n- `review[pt]` — 综述\n- `clinical trial[pt]` — 临床试验\n- `case reports[pt]` — 病例报告\n\n## 日期限定（两种方式）\n\n1. 查询内：`\"covid-19\"[mh] AND 2022:2025[pdat]`\n2. 脚本参数（更推荐）：`--mindate 2022/01/01 --maxdate 2025/12/31`\n\n## 短语检索\n\n- 双引号锁定短语，禁用自动术语映射：`\"blood pressure\"` \n- 截词：`*`（至少 4 个字符后），如 `diabet*`\n\n## 典型查询示例\n\n```\n# 某药治疗某病的 RCT\nsemaglutide[tiab] AND \"Obesity\"[MeSH Terms] AND randomized controlled trial[pt]\n\n# 某作者在某期刊的文章\nWang Y[Author] AND \"Lancet\"[Journal]\n\n# 近 5 年系统综述\n\"Alzheimer Disease\"[MeSH Terms] AND systematic review[pt] AND 2020:2025[pdat]\n\n# 标题含某关键词、英文、有免费全文\nmetformin[Title] AND english[la] AND free full text[Filter]\n```\n\n## 排序说明\n\n- `--sort relevance`（默认）：相关性，适合\"最重要的几篇\"\n- `--sort pub_date`：按发表日期倒序，适合\"最新的几篇\""},{"path":"references/register-api-key.md","content":"# 小白指南：注册 NCBI 账户并获取免费的 PubMed API Key\n\n> 这个技能**不申请 key 也能用**。只有当你需要\"一次查很多篇\"或\"查得快一点\"时，才需要做下面这一步。\n> 全程免费，不用绑卡、不用付费，5 分钟左右搞定。\n\n## 一、先确认：你到底需不需要？\n\n| 你的使用场景 | 需要申请吗 |\n|------|------|\n| 平时每次查几篇文献（≤20 篇） | 不需要，直接能用 |\n| 想一次抓取几十上百篇、或写批量脚本 | 需要，能明显提速 |\n| 搜索时偶尔报错\"访问太频繁\" | 需要，能避免被限流 |\n\n## 二、第一步：注册一个 NCBI 账户（没有就先注册）\n\n1. 打开网站：\n2. 点 **Register for an NCBI account**（注册账户）。\n3. 可以用**邮箱**注册，也可以直接用 **Google / Microsoft 账号**一键登录（最省事）。\n4. 按提示填邮箱、设密码，收一封验证邮件点链接确认。\n5. 注册完成，记住这个账号即可。\n\n> 小提示：NCBI 是\"美国国立生物技术信息中心\"，PubMed 就是它家的数据库。注册它家账户不会给你发广告。\n\n## 三、第二步：生成一个 API Key（一次性操作）\n\n1. 登录后打开：\n2. 找到 **API Key** 这一栏，点 **Create an API Key**（创建密钥）。\n3. 系统会给你一串类似这样的字符（举例）：\n ```\n 0123456789abcdef0123456789abcdef0123\n ```\n4. **复制保存好这串字符**（建议先贴在记事本里，后面用得到）。\n\n> 这就是你的\"API Key\"。它相当于你的专属通行码，能让你查文献的速度从每秒 3 次提升到每秒 10 次。\n\n## 四、第三步：把这个 Key 告诉本技能（两种方式任选）\n\n### 方式 A：临时用一次（在对话里说）\n直接在对话里告诉我：\n> \"用邮箱 me@example.com 和 API key 0123...ef 帮我查 XX\"\n\n我会把它作为本次命令的参数传给脚本（`--email` 和 `--api-key`）。\n\n### 方式 B：设成环境变量（一劳永逸，推荐）\n把 key 存到电脑的环境变量里，以后不用每次都说：\n\n- **Windows（PowerShell）**：\n ```powershell\n [System.Environment]::SetEnvironmentVariable(\"NCBI_API_KEY\", \"0123...ef\", \"User\")\n ```\n 设置后**重启一下 WorkBuddy** 让它读到新变量。\n- **macOS / Linux**：把下面这行加到 `~/.zshrc` 或 `~/.bashrc`，然后重开终端：\n ```bash\n export NCBI_API_KEY=\"0123...ef\"\n ```\n\n设好后，技能会自动使用它，你无需再手动提供。\n\n## 五、常见问题\n\n- **Key 会过期吗？** 一般不会自动过期，但你随时可以在设置页 **Delete** 后重新生成一个。\n- **Key 能给别人吗？** 不能。它绑定你的账户，相当于密码，别外传。\n- **邮箱填了干嘛？** NCBI 建议填，方便他们在接口出问题时联系你，纯属礼貌字段，不强制。\n- **还是看不懂？** 直接把报错或卡住的地方发给我，我一步步带你点。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用 Skill: Unified Research Finder Owner: georgechou17 Summary: 统一的学术文献检索助手。覆盖两大体系：(1) PubMed 官方 E-utilities API（esearch+efetch，真实 PMID/摘要/DOI）与 PubMed 网页检索；(2) Google Scholar 及其镜像站——灯塔学术搜索、烂番薯学术搜索、Google Scholar 香港镜像、Google Scholar 官方站，以及 KipHub学术、学术搜索Pro 等大陆镜像，按「kiphub → 烂番薯 → 学术搜索Pro → 灯塔 → 香港 → 官方」优先级自动回退。当用户要找文献、查论文、搜 PubMed、查 Google 学术/谷歌学术、用学术镜像站、要影响因子或引用 Tags: latest:1.1.1 Version history: v1.1.1 | 2026-07-24T14:","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1164,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:00:14.703Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-13T18:16:23.507Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}