AI CLI任务完成通知工具：告别等待，实现异步人机协作-编程实验室

1. 项目概述：AI CLI 任务完成通知工具

如果你和我一样，经常在终端里使用 Claude Code、Codex、OpenCode 或 Gemini 这类 AI 命令行工具来处理一些耗时任务，比如让 AI 帮你重构一大段代码、分析一个复杂的日志文件，或者生成一份详细的文档，那你肯定遇到过这个场景：你输入一个复杂的指令，然后……就开始了漫长的等待。你不敢离开电脑，生怕错过 AI 完成的那一刻，但又不想干盯着屏幕浪费时间。这种“人机等待”的状态，极大地打断了工作流。

AI CLI Complete Notify就是为了解决这个痛点而生的。它是一个智能的任务完成通知工具，核心功能就是自动监控你指定的 AI CLI 工具，当它们完成一个耗时任务时，通过多种渠道（如桌面弹窗、Webhook 推送到飞书/钉钉/企业微信、Telegram 机器人、邮件等）及时通知你。这样一来，你大可以放心地去泡杯咖啡、处理另一项工作，或者只是简单地离开座位活动一下，而不用担心错过 AI 的“完工报告”。

这个工具最吸引我的地方在于它的“智能”和“灵活”。它不仅仅是简单地定时轮询日志文件。首先，它支持智能防抖：能根据任务是否调用了工具（比如文件读写、代码执行）来动态调整等待时间（有工具调用时默认等待 60 秒，无工具调用时仅 15 秒），有效避免了 AI 在思考过程中因短暂停顿而误触发通知。其次，它提供了多种集成模式：对于原生支持 Hook 或插件的工具（如 Claude Code、Gemini CLI、OpenCode），它可以直接监听其生命周期事件，实现近乎实时的精准通知；对于不支持 Hook 的工具（如 Codex），则通过稳健的日志监控模式作为后备方案。最后，它的配置极其灵活：你可以为 Claude、Codex、OpenCode、Gemini 分别独立设置是否启用通知、触发通知的任务时长阈值，以及选择各自偏好的通知渠道。

从技术栈来看，项目经历了从 Electron 到 Tauri 的架构迁移。当前版本（v2.x）基于 Tauri 2 构建，这使得最终的桌面应用安装包体积大幅缩减（便携版压缩包约 20 MB），运行时资源占用也更低，同时保持了完整的 Node.js CLI 功能作为“副驾驶”进程。前端采用 React 18 + TypeScript + Tailwind CSS，提供了一个清晰、现代化的双语配置界面。无论是追求极致轻量化的 CLI 用户，还是偏好图形化配置的桌面用户，都能找到适合自己的使用方式。

2. 核心功能与设计思路拆解

2.1 多源监控与差异化策略

工具的核心是“监控”，但不同的 AI CLI 工具在架构、日志输出和事件机制上差异很大。AI CLI Complete Notify没有采用一刀切的方案，而是为每个工具设计了最适配的监控策略，这体现了其设计上的深思熟虑。

对于 Claude Code 和 Gemini CLI，它们提供了原生的 Hook 机制。Claude Code 有Stop事件，Gemini CLI 有AfterAgent事件。这些事件是 AI 模型自身在完成一个完整的“回合”（Turn）后主动发出的信号，准确性极高。工具通过hooks install命令，将一个小小的监听脚本注入到这些 CLI 工具的配置目录中。当事件触发时，脚本会立即调用本工具的提醒逻辑。这种方式的优势非常明显：零延迟、高精度、低开销。它不需要持续轮询日志文件，几乎在 AI 停下的瞬间就能知晓，并且完全避免了因日志输出格式变化或内容干扰导致的误判。

对于 OpenCode，它支持全局插件系统。工具通过安装一个全局插件，监听session.idle（会话空闲）和session.error（会话错误）事件。其原理与 Hook 类似，也是基于事件回调，属于“一等公民”式的集成。

对于 Codex（以及其他暂无原生事件支持的 CLI），工具采用了Watch（监控）模式作为通用后备方案。这个模式会持续监视特定目录下的日志文件（例如~/.codex/logs/）。它通过一个巧妙的逻辑来判断任务是否完成：持续读取日志，如果发现日志文件在超过一段“静默时间”（Debounce Time）内没有新的内容追加，就认为当前任务已经完成，随即触发通知。这个“静默时间”就是前面提到的智能防抖时间，会根据任务类型动态调整。

设计考量：为什么 Codex 不用 Hook？这通常是因为该 CLI 工具本身未暴露相应的事件接口。Watch 模式虽然有一定延迟（需要等待静默期结束），并且依赖日志文件的稳定输出，但它具有最强的普适性。只要 AI 工具会把对话记录写到本地文件，理论上就能被监控。这种“Hook 优先，Watch 兜底”的分层设计，在追求最佳体验的同时，也保证了最大的兼容性。

2.2 通知渠道的聚合与路由

通知功能是工具价值的最终体现。它支持一个相当丰富的通知矩阵，并且设计上考虑到了可靠性和用户体验。

渠道类型：

桌面通知：在 Windows 上利用系统 Toast 通知，在 macOS 上利用原生通知中心。这是最直接、最快速的感知方式。
Webhook：支持飞书、钉钉、企业微信的群机器人。这是团队协作场景下的利器，可以把通知推送到项目群，让相关成员都知晓进度。
Telegram Bot：适合个人开发者或远程团队，通过私密的 Telegram 频道或群组接收通知。
邮件（SMTP）：作为一种异步、可归档的备份通知方式，适合需要留痕的场景。
声音/TTS 提醒：提供听觉反馈，在你可能暂时离开屏幕时尤其有用。
智能手环/手表提醒：这并不是一个独立的通道，而是通过上述手机通知（如 Telegram、邮件客户端推送）间接同步到手环设备上。

路由逻辑：工具允许你为每个 AI 来源（Claude, Codex, OpenCode, Gemini）独立配置启用哪些通知渠道。例如，你可以设置 Codex 的任务只发桌面通知和声音，而 Claude 的重要任务则额外推送飞书群。在桌面应用的“通道配置”和“各 CLI 来源”设置面板中，可以精细化管理这些开关。

可靠性设计：

并行发送：从 v2.1.0 开始，各通知渠道的发送改为并行执行，桌面弹窗不再等待网络请求返回，实现了更快的本地响应。
格式自适应：Webhook 发送时会自动检测目标平台（飞书/钉钉/企微），并组装对应的 JSON 载荷格式，确保消息能正确显示。
失败静默：单个通道发送失败（如网络问题）不会影响其他通道，也不会导致主进程崩溃，保证了核心监控功能的稳定运行。

2.3 配置管理与安全性

工具的配置系统分为两层，兼顾了灵活性与安全性，这也是很多专业工具的做法。

运行时配置 (settings.json)：此文件由桌面应用自动管理，存储于用户的应用数据目录（Windows 在%APPDATA%，macOS/Linux 在~/.ai-cli-complete-notify/）。它主要保存非敏感的操作偏好，例如：
- 各个 AI 来源的启用状态和任务时长阈值。
- 每个来源下各个通知渠道的开关状态。
- 监控的轮询间隔、防抖时间等运行时参数。
- 界面语言、窗口行为等应用设置。这些设置通过图形界面调整后即时生效并保存。
环境变量配置 (.env文件)：此文件需要用户从.env.example复制并手动填写，通常位于项目根目录或用户指定的路径。它专门用于存储敏感的凭证信息，例如：
- Webhook 的完整 URL（内含 Token）。
- Telegram Bot 的 Token 和 Chat ID。
- 邮件 SMTP 服务器的地址、端口、账号、密码。
- AI 摘要功能所需的 API Key 和 URL。这种分离的好处是显而易见的：你可以放心地将settings.json备份或同步，而无需担心泄露密钥；同时，.env文件可以被.gitignore排除，避免意外提交到版本库。

一个重要细节：在 v2.3.0 之前，.env中的某些默认开关（如SOUND_ENABLED=true）会强制覆盖settings.json中的保存值，这有时会造成混淆。新版本修正了这一点，settings.json中明确保存的渠道开关拥有最高优先级，.env中的默认值仅在settings.json没有相应记录时才起作用。这使得配置行为更加符合直觉。

3. 实战部署与核心配置详解

3.1 桌面应用快速上手（Windows 便携版）

对于大多数 Windows 用户，使用便携版是最快捷的方式。你不需要安装 Node.js 或任何依赖。

下载与解压：前往项目的 Releases 页面，找到最新版本的ai-cli-complete-notify-<version>-portable-win-x64.zip文件并下载。将其解压到任意你喜欢的目录，例如D:\Tools\AI-Notifier\。整个工具的所有文件都在这个目录下，可以随意移动。
初始配置：在解压后的目录中，你会看到一个.env.example文件。将其复制一份，并重命名为.env。用文本编辑器（如 VSCode、Notepad++）打开这个.env文件。你需要根据注释，填写你希望启用的通知渠道的配置。
```
# 示例：配置飞书群机器人Webhook WEBHOOK_URLS=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # 启用飞书卡片格式（更美观） WEBHOOK_USE_FEISHU_CARD=true # 示例：配置Telegram Bot TELEGRAM_BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ TELEGRAM_CHAT_ID=-1001234567890 # 示例：启用声音和桌面通知（作为默认值） NOTIFICATION_ENABLED=true SOUND_ENABLED=true
```
注意：TELEGRAM_CHAT_ID可以是个人ID（正数）或群组/频道ID（负数）。如何获取 Bot Token 和 Chat ID 属于 Telegram Bot 创建流程，此处不赘述。
运行与配置：双击运行目录中的ai-cli-complete-notify.exe。首次运行可能会弹出 Windows Defender 防火墙提示，允许即可。应用启动后，你会看到配置界面。
- 顶部工具栏：可以切换中英文，控制“监控”总开关，以及最小化、关闭窗口。
- 通道配置：在这里可以测试并全局开关各类通知渠道。建议先点“测试”按钮，确保每个渠道都能正常工作。
- 各 CLI 来源：这是核心设置区。为你常用的 AI 工具（如 Codex）启用通知，并设置一个合理的“任务时长阈值”。例如，设置为 30 秒，意味着只有运行超过 30 秒的任务才会触发通知，避免那些秒级完成的简单命令打扰你。
- 监控配置：设置日志轮询间隔和防抖时间。通常保持默认即可。
- AI 摘要：如果你希望通知内容不是冗长的原始任务描述，而是 AI 总结的一句话概要，可以在这里配置 OpenAI、Claude、DeepSeek 等模型的 API。这是一个锦上添花的功能。
后台运行与托盘：配置完成后，可以点击窗口的“隐藏到托盘”按钮。应用会最小化到系统托盘区（可能在任务栏的“^”隐藏图标区域）。此时监控服务已在后台运行。你可以放心地打开你的 AI CLI 工具开始工作。

3.2 CLI 模式与 WSL 集成指南

对于 Linux、macOS 用户，或者需要在 Windows Subsystem for Linux (WSL) 环境下使用的开发者，需要通过源码以 CLI 模式运行。

环境准备：

# 克隆仓库 git clone https://github.com/ZekerTop/ai-cli-complete-notify.git cd ai-cli-complete-notify # 安装依赖 (确保已安装 Node.js >= 18) npm install # 复制并配置环境变量文件 cp .env.example .env # 使用 vim 或 nano 编辑 .env，填入你的配置 nano .env

启动监控服务（Watch 模式）：这是最常用的模式，让工具在后台持续监控日志。
```
# 监控所有支持的来源（Claude, Codex, Gemini），并为不同工具设置防抖时间 node ai-reminder.js watch --sources all --gemini-quiet-ms 3000 --claude-quiet-ms 60000
```
- --sources all：监控所有已配置的 AI 工具。
- --gemini-quiet-ms 3000：Gemini 的日志静默 3 秒即视为任务完成。
- --claude-quiet-ms 60000：Claude 的日志静默 60 秒（因常涉及工具调用）才视为完成。这个命令会持续运行，占用一个终端。你可以使用Ctrl+C停止它。

在 WSL 中持久化运行：在 WSL 中，你希望这个监控服务能一直运行，即使关闭终端窗口。方案一：使用nohup(简单)

nohup node ai-reminder.js watch --sources all > ~/ai-notify.log 2>&1 & # 查看日志 tail -f ~/ai-notify.log

方案二：使用tmux或screen(更稳定，推荐)

# 安装 tmux sudo apt install tmux -y # 新建一个名为 ai-notify 的会话并在其中启动监控 tmux new -s ai-notify # 在 tmux 会话中运行命令 node ai-reminder.js watch --sources all # 按下 Ctrl+B，然后按 D，脱离当前会话。监控服务会在后台继续运行。 # 以后想重新连接查看，执行： tmux attach -t ai-notify

为 AI 工具安装 Hook（强烈推荐）：如果你主要使用 Claude Code 或 Gemini CLI，安装 Hook 能获得最佳体验。

# 检查当前 Hook 状态 node ai-reminder.js hooks status # 为 Claude Code 安装 Hook node ai-reminder.js hooks install --target claude # 为 Gemini CLI 安装 Hook node ai-reminder.js hooks install --target gemini # 为 OpenCode 安装全局插件 node ai-reminder.js hooks install --target opencode

安装成功后，当你使用对应的 AI CLI 时，工具就能通过事件机制近乎实时地感知任务完成，无需依赖日志监控。

3.3 关键配置项解析与建议

任务时长阈值：位于每个 AI 来源的设置中。这个值（单位：秒）决定了任务运行多久以上才发送通知。设置这个值非常重要，可以过滤掉大量简单的、交互式的命令。例如，你问 AI “当前时间”，它可能瞬间回复，这种就不需要通知。建议根据你的使用习惯设置，比如 30 秒或 60 秒。对于复杂的代码生成或分析任务，这个阈值能确保只在你真正需要离开时提醒你。
智能防抖时间：在“监控配置”中。这是 Watch 模式下的核心参数，定义了“多久没有新日志才算任务完成”。工具已经内置了智能调整：如果 AI 的消息中检测到工具调用（tool_use），则使用较长的防抖时间（默认 60000 毫秒），因为工具调用可能涉及外部 I/O，耗时较长且不稳定；如果没有工具调用，则使用较短的防抖时间（默认 15000 毫秒）。一般用户无需修改，除非你观察到频繁的误报或漏报。
确认提示开关：这是一个针对 Codex 的高级功能（默认关闭）。当 Codex 运行在“计划模式”并需要用户做出选择（如“请确认执行方案 A 还是 B？”）时，它会暂停并输出一个交互式提示。启用此开关后，工具会识别这种“确认提示”并发送一次通知，提醒你回来做决策。注意：一旦发送了确认提示通知，该回合就不会再发送任务完成通知。这个功能适合那些深度使用 Codex 进行复杂、多步骤规划的用户。对于只想在最终完成时得到通知的用户，保持关闭即可。
AI 摘要配置：在“AI 摘要”标签页。如果你觉得原始的任务描述（通常是用户输入的整个问题）太长，可以启用此功能。工具会将任务描述发送给你配置的 AI 模型（如 GPT-4o-mini），请求生成一个简短的总结。例如，将“请分析项目根目录下所有 .js 文件的代码结构，找出潜在的性能瓶颈，并给出重构建议”总结为“分析JS项目性能瓶颈与重构建议”。需要设置 API Key 和模型。还有一个超时时间（默认 15000 毫秒），如果摘要生成超时，则会回退到使用原始任务描述，确保通知的可靠性。

4. 高级用法、问题排查与优化心得

4.1 混合使用 Hook 与 Watch 模式

在实际使用中，你可能会同时使用多个 AI 工具。最佳实践是为每个工具启用其最优的监控方式。

Claude Code / Gemini CLI / OpenCode：优先使用hooks install安装事件钩子/插件。然后在桌面应用的“Hook 集成”面板，或通过 CLI 的--mode hooks参数，为这些来源启用 Hook 模式。这样，它们的通知将由事件直接驱动，几乎无延迟。
Codex：继续使用 Watch 模式。在桌面应用中，确保“监控”总开关是打开的，并且 Codex 来源的“启用”是勾选的。
桌面应用的角色：桌面应用本身是一个统一的配置中心和控制面板。无论底层是 Hook 事件触发还是 Watch 轮询触发，最终都会汇聚到桌面应用的核心逻辑，根据你的配置去分发通知。

你可以通过以下命令查看混合模式下的状态：

node ai-reminder.js config

这个命令会打印出当前生效的完整运行时配置，包括每个来源的启用状态、监控模式、以及各个渠道的开关情况，方便你进行调试。

4.2 常见问题与解决方案

问题一：收不到任何通知。

检查顺序：
1. 来源启用：在桌面应用“各 CLI 来源”中，确认你使用的 AI 工具（如 Codex）对应的开关是打开的。
2. 监控开关：桌面应用顶部工具栏的“监控”开关是否开启？（绿色为开启）。
3. 渠道启用：在“通道配置”和具体来源的设置里，确认你期望的通知渠道（如桌面通知、Webhook）是启用的。
4. 配置正确：检查.env文件中的 Webhook URL、Telegram Token 等是否填写正确。对于 Webhook，务必使用桌面应用内的“测试”功能验证。
5. 日志路径：Watch 模式依赖于读取正确的日志文件。运行node ai-reminder.js paths可以查看工具认为的日志路径。确保你的 AI CLI 确实将日志写入这些位置。有时 AI CLI 的版本更新会改变日志格式或路径。
6. 任务时长阈值：确认任务实际运行时间超过了设置的阈值。可以用node ai-reminder.js run --source codex -- codex "一个复杂任务，预计耗时2分钟"来测试一个长任务。

问题二：通知有延迟，或者 AI 还在输出时就收到通知了。

原因与调整：这通常是 Watch 模式下的防抖时间设置与实际情况不匹配。
- 延迟过长：如果 AI 明明已停止输出很久才通知，可以尝试适当减少--claude-quiet-ms或--gemini-quiet-ms的值（在监控配置中调整）。
- 提前通知：如果 AI 还在“思考”（输出...或换行）时就误报完成，说明静默时间太短。应增加防抖时间。更根本的解决方案是切换到 Hook 模式，如果该 AI 工具支持的话。Hook 模式基于明确的事件，没有延迟和误判问题。

问题三：安装 Hook 失败或无效。

排查步骤：
1. 运行node ai-reminder.js hooks status查看状态。它会显示 Hook 文件预期的路径和当前是否存在。
2. 确保你对目标 AI CLI 的配置目录有写入权限。
3. 某些 AI CLI 可能需要重启后才能加载新的 Hook。关闭并重新打开你的 Claude Code 或 Gemini CLI 终端。
4. 检查 AI CLI 的版本是否过旧，可能不支持 Hook 功能。

问题四：在 WSL 中运行时，桌面通知不工作。

这是预期行为：桌面通知是 Windows 系统的功能。当工具运行在 WSL 的 Linux 环境中时，无法直接调用 Windows 的 Toast 通知 API。
解决方案：
1. 使用其他跨平台的通道，如Webhook或Telegram，它们不受系统限制。
2. 如果你希望在 WSL 中触发 Windows 桌面通知，一个变通方法是：在 Windows 主机上也运行一个该工具的实例（便携版），并配置好。然后，在 WSL 中通过调用 localhost 的某个接口（需要工具额外开发）或者利用 WSL 的powershell.exe执行一段脚本来“转发”通知。不过目前该工具未内置此功能。更简单的做法是依赖 Webhook 推送，然后在 Windows 上通过飞书/钉钉的桌面客户端接收通知。

4.3 性能优化与使用技巧

资源占用：Tauri 版本的应用本身非常轻量。主要的资源消耗来自于 Node.js 的 Watch 进程（如果启用）。在监控多个日志文件且轮询间隔很短时，可能会有一定的 CPU 和磁盘 I/O。如果感到电脑风扇狂转，可以尝试：
- 在“监控配置”中调大轮询间隔，例如从 1000 毫秒改为 3000 毫秒。
- 只启用你真正使用的 AI 来源，减少同时监控的文件数量。
- 优先使用Hook 模式，它不需要持续轮询，资源占用极低。
通知风暴抑制：Claude Code 有时会将一个复杂问题拆分成多个子任务（Sub-turn）依次执行。早期的版本可能会对每个子任务都发送通知。现在工具已经实现了全回合检测，它会等待一个完整的“对话回合”结束（即用户一次提问，AI 完全回答完毕），才发送一次通知。如果你仍然遇到频繁通知，请检查是否在短时间内手动执行了多个独立的 AI 命令。
利用 AI 摘要提升可读性：当你在处理大量相似任务时，通知栏里冗长的原始问题可能难以快速区分。启用 AI 摘要功能后，通知标题会变成简洁的总结，让你一眼就知道是哪个任务完成了。虽然这会增加一点延迟（等待 AI 总结）和 API 成本，但对于提升信息处理效率很有帮助。
便携版的维护：Windows 便携版是一个完整的绿色软件。更新时，只需下载新版本的 zip 包，解压到新目录，然后将旧目录中的.env配置文件复制过去即可。所有的个人设置都保存在%APPDATA%\ai-cli-complete-notify\目录下，与便携版本体分离，因此更新不会丢失配置。

这个工具将我从中断式等待中解放了出来，让我能更专注地进行上下文切换，真正实现了与 AI 协作的“异步化”。从最初的简单日志监控，到如今支持多源、多通道、智能防抖和事件钩子的成熟工具，它的演进也反映了 AI 开发者工作流不断精细化的趋势。如果你也受困于等待 AI 完成任务的焦虑，不妨花二十分钟配置一下它，或许你会发现自己多出了不少“咖啡时间”。