PatentAgent

基于大语言模型（LLM）驱动的智能专利分析系统。用自然语言与专利数据对话。

PatentSmelter 的下一代演进。从"批处理工具箱"到"对话式智能分析"。

唯一用户入口：frontend/ + server.py。MCP stdio/HTTP 服务作为可选的 外部 AI 客户端集成接口，与 Web 共用工具注册表，但不是另一套用户界面。

暂时以AGPL的形式开源。以后也许（但不保证）会转换为更宽松的模式。Contact: 2507380208@wtu.edu.cn

快速开始

后端以 pyproject.toml 为唯一依赖声明，uv.lock 固定完整环境。要求 Python 3.10+， 推荐使用 Python 3.13 或 3.14；CI 覆盖 3.10–3.14：

uv sync --frozen --extra mcp --group dev
cd frontend && npm ci && cd ..

requirements.txt 是由锁文件导出的 pip 兼容清单，不应手工编辑。MiniLM 运行库属于 标准依赖；模型权重不会提交到仓库，只在首次显式启用 Beta 时下载约 471MB 到用户缓存目录。

一键启动（推荐）

cd PatentAgent
bash start.sh

自动启动后端 (FastAPI :8000) 和前端 (React :5173)，浏览器自动打开。

分别启动

后端：

cd PatentAgent
MCP_INPUT_DIR=./my_patents PATENT_DATA_ROOT=./my_patents uvicorn server:app --host 127.0.0.1 --port 8000
# API 文档: http://localhost:8000/docs

前端：

cd PatentAgent/frontend
npm ci          # 首次运行，严格按 package-lock.json 安装
npm run dev     # http://localhost:5173

可选：MCP 集成

cd PatentAgent
pip install mcp
python mcp_server.py

需要从 Claude Code / VS Code / Cursor 调用分析工具时再配置 MCP。详见 MCP 使用指南。

Related MCP server: Patent Big Data MCP Server

核心特性

• 对话式交互 — 自然语言提问，Agent 理解意图、制定计划、调用工具、输出结论

• 动态工具目录 — 工具数以 /api/tools 注册表为单一来源，并按当前字段能力启用或降级

• 智能关键词过滤 — 400 词专利专用停用词库 + NLTK 词性过滤，剔除说明书套话和语境噪音

• 结果可追溯 — 图表、结构化摘要、方法、字段覆盖率、警告、参数和耗时统一返回

• 原生可视化 — React/ECharts 优先读取结构化结果，支持原始尺寸、适应窗格、全屏、PNG/JSON 导出与数据表切换

• 多供应商 LLM — 多个命名配置、OpenAI/Anthropic/DeepSeek 三类协议、OpenRouter/Ollama/vLLM 与自定义兼容服务

• 极速加载 — 8 线程并行解析 + Pickle 缓存，首次 10s，缓存命中 0.3s

• 报告导出 — HTML 报告（含完整中文排版），CSV 数据导出

• MCP 协议支持 — 标准 MCP (Model Context Protocol) stdio/HTTP 服务器，Claude Code / VS Code / Cursor 可直接调用全部工具

• 算法证据登记表 — 16 个工具逐一登记算法 ID、版本、公式、字段门槛、论文来源与禁止结论

• 统一文件导入 — WoS、Google Patents JSONL、USPTO grant XML/PFW JSON 统一进入 PatentRecord v3，并返回字段覆盖、冲突与来源能力报告

• 多语言检索 Beta — 单次显式启用本地 MiniLM 与词法 RRF；失败会明确回退，不替代默认 TF-IDF 基线

数据源能力

正式支持 WoS Derwent tagged text、Google Patents Public Data JSONL、USPTO grant full-text XML 和 Patent File Wrapper JSON。EPO OPS 与 CNIPA 仅处于格式准备阶段， 没有账号、抓取器或生产适配器。详细字段边界和官方来源见 数据源能力矩阵。 固定样例的字段覆盖、代理指标和 10 万条工程压力结果见 V3.1 验证报告。

POST /api/data/load 可传 source_format=auto|wos_dii|google_patents_jsonl|uspto_grant_xml|uspto_file_wrapper_json； 旧请求缺省仍为 auto。自动模式按内容签名识别已支持的标准格式，并在导入报告中逐文件 返回识别依据；它不对任意厂商变体承诺 100% 命中。建议导入目录提供 patentagent-import.json 和 SHA-256 以获得确定性识别，失败时也可手工指定格式。

工具清单

MCP 使用指南

PatentAgent 提供标准 MCP 服务器；可用工具数量以运行时注册表为准，与 /api/tools 保持一致。

什么是 MCP

MCP 是一种标准化的 AI 工具通信协议。有了它，AI 客户端不再局限于"只能聊天"，而是可以主动发现和调用运行时注册表中的工具。AI 客户端可以：

• 自动发现有哪些分析工具可用

• 根据用户意图选择合适的工具

• 传参调用工具，获取结构化分析结果

• 基于真实数据撰写分析结论

安装 MCP 依赖

pip install mcp

启动 MCP 服务器

stdio 模式（推荐，用于 Claude Code / VS Code / Cursor）：

python mcp_server.py

服务器通过标准输入输出与客户端通信，不需要网络端口。

HTTP 模式（用于远程访问）：

python mcp_http_server.py --port 8000 --host 127.0.0.1

HTTP 默认只允许本机。若确需绑定非回环地址，必须同时设置强随机 MCP_AUTH_TOKEN，客户端以 Authorization: Bearer <token> 认证；缺少令牌时服务拒绝启动。

环境变量配置

配置 Claude Code

在项目根目录创建或编辑 .mcp.json：

{
  "mcpServers": {
    "patent-agent": {
      "command": "python3",
      "args": ["/绝对路径/PatentAgent/mcp_server.py"],
      "env": {
        "MCP_INPUT_DIR": "/绝对路径/my_patents",
        "MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

重启 Claude Code 后，MCP 服务器自动启动。你可以直接说：

• "列出可用的专利分析工具"

• "给我一个专利数据集的总览"

• "分析 2018 到 2022 年的公开趋势"

• "找找技术空白点，哪些方向还没有专利布局"

• "用词云展示技术热点"

配置 VS Code / Cursor

在项目根目录创建 .vscode/mcp.json：

{
  "servers": {
    "patent-agent": {
      "type": "stdio",
      "command": "python3",
      "args": ["/绝对路径/PatentAgent/mcp_server.py"],
      "env": {
        "MCP_INPUT_DIR": "/绝对路径/my_patents",
        "MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

MCP 工具清单

MCP 服务器暴露的工具接口（数量以运行时注册表为准）：

分析结果格式

MCP 工具调用返回两种内容类型：

• text — 结构化 JSON 数据，包含分析结果的主要数据（如趋势数据点、词频列表、矩阵数值等）

• resource（可选）— 嵌入式 HTML 图表（text/html MIME），客户端渲染为交互式 pyecharts 图表

验证 MCP 服务器

可以使用 Python 脚本验证 MCP 服务器是否正常工作：

python -m pytest tests/test_mcp_integration.py -v

测试覆盖：服务器初始化、动态工具列表、工具调用、错误处理。

架构

唯一用户入口: React Frontend (Vite + TypeScript)
                       ↕ HTTP + SSE
              FastAPI Backend (server.py 兼容入口)
                       ↕
可选集成接口: MCP Server (stdio/HTTP, JSON-RPC)
         ↕
patent_agent 模块化单体 (application/domain/security/infrastructure/api)
         ↕
Agent 流水线 (Intent/Plan/Policy/Execute/Validate/Synthesize)
         ↕
Tool 层 (注册表为单一来源，含能力门禁与统一结果契约)
         ↕
Engine 层 (纯计算)
         ↕
数据访问层 (Parquet 缓存 + 列投影)
         ↕
知识库层 (16 工具算法证据登记表 + 决策模板)

项目结构

PatentAgent/
├── server.py              # FastAPI 后端（REST、会话管理与 SSE 流式）
├── start.sh               # 一键启动脚本
├── frontend/              # React 前端
│   ├── src/
│   │   ├── App.tsx         #   主应用（三栏布局）
│   │   ├── api.ts          #   全部 API 调用 + SSE 流
│   │   ├── types.ts        #   TypeScript 类型定义
│   │   ├── features/       #   datasets/sessions/agent/tools/providers/reports
│   │   └── components/     #   原生 ECharts、工具卡与消息组件
│   └── package.json
├── patent_agent/          # 模块化单体边界与公共强类型契约
│   ├── application/      #   数据、工具、报告等用例
│   ├── domain/           #   Dataset/Task/Tool envelope
│   ├── security/         #   内存凭证仓与模型 URL 安全
│   └── infrastructure/   #   AppContainer、配置、日志与请求门禁
├── reporting/             # 后端 HTML/Word/PDF 报告生成
├── agent/                 # Agent 编排层
│   ├── orchestrator.py    #   兼容外观与状态机
│   ├── pipeline.py        #   Planner/Executor/Validator/Synthesizer
│   ├── strategy_chains.py #   旧版兼容，Web 主流程不再调用
│   ├── cross_tool_synthesis.py  # 跨工具关联推理
│   ├── recommendation_engine.py # 战略建议生成
│   ├── adaptive_planner.py      # 旧版兼容，不会自动追加工具
│   ├── proactive_discovery.py   # 主动发现引擎
├── storage/conversation_store.py # 会话、轮次与结构化证据（不保存 API Key/图表 HTML）
├── storage/provider_store.py     # 非敏感供应商配置与幂等 SQLite 迁移
│   └── prompts.py
├── tools/                 # Tool 层（16 个运行时注册工具）
├── engine/                # 分析引擎层 (13个纯计算模块)
├── patent_mcp/            # MCP 服务器
├── mcp_server.py          # MCP stdio 入口
├── mcp_http_server.py     # MCP HTTP 入口
├── models/                # Pydantic 数据模型
├── knowledge/             # 单一算法证据登记表 + 决策模板
├── storage/               # 数据访问层
├── viz/                   # 旧客户端/MCP 的 pyecharts 兼容可视化层
└── tests/                 # Python 回归测试 + 前端渲染测试

运行状态由 FastAPI lifespan 创建的 AppContainer 持有，不再由 server.py 的可变模块 全局变量持有。SQLite 记录数据集版本、轮次任务、工具 provenance/metrics、审批、报告和 可续传事件；进程重启会把运行中任务标记为 interrupted，不会自动重复 LLM 调用。

可复现性与质量门禁

uv lock --check
uv run python -m pytest -q
cd frontend && npm test -- --run && npm run build

tests/fixtures/wos_golden/ 是固定的五年以上合成 WoS 数据集；16 个工具均校验统一的 ToolExecutionEnvelope、数据版本、字段覆盖、算法参数和执行指标。更新金样必须显式运行 python scripts/generate_golden_wos_fixture.py 并审查差异。GitHub Actions 在 Python 3.10/3.11/3.12/3.13/3.14、Node 20、MCP、迁移、锁文件和金样回归全部通过后才满足合并门禁；V* 标签只生成源码、前端产物与 SHA-256 校验和，不发布 PyPI。

配置

LLM 设置

左侧供应商卡只显示当前名称、协议、模型与连接状态；“切换 / 设置”打开高级设置。 高级设置可以保存多个命名配置，并提供 OpenAI、Claude、DeepSeek、OpenRouter、 Ollama、vLLM 和自定义预设。显示名称只用于识别配置，请求消息格式只由 openai_chat、anthropic_messages 或 deepseek_chat 协议决定。

“保存”只写入非敏感配置；“测试连接”不会切换 Agent；“保存并连接”只有在完整能力 探测通过后才替换当前 Agent。探测依次验证普通文本、工具选择、本地工具结果回传、 最终文本和结构化 JSON 输出。仅能聊天但不能完成工具闭环的模型不能激活。

API Key 与标为“敏感”的 Extra Header 只保存在后端进程内存：不会写入 .patentagent/sessions.db、日志或 API 响应。后端重启后会恢复配置和上次选择，但必须 重新输入凭证。Ollama/vLLM 等本机端点可选择“无鉴权”；远程 Base URL 必须使用 HTTPS。 Extra Body 只接受 JSON 对象，不能覆盖 model/messages/tools/tool_choice/response_format/max_tokens 等编排器字段。Agent 正在生成时不能切换、编辑当前配置、删除当前配置或断开连接。

供应商配置 API：

GET    /api/llm/profiles
POST   /api/llm/profiles
PATCH  /api/llm/profiles/{id}
DELETE /api/llm/profiles/{id}
POST   /api/llm/profiles/{id}/models
POST   /api/llm/profiles/{id}/probe
POST   /api/llm/profiles/{id}/activate
POST   /api/llm/disconnect

旧 /api/agent/config 继续兼容，并经过相同的 URL 校验、协议适配和完整能力探测。

Web Agent 的正常流程由 LLM 第一轮直接选择最小必要工具集，本地参数/数据/ 成本门禁通过后执行，再按 OpenAI、Claude 或 DeepSeek 的官方消息协议回传结果。 第二轮禁用新工具并生成针对当前问题的结构化答案和动态追问。

你也可以在网页端利用“高级设置”来自行配置服务商，例如Openrouter等。本人致力于降低软件使用门槛。建议用户使用Deepseek作为默认模型，能大大降低使用成本。

数据格式

支持 Web of Science (Clarivate Derwent) 专利导出 .txt 文件。

将文件放入 my_patents/ 目录，在 GUI 中加载即可。支持增量更新，缓存自动失效。

文档

• V3.1 更新日志 — 当前版本的重要新增、变更、安全修复与兼容说明

• 项目与论文审计 — 数据质量、论文适用条件、优势/弱点和法律边界

• 16 工具算法证据矩阵 — 由 knowledge/tool_evidence.json 自动生成

• DII 基准数据状态 — 检索式、授权核验和导入审计方法（随专利数据目录提供，不包含在源码仓库中）

• 软件说明书 — 架构设计、功能详解、技术栈、版本历史

• 操作指南 — 从零开始的手把手教程，含环境配置、工具使用、常见问题

作者

Wu Jinhong、Chen Siyu。版权与许可声明见 LICENSE。