快速開始：5分鐘上手 opencode-notify
學完你能做什麼
- 3 分鐘內完成 opencode-notify 外掛程式安裝
- 觸發第一個桌面通知，驗證安裝成功
- 了解不同安裝方式的差異和適用情境
你現在的困境
您委託 AI 完成一個任務後切換到其他視窗工作。現在你每隔 30 秒就切回去看一眼：完成了嗎？出錯了？還是在等權限？opencode-notify 正是為了解決這個問題而生的。
這種反覆切換既打斷思路，又浪費時間。
什麼時候用這一招
在以下情境下啟用 opencode-notify：
- 你經常在 AI 執行任務時切換到其他應用程式
- 你希望在 AI 需要你時被第一時間提醒
- 你想在保持專注的同時不錯過重要事件
核心思路
opencode-notify 的工作原理很簡單：監聽 OpenCode 的事件，在關鍵時刻發送原生桌面通知。
它會通知你：
- ✅ 任務完成（Session idle）
- ✅ 執行出錯（Session error）
- ✅ 需要權限（Permission updated）
它不會通知你：
- ❌ 每個子任務完成（太吵）
- ❌ 終端機聚焦時的任何事件（你在看終端機，不需要通知）
🎒 開始前的準備
前置要求
- 已安裝 OpenCode
- 有可用的終端機（macOS Terminal、iTerm2、Windows Terminal 等）
- macOS/Windows/Linux 系統（三者均支援）
跟我做
第 1 步：選擇安裝方式
opencode-notify 提供兩種安裝方式：
| 方式 | 適用情境 | 優點 | 缺點 |
|---|---|---|---|
| OCX 套件管理器 | 大多數使用者 | 一鍵安裝、自動更新、相依套件管理完整 | 需要先安裝 OCX |
| 手動安裝 | 特殊需求 | 完全控制、無需 OCX | 需手動管理相依套件和更新 |
推薦：優先使用 OCX 安裝，更省心。
第 2 步：透過 OCX 安裝（推薦）
2.1 安裝 OCX 套件管理器
OCX 是 OpenCode 的官方外掛程式套件管理器，可以方便地安裝、更新和管理外掛程式。
安裝 OCX：
curl -fsSL https://ocx.kdco.dev/install.sh | sh你應該看到：安裝指令碼顯示進度，最後提示安裝成功。
2.2 新增 KDCO Registry
KDCO Registry 是一個外掛程式倉庫，包含 opencode-notify 等多個實用外掛程式。
新增 registry：
ocx registry add https://registry.kdco.dev --name kdco你應該看到：提示 "Registry added successfully" 或類似資訊。
可選：全域設定
如果你想在所有專案中使用同一個 registry，新增 --global 參數：
ocx registry add https://registry.kdco.dev --name kdco --global2.3 安裝 opencode-notify
安裝外掛程式：
ocx add kdco/notify你應該看到：
✓ Added kdco/notify to your OpenCode workspace第 3 步：一次性安裝整個工作區（可選）
如果你想要完整的體驗，可以安裝 KDCO 工作區，它包含：
- opencode-notify（桌面通知）
- 背景代理（Background Agents）
- 專用代理（Specialist Agents）
- 規劃工具（Planning Tools）
安裝工作區：
ocx add kdco/workspace你應該看到：提示多個元件被成功新增。
第 4 步：驗證安裝
安裝完成後，我們需要觸發一個通知來驗證設定是否正確。
驗證方法 1：讓 AI 完成一個任務
在 OpenCode 中輸入：
請計算 1 到 10 的和，然後等待 5 秒後告訴我結果。切換到其他視窗工作幾秒後，你應該看到桌面通知彈出。
驗證方法 2：檢查設定檔
查看設定檔是否存在：
# macOS/Linux
cat ~/.config/opencode/kdco-notify.json
# Windows PowerShell
type $env:USERPROFILE\.config\opencode\kdco-notify.json你應該看到：
- 如果檔案不存在 → 說明使用預設設定（正常）
- 如果檔案存在 → 顯示你的自訂設定
第 5 步：手動安裝（備選方案）
如果你不想使用 OCX，可以手動安裝。
5.1 複製原始碼
將 opencode-notify 的原始碼複製到 OpenCode 外掛程式目錄：
# 從原始碼複製到獨立目錄
mkdir -p ~/.opencode/plugin/kdco-notify
cp src/notify.ts ~/.opencode/plugin/kdco-notify/
cp -r src/plugin/kdco-primitives ~/.opencode/plugin/kdco-notify/5.2 安裝相依套件
手動安裝必要的相依套件：
cd ~/.opencode/plugin/
npm install node-notifier detect-terminal @opencode-ai/plugin @opencode-ai/sdk注意事項
- 相依套件管理：需要手動安裝和更新
node-notifier和detect-terminal - 更新困難：每次更新都需要手動重新複製原始碼
- 不推薦：除非有特殊需求，建議使用 OCX 安裝
檢查點 ✅
完成上述步驟後，請確認：
- [ ] OCX 安裝成功（
ocx --version能輸出版本號） - [ ] KDCO Registry 已新增（
ocx registry list顯示 kdco） - [ ] opencode-notify 已安裝（
ocx list顯示 kdco/notify） - [ ] 收到第一個桌面通知
- [ ] 通知顯示正確的任務標題
如果某個步驟失敗：
- 查看 故障排除 取得協助
- 檢查 OpenCode 是否正常執行
- 確認你的系統支援桌面通知
踩坑提醒
常見問題 1：通知不顯示
原因：
- macOS：系統通知被關閉
- Windows：通知權限未授予
- Linux：未安裝 notify-send
解決方法：
| 平台 | 解決方法 |
|---|---|
| macOS | 系統設定 → 通知 → OpenCode → 允許通知 |
| Windows | 設定 → 系統 → 通知 → 開啟通知 |
| Linux | 安裝 libnotify-bin：sudo apt install libnotify-bin |
常見問題 2：OCX 安裝失敗
原因：網路問題或權限不足
解決方法：
- 檢查網路連線
- 使用 sudo 安裝（需要管理員權限）
- 手動下載安裝指令碼並執行
常見問題 3：相依套件安裝失敗
原因：Node.js 版本不相容
解決方法：
- 使用 Node.js 18 或更高版本
- 清除 npm 快取：
npm cache clean --force
本課小結
本課我們完成了：
- ✅ 安裝 OCX 套件管理器
- ✅ 新增 KDCO Registry
- ✅ 安裝 opencode-notify 外掛程式
- ✅ 觸發第一個桌面通知
- ✅ 了解手動安裝方法
關鍵要點：
- opencode-notify 使用原生桌面通知，無需頻繁切換視窗
- OCX 是推薦的安裝方式，自動管理相依套件和更新
- 預設只通知父工作階段，避免子任務噪音
- 終端機聚焦時自動抑制通知
下一課預告
下一課我們學習 運作原理。
你會學到：
- 外掛程式如何監聽 OpenCode 事件
- 智慧過濾機制的工作流程
- 終端機檢測和焦點感知的原理
- 不同平台的功能差異
附錄：原始碼參考
點選展開查看原始碼位置
更新時間：2026-01-27
| 功能 | 檔案路徑 | 行號 |
|---|---|---|
| 外掛程式主入口 | src/notify.ts | 1-407 |
| 設定載入 | src/notify.ts | 90-114 |
| --- | --- | --- |
| --- | --- | --- |
| --- | --- | --- |
| 通知發送 | src/notify.ts | 280-308 |
| 終端機檢測 | src/notify.ts | 145-176 |
| 靜音時段檢查 | src/notify.ts | 181-199 |
| 預設設定 | src/notify.ts | 30-48 |
關鍵常數：
DEFAULT_CONFIG.sounds.idle = "Glass"：任務完成預設音效DEFAULT_CONFIG.sounds.error = "Basso"：錯誤預設音效DEFAULT_CONFIG.sounds.permission = "Submarine"：權限請求預設音效DEFAULT_CONFIG.notifyChildSessions = false：預設只通知父工作階段
關鍵函式：
NotifyPlugin()：外掛程式入口函式，回傳事件處理器loadConfig()：載入設定檔，合併預設值sendNotification()：發送原生桌面通知detectTerminalInfo()：偵測終端機類型和 Bundle IDisQuietHours()：檢查目前時間是否在靜音時段isParentSession()：判斷是否為父工作階段isTerminalFocused()：偵測終端機是否為前景視窗