espacenet-cli

欧洲专利局 Espacenet 的命令行客户端，为 Agent 而生。 检索、著录数据、权利要求、 说明书、同族、法律事件、PDF 下载、检索会话留档与报告——每条命令都支持 --json。

English TL;DR — An agent-first CLI for the EPO's Espacenet. If you use any AI agent (Claude Code, Codex, Cursor, Copilot, …), send this repo to it; the agent will audit the code, set up the environment, and install it for you. Protocol: AGENTS.md.

你只需要做一件事

把这个仓库的链接发给你的 Agent，然后说："按 AGENTS.md 的协议安装并给我演示一次检索"。

不需要你会 Python，不需要懂命令行，不需要配置任何东西。你的 Agent 会：

1. 先做安全审查——通读全部代码，检查有没有恶意注入、后门、数据外传等风险， 给你一份安全报告（只有报告干净它才继续；发现问题它会拒绝安装并告诉你为什么）；
2. 自动配置全部环境——Python、依赖库、检测本机 Edge，缺什么装什么，你无需过问；
3. 装好并演示——跑一次真实检索给你看结果。

三步全自动，这正是 Agent 时代安装软件的方式。安全审查协议全文见 AGENTS.md（你的 Agent 认识这个文件名——它是 Agent 业界通行约定）。

装好之后，对 Agent 说这些话

（你也可以自己敲 espacenet 进入交互模式；但通常没必要——交给 Agent 说人话即可。）

环境要求（仅告知，Agent 会自动搞定）

机器可读输出契约（借鉴 GitHub CLI）

Agent 与脚本依赖的不是某个命令，而是稳定的输出契约：

• stdout 只出数据，stderr 只出诊断：管道里 | jq 永远不会被进度信息污染
• --json 字段投影：--json publicationNumber,title,applicants 只输出所选字段； 拼错字段立即报错并列出该命令全部可用字段（不消耗检索配额）
• --jq 过滤：search 'ti="brake"' --json --jq '.results[].publicationNumber'， 内置 jq 常用子集（.字段 / .[] / .[N] / | 管道），零新增依赖
• 稳定性承诺：JSON 字段名只增不改；错误码（CHALLENGE_BLOCKED、 FAIR_USE_REJECTED、SEARCH_BUDGET、INVALID_PN…）与退出码（0/1/2/130）冻结； 新能力以新增字段/命令的方式交付
• 各命令可用字段目录：见 espacenet_cli/utils/format.py 的 JSON_FIELDS

对服务方的承诺（内置，无法绕过）

• 检索令牌桶：12 次突发、≈8.6 次/分钟回填、触发限流自动冷却 6-7 分钟（实测校准， 见 docs/RATELIMIT.md）；默认强制，不提供关闭开关
• 单件专利完整档案（权利要求+说明书+同族+法律+PDF）经本地缓存只耗 0-1 次检索配额
• 遵守 EPO Fair Use charter：小规模、个人/研究用途； 大规模需求请引导用户走官方 OPS API

文档

• AGENTS.md — 给 Agent 的操作手册：安装协议（安全审查→环境→安装→验证）、使用速查、贡献流程
• docs/RATELIMIT.md — 限流实测数据与效用最大化
• docs/ESPACENET-PROTOCOL.md — Espacenet 接口协议分析（维护传输层必读）
• CHANGELOG.md — 版本记录

参与维护

欢迎所有正在用 Agent 做专利检索的人——不要求会编程。两类贡献同等重要：

• 人类：提真实检索场景、验收功能、写用例；开发见 CONTRIBUTING.md
• Agent：使用中发现问题/可改进点，按 AGENTS.md 的贡献协议直接提 Issue/PR

路线图：OPS API 双后端（彻底摆脱匿名限流）→ PyPI 发布 → 多专利局适配。认领方式见 Issue 区 good first issue。

致谢

本项目按 CLI-Anything 方法论构建（历史版本曾以 cli-anything-espacenet 为名发布，0.4.0 起更名 espacenet-cli 独立发展）。

免责声明

本项目与欧洲专利局（EPO）无任何关联，非官方工具。使用即表示同意遵守 EPO Fair Use charter 与网站条款；违反导致的访问受限由使用者自行承担。

License

Apache-2.0