7.6 KiB
编写命令
当你需要自己编写命令时，可能需要了解或参考以下内容。
命令仓库 Command Registry
每个 .py 文件，就是一个命令仓库，里面可以注册多个命令，每个命令也可以注册多个命令名。
程序启动时，会自动加载 commands 目录下的所有 .py 文件（模块）中的 __registry__ 对象，这是一个 CommandRegistry 类型的对象，在创建这个对象的时候，可以指定一个 init_func 参数作为初始化函数，将会在命令仓库被加载时调用。
使用 __registry__ 对象的 register 装饰器可用来将一个函数注册为一个命令，装饰器的一个必填参数为命令名，可选参数 hidden 表示是否将命令名暴露为可直接调用（即形如 /command_name 这样调用），如果此项设为 True 则只能在命令名前加仓库名调用。
同一个函数可以注册多次不同命令名（相当于别名），以适应不同的语境。
CommandRegistry 类的 restrict 装饰器用于限制命令的调用权限，这个装饰器必须在注册命令到仓库之前调用，表现在代码上就是 restrict 装饰器必须在所有 register 装饰器下方。关于此装饰器的参数基本上从参数名就能看出含义，具体见 command.py 中的代码。
有一点需要注意的是，full_command_only 参数和 register 装饰器的 hidden 参数表现出的特性相同（都是防止直接访问），但不同之处在于它对整个命令有效，无论命令被以不同命令名注册过多少次。这导致 restrict 的 full_command_only 参数和 register 的 hidden 参数的建议使用场景有所不同，比如，当需要添加一个可以确定不希望普通用户意外调用到的命令时，可使用如下方式注册：
@__registry__.register('pro_command')
@__registry__.restrict(full_command_only=True, allow_group=False)
def pro_command(args_text, ctx_msg):
pass
而如果需要添加一个希望普通用户使用、同时也让高级用户使用起来更舒适的命令，可能用如下方式注册：
@__registry__.register('list_all', hidden=True)
@__registry__.register('列出所有笔记')
@__registry__.restrict(group_admin_only=True)
def list_all(args_text, ctx_msg):
pass
这样可以在保持高级用户可以通过简洁的方式调用命令的同时，避免不同命令仓库下同名命令都被调用的问题（因为在默认情况下命令中心在调用命令时，不同仓库中的同名命令都会被依次调用）。
命令中心 Command Hub
程序启动时加载的命令仓库全部被集中在了命令中心，以 .py 文件名（除去后缀）（也即模块名）为仓库名。命令中心实际上应作为单例使用（插件编写者不应当自己创建实例），即 command.py 中的 hub 对象，类型是 CommandHub，调用它的 call 方法将会执行相应的命令，如果调用失败（如命令不存在、没有权限等）会抛出相应的异常。
命令之间内部调用
调用命令中心的 call 方法是一种可行的命令内部调用方法，不过由于 call 方法内会进行很多额外操作（例如命令名匹配、权限检查等），所以并不建议使用这个方法来进行内部调用。
一般而言，当编写命令时发现需要调用另一个已有的命令，可以直接导入相应的模块，然后调用那个命令函数，这样避免了冗杂的命令名匹配过程，例如：
from commands import core
@__registry__.register('cmd_need_call_another')
def cmd_need_call_another(args_text, ctx_msg):
core.echo(args_text, ctx_msg)
这里直接调用了 core.echo。
数据持久化
可以使用数据库或文件来对数据进行持久化，理论上只要自行实现数据库和文件的操作即可，这里为了方便起见，在 little_shit.py 提供了获取默认数据库路径、默认临时文件路径等若干函数。
使用默认的路径，可以保持文件结构相对比较清晰。
Source 和 Target
对于用户发送的消息，我们需要用某种标志来区分来源，对于用户保存的数据，也要区分这份数据属于谁。在私聊消息的情况下，这个很容易理解，不同的 QQ 号就是不同的来源，然而在群消息的情况下，会产生一点区别，因此这里引入 Source 和 Target 两个概念。
Source 表示命令的来源（由谁发出），Target 表示命令将对谁产生效果。
在私聊消息中，这两者没有区别。在群聊中，每个用户（如果限制了权限，则可能只有管理员或群主，但这不影响理解）都可以给 bot 发送命令，但命令在后台保存的数据，应当是属于整个群组的，而不是发送命令的这个用户。与此同时，不同的用户在群聊中发送命令时，命令应当能区分他们，并在需要交互时正确地区分不同用户的会话（关于会话的概念，在下一个标题下）。
以 commands/note.py 中的命令为例，多个管理员可以同时开启会话来添加笔记，最终，这些笔记都会存入群组的数据中，因此这些命令通过 Source 来区分会话，用 Target 来在数据库中区分数据的归属。这也是建议的用法。
至于如何获取 Source 和 Target，可用 little_shit.py 中的 get_source 和 get_target 函数，当然，如果你对默认的行为感到不满意，也可以自己去实现不一样的区分方法。
交互式命令 Interactive Command
通常我们会希望一条命令直接在一条消息中发出然后直接执行就好，但这在某些情况下对普通用户并不友好，因此这里支持了交互式命令，也就是在一条命令调用之后，进行多次后续互动，来引导用户完成数据的输入。
为了实现交互式命令，引入了「会话 Session」概念。
我们以 commands/note.py 里的 note.take 命令为例，如果发送命令 /记笔记（此为一个别名，和 /note.take 等价），且不加参数，那么 note.take 命令就认为需要开启交互式会话来引导用户输入需要记录的内容，调用 interactive.py 中的 get_session 函数，由于原先不存在该 Source 的会话，且传入了 cmd 参数，就会新创建一个会话，并注册在 interactive.py 中的 _sessions 字典（这是一个 TTL 字典，目前写死了有效时间 5 分钟，如果需要实现其它有效时间的会话，请先自行实现）。在这个获取的会话对象中，可以保存当前会话的状态和数据。
注意这里的会话对象，是每个 Source 对应一个。一旦创建了一个会话对象，该 Source 原来可能对应的会话就会被关闭。
另外，主程序 app.py 中处理接收到的消息时，面临两种消息，一种是命令，一种是不带命令的普通消息，对这两种消息，分别作如下处理：
- 如果是命令，那么不管前面是不是在会话中，都会清除原来的会话，然后启动新的命令（至于新的命令会不会开启新的会话，并没有影响）；
- 如果是普通消息，那么如果当前 Source 在某个会话中，就会讲消息内容作为参数，调用该会话的命令，如果没有在会话中，则调用 fallback 命令（一般让图灵机器人去处理）。
除了获取会话对象，还需要在命令中自己实现一个状态机，根据会话对象中保存的状态来判断当前这个 Source 处在交互式命令的哪一个阶段。
总体来说交互式命令相比普通命令写起来更复杂一点，具体写法可以参考 commands/note.py。