From c444007f04fdf487236e0f712c63c1e108543699 Mon Sep 17 00:00:00 2001 From: kai Date: Wed, 22 Apr 2026 17:04:05 +0800 Subject: [PATCH] =?UTF-8?q?v0.8:=20Serper=20=E9=9B=86=E6=88=90=20+=20H1=20?= =?UTF-8?q?=E7=AB=A0=E8=8A=82=E6=A0=87=E9=A2=98=E5=8F=8C=E8=A1=8C=E5=B1=85?= =?UTF-8?q?=E4=B8=AD=20+=20=E5=8F=8D=E6=96=B9=E8=AF=81=E6=8D=AE=E8=A7=82?= =?UTF-8?q?=E7=82=B9=E5=8C=96=20+=20=E6=9C=AF=E8=AF=AD=E6=A0=B8=E6=9F=A5?= =?UTF-8?q?=E5=91=BD=E4=BB=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增：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 章 多种形式都识别）。 --- .opencode/agents/dr-analyst.md | 2 +- .opencode/commands/dr-glossary.md | 60 +++++++ .opencode/skills/evidence-table/SKILL.md | 44 ++++- .opencode/skills/search-strategy/SKILL.md | 79 ++++++--- .opencode/templates/report-template.py | 92 ++++++++++- scripts/lib/search_client.py | 113 +++++++++++-- scripts/lib/serper_client.py | 190 ++++++++++++++++++++++ 7 files changed, 539 insertions(+), 41 deletions(-) create mode 100644 .opencode/commands/dr-glossary.md create mode 100644 scripts/lib/serper_client.py diff --git a/.opencode/agents/dr-analyst.md b/.opencode/agents/dr-analyst.md index ef45a95..a8dc707 100644 --- a/.opencode/agents/dr-analyst.md +++ b/.opencode/agents/dr-analyst.md @@ -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) diff --git a/.opencode/commands/dr-glossary.md b/.opencode/commands/dr-glossary.md new file mode 100644 index 0000000..b646a11 --- /dev/null +++ b/.opencode/commands/dr-glossary.md @@ -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//phase1/framework.md` 抽取所有 H2/H3 标题 + 表格中的英文机构名、技术名、药物名。保存到 `projects//phase2/terms.txt`（一行一个）。 +- `--from phase2`：从 `projects//phase2/drafts/*.md` 抽取所有高频英文专有名词（首字母大写、不在常见词词典）。 +- `--from phase4`（默认）：直接用 `projects//phase4/glossary.json`。 + +### Step 3: 调用 build_glossary.py + +```bash +uv run python scripts/build_glossary.py --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 ` 把修正回塗到正文 + +## 注意事项 + +- build_glossary 需要网络访问，Serper 和 Exa 都需要代理。如遇 SSL EOF，降 `--workers 3`。 +- Haiku 对极专业或极新兴术语（如 "muRNA", "SBS linker"）的判断可能不准，低置信度的条目必须人工复核。 +- 别对通用缩写（PDE/ASGPR/LNP）作自动替换——apply_glossary 已有黑名单，但核查结果在 glossary.json 里仍会体现。 diff --git a/.opencode/skills/evidence-table/SKILL.md b/.opencode/skills/evidence-table/SKILL.md index e0ce692..9661ed9 100644 --- a/.opencode/skills/evidence-table/SKILL.md +++ b/.opencode/skills/evidence-table/SKILL.md @@ -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]。影响评估：<说明> + +综合而言，核心结论仍成立，但需在 <某个具体维度> 上留出缓冲。 +``` + +### 禁止的写法 + +- 单独用 **加粗段** 冒充反方证据标题（`**反方证据：** ...`） +- 反方证据后不做整合判断，只是堆数据 +- 在每个小节末尾都加反方证据（只在章末加一次即可；若小节级别有重大挑战，写在小节正文里即可） + +--- + ## 置信度分级标准 | 置信度 | 条件 | 正文处理方式 | diff --git a/.opencode/skills/search-strategy/SKILL.md b/.opencode/skills/search-strategy/SKILL.md index 6dbef6c..27f27da 100644 --- a/.opencode/skills/search-strategy/SKILL.md +++ b/.opencode/skills/search-strategy/SKILL.md @@ -82,39 +82,74 @@ description: 生物医药深度研究的统一检索策略。规定信源优先 --- -## 三、API 调用顺序（技术栈） +## 三、API 调用顺序（技术栈，v0.8 更新） + +**按"查询类型"路由到最合适的 API**，而不是一律走通用搜索。 ``` -┌─────────────────────────────────────────────┐ -│ Phase 1 初扫（dr-searcher 用） │ -│ ├── tavily (MCP) — 快速宽扫 │ -│ ├── brave (MCP) — 交叉验证 │ -│ └── exa (MCP) — neural search │ -│ │ -│ 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 继续用 │ -│ │ -│ Phase 2 反验（dr-verifier 用） │ -│ └── 与 analyst 相同但查反向关键词 │ -└─────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ 查询类型 首选 备选 │ +├──────────────────────────────────────────────────────────────┤ +│ 专利 Serper Patents Google Patents 爬页 │ +│ (site:patents.google.com) │ +│ │ +│ 学术论文 Serper Scholar PubMed E-utils │ +│ (带引用数/年份/期刊) (原始数据库) │ +│ │ +│ 新闻 / 行业动态 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 列表 diff --git a/.opencode/templates/report-template.py b/.opencode/templates/report-template.py index d76e6c5..d0b74bb 100755 --- a/.opencode/templates/report-template.py +++ b/.opencode/templates/report-template.py @@ -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(?:第\s*[一二三四五六七八九十百零〇两廿卅\d]+\s*章)|(?:Chapter\s+\d+))" + r"\s*[—–\-：:]\s*" + r"(?P.+?)\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"])) diff --git a/scripts/lib/search_client.py b/scripts/lib/search_client.py index 3bf6807..4fe3e88 100644 --- a/scripts/lib/search_client.py +++ b/scripts/lib/search_client.py @@ -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,18 +170,12 @@ 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: - # 其它错误继续往下试 - pass + except SearchError: + pass if self._tavily: try: return self._tavily.search(query, num_results=num_results) @@ -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]}") diff --git a/scripts/lib/serper_client.py b/scripts/lib/serper_client.py new file mode 100644 index 0000000..2916eaf --- /dev/null +++ b/scripts/lib/serper_client.py @@ -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]}")