Add V2 plugin
This commit is contained in:
Kwaroran
159
plugins.md
Normal file
159
plugins.md
Normal file
@@ -0,0 +1,159 @@
|
||||
|
||||
# Plugins
|
||||
|
||||
RisuAI uses a plugin system to allow for easy extension of the functionality.
|
||||
|
||||
## Creating a Plugin
|
||||
|
||||
A plugin is a js file with a header. for example:
|
||||
|
||||
```js
|
||||
//@name exampleplugin
|
||||
//display-name: Example Plugin
|
||||
|
||||
// Plugin code here
|
||||
```
|
||||
|
||||
## Header Fields
|
||||
|
||||
- `@name <name>` - The name of the plugin. This is used to identify the plugin. required.
|
||||
- `@display-name <display_name>` - The display name of the plugin. This is used to display the plugin in the UI.
|
||||
- `@arg <name> <type>` Argument definition. This is used to define the arguments that the plugin takes. The type can be `int` or `string`.
|
||||
|
||||
## API Reference
|
||||
|
||||
|
||||
### `risuFetch(url: string, arg: GlobalFetchArgs = {}): Promise<GlobalFetchResult>`
|
||||
|
||||
> Note: `nativeFetch` is recommended for fetching URLs with POST request, as it has the same functionality as `risuFetch`, but with a similar API to `fetch` with more predictable behavior.
|
||||
|
||||
Fetches a URL with a native API, which doesn't have CORS restrictions.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `url: string` - The URL to fetch.
|
||||
- `arg: GlobalFetchArgs` - The fetch arguments.
|
||||
- `body: string|Object` - The body to send with the request. if it's an object, it will be converted to JSON.
|
||||
- `headers: Record<string, string>` - The headers to send with the request.
|
||||
- `method: string` - The method to use for the request `GET` and `POST` are supported. Default: `POST`.
|
||||
- `abortSignal: AbortSignal` - The signal to use for aborting the request.
|
||||
- `rawResponse: boolean` - If true, the response will be returned as Uint8Array. Default: `false`.
|
||||
|
||||
#### Returns
|
||||
|
||||
- `Promise<GlobalFetchResult>` - The fetch result.
|
||||
- `ok: boolean` - If the request was successful.
|
||||
- `data: any` - The response data which is parsed JSON if possible. if `rawResponse` is true, it will be a Uint8Array.
|
||||
- `headers: Record<string, string>` - The response headers.
|
||||
|
||||
### `nativeFetch(url: string, arg: NativeFetchArg = {}): Promise<NativeFetchResults>`
|
||||
|
||||
Fetches a URL with the native fetch API, which has CORS restrictions.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `url: string` - The URL to fetch.
|
||||
- `arg: NativeFetchArg` - The fetch arguments.
|
||||
- `body: string|Uint8Array|ArrayBuffer` - The body to send with the request.
|
||||
- `headers: Record<string, string>` - The headers to send with the request.
|
||||
- `method: string` - The method to use for the request. only `POST` is supported. Default: `POST`.
|
||||
- `signal: AbortSignal` - The signal to use for aborting the request.
|
||||
|
||||
#### Returns
|
||||
|
||||
- `Promise<NativeFetchResults>` - The fetch result.
|
||||
- `body: ReadableStream<Uint8Array>` - The response body.
|
||||
- `headers: Headers` - The response headers.
|
||||
- `status: number` - The response status.
|
||||
- `json: () => Promise<any>` - A function that returns a promise that resolves to the JSON representation of the response body.
|
||||
- `text: () => Promise<string>` - A function that returns a promise that resolves to the text representation of the response body.
|
||||
|
||||
### `getArg(name: string): string|number`
|
||||
|
||||
Gets the argument value by name.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `name: string` - The argument name. must be format of `<plugin_name>::<arg_name>` like `exampleplugin::arg1`.
|
||||
|
||||
#### Returns
|
||||
|
||||
- `string|number` - The argument value.
|
||||
|
||||
### `getChar(): character`
|
||||
|
||||
Gets the current character.
|
||||
|
||||
### `setChar(char: character): void`
|
||||
|
||||
Sets the current character.
|
||||
|
||||
### `addProvider(type: string, func: (arg:PluginV2ProviderArgument) => Promise<{success:boolean,content:string}>): void`
|
||||
|
||||
Adds a provider to the plugin.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `type: string` - The provider name.
|
||||
- `func: (arg:PluginV2ProviderArgument) => Promise<{success:boolean,content:string}>` - The provider function.
|
||||
- `arg: PluginV2ProviderArgument` - The provider argument.
|
||||
- `prompt_chat: Chat[]` - The chat prompt.
|
||||
- `frequency_penalty?: number` - The frequency penalty.
|
||||
- `min_p?: number` - The minimum p value.
|
||||
- `presence_penalty?: number` - The presence penalty.
|
||||
- `repetition_penalty?: number` - The repetition penalty.
|
||||
- `top_k?: number` - The top k value.
|
||||
- `top_p?: number` - The top p value.
|
||||
- `temperature?: number` - The temperature value.
|
||||
- `mode: string` - The mode. one of `model`, `submodel`, `memory`, `emotion`, `otherAx`, `translate`
|
||||
- `Promise<{success:boolean,content:string}>` - The provider result.
|
||||
- `success: boolean` - If the provider was successful.
|
||||
- `content: string` - The provider content.
|
||||
|
||||
### `addRisuScriptHandler(type: string, func: (content:string) => string|null|undefined|Promise<string|null|undefined>): void`
|
||||
|
||||
Adds a risu script handler to the plugin.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `type: string` - The handler type. one of `display`, `output`, `input`, `process`
|
||||
- `func: (content:string) => string|null|undefined|Promise<string|null|undefined>` - The handler function.
|
||||
- `content: string` - The content to handle.
|
||||
- `string|null|undefined|Promise<string|null|undefined>` - The handler result. if it is a string or string promise, the data will be replaced with the result.
|
||||
|
||||
### `removeRisuScriptHandler(type: string, func: (content:string) => string|null|undefined|Promise<string|null|undefined>): void`
|
||||
|
||||
Removes a risu script handler from the plugin.
|
||||
|
||||
### `addRisuReplacer(type: string, func: ReplacerFunction): void`
|
||||
|
||||
Adds a risu replacer to the plugin.
|
||||
|
||||
#### Arguments
|
||||
|
||||
- `type: string` - The replacer type. one of `beforeRequest`, `afterRequest`.
|
||||
- `func: ReplacerFunction` - The replacer function. vary depending on the type.
|
||||
- If the type is `afterRequest`, the function should be `(content: string) => string`.
|
||||
- If the type is `beforeRequest`, the function should be `(content: Chat[]) => Chat[]`.
|
||||
|
||||
### `removeRisuReplacer(type: string, func: ReplacerFunction): void`
|
||||
|
||||
Removes a risu replacer from the plugin.
|
||||
|
||||
### `onUnload(func: () => void): void`
|
||||
|
||||
Adds an unload handler to the plugin.
|
||||
|
||||
|
||||
## Migration from Plugin V1
|
||||
|
||||
The plugin system has been updated to V2. The following changes have been made:
|
||||
- Now runs in same context as the main script rather than in a sandbox, making it accessible to the main script and DOM.
|
||||
- Added `nativeFetch`, `addRisuScriptHandler`, `removeRisuScriptHandler`, `addRisuReplacer`, `removeRisuReplacer`, `onUnload` functions.
|
||||
- `method`, `abortSignal`, `rawResponse` arguments has been added to `risuFetch`.
|
||||
- `min_p`, `top_k`, `top_p`, `mode` arguments has been added to `addProvider`.
|
||||
- `bias` argument has been removed from `addProvider`. however for compatibility, it still calls with empty array.
|
||||
- Now plugin doesn't automatically terminates itself. you have to manually unload the plugin using `onUnload` function.
|
||||
- `addCharaJs` function has been removed. use `addRisuScriptHandler` instead.
|
||||
- Many security restrictions have been removed.
|
||||
- `@risu-name`, `@risu-display-name`, `@risu-arg` headers has been removed. use `@name`, `@display-name`, `@arg` instead. if it's not present, it will be ran as V1 plugin.
|
||||
Reference in New Issue
Block a user