ssci-subagent-skills 1.0.0

package/skills/patent-downloader/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: patent-downloader
+description: Complete MCP Server implementation for searching and downloading patents from Google Patents. Use when Claude needs to: (1) Search patents by keywords, (2) Download single patent PDF, (3) Batch download multiple patents with rate limiting. Includes FastMCP server with Playwright automation, anti-scraping measures, and cross-platform support. The skill provides ready-to-use Python code with browser automation, resource blocking for performance, and robust error handling.
+---
+
+# Patent Downloader
+
+完整的 MCP Server 实现，用于从 Google Patents 搜索和下载专利 PDF。
+
+## 快速开始
+
+1. 从 `scripts/patent_server.py` 复制代码到目标项目
+2. 安装依赖：`pip install -r assets/requirements.txt`
+3. 安装浏览器：`playwright install chromium`
+4. 运行服务器：`python patent_server.py`
+5. 在 MCP 配置中注册服务器
+
+详细使用说明见 `assets/README_TEMPLATE.md`。
+
+## 核心功能
+
+### 1. search_patents(query: str) -> str
+
+在 Google Patents 上搜索关键词，返回前 5 条结果。
+
+**输入**:
+- `query`: 搜索关键词（例如："neural network", "quantum computing"）
+
+**输出**:
+- Markdown 格式的专利列表，包含：
+  - 专利标题
+  - 专利 ID（如 US10123456B2）
+  - 摘要片段（前 200 字符）
+
+**示例**:
+```
+搜索关于 "artificial intelligence" 的专利
+```
+
+### 2. download_single_patent(patent_id: str) -> str
+
+下载单个专利的 PDF 文件到用户的下载目录。
+
+**输入**:
+- `patent_id`: 专利标识符（例如："US10123456B2", "CN123456789A"）
+
+**输出**:
+- 成功：返回保存路径（例如 `✅ Successfully downloaded: C:\Users\...\Downloads\US10123456B2.pdf`）
+- 失败：返回详细错误信息
+
+**专利 ID 格式**:
+- 美国专利：`US{数字}{字母}`（如 US10123456B2）
+- 中国专利：`CN{数字}{字母}`（如 CN123456789A）
+- 欧洲专利：`EP{数字}{字母}`（如 EP3456789B1）
+
+**示例**:
+```
+下载专利 US10123456B2
+```
+
+### 3. batch_download_patents(patent_ids: list[str]) -> str
+
+批量下载多个专利，包含智能限流和容错机制。
+
+**输入**:
+- `patent_ids`: 专利 ID 列表（例如：["US10123456B2", "CN123456789A", "EP3456789B1"]）
+
+**输出**:
+- 详细的下载报告，包含：
+  - 总数、成功数、失败数
+  - 成功率百分比
+  - 每个专利的下载结果
+
+**特性**:
+- **限流**: 每次下载之间 3-7 秒随机延迟，避免被封禁
+- **容错**: 单个失败不影响整体，继续下载其余专利
+- **进度显示**: 实时显示当前进度（如 `[2/5] Downloading: CN123456789A`）
+
+**示例**:
+```
+批量下载这些专利：
+- US10123456B2
+- CN123456789A
+- EP3456789B1
+```
+
+## 技术实现要点
+
+### 防爬策略
+
+代码实现了多层反检测机制：
+
+1. **Headless 模式**: 使用 `headless=True` 运行无头浏览器
+2. **反自动化参数**: 添加 `--disable-blink-features=AutomationControlled`
+3. **Navigator 覆盖**: 注入脚本将 `navigator.webdriver` 设为 `undefined`
+4. **真实 User-Agent**: 使用 Chrome 120 的真实 User-Agent
+5. **浏览器指纹**: 设置真实视口大小（1920x1080）和语言（zh-CN）
+
+关键代码：
+```python
+ANTI_DETECTION_SCRIPT = """
+    Object.defineProperty(navigator, 'webdriver', {
+        get: () => undefined
+    });
+"""
+
+browser = await playwright.chromium.launch(
+    headless=True,
+    args=["--disable-blink-features=AutomationControlled"]
+)
+
+await context.add_init_script(ANTI_DETECTION_SCRIPT)
+```
+
+### 性能优化
+
+通过资源拦截显著提升性能：
+
+```python
+await page.route(
+    lambda route: route.request.resource_type in ["image", "font", "stylesheet"],
+    lambda route: route.abort()
+)
+```
+
+拦截的资源类型：
+- **Image**: 图片（.png, .jpg, .gif）
+- **Font**: 字体（.woff, .woff2）
+- **Stylesheet**: CSS 文件
+
+只加载 HTML 内容，减少 60-80% 的带宽使用。
+
+### 批量下载优化
+
+- 单次浏览器实例（复用 BrowserContext）
+- 单个 Page 对象（避免开销）
+- 随机延迟（`random.uniform(3.0, 7.0)`）
+- 独立错误处理（try/except 包裹每个下载）
+
+### 跨平台兼容
+
+使用 `pathlib` 处理文件路径：
+
+```python
+from pathlib import Path
+
+DOWNLOAD_DIR = Path.home() / "Downloads"
+download_path = DOWNLOAD_DIR / f"{patent_id}.pdf"
+```
+
+自动适配：
+- Windows: `C:\Users\{用户}\Downloads\`
+- macOS: `/Users/{用户}/Downloads/`
+- Linux: `/home/{用户}/Downloads/`
+
+## 资源文件
+
+### scripts/patent_server.py
+
+完整的 MCP Server 实现（~300 行），包含：
+
+- **FastMCP 初始化**: `mcp = FastMCP("patent-downloader")`
+- **浏览器上下文创建**: `create_browser_context()` 函数
+- **三个 MCP 工具**: 使用 `@mcp.tool()` 装饰器
+- **错误处理**: 每个 tool 都有完整的 try/except
+- **资源清理**: `finally` 块确保浏览器关闭
+
+### assets/requirements.txt
+
+Python 依赖：
+```
+mcp>=1.0.0
+playwright>=1.40.0
+```
+
+### assets/README_TEMPLATE.md
+
+用户使用指南，包含：
+- 安装步骤
+- MCP 配置方法
+- 使用示例
+- 常见问题
+- 技术限制
+
+### references/google_patents.md
+
+Google Patents 网站结构参考，包含：
+- URL 格式说明
+- HTML 选择器
+- 专利 ID 格式
+- 调试技巧
+- 性能优化建议
+
+## 配置 MCP
+
+在用户的 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "patent-downloader": {
+      "command": "python",
+      "args": ["/absolute/path/to/patent_server.py"],
+      "env": {}
+    }
+  }
+}
+```
+
+**重要**:
+- 使用绝对路径
+- 确保 `patent_server.py` 可执行
+- 已安装 Playwright 浏览器
+
+## 故障排除
+
+### 问题：找不到 PDF 下载链接
+
+**检查项**:
+1. 专利 ID 格式是否正确
+2. 网络连接是否正常
+3. 使用 `headless=False` 调试查看实际页面
+
+### 问题：批量下载速度慢
+
+**说明**: 这是正常的。3-7 秒延迟是故意设计的，避免被 Google Patents 封禁。
+
+### 问题：CAPTCHA 或验证页面
+
+**解决方案**:
+1. 确认反爬脚本已注入
+2. 增加延迟时间（修改 `random.uniform(7.0, 15.0)`）
+3. 检查 IP 是否被限制
+
+详细调试方法见 `references/google_patents.md`。
+
+## 使用场景
+
+当用户请求以下任务时，使用此技能：
+
+1. **"搜索关于 X 的专利"** → `search_patents`
+2. **"下载专利 {ID}"** → `download_single_patent`
+3. **"批量下载这些专利..."** → `batch_download_patents`
+4. **"查找某个技术领域的专利"** → 先 `search_patents` 再批量下载
+
+## 代码模式
+
+### 创建浏览器上下文
+
+```python
+from playwright.async_api import async_playwright
+
+async with async_playwright() as p:
+    browser, context, page = await create_browser_context(p)
+    try:
+        # 执行操作
+        await page.goto(url)
+    finally:
+        await browser.close()
+```
+
+### 查找并下载 PDF
+
+```python
+# 查找下载链接
+selectors = ["a[href*='.pdf']", "button[title*='PDF']"]
+for selector in selectors:
+    element = await page.query_selector(selector)
+    if element:
+        break
+
+# 下载
+async with page.expect_download() as download_info:
+    await element.click()
+download = await download_info.value
+await download.save_as(path)
+```
+
+### 批量处理模板
+
+```python
+for i, item in enumerate(items, 1):
+    try:
+        # 处理单个项目
+        result = await process_item(item)
+        success_count += 1
+    except Exception as e:
+        failure_count += 1
+        log_error(e)
+
+    # 限流（除最后一个）
+    if i < len(items):
+        await asyncio.sleep(random.uniform(3.0, 7.0))
+```
+
+## 技术约束
+
+- **框架**: 必须使用 FastMCP (`from mcp.server.fastmcp import FastMCP`)
+- **浏览器**: 仅支持 Chromium（Playwright）
+- **Python 版本**: 需要 Python 3.8+
+- **网络**: 需要访问 Google Patents（可能需要代理）
+- **磁盘空间**: 每个 PDF 约 1-5 MB
+
+## 安全和合规
+
+- 仅用于合法的专利研究
+- 遵守 Google Patents 服务条款
+- 不要用于商业目的的批量爬取
+- 建议批量下载不超过 20 个专利

package/skills/patent-downloader/assets/README_TEMPLATE.md

@@ -0,0 +1,140 @@
+# Google Patents Downloader - MCP Server
+
+一个基于 Model Context Protocol (MCP) 的服务器，用于从 Google Patents 搜索和下载专利 PDF。
+
+## 功能特性
+
+- **搜索专利**: 通过关键词搜索 Google Patents 并获取前 5 条结果
+- **单文件下载**: 下载单个专利的 PDF 文件
+- **批量下载**: 批量下载多个专利，包含智能限流和容错机制
+- **反爬策略**: 使用 Playwright 模拟真实浏览器行为
+- **跨平台支持**: 支持 Windows 和 macOS
+
+## 安装步骤
+
+### 1. 安装 Python 依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. 安装 Playwright 浏览器
+
+```bash
+playwright install chromium
+```
+
+**注意**: 首次使用需要下载 Chromium 浏览器（约 150MB）。
+
+## 配置 MCP
+
+在你的 MCP 配置文件中添加此服务器（通常在 `~/.config/claude-code/mcp_config.json` 或类似位置）：
+
+```json
+{
+  "mcpServers": {
+    "patent-downloader": {
+      "command": "python",
+      "args": ["/path/to/scripts/patent_server.py"],
+      "env": {}
+    }
+  }
+}
+```
+
+**重要**: 将 `/path/to/scripts/patent_server.py` 替换为实际的 `patent_server.py` 文件路径。
+
+## 使用方法
+
+### 搜索专利
+
+向 Claude 发送请求：
+```
+搜索关于 "neural network" 的专利
+```
+
+Claude 会调用 `search_patents` 工具并返回前 5 条结果。
+
+### 下载单个专利
+
+```
+下载专利 US10123456B2 的 PDF
+```
+
+Claude 会调用 `download_single_patent` 工具，文件将保存到你的下载目录。
+
+### 批量下载专利
+
+```
+批量下载这些专利：
+- US10123456B2
+- CN123456789A
+- EP3456789B1
+```
+
+Claude 会调用 `batch_download_patents` 工具，自动添加 3-7 秒的随机延迟以避免被封禁。
+
+## 工作原理
+
+### 技术栈
+
+- **FastMCP**: MCP 服务器框架
+- **Playwright**: 浏览器自动化
+- **Chromium**: 无头浏览器
+
+### 防爬措施
+
+- 设置 `headless=True` 运行无头浏览器
+- 添加 `--disable-blink-features=AutomationControlled` 参数
+- 注入脚本将 `navigator.webdriver` 设为 `undefined`
+- 使用真实的 User-Agent
+- 拦截图片、字体和 CSS 以提升性能
+
+### 性能优化
+
+- 拦截静态资源（图片、字体、CSS）只加载 HTML
+- 批量下载时复用浏览器实例
+- 随机延迟（3-7秒）避免请求过快
+
+## 文件保存位置
+
+下载的 PDF 文件默认保存到：
+- **Windows**: `C:\Users\YourUsername\Downloads\`
+- **macOS**: `/Users/YourUsername/Downloads/`
+
+文件名格式：`{专利ID}.pdf`（例如：`US10123456B2.pdf`）
+
+## 常见问题
+
+### Q: 下载失败怎么办？
+
+A: 可能的原因：
+1. 专利 ID 格式错误（确保使用完整 ID，如 US10123456B2）
+2. 网络连接问题
+3. Google Patents 网站结构变化
+
+### Q: 批量下载速度慢？
+
+A: 这是正常的。为了避免被 Google Patents 封禁，每次下载之间有 3-7 秒的随机延迟。
+
+### Q: 如何查看下载进度？
+
+A: Claude 会显示当前进度，例如 `[2/5] Downloading: CN123456789A`。
+
+### Q: 可以修改下载目录吗？
+
+A: 可以。修改 `patent_server.py` 中的 `DOWNLOAD_DIR` 变量：
+
+```python
+DOWNLOAD_DIR = Path("your/custom/path")
+```
+
+## 技术限制
+
+- 仅支持 Chromium 浏览器
+- 需要稳定的网络连接
+- 批量下载时单次请求建议不超过 20 个专利
+
+## 许可证
+
+本工具仅供学习和研究使用。请遵守 Google Patents 的服务条款。

package/skills/patent-downloader/assets/requirements.txt

@@ -0,0 +1,5 @@
+# MCP Server framework
+mcp>=1.0.0
+
+# Browser automation
+playwright>=1.40.0

package/skills/patent-downloader/references/google_patents.md

@@ -0,0 +1,210 @@
+# Google Patents 网站结构参考
+
+本文档提供 Google Patents 网站的 HTML 结构和 API 参考，用于维护和调试专利下载功能。
+
+## 搜索页面结构
+
+### URL 格式
+
+```
+https://patents.google.com/?q={query}
+```
+
+参数：
+- `query`: 搜索关键词（URL 编码）
+
+### 主要选择器
+
+搜索结果容器：
+```html
+<search-result>
+  <!-- 单个搜索结果 -->
+</search-result>
+```
+
+专利标题链接：
+```html
+<a state="search-result-title">专利标题</a>
+```
+
+摘要片段：
+```html
+<span class="style-scope patent-result">
+  摘要内容...
+</span>
+```
+
+## 专利详情页结构
+
+### URL 格式
+
+```
+https://patents.google.com/patent/{patent_id}/{lang}
+```
+
+参数：
+- `patent_id`: 专利标识符（例如：US10123456B2, CN123456789A）
+- `lang`: 语言代码（可选，推荐使用 `zh` 获取中文界面）
+
+示例：
+- `https://patents.google.com/patent/US10123456B2/zh`
+- `https://patents.google.com/patent/CN123456789A/zh`
+
+### PDF 下载链接
+
+PDF 下载链接的常见选择器：
+
+1. 直接链接：
+```html
+<a href="https://patentimages.storage.googleapis.com/.../US10123456.pdf" download>
+  Download PDF
+</a>
+```
+
+2. 按钮：
+```html
+<button title="Download PDF">...</button>
+```
+
+3. 图标按钮：
+```html
+<button class="download-icon">...</button>
+```
+
+### 查找 PDF 链接的策略
+
+代码中使用多个选择器按优先级尝试：
+
+```python
+selectors = [
+    "a[href*='.pdf']",           # 直接包含 .pdf 的链接
+    "button[title*='PDF']",      # 标题包含 PDF 的按钮
+    "button[title*='pdf']",      # 标题包含 pdf 的按钮（小写）
+    "a[download]",               # 带有 download 属性的链接
+]
+```
+
+## 专利 ID 格式
+
+### 美国专利 (US)
+- 格式：`US{数字}{字母}`
+- 示例：`US10123456B2`, `US7890123B1`
+
+### 中国专利 (CN)
+- 格式：`CN{数字}{字母}`
+- 示例：`CN123456789A`, `CN102345678B`
+
+### 欧洲专利 (EP)
+- 格式：`EP{数字}{字母}`
+- 示例：`EP3456789B1`
+
+### 世界专利 (WO)
+- 格式：`WO{数字}{字母}`
+- 示例：`WO2023123456A1`
+
+## 常见问题排查
+
+### 问题 1: 找不到 PDF 链接
+
+**症状**: `Failed to find PDF download link`
+
+**可能原因**:
+1. 页面结构变化，选择器失效
+2. 专利没有 PDF 版本
+3. 页面加载未完成
+
+**解决方法**:
+1. 检查页面是否完全加载（增加 timeout）
+2. 使用浏览器开发者工具检查实际 HTML 结构
+3. 更新选择器列表
+
+### 问题 2: 下载超时
+
+**症状**: `Timeout waiting for download`
+
+**可能原因**:
+1. 网络连接慢
+2. PDF 文件过大
+3. 服务器响应慢
+
+**解决方法**:
+1. 增加 timeout 值（默认 30000ms）
+2. 检查网络连接
+
+### 问题 3: 浏览器被检测为自动化
+
+**症状**: Google Patents 返回验证页面或 CAPTCHA
+
+**可能原因**:
+1. 反爬措施不足
+2. 请求频率过高
+
+**解决方法**:
+1. 确认反爬脚本已注入
+2. 增加请求间隔时间
+3. 检查 User-Agent 是否正确
+
+## 调试技巧
+
+### 1. 在非 Headless 模式下调试
+
+临时修改代码以查看浏览器行为：
+
+```python
+browser = await playwright.chromium.launch(
+    headless=False,  # 显示浏览器窗口
+    args=[...]
+)
+```
+
+### 2. 打印页面 HTML
+
+```python
+content = await page.content()
+print(content)
+```
+
+### 3. 等待特定元素
+
+```python
+await page.wait_for_selector("your-selector", timeout=30000)
+```
+
+### 4. 截图调试
+
+```python
+await page.screenshot(path="debug.png")
+```
+
+## 性能优化建议
+
+### 1. 资源拦截
+
+当前实现拦截了以下资源类型：
+- `image`: 图片（.png, .jpg, .gif）
+- `font`: 字体（.woff, .woff2, .ttf）
+- `stylesheet`: CSS 文件
+
+这可以显著减少带宽使用和加载时间。
+
+### 2. 上下文复用
+
+批量下载时：
+- 只启动一个浏览器实例
+- 复用同一个 BrowserContext
+- 复用同一个 Page 对象
+
+### 3. 并发控制
+
+当前实现是串行下载。如需并发，建议：
+- 不超过 3 个并发连接
+- 使用 `asyncio.Semaphore` 控制并发数
+- 每个连接使用独立的 Page 对象
+
+## 未来改进方向
+
+1. **支持更多下载格式**: 除了 PDF，支持下载专利的其他格式
+2. **增量下载**: 检测本地已存在文件，跳过重复下载
+3. **断点续传**: 支持大文件的断点续传
+4. **代理支持**: 添加 HTTP/SOCKS 代理支持
+5. **下载队列**: 实现持久化的下载队列