打包与发布 | EmDash CMS Everything

发布一个可用的沙箱插件，以便其他站点可以安装。发布仅适用于沙箱插件：原生插件通过 npm 分发。

可直接从 CLI 发布，或使用自动化发布服务从 GitHub Actions 构建并发布。两条路径都会将发布写入你的 Atmosphere 账户。只有在明确选择 CLI 直接 --url 路径时，才需要单独的产物主机。

前置条件

有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者（author 或 authors）以及安全联系人（security 或 securityContacts）。运行 emdash-plugin validate 确认。
version（在 package.json 中，或仅注册表插件则在清单中）。
用于发布的 Atmosphere 账户。

选择发布方式

两种方式都会创建发布者拥有的包与发布记录。选择发布构建应在何处运行，以及由哪份凭据授权。

方式	适用场景	账户访问
`emdash-plugin publish`	从你的计算机或其他可信环境构建并发布。	本地 CLI 会话写入包配置文件、发布与 blob。
自动化发布	GitHub Actions 需从版本标签或手动工作流运行构建发布。	本地 CLI 引导配置文件；发布服务保留 create-only 的发布与 blob 权限。

你的 Atmosphere 账户

你在 Atmosphere 账户 下发布：这是一种用户拥有的可移植身份，用于 Bluesky 以及 AT Protocol 网络上的其他应用。一个账户是你在网络上的唯一登录，处处使用相同的 @handle，身份与数据不绑定于单一应用。EmDash 将该账户用作你的发布者身份：你发布的每个版本都是你自己账户上的一条记录，并以你的名义签名。

EmDash 对站点使用与其 Atmosphere 登录相同的 Atmosphere 账户。

使用现有账户

若已有 Bluesky 账户或其他 Atmosphere 账户，请用其 handle 登录：

emdash-plugin login alice.bsky.social

这会在浏览器中打开账户提供方的登录页。EmDash 永远看不到你的密码。emdash-plugin whoami 列出已存储的会话；emdash-plugin switch <did> 切换当前活动会话。

注册账户

若尚无 Atmosphere 账户，可通过任意提供方创建，然后运行 emdash-plugin login <your-handle>。可选：

应用，例如 Bluesky。 注册 Bluesky 会创建由 Bluesky 托管的 Atmosphere 账户。这是最快的路径。
独立提供方。 社区或注重隐私的账户主机。可在 atmosphereaccount.com 浏览选项。
自托管。 运行自己的提供方，以完全控制身份与数据。

无论选择哪种，该账户的 @handle 就是传给 emdash-plugin login 的内容，账户 DID 则是你在清单中固定为 publisher 的值。

从插件目录发布

登录一次，然后从包含 emdash-plugin.jsonc 的目录发布：

emdash-plugin login alice.example.com
emdash-plugin publish

publish 执行与 bundle 相同的构建与校验检查，创建 gzip 归档，上传到你的 personal data server（PDS），上传任何已声明的列表图片，并写入发布记录。

当有规范的 HTTPS 仓库可用时，命令会将其加入包配置文件，并可附带 provenance。没有仓库元数据的配置文件也允许无 provenance 的发布。若 profile setup 已将包配置为要求 provenance，请改为通过生成的 GitHub Actions 工作流发布。

Bundle

bundle 运行 build、校验、收集资源并创建 tarball。在 tarball 内，plugin.mjs 被打包为 backend.js（注册表期望的文件名）。

该命令接受以下标志：

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]

标志	默认值	说明
`--dir`	当前目录	插件源目录。
`--out-dir`, `-o`	`dist`	tarball 输出目录。
`--validate-only`	`false`	跳过 tarball，但仍生成 `dist/` 产物。

tarball 内容

文件	必需	说明
`manifest.json`	是	生成的清单：id、version、capabilities、hosts，以及从源代码读取的 hooks 与 routes。无需手工维护。
`backend.js`	是	构建后的自包含运行时文件（`dist/plugin.mjs`）。
`README.md`	否	插件文档。
`icon.png`	否	约定式捆绑图标。必须是可读的 PNG；建议 256×256。
`screenshots/`	否	最多八个 `.png`、`.jpg` 或 `.jpeg` 文件；建议 1920×1080 或更小。

校验

bundle（以及 --validate-only）会检查：

大小上限（RFC 0001，解压后）： 总计 ≤ 256 KB，单文件 ≤ 128 KB，≤ 20 个文件。gzip tarball 只是其中一小部分。
backend.js 中无 Node 内置模块 — 沙箱代码不能导入 fs、path、child_process 等。请使用 Web API，或将该逻辑移到原生插件。
capabilities 健全性 — 名称必须属于已识别集合。
信任契约一致性 — Capabilities 与 hosts 中的交叉规则 network:request / allowedHosts。
约定式捆绑资源 — 不可读的 icon.png 或截图会被跳过。当图标不是 256×256 或截图超过 1920×1080 时，CLI 会警告，但仅尺寸不会导致捆绑失败。每个包含的文件仍计入解压后的文件数与大小上限。

发布前检查 tarball，可列出其内容：

emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz

Publish

发布当前源码，并将其产物托管到你的 PDS：

emdash-plugin publish

以下清单块添加列表图片。路径相对于 emdash-plugin.jsonc；支持 PNG、JPEG 与 WebP。

{
  "release": {
    "artifacts": {
      "icon": { "file": "./icon.png" },
      "banner": { "file": "./banner.webp" },
      "screenshots": [
        { "file": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

清单中声明的列表图片，与 tarball 中包含的约定式 icon.png 和 screenshots/ 文件不同。发布会将每张声明的图片上传到发布者的 PDS，并将其 blob 引用写入发布记录。每张图片限制为 1 MiB、任一维度 8,192 像素；一次发布最多可声明八张截图。完整形态见发布字段。

publish 的步骤：

构建插件，校验解压后上限，并创建 gzip 归档。
恢复 Atmosphere 账户会话，并检查发布者固定。
确认 OAuth 授权包含包与图片 blob 作用域。
将包与声明的图片上传到你的 PDS，并将返回的每个 blob CID 与上传字节核对。
首次发布时创建包配置文件，并写入不可变的发布记录。

CLI 将已发布的包标识为 @<publisher-handle>/<slug>，打印批准后可用的公开页面，并给出 emdash-plugin info … --version <version> --watch 命令。该命令直接读取 labeler 的当前检查；未批准包的元数据仍不会出现在聚合器响应与公开插件站点中。

若现有登录早于 blob 发布，publish 会报告 MISSING_BLOB_SCOPE。运行 emdash-plugin logout 并重新登录以批准新作用域。

使用外部包 URL

当包捆绑已通过 HTTPS 可用，或账户提供方不接受 gzip blob 时，传入 --url：

emdash-plugin publish --url https://downloads.example.com/gallery-1.0.0.tar.gz

CLI 会下载该 URL，校验所提供的捆绑并计算校验和。此路径不会上传包 blob。列表图片仍使用 PDS blob。

要将托管字节与本地 tarball 比较，请添加 --local：

emdash-plugin publish \\
  --url https://downloads.example.com/gallery-1.0.0.tar.gz \\
  --local dist/gallery-1.0.0.tar.gz

版本默认不可变

emdash-plugin publish 拒绝替换具有相同 slug 与版本的现有发布。再次发布前请递增 version。构建从 package.json 读取 version（见保持单一版本值）。扩大的信任契约递增 major，新 hooks 或 routes 递增 minor，修复递增 patch。

发布者不匹配

若 publish 因 MANIFEST_PUBLISHER_MISMATCH 失败，则活动会话是与清单中固定的 publisher 不同的 Atmosphere 账户。用 emdash-plugin switch <did> 切换到固定账户，或在确实将插件转移到新账户时更新清单中的 publisher。会话管理见使用现有账户。

接下来读什么

emdash-plugin CLI — 每条命令
自动化插件发布 — 从已批准的 GitHub Actions 工作流发布
清单 — 字段、信任契约、发布者固定
Capabilities 与安全