高级用法：配置技巧与最佳实践

学完你能做什么

理解为什么默认只通知父会话，减少通知噪声
自定义 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()：加载并合并用户配置

5 分钟收到第一个通知

适配你的平台

定制你的通知体验

遇到问题怎么办

查阅配置和事件

看看更新了什么

高级用法：配置技巧与最佳实践

学完你能做什么

你现在的困境

什么时候用这一招

核心思路

🎒 开始前的准备

跟我做

第 1 步：理解父会话过滤

第 2 步：自定义 macOS 通知音效

第 3 步：手动指定终端类型

第 4 步：临时静音通知

第 5 步：平衡通知策略

检查点 ✅

踩坑提醒

配置修改不生效

音效不播放

终端覆盖无效

本课小结

下一课预告

附录：源码参考

高级用法：配置技巧与最佳实践 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

核心思路 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：理解父会话过滤 ​

第 2 步：自定义 macOS 通知音效 ​

第 3 步：手动指定终端类型 ​

第 4 步：临时静音通知 ​

第 5 步：平衡通知策略 ​

检查点 ✅ ​

踩坑提醒 ​

配置修改不生效 ​

音效不播放 ​

终端覆盖无效 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

高级用法：配置技巧与最佳实践

学完你能做什么

你现在的困境

什么时候用这一招

核心思路

🎒 开始前的准备

跟我做

第 1 步：理解父会话过滤

第 2 步：自定义 macOS 通知音效

第 3 步：手动指定终端类型

第 4 步：临时静音通知

第 5 步：平衡通知策略

检查点 ✅

踩坑提醒

配置修改不生效

音效不播放

终端覆盖无效

本课小结

下一课预告

附录：源码参考