/byted-volcengine-alert-inspection-analyzer

name: byted-volcengine-alert-inspection-analyzer
description: 面向日常运维巡检场景，对告警、体检等信息进行按日采集、结构化沉淀和周期输出（日报/周报/月报）。
version: 1.0.0

byted-volcengine-alert-inspection-analyzer

把“飞书群告警消息拉取 + 过滤 + 去重 + 事件聚合 + 风险分析 + 报告输出”固化为标准技能。

适用场景

当用户提出以下类型需求时使用本技能：

• 查询某个飞书群某天/某时间段内的云告警通知
• 拉取指定机器人、Bot、应用发送的告警消息
• 对告警消息做巡检分析、日报、复盘或稳定性判断
• 需要导出结构化 JSON、Markdown 报告或压缩包
• 需要判断告警是否恢复、是否存在未闭环事件、是否为噪声告警

输入要求

至少需要以下三类信息：

1. `chat_id`：飞书群 ID，例如 `oc_xxx` 2. `time`：时间范围

• 相对时间：`today`、`yesterday`、`last_24_hours`、`this_week`
• 或绝对时间：`start_time` + `end_time`，ISO 8601 格式，例如 `2026-06-05T00:00:00+08:00`

3. `bot`：机器人标识

• 优先使用 `bot_sender_id` / app id，例如 `cli_xxx`
• 如果只有机器人名称，先按时间范围拉取消息后从 sender 信息识别；同时说明精确度风险

可选信息：

• `output_dir`：输出目录，默认 `output/alert_inspection_<日期>_<chat_id>/`
• `report_format`：`json`、`markdown`，默认同时生成
• `keyword`：内容关键词过滤，例如“火山引擎云监控告警通知”

工作流程

1. 校验输入

• 缺少 `chat_id`、`time` 或 `bot` 时，先向用户补齐。
• 时间必须二选一：相对时间，或 `start_time + end_time`。
• 对中文日期（如“6月5日”）默认使用当前年份和北京时间，除非用户另有说明。

2. 拉取飞书消息

优先使用 `feishu_im_user_get_messages` 工具：

{
  "chat_id": "oc_xxx",
  "start_time": "2026-06-05T00:00:00+08:00",
  "end_time": "2026-06-05T23:59:59+08:00",
  "page_size": 50,
  "sort_rule": "create_time_asc"
}

分页规则：

• 每页最多 50 条。
• 如果返回 `has_more=true`，继续使用 `page_token` 拉取下一页。
• 合并所有分页结果后按 `message_id` 去重。

3. 机器人过滤

过滤优先级：

1. 如果用户提供 `bot_sender_id`：按 `sender.id` 精确过滤。 2. 如果只有机器人名称：

• 先从返回消息中识别 `sender.sender_type == app` 的候选 sender id。
• 结合消息卡片标题、内容关键词和告警语义做保守筛选。
• 一旦确认 sender id，后续分析中记录为 `filter_mode=identified_sender_id`。

3. 如果无法确认 sender id：

• 用内容关键词过滤。
• 在报告中明确标注 `filter_mode=keyword_only`，说明可能不完整或不精确。

4. 标准化消息

使用 `scripts/alert_inspection.py` 对原始消息 JSON 做标准化。标准字段：

• `message_id`
• `create_time`
• `status`：`警告` / `已恢复` / `严重` / `未知`
• `policy`
• `resource`
• `metric`
• `current_value`
• `content`
• `sender`

从飞书卡片内容中尽量提取：

• 告警策略
• 告警级别
• 项目
• 地域
• 告警时间
• 云产品
• 资源 ID
• 当前值
• 告警详情链接

5. 分析告警

分析维度：

• 总消息数、警告数、恢复数、未知数
• 按策略统计
• 按指标统计
• 按资源统计
• 按小时统计
• 告警事件闭环：连续警告到恢复为一个事件周期
• 未恢复事件识别
• 持续时间、最长事件、重复事件
• 风险等级：低 / 中 / 高
• 可能原因与处置建议

风险判断建议：

• **低风险**：少量告警，全部快速恢复，无重复集中模式。
• **中风险**：同一资源/指标反复告警，全部恢复但频率较高。
• **高风险**：存在未恢复告警、严重级别告警、长时间持续、核心指标异常或高频集中爆发。

6. 输出文件

默认输出到：

output/alert_inspection_<YYYY-MM-DD>_<chat_id>/

应生成：

• `raw_messages.json`：原始消息
• `normalized_messages.json`：标准化消息
• `analysis.json`：统计与分析结构化数据
• `report.md`：面向用户的中文分析报告
• `run_meta.json`：运行元数据

如用户要求发送压缩包，则将输出目录打包为 `.zip` 后用 `message` 工具发送。

推荐执行方式

A. 已通过工具获得原始消息时

将工具返回结果保存为原始 JSON：

python scripts/alert_inspection.py \
  --input raw_messages.json \
  --chat-id oc_xxx \
  --bot-name 云告警通知 \
  --start-time 2026-06-05T00:00:00+08:00 \
  --end-time 2026-06-05T23:59:59+08:00 \
  --output-dir output/alert_inspection_2026-06-05_oc_xxx

B. 需要从飞书实时拉取时

1. 用 `feishu_im_user_get_messages` 按群和时间分页拉取。 2. 保存为 `raw_messages.json`。 3. 调用 `scripts/alert_inspection.py` 生成分析文件。 4. 回复用户摘要；如果有文件/压缩包，使用 `message` 工具发送，不要只返回 `MEDIA:` 标签。

回复用户模板

已完成告警巡检分析。

结果摘要：
- 时间范围：...
- 命中消息：... 条
- 警告：... 条，恢复：... 条，未闭环：... 条
- 主要资源：...
- 风险等级：...
- 输出目录：...

核心判断：...
建议：...

注意事项

• 不要编造告警数据；没有拿到原始消息就不要声称已分析。
• 机器人名称不是稳定过滤条件，优先使用 sender id。
• 报告中要明确数据来源、过滤方式和精度风险。
• 不要输出 token、cookie、授权信息等敏感数据。
• 外发文件时遵循当前平台文件发送规则，使用 `message` 工具发送本地绝对路径。