patent-checker

专利检查器

日语版：README_ja.md

Patent Checker 可帮助你查找可能与你的软件项目相关的已公开专利，并将发现记录为带日期的流程式报告。它旨在针对同一项目多次运行——无论是在构思阶段、开发期间、发布前还是每次更新前：后续运行只搜索新内容、重新检查你正在监控的专利，并告知你自上次运行以来有哪些变化。它由两部分构成：

• 一个 MCP 服务，以确定性方式获取公开专利数据（EPO Open Patent Services 和 Google Patents）：搜索结果、书目信息、权利要求、法律状态、专利家族，以及离线辅助工具；以及
• 一个 Agent Skill，引导你的 AI 编码 Agent（Claude Code、Codex CLI、Cursor、Gemini CLI、GitHub Copilot CLI、OpenCode、OpenHands、Hermes Agent）完成判断工作：阅读你的代码库、将其中的功能转换为专利术语、筛选候选专利并撰写报告。

Patent Checker 不会判断任何内容是否侵犯专利。它的报告包含观察结果、范围说明和待解问题，绝不会给出结论。

状态：稳定版（v1.4）。

重要通知

安装任何内容前，请先阅读以下通知。该工具会要求你确认一次，并记录确认结果。

• 你在这里获知的信息可能会对你不利。 报告会记录你在特定日期知悉了特定专利。在某些司法管辖区，尤其是美国，知晓某项专利可能成为认定故意侵权并判处加重赔偿的依据。记录你如何应对及其日期，也可能对你有利。Patent Checker 允许你选择记录的存放位置，以及是否将其纳入版本控制：请慎重作出选择。
• 搜索结果并不完整。 没有任何专利搜索是穷尽无遗的。覆盖范围因国家、语言、公开阶段和数据源而异，近期申请可能完全缺失。报告中没有某份文件，绝不能证明不存在相关专利。
• 这只是搜索辅助工具，不是法律建议。 Patent Checker 不能替代具备资质的专利律师或代理人，其作者不对基于其输出所作或未作的决定承担责任。关于你的项目的最终判断以及对此作出的任何回应，均由你负责。

本工具有两项通知。用户通知（以上三点）会由 Skill 向进行检索的用户展示，也会在安装程序开始时展示；你的确认记录会保存在本地，并在每次运行前检查。运营者通知面向启动服务的人员，涉及数据源条款、凭据以及服务会存储的内容；在确认该通知前，服务不会启动。

工作原理

your agent ──(Skill: judgment)──► patent-checker MCP server ──► EPO OPS
   │                                   │  deterministic fetch,      Google Patents
   │  reads your code, writes           │  normalization, cache
   ▼  the report                        ▼
.patent-checker/reports/…        shared document cache

1. Skill 会读取你的代码库，列出可能作为专利主张的技术特性；将常见技术（标准、库或平台原样提供的内容）排除在搜索之外，并在报告中说明；将其余内容转换为专利术语并构建搜索查询。
2. MCP 服务会通过 EPO OPS 执行查询，获取候选文档（从 Google Patents 获取权利要求，从 OPS 获取书目信息和法律状态），并缓存每份文档，避免重复获取。
3. Skill 会分阶段筛选候选项，将权利要求要素映射到你的特性，并撰写报告：搜索了什么、发现了什么、每个候选项与你的代码有何关联，以及哪些内容未涵盖。
4. Skill 还会在你的项目中保留一份探索台账（特性、查询、筛选过的专利族、监控中的专利及其状态快照）。下次运行时会从台账开始：服务会将存储的快照与当前记录进行比较，新报告会先给出一份不含专利术语的摘要，然后说明发生了哪些变化。

服务接收的始终只有公开专利数据：搜索表达式、公开编号、专利族标识符、日期，以及它此前返回的状态快照。你的源代码、项目说明和台账不会离开你的设备：分析过程在你的 Agent 内部进行。

先决条件

• 支持 Agent Skills 和 MCP 的 AI 编码 Agent：Claude Code、OpenAI Codex CLI、Cursor、Gemini CLI、GitHub Copilot CLI、OpenCode、OpenHands 或 Hermes Agent。
• uv，用于命令行工具和安装程序；如果你的设备上没有 Python，uv 会自行获取 Python 3.12 或更新版本。生成下文中的 bearer token 时，使用 Python 也最方便。
• Docker with Compose v2，如果你要在容器中运行服务（推荐）。没有 Docker 时，服务会作为普通进程运行。
• EPO Open Patent Services 账号（推荐）。在 https://developers.epo.org/ 注册，然后创建应用以获取 consumer key 和 secret。**请尽早申请：审批由人工处理，通常需要约 1 个工作日。**如果没有账号，服务会以降级模式运行。

bearer token

服务通过 HTTP 进行监听，每个 MCP 客户端都必须在每次请求中提供一个 bearer token：只有你的服务和你自己的 Agent 知道的秘密字符串。它可以阻止设备上的其他程序，或在你将端口暴露到网络时阻止网络上的其他程序，使用你的服务和 EPO OPS 配额。它不依赖账号或注册；你只需自行生成一次 token，并将相同的值提供给服务和安装程序。

生成一个（任意 32 个随机字节即可）：

python3 -c "import secrets; print(secrets.token_urlsafe(32))"      # macOS, Linux

python -c "import secrets; print(secrets.token_urlsafe(32))"       # Windows

保存位置：

• Docker Compose：放入 compose.yaml 旁的文件 secrets/server_token.txt。
• 不使用 Docker 时：放入 .env，设置为 PATENT_CHECKER_SERVER_TOKEN=…（或放入由 PATENT_CHECKER_SERVER_TOKEN_FILE 指定的文件）。
• 你的 Agent：patent-checker install 会提示你输入 token（或从 --token-file 读取），并将其写入每个 Agent 的 MCP 配置。

没有 token 时，HTTP 服务不会启动。唯一的例外是 patent-checker serve --transport stdio：此模式不需要 token，因为 Agent 会以你自己的权限将服务作为子进程启动；这是针对单个本地客户端的特殊情况，并非默认方式。请像对待密码一样保管 token：确保存放它的文件安全私密；如需轮换，请写入一个新值并重新运行 patent-checker install。

未拥有 EPO OPS 账号（降级模式）

如果不设置 OPS 凭据（secrets/ops_key.txt 和 ops_secret.txt 为空，或 .env 中没有 PATENT_CHECKER_OPS_KEY），服务器 会以降级模式启动，并在启动时和 server_status 中说明这一点。

• 仍可使用：当 Agent 已知文献的公开编号时，从 Google Patents 获取权利要求；公开编号规范化；离线辅助功能（去重、批量验证）。
• 不可用：专利搜索、书目信息、法律状态和专利族。技能会切换到降级流程，由 Agent 自行通过网页搜索查找候选公开编号；覆盖范围会缩小，报告也会说明这一点。

降级模式适合初步查看。如需进行真正的探索，请获取 OPS 账号，并在设置好凭据后重启服务器。

安装服务器

两种方式都需要确认已阅读运营者须知，并设置 bearer token。

选项 A：Docker Compose（推荐）

mkdir patent-checker-server && cd patent-checker-server
curl -fsSLO https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/compose.yaml
mkdir secrets

# 1. EPO OPS credentials (or leave both files empty for degraded mode)
printf '%s' 'YOUR_OPS_CONSUMER_KEY'    > secrets/ops_key.txt
printf '%s' 'YOUR_OPS_CONSUMER_SECRET' > secrets/ops_secret.txt

# 2. The bearer token (see above)
python3 -c "import secrets; print(secrets.token_urlsafe(32))" > secrets/server_token.txt
chmod 600 secrets/*.txt

# 3. Read the operator notice (add --lang ja for Japanese), then acknowledge it
docker compose run --rm patent-checker serve --show-operator-notice
echo 'PATENT_CHECKER_OPERATOR_CONSENT=1.0' >> .env

# 4. Start
docker compose up -d
curl -fsS http://127.0.0.1:8642/health

在 Windows 上，请用 PowerShell 创建这三个文件，而不要使用 printf （Set-Content 会写入字节顺序标记，导致其成为 token 的一部分，因此请直接使用 .NET）：

New-Item -ItemType Directory -Force secrets | Out-Null
New-Item -ItemType File -Force secrets\ops_key.txt, secrets\ops_secret.txt | Out-Null   # empty: degraded mode
$token = python -c "import secrets; print(secrets.token_urlsafe(32))"
[IO.File]::WriteAllText("$PWD\secrets\server_token.txt", $token)

镜像发布于 ghcr.io/xhighhongo41/patent-checker 和 docker.io/xhighhongo41/patent-checker，标签为 X.Y.Z、X.Y 和 latest。容器内部绑定到 0.0.0.0，但 Compose 只会将端口发布到你本机的环回地址（127.0.0.1:8642）。服务器接受的 Host 标头包括环回名称 localhost、127.0.0.1 和 ::1（HTTP 层始终允许这些名称），以及通过 PATENT_CHECKER_SERVER_ALLOWED_HOSTS 添加的任何名称——除此之外均不接受。 获取的文档、搜索结果和请求日志存放在命名卷 patent-checker-data 中。容器以非特权用户身份运行，使用只读文件系统，并移除所有 Linux 功能；如果你的 Docker 引擎拒绝其中某项设置，可以删除 compose.yaml 中 # Hardening 下的四行，而不会改变服务器的行为。

密钥文件只在启动时读取一次；OPS 文件为空表示“未配置”（降级模式）。如果你在 Linux 上使用的 Docker Engine 账号 UID 不是 1000，请参阅 secrets/README.md 中关于文件所有权的说明。

如需在多台设备之间共享一台服务器（tailnet、VPN、LAN），请参阅 docs/deploy-lan.md：其中介绍了 Tailscale Serve、在同一容器前配置 TLS 终止代理，以及在专用网络上使用纯 HTTP，并说明了这些方式各自需要你自行处理的事项。

选项 B：不使用 Docker

uv tool install patent-checker
mkdir patent-checker-server && cd patent-checker-server
curl -fsSLO https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/.env.example
cp .env.example .env

然后编辑 .env：

1. 将 EPO OPS 密钥和密文填入 PATENT_CHECKER_OPS_KEY 和 PATENT_CHECKER_OPS_SECRET（降级模式下请留空）。
2. 生成 bearer token（见上文），并填入 PATENT_CHECKER_SERVER_TOKEN。
3. 使用 patent-checker serve --show-operator-notice 阅读运营者须知 （如需日语，请添加 --lang ja），并设置 PATENT_CHECKER_OPERATOR_CONSENT=1.0。

最简 .env 文件如下：

PATENT_CHECKER_OPS_KEY=YOUR_OPS_CONSUMER_KEY
PATENT_CHECKER_OPS_SECRET=YOUR_OPS_CONSUMER_SECRET
PATENT_CHECKER_SERVER_TOKEN=the-token-you-generated
PATENT_CHECKER_OPERATOR_CONSENT=1.0

使用 patent-checker serve 启动服务器。它通过 http://127.0.0.1:8642/mcp 提供 Streamable HTTP 服务。服务器会从你启动时所在的目录及其父目录中查找 .env，但不会继续查找到主目录或文件系统根目录；环境中已有的变量优先。数据存储在每用户的数据目录中（Linux 和 macOS 上为 ~/.local/share/patent-checker，Windows 上为 %LOCALAPPDATA%\patent-checker）。如果端口已被占用，服务器会停止并显示提示；请使用 --port 选择其他端口，并向你的 Agent 注册该 URL。

--transport stdio 会在不使用网络端口且无需 token 的情况下运行服务器，仅供单个本地客户端使用；此时服务器会以你的用户权限运行，因此默认使用 HTTP。有关如何向 Agent 注册，请参阅 docs/mcp-clients.md。

安装 Skill 并连接 Agent

引导脚本会安装命令行工具；patent-checker install 会完成其余工作——向用户显示通知，将 Skill 复制到 Agent 会读取的位置，并向它们注册 MCP 服务：

curl -LsSf https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/install.ps1 | iex"

这两个脚本都会安装 uv 和该工具，然后继续运行 patent-checker install。像上面这样通过管道传入 sh 时，Shell 脚本的 标准输入是管道，因此它会改为在终端中提问；只有在完全没有终端时（例如 CI 任务），它才会停止并打印供你接下来运行的 patent-checker install 命令。

想先阅读脚本？使用 | more 而不是 | sh 来获取脚本， 或者完全跳过脚本——它执行的两个步骤是：

uv tool install patent-checker
patent-checker install

patent-checker install：

1. 显示用户通知并征求你的同意（记录在 ~/.config/patent-checker/consent.json 中，包括日期和通知 版本；只有通知发生变化时才会再次询问）；
2. 询问 bearer token（或从 --token-file 读取）；
3. 将 Skill 复制到 ~/.agents/skills/patent-checker/（供 Codex CLI、OpenCode、Cursor、Gemini CLI 和 Copilot CLI 读取），并复制到需要 Skill 的 Agent 的私有目录中（~/.claude/skills/、 ~/.openhands/skills/、~/.hermes/skills/）；
4. 向每个检测到的 Agent 注册服务（除非传入 --url，否则使用 http://127.0.0.1:8642/mcp），优先使用 Agent 自带的 mcp add 命令（Claude Code、Gemini CLI、Copilot CLI、带有 --token-env 的 Codex CLI）；否则编辑 Agent 的 JSON 或 TOML 配置（Cursor、OpenCode、Codex CLI）；对于不会修改其配置的 Agent（Hermes Agent，以及未安装其 CLI 时的 OpenHands），则打印供粘贴的配置片段；
5. 打印一张表格，列出对每个 Agent 执行的操作。任何步骤失败时，退出码都不为零；打印配置片段不算失败。

Agent	注册方式	配置文件
Claude Code	claude mcp add	用户设置（使用 --scope project 时为 .mcp.json）
Gemini CLI	gemini mcp add	~/.gemini/settings.json
GitHub Copilot CLI	copilot mcp add	~/.copilot/mcp-config.json
Cursor	原地编辑	~/.cursor/mcp.json
OpenCode	原地编辑	~/.config/opencode/opencode.json
Codex CLI	codex mcp add / 追加	~/.codex/config.toml
OpenHands	openhands mcp add（未安装 CLI 时粘贴配置片段）	由 OpenHands CLI 管理
Hermes Agent	粘贴配置片段	~/.hermes/config.yaml

如果设置了 XDG_CONFIG_HOME，OpenCode 会使用该路径。Gemini CLI、 Copilot CLI 和 OpenHands 命令的用法遵循其文档说明，但尚未在真实工具中测试；如果其中某个命令失败，安装程序会改为编辑文件或提供配置片段，并说明情况。

实用选项：--list-agents（显示将安装到哪些位置）， --dry-run（执行所有操作，但不写入），--agent claude-code --agent cursor （不自动检测；使用 --agent all 可选择所有受支持的 Agent）， --scope project（安装到当前项目，而不是你的主目录）， --lang ja（日语通知），--agree（无需询问即可同意通知——没有终端可供提问时必须使用）， --no-skill / --no-mcp、--json（将报告作为单个 JSON 文档打印， 供脚本使用；此时通知和问题会输出到标准错误）。 重新运行安装程序是安全的：它会刷新 Skill 副本，并原地更新服务条目；首次运行时创建的原始配置文件备份（.bak）永远不会被覆盖。唯一的例外是 Codex CLI：它会保留现有条目；如需更改，请编辑 ~/.codex/config.toml。

在不暴露令牌的情况下传递 bearer 令牌

安装程序绝不会将令牌作为命令行参数，因此令牌不会出现在你的 shell 历史记录中。通过以下任一方式提供令牌：

patent-checker install --token-file /path/to/secrets/server_token.txt
# or
export PATENT_CHECKER_SERVER_TOKEN="$(cat /path/to/secrets/server_token.txt)"
patent-checker install
# or just run it: the installer prompts for the token without echoing it

默认情况下，令牌值会写入各 Agent 自己的配置文件，并将文件设为只有你能读取（在 Windows 上，文件会保留其常规权限）。使用 --token-env 时，安装程序完全不需要令牌值：它会按照各 Agent 支持的格式，写入对 PATENT_CHECKER_SERVER_TOKEN 环境变量的引用；你需要在启动 Agent 前导出该变量。Copilot CLI 和 OpenHands 没有记录对此类引用的支持，因此 --token-env 会改为打印相应片段。使用 Agent 自带的 CLI 进行注册时，令牌会在调用期间出现在该进程的参数中。

使用 --scope project 时，保存令牌的配置文件会写入项目目录中。安装程序会提醒你：不要提交该文件。

安装程序打印的注册命令和代码片段绝不会包含令牌；它们会使用 ${PATENT_CHECKER_SERVER_TOKEN} 或占位符。

如果服务返回 401

401 表示 Agent 发送的令牌与启动服务时使用的令牌不一致。请比对两者：服务端令牌位于 secrets/server_token.txt 或 .env；Agent 端令牌位于上表中的配置文件中（Claude Code 可通过 claude mcp get patent-checker 显示令牌）。确保 <token> 之类的占位符没有被原样注册。服务未运行时会产生 connection refused 错误，而不是 401，因此两者很容易区分。

手动注册

各 Agent、GitHub Copilot 编码 Agent 以及 stdio 形式所需的确切命令或文件见 docs/mcp-clients.md。

仅使用手机的 Agent 和云端 Agent

将 Skill 提交到你的代码库中，路径为 .agents/skills/patent-checker/（运行 patent-checker install --scope project --no-mcp，然后将该目录添加到 git），并在云端 Agent 可通过 HTTPS 访问的位置运行服务（见 docs/deploy-lan.md）。同意记录按用户保存；如果云端 Agent 的主目录被重置，它会在下次运行时重新记录同意，或者使用 patent-checker consent record --project 将记录保存在项目中。

用法

请 Agent 探索其当前所处理项目的相关在先专利：

使用 patent-checker skill 探索与此项目相关的在先专利。

Skill 会先检查同意记录，并询问是否应将 .patent-checker/ 添加到 .gitignore（每个项目只询问一次），然后按照上述步骤执行，并将报告写入 .patent-checker/reports/report-<target>-<YYYYMMDD-HHMM>.md。报告绝不会被覆盖；同一项目后续运行时会生成新的、带日期的文件。<target> 是受检对象的名称——除非你和 Agent 商定使用其他名称，否则就是代码库的名称；每个受检对象都会在 .patent-checker/ledger/<target>/ 下保存自己的记录。整个会话期间，请保持服务运行。

规模与成本。 对一个中等规模的项目进行一次探索，涉及阅读代码、进行一轮或多轮搜索，以及分阶段筛选数十份候选文档。预计会消耗约百万级的 Agent 通信令牌（开发期间使用 Claude Code 在中等规模项目上测得），其中大部分用于筛选；如果 Agent 支持委派，Skill 会将第一阶段筛选交给较小的模型。一次运行并不能做到穷尽：多次运行、采用不同的查询词汇，以及进行专业搜索，都能发现单次运行无法找到的内容。

再次运行

每当项目有进展，或报告中下次检查的日期已到时，都可以再次询问：

使用 patent-checker 技能，跟进对此项目的早期探索。

该技能会在 .patent-checker/ledger/<target>/ 下找到记录，并提出两种运行方式之一：

• 跟进运行会读取自探索所依据的提交以来代码的变化，仅针对此后公布的专利运行早先的查询（新功能会覆盖新的查询），只筛查此前从未见过的专利族，重新检查每一项受监控的专利；只有当你的功能、专利权利要求或早先的阅读结果发生变化时，才会重新阅读文档。报告会描述所有内容的当前状态。报告开头是简短摘要 “不使用专利术语的摘要”，用不含专利词汇的语言说明项目的哪些部分接近了哪些专利，以及报告如何处理这些部分；随后是 “自上次探索以来的变化”：项目变化、新文档、法律状态和权利要求的变化、观察结果的变化及其原因，以及经检查后确认未发生变化的文档。
• 监控运行只重新检查受监控的专利，并写入一份简短的 update-<target>-<YYYYMMDD-HHMM>.md。其成本仅为一次探索的一小部分，并会明确说明没有进行搜索。

不会重复下载任何内容：权利要求会永久保留在缓存中；法律状态每周刷新一次，专利族每月刷新一次；每项结果都会标明获取时间，因此报告可以说明其事实“截至”何时。开发期间的测量结果显示：对一个中型项目进行首次探索三周后，17 条已存储的查询在新的公布时间窗口内返回 11 条结果，而非全时段的 712 条；其中 8 条属于已筛查过的专利族；全部 25 项受监控的专利都重新检查了，约发出了 50 次上游请求；同一天运行监控则不需要任何请求。如果你使用较早版本探索过某个项目，该技能会先提出将最新报告导入记录。

不使用 MCP 服务

如果无法连接到服务，该技能会在你的机器上改用 patent-checker 命令行工具继续运行，该工具提供相同的操作（见下方命令参考）。安装任何内容前都会先征求你的同意。若要为机器做好准备，或自行运行命令：

uv tool install patent-checker
patent-checker credentials set      # asks for the EPO OPS key and secret without echoing them
patent-checker status               # what is configured, and where from; no network

credentials set 会将密钥和密码存储在你用户的 ~/.config/patent-checker/credentials.env 中（仅你可读取），这样该工具就能在任何项目中找到它们。环境变量或项目的 .env 中的值优先于该文件；patent-checker credentials status 会说明使用的是哪一处凭据，而 credentials clear 会删除该文件。没有 OPS 凭据时，该技能会提供降级模式。使用 uv tool upgrade patent-checker 和 uv tool uninstall patent-checker 更新和移除该工具。

配置

服务（patent-checker serve）以及（适用时）CLI 读取的环境变量。相同的列表及注释见 .env.example。CLI 的 --host 和 --port 选项会覆盖 PATENT_CHECKER_SERVER_HOST 和 PATENT_CHECKER_SERVER_PORT。

变量	默认值	含义
PATENT_CHECKER_OPS_KEY、PATENT_CHECKER_OPS_SECRET	未设置	EPO OPS 消费者密钥和密钥。可以直接设置值，也可以通过 _FILE 变体（PATENT_CHECKER_OPS_KEY_FILE、……）设置保存该值的文件路径；不能同时使用两种方式。空文件表示“未配置”（降级模式）。四个变量均未设置时，将读取每用户凭据文件。
PATENT_CHECKER_CREDENTIALS_FILE	~/.config/patent-checker/credentials.env	由 patent-checker credentials set 写入的每用户凭据文件。仅从中读取四个 OPS 变量；若文件可被其他用户读取，会发出警告后使用。
PATENT_CHECKER_OPERATOR_CONSENT	未设置（必需）	你已确认的操作员告知版本（1.0）。否则服务拒绝启动。
PATENT_CHECKER_SERVER_TOKEN（_FILE）	未设置（http 必需）	客户端必须提供的 Bearer 令牌。
PATENT_CHECKER_SERVER_HOST、PATENT_CHECKER_SERVER_PORT	127.0.0.1、8642	绑定地址。若绑定到环回地址以外的地址，还必须设置 PATENT_CHECKER_SERVER_ALLOWED_HOSTS；加密由网络或代理负责（文档）。
PATENT_CHECKER_SERVER_ALLOWED_HOSTS	未设置	客户端将在 Host 标头中使用的逗号分隔主机名。仅允许名称：不接受通配符，IPv6 地址不带方括号。
PATENT_CHECKER_SERVER_RPS、PATENT_CHECKER_SERVER_BURST	5、10	传入 MCP 请求的限制（用于防止 Agent 循环失控；上游请求节流另行处理）。
PATENT_CHECKER_DATA_DIR	每用户数据目录（服务）、./.patent-checker（CLI）	搜索缓存、请求日志，以及设置后使用的共享文档缓存（<dir>/cache）。服务将数据保存在运行它的用户目录中；CLI 将数据保存在运行它的项目目录中。容器镜像将其设为 /data。
PATENT_CHECKER_CACHE_DIR	<per-user data dir>/cache	共享文档缓存（书目、权利要求、法律状态、专利族、Google Patents 页面），CLI 和服务会在不同项目间共用此缓存。
PATENT_CHECKER_CACHE_TTL	biblio=90d,claims=0,legal=7d,family=30d,gp=0,search=1d,searchbib=1d	各类型的过期时间设置：<n>d、<n>h，或 0，表示永不过期（而非“不缓存”）。CLI 也会读取此变量。
PATENT_CHECKER_PACING_DIR	<per-user data dir>/pacing	共享上游请求节流状态目录（最后请求时间、冷却时间、限流阻止状态）；同一用户运行的所有 patent-checker 进程共用该目录。容器镜像将其设为 /data/pacing。CLI 也会读取此变量。
PATENT_CHECKER_LOG_LEVEL	info	debug、info、warning 或 error。所有服务日志都会输出到标准错误。

此外，还会使用三个非本项目的变量。在 Linux 和 macOS 上，每用户数据目录遵循 XDG_DATA_HOME （$XDG_DATA_HOME/patent-checker；未设置时为 ~/.local/share/patent-checker），每用户同意记录遵循 XDG_CONFIG_HOME （$XDG_CONFIG_HOME/patent-checker/consent.json；未设置时为 ~/.config/patent-checker/consent.json）；在 Windows 上，每用户数据目录为 %LOCALAPPDATA%\patent-checker（若未设置，则回退到 ~\AppData\Local\patent-checker）。patent-checker install --lang 的默认值取自 LC_ALL 或 LANG。

每个 patent-checker 命令都会从其运行目录或父目录中读取 .env，绝不会从主目录或文件系统根目录读取。OPS 凭据的查找顺序为：先查环境变量，再查该 .env，最后查每用户凭据文件。使用 Compose 时，凭据来自 secrets/ 下的文件，而 compose.yaml 同目录的 .env 提供 PATENT_CHECKER_OPERATOR_CONSENT （以及可选的 PATENT_CHECKER_IMAGE、PATENT_CHECKER_PORT、 PATENT_CHECKER_SERVER_ALLOWED_HOSTS 和 PATENT_CHECKER_LOG_LEVEL）。其他变量可以添加到 compose.yaml 的 environment: 下。

在容器和 CLI 之间共享文档缓存（高级）

你机器上的 CLI 和容器中的服务各自维护独立的文档缓存。要共享缓存，请让两者指向同一个目录：在 environment: 下添加 PATENT_CHECKER_CACHE_DIR: /cache，并在 volumes: 下绑定挂载你的 缓存目录，例如 ~/.local/share/patent-checker/cache:/cache。容器以 UID 1000 写入；如果这不是你的 用户 ID，挂载的目录必须允许该用户写入。不要在容器内运行 patent-checker clean --shared：要清除容器的数据，请删除其卷（docker compose down -v）。

缓存与清理

获取的专利文档只保存一份，存放在共享文档缓存中，并按类型设置过期时间；搜索结果和请求日志则保存在运行它们的一方（服务的数据目录，或从项目中使用 CLI 时的项目 .patent-checker/ 目录）。

• patent-checker cache status 显示缓存内容、缓存位置，以及其中有多少内容已过期或损坏。
• patent-checker cache clear [--kind KIND] [--older-than DAYS] [--pub …] [--expired] [--broken] 列出将要删除的内容；添加 --yes 即可删除。KIND 可以是 biblio、claims、legal、family、gp、search、searchbib。
• patent-checker clean 列出项目的痕迹（搜索缓存、请求日志、旧版布局遗留文件），并在添加 --yes 时将其删除。除非添加 --include-artifacts 或 --include-consent，否则会保留报告、Agent 的探索笔记、台账和同意记录；--shared 会将清理范围扩展到共享文档缓存和服务的数据 目录。
• patent-checker ledger status 汇总项目的台账（运行记录、受监控的专利、到期的检查），而 patent-checker ledger check 会根据台账格式验证每个目标的台账；--target <name> 可将任一命令的范围限制为一个目标。两者都只读取数据。台账由你的 Agent 写入，与报告放在一起；是否在 git 中跟踪它，也由你自行选择：它是关于你所知内容的带日期记录， 就像报告一样。
• 不带类型代码的公开号（EP1234567）表示“当前版本”，因此以这种方式获取的权利要求会像同族数据一样过期，而不是永久保留；带类型代码（EP1234567B1）则永不过期。
• 使用 Compose 时，docker compose down -v 会删除服务的卷、 缓存及所有数据。

未添加 --yes 时，不会删除任何内容。

命令参考

Agent 通过 MCP 工具执行的所有操作，也可以在 shell 中完成，每个工具对应一条命令：

MCP 工具	CLI 命令	用途
server_status	patent-checker status	版本、OPS 是否已配置（以及配置来源）、数据位置、同意状态和请求节奏；CLI 形式不会使用网络
ops_search	patent-checker search "<cql>"	搜索已公开的数据（CQL）
ops_search_biblio	patent-checker search-biblio "<cql>"	同样的搜索，并返回每条命中的书目信息
search_plan_check	patent-checker plan-check "<q1>" "<q2>" …	在搜索前查看多个查询的命中数
get_biblio	patent-checker biblio <pub>	单个公开文本的书目信息
get_claims	patent-checker claims <pub>	单个公开文本的权利要求文本
get_legal	patent-checker legal <pub>	INPADOC 法律状态事件
get_family	patent-checker family <pub>	简单专利族
watch_check	patent-checker watch <pub> …	根据已存储的快照重新检查受监控的公开文本
normalize_pubnum	patent-checker normalize <text>	将公开号转换为 DOCDB 拼写形式（离线）
dedup_families	patent-checker dedup <hits.json>	将搜索命中归并为专利族（离线）
verify_batch	patent-checker verify --input <pubs.json> --output <records.json>	查找委托批次中的遗漏项（离线）
usage_report	patent-checker usage	本地请求日志摘要
—	patent-checker ledger status / ledger check，两者均支持 [--target <name>]	读取项目账本，或根据账本格式验证账本
—	patent-checker cache status / cache clear	查看缓存内容，并删除其中一部分
—	patent-checker clean	移除此项目留下的痕迹
—	patent-checker consent status / consent show / consent record	用户告知信息及其同意记录
—	patent-checker install [--json]	放置 Skill，并为你的 Agent 注册服务
—	patent-checker uninstall [--json]	移除 Skill，并取消服务在 Agent 中的注册
—	patent-checker credentials set / credentials status / credentials clear	每位用户的 OPS 凭据文件
—	patent-checker serve	运行 MCP 服务

获取数据的命令（search、search-biblio、plan-check、biblio、 claims、legal、family、watch）均支持 --refresh，可在该次调用中绕过 缓存。没有对应 MCP 工具的命令是有意如此设计的：服务绝不会读取或删除项目文件， 也绝不会处理你的凭据。

安全模型

• 服务默认绑定到 loopback 接口，并要求每个请求都携带 bearer 令牌；令牌会通过恒定时间比较进行验证。Host 和 Origin 标头会根据你配置的名称进行验证（不支持通配符），以此阻止 DNS 重绑定攻击访问 loopback 服务；此检查不会阻止从 loopback 本身提供的页面，令牌会阻止这类访问。
• 无论是服务还是命令行工具，都只会连接 ops.epo.org 和 patents.google.com，并且只会在自身的数据目录下写入内容。它不包含代码执行工具。
• 它只接收公开的专利数据——搜索表达式、公开编号、专利族标识符、日期，以及此前返回的状态快照——并会拒绝过大的请求。你的代码、文档和台账由你的 Agent 在你的机器上处理。经过身份验证的客户端可以查看服务存放数据的位置（server_status）；主机的其他信息不会暴露。
• 传入请求会受到速率限制；对上游的请求会控制频率、逐个串行处理并缓存，以防失控的 Agent 对数据源发起过多请求。
• GET /health 无需身份验证，供容器健康检查使用，只会返回状态、版本和传输方式。
• 凭据从环境变量、项目 .env、由 _FILE 变量指定的文件或每用户凭据文件中读取；绝不会记录到日志中、由 status 或 credentials status 打印出来，也不会出现在启动横幅或错误消息中。每用户文件仅对你可读；如果其他人也能读取，系统会显示警告。
• 容器以非特权用户身份运行，使用只读文件系统并移除所有 capabilities；只有 /data 可写。
• --transport stdio 无需身份验证：仅在单个本地客户端使用，并注意服务会以你的权限运行。
• 你可以向其他机器提供服务，但责任由你承担。传输使用纯 HTTP，服务不提供 TLS：令牌的安全仅取决于网络（tailnet、VPN）或前置的 TLS 终止代理所提供的保护；在可用的情况下，建议使用代理（docs/deploy-lan.md）。设置 PATENT_CHECKER_SERVER_ALLOWED_HOSTS，并将令牌视为网络与 OPS 配额之间唯一的防线。
• Skill 会将服务返回的所有内容（包括专利文本）视为待分析的数据，而不是需要遵循的指令。
• 发布版本由 CI 根据版本标签构建并发布；每次变更都会扫描依赖项和容器映像，检查已知漏洞。如需报告安全问题，请参阅 SECURITY.md。

数据源与合理使用

• EPO Open Patent Services 的使用遵循与你注册的应用相关的条款，包括每周合理使用配额。服务端会间隔发送请求并遵守 OPS 的限流标头，但无法得知有多少其他客户端在共用你的凭据。法律状态信息来自 OPS，是报告中的权威值。每位用户的所有专利检查器进程通过一个小型状态文件（PATENT_CHECKER_PACING_DIR）共享请求间隔，因此，在 shell 中依次运行 patent-checker 命令时，间隔与服务端保持一致；某个进程遇到的冷却期或更严格的间隔也会延续到后续进程。当 OPS 完全拒绝某项服务（HTTP 403，且其限流标头为 black）时，该服务会被视为阻止使用 15 分钟：后续对此服务的调用会立即失败，并通过 external_api_error 指明重试时间，而不会延长阻止时间；patent-checker usage 会在 pacing 下显示被阻止的服务。将多个查询放入一次 plan-check 调用仍可节省请求。
• Google Patents 按每次一页文档的方式获取，速度和数量与人在浏览器中阅读相近，并会缓存每一页，避免重复获取。我们有意不使用搜索端点：Google 的 robots.txt 允许访问某条路径，并不代表其服务条款允许批量收集数据。
• 专利文档受其申请人版权保护。报告仅引用所讨论的权利要求段落，并注明来源，绝不重新分发全文；缓存保留在你的设备上，不属于任何报告的一部分。

备注

• 美国公开申请号有两种 DOCDB 写法。 EPO 的 DOCDB 数据会将同一份美国授权前公开文本存储为 10 位写法（US2007016547A1）或 11 位写法（US20260024003A1），具体取决于文档；同一年份中两种写法都存在（截至 2026-10 测量）。Google Patents 在所有年份中都使用 11 位写法。这些工具会对两种写法进行规范化；如果 OPS 对其中一种写法返回 404，则会使用另一种写法重试一次。它们也接受编号部分带有字母的号码，因为 OPS 对部分日本、印度、台湾、匈牙利和巴西公开文本采用这种写法（JP.H0218652.A 或 JPH0218652A）；手动输入号码时，两种形式都可接受。
• 如果某份文档返回的法律状态完全没有事件，系统会如实报告（events: [] 并附带说明），这与“未找到”并不相同。
• 通知内容变更时，Skill 会再次征求同意，或者服务端会要求重新确认；在此之前不会重复询问。

更新

Docker Compose：docker compose pull && docker compose up -d。

不使用 Docker：停止正在运行的服务端，然后

uv tool upgrade patent-checker
patent-checker serve

设备上的工具和 Skill：uv tool upgrade patent-checker && patent-checker install。重新运行安装程序会刷新 Skill 副本以及各个 Agent 配置中的服务端条目。请确保服务端和 Skill 使用相同版本：两者由同一条命令更新，而较新版本的 Skill 可能会调用较旧版本服务端不具备的工具。

卸载

• Agents：patent-checker uninstall 会移除服务注册信息，以及 patent-checker install 创建的 Skill 副本（如果是在项目中按该方式安装的，请添加 --scope project；--dry-run 会显示将执行的操作）。它会编辑 JSON 配置，在可用时运行各 Agent 自带的 mcp remove 命令，并且仅当 Skill 目录中包含此 Skill 时才会删除该目录。它会列出留给你处理的内容：当 codex 命令不可用时，Codex CLI 表格 [mcp_servers.patent-checker]、OpenHands 和 Hermes Agent 条目，以及原始配置文件的 .bak 备份。
• 服务：运行 docker compose down -v（删除容器、缓存及所有内容），或运行 uv tool uninstall patent-checker（如果也想删除缓存，请一并删除用户数据目录 ~/.local/share/patent-checker 或 %LOCALAPPDATA%\patent-checker）。
• 记录：在项目中运行 patent-checker clean --yes --include-artifacts --include-consent，以删除报告、笔记和同意记录（请在卸载工具前运行）；~/.config/patent-checker/consent.json 存储用户级同意记录，而 patent-checker credentials clear 会删除用户级凭据文件。

更新日志

• v1.4.1 (2026-10)：EPO OPS 会针对同一件美国授权前公开申请，按文档分别使用 10 位或 11 位 DOCDB 拼写形式。当其中一种拼写形式返回 404 时，公开申请端点（书目信息、权利要求、法律状态、专利族）现在会使用另一种形式重试一次，因此不会再仅因拼写形式而导致检索失败。
• v1.4 (2026-09)：报告开篇摘要现在标题为 “不使用专利术语的摘要”（日文「特許用語を使わない要約」）。在任何搜索开始之前，Skill 会将属于通用技术的特征排除在搜索之外——例如标准、广泛使用的库、运行时或平台自带的功能、教科书方法、工具链内部实现和配置；每项特征都会注明类别和原因，并在报告中紧接特征表列出；如有疑问，则保留该特征。台账会将此类特征标记为 excluded，使后续运行不再筛查这些特征；ledger check 会要求说明原因。
• v1.3 (2026-09)：报告以 “不使用专利术语的摘要” 开篇，摘要不使用专利术语，说明项目的哪些部分与哪些专利接近，以及报告如何处理这些部分，不添加任何主观判断。命令行工具可独立运行：patent-checker credentials set 会为你的用户保存 OPS 密钥和密钥短语，patent-checker status 会在不访问网络的情况下显示配置；无法连接服务时，Skill 会切换到 CLI。新增 patent-checker uninstall、install --json、通过 CLI 注册 OpenHands、在 XDG_CONFIG_HOME 下配置 OpenCode，以及在通过管道运行时会在终端提问的 shell 引导程序。网络指南现在除了 Caddy 示例，还介绍了 Tailscale Serve 和专用网络上的纯 HTTP；建议使用 TLS，由运维人员自行决定。
• v1.2 (2026-09)：跨进程保持请求节奏。每项 OPS 服务的最小间隔、冷却时间和收紧后的间隔现在保存在一个小型的用户状态文件中，并由文件锁保护，因此连续运行的 CLI 命令之间也会像服务端调用一样留出间隔；如果 OPS 服务拒绝请求（HTTP 403，限流状态为 black），则在本地封锁 15 分钟，进一步的调用会立即失败并显示可重试时间（PATENT_CHECKER_PACING_DIR，patent-checker usage 会报告状态）。编号部分含字母的公开申请号（JP.H0218652.A、 IN.985DE2013.A、TW.I707812.B）现在可以解析并往返转换，因此可以获取和监控 OPS 按此类编号列出的文档。CLI 参数错误会与无法读取的上游数据错误区分开；ledger status 会列出 ledger check 检查的所有目标；cache status 会显示按不含类型代码的编号存储的条目及其过期时间；请求日志时间戳现在包含 UTC 偏移量。文档现已与代码保持一致（通过管道运行时的引导行为、/health、接受的 Host 标头、运维人员告知中的服务器接收信息列表、命令参考）。
• v1.1 (2026-09)：专为重复运行而构建。每个项目的台账会将一次探索的记录保留到下一次运行；后续运行只搜索新公开的专利，并且只筛查新的专利族；新增 watch_check 工具，用于将受监控专利的法律状态和专利族与上一次运行进行比较；报告以“与上次探索相比的变化”开篇，并为仅检查状态的场景提供简短的监控更新。每条结果都会注明获取时间（fetched_at），权利要求结果会标明实际读取的公开申请（pub_docdb），未提供类型代码的权利要求请求不再永久缓存，dedup_families 会标记已知专利族，usage_report 接受开始时间；新增 patent-checker watch 和 patent-checker ledger status|check 命令。构建容器镜像时会应用发行版的安全更新。
• v1.0 (2026-09)：稳定版发布。常数时间 Bearer 令牌检查，绝不从用户主目录或文件系统根目录读取 .env，请求大小限制，加固容器（只读、无功能），使用 Caddy 的局域网/TLS 示例，改进安装程序（--token-env 无需令牌值、配置文件仅限所有者访问、绝不覆盖备份、失败时返回非零退出码、注册 Codex CLI），缓存和解析器修复（并发写入、CPC 符号、空法律状态、非 UTF-8 页面），上游调用在 401/429/503 时重试一次且绝不阻塞无关工具，每条命令都会读取 .env，使用简明错误消息而非回溯，Python 3.12 或更高版本，且已使用 3.13 测试，在 CI 中进行安全扫描，列入 MCP Registry，重新组织文档。
• v0.5 (2026-09-06)：首次公开发布。Docker 镜像（GHCR、Docker Hub）和使用文件形式密钥的 Compose 部署，面向 8 个 Agent 的 patent-checker install、引导脚本、PyPI 软件包、/health、日志级别设置。
• v0.4 (2026-09-05)：按用户共享的文档缓存，按类型设置过期时间并支持自修复；cache status / cache clear / clean；针对 2026 年美国编号变更的公开申请号标准化。
• v0.3 (2026-09-04)：MCP 服务（FastMCP 4、Streamable HTTP、Bearer 令牌、Host/Origin 验证、出站允许列表、速率限制）、运维人员告知、首个文件缓存。
• v0.1–v0.2 (2026-08)：开发版本；核心库、CLI 和带有同意门控及报告模板的 Agent Skill。

许可证

Apache-2.0。请参阅 LICENSE。

如有疑问或 Bug 报告，请访问 GitHub Issues。