查看“︁LNNBot/指令”︁的源代码

'''指令'''是 [[LNNBot]] 功能的一类，基于 Koishi.js 框架的指令系统，有共通的语法。可通过发送以斜杠（<code>/</code>）开头的消息来调用指令；在 QQ 私聊和部分群聊内可以省略斜杠前缀。

== 语法 ==

在 Koishi.js 框架中，指令由'''名称'''、若干'''参数'''和若干'''选项'''组成，其间使用空格、换行等空白字符分隔。一般情况下，指令选项可以以任意顺序写在参数前后或之间。

斜杠前缀是通过消息调用指令的一种标志，并不是指令语法的一部分；在部分高级功能中“输入一条指令”时不可包含斜杠前缀。

=== 参数 ===

参数可以是不含空白字符的内容或用引号（<code>""</code>、<code><nowiki>''</nowiki></code>、-{<code>“”</code>、<code>‘’</code>}-）包围的任意内容，如果参数值本身就以引号开头和结尾则需要再加一层引号（可以是相同的引号，如 <code>""content""</code>）。

参数分为'''必填参数'''和'''可选参数'''，在指令用法中分别使用角括号和方括号包围参数名表示，如指令 <code>[[LNNBot/指令/5k|5k]]</code> 有一个必填参数 <code>text1</code> 和一个可选参数 <code>text2</code>，写作 <code>5k <text1> [text2]</code>。

有些指令有'''可变参数'''，即接受任意数量的额外参数，在指令用法中表示为最后一个参数的名称''前''加三点（如<code><...words></code>；区别于下文的''贪婪值''）。

=== 选项 ===

选项的通用语法是''两个''横杠（<code>--</code>）后紧跟'''选项名'''。很多选项是'''具值选项'''，它们后面需要再跟一个'''选项值'''，选项值的语法类似于参数。选项名和选项值之间由空白字符或一个等号（<code>=</code>）相隔，等号之后也可以有空白。等号后不能紧跟使用引号语法的选项值，可以在等号后添加空白或直接用空白代替等号。

大多数选项有单个字符的'''短名'''，可以用''一个''横杠后跟短名的'''短语法'''表示（如 <code>-a</code>）。短语法可以'''串联'''，写成一个横杠后连续跟上多个选项的短名（如 <code>-abc</code> 同时指定了选项 <code>-a -b -c</code>）。串联短语法中除最后一个选项外，其他具值选项（若有）的值为空，最后一个选项可以正常指定值（如 <code>-abc "选项c的值"</code>）。

有些选项有'''符号名'''，可以用一个或几个特殊符号（如 <code>/</code>、<code>--</code>）的'''符号语法'''表示。具值选项使用符号语法时不能使用等号分隔名和值，只能用空白字符分隔。

有些指令使用'''严格选项解析'''，这些指令在解析时若遇到不存在的长、短选项，会将其视为参数，而非报错或忽略。

=== 值类型 ===

每个参数和具值选项都有类型，类型影响该参数或选项值的格式要求和解析逻辑。在指令定义中表示为值名称后跟冒号和类型英文名，在帮助信息中不会显示。

{|class="wikitable mw-collapsible mw-collapsed"
! 类型名称 !! 值格式 !! 说明
|- id="值类型_string"
| <code>string</code> 字符串 || 文本 || 默认类型
|- id="值类型_number"
| <code>number</code> 数字 || 浮点数 ||
|- id="值类型_integer"
| <code>integer</code> 整数 || 整数 ||
|- id="值类型_posint"
| <code>posint</code> 正整数 || 正整数 ||
|- id="值类型_natural"
| <code>natural</code> 自然数 || 非负整数 ||
|- id="值类型_date"
| <code>date</code> 日期 || 日期<br/>或持续时间表示距离现在 || 持续时间单位 w/week(s)、d/day(s)、h/hour(s)、m/min/minute(s)、s/sec/second(s)，从大单位到小单位，不可有任何空格，如：<code>2w2d</code>
|- id="值类型_user"
| <code>user</code> 用户 || @提及人员或字符 <code>@</code> 后加用户 ID || 可在 ID 前加平台 ID 和冒号来选择其他聊天平台的用户账号
|- id="值类型_channel"
| <code>channel</code> 频道 || #频道链接或字符 <code>#</code> 后加频道 ID || 可在 ID 前加平台 ID 和冒号来选择其他聊天平台的频道
|-
| <code id="值类型_image">image</code>/<code id="值类型_audio">audio</code>/<code id="值类型_video">video</code> 图片/音频/视频 || 图片/语音/视频 ||
|- id="值类型_file"
| <code>file</code> 文件 || 发送文件 ||
|- id="值类型_text"
| <code>text</code> 文本 || 文本 || 遇非文本内容如表情、图片，传入 XML 元素代码且解转义一次
|- id="值类型_rawtext"
| <code>rawtext</code> 纯文本 || 纯文本 || 遇非文本内容如表情、图片，直接剔除
|- id="值类型_elements"
| <code>elements</code> 元素 || 任意内容 ||
|- id="值类型_fragment"
| <code>fragment</code> 片段 || 任意内容 || 非 Koishi.js 自带的标准值类型，非贪婪
|}

=== 贪婪值 ===

值类型为 <code>text</code>、<code>rawtext</code> 或 <code>elements</code> 会使指令其余的部分不再解析选项和参数语法，直接全部视为该值的内容（首尾若有引号也会视为值的一部分），称为'''贪婪值'''（使用贪婪值的参数称为'''贪婪参数'''，有贪婪值的选项称为'''贪婪选项'''）。贪婪值必须写在指令的末尾（即使用贪婪参数时其他参数和所有选项必须写在贪婪参数之前，使用贪婪选项时其他选项和所有参数必须写在贪婪选项之前），且贪婪选项和贪婪参数不能同时使用。贪婪值在指令用法中表示为值名称''后''加三点（如 <code><input...></code>；区别于上文的''可变参数''）。

=== 插值 ===

'''插值'''是将一条指令的结果直接作为另一条指令输入的一部分的功能，可以用于指令的参数和选项（包括贪婪值）内，但在直单引号（<code><nowiki>''</nowiki></code>）包围的值中无效。基本的插值语法是 <code>$(指令)</code>（被插值的指令不可包含半角右圆括号，除非在引号内），同时也存在一些其他插值语法，会直接使用对应的指令进行插值：

{|class="wikitable"
! 语法 !! 等价语法 !! 备注
|-
| <code>${代码...}</code> || <code>$([[LNNBot/指令/evaluate|eval]] 代码...)</code> ||
|-
| <code>$¿{代码...}</code> || <code>$([[LNNBot/指令/whatlang|whatlang]] 代码...)</code> ||
|-
| <code>$¿(名称 参数...)</code> || <code>$([[LNNBot/指令/whatcmd|whatcmd]] 名称 参数...)</code> || WhatCommands指令不可包含半角右圆括号，除非在引号内
|}

在一些情况下（如输入 JavaScript 代码时），我们可能不希望指令系统解析插值语法。在 QQ 平台，对于一些会自动剔除掉 QQ 表情的指令（如 <code>[[LNNBot/指令/evaluate|eval]]</code>，它的参数为 <code>rawtext</code> 类型），可以通过在美元符与括号之间添加一个 QQ 表情来“转义”插值语法。也可以通过先发送代码，再引用这条消息调用指令的方法来绕过插值解析。通过在 <code>[[LNNBot/指令/rpipeline|rpipeline]]</code> 指令的快捷方式（如 <code><|</code>）中使用 <code>ECHO</code> 或 <code>:</code> 特殊指令向欲调用的指令传递参数也能绕过插值解析，但需要确保文本内容不含前后都是空白字符的竖线（<code>|</code>）。

== 机制 ==

=== 查询帮助 ===

指令 <code>[[LNNBot/指令/help|help]]</code> 可显示指令菜单或查询特定指令的帮助。

有些指令是'''隐藏指令'''，不会出现在菜单里，但仍能通过 <code>help</code> 查询到其帮助信息。

=== 别名 ===

有些指令有'''别名'''，别名可以用来代替指令名调用指令。

有些别名是'''附带参数和/或选项的别名'''，使用这种别名调用指令时会自动指定指令的第一个或前几个参数，或是给一个或多个选项附带不同的默认值，也可能参数和选项都有。在帮助信息中显示为 <code>''别名''（=''指令名称'' ''参数和/或选项''）</code>。

有些指令在帮助信息中会用默认使用它的一个别名而不是其原本的名称显示，我们称这些指令的'''显示名称'''不同于其'''原本名称'''；相应的原本名称可能会被列举为别名之一，也可能因被禁用而不在帮助信息中显示。在本wiki条目的子页面标题中，我们总是使用指令的原本名称。

=== 别名指令 ===

'''别名指令'''，不同于指令的别名，是指通过 [https://common.koishi.chat/zh-CN/plugins/alias.html alias 插件]创建的一种特殊的指令，它们在调用时会在展开插值语法后，将指令名直接替换为一段预先定义的指令，然后再作为一条指令执行（会再次展开插值语法，再解析参数和选项的语法）。别名指令不会显示在其实际调用的指令的帮助信息中，对别名指令查询帮助会显示其实际指令段。别名指令一般都是隐藏指令。

=== 特殊调用方式 ===

在 QQ 私聊和部分群聊调用指令时可以省略斜杠，直接发送指令内容；在 Discord 平台，因为斜杠有时是一种特殊语法，所以也允许以两个斜杠开头。

部分指令也能用其他独特的语法来调用，称为'''快捷方式'''，如 <code>[[LNNBot/指令/evaluate|eval]]</code> 指令可以通过发送大于号和空格开头的消息来调用。

=== 捕获引用 ===

当调用指令的消息引用（回复）了另一条消息，大多数指令都会将被引用的消息内容自动添加到指令末尾作为参数或选项值。通过这种方式传入的输入不会解析选项、参数和插值语法，直接作为一个值使用。若指令使用了贪婪参数或选项，则会将被引用内容直接添加到贪婪值的末尾。

=== 请求输入参数 ===

有些指令在缺少必填参数时，会显示“请发送''(参数描述)''…”（区别于报错“缺少''某参数''…”），调用指令的用户若在 1 分钟内在同一聊天内发送了消息，bot 会将该消息的内容作为缺少的参数使用。目前无法在 bot 请求输入参数时手动取消调用，需要等待 1 分钟或通过发送一条任意内容来完成调用，否则直接重新进行指令调用不会被 bot 正常识别。

=== 子指令 ===

有些指令是另一个指令的'''子指令'''。子指令不会在顶层帮助菜单中显示，只会在其父指令的帮助信息内显示。子指令分为'''层级式'''和'''派生式'''两种，派生式子指令的名称总是以其父指令的名称加句点（<code>.</code>）开头。

有些指令本身并没有功能，仅用于收纳其他指令作为子指令，称为'''分组指令'''。调用分组指令的派生式子指令时可以用空格代替指令名中的句点；而如果直接调用分组指令本身，或将空格替换为句点后并不是一个存在的派生式子指令名称，则会直接显示分组指令的帮助信息。

=== 禁用指令 ===

指令可以被 bot 管理员在特定群聊中禁用。此时，该指令及其子指令都无法在该群聊中被调用。有些指令是'''群聊中默认禁用'''的，需要 bot 管理员手动为特定群聊启用才可调用。

== 指令列表 ==

指令文档索引尚未建成，您可以浏览下列已编写的指令条目：

{{Special:PrefixIndex/LNNBot/指令/|stripprefix=1}}

; 快捷方式索引

{{LNNBot指令链接|rpipeline|<&vert;}} · {{LNNBot指令链接|evaluate|>}} · {{LNNBot指令链接|rpipeline|&vert;}} · {{LNNBot指令链接|sletscript|§>}} · {{LNNBot指令链接|sletpreset|§§}} · {{LNNBot指令链接|whatlang|¿}} · {{LNNBot指令链接|whatcmd|¿¿}} · {{LNNBot指令链接|uiua|∪}} · {{LNNBot指令链接|thursday|疯狂星期四}}