Update docs

docs/api.md

@@ -983,7 +983,7 @@ sidebar: auto
 
 ## `none.command` 模块
 
-### _decorator_ `on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False)`
+### _decorator_ `on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False, shell_like=False )`
 
 - **说明:**
 
@@ -998,6 +998,7 @@ sidebar: auto
   - `permission: int`: 命令所需要的权限，不满足权限的用户将无法触发该命令
   - `only_to_me: bool`: 是否只响应确定是在和「我」（机器人）说话的命令
   - `privileged: bool`: 是否特权命令，若是，则无论当前是否有命令会话正在运行，都会运行该命令，但运行不会覆盖已有会话，也不会保留新创建的会话
+  - `shell_like: bool`: 是否使用类 shell 语法，若是，则会自动使用 `shlex` 模块进行分割（无需手动编写参数解析器），分割后的参数列表放入 `session.args['argv']`
 
 - **要求:**
 
@@ -1024,6 +1025,8 @@ sidebar: auto
 
   将函数装饰为命令参数解析器。
 
+  如果已经在 `on_command` 装饰器中使用了 `shell_like=True`，则无需手动使用编写参数解析器。
+
 - **要求:**
 
   对被装饰函数的要求同 `on_command` 装饰器。
@@ -1077,7 +1080,15 @@ sidebar: auto
 
   命令组内命令的默认 `privileged` 属性。
 
-#### `__init__(name, permission=None, *, only_to_me=None, privileged=None)`
+#### `shell_like`
+
+- **类型:** `Optional[bool]`
+
+- **说明:**
+
+  命令组内命令的默认 `shell_like` 属性。
+
+#### `__init__(name, permission=None, *, only_to_me=None, privileged=None, shell_like=None)`
 
 - **说明:**
 
@@ -1089,8 +1100,9 @@ sidebar: auto
   - `permission: Optional[int]`: 对应 `permission` 属性
   - `only_to_me: Optional[bool]`: 对应 `only_to_me` 属性
   - `privileged: Optional[bool]`: 对应 `privileged` 属性
+  - `shell_like: Optional[bool]`: 对应 `shell_like` 属性
 
-#### _decorator_ `command(name, *, aliases=None, permission=None, only_to_me=None, privileged=None)`
+#### _decorator_ `command(name, *, aliases=None, permission=None, only_to_me=None, privileged=None, shell_like=None)`
 
 - **说明:**
 
@@ -1103,6 +1115,7 @@ sidebar: auto
   - `permission: Optional[int]`: 同上
   - `only_to_me: Optional[bool]`: 同上
   - `privileged: Optional[bool]`: 同上
+  - `shell_like: Optional[bool]`: 同上
 
 - **用法:**
 
@@ -1160,7 +1173,7 @@ sidebar: auto
 
   命令会话已获得的所有参数。
 
-#### _property_ `is_first_run`
+#### _readonly property_ `is_first_run`
 
 - **类型:** `bool`
 
@@ -1168,6 +1181,22 @@ sidebar: auto
 
   命令会话是否第一次运行。
 
+#### _readonly property_ `argv`
+
+- **类型:** `List[str]`
+
+- **说明:**
+
+  命令参数列表，本质上是 `session.get_optional('argv', [])`，通常搭配 `on_command(..., shell_like=True)` 使用。
+
+- **用法:**
+
+  ```python
+  @on_command('some_cmd', shell_like=True)
+  async def _(session: CommandSession):
+      argv = session.argv
+  ```
+
 #### `get(key, *, prompt=None)`
 
 - **说明:**
@@ -1774,52 +1803,66 @@ async def _(session):
 
 ### _class_ `ArgumentParser`
 
-继承自 `argparse.ArgumentParser` 类，修改部分函数实现使其不再打印文本到标准输出、并且不再在参数错误时直接退出程序。
+继承自 `argparse.ArgumentParser` 类，修改部分函数实现使其适用于命令型聊天机器人。
 
-此类可用于命令参数的解析。基本用法和 Python 内置的 `argparse.ArgumentParser` 类一致，区别是当它需要导致程序退出时，行为改变为抛出 `none.argparse.ParserExit` 异常。
+此类可用于命令参数的解析。基本用法和 Python 内置的 `argparse.ArgumentParser` 类一致，下面主要列出与 Python 原生含义和行为不同的属性和方法。
 
 - **用法:**
 
   ```python
-  parser = ArgumentParser()
+  USAGE = r"""
-  parser.add_argument('-S', '--second')
+  创建计划任务
-  parser.add_argument('-M', '--minute')
-  parser.add_argument('-H', '--hour')
-  parser.add_argument('-d', '--day')
-  parser.add_argument('-m', '--month')
-  parser.add_argument('-w', '--day-of-week')
-  parser.add_argument('-f', '--force', action='store_true', default=False)
-  parser.add_argument('-v', '--verbose', action='store_true', default=False)
-  parser.add_argument('--name', required=True)
-  parser.add_argument('commands', nargs='+')
 
-  argv = ['-S', '*/10', '-v', '--force', '--name', 'test', 'echo wow']
+  使用方法：
+  XXXXXX
+  """.strip()
 
-  try:
+  @on_command('schedule', shell_like=True)
-      return parser.parse_args(argv)
+  async def _(session: CommandSession):
-  except ParserExit as e:
+      parser = ArgumentParser(session=session, usage=USAGE)
-      if e.status == 0:
+      parser.add_argument('-S', '--second')
-          # --help
+      parser.add_argument('-M', '--minute')
-          await session.send(help_msg)
+      parser.add_argument('-H', '--hour')
-      else:
+      parser.add_argument('-d', '--day')
-          await session.send('参数不足或不正确，请使用 --help 参数查询使用帮助')
+      parser.add_argument('-m', '--month')
+      parser.add_argument('-w', '--day-of-week')
+      parser.add_argument('-f', '--force', action='store_true', default=False)
+      parser.add_argument('-v', '--verbose', action='store_true', default=False)
+      parser.add_argument('--name', required=True)
+      parser.add_argument('commands', nargs='+')
+
+      args = parser.parse_args(session.argv)
+      name = args.name
+      # ...
   ```
 
-### _class_ `ParserExit`
+#### `__init__(session=None, usage=None, **kwargs)`
-
-继承自 `RuntimeError` 类，在 `ArgumentParser` 解析出错时抛出。
-
-#### `status`
 
 - **说明:**
 
-  `argparse.ArgumentParser` 类的 `exit()` 方法的 `status` 参数。
+  初始化 `ArgumentParser` 对象。
 
-#### `message`
+- **参数:**
+
+  - `session: CommandSession`: 当前需要解析参数的命令会话，用于解析失败或遇到 `--help` 时发送提示消息
+  - `usage: str`: 命令的使用帮助，在参数为空或遇到 `--help` 时发送
+  - `**kwargs: Any`: 和 Python `argparse.ArgumentParser` 类一致
+
+#### `parse_args(args=None, namespace=None)`
 
 - **说明:**
 
-  `argparse.ArgumentParser` 类的 `exit()` 方法的 `message` 参数。
+  解析参数。
+
+  Python 原生的「打印到控制台」行为变为「发送消息到用户」，「退出程序」变为「结束当前命令会话」。
+
+- **参数:**
+
+  和 Python `argparse.ArgumentParser` 类一致。
+
+- **异常:**
+
+  无。
 
 ## `none.sched` 模块
 

docs/changelog.md

@@ -8,6 +8,9 @@ sidebar: auto
 
 - 修复调用不存在的多级命令（例如 `/echo/nonexist`）时，抛出异常导致 WebSocket 连接断开的问题
 - 调整 Expression 相关接口：移除了所有 `send_expr()` 函数和方法，移除了 `CommandSession.get()` 方法的 `prompt_expr` 参数，移除了 `none.expression` 模块，原 `render()` 函数移动到 `none.helpers` 模块并改名为 `render_expression()`
+- 修改 `none.argparse.ArgumentParser` 类的构造方法和 `parse_args()` 方法：构造方法新增 `session` 参数，可传入 `CommandSession` 对象；`parse_args()` 方法可直接用于解析参数，用户输入的参数错误，会发送错误提示或使用帮助
+- `on_command` 装饰器新增 `shell_like` 参数，设为 `True`（默认 `False`）将自动以类 shell 语法分割命令参数 `current_arg`（不再需要自行编写 args parser），并将分割后的参数列表放入 `session.args['argv']`
+- `CommandSession` 类新增 `argv` 只读属性，用于获取 `session.args['argv']`，如不存在，则返回空列表
 
 ## v0.4.3