From 1c9136d672546e4297d1f3703cd99401659fad36 Mon Sep 17 00:00:00 2001 From: Richard Chien Date: Mon, 16 Mar 2020 21:10:26 +0800 Subject: [PATCH] fix format --- docs/advanced/server-app.md | 2 +- docs/guide/README.md | 4 ++-- docs/guide/basic-configuration.md | 2 +- docs/guide/command.md | 10 +++++----- docs/guide/cqhttp.md | 2 +- docs/guide/getting-started.md | 8 ++++---- docs/guide/installation.md | 6 +++--- docs/guide/nl-processor.md | 10 +++++----- docs/guide/notice-and-request.md | 4 ++-- docs/guide/scheduler.md | 2 +- docs/guide/tuling.md | 6 +++--- docs/guide/usage.md | 2 +- docs/guide/whats-happened.md | 6 +++--- 13 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/advanced/server-app.md b/docs/advanced/server-app.md index 07a8e4c9..541a1e1e 100644 --- a/docs/advanced/server-app.md +++ b/docs/advanced/server-app.md @@ -2,7 +2,7 @@ 如果需要对 web 框架进行更详细的控制，可以通过 `bot.server_app` 访问到内部的 Quart 对象，之后可以像使用 Quart 的 app 对象一样添加路由、设置生命周期处理函数等。 -::: tip 提示 +:::tip 提示 Quart 是一个与 Flask 具有相同 API 的异步 web 框架，其用法可以参考 [官方文档](https://pgjones.gitlab.io/quart/)。 ::: diff --git a/docs/guide/README.md b/docs/guide/README.md index b8359717..2237569e 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,10 +1,10 @@ # 概览 -::: tip 提示 +:::tip 提示 如果在阅读本文档时遇到难以理解的词汇，请随时查阅 [术语表](../glossary.md) 或使用 [Google 搜索](https://www.google.com/ncr)。 ::: -::: tip 提示 +:::tip 提示 初次使用时可能会觉得这里的概览过于枯燥，可以先简单略读之后直接前往 [安装](./installation.md) 查看安装方法，并进行后续的基础使用教程。 ::: diff --git a/docs/guide/basic-configuration.md b/docs/guide/basic-configuration.md index b5bebd8b..36012a7f 100644 --- a/docs/guide/basic-configuration.md +++ b/docs/guide/basic-configuration.md @@ -2,7 +2,7 @@ 到目前为止我们还在使用 NoneBot 的默认行为，在开始编写自己的插件之前，我们先尝试在配置文件上动动手脚，让 NoneBot 表现出不同的行为。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-1](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-1) 查看。 ::: diff --git a/docs/guide/command.md b/docs/guide/command.md index 9c39da72..50783d4a 100644 --- a/docs/guide/command.md +++ b/docs/guide/command.md @@ -2,7 +2,7 @@ 本章将以一个天气查询插件为例，教你如何编写自己的命令。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-2](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-2) 查看。 ::: @@ -59,7 +59,7 @@ if __name__ == '__main__': 这表示 NoneBot 已经成功加载到了 `weather` 插件。 -::: warning 注意 +:::warning 注意 如果你运行时没有输出成功导入插件的日志，请确保你的当前工作目录是在 `awesome-bot` 项目的主目录中。 如果仍然不行，尝试先在 `awesome-bot` 主目录中执行下面的命令： @@ -120,7 +120,7 @@ async def get_weather_of_city(city: str) -> str: return f'{city}的天气是……' ``` -::: tip 提示 +:::tip 提示 从这里开始，你需要对 Python 的 asyncio 编程有所了解，因为 NoneBot 是完全基于 asyncio 的，具体可以参考 [廖雪峰的 Python 教程](https://www.liaoxuefeng.com/wiki/0014316089557264a6b348958f449949df42a6d3a2e542c000/00143208573480558080fa77514407cb23834c78c6c7309000)。 ::: @@ -149,7 +149,7 @@ async def weather(session: CommandSession): 你可能想问了，既然是重新执行，那执行到 `session.get()` 的时候不还是会中断吗？实际上，NoneBot 在 1.0.0 及更早版本中确实是这样的，必须手动编写下面要说的参数解析器，才能够让 `session.get()` 正确返回；而从 1.1.0 版本开始，NoneBot 会默认地把用户的完整输入作为当前询问内容的回答放进会话状态。 -::: tip 提示 +:::tip 提示 删掉下面这段参数解析器，天气命令也可以正常使用，可以尝试不同的输入，看看行为上有什么不同。 ::: @@ -186,7 +186,7 @@ async def _(session: CommandSession): 如果不是第一次运行，那就说明命令处理函数中向用户询问了更多信息，导致会话被中断，并等待用户回复（也就是 `session.get()` 的效果）。这时候需要判断用户输入是不是有效，因为我们已经明确地询问了，如果用户此时发送了空白字符，显然这是没有意义的内容，需要提示用户重新发送。相反，如果有效的话，则直接以 `session.current_key` 作为 key（也就是 `session.get()` 的第一个参数，上例中只有可能是 `city`），将输入内容存入会话状态。 -::: tip 提示 +:::tip 提示 上面用了 `session.current_arg_text` 来获取用户当前输入的参数，这表示从用户输入中提取纯文本部分，也就是说不包含图片、表情、语音、卡片分享等。 如果需要用户输入的原始内容，请使用 `session.current_arg`，里面可能包含 CQ 码。除此之外，还可以通过 `session.current_arg_images` 获取消息中的图片 URL 列表。 diff --git a/docs/guide/cqhttp.md b/docs/guide/cqhttp.md index 3220501a..e427ef20 100644 --- a/docs/guide/cqhttp.md +++ b/docs/guide/cqhttp.md @@ -12,7 +12,7 @@ 幸运的是，`NoneBot` 类是继承自 aiocqhttp 的 [`CQHttp` 类](https://python-aiocqhttp.cqp.moe/module/aiocqhttp/#aiocqhttp.CQHttp) 的，而这个类实现了 `__getattr__()` 魔术方法，由此提供了直接通过 bot 对象调用 CQHTTP 的 API 的能力。 -::: tip 提示 +:::tip 提示 如果你在使用 HTTP 通信，要调用 CQHTTP API 要在 `config.py` 中添加： ```python diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 5baee1c6..28b9419c 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -21,7 +21,7 @@ if __name__ == '__main__': 2. 加载 NoneBot 内置的插件 3. 在地址 `127.0.0.1:8080` 运行 NoneBot -::: tip 提示 +:::tip 提示 这里 `nonebot.run()` 的参数 `host='127.0.0.1'` 表示让 NoneBot 监听本地环回地址，如果你的 酷Q 运行在非本机的其它位置，例如 Docker 容器内、局域网内的另一台机器上等，则这里需要修改 `host` 参数为希望让 CQHTTP 插件访问的 IP。如果不清楚该使用哪个 IP，或者希望本机的所有 IP 都被监听，可以使用 `0.0.0.0`。 ::: @@ -48,7 +48,7 @@ Running on http://127.0.0.1:8080 (CTRL + C to quit) 如果你在之前已经按照 [安装](/guide/installation.md) 的建议使用默认配置运行了一次 CQHTTP 插件，此时 酷Q 的 `data/app/io.github.richardchien.coolqhttpapi/config/` 目录中应该已经有了一个名为 `.json` 的文件（`` 为你登录的 QQ 账号）。修改这个文件，**修改如下配置项（如果不存在相应字段则添加）**： -::: warning 注意 +:::warning 注意 如果使用 CQHTTP 插件官方 Docker 镜像运行 酷Q，则配置文件所在目录可能是 `app/io.github.richardchien.coolqhttpapi/config/`。 ::: @@ -60,7 +60,7 @@ Running on http://127.0.0.1:8080 (CTRL + C to quit) } ``` -::: tip 提示 +:::tip 提示 **这里的 `127.0.0.1:8080` 对应 `nonebot.run()` 中传入的 `host` 和 `port`**，如果在 `nonebot.run()` 中传入的 `host` 是 `0.0.0.0`，则插件的配置中需使用任意一个能够访问到 NoneBot 所在环境的 IP，**不要直接填 `0.0.0.0`**。特别地，如果你的 酷Q 运行在 Docker 容器中，NoneBot 运行在宿主机中，则默认情况下这里需使用 `172.17.0.1`（即宿主机在 Docker 默认网桥上的 IP，不同机器有可能不同，如果是 macOS 系统或者 Windows 系统，可以考虑使用 `host.docker.internal`，具体解释详见 Docker 文档的 [Use cases and workarounds](https://docs.docker.com/docker-for-mac/networking/#use-cases-and-workarounds) 的「I WANT TO CONNECT FROM A CONTAINER TO A SERVICE ON THE HOST」小标题）。 ::: @@ -79,7 +79,7 @@ Running on http://127.0.0.1:8080 (CTRL + C to quit) 这表示 CQHTTP 插件已经成功地连接上了 NoneBot，与此同时，CQHTTP 的日志控制台（和日志文件）中也会输出反向 WebSocket 连接成功的日志。 -::: warning 注意 +:::warning 注意 如果到这一步你没有看到上面这样的成功日志，CQHTTP 的日志中在不断地重连或无反应，请注意检查配置中的 IP 和端口是否确实可以访问。比较常见的出错点包括： - NoneBot 监听 `0.0.0.0`，然后在 CQHTTP 配置中填了 `ws://0.0.0.0:8080/ws/` diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 20197b20..8f9f9ded 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -2,7 +2,7 @@ ## NoneBot -::: warning 注意 +:::warning 注意 请确保你的 Python 版本 >= 3.7。 ::: @@ -28,7 +28,7 @@ python setup.py install 如果你的操作系统是 Linux 或 macOS，可以使用版本发布页中 酷Q 官方提供的 Docker 镜像，也可以直接跳至下一个标题，使用 CQHTTP 插件官方提供的 Docker 镜像。 -::: tip 提示 +:::tip 提示 如果这是你第一次使用 酷Q，建议完成它自带的新手教程，以对 酷Q 的运行机制有所了解。 ::: @@ -36,6 +36,6 @@ python setup.py install 前往 [CQHTTP 插件文档](https://cqhttp.cc/docs/)，按照其教程的「使用方法」安装插件。安装后，请先使用默认配置运行，并查看 酷Q 日志窗口的输出，以确定插件的加载、配置的生成和读取、插件版本等符合预期。 -::: warning 注意 +:::warning 注意 请确保你安装的插件版本 >= 4.8，通常建议插件在大版本内尽量及时升级至最新版本。 ::: diff --git a/docs/guide/nl-processor.md b/docs/guide/nl-processor.md index f0ef7067..5c902248 100644 --- a/docs/guide/nl-processor.md +++ b/docs/guide/nl-processor.md @@ -8,7 +8,7 @@ 今天南京天气怎么样？ ``` -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-3](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-3) 查看。 ::: @@ -118,11 +118,11 @@ async def _(session: NLPSession): 在 NoneBot 中，自然语言处理器的工作方式就是将用户的自然语言消息解析成一个命令和命令所需的参数，由于自然语言消息的模糊性，在解析时不可能完全确定用户的意图，因此还需要返回一个置信度作为这个命令的确定程度。 -::: warning 注意 +:::warning 注意 这里的「置信度」与统计学中的置信度没有任何关系，只表示对「当前用户输入的意图是触发某命令」这件事有多大把握，应理解为普通意义的「confidence」。 ::: -::: tip 提示 +:::tip 提示 置信度的计算需要自然语言处理器的编写者进行恰当的设计，以确保各插件之间的功能不会互相冲突。 ::: @@ -152,7 +152,7 @@ async def _(session: NLPSession): pip install jieba ``` -::: tip 提示 +:::tip 提示 如果你没有使用过结巴分词，建议先前往它的 [项目主页](https://github.com/fxsjy/jieba) 查看代码示例以了解基本用法。 ::: @@ -215,7 +215,7 @@ async def _(session: NLPSession): 这里我们首先使用结巴分词的 posseg 模块进行词性标注，然后找出第一个标记为 `ns`（表示地名，其它词性见 [ICTCLAS 汉语词性标注集](https://gist.github.com/luw2007/6016931#ictclas-%E6%B1%89%E8%AF%AD%E8%AF%8D%E6%80%A7%E6%A0%87%E6%B3%A8%E9%9B%86)）的词，赋值给 `city`，进而作为 `weather` 命令的参数传入 `IntentCommand`（如果 `city` 为空，则给 `current_arg` 传入空字符串）。 -::: tip 提示 +:::tip 提示 这里使用了 `current_arg`，因为之前编写的天气命令能够处理第一次运行时就附带了参数（城市名）的情况。 你也可以在你自己的功能中使用 `args` 传入更复杂的初始参数。 diff --git a/docs/guide/notice-and-request.md b/docs/guide/notice-and-request.md index eedea327..e37c4d77 100644 --- a/docs/guide/notice-and-request.md +++ b/docs/guide/notice-and-request.md @@ -4,7 +4,7 @@ 本章将介绍如何在插件中处理通知和请求。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-5](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-5) 查看。 ::: @@ -51,7 +51,7 @@ async def _(session: NoticeSession): await session.send('欢迎新朋友～') ``` -::: warning 注意 +:::warning 注意 这里最好预先判断一下是不是你想发送的群（通过 `session.event.group_id`），否则机器人所在的任何群有新成员进入它都会欢迎。 ::: diff --git a/docs/guide/scheduler.md b/docs/guide/scheduler.md index d43eb680..36219523 100644 --- a/docs/guide/scheduler.md +++ b/docs/guide/scheduler.md @@ -2,7 +2,7 @@ 实际应用中还经常会有定时执行任务的需求，为了方便这类需求的开发，NoneBot 可选地包含了计划任务功能。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-6](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-6) 查看。 ::: diff --git a/docs/guide/tuling.md b/docs/guide/tuling.md index d733e79e..df545c92 100644 --- a/docs/guide/tuling.md +++ b/docs/guide/tuling.md @@ -1,6 +1,6 @@ # 接入图灵机器人 -::: danger 重要 +:::danger 重要 本章内容可能已经过时，即将更新。 ::: @@ -10,7 +10,7 @@ 不过还是有解决方案的，市面上有一些提供智能聊天机器人接口的厂商，本章我们以 [图灵机器人](http://www.tuling123.com/) 为例，因为它的使用比较广泛，接入也比较简单，不过缺点是免费调用次数比较少。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-4](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-4) 查看。 ::: @@ -18,7 +18,7 @@ 首先前往 [图灵机器人官网](http://www.tuling123.com/) 注册账号，然后在「机器人管理」页根据它的提示创建机器人，可以设置机器人名字、属性、技能、语料库等。 -::: warning 注意 +:::warning 注意 图灵机器人的免费套餐现在需要实名认证后才可使用。 ::: diff --git a/docs/guide/usage.md b/docs/guide/usage.md index fda2724b..5284c217 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -4,7 +4,7 @@ 现在，为了让用户能够更方便的使用，是时候编写一个使用帮助了。 -::: tip 提示 +:::tip 提示 本章的完整代码可以在 [awesome-bot-7](https://github.com/richardchien/nonebot/tree/master/docs/guide/code/awesome-bot-7) 查看。 ::: diff --git a/docs/guide/whats-happened.md b/docs/guide/whats-happened.md index d56ff4ff..85f80736 100644 --- a/docs/guide/whats-happened.md +++ b/docs/guide/whats-happened.md @@ -2,7 +2,7 @@ 上一章中我们已经运行了一个最小的 NoneBot 实例，在看着 QQ 机器人回复了自己的消息的同时，你可能想问，这是如何实现的？具体来说，NoneBot、CQHTTP 插件、酷Q，这三者是如何协同工作的？本章将对这个问题做一个初步解答。 -::: tip 提示 +:::tip 提示 如果你已经有较丰富的 QQ 机器人开发经验，尤其是使用 CQHTTP 插件的经验，可以直接跳到 [NoneBot 出场](#nonebot-出场)。 ::: @@ -20,7 +20,7 @@ CQHTTP 插件收到消息后，会将其包装为一个统一的事件格式， 接着，插件把包装好的事件转换成 JSON 格式，并通过「反向 WebSocket」发送给 NoneBot。这里的「反向 WebSocket」，连接的就是我们在 CQHTTP 插件的配置中指定的 `ws_reverse_url`，即 NoneBot 监听的 WebSocket 入口。 -::: tip 提示 +:::tip 提示 「反向 WebSocket」是 CQHTTP 插件的一种通信方式，表示插件作为客户端，主动去连接配置文件中指定的 `ws_reverse_url`。除此之外还有 HTTP、（正向）WebSocket 等方式。除了反向 WebSocket，NoneBot 也支持通过 HTTP 与 CQHTTP 通信。 ::: @@ -34,7 +34,7 @@ CQHTTP 插件通过反向 WebSocket 将消息事件发送到 NoneBot 后，NoneB 负责处理消息的函数会尝试把消息作为一个命令来解析，根据默认配置，它发现消息内容 `/echo 你好，世界` 符合命令的一个特征——以 `/` 开头，剥离掉这个起始字符之后，消息变为 `echo 你好，世界`，紧接着，它读取第一个空白字符之前的内容，即 `echo`，将其理解为命令的名字。 -::: tip 提示 +:::tip 提示 实际上，它还会使用配置中的分隔符对 `echo` 做一个分割，不过这里分割完也只有一个部分，所以实际命令名字为 `('echo',)`，形式是一个 Python 元组；而如果我们发送的命令是 `note.add`，分割之后就是 `('note', 'add')`。 :::