网管平台告警轮询（NMS Alert Poller）
Overview
提供一个可配置、平台无关的告警巡检能力：按固定间隔（默认 5 分钟）调用任意 REST API 网管平台，
拉取全体设备的告警列表，通过本地状态文件去重以识别"新增"告警，并对每一条新增告警调用配置好的
通知 Webhook（钉钉 / 飞书 / 企业微信 / 通用）。适合做轻量级网络告警监控、定时巡检、故障即时推送。
核心交付物：
- scripts/poll_alerts.py — 轮询与通知主脚本（标准库实现，仅 YAML 解析需可选 pyyaml）。
- scripts/config.example.yaml — 配置模板（带中文注释，不含密钥）。
- references/webhook_formats.md — 三种群机器人接入与签名说明、模板变量与多机器人约定。
When to use
- 用户希望"对网管平台告警做定时轮询 / 巡检"。
- 用户要求"每 N 分钟检查一次设备告警，有新增就通知我/推送到群"。
- 用户需要把某个 REST API 平台的告警事件接入钉钉/飞书/企业微信。
- 用户要搭建一个无需人工干预的告警监控自动化。
不适用：单次手动查看告警（可直接调用 API，无需本 skill 的去重/调度封装）。
Workflow
1. 准备配置文件
首次使用，将 scripts/config.example.yaml 复制为 config.yaml，并按目标平台填写：
nms.base_url+nms.alerts_endpoint：告警列表接口。nms.auth：认证方式（bearer / apikey / basic）。nms.response.*：把平台返回字段映射为{id, device, severity, message, time}。
列表路径与字段均支持点号嵌套（如data.alerts、device.name）。notify.*：选dingtalk/feishu/wecom/generic，填 Webhook 地址与加签secret。
此外还支持dingtalk_user：不走群机器人，而是经由dws（connector-dingtalk）以
个人单聊方式把告警直接发给指定用户。需配置：recipient_query：接收人姓名/备注（用dws --user-query解析），或recipient_id：钉钉 openId（用dws --user）。format：markdown（默认）或text。- 该方式要求本机
dws已连接钉钉账号；发送时脚本自动加--yes以适配非交互环境。
典型用法：用户不要群机器人、希望告警只推到自己钉钉时，设type: dingtalk_user+
recipient_query: "你的名字"。 poller.interval_seconds：默认300（5 分钟）。dedup.state_file：已见告警状态文件，用于跨轮询去重；retain_days控制清理周期。
密钥安全：所有含 ${ENV_VAR} 的值会从环境变量展开，切勿把真实 token 写进配置文件。
在运行环境导出：export NMS_TOKEN=xxx、export ALERT_WEBHOOK_URL=xxx、export ALERT_WEBHOOK_SECRET=xxx。
Webhook 三种机器人的接入与签名细节见 references/webhook_formats.md（含模板变量与多机器人约定）。
2. 验证配置（dry-run）
先用 dry-run 跑一次，确认接口连通、字段映射正确、能识别新增告警，但不发通知：
python3 scripts/poll_alerts.py --config scripts/config.yaml --dry-run
脚本会打印人类可读结果，并输出一行 JSON 摘要（含 new_count、total_active、errors）。
检查 new_count 与设备/等级字段是否符合预期；有 errors 先排查接口或字段映射。
3. 正式轮询一次
python3 scripts/poll_alerts.py --config scripts/config.yaml
新增告警会被推送至配置的 Webhook，状态文件写入本次所有活跃告警 ID，下一轮只推"新出现"的告警。
4. 持续轮询（可选）
- 方式 A — 脚本自循环（不依赖调度器，最稳妥，满足"每 5 分钟"）：
bash # 安静模式：stdout 只输出单行状态；完整详情写入受控轮转的日志文件 python3 scripts/poll_alerts.py --config scripts/config.yaml --loop --quiet \ --log-file ~/.workbuddy/skills/nms-alert-poller/logs/poll_loop.log
> ⚠️ 关于"日志一直打印告警信息"：脚本本身只向 stdout 输出，不会自行创建
> 任何日志文件。若此前用... --loop > poll_loop.log 2>&1这类 shell 重定向 来落盘，
> 每个轮询周期都会把完整告警详情（设备 / 内容 / 时间）无限制地追加进该文件——
> 这正是"一直打印告警"的真正来源。改用--log-file（自带 2MB 轮转、保留 3 份）
> 即可让日志受控、自动滚动，且配合--quiet时 stdout 仅保留一行状态、不再刷屏。 - 方式 B — WorkBuddy 定时自动化：用
automation_update创建一个
scheduleType=recurring、rrule=FREQ=MINUTELY;INTERVAL=5的自动化，prompt 写明
"使用 nms-alert-poller skill，运行 poll_alerts.py 对网管平台全体设备告警轮询一次，
将本次新增数量/总数/错误摘要报告给用户"。让它在后台每 5 分钟执行一次本流程。
（若运行环境的调度器不支持分钟级，则用方式 A 或系统 cron 兜底。）
运行说明
- Python 路径：在本环境使用 managed Python（通过 WorkBuddy 的 Python 运行时执行）；
其他环境用python3（需pip install pyyaml才能读.yaml，或改用.json配置免依赖）。 - 配置文件定位顺序：
--config参数 → 环境变量NMS_POLLER_CONFIG→ 脚本同目录
config.yaml/config.json→~/.workbuddy/skills/nms-alert-poller/config.yaml。 - 退出码：本轮成功
0，存在错误（含通知失败）1，配置加载失败2。自动化可据此判断健康度。 - 去重逻辑：只有"本次出现、且状态文件中未记录过"的告警才算新增；告警恢复后若再次触发会重新推送（适合抖动场景）。
- 多机器人通知：
notify支持写成列表，脚本会遍历每个通知通道逐一发送（每个通道可独立配置
type、webhook_url、secret、template、severity_map等）。 - 日志落盘：脚本默认只输出到 stdout，不写文件。需要持久化日志请用
--log-file <路径>（自带 2MB 轮转、保留 3 份），不要依赖 shell 重定向；
循环模式建议配合--quiet（-q），这样每个周期只在 stdout 留一行状态，
完整告警详情仅写入受控日志，避免日志无限膨胀。 - 常用参数：
--loop持续循环；--quiet/-q安静模式（只输出必要状态）；
--log-file <路径>受控轮转日志；--dry-run只识别新增、不发 Webhook。
扩展
- 多机器人：已原生支持，将
notify写为列表即可同时推送到多个群/用户，各通道独立配置（详见references/webhook_formats.md）。 - 自定义动作：若通知目标不是群机器人而是派单/处置接口，在
poll_once的通知段落
替换为对应的 HTTP 调用即可（脚本已封装http_json与签名工具函数）。
