From 4c41dd09d2f0692226431c26157a88e4ec2e5839 Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Sat, 31 Dec 2022 18:12:28 +0800 Subject: [PATCH] update some docs --- docs/guide/README.md | 11 +++---- docs/guide/get_started.md | 61 ++++++++++++++++++++++++++--------- docs/guide/installation.md | 3 ++ docs/guide/structure.md | 66 ++++++++++++++++---------------------- 4 files changed, 80 insertions(+), 61 deletions(-) diff --git a/docs/guide/README.md b/docs/guide/README.md index d03ded72..63b497c9 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -8,16 +8,13 @@ 框架内置了对于 WebSocket 和 HTTP 的服务端和客户端支持，并针对聊天机器人消息处理进行优化扩展，提供常用会话机制和内部调用机制，让代码更为灵活。 -这里放个代码示例 - ## 环境要求 虽然我们已经大力简化了运行框架的要求，但仍然存在少量的必要项： -- PHP 8.0 或以上版本 -- JSON 扩展 -- Tokenizer 扩展 -- Composer 工具 +- PHP 8.0 或以上版本（使用命令 `php -v` 检查） +- Tokenizer 扩展（使用命令 `php -m | grep tokenizer` 检查） +- Composer 工具（使用命令 `composer` 检查） ## 框架特色 @@ -25,5 +22,5 @@ - WebSocket 服务器、HTTP 服务器兼容运行，一个框架多个用处 - 支持命令、自然语言处理等多种插件形式 - 支持多个机器人账号负载均衡 -- 模块分离和自由组合，可根据自身需求自己建立模块内的目录结构和代码结构 +- 完善的插件系统，可以随意加载和编写独立的插件 - 灵活的注释和注解注册事件方式，支持 PHP 原生注解，提示更为友好 diff --git a/docs/guide/get_started.md b/docs/guide/get_started.md index 7478c068..fbae10ad 100644 --- a/docs/guide/get_started.md +++ b/docs/guide/get_started.md @@ -17,7 +17,7 @@ 这里以 Walle-Q 实现端为例，在实际使用中，你可以自由选用不同的实现端。 -你可以前往 Walle-Q 的[发布页面](https://github.com/onebot-walle/walle-q/releases)下载最新的发行版本，并运行以进行初始化。 +你可以前往 Walle-Q 的 [发布页面](https://github.com/onebot-walle/walle-q/releases) 下载最新的发行版本，并运行以进行初始化。 在登录成功后，请关闭 Walle-Q 以修改配置文件。 @@ -38,26 +38,57 @@ reconnect_interval = 4 修改完成并保存后，重新启动 Walle-Q 并登录即可。如果出现连接失败也请勿惊慌，因为框架此时尚未启动，失败是正常现象。 +有些情况可能无法正常扫码登录，可使用 QQ+密码 的方式登录，在最上方插入配置： + +```toml +[qq.123456] +password = "MyPassword" +``` + +> 请将 123456 替换为你的机器人 QQ 号码，MyPassword 替换为机器人 QQ 密码。 + ## 编写第一个功能 在框架中，几乎所有事件的绑定都是通过注解进行的，详情可以参阅 注解的使用。 -让我们在 `src/Module/Repeater.php` 中开发我们的第一个功能。 +让我们新建第一个插件，插件的功能很简单，就是复读。我们假设这个复读插件的名字是 `repeater` -```php -namespace Module; - -class Repeater -{ - #[BotCommand('echo')] - public function repeat(OneBotEvent $event, BotContext $context): void - { - $context->reply($event->getMessage()); - } -} +```bash +./zhamao plugin:make +# 然后根据提示，创建，比如名字输入 repeater +# 选择类型的时候，输入 file ``` -借助容器的依赖注入功能，我们可以直接指定相应的类，相关实例会在调用时自动传入。 +我们就可以在目录 `plugins/repeater/` 下得到两个文件，其中 `main.php` 代码可能如下： + +```php +on(fn () => '这是repeater插件的第一个命令！'); + +$plugin->addBotCommand($cmd1); + +return $plugin; +``` + +然后根据复读的原理（简单重复一遍用户发的消息），将上方 `$cmd1` 替换为下面的指令： + +```php +$cmd1 = BotCommand::make('repeater', match: '复读')->on(function(OneBotEvent $event, BotContext $ctx) { + $ctx->reply($event->getMessage()); +}); +``` + +此后，保存文件。 + +> 借助容器的依赖注入功能，我们可以直接指定相应的类，相关实例会在调用时自动传入。上方的 OneBotEvent 和 BotContext 可以自由选择位置。 ## 启动框架 @@ -65,7 +96,7 @@ class Repeater 启动后，Walle-Q 的日志应当会显示连接成功的信息。 -此时，你可以通过任意账号向机器人发送 `echo 给我复读` 消息，机器人会回复 `给我复读`。 +此时，你可以通过任意账号向机器人发送 `复读 给我复读` 消息，机器人会回复 `复读 给我复读`。 至此，你的第一个功能，复读机，也就开发完成了。 diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 6e0a3527..4d015dc9 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -39,6 +39,9 @@ composer require zhamao/framework ## 安装完成后启动 ./zhamao server + +## 生成新插件脚手架，用于开发 +./zhamao plugin:make ``` ## Windows 安装方法 diff --git a/docs/guide/structure.md b/docs/guide/structure.md index 7bf08183..ed641d85 100644 --- a/docs/guide/structure.md +++ b/docs/guide/structure.md @@ -1,48 +1,36 @@ # 目录结构 -## 根目录 +## 用户目录 -### Config 目录 +### config 目录 `config` 目录包含框架、应用的所有配置文件。最好把这些文件都浏览一遍，并熟悉所有可用的选项。 -### Src 目录 - -`src` 目录包含应用的核心代码，你的大部分工作都将在这里进行。 - -### Tests 目录 - -`tests` 目录通常是你编写 PHPUnit 单元测试和功能测试的地方。你可以使用 `composer test` 运行其中的测试。 - -> 该目录并不自带 -> - -### Vendor 目录 - -`vendor` 目录包含你通过 Composer 安装的所有依赖。 - -## Src 目录 - -你的大多数代码都位于 `src` 目录中。 - -### Globals 目录 - -`globals` 目录包含你的全局定义文件，例如全局函数和常量等。 - -需要注意的是，框架本身并不会为你自动加载其中的文件，你需要自行使用 Composer 自动加载或其他方式加载其中的代码。 - -例如 `Globals/my_functions.php` 可以被添加到 `composer.json` 当中。 - -```json -{ - "autoload": { - "files": [ - "src/Globals/my_functions.php" - ] - } -} +``` +config/ +├── global.php # 全局配置文件 +├── container.php # 容器配置文件 +└── motd.txt # 框架启动时展示的文字信息 ``` -### Module 目录 +### vendor 目录 + +`vendor` 目录包含你通过 Composer 安装的所有依赖，此目录为自动生成，无需操作。 + +### plugins 目录 + +`plugins` 目录包含你编写或加载到源代码模式的插件，里面的插件都会被框架自动扫描并解析，你可以在其中利用注解来注册事件绑定并进行相应处理。 + +比如你通过 `./zhamao plugin:make` 新建了一个名字叫 `test-app` 的插件，并且设置为单文件模式（`file`），那么这个插件内包含的文件及结构为： + +``` +plugins/ +└── test-app/ + ├── main.php # 你的插件源代码文件 + └── zmplugin.json # 插件元信息（如名称、版本等） +``` + +### zm_data 目录 + +`zm_data` 目录存放了框架运行时持久化保存的数据，例如 KV 数据库、驱动日志等内容。 -`module` 目录包含你机器人或是服务的主体代码，其中的所有类都会被框架自动扫描并解析，你可以在其中利用注解来注册事件绑定并进行相应处理。