docs: renew readme

86509ee5 · 迷子 (Maiko Tan) · GitHub · d010465c · 86509ee5 · 86509ee5
Commit 86509ee5 authored Mar 30, 2022 by 迷子 (Maiko Tan) Committed by GitHub Mar 30, 2022
Hide whitespace changes
Inline Side-by-side

Showing with 234 additions and 219 deletions

CONTRIBUTING.md CONTRIBUTING.md +199 -0

README.md README.md +35 -219

No files found.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
+## 图源
+图源由其他 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;
+}
+@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;
+  }
+}
+```
\ No newline at end of file
--- a/README.md
+++ b/README.md
@@ -4,14 +4,29 @@ 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)
+### 包管理器
+推荐使用 yarn 安装插件，当然，也可以使用 npm 安装。
 ```bash
+# 如果你使用 yarn
+yarn add koishi-plugin-pics
+# 如果你使用 npm
 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 插件有哪些图源插件可以使用，以及每个图源插件的配置。对于配置项的详细说明，请参考[配置](#配置)。
 ```yaml
 # koishi.yml
 plugins:
@@ -92,24 +107,22 @@ pic.sources 查询全部的图源。 pic -s pixiv 查询含有 pixiv 标签的
 ## 配置
-koishi-plugin-pics 的配置仅有 `commandName` 一项，用于指定指令名称。
+koishi-plugin-pics 的配置如下表所示：
-其余配置均在各图源中自定义。通常来说具有下面几个字段。
+|:-:|:-:|:-:|:-:|
+|参数|类型|是否必选|描述|
+|commandName|string|否|指令名称，默认为 pic。|
+图源相关的配置由图源插件自定义，但 pics 插件会在其基础上添加以下几个字段：
+|:-:|:-:|:-:|:-:|
+|参数|类型|是否必选|描述|
+|name|string|是|图源名称|
+|tags|string[]|否|图源标签|
+|weight|number|否|图源权重，越大优先级越高|
+|description|string|否|图源的描述|
+|isDefault|boolean|否|是否默认图源，若设置为 false 或不设置，则需要通过 `-s` 选项指定图源才能调用|
-```ts
-export interface PicSourceInfo {
-  // 图源的标签列表，使用 -s 参数匹配。
-  tags: string[];
-  // 图源权重，权重越大随机到的概率越大，默认 1
-  weight: number;
-  // 图源名称。
-  name: string;
-  // 图源介绍
-  description: string;
-  // 是否为默认图源。用户未指定参数时使用默认图源。
-  isDefault: boolean;
-}
-```
 ```yaml
 plugins:
@@ -166,209 +179,9 @@ plugins:
        useOriginal: true
 ```
-## 图源
+## 作为 koishi 服务提供接口
-图源由其他 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);
-  }
-}
-```
-#### 多图源
+`pics` 导出 `PicsContainer` 类作为 koishi 的服务，因此你可以在其他插件中通过 `ctx.pics` 访问其接口。例如，当你需要随机图片时，可以调用 `ctx.pics.randomPic()` 方法获取。
-```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;
-  }
-}
-```
-## 提供服务
-`pics` 也作为服务导出。对于其他插件需要使用随机图片的场景，可以使用 `ctx.pics.randomPic()` 方法来获取随机图片。
 > 若不希望注册随机图片指令，可以使用 `ctx.never().plugin('koishi-plugin-pics')` 来禁用指令注册。
@@ -396,3 +209,6 @@ export default class SomePlugin {
  }
 }
 ```
+## 贡献代码
+如果你想要向本插件贡献代码，或开发新的图源插件，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。