发布插件

管理开发者命名空间，上传安装包并提交版本审核。

Plugin API v1

Documentation content is currently available in Simplified Chinese.

把插件发布到飞块拓展商店，让全世界的飞块用户都能在商店一键发现、安装和享受你的创意！

拓展商店为每个插件提供了精美的展示详情页（包含功能介绍、精美截图、版本日志与作者主页）。通过上传 .flyext 安装包，商店会自动解析清单中的唯一标识（ID）与版本号（Version），引导你完成发布与审核流程。

#1. 注册账号与管理开发者命名空间

#获得你的专属命名空间

在拓展商店中，可以使用用户名密码直接注册，也可以通过 GitHub 快捷登录：

注册成功后，系统会默认以小写用户名分配一个初始命名空间，例如 my-studio。
如果你的 GitHub 账号名称已被他人占用或包含系统保留前缀，系统会自动追加唯一的数字后缀。后续你在 GitHub 上修改昵称不会影响已创建的命名空间或已发布的插件 ID。

#申请与管理多个命名空间

在开发者工作台进入“管理命名空间”，你可以：

为命名空间补充清晰的组织介绍；
设置日常偏好的默认空间；
申请额外的命名空间：如果团队有不同的子品牌或独立项目，只需提交新的空间名称即可发起申请。管理员审核通过后即可立即使用。每个账号最多可拥有 10 个命名空间，同时最多可保留 5 条待审核申请。

⚠️ 命名空间规则：

插件清单中的唯一 ID 必须以你拥有的命名空间作为前缀，例如 my-studio.hello。

格式要求使用全小写英文字母、数字、点号、下划线或连字符（[a-z0-9._-]）。

命名空间一旦绑定了已上架的插件，将无法删除或直接改名，以避免破坏其他开发者在依赖或跨插件调用中的 ID 引用。

#2. 上传安装包与创建版本

在开发者工作台点击“上传插件”，只需上传打包好的 .flyext 安装包（单个安装包最大支持 256 MiB）：

自动提取元信息：无需再手动填写插件 ID、名称或版本号，商店服务会自动解包读取 manifest.json 中的 id、name 和 SemVer 语义化 version。
首次上传与版本迭代：
- 首次上传该 ID 的安装包时，会自动为你建立该插件的私有空间与首个版本草稿；
- 后续上传新功能时，会自动追加新的版本记录。请注意，已上传的同版本包体无法重复覆盖；若有修改，请递增清单中的 version 后重新打包上传。
安全透明的进度流：
上传完成后，工作台会清晰呈现发布导航条：上传安装包 → 完善插件资料 → 提交审核 → 开放发布，并实时标记出当前尚未补齐的信息。

#3. 完善精美的公开资料

一份详实、美观的资料页面能够大幅提升用户的下载意愿与信任度。在“插件资料”标签页中，你可以完善以下信息：

简介与详细功能介绍：清晰阐述插件能为用户解决什么痛点、核心功能有哪些、以及是否需要额外的硬件连接或系统权限授权。
分类与标签：选择最贴切的应用场景（如工具、音频、生产力、开发辅助等），方便用户在商店中精准筛选。
高品质界面截图：
- 支持上传 16:9 比例的直观截图（服务端会自动校验比例并无损压缩为快速加载的 WebP 格式）；
- 建议截图展示按键在飞块中的实际配置界面、动作流编排或超级块在真实设备上的渲染效果。
图标展示（Icon）：
插件图标直接由安装包内 manifest.icon 声明的图片文件决定（支持包内 PNG、JPEG 或 WebP）。更换图标只需在清单中替换图片并在新版本中发布。

💡 作者专属预览：在资料编辑过程中，你可以随时点击“预览展示页面”，提前查看公开展示页的实际视觉效果（该链接仅对你本人和审核人员可见）。

#4. 提交审核与上线流程

当资料填写完整且包体检查通过后，即可一键点击“提交人工审核”：

自动化静态合规检查：
在提交前后，商店后端会异步校验 ZIP 归档结构、清单 Schema、CRC 校验码以及文件路径引用完整性（检查过程绝不会执行任何插件运行代码）。
人工安全与功能复核：
审核团队会比对安装包的权限声明与资料描述。如果插件申请了高危权限（如发起外网请求或调起本地原生工具），请确保在功能介绍中有合理解释。
审核状态全追踪：
- 待提交：尚未正式入队，可自由修改资料；
- 审核中：已进入审核队列，请耐心等待；
- 驳回：审核团队会详细附上驳回原因与修改建议，修改资料或上传修复后的新版本即可重新提交；
- 已通过：恭喜！插件已正式上架，所有飞块用户均可在客户端与商店网页中浏览、搜索并一键下载。

#5. 后续维护与版本迭代

平滑发布更新：当需要发布新特性或修复 Bug 时，只需在本地将 version 递增（如 1.0.1 -> 1.1.0），打包后在工作台上传即可。已发布的历史版本不会被覆盖，用户可以随时查阅各版本的更新日志。
撰写清晰的更新说明：如果新版本涉及动作参数的增删或数据结构调整，强烈建议在更新说明中提供清晰的迁移指引，帮助已有用户无痛升级配置。

#6. 使用 API 密钥自动发布

Agent 或 CI 可以通过 API 密钥调用开放接口完成同样的上传、资料更新、提交审核与状态查询。密钥在账户设置的「API 密钥」中生成，调用方式与完整接口列表见 API 密钥与开放 API。