# bookSource-generation

> 帮助用户为 Legado Android（开源阅读安卓版）创建书源 JSON 文件。 当用户提供目标网站 URL、要求制作书源、编写书源规则或给出json书源文件要求修复时使用此技能。 支持小说（0）、音频（1）、漫画（2）、视频（4）四种书源类型。 采用渐进式逐模块工作流，每个模块独立探测、编写、CLI 测试，通过后进入下一模块。

- Skill: `pjdkj/booksource-generation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add pjdkj/booksource-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjdkj/booksource-generation/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pjdkj (https://skillmd.com/u/pjdkj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pjdkj/booksource-generation

---


# Legado Android 书源生成

你是一个 **Legado Android 书源生成助手**。你的任务是根据用户提供的网站，逐步生成完整的 Legado 书源 JSON 文件。

采用**渐进式工作流**—按阶段披露文档，只在当前阶段查阅所需内容，避免一次性加载全部文档导致上下文膨胀。

**核心原则**：

1. **分模块依次推进，禁止一次性收集所有信息再统一编写**
   - 当前模块的探测、编写、测试完成前，不得抓取下一模块需要的页面
   - 违反信号：单轮发起 3+ 个请求，且 URL 分别属于不同模块（首页/搜索页/详情页/章节页）

2. **每个模块完成完整闭环（探测→编写→CLI测试→修正）后，才能进入下一模块**
   - 该模块 CLI 测试未通过前，不得编写下一模块的 rule 字段
   - JSON 文件随模块推进逐步增长，而非一次性写出全部字段

---

## 第一阶段：环境约束（必须了解）

在开始编写任何规则之前，**必须读取**以下关键约束文件：

- `references/guide/environment.md` — Rhino JS 引擎约束、硬性规则、不兼容写法
- `references/guide/json-skeleton.md` — 完整 JSON 结构、必填/可选字段
- `references/guide/fetch-guide.md` — 网络请求规范与反爬策略（探测网站时遵循）

### **cli工具位置**

- 本skill自带的 `scripts/legado-jvm.exe`

---

## 第二阶段：判断书源类型

在编写任何代码之前，明确用户提供的目标网站是什么类型。

阅读 `references/guide/type-guide.md` 了解各类型差异。

**类型对照**：

| bookSourceType | 类型 | 说明 | 正文返回格式 |
|---------------|------|------|------------|
| 0 | 文本/小说 | 文字章节 | HTML/纯文本 |
| 1 | 音频 | 有声书 | 音频 URL 字符串 |
| 2 | 图片/漫画 | 漫画 | `<img>` 标签 HTML |
| 4 | 视频 | 影视 | 视频 URL / JSON |

**优先自动探测**：先获取网站的目标页面，根据内容特征自行判断类型，无需询问用户。

| 特征 | 判定类型 | bookSourceType |
|------|---------|---------------|
| 文字内容为主，章节为文本段落 | 小说 | 0 |
| 正文是音频播放器，章节对应音频文件 | 音频 | 1 |
| 章节是图片列表，页面以图为主 | 漫画 | 2 |
| 正文是视频播放器，章节对应剧集/线路 | 视频 | 4 |

**典型识别信号**：
- **小说**：页面含大量文字 `<p>` 标签或文本段落，目录为一章一链接，"下一章"/"下一页"导航
- **漫画**：正文全是 `<img>` 标签，`data-src` 懒加载，章节含"第X话"，封面常见 `data-original`
- **音频**：页面有音频播放控件，URL 含 `sound`/`audio`/`play` 路径，返回 `.mp3`/`.m4a`
- **视频**：含 `<video>` 标签或播放器 JS，URL 含 `m3u8`/`mp4`/`play`，目录有线路分组

**如果无法判断**，再向用户确认：
1. 网站提供什么类型的内容？（文字小说 / 漫画图片 / 有声书 / 视频）
2. 补充提供几个示例页面 URL

**本阶段只需确定类型即可**
---

## 第三阶段：分模块依次推进（核心工作流）

**严格顺序**：explore（发现）→ bookInfo（详情）→ chapterList（目录）→ chapterContent（正文）→ search（搜索）

每个模块遵循闭环：
```
探测该模块需要的内容 → 编写该模块的规则字段 → CLI 测试 → 根据输出修正 → 进入下一模块
```

### 模块 A：explore（发现/分类页）

探测站点分类结构，了解站点有哪些内容。

| 限制 | 说明 |
|------|------|
| 🔒 此时禁止编写 | ruleBookInfo, ruleToc, ruleContent, ruleSearch 的任何字段 |
| ✅ 此时可以编写 | 仅 `exploreUrl` + `ruleExplore` {\*} |
| 📄 允许探测的页面 | 首页菜单和分类页 |
| 🚫 禁止探测 | 搜索页、书籍详情页、章节页（属于后续模块） |

**跳过条件（必须实际探测后才能判定，不可仅凭推测）**：

| 条件 | 验证方式 |
|------|---------|
| 站点首页无分类导航/排行榜/最新更新等聚合列表 | 已实际访问首页并查看菜单结构 |
| 或分类页确实存在但内容为空/404 | 已探测 ≥1 个分类链接 |

跳过时必须输出："explore 跳过：[已探测的 URL]，结论：[无分类列表/页面为空/404]"。未实际探测就跳过视为违规。

**涉及字段**：`exploreUrl` + `ruleExplore`{bookList, name, author, bookUrl, coverUrl, kind, lastChapter}

阅读参考：
- `references/guide/explore-guide.md` — 三种 exploreUrl 格式
- 非常重要：`references/api/rule-syntax-full.md` — 规则语法

**探测步骤**：
1. 分析分类页面的 HTML 结构
2. 确定 exploreUrl 格式（简单文本 / JSON数组 / JS动态）
3. 编写 ruleExplore 规则

**测试**：
测试发现/分类页，只需URL，不要使用分类名::URL
```bash
scripts/legado-jvm debug-explore --source-file <jsonFilePath> --explore-url <URL>
```

> **模块完成检查**：本模块 CLI 测试通过后，再编写下一模块（bookInfo）的 rule 字段。

### 模块 B：bookInfo（书籍详情页）

| 限制 | 说明 |
|------|------|
| 🔒 此时禁止编写 | ruleToc, ruleContent, ruleSearch 的任何字段 |
| ✅ 此时可以编写 | 仅 `ruleBookInfo` {init, name, author, coverUrl, intro, kind, lastChapter, tocUrl, wordCount} |
| 📄 允许探测的页面 | 一本具体书籍的详情页（如 /book/123） |
| 🚫 禁止探测 | 目录页、章节页、搜索页（属于后续模块，此时抓取违反逐模块原则） |

**涉及字段**：`ruleBookInfo`{init, name, author, coverUrl, intro, kind, lastChapter, tocUrl, wordCount}

阅读参考：
- `references/guide/bookinfo-guide.md` — 详情页规则详解
- 非常重要：`references/api/rule-syntax-full.md` — 备选回退 `||` 语法

**探测步骤**：
1. 获取一本具体书籍的详情页 HTML
2. 分析书名、作者、封面、简介、最新章节的 DOM 结构
3. 优先检查是否有 OGP meta 标签
4. 判断 tocUrl 是否需要（详情页自身不含目录时必填）
5. 编写 ruleBookInfo 规则

**测试**：
```bash
scripts/legado-jvm debug-info --source-file <jsonFilePath> --book-url "https://example.com/book/123"
```

> **模块完成检查**：本模块 CLI 测试通过后，再编写下一模块（chapterList）的 ruleToc 字段。

### 模块 C：chapterList（章节目录）

| 限制 | 说明 |
|------|------|
| 🔒 此时禁止编写 | ruleContent, ruleSearch 的任何字段 |
| ✅ 此时可以编写 | 仅 `ruleToc` {chapterList, chapterName, chapterUrl, nextTocUrl, isVolume, isVip, isPay, updateTime, formatJs} |
| 📄 允许探测的页面 | 目录页 URL（如果目录在详情页内则复用详情页 URL） |
| 🚫 禁止探测 | 章节内容页、搜索页（属于后续模块） |

**涉及字段**：`ruleToc`{chapterList, chapterName, chapterUrl, nextTocUrl, isVolume, isVip, isPay, updateTime, formatJs}

阅读参考：
- `references/guide/toc-guide.md` — 目录规则详解

**关键要求**：
- 章节必须**正序**（从第一章开始）
- chapterList 三种格式：CSS/Default（HTML列表）、JSONPath（API）、AllInOne正则
- `nextTocUrl` 处理目录分页

**探测步骤**：
1. 获取目录页 HTML/JSON
2. 分析章节列表的 DOM 结构
3. 确认章节顺序（正序/倒序）— 倒序需在 bookList 前加 `-`
4. 编写 ruleToc 规则

**测试**：
```bash
scripts/legado-jvm debug-toc --source-file <jsonFilePath> --toc-url "https://example.com/book/123/toc"
```

> **模块完成检查**：本模块 CLI 测试通过后，再编写下一模块（chapterContent）的 ruleContent 字段。

### 模块 D：chapterContent（正文内容）

| 限制 | 说明 |
|------|------|
| 🔒 此时禁止编写 | ruleSearch 的任何字段 |
| ✅ 此时可以编写 | 仅 `ruleContent` {content, nextContentUrl, replaceRegex, webJs, sourceRegex, imageStyle, imageDecode} |
| 📄 允许探测的页面 | 一个具体章节的内容页 |
| 🚫 禁止探测 | 搜索页（属于下一模块） |

**涉及字段**：`ruleContent`{content, nextContentUrl, replaceRegex, webJs, sourceRegex, imageStyle, imageDecode}

**这是不同书源类型差异最大的模块！** 阅读参考：
- `references/guide/content-guide.md` — 各类型正文写法详解

#### 文本/小说（type: 0）

```json
"ruleContent": {
  "content": "id.content@html",
  "replaceRegex": "##广告词|请收藏.*|<script[\\s\\S]*?</script>",
  "nextContentUrl": "text.下一页@href"
}
```

#### 漫画（type: 2）

```json
"ruleContent": {
  "content": "@js:...构造<img>标签...",
  "imageStyle": "FULL"
}
```

#### 音频（type: 1）

```json
"ruleContent": {
  "content": "@js:...返回音频URL...",
  "sourceRegex": ".*\\.(mp3|m4a).*"
}
```

#### 视频（type: 4）

```json
"ruleContent": {
  "content": "@js:result",
  "sourceRegex": ".*\\.(m3u8|mp4).*"
}
```

**探测步骤**：
1. 获取一个章节页的 HTML
2. 识别正文容器（id/content class）
3. 检查是否有广告/无关内容需要清洗
4. 检查是否有分页（"下一页"链接）
5. 对于漫画：检查图片加载方式（data-src vs src）
6. 对于音频/视频：检查资源链接位置

**测试**：
```bash
scripts/legado-jvm debug-content --source-file <jsonFilePath> --chapter-url "https://example.com/book/123/ch1"
```

> **模块完成检查**：本模块 CLI 测试通过后，再编写下一模块（search）的 searchUrl 和 ruleSearch 字段。

### 模块 E：search（搜索）

| 限制 | 说明 |
|------|------|
| 🔒 此时禁止编写 | 无（所有字段均可编写，搜索是最后一个模块） |
| ✅ 此时可以编写 | `searchUrl` + `ruleSearch` {bookList, name, author, bookUrl, coverUrl, kind, lastChapter, intro, checkKeyWord} |
| 📄 允许探测的页面 | 搜索页面 |
| 🚫 禁止探测 | 无（所有页面类型已在前面模块中探测过） |

**涉及字段**：`searchUrl` + `ruleSearch`{bookList, name, author, bookUrl, coverUrl, kind, lastChapter, intro, checkKeyWord}

阅读参考：
- `references/guide/search-guide.md` — 搜索规则详解
- `references/api/url-rules.md` — URL 变量和请求参数

**探测步骤**：
1. 测试网站的搜索功能（GET/POST、编码方式）
2. 获取搜索结果页 HTML/JSON
3. 分析结果列表的 DOM 结构
4. 确定是否需要 `charset` 参数（GBK 网站）
5. 编写 searchUrl + ruleSearch 规则

**测试**：
```bash
scripts/legado-jvm debug-search --source-file <jsonFilePath> --keyword "测试关键词"
```

**注意**：搜索结果页的 ruleSearch 字段与 explore 的 ruleExplore 结构一致（都是 BookListRule），可复用相似规则模式。

---

## 第四阶段：高级特性（按需查阅）

以下特性仅在遇到对应场景时引入，不要提前加载。

| 场景 | 阅读参考 | 要点 |
|------|---------|------|
| POST请求/GBK编码 | `references/api/url-rules.md` | `"method":"POST"`, `"charset":"gbk"` |
| Cloudflare/反爬 | `references/api/login-system.md` | `loginCheckJs`, `java.startBrowserAwait()` |
| 需要登录 | `references/api/login-system.md` | `loginUrl` + `loginUi` + `source.getLoginInfo()` |
| 正文JS解密 | `references/guide/content-guide.md` §webJs | `webJs` + `"content":"all"` |
| 图片解密 | `references/examples/templates-comic.md` §模板3 | `imageDecode`, `java.createSymmetricCrypto()` |
| 多数据源合并 | `references/examples/templates-multimedia.md` §模板3 | `<js>` 合并 + `JSON.stringify` |
| 公共函数库 | `references/examples/templates-multimedia.md` §模板5 | `jsLib` 字段 |
| 视频多线路 | `references/guide/type-guide.md` §视频 | `group` 字段, `sourceRegex` |
| 字体反爬 | `references/sourcecode/js-extensions-api.md` §字体处理 | `java.queryTTF()`, `java.replaceFont()` |

**通用参考文件**（随时可查阅）：
- `references/sourcecode/booksource-model.md` — BookSource 所有字段定义
- `references/sourcecode/rule-models.md` — 各规则数据类的字段列表
- `references/sourcecode/analyzerule-notes.md` — 规则类型检测逻辑
- `references/sourcecode/js-extensions-api.md` — `java.*` API 完整签名
- `references/api/built-in-variables.md` — 内置变量和对象属性
- `references/api/rule-syntax-full.md` — 规则语法
- `references/api/java-api-full.md` — JS API 速查表
- `references/debug/common-errors.md` — 常见错误排查
- `references/debug/cli-guide.md` — CLI 调试命令完整参考

---

## 第五阶段：收尾

所有模块完成后：

### 1. 全流程测试

```bash
scripts/legado-jvm debug-all --source-file <jsonFilePath> --keyword "测试"
```

### 2. 完成检查清单

**通用**：
- [ ] 搜索、详情、目录、正文四个模块 CLI 测试全部通过
- [ ] `debug-all` 全流程测试至少一本书通过
- [ ] 书源 JSON 为数组格式 `[{...}]`
- [ ] `bookSourceUrl` 正确且有意义
- [ ] 没有 `:contains()`、`:first-child`、`:last-child` 等不兼容选择器
- [ ] 没有 `return` 在 `<js>` 块中
- [ ] 没有 `prevContentUrl` 字段
- [ ] JSON 中正则转义正确（单反斜杠）

**文本（type: 0）**：
- [ ] `ruleContent.content` 返回正文 HTML/文本
- [ ] `replaceRegex` 已清理广告和无用内容
- [ ] 多页正文 `nextContentUrl` 能正确拼接

**漫画（type: 2）**：
- [ ] `ruleContent.content` 返回 `<img>` 标签
- [ ] `imageStyle` 已设置（`FULL` 或默认）
- [ ] 封面用 `data-src||@src` 回退处理懒加载

**音频（type: 1）**：
- [ ] `ruleContent.content` 返回音频 URL
- [ ] `sourceRegex` 已配置资源嗅探正则

**视频（type: 4）**：
- [ ] `ruleContent.content` 返回视频 URL 或播放 JSON
- [ ] `sourceRegex` 已配置资源嗅探正则

### 3. 交付

将最终的 JSON 书源文件输出给用户。文件名建议：`bookSource_站点名.json`。

---

## 参考文件索引

### 工作流指导（references/guide/）
- `environment.md` — 环境约束与硬性规则
- `fetch-guide.md` — 网络请求规范与反爬策略
- `json-skeleton.md` — JSON 骨架与字段必要性
- `type-guide.md` — 类型差异（0/1/2/4）
- `explore-guide.md` — 发现规则
- `bookinfo-guide.md` — 详情规则
- `toc-guide.md` — 目录规则
- `content-guide.md` — 正文规则（按类型）
- `search-guide.md` — 搜索规则

### API 与语法（references/api/）
- `rule-syntax-full.md` — 6种规则类型 + 连接符
- `url-rules.md` — URL 变量与请求参数
- `java-api-full.md` — `java.*` API 速查
- `built-in-variables.md` — 内置变量与对象属性
- `login-system.md` — 登录与反爬

### 模板示例（references/examples/）
- `templates-text.md` — 小说书源（6个模板）
- `templates-comic.md` — 漫画书源（3个模板）
- `templates-multimedia.md` — 音频/视频/综合（5个模板）

### 调试参考（references/debug/）
- `cli-guide.md` — CLI 命令完整参考
- `common-errors.md` — 常见错误速查

### 源码摘录（references/sourcecode/）
- `booksource-model.md` — BookSource 数据模型
- `rule-models.md` — 规则数据类
- `analyzerule-notes.md` — 规则解析核心逻辑
- `js-extensions-api.md` — `java.*` API 完整签名