打包與發布

發布一個可用的沙箱外掛，以便其他站點可以安裝。發布僅適用於沙箱外掛：原生外掛透過 npm 分發。

可直接從 CLI 發布，或使用自動化發布服務從 GitHub Actions 建置並發布。兩條路徑都會將發布寫入你的 Atmosphere 帳戶。只有在明確選擇 CLI 直接 --url 路徑時，才需要單獨的產物主機。

前置條件

• 有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者（author 或 authors）以及安全聯絡人（security 或 securityContacts）。執行 emdash-plugin validate 確認。
• version（在 package.json 中，或僅註冊表外掛則在清單中）。
• 用於發布的 Atmosphere 帳戶。

選擇發布方式

兩種方式都會建立發布者擁有的套件與發布記錄。選擇發布建置應在何處執行，以及由哪份憑證授權。

你的 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]

tarball 內容

校驗

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 的步驟：

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 與安全性