mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-07-26 15:51:26 +00:00
完善文档、清理垃圾、添加 Travis CI 配置文件
This commit is contained in:
Richard Chien
@ -1,6 +1,6 @@
|
||||
# 编写命令
|
||||
|
||||
当你需要自己编写命令时，可能需要了解或参考以下内容。
|
||||
`commands` 目录中所有不以 `_` 开头的 `.py` 文件会被加载进程序，一般把命令放在这个目录里。对于临时不需要的命令，可以通过在文件名前加 `_` 来屏蔽掉。要自行编写命令，需要涉及到的概念比较多，请参考下面内容，或参考已内置的命令的写法。
|
||||
|
||||
## 命令仓库 Command Registry
|
||||
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
# 编写过滤器
|
||||
|
||||
`filters` 目录中所有不以 `_` 开头的 `.py` 文件会被加载进程序，一般把过滤器放在这个目录里。对于临时不需要的过滤器，可以通过在文件名前加 `_` 来屏蔽掉。
|
||||
|
||||
## 写法
|
||||
|
||||
编写过滤器比较简单，只需要调用 `filter.py` 中的 `add_filter` 函数，传入过滤器函数和优先级，即可。
|
||||
编写过滤器比较简单，只需要调用 `filter.py` 中的 `add_filter` 函数或 `as_filter` 装饰器，传入过滤器函数和优先级，即可。
|
||||
|
||||
比如我们需要做一个消息拦截器，当匹配到消息中有不文明词汇，就发送一条警告，并拦截消息不让后续过滤器和命令处理，代码可能如下：
|
||||
|
||||
```python
|
||||
from filter import add_filter
|
||||
from filter import add_filter, as_filter
|
||||
from commands import core
|
||||
|
||||
|
||||
@ -17,8 +19,16 @@ def _interceptor(ctx_msg):
|
||||
return False
|
||||
return True
|
||||
|
||||
add_filter(_interceptor, priority=100)
|
||||
|
||||
add_filter(_interceptor, 100)
|
||||
# 或下面这样
|
||||
|
||||
@as_filter(priority=100)
|
||||
def _interceptor(ctx_msg):
|
||||
if 'xxx' in ctx_msg.get('content', ''):
|
||||
core.echo('请不要说脏话', ctx_msg)
|
||||
return False
|
||||
return True
|
||||
```
|
||||
|
||||
一般建议优先级设置为 0～100 之间。
|
||||
@ -27,14 +37,11 @@ add_filter(_interceptor, 100)
|
||||
|
||||
## 现有的几个重要过滤器
|
||||
|
||||
### 消息日志过滤器
|
||||
|
||||
此过滤器用于把收到的消息打印在标准输出，在 `filters/message_logger_1000.py` 中定义，优先级 1000，一般不建议添加其它优先级比它高的过滤器，以确保日志不受任何干扰。
|
||||
|
||||
### 分离@开头过滤器
|
||||
|
||||
用于分离群组和讨论组中消息开头的 `@CCZU 小开`，优先级 50，在 `filters/split_at_xiaokai_50.py` 中定义。通过此过滤器的消息的 `content` 字段会被更新为分离掉开头的剩余部分，也就是说通过此过滤器的消息，就是确定用户的意图就是和这个 bot 说话的消息。
|
||||
|
||||
### 命令分发过滤器
|
||||
|
||||
用于处理消息中的命令，优先级 0，在 `filters/command_dispatcher_0.py` 中定义。
|
||||
| 文件 | 优先级 | 作用 | 备注 |
|
||||
| ------------------------------------- | ----- | ---------------------------------------- | -------------------------------------- |
|
||||
| unitize_context_message_10000.py | 10000 | 对来自不同平台（QQ、微信）的消息上下文进行统一化，以避免耦合 | 不建议添加比它优先级更高的过滤器 |
|
||||
| message_logger_1000.py | 1000 | 把收到的消息打印在标准输出 | 不建议添加比它优先级更高的过滤器 |
|
||||
| intercept_some_message_formats_100.py | 100 | 拦截某些不支持的消息类型，对于文本消息，会把 `content` 字段复制到 `text` 字段 | 如果要自己编写插件，这里可以按需修改 |
|
||||
| speech_recognition_90.py | 90 | 对语音消息进行语音识别（仅私聊消息），并把识别出的文字放到 `text` 字段，并标记 `from_voice` 字段为 True | 如果不需要可以删掉 |
|
||||
| split_at_xiaokai_50.py | 50 | 分离群组和讨论组中消息开头的 `@CCZU 小开`，并更新 `text` 字段为剩余部分 | 也就是说通过此过滤器的消息，就是确定用户的意图就是和这个 bot 说话的消息 |
|
||||
| command_dispatcher_0.py | 0 | 识别消息中的命令，并进行相应的调用 | |
|
||||
24
docs/Write_NLProcessor.md
Normal file
24
docs/Write_NLProcessor.md
Normal file
@ -0,0 +1,24 @@
|
||||
# 编写自然语言处理器
|
||||
|
||||
`nl_processors` 目录中所有不以 `_` 开头的 `.py` 文件会被加载进程序，一般把自然语言处理器（后面称 NL 处理器）放在这个目录里。对于临时不需要的 NL 处理器，可以通过在文件名前加 `_` 来屏蔽掉。
|
||||
|
||||
## 流程
|
||||
|
||||
程序执行时 `natural_language.process` 命令会调用 `nl_processor.py` 中的 `parse_potential_commands` 函数来解析可能的等价命令，此函数会对消息文本进行分词，然后进行关键词匹配（关键词在注册 NL 处理器是传入），并调用所有匹配到的 NL 处理器，每个 NL 处理器会返回 None 或一个四元组（从 0 到 3 分别是：置信度（0~100）、命令名、参数、已解析到的数据）。
|
||||
|
||||
完成后，`parse_potential_commands` 把所有非 None 的结果放在一个 list 返回给 `natural_language.process` 命令，该命令再从中选择置信度最高，且超过 60 的命令执行（在调用之前会把已解析到的数据放在消息上下文的 `parsed_data` 字段）。如果没有置信度超过 60 的命令，则调用 `config.py` 中 `fallback_command_after_nl_processors` 字段指定的命令。
|
||||
|
||||
## 写法
|
||||
|
||||
由以上流程可知，在编写 NL 处理器时需要注册关键词，然后返回一个包含可能的等价命令和置信度的四元组。例子如下：
|
||||
|
||||
```python
|
||||
from nl_processor import as_processor
|
||||
|
||||
|
||||
@as_processor(keywords=('翻译(为|成|到)?', '.+(文|语)'))
|
||||
def _processor(sentence, segmentation):
|
||||
return 90, 'translate.translate_to', '', None
|
||||
```
|
||||
|
||||
注意关键词需要传入一个可迭代对象，每个元素为一个正则表达式字符串；函数接收的参数有且只有两个必填项，第一个为原文本字符串，第二个为使用 jieba 分词之后的分词列表，每个元素都包含 `flag` 和 `word` 两个属性（是对象的属性，不是字典的键），分别是词性标记（jieba 分词的词性标记见 [ICTCLAS 汉语词性标注集](https://gist.github.com/luw2007/6016931#ictclas-汉语词性标注集)）和词语的字符串。
|
||||
@ -1,25 +1,28 @@
|
||||
self.$config = {
|
||||
title: 'XiaoKai Bot 文档',
|
||||
home: 'https://raw.githubusercontent.com/CCZU-DEV/xiaokai-bot/master/README.md',
|
||||
repo: 'CCZU-DEV/xiaokai-bot',
|
||||
url: 'https://cczu-dev.github.io/xiaokai-bot',
|
||||
nav: {
|
||||
default: [
|
||||
{
|
||||
title: '首页', path: '/'
|
||||
},
|
||||
{
|
||||
title: '编写插件', type: 'dropdown',
|
||||
items: [
|
||||
{
|
||||
title: '过滤器', path: '/Write_Filter'
|
||||
},
|
||||
{
|
||||
title: '命令', path: '/Write_Command'
|
||||
}
|
||||
title: 'XiaoKai Bot 文档',
|
||||
home: 'https://raw.githubusercontent.com/CCZU-DEV/xiaokai-bot/master/README.md',
|
||||
repo: 'CCZU-DEV/xiaokai-bot',
|
||||
url: 'https://cczu-dev.github.io/xiaokai-bot',
|
||||
nav: {
|
||||
default: [
|
||||
{
|
||||
title: '首页', path: '/'
|
||||
},
|
||||
{
|
||||
title: '编写插件', type: 'dropdown',
|
||||
items: [
|
||||
{
|
||||
title: '过滤器', path: '/Write_Filter'
|
||||
},
|
||||
{
|
||||
title: '命令', path: '/Write_Command'
|
||||
},
|
||||
{
|
||||
title: '自然语言处理器', path: '/Write_NLProcessor'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
plugins: []
|
||||
},
|
||||
plugins: []
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user