专利下载（patent-batch-download）

用途

用户给一份专利号清单，本技能批量抓取 PDF 全文（可选权利要求 + 说明书文本），落盘为本地文件，并生成一份带下载状态与失败原因的核对清单。

设计对象是「突发批量、平时不用」的场景：简单、可断点续传、失败可追溯，不追求花哨功能。

硬约束（任何情况下不得突破）

1. 禁止伪造。下载失败必须如实记录原因，严禁用占位文件、空 PDF 或编造的标题充数。
2. 限速。默认每次请求间隔 ≥1.5 秒 + 随机抖动，绝不并发打接口。
3. 用途限定。仅用于用户个人的研究/存档，不得转售或公开分发下载文件。
4. 密钥缺失时不猜测。没有 PatentMax 密钥就下不了中国专利，直接告知申请入口，不要换数据源硬凑。
5. PDF 有效性校验。落盘前必须确认字节流以 %PDF 开头，防止把错误页存成 .pdf。
6. 区分产品线。PatentMax（api.ip930.com，Bearer 鉴权）与知嘟嘟 API（www.iprdb.com，t= 参数）
   共用数据库但密钥不通用，混淆会得到误导性的「非法 token」。
7. 号匹配要精确，改前先跑回归。禁止用子串包含判号（target in doc 会让错号命中真号，
   静默下错专利）。动 normalize / match_patents / pick_variant / done_key 之前和之后
   都必须跑 python scripts/test_match.py——离线、免费、58 个用例。

通道路由（已实测，勿凭印象改动）

元数据（标题/申请人/法律状态/公开日）统一由 PatentMax /api/search 补齐，中、美都能查到，
所以美国通道的清单字段同样完整。检索必须先于下载——documentDate 是拼 PDF 路径的必要输入。

完整端点、实测样本、失败原因见 @references/endpoints.md。改动任何端点前必须先重读该文件并重新实测。

密钥配置（三选一，优先级从高到低）

1. 命令行 --token
2. 环境变量 PATENTMAX_TOKEN
3. config.json 的 patentmax_token 字段（该文件在 skill 根目录，不在 scripts/ 下；技能包内只带 config.example.json，复制一份改名为 config.json 再填入自己的密钥）

首次使用：获取免费密钥（约 2 分钟）

技能包不附带任何密钥。每个使用者用自己的 PatentMax 密钥，额度互不相干：

1. 注册/登录 PatentMax 开放平台 https://api.ip930.com（新用户前 30 次检索免费，注册约 2 分钟）
2. 进入「API 密钥」页 → 填一个名字（如 专利下载）→ 下拉框选 生产密钥 → 点「创建」
   - ⚠️ 生产密钥按实际调用计费；测试密钥不计费但只返回示例数据，选错会下到假文件
3. 复制生成的 pm_live_... 密钥，按上面三种方式任选其一配置

成本预期（务必提前告知用户）

• 美国专利：0 成本（USPTO 官方直连，不消耗任何额度、无需注册）
• 中国专利：按次计费——每条至少消耗 1 次检索，外加 PDF 下载的调用次数；新用户前 30 次检索免费，之后具体单价以 PatentMax 开放平台「计费与套餐」页为准
• 额度没有公开查询接口，只能登录控制台「查看用量与账单」；批量前建议先确认余额
• 余额耗尽的表现：所有接口（含检索）统一返回 409 CONFLICT / API 余额不足，当前 ¥0.00。
  脚本识别到该状态会立即停止发请求，把剩余条目如实记为「未执行」并打印醒目提示——
  别把它误判成通道故障或号码问题。充值后重跑同一命令即可续上（已下载的自动跳过）
• --text（抓权利要求/说明书全文）额外消耗 2–4 次/条，按需开启
• 批量前可用 --max-calls N 设一个硬上限兜底（额度查不到，只能自保）；
  脚本按「检索 1 + PDF 1（--text 再加 3）」预留每条预算，预算不足的条目直接标「未执行」，
  不会出现钱花了、文件没拿到的空跑

网络与安全

• TLS 默认开启证书校验。密钥以 Authorization: Bearer 头发送，不校验等于把它交给中间人；
  早期版本无条件 CERT_NONE 是没必要的降级（实测本机严格校验直接可用）。
  脚本启动时探测一次：校验通过就用严格模式（日志打印 TLS：证书校验已开启）；
  仅当本机证书链确实不可用（企业代理 / 自签 CA）时才降级，并打印醒目警告。
  强制关闭：PATENT_DL_INSECURE_TLS=1（不推荐）。
• 有限重试：对 429/500/502/503/504 与连接超时自动重试 2 次（退避 2s、4s）。
  GET 幂等，重试不会重复计费出两份文件；<u>不</u>重试 4xx 业务错误（如密钥、参数类）。
• 密钥/额度类错误（TOKEN/UNAUTHORIZED/FORBIDDEN/额度）立即冒泡终止该条，
  不做无意义重试，也不退化成别的数据源硬凑。

固定流程

第 1 步 · 清单确认

拿到清单后先问清三件事（一次性问完，不要挤牙膏）：
1. 号码形态：公开号、申请号、带不带国家码、带不带小数点都能吃，详见下表。
只有真歧义的形态才需要和用户确认。
2. 是否需要文本版全文（权利要求/说明书）：默认不抓；需要时加 --text，按次计费。
3. 输出目录与命名：默认 ./patents/，文件名为库内标准号（如 CN114824336B.pdf）。

号段写法兼容表（2026-09-14 实测）

同一件专利，用户可能上传成下面任意一种写法，脚本都能识别，且归并成一条（不会各下一遍）：

判定依据（不要凭印象改）：

• 中国公开号是 9 位（2003 年起）；美国公告号最长 8 位、申请公开号 11 位
  → 所以 9 位只能是中国公开号，7–8 位才是中/美真歧义。
• 中国申请号是 13 位 = 4 位年 + 8 位序号 + 1 位校验位；去掉校验位是 12 位
  → 12/13 位只可能是中国申请号，无歧义，脚本自动归一并按 CN 走 PatentMax。
• 校验位是前 12 位的确定函数：各位乘权重（2,3,4,5,6,7,8,9 循环）求和后对 11 取模，10 记作 X。
  已用 3 个真实申请号验证：202010783517→8、202111491053→4、202310894263→0。
  两个用途：给缺校验位的 12 位号补全；发现抄错（如 2026112241731 会提示
  「校验位对不上，按前 12 位应为 .0」）。脚本只警告不改号——静默改号会下到另一件专利。
• 7–8 位纯数字按美国号处理会得到「USPTO 404 + 检索 0 命中」的双重失败，
  所以这类必须停下来问用户，不可擅自下载。

第 2 步 · 试运行

python scripts/patent_dl.py --nums "US11000000B2,<用户的一条CN号>" --out ./patents --dry-run
python scripts/patent_dl.py --nums "<挑 2-3 条>" --out ./patents

确认通道路由正确、PDF 真能落盘，再跑全量。

> 解释器：想同时拿到 _manifest.xlsx 就得用装了 openpyxl 的解释器，例如隔离 venv
> ~/.workbuddy/binaries/python/envs/default/Scripts/python.exe（Windows）或 /bin/python。
> 用裸 python 且没装 openpyxl 时脚本只出 CSV 并提示——不是错误，但少了 Excel 交付物。

> 改匹配逻辑前先跑回归：python scripts/test_match.py
> 58 个离线用例覆盖：公开号/申请号的 20 余种写法（含带国家码、缺校验位、全角、带空格）、
> 13 位申请号、显式种类码、纯数字美国号、错号不得误命中、--variant 取值、
> 校验位算法（3 个真实号）与「抄错校验位要报警」、同族写法归一键。
> 不联网、不消耗额度。号匹配出错会静默下错专利，比下载失败严重得多，
> 必须能在不花钱的前提下验。

第 3 步 · 全量执行

python scripts/patent_dl.py --list 清单.txt --out ./patents --max-calls 200

--variant：同一申请号往往不止一篇

按申请号检索，库内常返回两篇：CN111735730A（申请公布，2020-10-02）与
CN111735730B（授权公告，2020-12-08）。旧版静默取第一篇，用户想要可主张的授权文本时拿到的是公开文本。

无论取哪篇，命中多篇时都会在日志里打印全部候选与公开日，不做静默取舍。

第 4 步 · 核对与交付

每次运行结束后必须向用户报告，不得只说"完成了"：
- 成功 / 失败 / 跳过（已存在）条数
- 失败条目逐条列出原因（检索未命中、该地区无通道、接口 503 等）
- 消耗的 API 调用次数估算，并提示以 PatentMax 控制台账单为准
- 清单文件路径（_manifest.csv / _manifest.xlsx）

断点续传

重跑同一命令只补失败的。判断走 _manifest.csv 里「状态=成功 且 PDF 仍以 %PDF 开头」的行
（键是归一化后的号码：2020107835178、202010783517.8、CN202010783517.8 视为同一条），
不是按输入号去找文件名——下载成功后文件已重命名为标准号（CN111735730A.pdf），
按输入号找必然落空、白扣额度。
清单幂等：同键重跑覆盖原行，不会堆重复记录。行键优先用标准号，
所以 --variant all 下 A/B 两篇各占一行、互不覆盖。

同一件专利不会被重复下载，三层保障：

> 想同时要 A、B 两篇时，用 --variant all，或在清单里显式写 CN…A 与 CN…B
> ——显式点名要另一篇时不会被上述规则拦下。

续传分三级，目的是「能省则省，但不能省错」：

缺哪样补哪样：PDF 已在本地就只抓 --text 全文，不存在就只抓 PDF，都齐才整体跳过。
「后来才想加 --text」不会把 PDF 重买一遍。

> 取舍：0 次调用那两条会沿用清单里已有的元数据。若清单被清空或换了输出目录，
> 跳过项就只记路径、标题/申请人留空——想补齐字段就重跑一次（每条多花 1 次检索）。
> 省钱优先，因为额度不可查、也退不回来。

扩写号段支持（维护指南）

用户又传来一种没见过的写法时，照这个顺序改。不要直接改代码试——号解析错了会静默下错专利，
必须先能在不花钱的前提下验证。

改动的落点只有 4 处，全在 scripts/patent_dl.py：

固定流程：

1. 先写用例：往 scripts/test_match.py 的 PARSE_CASES（解析契约）或 CASES（比对结果）
   里加一行，写明期望值。此时跑 python scripts/test_match.py 应当是 FAIL —— 这才叫复现了问题。
2. 改上面 4 处里对应的那一处，再跑 python scripts/test_match.py，必须 全部通过。
3. --dry-run 演练一次真实写法，确认通道路由与提示语对：
   bash python scripts/patent_dl.py --nums "<新写法>,<旧写法>" --out ./.tmp-fmt --dry-run
   同一件专利的多种写法应当打印 [去重] … 与前面的写法指向同一件专利，跳过。
4. 更新本文档的号段写法兼容表与故障速查表。

踩过的坑（改之前先读一遍）：

• 种类码绝不能丢。^([0-9]+)([A-Z]?)$ 会把 US9000000A 吃成 num='9000000A'，
  种类码没了 → 404。号码段与种类码必须分开捕获。
• 禁止子串包含判号。"1234567" in "US12345678B2" 为真 → 静默下错文件。
• 加国家码前缀要兼容两种含义：CN 后面是 9 位=公开号，是 12/13 位=申请号。
• 不要替用户静默改号。校验位对不上就如实报警告，让人确认；自动纠正会下到别的专利。
• 去重比字面字符串要不得：2026112241730 与 202611224173.0 是同一件，
  必须按 done_key() 归一后比。
• 改 normalize() 的 note 文案时注意，route() 用 note.startswith("缺国家代码") 分流，
  改文案要同步改判断。

新增一个国家通道（例如将来 EP 有源了）：在 route() 里给出主通道，在 references/endpoints.md
记下实测样本与失败原因，并把 SKILL.md 的通道表更新。没有实测过的通道不要写进表里。

用户需要提供什么

已知局限（必须主动告知用户）

• PDF 是扫描图像版：不可检索、不可复制。下游要做文本分析必须用 --text 抓结构化全文。
• 同一申请号常有 A/B 两篇（申请公布 + 授权公告）。默认 --variant auto 取公开日最晚的一篇，
  即通常意义上的授权文本；若用户明确要申请公布版，用 --variant first（或 all 两篇都要）。
• 只有中国专利有 PDF 自动通道。美国靠 USPTO 免费直连；EP/WO/JP/KR 目前下不了。
  USPTO 直连按公告号取值，无法指定同号的其他篇目（--variant all 时第二篇会如实记为失败）。
• 额度无法通过 API 查询，只能看网页控制台。批量前建议先确认余额。
• seq 位规律来自 8 个样本（恒为 1）。若遇到 503，先确认 documentDate 是否正确，
  再人工核对 https://app.ip930.com 上的原文链接。
• 国知局 epub 在沙箱内测不准，真实网络下可能是中国的免费替代通道，待重测。

故障速查