@freely01/opencode-notify 0.1.1 → 0.3.0

package/config.ts

@@ -49,6 +49,14 @@ export interface ChannelsConfig {
   custom_webhook?: CustomWebhookChannelConfig
 }
 
+/** 日志配置 */
+export interface LogConfig {
+  /** 日志等级：error | warn | info | debug，默认 info */
+  level?: string
+  /** 日志文件路径，默认 ~/.opencode-notify/plugin.log */
+  file?: string
+}
+
 /** 插件配置 */
 export interface PluginConfig {
   channels?: ChannelsConfig
@@ -64,35 +72,287 @@ export interface PluginConfig {
   /** 去重时间窗口（秒），默认 60 */
   dedupe_seconds?: number
   /**
-   * 当用户活跃（正在操作 TUI）时抑制通知
-   * 检测的事件：message.updated / permission.replied / question.replied / command.executed / tui.command.execute
+   * 会话感知抑制开关
+   * true  → 会话活跃时按 suppress_events_when_active 列表过滤通知
+   * false → 不抑制（旧行为，所有事件都通知）
    * @default true
    */
   suppress_when_active?: boolean
-  /** 用户活跃超时时间（毫秒），超过此时间无操作视为离开 */
+  /**
+   * 会话操作超时（毫秒）
+   * 超过此时间无操作 → 视为不活跃，不再抑制通知
+   * @default 15000
+   */
   activity_timeout_ms?: number
-  /** 写入 ~/.opencode-notify/plugin.log 调试日志，默认 false */
-  debug_log?: boolean
+  /**
+   * 活跃时抑制哪些事件
+   * 空数组表示不抑制任何事件（仅跟踪会话，不影响通知）
+   * @default ["permission_required", "input_required"]
+   */
+  suppress_events_when_active?: string[]
+  /**
+   * 超时会话自动淘汰（毫秒）
+   * 会话超过此时间无任何活动 → 从追踪 Map 移除（防内存泄漏）
+   * @default 600000 (10 分钟)
+   */
+  session_stale_timeout_ms?: number
+  /**
+   * 远程延迟推送渠道列表
+   *
+   * 这些渠道在正常通知发出后，还会额外进行一次延迟推送。
+   * 正常通知不受影响（该发就发），延迟推送是额外补偿。
+   *
+   * 适用场景：用户不在电脑前时，正常通知可能没看到，
+   * 延迟推送在用户仍未操作时再次通知。
+   *
+   * 用户回到 opencode TUI 操作 → 取消该会话所有待发延迟通知。
+   *
+   * @default [] （不启用延迟推送）
+   */
+  remote_delay_channels?: string[]
+  /**
+   * 远程延迟秒数
+   * 正常通知发出后等待此秒数，用户仍无操作则再次通知
+   * @default 60
+   */
+  remote_delay_seconds?: number
+  /**
+   * 远程延迟最多重复次数
+   * @default 3
+   */
+  remote_delay_max_count?: number
+  /**
+   * 日志配置
+   *
+   * level: error | warn | info | debug
+   *   - error → 仅记录错误
+   *   - warn  → 错误 + 警告
+   *   - info  → 错误 + 警告 + 常规信息（默认）
+   *   - debug → 全部日志（相当于旧版的 debug_log: true）
+   *
+   * file: 日志文件路径，默认 ~/.opencode-notify/plugin.log
+   */
+  log?: LogConfig
 }
 
-import { readFileSync, existsSync } from "node:fs"
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { join, dirname } from "node:path"
 import yaml from "js-yaml"
 
+/** 默认配置文件路径 */
+export function defaultConfigPath(): string {
+  return join(homedir(), ".config", "opencode", "opencode-notify.yaml")
+}
+
+/** 默认配置模板内容（仅启用系统通知） */
+const DEFAULT_CONFIG_TEMPLATE = `# =============================================================================
+# opencode-notify 配置文件
+# =============================================================================
+# 文件位置: ~/.config/opencode/opencode-notify.yaml
+#
+# 配置优先级: YAML 文件 > plugin options (opencode.json tuple) > 默认值
+#
+# 首次运行自动生成，仅启用了系统通知渠道，开箱即用。
+# 其他渠道按需取消注释即可启用。
+# =============================================================================
+
+
+# =============================================================================
+# 通知渠道
+# =============================================================================
+channels:
+
+  # ---------------------------------------------------------------------------
+  # 系统消息通知 (macOS / Linux / Windows)
+  # ---------------------------------------------------------------------------
+  # 弹出 OS 原生通知横幅，开箱即用，无需额外配置。
+  #   macOS  - 使用 osascript (display notification)
+  #   Linux  - 使用 notify-send (需 libnotify 包，桌面版通常预装)
+  #   Windows - 使用 PowerShell New-BurntToastNotification
+  #             (需额外安装 BurntToast 模块)
+  # ---------------------------------------------------------------------------
+  system_message:
+    enabled: true                    # true=启用, false=禁用
+
+  # ---------------------------------------------------------------------------
+  # 屏幕跑马灯 (Linux X11 专用)
+  # ---------------------------------------------------------------------------
+  # 屏幕四边彩色高亮闪烁，作为系统通知之外的视觉辅助。
+  # 使用 Python + PyGObject(GTK 3)，Ubuntu GNOME 桌面内置。
+  # 支持独立配置事件过滤和持续时间/速度/不透明度。
+  # 取消下方注释启用：
+  # ---------------------------------------------------------------------------
+  # screen_flash:
+  #   enabled: true
+  #   duration: 3.5                  # 持续秒数
+  #   speed: 5.0                     # 移动速度因子
+  #   intensity: 0.85                # 不透明度 0.0~1.0
+
+  # ---------------------------------------------------------------------------
+  # 企业微信 群机器人 Webhook
+  # ---------------------------------------------------------------------------
+  # 发送 Markdown 消息到企业微信群聊。
+  # 使用前提：在企业微信群中添加群机器人，获取 Webhook URL。
+  # 文档: https://developer.work.weixin.qq.com/document/path/99110
+  # 取消下方注释并填入 webhook_url 启用：
+  # ---------------------------------------------------------------------------
+  # wechat_work:
+  #   enabled: true
+  #   webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
+
+  # ---------------------------------------------------------------------------
+  # 飞书 自定义机器人 / 流程触发器 Webhook
+  # ---------------------------------------------------------------------------
+  # 发送卡片消息到飞书群聊。
+  # 使用前提：在飞书群中添加自定义机器人，获取 Webhook URL。
+  # 文档: https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
+  # 取消下方注释并填入 webhook_url 启用：
+  # ---------------------------------------------------------------------------
+  # feishu:
+  #   enabled: true
+  #   webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
+
+  # ---------------------------------------------------------------------------
+  # 自定义 Webhook (通用 HTTP POST)
+  # ---------------------------------------------------------------------------
+  # 发送 HTTP 请求到任意 Webhook 服务。
+  # 支持模板插值自动填充消息内容。
+  # 适用服务: Gotify, Bark, PushDeer, Slack Webhook, Discord Webhook 等
+  #
+  # Gotify 配置示例:
+  #   url: "https://gotify.example.com/message"
+  #   method: "POST"
+  #   headers:
+  #     X-Gotify-Key: "your-app-token"
+  #   template: '{"title":"{{title}}","message":"{{body}}","priority":5}'
+  #
+  # 模板占位符: {{title}} {{body}} {{event}} {{agent}} {{sessionID}}
+  # 取消下方注释并配置 url 启用：
+  # ---------------------------------------------------------------------------
+  # custom_webhook:
+  #   enabled: true
+  #   url: ""
+  #   method: "POST"                  # 请求方法: "POST" | "GET"
+  #   headers: {}                     # 自定义请求头
+  #   template: ""                    # 消息模板（JSON 字符串）
+
+
+# =============================================================================
+# 通知事件订阅
+# =============================================================================
+# 只订阅你关心的事件类型，减少不必要通知。
+#
+# 可选事件（各渠道也可单独配置 events 覆盖此全局列表）:
+#   permission_required  - Agent 需要用户授权（如执行命令、读写文件）
+#                          触发: permission.asked / question.asked
+#   input_required       - Agent 等待用户输入
+#                          触发: session.idle / session.status(idle)
+#   run_completed        - 任务执行完成（技术预留，暂未实现）
+#   run_failed           - 任务执行失败
+#                          触发: session.error
+# ---------------------------------------------------------------------------
+events:
+  - permission_required               # 权限请求通知（推荐开启）
+  - input_required                    # 等待输入通知（推荐开启）
+  - run_failed                        # 任务失败通知
+
+
+# =============================================================================
+# 去重设置
+# =============================================================================
+# 同一事件在时间窗口内只发送一次，避免重复骚扰。
+# 去重 key: agent:event:sessionID
+# 例如 60 秒内同一个会话的权限请求不会重复弹通知。
+# ---------------------------------------------------------------------------
+dedupe_seconds: 60                   # 去重时间窗口（秒），0 或负数=不限制
+
+
+# =============================================================================
+# 会话感知抑制
+# =============================================================================
+# 当用户在 opencode TUI 中操作（输入消息、回应权限等），
+# 部分通知可能冗余（屏上已可见）。插件追踪每个会话的操作时间戳，
+# 只对活跃会话按事件类型选择性过滤。
+#
+# 检测的用户活跃事件:
+#   message.updated      - 用户发送了消息
+#   permission.replied   - 用户回应了授权
+#   question.replied     - 用户回答了问题
+#   command.executed     - 用户执行了命令
+#   tui.command.execute  - 用户按键操作 TUI
+#
+# 抑制规则:
+#   permission_required / input_required: 活跃时抑制（屏上可见）
+#   run_failed / run_completed: 始终通知（异步结果，人可能走开）
+# ---------------------------------------------------------------------------
+suppress_when_active: true           # true=开启会话感知抑制, false=不抑制
+activity_timeout_ms: 15000           # 会话操作超时（毫秒）
+                                     # 超过此时间该会话无操作 → 视为不活跃
+                                     # 推荐值: 10000~30000
+suppress_events_when_active:         # 活跃时抑制哪些事件（不填继承默认）
+  - permission_required
+  - input_required
+  # run_failed / run_completed 不在列表中 → 始终通知
+session_stale_timeout_ms: 600000     # 超时会话自动淘汰（毫秒）
+                                     # 10 分钟无任何活动的会话从追踪 Map 移除
+                                     # 防止长期运行导致内存泄漏
+
+
+# =============================================================================
+# 远程延迟推送
+# =============================================================================
+# 正常通知发出后，如果用户长时间未操作，针对指定渠道额外再推送一次。
+# 用户回到 opencode TUI 操作 → 自动取消所有待发延迟通知。
+#
+# 适用场景：用户离开电脑后，系统通知可能一闪而过没看到，
+# 延迟推送在用户仍未回来时再次尝试发出。
+#
+# remote_delay_seconds 和 remote_delay_max_count 仅在
+# remote_delay_channels 非空时生效。
+# ---------------------------------------------------------------------------
+remote_delay_channels: []            # 启用的延迟推送渠道列表
+                                     # 可选: system_message, screen_flash,
+                                     #       wechat_work, feishu, custom_webhook
+                                     # 空 = 不启用延迟推送
+# remote_delay_seconds: 60           # 延迟秒数（默认 60）
+# remote_delay_max_count: 3          # 最多重复次数（默认 3）
+
+
+# =============================================================================
+# 日志配置
+# =============================================================================
+# 所有通知失败、警告、运行信息均写入日志文件。
+# 日志等级控制输出详细程度，日常使用 info 即可。
+# ---------------------------------------------------------------------------
+log:
+  level: info                        # 日志等级: error | warn | info | debug
+                                     #   error - 仅记录错误
+                                     #   warn  - 错误 + 警告
+                                     #   info  - 错误 + 警告 + 常规信息（推荐）
+                                     #   debug - 全部日志（排查问题时使用）
+  # file: "~/.opencode-notify/plugin.log"  # 日志文件路径（可选，默认同上）
+`
+
 /**
- * 加载 YAML 配置文件
- *
- * 文件路径优先级:
- * 1. OPENCODE_NOTIFY_CONFIG 环境变量
- * 2. ~/.config/opencode/opencode-notify.yaml
- *
- * 文件不存在时返回 null，插件使用默认配置 + plugin options
+ * 确保配置文件存在，不存在则生成默认模板
  */
+export function ensureConfigFile(): void {
+  const configPath = join(homedir(), ".config", "opencode", "opencode-notify.yaml")
+  if (existsSync(configPath)) return  // 已存在
+
+  try {
+    const configDir = dirname(configPath)
+    if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true })
+    writeFileSync(configPath, DEFAULT_CONFIG_TEMPLATE, "utf-8")
+    console.error(`[opencode-notify] 已生成默认配置文件: ${configPath}`)
+  } catch {
+    // 生成失败不影响插件加载（使用内置默认配置）
+  }
+}
+
 export function loadYamlConfig(): PluginConfig | null {
-  const configPath =
-    process.env.OPENCODE_NOTIFY_CONFIG ??
-    join(homedir(), ".config", "opencode", "opencode-notify.yaml")
+  const configPath = join(homedir(), ".config", "opencode", "opencode-notify.yaml")
 
   if (!existsSync(configPath)) return null
 
@@ -121,7 +381,7 @@ export function mergeConfig(base: PluginConfig, overrides: PluginConfig): Plugin
 }
 
 /** 默认配置 */
-const DEFAULT_CONFIG: Required<Pick<PluginConfig, "suppress_when_active" | "activity_timeout_ms" | "debug_log">> & PluginConfig = {
+const DEFAULT_CONFIG: Required<Pick<PluginConfig, "suppress_when_active" | "activity_timeout_ms" | "suppress_events_when_active" | "session_stale_timeout_ms" | "remote_delay_seconds" | "remote_delay_max_count">> & PluginConfig = {
   channels: {
     system_message: { enabled: true },
     screen_flash: { enabled: false },
@@ -137,26 +397,19 @@ const DEFAULT_CONFIG: Required<Pick<PluginConfig, "suppress_when_active" | "acti
   ],
   dedupe_seconds: 60,
   suppress_when_active: true,
-  activity_timeout_ms: 30_000,
-  debug_log: false,
+  activity_timeout_ms: 15_000,
+  suppress_events_when_active: ["permission_required", "input_required"],
+  session_stale_timeout_ms: 600_000,
+  remote_delay_channels: [],
+  remote_delay_seconds: 60,
+  remote_delay_max_count: 3,
+  log: { level: "info", file: undefined },
 }
 
 /**
- * 合并配置：options → 环境变量 → 默认值
+ * 合并配置：options → 默认值
  */
 export function resolveConfig(options: PluginConfig): PluginConfig {
-  const wechatWebhook =
-    options.channels?.wechat_work?.webhook_url ||
-    process.env.OPENCODE_NOTIFY_WECHAT_WEBHOOK
-
-  const feishuWebhook =
-    options.channels?.feishu?.webhook_url ||
-    process.env.OPENCODE_NOTIFY_FEISHU_WEBHOOK
-
-  const customWebhookUrl =
-    options.channels?.custom_webhook?.url ||
-    process.env.OPENCODE_NOTIFY_CUSTOM_WEBHOOK_URL
-
   // 全局 events，各渠道继承此值
   const globalEvents = options.events ?? DEFAULT_CONFIG.events
 
@@ -186,14 +439,14 @@ export function resolveConfig(options: PluginConfig): PluginConfig {
         enabled:
           options.channels?.wechat_work?.enabled ??
           DEFAULT_CONFIG.channels!.wechat_work!.enabled,
-        webhook_url: wechatWebhook || undefined,
+        webhook_url: options.channels?.wechat_work?.webhook_url || undefined,
         events: chEvents(options.channels?.wechat_work),
       },
       feishu: {
         enabled:
           options.channels?.feishu?.enabled ??
           DEFAULT_CONFIG.channels!.feishu!.enabled,
-        webhook_url: feishuWebhook || undefined,
+        webhook_url: options.channels?.feishu?.webhook_url || undefined,
         events: chEvents(options.channels?.feishu),
       },
       custom_webhook: {
@@ -201,7 +454,7 @@ export function resolveConfig(options: PluginConfig): PluginConfig {
           options.channels?.custom_webhook?.enabled ??
           DEFAULT_CONFIG.channels?.custom_webhook?.enabled ??
           false,
-        url: customWebhookUrl || undefined,
+        url: options.channels?.custom_webhook?.url || undefined,
         method: options.channels?.custom_webhook?.method ?? "POST",
         headers: options.channels?.custom_webhook?.headers,
         template: options.channels?.custom_webhook?.template,
@@ -212,6 +465,14 @@ export function resolveConfig(options: PluginConfig): PluginConfig {
     dedupe_seconds: options.dedupe_seconds ?? DEFAULT_CONFIG.dedupe_seconds,
     suppress_when_active: options.suppress_when_active ?? DEFAULT_CONFIG.suppress_when_active,
     activity_timeout_ms: options.activity_timeout_ms ?? DEFAULT_CONFIG.activity_timeout_ms,
-    debug_log: options.debug_log ?? DEFAULT_CONFIG.debug_log,
+    suppress_events_when_active: options.suppress_events_when_active ?? DEFAULT_CONFIG.suppress_events_when_active,
+    session_stale_timeout_ms: options.session_stale_timeout_ms ?? DEFAULT_CONFIG.session_stale_timeout_ms,
+    remote_delay_channels: options.remote_delay_channels ?? DEFAULT_CONFIG.remote_delay_channels,
+    remote_delay_seconds: options.remote_delay_seconds ?? DEFAULT_CONFIG.remote_delay_seconds,
+    remote_delay_max_count: options.remote_delay_max_count ?? DEFAULT_CONFIG.remote_delay_max_count,
+    log: {
+      level: options.log?.level ?? DEFAULT_CONFIG.log?.level ?? "info",
+      file: options.log?.file,
+    },
   }
 }

package/delayed-dispatcher.ts

@@ -0,0 +1,135 @@
+import type { Message } from "./message.js"
+import type { Sender } from "./senders/types.js"
+import { error, warn, info, debug } from "./log.js"
+
+/**
+ * 远程延迟通知调度器
+ *
+ * 职责：
+ * 1. 正常通知发出后，为指定渠道额外调度延迟推送
+ * 2. 延迟期内用户活跃 → 取消该会话所有待发延迟通知
+ * 3. 超时后发送，最多重复 remote_delay_max_count 次
+ */
+
+interface PendingEntry {
+  /** 当前已发送次数 */
+  count: number
+  /** 定时器 ID，用于取消 */
+  timeoutId: ReturnType<typeof setTimeout> | null
+}
+
+export class DelayedDispatcher {
+  /**
+   * 待发延迟通知
+   * Map<sessionID, Map<channelName, PendingEntry>>
+   */
+  private pending: Map<string, Map<string, PendingEntry>> = new Map()
+
+  constructor(
+    /** 延迟毫秒数 */
+    private delayMs: number,
+    /** 最大重复次数 */
+    private maxCount: number,
+    /** 需要延迟推送的渠道名列表 */
+    private channelNames: string[],
+    /** 渠道名 → Sender 映射（已包含事件过滤） */
+    private senders: Map<string, Sender>,
+  ) {}
+
+  /**
+   * 调度延迟通知
+   *
+   * 在正常通知发出后调用，为 remote_delay_channels 中的渠道
+   * 逐个调度延迟推送。同一会话同一渠道已有待发任务则跳过（不重复调度）。
+   */
+  schedule(msg: Message): void {
+    if (this.channelNames.length === 0) return
+
+    const sid = msg.sessionID
+    if (!this.pending.has(sid)) {
+      this.pending.set(sid, new Map())
+    }
+
+    const chMap = this.pending.get(sid)!
+    for (const ch of this.channelNames) {
+      // 该渠道已有待发延迟 → 跳过（不重复调度）
+      if (chMap.has(ch)) continue
+
+      chMap.set(ch, { count: 0, timeoutId: null })
+      this.scheduleOne(sid, ch, msg)
+      info(`远程延迟: 已调度 会话=${sid} 渠道=${ch} 延迟=${this.delayMs}ms`)
+    }
+  }
+
+  /**
+   * 取消指定会话的所有待发延迟通知
+   *
+   * 在用户活跃事件或会话删除时调用。
+   */
+  cancelForSession(sessionID: string): void {
+    const chMap = this.pending.get(sessionID)
+    if (!chMap) return
+
+    for (const [ch, entry] of chMap) {
+      if (entry.timeoutId !== null) {
+        clearTimeout(entry.timeoutId)
+      }
+    }
+    this.pending.delete(sessionID)
+    info(`远程延迟: 已取消 会话=${sessionID}`)
+  }
+
+  /**
+   * 等待指定会话的待发延迟任务数量
+   * 用于测试/诊断
+   */
+  pendingCount(sessionID: string): number {
+    return this.pending.get(sessionID)?.size ?? 0
+  }
+
+  /**
+   * 清理所有待发任务（插件卸载时调用）
+   */
+  destroy(): void {
+    for (const sessionID of this.pending.keys()) {
+      this.cancelForSession(sessionID)
+    }
+  }
+
+  /**
+   * 调度单次延迟发送
+   */
+  private scheduleOne(sid: string, ch: string, msg: Message): void {
+    const chMap = this.pending.get(sid)
+    if (!chMap) return
+    const entry = chMap.get(ch)
+    if (!entry) return
+
+    entry.timeoutId = setTimeout(() => {
+      entry.timeoutId = null
+
+      // 发送延迟通知
+      const sender = this.senders.get(ch)
+      if (sender) {
+        sender.send(msg).catch((err) => {
+          error(`远程延迟推送失败 会话=${sid} 渠道=${ch}: ${err}`)
+        })
+        info(`远程延迟: 已推送 会话=${sid} 渠道=${ch}`)
+      }
+
+      // 检查是否需要继续重试
+      entry.count++
+      if (entry.count < this.maxCount) {
+        this.scheduleOne(sid, ch, msg)
+        debug(`远程延迟: 重试 ${entry.count}/${this.maxCount} 会话=${sid} 渠道=${ch}`)
+      } else {
+        // 达到最大次数，清理
+        chMap.delete(ch)
+        if (chMap.size === 0) {
+          this.pending.delete(sid)
+        }
+        info(`远程延迟: 已完成 会话=${sid} 渠道=${ch} (推送${entry.count}次)`)
+      }
+    }, this.delayMs)
+  }
+}

package/dispatcher.ts

@@ -1,6 +1,7 @@
 import type { Message } from "./message.js"
 import type { Sender } from "./senders/types.js"
 import { FileStore } from "./store.js"
+import { error, warn, info, debug } from "./log.js"
 
 /**
  * 通知分发器
@@ -27,6 +28,7 @@ export class Dispatcher {
 
   async dispatch(msg: Message): Promise<void> {
     if (this.senders.length === 0) {
+      warn(`没有启用的通知渠道，跳过: ${msg.event} 会话=${msg.sessionID}`)
       return
     }
 
@@ -36,9 +38,12 @@ export class Dispatcher {
     // 去重检查 + 预留发送时隙
     const allowed = this.store.reserveSend(key, this.windowSec, now)
     if (!allowed) {
-      return // 去重命中，跳过
+      debug(`去重命中，跳过: ${key}`)
+      return
     }
 
+    info(`分发通知: agent=${msg.agent} event=${msg.event} 会话=${msg.sessionID} 渠道数=${this.senders.length}`)
+
     // 并发发送到所有渠道
     const results = await Promise.allSettled(
       this.senders.map((s) => s.send(msg)),
@@ -51,19 +56,19 @@ export class Dispatcher {
 
     if (allSuccess) {
       this.store.markSent(key, now)
+      debug(`通知发送成功: ${key}`)
     } else {
       // 有失败 → 释放预留
       this.store.clearReservation(key)
-      // 记录失败（但不抛异常避免影响主流程）
+      let failCount = 0
       for (let i = 0; i < results.length; i++) {
         const r = results[i]
         if (r.status === "rejected") {
-          console.error(
-            `[opencode-notify] sender ${this.senders[i].name} failed:`,
-            r.reason,
-          )
+          failCount++
+          error(`渠道 ${this.senders[i].name} 发送失败: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`)
         }
       }
+      warn(`通知部分失败: ${key} (${failCount}/${this.senders.length} 个渠道失败)`)
     }
   }
 }