skill-astrbot-dev

name	skill-astrbot-dev
description	AstrBot plugin development reference and workflow guide. Use this skill when you are: - Writing AstrBot plugins, hooks, decorators, or message handlers - Implementing platform adapters, message chains, or event flows - Configuring plugin schemas, sessions, or lifecycle management - Working with Agent system (tools, subagents, personas, sandboxes, cron jobs) - Converting between AstrBot message models and platform-specific formats - Looking up AstrBot API signatures, hook inventories, or code entrypoints - Debugging plugin issues related to message routing, event handling, or provider integration Provides reference docs for: messages, platform adapters, plugin config, agent system, and core concepts.
metadata	{"short-description":"AstrBot plugin development reference","version":"4.x","compatibility":"astrbot >=4.16","license":"MIT"}

skill-astrbot-dev

This skill provides the authoritative reference for AstrBot plugin and core development.

It covers message models, platform adapter interfaces, plugin configuration schemas, hooks/lifecycle, and the Agent system (tools, subagents, personas, sandboxes, cron).

When to use

Use this skill when you ask for help with:

• AstrBot plugin structure, decorators/hooks, lifecycle, schema, sessions
• Message model/event flow and message-chain conversion
• Platform adapter interface and message conversion patterns
  • Agent topics (tools/providers/personas/subagents/sandbox/cron/context compression)
  • Context management (conversation branches, history operations, context injection, compression strategies)

Mandatory workflow (use this every time)

1. Start from a single entrypoint (avoid broad loading):
   • Site index: skill-astrbot-dev/index.md
   • Core concepts: skill-astrbot-dev/design_standards/core_concepts.md
2. Pick one topic folder and stay focused:
   • Agent system: skill-astrbot-dev/agent/
   • Plugin config: skill-astrbot-dev/plugin_config/
   • Messages: skill-astrbot-dev/messages/
   • Platform adapters: skill-astrbot-dev/platform_adapters/
3. For Agent Runner (v4.7.0+): skill-astrbot-dev/agent/agent-runner.md
4. If the user targets a specific AstrBot version, cross-check:
   • skill-astrbot-dev/snapshots/<version>/
5. If docs and code disagree, treat code as truth:
   • Core code lives under astrbotcore/astrbot/core/ (read only the needed files)

STRONGLY ADVISED: use AstrBot SDK while writing plugins

When writing plugin code, strongly advised to install AstrBot SDK locally and use it for API reference, signature lookup, and IDE auto-completion.

python -m pip install -U astrbot

Use SDK symbols first when implementing hooks, provider/context calls, and agent runner integration. This helps reduce guesswork and signature mismatch.

If AstrBot source code in this repo is available, still treat repo code as higher priority than package docs.

Plugin project structure (strongly advised)

A standard AstrBot plugin project should include:

• main.py: entrypoint. Implement plugin startup and primary features here.
• metadata.yaml: plugin metadata (name, version, author, repo, description).
• README.md: installation, usage, feature overview, and dev links.
• .gitignore: ignore Python cache (__pycache__) and IDE config files.
• LICENSE: open-source license file.

metadata.yaml minimal template

name: astrbot_plugin_helloworld # 插件唯一识别名，最好以 astrbot_plugin_ 前缀开头
display_name: helloworld # 展示名（v4.5.0+）
desc: AstrBot 插件示例。 # 插件简短描述
version: v1.3.0 # 版本号：v1.1.1 或 v1.1
author: Soulter # 作者
repo: https://github.com/Soulter/helloworld # 插件的仓库地址
astrbot_version: ">=4.16,<5" #声明插件要求的 AstrBot 版本范围。

Code rules for plugin implementation

• Use async def for handlers/hooks/tool functions.
• Keep main.py focused on plugin entry and orchestration; extract complex logic into submodules.
• Add type hints for public methods and hook signatures.
• Do not hardcode provider IDs or secrets; expose configurable fields in _conf_schema.json.
• Prefer small, testable functions over large monolithic handler bodies.
• Keep README and metadata consistent with actual plugin behavior and version. -If you are writing AstrBot core code instead of plugins, you must submit a PR to https://github.com/AstrBotDevs/AstrBot-docs if the changes require doc updates (for instance: new hooks, new APIs, new features, platform adapter changes, and so on). If you don't see the docs repo, please remind the user to clone the docs-repo and add it to the workspace. Ensure that a requirements.txt file is created in the plugin directory and populated with the necessary dependencies. It's best to keep the plugin size under 32MB. For large resources like high-resolution images, it is best to use a CDN instead of hardcoring. It's better to use new hooks instead of old ones.

Hooks: avoid missing / outdated references

There are two different "hook" layers you must not mix up:

• Plugin event hooks (decorators): skill-astrbot-dev/plugin_config/hooks.md
• Agent runner hooks (BaseAgentRunHooks): skill-astrbot-dev/agent/agent-related-hooks.md

If you need a complete hook inventory (because context may be truncated), generate it locally:

python scripts/generate_hook_inventory.py

This writes to skill-astrbot-dev/.tmp/hook_inventory/ (gitignored). Use it as a scratchpad for writing/updating docs; do not reference .tmp paths as public documentation URLs.

High-signal code entrypoints (open only when needed)

• Event hooks registration + signatures: astrbotcore/astrbot/core/star/register/star_handler.py
• Event types: astrbotcore/astrbot/core/star/star_handler.py
• Agent runners + hook call order: astrbotcore/astrbot/core/agent/runners/
• Agent hook interface: astrbotcore/astrbot/core/agent/hooks.py
• Main agent build (sandbox/cron/tools): astrbotcore/astrbot/core/astr_main_agent.py
• Skills system (AstrBot runtime skills): astrbotcore/astrbot/core/skills/skill_manager.py
• Subagents config loading: astrbotcore/astrbot/core/subagent_orchestrator.py

v4.5.7+ New Tool Definition Pattern

推荐使用 dataclass 模式定义 Tool（见 skill-astrbot-dev/design_standards/core_concepts.md 第7节）：

from pydantic.dataclasses import dataclass
from astrbot.api import FunctionTool

@dataclass
class MyTool(FunctionTool):
    name: str = "my_tool"
    description: str = "工具描述"
    parameters: dict = {...}

    async def call(self, context, **kwargs) -> str:
        return "结果"

注册：self.context.add_llm_tools(MyTool())

装饰器方式仍然支持，但推荐新项目使用 dataclass 模式。