EN
打包、安装和发布插件

打包、安装和发布插件

构建可更新的签名插件并发布多平台版本

先完成项目创建。生成项目的 build.ps1 提供 Check、Build、Keygen、Pack 四个动作。脚本从项目自身目录读取配置，临时设置交叉编译环境，结束时恢复原环境；不会自动修改全局 Go 配置或发布到市场。

一次创建作者密钥

为这个作者的插件保留稳定的 Ed25519 密钥，把它放在项目目录之外：

./build.ps1 -Action Keygen -PublisherKey E:/private/plugin-keys/my-plugin.key

Keygen 在文件存在时失败，不覆盖旧密钥。后续版本继续使用原密钥；不要每次打包重新生成。SDK 会把公钥放进包描述，私钥不进入 .ynp。

编译和打包

./build.ps1 -Action Check
./build.ps1 -Action Build -Architectures amd64
./build.ps1 -Action Pack -PublisherKey E:/private/plugin-keys/my-plugin.key

Pack 默认先测试，再分别编译 Windows amd64 和 arm64，调用公开的 packaging.Write 生成：

Windows payload 使用 -ldflags=-H windowsgui，与宿主正式 Process smoke 一致。它仍通过继承的标准句柄交换协议；不需要创建控制台窗口。不要删掉该参数后把普通控制台程序当作等价的 LPAC guest。

dist/my-plugin-1.0.0-windows-amd64.ynp
dist/my-plugin-1.0.0-windows-arm64.ynp

它们是同一个逻辑包和版本的不同运行变体，不是两个不同插件。一个逻辑包可以声明多个节点。变体之间的业务合同应一致，仅实现与平台支持不同。

.ynp 包含节点合同与实现清单、签名、节点可执行文件、yotta-plugin.json，以及可选 companion 和资源。packaging.Write 计算真实文件大小和摘要，生成清单并签名，避免作者手工拼接不一致的文件。包描述有面板时使用 yotta.plugin/v2；没有面板时使用 v1。

当前高层打包 API 为 Process 实现生成 ABI 声明，不能把 .wasm 文件换进去就宣称支持 Wasm。Wasm 扩展开发需要对应运行时合同和完整打包支持。

本地安装与调试

  1. 在“设置 → 插件”导入匹配当前平台的 .ynp。
  2. 重启 App，使节点目录加载新一代插件。
  3. 在工作流中添加节点并运行，核对输入输出、错误和取消。
  4. 有面板时再核对后台服务启动、snapshot、按钮交互和停止。

插件设置支持启用/停用、更新、恢复上一版、卸载和 companion 启停；界面区分已保存状态与当前进程已加载的版本。运行中的工作流持有对应包身份，完成前可能阻止生命周期修改。卸载插件不会删除用户工作流，相关工作流需要恢复依赖后才能使用。

遇到导入失败先检查宿主错误：包摘要/签名、作者身份、宿主 API 兼容、平台支持、节点合同和面板定义。不要修改签名后的压缩包来临时修补；修正源码和元数据后重新构建。

发布到市场

插件功能由签名贡献自动推导：maps → 地图、positionSources → 定位、节点合同 → 节点、panels → 面板。同一个包可以提供多项功能；市场使用版本/平台变体的实际贡献筛选，不需要额外填功能标签。纯地图包可以不提供节点。

定位贡献使用 SDK positionsource.Contribution，注册到 packaging.Descriptor.PositionSources：稳定 ID、TitleKey、Protocol: positionsource.Protocol、CompanionID、DescriptorPath、SamplePath，以及可选的 SettingsPanelID。后者必须是同一 companion 提供的面板。打包器使用 descriptor v5；现有 map v4 包继续兼容。运行时的 map 观测能力表示当前地图编号，与提供底图的地图功能不同。

宿主按 package ID + contribution ID 发现源，允许为定位源保存多个 Network 连接实例。路径编辑器独立选择地图和定位；地图显示设置归当前视图，录制设置归路径会话。更新源时保留贡献 ID，不能用端口或展示名替代稳定身份。旧手动采样地址继续可用。

在 Hub 的插件作者发布入口 /creator/plugins：

  1. 使用该作者账号对应的真实 publisher namespace。
  2. 选择同一 Package ID、同一版本的多个平台 .ynp 文件。
  3. 填写名称、简介、分类、标签、业务维度、使用说明和更新记录。
  4. 发布后在市场核对业务筛选、系统兼容信息、详情和安装。

平台、架构、运行方式从已验证制品推导，作者不重复填写这些系统筛选项。发布失败时保留输入，检查错误后重试。当前市场支持真实多版本 Node Pack；独立作者历史管理和 GitHub Release 来源绑定仍是后续能力，不把它们当作当前发布入口的必需步骤。

发布后续版本

修改 plugin.json.version 后，沿用 namespace、slug 和作者密钥重新打包。保持已发布版本不可变，不用相同版本号替换不同内容。原版与新版都应能被明确识别。

节点语义或接口变化时另行决定 nodeVersion，并核对既有工作流兼容性。面板/字段/组件 ID 同样要保持稳定，删除或改类型时检查引用影响。更换 SDK 版本后重新解析依赖、测试和打包，不能只改显示版本。

发布验证至少覆盖首次安装、升级、旧工作流加载、停用/重启和恢复上一版。模板产物、测试 profile、密钥和发布账号数据应各自存放；不要为了验收清空正在使用的 App 数据。