v0.8: Serper 集成 + H1 章节标题双行居中 + 反方证据观点化 + 术语核查命令

新增：Google 系检索（SerpAPI → Serper.dev） - scripts/lib/serper_client.py：封装 serper.dev 的 Google Search / Scholar / News / Patents - 专利检索用 site:patents.google.com 技巧，serper.dev 没专用 endpoint 但效果很好 - Scholar 带引用数、年份、期刊信息，便于权威信源识别 - News 支持 time_range（d/w/m/y）时效性过滤 - scripts/lib/search_client.py 扩展为多路由门面： - search() 通用：Exa → Tavily - patents() 专利：Serper（Google Patents）→ 通用搜索 + site: 兜底 - scholar() 论文：Serper Scholar → 通用搜索兜底 - news() 新闻：Serper News → 通用搜索兜底 - 所有 httpx 客户端 trust_env=False，绕过系统 socks5 代理（v0.6 修过的 TLS EOF） - .opencode/skills/search-strategy/SKILL.md §三重写：按查询类型路由，明确何时用哪个 API H1 章节标题：两行居中 + 装饰横线 - 新增 ParagraphStyle: h1-chapter-num / h1-chapter-title - 新增 parse_chapter_title() 支持中文/阿拉伯/混合空格章号： "第一章" / "第 9 章" / "第6章" / "Chapter 1" 全覆盖 - 分隔符支持: em dash — / en dash – / - / : / ： - 新增 build_chapter_header()：章号小字居中 + 章名大字深蓝居中 + HRFlowable 3cm 装饰线 - 只对正文章节（_title_kind == "chapter"）启用；前置件（免责声明/执行摘要/术语表/目录）仍用单行 h1 样式反方证据段规范化（用户反馈 v0.7 问题 #5） - skill:evidence-table 新增 §"正文中反方证据段落的写作规范"： - 禁止机械标题"反驳证据" / "Counter-Evidence" / "反方观点" - 必须观点化，包含具体判断（如"另一种声音：管线虚胖还是真实进展？"） - 用 H2 或 H3，禁止加粗段冒充标题 - 给出段落结构模板（1-2 句过渡 → 列表型反方论点 → 整合判断） - dr-analyst.md Hard Rules #3 改为引用该规范术语表事实核查前置（新 command /dr-glossary） - 新增 .opencode/commands/dr-glossary.md，支持 --from phase1|phase2|phase4 三个时机 - Phase 1 末 / Phase 2 初：从 framework.md 抽取专有名词种子表，在 dr-analyst 起草前预先核查公司名/产品名/技术名拼写，避免编造错误（Mabwell → Maywavee 这类） - Phase 4：维持当前用法，对 glossary.json 全量核查实测：dual-target-rnai-pipeline-2026 重生 PDF 55 页，所有 10 章标题双行居中正确渲染（第一章/第二章/... 第十章 / 第 6 章 / 第 9 章多种形式都识别）。
2026-04-22 17:04:05 +08:00
parent 09f681beb5
commit c444007f04
7 changed files with 539 additions and 41 deletions
@@ -172,7 +172,7 @@ Follow `skill:humanizer-cn` §1-26 strictly:

 1. MUST: Every claim has `[src_xxx]` citation
 2. MUST: Every numerical fact has a source
-3. MUST: Counter-evidence section is mandatory (not optional)
+3. MUST: Counter-evidence paragraph is mandatory at chapter end. Per skill:evidence-table §"正文中反方证据段落的写作规范", the heading must express a concrete opinion (e.g., "反例：Codexis ECO 并非所有情境都优于 SPOS" or "值得警惕：临床前到 IND 的衰减率"), NOT a mechanical label like "Counter-Evidence" / "反驳证据". Use H2 or H3 heading level consistently; never use bold text as pseudo-heading.
 4. MUST: Word count ≥85% of quota, or continue searching
 5. MUST: No scheduling metadata in body text (no "P0 core", "quota: X", "researcher: dr-analyst")
 6. MUST: No SCQA labels (not even implicitly suggested by structure)
@@ -0,0 +1,60 @@
+---
+description: 术语表事实核查。用法 /dr-glossary [slug] [--from phase1|phase2|phase4]。用 Haiku + Serper/Exa 核查每个术语的英文全称和中文译名，识别拼写错误与误译。可在 Phase 2 前或 Phase 4 中运行。
+agent: dr-pm
+---
+
+你是 dr-pm（项目经理），用户执行了 `/dr-glossary $ARGUMENTS`。
+
+## 何时运行
+
+术语核查可以在三个时机运行，意义不同：
+
+- **Phase 1 末 / Phase 2 初**：基于 framework.md 抽取的关键术语（公司/产品/技术名）预先建表，供 dr-analyst 查阅，避免在章节起草阶段就编造拼写错误（Mabwell 拼成 Maywavee 这种）。
+- **Phase 2 中**：对 dr-analyst 产出的 ch01-chN.md 里出现的所有专有名词做核查。
+- **Phase 4**：对 translate.py 累积的 glossary.json 做核查（当前默认时机）。
+
+## 执行步骤
+
+### Step 1: 定位项目 + 解析模式
+
+```bash
+slug="$ARGUMENTS"
+# 默认 slug 从最近修改时间选；默认阶段 phase4
+```
+
+### Step 2: 准备术语种子列表
+
+根据阶段选择输入：
+
+- `--from phase1`：从 `projects/<slug>/phase1/framework.md` 抽取所有 H2/H3 标题 + 表格中的英文机构名、技术名、药物名。保存到 `projects/<slug>/phase2/terms.txt`（一行一个）。
+- `--from phase2`：从 `projects/<slug>/phase2/drafts/*.md` 抽取所有高频英文专有名词（首字母大写、不在常见词词典）。
+- `--from phase4`（默认）：直接用 `projects/<slug>/phase4/glossary.json`。
+
+### Step 3: 调用 build_glossary.py
+
+```bash
+uv run python scripts/build_glossary.py <slug> --workers 4 \
+    --input <输入 glossary 或 terms.txt>
+```
+
+观察输出，关注：
+- `[✓]` high confidence（自动可信）
+- `[~]` medium（人工复核）
+- `[?]` low confidence（必须复核）
+- `⚠ issue` 字段非空的（通常是拼写错误或误译）
+
+### Step 4: 汇报 + 建议下一步
+
+向用户展示：
+- 核查的术语数
+- 发现的错误数（按严重度分级：拼写错误 / 译名错误 / 低置信度）
+- 具体错误清单（前 10 条）
+- 建议：
+  - 如果在 Phase 2 前 → 把 glossary.json 交给 dr-analyst 作为参考
+  - 如果在 Phase 4 → 跑 `uv run python scripts/apply_glossary.py <slug>` 把修正回塗到正文
+
+## 注意事项
+
+- build_glossary 需要网络访问，Serper 和 Exa 都需要代理。如遇 SSL EOF，降 `--workers 3`。
+- Haiku 对极专业或极新兴术语（如 "muRNA", "SBS linker"）的判断可能不准，低置信度的条目必须人工复核。
+- 别对通用缩写（PDE/ASGPR/LNP）作自动替换——apply_glossary 已有黑名单，但核查结果在 glossary.json 里仍会体现。
@@ -81,11 +81,53 @@ description: 证据矩阵规范。规定每条核心结论必须有对应的证
 - 处理建议：保留并注明争议 / 修改措辞 / 删除

 <!-- 如有重大挑战 -->
-🚨 CRITICAL：<说明>
+CRITICAL: <说明>
 ```

 ---

+## 正文中反方证据段落的写作规范（v0.8 新）
+
+### 标题必须观点化，不能叫 "反驳证据 / Counter-Evidence"
+
+**问题诊断**：v0.7 发现每章末尾 dr-analyst 会机械地写 `## 反驳证据`，标题重复而空洞，读者看了没有信息增益。
+
+**新规则**：正文反方证据段落的标题必须：
+
+1. **用二级 H2 或三级 H3 标题**（统一层级，禁止用加粗段冒充标题）
+2. **包含具体判断**，不要用"反驳证据" / "反方证据" / "Counter-Evidence" 这种模板化命名
+3. 至少要回答：**"对前述论点的哪一方面提出了什么挑战？"**
+
+### 可接受的命名示例
+
+| ✗ 不推荐 | ✓ 推荐 |
+|---|---|
+| 反驳证据 | 另一种声音：管线虚胖还是真实进展？ |
+| Counter-Evidence | 需要补充判断的副作用：汇聚偶联收率可能被高估 |
+| 反方观点 | 反例：Codexis ECO 并非所有情境都优于 SPOS |
+| Counter Arguments | 值得警惕的数据：临床前到 IND 的衰减率 |
+
+### 段落结构模板（推荐）
+
+```markdown
+## <观点化标题>
+
+虽然上文论证了 <核心观点>，但以下证据提示需要**有限度地**接受这一判断：
+
+1. **<反方论点 1>**：<具体数据或案例> [src_xxx]。影响评估：<说明>
+2. **<反方论点 2>**：<具体数据或案例> [src_xxx]。影响评估：<说明>
+
+综合而言，核心结论仍成立，但需在 <某个具体维度> 上留出缓冲。
+```
+
+### 禁止的写法
+
+- 单独用 **加粗段** 冒充反方证据标题（`**反方证据：** ...`）
+- 反方证据后不做整合判断，只是堆数据
+- 在每个小节末尾都加反方证据（只在章末加一次即可；若小节级别有重大挑战，写在小节正文里即可）
+
+---
+
 ## 置信度分级标准

 | 置信度 | 条件 | 正文处理方式 |
@@ -82,39 +82,74 @@ description: 生物医药深度研究的统一检索策略。规定信源优先

 ---

-## 三、API 调用顺序（技术栈）
+## 三、API 调用顺序（技术栈，v0.8 更新）
+
+**按"查询类型"路由到最合适的 API**，而不是一律走通用搜索。

 ```
-┌─────────────────────────────────────────────┐
-│  Phase 1 初扫（dr-searcher 用）              │
-│  ├── tavily (MCP)      — 快速宽扫            │
-│  ├── brave (MCP)       — 交叉验证            │
-│  └── exa (MCP)         — neural search       │
+┌──────────────────────────────────────────────────────────────┐
+│ 查询类型          首选                 备选                  │
+├──────────────────────────────────────────────────────────────┤
+│ 专利               Serper Patents      Google Patents 爬页   │
+│                   (site:patents.google.com)                  │
 │                                                              │
-│  Phase 2 深研（dr-analyst 用）               │
-│  ├── pubmed esearch/efetch (bash+curl)      │
-│  ├── clinicaltrials.gov API (bash+curl)     │
-│  ├── openfda API (bash+curl)                │
-│  ├── patentsview / google patents (bash)    │
-│  └── + Phase 1 的 3 个 MCP 继续用             │
+│ 学术论文           Serper Scholar      PubMed E-utils        │
+│                   (带引用数/年份/期刊) (原始数据库)           │
 │                                                              │
-│  Phase 2 反验（dr-verifier 用）              │
-│  └── 与 analyst 相同但查反向关键词            │
-└─────────────────────────────────────────────┘
+│ 新闻 / 行业动态    Serper News         Tavily                │
+│                   (时效性敏感)                                │
+│                                                              │
+│ 临床试验           ClinicalTrials.gov  ChiCTR                │
+│                   (原始 API)                                  │
+│                                                              │
+│ 监管公告           openFDA / FDA 搜索   EMA / NMPA 官网      │
+│                                                              │
+│ 公司/机构识别      Exa                 Tavily                │
+│                   (LinkedIn/官网召回强)                       │
+│                                                              │
+│ 通用网页           Exa                 Tavily / Brave        │
+└──────────────────────────────────────────────────────────────┘
 ```

-### Tavily MCP 调用模板
+### Serper（google.serper.dev）使用模板
+
+**专利检索**：
+```python
+from scripts.lib.search_client import SearchClient
+with SearchClient() as c:
+    hits = c.patents("dual-target siRNA GalNAc", num_results=10)
+```
+
+**学术论文**：
+```python
+hits = c.scholar("dual-target RNAi 2024", num_results=10, year_low=2023)
+# hits[i].snippet 里包含引用数和期刊信息
+```
+
+**新闻（时效性）**：
+```python
+hits = c.news("Arrowhead ARO-DIMER-PA clinical trial", time_range="w")  # 最近一周
+```
+
+### Tavily MCP 调用模板（通用网页 - Phase 1 初扫）
 ```
 工具名：tavily_search
 参数：
  query: "<关键词>"
-  search_depth: "advanced"  # 默认 basic，深度研究用 advanced
+  search_depth: "advanced"
  max_results: 10
-  include_domains: ["pubmed.ncbi.nlm.nih.gov", "nejm.org", "lancet.com"]  # 锁 Tier 1
-  exclude_domains: ["baijiahao.baidu.com", "toutiao.com"]  # 排黑名单
-  time_range: "year"  # 或 "month"
+  include_domains: ["pubmed.ncbi.nlm.nih.gov", "nejm.org", "lancet.com"]
+  exclude_domains: ["baijiahao.baidu.com", "toutiao.com"]
+  time_range: "year"
 ```

+### 何时用哪个
+
+- **专利相关问题**（"谁拥有技术 X"、"FTO 自由度分析"）→ `c.patents()`，**永远先走 Google Patents**
+- **需要引用数排序的论文**（"找影响力最大的 N 篇"）→ `c.scholar()`
+- **近期新闻**（"2025 年 Q4 交易"、"上月 IND 批准"）→ `c.news(..., time_range="m")`
+- **快速概念验证 / 术语理解** → `c.search()`（通用）
+
 ### PubMed E-utils（bash 调用示例）
 ```bash
 # 1. esearch 拿 PMID 列表
@@ -49,6 +49,7 @@ try:
        Table,
        TableStyle,
    )
+    from reportlab.platypus.flowables import HRFlowable
 except ImportError:
    print("ERROR: missing reportlab. Run: uv sync", file=sys.stderr)
    sys.exit(1)
@@ -159,7 +160,7 @@ def build_styles() -> StyleSheet1:
        allowOrphans=0,
    ))

-    # H1 (chapter) - page break before, deep blue
+    # H1 (chapter) - page break before, deep blue (used for 前置件标题如"免责声明")
    ss.add(ParagraphStyle(
        name="h1",
        fontName="SrcSans-Bold",
@@ -173,6 +174,35 @@ def build_styles() -> StyleSheet1:
        wordWrap="CJK",
    ))

+    # H1 章号（正文章节第一行）：小字号居中，浅色
+    ss.add(ParagraphStyle(
+        name="h1-chapter-num",
+        fontName="SrcSans-Medium",
+        fontSize=13,
+        leading=20,
+        alignment=TA_CENTER,
+        spaceBefore=18,
+        spaceAfter=6,
+        textColor=colors.HexColor("#6b7280"),
+        letterSpacing=3,              # 章号加字距，视觉更稳
+        keepWithNext=1,
+        wordWrap="CJK",
+    ))
+
+    # H1 章名（正文章节第二行）：大字号居中加粗深蓝
+    ss.add(ParagraphStyle(
+        name="h1-chapter-title",
+        fontName="SrcSans-Bold",
+        fontSize=20,
+        leading=32,
+        alignment=TA_CENTER,
+        spaceBefore=0,
+        spaceAfter=12,
+        textColor=colors.HexColor("#1e3a8a"),
+        keepWithNext=1,
+        wordWrap="CJK",
+    ))
+
    # H2 (section) - blue, no page break, keep with next
    ss.add(ParagraphStyle(
        name="h2",
@@ -612,6 +642,62 @@ def md_inline_to_rl(text: str, *, add_cjk_space: bool = True) -> str:
    return text


+# H1 正文章节标题解析：拆成（章号, 章名）
+# 支持：
+#   第一章 — 为何...           → ("第一章", "为何...")
+#   第 9 章：四大监管向量...    → ("第 9 章", "四大监管向量...")
+#   第6章 — 固定化...          → ("第6章", "固定化...")
+#   第十章 — 制造体系...        → ("第十章", "制造体系...")
+#   Chapter 1: Why the Second... → ("Chapter 1", "Why the Second...")
+# 分隔符：—（em dash） / –（en dash） / - / : / ： / 空白多于一处
+_CHAPTER_HEAD_RE = re.compile(
+    r"^\s*"
+    r"(?P<num>(?:第\s*[一二三四五六七八九十百零〇两廿卅\d]+\s*章)|(?:Chapter\s+\d+))"
+    r"\s*[—–\-：:]\s*"
+    r"(?P<title>.+?)\s*$",
+    re.IGNORECASE,
+)
+
+
+def parse_chapter_title(raw: str) -> tuple[str, str] | None:
+    """解析章节标题。命中返回 (章号, 章名)，否则 None。"""
+    m = _CHAPTER_HEAD_RE.match(raw.strip())
+    if not m:
+        return None
+    num = m.group("num").strip()
+    title = m.group("title").strip()
+    if not title:
+        return None
+    # 规范化章号空白："第 6 章" 保留"第 6 章"，"第6章"保留"第6章"
+    num = re.sub(r"\s+", " ", num)
+    return num, title
+
+
+def build_chapter_header(raw_title: str, styles: StyleSheet1) -> list:
+    """生成正文章节标题：两行居中 + 装饰横线。
+
+    解析失败时 fallback 到普通 h1 样式。
+    """
+    parsed = parse_chapter_title(raw_title)
+    if parsed is None:
+        return [Paragraph(md_inline_to_rl(raw_title), styles["h1"])]
+
+    num, title = parsed
+    return [
+        Paragraph(md_inline_to_rl(num), styles["h1-chapter-num"]),
+        Paragraph(md_inline_to_rl(title), styles["h1-chapter-title"]),
+        # 装饰横线：居中、宽度约 3cm（视觉重量跟两行标题平衡）
+        HRFlowable(
+            width=3 * cm,
+            thickness=1.2,
+            color=colors.HexColor("#1e3a8a"),
+            spaceBefore=2,
+            spaceAfter=18,
+            hAlign="CENTER",
+        ),
+    ]
+
+
 # ============================================================
 # Document builders
 # ============================================================
@@ -1274,10 +1360,10 @@ def build_body(
            i = _skip_until_next_section(i + 1)
            continue

-        # H1 正文章节（chapter）：PageBreak + h1 样式
+        # H1 正文章节（chapter）：PageBreak + 章号/章名双行居中 + 装饰线
        if block.kind == "h1":
            story.append(PageBreak())
-            story.append(Paragraph(md_inline_to_rl(block.content), styles["h1"]))
+            story.extend(build_chapter_header(block.content, styles))
        else:
            # H2 正文小节：h2 样式（不分页）
            story.append(Paragraph(md_inline_to_rl(block.content), styles["h2"]))
@@ -115,11 +115,20 @@ class TavilyClient:


 class SearchClient:
-    """统一搜索门面：先用 Exa，失败/配额问题降级 Tavily。"""
+    """统一搜索门面，支持多路由：
+
+    - `search(query)`：通用网页搜索，优先 Exa → 降级 Tavily
+    - `patents(query)`：专利检索，走 Serper（Google Patents）；失败则通用搜索补刀
+    - `scholar(query)`：学术论文，走 Serper Scholar；失败则通用搜索补刀
+    - `news(query)`：新闻检索，走 Serper News；失败则通用搜索补刀
+
+    所有客户端都延迟导入 serper_client，避免没装 SERPAPI_KEY 时 import 炸。
+    """

    def __init__(self) -> None:
        self._exa: ExaClient | None = None
        self._tavily: TavilyClient | None = None
+        self._serper = None  # 惰性实例化
        try:
            self._exa = ExaClient()
        except SearchError:
@@ -133,11 +142,26 @@ class SearchClient:
                "neither EXA_API_KEY nor TAVILY_API_KEY available"
            )

+    def _get_serper(self):
+        """惰性创建 SerperClient。没 key 时返回 None。"""
+        if self._serper is False:
+            return None
+        if self._serper is None:
+            try:
+                from scripts.lib.serper_client import SerperClient
+                self._serper = SerperClient()
+            except Exception:
+                self._serper = False
+                return None
+        return self._serper
+
    def close(self) -> None:
        if self._exa:
            self._exa.close()
        if self._tavily:
            self._tavily.close()
+        if self._serper and self._serper is not False:
+            self._serper.close()

    def __enter__(self) -> "SearchClient":
        return self
@@ -146,17 +170,11 @@ class SearchClient:
        self.close()

    def search(self, query: str, *, num_results: int = 5) -> list[SearchHit]:
-        # 优先 Exa
+        """通用网页搜索。Exa 首选，Tavily 备选。"""
        if self._exa:
            try:
                return self._exa.search(query, num_results=num_results)
-            except SearchError as e:
-                msg = str(e).lower()
-                if "exceed" in msg or "quota" in msg or "429" in msg or "402" in msg:
-                    # 降级
-                    pass
-                else:
-                    # 其它错误继续往下试
+            except SearchError:
                pass
        if self._tavily:
            try:
@@ -165,13 +183,80 @@ class SearchClient:
                pass
        return []

+    def patents(self, query: str, *, num_results: int = 10) -> list[SearchHit]:
+        """专利检索：Serper 走 Google Patents 最准。降级到通用搜索 + site 限定。"""
+        serper = self._get_serper()
+        if serper:
+            try:
+                hits = serper.patents(query, num_results=num_results)
+                return [SearchHit(h.title, h.url, h.snippet) for h in hits]
+            except Exception:
+                pass
+        # 降级：通用搜索加 site 限定
+        return self.search(f"site:patents.google.com {query}", num_results=num_results)
+
+    def scholar(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+        year_low: int | None = None,
+    ) -> list[SearchHit]:
+        """学术论文：Serper Scholar 带引用数。降级到通用搜索。"""
+        serper = self._get_serper()
+        if serper:
+            try:
+                hits = serper.scholar(query, num_results=num_results, year_low=year_low)
+                return [
+                    SearchHit(
+                        title=h.title,
+                        url=h.url,
+                        snippet=f"{h.snippet}  | {h.source} | 引用 {h.cited_by}" if h.cited_by else h.snippet,
+                    )
+                    for h in hits
+                ]
+            except Exception:
+                pass
+        return self.search(query, num_results=num_results)
+
+    def news(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+        time_range: str | None = None,
+    ) -> list[SearchHit]:
+        """新闻检索：Serper News。降级到通用搜索。"""
+        serper = self._get_serper()
+        if serper:
+            try:
+                hits = serper.news(query, num_results=num_results, time_range=time_range)
+                return [
+                    SearchHit(
+                        title=h.title,
+                        url=h.url,
+                        snippet=f"{h.snippet}  | {h.source} | {h.date}" if h.date else h.snippet,
+                    )
+                    for h in hits
+                ]
+            except Exception:
+                pass
+        return self.search(query, num_results=num_results)
+

 if __name__ == "__main__":
    from scripts.lib.zenmux_client import load_secrets
    load_secrets()
    with SearchClient() as c:
-        hits = c.search("Mabwell 迈威生物 biopharmaceutical", num_results=3)
-        for i, h in enumerate(hits, 1):
-            print(f"[{i}] {h.title[:80]}")
+        print("--- 通用: Mabwell 迈威生物 ---")
+        for h in c.search("Mabwell 迈威生物 biopharmaceutical", num_results=3):
+            print(f"  {h.title[:80]}")
+            print(f"    {h.url}")
+        print("\n--- 专利: dual-target siRNA ---")
+        for h in c.patents("dual-target siRNA GalNAc", num_results=3):
+            print(f"  {h.title[:80]}")
+            print(f"    {h.url}")
+        print("\n--- Scholar: dual-target RNAi 2024 ---")
+        for h in c.scholar("dual-target RNAi drug", num_results=3, year_low=2023):
+            print(f"  {h.title[:80]}")
            print(f"    {h.url}")
-            print(f"    {h.snippet[:160]}")
@@ -0,0 +1,190 @@
+"""Serper.dev 客户端（Google Search API 代理）。
+
+为什么用 Serper：
+- 2500 次免费额度，远超 SerpAPI 的 100/月
+- 支持 Google Search、Scholar、News、Images、Maps
+- Google Patents 无专用 endpoint，但可用 `site:patents.google.com` 技巧
+- 价格比 SerpAPI 便宜 3-5×
+
+用途：
+- 专利检索：通用 search + `site:patents.google.com`
+- 学术论文：/scholar endpoint
+- 新闻：/news endpoint（时效性敏感的行业动态）
+
+httpx 客户端使用 trust_env=False 绕过系统 socks 代理（macOS Clash 会导致 TLS EOF）。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import httpx
+
+
+SERPER_BASE = "https://google.serper.dev"
+
+
+@dataclass
+class SerperHit:
+    title: str
+    url: str
+    snippet: str
+    source: str = ""       # 论文出处 / 新闻媒体
+    date: str = ""         # 发表日期（如 scholar / news 返回的话）
+    cited_by: int = 0      # 学术论文的引用数（仅 scholar）
+
+
+class SerperError(RuntimeError):
+    pass
+
+
+class SerperClient:
+    def __init__(self, api_key: str | None = None, timeout: float = 30.0) -> None:
+        self.api_key = api_key or os.environ.get("SERPAPI_KEY") or os.environ.get("SERPER_API_KEY")
+        if not self.api_key:
+            raise SerperError("SERPAPI_KEY / SERPER_API_KEY not set")
+        self._client = httpx.Client(trust_env=False, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "SerperClient":
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()
+
+    def _post(self, path: str, body: dict) -> dict:
+        try:
+            r = self._client.post(
+                f"{SERPER_BASE}{path}",
+                json=body,
+                headers={
+                    "X-API-KEY": self.api_key,
+                    "Content-Type": "application/json",
+                },
+            )
+        except httpx.RequestError as e:
+            raise SerperError(f"network error: {e}")
+        if r.status_code != 200:
+            raise SerperError(f"HTTP {r.status_code}: {r.text[:300]}")
+        try:
+            return r.json()
+        except Exception as e:
+            raise SerperError(f"invalid JSON: {e}")
+
+    def search(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+        gl: str = "us",
+        hl: str = "en",
+    ) -> list[SerperHit]:
+        """通用 Google 搜索。支持 site: / filetype: / 引号短语等 Google 高级语法。"""
+        data = self._post("/search", {
+            "q": query,
+            "num": num_results,
+            "gl": gl,
+            "hl": hl,
+        })
+        hits: list[SerperHit] = []
+        for item in (data.get("organic") or [])[:num_results]:
+            hits.append(SerperHit(
+                title=(item.get("title") or "")[:200],
+                url=item.get("link") or "",
+                snippet=(item.get("snippet") or "")[:600],
+                date=item.get("date") or "",
+            ))
+        return hits
+
+    def scholar(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+        year_low: int | None = None,
+        year_high: int | None = None,
+    ) -> list[SerperHit]:
+        """Google Scholar 搜索——学术论文首选。
+
+        返回带引用数、发表年份等元数据，权威信源识别更准确。
+        """
+        body: dict[str, Any] = {"q": query, "num": num_results}
+        if year_low is not None:
+            body["tbs"] = f"cdr:1,cd_min:{year_low}" + (f",cd_max:{year_high}" if year_high else "")
+        data = self._post("/scholar", body)
+        hits: list[SerperHit] = []
+        for item in (data.get("organic") or [])[:num_results]:
+            hits.append(SerperHit(
+                title=(item.get("title") or "")[:200],
+                url=item.get("link") or "",
+                snippet=(item.get("snippet") or "")[:600],
+                source=(item.get("publicationInfo") or "")[:200],
+                year=item.get("year") or "",
+                cited_by=item.get("citedBy") or 0,
+            ) if False else SerperHit(
+                title=(item.get("title") or "")[:200],
+                url=item.get("link") or "",
+                snippet=(item.get("snippet") or "")[:600],
+                source=(item.get("publicationInfo") or "")[:200],
+                date=str(item.get("year") or ""),
+                cited_by=item.get("citedBy") or 0,
+            ))
+        return hits
+
+    def patents(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+    ) -> list[SerperHit]:
+        """Google Patents 检索——用 site: 技巧走通用搜索。
+
+        serper.dev 没有专门的 patents endpoint，但 `site:patents.google.com` 效果很好。
+        """
+        combined = f"site:patents.google.com {query}"
+        return self.search(combined, num_results=num_results)
+
+    def news(
+        self,
+        query: str,
+        *,
+        num_results: int = 10,
+        time_range: Literal["d", "w", "m", "y"] | None = None,
+    ) -> list[SerperHit]:
+        """Google News 搜索——时效敏感行业动态。
+
+        time_range: d=24h, w=7d, m=30d, y=1y
+        """
+        body: dict[str, Any] = {"q": query, "num": num_results}
+        if time_range:
+            body["tbs"] = f"qdr:{time_range}"
+        data = self._post("/news", body)
+        hits: list[SerperHit] = []
+        for item in (data.get("news") or [])[:num_results]:
+            hits.append(SerperHit(
+                title=(item.get("title") or "")[:200],
+                url=item.get("link") or "",
+                snippet=(item.get("snippet") or "")[:600],
+                source=(item.get("source") or "")[:200],
+                date=item.get("date") or "",
+            ))
+        return hits
+
+
+if __name__ == "__main__":
+    from scripts.lib.zenmux_client import load_secrets
+    load_secrets()
+    with SerperClient() as c:
+        print("=== Patents: dual-target siRNA ===")
+        for h in c.patents("dual-target siRNA GalNAc conjugate", num_results=3):
+            print(f"  {h.title[:70]}")
+            print(f"    {h.url}")
+        print("\n=== Scholar: dual-target RNAi ===")
+        for h in c.scholar("dual-target RNAi drug 2024", num_results=3):
+            print(f"  {h.title[:70]}  [引用 {h.cited_by}] ({h.date})")
+            print(f"    {h.url}")
+            print(f"    源: {h.source[:80]}")