LSBible SDK：结构化圣经数据获取与AI集成的开发实践

1. 项目概述：为AI圣经研究打造的多语言SDK

如果你正在开发与圣经内容相关的应用，无论是个人灵修工具、教会管理软件，还是想将经文无缝集成到AI助手（比如Claude、Cursor）中，你大概率会遇到一个头疼的问题：如何稳定、可靠且结构化地获取圣经文本？自己爬取网站？格式解析一团糟；使用传统API？往往只返回原始HTML或难以处理的字符串，更别提对经文引用（如“约翰福音3:16”）进行严格的验证了。这正是kdcokenny/lsbible这个开源项目要解决的核心痛点。

这是一个为Legacy Standard Bible (LSB)官方阅读网站read.lsbible.org构建的、多语言（目前支持TypeScript和Python）的软件开发工具包（SDK）项目。但它的野心远不止是一个简单的API客户端包装。它通过一套精心设计的、强类型的编程接口，将圣经文本从网页HTML转换成了开发者可以直接操作的、结构化的数据对象。这意味着你可以用client.getVerse(BookName.JOHN, 3, 16)这样清晰、安全的方式获取经文，而不是去拼接和解析容易出错的字符串。更重要的是，它原生集成了Model Context Protocol (MCP)服务器，这使得你可以零代码地将整本LSB圣经作为“知识库”或“工具”，直接挂载到Claude Desktop、Cursor、Windsurf等20多种支持MCP的AI应用里。想象一下，在写代码或与AI对话时，直接让Claude“查一下哥林多前书13章关于爱的经文”，并立刻得到准确、格式完整的回答——这个项目让这变成了开箱即用的现实。

我之所以花时间深入研究并实践这个项目，是因为在构建宗教类或文本密集型应用时，数据源的规范性和易用性直接决定了开发效率和最终产品的稳定性。LSB本身是一个强调逐字翻译准确性的现代译本，其网站结构清晰，为自动化处理提供了良好基础。而这个SDK项目，则是在此基础上，为开发者铺平了道路。无论你是想快速构建一个圣经查询机器人，还是为一个复杂的在线教育平台集成经文内容，亦或是单纯想探索AI如何与结构化宗教文本互动，这个工具包都提供了一个极为专业的起点。接下来，我将带你深入拆解它的设计哲学、实战用法以及那些在官方文档里不会明说的“坑”与技巧。

2. 核心设计哲学：为什么“结构化参数”优于“字符串解析”？

在接触这个SDK时，你首先会注意到一个鲜明的设计选择：它彻底摒弃了传统圣经API常见的字符串传参方式（如getVerse("John 3:16")），转而强制使用结构化参数（如getVerse(BookName.JOHN, 3, 16)）。这绝非为了标新立异，而是源于一线开发中血泪教训的总结。让我们深入剖析其背后的逻辑。

2.1 传统字符串解析的陷阱

为什么字符串解析是“万恶之源”？我们来看几个典型场景：

1. 歧义性：“1 John 2:1” 指的是《约翰一书》第2章第1节，但一个简单的字符串解析器如何区分“1”是书名的一部分还是章节号？它需要一套复杂的、包含所有书卷缩写和别名的规则库。
2. 输入容错：用户可能输入“jn 3:16”、“JOHN 3:16”、“John3:16”甚至带有全角冒号的“John 3：16”。处理所有这些变体需要大量的正则表达式和清洗逻辑，且极易遗漏边缘情况。
3. 无即时反馈：当你调用getVerse("Jonah 4:11")时，如果《约拿书》只有4章，第11节不存在，这个错误只有在请求发送到服务器并返回后才会被发现。这意味着网络延迟和无效的API调用。
4. 工具链支持差：在IDE中，字符串无法提供自动补全。你无法通过输入BookName.然后按Tab键快速选择书卷名，必须手动记忆和键入，容易拼写错误。

这个SDK的设计者显然深受其苦，因此采用了“将验证提前到编译时或运行时最早时刻”的策略。

2.2 枚举（Enum）与强类型验证的威力

该SDK为66卷圣经书卷定义了一个完整的枚举（在TypeScript中是BookName，在Python中也是BookName）。这样做带来了立竿见影的好处：

• 绝对的准确性：BookName.JOHN永远指向《约翰福音》，不存在任何歧义。像《约翰一书》、《约翰二书》、《约翰三书》则分别对应BookName.JOHN_1,BookName.JOHN_2,BookName.JOHN_3，从根源上杜绝了混淆。
• 极致的开发体验：现代IDE（如VSCode、PyCharm）可以对枚举值进行自动补全和代码导航。你不需要记住“腓利门书”的英文是“Philemon”，只需输入BookName.P然后从列表中选择。这大幅降低了开发者的认知负担和出错概率。
• 编译时/静态检查：在TypeScript中，如果你错误地传递了BookName.JOHN_4（不存在），类型检查器会在你写代码的时候就报错。在Python中，虽然是在运行时验证，但验证逻辑在本地SDK内，速度极快，无需网络往返。

2.3 参数结构化带来的衍生优势

这种设计像多米诺骨牌一样，引发了一系列积极的连锁反应：

• 测试变得极其简单：你可以轻松地用循环遍历BookName枚举、章节和节数范围来生成测试用例，进行全面的冒烟测试。而用字符串方式，构造测试用例本身就是一个容易出错的过程。
• API契约清晰稳定：方法的签名(book: BookName, chapter: number, verse: number)明确无误地定义了契约。任何调用者都必须遵守这个格式，这使得代码的可读性和可维护性大大增强。
• 多语言SDK的一致性：由于核心设计是“结构化参数优先”，为不同编程语言实现SDK时，可以保持几乎相同的接口设计。TypeScript和Python的用法高度相似，降低了跨语言开发者的学习成本。
• 便于扩展：未来如果要支持获取一个范围内的经文（如“约翰福音3:16-18”），可以自然地扩展为getVerses(BookName.JOHN, 3, 16, 18)，结构依然清晰。而字符串方式可能需要引入更复杂的语法解析器。

实操心得：拥抱枚举，远离字符串魔法在我过去的项目中，曾因为字符串解析的bug（将“Song of Solomon”错误匹配）导致生产环境显示错误经文，教训深刻。自那以后，我在处理任何有固定集合的数据（如国家、省份、状态码、书卷名）时，都优先考虑使用枚举或常量对象。这不仅是SDK的设计，更是一种值得推广的最佳实践。当你看到BookName枚举时，就应该意识到，这背后是一套旨在提升软件可靠性和开发效率的成熟工程思想。

3. 实战指南：三大使用场景深度解析

这个SDK提供了三种不同层次的使用方式，从“零代码”的AI集成到“全代码”的应用开发，覆盖了从普通用户到资深开发者的全部需求。我们逐一拆解。

3.1 场景一：作为MCP服务器集成（面向AI用户与开发者）

这是项目最亮眼、也是门槛最低的功能。MCP（Model Context Protocol）是一个由Anthropic推出的开放协议，旨在让AI模型能够安全、可控地访问外部工具和数据源。简单说，它让Claude这类AI能“使用”你提供的工具。

3.1.1 MCP服务器能做什么？安装并配置好LSBible的MCP服务器后，你的AI助手（如Claude Desktop）将获得以下能力：

• 自然语言查询经文：你可以直接对话：“请给我出埃及记20章1-17节（十诫）的内容。” AI会调用MCP工具获取经文并呈现在对话中。
• 智能搜索：“圣经中哪里提到了‘好撒玛利亚人’的比喻？” AI会执行搜索并返回相关经文及上下文。
• 获取圣经元数据：“圣经有多少卷书？新约有哪些书？” AI可以查询内置的圣经结构数据。
• 生成学习材料：结合AI的推理能力，你可以要求它“根据罗马书第8章，生成一个小组讨论问题列表”。AI在拥有经文上下文后，能做出更精准、相关的回应。

3.1.2 安装与配置详解安装方式有两种，推荐给不同用户：

• 远程服务器（最简单）：适用于绝大多数用户。你只需要在MCP客户端的配置文件中添加一行服务器地址。以Claude Desktop为例，找到其配置文件（通常在~/.config/claude/desktop-config.json或类似路径），在mcpServers部分添加：

  { "lsbible": { "command": "npx", "args": ["-y", "lsbible-mcp"] } }

  或者使用作者提供的托管服务（如果可用）：

  { "lsbible": { "url": "https://lsbible.kdco.dev/mcp" } }

  重启Claude Desktop即可。这种方式无需安装Node.js或任何依赖，由服务提供商维护，最为省心。

• 本地运行（适合开发者或需要离线/定制）：你需要先安装Node.js环境，然后通过npm全局安装或直接运行项目包。

  # 方法1：使用npx临时运行（每次启动Claude都会执行） # 配置文件中command和args如上所示。 # 方法2：全局安装后运行 npm install -g lsbible # 然后在配置文件中，command改为 "lsbible-mcp"

注意事项：网络环境与权限

1. 网络连接：MCP服务器（无论是本地还是远程）在响应AI查询时，仍需访问read.lsbible.org获取数据。请确保运行环境网络通畅。
2. 安全提示：首次配置时，Claude Desktop可能会提示“是否允许来自未知服务器的连接”。这是因为MCP服务器使用了自签名证书或非标准端口。请确认你添加的服务器地址是可信的（如官方的kdcokenny/lsbible仓库中提到的地址），然后放心允许。
3. 多客户端支持：除了Claude，Cursor、Windsurf、Continue.dev等主流AI编程助手都支持MCP。配置方法类似，具体请查阅各自客户端的文档。这个SDK的MCP实现是通用的，一次配置，多端受益。

3.2 场景二：使用TypeScript SDK进行应用开发

如果你正在构建一个Web应用、Node.js服务或任何JavaScript/TypeScript项目，并需要集成圣经内容，那么TypeScript SDK是你的不二之选。

3.2.1 安装与初始化首先，通过npm安装SDK：

npm install lsbible

然后，在你的代码中初始化客户端。客户端设计为无状态的，通常可以作为一个单例使用。

import { LSBibleClient, BookName, type VerseResponse } from 'lsbible'; // 创建客户端实例。默认会使用内置的缓存（TTL 1小时）以减少API调用。 const client = new LSBibleClient(); // 你也可以自定义缓存配置，例如禁用缓存或调整TTL（生存时间）。 import { MemoryCache } from 'lsbible'; const clientWithCustomCache = new LSBibleClient({ cache: new MemoryCache({ ttl: 1800 }), // 缓存30分钟 });

3.2.2 核心操作：获取经文与解析富文本获取单节经文是最基本的操作，但返回的数据结构却非常丰富。

async function demonstrateVerseFetch() { try { const passage: VerseResponse = await client.getVerse(BookName.JOHN, 3, 16); // 1. 访问纯文本内容（最常用） console.log(passage.verses[0].plainText); // 输出: "For God so loved the world, that He gave His only Son..." // 2. 遍历段落（Paragraph）和经文（Verse） for (const paragraph of passage.paragraphs) { console.log(`段落类型: ${paragraph.type}`); // e.g., "paragraph", "heading" for (const verse of paragraph.verses) { console.log(` 第${verse.verseNumber}节: ${verse.plainText}`); } } // 3. 深入挖掘富文本格式（这是LSB的特色，也是SDK的亮点） const firstVerse = passage.verses[0]; for (const segment of firstVerse.segments) { let prefix = ''; if (segment.isRedLetter) prefix = '[耶稣的话] '; if (segment.isItalic) prefix = '[译者添加] '; if (segment.isSmallCaps) prefix = '[神圣名] '; // 代表YHWH console.log(prefix + segment.text); } // 输出可能类似： // [耶稣的话] For God so loved the world, // that He gave His only Son... } catch (error) { // 错误处理：可能是网络错误、无效的经文引用等。 console.error('获取经文失败:', error); } }

3.2.3 高级功能：搜索与元数据查询除了按坐标获取，全文搜索是另一个强大功能。

async function demonstrateSearch() { const results = await client.search('love', { limit: 10 }); // 搜索“爱”，限制前10条结果 console.log(`共找到 ${results.matchCount} 处匹配。`); // 1. 查看搜索结果分布（非常实用的分析功能） if (results.hasSearchMetadata) { console.log('--- 按圣经部分分布 ---'); for (const [section, count] of Object.entries(results.countsBySection)) { console.log(`${section}: ${count} 次`); } // 输出可能： // Gospels: 45 // Pauline Epistles: 101 // General Epistles: 12 // 这让你一眼看出“爱”这个概念在新约书信中讨论最多。 } // 2. 遍历具体的经文结果 for (const item of results.items) { console.log(`\n${item.reference} (${item.bookName} ${item.chapter}:${item.verse})`); console.log(item.snippet); // 显示包含搜索词的关键片段 } // 3. 获取整章内容 const entireChapter = await client.getChapter(BookName.PSALMS, 23); console.log(`诗篇23篇共有${entireChapter.verseCount}节经文。`); // 适合用于一次性显示整章，避免多次请求。 }

3.3 场景三：使用Python SDK进行数据分析与后端集成

对于数据科学、自动化脚本或Django/Flask后端服务，Python SDK提供了同样强大的功能，并充分利用了Python生态的优势（如Pydantic、httpx）。

3.3.1 安装与上下文管理器推荐使用uv这个更快的Python包管理器，当然pip也可以。

# 使用 uv uv pip install lsbible # 或使用 pip pip install lsbible

Python SDK的客户端实现了上下文管理器协议，推荐使用with语句来确保资源被正确清理，尽管对于简单的脚本，直接实例化也可以。

from lsbible import LSBibleClient, BookName # 推荐方式：使用上下文管理器 with LSBibleClient() as client: passage = client.get_verse(BookName.JOHN, 3, 16) print(passage.verses[0].plain_text) # 简单脚本也可直接使用 client = LSBibleClient() passage = client.get_verse(BookName.JOHN, 3, 16)

3.3.2 利用Pydantic模型进行数据验证与转换Python SDK使用Pydantic v2来定义所有数据模型，这带来了巨大的优势。

from lsbible import LSBibleClient, BookName, VerseResponse from pydantic import ValidationError client = LSBibleClient() try: # 获取的数据会自动被VerseResponse模型校验 passage: VerseResponse = client.get_verse(BookName.JOHN, 3, 16) # 1. 模型是“冻结的”（frozen=True），防止意外修改，保证数据一致性。 # passage.verses[0].plain_text = "修改内容" # 这行会抛出AttributeError # 2. 方便的数据导出与序列化 verse_dict = passage.verses[0].model_dump() # 转换为字典 print(verse_dict['plain_text']) verse_json = passage.verses[0].model_dump_json() # 转换为JSON字符串 # 非常适合存入数据库（如JSON字段）或通过API返回。 # 3. 类型提示完善，IDE支持极佳 # 在VSCode或PyCharm中，输入 `passage.` 后IDE会提示所有可用属性： # .verses, .paragraphs, .reference, .translation 等。 except ValidationError as e: # 如果API返回的数据结构与模型不匹配（极少数情况，如网站改版），会在此捕获错误。 print(f"数据验证失败: {e}") # 这时应该回退到降级方案或通知维护者。

3.3.3 构建实际应用示例：一个简单的经文查询CLI工具让我们结合argparse和rich库，快速构建一个美观的命令行查询工具。

# bible_cli.py import argparse from rich.console import Console from rich.table import Table from rich import print as rprint from lsbible import LSBibleClient, BookName, LSBibleError console = Console() def get_and_display_verse(book_name: str, chapter: int, verse: int): """根据书卷名、章、节获取并格式化显示经文""" try: # 将字符串书卷名转换为枚举（这里需要一点映射，实际可以做得更完善） # 简化示例：假设输入是标准的英文全称，如“John” book_enum = getattr(BookName, book_name.upper()) except AttributeError: console.print(f"[red]错误：未找到书卷 '{book_name}'。请使用英文标准名（如John, Genesis）。[/red]") return try: with LSBibleClient() as client: passage = client.get_verse(book_enum, chapter, verse) # 使用Rich创建漂亮的输出 table = Table(title=f"[bold blue]{passage.reference}[/bold blue]", show_header=False) table.add_column("内容", style="white", no_wrap=False) for para in passage.paragraphs: for v in para.verses: text_to_display = v.plain_text # 高亮显示耶稣的话（红字） # 注意：这里简化处理，实际应遍历segments table.add_row(f"[bold]{v.verseNumber}[/bold]. {text_to_display}") console.print(table) console.print(f"\n[i]译文: {passage.translation}[/i]") except LSBibleError as e: console.print(f"[red]获取经文时出错: {e}[/red]") def search_bible(keyword: str, limit: int = 5): """搜索圣经并显示结果分布""" with LSBibleClient() as client: results = client.search(keyword, limit=limit) console.print(f"[bold green]搜索词 '{keyword}' 共找到 {results.match_count} 处匹配。[/bold green]") if results.has_search_metadata: dist_table = Table(title="匹配分布（按圣经部分）") dist_table.add_column("部分", style="cyan") dist_table.add_column("匹配数", style="magenta") for section, count in results.counts_by_section.items(): dist_table.add_row(section, str(count)) console.print(dist_table) console.print("\n[bold]前{limit}条结果：[/bold]") for idx, item in enumerate(results.items, 1): console.print(f"{idx}. [yellow]{item.reference}[/yellow]: {item.snippet}") if __name__ == "__main__": parser = argparse.ArgumentParser(description="LSB圣经命令行查询工具") subparsers = parser.add_subparsers(dest='command', help='可用命令') # 查询经文命令 verse_parser = subparsers.add_parser('verse', help='查询特定经文') verse_parser.add_argument('book', help='书卷名，如 John, Genesis') verse_parser.add_argument('chapter', type=int, help='章号') verse_parser.add_argument('verse', type=int, help='节号') # 搜索命令 search_parser = subparsers.add_parser('search', help='搜索经文内容') search_parser.add_argument('keyword', help='搜索关键词') search_parser.add_argument('-l', '--limit', type=int, default=5, help='显示结果数量限制') args = parser.parse_args() if args.command == 'verse': get_and_display_verse(args.book, args.chapter, args.verse) elif args.command == 'search': search_bible(args.keyword, args.limit) else: parser.print_help()

运行示例：

python bible_cli.py verse John 3 16 python bible_cli.py search love --limit 3

4. 深入架构：SDK内部运作机制与最佳实践

理解了怎么用，我们再来看看它“为什么”这么稳定好用。剖析其内部架构，能帮助我们在更复杂的场景下用好它，甚至为贡献代码做准备。

4.1 客户端与缓存策略解析

LSBibleClient类是这个SDK的门面。它的核心工作流程如下：

1. 接收结构化请求：如(BookName.JOHN, 3, 16)。
2. 本地验证：调用validators模块，检查章节号是否在该书卷的有效范围内（例如，《约拿书》只有4章，请求第5章会立即抛出InvalidChapterError）。这是避免无效网络请求的第一道防线，也是响应速度快的秘诀之一。
3. 检查缓存：如果启用了缓存（默认是MemoryCache），客户端会先用请求参数生成一个缓存键，查询内存中是否有未过期的结果。缓存键的设计通常包含了书卷、章、节和翻译版本，确保不同请求不会冲突。
4. 构造API请求：如果缓存未命中，则向https://read.lsbible.org/_next/data/{buildId}/index.json发起HTTP GET请求。这里有个关键点：buildId。这是Next.js构建的哈希ID，网站更新时会变。SDK内部有一个机智的机制，会先从网站首页抓取最新的buildId，然后再用这个ID去请求数据。这保证了SDK总能与网站最新版本兼容，无需手动升级。
5. 解析与转换：API返回的是包含HTML片段的JSON。parser模块（TypeScript用LinkedOM，Python用BeautifulSoup）会解析HTML，识别出段落、经文、以及红字、斜体等格式标签，将其转换为结构化的Verse、Paragraph、TextSegment对象。
6. 模型验证与返回：解析后的数据被送入Pydantic/Zod模型进行最终验证，确保结构完全符合预期，然后返回给调用者。同时，结果会被存入缓存。

缓存策略建议：

• 默认内存缓存：对于短期运行的单机脚本或服务器，默认的MemoryCache(TTL=3600秒) 非常合适。它减少了重复请求，加快响应速度。
• 分布式缓存场景：如果你在云函数（如AWS Lambda）或无状态容器中运行，内存缓存会在每次冷启动时失效。此时，可以考虑实现一个基于Redis或Memcached的缓存适配器，替换默认的MemoryCache。SDK的缓存接口设计是抽象的，理论上可以实现ICache接口来接入任何存储后端。
• 禁用缓存：在开发调试或需要实时获取网站最新内容（尽管LSB网站本身不常更新）时，可以传入cache: null来禁用缓存。

4.2 错误处理与健壮性设计

一个优秀的SDK必须有清晰的错误处理。LSBible SDK定义了一系列自定义异常/错误类：

• InvalidReferenceError：引用的书卷、章、节无效。例如，请求《马太福音》第100章。
• BibleParserError：解析从API获取的HTML时出错。这可能意味着网站HTML结构发生了变化，需要更新SDK的解析逻辑。
• APIError：网络请求失败、API返回非200状态码等。
• CacheError：缓存操作失败（比较少见）。

最佳实践：编写健壮的调用代码

from lsbible import LSBibleClient, BookName, InvalidReferenceError, BibleParserError, APIError client = LSBibleClient() try: response = client.get_verse(BookName.PSALMS, 151, 1) # 诗篇只有150篇 except InvalidReferenceError as e: # 处理无效引用：可以提示用户，或记录日志 print(f"请求的经文引用无效，请检查：{e}") # 可以在这里提供一个友好的回退，比如推荐诗篇23篇。 except BibleParserError as e: # 解析错误：通常是网站结构变化，需要通知开发者或使用降级方案 print(f"解析圣经内容时发生意外错误，这可能是临时问题。") # 可以考虑记录详细的错误信息和原始响应，便于上报issue。 # logger.error(f"Parser failed. Raw data: {e.raw_data}") except APIError as e: # 网络或API错误：检查网络连接，或重试 print(f"网络请求失败: {e}") if e.status_code == 429: print("请求过于频繁，请稍后再试。") except Exception as e: # 捕获其他未预期的异常 print(f"发生未知错误: {e}")

4.3 性能考量与优化建议

1. 批量请求的缺失与应对：当前SDK主要提供单节 (getVerse) 和单章 (getChapter) 的获取。如果你需要获取大量不连续的经文（例如，一个包含100处不同经文的阅读计划），频繁的HTTP请求会成为瓶颈。

   • 优化策略：在应用层实现一个简单的“请求队列”或“批量获取器”。你可以收集一段时间内（比如用户一次操作中）的所有经文引用，虽然不能合并为一个API请求（因为网站API可能不支持），但可以使用异步并发来同时发起多个请求，显著减少总等待时间。在Python中可以用asyncio.gather，在TypeScript/Node.js中可以用Promise.all。

   import asyncio # 假设有一个异步客户端（当前SDK是同步的，此处为概念示例） async def fetch_many_verses(references): tasks = [client.get_verse_async(ref.book, ref.chapter, ref.verse) for ref in references] return await asyncio.gather(*tasks, return_exceptions=True)

2. 缓存是性能的关键：务必利用好缓存。对于静态内容（圣经文本几乎不变），设置较长的TTL（如24小时）是安全的。这能极大提升重复访问的速度，并减轻对源站的压力。

3. 解析开销：HTML解析（特别是BeautifulSoup）有一定开销。getChapter获取整章内容进行一次解析，比多次调用getVerse获取同一章的不同节要高效得多。因此，在已知需要整章内容时，务必使用getChapter方法。

5. 常见问题排查与实战技巧

在实际集成和使用过程中，你可能会遇到一些典型问题。以下是我在测试和模拟使用中总结出的排查清单和技巧。

5.1 安装与依赖问题

5.2 运行时与API问题

5.3 高级技巧与最佳实践

1. 构建离线版本或备用数据源：虽然SDK依赖在线API，但对于需要高可用性的应用（如宣教地区的离线应用），可以考虑定期将整本LSB圣经（通过循环调用getChapter）爬取并存储到本地数据库（如SQLite的JSON字段或PostgreSQL）。然后，基于本地数据实现一个兼容LSBibleClient接口的“离线客户端”。注意：务必尊重LSB的版权和许可，仅用于合法、合理的使用场景。

2. 与前端框架集成：在React/Vue.js应用中，可以将LSBibleClient封装成一个自定义Hook或Composable函数，并集成状态管理（如Zustand、Pinia），管理经文数据的加载状态、缓存和错误。

   // React Hook示例 (概念) import { useState, useEffect } from 'react'; import { LSBibleClient, BookName } from 'lsbible'; const client = new LSBibleClient(); function useBibleVerse(book: BookName, chapter: number, verse: number) { const [data, setData] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); useEffect(() => { const fetchVerse = async () => { setLoading(true); setError(null); try { const passage = await client.getVerse(book, chapter, verse); setData(passage); } catch (err) { setError(err); } finally { setLoading(false); } }; fetchVerse(); }, [book, chapter, verse]); // 依赖项变化时重新获取 return { data, loading, error }; }

3. 扩展SDK功能：如果你需要SDK未提供的功能（例如，获取每日经文、根据主题查询相关经文列表），可以在不修改原SDK的基础上，创建一个“服务层”或“工具类”。这个类内部使用LSBibleClient，对外提供更高级的、符合你业务逻辑的API。

   # advanced_bible_service.py from lsbible import LSBibleClient, BookName from typing import List from dataclasses import dataclass @dataclass class DailyReading: date: str passages: List # 包含多个经文引用 class AdvancedBibleService: def __init__(self): self.client = LSBibleClient() # 可以预加载一个阅读计划 self.reading_plan = self._load_reading_plan() def get_daily_reading(self, date_str: str) -> DailyReading: """根据日期获取当日阅读经文""" # ... 实现根据日期查找阅读计划的逻辑 plan_for_today = self.reading_plan.get(date_str) passages = [] for ref in plan_for_today: passage = self.client.get_chapter(ref.book, ref.chapter) # 获取整章 passages.append(passage) return DailyReading(date=date_str, passages=passages) def _load_reading_plan(self): # 从文件或数据库加载一个预设的读经计划 pass

这个项目以其严谨的设计、对开发者体验的重视以及对新兴AI生态（MCP）的快速拥抱，为圣经软件开发者提供了一个近乎“工业级”的起点。它解决的不是“从零到一”的问题，而是“从一到一百”的问题——让你能专注于构建应用独特的价值，而不是反复折腾数据获取和解析的基础设施。无论你的目标是一个简单的查询工具，还是一个深度集成AI的复杂研究平台，kdcokenny/lsbibleSDK都值得你将其纳入技术选型的评估清单。