打包与发布 | 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 准备档案；发布服务仅保留创建发布记录和 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 归档，将其上传到你的个人数据服务器（PDS），上传所有已声明的列表图片，并写入发布记录。

当有可用的规范 HTTPS 仓库时，该命令会把它连同可选的来源证明添加到包档案中。没有仓库元数据的档案也允许不带来源证明的发布。如果 profile setup 已将该包配置为要求来源证明，请改为通过生成的 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、版本、capability、主机，以及从你的源码中读取的钩子和路由。你无需手动维护它。
`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，或把这部分逻辑移到原生插件中。
Capability 合理性——名称必须在已识别的集合内。
信任契约的一致性——来自 Capability 与主机的 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": "./images/editor.png" },
        { "file": "./images/settings.jpg", "lang": "en" }
      ]
    }
  }
}

发布时，每个已声明的图片都会上传到发布者的 PDS，并把它的 blob 引用写入发布记录。每张图片限制为 1 MiB，且任一边不超过 8,192 像素；一次发布最多可声明八张截图。无论清单是否声明，bundle 还会把约定的 icon.png 以及 screenshots/ 中的 PNG 和 JPEG 文件打包进 tarball，每个被打包的文件都会计入每文件 128 KB、总计 256 KB 的大小上限。请把已声明的截图存放在其他文件夹中，例如 images/。完整结构请参见发布字段。

publish 会做这些事：

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

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

如果现有登录早于 blob 发布功能，publish 会报告 MISSING_BLOB_SCOPE。请运行 emdash-plugin logout，然后重新登录以批准新的作用域。

使用外部包 URL

当包的 bundle 已经可以通过 HTTPS 获取，或者账户提供方不接受 gzip blob 时，请传入 --url：

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

CLI 会下载该 URL、校验所提供的 bundle，并计算其校验和。这条路径不会上传包 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（参见只保留一处版本号）。扩大信任契约时提升主版本，新增钩子或路由时提升次版本，修复问题时提升补丁版本。

发布者不匹配

如果 publish 因 MANIFEST_PUBLISHER_MISMATCH 而失败，说明当前活动会话所用的 Atmosphere 账户与清单中固定的 publisher 不是同一个。请用 emdash-plugin switch <did> 切换到固定的账户；如果你确实要把插件转移到新账户，则更新清单中的 publisher。会话的管理方法请参见使用现有账户。

接下来读什么

emdash-plugin CLI——每一条命令
自动化插件发布——通过获批的 GitHub Actions 工作流发布
插件清单——字段、信任契约、发布者固定
能力与安全