AstrBot/docs/v4/api-reference.md

AstrBot SDK v4 API 参考

本文档提供 AstrBot SDK v4 的完整 API 参考。

目录

• 核心概念
• 顶层 API
• 装饰器
• Context 上下文
• MessageEvent 消息事件
• 客户端 API
• 错误处理
• 测试工具

---

核心概念

AstrBot SDK v4 采用协议优先的设计，插件与宿主通过显式协议消息交互：

┌─────────────────┐
│   插件代码       │
├─────────────────┤
│  Context        │  ← 运行时上下文
│  ├─ llm         │  ← LLM 客户端
│  ├─ memory      │  ← 记忆客户端
│  ├─ db          │  ← 数据库客户端
│  └─ platform    │  ← 平台客户端
├─────────────────┤
│  CapabilityProxy│  ← 能力代理
├─────────────────┤
│  Peer           │  ← 对等节点通信
└─────────────────┘

---

顶层 API

从 astrbot_sdk 直接导入的推荐入口：

from astrbot_sdk import (
    Star,           # 插件基类
    Context,        # 运行时上下文
    MessageEvent,   # 消息事件
    AstrBotError,   # 错误类型
    on_command,     # 命令装饰器
    on_message,     # 消息装饰器
    on_event,       # 事件装饰器
    on_schedule,    # 定时任务装饰器
    provide_capability,  # 能力提供装饰器
    require_admin,  # 管理员权限装饰器
)

---

装饰器

@on_command

注册命令处理器。

@on_command(
    command: str,              # 命令名称
    *,
    aliases: list[str] | None = None,    # 命令别名
    description: str | None = None,      # 命令描述
)

示例：

@on_command("hello", aliases=["hi"], description="发送问候")
async def hello(self, event: MessageEvent, ctx: Context):
    await event.reply("Hello!")

@on_message

注册消息处理器，支持正则匹配或关键词匹配。

@on_message(
    *,
    regex: str | None = None,           # 正则表达式
    keywords: list[str] | None = None,  # 关键词列表
    platforms: list[str] | None = None, # 平台过滤
)

示例：

@on_message(regex=r"^ping$")
async def ping(self, event: MessageEvent):
    await event.reply("pong")

@on_message(keywords=["帮助", "help"])
async def help_handler(self, event: MessageEvent):
    await event.reply("这是帮助信息...")

@on_event

注册事件处理器。

@on_event(event_type: str)  # 事件类型

常见事件类型：

• "message" - 消息事件
• "group_join" - 群加入事件
• "group_leave" - 群退出事件
• "friend_add" - 好友添加事件

示例：

@on_event("group_join")
async def on_group_join(self, event: MessageEvent, ctx: Context):
    await ctx.platform.send(event.session_id, "欢迎加入群组！")

@on_schedule

注册定时任务。

@on_schedule(
    *,
    cron: str | None = None,        # Cron 表达式
    interval_seconds: int | None = None,  # 间隔秒数
)

示例：

# 每 60 秒执行一次
@on_schedule(interval_seconds=60)
async def heartbeat(self, ctx: Context):
    await ctx.db.set("last_heartbeat", {"time": "now"})

# 使用 cron 表达式（每天 9 点）
@on_schedule(cron="0 9 * * *")
async def daily_greeting(self, ctx: Context):
    pass

@require_admin

要求管理员权限才能执行。

@require_admin
@on_command("admin")
async def admin_only(self, event: MessageEvent):
    await event.reply("管理员命令已执行")

@provide_capability

声明插件对外暴露的能力。

@provide_capability(
    name: str,                              # 能力名称
    *,
    description: str,                       # 能力描述
    input_schema: dict | None = None,       # 输入 JSON Schema
    output_schema: dict | None = None,      # 输出 JSON Schema
    supports_stream: bool = False,          # 是否支持流式
    cancelable: bool = False,               # 是否可取消
)

示例：

@provide_capability(
    "demo.echo",
    description="回显输入文本",
    input_schema={
        "type": "object",
        "properties": {"text": {"type": "string"}},
        "required": ["text"],
    },
    output_schema={
        "type": "object",
        "properties": {"echo": {"type": "string"}},
    },
)
async def echo_capability(self, payload: dict, ctx: Context, cancel_token):
    return {"echo": payload.get("text", "")}

---

Context 上下文

运行时上下文，提供所有能力客户端。

class Context:
    llm: LLMClient         # LLM 客户端
    memory: MemoryClient   # 记忆客户端
    db: DBClient           # 数据库客户端
    platform: PlatformClient  # 平台客户端
    plugin_id: str         # 插件 ID
    logger: Logger         # 日志器
    cancel_token: CancelToken  # 取消令牌

CancelToken

取消信号，用于处理中断请求。

class CancelToken:
    @property
    def cancelled(self) -> bool  # 是否已取消

    def cancel(self) -> None      # 发送取消信号

    async def wait(self) -> None  # 等待取消

    def raise_if_cancelled(self) -> None  # 如果已取消则抛出异常

示例：

async def long_task(self, ctx: Context):
    for i in range(100):
        ctx.cancel_token.raise_if_cancelled()  # 检查取消信号
        await asyncio.sleep(1)

---

MessageEvent 消息事件

消息事件对象，包含消息信息和操作方法。

class MessageEvent:
    text: str              # 消息文本
    user_id: str | None    # 用户 ID
    session_id: str        # 会话 ID
    group_id: str | None   # 群组 ID（私聊为 None）
    platform: str          # 平台名称
    raw: dict              # 原始消息数据

方法

event.reply()

回复消息。

async def reply(self, text: str) -> None

示例：

await event.reply("收到您的消息！")

event.plain_result()

创建纯文本结果。

def plain_result(self, text: str) -> MessageEventResult

示例：

return event.plain_result("处理完成")

event.to_payload()

转换为字典格式。

def to_payload(self) -> dict[str, Any]

event.session_ref

获取结构化会话引用。

@property
def session_ref(self) -> SessionRef | None

---

客户端 API

LLMClient

详细文档

# 简单对话
reply = await ctx.llm.chat("你好")

# 带历史对话
reply = await ctx.llm.chat("继续", history=[
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！"},
])

# 流式对话
async for chunk in ctx.llm.stream_chat("讲个故事"):
    print(chunk, end="")

DBClient

详细文档

# 读写数据
await ctx.db.set("user:1", {"name": "张三"})
data = await ctx.db.get("user:1")

# 前缀查询
keys = await ctx.db.list("user:")

# 批量操作
await ctx.db.set_many({"a": 1, "b": 2})
values = await ctx.db.get_many(["a", "b"])

MemoryClient

详细文档

# 保存记忆
await ctx.memory.save("user_pref", {"theme": "dark"})

# 语义搜索
results = await ctx.memory.search("用户偏好")

# 精确获取
pref = await ctx.memory.get("user_pref")

PlatformClient

详细文档

# 发送消息
await ctx.platform.send(event.session_id, "你好")

# 发送图片
await ctx.platform.send_image(event.session_id, "https://example.com/img.png")

# 获取群成员
members = await ctx.platform.get_members(event.session_id)

---

错误处理

AstrBotError

统一的错误类型。

class AstrBotError(Exception):
    code: str       # 错误码
    message: str    # 错误消息
    hint: str       # 解决建议
    retryable: bool # 是否可重试

错误码

错误码	说明	可重试
llm_not_configured	LLM 未配置	否
capability_not_found	能力未找到	否
permission_denied	权限不足	否
invalid_input	输入无效	否
cancelled	操作已取消	否
capability_timeout	能力调用超时	是
network_error	网络错误	是

示例：

from astrbot_sdk import AstrBotError

try:
    result = await ctx.llm.chat("hello")
except AstrBotError as e:
    print(f"[{e.code}] {e.message}")
    if e.hint:
        print(f"建议: {e.hint}")

---

测试工具

MockContext

用于单元测试的模拟上下文。

from astrbot_sdk.testing import MockContext, MockMessageEvent

ctx = MockContext(plugin_id="test")
event = MockMessageEvent(text="hello", context=ctx)

# 模拟 LLM 响应
ctx.llm.mock_response("你好！")

# 断言发送内容
await event.reply("测试")
ctx.platform.assert_sent("测试")

PluginHarness

完整的插件测试工具。

from astrbot_sdk.testing import PluginHarness, LocalRuntimeConfig

harness = PluginHarness(
    LocalRuntimeConfig(plugin_dir=Path("my-plugin"))
)

async with harness:
    records = await harness.dispatch_text("hello")
    assert any(r.text for r in records)

---

更多资源

• 快速开始
• LLM 客户端文档
• 数据库客户端文档
• 平台客户端文档
• 记忆客户端文档
• 架构设计