Update docs

docs/guide/code/awesome-bot-1/config.py

@@ -4,4 +4,4 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}

docs/guide/code/awesome-bot-1/requirements.txt

@@ -1 +1 @@
-nonebot>=1.0.0
+nonebot>=1.1.0

docs/guide/code/awesome-bot-2/awesome/plugins/weather.py

@@ -5,7 +5,7 @@ from nonebot import on_command, CommandSession
 # 这里 weather 为命令的名字，同时允许使用别名「天气」「天气预报」「查天气」
 @on_command('weather', aliases=('天气', '天气预报', '查天气'))
 async def weather(session: CommandSession):
-    # 从 Session 对象中获取城市名称（city），如果当前不存在，则询问用户
+    # 从会话状态（session.state）中获取城市名称（city），如果当前不存在，则询问用户
     city = session.get('city', prompt='你想查询哪个城市的天气呢？')
     # 获取城市的天气预报
     weather_report = await get_weather_of_city(city)
@@ -19,13 +19,22 @@ async def weather(session: CommandSession):
 async def _(session: CommandSession):
     # 去掉消息首尾的空白符
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        # 如果当前正在向用户询问更多信息（本例中只有可能是要查询的城市），则直接赋值
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        # 如果当前没有在询问，但用户已经发送了内容，则理解为要查询的城市
-        # 这种情况通常是用户直接将城市名跟在命令名后面，作为参数传入
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        # 该命令第一次运行（第一次进入命令会话）
+        if stripped_arg:
+            # 第一次运行参数不为空，意味着用户直接将城市名跟在命令名后面，作为参数传入
+            # 例如用户可能发送了：天气 南京
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        # 用户没有发送有效的城市名称（而是发送了空白字符），则提示重新输入
+        # 这里 session.pause() 将会发送消息并暂停当前会话（该行后面的代码不会被运行）
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    # 如果当前正在向用户询问更多信息（例如本例中的要查询的城市），且用户输入有效，则放入会话状态
+    session.state[session.current_key] = stripped_arg
 
 
 async def get_weather_of_city(city: str) -> str:

docs/guide/code/awesome-bot-2/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-2/config.py

@@ -4,4 +4,4 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}

docs/guide/code/awesome-bot-2/requirements.txt

@@ -1 +1 @@
-nonebot>=1.0.0
+nonebot>=1.1.0

docs/guide/code/awesome-bot-3/awesome/plugins/weather/__init__.py

@@ -1,5 +1,5 @@
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from jieba import posseg
 
 from .data_source import get_weather_of_city
@@ -15,21 +15,27 @@ async def weather(session: CommandSession):
 @weather.args_parser
 async def _(session: CommandSession):
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        if stripped_arg:
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    session.state[session.current_key] = stripped_arg
 
 
 # on_natural_language 装饰器将函数声明为一个自然语言处理器
 # keywords 表示需要响应的关键词，类型为任意可迭代对象，元素类型为 str
 # 如果不传入 keywords，则响应所有没有被当作命令处理的消息
-@on_natural_language(keywords=('天气',))
+@on_natural_language(keywords={'天气'})
 async def _(session: NLPSession):
     # 去掉消息首尾的空白符
-    stripped_msg_text = session.msg_text.strip()
+    stripped_msg = session.msg_text.strip()
     # 对消息进行分词和词性标注
-    words = posseg.lcut(stripped_msg_text)
+    words = posseg.lcut(stripped_msg)
 
     city = None
     # 遍历 posseg.lcut 返回的列表
@@ -39,5 +45,5 @@ async def _(session: NLPSession):
             # ns 词性表示地名
             city = word.word
 
-    # 返回处理结果，三个参数分别为置信度、命令名、命令会话的参数
-    return NLPResult(90.0, 'weather', {'city': city})
+    # 返回意图命令，前两个参数必填，分别表示置信度和意图命令名
+    return IntentCommand(90.0, 'weather', current_arg=city or '')

docs/guide/code/awesome-bot-3/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-3/config.py

@@ -4,5 +4,5 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}
 NICKNAME = {'小明', '明明'}

docs/guide/code/awesome-bot-3/requirements.txt

@@ -1,2 +1,2 @@
-nonebot>=1.0.0
+nonebot>=1.1.0
 jieba

docs/guide/code/awesome-bot-4/awesome/plugins/tuling.py

@@ -4,7 +4,7 @@ from typing import Optional
 import aiohttp
 from aiocqhttp.message import escape
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from nonebot.helpers import context_id, render_expression
 
 # 定义无法获取图灵回复时的「表达（Expression）」
@@ -20,7 +20,7 @@ EXPR_DONT_UNDERSTAND = (
 @on_command('tuling')
 async def tuling(session: CommandSession):
     # 获取可选参数，这里如果没有 message 参数，命令不会被中断，message 变量会是 None
-    message = session.get_optional('message')
+    message = session.state.get('message')
 
     # 通过封装的函数获取图灵机器人的回复
     reply = await call_tuling_api(session, message)
@@ -38,7 +38,7 @@ async def tuling(session: CommandSession):
 async def _(session: NLPSession):
     # 以置信度 60.0 返回 tuling 命令
     # 确保任何消息都在且仅在其它自然语言处理器无法理解的时候使用 tuling 命令
-    return NLPResult(60.0, 'tuling', {'message': session.msg_text})
+    return IntentCommand(60.0, 'tuling', args={'message': session.msg_text})
 
 
 async def call_tuling_api(session: CommandSession, text: str) -> Optional[str]:

docs/guide/code/awesome-bot-4/awesome/plugins/weather/__init__.py

@@ -1,5 +1,5 @@
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from jieba import posseg
 
 from .data_source import get_weather_of_city
@@ -15,21 +15,27 @@ async def weather(session: CommandSession):
 @weather.args_parser
 async def _(session: CommandSession):
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        if stripped_arg:
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    session.state[session.current_key] = stripped_arg
 
 
 # on_natural_language 装饰器将函数声明为一个自然语言处理器
 # keywords 表示需要响应的关键词，类型为任意可迭代对象，元素类型为 str
 # 如果不传入 keywords，则响应所有没有被当作命令处理的消息
-@on_natural_language(keywords=('天气',))
+@on_natural_language(keywords={'天气'})
 async def _(session: NLPSession):
     # 去掉消息首尾的空白符
-    stripped_msg_text = session.msg_text.strip()
+    stripped_msg = session.msg_text.strip()
     # 对消息进行分词和词性标注
-    words = posseg.lcut(stripped_msg_text)
+    words = posseg.lcut(stripped_msg)
 
     city = None
     # 遍历 posseg.lcut 返回的列表
@@ -39,5 +45,5 @@ async def _(session: NLPSession):
             # ns 词性表示地名
             city = word.word
 
-    # 返回处理结果，三个参数分别为置信度、命令名、命令会话的参数
-    return NLPResult(90.0, 'weather', {'city': city})
+    # 返回意图命令，前两个参数必填，分别表示置信度和意图命令名
+    return IntentCommand(90.0, 'weather', current_arg=city or '')

docs/guide/code/awesome-bot-4/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-4/config.py

@@ -4,7 +4,7 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}
 NICKNAME = {'小明', '明明'}
 
 TULING_API_KEY = ''

docs/guide/code/awesome-bot-4/requirements.txt

@@ -1,3 +1,3 @@
-nonebot>=1.0.0
+nonebot>=1.1.0
 jieba
 aiohttp

docs/guide/code/awesome-bot-5/awesome/plugins/tuling.py

@@ -4,7 +4,7 @@ from typing import Optional
 import aiohttp
 from aiocqhttp.message import escape
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from nonebot.helpers import context_id, render_expression
 
 # 定义无法获取图灵回复时的「表达（Expression）」
@@ -20,7 +20,7 @@ EXPR_DONT_UNDERSTAND = (
 @on_command('tuling')
 async def tuling(session: CommandSession):
     # 获取可选参数，这里如果没有 message 参数，命令不会被中断，message 变量会是 None
-    message = session.get_optional('message')
+    message = session.state.get('message')
 
     # 通过封装的函数获取图灵机器人的回复
     reply = await call_tuling_api(session, message)
@@ -38,7 +38,7 @@ async def tuling(session: CommandSession):
 async def _(session: NLPSession):
     # 以置信度 60.0 返回 tuling 命令
     # 确保任何消息都在且仅在其它自然语言处理器无法理解的时候使用 tuling 命令
-    return NLPResult(60.0, 'tuling', {'message': session.msg_text})
+    return IntentCommand(60.0, 'tuling', args={'message': session.msg_text})
 
 
 async def call_tuling_api(session: CommandSession, text: str) -> Optional[str]:

docs/guide/code/awesome-bot-5/awesome/plugins/weather/__init__.py

@@ -1,5 +1,5 @@
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from jieba import posseg
 
 from .data_source import get_weather_of_city
@@ -15,21 +15,27 @@ async def weather(session: CommandSession):
 @weather.args_parser
 async def _(session: CommandSession):
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        if stripped_arg:
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    session.state[session.current_key] = stripped_arg
 
 
 # on_natural_language 装饰器将函数声明为一个自然语言处理器
 # keywords 表示需要响应的关键词，类型为任意可迭代对象，元素类型为 str
 # 如果不传入 keywords，则响应所有没有被当作命令处理的消息
-@on_natural_language(keywords=('天气',))
+@on_natural_language(keywords={'天气'})
 async def _(session: NLPSession):
     # 去掉消息首尾的空白符
-    stripped_msg_text = session.msg_text.strip()
+    stripped_msg = session.msg_text.strip()
     # 对消息进行分词和词性标注
-    words = posseg.lcut(stripped_msg_text)
+    words = posseg.lcut(stripped_msg)
 
     city = None
     # 遍历 posseg.lcut 返回的列表
@@ -39,5 +45,5 @@ async def _(session: NLPSession):
             # ns 词性表示地名
             city = word.word
 
-    # 返回处理结果，三个参数分别为置信度、命令名、命令会话的参数
-    return NLPResult(90.0, 'weather', {'city': city})
+    # 返回意图命令，前两个参数必填，分别表示置信度和意图命令名
+    return IntentCommand(90.0, 'weather', current_arg=city or '')

docs/guide/code/awesome-bot-5/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-5/config.py

@@ -4,7 +4,7 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}
 NICKNAME = {'小明', '明明'}
 
 TULING_API_KEY = ''

docs/guide/code/awesome-bot-5/requirements.txt

@@ -1,3 +1,3 @@
-nonebot>=1.0.0
+nonebot>=1.1.0
 jieba
 aiohttp

docs/guide/code/awesome-bot-6/awesome/plugins/tuling.py

@@ -4,7 +4,7 @@ from typing import Optional
 import aiohttp
 from aiocqhttp.message import escape
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from nonebot.helpers import context_id, render_expression
 
 # 定义无法获取图灵回复时的「表达（Expression）」
@@ -20,7 +20,7 @@ EXPR_DONT_UNDERSTAND = (
 @on_command('tuling')
 async def tuling(session: CommandSession):
     # 获取可选参数，这里如果没有 message 参数，命令不会被中断，message 变量会是 None
-    message = session.get_optional('message')
+    message = session.state.get('message')
 
     # 通过封装的函数获取图灵机器人的回复
     reply = await call_tuling_api(session, message)
@@ -38,7 +38,7 @@ async def tuling(session: CommandSession):
 async def _(session: NLPSession):
     # 以置信度 60.0 返回 tuling 命令
     # 确保任何消息都在且仅在其它自然语言处理器无法理解的时候使用 tuling 命令
-    return NLPResult(60.0, 'tuling', {'message': session.msg_text})
+    return IntentCommand(60.0, 'tuling', args={'message': session.msg_text})
 
 
 async def call_tuling_api(session: CommandSession, text: str) -> Optional[str]:

docs/guide/code/awesome-bot-6/awesome/plugins/weather/__init__.py

@@ -1,5 +1,5 @@
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from jieba import posseg
 
 from .data_source import get_weather_of_city
@@ -15,21 +15,27 @@ async def weather(session: CommandSession):
 @weather.args_parser
 async def _(session: CommandSession):
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        if stripped_arg:
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    session.state[session.current_key] = stripped_arg
 
 
 # on_natural_language 装饰器将函数声明为一个自然语言处理器
 # keywords 表示需要响应的关键词，类型为任意可迭代对象，元素类型为 str
 # 如果不传入 keywords，则响应所有没有被当作命令处理的消息
-@on_natural_language(keywords=('天气',))
+@on_natural_language(keywords={'天气'})
 async def _(session: NLPSession):
     # 去掉消息首尾的空白符
-    stripped_msg_text = session.msg_text.strip()
+    stripped_msg = session.msg_text.strip()
     # 对消息进行分词和词性标注
-    words = posseg.lcut(stripped_msg_text)
+    words = posseg.lcut(stripped_msg)
 
     city = None
     # 遍历 posseg.lcut 返回的列表
@@ -39,5 +45,5 @@ async def _(session: NLPSession):
             # ns 词性表示地名
             city = word.word
 
-    # 返回处理结果，三个参数分别为置信度、命令名、命令会话的参数
-    return NLPResult(90.0, 'weather', {'city': city})
+    # 返回意图命令，前两个参数必填，分别表示置信度和意图命令名
+    return IntentCommand(90.0, 'weather', current_arg=city or '')

docs/guide/code/awesome-bot-6/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-6/config.py

@@ -4,7 +4,7 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}
 NICKNAME = {'小明', '明明'}
 
 TULING_API_KEY = ''

docs/guide/code/awesome-bot-6/requirements.txt

@@ -1,4 +1,4 @@
-nonebot>=1.0.0
+nonebot>=1.1.0
 jieba
 aiohttp
 pytz

docs/guide/code/awesome-bot-7/awesome/plugins/tuling.py

@@ -4,7 +4,7 @@ from typing import Optional
 import aiohttp
 from aiocqhttp.message import escape
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from nonebot.helpers import context_id, render_expression
 
 __plugin_name__ = '智能聊天'
@@ -27,7 +27,7 @@ EXPR_DONT_UNDERSTAND = (
 @on_command('tuling')
 async def tuling(session: CommandSession):
     # 获取可选参数，这里如果没有 message 参数，命令不会被中断，message 变量会是 None
-    message = session.get_optional('message')
+    message = session.state.get('message')
 
     # 通过封装的函数获取图灵机器人的回复
     reply = await call_tuling_api(session, message)
@@ -45,7 +45,7 @@ async def tuling(session: CommandSession):
 async def _(session: NLPSession):
     # 以置信度 60.0 返回 tuling 命令
     # 确保任何消息都在且仅在其它自然语言处理器无法理解的时候使用 tuling 命令
-    return NLPResult(60.0, 'tuling', {'message': session.msg_text})
+    return IntentCommand(60.0, 'tuling', args={'message': session.msg_text})
 
 
 async def call_tuling_api(session: CommandSession, text: str) -> Optional[str]:

docs/guide/code/awesome-bot-7/awesome/plugins/weather/__init__.py

@@ -1,5 +1,5 @@
 from nonebot import on_command, CommandSession
-from nonebot import on_natural_language, NLPSession, NLPResult
+from nonebot import on_natural_language, NLPSession, IntentCommand
 from jieba import posseg
 
 from .data_source import get_weather_of_city
@@ -22,21 +22,27 @@ async def weather(session: CommandSession):
 @weather.args_parser
 async def _(session: CommandSession):
     stripped_arg = session.current_arg_text.strip()
-    if session.current_key:
-        session.args[session.current_key] = stripped_arg
-    elif stripped_arg:
-        session.args['city'] = stripped_arg
+
+    if session.is_first_run:
+        if stripped_arg:
+            session.state['city'] = stripped_arg
+        return
+
+    if not stripped_arg:
+        session.pause('要查询的城市名称不能为空呢，请重新输入')
+
+    session.state[session.current_key] = stripped_arg
 
 
 # on_natural_language 装饰器将函数声明为一个自然语言处理器
 # keywords 表示需要响应的关键词，类型为任意可迭代对象，元素类型为 str
 # 如果不传入 keywords，则响应所有没有被当作命令处理的消息
-@on_natural_language(keywords=('天气',))
+@on_natural_language(keywords={'天气'})
 async def _(session: NLPSession):
     # 去掉消息首尾的空白符
-    stripped_msg_text = session.msg_text.strip()
+    stripped_msg = session.msg_text.strip()
     # 对消息进行分词和词性标注
-    words = posseg.lcut(stripped_msg_text)
+    words = posseg.lcut(stripped_msg)
 
     city = None
     # 遍历 posseg.lcut 返回的列表
@@ -46,5 +52,5 @@ async def _(session: NLPSession):
             # ns 词性表示地名
             city = word.word
 
-    # 返回处理结果，三个参数分别为置信度、命令名、命令会话的参数
-    return NLPResult(90.0, 'weather', {'city': city})
+    # 返回意图命令，前两个参数必填，分别表示置信度和意图命令名
+    return IntentCommand(90.0, 'weather', current_arg=city or '')

docs/guide/code/awesome-bot-7/bot.py

@@ -6,6 +6,8 @@ import config
 
 if __name__ == '__main__':
     nonebot.init(config)
-    nonebot.load_plugins(path.join(path.dirname(__file__), 'awesome', 'plugins'),
-                      'awesome.plugins')
+    nonebot.load_plugins(
+        path.join(path.dirname(__file__), 'awesome', 'plugins'),
+        'awesome.plugins'
+    )
     nonebot.run()

docs/guide/code/awesome-bot-7/config.py

@@ -4,7 +4,7 @@ HOST = '0.0.0.0'
 PORT = 8080
 
 SUPERUSERS = {12345678}
-COMMAND_START.add('')
+COMMAND_START = {'', '/', '!', '／', '！'}
 NICKNAME = {'小明', '明明'}
 
 TULING_API_KEY = ''

docs/guide/code/awesome-bot-7/requirements.txt

@@ -1,4 +1,4 @@
-nonebot>=1.0.0
+nonebot>=1.1.0
 jieba
 aiohttp
 pytz