Skip to content

K
koishi-plugin-pics
Commit b066b81e authored by nanahira's avatar nanahira
Browse files
Options

Merge branch 'docs/renew-readme' of git.mycard.moe:3rdeye/koishi-plugin-pics into next

parents 020820bf ff4a1119
Hide whitespace changes
Inline Side-by-side
Showing with 265 additions and 292 deletions
CONTRIBUTING.md 0 → 100644
View file @ b066b81e
# 贡献代码
如果你对本插件有任何的意见建议，欢迎开启 issue 进行说明，或者你也可以直接贡献代码。
由于 pics 设计为可插拔式的框架，当前仓库仅实现了发送图片的功能，而获取图源的能力则完全由其他插件所实现（下称图源插件）。因此你可以选择向 pics（即本仓库）贡献代码，也可以开发新的图源插件，或向现有的图源插件贡献代码。
# 向当前仓库贡献代码
本仓库采用了 [koishi-thirdeye](https://koishi.js.org/about/decorator) 进行开发，思路与理念与传统的 koishi 插件并不相同，在贡献代码之前请先了解双方的异同。
# 开发图源插件
图源由其他 Koishi 插件提供。这些插件需要实现 `PicSource` 类，并使用 `ctx.pics.addSource(picSource, ctx)` 进行注入。
### 类定义
图源插件推荐在 `package.json` 的 `keywords` 内写上 `required:pics` 以保证正确被 Koishi 插件市场搜索。
```ts
export interface PicResult {
// 图片 URL
url: string;
// 图片介绍，会一并出现在底部
description?: string;
}
export class PicSource {
// 构造函数传入 ctx 对象
constructor(ctx: Context);
// 图源的标签列表，使用 -s 参数匹配。
tags: string[];
// 图源权重，权重越大随机到的概率越大，默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
// 获取随机图片。 picTags 可能是空数组。
randomPic(picTags: string[]): PicResult | Promise<PicResult>;
// 图源启动时运行，可选
onStartup(): Awaitable<void>;
// 图源卸载时运行，可选
onShutdown(): Awaitable<void>;
}
```
### 插件示例
#### 单图源
```ts
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
@RegisterSchema()
export class Config extends PicSourceConfig {
@SchemaProperty({ default: 10000 })
code: number;
}
@DefinePlugin({ name: 'my-picsource', schema: Config })
export default class MyPicSource extends PicSource implements LifecycleEvents {
constructor(ctx: Context, config: Partial<Config>) {
super(ctx);
}
@InjectConfig()
private config: Config;
@Inject(true)
private pics: PicsContainer;
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
onApply() {
this.config.applyTo(this);
this.pics.addSource(this);
}
}
```
#### 多图源
```ts
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
@RegisterSchema()
export class InstanceConfig extends PicSourceConfig {
@SchemaProperty({ default: 10000 })
code: number;
}
@RegisterSchema()
export class Config {
constructor(config: Partial<InstanceConfig>[]) {}
@SchemaProperty({ type: InstanceConfig })
instances: InstanceConfig[];
}
export default class MyPicSourceInstance extends PicSource {
constructor(ctx: Context, config: Partial<Config>) {
super(ctx);
config.applyTo(this);
}
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
}
@DefinePlugin({ name: 'my-picsource', schema: Config })
export default class MyPicSource extends BasePlugin<Config> implements LifecycleEvents {
@InjectConfig()
private config: Config;
@Inject(true)
private pics: PicsContainer;
onApply() {
for (const instanceConfig of this.config.instances) {
const instance = new MyPicSourceInstance(this.ctx, instanceConfig);
this.pics.addSource(instance);
}
}
}
```
### 开箱即用的 Schema 定义
为了方便编写图源插件的配置部分，这里提供了一些开箱即用的配置文件 Schema 定义，可以从 `koishi-plugin-pics` 中导出。
#### `PicSourceSchema`
包含下列字段的 Schema 定义，方便创建图源插件的配置。
```ts
export interface PicSourceInfo {
// 图源的标签列表，使用 -s 参数匹配。
tags: string[];
// 图源权重，权重越大随机到的概率越大，默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
}
```
同时 `PicSourceInfo` 也可以从 `koishi-plugin-pics` 中导出。
#### `PicSourceConfig`
[`schemastery-gen`](https://code.mycard.moe/3rdeye/schemastery-gen) 或 [`koishi-thirdeye`](https://code.mycard.moe/3rdeye/koishi-thirdeye) 用户可以使用 `PicSourceConfig` 类。插件的配置文件直接继承该类即可。
> 继承 `PicSourceConfig` 的类需要手动使用 `@RegisterSchema()` 装饰器将自身注册为 Schema 定义。
> `schemastery-gen` 包请**不要**使用 Webpack 打包。使用 Webpack 编写插件的用户请把该包列为 external 。
```ts
export class PicSourceConfig {
@SchemaProperty({ type: 'string', default: [], desc: '图源标签' })
tags: string[];
@SchemaProperty({ default: 1, desc: '图源权重' })
weight: number;
@SchemaProperty({ default: 1, desc: '图源名称', required: true })
name: string;
@SchemaProperty({ desc: '图源描述' })
description?: string;
@SchemaProperty({ desc: '是否为默认图源' })
isDefault?: boolean;
// 给目标对象注入上述对象。
applyTo(target: PicSourceInfo) {
target.tags ||= this.tags;
target.weight ||= this.weight;
target.name ||= this.name;
target.description ||= this.description;
target.isDefault = this.isDefault;
}
}
```
README.md
View file @ b066b81e
......@@ -4,13 +4,43 @@ Koishi 的随机图片插件
## 安装
### npm
你可以选择通过 koishi 的插件市场安装本插件，也可以使用 npm 或 yarn 等包管理器安装。
### 通过插件市场
如果你通过 koishi 的[模板项目](https://koishi.js.org/guide/introduction/template.html)创建了你的机器人项目，你可以直接从插件市场安装本插件。详情请参考[安装和配置插件](https://koishi.js.org/guide/introduction/template.html#%E5%AE%89%E8%A3%85%E5%92%8C%E9%85%8D%E7%BD%AE%E6%8F%92%E4%BB%B6)
### 通过包管理器
由于 koishi 现在的默认包管理器是 yarn，因此推荐使用 yarn 安装插件，当然，你也可以使用 npm 安装。
```bash
# 如果你使用 yarn
yarn add koishi-plugin-pics
# 如果你使用 npm
npm install koishi-plugin-pics
```
## 快速开始
## 开始使用
由于 pics 仅仅是一个随机图片的插件框架，并不包含任何图源的实现，因此你必须添加至少一个图源插件才能开始使用。
### 图源插件
* [`koishi-plugin-picsource-localfs`](https://npmjs.com/package/koishi-plugin-picsource-localfs) 本地文件图源。
* [`koishi-plugin-picsource-lolicon`](https://npmjs.com/package/koishi-plugin-picsource-lolicon) [Lolicon](https://api.lolicon.app/ ) 图源。
* [`koishi-plugin-picsource-heisi`](https://npmjs.com/package/koishi-plugin-picsource-heisi) heisi 图源，基于 [nonebot_plugin_heisi](https://github.com/yzyyz1387/nonebot_plugin_heisi)。
* [`koishi-plugin-picsource-yande`](https://npmjs.com/package/koishi-plugin-picsource-yande) [Yandere](https://yande.re/) 及 [Konachan](https://konachan.com) 图源。
### 图源配置
在开始启动之前，你还需要添加一些配置，告诉 pics 插件有哪些图源插件可以使用，以及每个图源插件的配置。对于配置项的详细说明，请参考[配置](#配置)。
下面以 [`koishi-plugin-picsource-lolicon`](https://npmjs.com/package/koishi-plugin-picsource-lolicon) 和
[`koishi-plugin-picsource-yande`](https://npmjs.com/package/koishi-plugin-picsource-yande) 为例进行说明。
```yaml
# koishi.yml
......@@ -18,8 +48,6 @@ plugins:
pics:
commandName: pic
picsource-lolicon: # Lolicon 图源
$install: true
$community: true
name: lolicon
r18: 2
tags:
......@@ -29,43 +57,15 @@ plugins:
description: 'Lolicon API 的图'
isDefault: true
weight: 2
picsource-yande: # Yande 图源插件
$install: true
$community: true
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
```
安装后，可以使用指令 `pic` 获取一张随机图片，使用指令 `pic -t <tag>` 获取一张特定 tag 的图片，也可以使用 `pic -s konachan` 来获取 Konachan 的图片。
成功启动 koishi 后，就可以使用指令 `pic` 获取一张随机图片，更多的选项可以参考下方[指令](#指令)章节。
## 指令
### 获取随机图片
```
```text
pic [...tags:string]
获取随机图片
从各个图源中随机获取一张随机图片。图源可以用 pic.sources 查询。参数均为可选。
......@@ -82,65 +82,46 @@ pic.sources 查询图源列表
### 查询图源列表
```
pic.sources
```text
pic.sources [...tags]
查询图源列表
图源标签可用于图片获取的图源筛选。
使用示例：
pic.sources 查询全部的图源。
pic pixiv 查询含有 pixiv 标签的图源。
pic.sources pixiv 查询含有 pixiv 标签的图源。
```
## 配置
koishi-plugin-pics 的配置仅有 `commandName` 一项，用于指定指令名称。
### pics 配置
其余配置均在各图源中自定义。通常来说具有下面几个字段。
koishi-plugin-pics 的配置如下表所示：
```ts
export interface PicSourceInfo {
// 图源的标签列表，使用 -s 参数匹配。
tags: string[];
// 图源权重，权重越大随机到的概率越大，默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
}
```
|参数|类型|是否必选|描述|
|:-:|:-:|:-:|:-:|
|commandName|string|否|指令名称，默认为 pic。|
```yaml
plugins:
pics:
commandName: pic
picsource-lolicon:
$install: true
$community: true
name: lolicon
r18: 2
tags:
- anime
- 动漫
- 二次元
description: 'Lolicon API 的图'
isDefault: true
weight: 2
```
### 图源插件通用配置
图源相关的配置由图源插件自定义，但 pics 插件会在其基础上添加以下几个字段：
|参数|类型|是否必选|描述|
|:-:|:-:|:-:|:-:|
|name|string|是|图源名称|
|tags|string[]|否|图源标签|
|weight|number|否|图源权重，越大优先级越高|
|description|string|否|图源的描述|
|isDefault|boolean|否|是否默认图源，若设置为 false 或不设置，则需要通过 `-s` 选项指定图源才能调用|
### 多图源的配置
> 有些形如 yande 的图源插件，可能会配置多个图源。这时候每个图源都需要依照定义分开配置。
有些图源插件可以配置不止一个图源，如 yande 支持 yande 和 konachan，这种情况下，你需要在 `instances` 数组里分别配置这些图源。
```yaml
# koishi.yml
plugins:
pics:
commandName: pic
picsource-yande:
$install: true
$community: true
instances:
- name: yande # Yande 图源
tags:
......@@ -168,233 +149,28 @@ plugins:
useOriginal: true
```
## 图源
图源由其他 Koishi 插件提供。这些插件需要实现 `PicSource` 类，并使用 `ctx.pics.addSource(picSource, ctx)` 进行注入。
### 图源插件
下面是一些开箱即用的图源。如果你希望你编写的图源插件在此处列出，欢迎提交 Pull Request 或发邮件给 `nanahira@momobako.com` 。
* [`koishi-plugin-picsource-localfs`](https://github.com/koishijs/koishi-plugin-picsource-localfs) 本地文件图源。
* [`koishi-plugin-picsource-lolicon`](https://github.com/koishijs/koishi-plugin-picsource-lolicon) [Lolicon](https://api.lolicon.app/ ) 图源。
* [`koishi-plugin-picsource-heisi`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-heisi) 黑丝图源。
* [`koishi-plugin-picsource-yande`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-yande) [Yande](https://yande.re/) 以及 [Konachan](https://konachan.com) 图源。
### 类定义
图源插件推荐在 `package.json` 的 `keywords` 内写上 `required:pics` 以保证正确被 Koishi 插件市场搜索。
```ts
export interface PicResult {
// 图片 URL
url: string;
// 图片介绍，会一并出现在底部
description?: string;
}
export class PicSource {
// 构造函数传入 ctx 对象
constructor(ctx: Context);
// 图源的标签列表，使用 -s 参数匹配。
tags: string[];
// 图源权重，权重越大随机到的概率越大，默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
// 获取随机图片。 picTags 可能是空数组。
randomPic(picTags: string[]): PicResult | Promise<PicResult>;
// 图源启动时运行，可选
onStartup(): Awaitable<void>;
// 图源卸载时运行，可选
onShutdown(): Awaitable<void>;
}
```
### 插件示例
#### 单图源
```ts
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
@RegisterSchema()
export class Config extends PicSourceConfig {
@SchemaProperty({ default: 10000 })
code: number;
}
@DefinePlugin({ name: 'my-picsource', schema: Config })
export default class MyPicSource extends PicSource implements LifecycleEvents {
constructor(ctx: Context, config: Partial<Config>) {
super(ctx);
}
@InjectConfig()
private config: Config;
@Inject(true)
private pics: PicsContainer;
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
onApply() {
this.config.applyTo(this);
this.pics.addSource(this);
}
}
```
#### 多图源
```ts
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
@RegisterSchema()
export class InstanceConfig extends PicSourceConfig {
@SchemaProperty({ default: 10000 })
code: number;
}
## 作为 koishi 服务提供接口
@RegisterSchema()
export class Config {
constructor(config: Partial<InstanceConfig>[]) {}
`pics` 插件还导出了 `PicsContainer` 类作为 koishi 的服务，因此你可以在其他插件中通过 `ctx.pics` 访问其接口。例如，当你需要随机图片时，可以调用 `ctx.pics.randomPic()` 方法获取。
@SchemaProperty({ type: InstanceConfig })
instances: InstanceConfig[];
}
当你想要添加自己实现的图源时，也同样通过 `ctx.pics` 添加，详细信息请查看[贡献指南](./CONTRIBUTING.md)。
### API
export default class MyPicSourceInstance extends PicSource {
constructor(ctx: Context, config: Partial<Config>) {
super(ctx);
config.applyTo(this);
}
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
}
@DefinePlugin({ name: 'my-picsource', schema: Config })
export default class MyPicSource extends BasePlugin<Config> implements LifecycleEvents {
@InjectConfig()
private config: Config;
@Inject(true)
private pics: PicsContainer;
onApply() {
for (const instanceConfig of this.config.instances) {
const instance = new MyPicSourceInstance(this.ctx, instanceConfig);
this.pics.addSource(instance);
}
}
}
```
### 开箱即用的 Schema 定义
为了方便编写图源插件的配置部分，这里提供了一些开箱即用的配置文件 Schema 定义，可以从 `koishi-plugin-pics` 中导出。
#### `PicSourceSchema`
* `randomPic(picTags: string[] = [], sourceTags: string[] = []): Promise<{ url: string, description?: string }>`
包含下列字段的 Schema 定义，方便创建图源插件的配置。
### 示例
```ts
export interface PicSourceInfo {
// 图源的标签列表，使用 -s 参数匹配。
tags: string[];
// 图源权重，权重越大随机到的概率越大，默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
}
```
import type {} from 'koishi-plugin-pics'; // 你需要导入 pics 插件的类型定义
同时 `PicSourceInfo` 也可以从 `koishi-plugin-pics` 中导出。
#### `PicSourceConfig`
[`schemastery-gen`](https://code.mycard.moe/3rdeye/schemastery-gen) 或 [`koishi-thirdeye`](https://code.mycard.moe/3rdeye/koishi-thirdeye) 用户可以使用 `PicSourceConfig` 类。插件的配置文件直接继承该类即可。
> 继承 `PicSourceConfig` 的类需要手动使用 `@RegisterSchema()` 装饰器将自身注册为 Schema 定义。
> `schemastery-gen` 包请**不要**使用 Webpack 打包。使用 Webpack 编写插件的用户请把该包列为 external 。
```ts
export class PicSourceConfig {
@SchemaProperty({ type: 'string', default: [], desc: '图源标签' })
tags: string[];
@SchemaProperty({ default: 1, desc: '图源权重' })
weight: number;
@SchemaProperty({ default: 1, desc: '图源名称', required: true })
name: string;
@SchemaProperty({ desc: '图源描述' })
description?: string;
@SchemaProperty({ desc: '是否为默认图源' })
isDefault?: boolean;
// 给目标对象注入上述对象。
applyTo(target: PicSourceInfo) {
target.tags ||= this.tags;
target.weight ||= this.weight;
target.name ||= this.name;
target.description ||= this.description;
target.isDefault = this.isDefault;
}
}
await ctx.pics.randomPic(['komeiji koishi'], ['pixiv']) //-> { url: string, description?: string }
```
## 提供服务
`pics` 也作为服务导出。对于其他插件需要使用随机图片的场景，可以使用 `ctx.pics.randomPic()` 方法来获取随机图片。
## 贡献代码
> 若不希望注册随机图片指令，可以使用 `ctx.never().plugin('koishi-plugin-pics')` 来禁用指令注册。
如果你想要向本插件贡献代码，或开发新的图源插件，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
### API
* `randomPic(picTags: string[] = [], sourceTags: string[] = []): Promise<{ url: string, description?: string }>`
## 许可证
### 示例
```ts
import { PicsContainer } from 'koishi-plugin-pics';
import { Inject, DefinePlugin } from 'koishi-thirdeye';
@DefinePlugin()
export default class SomePlugin {
@Inject(true)
private pics: PicsContainer;
// ...
// somewhere needed
async getRandomPics(picTags: string[], sourceTags: string[] = []) {
const pics = await this.pics.randomPic(picTags, sourceTags);
return pics;
}
}
```
本项目源码以 [MIT 协议](./LICENSE) 授权。
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment