Merge pull request #243 from zhamao-robot/doc-update

文档更新 - 机器人上下文

.editorconfig

@@ -11,5 +11,5 @@ trim_trailing_whitespace = true
 [*.md]
 trim_trailing_whitespace = false
 
-[*.{yml,yaml}]
+[*.{yml,yaml, vue}]
 indent_size = 2

composer.json

@@ -32,7 +32,7 @@
         "symfony/routing": "~6.0 || ~5.0 || ~4.0"
     },
     "require-dev": {
-        "captainhook/captainhook": "^5.12",
+        "captainhook/captainhook": "^5.10",
         "friendsofphp/php-cs-fixer": "^3.2 != 3.7.0",
         "jangregor/phpstan-prophecy": "^1.0",
         "jetbrains/phpstorm-attributes": "^1.0",

docs/.vuepress/components/ChatBox.vue

@@ -4,7 +4,7 @@
     <div v-for="i in chat" v-bind="i">
       <div class="doc-chat-row" v-if="i.type === 0">
         <div class="doc-chat-box">{{ i.content }}</div>
-        <img class="doc-chat-avatar" src="https://api.btstu.cn/sjtx/api.php"  alt=""/>
+        <img class="doc-chat-avatar" src="https://zhamao.xin/images/customer_avatar.png"  alt=""/>
       </div>
       <div class="doc-chat-row doc-chat-row-robot" v-else-if="i.type === 1">
         <img class="doc-chat-avatar" src="https://docs-v1.zhamao.xin/logo.png" alt=""/>
@@ -21,6 +21,13 @@
           <img :src="i.content" alt="" />
         </div>
       </div>
+      <div class="doc-chat-row doc-chat-row-robot" v-else-if="i.type === 4">
+        <img class="doc-chat-avatar" src="https://docs-v1.zhamao.xin/logo.png" alt=""/>
+        <div class="doc-chat-box doc-chat-box-robot">
+          <div class="doc-chat-box-quote">{{ i.quote }}</div>
+          <span v-for="(p,index) in i.content.split('\n')">{{p}}<br v-if="index !== i.content.length - 1"></span>
+        </div>
+      </div>
     </div>
   </div>
 </div>
@@ -85,6 +92,14 @@ export default {
   justify-content: flex-start !important;
 }
 
+.doc-chat-box-quote {
+  background-color: #cecece;
+  margin: .4rem .2rem;
+  border-radius: .3rem;
+  padding: .4rem .6rem;
+  font-size: 12px;
+}
+
 .doc-chat-box {
   color: #000000de;
   position: relative;

docs/.vuepress/config.js

@@ -27,6 +27,7 @@ module.exports = {
         nav: [
             { text: '指南', link: '/guide/' },
             { text: '事件', link: '/event/' },
+            { text: '组件', link: '/components/bot/bot-context' },
             { text: 'API 文档', link: '/doxy/', target: '_blank' },
             { text: '炸毛框架 v2', link: 'https://docs-v2.zhamao.xin/' }
         ],
@@ -59,6 +60,17 @@ module.exports = {
                         'extend',
                     ]
                 }
+            ],
+            '/components/': [
+                {
+                    title: '组件',
+                    collapsable: false,
+                    sidebarDepth: 2,
+                    children: [
+                        'bot/bot-context',
+                        'bot/message-segment',
+                    ]
+                }
             ]
         }
     }

docs/components/bot/bot-context.md

@@ -0,0 +1,322 @@
+# OneBot 机器人上下文
+
+在你使用炸毛框架为你的机器人编写逻辑和使用插件时，围绕机器人的核心处理方式为机器人上下文。
+机器人上下文可获取当前机器人事件的其他参数、发起机器人动作请求、互动询问消息等。
+
+BotContext 为上下文对象，例如下方的 `#[\BotCommand]` 事件：
+
+```php
+#[\BotCommand(match: 'SOS')]
+public function sos(\BotContext $ctx)
+{
+    $ctx->reply('不许求救！');
+}
+```
+
+关于 BotContext 机器人上下文，如果你不喜欢上方通过参数绑定的依赖注入（DI）形式获取，还可以在相关事件内使用全局函数 `bot()` 获取：
+
+```php
+bot()->reply('牛逼');
+```
+
+## reply() - 快速回复消息
+
+可能是你在编写插件时最常用的方法，用于快速回复消息。
+
+- 定义：`reply($message, int $reply_mode = ZM_REPLY_NONE)`
+- 返回：`ActionResponse|bool`
+
+参数说明：
+
+- `$message`：消息内容，可以是字符串或数组，如果是数组，会验证是否为标准的消息段格式。有关消息段格式的说明，见 [消息段](message-segment.md)。
+- `$reply_mode`：回复模式，可选值为 `ZM_REPLY_NONE`、`ZM_REPLY_MENTION`、`ZM_REPLY_QUOTE`，默认为 `ZM_REPLY_NONE`。
+
+回复模式说明：
+
+- `ZM_REPLY_NONE`：不回复，直接发送消息。
+- `ZM_REPLY_MENTION`：回复并 @ 消息发送者。
+- `ZM_REPLY_QUOTE`：回复并引用消息。
+
+其中 `$message` 和下方的 `sendMessage()` 内的 `$message` 参数格式一致，可参考下方。
+`$reply_mode` 可以通过 `ZM_REPLY_MENTION` 和 `ZM_REPLY_QUOTE` 两个常量来设置，例如：
+
+```php
+#[BotCommand(match: '测试at')]
+public function testAt(\BotContext $ctx)
+{
+    $ctx->reply('测试at回复完成', ZM_REPLY_MENTION);
+}
+
+#[BotCommand(match: '测试引用')]
+public function testDefault(\BotContext $ctx)
+{
+    $ctx->reply('测试引用回复完成', ZM_REPLY_QUOTE);
+}
+```
+
+<chat-box :my-chats="[
+{type:0,content:'测试at'},
+{type:1,content:'@123456 测试at回复完成'},
+{type:0,content:'测试引用'},
+{type:4,quote:'测试引用',content:'测试引用回复完成'},
+]" />
+
+::: warning 注意
+
+`reply()` 只能运用在 `BotCommand`、`BotEvent` 的回调事件中，如果你想在其他事件中使用，可以使用 `sendMessage()` 方法。
+
+:::
+
+## sendMessage() - 发送一条机器人消息
+
+作为聊天机器人的最主要功能，`sendMessage()` 方法可以发送一条消息。
+
+- 定义：`sendMessage($message, string $detail_type, array $params = [])`
+- 返回：`ActionResponse|bool`
+
+参数说明：
+
+- `$message`：消息内容，可以是字符串或数组，如果是数组，会验证是否为标准的消息段格式。有关消息段格式的说明，见 [消息段](message-segment.md)。
+- `$detail_type`：消息类型，可选值为 `private`、`group`、`channel`，分别表示私聊、群聊、频道。如果你的机器人实现端有扩展，也可以使用自定义的消息类型。
+- `$params`：可选参数，用于指定消息的其他参数，例如 `group_id`、`user_id` 等。
+- `ActionResponse|false`：如果发送成功，返回一个 `ActionResponse` 对象，否则返回 `false`。
+
+::: tip 提示
+
+如果你的 PHP 没有安装 Swoole 扩展且 PHP 版本低于 8.1，那么将无法返回 ActionResponse，只能返回 `true` 或 `false`。
+
+:::
+
+示例：
+
+```php
+// 发送一条私聊消息
+$response = $ctx->sendMessage('你好', 'private', ['user_id' => '123456']);
+if ($response instanceof \ActionResponse) {
+    // 发送成功
+    $response->data['message_id']; // 获取发送的消息 ID
+} else {
+    // 发送失败
+}
+
+// 发送一条多媒体消息，例如图片
+$ctx->sendMessage([MessageSegment::image(file_id: '7815696ecbf1c96e6894b779456d330e')]);
+```
+
+## sendAction() - 发送一个机器人动作
+
+`sendAction()` 方法可以发送一个机器人动作，动作的格式和支持的动作列表详见 [OneBot12 - 接口定义](https://12.onebot.dev/interface/)。
+
+- 定义：`sendAction(string $action, array $params = [], ?array $self = null)`
+- 返回：`ActionResponse|bool`
+
+参数说明：
+
+- `$action`：动作名称，例如 `send_message`、`get_status` 等。
+- `$params`：动作参数，例如 `message`、`user_id` 等。
+- `$self`：可选参数，用于指定动作的机器人平台和对应机器人自身 ID，如果不指定，将使用当前上下文机器人的 ID。
+
+`$self` 参数仅在连接到炸毛框架的 OneBot 12 实现端需要时有效，例如部分机器人实现端支持多机器人占用一个连接，这时必须指定 `self.user_id` 和 `self.platform` 参数。
+
+示例：
+
+```php
+// 从实现端获取机器人状态，写入终端日志
+$response = $ctx->sendAction('get_status');
+if ($response instanceof \ActionResponse) {
+    // 获取成功
+    $good = $response->data['good']; // 获取机器人在线状态
+    logger()->info('机器人状态：' . ($good ? '在线' : '离线'));
+} else {
+    logger()->error('获取机器人状态失败');
+}
+```
+
+::: tip 提示
+
+部分 OneBot 12 实现端支持了较多 OneBot 12 标准以外的扩展动作，这里也可以使用 `sendAction()` 方法发送这些扩展动作。
+但动作列表需要自行寻找对应实现端的文档进行查询。
+
+:::
+
+## prompt() - 等待一条消息回复
+
+`prompt()` 方法用处是等待一条用户的回复消息，它会阻塞当前协程，直到用户回复消息或超时。
+
+> 此方法仅在 `BotCommand` 或 `BotEvent` 内 `type` 为 `message` 的上下文中有效，且仅可在协程环境可用时使用。
+
+- 定义：`prompt($prompt = '', int $timeout = 600, string $timeout_prompt = '', bool $return_string = false)`
+- 返回：`MessageSegment[]|string|false`
+
+参数说明：
+
+- `$prompt`：可选参数，用于指定等待回复时发送的提示消息，如果不指定，将不发送提示消息。
+- `$timeout`：可选参数，用于指定等待回复的超时时间，单位为秒，如果不指定，将使用默认的 600 秒。
+- `$timeout_prompt`：可选参数，用于指定等待回复超时时发送的提示消息，如果不指定，将不发送提示消息。
+- `$return_string`：可选参数，用于指定是否返回字符串形式的消息，如果不指定，将返回消息段数组。
+
+示例：
+
+```php
+#[\BotCommand(match: '测试段')]
+public function testSegment(\BotContext $ctx)
+{
+    // 等待用户回复一条消息
+    $reply = $ctx->prompt('请回复一条消息');
+    // 如果用户回复了消息，那么 reply 将是一个消息段数组
+    // 如果用户没有回复消息，超时了，那下方的代码不会被执行，此处的事件流程将强制中断
+    $ctx->reply(['你回复了：', ...$reply]);
+}
+
+#[\BotCommand(match: '测试字符串')]
+public function testString(\BotContext $ctx)
+{
+    // 等待用户回复一条消息
+    $reply = $ctx->prompt('请回复一条消息', 600, '你超时了', true);
+    // 如果用户回复了消息，那么 reply 将是一个字符串
+    // 如果用户没有回复消息，超时了，那下方的代码不会被执行，此处的事件流程将强制中断
+    $ctx->reply('你回复了：' . $reply);
+}
+```
+
+<chat-box :my-chats="[
+{type:0,content:'测试段'},
+{type:1,content:'请回复一条消息'},
+{type:0,content:'test'},
+{type:1,content:'你回复了：test'},
+{type:0,content:'测试字符串'},
+{type:1,content:'请回复一条消息'},
+{type:2,content:'等待 600 秒以上'},
+{type:1,content:'你超时了'},
+]" />
+
+## hasReplied() - 检查是否已回复
+
+`hasReplied()` 方法用处是检查当前事件是否已经回复过消息，如果已经回复过消息（即调用过 `reply()`），那么这里将返回 `true`，否则返回 `false`。
+
+- 定义：`hasReplied()`
+- 返回：`bool`
+
+示例：
+
+```php
+#[\BotCommand(match: '测试消息')]
+public function testMsg(\BotContext $ctx)
+{
+    $ctx->reply('这是一条消息');
+    // 检查是否已经回复过消息
+    if ($ctx->hasReplied()) {
+        $ctx->reply('已经回复过消息了');
+    } else {
+        $ctx->reply('还没有回复过消息');
+    }
+}
+```
+
+<chat-box :my-chats="[
+{type:0,content:'测试消息'},
+{type:1,content:'这是一条消息'},
+{type:1,content:'已经回复过消息了'},
+]" />
+
+## getBot() - 获取其他机器人上下文对象
+
+`getBot()` 方法用处是获取其他机器人的上下文，这里的“其他机器人”是指同时连接到框架的其他 OneBot 12 实现端的上下文。
+
+例如你使用了两个 Walle-Q 连接到框架，机器人 QQ 号分别为 123 和 456，你在 123 机器人的上下文中要获取 456 机器人的上下文：
+
+```php
+$another_ctx = $ctx->getBot(bot_id: '456', platform: 'qq');
+```
+
+- 定义：`getBot(string $bot_id, string $platform = '')`
+- 返回：`\BotContext`
+
+## getParam() - 获取 BotCommand 注解解析出来的参数
+
+`getParam()` 方法用处是获取 BotCommand 和 CommandArgument 注解解析出来的参数，这里的“参数”是指 BotCommand 注解的 `param` 属性。
+
+- 定义：`getParam(string $name)`
+- 返回：`MessageSegment[]|string|null`
+
+参数 `$name` 是参数名，如果参数不存在，将返回 `null`。
+
+由 CommandArgument 注解解析出来的参数，且 `required` 为 `true`，则对应名字的 param 必定会存在，可以通过对应 CommandArgument 绑定的名字来获取，例如：
+
+```php
+#[\BotCommand(match: '测试参数')]
+#[\CommandArgument(name: 'param1', type: 'string', required: true)]
+public function testParam(\BotContext $ctx)
+{
+    $ctx->reply(['参数1：', ...$ctx->getParam('param1')]);
+}
+```
+
+<chat-box :my-chats="[
+{type:0,content:'测试参数'},
+{type:1,content:'请输入param1'},
+{type:0,content:'test'},
+{type:1,content:'参数1：test'},
+{type:0,content:'测试参数 test123'},
+{type:1,content:'参数1：test123'},
+]" />
+
+如果你没有使用 CommandArgument 绑定参数或想获取更多参数，可以使用 `getParam('.unnamed')` 方法，这样会返回所有未绑定的参数：
+
+```php
+#[\BotCommand(match: '测试参数')]
+#[\CommandArgument(name: 'param1', type: 'string', required: true)]
+public function testParam(\BotContext $ctx)
+{
+    $ctx->reply(['参数1：', ...$ctx->getParam('param1')]);
+    $ctx->reply('未命名参数列表：[' . implode(', ', $ctx->getParam('.unnamed')) . ']');
+}
+```
+
+<chat-box :my-chats="[
+{type:0,content:'测试参数 abc def ghhaha   你好'},
+{type:1,content:'参数1：abc'},
+{type:1,content:'未命名参数列表：[def, ghhaha, 你好]'},
+]" />
+
+## getParamString() - 获取 BotCommand 注解解析出来的参数字符串
+
+`getParamString()` 功能和 `getParam()` 完全一样，参数也一模一样，不一样的地方在于这个方法返回的参数都是字符串，而 `getParam()` 返回的是 MessageSegment 数组。
+
+一般用于不在意用户返回的其他富文本参数，只需要字符串参数的情况。
+
+- 定义：`getParamString(string $name)`
+- 返回：`string|null`
+
+## getParams() - 获取 BotCommand 注解解析出来的所有参数
+
+`getParams()` 方法用处是获取 BotCommand 注解解析出来的所有参数，这里的“参数”是指 BotCommand 注解的 `param` 属性。
+
+- 定义：`getParams()`
+- 返回：`array`
+
+```php
+#[\BotCommand(match: '测试参数')]
+#[\CommandArgument(name: 'param1', type: 'string', required: true)]
+public function testParam(\BotContext $ctx)
+{
+    logger()->info(json_encode($ctx->getParams(), JSON_PRETTY_PRINT));
+}
+// 假设询问内容为“测试参数 abc def”，返回结果：
+/*
+{
+    "param1":[{"type":"text","data":{"text":"abc"}}],
+    ".unnamed":[{"type":"text","data":{"text":"def"}}]
+}
+*/
+```
+
+## getSelf() - 获取当前上下文的机器人信息
+
+- 定义：`getSelf()`
+- 返回：`array`
+
+```php
+$self = $ctx->getSelf();
+// 返回：["user_id" => "123456", "platform" => "qq"]
+```

docs/components/bot/message-segment.md

@@ -0,0 +1,3 @@
+# 机器人消息段格式
+
+TODO。

docs/guide/README.md

@@ -24,3 +24,4 @@
 - 支持多个机器人账号负载均衡
 - 完善的插件系统，可以随意加载和编写独立的插件
 - 灵活的注释和注解注册事件方式，支持 PHP 原生注解，提示更为友好
+- 如果你不想安装 PHP 环境，可以使用静态编译的 PHP

docs/guide/configuration.md

@@ -1,6 +1,6 @@
 # 配置
 
-炸毛框架的所有配置文件都存储在 `config` 目录中。每个选项都带有文档，所以你可以查阅这些文件并熟悉可用的配置项。
+炸毛框架的所有配置文件都存储在 `config/` 目录中。每个选项都带有文档，所以你可以查阅这些文件并熟悉可用的配置项。
 
 一般来说，我们建议你优先查看 `config/global.php` 文件及其文档，它包含了运行框架所需要的绝大部分配置，例如通信方式和时区等。
 
@@ -32,7 +32,7 @@
 
 ## 访问配置项
 
-你可以在任何地方使用全局 `config` 函数获取配置项值。支持使用点语法获取，配置项名称由文件名开头，并允许指定默认值。
+你可以在任何地方使用全局 `config()` 函数获取配置项值。支持使用点语法获取，配置项名称由文件名开头，并允许指定默认值。
 
 ```php
 # 获取时区，未设置则返回 Asia/Shanghai

docs/guide/get_started.md

@@ -1,4 +1,4 @@
-# 快速上手
+# 快速上手 - 聊天机器人
 
 在这里，我们将会以一个基础的复读机为例，帮助你快速熟悉框架的开发流程。
 
@@ -6,7 +6,7 @@
 
 其中一些可用的选项为：
 
-- Walle-Q
+- Walle-Q（QQ 端）
 - 更多…
 
 ## 机器人实现端
@@ -25,7 +25,7 @@
 
 在于框架对接的情况中，我们只需要关注 `onebot.websocket_rev` 配置。
 
-```toml
+```toml {7}
 [onebot]
 http = []
 http_webhook = []
@@ -107,6 +107,6 @@ $cmd1 = BotCommand::make('repeater', match: '复读')->on(function(OneBotEvent $
 
 ## 使用机器人 API 和更多事件
 
-如果你希望机器人进行其他复杂的动作（操作），请参见 机器人 API。
+如果你希望机器人进行其他复杂的动作（操作），请参见 机器人上下文。
 
 关于更多可以注册绑定的事件，请参见 注解事件。

docs/guide/installation.md

@@ -5,6 +5,7 @@
 - 一键脚本
 - Docker
 - Composer
+- Phar 发行模式
 
 ## 一键脚本
 
@@ -44,6 +45,17 @@ composer require zhamao/framework
 ./zhamao plugin:make
 ```
 
+## Phar 发行模式
+
+如果你对框架本身不感兴趣，只是想使用框架提供的功能，你可以直接下载 Phar 发行模式的框架，然后在任意目录下使用。
+
+你可以到 GitHub Release 下载框架的自动打包 Phar 版本，同时下载一个静态的 PHP 运行时，然后将二者放在同一目录下，即可使用。
+但请注意，测试版一般不会发布 Phar 包，因此你需要自行构建。
+
+如果你的操作系统已经安装好了 PHP 并设置了环境变量，你也可以直接使用 `./zhamao.phar` 来运行框架。
+
+> 如果在 Linux、macOS 环境下提示权限不足，请使用 `chmod +x zhamao.phar` 来授予执行权限。
+
 ## Windows 安装方法
 
 由于 Windows 系统下的 PHP 环境配置较为复杂，我们推荐使用 Docker 或一键脚本来进行安装。
@@ -79,10 +91,14 @@ cd zhamao-v3
 3. 从 PHP 官网下载 PHP，选择 `Non Thread Safe` 版本，PHP 版本选择 8.0 ~ 8.2 均可（推荐 8.1），下载完成后解压到框架目录下的 `runtime\php` 目录，例如 `D:\zhamao-v3\runtime\php\`。
 4. 从 [Composer 官网](https://getcomposer.org/download/) 或 [阿里云镜像](https://mirrors.aliyun.com/composer/composer.phar) 下载 Composer，下载到 `runtime\` 目录。
 5. 在你的脚手架目录下执行 `.\runtime\php\php.exe .\runtime\composer.phar install` 安装框架依赖。
-6. 执行框架初始化命令：`./zhamao init`。
+6. 执行框架初始化命令：`./zhamao init`。（如果提示没有 `./zhamao` 文件，本步骤可尝试使用 `.\runtime\php\php.exe .\vendor\bin\zhamao init` 来执行）
 7. 接下来你就可以使用和上方所有框架操作指令相同的内容了，例如 `./zhamao plugin:make`、`./zhamao server` 等。
 8. 如果你需要使用 Composer，你可以使用 `.\runtime\php\php.exe .\runtime\composer.phar` 来代替 `composer` 命令。
 
+## 提升性能
+
+如果你打算让你的框架提升处理性能，我们建议你为 PHP 安装 Swoole 扩展、libevent 扩展，或将 PHP 版本提升到 8.1 及以上。
+
 ## 更多的环境部署和开发方式
 
 除了上述方式之外，框架还支持源码模式、守护进程等运行方式，详情请参阅 [进阶开发]。