在 AI 辅助编程日益普及的今天，Claude Code 、Cursor 、Windsurf 、Trae 等 AI 工具极大地提升了我们的开发效率。但这些工具都有一个共同的问题：它们在执行完任务后不会主动通知用户，导致开发者需要手动检查任务状态 。如果在同时运行多个任务时，容易错过重要信息或无法有效安排工作优先级。
为了解决这一问题，本人写了 AI Common Notify —— 一个为所有主流 AI 编程工具提供统一通知服务的开源工具。它能在 AI 工具完成任务后主动发送系统通知，让您在多任务并行时也能井然有序地处理工作。
AI Common Notify 本质上是一个通知应用工具，因此它也可以不只应用于 ai 编辑器。
项目地址：https://github.com/MichealWayne/ai-common-notify
目前市面上虽然已有一些小的通知工具，但它们通常只针对单一 AI 工具，例如仅支持 Claude Code。这种碎片化的解决方案带来了以下问题：
工具割裂 ：每个 AI 工具需要单独的通知服务、如配 hook、配 mcp，用户需要安装和配置多个工具体验不一致 ：不同通知服务的样式、行为和配置方式差异很大维护成本高 ：当需要调整通知设置时，需要逐一修改各个工具的配置扩展性差 ：缺乏统一的扩展机制，难以集成自定义通知渠道
AI Common Notify 针对上述痛点提供了全面解决方案：
统一接口 ：一个工具支持所有主流 AI 编程工具（Claude Code、Cursor、Windsurf、Trae 等）跨平台兼容 ：支持 Windows、macOS 和 Linux高度可配置 ：支持自定义标题、消息模板、紧急程度、超时时间、声音和图标扩展性强 ：通过脚本回调机制，可轻松集成微信通知、钉钉机器人等自定义通知渠道易于部署 ：支持 npm 全局安装和独立可执行文件，一键配置智能初始化 ：自动检测项目中使用的 AI 工具并生成相应配置
在本地环境安装Nodejs （推荐 v18 及以上）后，可通过 npm 全局快速安装：
1 npm install -g ai-common-notify
安装完成后，通过以下命令验证是否安装成功：
1 2 ai-common-notify --version
如果看到版本信息或系统通知弹出，说明安装成功。
AI Common Notify 支持多种通知触发方式，适配不同 AI 工具的特点：
可通过ai-common-notify quickInit命令在项目下快速初始化配置
通过 Claude Code 的 Hook 系统集成，在任务完成时发送通知：
在 Claude Code 设置文件 (~/.claude/settings.json 或项目中的 .claude/settings.json)设置：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "hooks" : { "Stop" : [ { "matcher" : ".*" , "hooks" : [ { "type" : "command" , "command" : "ai-common-notify hook" } ] } ] } }
也可通过ai-common-notify quickInit命令在项目下快速初始化配置
通过在 IDE 中设置 MCP 为 Cursor 等工具提供通知服务：
1 2 3 4 5 6 7 8 { "mcpServers" : { "NotificationServer" : { "command" : "ai-common-notify" , "args" : ["mcp" ] } } }
使用提示 ：当使用 Cursor 或 Windsurf 等 MCP 工具时，建议在您的提示（prompt）最后明确要求发送通知，例如：”最后，任务完成时发送通知给我。“、”Finally, send me a notification when the task is finished.“ 这有助于确保 AI 工具调用通知工具。您也可以在 Cursor 的设置中将此提示添加为规则，这样就不需要每次都手动输入。
api 模式主要用于在线的平台工具进行调用，以统一通知处理。AI Common Notify 提供 RESTful API 供自定义工具调用：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 ai-common-notify api curl -X POST http://localhost:6001/api/v1/notify \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secret-token" \ -d '{ "title": "任务完成", "message": "代码重构已完成", "urgency": "normal", "timeout": 0, "sound": true }'
AI Common Notify 支持丰富的通知定制选项：
title: 通知标题message: 通知内容urgency: 紧急程度（low/normal/critical）timeout: 超时时间（秒，0 表示永久显示）（部分系统不适用 ）sound: 是否播放声音icon: 自定义图标路径（部分系统不适用 ）
通过 JSON 配置文件实现更精细的控制：
1 2 3 4 5 6 7 8 9 { "notifications" : { "default_timeout" : 0 , "default_sound" : true , "default_urgency" : "normal" , "title_template" : "{tool_name} - {project_name}" , "message_template" : "{message}" } }
脚本回调在 AI Common Notify 的配置文件中设置，通过脚本回调扩展可以实现在通知发送时执行自定义脚本，让我们可以轻松集成微信通知、钉钉机器人等自定义通知渠道：
shell:
1 2 3 4 5 6 7 8 9 10 11 12 { "scripts" : { "timeout" : 30000 , "notify" : [ { "type" : "shell" , "path" : "/path/to/your/script.sh" , "enabled" : true } ] } }
nodejs:
1 2 3 4 5 6 7 8 9 10 11 12 { "scripts" : { "timeout" : 30000 , "notify" : [ { "type" : "node" , "path" : "/path/to/your/script.js" , "enabled" : true } ] } }
脚本中可以接收丰富的环境变量（如 nodejs 可以用process.env获取）：
NOTIFY_TITLE: 通知标题NOTIFY_MESSAGE: 通知消息NOTIFY_URGENCY: 紧急程度NOTIFY_TIMEOUT: 超时时间NOTIFY_SOUND: 是否播放声音NOTIFY_PROJECT_NAME: 项目名称NOTIFY_TOOL_NAME: 工具名称NOTIFY_TIMESTAMP: 时间戳
通过脚本回调扩展我们可以额外完成很多自定义功能，如：
Node.js 脚本示例（发送到企业微信）
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 const https = require ('https' );const webhookUrl = 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' ;const message = { msgtype: 'text' , text: { content: `[${process.env.NOTIFY_TIMESTAMP} ] ${process.env.NOTIFY_TITLE} \n${process.env.NOTIFY_MESSAGE} \n项目: ${process.env.NOTIFY_PROJECT_NAME} \n工具: ${process.env.NOTIFY_TOOL_NAME} ` , }, }; const data = JSON .stringify(message);const options = { method: 'POST' , headers: { 'Content-Type' : 'application/json' , 'Content-Length' : data.length, }, }; const req = https.request(webhookUrl, options, res => { console .log(`微信通知发送状态: ${res.statusCode} ` ); }); req.on('error' , error => { console .error('微信通知发送失败:' , error); }); req.write(data); req.end();
个人开发者也可以考虑接入 PushPlus 、WxPusher 、Server 酱 这类集成好的平台来实现微信等推送。
AI Common Notify 提供了一键初始化功能，自动为项目中检测到的 AI 工具生成或更新配置文件：
1 2 3 4 5 6 7 8 9 10 cd /path/to/your/projectai-common-notify quickInit ai-common-notify quickInit --tool cursor ai-common-notify quickInit --tool claudecode ai-common-notify quickInit --tool windsurf
该功能支持的工具包括：
Cursor : 通过 MCP 协议集成Claude Code : 通过 Hook 系统集成Windsurf : 通过 MCP 协议和规则文件集成Gemini-cli : 通过 MCP 协议集成
AI Common Notify 具备完善的错误处理和日志记录功能，以便问题反馈和排查：
1 2 3 4 5 ai-common-notify errlog ai-common-notify alllog
AI Common Notify 支持多层级配置，优先级从低到高依次为：
全局配置 : ~/.config/ai-common-notify/config.json (Linux/macOS) 或 %APPDATA%\\ai-common-notify\\config.json (Windows)项目配置 : <project-root>/.ai-notify.json
全局配置示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { "server" : { "port" : 6001 , "host" : "localhost" , "token" : "generated-secret-token" }, "notifications" : { "default_timeout" : 0 , "default_sound" : true , "default_urgency" : "normal" }, "scripts" : { "timeout" : 30000 , "notify" : [ { "type" : "shell" , "path" : "/home/user/scripts/notify-log.sh" , "enabled" : true } ] }, "logging" : { "retentionHours" : 168 }, "platforms" : { "linux" : { "sound_enabled" : false } } }
项目配置示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "notifications" : { "default_urgency" : "critical" , "title_template" : "[PROJECT] {tool_name} - {project_name}" }, "scripts" : { "notify" : [ { "type" : "node" , "path" : "/path/to/project/scripts/notify.js" , "enabled" : true } ] } }
实际有些简单的场景：
当同时运行多个 AI 任务时，AI Common Notify 能帮助您：
对于需要长时间运行的 AI 任务，您可以设置完成后通知：
1 2 ai-common-notify send --title "模型训练完成" --message "模型训练已完成，准确率95.2%"
在 CI/CD 流程中集成关键错误通知：
1 2 3 4 if [ $ERROR_CODE -ne 0 ]; then ai-common-notify send --title "构建失败" --message "构建过程出现错误，请检查日志" --urgency critical fi
在自动化脚本中使用 AI Common Notify：
1 2 3 4 #!/bin/bash echo "开始部署..." ai-common-notify send --title "部署完成" --message "应用已成功部署到生产环境"
AI Common Notify 通过提供统一的通知接口，有效解决了 AI 编程工具生态中通知机制缺失的问题。它不仅支持多种主流 AI 工具，还提供了灵活的配置选项、强大的脚本扩展能力和 REST API，满足不同用户的使用需求。
