# 外掛與技能

## 外掛

### 什麼是外掛？

外掛是在執行期擴展 Neotask 功能的 TypeScript 模組。它們可以添加新的訊息頻道、代理程式工具、RPC 方法、CLI 命令、背景服務和技能。

### 官方外掛

**訊息頻道：**
- Microsoft Teams、Matrix、Nostr、Zalo、Feishu/Lark、LINE、Nextcloud Talk、Mattermost、Tlon、Twitch

**功能：**
- **語音通話**, 用於入站/出站語音通話的 SIP 電話支援
- **記憶體（LanceDB）**, 具有向量相似性搜尋的長期記憶體
- **MCP Native**, 用於橋接外部工具的模型上下文協定伺服器整合

**驗證提供者：**
- Google Antigravity OAuth、Gemini CLI OAuth、Qwen OAuth、Minimax OAuth、VS Code Copilot Proxy

### 外掛功能

外掛可以註冊：
- **RPC 方法**, 用戶端呼叫的自訂 WebSocket 方法
- **HTTP 處理程式**, Gateway 上的自訂 HTTP 端點
- **代理程式工具**, 代理程式可以呼叫的具有類型化結構描述的新工具
- **CLI 命令**, 額外的命令列命令
- **背景服務**, Gateway 管理的長期執行程序
- **技能**, 與外掛捆綁的技能目錄
- **自動回覆命令**, 無需 AI 代理程式即可執行的命令

### 外掛安全性

Neotask 會在外掛執行前進行多層檢查：

- **簽署並驗證。** 公開 Construct 目錄中的套件由 Neotask 發布，發布前會自動檢查，並以 Neotask 的發布金鑰簽署。安裝前，Neotask 會以內建於 Neotask 的金鑰驗證簽章，並驗證下載檔案的 SHA-256 雜湊值。
- **不執行安裝指令碼。** Construct 套件已內含相依套件，因此安裝時絕不會執行套件管理員或安裝指令碼。其他外掛安裝使用 npm 時，安裝指令碼會保持關閉。
- **安裝時掃描。** 從 Construct 以外安裝的外掛會接受危險程式碼掃描，發現嚴重問題時會阻止安裝。
- **依版本授權。** 只有在您的帳戶持有該版本的有效授權時，Construct 外掛才會載入。已撤銷的版本不會載入。
- **代理動作需要核准。** 代理的工具呼叫（包括外掛新增的工具）都會依照您的核准政策檢查，需要您同意的動作會等待您的核准。代理若要在 Neotask 內附的安裝方案之外安裝軟體，一律會向您顯示確切的指令並等待您的核准。
- **選用沙箱。** 您可以讓代理的工具在隔離的 Docker 容器中執行，而不是直接在您的電腦上執行。沙箱預設為關閉；啟用方式請參閱[安全性](security.md)。

原生外掛在 Gateway 程序內執行，因此從 Construct 以外安裝的外掛是您選擇執行的程式碼。請使用 `plugins.allow` 列出允許載入的外掛。

---

## 技能

### 什麼是技能？

技能是模組化功能，教導代理程式新的工作流程。每個技能都是一個 markdown 檔案（`SKILL.md`），其中包含在相關時注入代理程式上下文的指令。

### 技能位置（優先順序）

1. **工作空間技能**, `<workspace>/skills/`（最高優先）
2. **管理技能**, `~/.neotask/skills/`
3. **捆綁技能**, 隨 Neotask 提供
4. **外掛技能**, 與已安裝外掛一起封裝的技能
5. **額外目錄**, 額外設定的路徑（最低優先）

當多個技能共享相同名稱時，最高優先位置獲勝。

### 技能功能

- **使用者可呼叫**, 使用斜線命令直接觸發技能（例如 `/docker-build`）
- **模型可呼叫**, 代理程式在相關時可以自主呼叫的技能
- **命令分派**, 映射至特定工具的技能
- **需求管控**, 技能只在滿足需求時載入（所需二進位檔、設定鍵、環境變數、外掛）

### 建立技能

建立帶有 YAML 前置資料的 `SKILL.md` 檔案，定義技能的元資料和指令：

**前置資料欄位：**
- `name`, 技能識別符
- `description`, 技能的功能
- `homepage`, 文件連結
- `user-invocable`, 使用者是否可以直接觸發
- `disable-model-invocation`, 防止代理程式自主呼叫
- `command-dispatch`, 要分派至的工具
- `metadata.neotask.requires`, 先決條件（二進位檔、設定、環境變數、外掛）

**正文：** 教導代理程式如何使用技能的 Markdown 指令，包括範例和準則。

### 技能目錄

在[技能目錄](/skills)中瀏覽可用技能。

### 技能類別

技能涵蓋廣泛的功能：

| 類別 | 範例 |
|------|------|
| **生產力** | 電子郵件管理、日曆、文件生成 |
| **開發** | Git 操作、CI/CD、Docker、程式碼審查 |
| **溝通** | 訊息傳送、通知、公告 |
| **媒體** | 圖像處理、影片編輯、音訊轉錄 |
| **AI 與模型** | 模型切換、提示管理、RAG |
| **智慧家居** | IoT 裝置控制、自動化觸發 |
| **工具** | 檔案轉換、資料轉換、網頁爬取 |