plugins.json 與 notecraft-plugin.json

Plugin 相關的設定檔有兩份，由不同的人寫：

兩份都有對應的 JSON Schema。在檔案開頭加上 $schema，編輯器就會提示欄位與格式：

plugins.json

<專案根> 是你執行 notecraftapp 指令時所在的目錄。沒有這個檔案時，plugin 功能整個不啟用，不報錯。

{
  "plugins": [
    { "plugin": "er-diagram-renderer", "files": ["**/*.er.json"] }
  ]
}

頂層欄位

每一條規則

glob 支援 *、**、?、{a,b}，大小寫有別，. 開頭的資料夾不比對。plugin id 的寫法是小寫英數，以 - 連接，例如 openapi-renderer。

build 時的檢查

id 的寫法、不認得的欄位這類格式限制，build 不會擋，只會在編輯器透過 $schema 提示。

規則的寫法與多條命中時的行為見映射規則 plugins.json，disabled 見啟用與停用。

notecraft-plugin.json

每個 plugin 資料夾的根目錄都有一份，檔名固定。只是使用 plugin 的話不需要改它；這一節給想讀懂或自己寫 plugin 的人。

{
  "id": "my-renderer",
  "title": "我的渲染器",
  "description": "把某種 JSON 資料畫成頁面",
  "version": "0.1.0"
}

欄位

manifest 沒有 entry 與 accepts：

• 入口檔名固定是同一個資料夾裡的 renderer.tsx，它的 default export 就是渲染器
• 這個 plugin 吃哪些檔案，完全由專案的 plugins.json 決定，plugin 自己不宣告

什麼時候檢查

安裝時的其他檢查（檔案類型、import 白名單）見安全模型。

engines

"engines": { "notecraftapp": ">=1.6.0" }

install-plugin 只認得三種寫法：

不合時拒絕安裝，並顯示需要的版本與你目前的版本。

meta

資料檔頁的標題、描述與「回到來源筆記」連結，預設讀資料檔頂層的 meta.title、meta.description、meta.backTo。資料格式不是你自己定的（例如 OpenAPI 文件的標題在 info.title），就在 manifest 的 meta 以 JSON Pointer 指定來源：

"meta": {
  "title": "/info/title",
  "description": "/info/description",
  "backTo": "/x-notecraft-back-to"
}

• 每個值都要以 / 開頭，或是空字串（指整份資料）
• 沒寫的鍵仍退回 meta.<鍵>
• 取到的值不是字串時，當作沒有
• 需要 notecraftapp 1.6.0 以上，建議同時把 engines.notecraftapp 寫成 >=1.6.0

plugin 資料夾

.notecraft/plugins/
├── _types.d.ts                 安裝時產生，給 renderer 取得型別
└── <id>/
    ├── notecraft-plugin.json   manifest
    ├── renderer.tsx            入口，檔名固定
    └── schema.json             資料的 JSON Schema（檔名由 dataSchema 決定）

renderer.tsx 收到的 props：

renderer 能 import 的套件與 AI 生成元件共用同一份白名單，見安全模型。