> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 外掛

> 從市集安裝技能、子代理、MCP 伺服器與 hooks 的組合包

外掛將[技能](/zh-Hant/ctor/reference/skills)、[子代理](/zh-Hant/ctor/reference/sub-agents)、[MCP 伺服器](/zh-Hant/ctor/reference/mcp)與 [hooks](/zh-Hant/ctor/reference/hooks) 組合在一起，讓您可以從市集一次安裝。CTOR 的外掛系統與 Claude Code 外掛生態系相容。

## 外掛面板

點選側邊欄中的 **Plugins**（外掛）開啟面板。這一個按鈕取代了先前分開的 **Skills**、**Sub-Agents** 與 **MCP** 按鈕。

面板有四個分頁：

* **外掛** —瀏覽市集並安裝外掛
* **技能** —先前技能面板的所有功能（請參閱[技能](/zh-Hant/ctor/reference/skills)）
* **子代理** —先前子代理面板的所有功能（請參閱[子代理](/zh-Hant/ctor/reference/sub-agents)）
* **MCP** —先前 MCP 面板的所有功能（請參閱 [MCP 伺服器](/zh-Hant/ctor/reference/mcp)）

技能、子代理與 MCP 分頁保留了它們所取代面板的全部管理功能。

## 新增市集

市集是列出一個或多個外掛的 GitHub 儲存庫，或本機資料夾。在您新增任何市集之前，**外掛**分頁會顯示空白狀態（尚未新增市集）。

在**外掛**分頁中，於輸入欄位輸入 GitHub 儲存庫，然後點選**新增**。可接受的格式：

* `owner/repo`
* `owner/repo@ref` —其中 `ref` 為分支、標籤或提交 SHA
* 任何 `github.com` 網址

若要改從磁碟新增市集，請點選資料夾按鈕並選擇本機資料夾。

每個市集會顯示為獨立的區塊，列出其外掛。本機來源會顯示**本機**徽章；內建市集（見下文）則會顯示**內建**徽章。區塊上有兩個動作：

* **重新整理** —重新擷取清單並檢查外掛更新
* **移除** —移除市集，並顯示行內確認（要移除這個市集嗎？已安裝的外掛會保留。）——內建市集沒有此動作

### GitHub Token 驗證

在**外掛**分頁頂端設定 **GitHub Token**，即可提高 GitHub 匿名速率限制，並新增您的 token 有讀取權限的私有儲存庫。儲存後會以遮罩顯示（例如 `••••1a2b`）——點選**編輯**可變更，點選**清除**可移除。

您新增的每個 GitHub 市集，都能在儲存庫輸入欄旁選擇驗證方式：

| 授權     | 行為                        |
| ------ | ------------------------- |
| **全域** | 使用您已儲存的 GitHub token（預設）  |
| **自訂** | 只為此市集使用另一個 token——新增前必須設定 |
| **無**  | 不使用 token——僅限公開儲存庫        |

市集的授權模式會以\*\*授權：{mode}\*\*徽章顯示在其區塊標題中。

<Warning>
  Token 會以純文字形式儲存於本機，未經加密。請使用僅授權給市集所需儲存庫的 token。
</Warning>

### 資訊清單格式

CTOR 會依以下順序讀取市集的資訊清單：

1. `.bricks-plugin/marketplace.json`
2. `.claude-plugin/marketplace.json`

當兩者同時存在時，以 `.bricks-plugin` 格式為準。僅包含 `plugin.json` 的儲存庫會被視為單一外掛的市集。

### 內建市集

CTOR 內建了一個市集——**bricks-ctor-agent-skills**，來自 `mybigday/bricks-ctor-agent-skills`。它一律已註冊、無需任何設定，並會在啟動時與每天自動重新整理；若無法連上 GitHub，則會保留上次快取的內容。

它收錄 BRICKS 團隊的官方 plugin，其中包含 **App Templates**（`app-templates`）——將現有應用程式轉換成可重複使用的提示範本，以簡短的需求清單描述其設計、狀態與資料流，讓您能重建或改造它。由市集提供代表這些 plugin 不需發布 app 版本即可更新。

它的區塊會以醒目樣式呈現，並固定在市集清單的最下方，附有**內建**徽章（將滑鼠移到上面可看到提示文字）。它沒有**移除**動作，且名稱受到保留——從其他來源新增或取代名為 `bricks-ctor-agent-skills` 的市集會失敗，並顯示「此名稱屬於內建市集，無法取代或移除。」

## 外掛卡片

每個外掛會顯示一張卡片，包含名稱、版本與說明，以及摘要其內容和安裝位置的徽章：

* **安裝範圍** —**全域**、**此專案**或 **N 個專案**
* **MCP ×N** —外掛所包含的 MCP 伺服器數量
* **Hooks** —當外掛定義了 hooks 時顯示；在您啟用之前會顯示 **Hooks（未核准）**

卡片動作：

| 動作       | 說明                 |
| -------- | ------------------ |
| **安裝**   | 安裝外掛（開啟安裝對話框）      |
| **管理**   | 變更已安裝的技能選擇         |
| **更新**   | 當市集有較新版本時可用        |
| **解除安裝** | 從目前範圍移除外掛（再次點選以確認） |
| **全部移除** | 從所有範圍移除外掛          |

## 安裝外掛

點選**安裝**會開啟**安裝 {name}** 對話框。對話框開頭是一則信任提示。

<Warning>
  技能會指示代理並可讀取專案檔案，請只安裝來自可信任儲存庫的外掛。
</Warning>

提示下方列出外掛提供的所有內容，讓您選擇要安裝的項目：

* **技能**以核取方塊呈現，需自行勾選，並提供 **Select all** / **Select none**。當目標範圍中已存在同名技能時，該技能會顯示**覆寫**徽章。名稱與內建技能衝突的技能會顯示**保留名稱**徽章，並會被略過。
* **代理**與技能並列顯示。
* **MCP 伺服器**需要逐一伺服器明確同意，位於一則「MCP 伺服器會執行本機程序」提示之下。每個伺服器會顯示其解析後的完整指令列，且預設不勾選。
* **Hooks** 需要單一次明確同意，位於一則「Hooks 會在代理事件時執行本機指令」提示之下。點選\*\*啟用 hooks（N）\*\*即可在同意前檢視每個事件、比對器與指令。

CTOR 尚不支援的元件會列為**尚不支援（已忽略）**——目前包含斜線指令。

安裝按鈕會顯示目前的選取數量，例如**安裝（3）**。

### 安裝範圍

**此專案 | 全域**分段控制項可選擇目標範圍：

* **全域**安裝會套用至每個專案與主聊天。技能會放入 `~/.bricks-project-desktop/skills/`。
* **專案**安裝僅套用至開啟的專案。技能會放入 `.bricks/skills/`。

外掛安裝的技能會出現在**技能**分頁中，並帶有**外掛：{plugin}** 徽章。外掛安裝的代理會出現在**子代理**分頁中（不帶徽章）。

## 更新與安全性

* 外掛的 MCP 伺服器存放在機器本機的登錄中，絕不會寫入專案的 `.mcp.json`。
* MCP 核准會綁定至指令。若指令在更新後變更，您必須重新核准。
* 更新會取代未修改的外掛檔案，但絕不會覆寫您已編輯過的技能或代理——會保留您編輯過的版本。解除安裝時亦同。
* 更新只會重新展開您在安裝時所選的技能。更新中新增的技能需要重新安裝才能選擇加入。

## MCP 範圍與繼承

**MCP** 分頁有自己的**此專案 | 全域**切換器。

* **全域**會編輯主工作區的 `.mcp.json`，標示為「主工作區 — 所有專案都會繼承」。
* 專案會在自己的伺服器之下繼承全域伺服器。專案項目依名稱優先，因此整體優先順序為外掛 \< 繼承 \< 專案。
* 每個專案都有**繼承全域 MCP 伺服器**切換。
* 繼承的伺服器會顯示**全域**徽章；外掛的伺服器會顯示**外掛**徽章。

關於如何設定與管理伺服器，請參閱 [MCP 伺服器](/zh-Hant/ctor/reference/mcp)。

## Claude Code 相容性

現有的 Claude Code 外掛或市集可在 CTOR 中原封不動地運作：

* CTOR 會讀取 `.claude-plugin/` 資訊清單。
* 它會解析 MCP 與 hook 指令中的 `${CLAUDE_PLUGIN_ROOT}`（以及 `${BRICKS_PLUGIN_ROOT}`）。
* 僅會啟用技能、代理、MCP 伺服器與 hooks。其他 Claude Code 元件類型會被忽略。

## 錯誤訊息

當安裝程式無法新增市集或外掛時，會回報明確的錯誤，包含：

* 無效的儲存庫規格
* 找不到儲存庫，或您的 token 無法讀取該私有儲存庫
* GitHub 速率限制
* 下載或解壓縮失敗
* 遺失或無效的資訊清單——純技能儲存庫可改從**技能**分頁安裝
* 不支援的來源類型