# Astrbot Plugin Runtime Patching

> QQ parsing bugs, fork drift. Hot-patch AstrBot plugins.

- Skill: `publieople/astrbot-plugin-runtime-patching` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add publieople/astrbot-plugin-runtime-patching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/publieople/astrbot-plugin-runtime-patching/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: publieople (https://skillmd.com/u/publieople)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/publieople/astrbot-plugin-runtime-patching

---


# AstrBot Plugin Runtime Patching

Patch a running AstrBot's plugins without rebuilding the bot. This skill
is for when an installed plugin behaves wrong despite correct config and
the user wants a quick in-place fix (not a full reinstall).

## When to use

- User says "插件 X 不工作了 / 报错了 / 一直说不可用" with logs pointing
  to `astrbot_plugin_<name>`.
- User reports a plugin shows wrong version in the marketplace but the
  upstream repo has moved on (fork drift).
- User's plugin command parses its `args_str` wrong when invoked via QQ
  reply.

## When NOT to use

- The bot itself fails to start (`astrbot` won't come up) — that's an
  AstrBot core / config problem, not a plugin problem.
- The plugin was never installed — go through AstrBot's plugin market
  first.
- The user wants to publish a fix upstream — that's
  `astrbot-plugin-development`; this skill is for local hot-fix only.

## Triage workflow

1. **Localise the failure**: `tail -F /home/po/astrbot/data/logs/astrbot.log`
   (rotated siblings `astrbot.YYYY-MM-DD_HH-MM-SS_xxxxxx.log`). Grep for
   the plugin name and for `ERROR` / `Traceback`. The log line that
   names a strategy / command / config key is the one to read.

2. **Read the plugin source**: `/home/po/astrbot/data/plugins/<name>/`.
   `main.py` is the entry. Each provider / strategy lives in its own
   file (`sauce_nao_strategy.py`, etc.). `metadata.yaml` has the version
   the bot believes is installed. `_conf_schema.json` lists config keys.

3. **Read AstrBot's message adapter** when a command parses wrong:
   `/home/po/.local/share/uv/tools/astrbot/lib/python3.12/site-packages/astrbot/core/platform/sources/aiocqhttp/aiocqhttp_platform_adapter.py`.
   This is where `event.message_str` is built. If your command handler
   sees "message_str contains quoted-message noise", the bug is in
   *your plugin's parser*, not in AstrBot (see references below).

4. **Patch in place**. Use `search_files` to find the right line range
   before `patch`. Don't rewrite the file from scratch — one guard
   in the shared resolver is smaller diff than guards in every caller.

5. **Reload, do not full restart**. WebUI 插件页 → 重载 is enough for
   pure-Python changes. Only `sudo systemctl restart astrbot` if the
   patch changed `metadata.yaml` (AstrBot reads it on startup) or
   dependencies (`requirements.txt`).

6. **Verify**. Re-trigger the failing command once and grep the log for
   the previous error string — if absent, patch landed.

## Pitfalls

- **Plugin version is cached in `data/plugins.json`** (and
  `data/plugins_custom_<md5>.json` for custom registries). The market
  shows the cached version until MD5 mismatches. Restart does not force
  refresh; the MD5 endpoint is `https://api.soulter.top/astrbot/plugins-md5`.
  When upstream is forked and the new owner hasn't pushed to
  `AstrBotDevs/AstrBot_Plugins_Collection`, the cache stays stale forever.
  Workaround: `rm -rf` the plugin dir and `git clone` the new repo, then
  reload.

- **`metadata.yaml` has no `astrbot_version` constraint check at
  runtime** (it's only a market-metadata hint). Patches that depend on
  new AstrBot core APIs need a version check you write yourself.

- **`pip install -r requirements.txt` after a plugin update will trigger
  pip 26.3 deprecation warnings** if the plugin imports `data.plugins.<x>`
  in an order pip doesn't expect. Safe to ignore until pip 26.3 actually
  enforces it. Do not "fix" by changing import paths — that breaks
  AstrBot's plugin loader.

- **Fork reinstalls wipe any in-place patch you made to `main.py`.**
  If you patch and the user later upgrades, re-apply or upstream the
  fix. Mark `ponytail:` comments so future-you knows what was local.

## References

- `references/onebot-reply-messagestr-pollution.md` — exact bug pattern
  for QQ reply-mode command parsing, with the `rfind` + whitelist
  filter fix. Read this when the log shows `未找到策略 '图片 MSG_ID:...`.
- `references/plugin-market-cache-fork-staleness.md` — when plugin
  market stays on old version after the upstream has moved.