Merge master

README.md

@@ -23,9 +23,24 @@ npm install koishi-plugin-pics
 
 ## 开始使用
 
-由于 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) 为例，你可以在插件市场搜索相应的名字或者使用 yarn 直接安装。
+由于 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
@@ -42,35 +57,9 @@ plugins:
     description: 'Lolicon API 的图'
     isDefault: true
     weight: 2
-  picsource-yande: # 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
 ```
 
-安装后，可以使用指令 `pic` 获取一张随机图片，使用指令 `pic -t <tag>` 获取一张特定 tag 的图片，也可以使用 `pic -s konachan` 来获取 Konachan 的图片。
+成功启动 koishi 后，就可以使用指令 `pic` 获取一张随机图片，更多的选项可以参考下方[指令](#指令)章节。
 
 ## 指令
 
@@ -94,23 +83,27 @@ pic.sources 查询图源列表
 ### 查询图源列表
 
 ```text
-pic.sources
+pic.sources [...tags]
 查询图源列表
 图源标签可用于图片获取的图源筛选。
 
 使用示例：
 pic.sources 查询全部的图源。
-pic pixiv 查询含有 pixiv 标签的图源。
+pic.sources pixiv 查询含有 pixiv 标签的图源。
 ```
 
 ## 配置
 
+### pics 配置
+
 koishi-plugin-pics 的配置如下表所示：
 
 |参数|类型|是否必选|描述|
 |:-:|:-:|:-:|:-:|
 |commandName|string|否|指令名称，默认为 pic。|
 
+### 图源插件通用配置
+
 图源相关的配置由图源插件自定义，但 pics 插件会在其基础上添加以下几个字段：
 
 |参数|类型|是否必选|描述|
@@ -121,34 +114,14 @@ koishi-plugin-pics 的配置如下表所示：
 |description|string|否|图源的描述|
 |isDefault|boolean|否|是否默认图源，若设置为 false 或不设置，则需要通过 `-s` 选项指定图源才能调用|
 
-```yaml
-plugins:
-  pics:
-    commandName: pic
-  picsource-lolicon:
-    $install: true
-    $community: true
-    name: lolicon
-    r18: 2
-    tags:
-      - anime
-      - 动漫
-      - 二次元
-    description: 'Lolicon API 的图'
-    isDefault: true
-    weight: 2
-```
+### 多图源的配置
 
-> 有些形如 yande 的图源插件，可能会配置多个图源。这时候每个图源都需要依照定义分开配置。
+有些图源插件可以配置不止一个图源，如 yande 支持 yande 和 konachan，这种情况下，你需要在 `instances` 数组里分别配置这些图源。
 
 ```yaml
 # koishi.yml
 plugins:
-  pics:
-    commandName: pic
   picsource-yande:
-    $install: true
-    $community: true
     instances:
       - name: yande # Yande 图源
         tags:
@@ -178,9 +151,9 @@ plugins:
 
 ## 作为 koishi 服务提供接口
 
-`pics` 导出 `PicsContainer` 类作为 koishi 的服务，因此你可以在其他插件中通过 `ctx.pics` 访问其接口。例如，当你需要随机图片时，可以调用 `ctx.pics.randomPic()` 方法获取。
+`pics` 插件还导出了 `PicsContainer` 类作为 koishi 的服务，因此你可以在其他插件中通过 `ctx.pics` 访问其接口。例如，当你需要随机图片时，可以调用 `ctx.pics.randomPic()` 方法获取。
 
-> 若不希望注册随机图片指令，可以使用 `ctx.never().plugin('koishi-plugin-pics')` 来禁用指令注册。
+当你想要添加自己实现的图源时，也同样通过 `ctx.pics` 添加，详细信息请查看[贡献指南](./CONTRIBUTING.md)。
 
 ### API
 
@@ -189,22 +162,9 @@ plugins:
 ### 示例
 
 ```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;
-  }
-}
+import type {} from 'koishi-plugin-pics'; // 你需要导入 pics 插件的类型定义
+
+await ctx.pics.randomPic(['komeiji koishi'], ['pixiv']) //-> { url: string, description?: string }
 ```
 
 ## 贡献代码

src/index.ts

@@ -253,7 +253,7 @@ export default class PicsContainer
       // .option('source', '-s <source:string>  要查询的图源标签，逗号分隔。')
       .usage('图源标签可用于图片获取的图源筛选。')
       .example(`${this.config.commandName}.sources 查询全部的图源。`)
-      .example(`${this.config.commandName} pixiv 查询含有 pixiv 标签的图源。`)
+      .example(`${this.config.commandName}.sources pixiv 查询含有 pixiv 标签的图源。`)
       .action(async (argv, ...sourceTags) => {
         sourceTags ||= [];
         const sources = this.pickAvailableSources(sourceTags, true);