mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-16 01:40:15 +08:00

Files

whatevertogo 1fec76eda1 feat: add platform client documentation and examples

- Introduced platform client documentation in `docs/v4/clients/platform.md` detailing methods for sending messages, images, and managing group members.
- Added example plugins for LLM chat and database functionalities in `docs/v4/examples/README.md`, `docs/v4/examples/llm-chat/README.md`, and `docs/v4/examples/database/README.md`.
- Enhanced quickstart guide with links to new documentation and example plugins.
- Implemented runtime contract tests to ensure compatibility of public capabilities and hooks.

2026-03-13 21:09:13 +08:00

3.9 KiB

Raw Blame History

AstrBot SDK v4 Quickstart

这份 quickstart 只覆盖当前已经落地的能力：Star、Context、MessageEvent、astr dev --local、astrbot_sdk.testing。

1. 创建插件目录

现在可以直接生成一个符合当前 loader 契约的骨架：

astrbot-sdk init my-plugin

生成结果大致是：

my-plugin/
├── plugin.yaml
├── requirements.txt
├── main.py
└── tests/
    └── test_plugin.py

如果你想手动创建，目录结构也至少应包含这些文件。requirements.txt 可以先留空。

2. 编写 `plugin.yaml`

name: my_plugin
display_name: My Plugin
desc: 我的第一个 AstrBot SDK v4 插件
author: you
version: 0.1.0
runtime:
  python: "3.12"
components:
  - class: main:MyPlugin

3. 编写 `main.py`

from astrbot_sdk import Context, MessageEvent, Star, on_command


class MyPlugin(Star):
    @on_command("hello")
    async def hello(self, event: MessageEvent, ctx: Context) -> None:
        reply = await ctx.llm.chat("say hello")
        await event.reply(reply)

4. 本地运行

安装当前仓库后，可以直接用本地 mock core 跑插件：

astr dev --local --plugin-dir my-plugin --event-text "hello"

或者：

astrbot-sdk dev --local --plugin-dir my-plugin --event-text "hello"

进入交互模式：

astr dev --local --plugin-dir my-plugin --interactive

交互模式下支持这些元命令：

/session <id> 切换 session
/user <id> 切换 user
/platform <name> 切换 platform
/group <id> 切换为群消息
/private 切回私聊
/event <type> 切换事件类型
/exit 退出

4.1 校验与打包

本地写完插件后，可以先做静态校验，再构建 zip 包：

astrbot-sdk validate --plugin-dir my-plugin
astrbot-sdk build --plugin-dir my-plugin

默认构建产物会写到 my-plugin/dist/。

5. 直接写 handler 单元测试

如果你不想每次都起完整 harness，可以直接用 MockContext 和 MockMessageEvent：

import pytest

from astrbot_sdk.testing import MockContext, MockMessageEvent


@pytest.mark.asyncio
async def test_hello_handler():
    ctx = MockContext(plugin_id="demo")
    event = MockMessageEvent(text="hello", context=ctx)
    ctx.llm.mock_response("你好！")

    async def handler(event, ctx):
        text = await ctx.llm.chat("hello")
        await event.reply(text)

    await handler(event, ctx)

    assert event.replies == ["你好！"]
    ctx.platform.assert_sent("你好！")

6. 用 `PluginHarness` 跑真实插件

如果你想复用真实的 loader / HandlerDispatcher / compat 链路，用 PluginHarness：

import pytest
from pathlib import Path

from astrbot_sdk.testing import LocalRuntimeConfig, PluginHarness


@pytest.mark.asyncio
async def test_plugin_directory():
    harness = PluginHarness(
        LocalRuntimeConfig(plugin_dir=Path("my-plugin")),
    )

    async with harness:
        records = await harness.dispatch_text("hello")

    assert any(item.text for item in records)

7. 更多文档

API 参考 - 完整的 API 文档
LLM 客户端 - 大语言模型调用
数据库客户端 - 数据持久化存储
平台客户端 - 消息发送与群管理
记忆客户端 - 语义搜索存储

示例插件

LLM 对话插件 - AI 对话功能演示
数据库插件 - 数据存储功能演示

8. 当前边界

当前 quickstart 对应的是已经存在的能力，不包含这些后续项：

TODO: 这些功能正在开发中：

ctx.http / ctx.cache / ctx.storage / ctx.i18n
完整宿主调度下的 schedule 执行器

如果你需要查看当前架构与兼容边界，请看 ARCHITECTURE.md。

3.9 KiB Raw Blame History Unescape Escape