Codex CLI 任务完成提醒系统 (支持手环震动)

这是一个智能提醒系统，用于在Codex CLI完成任务时通过多种方式提醒你，支持手机通知和手环震动，让你可以专心玩手机而不用频繁检查任务状态。

🎯 功能特点

• ✅ 飞书通知推送：任务完成时自动发送飞书消息到手机
• ✅ 手环震动提醒：小米手环等智能穿戴设备会震动提醒
• ✅ 语音声音提醒：Windows 播放语音提示，其它平台触发蜂鸣声
• ✅ 双重提醒保障：声音 + 手机推送，确保不会错过
• ✅ 智能项目识别：自动识别项目名称（package.json > git仓库名 > 目录名）
• ✅ 目录白名单过滤：支持按目录白名单触发通知，规避 Codex 临时工作目录
• ✅ 精简消息格式：项目名: 任务信息，适配手环显示
• ✅ Windows系统优化：完美支持Windows 10/11
• ✅ 配置灵活：可自由开关各种提醒方式
• ✅ 安全可靠：使用官方API，安全稳定

📁 项目结构

codex-notify/
├── bin/
│   └── codex-notify.js        # CLI 入口（notify/setup/install-hook）
├── config.json                # 默认配置文件，可由向导更新
├── env-config.js              # 环境变量配置管理
├── feishu-notify.js           # 飞书通知模块
├── hook-installer.js          # Codex Stop Hook 安装工具
├── logger.js                  # 日志工具
├── notification-manager.js    # 通知管理器（统一分发各通知）
├── notify-sound.js            # Windows 声音提醒脚本（其他平台回退蜂鸣声）
├── notify-system.js           # 主通知系统
├── setup-wizard.js            # 交互式配置向导
├── telegram-notify.js         # Telegram 通知模块（可选）
├── .env.example               # 环境变量模板文件
├── README.md
├── SETUP.md
├── package.json
├── package-lock.json
└── test-project/
    └── package.json

说明：仓库默认不包含 .env 与运行时生成的日志文件（例如 task-completion-log.jsonl），这些文件会在配置或运行过程中按需创建，并已经列入 .gitignore。

🛠 安装和配置

⚡ 快速开始（推荐方式）

方式A：使用 npm CLI 一键部署（推荐）

1. 安装或直接运行 CLI

   # 全局安装（推荐）
   npm install -g codex-notify
   # 或使用 npx 临时运行
   npx codex-notify setup

2. 运行交互式配置向导，录入飞书信息

   codex-notify setup

   • 再次运行向导时，可在提示“是否需要配置飞书通知”时输入 n 跳过录入，沿用已有 webhook。
3. （可选）如需自定义消息或重新写入 Codex Stop Hook

   codex-notify install-hook --message "Codex任务已完成"

   • 运行 setup 时已自动安装一次 Hook；仅当需要修改提示语、指定自定义 settings.json 路径或覆盖旧版本配置时才需执行此命令。
4. 验证通知链路是否通畅

   codex-notify notify --message "测试任务" --cwd ./你的项目目录

5. 重启 Codex CLI 以加载最新 Hook 配置

方式B：手动配置（适合自定义场景）

1. 在飞书中创建群组，添加自定义机器人，复制 webhook 地址
2. 根据操作系统创建全局环境变量文件并写入 FEISHU_WEBHOOK_URL=你的webhook地址
   • Linux/macOS：~/.codex/codex-notify.env
   • Windows：%USERPROFILE%\.codex\codex-notify.env
3. 如需单独覆盖某个项目，可在仓库根目录创建 .env 文件，内容与全局文件一致
4. 手动配置 Codex Hook（见后文），并执行 node notify-system.js 验证
5. 重启 Codex CLI 使配置生效

方式C：直接使用源码仓库（无需安装）

1. 进入仓库根目录，直接运行本地向导

   node setup-wizard.js

   • 此命令与 codex-notify setup 功能一致，会自动写入飞书 Webhook、生成 ~/.codex/codex-notify.env、同步更新 ~/.codex/config.toml 并安装 Stop Hook。
2. 按照向导提示粘贴飞书 webhook，等待自动测试结果。
3. 向导结束后，重启或重新打开 Codex CLI 会话。
4. （可选）直接在仓库内验证

   node notify-system.js --message "测试任务"

   • 若提示手动指定任务目录，可追加 --cwd 参数。

详细操作请参考 SETUP.md

📋 配置说明

环境变量配置（推荐方式）

Linux/macOS 建议在 ~/.codex/codex-notify.env 中维护全局配置；Windows 请使用 %USERPROFILE%\.codex\codex-notify.env。仓库根目录的 .env 会覆盖全局配置。

# 飞书Webhook地址
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/你的地址

# 通知开关
NOTIFICATION_ENABLED=true    # 是否启用远程通知（false 时禁用飞书/Telegram 推送）
SOUND_ENABLED=true          # 是否启用声音提醒（Windows 语音提示，其他平台蜂鸣声）

# 目录白名单（可选）
CODEX_NOTIFY_ALLOWED_DIRS=/home/yourname/project-a,/home/yourname/project-b

提示：系统会在运行时自动将新的项目目录追加到 CODEX_NOTIFY_ALLOWED_DIRS，以过滤 Codex 的临时随机目录；如需清理或调整，可手动编辑该字段。

配置文件方式（可选）

config.json 仍然支持传统配置方式，环境变量会覆盖配置文件设置。

{
  "notification": {
    "feishu": {
      "enabled": false
    },
    "sound": {
      "enabled": false
    }
  }
}

🔧 Codex CLI Hook配置

快速安装（推荐）

codex-notify install-hook --message "Codex任务已完成"

• CLI 会自动定位 notify-system.js 实际路径，并写入 Codex CLI 的 Stop Hook
• 若已有同名命令可通过 --force 覆盖：codex-notify install-hook --force
• 如需指定 settings.json 位置，可追加 --settings /custom/path/settings.json

手动配置

如需完全手动控制，可直接编辑 Codex CLI 的 settings.json：

• Linux/macOS：~/.codex/settings.json
• Windows：%USERPROFILE%\.codex\settings.json

推荐配置（使用统一通知系统）
为避免 Windows Stop Hook 在执行命令时触发编码错乱，建议优先通过 CLI 自动安装 Hook；若需手动编辑 settings.json，请使用 --message-base64 参数并传入 UTF-8 文本对应的 Base64 字符串。下面示例中 Q29kZXjku7vliqHlt7LlrozmiJA= 即 “Codex任务已完成” 的 Base64 结果。

Linux/macOS 示例：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node /projects/codex-notify/notify-system.js --message-base64 \"Q29kZXjku7vliqHlt7LlrozmiJA=\""
      }]
    }]
  }
}

Windows 示例（注意需要使用双反斜杠或用双引号包裹路径）：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node \"C:\\\\Users\\\\你的用户名\\\\Projects\\\\codex-notify\\\\notify-system.js\" --message-base64 \"Q29kZXjku7vliqHlt7LlrozmiJA=\""
      }]
    }]
  }
}

高级配置（自定义消息）
如需自定义提示语，可将 Base64 字符串替换为自己的编码结果：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node /projects/codex-notify/notify-system.js --message-base64 \"5Luj56CB5LyY5YyW5a6M5oiQ\""
      }]
    }]
  }
}

Base64 生成方式示例：

• Linux/macOS：printf '代码优化完成' | base64
• Windows PowerShell：[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('代码优化完成'))

⚠️ 编码兼容说明

• v1.1.0 起 Stop Hook 默认以 Base64 方式传递任务描述，解决 Windows CMD/PowerShell 触发时的中文乱码问题。
• 已安装旧版 Hook 的用户可执行 codex-notify install-hook --force 或重新运行 codex-notify setup（是否需要配置飞书通知？ 选择 n）来更新命令。
• 当需要与其他系统集成时，请坚持使用 UTF-8 编码并在必要时传递 Base64，防止出现 Codex浠诲姟宸插畬鎴? 这类乱码。

该配置会：

• ✅ 自动识别项目名称并显示在通知标题
• 📱 发送飞书通知（如果配置了）
• 🔊 播放声音提醒
• ⌚ 触发手环震动

🎯 使用效果

配置完成后，当Codex CLI完成任务时：

1. 📱 手机通知：飞书APP会收到任务完成消息
2. ⌚ 手环震动：小米手环等智能设备会震动提醒
3. 🔊 声音提醒：Windows 播放语音提示，其它平台自动触发蜂鸣声

这样你就可以专心玩手机，当任务完成时通过手环震动就能知道！

🧪 测试功能

测试完整通知系统

codex-notify notify --message "测试任务"
# 或手动运行
node notify-system.js --task "测试任务"

只测试飞书通知

node feishu-notify.js --webhook "你的webhook地址" --message "测试消息"

只测试声音提醒

node notify-sound.js

测试Codex CLI集成

cd test-project
npm run test

🔧 技术实现

架构设计

• 分层架构：env-config → notification-manager → notify-system
• 模块化设计：分离各种通知方式，独立开发和测试
• 统一接口：通过NotificationManager统一管理所有通知
• 异步处理：并行发送多种通知，提高响应速度
• 容错机制：单一通知失败不影响其他通知方式
• 环境变量优先：支持.env安全配置，保护敏感信息

安全特性

• 🔒 环境变量保护：敏感信息存储在.env文件中，已加入.gitignore
• 🔐 配置隔离：敏感配置与代码分离，防止意外泄露
• 🛡️ 模板化配置：提供.env.example模板，便于团队协作

核心模块

• notify-system.js：主通知系统，协调所有提醒方式
• notification-manager.js：通知管理器，统一管理各种通知接口
• env-config.js：环境变量配置管理，统一处理环境变量加载
• feishu-notify.js：飞书API调用模块，支持富文本消息
• telegram-notify.js：Telegram 推送模块（可选启用）
• config.json：传统的配置文件管理（可选）

智能功能

• 🧠 项目名称识别：自动识别当前项目名称（package.json > git仓库名 > 目录名）
• 📱 手环适配：消息格式优化，项目名优先显示，适配小屏幕设备
• 🔄 跨项目支持：无论从哪个目录启动Codex CLI都能正确识别项目

Hook集成

• 使用Codex CLI的Stop hook，在任务完成时自动触发
• 不影响正常的任务执行流程
• 支持命令行参数自定义任务信息

📈 产品路线图

近期计划 (v1.2)

• [ ] 支持更多通知平台（微信、钉钉、企业微信）
• [ ] 添加任务执行时间统计
• [ ] 支持自定义通知模板
• [ ] 开发可视化配置界面

中期计划 (v2.0)

• [ ] 开发Codex CLI官方插件
• [ ] 支持跨平台（macOS、Linux）
• [ ] 添加任务进度实时推送
• [ ] 支持群组协作通知

长期愿景

• [ ] 智能任务调度和优先级管理
• [ ] 集成更多智能穿戴设备
• [ ] 开发移动端APP
• [ ] 支持多AI平台集成

🏆 参赛亮点

解决的实际问题

1. 专注度提升：开发者可以专心做其他事情，不用频繁检查任务状态
2. 效率优化：及时获知任务完成，提高工作流程效率
3. 体验改善：通过手环震动等私密提醒，不打扰他人

技术创新点

1. 多通道通知：声音 + 手机推送 + 手环震动的立体提醒体系
2. 智能集成：与Codex CLI深度集成，自动触发通知
3. 模块化架构：高度可扩展，支持多种通知方式
4. 用户友好：配置简单，一键启用

商业价值

• B2C市场：面向个人开发者的小工具产品
• B2B市场：面向开发团队的协作效率工具
• 生态价值：丰富AI编程工具生态，提升用户体验

🎯 完整使用流程

graph TD
    A[用户向Codex CLI下达任务] --> B[Codex CLI执行任务]
    B --> C[用户专心玩手机/做其他事]
    B --> D[任务执行完成]
    D --> E[触发Stop Hook]
    E --> F[调用notify-system.js]
    F --> G[并行发送通知]
    G --> H[📱 飞书消息推送到手机]
    G --> I[🔊 电脑播放语音提醒]
    H --> J[⌚ 手环震动提醒]
    I --> K[用户听到语音提醒]
    J --> L[用户感到手环震动]
    K --> M[查看任务结果]
    L --> M

现在你只需要配置好飞书webhook，就能享受这个强大的提醒系统了！详细配置请查看 SETUP.md。

让AI编程更专注，让开发更高效！ 🚀