koishi-plugin-pics

Koishi 的随机图片插件

安装

你可以选择通过 koishi 的插件市场安装本插件，也可以使用 npm 或 yarn 等包管理器安装。

通过插件市场

如果你通过 koishi 的模板项目创建了你的机器人项目，你可以直接从插件市场安装本插件。详情请参考安装和配置插件

通过包管理器

由于 koishi 现在的默认包管理器是 yarn，因此推荐使用 yarn 安装插件，当然，你也可以使用 npm 安装。

# 如果你使用 yarn
yarn add koishi-plugin-pics
# 如果你使用 npm
npm install koishi-plugin-pics

开始使用

由于 pics 仅仅是一个随机图片的插件框架，并不包含任何图源的实现，因此你必须添加至少一个图源插件才能开始使用。

图源插件

koishi-plugin-picsource-localfs 本地文件图源。
koishi-plugin-picsource-lolicon Lolicon 图源。
koishi-plugin-picsource-heisi heisi 图源，基于 nonebot_plugin_heisi。
koishi-plugin-picsource-yande Yandere 及 Konachan 图源。

图源配置

在开始启动之前，你还需要添加一些配置，告诉 pics 插件有哪些图源插件可以使用，以及每个图源插件的配置。对于配置项的详细说明，请参考配置。

下面以 koishi-plugin-picsource-lolicon 和 koishi-plugin-picsource-yande 为例进行说明。

# koishi.yml
plugins:
  pics:
    commandName: pic
  picsource-lolicon: # Lolicon 图源
    name: lolicon
    r18: 2
    tags:
      - anime
      - 动漫
      - 二次元
    description: 'Lolicon API 的图'
    isDefault: true
    weight: 2

成功启动 koishi 后，就可以使用指令 pic 获取一张随机图片，更多的选项可以参考下方指令章节。

指令

获取随机图片

pic [...tags:string]
获取随机图片
从各个图源中随机获取一张随机图片。图源可以用 pic.sources 查询。参数均为可选。
可用的选项有：
-t, --tag <tag> 需要查询的图片标签，逗号分隔。
使用示例：
pic 获取一张随机图片。
pic yuyuko 获取一张 yuyuko 标签的图片。
pic -s yande 获取一张 yande 图源的图片。
pic -s yande yuyuko saigyouji 从 yande 图源中获取一张具有 yuyuko 以及 saigyouji 标签的图。
可用的子指令有：
pic.sources 查询图源列表

查询图源列表

pic.sources [...tags]
查询图源列表
图源标签可用于图片获取的图源筛选。

使用示例：
pic.sources 查询全部的图源。
pic.sources pixiv 查询含有 pixiv 标签的图源。

配置

pics 配置

koishi-plugin-pics 的配置如下表所示：

参数	类型	是否必选	描述
commandName	string	否	指令名称，默认为 pic。
useAssets	boolean	默认 `true`	Assets 服务可用时，使用 Assets 缓存图片。
useBase64	boolean	默认 `false`	使用 Base64 发送图片结果。

图源插件通用配置

图源相关的配置由图源插件自定义，但 pics 插件会在其基础上添加以下几个字段：

参数	类型	是否必选	描述
name	string	是	图源名称
tags	string[]	否	图源标签
weight	number	否	图源权重，越大优先级越高
description	string	否	图源的描述
isDefault	boolean	否	是否默认图源，若设置为 false 或不设置，则需要通过 `-s` 选项指定图源才能调用

多图源的配置

有些图源插件可以配置不止一个图源，如 yande 支持 yande 和 konachan，这种情况下，你需要在 instances 数组里分别配置这些图源。

# koishi.yml
plugins:
  picsource-yande:
    instances:
      - name: yande # Yande 图源
        tags:
          - anime
          - foreign
          - 动漫
          - 二次元
        weight: 1
        isDefault: true
        description: 'Yande 的图'
        endpoint: https://yande.re/post.json
        pageLimit: 200
        useOriginal: true
      - name: konachan # Konachan 图源
        tags:
          - anime
          - foreign
          - 动漫
          - 二次元
        weight: 1
        isDefault: true
        description: 'Konachan 的图'
        endpoint: https://konachan.com/post.json
        pageLimit: 270
        useOriginal: true

作为 koishi 服务提供接口

pics 插件还导出了 PicsContainer 类作为 koishi 的服务，因此你可以在其他插件中通过 ctx.pics 访问其接口。例如，当你需要随机图片时，可以调用 ctx.pics.randomPic() 方法获取。

当你想要添加自己实现的图源时，也同样通过 ctx.pics 添加，详细信息请查看贡献指南。

API

获取图片

randomPic(picTags: string[] = [], sourceTags: string[] = []): Promise<{ url: string, description?: string }> 获取随机图片。
getSegment(url: string, bot?: Bot): Promise<string> 从图片 URL 获取消息段。 由于 OneBot 的一些对接原因，OneBot 机器人所使用的格式与其他机器人不同，因此需要传入机器人判别。

图源管理

addSource(source: PicSource) 进行图源注册。会自动处理插件卸载相关逻辑。

中间件管理

middleware(mid: PicMiddleware) 注册图像处理中间件。

辅助方法

urlToBuffer(url: string, extraConfig: AxiosRequestConfig = {}): Promise<Buffer> 从图片 URL 下载为 Buffer 数据。
bufferToUrl(buffer: Buffer): string 从 Buffer 转换为 base64:// 形式的 URL。
download(url: string, extraConfig: AxiosRequestConfig = {}) 从图片 URL 转换为 base64:// 形式的 URL。

示例

import type {} from 'koishi-plugin-pics'; // 你需要导入 pics 插件的类型定义

await ctx.pics.randomPic(['komeiji koishi'], ['lolicon']) //-> { url: string, description?: string }

贡献代码

如果你想要向本插件贡献代码，或开发新的图源插件，请参阅 CONTRIBUTING.md。

许可证

本项目源码以 MIT 协议授权。

koishijs/koishi-plugin-pics