外掛

操作者以外掛加入行程內擴展。一個外掛是一個目錄、一份 plugin.json，以及自己載入上下文中的一個組件。它可以貢獻工具、協定用戶端、核准分類器、斜線命令、鉤子、原始鉤子和提示佔位符。主機載入外掛、外部工具和技能之後，用這些目錄的唯讀快照呼叫 Attach，然後用活動的工作階段和審查模型呼叫 AttachSession。實作 IPluginModelClient 的外掛還會收到這些模型的用戶端。帶有被接納狀態欄位的外掛隨後收到 AttachStatus。

主機擁有目錄註冊、核准、工作區圍欄、輸出截斷和逾時。外掛程式碼不繞過 ToolInvocationPolicy。

這不是什麼

機制	角色
PluginRegistry	第一方行程內貢獻（內建工具和六種線路協定）。
外部工具集	tools/ 下模型可呼叫的工具。它們不實作此契約，也沒有鉤子。見 external-tools.md。
技能	透過 skill 工具載入的 Markdown 指令。
MCP	已推遲。它不是外掛執行器。

身份

外掛沒有 JSON 身份欄位。外掛就是 plugins/ 下的目錄。

~/.crystal/plugins/<directory>/plugin.json
<workspace>/.crystal/plugins/<directory>/plugin.json

執行時資料單獨位於這兩棵樹中的 data/plugins/<directory>/；見資料目錄。

覆蓋鍵：目錄名。專案目錄整體替換同名的主目錄外掛。目錄名是 1–64 個字元，以字母開頭，然後是 A–Z a–z 0–9 _ . -。

IPlugin.Name 是 /plugins 顯示的名稱。它必須非空。兩個已載入的外掛不能共用它。

發現

config.json 欄位 plugins 啟用發現（預設 true）。為 true 時，該欄位從寫入的檔案中省略。為 false 時，不掃描清單。crystal run --plugins on|off 為一次行程覆寫該開關，且不寫回。

plugin.json 欄位 enabled 開啟或關閉一個外掛（預設 true）。"enabled": false 在覆蓋之後省略該外掛，沒有操作者說明。缺失、不可讀或無效的清單跳過該外掛並記錄一條英文說明。工作階段仍然啟動。

/plugins 列出已載入的外掛和任何未載入的目錄。/plugins on、/plugins off 和 /plugins reload 在發現開關改變時持久化它並重新載入目錄。/plugins enable <directory>、/plugins disable <directory> 和 /plugins show <directory> 更改或顯示一份清單。前綴 home 或 project 選擇那棵樹。沒有前綴時，專案目錄優先於 Home。更改後該命令重新載入目錄。它不建立目錄。損壞的清單保持不變。

crystal plugins list、show、enable 和 disable 在工作階段外做同樣的事。--source home|project 選擇樹。--workspace 選擇專案根。--home 選擇資料目錄。預設輸出是 Spectre.Console 表格。--format text 把相同欄位印出為對齊的純文字。這些命令寫入 plugin.json 中的 enabled，不寫入 config.json。開啟一個外掛不會開啟發現。crystal run --plugins 仍然是僅限行程的覆寫。

清單

plugin.json 是 JSON。未知欄位被忽略。

{
  "enabled": true,
  "assembly": "Acme.Plugin.dll",
  "type": "Acme.AcmePlugin"
}

assembly 是外掛目錄內的路徑。type 是公用入口類型。它實作 CrystalCode.Plugins.IPlugin，並有公用無參數建構函式。