外掛中心

外掛中心讓你不必離開編輯器就能安裝外掛。它和 cdui plugin install 是同一套安裝流程的兩個入口，所以一次安裝會做哪些事、什麼算失敗、失敗叫什麼名字，兩邊都是同一份答案。

打開它有兩條路：側邊欄的自訂與外掛分頁裡，外掛區段標題上有一顆按鈕，寫著外掛中心...；或是工具列 > 設定 > 選用套件與外掛 > 外掛中心 > 開啟。旁邊的套件中心是另一個視窗、管的是另一件事——模型檔與 Python 套件，不是節點；見選用套件包。

清單

視窗分成三塊：外掛清單、清單上方收合著的從來源安裝區塊，以及右邊回報目前進行中安裝的那一欄。

全部、已安裝、未安裝用來篩選清單。「未安裝」是這台機器上沒有的——你從沒裝過的，以及你解除安裝掉的。其餘都算在「已安裝」裡，包括你停用掉的，以及安裝還在跑的。

每張卡片會寫上外掛名稱、一顆狀態標籤（已安裝、停用、未安裝、已移除、安裝中或檔案遺失）與版本，接著是說明文字，然後是兩行小字。第一行說它從哪裡來：內建、官方、本機連結或本機複本（附上複製來源的路徑），抓取來源的 owner/repo 連結，以及它鎖定的那個 commit。第二行說它帶來什麼：涵蓋哪些章節、註冊幾個節點，以及安裝它會一併裝進來的 Python 套件。按鈕排在最後，而且只要這一列有任何動作在進行中，全部按鈕都會關掉。

安裝內建套件包

這個版本本身就帶了六個套件包：edu、foundations、deep、rl、stats、eval。找到那一列，按安裝即可。內建套件包不是第三方，所以沒有東西要你同意，也沒有第二顆按鈕要按。

工作結束後，面板會重新讀取型錄、節點定義與外掛介面，所以新節點會直接出現在節點面板裡，不需要重新整理頁面。它們的名稱都帶著所屬套件包——edu:FilterRows、foundations:Edu-KNN——所以在節點面板搜尋套件包 id 就找得到。

從 GitHub 安裝

展開清單上方的從來源安裝。裡面的欄位接受型錄中的名稱、owner/repo、owner/repo@ref（標籤、分支或 commit）、GitHub URL、其他 git 主機的 HTTPS URL（見從其他 git 主機安裝），或伺服器上的路徑（見從資料夾或壓縮檔安裝）；欄位下方那行字列出所有可用的寫法。檢視只會讀取某一個確定 commit 上的 manifest，不會安裝任何東西。回來的是清單最上方的一張卡片，之後的安裝是對這張卡片動作，而不是對分支一分鐘後的內容動作。

卡片會寫出外掛名稱、作者、版本與 commit，以及它會安裝的 Python 套件。下面則是它要求的東西：

• 這個外掛要求： 每個宣告的能力各一行——network、filesystem 或 process-env——每一行都說明授予它的代價是什麼。清單下面那句話才是重點：「授予只是聲明，執行時不會強制限制；外掛之後不會再詢問。」勾選框寫的是同意授予這些能力。
• 信任這位作者，允許匯入 ……（後面接著模組名稱）是第二個勾選框，對應這個外掛要求關閉安全掃描的那些模組。這是對作者的判斷，不是對某個功能的判斷。
• 外掛帶有介面時，卡片上會多出一則警告：「包含會在編輯器中以完整權限執行的 JavaScript。」瀏覽器端的程式碼不在上面兩個勾選框的範圍內。

manifest 提出的每個勾選框都勾完之前，安裝都是不能按的；取消則把這次檢視丟掉。已經裝過的外掛，按鈕會變成重新安裝，意思是用這一版取代現有的安裝。

從資料夾或壓縮檔安裝

用隨身碟或共用磁碟發下來、無法連上 GitHub 的外掛，在同一個欄位輸入它的路徑即可：外掛資料夾，或是它的 .zip、.tar.gz、.tgz 壓縮檔。路徑是在伺服器所在的那台機器上讀取的，所以別台筆電上的資料夾讀不到。可用的寫法有四種：

• 絕對路徑：/Volumes/USB/my-plugin、D:\plugins\my-plugin.zip；
• 以 ./ 或 ../ 開頭的相對路徑，以伺服器的工作目錄為起點（單獨的 plugins/x 代表 GitHub 的 owner/repo）；
• 家目錄底下的路徑：~/Downloads/my-plugin.tgz；
• file:// URL：file:///srv/share/my-plugin。

壓縮檔的 manifest 可以放在根目錄，或放在唯一的頂層資料夾裡；macOS 壓縮時加進去的 __MACOSX 資料夾會被忽略。

檢視會把資料夾複製（或把壓縮檔解開）到一個暫存目錄，在那裡讀取 manifest。限制與 GitHub 下載相同：壓縮檔 100 MB、解開後 500 MB 與 20,000 個檔案，不能有符號連結、裝置檔，也不能有任何成員落在外掛資料夾之外。複製資料夾時會略過 .git、__pycache__、.venv、venv 與 node_modules。卡片上會寫**本機資料夾：或本機壓縮檔：**加上路徑，並提出與儲存庫相同的問題。安裝時會再複製一次來源，經過安全掃描、相依套件安裝與暫存，放進 <USER_DATA>/plugins/<id>/。你的資料夾不會被修改，之後也不會從那裡載入。

安裝鎖定的是檢視時讀到的內容：壓縮檔本身的 sha256，或複製出來的資料夾裡每個檔案的 sha256。在檢視與安裝之間被修改過的資料夾，會以「changed after it was reviewed」拒絕；請重新檢視一次。本機複本沒有更新，因為沒有地方可以抓新版。要換成新的版本，用重新安裝（或 cdui plugin install <路徑> --force）蓋過去。

從其他 git 主機安裝

放在 GitLab、Gitea 或 Forgejo、Codeberg、Bitbucket，或學校自架伺服器上的外掛，在同一個欄位輸入 https://host/owner/repo 即可，.git 與 @ref（分支、標籤或 commit）都可加可不加：https://gitlab.com/school/ml-nodes.git@v1.2、https://git.school.edu:3000/teacher/demo。只接受 https:// URL，而且裡面不能帶使用者名稱或 token；ssh://、git@host:owner/repo 與 http:// 都會被拒絕。github.com 的 URL 仍照上面說明的方式走 GitHub API。

檢視會用伺服器上的 git 把儲存庫複製到暫存目錄（ref 是分支或標籤時做淺層複製，ref 是 commit 時複製完整歷史），在那裡讀取 manifest；複製結果同樣受上一節的資料夾限制，.git 不會被複製進去，超過五分鐘的複製會被中止。卡片上會寫儲存庫：加上 URL，以及讀到的那個 commit。安裝時會再複製一次那個 commit，所以檢視之後才移動的分支，裝進來的仍是你檢視過的內容。安裝後那一列會連到該 URL，並提供更新：用記錄的 URL 與 ref 再複製一次，答案與 GitHub 的更新相同，共三種。

這種來源需要伺服器的 PATH 上有 git。沒有的話會以「從這個 git 主機安裝需要伺服器上有 git」拒絕；GitHub 儲存庫與本機資料夾不需要 git。私人儲存庫從外面看起來跟不存在一樣：伺服器不會詢問密碼。

啟用、停用、更新、解除安裝

停用會把外掛留在磁碟上，只把它的節點從註冊表拿掉；啟用再放回去。兩者都不下載任何東西。

更新只會出現在從儲存庫（GitHub 或其他 git 主機）抓來的外掛上，而且有三種答案：已經是最新、新版本比目前安裝的版本多要求了什麼（於是打開一張檢視卡片，上面列出多出來的能力），或是沒有新東西需要同意、工作直接開始。內建套件包沒有更新按鈕：它隨版本發佈，用 cdui update 更新。用 cdui plugin link 連結的目錄也沒有，因為它本來就是你磁碟上的內容；從本機資料夾或壓縮檔複製進來的外掛同樣沒有。

解除安裝會先問一次，而且那句話會寫出外掛名稱與移除它的兩個後果：使用它節點的圖將無法執行，以及它安裝的 Python 套件會保留。下載或複製進來的外掛，目錄會被刪掉（原本的資料夾或壓縮檔留在原處）；內建套件包則保留檔案並記成「已移除」，在你再次按名稱安裝之前都不會回來。這裡不會移除任何外掛的 Python 套件：伺服器不能把自己正在使用的套件從執行中的直譯器底下抽掉。解除安裝完成後，右邊那一欄會列出留下來、而且其他地方都不再需要的套件，以及停掉伺服器後用來移除它們的那行 uv pip uninstall 指令。

觀看安裝進度

右邊那一欄會寫出外掛名稱、目前在哪個步驟（正在解析來源、正在下載、正在解壓縮、正在檢查程式碼、安裝 Python 套件、正在複製檔案、正在寫入安裝紀錄、正在載入節點），以及整個工作的進度，下面則是安裝程式自己的紀錄。取消安裝會停掉它；關掉視窗則不會：工作屬於伺服器，所以重新打開面板、換一個分頁，或重新整理頁面，都會接回同一個工作。這個面板和套件中心加起來，同一時間只跑一個安裝。

失敗的工作會在「或在終端機安裝：」底下，提供能重現這一列的那行 cdui plugin install 指令。見外掛指令。

從網路安裝

檢視、安裝、更新、取消與解除安裝，在伺服器不是綁在回送（loopback）位址時一律拒絕，這是在每個寫入動作本來就需要的工作階段 token 之外再加一層：這幾件事決定的是這台機器會匯入哪些程式碼。把編輯器開在區域網路位址上時，檢視、安裝、更新與解除安裝在所有瀏覽器裡都是關的，包括伺服器本機那一個，底部會寫著「僅能在執行伺服器的電腦上安裝。」取消安裝仍然按得下去，但伺服器會拒絕。刻意對區域網路提供服務的教室或實驗室，可以用 CODEFYUI_ALLOW_REMOTE_PLUGIN_INSTALL=1 重新開放。啟用與停用不受這道限制——它們處理的是這台機器已經有、而且你已經同意過的程式碼——所以遠端瀏覽器只要有 token，仍然可以把外掛開開關關。

檔案放在哪裡

下載來的外掛，以及從本機資料夾或壓縮檔複製進來的外掛，都放在 <USER_DATA>/plugins/<id>/，而 <USER_DATA>/plugins/installed.json 記錄每一次安裝，包含你授予的能力，所以下次 cdui start 還找得到它們。以 cdui start 或 cdui dev 啟動的伺服器，以及每一個 cdui plugin 指令，<USER_DATA> 是 <install dir>/.codefyui_dev/（預設安裝位置為 ~/CodefyUI/.codefyui_dev/）；事先已設定 CODEFYUI_USER_DATA_DIR 時就是那個目錄。平台目錄（Windows 的 %LOCALAPPDATA%\codefyui、macOS 的 ~/Library/Application Support/codefyui、Linux 的 ~/.local/share/codefyui）只適用於沒有設定該變數、手動啟動的 uvicorn app.main:app。內建套件包不會被複製到任何地方：它們放在版本內的 plugins/<id>/，就地啟用，所以鎖定檔對它們記的是一筆紀錄，不是一份副本。

疑難排解

• 「請輸入 owner/repo[@ref]、GitHub URL、其他 git 主機的 https://host/owner/repo[@ref]，或伺服器上的資料夾、.zip、.tar.gz 路徑……」 這個字串連伺服器都沒問就被擋下來了，因為它不是一個來源：這個欄位接受的是這個版本內建的套件包名稱、帶有選用 @ref 的 owner/repo、GitHub URL、其他 git 主機的 https:// URL，或從資料夾或壓縮檔安裝列出的任一種路徑寫法。如果打的是一個這個版本不認得的單字，則是由伺服器拒絕，並在下面印出哪些名稱才有效。
• 「沒有安裝任何東西：……的 Python 套件會替換伺服器正在使用的套件。」 外掛的 Python 套件一律以「只新增」的方式安裝，並套用一份約束檔，把伺服器環境中已安裝的每個套件都鎖在目前版本（CodefyUI 本身這類可編輯安裝除外），所以外掛要求的任何東西都不會取代伺服器已經有的套件。當這件事沒辦法在執行中完成時，工作會在複製檔案與寫入紀錄之前就停下來——外掛沒有被安裝，磁碟上也沒有任何改變。停掉伺服器，執行面板印出的那行 uv pip install，再安裝一次。對同一台執行中的伺服器再試一次，結果會完全一樣。
• 解除安裝時說目錄還在。 有東西開著裡面的檔案，這在 Windows 上是最常見的原因。這種情況什麼都沒被移除：鎖定檔的紀錄還在，外掛也還是安裝狀態。關掉正在使用那個目錄的程式，或停掉伺服器，再解除安裝一次。
• 檔案遺失。 鎖定檔裡有這個外掛，但它的目錄不見了。按安裝會開啟一張檢視卡片，說這個外掛已經安裝；在卡片上按重新安裝就會重新抓一次檔案。解除安裝則清掉那筆紀錄。
• 「伺服器上的這個路徑沒有東西。」 路徑是在伺服器那台機器上讀取的。確認磁碟在那台機器上有掛載，以及相對路徑是從伺服器的工作目錄算起；改用絕對路徑就不必考慮這件事。
• 「這個外掛含有連結、裝置檔，或指向資料夾外的路徑。」 以及其他關於大小、檔案數或目錄結構的拒絕，都會寫出資料夾或壓縮檔違反的是哪一條規則。這種情況什麼都沒有被複製。
• 「…… changed after it was reviewed」。 檔案與檢視時讀到的不一樣。再按一次檢視，安裝它顯示的內容。
• 「從這個 git 主機安裝需要伺服器上有 git。」 在伺服器那台機器上安裝 git，確認它在伺服器啟動時的 PATH 上，然後重新啟動伺服器。
• 「這個 git 主機上沒有這個儲存庫或 ref，或是需要登入。」 檢查 URL 與 @ref。私人儲存庫無法用這種方式安裝；請把它下載成壓縮檔，改安裝那個檔案。
• 「複製儲存庫花了太久。」 從伺服器連到那個主機很慢或連不上。稍後再試，或改用儲存庫的壓縮檔安裝。
• 「已達 GitHub 請求上限」。 未帶憑證的 GitHub 請求是按來源位址計算的，一整間教室共用一個 NAT 出口，一個上午就可能用完。在伺服器設定 CODEFYUI_GITHUB_TOKEN，或稍後再試。

路由、安全性層級，以及每一種拒絕的正式名稱，見外掛包。