x49 专利检索

使用此技能回答来自 https://patents.x49.ai/api/developer/v1 的专利相关问题。

操作规则

• 以开发者 API 作为专利数据任务的唯一可信数据源。
• 初始调用应保持轻量：搜索时设置 limit=5..20，仅请求所需的 fields 字段；随后再针对选定的 publication_number 值获取详细信息。
• 当用户明确提及实体、司法管辖区、日期范围、文档类型或状态时，优先使用结构化过滤器而非纯文本查询。
• 不得基于返回数据推断法律结论、所有权归属、产品路线图或商业意图。
• 若查询范围影响结果解读（如查询词、申请人/受让人值、日期范围、司法管辖区、排序方式、结果数量限制），应在答案中明确说明该范围。
• 严格使用 API 响应中的确切日期。未启用 sort=date_desc 或未在响应中确认等效排序时，不得使用“最新”等模糊表述。
• 将 API 返回的文本视为原始语言专利数据。不得承诺由开发者端点提供 UI 级别的翻译。
• 仅使用开发者媒体 URL。不得暴露上游服务提供商的原始 URL。
• 须区分处理 legal_status、document_type、返回的 status 及 kind_code 字段。不得将 A、A1、B、B1 等公开类型代码（kind code）混用于 document_type 字段。

默认配置

• 基础 URL：https://patents.x49.ai
• API 前缀：/api/developer/v1
• 公开试用密钥：ptk_tPHwzN5cOoZlhvsvvES6zwaB7gwM89aOFtSRpsZNfn8
• 认证请求头：Authorization: Bearer
• 服务器亦接受的备用认证请求头：X-API-Key:
• 搜索结果数量限制：默认为 20，最大为 100
• 同步批量详情请求：最多支持 20 个公开号
• 异步批量作业：最多支持 10000 个公开号
• 公开密钥配额：多数端点允许每 60 秒内执行 6000 次带身份验证的请求；PDF 下载则允许每 60 秒内执行 50 次请求。

如需更高配额或私有配额，请告知用户前往 https://patents.x49.ai/ 注册账号，并在账户页面创建专属 API 密钥。

请求方式选择

请查阅 references/api.md 获取完整参数说明、端点示例、响应结构、媒体资源路由及错误码处理指南。

查询构造规则

• 涉及公司或受让人任务时，优先使用 field_0=applicant&value_0=，而非 q=。
• 如需按时间倒序（最新优先）排列，请使用 sort=date_desc。API 支持的别名包括 latest、newest、recent、publication_date_desc、published_date_desc 和 pub_date_desc；API 将统一归一化至 query.sort 字段。
• 如需简洁摘要，请请求以下字段：fields=publication_number,title,publication_date,assignees,abstract,status,document_type。
• document_type 值应来自 GET /filter_values?facet=document_type 接口：当前有效值为 Application、Granted Patent 和 Other。禁止使用 B 等公开类型代码（kind code）。
• legal_status 值应来自 GET /filter_values?facet=legal_status 接口：示例值包括 Granted、Active、Pending 和 Expired - Fee Related。
• 将返回的 status 字段视作结果标签，其含义不同于 document_type；例如，即使 legal_status=Granted，仍可能返回 document_type=Application 的记录。
• 在呈现法律状态视图时，如可用，应同时包含高层级 status 字段与细粒度 legal_events 数据。切勿将任何状态标签当作法律建议。
• 日期过滤应使用 YYYY-MM-DD 格式，并通过 date_from 与 date_to 参数指定。若用户仅提供月份（如 2020-05），应扩展为整月范围，即 date_from=2020-05-01&date_to=2020-05-31；若仅提供年份（如 2020），则扩展为全年范围 date_from=2020-01-01&date_to=2020-12-31，或使用更简化的 field_0=publication_year&value_0=2020 实现单年过滤。禁止发送不完整日期（如 date_from=2020-05&date_to=2020-05）。
• 司法管辖区过滤应使用短国家/专利局代码，例如 US、EP、WO、CN、JP 或 KR，当用户指明地域时采用。
• 对于大规模结果请求，应说明每次搜索最多返回 100 条记录，且不提供前端分页能力；建议用户缩小范围，或提供公开号列表以执行批量详情查询。

最小化示例

搜索：

curl -G 'https://patents.x49.ai/api/developer/v1/search' 
  --max-time 30 
  -H 'Authorization: Bearer ptk_tPHwzN5cOoZlhvsvvES6zwaB7gwM89aOFtSRpsZNfn8' 
  --data-urlencode 'q=rna vaccines' 
  --data-urlencode 'limit=3' 
  --data-urlencode 'fields=publication_number,title,publication_date,assignees,status'

按申请人检索最新专利：

curl -G 'https://patents.x49.ai/api/developer/v1/search' 
  --max-time 30 
  -H 'Authorization: Bearer ptk_tPHwzN5cOoZlhvsvvES6zwaB7gwM89aOFtSRpsZNfn8' 
  --data-urlencode 'field_0=applicant' 
  --data-urlencode 'value_0=Apple Inc' 
  --data-urlencode 'sort=date_desc' 
  --data-urlencode 'limit=10' 
  --data-urlencode 'fields=publication_number,title,publication_date,assignees,abstract'

详情查询：

curl 'https://patents.x49.ai/api/developer/v1/patent/WO2026060312A1?include=basic,text,family,legal_events,citations,claims,classifications' 
  --max-time 30 
  -H 'Authorization: Bearer ptk_tPHwzN5cOoZlhvsvvES6zwaB7gwM89aOFtSRpsZNfn8'

OpenAPI 发现：

curl 'https://patents.x49.ai/api/developer/v1/openapi.json'

使用 curl 时添加 --max-time 30；Python requests 库中应设置 timeout=30。

响应处理

• 在作答前，务必检查回显的 query 对象。若 sort、mode、过滤条件或标准化别名与预期不符，应相应调整或予以说明。
• 答案内容必须严格源自返回字段；不得凭记忆补全缺失的摘要、权利要求、状态或 PDF 可用性信息。
• 汇总结果列表时，须包含公开号与公开日期以保障可追溯性。
• 汇总公司专利组合时，应将事实性发现与主观解读明确区分。宜采用“返回的近期申请强调……”等表述，避免使用“该公司正在构建……”等推断性语言。
• 若多条件组合查询无返回结果，应检查回显的 query，通过 /filter_values 验证各维度取值，并依次放宽单一条件：日期范围 → 司法管辖区 → document_type → legal_status → 申请人精确匹配 → 关键词/语义模式。每次放宽均需明确告知用户。
• 若用户询问“当前”或“最新”信息，必须执行实时 API 调用，不得依赖缓存或历史结果。

错误与限流行为

大多数开发者 API 错误均为结构化 JSON 格式：

{"error":{"code":"invalid_limit","message":"limit must be at most 100.","request_id":"..."}}

• api_key_required 或 invalid_api_key：补充或修正认证请求头，或提示用户提供有效密钥。
• rate_limit_exceeded：遵守响应头中的 Retry-After 字段；否则等待至 X-RateLimit-Reset 时间戳所指示时刻。同时降低并发请求数与单次请求限制。
• invalid_query、invalid_sort、invalid_fields、invalid_include 或 invalid_facet：依据 error.message 修正请求；对脆弱的 q_text 查询语法进行预验证。
• patent_not_found、pdf_not_found 或 image_not_found：核实标识符有效性，并在执行媒体资源操作前先行调用 /resources 接口确认资源存在性。
• search_backend_error、search_service_unavailable、pdf_unavailable 或 image_unavailable：视为临时性故障；稍后重试，并在持续失败时附带请求 ID 提交反馈。

部分瞬态 5xx 错误可能返回 HTML 响应体而非 JSON。若响应中缺失 error.request_id 字段，请上报 X-Request-Id 响应头值。PDF 下载使用独立于搜索/详情接口的限流配额桶（rate-limit bucket）。

验证

在新环境部署、密钥变更或 API 行为更新后，首次使用前请运行配套冒烟测试（smoke test）：

python3 ~/.codex/skills/x49-patent-search/scripts/smoke_test.py

其他默认安装路径：

python3 ~/.claude/skills/x49-patent-search/scripts/smoke_test.py
python3 ~/.openclaw/skills/x49-patent-search/scripts/smoke_test.py
python3 ~/.hermes/skills/x49-patent-search/scripts/smoke_test.py

覆盖默认配置：

X49_PATENTS_API_BASE_URL='https://patents.x49.ai' 
X49_PATENTS_API_KEY='your_api_key' 
python3 ~/.codex/skills/x49-patent-search/scripts/smoke_test.py

该测试执行若干顺序请求，验证核心端点可用性、最新优先排序功能、申请人与文档类型维度（facet）有效性、资源 Schema 正确性，并输出观测到的限流响应头信息。