Skip to content
BranchesTags

Repository files navigation

UsefulBot

UsefulBot 是一个 Kotlin 漫画下载机器人，可同时接入 NapCat / OneBot 11 和 Telegram Bot API。目前支持 E-Hentai、ExHentai 与 JMComic，提供搜索、下载、PDF 生成、任务队列、缓存和 GP 计费。

主要功能

  • 下载 E-Hentai / ExHentai 画廊并生成 PDF。
  • 通过 JM 车号或专辑链接下载 JMComic，自动还原分块图片并生成 PDF。
  • 搜索 E-Hentai / ExHentai 和 JMComic。
  • 支持 NapCat 与 Telegram 同时在线，共享下载任务和生成结果。
  • 获取漫画信息和封面后立即回复，下载与 PDF 生成继续在后台执行。
  • 支持重复任务合并、PDF 缓存、失败退款和每日签到。
  • 支持任务查询/取消、重启恢复、失败自动补发、批量下载和 GP 流水查询。
  • 提供访问控制、命令限流、每日额度、缓存治理、健康检查和管理员命令。
  • 内置简体中文和英文消息，未知语言自动回退到英文。
  • Telegram 可通过本地 Bot API 服务发送最大 2000 MB 的完整文件。

快速开始

环境要求

  • JDK 17 或更高版本（CI 使用 JDK 21）。
  • NapCat 模式：可用的 OneBot 11 正向 WebSocket 服务。
  • Telegram 模式：通过 BotFather 创建的 Bot Token。
  • 访问受限漫画源时，需要自行配置合规可用的代理。

构建

Windows：

.\gradlew.bat --no-daemon build
java -jar .\implements\build\libs\UsefulBot-1.5.0.jar

Linux / macOS：

./gradlew --no-daemon build
java -jar ./implements/build/libs/UsefulBot-1.5.0.jar

普通 JAR 是动态 Loader，首次运行时会从 Maven Central 下载锁定版本的依赖，并校验 SHA-256。依赖默认缓存到 Loader JAR 相同目录下的 deps 文件夹，后续运行直接复用。可通过 -Dusefulbot.mavenRepository=<仓库地址> 和 -Dusefulbot.dependencyCache=<目录> 覆盖仓库与缓存位置。 Loader 会通过公网出口 IP 检测国家代码；检测为中国大陆时优先使用阿里云 Maven 镜像，失败后自动回退 Maven Central。可通过 -Dusefulbot.mavenRegion=CN 强制使用中国区策略，或显式指定仓库以跳过 IP 属地检测。

构建同时会生成无需联网的 UsefulBot-1.5.0-all.jar。只解析和缓存依赖而不启动机器人时，可执行：

java -jar ./implements/build/libs/UsefulBot-1.5.0.jar --resolve-dependencies-only

首次运行会在当前工作目录生成 config.json。修改配置后需要重启程序。

配置

下面仅列出常用字段；未填写的字段会使用程序默认值。

{
  "version": 10,
  "Bot": {
    "CommandOperator": "/",
    "Language": "zh-CN",
    "napcat": {
      "Enabled": true,
      "BlurImages": true,
      "WebsocketURL": "ws://127.0.0.1:3000",
      "Token": "napcat!"
    },
    "telegram": {
      "Enabled": false,
      "BlurImages": false,
      "Token": "",
      "ApiBaseURL": "https://api.telegram.org",
      "UploadTimeoutMinutes": 60,
      "EnableInlineMode": true,
      "LargeFile": {
        "Policy": "SPLIT_PDF",
        "MaxPartSizeMiB": 48,
        "TempDirectory": "data/telegram/temp"
      }
    }
  },
  "Proxy": {
    "Type": "DIRECT",
    "Address": "127.0.0.1",
    "Port": 1080
  },
  "Ehentai": {
    "ipb_member_id": "",
    "ipb_pass_hash": "",
    "igneous": "",
    "isExHentai": false,
    "MaxArchiveSizeMiB": 0
  },
  "ComicParallelCount": 2,
  "Access": {
    "CommandsPerMinute": 20,
    "DailyDownloadLimit": 20
  },
  "Tasks": {
    "UserCapacity": 5
  },
  "Cache": {
    "MaxSizeMiB": 10240,
    "TtlDays": 30,
    "CleanupIntervalMinutes": 60,
    "MinimumFreeSpaceMiB": 1024
  },
  "DeliveryRetry": {
    "Enabled": true,
    "IntervalSeconds": 60,
    "MaxAttempts": 10
  },
  "Batch": {
    "Enabled": false,
    "MaxItems": 10
  }
}

Bot 适配器

  • Bot.napcat.Enabled：启用 NapCat。
  • Bot.telegram.Enabled：启用 Telegram。
  • 两者可同时启用；相同漫画只下载和生成一次，再分别发送给订阅者。
  • BlurImages：控制对应平台发送漫画信息时是否模糊封面。
  • Language：支持 en、en-US、zh、zh-CN、中文 等写法。
  • 用户可在 Telegram 通过 /prefs blur 覆盖封面模糊设置；QQ/NapCat 始终使用服务端 BlurImages。
  • Telegram LargeFile.Policy 只能由服务端配置，用户命令不能更改。

访问与运行策略

  • CommandsPerMinute 和 DailyDownloadLimit：0 表示不限制。
  • 用户、群和多平台访问由内置 permissions 插件管理；权限规则和动态封禁保存在插件自己的 H2 数据库中。
  • 首次启动可在 JLine 控制台执行 permission grant tg:user:<id> usefulbot.admin（QQ 使用 qq:user:<id>）授予管理员权限。
  • 控制台只补全并执行显式包含 ALLOW_CONSOLE 的命令；当前包括 health、admin 和 permission 的管理子命令。
  • permissions 是基础内置插件，不能通过 Plugins.Disabled 或运行时卸载关闭；EH/JM 统一属于 comic 插件，可整体禁用。
  • Cache 控制 PDF 总容量、保留天数、清理周期及低磁盘告警阈值。
  • Batch.Enabled 默认为 false；只有设为 true 时才注册 /batch 并同步到 Telegram 菜单。

代理

Proxy.Type 可使用 Java 支持的以下类型：

  • DIRECT：不使用代理。
  • HTTP：HTTP 代理。
  • SOCKS：SOCKS 代理。

E-Hentai / ExHentai

  • 使用 ExHentai 时需要配置对应 Cookie，并将 isExHentai 设为 true。
  • MaxArchiveSizeMiB 限制下载归档大小，设为 0 表示不限制。
  • 超过限制时只发送画廊信息，不下载归档或生成 PDF。

JMComic 的 API、网页和图片域名已内置，通常无需手动配置。

Telegram 大文件

官方 Bot API

使用 https://api.telegram.org 时，超过官方上传限制的 PDF 按 LargeFile.Policy 处理：

  • SPLIT_PDF：按页拆分为不超过 MaxPartSizeMiB 的 PDF 分卷。
  • FAIL：不进行分卷，上传失败会作为任务失败处理。

分卷首次上传后会缓存 Telegram file_id。其他用户请求相同 PDF 时直接复用，失效的分卷才会重新生成和上传。

本地 Bot API

如需发送完整大文件，请运行官方的本地 telegram-bot-api 服务，并修改：

"ApiBaseURL": "http://127.0.0.1:8081",
"UploadTimeoutMinutes": 60

本地服务允许上传最大 2000 MB。UsefulBot 会直接使用 sendDocument multipart 上传，不会因为 50 MiB 限制预先拆分 PDF。

从云端 Bot API 切换到本地服务前，需要按照上游说明对 Bot 调用 logOut。构建步骤可使用官方的 telegram-bot-api 构建说明生成器。

Telegram 发送的普通 PDF 和 PDF 分卷均不设置打开密码；NapCat 发送原始完整 PDF。

命令

命令 说明
/help 显示帮助和可用命令
/about 显示机器人信息
/plugins 以 [name:version,] 格式显示插件列表
/get eh <链接> 下载 E-Hentai / ExHentai 画廊
/get jm <车号或链接> 下载 JMComic 专辑
/query eh <链接> 查询 E-Hentai / ExHentai 画廊信息和封面
/query jm <车号或链接> 查询 JMComic 专辑信息和封面
/search eh <关键词> 搜索 E-Hentai / ExHentai
/search jm <关键词> 搜索 JMComic
/checkin 每日签到领取 GP
/info 查看 GP 余额和账户信息
/history [数量] 查看最近的 GP 收支记录
/tasks 查看任务 ID、阶段、进度和排队位置
/cancel <任务ID> 取消任务或退出共享任务
/batch 每行一个 eh <链接> 或 jm <车号>，批量提交；默认不注册
/prefs show 查看个人语言、Telegram 封面模糊和进度通知偏好
/prefs language <zh-CN|en> 设置个人语言
/prefs blur <on|off|default> 设置 Telegram 封面模糊；QQ 不允许设置
/prefs progress <on|off> 开关提前发送漫画信息等进度通知
/health 查看队列、补发箱、用户、磁盘和 Provider 状态（管理员）
/admin GP、封禁、缓存、补发和任务管理（管理员）

示例：

/get eh https://e-hentai.org/g/123456/abcdef1234/
/get jm JM123456
/get jm https://18comic.vip/album/123456/
/query eh https://e-hentai.org/g/123456/abcdef1234/
/query jm JM123456
/search eh --category=manga --min-stars=4 language:chinese
/search jm --page=2 中文 全彩
/checkin
/info

E-Hentai 搜索支持：

  • --category=分类,...
  • --min-stars=0..5
  • language:chinese、artist:name 等官方标签语法

可用分类包括 misc、doujinshi、manga、artist-cg、game-cg、image-set、cosplay、asian-porn、non-h 和 western。

Telegram 命令菜单

Telegram 适配器连接成功后会调用 setMyCommands，根据程序实际注册的命令自动更新菜单，无需在 BotFather 中手工维护。菜单同步失败不会阻止 Bot 继续接收消息，失败原因会写入运行日志。

Telegram Inline 搜索

  1. 在 BotFather 中执行 /setinline。
  2. 保持 EnableInlineMode 为 true。
  3. 在任意聊天中输入：
@机器人用户名 eh <关键词>
@机器人用户名 jm <关键词>

PDF、缓存与计费

  • E-Hentai PDF 密码为 <gallery-id>-<token>。
  • JMComic PDF 密码为 JM<车号>。
  • JMComic 按 floor(PDF 大小 MiB × 1.1) 收取 GP。
  • 每日签到奖励为 150～250 GP，按 UTC 日期判断。
  • 发送或任务失败时自动退款。
  • 同一漫画的并发请求会合并为一个共享任务。
  • 任务完成后自动清理下载归档、解压图片、封面、断点进度和临时文件，仅保留最终 PDF。
  • PDF 缓存按配置的容量与 TTL 清理；待补发文件在补发完成前不会被清理。
  • 进程重启后会恢复未完成任务；文件发送失败时进入持久化补发箱并自动重试。

数据目录

plugins/
├─ comic/
│  ├─ comic.mv.db  # 漫画任务、订阅、补发队列和每日下载额度
│  ├─ eh/           # E-Hentai 归档、图片、PDF 与临时文件
│  └─ jm/           # JMComic 图片、PDF 与临时文件
└─ permissions/
   └─ permissions.mv.db  # 权限规则和动态封禁

data/
├─ telegram/temp/  # Telegram PDF 分卷临时目录
└─ data.mv.db      # 经济、Telegram/NapCat 文件 ID 缓存和用户偏好

启动时会把旧的 data/eh、data/jm、plugins/eh/data 和 plugins/jm/data 合并迁移到 plugins/comic。已存在的目标文件不会被覆盖。

所有运行状态均使用 H2 持久化，不再读写 bot-state.json。GP 用户主键直接保存为 tg:<id> 或 qq:<id>。本版本不迁移旧的 data/gp.mv.db，升级时应删除旧库并让程序重新创建。请在程序停止后备份数据库，避免得到不一致的文件快照。

错误报告

命令执行、漫画生成或文件投递发生未处理异常时，程序会在项目根目录的 error/ 写入 <UTC时间戳>.err.log。日志包含平台、用户和会话、消息 ID、完整操作命令、异常原因及堆栈。用户只会收到安全提示和对应文件名，并被提示联系管理员，不会直接看到内部异常内容。

配置兼容

旧版本配置会在启动时自动升级到当前格式，并保留未知字段。

测试

.\gradlew.bat --offline --no-daemon test

构建可执行 JAR：

.\gradlew.bat --offline --no-daemon :implements:shadowJar

相关项目

许可与使用说明

本项目使用 BSD 3-Clause License。请遵守所在地区法律、目标站点服务条款及内容版权要求，仅下载和处理你有权访问的内容。

About

A useful bot, designed for Onebot11 Procotol

Resources

Readme
BSD-3-Clause license
Activity

Stars

3 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages