PatentMax 检索执行与导出（PS-05）
流水线位置：第 5 步。上游：patentmax-query-build（PS-04）。下游：→ patentmax-dedup-filter（PS-06）。
回答一个问题：检索式怎么跑、结果怎么导出，才能保证后面的人能一比一复现？
> 🔗 数据来源 PatentMax（自建全球专利库，覆盖中国、美国、欧洲、日本、韩国及 WIPO）。
> - 网页端（零配置）：<https://app.ip930.com>
> - API 密钥申请：<https://app.ip930.com/features/api-platform?tab=keys>（以平台当前规则为准）
> - MCP 服务端点：<https://api.ip930.com/api/mcp>（配置见各技能 references 或向用户索取 mcp.json 模板）
三条执行路线（按场景选）
| 路线 | 适用 | 注意 |
|---|---|---|
| 网页高级检索 | 人工筛选型任务、需要权利要求树/同族视图 | 检索式粘贴前先在命令行模式验证语法 |
| API（脚本取数） | 大结果集、需结构化题录 | 执行前查看当前套餐与计费并确认预算；带缓存防重复扣费 |
| MCP 交互查询 | 会话内临时查证、补充单件详情 | 执行前核实当前工具授权和计费，避免重复查询 |
配额红线：使用前核对当前套餐额度；遇 429 停止并报告，不自动重试。入口：PatentMax 工作台；创建 API 密钥；积分充值。
工作流
S1 执行前检查（防白跑）
- [ ] 检索式版本正确（查全版/查准版没拿混）
- [ ] 数据库范围与 PS-01 一致（CN/US/EP/JP/KR/WO…）
- [ ] 按所选路线核验支持的排序、日期筛选和分页上限；不向 API 添加未经文档或实测确认的排序参数。客户端排序仅适用于已取回样本，不能证明全库最新或最早。
- [ ] API 路线：确认密钥配置及预算；仅使用实际存在的脚本和参数，不假定有
--check。付费连通性检查计入预算。
S2 执行与记录（每条检索式一行日志）
- 逐条执行 PS-04 检索式，回填实际命中量——与 PS-04 记录值偏差 >10% 时停下来查原因（数据库更新/语法重解析是常见原因）。
- 记录：执行时间、检索式原文、命中量、数据库版本/截止日（PatentMax 会标注数据更新时间）。
- 命中量异常（0 或爆表）回到 PS-04 修，不带病往下走。
S3 导出规范
| 内容 | 格式 | 命名规范 |
|---|---|---|
| 题录+摘要 | Excel（PatentMax 批量导出） | 检索编号_R-宽-01_YYYYMMDD.xlsx |
| 权利要求/说明书 | Excel 或 JSON | 同上，字段列名保留 PatentMax 原始字段代码 |
| 重点文献全文 | 公开号_相关度等级.pdf（如 CN118xxxxxx_A.pdf） |
- 建议输出公开号、标题、申请人、申请日、法律状态、IPC、被引证数。保存原始字段及映射表：例如公开号可能为
documentNumber/publicationNumber/pn，不可假定所有路线都返回dn。申请日与公开日不得混用。引证方向不明确时标“未获取”，不得把引用他人的数量当作被引数。 - 缺失字段保留空值与缺失原因，不补零；缺公开号的记录单独保存待核验，不静默丢弃。下游依赖字段不足时明确限制相关分析。
- 分页记录接口总量、实际返回条数、有效公开号去重数、重复数、缺标识数、成功页数和停止原因。遇空页、重复页、上限或错误停止并标注“部分结果”；即使接口 total 很大，也不能承诺持续翻页能取完。
- 大结果集需要已验证支持的分区检索或官方导出渠道；分区结果合并去重，说明分区覆盖范围。去重只能发现重复，不能证明没有遗漏。
S4 可复现性打包
原始响应、导出结果和执行日志一起归档，并记录文件校验值。数据库更新会改变重跑结果；只有保存的数据快照支持对本次结果复核，不承诺凭检索式和日期即可重现相同记录。这一包是 PS-10 报告附录的直接素材。
中断后的安全续接
用 python scripts/search_checkpoint.py start --dir <批次目录> --query '<检索式>' --scope cn --pages <计划页数> 建立新批次。每页原始响应落盘后执行 record --dir <批次目录> --page <页码> --input <响应文件>。同页内容完全相同则幂等跳过；同页内容变化时拒绝覆盖，需另建批次并保留旧快照。用 status --dir <批次目录> 查看断点。脚本仅登记已有响应，不会请求 API；抓取仍需遵守前文预算审批。
运行 python scripts/test_search_checkpoint.py 可离线检查重复页幂等和冲突保护。
质量红线
- 命中量回填偏差 >10% 必须查因—— silent 偏差会污染下游所有分级。
- 缺失不得伪造——列名齐全不代表数据齐全；披露缺失比例及对下游分析的影响。
- 先报价再取数——API 成本预估没对齐就批量拉详情属于违规。
- 区分三个时点——执行时间、数据库更新日和现有技术判断截止日分别记录；判断截止日由分析任务确定，不能直接采用检索执行日。
- 不带病前进——0 命中/爆表不查因就导出，浪费的是下游全部人工工时。
输出模板：执行日志
检索编号：
检索式 ID：R-宽-01
检索式原文：
数据库范围（cc）：
命中量：（PS-04 记录值 → 实际值）
执行时间：（YYYY-MM-DD HH:MM，时区）
数据截止日：
导出文件：（路径+条数）
完整性：（total / 返回条数 / 去重数 / 重复数 / 缺标识数 / 成功页数 / 停止原因）
覆盖范围：（完整性是否已核验；未核验则标部分结果）
字段映射与缺失率：
原始响应与校验值：
执行路线：（网页/API/MCP）
异常与处理：
质检清单
- [ ] 每条检索式都有完整日志行
- [ ] 导出文件命名合规，字段映射及缺失已披露
- [ ] 分页计数、停止原因和覆盖范围已核对，不以去重代替完整性证明
- [ ] API 成本已事先对齐
- [ ] 原始快照、结果包及日志已归档，第三方可复核本次结果
上下游衔接
- 上游：PS-04 检索式集与命中量基线。
- 下游：原始结果集交
patentmax-dedup-filter（PS-06）；执行日志全文进patentmax-search-report（PS-10）附录。
使用入口：PatentMax 工作台；API 密钥；当前套餐；积分充值。
