alibabacloud-finops-inspect

阿里云 FinOps 资源检查技能

⚠️ 强制执行协议 ⚠️

此技能必须且只能通过运行以下命令执行：

python3 scripts/main.py [parameters]

禁止的操作（违反即视为执行无效）：

• ❌ 直接运行 aliyun CLI 命令
• ❌ 编写自定义 bash/python 脚本
• ❌ 在代码中直接调用 SDK API
• ❌ 使用 python3 scripts/main.py 以外的任何执行方式

Agent 必须先向用户确认参数，然后使用适当的标志运行 python3 scripts/main.py。不得例外。

概述

此技能提供了一个预置的 Python 脚本（scripts/main.py），用于对阿里云账号的所有地域执行以成本为导向的健康检查。Agent 的职责仅限于：

1. 将用户意图解析为 CLI 参数
2. 与用户确认参数（HITL）
3. 运行 python3 scripts/main.py [parameters]
4. 将脚本输出作为最终报告呈现

脚本会在内部处理：凭证初始化、地域发现、多产品资源收集、CloudMonitor 指标汇总、判断与建议生成，以及结构化报告输出。Agent 不得复刻任何这些逻辑——只需运行脚本。

注意：下方的工作流部分仅为文档说明脚本的内部实现。Agent 不得使用其中的信息编写自定义代码或直接调用 API。唯一需要执行的操作是运行 python3 scripts/main.py。

功能

此技能实现以下功能：

1. 凭证和地域准备

   • 按优先级加载 AK/SK：环境变量 → Alibaba Cloud CLI 配置 → 运行时提示
   • 调用 ECS API 自动发现账号下所有已启用的地域
   • 允许用户通过 --regions 参数明确指定地域

2. 核心资源利用率检查

   • 检查 ECS 实例 7 天平均 CPU、内存、IOPS 和内网带宽
   • 检查 RDS 实例的 CPU、内存、IOPS、连接数使用率和磁盘使用率
   • 为结果标记三个严重级别：严重闲置 / 利用率低 / 正常
   • 单独识别“已停止但仍在计费”的包年包月 ECS 实例
   • 识别长期运行（>30 天）的后付费实例，并建议切换为包年包月（订阅）计费以节省成本

3. 闲置资源检测

   • 检测未绑定或无流量的弹性公网 IP（EIP）
   • 检测未挂载的数据盘，并根据创建时长提升优先级
   • 检测没有监听器或没有后端服务器的负载均衡器（CLB/ALB/NLB）
   • 检测未绑定 EIP 或没有任何 SNAT/DNAT 规则的公网 NAT 网关

4. 优化建议引擎

   • 将建议分为 P0（立即处理）/ P1（建议处理）/ P2（持续观察）
   • 针对不同资源场景应用差异化建议模板（降配 / 释放 / 切换计费方式 / 转为 Serverless 等）
   • 可选择显示每项资源的预估月度成本

5. 报告输出

   • 结构化文本报告：检查摘要 + 各资源明细表 + 建议摘要 + 错误摘要

重要说明

• 只读保证：
  • 此技能仅调用 Describe* / List* 只读 API，绝不执行 Delete / Stop / Modify 操作。所有建议都包含“请在操作前确认”的警告。
• 操作成本：
  • 此技能本身不会创建实时资源，但会调用大量只读 OpenAPI 接口。在大型账户场景中（数千个实例 × 多个地域 × 多项指标），CloudMonitor 调用量很大——必须内置限流机制，以避免触发 API 限流。
• 凭证安全：
  • AK/SK 仅在内存中使用，绝不会持久化、写入日志或包含在报告中。建议使用遵循最小权限原则的 RAM 子账号运行。
• 内存指标依赖：
  • ECS 内存利用率需要在实例上安装 CloudMonitor Agent（cloudmonitor-agent）。未安装该 Agent 的实例会被标记为“缺少内存数据”，并仅依据 CPU 指标进行判断。
• 观察窗口处理：
  • 最近 7 天内创建的资源会被标记为“观察窗口”，并排除在闲置 / 低利用率判断之外，以避免误报。

前提条件

• 环境：Python 3.10+
• Alibaba Cloud 账号：已开通相关服务（ECS / RDS / VPC / SLB / ALB / NLB / CMS 等）的 Alibaba Cloud 账号
• 访问凭证：正确配置访问凭证。此技能使用 alibabacloud-credentials 凭证链，自动从环境变量或 CLI 配置中读取凭证。配置详情请参阅 在 Python 中管理访问凭证。
• RAM 权限：建议使用遵循最小权限原则且仅包含只读操作的 RAM 策略。关键操作包括：
  • ecs:DescribeRegions / ecs:DescribeInstances / ecs:DescribeDisks
  • rds:DescribeDBInstances
  • vpc:DescribeEipAddresses / vpc:DescribeNatGateways / vpc:DescribeSnatTableEntries / vpc:DescribeForwardTableEntries
  • slb:DescribeLoadBalancers / slb:DescribeLoadBalancerListeners
  • alb:ListLoadBalancers / alb:ListListeners / alb:ListServerGroups / alb:ListServerGroupServers
  • nlb:ListLoadBalancers / nlb:ListListeners / nlb:ListServerGroups
  • cms:DescribeMetricLast / cms:DescribeMetricList

可观测性

此技能发出的所有 Alibaba Cloud API 调用都必须携带 User-Agent 请求头，以便追踪和调试。

User-Agent 模板

AlibabaCloud-Agent-Skills/alibabacloud-finops-inspect/{session-id}

UA 字符串由以 / 分隔的三个部分组成：

部分	值	说明
前缀 + 技能名称	AlibabaCloud-Agent-Skills/alibabacloud-finops-inspect	固定前缀 AlibabaCloud-Agent-Skills 后接技能名称，技能名称必须与此 SKILL.md 前置元数据中的 name 字段完全一致
会话 ID	{session-id}	当前执行会话的唯一标识符

完整 UA 示例：AlibabaCloud-Agent-Skills/alibabacloud-finops-inspect/{session-id}

会话 ID 生成规则

1. 首选来源：从环境变量 SKILL_SESSION_ID 读取（由 Agent 运行时通过 SKILL_SESSION_ID=xxx python3 scripts/main.py 注入）。
2. 回退方案：如果未设置 SKILL_SESSION_ID 或其值为空，则生成 UUID4 十六进制字符串（uuid.uuid4().hex）作为会话 ID。格式为 32 位小写十六进制字符串（例如：a1b2c3d4e5f6789012345678abcdef01）。
3. 不可变性：单次执行过程中，会话 ID 必须保持不变。在进程启动时生成一次，并在后续所有 API 调用中重复使用。
4. 完整性：UA 字符串必须始终包含全部三个部分。不得生成只有两个部分的 UA（即不得省略 session-id）。

实现参考

import os
import uuid

SKILL_NAME = 'alibabacloud-finops-inspect'
SESSION_ID = os.environ.get('SKILL_SESSION_ID', '') or uuid.uuid4().hex

def _build_user_agent() -> str:
    """Build the complete three-segment User-Agent string."""
    return f'AlibabaCloud-Agent-Skills/alibabacloud-finops-inspect/{SESSION_ID}'

创建 SDK 客户端时，通过 Config(user_agent=...) 注入 UA。完整的集成模式请参阅 references/api-calling-patterns.md。

工作流

⚠️ 提醒：以下工作流步骤描述的是 scripts/main.py 的内部逻辑。Agent 不得手动实现这些步骤。Agent 唯一的工作是使用正确的参数运行 python3 scripts/main.py。

强制执行规则

⚠️ 绝对要求 — 请先阅读 ⚠️

唯一有效的执行方式是：python3 scripts/main.py [parameters]

绝不要直接使用 aliyun CLI。绝不要编写自定义脚本。绝不要直接调用 API。 如果执行上述任何操作，执行均无效，且无法通过评估。

1. 单一入口：所有检查任务都必须通过 python3 scripts/main.py 并使用适当的 CLI 参数来执行。Agent 不得：

   • ❌ 直接运行 aliyun ecs/rds/vpc/slb CLI 命令
   • ❌ 编写 bash 脚本（例如 check_idle_resources.sh）
   • ❌ 编写自定义 Python 脚本
   • ❌ 不通过 scripts/main.py 调用 SDK API
   • ❌ 使用 python3 scripts/main.py 以外的任何方法

   正确的执行模式必须始终按顺序包含以下 3 个步骤：

   步骤 A — 从用户请求中解析参数（此时不要执行任何操作）

   步骤 B — HITL 确认（强制要求 — 见下方规则 3）。展示参数并在继续前征求用户确认。

   步骤 C — 仅在用户确认后，执行：

   # Install dependencies (if not already done)
   pip install -r scripts/requirements.txt
   
   # Run the inspection script
   python3 scripts/main.py --regions cn-hangzhou --types ecs --idle-only
   

   ⚠️ 步骤 C 不得早于步骤 B 完成。 如果 Agent 未经用户确认就运行脚本，执行无效。

2. 参数映射：Agent 必须将用户意图映射到正确的 CLI 参数。映射规则如下：

   • 用户指定区域 → --regions <region_list>
   • 用户指定资源类型 → --types <type_list>
   • 用户只想检测闲置资源 → --idle-only
   • 用户只想分析利用率 → --utilization-only
   • 用户指定 CPU 阈值 → --cpu-threshold <value>
   • 用户指定内存阈值 → --memory-threshold <value>
   • 用户指定回溯天数 → --days <value>

   自然语言意图检测（强制关键字到参数规则）：

   • 用户提及以下任一词语时："闲置"、"零连接"、"未使用"、"idle"、"unused"、"unbound"、"zero traffic"、"零流量"、"没有在用" → 必须添加 --idle-only
   • 用户提及以下任一词语时："利用率"、"CPU"、"utilization"、"低负载"、"资源使用率"（且未出现闲置相关关键词）→ 必须添加 --utilization-only
   • 用户提及具体资源类型，例如 "RDS"、"ECS"、"EIP"、"磁盘"、"负载均衡"、"NAT" → 必须添加 --types <matched_types>
   • 用户提及具体区域，例如 "杭州"、"上海"、"cn-hangzhou"、"cn-shanghai" → 必须添加 --regions <region_ids>

   ⚠️ 区域参数规则：如果用户指定了任何区域（通过名称或 ID），Agent 必须始终包含 --regions，并使用准确的区域 ID。常见映射："杭州" / "华东1" = cn-hangzhou、"上海" / "华东2" = cn-shanghai、"北京" / "华北2" = cn-beijing、"深圳" / "华南1" = cn-shenzhen。用户指定区域时运行全区域扫描属于无效操作。

3. HITL 确认检查点（⚠️ 阻断性要求 — 未经确认不得继续执行）：

   此步骤不可跳过。跳过此步骤 = 执行无效 = 失败。

   Agent 必须在运行任何命令前按顺序执行以下操作：

   • 停止 — 尚不运行 pip install 或 python3
   • 展示 — 以结构化列表向用户展示所有已解析的参数
   • 询问 — 明确询问：“是否按这些参数继续？”（或提出等效的确认问题）
   • 等待 — 在用户明确同意前，不执行任何操作

   HITL 交互示例（Agent 必须遵循此模式）：

   Agent: I've parsed your request. Here are the parameters I'll use:
   - Command: python3 scripts/main.py
   - Regions: cn-hangzhou
   - Types: ecs
   - Mode: --utilization-only
   - CPU threshold: 10%
   - Days: 7
   
   Shall I proceed with these parameters?
   
   User: Yes, go ahead.
   
   Agent: [NOW executes pip install + python3 scripts/main.py ...]
   

   此项的重要性：评估系统会检查确认消息是否与任何执行命令位于不同的 Agent 轮次／消息中。Agent 必须单独发送参数确认消息，然后停止并等待用户回复。只有在下一轮（用户确认后），Agent 才应运行 pip install 或 python3。将确认文本与执行命令打包在同一条 Agent 消息／步骤中，会被视为跳过 HITL，并导致失败。

4. 报告结构强制要求：最终报告输出必须严格按顺序包含以下全部四个部分，即使某个部分没有数据也必须包含（使用只有表头的空表格）：

   • INSPECTION SUMMARY（扫描资源总数、发现问题总数）
   • 按资源类型划分的详细信息表（ECS/RDS/EIP/DISK/CLB/ALB/NLB/NAT — 每种类型都必须作为章节标题出现，即使内容为空）
   • RECOMMENDATION SUMMARY（按 P0/P1/P2 分组）
   • ERROR SUMMARY（API 调用失败；如果没有错误，则填写 "None"）

   执行后的报告验证（必须执行）：脚本运行完毕后，Agent 必须：

   • 扫描脚本输出，检查是否包含全部 8 个资源类型标题：ECS DETAILS、RDS DETAILS、EIP DETAILS、DISK DETAILS、CLB DETAILS、ALB DETAILS、NLB DETAILS、NAT DETAILS
   • 如果脚本输出缺少任何标题，Agent 必须手动补上缺失的章节，包括标题和文本 "No issues found."
   • 验证 INSPECTION SUMMARY、RECOMMENDATION SUMMARY 和 ERROR SUMMARY 均已出现
   • 最终答案必须向用户提供完整且已验证的报告

1. 凭据和地域准备

首先，alibabacloud-credentials 凭据链会按以下优先级加载 AK/SK：环境变量 → ~/.aliyun/config.json → 运行时提示。凭据仅保存在内存中。

接下来，调用 DescribeRegions API，获取账户已启用地域的列表。如果用户传入了 --regions，则使用该列表。

多地域并发：不同地域的限流彼此独立，因此该技能默认并发发送 3-5 个跨地域请求，以缩短总执行时间。在单个地域内，请求仍按顺序执行，以避免触发限流。

2. ECS 实例检查

调用 DescribeInstances API，并使用分页（每页 100 条）获取所有 ECS 实例，收集实例 ID、实例类型、计费方式、创建／到期时间、状态等信息。

对于所有 Running 实例，调用 CloudMonitor DescribeMetricLast（命名空间 acs_ecs_dashboard），使用按日聚合（Period=86400）查询近 7 天的以下指标：

• CPUUtilization（CPU 利用率）
• memory_usedutilization（内存利用率，需要 CloudMonitor agent）
• DiskReadIOPS / DiskWriteIOPS（磁盘读／写 IOPS）
• IntranetInRate / IntranetOutRate（内网带宽）

判断逻辑：CPU < 5% 且内存 < 10% 且网络 < 50 Kbps →“严重闲置”；CPU < 10% 或内存 < 20% →“利用率低”。

额外检查：筛选 DescribeInstances 结果中 Status=Stopped 且计费方式为 PrePaid 的实例，并单独列出“已停止但仍在计费”的实例。

计费优化检查：对于利用率正常（非闲置或低利用率）的 Running + PostPaid 实例，检查创建时间。如果实例已运行超过 30 天，则生成一条 P2 建议，建议转换为 PrePaid（包年包月）计费，以节省约 30%-50% 的成本。

3. RDS 实例检查

调用 DescribeDBInstances API 并使用分页（每页 100 条），检索所有处于 Running 状态的 RDS 实例，收集实例 ID、引擎类型／版本、实例规格、计费方式、实例角色等信息。

对于每个实例，调用 DescribeMetricLast（Namespace acs_rds_dashboard）查询 CpuUsage / MemoryUsage / IOPSUsage / ConnectionUsage 指标，并使用 7 天平均值进行判断。

特殊处理：PayType=Serverless 的实例会自动缩容至零，这是正常行为。此类实例不纳入判断，或标记为“Serverless 实例”，而不是视为资源浪费。

计费优化检查：对于利用率正常（非闲置或低利用率）的 Running + Postpaid RDS 实例，检查创建时间。如果实例已运行超过 30 天，则生成一条 P2 建议，建议转换为 PrePaid（订阅）计费方式，以节省约 30%-50% 的成本。

4. 闲置资源检查

4.1 EIP 闲置检测

调用 DescribeEipAddresses API 并使用分页检索所有 EIP。Status=Available 直接判定为“未绑定 EIP”（P0）。对于 Status=InUse 的 EIP，调用 DescribeMetricLast（Namespace acs_vpc_eip，MetricName net_rx.rate / net_tx.rate）查询 7 天流量。流量全为零时，判定为“已绑定但流量为零”（P1）。

4.2 云盘闲置检测

调用 DescribeDisks API，并使用筛选条件 Status=Available AND DiskType=data（仅数据盘，不包括系统盘），通过分页检索所有未挂载的云盘。创建时间超过 30 天的云盘升级为 P0。

4.3 负载均衡闲置检测

CLB / ALB / NLB 使用完全不同的 SDK 和数据结构，因此分别处理：

• CLB：调用 DescribeLoadBalancers 列出实例，然后针对每个实例调用 DescribeLoadBalancerListeners，检索监听器及其后端服务器。没有监听器，或每个监听器的所有后端权重均为零时，判定为闲置。
• ALB：调用 ListLoadBalancers → ListListeners → ListServerGroups → ListServerGroupServers。未绑定服务器组的监听器，或没有后端服务器的服务器组，均判定为闲置。
• NLB：调用 ListLoadBalancers → ListListeners → ListServerGroups。判定逻辑与 ALB 相同。

4.4 NAT 网关闲置检测

调用 DescribeNatGateways 获取公网 NAT 网关（使用 NetworkType 字段排除 VPC 私网 NAT）。检查每个网关绑定的 EIP 列表：

• 未绑定 EIP →“完全闲置”（P0）
• 已绑定 EIP，但 DescribeSnatTableEntries 和 DescribeForwardTableEntries 均返回零条记录 →“缺少配置”（P0）

5. 生成建议并输出报告

将检查器结果汇总到建议引擎中，并按以下标准评级：

• P0 — 立即处理：确定存在浪费（未挂载磁盘超过 30 天、未绑定的 EIP、没有监听器的 LB、没有 EIP 的 NAT）
• P1 — 建议处理：极有可能存在浪费（ECS 的 CPU 连续 7 天低于 5%、RDS 连接数为零、已绑定但流量为零的 EIP）
• P2 — 观察：存在优化空间（ECS 的 CPU 为 5%–10%、仍处于观察期内的资源）

最后，按照以下强制要求的四部分模板生成结构化文本报告：

================================================================================
ALIBABA CLOUD FINOPS RESOURCE INSPECTION REPORT
================================================================================
Generated: <timestamp>
Inspection Period: <start> - <end>
Regions Scanned: <region_list>

--------------------------------------------------------------------------------
INSPECTION SUMMARY
--------------------------------------------------------------------------------
Total Resources Scanned: <count>
Total Issues Found: <count>

Resource Counts:
  ECS: <count>
  RDS: <count>
  EIP: <count>
  DISK: <count>
  CLB: <count>
  ALB: <count>
  NLB: <count>
  NAT: <count>

Issue Counts by Severity:
  P0 - Act Now: <count>
  P1 - Recommended: <count>
  P2 - Observe: <count>

--------------------------------------------------------------------------------
<RESOURCE_TYPE> DETAILS
--------------------------------------------------------------------------------
(One section per resource type, even if empty: "No <type> issues found.")

--------------------------------------------------------------------------------
RECOMMENDATION SUMMARY
--------------------------------------------------------------------------------
(Sorted by priority P0 → P1 → P2, each with "[Please confirm before acting]")

--------------------------------------------------------------------------------
ERROR SUMMARY
--------------------------------------------------------------------------------
(List of API failures, or "None")

================================================================================
END OF REPORT
================================================================================

重要：必须包含所有部分。如果某种资源类型没有问题，请输出该部分的标题，后接“No issues found”。报告中不得包含任何 AK/SK 信息。

6. API 限流和重试策略

• CloudMonitor CMS QPS：约 20–50 QPS — 请求间隔为 50–100 ms
• 限流响应：采用指数退避（1s → 2s → 4s），最多重试 3 次
• 网络超时：最多重试 2 次，并逐步增加超时时间（5s → 10s → 15s）
• 总执行超时时间：10 分钟 — 超时时中止并输出部分结果
• 错误处理：单个 API 调用失败不会中止整体检查；错误将在报告末尾汇总

执行命令（强制入口）

重要：以下命令是执行此技能的唯一有效方式。Agent 必须使用 python3 scripts/main.py 并指定相应标志。禁止编写自定义脚本或直接调用 API。

首先安装依赖项：

pip install -r scripts/requirements.txt

# Full inspection (all regions + all resource types)
python scripts/main.py

# Specify regions
python scripts/main.py --regions cn-hangzhou,cn-shanghai

# Specify resource types
python scripts/main.py --types ecs,rds,eip,disk

# Custom thresholds
python scripts/main.py --cpu-threshold 15 --memory-threshold 25 --days 14

# Idle resources only
python scripts/main.py --idle-only

# Utilization analysis only
python scripts/main.py --utilization-only

参数	默认值	说明
--regions	all regions	以逗号分隔的 Region ID
--types	all types	资源类型：ecs,rds,eip,disk,clb,alb,nlb,nat
--cpu-threshold	10	CPU 低利用率阈值（%）
--memory-threshold	20	内存低利用率阈值（%）
--days	7	监控回溯天数
--idle-only	false	仅检查空闲资源
--utilization-only	false	仅检查利用率

相关文档

• Python SDK 文档
• 在 Python 中管理访问凭证
• ECS 产品
• RDS 产品
• VPC 产品
• SLB（CLB）产品
• ALB 产品
• NLB 产品
• CloudMonitor（CMS）产品