TaskSentinel

KO | EN

gitlite — search

#react #ai #llm #golang #go #android #machine-learning #linux #docker #macos #security #pytorch #ios #openai

(★ 18)

A powerful, lightweight enterprise notification tool designed for developers and DevOps teams, supporting automated notifications for WeChat Work and DingTalk platforms.| 一个功能强大、轻量级的企业通知工具，专为开发者和运维团队设计，支持企业微信和钉钉平台的自动化通知。| Claude Code

TaskSentinel 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TaskSentinel

**中文** | [English](README_en.md)

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

## 🚀 项目简介

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+ (运行测试套件)

## 🔧 安装方式

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

```bash
# 下载并运行安装脚本
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`（或您选择的路径）
- 生成初始配置文件模板

### 方式二：手动安装

```bash
# 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 格式，主要分为全局配置和平台配置两部分：

```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": { ... }
    }
  }
}
```

### 钉钉平台配置

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

2. **配置示例**：
```json
{
  "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"
          }
        }
      }
    }
  }
}
```

### 企业微信平台配置

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

2. **配置示例**：
```json
{
  "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 平台配置

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

2. **配置示例**：
```json
{
  "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`: 消息模板配置

#### @提及功能配置

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

#### 消息模板配置

```json
{
  "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 的钩子系统中，自动发送开发进度和任务完成通知。

### 快速配置

1. **复制示例配置**：
   ```bash
   cp config/claude-settings.example.json .claude/settings.json
   ```

2. **配置 TaskSentinel 通知设置**：
   ```bash
   # 编辑您的通知配置
   nano ~/.tasksentry/config.json
   ```

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

### 支持的钩子事件

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

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

### 完整配置示例

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

```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`) 的功能：

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

### 高级配置

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

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

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

## 📖 使用方法

### 基本用法

```bash
# 发送简单文本消息
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 "调试消息"
```

### 高级用法

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

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

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

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

### 脚本集成示例

```bash
#!/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"**
```bash
# 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: 权限问题**
```bash
# 修复脚本权限
chmod +x /usr/local/bin/tasksentry

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

### 调试模式

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

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

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

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

调试输出将包含：
- HTTP 请求详情
- 签名生成过程
- 节流检查结果
- 错误堆栈信息

## 🧪 测试

运行完整测试套件：

```bash
# 安装测试依赖
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](CONTRIBUTING.md) 了解详细信息。

### 开发环境设置

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

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

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

## 📄 许可证

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

## 🙋‍♂️ 获取帮助

- **问题报告**: [GitHub Issues](https://github.com/TaskSentinel/TaskSentinel/issues)
- **功能请求**: [GitHub Discussions](https://github.com/TaskSentinel/TaskSentinel/discussions)
- **文档**: [Wiki](https://github.com/TaskSentinel/TaskSentinel/wiki)
- **集成指南**: [集成文档](docs/integrations.md)
- **Claude Code 集成**: [Claude Code Hooks 配置](docs/hooks_configuration.md)

---

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

TaskSentinel

TaskSentinel 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

TaskSentinel

TaskSentinel 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README