koishi-plugin-checkin-custom/readme.md

一个高度可配置的、支持多类型打卡和独立排行榜的 Koishi 插件。

# koishi-plugin-checkin-custom

[![koishi](https://img.shields.io/badge/koishi-v4-brightgreen?style=flat-square)](https://koishi.chat)

一个设计的高度可配置的 Koishi 打卡插件。它允许你创建多种独立的打卡项目，并为这些活动配置专属的排行榜。

## ✨ 特性

- **多打卡类型**: 可创建多个独立的打卡指令，每个指令拥有自己的主题、文案和日历。
- **独立排行榜**: 可创建多个排行榜，每个排行榜可独立统计一种或多种打卡类型的总和。
- **高度自定义**:
  - 自定义指令名称。
  - 自定义打卡成功/失败的文案。
  - 自定义日历标题、背景图片、主题色。
  - 自定义背景图的显示方式（覆盖或完整显示）与模糊程度。
- **数据库支持**: 基于数据库服务，数据持久化存储。
- **图片生成**: 基于 Puppeteer 服务，将打卡日历渲染为图片。

## 💿 安装

1.  从 Koishi 插件市场搜索 `checkin-custom` 并安装。
2.  确保你的 Koishi 实例已经安装并启用了以下两个核心服务插件：
    - `koishi-plugin-puppeteer`
    - 任意一个数据库服务插件 (例如 `koishi-plugin-database-mysql` 或 `koishi-plugin-database-sqlite`)

## ⚙️ 配置项说明

插件的配置分为三个主要部分，你可以在 Koishi 控制台中直观地进行设置。

### 打卡指令设置

此部分是一个数组，允许你添加任意多个独立的打卡活动。每个活动包含以下配置：

- **commandName**: (必填) 指令的名称，例如 `早起打卡`。**这也是该打卡类型的唯一标识符**，会被排行榜配置引用。
- **successMessage**: 打卡成功时发送的文案。
- **alreadyCheckedMessage**: 当日重复打卡时发送的文案。
- **checkinTitle**: 生成的日历图片上显示的标题。
- **backgroundImage**: (可选) 日历图片的背景图路径。请填写相对于 Koishi 项目根目录的路径，例如 `assets/bg.jpg`。
- **backgroundSize**: 背景图的缩放模式。
  - `cover`: 填满整个区域，可能会放大或裁剪图片。
  - `contain`: 将图片完整显示在区域内，可能会产生留白。
- **backgroundBlur**: 背景图的模糊程度，单位为像素。设为 `0` 可关闭模糊效果。
- **themeColor**: 日历中用于高亮“今天”的颜色。

### 排行榜设置

此部分也是一个数组，允许你添加任意多个独立的排行榜。每个排行榜包含以下配置：

- **commandName**: (必填) 排行榜指令的名称，例如 `作息榜`。
- **title**: 排行榜图片的标题。
- **includedTypes**: 要统计的打卡类型列表。
  - 在这里填入你上面设置的打卡指令的 `commandName`。
  - **如果此列表为空，该排行榜将统计所有类型的打卡总和。**

### 高级设置

- **debug**: 是否在控制台输出详细的调试信息。

## 📖 使用

根据你在“打卡指令设置”和“排行榜设置”中配置的 `commandName`，向机器人发送对应的指令即可。

## ⚠️ 免责声明

- 本插件允许用户配置并显示本地图片。请确保你对所使用的图片拥有合法的使用权，并遵守相关法律法规。
- 插件作者不对任何因使用者配置不当（例如使用了受版权保护的、非法的或不适宜的图片）而导致的法律纠纷或任何形式的损失承担责任。
- 用户对本插件的所有使用行为负全部责任。

## 📄 开源许可

本插件使用 [MIT](./LICENSE) 许可证发布。

Copyright (c) 2025 WhiteBr1ck