#+TITLE: Kobo Manga Pipeline
#+AUTHOR: Cytrogen
#+OPTIONS: toc:2

自动化漫画下载-转换-导入流水线，从漫画源下载漫画，转换为 KEPUB 推送到 Kobo e-reader。

* 功能

- 插件化漫画源架构，自行开发源适配器
- 并发下载引擎，支持重试与断点续传
- 图片处理（裁边、缩放、灰度转换等，可配置）
- KEPUB 打包（固定布局 EPUB3，RTL 日漫阅读顺序）
- 传输到 Kobo（USB 直传 / Calibre）
- 订阅追更与调度

* 安装

需要 Python 3.12+ 和 [[https://docs.astral.sh/uv/][uv]]。

#+begin_src bash
git clone <repo-url>
cd kobo-manga
uv sync
#+end_src

* 使用

** 搜索漫画

#+begin_src bash
uv run kobo-manga search "漫画名"
uv run kobo-manga search "漫画名" -s <源名称>
#+end_src

** 下载

#+begin_src bash
uv run kobo-manga download "漫画名" -c 1-10
#+end_src

** 订阅追更

#+begin_src bash
uv run kobo-manga subscribe "漫画名"
uv run kobo-manga subscriptions
uv run kobo-manga update
#+end_src

** 本地库

#+begin_src bash
uv run kobo-manga list
uv run kobo-manga config
#+end_src

* 源插件开发

本项目采用插件化架构，不内置任何漫画源。用户需自行开发源适配器。

** 接口

所有源需继承 =BaseSource= 并实现以下方法：

#+begin_src python
from kobo_manga.sources.base import BaseSource
from kobo_manga.sources import register_source
from kobo_manga.models import MangaInfo, Chapter, PageImage


class MySource(BaseSource):
    name = "my_source"
    URL_PATTERNS = ["example.com"]  # 可选，用于从 URL 自动推断源

    async def search(self, keyword: str) -> list[MangaInfo]:
        """搜索漫画，返回结果列表。"""
        ...

    async def get_manga_info(self, manga_url: str) -> MangaInfo:
        """获取漫画详情，包含完整章节列表。"""
        ...

    async def get_chapter_images(self, chapter: Chapter) -> list[PageImage]:
        """获取章节的所有图片 URL。"""
        ...

    async def close(self) -> None:
        """释放资源（如 HTTP 客户端）。"""
        ...


register_source(MySource)
#+end_src

** 数据模型

| 类型        | 字段                                                         |
|-------------+--------------------------------------------------------------|
| =MangaInfo= | id, title, source, url, author, cover_url, description, tags, chapters |
| =Chapter=   | id, title, chapter_number, url, page_count, chapter_type     |
| =PageImage= | chapter_id, page_number, url, local_path                     |

** 安装插件

将插件 =.py= 文件放入 =src/kobo_manga/sources/= 目录，程序启动时会自动扫描并加载。

* TODO

- [ ] Web UI 管理界面
- [ ] Kobo Sync Protocol（通过 WiFi 无线推送到 Kobo 设备）

* 项目结构

#+begin_example
src/kobo_manga/
  config.py        - YAML 配置加载
  models.py        - 数据模型
  utils.py         - 公用工具函数
  sources/
    base.py        - 源适配器抽象基类
    __init__.py    - 插件注册与自动发现
  downloader/      - 并发下载引擎 + 重试 + 断点续传
  processor/       - 图片处理流水线
  converter/       - KEPUB 打包
  transfer/        - 设备传输（USB / Calibre）
  scheduler/       - 追更调度
  db/              - SQLite 状态存储
  cli/             - CLI 入口
#+end_example

* 技术栈

- [[https://www.python.org/][Python]] 3.12+，[[https://docs.astral.sh/uv/][uv]] 包管理
- [[https://www.python-httpx.org/][httpx]] 异步 HTTP 客户端
- [[https://python-pillow.org/][Pillow]] 图片处理
- [[https://pyyaml.org/][PyYAML]] 配置
- [[https://www.sqlite.org/][SQLite]]（WAL 模式）状态存储

* 许可证

本项目基于 [[./LICENSE][GNU General Public License v3.0]] 发布。