@freely01/opencode-notify 0.3.0 → 0.4.0

package/README.md

@@ -1,35 +1,20 @@
 # opencode-notify
 
-opencode 通知插件 — 监听会话中的关键事件，通过多渠道推送通知到你的手机、群聊或桌面。
-
-> ⚠️ **由AI辅助生成，内容及程序请辨别使用**
->
-> **个人项目，按需使用**
->
-> 此插件主要面向作者个人使用场景开发和测试，不一定适合所有用户和环境。
->
-> **AI 提示：**
-> - Windows 系统通知需额外安装 [BurntToast](https://github.com/Windos/BurntToast) PowerShell 模块
-> - Linux 系统通知需 `libnotify` 包（桌面发行版通常预装）
-> - 事件映射基于 @opencode-ai/plugin@1.15.12 的行为，后续版本升级可能影响兼容性
-> - `run_completed` 事件暂未实现（opencode 无直接完成事件）
-> - 屏幕跑马灯效果：Linux X11（Python + PyGObject）/ Windows（PowerShell + WinForms）四边彩色流动
-> - 仅在 Ubuntu 24.04 (X11) 环境下测试并使用，其它平台未验证
->
-> 如有问题欢迎提 Issue，但不保证及时响应和修复。
-
-## 功能特性
-
-- 监听 `permission_required` / `input_required` / `run_failed` 等事件
-- 多渠道通知：系统通知、企业微信、飞书、自定义 Webhook（Gotify / Bark / PushDeer 等）
-- YAML 配置文件，每项参数均有详细注释
-- 去重机制：同一事件在时间窗口内不重复发送
-- 会话感知抑制：活跃会话按事件类型智能过滤，不遗漏 `run_failed` 等重要通知
-- 零外部运行时依赖（仅 js-yaml 用于配置解析）
-- **屏幕跑马灯**：通知时屏幕四边高亮闪烁（Linux X11，Python + GTK 内置；Windows 实验性，PowerShell + WinForms）
+opencode 通知插件 — 监听会话关键事件，通过多渠道推送通知到手机、群聊或桌面。
+
+> ⚠️ **个人项目，按需使用** — 主要在 Ubuntu 24.04 (X11) 环境测试，其他平台可能存在问题。
+> 如有问题欢迎提 [Issue](https://github.com/luyanfeng/opencode-notify/issues)，不保证及时响应和修复。
+
+## 功能一览
+
+- **多渠道通知**：系统通知 + 屏幕跑马灯 + 企业微信 + 飞书 + 自定义 Webhook
+- **会话感知抑制**：活跃会话智能过滤冗余通知，不遗漏 `run_failed` 等重要事件
+- **Terminator 子屏检测**：自动识别子屏最大化遮挡场景，被隐藏的会话强制通知
+- **远程延迟推送**：正常通知发出后，对远程渠道额外延迟补偿，防止错过
+- **去重机制**：同一事件在时间窗口内不重复发送
 - **渠道级事件过滤**：每个渠道可独立配置监听哪些事件，灵活分流
-- **远程延迟推送**：正常通知发出后，指定渠道额外延迟推送以防遗漏
-- **Terminator 子屏检测**：自动检测子屏最大化场景，被遮挡的会话强制通知
+- **零外部运行时依赖**：仅 `js-yaml` 用于配置解析
+- **诊断 CLI**：验证配置、发送测试通知、调试事件流
 
 ## 平台支持
 
@@ -37,93 +22,84 @@ opencode 通知插件 — 监听会话中的关键事件，通过多渠道推送
 |------|:-----:|:-----:|:-------:|
 | 插件核心（事件监听/路由/分发） | ✅ | ✅ | ✅ |
 | 自定义 Webhook / 企业微信 / 飞书 | ✅ | ✅ | ✅ |
-| 诊断 CLI (`bun cli.ts`) | ✅ | ✅ | ✅ |
-| **系统消息通知** | ✅ `osascript` 内置 | ⚠️ 需 `libnotify` 包 | ⚠️ 需 BurntToast 模块 |
-| **屏幕跑马灯** | ❌ | ✅ Python+GTK 内置 | ✅ PowerShell+WinForms |
-
-**说明：**
-- **macOS**: 系统通知使用 `osascript`，系统内置，开箱即用
-- **Linux**: 系统通知使用 `notify-send`，来自 `libnotify`。桌面发行版通常预装，如缺失可 `apt install libnotify-bin` / `yum install libnotify`
-- **Windows**: 系统通知使用 PowerShell `New-BurntToastNotification`，需额外安装 [BurntToast](https://github.com/Windos/BurntToast) 模块。Webhook 渠道不受影响
-- **屏幕跑马灯**: Linux X11 使用 Python + PyGObject(GTK 3) 创建透明覆盖窗口，60fps 彩色四边跑马灯动画；Windows 使用 PowerShell + .NET WinForms 创建屏幕四边彩色闪烁边框（实验性）。中间完全透明可点击穿透，不影响操作。macOS 暂不支持
-- 非系统通知模块（Webhook 推送、CLI 诊断）均为纯 HTTP/Node API，全平台一致
+| 诊断 CLI | ✅ | ✅ | ✅ |
+| **系统消息通知** | ✅ `osascript` | ⚠️ 需 `libnotify` | ✅ WinRT Native Toast |
+| **屏幕跑马灯** | ❌ | ✅ Ubuntu 24.04 X11 | ✅ PowerShell+WinForms |
 
-> **已测试渠道：** 系统通知、企业微信、自定义 Webhook（Gotify）。飞书等其他渠道理论可用，暂未做验证。
+> **已测试渠道：** 系统通知、企业微信、自定义 Webhook（Gotify）。飞书等渠道理论可用，暂未验证。
 
 ## 快速开始
 
 ### 1. 安装
 
-将插件添加到 `~/.config/opencode/opencode.json` 的 `plugin` 列表中：
-
-**方式一：从 npm 安装（推荐）**
 ```bash
 npm install -g @freely01/opencode-notify
 ```
 
-```json
-{
-  "plugin": ["@freely01/opencode-notify"]
-}
-```
+详细安装方式（npm / 本地 / Bun）及平台依赖说明 → [doc/install.md](doc/install.md)
+
+### 2. 注册插件
+
+编辑 `~/.config/opencode/opencode.json`：
 
-**方式二：本地路径（开发调试）**
 ```json
 {
-  "plugin": [
-    "file:///home/<你的用户名>/path/to/opencode-notify/index.ts"
-  ]
+  "plugin": ["@freely01/opencode-notify"]
 }
 ```
 
-> 本地路径替换为你实际存放项目的目录。
-
-### 2. 配置
+### 3. 配置
 
-创建 `~/.config/opencode/opencode-notify.yaml`，完整示例：
+首次启动自动生成默认配置 `~/.config/opencode/opencode-notify.yaml`，或参考项目中的 `opencode-notify.yaml.example`。
 
 ```yaml
 channels:
   system_message:
     enabled: true
-    # events: [permission_required, input_required]   # 可选，不填继承全局
-
-  screen_flash:
+  wechat_work:
     enabled: true
-    duration: 3.5
-    speed: 5.0
-    intensity: 0.85
-
+    webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
   custom_webhook:
-    enabled: false
+    enabled: true
     url: "https://gotify.example.com/message"
     headers:
       X-Gotify-Key: "your-app-token"
-    template: '{"title":"{{title}}","message":"{{body}}","priority":5}'
-
-  wechat_work:
-    enabled: false
-    webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
-
-  feishu:
-    enabled: false
-    webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
 
 events:
   - permission_required
   - input_required
   - run_failed
 
-dedupe_seconds: 60
-suppress_when_active: false
-activity_timeout_ms: 30000
+suppress_when_active: true
+activity_timeout_ms: 15000
+suppress_events_when_active:
+  - permission_required
+  - input_required
+
+log:
+  level: info
 ```
 
-## 通知渠道
+完整配置项参考 → [配置参考](#配置参考)
+
+### 4. 验证
+
+```bash
+# 查看插件加载日志
+tail -f ~/.opencode-notify/plugin.log
+
+# 使用诊断 CLI 发送测试通知
+bun run cli.ts --test
+
+# 查看配置概览
+bun run cli.ts --config
+```
+
+---
 
-每个渠道可以独立配置监听的事件，不填则继承全局 `events` 配置。
+## 通知渠道
 
-可选事件值与全局 `events` 一致：
+每个渠道可独立配置监听事件，不填则继承全局 `events`。
 
 | 事件值 | 说明 |
 |--------|------|
@@ -132,69 +108,42 @@ activity_timeout_ms: 30000
 | `run_failed` | 任务执行失败 |
 | `run_completed` | 任务执行完成（技术预留，暂未实现） |
 
-```yaml
-# 自定义 Webhook 只推送权限请求和错误，不推送等待输入
-custom_webhook:
-  enabled: true
-  events:
-    - permission_required
-    - run_failed
-```
-
 ### 系统消息通知
 
-弹出操作系统原生通知横幅。
-
 | 平台 | 实现 |
 |------|------|
-| macOS | `osascript` (display notification) |
-| Linux | `notify-send`（需安装 `libnotify`） |
-| Windows | PowerShell (New-BurntToastNotification) |
+| macOS | `osascript`（内置） |
+| Linux | `notify-send`（需 `libnotify`） |
+| Windows | WinRT Native Toast |
 
 ### 屏幕跑马灯
 
-通知时在屏幕四边生成彩色高亮闪烁效果（跑马灯），视觉上更醒目：
+通知时屏幕四边彩色高亮闪烁，视觉更醒目。
 
 ![跑马灯效果](doc/de.png)
 
-- 独立渠道，可与系统通知分开启停、分开配置事件过滤
-- Linux X11: 使用 Python + PyGObject(GTK 3) 创建透明覆盖窗口，60fps 彩色灯光沿四边循环运动
-- Windows: 使用 PowerShell + .NET WinForms 创建屏幕四边彩色闪烁边框（8px 宽），中间完全透明可点击穿透，不阻挡任何操作
-- 非阻塞执行，不影响通知发送速度
-
 ```yaml
 screen_flash:
   enabled: true
-  # events: [run_failed]       # 可选，不填继承全局
-  duration: 3.0               # 持续秒数（默认 3.0）
-  speed: 4.0                  # 移动速度因子（默认 4.0）
-  intensity: 0.9              # 不透明度 0.0~1.0（默认 0.9）
+  duration: 3.0        # 持续秒数
+  speed: 4.0           # 移动速度因子
+  intensity: 0.9       # 不透明度 0.0~1.0
 ```
 
-### 自定义 Webhook
-
-通用 HTTP POST 发送器，支持任意 Webhook 服务。
-
-**支持的服务举例：**
+- **Ubuntu 24.04 X11**: Python + PyGObject(GTK 3) 创建透明覆盖窗口，60fps 彩色灯光沿四边循环运动
+- **Windows**: PowerShell + .NET WinForms 创建屏幕四边彩色闪烁边框（8px 宽），中间透明可点击穿透
+- 非阻塞执行，不影响通知发送速度
 
-| 服务 | 文档 |
-|------|------|
-| Gotify | [gotify.net](https://gotify.net/) |
-| Bark | [github.com/Finb/Bark](https://github.com/Finb/Bark) |
-| PushDeer | [pushdeer.com](https://pushdeer.com/) |
-| Slack Webhook | [api.slack.com/messaging/webhooks](https://api.slack.com/messaging/webhooks) |
-| Discord Webhook | [support.discord.com](https://support.discord.com/hc/en-us/articles/228383668) |
+### 自定义 Webhook
 
-**配置参数：**
+通用 HTTP 发送器，支持任意 Webhook 服务（Gotify / Bark / PushDeer / Slack / Discord 等）。
 
 | 参数 | 说明 |
 |------|------|
 | `url` | Webhook 地址 |
-| `method` | 请求方法 `POST` / `GET`，默认 `POST` |
-| `headers` | 自定义请求头（如 `X-Gotify-Key`） |
-| `template` | 消息模板，支持占位符 `{{title}}` `{{body}}` `{{event}}` `{{agent}}` `{{sessionID}}` |
-
-**Gotify 配置示例：**
+| `method` | `POST` / `GET`，默认 `POST` |
+| `headers` | 自定义请求头 |
+| `template` | 消息模板，支持 `{{title}}` `{{body}}` `{{event}}` `{{agent}}` `{{sessionID}}` |
 
 ```yaml
 custom_webhook:
@@ -210,110 +159,77 @@ custom_webhook:
 
 通过群机器人 Webhook 发送 Markdown 消息。
 
-**配置步骤：**
-
-1. 在企业微信群中添加群机器人
-2. 复制 Webhook URL
-3. 填入配置文件
-
 ```yaml
 wechat_work:
   enabled: true
   webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
 ```
 
-消息格式：Markdown，实际发送的请求体：
-
-```json
-{
-  "msgtype": "markdown",
-  "markdown": {
-    "content": "**事件标题**\n\n事件详情...\n> 会话: sessionID"
-  }
-}
-```
-
 消息包含：标题（加粗）、事件详情、会话 ID。
 
 ### 飞书
 
 通过自定义机器人或流程触发器 Webhook 发送卡片消息。
 
-**配置步骤：**
-
-1. 在飞书群中添加自定义机器人（或创建流程触发器）
-2. 复制 Webhook URL
-3. 填入配置文件
-
 ```yaml
 feishu:
   enabled: true
   webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
 ```
 
-消息格式：卡片消息（interactive），实际发送的请求体：
-
-```json
-{
-  "msg_type": "interactive",
-  "card": {
-    "header": {
-      "title": { "tag": "plain_text", "content": "事件标题" }
-    },
-    "elements": [
-      { "tag": "markdown", "content": "事件详情..." },
-      { "tag": "hr" },
-      { "tag": "note", "elements": [{ "tag": "plain_text", "content": "会话: sessionID" }] }
-    ]
-  }
-}
-```
-
-消息包含：标题头、正文（Markdown）、分割线、脚注（会话 ID）。
+消息格式：interactive 卡片消息，包含标题头、Markdown 正文、分割线、脚注。
 
 ### 远程延迟推送
 
-正常通知发出后，如果用户长时间未操作（未回到 opencode TUI），针对指定渠道额外再推送一次。
-用户在延迟期间回到 TUI 操作 → 自动取消该会话所有待发延迟通知。
-
-**适用场景：** 用户离开电脑后，系统通知可能一闪而过没看到；延迟推送在用户仍未回来时再次尝试发出。
+正常通知发出后，对指定渠道额外延迟补偿推送。用户在延迟期间回到 TUI 操作 → 自动取消。
 
 ```yaml
-remote_delay_channels:          # 哪些渠道需要额外延迟推送（空=不启用）
-  - system_message
+remote_delay_channels:
   - wechat_work
-  - feishu
   - custom_webhook
-remote_delay_seconds: 60        # 延迟秒数（默认 60）
-remote_delay_max_count: 3       # 最多重复次数（默认 3）
+remote_delay_seconds: 60
+remote_delay_max_count: 3
 ```
 
-**注意：**
-- `remote_delay_channels` 仅影响**额外延迟推送**，不影响正常通知（正常通知该发就发）
-- 延迟推送使用渠道自身的事件过滤规则，只有渠道订阅的事件才会延迟推送
-- 用户在该会话中进行任何操作（输入消息、回应权限、执行命令等）都会取消该会话所有待发延迟
-- 达到 `remote_delay_max_count` 次后停止推送
+**注意：** 仅影响额外延迟推送，不影响正常通知（该发就发）。用户在该会话中操作（输入消息、回应权限等）自动取消所有待发延迟。
 
-### Terminator 子屏遮挡检测（自动）
+---
 
-当用户在 **Terminator** 中最大化某个子屏幕时（`Ctrl+Shift+X`），
-其他子屏幕中的 opencode 会话虽活跃但被遮挡。插件自动检测该场景，
-被遮挡的会话即使活跃也会强制发送通知。
+## Terminator 子屏遮挡检测
 
-**检测原理**：`$TERMINATOR_UUID` + `$TERMINATOR_DBUS_NAME` + `$TERMINATOR_DBUS_PATH`
-环境变量确认在 Terminator 中 → DBus 查询焦点终端 UUID → 与本屏对比
-→ 不一致则强制通知，无需额外配置。
+> 详细设计原理 → [doc/features.md](doc/features.md#4-terminator-子屏幕遮挡检测)
 
-**外部依赖**（任一即可）：`busctl`（systemd 内置）| `python3-dbus` | `gdbus` | `xdotool`
+当你在 Terminator 中最大化某个子屏幕时（`Ctrl+Shift+X`），其他子屏被完全遮挡。插件自动检测此场景，被遮挡的会话即使活跃也强制发送通知。
+
+**检测策略：**
+
+```
+事件被活跃抑制
+  ↓
+Terminator 窗口是当前 X 活跃窗口？     ← xdotool + xprop
+  否 → 用户在别的应用中（浏览器/IDE）→ 强制通知
+  是 → 本屏可见 → 正常抑制
+```
+
+**外部依赖**（检测失败自动降级，不影响正常抑制）：
+
+| 工具 | 用途 | 安装 |
+|------|------|------|
+| `xdotool` | 获取活跃窗口 ID | `apt install xdotool` |
+| `xprop` | 查询窗口 WM_CLASS | 系统自带 |
+
+---
 
 ## 事件映射
 
-| 通知事件 | 触发场景 | 对应 opencode 事件 |
-|----------|---------|-------------------|
-| `permission_required` | Agent 需要授权（执行命令、读写文件等） | `permission.asked` / `question.asked` |
-| `input_required` | Agent 等待用户输入 | `session.idle` / `session.status` (idle) |
+| 通知事件 | 触发场景 | opencode 事件 |
+|----------|---------|---------------|
+| `permission_required` | Agent 需要授权 | `permission.asked` / `question.asked` |
+| `input_required` | Agent 等待用户输入 | `session.idle` / `session.status(idle)` |
 | `run_failed` | 任务执行失败 | `session.error` |
-| `run_completed` | 任务完成（预留，暂未实现） | 待组合判断 |
+| `run_completed` | 任务完成（预留） | — |
+
+---
 
 ## 配置参考
 
@@ -332,191 +248,121 @@ YAML 文件 > plugin options (opencode.json) > 默认值
 ```yaml
 channels:
   system_message:
-    enabled: true              # 系统通知开关
-    events: []                 # 可选，渠道级事件过滤（不填继承全局）
-                               # 可选值: permission_required | input_required | run_completed | run_failed
-  screen_flash:              # 屏幕跑马灯（仅 Linux X11）
-    enabled: true            #   开启（默认 false）
-    events: []               #   可选，渠道级事件过滤（不填继承全局）
-                             #   可选值: permission_required | input_required | run_completed | run_failed
-    duration: 3.5            #   持续秒数
-    speed: 5.0               #   移动速度因子
-    intensity: 0.85          #   不透明度 0.0~1.0
-
+    enabled: true
+    events: []
+  screen_flash:
+    enabled: false
+    duration: 3.5
+    speed: 5.0
+    intensity: 0.85
   custom_webhook:
-    enabled: false             # 自定义 Webhook 开关
-    events: []                 # 可选，渠道级事件过滤
-                               # 可选值: permission_required | input_required | run_completed | run_failed
-    url: ""                    # Webhook 地址
-    method: "POST"             # 请求方法 POST | GET
-    headers: {}                # 自定义请求头
-    template: ""               # 消息模板
-
+    enabled: false
+    url: ""
+    method: "POST"
+    headers: {}
+    template: ""
   wechat_work:
-    enabled: false             # 企业微信开关
-    events: []                 # 可选，渠道级事件过滤
-                               # 可选值: permission_required | input_required | run_completed | run_failed
-    webhook_url: ""            # 群机器人 Webhook URL
-                               # 消息格式: Markdown (msgtype=markdown, markdown.content)
-
+    enabled: false
+    webhook_url: ""
   feishu:
-    enabled: false             # 飞书开关
-    events: []                 # 可选，渠道级事件过滤
-                               # 可选值: permission_required | input_required | run_completed | run_failed
-    webhook_url: ""            # 机器人/流程触发器 Webhook URL
-                               # 消息格式: 卡片消息 (msg_type=interactive, card)
-
-events:                        # 订阅的事件列表
-                                 # 可选值: permission_required | input_required | run_completed | run_failed
-
-dedupe_seconds: 60             # 去重时间窗口（秒）
-suppress_when_active: true     # 会话感知抑制开关（按 suppress_events 列表过滤）
-activity_timeout_ms: 15000     # 会话活跃超时（毫秒），超过此时间无操作视为离开
-suppress_events_when_active:   # 活跃时抑制哪些事件（不填=默认列表）
-  - permission_required
-  - input_required
-  # run_failed / run_completed 不在列表中 → 始终通知
-session_stale_timeout_ms: 600000  # 超时会话自动淘汰（毫秒），默认 10 分钟
-remote_delay_channels: []        # 远程延迟推送渠道列表（空=不启用）
-                                 # 可选值: system_message, screen_flash, wechat_work, feishu, custom_webhook
-remote_delay_seconds: 60         # 远程延迟秒数（默认 60）
-remote_delay_max_count: 3        # 远程延迟最多重复次数（默认 3）
-log:                             # 日志配置
-  level: info                    #   等级: error | warn | info | debug（默认 info）
-                                 #   error - 仅记录错误
-                                 #   warn  - 错误 + 警告
-                                 #   info  - 错误 + 警告 + 常规信息（推荐）
-                                 #   debug - 全部日志（排查时使用）
-  # file: "~/.opencode-notify/plugin.log"  #   日志文件路径（可选，默认同上）
-```
-
-### 活跃抑制
-
-当用户正在 opencode TUI 中操作（输入消息、回应权限等），通知可能冗余（屏上已可见）。
-插件通过**会话感知抑制**解决：追踪每个会话的用户操作时间戳，活跃会话按事件类型选择性过滤。
-
-**检测的用户操作事件：**
-`message.updated` / `permission.replied` / `question.replied` / `command.executed` / `tui.command.execute`
-
-**抑制规则：**
-
-| 通知事件 | 活跃时默认行为 | 理由 |
-|---------|:------------:|------|
-| `permission_required` | ✅ 抑制 | 权限弹窗就在屏幕上 |
-| `input_required` | ✅ 抑制 | TUI 明确在等输入 |
-| `run_failed` | ❌ 不抑制 | 异步结果，人可能走开 |
-| `run_completed` | ❌ 不抑制 | 同上 |
+    enabled: false
+    webhook_url: ""
 
-**配置示例：**
+events: [permission_required, input_required, run_failed]
+dedupe_seconds: 60
 
-```yaml
-suppress_when_active: true          # 开启会话感知抑制
-activity_timeout_ms: 15000          # 15 秒无操作视为不活跃
-suppress_events_when_active:        # 活跃时抑制哪些事件
+suppress_when_active: true
+activity_timeout_ms: 15000
+suppress_events_when_active:
   - permission_required
   - input_required
-session_stale_timeout_ms: 600000    # 10 分钟无活动自动淘汰会话（防内存泄漏）
+session_stale_timeout_ms: 600000
+
+remote_delay_channels: []
+remote_delay_seconds: 60
+remote_delay_max_count: 3
+
+log:
+  level: info
 ```
 
-## 日志与故障排查
+### 活跃抑制
 
-插件日志位于 `~/.opencode-notify/plugin.log`（可通过 `log.file` 配置自定义）。
+当用户在 opencode TUI 中操作时，屏上已可见的通知被智能过滤。追踪的用户操作事件：`message.updated` / `permission.replied` / `question.replied` / `command.executed` / `tui.command.execute`。
 
-日志等级由 `log.level` 控制：
+| 事件 | 活跃时行为 |
+|------|:---------:|
+| `permission_required` | ✅ 抑制（屏上可见） |
+| `input_required` | ✅ 抑制（TUI 在等输入） |
+| `run_failed` | ❌ 不抑制（异步结果） |
+| `run_completed` | ❌ 不抑制（预留） |
 
-| 等级 | 包含内容 | 建议用途 |
-|------|---------|---------|
-| `error` | 仅错误 | 生产环境，只关心失败 |
-| `warn` | 错误 + 警告 | 生产环境，关注潜在问题 |
-| `info` | 错误 + 警告 + 常规信息 | 日常运行（默认） |
-| `debug` | 全部日志（含详细事件流） | 排查问题 |
+---
 
-```yaml
-log:
-  level: info                     # 推荐：日常使用记录所有关键信息
-  # level: debug                  # 排查问题时改为 debug
-  # file: "~/.opencode-notify/plugin.log"  # 可选自定义路径
-```
+## 日志与故障排查
 
-日志包含：
+日志位于 `~/.opencode-notify/plugin.log`（可通过 `log.file` 自定义）。
 
-- 插件加载信息（配置、已启用渠道、日志等级）
-- 渠道发送失败 / 成功
-- 会话活跃跳过通知
-- 远程延迟推送调度 / 取消 / 推送
-- 去重命中、状态存储异常等诊断信息
+| 等级 | 内容 | 用途 |
+|------|------|------|
+| `error` | 渠道失败、异常 | 生产环境 |
+| `warn` | 配置异常、部分失败 | 生产环境 |
+| `info` | 渠道启用、通知分发、抑制决策 | 日常运行（默认） |
+| `debug` | 全部事件流、DBus 调用详情 | 排查问题 |
 
 ```bash
-# 实时查看日志
 tail -f ~/.opencode-notify/plugin.log
-
-# 查看最近的插件加载信息
 grep "插件已加载" ~/.opencode-notify/plugin.log
-
-# 只看错误
 grep "\[ERROR\]" ~/.opencode-notify/plugin.log
-
-# 只看警告
-grep "\[WARN\]" ~/.opencode-notify/plugin.log
 ```
 
 ### 常见问题
 
 **Q: 插件未加载？**
-确认 `opencode.json` 中 `plugin` 列表的路径正确，指向 `index.ts` 文件。
+确认 `opencode.json` 中 `plugin` 路径正确，指向 `index.ts`。
 
 **Q: 通知没有弹出？**
-1. 检查日志中是否出现 `[event] type=` 行，确认事件是否被监听到
-2. 检查渠道是否已 `enabled: true`
-3. 检查 Webhook URL 是否正确
-4. 查看 `~/.opencode-notify/plugin.log` 中是否有错误信息
+检查日志是否有 `[event] type=` 行确认事件被监听到；检查渠道 `enabled: true`；检查 Webhook URL 正确性。
 
 **Q: 企业微信/飞书通知失败？**
-确认 Webhook URL 有效，网络可达。可通过 `curl` 直接测试：
+确认 Webhook URL 有效，网络可达：
 
 ```bash
-curl -X POST <webhook_url> -H "Content-Type: application/json" -d '{"msgtype":"markdown","markdown":{"content":"**测试**"}}'
+curl -X POST <webhook_url> -H "Content-Type: application/json" \
+  -d '{"msgtype":"markdown","markdown":{"content":"**测试**"}}'
 ```
 
+---
+
 ## 项目结构
 
 ```
 opencode-notify/
-├── index.ts                 # 插件入口
-├── cli.ts                   # 诊断工具
-├── config.ts                # 配置解析（YAML + plugin options）
-├── events.ts                # 事件路由
-├── log.ts                   # 共享日志模块
-├── session-tracker.ts       # 会话感知抑制
-├── terminator-detect.ts     # Terminator 子屏最大化检测
-├── delayed-dispatcher.ts    # 远程延迟推送调度器
-├── dispatcher.ts            # 去重分发
-├── store.ts                 # 状态存储
-├── message.ts               # 消息模型
+├── index.ts                  # 插件入口
+├── cli.ts                    # 诊断工具
+├── config.ts                 # 配置解析
+├── events.ts                 # 事件路由
+├── log.ts                    # 日志模块
+├── message.ts                # 消息模型
+├── session-tracker.ts        # 会话感知抑制
+├── terminator-detect.ts      # Terminator 子屏遮挡检测
+├── delayed-dispatcher.ts     # 远程延迟推送
+├── dispatcher.ts             # 去重分发
+├── store.ts                  # 状态存储
 ├── doc/
-│   ├── de.png                # 跑马灯效果截图
-│   └── features.md           # 功能说明（含 Terminator 友好体验说明）
+│   ├── install.md             # 安装指南
+│   ├── features.md            # 功能详解
+│   └── de.png                 # 跑马灯效果截图
 ├── scripts/
-│   └── marquee.py           # 屏幕跑马灯效果（Python+GTK）
+│   └── marquee.py             # 屏幕跑马灯脚本
 ├── senders/
-│   ├── types.ts             # Sender 接口
-│   ├── system/              # 系统通知（平台分包）
-│   │   ├── index.ts         #   注册表 + 自动选择平台
-│   │   ├── darwin.ts        #   macOS (osascript)
-│   │   ├── linux.ts         #   Linux (notify-send)
-│   │   └── win32.ts         #   Windows (PowerShell)
-│   ├── screen-flash/        # 屏幕跑马灯（Linux + Windows）
-│   │   ├── index.ts         #   入口 + 平台路由
-│   │   ├── linux.ts         #   Linux 实现 (Python+GTK)
-│   │   └── win32.ts         #   Windows 实现 (PowerShell+WinForms)
-│   ├── custom-webhook.ts    # 自定义 Webhook
-│   ├── wechat-work.ts       # 企业微信
-│   └── feishu.ts            # 飞书
-├── findings.md              # 研究记录
-├── plan.md                  # 需求与实现计划
-├── task_plan.md             # 任务跟踪
-├── progress.md              # 进度日志
+│   ├── types.ts               # Sender 接口
+│   ├── system/                # 系统通知
+│   ├── screen-flash/          # 屏幕跑马灯
+│   ├── custom-webhook.ts
+│   ├── wechat-work.ts
+│   └── feishu.ts
+├── opencode-notify.yaml.example
 ├── package.json
 └── tsconfig.json
 ```
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freely01/opencode-notify",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "opencode 通知插件 - 监听会话事件并通过多渠道推送通知",
   "type": "module",
   "main": "index.ts",

package/senders/system/darwin.ts

@@ -1,17 +1,40 @@
 /**
- * macOS 系统通知
+ * macOS 系统通知（⚠️ 未实际测试）
  *
  * 使用 osascript 调用原生通知中心。
- * - display notification: 弹窗 + 声音
+ * - display notification: 标题 + 副标题 + 正文 + 声音
  * - 系统内置，无需额外安装
+ * - 通知自动进入通知中心
+ *
+ * AppleScript 双引号使用 `""` 转义（与 shell/JScript 的 `\"` 不同）。
  */
 
 import { execSync } from "node:child_process"
 
 export async function notify(title: string, body: string): Promise<void> {
-  const script = `display notification "${body}" with title "${title}" sound name "default"`
+  // sanitize() 将 " 转义为 \"，但 AppleScript 使用 "" 表示双引号。
+  // 此处先还原，再应用 AppleScript 转义。
+  const asTitle = aq(title)
+  const asBody = aq(body)
+
+  // 提取 title 中的 [ses_xxx] 前缀作为副标题
+  const sessionMatch = title.match(/^(\[[^\]]+\])/)
+  const asSubtitle = aq(sessionMatch?.[1] ?? "")
+
+  const script = `display notification "${asBody}" with title "${asTitle}" subtitle "${asSubtitle}" sound name "default"`
   execSync(`osascript -e ${JSON.stringify(script)}`, {
     timeout: 5000,
     stdio: "ignore",
   })
 }
+
+/**
+ * 转为 AppleScript 安全字符串
+ * - 还原 sanitize() 的 \" 转义
+ * - 用 AppleScript 的 "" 方式转义双引号
+ */
+function aq(s: string): string {
+  return s
+    .replace(/\\"/g, '"')  // 还原 sanitize 转义
+    .replace(/"/g, '""')   // AppleScript 双引号转义
+}

package/terminator-detect.ts

@@ -1,24 +1,29 @@
 /**
- * Terminator 子屏幕最大化检测
+ * Terminator 子屏幕遮挡检测
  *
- * 当用户在 Terminator 中最大化某个子屏幕时（Ctrl+Shift+X），
- * 其他子屏幕被遮挡。通过 DBus 查询焦点终端 UUID，
- * 与本进程的 TERMINATOR_UUID 比较，判定本屏是否被遮挡。
+ * 检测当前子屏幕是否被真正遮挡（不可见），用于判定是否需要
+ * 强制通知（即使用户在该会话中活跃）。
  *
- * 检测策略（依次尝试）:
- *   1. busctl（systemd 自带，Ubuntu 预装）
- *   2. python3-dbus（备选）
- *   3. gdbus（GLib 备选）
- *   4. xdotool 窗口类检测（回退，仅判断是否在 Terminator 窗口中）
+ * 检测策略（两级）：
+ *   1. X 窗口级别：Terminator 是否是当前活跃窗口（xdotool + xprop）
+ *      否 → 用户在别的应用中 → 遮挡
+ *   2. 子屏级别：用户当前聚焦的是哪个子屏（DBus get_focused_terminal）
+ *     聚焦 != 本屏 → 用户在另一个子屏上 → 遮挡
+ *
+ * 注意：此版本 Terminator 未暴露 get_maximized_terminal 接口，
+ * 无法区分"分屏可见"和"最大化遮挡"。两级结合覆盖核心场景：
+ *   - Terminator 不活跃（浏览器/IDE）：强制通知
+ *   - 本屏聚焦：不通知
+ *   - 另一子屏聚焦（分屏或最大化）：强制通知
  */
 
 import { execSync } from "node:child_process"
-import { warn, debug } from "./log.js"
+import { debug } from "./log.js"
 
 /** 当前进程的 TERMINATOR_UUID */
 const MY_UUID = process.env.TERMINATOR_UUID ?? null
 
-/** Terminator DBus 信息（每实例唯一） */
+/** Terminator DBus 信息 */
 const DBUS_NAME = process.env.TERMINATOR_DBUS_NAME ?? null
 const DBUS_PATH = process.env.TERMINATOR_DBUS_PATH ?? null
 
@@ -26,10 +31,10 @@ const DBUS_PATH = process.env.TERMINATOR_DBUS_PATH ?? null
 let insideTerminator: boolean | null = null
 
 /**
- * 检测当前子屏幕是否被遮挡（用户在其他子屏幕上操作）
+ * 检测当前子屏幕是否被遮挡（不可见）
  *
- * @returns true  → 本子屏幕被遮挡，不应抑制通知
- *          false → 本子屏幕可见，正常抑制逻辑
+ * @returns true  → 本子屏幕被遮挡（用户看不到，应强制通知）
+ *          false → 本子屏幕可见（正常抑制逻辑）
  *          null  → 无法确定（不在 Terminator 中或检测失败）
  */
 export function isTerminalOccluded(): boolean | null {
@@ -40,57 +45,38 @@ export function isTerminalOccluded(): boolean | null {
 
   insideTerminator = true
 
-  // 如果没有 DBus 名称/路径信息，直接回退到 xdotool
-  if (!DBUS_NAME || !DBUS_PATH) {
-    debug(`Terminator DBus 环境变量不全: name=${DBUS_NAME} path=${DBUS_PATH}，回退到 xdotool`)
-    return callXdotool()
-  }
+  // ─── 第一级：X 窗口级别 ────────────────────────────────────────────────
+  // Terminator 窗口是否是当前 X 活跃窗口？
+  const terminatorActive = isTerminatorWindowActive()
 
-  // 策略 1: busctl
-  try {
-    const focused = callBusctl()
-    if (focused !== null) {
-      const occluded = !uuidEqual(focused, MY_UUID)
-      debug(`Terminator 焦点检测(busctl): 本屏=${shortId(MY_UUID)} 焦点=${shortId(focused)} 遮挡=${occluded}`)
-      return occluded
-    }
-  } catch (e) {
-    debug(`Terminator busctl 失败: ${e instanceof Error ? e.message : String(e)}`)
+  if (terminatorActive === false) {
+    // 用户在其他应用中（浏览器、IDE 等），本屏不可见
+    debug(`Terminator 窗口非活跃（用户在其他应用中），判定为遮挡`)
+    return true
   }
 
-  // 策略 2: python3-dbus
-  try {
-    const focused = callPythonDBus()
-    if (focused !== null) {
-      const occluded = !uuidEqual(focused, MY_UUID)
-      debug(`Terminator 焦点检测(python): 本屏=${shortId(MY_UUID)} 焦点=${shortId(focused)} 遮挡=${occluded}`)
-      return occluded
-    }
-  } catch (e) {
-    debug(`Terminator python-dbus 失败: ${e instanceof Error ? e.message : String(e)}`)
-  }
+  if (terminatorActive === true) {
+    // ─── 第二级：聚焦终端检测 ──────────────────────────────────────────
+    // Terminator 窗口活跃，检查用户聚焦的是不是本屏
+    const focused = queryFocusedTerminal()
 
-  // 策略 3: gdbus
-  try {
-    const focused = callGDBus()
     if (focused !== null) {
-      const occluded = !uuidEqual(focused, MY_UUID)
-      debug(`Terminator 焦点检测(gdbus): 本屏=${shortId(MY_UUID)} 焦点=${shortId(focused)} 遮挡=${occluded}`)
-      return occluded
+      if (focused === MY_UUID) {
+        debug(`Terminator 本屏聚焦，判定为可见`)
+        return false
+      }
+      // 用户聚焦在另一个子屏上 → 本屏不可见（无论分屏还是最大化）
+      debug(`Terminator 用户聚焦在其他子屏(${shortId(focused)})，判定为遮挡`)
+      return true
     }
-  } catch (e) {
-    debug(`Terminator gdbus 失败: ${e instanceof Error ? e.message : String(e)}`)
-  }
 
-  // 策略 4: xdotool 窗口类检测（回退）
-  try {
-    const result = callXdotool()
-    debug(`Terminator 窗口检测(xdotool): ${result}`)
-    return result
-  } catch (e) {
-    warn(`Terminator 所有检测策略均失败，最后错误: ${e instanceof Error ? e.message : String(e)}`)
-    return null
+    // 无法查询焦点状态，保守假设可见
+    debug(`Terminator 窗口活跃，无法查询焦点状态，保守假设不遮挡`)
+    return false
   }
+
+  // 无法确定 X 窗口状态
+  return null
 }
 
 /**
@@ -104,61 +90,62 @@ export function isInsideTerminator(): boolean {
 
 // ─── 工具函数 ───────────────────────────────────────────────────────────────
 
-/** 比较两个 UUID（忽略 urn:uuid: 前缀） */
-function uuidEqual(a: string, b: string): boolean {
-  const strip = (s: string) => s.replace(/^urn:uuid:/i, "")
-  return strip(a) === strip(b)
-}
-
 /** 取 UUID 前 8 位用于日志 */
 function shortId(uuid: string): string {
   return uuid.replace(/^urn:uuid:/i, "").slice(0, 8)
 }
 
-// ─── 检测策略实现 ───────────────────────────────────────────────────────────
-
-/** 策略 1: busctl（systemd） */
-function callBusctl(): string | null {
-  const out = execSync(
-    `busctl --user call ${DBUS_NAME} ${DBUS_PATH} ${DBUS_NAME} get_focused_terminal`,
-    { encoding: "utf-8", timeout: 3000 },
-  ).trim()
-  // 输出格式: s "uuid-string"
-  const m = out.match(/s\s+"([^"]+)"/)
-  return m ? m[1] : null
-}
+// ─── 第一级：X 窗口检测 ──────────────────────────────────────────────────
 
-/** 策略 2: python3-dbus */
-function callPythonDBus(): string | null {
-  const out = execSync(
-    `python3 -c "
-import dbus
-bus = dbus.SessionBus()
-proxy = bus.get_object('${DBUS_NAME}', '${DBUS_PATH}')
-focused = proxy.get_focused_terminal(dbus_interface='${DBUS_NAME}')
-print(focused)
-"`,
-    { encoding: "utf-8", timeout: 5000 },
-  ).trim()
-  return out || null
+/**
+ * 检测 Terminator 窗口是否是当前 X 活跃窗口
+ * @returns true=Terminator 是活跃窗口, false=不是, null=检测失败
+ */
+function isTerminatorWindowActive(): boolean | null {
+  try {
+    const out = execSync(
+      `xprop -id $(xdotool getactivewindow) WM_CLASS 2>/dev/null`,
+      { encoding: "utf-8", timeout: 5000 },
+    ).trim()
+    return out.includes('"Terminator"')
+  } catch (e) {
+    debug(`xprop/xdotool 检测 Terminator 窗口失败: ${e instanceof Error ? e.message : String(e)}`)
+    return null
+  }
 }
 
-/** 策略 3: gdbus（GLib） */
-function callGDBus(): string | null {
-  const out = execSync(
-    `gdbus call --session --dest ${DBUS_NAME} --object-path ${DBUS_PATH} --method ${DBUS_NAME}.get_focused_terminal`,
-    { encoding: "utf-8", timeout: 3000 },
-  ).trim()
-  // 输出格式: ('uuid-string',)
-  const m = out.match(/\('([^']+)'/)
-  return m ? m[1] : null
-}
+// ─── 第二级：聚焦终端检测 ───────────────────────────────────────────────
+
+/**
+ * 通过 DBus 查询当前聚焦的子屏 UUID
+ * @returns UUID 字符串，或 null（查询失败）
+ */
+function queryFocusedTerminal(): string | null {
+  if (!DBUS_NAME || !DBUS_PATH) return null
+
+  // 策略 1: busctl（无 stderr 输出，避免未知方法报错）
+  try {
+    const out = execSync(
+      `busctl --user call ${DBUS_NAME} ${DBUS_PATH} ${DBUS_NAME} get_focused_terminal 2>/dev/null`,
+      { encoding: "utf-8", timeout: 3000 },
+    ).trim()
+    const m = out.match(/s\s+"([^"]+)"/)
+    if (m) return m[1]
+  } catch {
+    // 静默忽略
+  }
+
+  // 策略 2: gdbus（备选）
+  try {
+    const out = execSync(
+      `gdbus call --session --dest ${DBUS_NAME} --object-path ${DBUS_PATH} --method ${DBUS_NAME}.get_focused_terminal 2>/dev/null`,
+      { encoding: "utf-8", timeout: 3000 },
+    ).trim()
+    const m = out.match(/\('([^']+)'/)
+    if (m) return m[1]
+  } catch {
+    // 静默忽略
+  }
 
-/** 策略 4: xdotool 窗口类检测 */
-function callXdotool(): boolean | null {
-  const cls = execSync(
-    `xdotool getactivewindow getwindowclassname`,
-    { encoding: "utf-8", timeout: 3000 },
-  ).trim()
-  return cls === "Terminator" ? true : null
+  return null
 }