将 Agent Zero 插件发布到社区 Plugin Index：从仓库准备到 PR 合入的完整贡献指南-北京尧图网络

将 Agent Zero 插件发布到社区 Plugin Index从仓库准备到 PR 合入的完整贡献指南【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文以 Agent Zero 仓库内插件贡献技能skills/a0-contribute-plugin/SKILL.md为核心系统讲解把一个在本地可用的插件发布到社区 Plugin Indexa0-plugins 社区索引仓库的完整流程让所有 Agent Zero 用户都能通过内置 Plugin Hub 发现并安装它。读完本文你将掌握独立插件仓库的目录规范与运行期plugin.yaml要求、索引提交index.yaml的编写规则、PR 前镜像 CI 的预校验清单以及plugin.yaml与index.yaml两套清单的本质区别并结合仓库源码理解插件发现、校验与生命周期机制。一、插件贡献的整体背景Plugin Index 与 Plugin HubAgent Zero 采用插件机制扩展能力仓库根目录plugins/内置框架级系统插件用户自研插件则位于usr/plugins/见 plugins/README.md。当本地插件想要被整个社区使用就需要提交到社区维护的Plugin Indexa0-plugins 索引仓库这是一个面向所有 Agent Zero 用户的插件注册表提交后插件即被纳入索引可被其他用户发现与安装。在 Agent Zero 内部内置的 Plugin Installer 插件提供了Plugin Hub界面用户从 Plugins 对话框的 Browse 标签页或 Install 按钮进入即可搜索、筛选、查看并直接安装社区索引中的插件全程无需离开 Agent Zero见 plugins/README.md 与 plugins/AGENTS.md。因此社区插件贡献的本质就是向这个索引提交一条条目使插件出现在 Plugin Hub 的浏览列表中。围绕这一目标仓库中的a0-contribute-plugin技能skills/a0-contribute-plugin/AGENTS.md 为技能 DOX 文档SKILL.md为实际的操作规程拥有完整的工作流所有权并保持与 Plugin Hub 及 a0-plugins 仓库当前要求的对齐。整个贡献链路可拆解为六个步骤确认前置条件 → 确认自动化偏好 → 准备插件 GitHub 仓库 → 确定索引目录名 → 创建索引提交 → 预校验并提交 PR。二、开始之前前置条件与自动化偏好确认2.1 前置条件检查正式动手前需要确认以下三项插件已存在且在本地可运行插件应位于usr/plugins/name/usr/目录被 gitignore是用户插件的唯一合法位置。这一点与插件架构约定一致——plugins/AGENTS.md 明确指出usr/plugins/之外、plugins/之下是框架保留区域社区贡献者不应在其中放置自定义插件。插件已完成审查如果尚未审查应先运行a0-review-plugin技能做全面审计。技能建议主动询问用户我建议在贡献前先做一次完整审查现在需要我来做吗用户具备 GitHub 账号且本机装有git/ghCLI后续的 fork、分支、commit、PR 全部依赖这两个工具。2.2 Step 0询问自动化偏好在开展任何 git 操作之前先询问用户你希望我自动处理 git 操作fork、分支、commit、PR还是希望我给出每一步命令由你手动执行自动模式通过代码执行工具直接运行gh与git命令手动模式在每一步向用户提供可直接复制的确切命令。这一步是技能的关键人机分工设计它把 git 操作的执行权明确交给用户决定避免在未获授权时擅自操作外部仓库。三、Step 1准备独立的插件 GitHub 仓库3.1 仓库结构与目录规范社区插件必须位于独立的 GitHub 仓库中且插件内容必须位于仓库根目录不能嵌套在子文件夹内your-plugin-repo/ - GitHub 仓库根目录 ├── plugin.yaml - 运行期清单必需 ├── README.md - 强烈推荐显示在 Plugin Hub 详情页 ├── LICENSE - 提交 Plugin Index 所必需放在仓库根目录 ├── default_config.yaml - 可选 ├── api/ - API 处理器 ├── tools/ - 智能体工具 ├── helpers/ - 共享 Python 逻辑 ├── prompts/ - 提示词模板 ├── agents/ - 智能体配置agent profiles ├── conf/ - 配置文件如 model_providers.yaml ├── extensions/ - 生命周期、UI 与隐式 extensible 钩子 └── webui/ - 前端页面、store、组件其中extensions/目录的布局必须遵循当前运行时约定与 plugins/AGENTS.md 记录的插件架构契约一致python/point/命名生命周期钩子python/_functions/module/qualname/start|end/隐式extensible钩子webui/point/UI 断点扩展。不要使用已废弃的扁平化形式python/module_qualname_start|end/。这一点在源码契约中有明确对应plugins/AGENTS.md 规定_functions扩展布局必须保留每个模块和嵌套 qualname 段废弃的扁平化扩展目录名不再被解析。3.2 运行期plugin.yaml的要求远端仓库的plugin.yaml是运行期清单驱动 Agent Zero 的插件行为。提交到 Plugin Index 时它必须包含name字段——CI 会校验该字段且必须与索引目录名完全一致name: my_plugin # 必需 - 必须与索引目录名一致^[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这些字段与仓库中helpers/plugins.py的PluginMetadata模型一一对应helpers/plugins.pyname、title、description、version、settings_sections、per_project_config、per_agent_config、always_enabled。其中settings_sections的合法取值为agent、external、mcp、developer、backup决定插件在 Settings 的哪些标签页显示配置小节always_enabled: true仅限框架核心插件使用社区插件应保持false详见 skills/a0-create-plugin/SKILL.md。3.3 创建仓库并推送自动模式若插件是本地构建的技能会帮助用户创建 GitHub 仓库并推送# 创建仓库自动模式 - 使用 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推送前建议核对仓库必须公开Plugin Index 的github字段指向公开仓库、插件内容在根目录、README.md与LICENSE齐备。四、Step 2确定索引目录名索引中的目录名必须满足与远端plugin.yaml的name字段完全一致符合^[a-z0-9_]$小写字母、数字、下划线不允许连字符在索引中唯一不能以_开头该前缀保留给框架内部使用与 plugins/AGENTS.md 中内置插件目录名与清单name必须以_开头以避免与社区插件冲突的约定互为镜像。在确定名称前可通过下载当前索引的生成产物来验证唯一性检查plugins键下是否已存在同名条目https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.json此index.json是 CI 生成的索引产物也是后续重复检测的事实来源——skills/a0-review-plugin/SKILL.md 的重复检测阶段同样基于该文件判断插件name是否已存在、是否已有条目指向同一githubURL。五、Step 3创建索引提交fork index.yaml5.1 Fork 与分支# 自动模式 gh repo fork https://github.com/agent0ai/a0-plugins --clone --remote cd a0-plugins git checkout -b add-plugin_name5.2 创建插件目录与index.yamlmkdir -p plugins/plugin_name需要再次强调索引使用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可选附加字段screenshots最多 5 个图片 URL每个 URL 必须可访问screenshots: - https://raw.githubusercontent.com/user/repo/main/docs/screenshot1.png - https://raw.githubusercontent.com/user/repo/main/docs/screenshot2.webp5.3 推荐标签与可选缩略图标签从 a0-plugins 仓库的TAGS.md中选用最多 5 个。常用标签包括tools、automation、workflow、api、web、database、memory、integration、security、development、llm、agents。缩略图可选向plugins/plugin_name/目录添加名为thumbnail.png、thumbnail.jpg或thumbnail.webp的正方形图片最大 20 KB必须为正方形宽高比。这里同样能看到目录内只允许index.yaml 可选缩略图这一约束在源码层的呼应index.yaml只承担可发现性描述title、description、github、tags、screenshots运行期行为仍由远端仓库根目录的plugin.yaml决定。六、Step 4PR 前本地预校验镜像 CI在打开 PR 之前先在本地运行以下检查——这正是 CI 将要校验的内容下表完整列出各条规则检查项规则plugins/name/中存在index.yaml必需目录中仅有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 -s https://raw.githubusercontent.com/user/repo/main/plugin.yaml | grep ^name: # 预期输出: name: plugin_nameLICENSE这一条值得单独强调Agent Zero 对本地插件并不强制要求 LICENSE见 skills/a0-review-plugin/SKILL.md本地缺失仅 WARN但提交 Plugin Index 前必须在仓库根目录放置 LICENSE使用户拥有明确的许可条款——这既是索引政策也是仓库层面的明确要求plugins/README.md。七、Step 5提交并打开 PR# 添加并提交 git add plugins/plugin_name/ git commit -m feat: add plugin_name plugin # 推送并打开 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 会在打开/同步/重新打开时自动校验CI 通过后由人工维护者审查并合入若 CI 失败后 PR 超过7 天无任何活动可能会被自动关闭。这也解释了 Step 4 预校验的价值把 CI 会做的检查前置到本地避免因琐碎错误如name不匹配、缩略图超 20 KB、目录混入多余文件导致 PR 进入漫长的失败-等待周期。八、两套清单一图看清文件位置用途关键字段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 不同、用途不同。这一区分在 plugins/AGENTS.md 与 plugins/README.md 中被反复强调索引index.yaml是与运行期plugin.yaml完全不同的文件、不同的 schema。从源码角度印证运行期清单的字段由helpers/plugins.py的PluginMetadata直接解析helpers/plugins.py用于插件的加载、启用状态、配置界面渲染与always_enabled强制开关而index.yaml是纯描述性条目只服务于 Plugin Hub 的浏览与发现。九、源码视角插件发现、校验与生命周期机制9.1 插件如何被发现与加载helpers/plugins.py定义了插件体系的底层机制理解它有助于把握贡献规范背后的原因插件根目录get_plugin_roots()按优先级返回usr/plugins/name与plugins/namehelpers/plugins.py用户插件优先发现规则get_plugins_list()遍历根目录以是否存在plugin.yaml为发现依据helpers/plugins.py——这正解释了为什么社区插件仓库根目录必须放置plugin.yaml缺失即无法被发现启用状态get_enabled_plugins()通过.toggle-1/.toggle-0文件与always_enabled字段决定插件是否激活helpers/plugins.py插件默认开启除非在usr/目录被显式禁用。9.2 钩子与生命周期插件根目录的hooks.py由call_plugin_hook()按名称调用helpers/plugins.py当前内置用法包括插件安装器在将插件放入usr/plugins/后调用install()、更新器在拉取新代码前调用pre_update()、卸载器在删除插件目录前调用uninstall()详见 skills/a0-create-plugin/SKILL.md。贡献者需要注意hooks.py运行在框架运行时若需要为目标运行时安装依赖必须在子进程中显式指定解释器如/opt/venv/bin/python不能直接sys.executable -m pip install。9.3 提交前的自动校验支撑仓库内置的_plugin_validator插件plugins/_plugin_validator/提供了清单、结构、约定与安全性的校验能力其 API 处理与校验清单位于 plugins/_plugin_validator/api/ 与 plugins/_plugin_validator/webui/plugin-validator-checks.json。结合 skills/a0-review-plugin/SKILL.md 的四阶段审计清单校验 → 结构校验 → 代码模式审查 → 安全与索引审查可以在贡献前对插件做完整体检把社区就绪READY作为提交的前提。十、贡献前质量保障与审查、创建技能的协作闭环社区插件贡献不应是写完就发仓库将其设计为一条完整的技能协作链路创建a0-create-plugin 负责插件的构建明确区分本地插件与社区插件两条路径并在创建时就强调社区插件的仓库结构要求内容在仓库根目录、name字段匹配索引目录名审查a0-review-plugin 提供四阶段完整审计最终给出 READY / NEEDS WORK / OPTIONAL IMPROVEMENTS 结论——注意对于 Plugin Index 提交缺失LICENSE虽标记为 WARN但会阻塞社区就绪判定贡献本文所述的 a0-contribute-plugin 负责发布流程其 DOX 契约skills/a0-contribute-plugin/AGENTS.md明确要求保持仓库、index.yaml、清单、许可证、校验与 PR 指导的同步更新不硬编码用户凭据、个人仓库名或私有 URL并确保与审查、管理技能的交接准确。对贡献者而言这条闭环的意义在于审查阶段发现的问题如清单字段缺失、Store Gate 模式违规、内联错误提示框、硬编码密钥、路径穿越风险等应在提交索引前解决避免污染社区索引并拖长 PR 周期。十一、相关资源完整贡献操作规程skills/a0-contribute-plugin/SKILL.md技能维护契约DOXskills/a0-contribute-plugin/AGENTS.md插件架构契约内置与自定义插件、manifest、扩展点、banners、Plugin Index 规则plugins/AGENTS.md插件生命周期开发指南docs/developer/plugins.md插件构建技能本地与社区插件两条路径skills/a0-create-plugin/SKILL.md插件审查技能四阶段审计与社区就绪评估skills/a0-review-plugin/SKILL.md插件发现与加载源码实现helpers/plugins.py内置校验器插件plugins/_plugin_validator/提交时以当前仓库所记录的规范为准本地插件位于usr/plugins/name/社区插件内容置于独立公开仓库根目录索引目录仅含index.yaml与可选缩略图运行期name与索引目录名严格一致LICENSE置于仓库根目录PR 每次仅提交一个插件。遵循这套流程即可让你的插件出现在 Plugin Hub 中被所有 Agent Zero 用户发现与安装。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

将 Agent Zero 插件发布到社区 Plugin Index：从仓库准备到 PR 合入的完整贡献指南

相关推荐

mimalloc 测试体系深入解析：从内部不变量检查到完整 API 面覆盖

Renovate postUpgradeTasks 怎么配置并在自托管环境允许执行

OpenMetadata Playwright E2E 文档生成器：架构、指标与自动化实战

更多资讯

Bokeh 浏览器端粒子动画：基于 CustomJS、requestAnimationFrame 与 WebGL 的高频渲染架构解析

FanControl 风扇控制软件：自己画转速曲线，让机箱风扇安静下来

芯片PAD金属体系详解：从结构设计到封装工艺适配

同一台电机测出三个效率值？台架测量链路误差排查实战

JWT认证机制解析与实战开发指南

1990-2025年各省统计年鉴面板数据无缺失填充版

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？