diff --git a/docs/glossary.md b/docs/glossary.md index 9cba6248..8b3ca7c1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -10,7 +10,7 @@ sidebar: auto ## CoolQ HTTP API 插件 -[CoolQ HTTP API 插件](https://github.com/richardchien/coolq-http-api) 是酷 Q 的一个第三方插件,用于将酷 Q 所提供的所有 DLL 接口转换为 HTTP 或 WebSocket 的 web 形式,从而使利用任意语言编写酷 Q 插件成为可能。 +[CoolQ HTTP API 插件](https://cqhttp.cc/) 是酷 Q 的一个第三方插件,用于将酷 Q 所提供的所有 DLL 接口转换为 HTTP 或 WebSocket 的 web 形式,从而使利用任意语言编写酷 Q 插件成为可能。 有时被称为 cqhttp、CQHttp、酷 Q HTTP API 等。 @@ -98,6 +98,14 @@ async def _(session): ## 上下文(Context) +通常通过 `session.ctx` 访问,是 CoolQ HTTP API 插件发送给 NoneBot 的原始事件数据,包含当前事件的来源信息、内容等,具体请参考 CoolQ HTTP API 插件文档的 [事件上报](https://cqhttp.cc/docs/#/Post). + ## 表达(Expression) +是 NoneBot 支持的一种消息渲染的机制,可以通过随机选择或函数生成+字符串格式化的方式根据参数生成出自然的、不固定的消息回复,提升用户体验。 + +Expression 可以是一个 `str`、元素类型是 `str` 的序列(一般为 `list` 或 `tuple`)或返回类型为 `str` 的 `Callable`。 + ## CQ 码 + +是酷 Q 用来表示非文本消息的一种表示方法,形如 `[CQ:image,file=ABC.jpg]`。具体的格式规则,请参考酷 Q 文档的 [CQ 码](https://d.cqp.me/Pro/CQ%E7%A0%81) 和 CoolQ HTTP API 插件文档的 [CQ 码](https://cqhttp.cc/docs/#/CQCode)。 diff --git a/docs/guide/code/awesome-bot-3/config.py b/docs/guide/code/awesome-bot-3/config.py index ccce361f..733613d5 100644 --- a/docs/guide/code/awesome-bot-3/config.py +++ b/docs/guide/code/awesome-bot-3/config.py @@ -5,3 +5,4 @@ PORT = 8080 SUPERUSERS = {12345678} COMMAND_START.add('') +NICKNAME = {'小明', '明明'} diff --git a/docs/guide/code/awesome-bot-4/config.py b/docs/guide/code/awesome-bot-4/config.py index 0066175d..262e4ccd 100644 --- a/docs/guide/code/awesome-bot-4/config.py +++ b/docs/guide/code/awesome-bot-4/config.py @@ -5,5 +5,6 @@ PORT = 8080 SUPERUSERS = {12345678} COMMAND_START.add('') +NICKNAME = {'小明', '明明'} TULING_API_KEY = '' diff --git a/docs/guide/tuling.md b/docs/guide/tuling.md index 087668d6..57f119e0 100644 --- a/docs/guide/tuling.md +++ b/docs/guide/tuling.md @@ -205,7 +205,17 @@ async def call_tuling_api(session: CommandSession, text: str) -> Optional[str]: 命令处理器这部分虽然代码比较少,但引入了不少新的概念。 -```python +```python {1,3-8,13,16,18} +from aiocqhttp.message import escape + +EXPR_DONT_UNDERSTAND = ( + '我现在还不太明白你在说什么呢,但没关系,以后的我会变得更强呢!', + '我有点看不懂你的意思呀,可以跟我聊些简单的话题嘛', + '其实我不太明白你的意思……', + '抱歉哦,我现在的能力还不能够明白你在说什么,但我会加油的~' +) + + @on_command('tuling') async def tuling(session: CommandSession): message = session.get_optional('message') @@ -216,4 +226,22 @@ async def tuling(session: CommandSession): await session.send_expr(EXPR_DONT_UNDERSTAND) ``` -未完待续…… +### 可选参数 + +首先看第 13 行,`session.get_optional()` 可用于获取命令的可选参数,也就是说,从 `session.args` 中尝试获取一个参数,如果没有,返回 `None`,但并不会中断命令的执行,比较类似于 `dict.get()` 方法。 + +### 消息转义 + +再看第 16 行,在调用 `session.send()` 之前先对 `reply` 调用了 `escape()`,这个 `escape()` 函数是 `aiocqhttp.message` 模块提供的,用于将字符串中的某些特殊字符进行转义。具体来说,这些特殊字符是酷 Q 看作是 CQ 码的一部分的那些字符,包括 `&`、`[`、`]`、`,`。 + +CQ 码是酷 Q 用来表示非文本消息的一种表示方法,形如 `[CQ:image,file=ABC.jpg]`。具体的格式规则,请参考酷 Q 文档的 [CQ 码](https://d.cqp.me/Pro/CQ%E7%A0%81) 和 CoolQ HTTP API 插件文档的 [CQ 码](https://cqhttp.cc/docs/#/CQCode)。 + +### 发送 Expression + +第 18 行使用了 NoneBot 中 Expression 这个概念,或称为「表达」。 + +Expression 可以是一个 `str`、元素类型是 `str` 的序列(一般为 `list` 或 `tuple`)或返回类型为 `str` 的 `Callable`。`session.send_expr()` 内部会调用 `none.expression.render()` 函数来将 Expression 渲染成字符串。 + +`render()` 首先判断 Expression 的类型,如果 Expression 是一个序列,则首先随机取其中的一个元素,如果是一个 `Callable`,则调用函数获取返回值。拿到最终的 `str` 类型的 Expression 之后,对它调用 `str.format()` 方法,格式化参数传入 `render()` 函数的命名参数(`**kwargs`),也即 `session.send_expr()` 的命名参数,最后返回格式化后的结果。特别地,如果 Expression 是个 `Callable`,在调用它获取返回值的时候,也会传入 `**kwargs`,以便函数根据参数来构造字符串。 + +你可以通过使用序列或 `Callable` 类型的 Expression 来让机器人的回复显得更加自然,甚至,可以利用更高级的人工智能技术来生成对话。 diff --git a/docs/guide/writing-nl-processors.md b/docs/guide/writing-nl-processors.md index 8a7ae08a..dd1c3a02 100644 --- a/docs/guide/writing-nl-processors.md +++ b/docs/guide/writing-nl-processors.md @@ -199,6 +199,22 @@ async def _(session: NLPSession): 如果一切顺利,第一句它会问你要查询哪个城市,第二句会直接识别到城市。 +## 优化群聊中的使用体验 + +到目前为止我们都只关注了私聊的情况,实际上我们的天气插件在群聊中也可以正常工作,但是有一个问题,我们必须@机器人,它才会回复。一种解决办法是,给 `on_natural_language` 装饰器添加参数 `only_to_me=False`,这样的话,机器人将会响应所有群聊中含有 `天气` 关键词的消息,这对于某些功能的插件来说可能比较适用。另一种办法是通过配置项 `NICKNAME` 设置机器人的昵称,例如: + +```python +NICKNAME = {'小明', '明明'} +``` + +`NICKNAME` 的值需要是一个 `Iterable`。设置了昵称之后,我们可以通过昵称来唤起机器人,例如: + +``` +小明,今天天气怎么样? +``` + +此处 `小明` 和@的效果相同。 + ## 更精确的自然语言理解 如果你是一位自然语言处理领域的爱好者或从业人员,你可以在 NoneBot 中很方便地将你的理论研究应用到实例中,在自然语言处理器中使用更高级的 NLP 技术,并且,可以通过增加命令的参数,将自然语言的理解更加细化,以向用户提供更加顺畅的使用体验。