华为云 CCE 可观测性上下文构建器

**⚠️ 执行方式（必须阅读）：此技能通过本地 Python 脚本使用 scripts/huawei-cloud.py 分发器执行操作。禁止使用 hcloud、kubectl 或其他 CLI 工具，或直接调用 API。**

• 所有操作均通过 scripts/huawei-cloud.py 以 --action <动作名称> 和 --params <json参数> 方式分发
• 所有脚本及环境检查脚本均位于技能包内。**必须使用 skill action=exec 执行；不得在 shell 中直接运行**
• 动作名称与参数详情，请参见下方核心工具部分
• 请勿尝试使用 hcloud、kubectl、curl IAM 等 CLI/API 方法。此技能不依赖这些工具
• 所有路径均为相对于技能目录的相对路径，即此 SKILL.md 所在目录

概述

该技能将分散的故障信号整合为结构化、可诊断的上下文包。首先收集时间窗口、集群、命名空间、工作负载、Pod、节点及告警范围，然后按类型（告警、事件、指标、日志）收集证据，沿时间线合并信号，识别信息缺口，并推荐合适的下一诊断技能进行交接。此技能严格只读——从不执行修复操作。

架构：python3 scripts/huawei-cloud.py 分发器 → 华为云 Python SDK + AOM/LTS API → 告警、指标、日志、事件聚合

相关技能：

• huawei-cloud-cce-pod-failure-diagnoser - Pod CrashLoopBackOff、ImagePullBackOff、OOMKilled 诊断
• huawei-cloud-cce-node-failure-diagnoser - 节点健康、资源压力、NPD 事件诊断
• huawei-cloud-cce-network-failure-diagnoser - 网络连通性、DNS、ELB 诊断
• huawei-cloud-cce-storage-failure-diagnoser - PVC/PV 挂载、存储资源配置诊断
• huawei-cloud-cce-root-cause-analyzer - 跨域根因分析与报告
• huawei-cloud-cce-auto-remediation-runner - 修复操作（扩容、驱逐、回滚等）
• huawei-cloud-cce-alarm-correlation-engine - 告警去重与关联
• huawei-cloud-cce-metric-analyzer - 深度指标趋势分析
• huawei-cloud-cce-log-analyzer - 深度日志模式分析

功能特性：

• 收集活跃及历史 AOM 告警，去重并按严重程度分组（huawei_list_aom_alarms、huawei_analyze_aom_alarms）
• 获取按对象和原因分组的 Kubernetes 事件（huawei_get_cce_events）
• 查询 Pod 和节点的 TopN 指标，识别资源峰值与异常（huawei_get_cce_pod_metrics_topN、huawei_get_cce_node_metrics_topN）
• 查询 AOM 与 LTS 日志以获取深层日志证据（huawei_query_aom_logs、huawei_get_recent_logs）
• 获取 Pod 侧容器日志（huawei_get_pod_logs）
• 获取 AOM 指标与实例列表（huawei_get_aom_metrics、huawei_list_aom_instances）
• 基于收集数据生成监控仪表盘（huawei_generate_monitor_dashboard）
• 沿时间线合并信号，标记信息缺口，并推荐下一诊断技能

典型使用场景：

• “收集过去一小时内集群 xyz 的全部可观测性数据”
• “为 Pod 崩溃事件构建上下文包”
• “在诊断前收集告警、事件与指标”
• “我看到多个告警，将其合并为诊断上下文”
• “展示完整的可观测性视图：告警 + 指标 + 日志 + 事件”
• “过去 30 分钟内命名空间 prod 发生了什么？”

前置条件

1. Python 依赖

• Python 3.8+ 及以下包：huaweicloudsdkcce、huaweicloudsdkcore、huaweicloudsdkaom、huaweicloudsdklts
• 首次使用前请运行环境检查（详见验证部分）

2. 凭据配置

• 有效的华为云凭据（AK/SK 模式）
• 安全规则：

- 不得在代码、对话或命令中暴露 AK/SK 值

- 不得使用 echo $HUAWEI_AK 或 echo $HUAWEI_SK 检查凭据

- 使用环境变量：HUAWEI_AK、HUAWEI_SK、HUAWEI_REGION

- 云操作建议使用 IAM 用户而非根账号

- 敏感操作启用 MFA

配置方法（仅支持环境变量）：

export HUAWEI_AK=<your-ak>
export HUAWEI_SK=<your-sk>
export HUAWEI_REGION=cn-north-4

重要安全提示：

• 不得将凭据提交至版本控制系统
• 使用权限最小化的 IAM 用户
• 定期轮换 AK/SK

3. IAM 权限要求

权限不足处理：

1. 当任一命令因 IAM 权限问题失败时，显示所需权限列表
2. 引导用户在 IAM 控制台创建自定义策略并授权
3. 暂停执行，等待用户确认权限已授予

核心工具

所有操作均通过 scripts/huawei-cloud.py 使用 skill action=exec 分发。

告警收集

技能：华为云 CCE 可观测性上下文构建器

版本：0.1.1

分块：2/3

动作列表

事件与指标采集

日志采集

可视化

参数说明

通用参数

告警采集参数

日志采集参数

*针对特定动作为必填项。

指标采集参数

工作流程

1. 记录排查范围：捕获故障时间、region、cluster_id、namespace、workload、pod、node 和用户提供的 alarm_id
2. 设定时间窗口：若时间不明确，默认使用最近 1 小时，并在输出中注明此假设
3. 采集告警：调用 huawei_list_aom_alarms 收集当前及历史告警，再通过 huawei_analyze_aom_alarms 进行去重和严重性分组
4. 采集事件：调用 huawei_get_cce_events 获取按关联对象和原因分组的 Kubernetes 事件
5. 采集指标：调用 Pod/Node TopN 指标工具，识别资源峰值、异常节点和异常 Pod
6. 采集日志：当需要日志证据时，优先使用 huawei_query_aom_logs，必要时补充 huawei_get_recent_logs 或 huawei_get_pod_logs 的 Pod 侧日志
7. 合并输出：将各类信号按时间线合并，输出异常摘要、缺失信息（数据缺口），以及推荐的诊断技能以供交接

完整证据收集工作流详见 references/workflow.md。

输出格式

请参考 references/output-schema.md 查看完整的 JSON 响应结构。

上下文包输出示例：

{
  "summary": "one paragraph context summary",
  "scope": {
    "region": "cn-north-4",
    "cluster_id": "optional",
    "namespace": "optional",
    "workload": "optional",
    "time_window": "optional"
  },
  "signals": {
    "alarms": [],
    "events": [],
    "metrics": [],
    "logs": []
  },
  "timeline": [],
  "gaps": [],
  "next_skill": "huawei-cloud-cce-pod-failure-diagnoser | huawei-cloud-cce-node-failure-diagnoser | huawei-cloud-cce-network-failure-diagnoser | huawei-cloud-cce-root-cause-analyzer"
}

关键输出字段说明：

• summary — 一段话总结所收集的可观测性上下文
• scope — 区域、集群、命名空间、工作负载和时间窗口
• signals — 按类型（告警、事件、指标、日志）分组的已收集证据
• timeline — 合并后的信号时间线，展示事件发生顺序
• gaps — 可能影响诊断准确性的缺失数据
• next_skill — 基于信号分析推荐的后续诊断技能，用于任务交接

风险规则

本技能为严格只读的可观测性采集，禁止任何状态变更操作。

name: Huawei Cloud Cce Observability Context Builder

version: 0.1.1

description: 用于构建华为云 CCE 可观测性上下文的只读技能，支持告警、指标、日志、事件等数据采集，不执行任何变更操作。

summary: 本技能仅用于收集和分析华为云 CCE 集群的可观测性数据，提供故障诊断所需的上下文信息。

安全约束

• 允许自动执行 R1 级别的只读查询：告警、指标、日志、事件、资源清单、只读报告生成
• 禁止任何需要 confirm=true 的操作 —— 不允许执行任何变更类操作
• 永远不持久化 AK/SK、令牌、证书或 kubeconfig
• 日志输出必须进行脱敏处理。若检测到疑似敏感信息，仅描述其位置，绝不复制原始内容
• 图表与报告只能基于授权查询结果生成

关于完整的风险分类，请参阅 references/risk-rules.md。

验证步骤

1. 运行 python3 scripts/huawei-cloud.py huawei_list_aom_alarms region=cn-north-4 cluster_id=<cluster-id> 以验证告警查询连通性
2. 运行 python3 scripts/huawei-cloud.py huawei_get_cce_events region=cn-north-4 cluster_id=<cluster-id> limit=10 以验证事件查询功能
3. 运行 python3 scripts/huawei-cloud.py huawei_get_cce_pod_metrics_topN region=cn-north-4 cluster_id=<cluster-id> namespace=default top_n=5 以验证指标 TopN 查询
4. 在健康命名空间上执行完整上下文构建，确认输出包含有效的 scope、signals、timeline、gaps 和 next_skill 字段
5. 验证输出中未建议任何变更类操作 —— 所有操作应为只读或转交至诊断技能

最佳实践

1. 始终从告警开始：优先使用 huawei_list_aom_alarms 和 huawei_analyze_aom_alarms 检查当前及历史告警 —— 告警是故障最直接的信号来源
2. 尽早定义作用域：在采集任何数据前，记录区域（region）、集群 ID（cluster_id）、命名空间（namespace）、工作负载（workload）、Pod、节点（node）及时间窗口。若时间窗口不明确，缺省采用最近 1 小时，并在输出中标注该假设
3. 使用 TopN 快速发现异常：huawei_get_cce_pod_metrics_topN 和 huawei_get_cce_node_metrics_topN 能高效识别资源峰值，无需遍历全部资源
4. 优先使用 AOM 日志，再补充 Pod 日志：huawei_query_aom_logs 提供结构化日志数据；如需容器侧日志详情，使用 huawei_get_pod_logs 或 huawei_get_recent_logs
5. 沿时间线合并信号：将告警、事件、指标和日志按时间顺序合并，可揭示单一数据类型无法呈现的因果链
6. 显式标记数据缺失：始终在 gaps 字段中标识缺失的数据 —— 这能指导下一诊断技能应收集哪些额外证据
7. 绝不建议变更操作：本技能为只读。涉及扩容、删除、重启、驱逐或漏洞状态变更的操作，应转交至 huawei-cloud-cce-auto-remediation-runner
8. 推荐正确的下一技能：根据信号分析结果，推荐最具体的诊断器 —— Pod 故障 → huawei-cloud-cce-pod-failure-diagnoser，节点问题 → huawei-cloud-cce-node-failure-diagnoser，网络问题 → huawei-cloud-cce-network-failure-diagnoser，跨域问题 → huawei-cloud-cce-root-cause-analyzer

参考文档

注意事项

1. 本技能为严格只读 —— 永不执行任何修复操作。如需变更操作，请转交至 huawei-cloud-cce-auto-remediation-runner
2. 所有操作均为 R1 级别（只读）—— 无需 confirm=true
3. 日志片段已脱敏处理 —— 检测到的密码、令牌、AK/SK、Authorization 头部等均在输出中被清除
4. AK/SK 不得硬编码 —— 必须通过环境变量传入
5. Python 调度脚本（scripts/huawei-cloud.py）是唯一合法执行方式 —— 不得使用 hcloud CLI 或直接调用 API
6. 输出中的 next_skill 字段使用 huawei-cloud-cce-* 命名规范，用于跨技能转交
7. 若需在上下文构建前进行告警关联分析，可考虑使用 huawei-cloud-cce-alarm-correlation-engine

常见陷阱