外掛程式清單

每個沙箱外掛程式都在其 package.json 旁邊有一個 emdash-plugin.jsonc。它需要手動編輯，包含外掛程式的身分、信任契約（能力、主機、儲存）以及註冊表顯示的設定檔欄位。emdash-plugin init 生成鷹架；CLI 在 build、dev、validate、bundle 和 publish 時自動讀取 ./emdash-plugin.jsonc。

該檔案是 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]" },

	// 可選設定檔
	"name": "Gallery",
	"description": "EmDash 的圖片畫廊區塊。",
	"keywords": ["gallery", "images"],
	"repo": "https://github.com/example/plugin-gallery",

	// 信任契約
	"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"] }
	}
}

能力

已識別的名稱：

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

• network:request 要求非空的 allowedHosts。如果外掛程式確實需要到達任何主機，請改用 network:request:unrestricted。
• network:request:unrestricted 要求 allowedHosts 為空 — 無限制能力已經授予所有主機，因此列表會產生矛盾。

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

儲存

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

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

管理介面

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

"admin": {
	"pages": [{ "path": "/gallery", "label": "畫廊", "icon": "image" }],
	"widgets": [{ "id": "recent-uploads", "title": "最近上傳", "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/    # 特定目錄

包含交叉欄位規則的離線 schema 檢查，使用 tsc 風格的 檔案:行:列 診斷。適合預提交鉤子或 CI 步驟。重複鍵和未知鍵是錯誤（嚴格模式捕獲 "licens" 等拼寫錯誤）。

CLI 旗標始終優先

明確的旗標（--license、--author-name 等）在兩者都設定時覆蓋清單值 — 適用於 CI 覆蓋。--no-manifest 完全跳過清單（如果預設路徑存在清單則發出警告，以保持發布者固定安全機制的可見性）。

下一步

• emdash-plugin CLI
• 打包和發布
• 能力與安全