@freely01/opencode-notify 0.1.0 → 0.2.0

package/README.md

@@ -24,10 +24,12 @@ opencode 通知插件 — 监听会话中的关键事件，通过多渠道推送
 - 多渠道通知：系统通知、企业微信、飞书、自定义 Webhook（Gotify / Bark / PushDeer 等）
 - YAML 配置文件，每项参数均有详细注释
 - 去重机制：同一事件在时间窗口内不重复发送
-- 活跃抑制：检测到用户在操作 TUI 时可自动跳过通知
+- 会话感知抑制：活跃会话按事件类型智能过滤，不遗漏 `run_failed` 等重要通知
 - 零外部运行时依赖（仅 js-yaml 用于配置解析）
 - **屏幕跑马灯**：通知时屏幕四边高亮闪烁（Linux X11，Python + GTK 内置）
 - **渠道级事件过滤**：每个渠道可独立配置监听哪些事件，灵活分流
+- **远程延迟推送**：正常通知发出后，指定渠道额外延迟推送以防遗漏
+- **Terminator 子屏检测**：自动检测子屏最大化场景，被遮挡的会话强制通知
 
 ## 平台支持
 
@@ -270,6 +272,41 @@ feishu:
 
 消息包含：标题头、正文（Markdown）、分割线、脚注（会话 ID）。
 
+### 远程延迟推送
+
+正常通知发出后，如果用户长时间未操作（未回到 opencode TUI），针对指定渠道额外再推送一次。
+用户在延迟期间回到 TUI 操作 → 自动取消该会话所有待发延迟通知。
+
+**适用场景：** 用户离开电脑后，系统通知可能一闪而过没看到；延迟推送在用户仍未回来时再次尝试发出。
+
+```yaml
+remote_delay_channels:          # 哪些渠道需要额外延迟推送（空=不启用）
+  - system_message
+  - wechat_work
+  - feishu
+  - custom_webhook
+remote_delay_seconds: 60        # 延迟秒数（默认 60）
+remote_delay_max_count: 3       # 最多重复次数（默认 3）
+```
+
+**注意：**
+- `remote_delay_channels` 仅影响**额外延迟推送**，不影响正常通知（正常通知该发就发）
+- 延迟推送使用渠道自身的事件过滤规则，只有渠道订阅的事件才会延迟推送
+- 用户在该会话中进行任何操作（输入消息、回应权限、执行命令等）都会取消该会话所有待发延迟
+- 达到 `remote_delay_max_count` 次后停止推送
+
+### Terminator 子屏遮挡检测（自动）
+
+当用户在 **Terminator** 中最大化某个子屏幕时（`Ctrl+Shift+X`），
+其他子屏幕中的 opencode 会话虽活跃但被遮挡。插件自动检测该场景，
+被遮挡的会话即使活跃也会强制发送通知。
+
+**检测原理**：`$TERMINATOR_UUID` + `$TERMINATOR_DBUS_NAME` + `$TERMINATOR_DBUS_PATH`
+环境变量确认在 Terminator 中 → DBus 查询焦点终端 UUID → 与本屏对比
+→ 不一致则强制通知，无需额外配置。
+
+**外部依赖**（任一即可）：`busctl`（systemd 内置）| `python3-dbus` | `gdbus` | `xdotool`
+
 ## 事件映射
 
 | 通知事件 | 触发场景 | 对应 opencode 事件 |
@@ -285,12 +322,10 @@ feishu:
 
 默认路径：`~/.config/opencode/opencode-notify.yaml`
 
-可通过环境变量 `OPENCODE_NOTIFY_CONFIG` 自定义路径。
-
 ### 配置优先级
 
 ```
-YAML 文件 > plugin options (opencode.json) > 环境变量 > 默认值
+YAML 文件 > plugin options (opencode.json) > 默认值
 ```
 
 ### 全部配置项
@@ -336,44 +371,81 @@ events:                        # 订阅的事件列表
                                  # 可选值: permission_required | input_required | run_completed | run_failed
 
 dedupe_seconds: 60             # 去重时间窗口（秒）
-suppress_when_active: false    # 用户活跃时是否跳过通知
-activity_timeout_ms: 30000     # 活跃超时判定（毫秒）
-debug_log: false               # 写入 ~/.opencode-notify/plugin.log 调试日志（默认 false）
+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 中操作（输入消息、回应权限等），通知可能冗余（屏上已可见）。
+插件通过**会话感知抑制**解决：追踪每个会话的用户操作时间戳，活跃会话按事件类型选择性过滤。
 
-| 变量 | 用途 |
-|------|------|
-| `OPENCODE_NOTIFY_CUSTOM_WEBHOOK_URL` | 覆盖 `custom_webhook.url` |
-| `OPENCODE_NOTIFY_WECHAT_WEBHOOK` | 覆盖 `wechat_work.webhook_url` |
-| `OPENCODE_NOTIFY_FEISHU_WEBHOOK` | 覆盖 `feishu.webhook_url` |
-| `OPENCODE_NOTIFY_CONFIG` | 自定义 YAML 配置文件路径 |
+**检测的用户操作事件：**
+`message.updated` / `permission.replied` / `question.replied` / `command.executed` / `tui.command.execute`
 
-### 活跃抑制
+**抑制规则：**
 
-当用户正在操作 TUI（发消息、翻页、回应权限等），说明人在屏幕前，可跳过通知。
-检测事件：`message.updated` / `permission.replied` / `question.replied` / `command.executed` / `tui.command.execute`
+| 通知事件 | 活跃时默认行为 | 理由 |
+|---------|:------------:|------|
+| `permission_required` | ✅ 抑制 | 权限弹窗就在屏幕上 |
+| `input_required` | ✅ 抑制 | TUI 明确在等输入 |
+| `run_failed` | ❌ 不抑制 | 异步结果，人可能走开 |
+| `run_completed` | ❌ 不抑制 | 同上 |
+
+**配置示例：**
 
 ```yaml
-suppress_when_active: true     # 开启抑制
-activity_timeout_ms: 30000     # 30 秒无操作视为离开
+suppress_when_active: true          # 开启会话感知抑制
+activity_timeout_ms: 15000          # 15 秒无操作视为不活跃
+suppress_events_when_active:        # 活跃时抑制哪些事件
+  - permission_required
+  - input_required
+session_stale_timeout_ms: 600000    # 10 分钟无活动自动淘汰会话（防内存泄漏）
 ```
 
 ## 日志与故障排查
 
-插件日志位于 `~/.opencode-notify/plugin.log`，默认**关闭**，需在配置中开启：
+插件日志位于 `~/.opencode-notify/plugin.log`（可通过 `log.file` 配置自定义）。
+
+日志等级由 `log.level` 控制：
+
+| 等级 | 包含内容 | 建议用途 |
+|------|---------|---------|
+| `error` | 仅错误 | 生产环境，只关心失败 |
+| `warn` | 错误 + 警告 | 生产环境，关注潜在问题 |
+| `info` | 错误 + 警告 + 常规信息 | 日常运行（默认） |
+| `debug` | 全部日志（含详细事件流） | 排查问题 |
 
 ```yaml
-debug_log: true
+log:
+  level: info                     # 推荐：日常使用记录所有关键信息
+  # level: debug                  # 排查问题时改为 debug
+  # file: "~/.opencode-notify/plugin.log"  # 可选自定义路径
 ```
 
-开启后日志包含：
+日志包含：
 
-- 插件加载信息（配置、已启用渠道）
-- 收到的事件（`[event] type=...`）
-- 匹配到的通知
-- 发送结果
+- 插件加载信息（配置、已启用渠道、日志等级）
+- 渠道发送失败 / 成功
+- 会话活跃跳过通知
+- 远程延迟推送调度 / 取消 / 推送
+- 去重命中、状态存储异常等诊断信息
 
 ```bash
 # 实时查看日志
@@ -382,8 +454,11 @@ tail -f ~/.opencode-notify/plugin.log
 # 查看最近的插件加载信息
 grep "插件已加载" ~/.opencode-notify/plugin.log
 
-# 查看事件流
-grep "\[event\]" ~/.opencode-notify/plugin.log
+# 只看错误
+grep "\[ERROR\]" ~/.opencode-notify/plugin.log
+
+# 只看警告
+grep "\[WARN\]" ~/.opencode-notify/plugin.log
 ```
 
 ### 常见问题
@@ -410,17 +485,30 @@ curl -X POST <webhook_url> -H "Content-Type: application/json" -d '{"msgtype":"m
 opencode-notify/
 ├── index.ts                 # 插件入口
 ├── cli.ts                   # 诊断工具
-├── config.ts                # 配置解析（YAML + options + env）
+├── 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               # 消息模型
+├── doc/
+│   ├── de.png                # 跑马灯效果截图
+│   └── features.md           # 功能说明（含 Terminator 友好体验说明）
 ├── scripts/
 │   └── marquee.py           # 屏幕跑马灯效果（Python+GTK）
 ├── senders/
 │   ├── types.ts             # Sender 接口
-│   ├── system.ts            # 系统通知
-│   ├── screen-flash.ts      # 屏幕跑马灯
+│   ├── system/              # 系统通知（平台分包）
+│   │   ├── index.ts         #   注册表 + 自动选择平台
+│   │   ├── darwin.ts        #   macOS (osascript)
+│   │   ├── linux.ts         #   Linux (notify-send)
+│   │   └── win32.ts         #   Windows (PowerShell)
+│   ├── screen-flash/        # 屏幕跑马灯（Linux X11）
+│   │   ├── index.ts         #   入口 + 平台守卫
+│   │   └── linux.ts         #   Linux 实现 (Python+GTK)
 │   ├── custom-webhook.ts    # 自定义 Webhook
 │   ├── wechat-work.ts       # 企业微信
 │   └── feishu.ts            # 飞书

package/cli.ts

@@ -14,7 +14,7 @@
 import { loadYamlConfig, resolveConfig, mergeConfig } from "./config.js"
 import type { PluginConfig, ChannelsConfig } from "./config.js"
 import type { Message } from "./message.js"
-import { SystemSender } from "./senders/system.js"
+import { SystemSender } from "./senders/system/index.js"
 import { CustomWebhookSender } from "./senders/custom-webhook.js"
 import { WechatWorkSender } from "./senders/wechat-work.js"
 import { FeishuSender } from "./senders/feishu.js"
@@ -25,8 +25,14 @@ import { join } from "node:path"
 // ─── 常量 ───────────────────────────────────────────────────────────────────
 
 const PKG = JSON.parse(readFileSync(join(import.meta.dirname, "package.json"), "utf-8"))
-const LOG_FILE = join(homedir(), ".opencode-notify", "plugin.log")
-const YAML_PATH = process.env.OPENCODE_NOTIFY_CONFIG ?? join(homedir(), ".config", "opencode", "opencode-notify.yaml")
+const DEFAULT_LOG_FILE = join(homedir(), ".opencode-notify", "plugin.log")
+const YAML_PATH = join(homedir(), ".config", "opencode", "opencode-notify.yaml")
+
+/** 读取有效日志文件路径（优先从配置中读取） */
+function getLogFile(): string {
+  const yamlCfg = loadYamlConfig()
+  return yamlCfg?.log?.file ?? DEFAULT_LOG_FILE
+}
 
 const SAMPLE_MSG: Message = {
   agent: "opencode",
@@ -72,7 +78,7 @@ function cmdCheck() {
   // 1. 检查配置文件是否存在
   if (!existsSync(YAML_PATH)) {
     console.log(`\n❌ 配置文件不存在: ${YAML_PATH}`)
-    console.log("   请创建配置文件，或设置 OPENCODE_NOTIFY_CONFIG 环境变量指向正确的路径")
+    console.log("   请创建 ~/.config/opencode/opencode-notify.yaml 配置文件")
     process.exit(1)
   }
   console.log(`\n✅ 配置文件: ${YAML_PATH}`)
@@ -145,6 +151,9 @@ function cmdCheck() {
   // 6. 检查活跃抑制
   console.log(`\n🔇 活跃抑制: ${cfg.suppress_when_active ? "开启" : "关闭"} (超时 ${cfg.activity_timeout_ms}ms)`)
 
+  // 6.5 日志配置
+  console.log(`\n📝 日志: 等级=${cfg.log?.level ?? "info"} 文件=${getLogFile()}`)
+
   // 7. 检查去重
   console.log(`\n🔄 去重窗口: ${cfg.dedupe_seconds} 秒`)
 
@@ -219,17 +228,18 @@ async function cmdTest(channel?: string) {
 // ─── 命令: log ───────────────────────────────────────────────────────────────
 
 function cmdLog(lines: number) {
-  if (!existsSync(LOG_FILE)) {
-    console.log(`日志文件不存在: ${LOG_FILE}`)
+  const logFile = getLogFile()
+  if (!existsSync(logFile)) {
+    console.log(`日志文件不存在: ${logFile}`)
     console.log("插件尚未运行过，或日志已被清理。")
     process.exit(1)
   }
 
-  const stat = statSync(LOG_FILE)
-  const all = readFileSync(LOG_FILE, "utf-8").trimEnd()
+  const stat = statSync(logFile)
+  const all = readFileSync(logFile, "utf-8").trimEnd()
   const entries = all.split("\n")
 
-  console.log(`📄 ${LOG_FILE} (${(stat.size / 1024).toFixed(1)} KB, ${entries.length} 行)\n`)
+  console.log(`📄 ${logFile} (${(stat.size / 1024).toFixed(1)} KB, ${entries.length} 行)\n`)
 
   const tail = entries.slice(-lines)
   for (const line of tail) {
@@ -270,16 +280,17 @@ function cmdInfo() {
   }
 
   // 日志文件
+  const logFile = getLogFile()
   console.log(`\n  📝 日志文件:`)
-  if (existsSync(LOG_FILE)) {
-    const stat = statSync(LOG_FILE)
-    const lines = readFileSync(LOG_FILE, "utf-8").split("\n").length
-    const recent = readFileSync(LOG_FILE, "utf-8").trimEnd().split("\n").slice(-1)[0] ?? ""
-    console.log(`     路径: ${LOG_FILE}`)
+  if (existsSync(logFile)) {
+    const stat = statSync(logFile)
+    const lines = readFileSync(logFile, "utf-8").split("\n").length
+    const recent = readFileSync(logFile, "utf-8").trimEnd().split("\n").slice(-1)[0] ?? ""
+    console.log(`     路径: ${logFile}`)
     console.log(`     大小: ${(stat.size / 1024).toFixed(1)} KB, ${lines} 行`)
     console.log(`     最新: ${recent}`)
   } else {
-    console.log(`     路径: ${LOG_FILE} (暂无日志)`)
+    console.log(`     路径: ${logFile} (暂无日志)`)
   }
 
   // 配置详情
@@ -308,6 +319,7 @@ function cmdInfo() {
 
     console.log(`\n  📋 订阅事件:   ${cfg.events?.join(", ") ?? "(无)"}`)
     console.log(`  🔇 活跃抑制:   ${cfg.suppress_when_active ? "开启" : "关闭"}`)
+    console.log(`  📝 日志等级:   ${cfg.log?.level ?? "info"}`)
     console.log(`  ⏱  去重窗口:   ${cfg.dedupe_seconds} 秒`)
   } else {
     console.log(`\n  ⚠️  未加载到配置`)