AstrBot SDK

优雅、安全、强大的机器人插件开发框架

AstrBot SDK 是一个基于 Python 3.12+ 的插件开发框架，采用进程隔离和能力路由架构，让插件崩溃不影响系统稳定，支持流式 LLM、语义记忆、跨平台消息收发。

---

核心特性

特性	说明
进程隔离	兼容插件一个worker独立进程运行，单个插件崩溃只影响崩溃插件的worker中的兼容插件使用
能力路由	显式声明能力(Capability)，支持 JSON Schema 验证和流式调用
内置 AI	集成 LLM 对话、语义记忆、知识库等 AI 能力
跨平台	统一 API 支持多平台消息收发（QQ、微信等）
类型安全	Pydantic 模型 + 类型注解，IDE 友好

---

分层架构

┌────────────────────────────────────────────────────────────┐
│                    插件开发者 API                          │
│   Star, Context, MessageEvent, 装饰器, 过滤器            │
└──────────────────────┬─────────────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────────────┐
│                    高层客户端 API                          │
│   ctx.llm.chat() / ctx.memory.save() / ctx.db.set()       │
└──────────────────────┬─────────────────────────────────────┘
                       │ CapabilityProxy
┌──────────────────────▼─────────────────────────────────────┐
│                   运行时 & 协议层                          │
│   HandlerDispatcher / CapabilityRouter / Peer / Transport  │
└──────────────────────┬─────────────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────────────┐
│                   AstrBot sdk_bridge                │
└────────────────────────────────────────────────────────────┘

关键概念：

• Star: 插件基类，所有插件都继承它
• Context: 运行时上下文，提供 llm、memory、db、platform 等客户端
• Capability: 能力，插件能做的事情（如 llm.chat、platform.send）
• Handler: 处理器，响应命令/消息的函数

---

快速开始

安装

pip install astrbot-sdk

初始化插件

# 生成插件骨架
astr init my-plugin

# 生成骨架 + AI 辅助开发配置（可选）
astr init my-plugin --agents claude,codex

astr init <name> 会生成插件骨架，并默认附带根级 AGENTS.md / CLAUDE.md 开发说明。传入 --agents 时，会在新插件目录下额外生成对应的项目级 agent 目录：

• Claude Code: .claude/skills/astrbot-plugin-dev/
• Codex: .agents/skills/astrbot-plugin-dev/
• OpenCode: .opencode/skills/astrbot-plugin-dev/

--agents 仅支持 claude、codex、opencode，使用逗号分隔；重复值会去重，非法值会直接报错。

第一个插件

# main.py
from astrbot_sdk import Star, Context, MessageEvent
from astrbot_sdk.decorators import on_command, on_message

class MyPlugin(Star):
    @on_command("hello", aliases=["hi"])
    async def hello(self, event: MessageEvent, ctx: Context):
        """打招呼命令"""
        await event.reply(f"你好，{event.sender_name}!")

    @on_message(keywords=["帮助"])
    async def help_handler(self, event: MessageEvent, ctx: Context):
        """关键词触发"""
        await event.reply("可用命令: /hello")

# plugin.yaml
_schema_version: 2
name: my_plugin
author: your_name
version: 1.0.0
components:
  - class: main:MyPlugin

常用功能

# LLM 对话
reply = await ctx.llm.chat("你好")
async for chunk in ctx.llm.stream_chat("讲故事"):
    print(chunk)

# 数据存储
await ctx.db.set("user:123", {"name": "Alice"})
data = await ctx.db.get("user:123")

# 语义记忆（需要 embedding provider）
await ctx.memory.save("pref", {"theme": "dark"})
results = await ctx.memory.search("用户喜欢什么")

# 发送消息
await ctx.platform.send(event.session_id, "消息内容")
await ctx.platform.send_image(event.session_id, "https://example.com/img.jpg")

---

我该看哪篇文档？

你的目标	推荐文档
刚开始写第一个插件	事件与组件 → 装饰器
想了解所有可用的客户端方法	常用客户端速查
插件需要生命周期钩子（启动/停止）	Star 生命周期
处理错误、调试问题	错误处理与调试
并发、性能、安全最佳实践	高级主题
写测试	测试指南
从旧版迁移	迁移指南
查完整 API 签名	客户端 API 参考
了解架构设计	架构文档

---

文档目录

入门（初级）

文档	内容
Context API	Context 类完整参考
事件与组件	MessageEvent 和消息组件使用
装饰器	所有装饰器详细说明
Star 生命周期	插件基类和生命周期钩子
常用客户端	LLM/Memory/DB/Platform 快速上手

进阶（中级）

文档	内容
错误处理	错误体系、处理模式、调试技巧
高级主题	并发、性能、安全、架构模式
测试指南	单元测试、集成测试、Mock 使用

参考（高级）

文档	内容
API 索引	所有导出类和函数入口
客户端 API	17 个客户端完整签名和示例
迁移指南	从旧版本迁移
安全清单	安全开发检查清单
架构文档	SDK 架构设计

---

开发

# 开发安装
pip install -e .

# 运行测试
python -m pytest tests -q

# 代码格式化
ruff format .
ruff check . --fix

---

相关资源

• AstrBot 主项目: https://github.com/AstrBotDevs/AstrBot
• Python 版本: >= 3.12
• SDK 版本: v4.0
• 协议版本: P0.6