打包和发布 | 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），上传任何声明的列表图片，并写入发布记录。

在站点可以安装纯 blob 发布版本之前，需要支持 PDS 托管注册表制品的 EmDash 版本。当发布版本必须在旧版站点上保持可安装时，请使用外部包 URL 路径。

打包

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、版本、能力、主机，以及从源代码读取的钩子和路由。您无需手动维护此文件。
`backend.js`	是	构建好的、自包含的运行时文件（`dist/plugin.mjs`）。
`README.md`	否	插件文档。
`icon.png`	否	256×256 PNG。
`screenshots/`	否	最多 5 张，最大 1920×1080。

验证

bundle（和 --validate-only）检查：

大小上限（RFC 0001，解压后）： 总计 ≤ 256 KB，每个文件 ≤ 128 KB，≤ 20 个文件。gzip 压缩后的 tarball 只是其中的一小部分。
backend.js 中无 Node 内置模块 — 沙盒代码不能导入 fs、path、child_process 等。请使用 Web API，或将该逻辑移至原生插件。
能力合理性 — 名称必须在已识别的集合中。
信任契约一致性 — 来自清单的 network:request / allowedHosts 交叉规则。
资产限制 — 图标 256×256，≤ 5 张截图，≤ 1920×1080。

要在发布前检查 tarball，请列出其内容：

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

发布

发布当前源代码并将其制品托管在您的 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" }
      ]
    }
  }
}

publish 的工作流程：

构建插件，验证解压后的大小限制，并创建 gzip 归档。
恢复您的 Atmosphere 账户会话并检查发布者固定。
确认 OAuth 授权包含包和图片 blob 范围。
将包和声明的图片上传到您的 PDS，然后根据上传的字节验证每个返回的 blob CID。
在首次发布时创建包配置文件，并写入不可变的发布记录。

如果现有登录早于 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

版本不可变

已发布的版本不能被覆盖或重新发布。在再次发布前请递增 version。构建从 package.json 读取 version（参见清单参考）。当信任契约扩展时递增主版本号，新增钩子或路由时递增次版本号，修复时递增补丁版本号。

发布者不匹配

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

接下来阅读

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