外掛程式清單

每個沙箱外掛程式的根目錄下都有一個 emdash-plugin.jsonc 檔案。當外掛程式同時是 npm 套件時，它與 package.json 放在一起。清單用於識別外掛程式、宣告它需要的存取權限與儲存，並提供其登錄庫項目與發佈版本所需的資訊。外掛程式 CLI 在驗證、建置、封裝、發佈以及準備自動化發佈時都會讀取它。

此檔案使用帶註解的 JSON（JSONC），因此可以寫註解，也允許尾端逗號。請保留 emdash-plugin init 建立的 $schema 屬性；編輯器會使用產生的 schema 提供自動完成，而 emdash-plugin validate 會執行完整檢查。

下面的範例包含了每一組欄位：

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "gallery",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "[email protected]" },
	"name": "Gallery",
	"description": "Image galleries for EmDash content.",
	"keywords": ["gallery", "images"],
	"sections": {
		"installation": { "file": "./docs/installation.md" },
		"faq": { "file": "./docs/faq.md" },
	},

	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {
		"galleries": { "indexes": ["contentId"] },
	},

	"admin": {
		"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	},

	"repo": "https://github.com/example/plugin-gallery",
	"release": {
		"requires": { "env:emdash": ">=0.37.0" },
		"artifacts": {
			"icon": { "file": "./images/icon.png" },
			"screenshots": [{ "file": "./images/editor.png", "lang": "en" }],
		},
	},
}

身分與版本

發佈者與 slug 共同識別登錄庫中的套件。slug 還會用在外掛程式路由的 URL 中，因此它不是 npm 套件名稱：對於 @example/plugin-gallery 這樣的套件，請使用 gallery。

只保留一處版本值

建置時會讓 version 與 package.json#version 保持一致：

• 如果兩個檔案都設定了版本，兩者的值必須一致。
• 如果只有一個檔案設定了版本，建置會使用它。
• 如果兩個檔案都沒有設定版本，建置會失敗。

對於 npm 套件，請把版本保存在 package.json 中，並在清單裡省略它。沒有 package.json 的純登錄庫外掛程式，必須在清單中設定 version。

套件資料

套件資料提供各個發佈版本中都會顯示的穩定資訊。

每個區段既可以是內嵌字串，也可以是相對於清單的檔案參照：

"sections": {
	"description": "A longer description written in CommonMark.",
	"installation": { "file": "./docs/installation.md" },
	"security": { "file": "./SECURITY.md" },
}

解析後的每個區段限制為 20,000 位元組與 2,000 個字素。檔案參照必須位於清單所在目錄之內；絕對路徑以及會跳出該目錄的 .. 路徑都會被拒絕。

publish 會在首次發佈時建立套件資料。之後的發佈不會取代其中的資料欄位。如需編輯已發佈的資料，請使用 emdash-plugin update-package：此指令預設只預覽變更，只有加上 --yes 才會寫入。

信任契約

信任契約由 capabilities、allowedHosts 與 storage 組成。這些欄位會告訴營運人員，外掛程式可以存取什麼，以及它會建立哪些歸外掛程式所有的集合。

下面的宣告允許讀取內容、允許向一個 API 及其子網域發出請求，並建立一個儲存集合：

"capabilities": ["content:read", "network:request"],
"allowedHosts": ["api.example.com", "*.cdn.example.com"],
"storage": {
	"events": {
		"indexes": ["savedAt", ["collection", "savedAt"]],
		"uniqueIndexes": ["eventId"],
	},
}

Capability 與主機

這三個欄位預設都為空。鷹架會明確寫出這些空值，方便審閱者看出此外掛程式沒有要求任何額外的存取權限或集合。

network:request 要求 allowedHosts 中至少有一個裸主機名稱。network:request:unrestricted 要求該清單為空，因為它刻意允許存取任何公開主機。能力與安全是關於每一項能力、其影響、主機模式與執行階段強制執行的權威參考。

儲存

storage 中的每個鍵都命名一個歸外掛程式所有的集合。它的 indexes 與 uniqueIndexes 決定了外掛程式可以依哪些欄位篩選或排序。儲存說明了集合命名、索引設計、查詢與分頁。

信任契約的任何部分發生變更，都需要發佈新的外掛程式版本，因為已安裝的網站同意的是先前的宣告。對於擴大了範圍的契約，請使用主版本號。

管理頁面與小工具

沙箱外掛程式使用 Block Kit 轉譯管理頁面與儀表板小工具。清單宣告它們出現在哪裡：

"admin": {
	"pages": [{ "path": "/settings", "label": "Settings", "icon": "settings" }],
	"widgets": [{ "id": "recent-events", "title": "Recent events", "size": "half" }],
}

頁面路徑以 / 開頭，可包含字母、數字、/、_ 或 -。小工具 ID 使用與外掛程式 slug 相同的小寫識別碼字元。小工具尺寸為 full、half 或 third。

頁面還可以設定 group，以加入側邊欄中可摺疊的資料夾。比對區分大小寫，並忽略前後空白。如果某個群組與側邊欄中顯示的某個集合的群組相同，該頁面就會放入那個資料夾；共用其他任何群組的頁面（無論來自哪個外掛程式）會在 Plugins 區段中組成一個以該標籤命名的資料夾。

宣告了頁面或小工具的外掛程式，必須在 src/plugin.ts 中定義一個名為 admin 的路由。如果缺少該路由，封裝檢查會失敗，因為 EmDash 將沒有任何東西可以呼叫來取得 Block Kit 回應。

發佈欄位

release 描述某個特定版本。頂層的 repo URL 會寫入發佈紀錄，自動化發佈設定也會用它把套件資料繫結到對應的 GitHub 儲存庫。

使用 env:emdash 與 env:astro 來設定可以安裝該發佈版本的 EmDash 與 Astro 版本範圍：

"release": {
	"requires": {
		"env:emdash": ">=0.37.0",
		"env:astro": ">=5.0.0 <7.0.0",
	},
}

EmDash 會在安裝之前檢查這些需求。無效的範圍會導致清單驗證失敗；不相容的發佈版本不會被安裝。

成品檔案路徑相對於清單，且必須位於其目錄之內。支援 PNG、JPEG 與 WebP。每個檔案限制為 1 MiB，且任一邊不超過 8,192 像素。選用的 lang 屬性用 BCP 47 語言標籤標明在地化的圖片。發佈時，這些檔案會與外掛程式套件分開上傳，並記錄它們實測的類型、尺寸、檢查碼以及個人資料伺服器（PDS）的 blob 參照。

發佈者固定

publisher 可以防止從錯誤的 Atmosphere 帳號誤發佈。建議使用帳號的 DID：

"publisher": "did:plc:abc123def456", // jane.example.com

在發佈或準備自動化發佈之前，CLI 會將清單中的發佈者與目前的工作階段進行比較。如果填寫的是 handle，會先解析為其目前的 DID 再比較。不相符時會以 MANIFEST_PUBLISHER_MISMATCH 失敗；沒有可以略過的覆寫旗標。

如果目前使用的工作階段不對，請執行 emdash-plugin whoami，然後切換到被固定的帳號：

emdash-plugin switch did:plc:abc123def456

只有在把套件轉移給另一個帳號時，才應修改清單中的發佈者。

驗證清單

在建置或發佈之前先驗證清單：

emdash-plugin validate

傳入檔案或目錄即可驗證另一份清單：

emdash-plugin validate ./packages/plugin-gallery

驗證在離線狀態下進行。它會回報重複的屬性、未知欄位、無效值、互斥的寫法，以及跨欄位錯誤，例如設定了 network:request 卻沒有非空的 allowedHosts 清單。

接下來請閱讀外掛程式 CLI 了解建置指令，或閱讀打包與發布了解發佈流程。