skill-astrbot-dev

skill-astrbot-dev

此技能提供 AstrBot 插件和核心开发的权威参考。

内容涵盖消息模型、平台适配器接口、插件配置架构、钩子／生命周期，以及 Agent 系统（工具、子 Agent、角色设定、沙箱、定时任务）。

适用场景

在以下情况寻求帮助时，请使用此技能：

• AstrBot 插件结构、装饰器／钩子、生命周期、架构、会话
• 消息模型／事件流和消息链转换
• 平台适配器接口和消息转换模式
  • Agent 相关主题（工具／提供方／角色设定／子 Agent／沙箱／定时任务／上下文压缩）
  • 上下文管理（对话分支、历史记录操作、上下文注入、压缩策略）

强制工作流程（每次都遵循）

1. 从单个入口开始（避免广泛加载）：
   • 工作流概览：plugin-development-workflow.md
   • 核心概念：design_standards/core_concepts.md
2. 选择一个主题文件夹并专注于此：
   • 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，而不是硬编码到项目中。 最好使用新的钩子，而不是旧钩子。

钩子：避免引用缺失或过时

有两种不同的“钩子”层，切勿混淆：

• 插件事件钩子（装饰器）：agent/agent-related-hooks.md + design_standards/event_flow.md
• Agent 运行器钩子（BaseAgentRunHooks）：agent/agent-related-hooks.md

如果需要完整的钩子清单（因为上下文可能被截断），请在本地生成：

python scripts/generate_hook_inventory.py

这会写入 skill-astrbot-dev/.tmp/hook_inventory/（已加入 gitignore）。请将其用作编写或更新文档时的临时参考； 不要将 .tmp 路径作为公开文档 URL 引用。

高价值代码入口（仅在需要时打开）

• 事件钩子注册与签名：astrbotcore/astrbot/core/star/register/star_handler.py
• 事件类型：astrbotcore/astrbot/core/star/star_handler.py
• Agent 运行器与钩子调用顺序：astrbotcore/astrbot/core/agent/runners/
• Agent 钩子接口：astrbotcore/astrbot/core/agent/hooks.py
• 主 Agent 构建（沙箱/定时任务/工具）：astrbotcore/astrbot/core/astr_main_agent.py
• 技能系统（AstrBot 运行时技能）：astrbotcore/astrbot/core/skills/skill_manager.py
• 子 Agent 配置加载：astrbotcore/astrbot/core/subagent_orchestrator.py
• 流水线阶段：astrbotcore/astrbot/core/pipeline/（参见 stage_order.py）

v4.5.7+ 新工具定义模式

推荐使用 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): 删除数据