TaskSentinel

中文 | English

一个功能强大、轻量级的企业通知工具，专为开发者和运维团队设计，支持企业微信和钉钉平台的自动化通知。

🚀 项目简介

TaskSentinel 是一个高度可配置的 Shell 脚本工具，旨在简化企业级通知的发送流程。它特别适合与 CI/CD 流程、监控系统和开发工作流集成，提供可靠的通知传递机制。

✨ 核心特性

多平台支持：完整支持企业微信、钉钉、Slack等多种通知平台
多种消息格式：支持纯文本和 Markdown 格式消息
智能@提及：支持根据事件类型自动@特定用户或@全员
Claude Code 集成：专门的适配器无缝集成 Claude Code 钩子系统
多应用集成：支持 GitHub Actions、Jenkins、Docker、Cron 等多种集成方式
安全机制：
- 钉钉加签安全验证（HMAC-SHA256）
- 企业微信 webhook 密钥保护
- 配置文件敏感信息加密存储
智能节流：可配置的通知频率限制，防止消息轰炸
错误处理：完善的重试机制和错误恢复
调试模式：详细的日志记录和调试信息
模板系统：预设通知模板（默认、警告、信息）
跨平台支持：Linux、macOS、Windows (WSL)

📋 系统要求

操作系统支持

Linux: Ubuntu 18.04+, CentOS 7+, Debian 9+
macOS: 10.15+
Windows: WSL 2 或 Git Bash

必需依赖

Bash: 4.0+ (推荐 5.0+)
jq: 1.6+ (JSON 处理工具)
curl: 7.40+ (HTTP 客户端)
OpenSSL: 1.1.1+ (加密工具，钉钉签名需要)

可选依赖

bats-core: 1.9.0+ (运行测试套件)

🔧 安装方式

方式一：自动安装（推荐）

# 下载并运行安装脚本
curl -fsSL https://raw.githubusercontent.com/TaskSentinel/TaskSentinel/main/scripts/install.sh | bash

# 或者克隆仓库后运行
git clone https://github.com/TaskSentinel/TaskSentinel.git
cd TaskSentinel
./scripts/install.sh

安装脚本将会：

检查并提示安装必需依赖
创建 ~/.tasksentry 配置目录
复制主脚本到 /usr/local/bin/tasksentry（或您选择的路径）
生成初始配置文件模板

方式二：手动安装

# 1. 克隆仓库
git clone https://github.com/TaskSentinel/TaskSentinel.git
cd TaskSentinel

# 2. 创建配置目录
mkdir -p ~/.tasksentry

# 3. 复制配置文件模板
cp config/config.example.json ~/.tasksentry/config.json

# 4. 复制主脚本到系统路径
sudo cp scripts/tasksentry.sh /usr/local/bin/tasksentry
sudo chmod +x /usr/local/bin/tasksentry

# 5. 编辑配置文件
nano ~/.tasksentry/config.json

⚙️ 配置说明

TaskSentinel 现已支持多平台同时配置和使用。新的配置结构允许您：

同时配置多个通知平台
独立控制每个平台的启用状态
为每个平台设置专属的配置参数

配置文件结构

配置文件使用 JSON 格式，主要分为全局配置和平台配置两部分：

{
  "debug": false,
  "throttle_seconds": 60,
  "retry": {
    "max_attempts": 3,
    "delay_seconds": 2
  },
  "platforms": {
    "dingtalk": {
      "enabled": true,
      "webhook_url": "...",
      "secret": "...",
      "format": "text",
      "mentions": { ... },
      "templates": { ... }
    },
    "wechat": {
      "enabled": false,
      "webhook_url": "...",
      "format": "markdown",
      "mentions": { ... },
      "templates": { ... }
    },
    "slack": {
      "enabled": false,
      "webhook_url": "...",
      "format": "json",
      "mentions": { ... },
      "templates": { ... }
    }
  }
}

钉钉平台配置

获取 Webhook URL 和密钥：
- 在钉钉群中，点击右上角设置图标
- 选择"智能群助手" > "添加机器人" > "自定义"
- 选择"加签"安全设置，复制密钥
- 复制生成的 Webhook URL
配置示例：

{
  "platforms": {
    "dingtalk": {
      "enabled": true,
      "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN",
      "secret": "SEC123456789abcdef_YOUR_SECRET_HERE",
      "format": "text",
      "mentions": {
        "enabled": true,
        "default_mention": ["@all"],
        "user_mappings": {
          "admin": {
            "name": "管理员",
            "mobile": "13800138000"
          }
        }
      }
    }
  }
}

企业微信平台配置

获取 Webhook URL：
- 在企业微信群中，点击右上角 "..."
- 选择"添加群机器人" > "创建一个机器人"
- 复制生成的 Webhook URL
配置示例：

{
  "platforms": {
    "wechat": {
      "enabled": true,
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_WECHAT_KEY",
      "format": "markdown",
      "mentions": {
        "enabled": true,
        "default_mention": [],
        "user_mappings": {
          "admin": {
            "name": "管理员"
          }
        }
      }
    }
  }
}

Slack 平台配置

获取 Webhook URL：
- 在 Slack 工作区中创建一个应用
- 启用 Incoming Webhooks 功能
- 复制生成的 Webhook URL
配置示例：

{
  "platforms": {
    "slack": {
      "enabled": true,
      "webhook_url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
      "format": "json",
      "mentions": {
        "enabled": true,
        "default_mention": ["@channel"],
        "user_mappings": {
          "admin": {
            "name": "@admin.user"
          }
        }
      }
    }
  }
}

完整配置选项

全局配置

debug: 调试模式开关，默认 false
throttle_seconds: 全局节流时间（秒），默认 60
retry.max_attempts: 最大重试次数，默认 3
retry.delay_seconds: 重试延迟时间（秒），默认 2

平台配置

每个平台都支持以下配置选项：

enabled: 是否启用该平台，true/false
webhook_url: Webhook URL（必需）
secret: 加签密钥（钉钉平台可选）
format: 消息格式，支持 text、markdown、json
mentions: @提及功能配置
templates: 消息模板配置

@提及功能配置

{
  "mentions": {
    "enabled": true,                    // 启用/禁用@提及功能
    "default_mention": ["@all"],        // 默认提及用户
    "user_mappings": {                  // 用户映射
      "admin": {
        "name": "管理员",
        "mobile": "13800138000"         // 钉钉需要手机号
      }
    },
    "event_mentions": {                 // 按事件类型配置提及
      "error": ["admin"],
      "warning": ["admin", "developer"],
      "task_complete": ["developer"],
      "info": []
    }
  }
}

消息模板配置

{
  "templates": {
    "default": {
      "title_prefix": "[通知]",
      "timestamp": true
    },
    "alert": {
      "title_prefix": "[警告]",
      "color": "red",                   // 部分平台支持颜色
      "timestamp": true
    },
    "info": {
      "title_prefix": "[信息]",
      "color": "blue",
      "timestamp": true
    }
  }
}

@提及功能说明

TaskSentinel 支持智能@提及功能，可以根据不同的事件类型自动@相关人员：

钉钉平台：使用 @手机号 格式，支持 @all 全员提及
企业微信平台：使用 <@手机号> 格式，支持 <@all> 全员提及
用户映射：通过 user_mappings 配置用户名到手机号的映射关系
事件级配置：不同事件类型可以配置不同的提及用户列表
灵活控制：可以通过 enabled 字段全局开关@提及功能

🔌 Claude Code 集成

TaskSentinel 提供专门的 Claude Code 适配器，可以无缝集成到 Claude Code 的钩子系统中，自动发送开发进度和任务完成通知。

快速配置

复制示例配置：

cp config/claude-settings.example.json .claude/settings.json

配置 TaskSentinel 通知设置：

# 编辑您的通知配置
nano ~/.tasksentry/config.json

测试集成：

# 测试通知钩子
echo '{"event": "info", "message": "测试消息"}' | ./scripts/claude-hook-adapter.sh

支持的钩子事件

TaskSentinel 适配器支持以下 Claude Code 钩子：

Notification: Claude Code 发送通知时触发
Stop: 主任务完成时发送完成通知
SubagentStop: 子任务完成时发送进度通知

完整配置示例

在项目根目录创建 .claude/settings.json：

{
  "Notification": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/scripts/claude-hook-adapter.sh",
          "timeout": 30
        }
      ]
    }
  ],
  "Stop": [
    {
      "hooks": [
        {
          "type": "command", 
          "command": "$CLAUDE_PROJECT_DIR/scripts/claude-hook-adapter.sh",
          "timeout": 30
        }
      ]
    }
  ],
  "SubagentStop": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/scripts/claude-hook-adapter.sh", 
          "timeout": 30
        }
      ]
    }
  ]
}

适配器工作原理

Claude Hook 适配器 (scripts/claude-hook-adapter.sh) 的功能：

数据格式转换：将 Claude Code 的钩子数据转换为 TaskSentinel 标准格式
事件类型映射：
- notification → info
- stop → task_complete
- error → error
- warning → warning
自动上下文获取：自动添加当前工作目录信息
错误处理：优雅处理缺失数据和格式错误

高级配置

您可以通过修改适配器脚本来自定义行为：

# 编辑适配器配置
nano scripts/claude-hook-adapter.sh

# 添加自定义事件映射
case "$CLAUDE_TYPE" in
    "deployment")
        EVENT_TYPE="task_complete"
        ;;
    "test_failure") 
        EVENT_TYPE="error"
        ;;
esac

📖 使用方法

基本用法

# 发送简单文本消息
tasksentry --message "Hello World"

# 发送带标题的消息
tasksentry --title "部署通知" --message "应用已成功部署到生产环境"

# 使用 Markdown 格式
tasksentry --title "**重要通知**" --message "## 系统维护\n\n维护时间：今晚 22:00-24:00" --format markdown

# 指定配置文件
tasksentry --config /path/to/config.json --message "自定义配置消息"

# 调试模式
tasksentry --debug --message "调试消息"

高级用法

# 使用预设模板
tasksentry --template alert --message "系统告警：CPU 使用率超过 90%"

# 管道输入
echo "构建失败" | tasksentry --title "CI/CD 通知"

# 文件内容作为消息
tasksentry --title "日志报告" --file /var/log/app.log

# 条件发送（仅当上个命令失败时发送）
make build || tasksentry --title "构建失败" --message "请检查构建日志"

脚本集成示例

#!/bin/bash
# deploy.sh - 部署脚本示例

set -e

# 部署开始通知
tasksentry --title "部署开始" --message "开始部署应用到生产环境"

# 执行部署
if docker-compose up -d; then
    tasksentry --template info --title "部署成功" --message "应用已成功部署并启动"
else
    tasksentry --template alert --title "部署失败" --message "部署过程中出现错误，请检查日志"
    exit 1
fi

🛠️ 故障排除

常见问题

Q: 提示 "jq: command not found"

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL  
sudo yum install jq

# macOS
brew install jq

Q: 钉钉消息发送失败，返回 310000 错误

检查加签密钥是否正确配置在 secret 字段
确认 Webhook URL 是否完整且有效
验证系统时间是否准确（加签对时间敏感）

Q: 企业微信消息格式错误

企业微信建议使用 "format": "markdown"
检查 Markdown 语法是否正确
避免使用不支持的 Markdown 元素

Q: 通知频率过高被限制

调整 throttle_seconds 配置
检查是否有多个脚本同时发送通知
使用调试模式查看节流日志

Q: 权限问题

# 修复脚本权限
chmod +x /usr/local/bin/tasksentry

# 修复配置文件权限
chmod 600 ~/.tasksentry/config.json

调试模式

启用调试模式获取详细信息：

# 方法1：命令行参数
tasksentry --debug --message "测试消息"

# 方法2：配置文件
{
  "debug": true,
  ...
}

# 方法3：环境变量
export TASKSENTRY_DEBUG=true
tasksentry --message "测试消息"

调试输出将包含：

HTTP 请求详情
签名生成过程
节流检查结果
错误堆栈信息

🧪 测试

运行完整测试套件：

# 安装测试依赖
npm install -g bats-core

# 运行所有测试
bats tests/

# 运行特定测试
bats tests/test_install.bats
bats tests/test_notifications.bats

# 生成测试覆盖率报告
bats --formatter tap tests/ | tee test_results.tap

🤝 贡献指南

我们欢迎社区贡献！请查看 CONTRIBUTING.md 了解详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/TaskSentinel/TaskSentinel.git
cd TaskSentinel

# 安装开发依赖
./scripts/install.sh --dev

# 运行代码检查
shellcheck scripts/*.sh

📄 许可证

本项目基于 MIT 许可证开源 - 详见 LICENSE 文件。

🙋‍♂️ 获取帮助

问题报告: GitHub Issues
功能请求: GitHub Discussions
文档: Wiki
集成指南: 集成文档
Claude Code 集成: Claude Code Hooks 配置

TaskSentinel - 让企业通知变得简单高效！ 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.bmad-core		.bmad-core
.claude/commands/BMad		.claude/commands/BMad
config		config
docs		docs
scripts		scripts
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_en.md		README_en.md

License

gonewx/TaskSentinel

Folders and files

Latest commit

History

Repository files navigation