Agent Zero 插件发布全指南：如何将你的插件提交到社区 Plugin Index

Agent Zero 插件发布全指南如何将你的插件提交到社区 Plugin Index【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 为社区提供了统一的插件分发机制——Plugin Index社区插件索引仓库agent0ai/a0-plugins与内置的 Plugin Hub任何用户都可以通过 Browse / Install 界面搜索、查看并安装社区插件。本文以技能文档 skills/a0-contribute-plugin/SKILL.md 为骨架完整讲解从本地插件到公开上架的六步流程准备独立 GitHub 仓库、选择索引文件夹名、创建index.yaml提交、CI 预校验、发起 Pull Request并深度解析plugin.yaml与index.yaml两套清单的区别以及仓库中 plugins/AGENTS.md、plugins/README.md、docs/developer/plugins.md 等文档所规定的架构契约与校验规则。读完本文你将能够独立完成一次合规、可被 CI 校验通过、可被其他 Agent Zero 用户一键安装的插件上架。一、先厘清两个概念插件仓库与插件索引在动手之前必须先分清两套完全不同的清单和两个完全不同的仓库概念位置作用插件仓库你自己的独立 GitHub 仓库插件内容位于仓库根目录存放可运行的插件本体运行时清单plugin.yaml、代码、前端资源插件索引社区仓库agent0ai/a0-plugins的plugins/name/目录只存放一个index.yaml索引清单与可选缩略图驱动可发现性Agent Zero 官方对此有明确表述索引清单index.yaml与运行时清单plugin.yaml是两套 schema、两种用途绝不能混用详见 plugins/AGENTS.md 与 plugins/README.md。plugin.yaml驱动 Agent Zero 的运行时行为是否被发现、是否常驻、配置作用域等index.yaml只描述这个插件是什么、从哪里安装、有什么标签供 Plugin Hub 展示与检索。从仓库结构看内置的插件校验器 plugins/_plugin_validator 正是围绕这两套契约实现自动校验的它检查清单、目录结构、代码规范与安全约定其 plugin.yaml 也体现了name、settings_sections、per_project_config等运行时字段的标准写法。二、前置条件发布前必须确认的三件事在进入 git 操作前先逐项核实插件已在本地正常工作插件存在于/a0/usr/plugins/name/目录且已通过本地测试。注意usr/plugins/才是用户自定义插件的合法位置而plugins/是框架内置插件的保留区plugins/README.md。插件已通过审查如果尚未审查应先执行a0-review-plugin技能做一次完整审计清单校验、结构校验、代码模式、安全与索引查重四个阶段详见 skills/a0-review-plugin/SKILL.md并向用户确认I recommend running a full review before contributing. Should I do that now?环境就绪用户拥有 GitHub 账号且本机装有git与ghCLI。安全提示社区插件会在用户的 Agent Zero 环境中执行代码。发布前请依据 docs/developer/sharing-and-safety.md 检查是否包含密钥、.env、本地绝对路径、机器特定配置等不应公开的内容。三、Step 0先问清自动化偏好在开始任何 git 操作之前必须向用户确认Do you want me to handle the git operations (fork, branch, commit, PR) automatically, or would you prefer I give you the steps to run manually?自动模式通过代码执行工具运行gh与git命令完成全部操作手动模式每一步向用户提供精确命令由用户自行执行。这不仅是操作方式的差异也关系到后续所有命令的组织形态——本文默认以自动模式给出命令手动模式可将其直接复制执行。四、Step 1准备插件 GitHub 仓库插件必须存放在独立的 GitHub 仓库中且插件内容位于仓库根目录不能放在子文件夹里否则无法被索引校验通过。4.1 推荐的仓库结构your-plugin-repo/ - GitHub repository root ├── plugin.yaml - runtime manifest (REQUIRED) ├── README.md - strongly recommended (shown in Plugin Hub detail view) ├── LICENSE - REQUIRED for Plugin Index submission (place at repo root) ├── default_config.yaml - optional ├── api/ - API handlers ├── tools/ - agent tools ├── helpers/ - shared Python logic ├── prompts/ - prompt templates ├── agents/ - agent profiles ├── conf/ - config files (e.g. model_providers.yaml) ├── extensions/ - lifecycle, UI, and implicit extensible hooks └── webui/ - frontend pages, stores, components其中extensions/内部的规范plugins/AGENTS.md为extensions/python/point/命名生命周期钩子named lifecycle hooksextensions/python/_functions/module/qualname/start|end/隐式extensible钩子extensions/webui/point/前端断点扩展。不要使用已废弃的扁平化形式extensions/python/module_qualname_start|end/——当前运行时只解析深层的_functions/...布局plugins/README.md 明确标注该扁平形式已停用。4.2 运行时清单plugin.yaml的硬性要求远端仓库的plugin.yaml必须包含name字段——CI 会校验该字段且必须与索引文件夹名完全一致name: my_plugin # REQUIRED - must match index folder name (^[a-z0-9_]$) title: My Plugin description: What this plugin does. version: 1.0.0 settings_sections: [] per_project_config: false per_agent_config: false always_enabled: false各字段含义结合 skills/a0-create-plugin/SKILL.md 与 plugins/AGENTS.md 展开name小写字母、数字、下划线^[a-z0-9_]$社区插件必须存在且与目录名一致本地私有插件缺失时仅记 WARN见 skills/a0-review-plugin/SKILL.md。title/description插件在 UI 中的展示名称与简介。version遵循 semver 或简单x.y.z格式。settings_sections决定插件在哪些设置页显示配置子区块合法值agent、external、mcp、developer、backup[]表示不显示。per_project_config/per_agent_config布尔值开启后支持按项目 / 按 Agent profile 作用域切换配置。always_enabled强制常驻开启并禁用 UI 开关仅限框架核心插件使用true为保留用法社区插件应为false或省略。4.3 本地插件仓库化并推送若插件是在本地构建的可帮助用户创建仓库并推送# Create repo (automatic mode - using gh CLI) gh repo create repo-name --public --description Agent Zero plugin: title git init git add . git commit -m feat: initial plugin commit git remote add origin https://github.com/user/repo-name.git git push -u origin main注意仓库必须为public——索引校验要求github字段指向存在的公开仓库CI 需要抓取你的远端plugin.yaml与LICENSE。五、Step 2选择索引文件夹名索引中的文件夹名必须同时满足与远端plugin.yaml的name字段完全一致符合^[a-z0-9_]$小写字母、数字、下划线不允许连字符-在索引中唯一不能以_开头_前缀保留给内部使用框架内置插件如_plugin_validator、_plugin_installer均遵循此约定。唯一性核查拉取当前生成的索引 JSON检查目标名称是否已作为plugins字典的键出现https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.jsonimport urllib.request, json url https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.json with urllib.request.urlopen(url, timeout30) as resp: index json.loads(resp.read()) plugins index.get(plugins, {}) # 检查 plugin_name 是否已存在于 plugins 中同时应留意索引中是否已有条目指向同一个githubURLURL 唯一性也是校验项之一。六、Step 3创建索引提交6.1 Fork 索引仓库并建分支# Automatic mode gh repo fork https://github.com/agent0ai/a0-plugins --clone --remote cd a0-plugins git checkout -b add-plugin_name6.2 创建插件文件夹mkdir -p plugins/plugin_name6.3 创建index.yaml再次强调索引仓库里使用index.yaml不是plugin.yaml这是两套完全不同的 schematitle: My Plugin description: One-sentence description of what the plugin does for the user. github: https://github.com/user/repo-name tags: - tools - example可选附加字段——截图最多 5 张必须是可访问的完整图片 URLscreenshots: - https://raw.githubusercontent.com/user/repo/main/docs/screenshot1.png - https://raw.githubusercontent.com/user/repo/main/docs/screenshot2.webp6.4 推荐标签使用索引仓库TAGS.md中收录的标签最多 5 个。常见标签tools、automation、workflow、api、web、database、memory、integration、security、development、llm、agents。6.5 可选缩略图在plugins/plugin_name/下放置一张方形图片命名thumbnail.png、thumbnail.jpg或thumbnail.webp大小≤ 20 KB且必须是正方形比例。该缩略图会直接展示在 Plugin Hub 的搜索结果中。七、Step 4PR 前预校验开 PR 前先在本地跑一遍与 CI 相同的检查这张检查表是原文档的核心资产务必逐项核对检查项规则index.yaml存在于plugins/name/必需文件夹内只有index.yaml 可选缩略图不允许其他文件/子目录title长度最多 50 字符description长度最多 500 字符index.yaml总长度最多 2000 字符tags数量最多 5 个screenshots数量最多 5 张且每个 URL 必须可访问githubURL指向存在的公开仓库远端plugin.yaml必须存在于仓库根目录远端plugin.yaml的name字段与索引文件夹名完全一致远端LICENSE必须存在于仓库根目录Plugin Index 政策文件夹名模式^[a-z0-9_]$不以_开头githubURL 唯一性索引中不能已有其他插件使用同一 URL其中远端plugin.yaml的name匹配可以直接用 curl 验证curl -s https://raw.githubusercontent.com/user/repo/main/plugin.yaml | grep ^name: # Expected output: name: plugin_name关于LICENSE本地插件不强制要求但提交 Plugin Index 前必须在仓库根目录放置LICENSE以便用户获得明确的许可条款plugins/README.md、docs/developer/plugins.md。审查技能中缺失LICENSE被记为 WARN但会阻塞社区贡献就绪状态见 skills/a0-review-plugin/SKILL.md。八、Step 5提交并打开 Pull Request# Add and commit git add plugins/plugin_name/ git commit -m feat: add plugin_name plugin # Push and open PR git push origin add-plugin_name gh pr create \ --repo agent0ai/a0-plugins \ --title feat: add plugin_name \ --body ## Plugin: title description - GitHub: github_url - Tags: tagsPR 规则一个 PR 只提交一个插件只能新增plugins/下的一个文件夹CI 在 PR 打开 / 同步 / 重新打开时自动校验CI 通过后由人工维护者审核并合并若 CI 失败后 PR 超过 7 天无活动可能被自动关闭。合并后的生效链路从仓库架构看插件上架后的完整链路是agent0ai/a0-plugins的plugins/name/index.yaml被汇总生成index.json→ Agent Zero 内置的 Plugin Installer_plugin_installer在 Plugins 对话框的Browse标签页 /Install按钮中展示该条目 → 用户点击安装后框架走clone → validate → 放入usr/plugins/→ 执行install钩子 → 刷新插件缓存的完整管线详见 skills/a0-manage-plugin/SKILL.md。因此你提交的index.yaml中github指向的仓库质量直接决定了用户安装体验。九、两套 Schema 速查对照文件位置用途关键字段plugin.yaml插件 GitHub 仓库根目录运行时清单驱动 Agent Zero 行为name必需、title、description、version、settings_sections、per_project_config、per_agent_config、always_enabledindex.yamla0-plugins/plugins/name/索引清单驱动可发现性title、description、github、tags、screenshots绝不要混淆这两者——schema 不同、职责不同、存放位置也不同。这是提交被 CI 拒绝的最常见原因之一。十、发布前与发布后的完整工作流衔接一次完整的社区插件之旅通常串起四个技能本文只覆盖其中的发布环节构建先在/a0/usr/plugins/name/完成插件开发含plugin.yaml、前端 Store Gate 模式、通知系统、设置 UI 等约定见 skills/a0-create-plugin/SKILL.md审查发布前用 skills/a0-review-plugin/SKILL.md 跑完清单、结构、代码模式、安全 索引查重四阶段审计输出 READY / NEEDS WORK 结论发布本文的六步流程仓库化 → 命名 →index.yaml→ 预校验 → PR管理上架后用户侧通过 skills/a0-manage-plugin/SKILL.md 完成浏览、安全扫描、安装、更新与卸载。此外docs/developer/sharing-and-safety.md 提供了该分享什么 / 分享到哪里 / 什么必须保密的决策树框架核心改动走主仓库贡献流程独立插件走专用公开仓库 索引提交纯流程性知识走技能工作流含密钥与客户数据的内容则必须留在私有仓库或usr/中。十一、参考资源仓库内插件架构契约清单字段、扩展布局、路由、banners 规则plugins/AGENTS.md核心插件总览与社区分享步骤plugins/README.md插件开发生命周期人向指南docs/developer/plugins.md发布前的完整审计流程skills/a0-review-plugin/SKILL.md插件构建本地 / 社区两条路径skills/a0-create-plugin/SKILL.md安装侧管理Browse、安全扫描、安装更新卸载skills/a0-manage-plugin/SKILL.md分享与安全决策树docs/developer/sharing-and-safety.md内置校验器参考实现plugins/_plugin_validator【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考