当前位置：首页 > news >正文

AI自动化生成Legado书源：基于MCP协议与网页解析的实践指南

news 2026/5/6 14:31:32

1. 项目概述：用AI解放双手，为Legado阅读器自动生成书源

如果你是一名深度阅读爱好者，并且恰好使用的是安卓平台上功能强大的开源阅读应用“Legado”（阅读），那么你一定对“书源”这个概念又爱又恨。爱的是，一个优质的书源能让你在App里畅读全网小说，体验丝滑；恨的是，寻找、维护甚至自己编写一个稳定可用的书源，过程往往充满了技术门槛和不确定性。你需要分析网页结构，编写复杂的CSS选择器或正则表达式，调试JSON规则，这对于非开发者来说，无异于一道天堑。

今天要聊的这个项目——legadoSkill，就是为了解决这个痛点而生的。它本质上是一个AI驱动的自动化工具，其核心目标就是：让你无需任何编程知识，只需提供一个小说网站的URL，它就能自动分析网站结构，并生成一个可供Legado App直接使用的、格式正确的书源JSON文件。简单来说，它把“写书源”这个技术活，变成了“填网址”这个简单操作。

我作为一个长期折腾各种阅读工具和自动化脚本的老玩家，初次接触这个项目时，第一反应是“终于有人把这个想法做出来了”。传统的书源制作，要么依赖社区大神分享（时效性差，容易失效），要么需要自己硬啃规则文档（学习成本高）。legadoSkill的思路则是将AI的网页理解能力与Legado的书源规则相结合，实现“所见即所得”的自动化生成。这对于想要扩展自己书库，但又不想陷入技术细节的普通用户来说，无疑是一个福音。

接下来，我将结合自己的实际测试和使用经验，为你深度拆解legadoSkill的工作原理、详细部署步骤、核心使用技巧，以及过程中可能遇到的“坑”和解决方案。无论你是刚接触Legado的新手，还是苦于维护书源的老鸟，这篇文章都能给你提供一条全新的、更高效的路径。

2. 核心原理与架构拆解：AI如何“看懂”网页并生成规则

在深入实操之前，我们有必要先搞清楚legadoSkill是怎么工作的。知其然，更要知其所以然，这样在遇到问题时，你才能心中有数，知道该从哪个环节入手排查。

2.1 Legado书源的本质：一套数据抓取规则

首先，我们要明白Legado的书源文件（一个.json文件）到底是什么。它并不是包含了小说内容本身，而是一套详细的“说明书”或“导航图”，告诉Legado App：

去哪里找书：即搜索功能的URL和参数格式。
如何解析搜索结果：从搜索结果页的HTML中，如何提取出每一本书的标题、作者、封面、详情页链接。
如何进入书籍详情页：书籍详情页的URL规则。
如何解析目录：从详情页或目录页中，如何提取出所有章节的标题和链接。
如何解析正文：从章节链接对应的页面中，如何提取出纯净的小说正文，并过滤掉广告、导航栏等无关信息。

这个过程，传统上完全依赖人工分析。你需要用浏览器的开发者工具（F12）查看网页元素，找到包含目标信息的HTML标签，然后编写对应的CSS选择器或正则表达式。这不仅繁琐，而且一旦网站改版，所有规则可能瞬间失效。

2.2 legadoSkill的AI赋能：从“人工分析”到“智能识别”

legadoSkill引入AI，正是为了替代上述人工分析中最核心、最耗时的部分：网页结构理解与信息定位。

它的工作流程可以概括为以下几个步骤：

网页获取与预处理：工具首先会访问你提供的目标URL，下载网页的HTML源码。为了提高AI分析的准确性，它可能会对HTML进行一些清理工作，比如规范化标签、移除某些干扰脚本等。
AI模型分析：这是核心环节。项目利用了基于MCP（Model Context Protocol）协议的AI客户端（如Trae IDE）。MCP可以理解为一种让AI模型更规范、更高效地使用工具和数据的协议。AI模型（很可能是类似GPT-4 Vision或Claude-3这类具有强大多模态理解能力的模型）会“阅读”整个网页的HTML结构。
关键信息识别与标注：AI的任务是像人一样，识别出网页中哪些部分是“书籍列表”，哪些是“单个书籍条目”，在条目中哪个元素是“标题”，哪个是“作者”，哪个是“链接”。它通过理解HTML的语义和视觉布局（尽管没有直接渲染，但标签结构隐含了布局信息）来完成这一点。
规则生成：识别出关键信息及其对应的HTML元素路径（例如，div.book-list > ul > li:nth-child(1) > a.title）后，AI会将这些路径转换成Legado书源规则能理解的格式，主要是CSS选择器，有时也会结合正则表达式。
JSON文件组装与验证：最后，工具将这些生成的规则填充到一个预设的书源JSON模板中，组装成一个完整的书源文件。它可能还会进行基础的验证，比如检查必要的字段（如bookSourceName,bookSourceUrl,ruleSearch等）是否都已正确生成。

为什么选择MCP协议？这是该项目设计上的一个亮点。MCP协议允许AI技能（Skill）以标准化的方式被封装和调用。legadoSkill本身就是一个MCP Skill。这意味着它不仅可以被Trae IDE调用，理论上任何兼容MCP协议的客户端（如Claude Desktop、Cursor IDE等）都可以集成并使用它，极大地提高了工具的通用性和可集成性。

注意：这里的“AI”并非指一个本地运行的大型神经网络，而是通过API调用云端的大语言模型（LLM）。因此，使用此工具需要稳定的网络连接，并且可能涉及相关AI服务的使用条款。

3. 环境准备与详细部署指南

纸上得来终觉浅，绝知此事要躬行。理论讲完，我们进入实战环节。根据项目说明，legadoSkill主要支持Windows平台，并依赖Python环境。下面是我一步步踩过来的详细部署流程。

3.1 基础环境搭建：Python与Git

1. 安装Python 3.8+这是整个工具的运行时环境。前往Python官网下载安装程序。这里有个关键细节：

务必勾选“Add Python to PATH”。这会将Python和pip（包管理工具）添加到系统环境变量，让你能在任何命令行窗口直接使用python和pip命令。如果安装时忘了勾选，后续命令会提示“不是内部或外部命令”，需要手动配置环境变量，比较麻烦。
安装完成后，打开命令提示符（Win+R，输入cmd），输入python --version和pip --version验证是否安装成功。

2. 获取legadoSkill项目代码项目代码托管在GitHub上。你有两种方式获取：

方式一（推荐，便于更新）：安装Git，然后在你想存放项目的目录（如D:\Tools）下打开命令提示符，执行：
```
git clone https://github.com/rezmdie/legadoSkill.git
```
这会将整个项目仓库克隆到本地。
方式二（简单）：直接访问项目的GitHub页面，点击“Code”按钮，选择“Download ZIP”，下载压缩包后解压到任意目录。

3.2 依赖安装与虚拟环境（高级但推荐）

直接使用系统Python安装依赖可能会污染全局环境。作为最佳实践，我强烈建议使用虚拟环境。

创建虚拟环境：在项目根目录（即包含requirements.txt的目录）下打开命令提示符。
```
# 创建名为 venv 的虚拟环境 python -m venv venv
```
激活虚拟环境：
```
# Windows venv\Scripts\activate
```
激活后，命令行提示符前会出现(venv)字样，表示你已进入隔离环境。
安装项目依赖：确保在虚拟环境激活状态下，执行：
```
pip install -r requirements.txt
```
如果pip版本过旧导致安装失败，可以先升级pip：python -m pip install --upgrade pip。
实操心得：requirements.txt文件通常位于项目根目录或debugger/子目录下，具体看项目结构。如果安装过程中报错，通常是网络问题或某个包缺少系统级依赖（如Windows上可能需要Microsoft C++ Build Tools）。耐心查看错误信息，或尝试使用国内镜像源加速：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。

3.3 配置AI客户端（以Trae IDE为例）

legadoSkill设计为在MCP客户端中运行。Trae IDE是官方示例中提到的客户端。你需要先下载并安装Trae IDE。

安装与启动：从Trae官网下载安装包，完成安装后启动。
导入legadoSkill：在Trae IDE中，通常会有“导入Skill”或“添加工具”的选项。你需要指向本地legadoSkill项目的根目录。具体路径可能因Trae版本而异，可能需要你指定包含skill.json或类似配置文件的目录。
可能的API密钥配置：如果legadoSkill的后端AI服务需要API密钥（例如调用OpenAI或Anthropic的API），你可能需要在Trae IDE的设置中，或legadoSkill的配置文件（如.env文件或config.py）中进行配置。这是最容易卡住的一步，因为原始项目文档可能未明确说明。你需要查看项目代码里是否有关于API配置的提示。

备选方案：命令行直接运行如果暂时不想配置Trae IDE，项目也可能提供了直接的命令行入口。查看项目根目录下是否有main.py、cli.py或run.py这样的文件。你可以尝试在激活的虚拟环境中运行：

python main.py --help

查看它支持哪些参数。如果支持，可能会是类似这样的用法：

python main.py --url "https://www.example-novel-site.com"

但这取决于项目作者是否实现了完整的CLI接口。

4. 核心使用流程与实战解析

假设你已经成功部署并配置好了环境，我们来看如何使用它来生成一个真正的书源。

4.1 目标网站分析与准备

不是所有网站都适合被自动化抓取。在开始前，你需要为目标网站做个“体检”：

选择结构清晰的网站：优先选择那些书籍列表、详情页布局规整，广告干扰少的正版或知名小说网站。过于复杂或严重依赖JavaScript渲染的网站（如某些现代Web App），AI解析的难度会大大增加。
获取关键URL：
- 搜索URL：打开目标网站，搜索一本你知道的书（如“斗破苍穹”）。观察浏览器地址栏，URL会发生变化。例如，可能变成https://www.xxx.com/search?keyword=斗破苍穹。这个URL模板（将关键词替换为{{key}}）就是书源中ruleSearch规则需要的。
- 书籍详情页URL：点击进入一本书的详情页，复制这个URL。
应对反爬措施：一些网站可能有简单的反爬机制。如果AI分析失败，你可能需要检查：
- 网站是否要求登录后才能查看？legadoSkill通常无法处理登录会话。
- 网站是否屏蔽了常见的爬虫User-Agent？这可能需要你在工具配置中修改请求头。

4.2 在Trae IDE中运行生成

这是最直观的方式，假设legadoSkill已成功导入Trae。

启动技能：在Trae IDE中找到已导入的legadoSkill，通常它会以一个可交互工具的形式出现。
输入参数：工具界面可能会要求你输入以下信息：
- base_url: 网站的域名，例如https://www.example-novel-site.com。
- search_url: 搜索URL模板（可选，AI可能会尝试自动发现）。
- example_detail_url: 一个具体的书籍详情页URL（非常重要，作为AI分析页面结构的样本）。
触发分析：点击运行或分析按钮。Trae IDE会将你的请求和网页内容发送给背后的AI模型进行处理。
获取结果：处理完成后，AI会返回一段JSON文本。这就是生成的Legado书源。Trae IDE可能会直接显示，或提供保存为文件的选项。
初步验证：将生成的JSON内容复制出来，保存为一个.json文件，例如example_novel.json。

4.3 生成书源的测试与调试

AI生成的规则并非100%完美，必须进行测试。

导入Legado App：在Legado App中，进入“书源管理” -> “本地导入”，选择你刚刚保存的example_novel.json文件。
功能测试：
- 搜索测试：在Legado的书源界面，使用导入的书源搜索你在准备阶段用的那本书。看是否能正确列出结果，并且标题、作者、封面信息正确。
- 详情页测试：点击搜索结果进入详情页，查看简介、目录是否能够正常加载。
- 阅读测试：选择第一章，尝试打开。这是最关键的一步，检查正文是否能够正确、完整、干净地显示，没有缺失段落或混杂大量广告。
常见问题与手动微调：
- 搜索无结果：可能是搜索URL规则或参数不对。你需要用浏览器开发者工具仔细对比手动搜索和书源搜索发出的网络请求差异，然后手动修改书源JSON中ruleSearch下的url和params字段。
- 目录获取失败：目录规则（ruleToc）可能不正确。你需要分析网站目录页的HTML结构，修正chapter的list选择器。有时目录是分页的，还需要处理nextTocUrl规则。
- 正文内容杂乱：正文规则（ruleContent）可能选取了过多元素。你需要加强净化规则，在ruleContent中添加replaceRegex或利用filter字段移除不需要的标签（如<script>,<div class="ad">等）。
核心技巧：legadoSkill生成的规则是一个极好的起点。即使它不完美，也完成了80%的工作——帮你定位到了核心的元素区域。剩下的20%微调，你可以借助浏览器开发者工具和Legado内置的“规则调试”功能（在书源编辑界面）来完成。这比从零开始写整个书源要轻松得多。

5. 进阶技巧与生态整合

当你熟悉基本流程后，可以探索一些更高级的用法，让legadoSkill发挥更大价值。

5.1 利用项目内置资源加速

仔细查看legadoSkill的项目仓库，你可能会发现一些宝藏：

预置规则/模板：作者可能为一些常见的小说网站（如起点、纵横、番茄等）已经编写了部分规则或模板。这些可以作为AI学习的样本，或者在你生成类似网站书源时直接参考甚至复用。检查项目下的templates/、rules/或examples/目录。
调试工具：debugger/目录下的工具可能帮助你更直观地看到AI分析的中间过程，或者手动测试CSS选择器，这对于理解和调试规则至关重要。
知识库：项目可能包含一个知识库文件，用于教AI某种特定网站的结构模式。你可以通过学习其格式，尝试为自己常看的冷门网站补充知识，提升生成质量。

5.2 与自动化工作流结合

legadoSkill的终极形态是融入自动化流水线。

批量生成：如果你有一批同类型的小说网站需要制作书源，可以编写一个简单的Python脚本，循环调用legadoSkill的命令行接口（如果存在）或API，传入不同的URL，自动生成一批书源文件。
书源验证与监控：书源失效是常态。你可以结合爬虫定时任务，用脚本定期用生成的书源去访问目标网站的关键页面（如搜索、目录），检查返回内容是否正常。一旦发现异常，可以触发警报甚至尝试用legadoSkill重新分析生成新规则。
集成到自有工具：由于它遵循MCP协议，理论上你可以将它集成到你自己开发的任何工具或平台中，为你的用户提供一键生成书源的功能。

5.3 理解局限性并合理预期

必须清醒认识到当前AI工具的局限性：

动态内容：对于大量使用JavaScript异步加载内容的网站，legadoSkill获取到的初始HTML可能是空的，AI无法分析有效结构。这需要配合无头浏览器（如Playwright）先渲染页面，但会大大增加复杂度和运行开销。
复杂交互：需要登录、验证码、或点击“展开更多”才能获取完整目录的网站，目前的AI技能可能难以处理。
规则泛化能力：AI基于一个或几个样例页面生成的规则，不一定能完美覆盖网站的所有页面状态（如搜索无结果时的页面、不同分类的列表页）。生成的规则可能需要人工补充一些条件判断。
成本与延迟：每次调用都涉及大模型API，可能有使用成本，并且分析速度取决于网络和模型响应时间，不如离线规则快。

因此，legadoSkill的最佳定位是“书源制作辅助工具”或“快速原型生成器”。它极大地降低了入门门槛和初始工作量，但产出的“毛坯”书源，经常需要有一定经验的用户进行最终的精装修和测试，才能成为一个稳定可靠的生产级书源。

6. 故障排除与经验实录

在实际操作中，你肯定会遇到各种问题。下面是我在测试过程中遇到的一些典型情况及其解决方法，希望能帮你少走弯路。

6.1 环境与依赖问题

问题1：pip install失败，提示某些包编译错误（特别是Windows上）。

原因：某些Python包（如cryptography,lxml等）包含C语言扩展，需要本地编译环境。
解决：安装Microsoft Visual C++ Build Tools。更简单的方法是，寻找该包的预编译轮子（wheel）。对于常用包，通常有针对不同Python版本和系统的预编译版本。可以使用pip install package_name --only-binary=:all:尝试强制使用二进制包，或者到 https://www.lfd.uci.edu/~gohlke/pythonlibs/ 这个非官方站点下载对应的.whl文件，然后用pip install xxx.whl安装。

问题2：运行工具时提示模块找不到（ModuleNotFoundError）。

原因：可能未在正确的虚拟环境中运行，或者依赖未安装完全。
解决：
1. 确认命令行前有(venv)标识。
2. 重新执行pip install -r requirements.txt。
3. 检查错误信息中缺失的具体模块名，尝试手动安装：pip install module_name。

6.2 AI客户端与连接问题

问题3：Trae IDE中无法识别或加载legadoSkill。

原因：Skill路径配置错误，或Trae IDE版本与Skill不兼容。
解决：
1. 仔细阅读legadoSkill项目README中关于Trae集成的部分。
2. 在Trae IDE中检查Skill的加载日志或错误信息。
3. 尝试在Trae IDE的社区或设置中寻找“手动安装Skill”的选项，确保指向包含skill.json（或类似入口文件）的目录。

问题4：AI分析过程长时间无响应或报错“API错误”。

原因：网络连接问题，或AI服务提供商（如OpenAI）的API密钥未设置、额度用尽、或请求频率超限。
解决：
1. 检查网络连接。
2. 重点检查API配置：在legadoSkill项目目录下寻找如.env.example,config.yaml,settings.py等配置文件。按照示例格式创建你自己的配置文件（如.env），并填入从AI服务商处获取的有效API密钥。你需要注册相应的AI服务（如OpenAI, Anthropic）并获取密钥。
3. 查看AI服务商后台的用量统计和错误日志。

6.3 书源生成与调试问题

问题5：生成的书源在Legado中搜索，列表显示乱码或错位。

原因：AI生成的CSS选择器可能不够精确，抓取到了多余的元素或属性。
解决：使用Legado的“规则调试”功能。在书源编辑界面，找到ruleSearch->books->list规则，点击调试。Legado会显示当前选择器匹配到的所有元素。你需要像侦探一样，对比网页HTML，调整选择器使其精确匹配到每个书籍条目块。通常需要加上更具体的父级选择器或使用:nth-child等伪类。

问题6：能搜索到书，但目录为空或正文加载失败。

原因：目录页或正文页的URL构造规则有误，或者页面内容是通过JavaScript动态加载的。
解决：
1. URL规则：检查书源中ruleToc的url规则。它可能依赖于搜索结果的某个属性，如$.resultUrl或$.detailUrl。确保这个属性在搜索规则ruleSearch的book字段中被正确提取。
2. 动态加载：这是硬骨头。首先在浏览器中打开目标章节页，按F12打开开发者工具，切换到“网络”(Network)选项卡，刷新页面。查看页面主要内容是通过哪个XHR或Fetch请求获取的（通常是返回JSON或HTML片段的请求）。如果能找到这个请求，你需要修改书源规则，将ruleContent的url指向这个API地址，并可能需要添加header和body参数来模拟请求。这超出了legadoSkill当前自动化的范围，需要手动分析。

问题7：生成的规则过于复杂或脆弱，网站稍一改版就失效。

原因：AI可能学习了页面中一些易变的属性，如带有随机哈希的class名（class=”div_abc123”）。
解决：人工优化规则。优先使用稳定的特征：
- 标签名+结构：如div.content > ul > li。
- 有语义的class/id：如class=”book-item”,id=”chapter-list”。
- 属性选择器：匹配部分固定文本，如a[href*=”/chapter/”]。
- 尽量避免使用:nth-of-type(n)这种依赖固定位置的规则，除非结构绝对稳定。

最后，也是最重要的一个体会：保持耐心，善用社区。legadoSkill是一个强大的工具，但它不是魔法。书源制作本身就是一个需要结合技术理解和耐心调试的工作。当遇到无法解决的问题时，不妨将你生成的书源JSON和目标网站URL分享到Legado相关的社区或论坛（如GitHub、酷安等），很多有经验的开发者乐于提供帮助。同时，关注legadoSkill项目的更新，作者可能会持续优化AI模型或增加对新类型网站的支持。

查看全文

http://www.jsqmd.com/news/764140/