openinsurance-wiki

openinsurance-wiki

一个国家保险市场的大脑。 一个自给自足、开源且不依赖特定国家的框架，将一国的公共保险文档转化为内容丰富、相互关联且注明来源的知识库，供任何 AI Agent 阅读。

在线阅读：sluyasu.github.io/OpenInsurance——本仓库中的每个页面都可浏览和搜索，无需安装。

它不是聊天机器人，也不是 RAG 黑箱，而是一个透明、可复现的知识图谱：本仓库包含完整流程——查找保险公司的公开一般条款 PDF，下载这些文件，并将每份文件转化为忠实的 Markdown 页面，尽可能保留 PDF 中的原始内容，并附上来源引用；所有页面还相互链接，构成一个可导航的产品、保险公司、险种、法规和概念图谱。

据我们所知，这是唯一开源、机器可读且注明来源的保险产品数据库（最接近的同类产品均为商业产品且不公开）。可将其用于任何国家：分类体系是数据，而非代码；添加国家的步骤已有文档说明（_meta/BOOTSTRAP-COUNTRY.md）。

数据集覆盖四个国家——比利时、法国、卢森堡和瑞士，共计39 家保险公司和 1,189 个产品页面（汽车、住房、健康、责任、旅行、法律保护等），每个页面均引用其来源文档：

国家	保险公司	产品页面	险种页面	状态
比利时（be）	24	269	17	参考国家：唯一完整的人工编写内容层——每个已有内容的险种都有对应页面，另含 3 个法规页面和一份国家术语表
法国（fr）	10	714	24	覆盖量最大；已列出的市场远未穷尽
卢森堡（lu）	4	194	15	已收录主要的本地保险公司
瑞士（ch）	1	12	0	仅完成第一个纵向切片，除此之外别无其他

这套方案首先在比利时得到验证，之后又运行了三次，因此“国家无关”不再只是设计主张，而是经过测试的能力。实时数量见 AGENTS.md 中的覆盖情况表；该表会在每次索引运行时根据数据重新生成。

---

2 分钟即可上手——无需 API 密钥

数据集已随仓库附带并完成构建：涵盖四个国家的 1,189 个产品页面、保险公司页面、术语表，以及背后的结构化 JSON。你只需要 LLM 密钥来从头重新提取数据，而非使用数据。

1. 阅读数据。 在线访问 sluyasu.github.io/OpenInsurance，或者将克隆的仓库作为 Obsidian 知识库打开，这样 [[wikilinks]] 就会变成可浏览的图谱。 （github.com 本身不会将 [[wikilinks]] 渲染成链接——通过网站或知识库浏览更方便。）

2. 接入 Agent（MCP）。 MCP 服务无需密钥且只读：

git clone https://github.com/sluyasu/OpenInsurance.git
cd OpenInsurance
python3 -m venv .venv && .venv/bin/pip install "mcp[cli]" pyyaml

然后将其注册到任意 MCP 客户端，例如 Claude Code：

claude mcp add insurance-wiki -- "$(pwd)/.venv/bin/python" "$(pwd)/mcp/insurance_wiki_mcp.py"

（或者从 PyPI 获取已发布的服务——运行 uvx openinsurance-wiki-mcp，并将 INSURANCE_WIKI_REPO 指向克隆的仓库；上面的仓库内服务始终与已提交的数据集相匹配。）

你可以使用 search、get_product、get_coverage（仅提供与一个问题相关的内容，并附上逐字引文）、compare_products、find_overlap（组合两份保单时查找可能重复的保障）、verify_claim（为事实核查提供逐字证据）、get_branch_overview 等工具。详见 mcp/README.md。

3. 获取原始数据。 data/<cc>/extracted/ 中为每份源文档保存了一个结构化 JSON 文件，并根据 schema/ 进行验证；data/<cc>/index.json 是扁平索引（cc = be、fr、lu、ch）。 AGENTS.md 是生成的清单（包含注释类型、数量，以及每个页面的 path / source_url / freshness），方便读取文件的 Agent 无需猜测即可浏览。

---

为什么使用 MCP 服务（而不是聊天机器人、RAG 技术栈或 REST API）

目标是让任何 AI Agent 都能根据可引用的文档回答保险问题。这一约束决定了架构：

为什么使用 MCP。 Model Context Protocol 是 AI 助手与数据之间的标准接口：只需一个服务，Claude、ChatGPT、Cursor 或你自己的 Agent 只要配置三行，就能接入，无需定制集成。此服务无需密钥（无需账户、API 密钥或配额）、只读，且无需托管：数据集就是仓库本身，因此数据随 git clone 一起获取，并可离线使用。Wiki 重新提取后，使用 git pull 即可升级。

为什么不用 RAG 聊天机器人。 聊天机器人只有一个界面；知识库则应该服务于多种用途（经纪人的比较工具、合规检查、市场映射 Agent）。RAG 会增加一个黑盒嵌入索引：你无法对它进行差异比较、在 PR 中审查或复现，而且检索错误也无从察觉。这里的检索层通过对已审查并提交的文件进行确定性匹配：相同查询每次都会返回相同文档，而且每个回答都附带来源 PDF 和页码。大模型留在它该在的地方：客户端，由它基于准确摘录进行推理。

为什么不用 REST API。 对于一年只更新几次的数据集，API 意味着需要一个全天候运行的服务、可用性保障、密钥、版本管理，以及为每个使用者分别定制集成。MCP 只需一个本地进程，就能提供相同的程序化访问能力。

工作原理分为四个阶段：

1. 来源（sources/）：已提交的 YAML 文件，说明各保险公司的公开 PDF 存放位置。
2. 冻结式提取（data/）：每个 PDF 只处理一次，转换为结构化 JSON 和带引文的 Markdown；所用提示词本身也会提交。查询时不会生成任何内容。
3. 确定性 MCP 服务（mcp/）：提供 10 个针对这些文件的只读工具。内部没有大模型，不联网，也不保留状态。相同输入，相同输出。
4. 推理客户端：上层的 Agent（Claude、经纪人聊天机器人、脚本）负责语义处理，并引用工具返回的内容。

信任边界清晰明确：第 4 阶段以下的所有内容都可复现、可审计。幻觉风险仅限于客户端；工具响应经过设计，可促使客户端如实作答：每个单产品响应都包含一份依据文档作答的约定，以及前置的引用行；对有歧义的产品名称会拒绝猜测，并列出候选项；此外还有一个 verify_claim 工具，可让 Agent 在回答前对照文档核实自己的草稿。请参阅服务文档中的响应规范说明。

运行速度。 服务会读取每个文件一次，并从内存中提供服务：在此数据集上，每个工具的热延迟为 0.01 至约 3 ms（测量结果可复现：mcp/README.md）。在实际聊天机器人中，用户感受到的耗时来自大模型自身的推理，而不是这些工具。

为什么要做这个项目

保险产品的文档以内容密集的 PDF 形式散落在数十家保险公司的网站上。目前没有中立、机器可读且易于导航的全国市场产品地图。本项目旨在构建这样一份地图——作为一项公共服务，并以便于 AI Agent 接入的形式提供。

本项目也契合正在形成的市场标准：欧盟法规 2017/1469 要求每款非寿险产品都提供标准化摘要（IPID）；EIOPA 积极推动产品比较和转换；而开放保险议程（OPIN、欧盟 FIDA 提案）则推动以机器可读的方式访问保险数据。本项目补上了其中缺失的公开文档这一层：以开放方式呈现产品的实际条款。

本项目有四个特点：

1. 自给自足、可复现。 克隆项目、添加自己的 LLM 密钥，然后运行 make all。它会从头开始抓取、下载并提取内容。没有隐藏的数据集——每个输入都已提交到仓库，每项输出都可重新生成。
2. 提取过程透明。 发送给 LLM 的确切提示词就保存在本仓库的文件中（extraction-agent/），而不是藏在代码里。你可以准确查看模型收到的指令，并使用自己的模型（Claude、Gemini、GPT 或本地模型）运行相同的提取流程。
3. 有据可依、注明出处。 每个产品页面都可追溯到源 PDF，并标注页码。引文会与原始文本核对。如果文档中没有，页面上就不会有。
4. 范围明确。 每个页面都对应一款特定保险产品的合同或合同前文档，除此之外一概不收录。保险公司的下载页面常常混有公司章程、基金报告和促销附加条款；这些内容会在三个关卡被拒绝（来源中记录的 out_of_scope 标记、提取 Agent 自己的判定，以及会阻止 CI 通过的检查）。请参阅 CONTRIBUTING。

---

Wiki 中有什么

按国家划分（wiki/<cc>/，例如 wiki/be/）：

文件夹	内容	创建方式
products/<insurer>/	每款保险产品对应一个详尽页面（一般条款 / IPID）	自动生成自 PDF
insurers/	每家保险公司对应一个页面，汇总其产品	自动生成
branches/	各保险险种概览（每个已有内容的险种都有一个；make validate 会列出缺少的概览）	手动编写
regulations/	监管机构和主要法律（FSMA、强制 RC 汽车保险、自然灾害险等）	手动编写
glossary/	各国特有术语（bonus-malus、免赔额、Branche 21/23 等）	手动编写

自动生成的页面和手动编写的页面保存在不同文件夹中，彼此不会冲突：修正事实时，应编辑提取数据并重新构建，而不是编辑自动生成的页面。

所有四个国家都有自动生成的内容；手动编写的内容则不尽相同，且会如实展示。比利时有险种、法规和术语表页面；法国和卢森堡有险种页面，且各有一个法规页面；瑞士目前两者都没有。make validate 会列出所有已有内容但仍缺少概览页面的险种。适用于所有国家的通用概念收录在 wiki/universal-glossary/ 中。

每个页面都是兼容 Obsidian 的 Markdown，包含 YAML frontmatter 和 [[wikilinks]]。

---

从头复现

这是唯一需要 LLM 密钥的步骤（提取步骤）。抓取和下载使用免费的技术栈（httpx + Playwright）。

git clone https://github.com/sluyasu/OpenInsurance.git
cd OpenInsurance
make setup                      # deps + playwright chromium (no paid scraping dependency)
cp .env.example .env            # set LLM_PROVIDER + your API key (any provider)

# Reproduce a slice end-to-end:
make download COUNTRY=be INSURER=<slug>   # fetch the public PDFs
make extract  COUNTRY=be INSURER=<slug>   # PDFs -> rich Markdown + JSON (uses YOUR model)
make build    COUNTRY=be                  # assemble the wiki
make validate COUNTRY=be                  # citation / wikilink / frontmatter gates

# ...or the whole chain:
make all COUNTRY=be

COUNTRY 可指定 sources/ 中的任意国家：be、fr、lu 或 ch。提取过程支持断点续跑（按来源校验和 + 提示词版本跳过已处理项），因此大型任务可以安全地停止并重新启动。

流水线的工作原理

sources/be/<insurer>.yml     (committed: where the public PDFs live)
        │  discover.py   crawl listing pages (httpx, Playwright fallback)
        ▼
data/be/pdfs/…               (downloaded; gitignored - regenerable; manifest.json committed)
        │  extract.py    PyMuPDF text  ──►  LLM (extraction-agent/ prompts)  ──►  MD + JSON
        ▼
data/be/extracted/…          (rich Markdown + structured JSON, page-cited)
        │  build_wiki.py
        ▼
wiki/be/…                    (the browsable, agent-readable knowledge base)

此处展示的是 be；fr/、lu/ 和 ch/ 下也有相同的布局，且它们使用相同的代码。

详情请参阅 CONTRIBUTING.md（如何添加国家 / 保险公司 / 产品）以及 extraction-agent/（确切的提示词）。

每次推送都会运行 CI 检查：wiki 验证（frontmatter、使用 --strict-links 检查链接、引用、根据 schema 和范围规则检查数据层）、pytest 测试套件、构建幂等性检查（重新构建已提交的 wiki 后必须没有差异），以及对构建后的网站进行死链检查；该检查会阻止部署。每月工作流会在数据集的新鲜度下降时创建一个 issue。

---

添加一个国家

1. sources/<cc>/_country.yml - 监管机构、语言、分支分类体系。
2. sources/<cc>/<insurer>.yml - 各保险公司公开 PDF 文件的存放位置。
3. wiki/<cc>/ - 手动编写分支 / 监管 / 术语表概览（也可以先创建占位内容）。
4. make all COUNTRY=<cc>。

schema 中没有针对特定国家的内容——分类体系属于数据，而非结构。四个国家（be、fr、lu、ch）使用相同的代码运行，流水线中没有按国家区分的分支。目前已知的一项限制是：产品页面的章节标题仍在 pipeline/render.py 中以法语硬编码，因此，文档不是法语的国家需要先将这些标题移入国家配置。

---

许可与来源

采用双重许可：代码（pipeline/、mcp/、适配器、schema）采用 MIT 许可；原创内容（wiki/、提取的数据、提示词、来源）采用 CC-BY-4.0 许可。从保险公司公开文档中引用的简短原文摘录仍归其出版方所有，不重新授权——请参阅 LICENSE、LICENSE-CONTENT 和 NOTICE。

产品页面是从保险公司公开发布的文档中提取的事实信息，并注明了各来源 PDF。这些页面不是保险公司的官方文件，且可能存在提取错误——请务必对照引用的 source_url 核实。本项目提供的是信息，而非个性化保险建议。