用途:在 nexu-io/open-design-agent-plugins 分发仓库中,为某个 plugins/<host>/<plugin>/ 载荷构建用于上传的压缩包(submission zip)。该压缩包是宿主专属产物,不具可移植性:一个宿主一个压缩包。不要把已构建的压缩包当作通用的 OpenDesign 插件 zip,也不要把 Codex 的压缩包交给其他宿主。载荷内容体现宿主约定,例如 .codex-plugin/plugin.json 的清单目录名、open-design.package.json 中声明的 schemaVersion:"open-design-codex-cloud-package/v3" 与 minimumCodexCliVersion、以及 skills/<skill>/agents/openai.yaml 这类按宿主命名的接口元数据。README.md、SKILL.md、assets/ 属于宿主中立内容,但它们本身不是可安装包,只有包进某个宿主的清单后才可安装。
主要能力与使用方式:运行 node scripts/package-plugin.mjs 构建。--host 默认 codex(当前唯一有打包规则的宿主);--plugin <name> 仅在 plugins/<host>/ 下存在多个插件时必需;--out-dir <path> 指定输出目录,默认 .tmp/plugin-upload(已 gitignore);--skip-gates 跳过校验器与包测试,仅用于丢弃式检查构建,不可用于要上传的产物;--json 输出机器可读结果,含压缩包 sha256。Codex 产物位于 .tmp/plugin-upload/<plugin>-plugin-<version>.zip。
限制与拒绝场景:未知宿主、载荷中带入他宿主的接口文件(如 agents/claude.yaml)、*.package.json 声明了其他宿主的 schemaVersion、release-manifest.json 中的 contentListSha256/version/path 与磁盘载荷不一致(常见于改载荷后未重新生成摘要)、载荷内含 OS 垃圾文件或符号链接,都会被拒绝;除非加 --skip-gates,否则脚本会先运行 scripts/validate-distribution.mjs 与 tests/distribution-contract.test.mjs 并报告结果。同一已审阅树应产生相同压缩包字节(固定 C 排序、zip -X、mtime 归一化为 release-manifest.json 的 generatedAt 且 TZ=UTC),两次连续运行应得到相同 sha256,否则需排查。压缩包仅用于 Portal 上传,不是用户常规安装途径(用户通过 Git marketplace 安装,命令为 codex plugin marketplace add nexu-io/open-design-agent-plugins);GitHub 源码下载包与上传产物不可互换。新增宿主需在 HOSTS 中补齐 manifestPath、packageContractSchema、agentInterfaceFile,并扩展校验与测试后再构建。