打包與發佈 | 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 工作流程發佈
外掛程式清單——欄位、信任契約、發佈者固定
能力與安全