外掛程式清單

每個沙盒外掛程式在其 package.json 旁邊都有一個 emdash-plugin.jsonc。它是手動編輯的，包含外掛程式的身份標識、信任契約（capabilities、hosts、storage）以及註冊表顯示的設定檔欄位。emdash-plugin init 會建立一個；CLI 會自動讀取 ./emdash-plugin.jsonc 用於 build、dev、validate、bundle 和 publish。

該檔案是 JSONC：允許註解和尾隨逗號。

以下範例顯示了一個圖片畫廊外掛程式的完整清單：

{
	"$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]" },

	// Optional profile
	"name": "Gallery",
	"description": "Image gallery block for EmDash.",
	"keywords": ["gallery", "images"],
	"repo": "https://github.com/example/plugin-gallery",

	// Trust contract
	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {}
}

身份標識

slug 和 publisher 共同構成套件的身份。EmDash 會自動從中派生套件的完整識別碼。

version 位於 package.json 中

建置會將清單的 version 與 package.json#version 進行協調：

• 兩者都設定且相等 → 正常。
• 兩者都設定但不同 → 硬錯誤。
• 只設定一個 → 該值生效。
• 兩者都未設定 → 硬錯誤。

npm 分發外掛程式的建議模式是從清單中省略 version，讓 package.json 成為唯一的真實來源（你的發佈工具已經在那裡提升了版本）。沒有 package.json 的純註冊表外掛程式必須在清單中設定 version — 沒有其他地方可以放置它。

設定檔

這些為註冊表清單提供資訊。license、作者（author 或 authors）和安全聯絡人（security 或 securityContacts）是必需的；其餘是可選的。

除非你真的有多個作者，否則使用單數形式 author / security — 這是常見情況，腳手架會產生它。

信任契約

信任契約包括 capabilities、allowedHosts 和 storage。這三者預設都為空，因此不需要額外權限的外掛程式可以完全省略它們。

{
	"capabilities": ["network:request", "content:read"],
	"allowedHosts": ["api.example.com", "*.cdn.example.com"],
	"storage": {
		"events": { "indexes": ["timestamp"] },
		"submissions": { "indexes": ["email"], "uniqueIndexes": ["token"] }
	}
}

Capabilities

已識別的名稱：

CLI 強制執行的兩條跨欄位規則（編輯器的 JSON-Schema 檢查不執行 — 執行 emdash-plugin validate）：

• network:request 需要非空的 allowedHosts。如果外掛程式確實必須存取任何主機，請改用 network:request:unrestricted。
• network:request:unrestricted 需要 allowedHosts 為空 — 不受限制的 capability 已經授予所有主機，因此清單會與之矛盾。

主機模式是純主機名稱（無方案、路徑或空格）。前導 *. 允許子網域：*.cdn.example.com。

Storage

集合名稱 → 索引設定的對映。集合名稱遵循相同的 /^[a-z][a-z0-9_]*$/ 規則（執行階段使用名稱作為 SQL 表格後綴）。索引是欄位名稱或複合陣列；uniqueIndexes 也可查詢 — 不要在 indexes 中也列出它們。

"storage": {
	"events": { "indexes": ["timestamp", ["collection", "timestamp"]] }
}

管理介面

可選。沙盒外掛程式透過 Block Kit 渲染管理頁面和儀表板小元件；清單僅宣告它們出現的位置。如果外掛程式沒有管理 UI，請完全省略 admin 索引鍵。

"admin": {
	"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	"widgets": [{ "id": "recent-uploads", "title": "Recent uploads", "size": "half" }]
}

宣告 admin.pages 或 admin.widgets 的外掛程式還必須在 src/plugin.ts 中提供渲染 Block Kit 內容的 admin 路由 — schema 無法強制執行這一點（路由名稱是從原始碼而非清單中探測的），但執行階段會檢查它。

發佈者固定

publisher 固定發佈身份，這樣你就不會意外地在錯誤的帳戶下發佈外掛程式。

在你的首次成功發佈時，如果清單的 publisher 與活動工作階段匹配，它會保持原樣。如果你使用 emdash-plugin init 建立腳手架並將其留空，CLI 會將活動工作階段的 DID 寫回清單。

以下範例顯示了 CLI 寫入的行，為了可讀性新增了已解析的控制代碼作為註解：

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

在每次後續發佈時，CLI 會將活動工作階段和固定的 publisher 解析為 DID 並進行比較。不匹配會立即以 MANIFEST_PUBLISHER_MISMATCH 失敗 — 沒有覆寫標誌。有意解決它：

• 工作階段錯誤：emdash-plugin switch <did>，然後再次發佈。
• 真正將外掛程式轉移到新發佈者：編輯清單中的 publisher。

不發佈的情況下驗證

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # 特定目錄

使用 tsc 風格的 file:line:column 診斷進行離線 schema 檢查，包括跨欄位規則。適用於預提交鉤子或 CI 步驟。重複索引鍵和未知索引鍵是錯誤（嚴格模式捕獲 "licens" 拼寫錯誤）。

CLI 標誌仍然優先

顯式標誌（--license、--author-name、…）在兩者都設定時會覆蓋清單值 — 對 CI 覆蓋有用。--no-manifest 完全跳過清單（如果在預設路徑存在清單則發出警告，這樣發佈者固定安全故事保持可見）。

下一步

• emdash-plugin CLI
• 打包和發佈
• Capabilities 和安全性