From 3e8a8dda50e4ea8dee8d5a7370276a7ea8084d15 Mon Sep 17 00:00:00 2001 From: Him188 Date: Wed, 15 Jun 2022 11:12:25 +0100 Subject: [PATCH] Update UserManual for command arguments, close #1952 --- docs/ConsoleTerminal.md | 245 ++++++++++++++++++++++++++++++++++++++++ docs/UserManual.md | 131 +-------------------- 2 files changed, 246 insertions(+), 130 deletions(-) create mode 100644 docs/ConsoleTerminal.md diff --git a/docs/ConsoleTerminal.md b/docs/ConsoleTerminal.md new file mode 100644 index 00000000000..43f2754ce2b --- /dev/null +++ b/docs/ConsoleTerminal.md @@ -0,0 +1,245 @@ +# Mirai - Console Terminal + +本文介绍如何使用 Mirai Console 的纯控制台前端，即 `mirai-console-terminal` +。本文部分内容实际上对所有前端都通用。 + +本文面向用户，若要开发 Mirai +Console，可参考 [Console 开发文档](../mirai-console/docs/README.md)。 + +本文假设你使用 Windows 操作系统。但 Mirai Console 并不仅限于 Windows +平台使用，在其他操作系统上的使用方法应当是类似的。 + +安装 +---- + +可以使用[脚本](https://mirai.mamoe.net/assets/uploads/files/1618372079496-install-20210412.cmd) +自动安装 32 位带 HTTP 插件的版本，也可以使用安装器个性化安装： + +[iTXTech/mcl-installer]: https://github.com/iTXTech/mcl-installer/releases + +1. 访问 [iTXTech/mcl-installer]； +2. 下载适合你的系统的可执行文件； +3. 在一个新文件夹存放这个文件，运行它； +4. 通常可以一路回车使用默认设置完成安装，安装完成后程序自动退出； +5. 运行 `mcl.cmd` 启动，成功后会看到绿色的 `mirai-console started successfully`。 + +了解运行环境 +---- + + +安装时自动下载了 Mirai Console +启动器（简称 [MCL](https://github.com/iTXTech/mirai-console-loader)）。 + +启动器会帮你准备运行环境，下载和更新 Mirai 核心。你也可以使用启动器下载一些插件（见下文）。 + +第一次运行 `mcl.cmd` 时会初始化运行环境。下表说明了各个文件夹的用途。 + +MCL 只是启动器，没有机器人功能。MCL 支持从远程仓库下载插件，并启动 Mirai Console +终端版（`mirai-console-terminal`）。 + +如果遇到启动器问题，请提交至 [iTXTech/mirai-console-loader](https://github.com/iTXTech/mirai-console-loader) +。 + +| 文件夹名称 | 用途 | +|:---------:|:--------------------| +| `scripts` | 存放启动器的脚本，一般不需要在意他们 | +| `plugins` | 存放插件 | +| `data` | 存放插件的数据，一般不需要在意它们 | +| `config` | 存放插件的配置，可以打开并修改配置 | +| `logs` | 存放运行时的日志，日志默认保留 7 天 | + +> 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法 + + +了解插件 +---- + +Mirai Console 原生支持 JAR 文件插件。一般插件的后缀为 `.mirai2.jar`（新版本）或 `.mirai.jar` +（旧版本）。 + +将插件 JAR 放在 `plugins` 目录中，重启 MCL 就会自动扫描并加载。 + +Mirai Console + +下载和安装插件 +---- + +刚刚装好的 Mirai Console 没有功能，功能将由插件提供。 + +### 使用 MCL 自动安装插件 + +### 如何安装官方插件 + +Mirai 官方提供两个插件： + +- [chat-command](https://github.com/project-mirai/chat-command): + 允许在聊天环境通过以 "/" 起始的消息执行指令（也可以配置前缀） +- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 + HTTP 支持，允许使用其他编程语言的插件 + +打开命令行 (Windows 系统在文件夹按住 Shift 单击鼠标右键，点击 "在此处打开 PowerShell")， +可以使用 MCL 自动安装这些插件，例如： + +安装 mirai-api-http 的 2.x 版本： + +```powershell +./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel stable-v2 +``` + +安装 chat-command： + +```powershell +./mcl --update-package net.mamoe:chat-command --type plugin --channel stable +``` + +注意：插件有多个频道，`--channel stable` 表示使用名为 `stable`（稳定）的频道。不同的插件可能会设置不同的频道， +具体需要使用哪个频道可参考特定插件的说明 (很多插件会单独说明要如何安装它们, 因此不必过多考虑)。 + +详细文档：[MCL/scripts](https://github.com/iTXTech/mirai-console-loader/blob/master/cli.md) + +### 在哪找社区插件 + +- Mirai + 官方论坛 [Mirai Forum](https://mirai.mamoe.net/category/11/%E6%8F%92%E4%BB%B6%E5%8F%91%E5%B8%83) + +> *我们还正在建设插件中心，完成后将会简化寻找插件的工作* + +### 如何安装社区插件 + +如果是 JAR 文件的插件，放入 `plugins` 即可。其他插件一般都有特殊说明如何使用，请参考它们的说明。 + +注意，mirai 在 2.11 时修改了加载策略。在这之后如果要从 MCL 安装插件 + +### 推荐安装的插件 + +- [chat-command](https://github.com/project-mirai/chat-command): + 不安装此环境不能在聊天环境中执行命令 +- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 + HTTP 支持，允许使用其他编程语言的插件 + +- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai) + ：高级权限组插件，适合权限分配模型比较复杂的情况 + +使用控制台指令 +----- + +启动 `mcl.cmd` 就会看到控制台。在控制台可以输入指令，按回车执行这条指令。 + +Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表。 + +一些常用指令介绍在[这里](/mirai-console/docs/BuiltInCommands.md#mirai-console---builtin-commands) +。 + +### 在群聊中使用命令 (权限授予) + +要允许从 QQ 聊天环境中使用各种命令, 你 **必须** 完成以下的配置： + +1. 安装 [chat-command](https://github.com/project-mirai/chat-command) +2. 完成命令执行权限授予 + +> 关于不同的权限系统，授予权限的方式或者授予权限的命令格式可能有所不一样。 +> +> 当使用非内置权限系统时，具体的权限管理相关命令以相关的权限系统的文档为准 +> > 如 `LuckPerms-Mirai` 插件的权限管理命令为 `/lp` 而不是 `/permission` + +要完成权限授予，你必须通过在控制台执行 +[`/permission permit [target] [permission]`](/mirai-console/docs/BuiltInCommands.md#permissioncommand) +来授予其他人执行相关命令的权限，需要执行的权限一般情况在插件的介绍页都会给明。 + +详见 [`PermissionCommand`](/mirai-console/docs/BuiltInCommands.md#permissioncommand) +。 + +### 指令参数智能解析 + +Console 会自动根据语境推断指令参数的含义。 + +假设一条禁言指令： + +``` +/mute # 为 target 设置 duration 秒的禁言 +``` + +`` 为目标群成员，`` 为禁言时间秒数。 + +若在群内发送消息执行指令 `/mute 123 60`，`123` 将会被首先看作是群员 QQ 号码寻找群员。 +若未找到，则会将 `123` 看作是群员的名片重新寻找。 + +群名片和昵称搜索是模糊匹配的，优先取用不会产生歧义的最相似的匹配。 +例如 `hello` 能匹配 `hella`，匹配率 80%；`hello` 匹配 `hel` 匹配率 60%。由于这两个匹配率都超过 +60%，它们都会成为候选；由于它们之间相差超过 10%，Mirai 会认为这没有歧义，选用 `hella`。 + +在一个群内也可以引用另一个群内的成员，使用 `群号码.群员号码` 格式。若没有 `群号码` 则会使用指令执行人所在的群。 + +在有多个机器人账号登录的情况下，可以使用 `机器人号码.群员号码` 的格式来指定某个机器人的群员。如果只有一个机器人则只需要使用 `群员号码`。 + +在控制台执行指令时，需要提供群号码才能引用到群员。 + +下面将列举智能解析支持的格式列表。 + +#### 好友 + +| 格式 | 示例 | 说明 | +|------------|-----------------|----------------------| +| 机器人号码.好友号码 | `123456.987654` | 一个机器人的一个好友 | +| 好友号码 | `987654` | 当前唯一在线机器人的一个好友 | +| `~` | `~` | 仅聊天环境下，指代指令调用人自己作为好友 | + +#### 群员 + +| 格式 | 示例 | 说明 | +|----------------|------------------------|----------------------| +| 机器人号码.群号码.群员号码 | `123456.123456.987654` | 一个机器人的一个群中的一个群员 | +| 机器人号码.群号码.群员名片 | `123456.123456.Alice` | 一个机器人的一个群中的一个群员 | +| 机器人号码.群号码.$ | `123456.123456.$` | 一个机器人的一个群中的随机群员 | +| 群号码.群员号码 | `123456.987654` | 当前唯一在线机器人的一个群的一个群员 | +| 群号码.群员名片 | `123456.Alice` | 当前唯一在线机器人的一个群的一个群员 | +| 群号码.$ | `123456.$` | 当前唯一在线机器人的一个群的随机群员 | +| 群员号码 | `987654` | 仅聊天环境下，当前群的一个群成员 | +| 群员名片 | `Alice` | 仅聊天环境下，当前群的一个群成员 | +| `$` | `$` | 仅聊天环境下，当前群的随机群成员 | +| `~` | `~` | 仅聊天环境下，指代指令调用人自己作为群员 | + +#### 群 + +| 格式 | 示例 | 说明 | +|-----------|-----------------|----------------------| +| 机器人号码.群号码 | `123456.987654` | 一个机器人的一个群 | +| 群号码 | `987654` | 当前唯一在线机器人的一个群 | +| `~` | `~` | 仅聊天环境下，指代指令调用人自己作为好友 | + +配置 +---- + +Mirai Console 支持一些自定义配置。各项配置可以在 `config` 目录中找到。 + +### 自动登录 + +修改 `AutoLogin.yml` 可配置自动登录。也可以使用 `/autologin` 指令。 + +### 指令前缀 + +可以在 `Command.yml` 配置指令前缀，默认为 `/`。注意，部分指令可不需要前缀也能使用，这取决于插件开发者的选择。 + +### 管理日志 + +Mirai Console 会记录运行时的日志并保存到 `logs` 目录中，其中 `latest.log` 为最新日志。 + +可以参考[日志文档](../mirai-console/docs/Logging.md)了解如何配置日志的详略程度。 + +若要向插件开发者提交问题，建议将日志等级调整为 `ALL` 并复现问题后附加 `latest.log` 一并提交。 + +### 配置权限 + +`grantedPermissionMap.yml` 包含权限授予信息。通常建议使用指令 `/perm` 来修改权限，而不建议直接修改配置。 + +### 远程仓库 + +`repoLoc.yml` 包含对远程仓库的配置，通常不需要修改，除非某个插件要求。 + + + +帮助改善文档 +----- + +如果你认为本文档还需要覆盖一些内容，请在 [issues](https://github.com/mamoe/mirai/issues/new/choose) +提交建议。 \ No newline at end of file diff --git a/docs/UserManual.md b/docs/UserManual.md index f76827ce219..344241a8063 100644 --- a/docs/UserManual.md +++ b/docs/UserManual.md @@ -24,136 +24,7 @@ Mirai 控制台现在有两个版本，插件在这两个版本的 Mirai Console ## 使用纯控制台版本 -### 安装 - -可以使用[脚本](https://mirai.mamoe.net/assets/uploads/files/1618372079496-install-20210412.cmd) -自动安装 32 位带 HTTP 插件的版本，也可以使用安装器个性化安装： - -1. 访问 [iTXTech/mcl-installer](https://github.com/iTXTech/mcl-installer/releases)； -2. 下载适合你的系统的可执行文件； -3. 在一个新文件夹存放这个文件，运行它； -4. 通常可以一路回车使用默认设置完成安装，安装完成后程序自动退出； -5. 运行 `mcl.cmd` 启动，成功后会看到绿色的 `mirai-console started successfully`。 - -### 了解运行环境 - -安装时自动下载了 Mirai Console -启动器（简称 [MCL](https://github.com/iTXTech/mirai-console-loader)）。 - -启动器会帮你准备运行环境，下载和更新 Mirai 核心。你也可以使用启动器下载一些插件（见下文）。 - -第一次运行 `mcl.cmd` 时会初始化运行环境。下表说明了各个文件夹的用途。 - -| 文件夹名称 | 用途 | -|:---------:|:--------------------| -| `scripts` | 存放启动器的脚本，一般不需要在意他们 | -| `plugins` | 存放插件 | -| `data` | 存放插件的数据，一般不需要在意它们 | -| `config` | 存放插件的配置，可以打开并修改配置 | -| `logs` | 存放运行时的日志，日志默认保留 7 天 | - -> 可以在[这里](https://github.com/iTXTech/mirai-console-loader)查看 MCL 详细用法 - -### 下载和安装插件 - -刚刚装好的 Mirai Console 是没有任何功能的。功能将由插件提供。 - -#### 如何安装官方插件 - -Mirai 官方提供两个插件： - -- [chat-command](https://github.com/project-mirai/chat-command): - 允许在聊天环境通过以 "/" 起始的消息执行指令 -- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 - HTTP 支持，允许使用其他编程语言的插件 - -打开命令行 (Windows 系统按住Shift+鼠标右键，点击"在此处打开 PowerShell"), -可以使用 MCL 自动安装这些插件如： - -``` -./mcl --update-package net.mamoe:mirai-api-http --type plugin --channel stable-v2 - -./mcl --update-package net.mamoe:chat-command --type plugin --channel stable -``` - -注意: 插件有多个频道, `--channel stable` 表示使用名为 `stable` 的频道. 不同的插件可能会设置不同的频道, 具体需要使用哪个频道可参考特定插件的说明 (很多插件会单独说明要如何安装它们, 因此不必过多考虑). - -详细文档：[MCL/scripts](https://github.com/iTXTech/mirai-console-loader/blob/master/cli.md) - -#### 在哪找社区插件 - -- Mirai - 官方论坛 [Mirai Forum](https://mirai.mamoe.net/category/11/%E6%8F%92%E4%BB%B6%E5%8F%91%E5%B8%83) - -> *我们还正在建设插件中心，完成后将会简化寻找插件的工作* - -#### 如何安装社区插件 - -如果是 JAR 文件的插件，放入 `plugins` 即可。其他插件一般都有特殊说明如何使用，请参考它们的说明。 - -#### 推荐安装的插件 - -- [chat-command](https://github.com/project-mirai/chat-command): - 不安装此环境不能在聊天环境中执行命令 -- [LuckPerms-Mirai](https://github.com/Karlatemp/LuckPerms-Mirai) (* - 社区*): 易用的高级高效率权限组插件, 适合权限分配模型比较复杂的情况 -- [mirai-api-http](https://github.com/project-mirai/mirai-api-http)：提供 - HTTP 支持，允许使用其他编程语言的插件 - -### 使用控制台指令 - -启动 `mcl.cmd` 就会看到控制台。在控制台可以输入指令，按回车执行这条指令。 - -Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表。 - -一些常用指令介绍在[这里](/mirai-console/docs/BuiltInCommands.md#mirai-console---builtin-commands) -。 - -#### 在群聊中使用命令 (权限授予) - -要允许从 QQ 聊天环境中使用各种命令, 你 **必须** 完成以下的配置 - -1. 安装 [chat-command](https://github.com/project-mirai/chat-command) -2. 完成命令执行权限授予 - -> 关于不同的权限系统, 授予权限的方式, 或者授予权限的命令格式, 可能有所不一样 -> -> 当使用 `非内置权限系统` 时, 具体的权限管理相关命令以相关的权限系统的文档为准 -> > 如 `LuckPerms-Mirai` 的权限管理命令为 `/lp` 而不是 `/permission` - -要完成权限授予, 你必须通过在控制台执行 -[`/permission permit [target] [permission]`](/mirai-console/docs/BuiltInCommands.md#permissioncommand) -来授予其他人执行相关命令的权限, 需要执行的权限一般情况在插件的介绍页都会给明 - -详见 [`PermissionCommand`](/mirai-console/docs/BuiltInCommands.md#permissioncommand) - -### 配置 - -Mirai Console 支持一些自定义配置。各项配置可以在 `config` 目录中找到。 - -### 自动登录 - -修改 `AutoLogin.yml` 可配置自动登录。也可以使用 `/autologin` 指令。 - -### 指令前缀 - -可以在 `Command.yml` 配置指令前缀，默认为 `/`。注意，部分指令可不需要前缀也能使用，这取决于插件开发者的选择。 - -### 管理日志 - -Mirai Console 会记录运行时的日志并保存到 `logs` 目录中，其中 `latest.log` 为最新日志。 - -可以参考[日志文档](../mirai-console/docs/Logging.md)了解如何配置日志的详略程度。 - -若要向插件开发者提交问题，建议将日志等级调整为 `ALL` 并复现问题后附加 `latest.log` 一并提交。 - -### 配置权限 - -`grantedPermissionMap.yml` 包含权限授予信息。通常建议使用指令 `/perm` 来修改权限，而不建议直接修改配置。 - -### 远程仓库 - -`repoLoc.yml` 包含对远程仓库的配置，通常不需要修改，除非某个插件要求。 +查看 [ConsoleTerminal.md](ConsoleTerminal.md)。 ## 解决问题