進階用法：設定技巧與最佳實務

學完你能做什麼

理解為什麼預設只通知父工作階段，減少通知雜訊
自訂 macOS 通知音效，區分不同類型事件
手動指定終端機類型，解決自動偵測問題
設定暫時靜音，避免會議、專注時段被打擾
優化通知策略，平衡即時性和干擾度

你現在的困境

通知外掛雖然很方便，但預設設定可能不適合所有人的工作習慣：

想追蹤所有 AI 子任務，但預設只通知父工作階段
使用小眾終端機，自動偵測失敗
會議時希望暫時靜音，但不想每次改設定檔
不同類型事件用同樣音效，分不清是任務完成還是出錯

什麼時候用這一招

當你已經熟悉外掛基礎用法，想要根據個人工作流優化通知體驗時。

核心思路

通知外掛的預設設定經過精心設計，但你可以透過設定檔調整行為。核心原則是：

減少雜訊，提升價值

父工作階段過濾：只通知主任務，忽略 AI 內部子任務
焦點感知：終端機啟用時不通知，避免重複提醒
批次通知：多個任務同時完成時合併通知

提示

所有設定項目在設定參考中有詳細說明。本課聚焦實際使用技巧和最佳實務。

🎒 開始前的準備

確保你已完成快速開始並成功接收到第一個通知。

跟我做

第 1 步：理解父工作階段過濾

為什麼

OpenCode 工作階段是樹狀結構：一個父工作階段可能有多個子工作階段。預設情況下，外掛只通知父工作階段完成，避免子任務的通知雜訊。

查看設定

編輯設定檔：

bash

# macOS/Linux
~/.config/opencode/kdco-notify.json

# Windows
%APPDATA%\opencode\kdco-notify.json

json

{
  "notifyChildSessions": false  // ← 預設 false
}

你應該看到：

notifyChildSessions: false 意味著只通知根工作階段
AI 內部執行的子工具呼叫不會觸發通知

何時啟用子工作階段通知

如果需要追蹤每個子任務（如除錯多步驟工作流），設定為 true：

json

{
  "notifyChildSessions": true  // ← 啟用後，每個子任務都會通知
}

注意

啟用子工作階段通知會顯著增加通知頻率，建議謹慎使用。

第 2 步：自訂 macOS 通知音效

為什麼

不同類型事件用不同音效，能讓你不看通知就知道發生了什麼。

查看可用音效

macOS 系統提供 14 種內建音效：

音效名	適用情境	風格
Glass	任務完成（預設）	清脆
Basso	錯誤（預設）	低沉
Submarine	權限請求（預設）	柔和
Bottle	特殊事件	輕快
Ping	一般提醒	簡潔
Pop	輕鬆事件	活潑
Purr	成功事件	溫和
Blow	警告	緊迫
Funk	特殊標記	獨特
Frog	提醒	響亮
Hero	重要事件	宏大
Morse	通知	節奏感
Sosumi	系統提示	經典
Tink	完成	輕快

自訂音效

修改設定中的 sounds 部分：

json

{
  "sounds": {
    "idle": "Ping",        // 任務完成
    "error": "Blow",      // 錯誤（更緊急）
    "permission": "Pop",   // 權限請求（更輕快）
    "question": "Tink"    // 問題詢問（可選，預設使用 permission 音效）
  }
}

你應該看到：

修改後，不同類型事件播放對應音效
如果未設定 sounds.question，將使用 sounds.permission 的音效

提示

音效只在 macOS 上生效，Windows 和 Linux 使用系統預設通知音效。

第 3 步：手動指定終端機類型

為什麼

detect-terminal 函式庫支援 37+ 終端機，但小眾終端機或自訂建置版本可能無法識別。

檢查目前偵測到的終端機

暫時無法直接查看偵測結果，但可以透過日誌判斷：

bash

# OpenCode UI 會顯示外掛啟動日誌

如果看到類似 "Terminal detection failed" 或通知無法聚焦，可能需要手動指定。

手動指定終端機

在設定中新增 terminal 欄位：

json

{
  "terminal": "wezterm"  // 使用終端機的小寫名稱
}

支援的終端機名稱

常用終端機名稱（不區分大小寫）：

終端機	設定值
Ghostty	`"ghostty"`
Kitty	`"kitty"`
iTerm2	`"iterm"` 或 `"iterm2"`
WezTerm	`"wezterm"`
Alacritty	`"alacritty"`
macOS Terminal	`"terminal"` 或 `"apple_terminal"`
Hyper	`"hyper"`
VS Code 終端機	`"code"` 或 `"code-insiders"`

你應該看到：

手動指定後，macOS 焦點偵測和點擊聚焦功能正常運作
如果指定無效，外掛會靜默失敗，回退到自動偵測

第 4 步：暫時靜音通知

為什麼

會議、程式碼審查或專注時段，你可能希望暫時不接收通知。

使用靜音時段

如果你每天固定時段（如夜間）不希望被打擾，設定靜音時段：

json

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",  // 晚上 10 點
    "end": "08:00"     // 次日早上 8 點
  }
}

跨午夜時段支援

靜音時段可以跨午夜（如 22:00-08:00）：

json

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"     // 22:00 - 次日 08:00
  }
}

你應該看到：

在靜音時段內，所有事件不發送通知
時段外恢復正常通知

提示

時間格式必須是 HH:MM（24 小時制），如 "22:30"。

第 5 步：平衡通知策略

為什麼

預設設定已經經過優化，但你可能需要根據工作流調整。

預設策略總結

設定項目	預設值	效果
`notifyChildSessions`	`false`	只通知父工作階段
`quietHours.enabled`	`false`	不啟用靜音時段

提示

焦點偵測功能（終端機啟用時不通知）是硬編碼啟用的，無法透過設定關閉。

推薦設定組合

情境 1：追求最小干擾（預設）

json

{
  "notifyChildSessions": false
}

情境 2：追蹤所有任務

json

{
  "notifyChildSessions": true
}

注意

這會顯著增加通知頻率，適合需要細粒度監控的情境。

情境 3：夜間靜音

json

{
  "notifyChildSessions": false,
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"
  }
}

你應該看到：

根據不同情境，通知行為有顯著差異
逐步調整找到最適合你的設定

檢查點 ✅

完成設定後，驗證以下內容：

檢查項目	驗證方法
父工作階段過濾	觸發一個帶子任務的 AI 任務，只收到一個「Ready for review」通知
音效自訂	分別觸發任務完成、錯誤、權限請求，聽到不同音效
終端機覆寫	macOS 下點擊通知，終端機視窗正確置頂
靜音時段	在靜音時段內觸發事件，不收到通知

踩坑提醒

設定修改不生效

問題：修改設定檔後，通知行為沒有變化。

原因：OpenCode 可能需要重啟外掛或 OpenCode 本身。

解決：重啟 OpenCode CLI 或 OpenCode UI。

音效不播放

問題：設定了自訂音效，但仍是預設音效。

原因：

音效名稱拼寫錯誤
不在 macOS 平台

解決：

檢查音效名稱是否在支援列表中（區分大小寫）
確認使用 macOS 系統

終端機覆寫無效

問題：設定了 terminal 欄位，但點擊通知仍無法聚焦。

原因：

終端機名稱錯誤
終端機程序名稱與設定值不匹配

解決：

嘗試小寫名稱
查看支援的終端機列表

本課小結

本課學習了 opencode-notify 的進階用法和最佳實務：

父工作階段過濾：預設只通知根工作階段，避免子任務雜訊
音效自訂：macOS 可自訂 14 種音效，區分事件類型
終端機覆寫：手動指定終端機類型，解決自動偵測問題
暫時靜音：透過 quietHours 設定靜音時段
策略平衡：根據工作流調整設定，平衡即時性和干擾度

核心原則：減少雜訊，提升價值。預設設定已經經過優化，大多數情況下無需修改。

下一課預告

下一課我們學習 故障排除。
你會學到：
通知不顯示怎麼辦
焦點偵測失效如何排查
常見錯誤資訊解讀
平台特定問題解決方案

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-27

功能	檔案路徑	行號
父工作階段偵測	`src/notify.ts`	205-214
設定 Schema	`src/notify.ts`	30-68
預設設定	`src/notify.ts`	56-68
macOS 音效列表	`README.md`	81

關鍵常數：

DEFAULT_CONFIG：預設設定值
TERMINAL_PROCESS_NAMES：終端機名稱到 macOS 程序名稱對應表

關鍵函式：

isParentSession()：判斷工作階段是否為父工作階段
loadConfig()：載入並合併使用者設定

進階用法：設定技巧與最佳實務 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

核心思路 ​

🎒 開始前的準備 ​

跟我做 ​

第 1 步：理解父工作階段過濾 ​

第 2 步：自訂 macOS 通知音效 ​

第 3 步：手動指定終端機類型 ​

第 4 步：暫時靜音通知 ​

第 5 步：平衡通知策略 ​

檢查點 ✅ ​

踩坑提醒 ​

設定修改不生效 ​

音效不播放 ​

終端機覆寫無效 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

進階用法：設定技巧與最佳實務

學完你能做什麼

你現在的困境

什麼時候用這一招

核心思路

🎒 開始前的準備

跟我做

第 1 步：理解父工作階段過濾

第 2 步：自訂 macOS 通知音效

第 3 步：手動指定終端機類型

第 4 步：暫時靜音通知

第 5 步：平衡通知策略

檢查點 ✅

踩坑提醒

設定修改不生效

音效不播放

終端機覆寫無效

本課小結

下一課預告

附錄：原始碼參考