Openzim Mcp

🚀 OpenZIM MCP Server

OpenZIM MCP 是一款现代、安全且高性能的 MCP（Model Context Protocol）服务器，它能让 AI 模型离线访问和搜索 ZIM 格式 的知识库。该工具将静态的 ZIM 存档转变为适用于大语言模型的动态知识引擎，为大语言模型提供智能、结构化的访问方式，使其能有效浏览和理解海量的知识仓库。

项目徽章

• 构建与质量：
  • 
  • 
  • 
  • 
• 包与版本：
  • 
  • 
  • 
  • 
• 代码质量与标准：
  • 
  • 
  • 
  • 
• 社区与贡献：
  • 
  • 
  • 
  • 

✨ 主要特性

• 🔒 安全至上：全面的输入验证和路径遍历保护。
• ⚡ 高性能：智能缓存和优化的 ZIM 文件操作。
• 🧠 智能检索：自动从直接访问回退到基于搜索的检索，以确保可靠的条目访问。
• 🧪 充分测试：拥有超过 90% 的测试覆盖率和全面的测试套件。
• 🏗️ 现代架构：采用依赖注入的模块化设计。
• 📝 类型安全：整个代码库都有完整的类型注解。
• 🔧 可配置：具有灵活的配置和验证机制。
• 📊 可观测：结构化日志记录和健康监控。

🚀 快速开始

安装

# 从 PyPI 安装（推荐）
pip install openzim-mcp

开发环境安装

对于贡献者和开发者：

# 克隆仓库
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# 安装依赖
uv sync

# 安装开发依赖
uv sync --dev

准备 ZIM 文件

从 Kiwix 库 下载 ZIM 文件（例如维基百科、维基词典等），并将它们放在一个目录中：

mkdir ~/zim-files
# 将 ZIM 文件下载到 ~/zim-files/ 目录下

运行服务器

# 使用控制台脚本（在使用 pip 安装后）
openzim-mcp /path/to/zim/files

# 或者使用模块
python -m openzim_mcp /path/to/zim/files

# 开发环境（从源代码运行）
uv run python -m openzim_mcp /path/to/zim/files

# 或者使用 make（开发环境）
make run ZIM_DIR=/path/to/zim/files

MCP 配置

添加到你的 MCP 客户端配置中：

{
"openzim-mcp": {
"command": "openzim-mcp",
"args": ["/path/to/zim/files"]
}
}

使用 Python 模块的替代配置：

{
"openzim-mcp": {
"command": "python",
"args": [
"-m",
"openzim_mcp",
"/path/to/zim/files"
]
}
}

开发环境（从源代码）：

{
"openzim-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/openzim-mcp",
"run",
"python",
"-m",
"openzim_mcp",
"/path/to/zim/files"
]
}
}

📚 详细文档

可用工具

list_zim_files - 列出允许目录中的所有 ZIM 文件

无需参数。

search_zim_file - 在 ZIM 文件内容中搜索

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• query（字符串）：搜索查询词。

可选参数：

• limit（整数，默认值：10）：返回的最大结果数。
• offset（整数，默认值：0）：结果的起始偏移量（用于分页）。

get_zim_entry - 获取 ZIM 文件中特定条目的详细内容

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• entry_path（字符串）：条目的路径，例如 'A/Some_Article'。

可选参数：

• max_content_length（整数，默认值：100000，最小值：1000）：返回内容的最大长度。

智能检索特性：

• 自动回退：如果直接路径访问失败，会自动搜索该条目并使用找到的精确路径。
• 路径映射缓存：缓存成功的路径映射，以提高重复访问的性能。
• 增强的错误指导：当找不到条目时，提供清晰的指导。
• 透明操作：无论路径编码差异（空格与下划线、URL 编码等）如何，都能无缝工作。

get_zim_metadata - 从 M 命名空间条目中获取 ZIM 文件元数据

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。

返回值： 包含 ZIM 元数据的 JSON 字符串，包括条目计数、存档信息以及元数据条目，如标题、描述、语言、创建者等。

get_main_page - 从 W 命名空间获取主页条目

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。

返回值： 主页内容或主页条目的相关信息。

list_namespaces - 列出可用的命名空间及其条目计数

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。

返回值： 包含命名空间信息的 JSON 字符串，包括条目计数、描述和每个命名空间（C、M、W、X 等）的示例条目。

browse_namespace - 分页浏览特定命名空间中的条目

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• namespace（字符串）：要浏览的命名空间（C、M、W、X、A、I 等）。

可选参数：

• limit（整数，默认值：50，范围：1 - 200）：返回的最大条目数。
• offset（整数，默认值：0）：分页的起始偏移量。

返回值： 包含命名空间条目的 JSON 字符串，包括标题、内容预览和分页信息。

search_with_filters - 使用高级过滤器在 ZIM 文件内容中搜索

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• query（字符串）：搜索查询词。

可选参数：

• namespace（字符串）：可选的命名空间过滤器（C、M、W、X 等）。
• content_type（字符串）：可选的内容类型过滤器（text/html、text/plain 等）。
• limit（整数，默认值：10，范围：1 - 100）：返回的最大结果数。
• offset（整数，默认值：0）：分页的起始偏移量。

返回值： 包含命名空间和内容类型信息的过滤搜索结果。

get_search_suggestions - 获取搜索建议和自动完成

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• partial_query（字符串）：部分搜索查询（至少 2 个字符）。

可选参数：

• limit（整数，默认值：10，范围：1 - 50）：返回的最大建议数。

返回值： 基于文章标题和内容的搜索建议的 JSON 字符串。

get_article_structure - 提取文章结构和元数据

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• entry_path（字符串）：条目的路径，例如 'C/Some_Article'。

返回值： 包含文章结构的 JSON 字符串，包括标题、章节、元数据和单词计数。

extract_article_links - 从文章中提取内部和外部链接

必需参数：

• zim_file_path（字符串）：ZIM 文件的路径。
• entry_path（字符串）：条目的路径，例如 'C/Some_Article'。

返回值： 包含分类链接（内部、外部、媒体）及其标题和元数据的 JSON 字符串。

示例

列出 ZIM 文件

{
"name": "list_zim_files"
}

响应：

在 1 个目录中找到 1 个 ZIM 文件：

[
{
"name": "wikipedia_en_100_2025-08.zim",
"path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"directory": "C:\\zim",
"size": "310.77 MB",
"modified": "2025-09-11T10:20:50.148427"
}
]

搜索 ZIM 文件

{
"name": "search_zim_file",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"query": "biology",
"limit": 3
}
}

响应：

找到 51 个与 "biology" 匹配的结果，显示 1 - 3 条：

## 1. Taxonomy (biology)
Path: Taxonomy_(biology)
Snippet: #  Taxonomy (biology) Part of a series on
---
Evolutionary biology
Darwin's finches by John Gould

* Index
* Introduction
* [Main](Evolution "Evolution")
* Outline

## 2. Protein
Path: Protein
Snippet: #  Protein A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

## 3. Ant
Path: Ant
Snippet: #  Ant Ants
Temporal range: Late Aptian – Present
---
Fire ants
[Scientific classification](Taxonomy_\(biology\) "Taxonomy \(biology\)")
Kingdom:  | [Animalia](Animal "Animal")
Phylum:  | [Arthropoda](Arthropod "Arthropod")
Class:  | [Insecta](Insect "Insect")
Order:  | Hymenoptera
Infraorder:  | Aculeata
Superfamily:  |
Latreille, 1809[1]
Family:  |
Latreille, 1809

获取 ZIM 条目

{
"name": "get_zim_entry",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"entry_path": "Protein"
}
}

响应：

# Protein

Path: Protein
Type: text/html
## Content

#  Protein

A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

**Proteins** are large biomolecules and macromolecules that comprise one or more long chains of amino acid residues. Proteins perform a vast array of functions within organisms, including catalysing metabolic reactions, DNA replication, responding to stimuli, providing structure to cells and organisms, and transporting molecules from one location to another. Proteins differ from one another primarily in their sequence of amino acids, which is dictated by the nucleotide sequence of their genes, and which usually results in protein folding into a specific 3D structure that determines its activity.

A linear chain of amino acid residues is called a polypeptide. A protein contains at least one long polypeptide. Short polypeptides, containing less than 20–30 residues, are rarely considered to be proteins and are commonly called peptides.

... [内容截断，总共 56,202 个字符，仅显示前 1,500 个字符] ...

智能检索示例

{
"name": "get_zim_entry",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"entry_path": "A/Test Article"
}
}

响应（展示智能检索工作情况）：

# Test Article

Requested Path: A/Test Article
Actual Path: A/Test_Article
Type: text/html

## Content

# Test Article

This article demonstrates the smart retrieval system automatically handling
path encoding differences. The system tried "A/Test Article" directly,
then automatically searched and found "A/Test_Article".

... [内容继续] ...

get_server_health - 获取服务器健康状况和统计信息

无需参数。

返回值：

• 服务器状态和性能指标。
• 缓存统计信息。
• 配置信息。
• 实例跟踪信息。
• 冲突检测结果。

示例响应：

{
"status": "healthy",
"server_name": "openzim-mcp",
"allowed_directories": 1,
"cache": {
"enabled": true,
"size": 1,
"max_size": 100,
"ttl_seconds": 3600
},
"instance_tracking": {
"active_instances": 1,
"conflicts_detected": 0
}
}

get_server_configuration - 获取详细的服务器配置

无需参数。

返回值： 全面的服务器配置，包括诊断信息、验证结果和冲突检测。

示例响应：

{
"configuration": {
"server_name": "openzim-mcp",
"allowed_directories": ["/path/to/zim/files"],
"cache_enabled": true,
"config_hash": "abc123...",
"server_pid": 12345
},
"diagnostics": {
"validation_status": "healthy",
"conflicts_detected": [],
"warnings": [],
"recommendations": []
}
}

diagnose_server_state - 全面的服务器诊断

无需参数。

返回值： 详细的诊断信息，包括实例冲突、配置验证、文件可访问性检查和可操作的建议。

示例响应：

{
"status": "healthy",
"server_info": {
"pid": 12345,
"server_name": "openzim-mcp",
"config_hash": "abc123..."
},
"conflicts": [],
"issues": [],
"recommendations": ["Server appears to be running normally"],
"environment_checks": {
"directories_accessible": true,
"cache_functional": true
}
}

resolve_server_conflicts - 识别和解决服务器冲突

无需参数。

返回值： 冲突解决的结果，包括清理操作和建议。

示例响应：

{
"status": "success",
"cleanup_results": {
"stale_instances_removed": 2
},
"conflicts_found": [],
"actions_taken": ["Removed 2 stale instance files"],
"recommendations": ["No active conflicts detected"]
}

其他搜索示例

{
"name": "search_zim_file",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"query": "computer",
"limit": 2
}
}

响应：

找到 39 个与 "computer" 匹配的结果，显示 1 - 2 条：

## 1. Video game
Path: Video_game
Snippet: #  Video game First-generation _Pong_ console at the Computerspielemuseum Berlin
---
Platforms

## 2. Protein
Path: Protein
Snippet: #  Protein A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

{
"name": "get_zim_entry",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"entry_path": "Evolution",
"max_content_length": 1500
}
}

响应：

# Evolution

Path: Evolution
Type: text/html
## Content

#  Evolution

Part of the Biology series on
---
****
Mechanisms and processes

* Adaptation
* Genetic drift
* Gene flow
* History of life
* Maladaptation
* Mutation
* Natural selection
* Neutral theory
* Population genetics
* Speciation

... [内容截断，总共 110,237 个字符，仅显示前 1,500 个字符] ...

高级知识检索示例

{
"name": "get_zim_metadata",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim"
}
}

响应：

{
"entry_count": 100000,
"all_entry_count": 120000,
"article_count": 80000,
"media_count": 20000,
"metadata_entries": {
"Title": "Wikipedia (English)",
"Description": "Wikipedia articles in English",
"Language": "eng",
"Creator": "Kiwix",
"Date": "2025-08-15"
}
}

{
"name": "browse_namespace",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"namespace": "C",
"limit": 5,
"offset": 0
}
}

响应：

{
"namespace": "C",
"total_in_namespace": 80000,
"offset": 0,
"limit": 5,
"returned_count": 5,
"has_more": true,
"entries": [
{
"path": "C/Biology",
"title": "Biology",
"content_type": "text/html",
"preview": "Biology is the scientific study of life..."
}
]
}

{
"name": "search_with_filters",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"query": "evolution",
"namespace": "C",
"content_type": "text/html",
"limit": 3
}
}

{
"name": "get_article_structure",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"entry_path": "C/Evolution"
}
}

响应：

{
"title": "Evolution",
"path": "C/Evolution",
"content_type": "text/html",
"headings": [
{"level": 1, "text": "Evolution", "id": "evolution"},
{"level": 2, "text": "History", "id": "history"},
{"level": 2, "text": "Mechanisms", "id": "mechanisms"}
],
"sections": [
{
"title": "Evolution",
"level": 1,
"content_preview": "Evolution is the change in heritable traits...",
"word_count": 150
}
],
"word_count": 5000
}

{
"name": "get_search_suggestions",
"arguments": {
"zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
"partial_query": "bio",
"limit": 5
}
}

响应：

{
"partial_query": "bio",
"suggestions": [
{"text": "Biology", "path": "C/Biology", "type": "title_start_match"},
{"text": "Biochemistry", "path": "C/Biochemistry", "type": "title_start_match"},
{"text": "Biodiversity", "path": "C/Biodiversity", "type": "title_start_match"}
],
"count": 3
}

服务器管理和诊断示例

{
"name": "get_server_health"
}

响应：

{
"status": "healthy",
"server_name": "openzim-mcp",
"uptime_info": {
"process_id": 12345,
"started_at": "2025-09-14T10:30:00"
},
"cache_performance": {
"enabled": true,
"size": 15,
"max_size": 100,
"hit_rate": 0.85
},
"instance_tracking": {
"active_instances": 1,
"conflicts_detected": 0
}
}

{
"name": "diagnose_server_state"
}

响应：

{
"status": "healthy",
"server_info": {
"pid": 12345,
"server_name": "openzim-mcp",
"config_hash": "abc123def456..."
},
"conflicts": [],
"issues": [],
"recommendations": ["Server appears to be running normally. No issues detected."],
"environment_checks": {
"directories_accessible": true,
"cache_functional": true,
"zim_files_found": 5
}
}

{
"name": "resolve_server_conflicts"
}

响应：

{
"status": "success",
"cleanup_results": {
"stale_instances_removed": 2,
"files_cleaned": ["/home/user/.openzim_mcp_instances/server_99999.json"]
},
"conflicts_found": [],
"actions_taken": ["Removed 2 stale instance files"],
"recommendations": ["No active conflicts detected after cleanup"]
}

🎯 ZIM 条目检索最佳实践

智能检索系统

OpenZIM MCP 实现了一个智能条目检索系统，该系统可以自动处理 ZIM 文件中常见的路径编码不一致问题：

• 工作原理：
  1. 优先直接访问：尝试使用提供的路径精确检索条目。
  2. 自动回退：如果直接访问失败，会自动使用各种搜索词搜索该条目。
  3. 路径映射缓存：缓存成功的路径映射，以提高重复访问的性能。
  4. 增强的错误指导：当找不到条目时，提供清晰的指导。
• 对大语言模型用户的好处：
  • 透明操作：无需了解 ZIM 路径编码的复杂性。
  • 单次工具调用：无需手动先进行搜索。
  • 可靠结果：在不同的路径格式（空格与下划线、URL 编码等）下都能保持一致的成功率。
  • 性能优化：缓存的映射提高了重复访问的速度。
• 自动处理的示例场景：
  • A/Test Article → A/Test_Article（空格转换为下划线）
  • C/Café → C/Caf%C3%A9（URL 编码差异）
  • A/Some-Page → A/Some_Page（连字符转换为下划线）

使用建议

直接条目访问：

{
"name": "get_zim_entry",
"arguments": {
"zim_file_path": "/path/to/file.zim",
"entry_path": "A/Article_Name"
}
}

条目未找到时： 系统将自动提供指导：

条目未找到：'A/Article_Name'。
该条目路径可能不存在于这个 ZIM 文件中。
尝试使用 search_zim_file() 查找可用条目，
或使用 browse_namespace() 探索文件结构。

⚠️ 重要注意事项和限制

内容长度要求

• get_zim_entry 的 max_content_length 参数必须至少为 1000 个字符。
• 超过指定限制的内容将被截断，并显示总字符数。

搜索行为

• 搜索结果可能包括在各种上下文中包含搜索词的文章。
• 结果按相关性排序，但可能并不总是与搜索词的主要含义直接相关。
• 搜索片段提供了内容的预览，但可能不显示搜索词的确切位置。

文件格式支持

• 目前支持 ZIM 文件（Zeno IMproved 格式）。
• 已使用维基百科 ZIM 文件（例如 wikipedia_en_100_2025-08.zim）进行测试。
• 文件路径在 JSON 中必须正确转义（Windows 路径使用 \\）。

🔄 多服务器实例管理

实例跟踪特性

• 自动实例注册：每个服务器实例都会自动使用唯一的进程 ID 和配置哈希进行注册。
• 冲突检测：检测多个具有不同配置的服务器访问相同目录的情况。
• 陈旧实例清理：自动识别并清理已终止进程的孤立实例文件。
• 配置验证：确保所有服务器实例使用兼容的配置。

冲突类型

1. 配置不匹配：多个具有不同设置的服务器访问相同的目录。
2. 多个实例：多个服务器同时运行（可能会导致混淆）。
3. 陈旧实例：已终止进程的孤立实例文件。

自动冲突警告

当检测到问题时，OpenZIM MCP 会自动在搜索结果和文件列表中包含冲突警告：

🔍 **检测到服务器冲突**
⚠️ 与服务器 PID 12345 的配置不匹配。搜索结果可能不一致。
💡 使用 'resolve_server_conflicts()' 解决这些问题。

最佳实践

• 定期使用 diagnose_server_state() 检查冲突。
• 运行 resolve_server_conflicts() 清理陈旧实例。
• 当访问共享目录时，确保所有服务器实例使用相同的配置。
• 使用 get_server_health() 监控服务器健康状况，获取实例跟踪信息。

🔧 配置

OpenZIM MCP 支持通过带有 OPENZIM_MCP_ 前缀的环境变量进行配置：

# 缓存配置
export OPENZIM_MCP_CACHE__ENABLED=true
export OPENZIM_MCP_CACHE__MAX_SIZE=200
export OPENZIM_MCP_CACHE__TTL_SECONDS=7200

# 内容配置
export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000
export OPENZIM_MCP_CONTENT__SNIPPET_LENGTH=2000
export OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT=20

# 日志配置
export OPENZIM_MCP_LOGGING__LEVEL=DEBUG
export OPENZIM_MCP_LOGGING__FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"

# 服务器配置
export OPENZIM_MCP_SERVER_NAME=my_openzim_mcp_server

配置选项

设置	默认值	描述
OPENZIM_MCP_CACHE__ENABLED	true	启用/禁用缓存
OPENZIM_MCP_CACHE__MAX_SIZE	100	最大缓存条目数
OPENZIM_MCP_CACHE__TTL_SECONDS	3600	缓存的 TTL（秒）
OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH	100000	最大内容长度
OPENZIM_MCP_CONTENT__SNIPPET_LENGTH	1000	最大片段长度
OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT	10	默认搜索结果限制
OPENZIM_MCP_LOGGING__LEVEL	INFO	日志级别
OPENZIM_MCP_LOGGING__FORMAT	%(asctime)s - %(name)s - %(levelname)s - %(message)s	日志消息格式
OPENZIM_MCP_SERVER_NAME	openzim-mcp	服务器实例名称

🔒 安全特性

• 路径遍历保护：安全的路径验证可防止访问允许目录之外的内容。
• 输入清理：所有用户输入都经过验证和清理。
• 资源管理：正确清理 ZIM 存档资源。
• 错误处理：清理后的错误消息可防止信息泄露。
• 类型安全：完整的类型注解可防止与类型相关的漏洞。

🚀 性能特性

• 智能缓存：具有 TTL 的 LRU 缓存，用于频繁访问的内容。
• 资源池化：高效的 ZIM 存档管理。
• 优化的内容处理：快速的 HTML 到文本转换。
• 懒加载：仅在需要时初始化组件。
• 内存管理：正确的清理和资源管理。

🧪 测试

该项目包括全面的测试，覆盖率超过 90%，使用了模拟数据和真实的 ZIM 文件：

测试类别

• 单元测试：使用模拟数据对单个组件进行测试。
• 集成测试：使用真实的 ZIM 文件进行端到端功能测试。
• 安全测试：进行路径遍历和输入验证测试。
• 性能测试：进行缓存和资源管理测试。
• 格式兼容性：测试各种 ZIM 文件格式和版本。
• 错误处理：使用无效和格式错误的 ZIM 文件进行测试。

测试基础设施

OpenZIM MCP 使用混合测试方法：

1. 基于模拟的测试：使用模拟的 libzim 组件进行快速单元测试。
2. 真实 ZIM 文件测试：使用官方的 zim-testing-suite 文件进行集成测试。
3. 自动测试数据管理：根据需要下载和组织测试文件。

测试数据来源

• 内置测试数据：仓库中包含的基本测试文件。
• zim-testing-suite 集成：来自 OpenZIM 项目的官方测试文件。
• 环境变量支持：使用 ZIM_TEST_DATA_DIR 指定自定义测试数据位置。

# 运行带覆盖率报告的测试
make test-cov

# 查看覆盖率报告
open htmlcov/index.html

# 使用真实的 ZIM 文件运行全面测试
make test-with-zim-data

测试标记

测试使用 pytest 标记进行组织：

• @pytest.mark.requires_zim_data：需要 ZIM 测试数据文件的测试。
• @pytest.mark.integration：集成测试。
• @pytest.mark.slow：长时间运行的测试。

📈 监控

OpenZIM MCP 提供内置的监控功能：

• 健康检查：监控服务器的健康状况和状态。
• 缓存指标：缓存命中率和性能统计信息。
• 结构化日志：JSON 格式的日志，便于解析。
• 错误跟踪：全面的错误日志记录和跟踪。

🔄 版本管理

本项目使用 语义化版本控制，并通过 release-please 进行自动版本管理。

自动发布

版本升级和发布基于 Conventional Commits 自动进行：

• feat: - 新特性（次版本升级）
• fix: - 错误修复（补丁版本升级）
• feat!: 或 BREAKING CHANGE: - 重大变更（主版本升级）
• perf: - 性能改进（补丁版本升级）
• docs:、style:、refactor:、test:、chore: - 不进行版本升级

发布流程

该项目使用一个 改进的、统一的发布系统，并进行自动验证：

1. 自动（推荐）：推送符合规范的提交 → Release Please 创建 PR → 合并 PR → 自动发布
2. 手动：使用 GitHub Actions UI 直接控制发布
3. 紧急情况：直接推送标签以进行关键修复

关键特性：

• ✅ 主分支的零接触发布
• ✅ 自动版本同步验证
• ✅ 每次发布前的全面测试
• ✅ 改进的错误处理和回滚能力
• ✅ 分支保护 防止发布失败

详细说明请参阅 发布流程指南。

提交消息格式

<类型>[可选范围]: <描述>

[可选正文]

[可选脚注]

示例：

feat: add search suggestions endpoint
fix: resolve path traversal vulnerability
feat!: change API response format
docs: update installation instructions

🤝 贡献

1. 分叉仓库。
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)。
3. 进行更改。
4. 运行测试 (make check)。
5. 使用符合规范的提交消息 (git commit -m 'feat: add amazing feature')。
6. 将更改推送到分支 (git push origin feature/amazing-feature)。
7. 打开一个拉取请求。

开发指南

• 遵循 PEP 8 风格指南。
• 为所有函数添加类型提示。
• 为新功能编写测试。
• 根据需要更新文档。
• 使用符合规范的提交消息 以实现自动版本控制。
• 在提交前确保所有测试通过。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Kiwix 提供 ZIM 格式和 libzim 库。
• MCP 提供模型上下文协议。
• 开源社区提供了本项目中使用的优秀库。