S-01 插件骨架固化

这个提交存在于:
Codex 2026-07-07 00:01:44 +08:00
当前提交 9b5ab4a956
共有 12 个文件被更改,包括 747 次插入 和 0 次删除

9
.gitignore Vendored 普通文件
查看文件

@ -0,0 +1,9 @@
__pycache__/
*.py[cod]
.ruff_cache/
.pytest_cache/
data/
work/
komga_library/
*.tmp

37
README.md 普通文件
查看文件

@ -0,0 +1,37 @@
# JMDownload 归档器
这是一个 AstrBot 插件,用于下载 JM 本子,并归档为 Komga 可直接扫描读取的漫画库文件。
## 命令
- `/jm download <id>` 或 `/jm 下载 <id>`:下载、归档,并按配置触发 Komga 扫描。
- `/jm status`:查看当前归档与 Komga 配置状态。
- `/jm scan`:手动触发一次 Komga 扫描。
## 归档结构
默认归档为 `cbz`,目录结构如下:
```text
<archive_root>/
<系列名>/
<系列名> [<JM ID>].cbz
```
Komga 扫描时会把父文件夹识别为 Series,把文件识别为 Book,所以 `archive_root` 建议直接填写 Komga library 的根目录。插件也保留 `pdf` 输出,用于兼容原 NoneBot 插件习惯。
## Komga 联动
在 AstrBot 插件配置里填写:
- `archive_root`:Komga library 根目录
- `komga.enabled`:是否启用自动扫描
- `komga.base_url`:Komga 服务地址
- `komga.library_id`:Komga library ID
- `komga.api_key` 或 `komga.username` + `komga.password`
归档完成后,插件会请求:
```text
POST /api/v1/libraries/{libraryId}/scan
```

92
_conf_schema.json 普通文件
查看文件

@ -0,0 +1,92 @@
{
"archive_root": {
"description": "归档根目录,建议填写 Komga 某个 library 的根目录;留空则使用插件数据目录。",
"type": "string",
"default": ""
},
"archive_format": {
"description": "归档格式,Komga 推荐 cbz,兼容原插件可选 pdf。",
"type": "string",
"default": "cbz",
"options": ["cbz", "pdf"]
},
"admin_only": {
"description": "仅允许 AstrBot 管理员执行下载和扫描命令。",
"type": "bool",
"default": true
},
"send_archive_file": {
"description": "平台支持文件消息时,把生成的归档文件发送回聊天。",
"type": "bool",
"default": false
},
"overwrite_existing": {
"description": "目标归档已存在时是否覆盖。",
"type": "bool",
"default": false
},
"delete_work_dir_after_archive": {
"description": "归档成功后删除临时下载目录。",
"type": "bool",
"default": true
},
"download_timeout_seconds": {
"description": "单个下载任务的超时时间,单位秒。",
"type": "int",
"default": 3600
},
"jm_batch_count": {
"description": "jmcomic 图片下载批次大小。",
"type": "int",
"default": 20
},
"jm_domains": {
"description": "jmcomic 域名列表,按优先级排序。",
"type": "list",
"default": [
"www.jmapiproxyxxx.vip",
"www.18comic-mygo.vip",
"18comic-MHWs.CC",
"18comic.vip",
"18comic.org"
]
},
"komga": {
"description": "Komga 联动配置。",
"type": "object",
"items": {
"enabled": {
"description": "归档后自动触发 Komga 扫描。",
"type": "bool",
"default": false
},
"base_url": {
"description": "Komga 服务地址,例如 http://127.0.0.1:25600。",
"type": "string",
"default": ""
},
"library_id": {
"description": "需要扫描的 Komga library ID。",
"type": "string",
"default": ""
},
"username": {
"description": "Komga Basic Auth 用户名。使用 API Key 时可留空。",
"type": "string",
"default": ""
},
"password": {
"description": "Komga Basic Auth 密码。",
"type": "string",
"default": "",
"invisible": true
},
"api_key": {
"description": "Komga API Key,会作为 X-API-Key 请求头发送。",
"type": "string",
"default": "",
"invisible": true
}
}
}
}

130
main.py 普通文件
查看文件

@ -0,0 +1,130 @@
from __future__ import annotations
from pathlib import Path
from astrbot.api import AstrBotConfig, logger
from astrbot.api.event import AstrMessageEvent, filter
import astrbot.api.message_components as Comp
from astrbot.api.star import Context, Star, StarTools
from .services.archive import ArchiveResult, ArchiveService
from .services.download import JMDownloadService
from .services.komga import KomgaClient, KomgaScanResult
from .services.settings import PluginSettings
class JMDownloadPlugin(Star):
def __init__(self, context: Context, config: AstrBotConfig | None = None) -> None:
super().__init__(context, config)
data_dir = self._get_data_dir()
self.config = config or {}
self.settings = PluginSettings.from_config(dict(self.config), data_dir)
self.settings.ensure_dirs()
self.downloader = JMDownloadService(self.settings)
self.archiver = ArchiveService(self.settings)
self.komga = KomgaClient(self.settings.komga)
async def initialize(self) -> None:
logger.info(
"JMDownload initialized: "
f"archive_root={self.settings.archive_root}, "
f"format={self.settings.archive_format}, "
f"komga={self.settings.komga.enabled}",
)
async def terminate(self) -> None:
logger.info("JMDownload terminated")
@filter.command_group("jm", alias={"JM", "Jm", "jM"})
def jm(self):
pass
@jm.command("download", alias={"下载"})
async def download(self, event: AstrMessageEvent, comic_id: str):
"""Download a JM album, archive it, and optionally ask Komga to scan."""
if self._deny_non_admin(event):
yield event.plain_result("JMDownload is admin-only in the current config.")
event.stop_event()
return
comic_id = comic_id.strip()
if not comic_id.isdigit():
yield event.plain_result("Usage: /jm download <numeric_id>")
event.stop_event()
return
await event.send(event.plain_result(f"Starting JM download: {comic_id}"))
try:
downloaded = await self.downloader.download(comic_id)
archive_result = await self.archiver.archive(downloaded)
self.downloader.cleanup(downloaded)
scan_result = await self.komga.scan_library()
except Exception as exc:
logger.exception(f"JMDownload failed for {comic_id}")
yield event.plain_result(f"JMDownload failed: {exc}")
event.stop_event()
return
if self.settings.send_archive_file:
yield event.chain_result(
[
Comp.Plain(self._format_success(archive_result, scan_result)),
Comp.File(name=archive_result.path.name, file=str(archive_result.path)),
],
)
else:
yield event.plain_result(self._format_success(archive_result, scan_result))
event.stop_event()
@jm.command("status")
async def status(self, event: AstrMessageEvent):
"""Show current JMDownload archive and Komga settings."""
lines = [
"JMDownload status",
f"Archive root: {self.settings.archive_root}",
f"Archive format: {self.settings.archive_format}",
f"Send archive file: {self.settings.send_archive_file}",
f"Komga enabled: {self.settings.komga.enabled}",
f"Komga can scan: {self.settings.komga.can_scan}",
]
yield event.plain_result("\n".join(lines))
event.stop_event()
@jm.command("scan")
async def scan(self, event: AstrMessageEvent):
"""Trigger a Komga scan for the configured library."""
if self._deny_non_admin(event):
yield event.plain_result("JMDownload is admin-only in the current config.")
event.stop_event()
return
result = await self.komga.scan_library()
yield event.plain_result(result.message)
event.stop_event()
def _deny_non_admin(self, event: AstrMessageEvent) -> bool:
return bool(self.settings.admin_only and not event.is_admin())
def _format_success(
self,
archive_result: ArchiveResult,
scan_result: KomgaScanResult,
) -> str:
existed = "existing archive reused" if archive_result.existed else "archive created"
return "\n".join(
[
f"JMDownload finished: {existed}",
f"Series: {archive_result.series_name}",
f"Pages: {archive_result.page_count}",
f"File: {archive_result.path}",
f"Komga: {scan_result.message}",
],
)
def _get_data_dir(self) -> Path:
try:
return StarTools.get_data_dir("astrbot_plugin_jmdownload")
except Exception:
fallback = Path("data/plugin_data/astrbot_plugin_jmdownload")
fallback.mkdir(parents=True, exist_ok=True)
return fallback.resolve()

15
metadata.yaml 普通文件
查看文件

@ -0,0 +1,15 @@
name: astrbot_plugin_jmdownload
author: YokiiroBW
desc: 下载 JM 本子,归档为 Komga 可读取的漫画库文件,并可自动触发 Komga 扫描。
short_desc: JM 下载与 Komga 归档联动。
version: 0.1.0
repo: "http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_jmdowloads"
display_name: JMDownload 归档器
support_platforms:
- aiocqhttp
- telegram
- discord
- slack
- kook
- satori
astrbot_version: ">=4.16,<5"

4
requirements.txt 普通文件
查看文件

@ -0,0 +1,4 @@
jmcomic>=0.3.0
PyYAML>=6.0
Pillow>=9.0.0
httpx>=0.27.0

2
services/__init__.py 普通文件
查看文件

@ -0,0 +1,2 @@
"""Service layer for the AstrBot JMDownload plugin."""

131
services/archive.py 普通文件
查看文件

@ -0,0 +1,131 @@
from __future__ import annotations
import asyncio
import os
import zipfile
from dataclasses import dataclass
from pathlib import Path
from xml.sax.saxutils import escape
from PIL import Image
from .download import DownloadedComic
from .images import safe_filename
from .settings import PluginSettings
@dataclass(frozen=True)
class ArchiveResult:
path: Path
series_dir: Path
series_name: str
book_name: str
existed: bool
page_count: int
class ArchiveError(Exception):
pass
class ArchiveService:
def __init__(self, settings: PluginSettings) -> None:
self.settings = settings
async def archive(self, downloaded: DownloadedComic) -> ArchiveResult:
return await asyncio.to_thread(self._archive_sync, downloaded)
def _archive_sync(self, downloaded: DownloadedComic) -> ArchiveResult:
series_name = safe_filename(downloaded.title, fallback=f"JM {downloaded.comic_id}")
book_name = safe_filename(f"{series_name} [{downloaded.comic_id}]")
series_dir = self.settings.archive_root / series_name
series_dir.mkdir(parents=True, exist_ok=True)
suffix = ".cbz" if self.settings.archive_format == "cbz" else ".pdf"
target_path = series_dir / f"{book_name}{suffix}"
if target_path.exists() and not self.settings.overwrite_existing:
return ArchiveResult(
path=target_path,
series_dir=series_dir,
series_name=series_name,
book_name=book_name,
existed=True,
page_count=len(downloaded.image_files),
)
tmp_path = target_path.with_suffix(f"{target_path.suffix}.tmp")
if tmp_path.exists():
tmp_path.unlink()
if self.settings.archive_format == "cbz":
self._create_cbz(tmp_path, downloaded, series_name, book_name)
else:
self._create_pdf(tmp_path, downloaded)
os.replace(tmp_path, target_path)
return ArchiveResult(
path=target_path,
series_dir=series_dir,
series_name=series_name,
book_name=book_name,
existed=False,
page_count=len(downloaded.image_files),
)
def _create_cbz(
self,
target_path: Path,
downloaded: DownloadedComic,
series_name: str,
book_name: str,
) -> None:
with zipfile.ZipFile(target_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
archive.writestr(
"ComicInfo.xml",
self._comic_info_xml(downloaded, series_name, book_name),
)
for index, image_path in enumerate(downloaded.image_files, start=1):
page_name = f"{index:04d}{image_path.suffix.lower()}"
archive.write(image_path, page_name)
def _create_pdf(self, target_path: Path, downloaded: DownloadedComic) -> None:
images: list[Image.Image] = []
try:
for image_path in downloaded.image_files:
image = Image.open(image_path)
if image.mode != "RGB":
image = image.convert("RGB")
images.append(image)
if not images:
raise ArchiveError("no images available for PDF creation")
images[0].save(
target_path,
"PDF",
save_all=True,
append_images=images[1:],
)
finally:
for image in images:
image.close()
def _comic_info_xml(
self,
downloaded: DownloadedComic,
series_name: str,
book_name: str,
) -> str:
return "\n".join(
[
'<?xml version="1.0" encoding="utf-8"?>',
"<ComicInfo>",
f" <Title>{escape(book_name)}</Title>",
f" <Series>{escape(series_name)}</Series>",
f" <Number>{escape(downloaded.comic_id)}</Number>",
f" <PageCount>{len(downloaded.image_files)}</PageCount>",
" <Manga>YesAndRightToLeft</Manga>",
"</ComicInfo>",
"",
],
)

105
services/download.py 普通文件
查看文件

@ -0,0 +1,105 @@
from __future__ import annotations
import asyncio
import shutil
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
import yaml
from astrbot.api import logger
from .images import collect_image_files, infer_album_title
from .settings import PluginSettings
@dataclass(frozen=True)
class DownloadedComic:
comic_id: str
title: str
work_dir: Path
download_dir: Path
image_files: list[Path]
class DownloadError(Exception):
pass
class JMDownloadService:
def __init__(self, settings: PluginSettings) -> None:
self.settings = settings
async def download(self, comic_id: str) -> DownloadedComic:
job_name = datetime.now().strftime(f"{comic_id}-%Y%m%d-%H%M%S")
work_dir = self.settings.work_root / job_name
download_dir = work_dir / "downloads"
config_path = work_dir / "jmcomic.yml"
download_dir.mkdir(parents=True, exist_ok=True)
self._write_jmcomic_config(config_path, download_dir)
try:
await asyncio.wait_for(
asyncio.to_thread(self._download_sync, comic_id, config_path),
timeout=self.settings.download_timeout_seconds,
)
except TimeoutError as exc:
raise DownloadError(f"download timed out after {self.settings.download_timeout_seconds}s") from exc
except Exception as exc:
raise DownloadError(str(exc)) from exc
image_files = collect_image_files(download_dir)
if not image_files:
raise DownloadError("download finished but no image files were found")
return DownloadedComic(
comic_id=comic_id,
title=infer_album_title(download_dir, comic_id),
work_dir=work_dir,
download_dir=download_dir,
image_files=image_files,
)
def cleanup(self, downloaded: DownloadedComic) -> None:
if not self.settings.delete_work_dir_after_archive:
return
if downloaded.work_dir.exists():
shutil.rmtree(downloaded.work_dir)
def _download_sync(self, comic_id: str, config_path: Path) -> None:
try:
import jmcomic
except ImportError as exc:
raise DownloadError("jmcomic is not installed; check plugin requirements.txt") from exc
logger.info(f"JMDownload: downloading album {comic_id} with {config_path}")
option = jmcomic.JmOption.from_file(filepath=str(config_path))
jmcomic.download_album(comic_id, option)
def _write_jmcomic_config(self, config_path: Path, download_dir: Path) -> None:
config = {
"version": "1.0",
"dir_rule": {
"base_dir": str(download_dir),
"rule": "Bd_Atitle_Pindex",
},
"client": {
"domain": self.settings.jm_domains,
},
"download": {
"cache": True,
"image": {
"decode": True,
"suffix": ".jpg",
},
"threading": {
"batch_count": self.settings.jm_batch_count,
},
},
}
config_path.parent.mkdir(parents=True, exist_ok=True)
config_path.write_text(
yaml.safe_dump(config, allow_unicode=True, sort_keys=False),
encoding="utf-8",
)

70
services/images.py 普通文件
查看文件

@ -0,0 +1,70 @@
from __future__ import annotations
import re
from pathlib import Path
IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".webp"}
WINDOWS_RESERVED_NAMES = {
"CON",
"PRN",
"AUX",
"NUL",
"COM1",
"COM2",
"COM3",
"COM4",
"COM5",
"COM6",
"COM7",
"COM8",
"COM9",
"LPT1",
"LPT2",
"LPT3",
"LPT4",
"LPT5",
"LPT6",
"LPT7",
"LPT8",
"LPT9",
}
def natural_key(value: Path | str) -> list[int | str]:
return [
int(part) if part.isdigit() else part.lower()
for part in re.split(r"(\d+)", str(value))
]
def collect_image_files(root: Path) -> list[Path]:
files = [
path
for path in root.rglob("*")
if path.is_file() and path.suffix.lower() in IMAGE_SUFFIXES
]
return sorted(files, key=natural_key)
def safe_filename(value: str, fallback: str = "untitled") -> str:
cleaned = "".join(
"_" if char in '<>:"/\\|?*' or ord(char) < 32 else char
for char in value.strip()
)
cleaned = re.sub(r"\s+", " ", cleaned).strip(" .")
if not cleaned:
cleaned = fallback
if cleaned.upper() in WINDOWS_RESERVED_NAMES:
cleaned = f"_{cleaned}"
return cleaned[:180]
def infer_album_title(download_dir: Path, comic_id: str) -> str:
candidates = []
for child in sorted(download_dir.iterdir(), key=lambda path: natural_key(path.name)):
if child.is_dir() and collect_image_files(child):
candidates.append(child.name)
if len(candidates) == 1:
return candidates[0]
return f"JM {comic_id}"

50
services/komga.py 普通文件
查看文件

@ -0,0 +1,50 @@
from __future__ import annotations
from dataclasses import dataclass
import httpx
from .settings import KomgaSettings
@dataclass(frozen=True)
class KomgaScanResult:
attempted: bool
success: bool
message: str
class KomgaClient:
def __init__(self, settings: KomgaSettings) -> None:
self.settings = settings
async def scan_library(self) -> KomgaScanResult:
if not self.settings.enabled:
return KomgaScanResult(False, False, "Komga scan is disabled")
if not self.settings.can_scan:
return KomgaScanResult(
False,
False,
"Komga scan is not configured; set base_url, library_id, and credentials",
)
headers = {}
auth = None
if self.settings.api_key:
headers["X-API-Key"] = self.settings.api_key
else:
auth = (self.settings.username, self.settings.password)
url = f"{self.settings.base_url}/api/v1/libraries/{self.settings.library_id}/scan"
try:
async with httpx.AsyncClient(timeout=30) as client:
response = await client.post(url, headers=headers, auth=auth)
if response.status_code == 202:
return KomgaScanResult(True, True, "Komga scan accepted")
return KomgaScanResult(
True,
False,
f"Komga scan failed: HTTP {response.status_code} {response.text[:200]}",
)
except Exception as exc:
return KomgaScanResult(True, False, f"Komga scan failed: {exc}")

102
services/settings.py 普通文件
查看文件

@ -0,0 +1,102 @@
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import Any
DEFAULT_JM_DOMAINS = [
"www.jmapiproxyxxx.vip",
"www.18comic-mygo.vip",
"18comic-MHWs.CC",
"18comic.vip",
"18comic.org",
]
@dataclass(frozen=True)
class KomgaSettings:
enabled: bool = False
base_url: str = ""
library_id: str = ""
username: str = ""
password: str = ""
api_key: str = ""
@classmethod
def from_config(cls, config: dict[str, Any]) -> "KomgaSettings":
return cls(
enabled=bool(config.get("enabled", False)),
base_url=str(config.get("base_url", "")).strip().rstrip("/"),
library_id=str(config.get("library_id", "")).strip(),
username=str(config.get("username", "")).strip(),
password=str(config.get("password", "")),
api_key=str(config.get("api_key", "")).strip(),
)
@property
def can_scan(self) -> bool:
has_auth = bool(self.api_key or (self.username and self.password))
return bool(self.enabled and self.base_url and self.library_id and has_auth)
@dataclass(frozen=True)
class PluginSettings:
data_dir: Path
work_root: Path
archive_root: Path
archive_format: str = "cbz"
admin_only: bool = True
send_archive_file: bool = False
overwrite_existing: bool = False
delete_work_dir_after_archive: bool = True
download_timeout_seconds: int = 3600
jm_batch_count: int = 20
jm_domains: list[str] | None = None
komga: KomgaSettings = KomgaSettings()
@classmethod
def from_config(cls, config: dict[str, Any], data_dir: Path) -> "PluginSettings":
archive_root_raw = str(config.get("archive_root", "")).strip()
archive_root = (
Path(archive_root_raw).expanduser()
if archive_root_raw
else data_dir / "komga_library"
)
archive_format = str(config.get("archive_format", "cbz")).strip().lower()
if archive_format not in {"cbz", "pdf"}:
archive_format = "cbz"
jm_domains = config.get("jm_domains", DEFAULT_JM_DOMAINS)
if not isinstance(jm_domains, list) or not jm_domains:
jm_domains = DEFAULT_JM_DOMAINS
komga_config = config.get("komga", {})
if not isinstance(komga_config, dict):
komga_config = {}
return cls(
data_dir=data_dir,
work_root=data_dir / "work",
archive_root=archive_root,
archive_format=archive_format,
admin_only=bool(config.get("admin_only", True)),
send_archive_file=bool(config.get("send_archive_file", False)),
overwrite_existing=bool(config.get("overwrite_existing", False)),
delete_work_dir_after_archive=bool(
config.get("delete_work_dir_after_archive", True),
),
download_timeout_seconds=max(
60,
int(config.get("download_timeout_seconds", 3600) or 3600),
),
jm_batch_count=max(1, int(config.get("jm_batch_count", 20) or 20)),
jm_domains=[str(domain).strip() for domain in jm_domains if str(domain).strip()],
komga=KomgaSettings.from_config(komga_config),
)
def ensure_dirs(self) -> None:
self.data_dir.mkdir(parents=True, exist_ok=True)
self.work_root.mkdir(parents=True, exist_ok=True)
self.archive_root.mkdir(parents=True, exist_ok=True)