English | 中文

为什么需要 ai-ding？

你运行 claude 然后等……等……10 分钟后发现它 5 分钟前就完成了。更糟的是 —— 它在问你问题，你根本没注意到。

ai-ding 在 AI 需要你关注时立即提醒：

• 回复结束时 — 附带回复内容摘要
• 问你问题时 — 直接看到问题文本
• 请求权限时 — 不再错过审批对话框
• 等待你操作时 — 再也不会漏掉提示

支持的通知渠道

| 渠道 | macOS | Linux | SSH | 需要配置 | |------|:-----:|:-----:|:---:|:--------:| | 桌面弹窗 | ✅ | ✅ | ❌ | 无 | | 声音提醒 | ✅ | ✅ | ✅ | 无 | | Telegram | ✅ | ✅ | ✅ | Bot token | | Slack | ✅ | ✅ | ✅ | Webhook URL | | Bark（iOS） | ✅ | ✅ | ✅ | Device key | | Server酱（微信） | ✅ | ✅ | ✅ | SendKey | | ntfy.sh | ✅ | ✅ | ✅ | Topic URL | | 邮件 | ✅ | ✅ | ✅ | SMTP 凭据 |

声音和桌面弹窗开箱即用。在 ~/.ai-ding.yaml 中启用更多渠道。

快速开始

作为 Claude Code 插件（推荐）

/plugin marketplace add qinsz01/ai-ding
/plugin install ai-ding@qinsz01

就这样。Claude 回复结束、提问、请求权限时都会自动通知你。

作为 CLI 工具

npm install -g ai-ding
ai-ding --init    # 创建 ~/.ai-ding.yaml
ai-ding --test    # 测试所有已启用的通知渠道

作为 Codex 插件

ai-ding 现在同时支持仓库级和个人级两种 Codex 安装方式。

仓库级安装

如果你直接 clone 了这个仓库，仓库里已经包含 Codex 所需文件：

• .agents/plugins/marketplace.json：把插件暴露到当前工作区的 marketplace
• .codex/hooks.json：通过仓库里的 dist/cli.js 发送 Stop 事件通知

如果你的 ~/.codex/config.toml 还没开启 hooks，需要加上：

[features]
codex_hooks = true

然后重启 Codex。若你希望在聊天里直接使用 notify skill，再通过 /plugins 安装 ai-ding。仓库级 Stop 通知则通过 .codex/hooks.json 直接生效。

个人级安装

如果你是通过 npm 全局安装的 ai-ding，执行：

ai-ding --install-codex

这个命令会：

• 把插件源码复制到 ~/.codex/plugins/ai-ding
• 更新 ~/.agents/plugins/marketplace.json
• 写入 ~/.codex/hooks.json
• 在 ~/.codex/config.toml 中启用 features.codex_hooks = true

执行后重启 Codex。自动 Stop 通知会立刻可用；如果你还想在 Codex 聊天里使用 notify skill，再通过 /plugins 安装 ai-ding。

如需移除个人级安装：

ai-ding --uninstall-codex

使用方法

# 发送通知（自动检测环境）
ai-ding "构建完成"

# 指定标题
ai-ding --title "CI 流水线" "所有测试通过"

# 只发送到指定渠道
ai-ding --channel telegram "部署失败"

# 禁用特定渠道
ai-ding --no-desktop --no-sound "静默提醒"

# 测试所有已配置的通知渠道
ai-ding --test

# 初始化配置文件
ai-ding --init

# 安装个人级 Codex 集成
ai-ding --install-codex

# 卸载个人级 Codex 集成
ai-ding --uninstall-codex

输出反馈

每次调用都会打印各渠道的发送结果：

[ai-ding] ✓ sound: terminal bell
[ai-ding] ✓ telegram: sent to chat 1234...
[ai-ding] ✓ slack: sent to Slack webhook
[ai-ding] Done: 3 sent.

如果某个渠道发送失败，会显示具体错误：

[ai-ding] ✓ sound: terminal bell
[ai-ding] ✗ telegram: HTTP 401: Unauthorized
[ai-ding] Done: 1 sent, 1 failed.

智能通知（插件模式）

Claude Code

作为 Claude Code 插件安装后，ai-ding 会发送上下文感知的通知：

| 触发时机 | 通知内容 | |----------|---------| | Claude 回复结束 | 最后一条回复的摘要 | | API 错误发生 | "API Error: rate_limit: 429 Too Many Requests" | | Claude 提问 | 问题文本 | | 计划需要审批 | "Plan ready for your approval" | | Claude 请求权限 | "Permission needed: Bash" | | Claude 等待操作 | "Claude is waiting for your input" | | 其他通知（错误等） | 转发通知消息 |

Subagent 活动（Explore、code-reviewer 等）不会触发通知 —— 只在你需要操作时才提醒。

Codex

在 Codex 中，ai-ding 使用官方支持的 Stop hook，并在每轮结束时转发最后一条 assistant 消息。这意味着：

• 任务完成摘要会自动通知
• 如果最后一条消息是在提问，问题内容也会被通知出来
• 直接 clone 本仓库时，可用仓库内的 .codex/hooks.json
• 全局安装后，可通过 ai-ding --install-codex 完成个人级接入

Codex 目前没有像 Claude Code 那样暴露计划审批、权限请求、分类通知等额外 hook 事件，所以这些 Claude 专属的上下文通知在 Codex 中暂时无法完全等价实现。

配置

编辑 ~/.ai-ding.yaml：

channels:
  desktop:
    enabled: true
  sound:
    enabled: true
    file: null           # 可选：自定义音频文件路径
  ntfy:
    enabled: false
    url: "https://ntfy.sh/your-topic"
  telegram:
    enabled: false
    bot_token: ""
    chat_id: ""
  bark:
    enabled: false
    url: "https://api.day.app"
    device_key: ""
  serverchan:
    enabled: false
    sendkey: ""
  slack:
    enabled: false
    webhook_url: ""
  email:
    enabled: false
    smtp_host: ""
    smtp_port: 587
    from: ""
    to: ""
    user: ""
    password: ""

remote:
  fallback_order:
    - sound
    - ntfy

defaults:
  message: "Task completed"
  title: "ai-ding"

环境变量

通过 AI_DING_* 环境变量覆盖任意配置项：

| 环境变量 | 对应配置路径 | |----------|-------------| | AI_DING_TELEGRAM_BOT_TOKEN | channels.telegram.bot_token | | AI_DING_TELEGRAM_CHAT_ID | channels.telegram.chat_id | | AI_DING_SLACK_WEBHOOK_URL | channels.slack.webhook_url | | AI_DING_NTFY_URL | channels.ntfy.url | | AI_DING_BARK_URL | channels.bark.url | | AI_DING_BARK_DEVICE_KEY | channels.bark.device_key | | AI_DING_SERVERCHAN_SENDKEY | channels.serverchan.sendkey | | AI_DING_EMAIL_SMTP_HOST | channels.email.smtp_host | | AI_DING_EMAIL_SMTP_PORT | channels.email.smtp_port | | AI_DING_EMAIL_FROM | channels.email.from | | AI_DING_EMAIL_TO | channels.email.to | | AI_DING_EMAIL_USER | channels.email.user | | AI_DING_EMAIL_PASSWORD | channels.email.password |

环境变量优先级高于 YAML 配置文件。

SSH 远程环境设置

通过 SSH 连接时，桌面通知无法传到你的本地电脑。ai-ding 使用逐级降级策略：

1. 终端响铃 (\a) — 零配置，但在 tmux 下可能不生效
2. ntfy.sh — 推送通知到手机/浏览器，只需配置一个 URL（推荐）

开启 SSH 终端响铃

| 终端 | 开启方法 | |------|---------| | Windows Terminal | 打开 settings.json，在 profile 中添加 "bellStyle": "audible" | | iTerm2（macOS） | Preferences → Profiles → Terminal → 勾选 "Audible bell" | | macOS Terminal | 偏好设置 → 描述文件 → 高级 → 勾选 "声音响铃" | | VS Code Terminal | 设置中添加 "terminal.integrated.enableBell": true | | PuTTY | Configuration → Terminal → Bell → 设为 "Play default sound" | | tmux | 在 ~/.tmux.conf 中添加 set -g bell-action any |

注意： 通过 tmux + SSH 使用终端响铃不可靠。如果你使用 tmux，强烈建议配置 ntfy.sh。

配置 ntfy.sh（SSH 推荐方案）

ntfy.sh 是 SSH 下最可靠的通知方式。无需注册，服务器端不需要安装任何东西。

第一步： 选一个唯一的主题名：my-dev-notifications-a1b2c3

第二步： 在你的设备上订阅：

• 手机：安装 ntfy 应用（iOS / Android）
• 浏览器：打开 https://ntfy.sh/your-topic-name 允许通知

第三步： 配置：

channels:
  ntfy:
    enabled: true
    url: "https://ntfy.sh/my-dev-notifications-a1b2c3"

或者直接用环境变量：

export AI_DING_NTFY_URL="https://ntfy.sh/my-dev-notifications-a1b2c3"

工作原理

通知请求
  │
  ├─ 本地桌面环境？
  │    ├─ 是 → 桌面弹窗 + 声音提醒
  │    └─ 否（SSH/CI） → 降级策略：
  │         ├─ 终端响铃 (\a) — 零配置
  │         └─ ntfy.sh 推送 — 只需一个 URL
  │
  └─ 并行推送：Telegram / Bark / Slack / 邮件
               （启用即发送，不受环境影响）

渠道配置指南

1. 在 Telegram 上找到 @BotFather 创建一个 Bot
2. 从 BotFather 获取 bot_token
3. 给你的 Bot 发一条消息，然后访问：

   https://api.telegram.org/bot<TOKEN>/getUpdates

4. 在返回结果中找到你的 chat_id

telegram:
  enabled: true
  bot_token: "123456:ABC-DEF"
  chat_id: "987654321"

1. 从 App Store 安装 Bark
2. 打开 App 获取服务器 URL 和设备密钥

bark:
  enabled: true
  url: "https://api.day.app"
  device_key: "your-device-key"

1. 在 sct.ftqq.com 注册
2. 关注微信公众号，获取 SendKey

serverchan:
  enabled: true
  sendkey: "SCTxxxx"

1. 在 Slack 工作区创建一个 Incoming Webhook
2. 复制 Webhook URL

slack:
  enabled: true
  webhook_url: "https://hooks.slack.com/services/T.../B.../xxx"

支持任意 SMTP 服务（Gmail、SendGrid、Mailgun 等）。

Gmail 用户需要使用应用专用密码：

email:
  enabled: true
  smtp_host: "smtp.gmail.com"
  smtp_port: 587
  from: "[email protected]"
  to: "[email protected]"
  user: "[email protected]"
  password: "your-app-password"

常见问题

可以。终端响铃（\a）无需配置即可在 SSH 下工作。如果需要更可靠的通知，推荐配置 ntfy.sh —— 只需一个 URL 就能推送通知到手机/浏览器。

可以。npm install -g ai-ding 安装后声音和桌面通知立即生效。如需更多渠道（Telegram、Slack 等），运行 ai-ding --init 编辑配置。

可以。所有已启用的渠道并行发送。你可以同时收到桌面弹窗 + 声音 + Telegram + 邮件。

cc-notify 是一个 Tauri 桌面应用（Rust + React），较重。ai-ding 是轻量 Node.js CLI —— 秒装，不需要 GUI。ai-ding 还支持中国特色渠道（Server酱、Bark），同时兼容 Claude Code 和 Codex CLI。

参与贡献

欢迎提交 PR！Fork 本仓库，做出修改，然后发起 Pull Request。

git clone https://github.com/qinsz01/ai-ding.git
cd ai-ding
npm install
npm test

许可证

MIT