From c7ce87c15f22d5821d0b6ebea07e066134a2fe0c Mon Sep 17 00:00:00 2001
From: Junyan Qin <rockchinq@gmail.com>
Date: Mon, 6 Jan 2025 20:47:56 +0800
Subject: [PATCH] doc: comments for LangBot python api

---
 docs/plugin/dev/api-ref.md | 77 +++++++++++++++++++++++++++++++++++---
 1 file changed, 71 insertions(+), 6 deletions(-)

diff --git a/docs/plugin/dev/api-ref.md b/docs/plugin/dev/api-ref.md
index 70307af43..cf0d042ed 100644
--- a/docs/plugin/dev/api-ref.md
+++ b/docs/plugin/dev/api-ref.md
@@ -4,14 +4,14 @@
 [[toc]]
 :::
 
-以下 API 仅针对 事件插件 可用，组件扩展形式请自行阅读源码。
+## 事件 API
 
-## 消息处理
+以下 API 仅在事件处理函数中可用。
 
 ### 回复消息
 
 ```python
-ctx.reply(message_chain: MessageChain)
+await ctx.reply(message_chain: MessageChain)
 ```
 
 回复此次事件的发起会话。
@@ -23,7 +23,7 @@ ctx.reply(message_chain: MessageChain)
 > 由于 QQ 官方 API 对主动消息的支持性很差，故若用户使用的是 QQ 官方 API，发送主动消息可能会失败
 
 ```python
-ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
+await ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
 ```
 
 发送主动消息给目标。
@@ -32,8 +32,6 @@ ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
 - `target_id`：目标 ID（QQ 号或群号）
 - `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
 
-## 事件处理
-
 ### 阻止事件默认行为
 
 ```python
@@ -57,3 +55,70 @@ ctx.add_return(name: str, value: Any)
 ```
 
 添加返回值，事件返回值均为**可选**的，每个事件支持的返回值请查看`pkg.plugin.events`中的每个事件的注释。
+
+## LangBot API
+
+以下 API 是 LangBot 直接提供给插件调用的，可以在事件处理函数之外调用。
+
+- `host` 表示 `pkg.plugin.context.APIHost` 类的对象，会被包含在每个插件类中。
+
+### 获取已启用的消息平台适配器列表
+
+```python
+host.get_platform_adapters()
+```
+
+获取已启用的消息平台适配器列表。
+
+- 返回值：`list[pkg.platform.adapter.MessageSourceAdapter]`
+
+### 发送主动消息
+
+```python
+await host.send_active_message(adapter: pkg.platform.adapter.MessageSourceAdapter, target_type: str, target_id: str, message_chain: MessageChain)
+```
+
+发送主动消息给目标。
+
+- `adapter`：消息平台适配器，通过 `host.get_platform_adapters()` 获取并选择其中一个
+- `target_type`：目标类型，可选值：`"person"`、`"group"`
+- `target_id`：目标 ID（QQ 号或群号）
+- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
+
+:::info
+- 某些消息平台可能不支持主动消息，或有严格限制
+- 某些消息平台适配器（例如`aiocqhttp`）是作为服务端等待消息平台连接上来推送消息，在连接成功之前，发送主动消息会失败
+:::
+
+示例：
+
+```python
+import asyncio
+import pkg.platform.types as platform_types
+
+...
+
+    # 某个插件的 initialize 函数
+    # 此代码将在 LangBot 启动 10 秒后尝试向 QQ 号 1010553892 发送消息 "hello, world!"
+    async def initialize(self):
+        print(self.host.get_platform_adapters())
+        
+        async def send_message():
+            print("send message start waiting")
+            await asyncio.sleep(10)
+
+            try:
+                await self.host.send_active_message(
+                    adapter=self.host.get_platform_adapters()[0],
+                    target_type="person",
+                    target_id="1010553892",
+                    message=platform_types.MessageChain([
+                        platform_types.Plain("hello, world!")
+                    ])
+                )
+            except Exception as e:
+                traceback.print_exc()
+            print("send message end")
+
+        asyncio.get_running_loop().create_task(send_message())
+```
\ No newline at end of file