# 发布插件

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

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

---

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

### 获得你的专属命名空间
在拓展商店中，可以使用用户名密码直接注册，也可以通过 GitHub 快捷登录：
- 注册成功后，系统会默认以小写用户名分配一个初始命名空间，例如 `my-studio`。
- 如果你的 GitHub 账号名称已被他人占用或包含系统保留前缀，系统会自动追加唯一的数字后缀。后续你在 GitHub 上修改昵称不会影响已创建的命名空间或已发布的插件 ID。

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

> ⚠️ **命名空间规则**：  
> - 插件清单中的唯一 ID 必须以你拥有的命名空间作为前缀，例如 `my-studio.hello`。  
> - 格式要求使用全小写英文字母、数字、点号、下划线或连字符（`[a-z0-9._-]`）。  
> - **命名空间一旦绑定了已上架的插件，将无法删除或直接改名**，以避免破坏其他开发者在依赖或跨插件调用中的 ID 引用。

---

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

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

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

---

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

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

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

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

---

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

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

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

---

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

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

---

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

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