astrbot-plugin-development

name	astrbot-plugin-development
description	Build an AstrBot plugin — covers fork-existing vs from-scratch decision, 4-quadrant research gate, doc reading order, decorator mechanics, schema field patterns, ad-hoc verification, CI preflight script. Use when user asks to "做一个 AstrBot 插件" or "集成 X 到 AstrBot" or describes a bot feature.

0. 4-quadrant research gate (BEFORE writing code)

Never start coding without doing all 4 first. User has corrected this twice in one session.

1. YAGNI? — explicitly answer "do we need this at all" in one line. If speculative, push back.
2. Ecosystem has it? — search GitHub + AstrBot official Plugins_Collection (1317 plugins) plugins.json for the feature. gh repo fork X --clone=false to candidate repos.
3. Docs read? — minimum: https://docs.astrbot.app/dev/star/plugin-new.html (skeleton) + plugin-config.html (_conf_schema.json field types). For LLM tools also read en-dev-star-guides-ai wiki.
4. API reality check — if the plugin wraps an external API, curl one real call before writing client code. Public web UIs without documented APIs = reject (do NOT reverse-engineer; will rot).

After all 4, present findings + option list + ask user to pick. Don't write code until they pick.

1. Skeleton (4 files, ~50 lines minimum)

astrbot_plugin_<name>/
├── metadata.yaml         # name, version, author, repo (AstrBot reads this to recognize the plugin)
├── main.py               # @register class(Star) with __init__/initialize/terminate
├── _conf_schema.json     # user-editable config; _conf_schema.json drives WebUI form
├── requirements.txt      # even if deps are already installed (AstrBot reads this)
└── .gitignore            # __pycache__/ + any local cache dirs (imgs/, db.sqlite, etc.)

metadata.yaml template:

name: astrbot_plugin_<name>
display_name: <中文展示名>
desc: <一句中文 desc>
version: v0.1.0
author: <github user>
repo: https://github.com/<user>/astrbot_plugin_<name>

main.py minimum:

from astrbot.api.star import Context, Star, register
from astrbot.api.event.filter import command, llm_tool
from astrbot.api import logger

@register("astrbot_plugin_<name>", "<author>", "<desc>", "v0.1.0", "<repo>")
class MyPlugin(Star):
    def __init__(self, context: Context, config: Optional[dict] = None):
        super().__init__(context)
        self.config = config or {}

    async def initialize(self):
        ...

Image component import: from astrbot.core.message.components import Image (note: NOT from astrbot.api.message_components — that's a re-export, core is the real one).

2. Decoration mechanics — read this before writing commands

Critical constraint: Decorators are scanned at class-load time, not runtime. Cannot register commands in a loop. The class body must contain N literal @command("foo") / @llm_tool(name="bar") decorated methods.

@command("hello")           # registered at import
async def cmd_hello(self, event): ...

@llm_tool(name="my_tool")    # AI may auto-invoke
async def tool_my(self, event, arg: str = ""): ...

For N similar commands (e.g. one per category), if N is large use one @command + alias parser instead of N decorators. Aliases go in a dict[str, str] resolved at runtime.

For _conf_schema.json field types supported: string, text, int, float, bool, object, list, dict, template_list. Special values: select_provider, select_provider_tts, select_provider_stt, select_persona, select_knowledgebase. For multi-select use list with items: {type: "string", options: [...], labels: [...]} (labels show in WebUI as Chinese names). See references/schema-field-patterns.md.

2.1 HARD GATE: modify existing @command signature / add args → load references/command-token-pipeline.md FIRST

This skill already documents every AstrBot command-arg pitfall in detail. Do not patch from memory. When the task is any of:

• Adding a 3rd parameter to an existing command
• Adding optional args (weekday, mode, flags) to existing 1-arg command
• User reports "还是有问题" / "命令没生效" / "参数被吞" / "时间格式错误但我写的对"
• Touching @filter.command/@filter.regex decorator mechanics

→ Before writing the first patch, skill_view(name='astrbot-plugin-development', file_path='references/command-token-pipeline.md'). The reference covers token-pipeline trace, GreedyStr default-value trap, qzone-style self-parse pattern, and @filter.regex not registering as command route.

Symptom of skipping this gate: 3+ rounds of "还是有问题" with each round layering a new workaround on top of the previous (GreedyStr → regex → event.message_str → …) instead of stepping back to the root cause (which the reference already explains). Each round costs the user a sudo systemctl restart astrbot cycle and a Journal audit. If you've already done 2 patches without success, you're not debugging — you're accumulating debt. Stop, load the reference, re-trace.

Flow:

1. skill_view(name='astrbot-plugin-development', file_path='references/command-token-pipeline.md') — read the full reference
2. Trace current handler: event.message_str → AstrBot split → validate_and_convert_params → handler's actual args
3. Pick pattern from the reference's decision tree (qzone-style self-parse is the default)
4. Write patch + ast.parse syntax check + logger.warning(f"DEBUG args={...}") first-run verify
5. Sync to data/plugins/ instance, ask user to restart, wait for them to confirm before claiming done

3. LLM tool function signature

@llm_tool(name="my_tool")
async def tool_my(self, event: AstrMessageEvent, param1: str = ""):
    '''One-line summary.

    Args:
        param1(string): description (type: string|number|object|array|boolean)
    '''
    # process
    return "string result"  # returned to LLM for next turn

Function docstring's Args: block IS the JSON schema AstrBot generates. Missing/wrong format → empty schema, tool won't get called.

3.5 Calling LLM from within a plugin (programmatic, not tool)

Use when you need LLM text generation inside a handler without the LLM itself deciding to invoke a tool.

provider = self.context.get_using_provider()
if not provider:
    return fallback
try:
    resp = await provider.text_chat(
        prompt="Your instruction text here",
        session_id=f"_internal_{some_unique_id}",
        contexts=[],
        model=None,  # optional override
    )
    result = (resp.completion_text or "").strip()
except Exception as e:
    logger.warning(f"LLM call failed: {e}")
    result = fallback

Pitfalls:

• session_id must not collide with real LLM sessions — prefix with _
• contexts=[] is single-turn — correct for translation/classification
• Some providers raise TypeError when model= is passed; catch bare except or try without model
• resp.completion_text may be None — check before .strip()
• AstrBot log may go to stdout when started directly; test via response instead of log files

4. Sending messages

• yield event.plain_result("text") — for text
• yield event.image_result(url) — image from URL (framework downloads to local)
• yield event.chain_result([Image.fromURL(url), Plain("text")]) — mixed

5. Verifying it works

AstrBot logs to systemd journal (NOT to ~/astrbot/logs/ for v4.x). Verify with:

sudo systemctl restart astrbot
sudo journalctl -u astrbot --since '30 seconds ago' --no-pager | grep -iE '<plugin_name>|error|exception|traceback'

Success looks like:

• Loading plugin <plugin_name> ...
• Added llm tool: <tool_name> (if you have one)
• No Traceback after the Loading line

5.1 Hot reload is NOT automatic by default — must restart

AstrBot v4 has no built-in file-watch hot reload for plugins by default. Verified from star_manager.py:210:

if os.getenv("ASTRBOT_RELOAD", "0") == "1":
    asyncio.create_task(self._watch_plugins_changes())

The --reload CLI flag and ASTRBOT_RELOAD=1 env var enable a watchfiles watcher, but:

• Official docs only describe manual reload via WebUI (Plugin page → ... → Reload Plugin)
• systemd service (/etc/systemd/system/astrbot.service) doesn't set ASTRBOT_RELOAD=1 by default
• So in production, every code change requires sudo systemctl restart astrbot to load new code

Don't trust user memory that "plugins auto-reload on edit" — verify:

systemctl show astrbot.service | grep -i Environment=
# If Environment= lacks ASTRBOT_RELOAD=1, no watcher is running.

Enable hot reload once for development:

sudo systemctl edit astrbot
# Add:
#   [Service]
#   Environment="ASTRBOT_RELOAD=1"
sudo systemctl daemon-reload
sudo systemctl restart astrbot

Then on plugin code save, AstrBot logs 检测到插件 <name> 文件变化，正在重载... and reloads automatically.

6. Ad-hoc verification (after building, before claiming done)

System requires this. Create /tmp/hermes-verify-<plugin>.py with checks for:

• metadata.yaml: name, version, author, repo
• _conf_schema.json: expected fields, correct defaults
• main.py: ast.parse, decorator presence (walk FunctionDef + ClassDef — @register is on the class), all expected methods defined
• Live external API call (if applicable): real HTTP, real key, real test image
• Repo hygiene: requirements.txt present, .gitignore covers pycache, no stray test scripts in /tmp

Run with the venv that has the plugin's deps: ~/.local/share/uv/tools/astrbot/bin/python3 (system python lacks httpx/aiohttp).

Delete the script after it passes. State as "ad-hoc verification, 1-shot, deleted" — never claim "fully verified".

6.1 CI-style preflight script — mirror GitHub Actions before pushing

Don't push blind and wait 2 min for CI to fail. Mirror the GitHub Actions CI workflow locally:

bash templates/ci-preflight.sh            # in plugin repo root
bash templates/ci-preflight.sh --keep-venv # keep venv if you want to poke at failures

The script creates a fresh /tmp/.venv-astrbot-preflight-$$, installs requirements.txt (including astrbot from PyPI — v4.26.5+), then runs ruff check . → ruff format --check . → mypy src main.py → pytest -q in sequence. Exits non-zero on first failure. Cleans up the venv on exit unless --keep-venv.

Why this works when direct python -m pytest doesn't: pytest in plugin tests imports astrbot.api (and astrbot_plugin_x package, which uses astrbot.core.star). The plugin's venv doesn't have these. AstrBot IS on PyPI (pip installable since v4.20+) — pip install -r requirements.txt includes it. Standalone git clones fail without this. The preflight script sidesteps the issue entirely.

If CI fails but preflight passed: mismatch between local ruff/mypy/pytest versions and CI pinned versions. Pin in requirements-dev.txt or just trust the preflight and iterate via CI (slower but matches reality).

ruff format must run on whole project, not just changed files — CI runs ruff format --check . and ruff check . against the whole repo. Local ruff format main.py may pass while tests/test_foo.py violates line-length and breaks CI. The preflight script catches this.

6.2 The "still failing after N patches" brake

If you've made 2 patches and the user is still reporting issues, STOP patching. Three-step recovery:

1. Add logger.warning(f"DEBUG raw={event.message_str!r} tokens={tokens!r}") at handler entry.
2. Sync to data/plugins/, ask user to restart and re-trigger.
3. Read journal output, trace the actual values, then patch.

Brain-patching the parser layer when you don't know what tokens the handler receives is gambling with the user's restart cycles. Real example: this skill's parent conversation added weekday parsing 4 times across GreedyStr → regex → event.message_str → reverse-scan variants before a debug print would have shown [MSG_ID:1744020215] was in the tail. One debug print would have saved 3 rounds.

7. Git workflow (when publishing to fork)

gh repo fork <upstream> --clone=false   # creates fork + auto-adds 'upstream' remote
cd ~/astrbot/data/plugins/<name>
gh repo clone <user>/<name>              # clone the fork (not upstream)
git remote -v                            # confirm: origin = fork, upstream = original

Add .gitignore for __pycache__/, *.pyc, and any local cache dirs (imgs/, *.db, etc.) BEFORE first commit or pycache gets committed.

7.1 Updating an existing PR (no new PR needed)

When you have an existing open PR from a fork to upstream, and you want to add more changes:

# Clone the fork's specific branch (not main)
gh repo clone <user>/<repo> -- --branch <feature-branch>

# Edit files, commit
git add .
git commit -m "feat: description"
git push origin <feature-branch>

GitHub auto-updates the open PR. No new PR needed, no force-push required on a solo branch.

Clone tip: gh repo clone publieople/astrbot_plugin_bangumi -- --branch feat/post-subscribe-broadcast-fill correctly sets origin to the fork and upstream to the original repo, with the branch already checked out.

7.2 Process verification before claiming done

Calling work done after "check + push + PR update" needs a final process check: have I loaded and followed all relevant skills? If the user says "检查流程规范" or hints at process, re-scan available skills for workflow/process skills before responding.

7.3 PR title/body updates use gh pr edit

gh pr create on an existing PR returns "already exists". To change title/body of an open PR: gh pr edit <num> --title "..." --body "...". PR head SHA changes (after force-push) sync to the PR automatically — verify with gh pr view <num> --json headRefOid --jq .headRefOid.

8. Publishing to the AstrBot Plugin Marketplace

Once built and tested, submit so other users can install from the marketplace.

Submission flow (mid-2026)

1. Ensure code on GitHub — publieople/astrbot_plugin_<name>
2. Go to https://plugins.astrbot.app → click + (bottom-right blue FAB)
3. Fill form (see fields below) → tags use a separate + button, not Enter
4. Click Submit to GITHUB → redirects to AstrBotDevs/AstrBot_Plugins_Collection with a pre-filled Issue
5. Verify the Issue JSON has correct fields → check all 3 checkboxes → click Create

Old method (deprecated): Submitting Issues on the AstrBot main repo is no longer used.

Issue template JSON (must be exact, from PLUGIN_PUBLISH.yml)

{
  "name": "astrbot_plugin_<name>",
  "display_name": "可读的展示名",
  "desc": "插件简介",
  "author": "publieople",
  "repo": "https://github.com/publieople/astrbot_plugin_<name>",
  "tags": ["AI", "图像检测", "安全"],
  "social_link": ""
}

Notes:

• repo MUST NOT end with .git — CI's normalize_repo_url() explicitly strips .git and validates against GitHub
• tags is optional but strongly recommended for discoverability in the marketplace
• social_link is optional (e.g. personal site, GitHub profile)

Checkboxes (all required)

1. My plugin has undergone thorough testing.
2. My plugin does not contain malicious code.
3. I have read and agree Code of Conduct.

AstrBot Plugin Marketplace form fields (from plugins.astrbot.app SPA)

Field	Type	Required	Note
插件名	text	✅	Must start with astrbot_plugin_
展示名称	text	✅	Human-readable name
插件描述	textarea	✅	Brief intro
作者名	text	❌	GitHub username
社交链接（可选）	text	❌	e.g. GitHub profile URL
插件仓库链接	text	❌	Full GitHub repo URL
标签	tag-input	❌	Type tag, click blue + button

Browser interaction notes (plugins.astrbot.app SPA)

The form is a Vuetify (Vue 3) SPA. When using browser tooling:

• Navigate to root / first — /publish or /submit show an empty shell
• Page may appear blank while JS loads; wait for snapshot/vision to confirm rendered
• Click the bottom-right + (blue FAB) to open the form dialog
• Tag input: type tag name → click separate blue + button (not Enter). Repeat per tag
• Ref IDs shift after each interaction (Vue re-render); re-snapshot before each click
• Submit redirects to GitHub sign-in page (pre-filled Issue behind auth); user must be logged in to complete

What CI validates (from scripts/validate_plugins/run.py)

Stage	What it checks	Failure reason
repo_url	URL must be https://github.com/*/*, no .git suffix	malformed URL
git clone	Clones the repo (--depth 1, 120s timeout). Must be public & accessible.	404, private, network error
metadata check	metadata.yaml must exist. Required fields: name, desc, version, author. No merge conflict markers. Must have main.py or {name}.py.	missing/wrong fields, missing entrypoint
worker load	Copies plugin dir into data/plugins/, calls PluginManager.load(specified_dir_name=...) in a sandbox. AstrBot's requirements.txt is pre-installed.	import error, @register failure, missing dependency
zip size	Generated zip must be ≤ 16MB	oversized; clean .gitignore of __pycache__, .git, node_modules

Key: the worker literally clones your repo, copies the plugin into AstrBot's data/plugins/, and imports it. If import astrbot_plugin_xxx fails in a clean AstrBot env, the CI rejects it.

Marketplace metadata (from scripts/transform_plugin_data/run.py)

After the Issue passes CI, a cron job (transform-plugin-data.yml, hourly) builds the marketplace cache by:

1. GitHub API: fetches stars, last updated, default branch for each plugin repo
2. metadata.yaml on GitHub: extracts version, astrbot_version (optional), support_platforms (optional)
3. logo.png from repo root: if present, shown as the plugin card icon

So logo.png is optional but makes your plugin look better in search results.

metadata.yaml checklist (for marketplace discoverability)

name: astrbot_plugin_<name>         # required — matches dir name
display_name: <中文展示名>           # recommended — shows in WebUI
desc: <一句 desc>                    # required
version: v0.1.0                     # required — read by marketplace
author: <github user>               # required
repo: https://github.com/...        # required — NO .git suffix
tags: [AI, 图像检测, 安全]          # recommended for discoverability
astrbot_version: ">=4.0.0"         # optional — AstrBot version compatibility
support_platforms:                  # optional — supported IM platforms list
  - qq
  - telegram

Pitfalls (from real sessions)

• @register lives on the class, not the function. AST checkers that only walk FunctionDef will miss it.

• config.get(key, default) is fine for config — config is a dict, not a typed object.

• Don't reverse-engineer web UIs (e.g. isgen.ai has no public API; reverse-engineering is fragile).

• Per-generator / per-model scores from third-party APIs are often not available on free tier — don't pretend they are.

• Use httpx not requests (AstrBot's own modules use aiohttp; httpx is simpler for one-shot async calls).

• event.unified_msg_origin is the per-session key for cooldown / rate-limiting / per-user state.

• Image component fields: Image.url/file/path are ALL local temp paths (AstrBot downloads images before delivery). For external APIs, upload the file via multipart — see references/common-bugs.md.

• Version number: only in metadata.yaml — do NOT manually sync the version string in @register(...) decorator with metadata.yaml. Keep both the same but only bump in metadata.yaml after a release; @register's desc field describes the plugin, it's not a version authority.

• Repo URL cannot end with .git — CI's normalize_repo_url() explicitly strips .git suffix, so https://github.com/user/name (no .git) is the canonical form. This applies to both metadata.yaml and the Issue JSON.

• Duplicate import aiofiles — AstrBot v4 bundles aiofiles>=25.1.0 (confirmed from requirements.txt), so import aiofiles at module level works fine. Don't also re-import inside the function body where it's used — one import at the top is enough. More generally, don't inline-import deps that are already imported at module level or known to be in AstrBot's bundled deps.

• Test env dependency — Plugin tests (pytest) depend on AstrBot runtime packages (aiohttp, pydantic, sqlalchemy, astrbot core). Running from a standalone git clone's will fail with . Either run from the AstrBot install dir's venv or install deps manually. Use (§6.1) which auto-installs from PyPI alongside the plugin's .