一个为 AstrBot 设计的自定义插件模板，基于官方基础模板扩展而来。当前版本主要补充了更完整的仓库工程化配置、社区协作文件、自动化工作流，以及更完善的插件元数据示例，适合作为个人或团队维护 AstrBot 插件仓库时的起始模板。

使用这个模板，让你的 AI 能产出更多应用了 AstrBot 新特性的插件代码！

• ✨ 功能特性
• 📊 输出示例
• 🚀 安装与使用
• 📋 指令说明
• ⚙️ 配置项详解
• 📂 插件目录与结构
• 🏗️ 架构说明
• ❓ 常见问题
• 🚧 已知限制
• 📄 许可证

开发者的话：

大家好，我是 DBJD-CR，这是我为 AstrBot 改的一个插件模板，如果存在做的不好的地方还请理解。

和我写的其他插件一样，本插件模板也是"Vibe Coding"的产物。

所以，本插件的所有文件内容，全部由 AI 编写完成，我几乎没有为该插件编写任何一行代码，仅进行了架构设计与修改部分文字描述和负责本文档的润色。所以，或许有必要添加下方的声明：

相较于官方基础模板，本插件模板当前新增或调整了以下内容：

本模板的 main.py 以最小实现演示了 AstrBot 插件常用的核心能力，方便新开发者"开箱即学"：

• 基础指令：演示配置读取与富媒体消息链（At + Plain）。
• 指令组与带参指令：演示指令组组织方式与自动参数解析。
• 权限过滤：演示仅管理员可用的指令。
• 主动消息：演示通过 unified_msg_origin 向任意会话推送消息。
• KV 存储：演示插件维度的 put_kv_data / get_kv_data。
• 大文件存储规范：演示将大文件存放于 data/plugin_data/<plugin_name>/ 目录。
• 文转图：演示 HTML + Jinja2 模板渲染图片。
• 会话控制：演示多轮交互（@session_waiter）。
• 调用 AI：演示调用当前会话的聊天模型。
• LLM 工具：演示通过 @filter.llm_tool 注册工具供模型调用。
• 钩子示例：演示 AstrBot 提供的事件钩子能力。
• 插件 Pages：演示在 WebUI 内嵌页面并通过 bridge 与后端 API 通信。
• 插件配置：提供可视化配置，支持 string/int/bool/object/list、滑块（slider）、下拉选项（options）与 _special 特殊渲染（模型/TTS/STT 提供商、人格、知识库选取）等类型。
• 插件国际化：提供中英文翻译资源，覆盖插件名、描述、配置项与 Pages 文案。

• 完整重写的 README 展示结构：新增 Socialify 封面、状态徽章、访问计数、快速导航、开发者说明、友情链接、推荐阅读、仓库状态与 Star 历史等更完整的仓库首页展示内容。
• 更适合二次分发的文档骨架：为安装、指令、配置、目录结构、架构说明、常见问题、已知限制等章节预留了更清晰的模板化占位结构，方便后续按真实插件内容补全。
• 补充 metadata.yaml 元数据：插件标识改为 astrbot_plugin_helloworld 前缀形式，并同步调整展示名、短描述、描述、作者、仓库地址、版本信息、AstrBot 版本约束与支持平台列表，作为更贴近实际发布场景的参考写法。
• 改为以 metadata.yaml 作为主要元数据来源：在 main.py 中移除了 register() 装饰器写法，仅保留基于插件类的实现方式，使模板结构与当前元数据文件协同。
• 新增贡献指南 CONTRIBUTING.md：补充了 Issue 使用说明、代码贡献流程、代码风格要求、提交规范与文档贡献说明。
• 新增更新日志 CHANGELOG.md：提供标准化版本记录文件，便于后续按发布节奏维护变更历史。
• 新增社区协作文件：补充 CODE_OF_CONDUCT.md、PULL_REQUEST_TEMPLATE.md 与多种 GitHub Issue 模板，覆盖 Bug、功能建议、文档建议、设计建议与开放讨论等协作场景。
• 新增 Dependabot 配置：通过 dependabot.yml 为 GitHub Actions 与 Python 依赖提供定期更新检查能力。
• 新增 Ruff 质量工作流：通过 ruff-format.yml 增加格式化、自动修复、质量报告与 PR 评论能力，用于改进模板仓库的代码规范体验。固定使用 0.14.2 版本。
• 新增长期未活跃 Issue 清理工作流：通过 stale.yml 自动标记和关闭长期无活动 Issue，减少仓库维护负担。
• 新增自动发布工作流：通过 release.yml 在 metadata.yaml 的版本号发生变更后自动提取版本信息、检查是否已有同名 Release，并尝试结合 CHANGELOG.md 生成发布说明，用于简化插件的版本发布流程。
• 新增“屎山检测”工作流：通过 shit-mountain.yml 集成额外的趣味化代码质量分析流程，作为仓库 CI 展示和风格化管理的一部分。
• 新增仓库展示资源与脚本：增加 assets/ 下的可视化徽图资源，以及 Windows 环境下可直接运行的 run_ruff.bat 脚本，方便本地维护。

整体上，这个模板已经不再只是官方示例的最小复制，而是一个偏向"可直接拿去改造成个人仓库"、同时覆盖 AstrBot 插件核心能力的增强版起始模板。

• /helloworld：@你 Hello, 用户名~
• /demo echo 你好：你说了：你好
• /demo todo 吃饭,睡觉,写插件：渲染并发送一张待办清单图片
• /demo guess：进入猜数字多轮会话，机器人提示"大了/小了/猜对啦"
• /demo ask 你好：调用当前会话的聊天模型并返回回复
• /demo data：插件数据目录: .../data/plugin_data/astrbot_plugin_helloworld
• /demo admin：仅管理员可用，返回当前平台名

1. 下载插件: ~~通过 AstrBot 的插件市场下载。~~或从本 GitHub 仓库的 Release 下载 astrbot_plugin_helloworld 的 .zip 文件，在 AstrBot WebUI 中的插件页面右下角的 ➕ 选择 从文件安装。

2. 安装依赖: 本插件的核心依赖为 None，插件下载安装时会自动安装插件所需的依赖，通常无需额外安装。如果你的环境中确实缺少相关依赖，请安装：

   pip install -r requirements.txt

3. 重启 AstrBot (可选): 如果插件没有正常加载或生效，可以尝试重启你的 AstrBot 程序。

4. 配置插件: 进入 AstrBot WebUI，找到 AstrBot 插件模板 插件，选择 插件配置 选项，配置相关参数。

AstrBot 提供的事件钩子用于拦截全局消息 / LLM 请求。事件钩子不能与指令装饰器（command/command_group 等）共用，且部分钩子内部不能使用 yield 发送消息，需改用 event.send()。

本插件在 AstrBot WebUI 中提供了一套结构清晰的可视化配置体系，覆盖基础行为、AI 联动与平台资源选取。 您可以在 AstrBot 管理面板的"插件配置"中直接编辑，无需修改代码。

{
  "greeting": "Hello",        // 默认问候语
  "count_limit": 10,          // 计数器上限（1~20，滑块）
  "mode": "fast",             // 运行模式（快速 / 安全）
  "tags": []                  // 自定义标签列表
}

{
  "advanced": {
    "ratio": 0.5             // 比例（0~1，滑块）
  }
}

{
  "ai_provider": "",         // 聊天模型提供商（select_provider）
  "tts_provider": "",        // TTS 提供商（select_provider_tts）
  "stt_provider": "",        // STT 提供商（select_provider_stt）
  "persona": "",             // 人格（select_persona）
  "knowledgebase": []        // 知识库，支持多选（select_knowledgebase）
}

{
  "enable_ai": true,             // 是否启用 AI 相关指令
  "enable_decorate": false,      // 是否在回复末尾追加感叹号（演示钩子）
  "enable_waiting_hint": false   // LLM 响应前是否发送提示（演示钩子，默认关）
}

AstrBot/
└─ data/
   └─ plugins/
      └─ astrbot_plugin_helloworld/
         ├─ .astrbot-plugin/                # 插件国际化资源
         │  └─ i18n/                        # 语言文件（zh-CN / en-US）
         ├─ .gitignore                      # Git 忽略规则
         ├─ _conf_schema.json               # AstrBot WebUI 配置界面 schema 定义
         ├─ CHANGELOG.md                    # 插件更新日志
         ├─ CONTRIBUTING.md                 # 本插件的贡献指南
         ├─ LICENSE                         # 许可证文件
         ├─ main.py                         # 插件主入口文件（能力演示）
         ├─ metadata.yaml                   # 插件元数据信息
         ├─ pages/                          # 插件 Pages（WebUI 内嵌页面）
         │  └─ demo/                        # 演示页：index.html / app.js / style.css
         ├─ README.md                       # 插件说明文档
         ├─ requirements.txt                # 插件依赖声明（本模板无第三方依赖）
         ├─ run_ruff.bat                    # Ruff 一键格式化与自动修复脚本
         │
         └─ assets/                         # README / 仓库展示资源

示例架构说明。

Socialify；仓库地址

MoeCounter；仓库地址

Repobeats

都是免费的哦。

要在你自己的仓库使用此模板，请修改以下文件的内容为你的实际情况 (主要是涉及仓库链接、徽章资源、发布流程与文档格式的替换)：

• PULL_REQUEST_TEMPLATE.md
• ShitMountain.svg 等 SVG 徽章资源 (不想要可以都删了)
• CHANGELOG.md
• CODE_OF_CONDUCT.md (替换为你的实际邮箱)
• CONTRIBUTING.md
• metadata.yaml (废话)
• README.md (不然呢)
• .github/workflows/release.yml (如你的版本字段、分支策略或 Changelog 标题格式不同，请一并调整)

• AstrBot：在此感谢其开发团队对该项目的付出。

我的其他插件：

• 主动消息 (Proactive_chat) - 它能让你的 Bot 在特定的会话长时间没有新消息后，用一个随机的时间间隔，主动发起一次拥有上下文感知、符合人设且包含动态情绪的对话。
• 灾害预警 (Disaster_Warning) - 它能让你的 Bot 提供实时的地震、海啸、台风、气象预警信息推送服务。
• 视奸面板 (Live_Dashboard) - 它能让你的 Bot 和群友随时随地视奸你。
• 代码统计 (Count_Loc) - 它能让你的 Bot 对任意公开的 GitHub 或 GitLab 仓库的代码行数、文件数量、注释行数、物理总行数等指标进行快捷获取和分析。

欢迎提交 Issue 和 Pull Request 来改进这个插件！

• 对于新功能的添加，请先通过 Issue 等方式讨论。
• 对于 PR (拉取请求)，请确保你已阅读并同意遵守本项目的 贡献指南。

如果你对这个插件模板有任何疑问、建议或 bug 反馈，欢迎加入我的 QQ 交流群。

• QQ 群: 1033089808

• 群二维码:

  

GNU Affero General Public License v3.0 - 详见 LICENSE 文件。

本插件采用 AGPL v3.0 许可证，这意味着：

• 您可以自由使用、修改和分发本插件。
• 如果您在网络服务中使用本插件，必须公开源代码。
• 任何修改都必须使用相同的许可证。

Made with ❤️ by DBJD-CR