本指南適用於基於舊版 definePlugin() 形式編寫的沙盒外掛程式作者。按順序處理這些破壞性變更。它們都不會改變您的鉤子或路由在執行階段的行為方式；它們改變的是外掛程式的宣告、建置和發布方式。
有關每個套件中的完整變更清單，請參閱 EmDash 更新日誌。
破壞性變更
重新命名：@emdash-cms/registry-cli 現在是 @emdash-cms/plugin-cli
早期版本將 CLI 作為 @emdash-cms/registry-cli 發布，帶有 emdash-registry 二進位檔案。
該套件現在是 @emdash-cms/plugin-cli，二進位檔案是 emdash-plugin。舊套件不再發布。
我應該怎麼做？
替換依賴項：
pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli在所有呼叫位置將 emdash-registry 替換為 emdash-plugin。每個子命令保持其名稱（bundle、publish、login、whoami、switch、validate），並新增了 init、build 和 dev。參見外掛程式 CLI。
變更：沙盒外掛程式使用 satisfies SandboxedPlugin 定義
早期版本將外掛程式的鉤子和路由包裝在從 emdash 匯入的 definePlugin() 中，每個處理器的參數都需要手動註解。
沙盒外掛程式現在是一個用 satisfies SandboxedPlugin 註解的純預設匯出。類型來自 emdash/plugin，這是一個僅類型的入口點，打包器會將其刪除。TypeScript 從鉤子或路由名稱推斷每個處理器的 event 和 ctx，因此處理器參數不需要註解。
我應該怎麼做？
對外掛程式的原始檔進行四項變更。替換匯入：
import { definePlugin, type ContentHookEvent, type PluginContext } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";將 definePlugin() 包裝器替換為純物件和 satisfies 註解：
export default definePlugin({ /* hooks, routes */ });
export default { /* hooks, routes */ } satisfies SandboxedPlugin;從每個處理器中刪除參數註解：
handler: async (event: ContentHookEvent, ctx: PluginContext) => {
handler: async (event, ctx) => {結果是一個預設匯出的物件：
import type { SandboxedPlugin } from "emdash/plugin";
export default {
hooks: {
"content:beforeSave": {
handler: async (event, ctx) => {
return event.content;
},
},
},
} satisfies SandboxedPlugin;要在輔助函式中命名事件類型，從 emdash/plugin 匯入：
import type { ContentHookEvent, PluginContext } from "emdash/plugin";處理器的 event 始終是該鉤子的規範類型。使用更窄的介面註解處理器不再通過類型檢查。使用 typeof 檢查或守衛在執行階段驗證您依賴的任何欄位，這是處理來自類型系統外部資料的正確方法。
變更：外掛程式是一個 src/plugin.ts 加 emdash-plugin.jsonc
早期版本將外掛程式拆分為兩個檔案：src/index.ts 返回一個 PluginDescriptor（id、version、capabilities、storage、entrypoint），src/sandbox-entry.ts 包含鉤子和路由。
外掛程式現在是一個執行階段檔案 src/plugin.ts（鉤子和路由）和一個手動編輯的清單 emdash-plugin.jsonc（身分和信任合約）。entrypoint 和 format 欄位已消失；建置會連接它們。
我應該怎麼做？
使用上述形式將鉤子和路由移動到 src/plugin.ts。將描述符的詮釋資料移動到 package.json 旁邊的 emdash-plugin.jsonc。描述符 id 變成清單 slug；capabilities、allowedHosts 和 storage 保持其形式；version 從 package.json 讀取，因此省略它。
以下範例顯示了宣告一個儲存集合的描述符的清單等效項：
{
"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",
"slug": "plugin-hello",
"publisher": "did:plc:abc123def456",
"license": "MIT",
"author": { "name": "Jane Doe", "url": "https://example.com" },
"security": { "email": "[email protected]" },
"capabilities": [],
"allowedHosts": [],
"storage": { "events": { "indexes": ["timestamp"] } }
}有關所有欄位，請參見外掛程式清單，有關 publisher 欄位，請參見發布者鎖定。
在 package.json 中，將 "./sandbox" 匯出指向建置的執行階段檔案：
"./sandbox": "./dist/sandbox-entry.mjs"
"./sandbox": "./dist/plugin.mjs"將清單新增到 files，以便隨套件一起發布：
"files": ["dist"]
"files": ["dist", "emdash-plugin.jsonc"]變更：使用 emdash-plugin build 建置
早期版本使用手寫的 tsdown 指令碼建置兩個原始檔。
emdash-plugin build 讀取 emdash-plugin.jsonc 和 src/plugin.ts 並產生 dist/ 建置物件。emdash-plugin dev 監視並重新建置。
我應該怎麼做？
替換建置指令碼並新增監視指令碼：
"scripts": {
"build": "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean"
"build": "emdash-plugin build",
"dev": "emdash-plugin dev"
}然後驗證並建置：
emdash-plugin validate
emdash-plugin build移除：從 emdash 匯出的標準格式類型和函式
早期版本從 emdash 匯出 StandardPluginDefinition、StandardHookHandler、StandardHookEntry、StandardRouteHandler、StandardRouteEntry 和函式 isStandardPluginDefinition。
這些已被移除。它們是舊版 definePlugin 形式的輔助別名。
我應該怎麼做？
使用 emdash/plugin 中的 SandboxedPlugin 實現相同目的。沙盒外掛程式的預設匯出已經透過其 satisfies SandboxedPlugin 註解進行了類型化，因此沒有 isStandardPluginDefinition 的替代品；如果需要，透過結構（{ hooks?, routes? }）識別外掛程式。
重新命名：執行階段 SandboxedPlugin 類型現在是 SandboxedPluginInstance
這僅影響自訂 SandboxRunner 的作者，例如 @emdash-cms/cloudflare。大多數外掛程式作者可以跳過此部分。
emdash 中的 SandboxedPlugin 現在指的是面向作者的原始碼形式。SandboxRunner.load 返回的執行階段控制代碼是 SandboxedPluginInstance。
我應該怎麼做？
如果您從 emdash 匯入 SandboxedPlugin 來類型化沙盒執行器或持有執行階段外掛程式控制代碼，請將匯入更改為 SandboxedPluginInstance：
import type { SandboxedPlugin } from "emdash";
import type { SandboxedPluginInstance } from "emdash";告知您的使用者
安裝您外掛程式的網站也需要更改其匯入。向他們指出新形式：刪除大括號和 ()。
import { helloPlugin } from "@my-org/plugin-hello";
import hello from "@my-org/plugin-hello";
export default defineConfig({
integrations: [
emdash({
sandboxed: [helloPlugin()],
sandboxed: [hello],
}),
],
});如果您的外掛程式透過其工廠接受組態，該組態將移至管理介面的外掛程式設定。在執行階段透過 ctx.kv 或 settings 讀取它。參見設定。