alibabacloud-kvstore-health-inspection

硬性规则（违反即刻失败）

核心规则：所有检查都必须通过 python3 scripts/health-inspect.py 执行。 该脚本在内部封装了所有正确的 API 调用。AI 不得直接调用 aliyun CLI 来收集检查数据。

1. 不得调用 aliyun CLI 收集数据：所有检查数据都必须通过 health-inspect.py 获取。AI 不得绕过脚本，直接运行 aliyun r-kvstore。允许 AI 直接调用的 aliyun 命令仅限：aliyun configure list（检查凭证）、aliyun version（检查版本）、aliyun configure set（设置配置）、aliyun plugin（插件管理）
2. 不得使用 CloudMonitor（cms）API：性能监控数据由脚本通过 R-kvstore describe-history-monitor-values API 获取。绝不可使用 aliyun cms describe-metric-list/describe-metric-data 作为替代
3. 不得直接连接 Redis：不得安装 redis-cli 客户端，不得以任何方式连接 Redis 实例，也不得执行任何 Redis 命令
4. 不得执行写操作：不得调用 modify-instance*、create-instance*、delete-instance* 或任何其他会修改实例状态的 API
5. API 调用失败时报告错误：如果脚本在任何步骤失败，都要在报告中标记为“检索失败”。不得尝试通过其他方法获取数据

---

如何使用此技能

用法

你无需手动运行任何脚本！ 这是一项 AI Agent 技能，只需用自然语言描述你的需求即可。

对话示例

示例 1：检查单个实例

Inspect Redis instance r-bp1xxxxxxxxxxxx

示例 2：检查多个实例

Inspect instances r-bp1xxxxxxxxxxxx and r-bp2yyyyyyyyyyyyyy

示例 3：检查整个账号（所有实例）

Inspect all Redis instances in my account

示例 4：指定 Region

Inspect Redis instance r-bp1xxxxxxxxxxxx in cn-hangzhou region

示例 5：使用自定义时间范围检查资源使用情况

Show resource usage for r-bp1xxxxxxxxxxxx in the last 3 days

对应 --days 3

示例 6：仅检查资源使用情况

Show CPU and memory usage for r-bp1xxxxxxxxxxxx

对应 --item resource

示例 7：仅检查慢日志

Analyze recent slow logs for r-bp1xxxxxxxxxxxx

对应 --item slowlog

示例 8：分析大 Key／热 Key

Check for big keys and hot keys in r-bp1xxxxxxxxxxxx

对应 --item bigkey

示例 9：组合检查项

Show slow logs and alert history for r-bp1xxxxxxxxxxxx

对应 --item slowlog --item alert

示例 10：批量检查并指定检查项

Show CPU usage for all instances in the last 3 days

对应 --all --days 3 --item resource

示例 11：指定输出格式

Generate a Markdown report for r-bp1xxxxxxxxxxxx

对应 --format markdown

AI 行为规则（必须遵守）

1. 必须使用脚本进行检查：所有检查操作只能通过 python3 scripts/health-inspect.py 完成。AI 的职责是：识别用户意图 -> 组合正确的脚本参数 -> 执行脚本 -> 向用户呈现报告。不得直接调用 aliyun CLI 收集任何检查数据
2. 检查模式选择：根据用户意图选择正确的执行模式
   • 用户说“所有实例”/“完整账号” -> 使用 --all
   • 用户指定多个实例 ID -> 传入多个 ID：health-inspect.py r-xxx r-yyy
   • 用户指定单个实例 -> 单实例模式：health-inspect.py r-xxx
3. 检查项选择：将用户关注的领域映射到 --item 参数
   • 用户提到“CPU”/“内存”/“资源使用情况”/“连接”/“带宽” -> --item resource
   • 用户提到“会话”/“连接”/“活跃连接”/“客户端 IP” -> --item session
   • 用户提到“大键”/“热键”/“大型键”/“按键统计的内存使用量” -> --item bigkey
   • 用户提到“慢日志”/“慢命令”/“延迟” -> --item slowlog
   • 用户提到“告警”/“警报”/“警告”/“通知” -> --item alert
   • 用户提到多个领域 -> 组合多个 --item（例如：--item resource --item slowlog）
   • 用户未指定（例如：“运行检查”/“完整检查”）-> 不添加 --item，默认执行完整检查
4. 统一输出：多实例（>=2）报告输出到同一个目录，其中包含索引页面（index.html）和各实例的详细报告；单实例输出为单个文件
5. 不要手动列出实例后逐个运行：脚本的 --all 内置实例发现功能。AI 无需先调用 describe-instances
6. 脚本执行失败时：如果脚本在任何步骤报告错误，将错误消息转达给用户。不要调用 aliyun CLI 尝试其他数据获取方式
7. 报告输出后不要追问：此技能仅用于检查。生成报告后，任务即完成。不要追加“需要进一步分析吗？”或任何类似的追问

AI 执行流程（严格按顺序执行）

1. 识别用户意图，选择正确的检查模式和参数
2. 执行 python3 scripts/health-inspect.py <params> —— 一条命令完成所有数据收集
3. 脚本会自动处理：区域发现、用于性能数据的 R-kvstore API 调用、报告生成
4. 向用户提供生成的报告文件路径
5. 根据报告内容回答后续问题

Alibaba Cloud Redis（KVStore）实例健康检查技能

此技能用于检查 Redis 实例的资源使用健康状况，并生成标准化报告。

检查维度（7 个部分）：

1. 实例基本信息 — ID、名称、版本、规格、架构、状态
2. 当前会话 — 连接使用情况分布、节点拓扑
3. 资源使用情况（过去 7 天） — CPU、内存、连接、带宽，以及 ECharts 图表
4. 大 Key / 热 Key — 缓存分析中的 Top10 大 Key 和 Top10 热 Key
5. 慢日志统计（过去 7 天） — 按类型汇总慢命令
6. 告警历史（过去 7 天） — CloudMonitor（CMS）告警记录
7. 检查结论与建议 — 按风险优先级排序的建议

资源指标：

• CPU 使用率、连接使用率、内存使用率
• 输入 / 输出带宽使用率
• 代理指标（仅限集群版 / 读写分离版）
• 持久内存使用率（仅限 Tair）
• 磁盘使用率（仅限 Tair）

架构支持：

• 标准版（单节点、主从）
• 集群版
• 读写分离版（SplitRW）

实例类型支持：

• Redis 社区版
• Tair（DRAM）
• Tair（持久内存，InstanceClass: tair.scm.*）
• Tair（ESSD，InstanceClass: tair.essd.*）

架构： R-kvstore API（DescribeHistoryMonitorValues）+ Aliyun CLI

---

前提条件

运行环境：

• Python >= 3.7
• Aliyun CLI >= 3.3.3
• 操作系统：Linux / macOS / Windows

所需 CLI 工具：

• aliyun CLI >= 3.3.3（已配置有效凭据）
• 无需 redis-cli（此技能通过 API 完成所有检查，无需直接连接 Redis）

Python 依赖：

# Uses only Python standard library: subprocess, json, os, sys, datetime
# All Alibaba Cloud API calls are made through aliyun CLI

安装验证：

安装前检查：Aliyun CLI 必须为 >= 3.3.3 运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 获取详细安装说明， 或运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装 / 更新。 随后【必须】运行 aliyun configure set --auto-plugin-install true，启用自动插件安装。 随后【必须】运行 aliyun plugin update，确保插件为最新版本。

【必须】CLI User-Agent — 每次调用 业务 API aliyun CLI（例如 aliyun r-kvstore …、aliyun das …、aliyun cms …）时，都必须携带 --user-agent 标志，并使用下方可观测性部分定义的完整 UA 模板。系统 / 实用工具命令不得携带 --user-agent（参见可观测性部分的排除列表）。不得依赖已弃用的 aliyun configure ai-mode 机制或 ALIBABA_CLOUD_USER_AGENT 环境变量——二者均已停用。

可观测性（每次调用 aliyun CLI 前必须遵循）

此技能通过 --user-agent 标志，在每条业务 API aliyun CLI 命令中发送可观测性标头。不得使用已弃用的 aliyun configure ai-mode enable / disable / set-user-agent 命令或 ALIBABA_CLOUD_USER_AGENT 环境变量。

适用范围规则（SA-2.11）：

• ✅ 业务 API 命令（携带 --user-agent）：aliyun r-kvstore <action>、aliyun das <action>、aliyun cms <action> 等。
• ❌ 系统 / 实用工具命令（不得携带 --user-agent）：aliyun configure …（例如 aliyun configure list、aliyun configure set）、aliyun plugin …（例如 aliyun plugin update、aliyun plugin install、aliyun plugin list）、aliyun help、aliyun version、aliyun upgrade、aliyun --help。

步骤 1 — 生成会话 ID（每次调用技能时生成一次）

# 32-char lowercase hex without dashes (UUID v4)
export ALICLOUD_SKILL_SESSION_ID="$(uuidgen | tr -d '-' | tr 'A-F' 'a-f')"

步骤 2 — UA 模板（必须使用包含 session-id 片段的完整格式）

AlibabaCloud-Agent-Skills/alibabacloud-kvstore-health-inspection/${ALICLOUD_SKILL_SESSION_ID}

/{session-id} 片段为必填项——不含该片段的 UA 将无法通过 SA-2.11 审核。

步骤 3 — 在每条业务 API aliyun CLI 命令中传递 --user-agent

仅适用于业务产品命令（r-kvstore / das / cms / 等）。上方范围规则中列出的系统命令不得追加 --user-agent。

# ✅ Business API command — UA REQUIRED
aliyun r-kvstore describe-instances \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-kvstore-health-inspection/${ALICLOUD_SKILL_SESSION_ID}"

# ❌ System / utility commands — UA MUST NOT be passed
aliyun configure list
aliyun plugin update
aliyun version

Python 脚本 scripts/health-inspect.py 会自动在每次内部业务 API aliyun 调用中注入此 UA，且绝不会用于系统命令。当 AI 发出直接 CLI 调用时，必须仅在业务 API命令中追加 --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-kvstore-health-inspection/${ALICLOUD_SKILL_SESSION_ID}"，不得在 aliyun configure …、aliyun plugin …、aliyun help、aliyun version、aliyun upgrade 或 aliyun --help 中追加。

不得省略 UA、修改格式或遗漏 /{session-id} 部分。

---

所需 RAM 权限

此技能仅使用只读 API。不需要写入权限。

完整权限策略和详细说明请参阅 references/ram-policies.md。

**[MUST] 权限失败处理：**执行期间，如果任何命令或 API 调用因权限错误而失败，请遵循以下流程：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停并等待用户确认已授予所需权限

---

身份验证

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不要读取、回显或打印 AK/SK 值
• 绝不要要求用户在对话或命令行中直接输入 AK/SK
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否有有效配置文件。

如果不存在有效配置文件，请在此处停止。 指导用户在此会话之外配置凭证。

---

参数参考

参数	必填/可选	说明	默认值
InstanceId	必填（使用 --all 时可省略）	Redis 实例 ID（r-xxx），支持多个	用户必须提供
RegionId	可选	实例地域（未提供时自动发现）	自动发现
Days	可选	检查时间范围（天）	7
Item	可选	指定检查项（可指定多个）；省略则执行完整检查	完整检查
Profile	可选	aliyun CLI 配置文件名称	默认配置文件
Output	可选	报告输出目录或文件路径	~/Downloads/
Format	可选	报告格式：html、markdown、text	html

Item 值：

item	检查内容
resource	CPU/内存/连接/带宽使用趋势（数据节点 + 代理节点）
session	当前会话信息、连接使用情况、源 IP 统计
bigkey	大 Key / 热 Key 分析（超大 Key、大 Key、热 Key、高流量 Key）
slowlog	慢日志统计和命令分析
alert	告警规则配置和告警历史

---

核心工作流

推荐：使用自动化脚本（一键检查）

python3 scripts/health-inspect.py <INSTANCE_ID> [options]

CLI 参数：

参数	简写	说明
INSTANCE_ID	（位置参数）	Redis 实例 ID，支持多个；使用 --all 时可省略
--all		检查当前账户中的所有 Redis 实例
--region	-r	指定 Region（未指定时自动发现）
--days	-d	检查时间范围（天），默认为 7
--item		指定检查项（可多次使用）；省略时执行完整检查。可选项：resource、session、bigkey、slowlog、alert
--profile	-p	指定 aliyun CLI 配置名称
--output	-o	指定报告输出目录或文件路径
--format	-f	报告格式：html（默认）、markdown、text

示例：

# Single instance (auto-discover Region)
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx

# Multi-instance
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx r-bp2yyyyyyyyyyyyyy

# All instances in account
python3 scripts/health-inspect.py --all

# All instances in specific Region
python3 scripts/health-inspect.py --all --region cn-hangzhou

# Custom time range (last 3 days)
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --days 3

# Resource usage only (CPU/memory/connection/bandwidth)
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item resource

# Big key and hot key analysis only
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item bigkey

# Slow logs only
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item slowlog

# Slow logs and alerts only
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item slowlog --item alert

# Batch + specific items
python3 scripts/health-inspect.py --all --item resource --item slowlog

# Markdown format
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --format markdown

# Custom output directory
python3 scripts/health-inspect.py --all -o /tmp/redis_report

# Full parameters
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx -p myprofile -r cn-hangzhou -d 14 -o ./report

脚本会自动完成所有检查步骤。对于多实例运行，报告会输出到同一目录，并附带一个汇总页面（index.html）。

检查项选择示例：

当用户指定特定检查项时，将其意图映射为 --item 参数：

# User says "check CPU and memory" -> resource item
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item resource

# User says "analyze slow commands" -> slowlog item
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item slowlog

# User says "find big keys" -> bigkey item
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item bigkey

# User says "check sessions and connections" -> session item
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item session

# User says "review alerts" -> alert item
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item alert

# User specifies multiple items
python3 scripts/health-inspect.py r-bp1xxxxxxxxxxxx --item resource --item bigkey --item slowlog

当用户未指定检查项时，省略 --item 参数以执行完整检查（全部 7 个部分）。

---

如需手动逐步调用 API 的详细信息，请参阅 references/manual-workflow.md（仅在脚本不可用时使用）。

---

如需报告输出格式模板（文本 + HTML/ECharts 布局规范），请参阅 references/report-format.md（仅在调整报告样式时参考）。

---

参考文档和脚本

• scripts/health-inspect.py — 一键检查主脚本
• scripts/find-instance-region.py — 自动发现实例 Region
• scripts/check-write-operation.sh — 写操作检测钩子
• config/metrics.json — 各架构类型的指标配置
• references/manual-workflow.md — 手动逐步调用 API 的详细信息
• references/report-format.md — 检查报告输出格式规范
• references/ram-policies.md — RAM 权限策略和设置指南
• references/cli-installation-guide.md — Aliyun CLI 安装和配置指南