快速开始：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 --global

2.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 安装失败

原因：网络问题或权限不足

解决方法：

1. 检查网络连接
2. 使用 sudo 安装（需要管理员权限）
3. 手动下载安装脚本并执行

常见问题 3：依赖安装失败

原因：Node.js 版本不兼容

解决方法：

• 使用 Node.js 18 或更高版本
• 清除 npm 缓存：npm cache clean --force

本课小结

本课我们完成了：

• ✅ 安装 OCX 包管理器
• ✅ 添加 KDCO Registry
• ✅ 安装 opencode-notify 插件
• ✅ 触发第一个桌面通知
• ✅ 了解手动安装方法

关键要点：

1. opencode-notify 使用原生桌面通知，无需频繁切换窗口
2. OCX 是推荐的安装方式，自动管理依赖和更新
3. 默认只通知父会话，避免子任务噪音
4. 终端聚焦时自动抑制通知

下一课预告

下一课我们学习 工作原理。

你会学到：

• 插件如何监听 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 ID
• isQuietHours()：检查当前时间是否在静音时段
• isParentSession()：判断是否为父会话
• isTerminalFocused()：检测终端是否为前台窗口