telegram-alert

Telegram告警专业版

专业版增强能力

功能能力

PRO版功能增强对比

复合触发条件

# PRO版支持复合逻辑
triggers:
  - name: "BTC突破+成交量放大"
    conditions:
      - ticker: BTC-USD
        metric: price
        operator: "above"
        value: 65000
      - ticker: BTC-USD
        metric: volume
        operator: "above"
        value: 1000000000
    logic: "AND"                    # AND 或 OR
# ...
  - name: "跌至支撑位或破前低"
    conditions:
      - ticker: AAPL
        metric: price
        operator: "below"
        value: 170
      - ticker: AAPL
        metric: price
        operator: "below"
        value: 165
    logic: "OR"

入门指引

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

场景一：多群组信号分发

用户输入："把买入信号同时发到3个Telegram群"

# 多群组推送
python3 （请参考skill目录中的脚本文件） broadcast \
  --message "买入信号: AAPL 突破阻力位180" \
  --chat-ids "@group1,@group2,@group3" \
  --priority high \
  --include-chart
# ...
# 输出：各群组发送状态
# [OK] @group1 - 发送成功
# [OK] @group2 - 发送成功
# [FAIL] @group3 - 发送失败（重试中）

场景二：复合触发告警

用户输入："BTC突破65000且成交量超过10亿时提醒"

# 设置复合触发
python3 （请参考skill目录中的脚本文件） add \
  --name "BTC突破+量能" \
  --conditions "price:BTC-USD:above:65000,volume:BTC-USD:above:1000000000" \
  --logic AND \
  --channels "telegram,dingtalk" \
  --priority high
# ...
# 启动监控
python3 （请参考skill目录中的脚本文件） monitor --multi-channel

场景三：定时市场播报

用户输入："每天9点和15点发市场概况，带图表"

# 设置定时播报
python3 （请参考skill目录中的脚本文件） add \
  --name "每日市场播报" \
  --times "09:00,15:00" \
  --message-type "market_summary" \
  --include-chart \
  --include-watchlist \
  --channels "telegram,dingtalk" \
  --chat-ids "@trading_team"

操作步骤

PRO版初始化

# 依赖说明
pip install -r requirements_pro.txt
# ...
# 配置多通道
cp config_pro_template.yaml config_pro.yaml
# 填入各通道的凭证

常用命令

# 多群组广播
python3 （请参考skill目录中的脚本文件） broadcast --message "信号" --chat-ids "@g1,@g2,@g3"
# ...
# 复合告警
python3 （请参考skill目录中的脚本文件） add --conditions "price:AAPL:above:180,volume:AAPL:above:100M" --logic AND
# ...
# 定时播报
python3 （请参考skill目录中的脚本文件） add --times "09:00,15:00" --message-type market_summary
# ...
# 告警历史分析
python3 （请参考skill目录中的脚本文件） stats --period 30d
python3 （请参考skill目录中的脚本文件） export --format excel

输入规范

输出规范

{
  "success": true,
  "data": {
    "message_id": "msg_20260728_001",
    "sent_channels": ["telegram"],
    "failed_channels": [],
    "metadata": {
      "template_used": "alert_pro",
      "priority": "high",
      "timestamp": "2026-07-28T10:30:00Z"
    }
  },
  "error": null
}

输出模板参考: assets/output.json

异常处置

安装与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Python版本: 3.9+
• 网络: 需访问各通知通道API

第三方依赖

API Key 配置

• 未配置的通道自动跳过，不影响已配置通道
• 所有凭证存储在本地配置文件

可用性分类

• 分类: MD+EXEC（Markdown指令+Python脚本执行）
• 说明: 多通道告警通知系统，支持复合触发与富媒体消息
• PRO版特性: 多群组同步、复合触发、富媒体、多通道、告警去重、优先级管理
• 兼容性: 完全兼容免费版命令与配置，支持一键迁移

案例展示

PRO多通道配置

pro_config:
  channels:
    telegram:
      bot_token: "${TELEGRAM_BOT_TOKEN}"
      groups:
        - chat_id: "@trading_signals"
          name: "交易信号群"
          priority: high
        - chat_id: "@risk_alerts"
          name: "风险告警群"
          priority: critical
        - chat_id: "@market_summary"
          name: "市场概况群"
          priority: normal
# ...
    dingtalk:
      webhook: "${DINGTALK_WEBHOOK}"
      secret: "${DINGTALK_SECRET}"
# ...
    wechat_work:
      webhook: "${WECOM_WEBHOOK}"
# ...
    email:
      smtp_host: "${SMTP_HOST}"
      smtp_port: 587
      username: "${EMAIL_USER}"
      password: "${EMAIL_PASS}"
# ...
  alerts:
    deduplication:
      enabled: true
      window: 300                # 去重窗口（秒）
    priority:
      levels: [critical, high, normal, low]
      routing:
        critical: ["telegram", "dingtalk", "email"]
        high: ["telegram", "dingtalk"]
        normal: ["telegram"]
        low: ["telegram"]
# ...
    triggers:
      max_conditions: 10         # 单告警最大条件数
      logic: ["AND", "OR"]
      custom_scripts: true       # 支持自定义脚本
# ...
  scheduling:
    timezone: "Asia/Shanghai"
    max_schedules: 50
    retry_failed: true
# ...
  history:
    storage: "数据库"
    retention_days: 365
    analytics: true

问答集锦

Q1：支持哪些通知通道？

PRO版支持Telegram、钉钉、企业微信、飞书Webhook和邮件五种通道。可同时配置多个通道，告警按优先级自动路由.

Q2：复合触发条件如何工作？

当所有条件（AND）或任一条件（OR）满足时触发告警。支持价格、成交量、技术指标等多种指标的组合。每个告警最多支持10个条件.

Q3：告警去重如何工作？

PRO版在配置的去重窗口（默认5分钟）内，相同标的相同类型的告警只发送一次。避免因价格波动导致短时间内重复告警.

Q4：富媒体消息支持哪些内容？

支持发送图表（自动生成价格走势图）、图片、交互按钮（如"查看详情"、"确认交易"）。图表数据实时获取并渲染.

Q5：定时播报支持自定义内容吗？

支持。可通过自定义脚本生成播报内容，包括市场概况、持仓P&L、自选股变动等。支持Jinja2模板灵活定制消息格式.

错误恢复指南

功能边界

• Bot Token依赖: 必须配置有效的Telegram Bot Token才能使用核心功能
• 群组权限: Bot需被添加为目标群组成员并具有发送消息权限
• API频率限制: Telegram API限制每秒30条消息，批量发送时自动排队
• 富媒体生成: 图表生成依赖matplotlib，未安装时降级为纯文本消息
• 历史存储: 历史记录功能依赖数据库，未配置时不影响告警功能
• 时区支持: 定时播报使用配置的时区，默认为Asia/Shanghai

安全规范

• 无硬编码密钥: 所有Bot Token、Webhook URL等凭证通过环境变量加载，不在代码中硬编码
• 无敏感信息泄露: 日志中对Token、Webhook等敏感字段进行脱敏处理
• 凭证存储安全: 配置文件建议加入.gitignore，避免泄露到版本控制系统
• 最小权限原则: Bot仅授予发送消息权限，不需要管理员权限
• 数据传输加密: 所有API调用使用HTTPS加密传输
• 无不可信外部调用: 仅调用用户配置的通知通道API，不发起未授权请求

安全风险防范

功能详解与边界条件

核心功能详解

1. 多群组广播：支持同时向多个Telegram群组发送告警消息，各群组独立追踪发送状态。
2. 复合触发条件：支持AND/OR逻辑组合多个触发条件，可基于价格、成交量、技术指标等。
3. 富媒体消息：支持发送自动生成的价格图表、图片、交互按钮等富媒体内容。
4. 多通道通知：除Telegram外，支持钉钉、企业微信、邮件等通道，按优先级自动路由。
5. 告警去重：在配置的时间窗口内对相同标的的相同告警进行去重，避免重复打扰。
6. 定时播报：支持按时间计划自动发送市场概况、持仓分析等定期报告。

边界条件

1. 群组数量限制：单次广播最多支持50个群组。
2. 消息长度限制：单条消息不超过4096个字符（Telegram API限制）。
3. 触发条件限制：单个告警最多支持10个复合条件。
4. 定时任务限制：最多支持50个定时任务。
5. 去重窗口：默认300秒，可配置范围为60-3600秒。
6. 优先级级别：支持critical、high、normal、low四个级别。
7. API频率：Telegram API限制每秒30条消息，超出自动排队。
8. 历史保留期：历史记录默认保留365天。

性能指标

1. 消息发送延迟：单条消息发送延迟<2秒。
2. 多群组广播：10个群组广播完成时间<10秒。
3. 触发检测精度：触发条件检测延迟<1秒。
4. 系统可用性：系统可用性不低于99.5%。
5. 错误率：消息发送错误率<0.1%。

差异化优势对比

与同类方案对比

独有功能组合

1. 多通道智能路由：根据告警优先级自动选择通知通道，critical级别同时推送多通道，low级别仅推Telegram。
2. 复合触发与去重结合：支持复杂的AND/OR触发条件组合，同时通过智能去重避免短时间内重复告警。
3. 富媒体自动生成：自动获取实时市场数据并生成价格走势图表，无需人工截图。

诊断与修复

创新亮点

效率提升量化分析

差异化对比

功能介绍

• 自动化执行: 多通道交易告警系统，支持Telegram多群组推送、复合触发条件、富媒体消息与团队协作。
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

技术支持

Q1: Telegram告警专业版支持哪些输入格式？

A1: 多通道交易告警系统，支持Telegram多群组推送、复合触发条件、富媒体消息与团队协作。。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

效能分析

核心功能亮点

• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

错误恢复方案

针对Telegram告警专业版使用中可能遇到的常见问题,提供以下排查方案:

Telegram告警专业版通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

部署指引

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪