skill-astrbot-dev

skill-astrbot-dev

このスキルは、AstrBot のプラグインおよびコア開発に関する信頼できるリファレンスです。

メッセージモデル、プラットフォームアダプターのインターフェース、プラグイン設定スキーマ、フック／ライフサイクル、Agent システム（ツール、サブエージェント、ペルソナ、サンドボックス、cron）を扱います。

使用する場面

次の内容についてサポートを求める場合は、このスキルを使用してください。

• AstrBot のプラグイン構造、デコレーター／フック、ライフサイクル、スキーマ、セッション
• メッセージモデル／イベントフローとメッセージチェーンの変換
• プラットフォームアダプターのインターフェースとメッセージ変換のパターン
  • Agent のトピック（ツール／プロバイダー／ペルソナ／サブエージェント／サンドボックス／cron／コンテキスト圧縮）
  • コンテキスト管理（会話ブランチ、履歴操作、コンテキスト注入、圧縮戦略）

必須のワークフロー（毎回使用してください）

1. 単一のエントリーポイントから始めます（広範囲に読み込まないでください）。
   • ワークフローの概要：plugin-development-workflow.md
   • コア概念：design_standards/core_concepts.md
2. 1 つのトピックフォルダーを選び、範囲を絞ります。
   • Agent システム：agent/（agent/index.md から開始）
   • プラグイン設定：plugin_config/
   • メッセージ：messages/
   • プラットフォームアダプター：platform_adapters/
3. Agent Runner（v4.7.0+）については、agent/agent-runner.md を参照します。
4. コンテキスト管理（会話、履歴、圧縮）については、agent/context-management.md を参照します。
5. ユーザーが特定の AstrBot バージョンを指定している場合は、リポジトリのタグと照合します。
   • git -C <astrbot-repo> describe --tags
6. ドキュメントとコードの内容が異なる場合は、コードを正とします。
   • コアコードは astrbotcore/astrbot/core/ 以下にあります（必要なファイルのみを読みます）。

強く推奨：プラグインの作成時に AstrBot SDK を使用する

プラグインコードを作成する際は、AstrBot SDK をローカルにインストールして、API リファレンスの確認、シグネチャの検索、IDE の自動補完に利用することを強く推奨します。

python -m pip install -U astrbot

フック、プロバイダー／コンテキスト呼び出し、Agent Runner との統合を実装する際は、まず SDK のシンボルを使用してください。 これにより、推測やシグネチャの不一致を減らせます。

このリポジトリで AstrBot のソースコードを利用できる場合でも、パッケージのドキュメントよりリポジトリのコードを優先してください。

プラグインプロジェクトの構成（強く推奨）

標準的な AstrBot プラグインプロジェクトには、次のファイルを含めてください。

• main.py：エントリーポイントです。プラグインの起動と主要機能をここに実装します。
• metadata.yaml：プラグインのメタデータ（名前、バージョン、作者、リポジトリ、説明）です。
• README.md：インストール方法、使用方法、機能の概要、開発リンクを記載します。
• .gitignore：Python のキャッシュ（__pycache__）や IDE の設定ファイルを除外します。
• LICENSE：オープンソースライセンスファイルです。

metadata.yaml の最小テンプレート

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 版本范围。

プラグイン実装のコードルール

• ハンドラー／フック／ツール関数には async def を使用します。
• main.py はプラグインのエントリーとオーケストレーションに集中させ、複雑なロジックはサブモジュールに切り出します。
• 公開メソッドとフックのシグネチャには型ヒントを追加します。
• プロバイダー ID やシークレットをハードコードせず、設定可能なフィールドを _conf_schema.json に定義します。
• 大規模で一枚岩のハンドラー本体より、小さくテスト可能な関数を優先します。
• README とメタデータの内容を、実際のプラグインの動作およびバージョンと一致させます。
  • プラグインではなく AstrBot のコアコードを作成している場合、変更にドキュメントの更新（新しいフック、新しい API、新機能、プラットフォームアダプターの変更など）が必要であれば、https://github.com/AstrBotDevs/AstrBot-docs に PR を提出する必要があります。ドキュメントのリポジトリが見つからない場合は、docs-repo をクローンしてワークスペースに追加するようユーザーに伝えてください。 プラグインのディレクトリに requirements.txt ファイルを作成し、必要な依存関係を記載してください。 プラグインのサイズは 32MB 未満に保つのが望ましいです。 高解像度画像などの大きなリソースには、ハードコードするのではなく CDN を使用するのがおすすめです。 古いフックより新しいフックを使用するのがおすすめです。

フック：参照の欠落・古さを防ぐ

混同してはいけない「フック」のレイヤーが2つあります。

• プラグインのイベントフック（デコレーター）：agent/agent-related-hooks.md + design_standards/event_flow.md
• エージェントランナーのフック（BaseAgentRunHooks）：agent/agent-related-hooks.md

フックの完全な一覧が必要な場合（コンテキストが途切れている可能性があるため）は、ローカルで生成してください。

python scripts/generate_hook_inventory.py

これは skill-astrbot-dev/.tmp/hook_inventory/（Gitignore 対象）に書き込みます。ドキュメントの作成・更新時の一時的な作業用として使用してください。 公開ドキュメントの URL として .tmp のパスを参照しないでください。

高シグナルのコードエントリーポイント（必要な場合のみ開く）

• イベントフックの登録とシグネチャ：astrbotcore/astrbot/core/star/register/star_handler.py
• イベントの種類：astrbotcore/astrbot/core/star/star_handler.py
• エージェントランナーとフック呼び出し順：astrbotcore/astrbot/core/agent/runners/
• エージェントフックのインターフェース：astrbotcore/astrbot/core/agent/hooks.py
• メインエージェントの構築（サンドボックス／cron／ツール）：astrbotcore/astrbot/core/astr_main_agent.py
• スキルシステム（AstrBot ランタイムスキル）：astrbotcore/astrbot/core/skills/skill_manager.py
• サブエージェントの設定読み込み：astrbotcore/astrbot/core/subagent_orchestrator.py
• パイプラインのステージ：astrbotcore/astrbot/core/pipeline/（stage_order.py を参照）

v4.5.7+ の新しいツール定義パターン

Tool の定義には dataclass パターンの使用を推奨します（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 パターンを推奨します。

AstrBot は OpenAPI を使用したプロジェクトのデバッグをサポートしています。ユーザーに API キーと AstrBot インスタンスの URL／アドレスを尋ねてください。さらに、OpenAPI のドキュメント全文を [https://docs.astrbot.app/scalar.html](https://docs.astrbot.app/scalar.html) から取得してください。自律的なデバッグに関する追加要件は Guidelines_Testing.md にあります。

AstrBot はプラグイン向けのシンプルな KV ストレージインターフェースを提供しています。設定、軽量な状態、ユーザーデータの保存に最適です。適切な場合は使用を検討してください。 Star を継承したプラグインクラス内で、次のメソッドを直接呼び出します。

• await self.put_kv_data(key: str, value: Any): データを保存します
• await self.get_kv_data(key: str, default: Any = None) -> Any: データを取得します
• await self.delete_kv_data(key: str): データを削除します