alibabacloud-governance-evaluation-report：查询阿里云账号的云治理成熟度检测结果，自动生成治理检测报告。帮助你快速了解账号在安全、稳定、成本、效率、性能五大领域的合规现状，识别高风险项并提供治理建议。

阿里云云治理中心检测报告

通过渐进式下钻工作流，引导用户发现治理风险、聚焦关键问题并采取修复行动。

场景说明

本 Skill 是问题发现与解决向导——不是全面的审计报告生成器。它以渐进式披露漏斗的方式运作：

1. 总览（快速诊断） —— 评分 + 支柱分布 + 关键风险 Top 项 → 引导用户选择方向
2. 支柱分析（聚焦下钻） —— 特定领域内的全部风险，按严重程度控制 → 引导用户到具体条目
3. 详情（深入） —— 单个检查项的完整修复步骤 → 引导用户到相关条目或资源
4. 资源（行动） —— 不合规资源清单，用于定向修复

每一层都聚焦于最重要的信息，并引导用户进入下一层。避免信息过载——保持输出简洁、可操作。

架构：云治理中心 API → CLI（aliyun governance）→ governance_query.py（合并 + 缓存）→ JSON 输出 → Agent 报告

工作原理

数据来源 —— 三个 API 提供全部数据：

1. list-evaluation-metadata —— 检查项定义（名称、描述、支柱、级别、修复建议）
2. list-evaluation-results —— 实际结果（状态、风险、合规率、评分）
3. list-evaluation-metric-details —— 特定检查项的不合规资源详情

处理 —— 脚本（governance_query.py）合并数据源并缓存结果 1 小时。它提供 4 种查询模式：overview、pillar、detail、resources。

输出 —— 结构化 JSON 供 Agent 生成用户友好的报告。报告直接在对话中以格式化文本输出，不写入文件。

前置条件

前置检查：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 确认 >= 3.3.3。若未安装或版本过低，
请使用包管理器，或 references/cli-installation-guide.md 中经过 SHA256 校验的固定版本包。
不要将远程下载的安装脚本直接管道到 shell 执行。
然后 [必须] 运行 aliyun plugin update 确保本地已有插件始终为最新版本。
[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。

aliyun version                                    # >= 3.3.3
aliyun configure set --auto-plugin-install true   # 启用插件自动安装
python3 --version                                 # Python 3.x

可观测性

本 Skill 发起的每次阿里云 API 调用都必须包含完整的

User-Agent 模板：

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

对本 Skill，{SKILL_NAME} 为

alibabacloud-governance-evaluation-report，因此具体形式为：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-governance-evaluation-report/{session-id}

Session ID 规则：

1. 每次会话（一次 Skill 调用）用 uuid.uuid4().hex 生成一个新的 session ID 一次。

它必须是 32 字符的十六进制 UUID v4 值：恰好 32 个小写十六进制字符，无连字符。

1. 该次调用中的每次阿里云 API 调用都复用同一 session ID，

包括直接 CLI 命令、辅助脚本调用、分页和重试。

1. 不要在相关调用之间重新生成 session ID。仅当新的 Skill 调用开始时才生成新的 session ID。
2. 在运行 governance_query.py 之前，将 ALIBABA_CLOUD_AGENT_SESSION_ID 设为该 32 字符十六进制 session ID。脚本会校验并复用所提供的 UUID；当变量缺失时，它每个进程生成一个 32 字符十六进制 UUID v4 并复用。
3. 绝不从账号 ID、凭证、用户数据或其他敏感值派生 session ID。

在运行 governance_query.py 之前，告知用户它会使用其当前 CLI 凭证调用本地

aliyun 可执行文件，并向阿里云云治理中心发送只读查询。脚本强制只读命令白名单，校验所有动态参数，并在每次调用前将解析后的可执行文件和 API 动作打印到 stderr。

鉴权

配置 CLI 鉴权（推荐 OAuth）：

OAuth 模式（推荐）

aliyun configure --mode OAuth

RAM 策略

需要云治理中心读取权限。完整策略见 references/ram-policies.md。

最低必需权限：

• governance:ListEvaluationMetadata
• governance:ListEvaluationResults

或附加系统策略：AliyunGovernanceReadOnlyAccess

参数确认

本 Skill 的用户特定参数极少。以下参数可能需要确认：

验证

使用前验证配置：

测试 CLI 连接

aliyun governance list-evaluation-results \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-governance-evaluation-report/{session-id} \

--cli-query "Results.TotalScore"

测试脚本

export ALIBABA_CLOUD_AGENT_SESSION_ID="{session-id}"

python3 scripts/governance_query.py overview

详细步骤见 [references/verification-method.md](references/verification-method.md)。

---

核心工作流

重要：参数确认 —— 执行任何命令或 API 调用前，
所有用户可自定义的参数（例如 --profile、--category、--id、--keyword、
--max-results 等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

重要：输出格式 —— 报告格式规范仅用于对话输出。
始终直接在聊天消息中以格式化 Markdown 输出报告内容。
不要创建或写入报告文件（例如 .md、.txt、.html）。无需生成文件。

脚本位置：scripts/governance_query.py

全局选项

模式 1：overview —— 整体成熟度报告

使用时机：用户询问账号整体健康状况、成熟度评分，或想要摘要。

python3 scripts/governance_query.py overview
python3 scripts/governance_query.py overview -r Error              # 仅高风险项
python3 scripts/governance_query.py overview -r Error,Warning      # 高 + 中风险
python3 scripts/governance_query.py --refresh overview             # 强制刷新数据

选项：

输出 JSON 字段：

• TotalScore —— 整体成熟度评分（0.0-1.0）
• PillarSummary —— 各支柱统计（已检查 / 有风险计数，始终不过滤）
• RiskDistribution —— 按风险级别计数（始终不过滤）
• RiskyItems —— 有风险的条目，若指定 --risk 则过滤，按严重程度排序
• RiskFilter —— 应用的风险过滤值（仅在使用 --risk 时出现）

报告格式：阅读 references/report-format-overview.md 获取确切的输出格式。

模式 2：pillar —— 支柱特定报告

使用时机：用户询问特定领域（安全、可靠性、成本等）。

python3 scripts/governance_query.py pillar -c <Category> [options]

选项：

类目值：

• Security —— 安全与访问控制
• Reliability —— 可靠性与韧性
• CostOptimization —— 成本优化
• OperationalExcellence —— 运营效率
• Performance —— 性能效率

级别值：Critical、High、Medium、Suggestion

风险值：Error、Warning、Suggestion、None

示例：

安全支柱中的所有风险项

python3 scripts/governance_query.py pillar -c Security --risky

仅 Critical/High 优先级的 Error 和 Warning 项

python3 scripts/governance_query.py pillar -c Security -l Critical,High -r Error,Warning --risky

**输出 JSON 字段**：
- `Category`、`CategoryCN` —— 支柱名称
- `MatchedCount` —— 匹配项数量
- `Items` —— 带状态的检查项列表

**报告格式**：阅读 [references/report-format-pillar.md](references/report-format-pillar.md) 获取确切的输出格式。

---

### 模式 3：`detail` —— 检查项详情

**使用时机**：用户询问特定检查项或如何修复问题。

python3 scripts/governance_query.py detail --id <metric-id>

python3 scripts/governance_query.py detail --keyword <search-term>

**选项**：

| 选项 | 说明 |
|--------|-------------|
| `--id` | 检查项 ID（例如 `apbxftkv5c`） |
| `--keyword` | 按名称 / 描述搜索（多个匹配时显示列表） |

**示例**：

按 ID 查询

python3 scripts/governance_query.py detail --id apbxftkv5c

按关键词搜索

python3 scripts/governance_query.py detail --keyword "MFA"

**输出 JSON 字段**：
- 基本信息：`Id`、`DisplayName`、`Description`、`Category`
- 状态：`Status`、`Risk`、`Compliance`、`NonCompliant`
- `Remediation` —— 修复步骤（Manual/Analysis/QuickFix）

**报告格式**：阅读 [references/report-format-detail.md](references/report-format-detail.md) 获取确切的输出格式。详情格式在需要时也涵盖资源清单。

---

### 模式 4：`resources` —— 不合规资源

**使用时机**：用户想查看哪些具体资源未通过某项检查。

python3 scripts/governance_query.py resources --id <metric-id>

**选项**：

| 选项 | 说明 |
|--------|-------------|
| `--id` | **必填**。检查项 ID |
| `--max-results` | 每页最大结果数（默认：50） |

**示例**：

列出未启用 MFA 的 RAM 用户

python3 scripts/governance_query.py resources --id apbxftkv5c

列出暴露高风险端口的安全组

python3 scripts/governance_query.py resources --id a9g6pv7r5b

**输出 JSON 字段**：
- `MetricId` —— 检查项 ID
- `TotalCount` —— 不合规资源数量
- `Resources[]` —— 资源列表：
  - `ResourceId`、`ResourceName`、`ResourceType`
  - `RegionId`、`ResourceOwnerId`
  - `Classification` —— 风险分类
  - `Properties` —— 资源特定属性

---

模式选择指南

默认：如果用户未指定支柱或检查项，使用 overview。

报告格式选择：确定查询模式后，在生成输出前阅读对应的报告格式参考文件。只读与用户意图匹配的格式文件——不要一次读取所有格式文件。

字段参考

缓存与清理

仅元数据（检查项定义）在本地缓存——结果始终实时获取。

• 缓存位置：~/.governance_cache/metadata.json
• TTL：24 小时（元数据很少变化）
• list-evaluation-results 和 list-evaluation-metric-details 从不缓存

强制刷新元数据缓存

python3 scripts/governance_query.py --refresh overview

手动清除缓存

rm -rf ~/.governance_cache/

最佳实践

1. 聚焦，不要堆砌 —— 每层报告应突出最重要的内容，而非列出一切。阅读对应的报告格式参考以了解数量控制规则
2. 遵循漏斗 —— 从 overview 开始，引导用户到 pillar，再到 detail。除非用户明确要求特定条目，否则不要跳过层级
3. pillar 模式使用 --risky 过滤 —— 调查问题时隐藏合规项以减少噪音
4. 按 Risk + Level 排优先级 —— 优先关注 Error 风险且建议级别为 Critical/High 的项
5. 遵循修复指引 —— 修改资源前用 detail 模式获取可操作的修复步骤
6. 始终引导后续步骤 —— 每份报告都必须基于实际数据以后续指引结尾，帮助用户继续探索
7. 缓存管理 —— 仅元数据被缓存（24 小时 TTL）；结果始终实时。用 --refresh 强制刷新元数据

参考资料