AstrBot 插件开发指南

使用 AI 快速开发 AstrBot 插件的完整指南。

🌐 在线工具：https://86lbs.github.io/astrbot_plugin_dev_guide/

---

🚀 立即开始

使用提示词生成器（推荐）

打开在线工具：https://86lbs.github.io/astrbot_plugin_dev_guide/prompt_generator.html

支持两种模式：

模式	说明	适用场景
🔧 通用模式	描述需求即可生成提示词	学习、开发、优化插件
📖 讲解模式	讲解插件代码原理	理解已有插件

使用步骤：

1. 选择模式（默认：通用模式）
2. 填写需求描述
3. （可选）填写 GitHub Token 用于发布
4. 点击生成提示词
5. 复制发送给 AI

---

🔧 通用模式

适用场景： 学习、开发、优化插件

输入示例：

# 学习
学习 AstrBot 插件开发

# 开发新插件
开发一个天气查询插件，支持 /天气 指令和 LLM Tool 调用

# 优化插件
优化 https://github.com/xxx/my_plugin，添加错误处理

# 理解代码
帮我理解 https://github.com/xxx/my_plugin 的工作原理

AI 会自动：

• 阅读开发指南了解规范
• 参考源码了解 API
• 编写/优化代码
• 进行自我审查
• 发布到 GitHub（如填写 Token）

---

📖 讲解模式

适用场景： 理解已有插件代码

输入示例：

插件仓库：https://github.com/xxx/my_plugin
我的问题：这个装饰器是怎么工作的？

讲解风格：

• 简单易懂（适合新手）
• 详细深入（适合进阶）
• 技术专业（适合开发者）

---

🔑 GitHub Token

何时需要：

• 发布插件到 GitHub 时需要

如何获取：

1. GitHub → Settings → Developer settings → Personal access tokens
2. 生成 Token，勾选 repo 权限
3. 复制到提示词生成器

安全说明：

• Token 仅用于生成提示词，不会被保存
• 重置表单时自动清空

---

📋 配置 Schema 格式

如果插件需要配置项，必须创建 _conf_schema.json 文件，格式如下：

{
    "api_key": {
        "type": "string",
        "description": "API 密钥",
        "default": ""
    },
    "timeout": {
        "type": "int",
        "description": "超时时间（秒）",
        "default": 30
    },
    "enable_feature": {
        "type": "bool",
        "description": "是否启用功能",
        "default": true
    },
    "temperature": {
        "type": "float",
        "description": "温度参数",
        "default": 0.7
    },
    "allowed_users": {
        "type": "list",
        "description": "允许使用的用户列表",
        "default": [],
        "items": {
            "type": "string"
        }
    }
}

支持的类型：

类型	说明	必需字段
string	字符串	type, description, default
int	整数	type, description, default
float	浮点数	type, description, default
bool	布尔值	type, description, default
list	列表	type, description, default, items

list 类型特殊说明：

• 必须添加 items 字段，指定列表元素的类型
• items 是一个对象，包含 type 字段

注意事项：

1. 每个配置项必须包含 type、description、default 三个字段
2. list 类型必须额外包含 items 字段
3. type 必须是上述支持的类型之一
4. 格式错误会导致插件无法加载

---

📁 文件说明

开发指南

文件	说明	推荐度
AGENT_ENTRY.md	Agent 入口文档 - 必读，包含配置格式	⭐⭐⭐⭐⭐
SOURCE_CODE_MAP.md	源码地图 - API 速查表	⭐⭐⭐⭐⭐
SELF_REVIEW.md	自我审查 - 模仿官方审核机器人	⭐⭐⭐⭐⭐
PUBLISH_GUIDE.md	发布指南 - GitHub 发布步骤	⭐⭐⭐⭐⭐
VERSION_MANAGEMENT.md	版本管理指南 - 版本号和更新日志	⭐⭐⭐⭐
MOCK_LLM_SERVER.md	模拟 LLM 服务 - 测试 Tool 无需真实模型	⭐⭐⭐⭐⭐

测试工具

文件	说明
tools/	完整测试工具集
├── mock_llm_server.py	模拟 LLM 服务（测试 Tool）
├── send_message.py	发送消息
├── deploy_plugin.sh	部署插件
└── view_log.sh	查看日志

---

🏗️ 本地测试环境

┌─────────────────────────────────────────────────────────────┐
│                   本地测试环境                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│   │ 模拟消息端  │───▶│  AstrBot    │───▶│ 模拟 LLM    │    │
│   │ (测试脚本)  │    │  (被测系统) │    │ (mock服务)  │    │
│   └─────────────┘    └─────────────┘    └─────────────┘    │
│          │                  │                   │          │
│          └──────────────────┼───────────────────┘          │
│                             ▼                              │
│                      ┌─────────────┐                       │
│                      │   插  件    │                       │
│                      │  (被测试)   │                       │
│                      └─────────────┘                       │
│                                                             │
│   优势：                                                    │
│   ✅ 无需真实 LLM API（省钱）                               │
│   ✅ 无需运行真实模型（省资源）                             │
│   ✅ 无需真实消息平台（简单）                               │
│   ✅ 完全可控可预测                                        │
│   ✅ 可自动化 CI/CD                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

测试 LLM Tool

使用模拟 LLM 服务，无需运行真实的 LLM 模型：

# 启动模拟服务
python tools/mock_llm_server.py

# 配置 AstrBot
# API Base: http://localhost:8000/v1
# API Key: mock-key
# Model: mock-model

详见 MOCK_LLM_SERVER.md

---

🔗 相关链接

• AstrBot 官网
• AstrBot 文档
• AstrBot GitHub
• Ollama 官网 - 本地 LLM 运行

📝 示例插件

使用本指南开发的插件示例：

• 易经算卦插件 - 传统金钱卦起卦法

🤝 贡献

欢迎提交 Issue 和 PR 完善本指南！

📄 许可证

MIT License

Copyright (c) 2025 86lbs

本教程采用 MIT 许可证，你可以自由使用、修改和分发。

注意：使用本教程开发的插件不需要标注来源，开发者可自行决定是否添加致谢。