RAM 权限诊断与修复

安装要求

前置检查：阿里云 CLI 版本 >= 3.3.3

运行 aliyun version 确认版本。若未安装或版本过低，请运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 更新，或参考 references/cli-installation-guide.md 获取安装说明。

前置检查：阿里云 CLI 插件需更新

[必须] 执行 aliyun configure set --auto-plugin-install true 以启用自动插件安装。

[必须] 执行 aliyun plugin update 确保现有插件始终为最新版本。

在核心工作流的开始阶段（任何 CLI 调用之前）：

[必须] 启用 AI 模式 —— AI 模式是 Agent Skill 执行所必需的。

在执行任何 CLI 命令前，请运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose"

[必须] 在每个退出点禁用 AI 模式 —— 无论因何原因交付最终响应，都必须先禁用 AI 模式。此规则适用于所有退出路径：工作流成功、失败、错误/异常、用户取消、会话结束或其他不再执行后续 CLI 命令的情况。

AI 模式仅用于 Agent Skill 调用场景，技能停止后必须关闭。

aliyun configure ai-mode disable

[必须] CLI User-Agent —— 每次调用 aliyun CLI 命令时，必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose

执行约束：当直接执行 aliyun CLI 命令（而非生成供用户复制的命令）时，始终追加 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose。不要将此标志添加到 Path B 输出或 Path C 控制台指引中显示的命令。

概述

当检测到 RAM 权限错误时，按以下步骤执行：

1. 快速分析 —— 解析原始错误字段（不调用工具），输出简要摘要，并让用户选择分析深度
2. 深度分析 —— （仅当用户选择路径 B 时）必要时解码，执行权限缺口分析，分类根本原因
3. 生成建议 —— 提供最小权限授权方案
4. 执行修复 —— 展示修复选项并等待用户选择

权限等级（L0–L3） 是代理内部的路由状态，由流程中 API 调用结果隐式推断得出。它决定诊断深度和可用修复路径。不得向用户声明或描述该等级。详见 references/diagnose-flow.md 中对各等级的定义。

第一步：快速分析

仅通过解析原始错误字段完成，不调用任何工具，随后由用户决定深入程度。

1a. 从原始错误中提取信息

• error_code：例如 NoPermission、Forbidden、InvalidSecurityToken
• missing_action：例如 ecs:StopInstance
• principal_type：SubUser / AssumedRoleUser / RootUser（来自 AuthPrincipalType）
• principal_display_name：UserId 或 role:session（来自 AuthPrincipalDisplayName）
• no_permission_type：ImplicitDeny 或 ExplicitDeny（来自 NoPermissionType）
• policy_type：例如 AccountLevelIdentityBasedPolicy、AssumeRolePolicy（来自 PolicyType）
• encoded_message：若存在 EncodedDiagnosticMessage，请保留，供第二步使用

1b. 输出简要摘要

基于提取的字段，输出简洁摘要：受影响主体、缺失操作、初步根因推断。

1c. 提供分析深度选择并等待用户确认

展示以下选项，并等待用户选择——在收到选择前不得继续：

• A. 快速路径（推荐场景：ImplicitDeny + 所有关键字段完整 + 常见服务）—— 跳过第二步，仅基于原始字段和内置知识生成建议
• B. 深度路径（推荐场景：ExplicitDeny、字段缺失或服务不熟悉）—— 执行完整的第二步分析，获得更精确结果。

需要两个可选权限：ram:DecodeDiagnosticMessage（解码编码错误）和系统策略 AliyunRAMReadOnlyAccess（权限缺口分析）。缺少这些权限会限制部分功能，但流程仍可继续。

• 跳过 —— 停止诊断，输出手动排查链接

清晰标注推荐选项，并简要说明原因。

若用户选择 A：进入第三步。在建议中注明此为快速分析结果；用户可在任意时刻请求深度分析。

若用户选择 B：进入第二步。

若用户选择跳过：输出错误摘要，提供 RAM 文档链接（https://help.aliyun.com/document_detail/93733.html）和 RAM 控制台链接（https://ram.console.aliyun.com/policies），并说明如何重新启动诊断。

边缘情况 —— ExplicitDeny 强制走路径 A：若 NoPermissionType = ExplicitDeny 但用户仍选择 A，需说明具体拒绝策略无法通过快速分析识别，提供有限建议并明确标注不确定性。

第二步：深度分析

*仅在第一步中用户选择路径 B 时进入。*

首先尝试使用第一步中的原始字段进行分类。DecodeDiagnosticMessage 为补充手段——仅在原始数据不足以自信分类时才调用。

在原始数据不足以确定根因时才解码：例如存在 ExplicitDeny（需 MatchedPolicies）、AccessDeniedDetail 缺失，或 PolicyType 未知。若 NoPermissionType、AuthAction、AuthPrincipalType 和 PolicyType 均存在且指向明确根因，则跳过解码，直接进入下一步。

将原始错误中的 EncodedDiagnosticMessage 内容转录，并调用：

aliyun ram decode-diagnostic-message --encoded-diagnostic-message "<transcribed-value>"

技能：阿里云 RAM 权限诊断

版本：0.0.2

分块：2/2

如果调用返回 EntityNotExist，请重新运行原始失败的命令，并将其输出保存到临时文件中（使用系统临时目录；按命令上下文命名文件，例如 /tmp/aliyun_ecs_stopinstance.txt）。从该文件中提取 EncodedDiagnosticMessage 并尝试解码。若文件中未找到该字段，标记为 L0 并继续。

若需对 SubUser 身份进行用户名解析以执行差距分析，请参考 references/diagnose-flow.md → 身份解析。若解析失败，标记为 L0 并继续。

根本原因类别：

• MissingAction — 身份策略缺少所需操作（最常见）
• ExplicitDeny — 明确拒绝语句阻止了访问（可能来自身份策略或控制策略）
• TrustPolicy — 角色信任策略不允许调用方承担该角色
• STSInsufficient — STS 临时凭证权限不足；根本原因在源角色上
• TokenExpired — STS 令牌已过期
• SLRMissing — 服务关联角色尚未创建
• ResourcePolicy — 资源端策略（如 OSS 存储桶策略）限制了访问

关于触发差距分析的规则及每类根本原因的处理详情，请参阅 references/diagnose-flow.md。

差距分析（当被触发时）：查询当前附加到身份的策略，然后与所需操作进行对比。使用 ListPoliciesForUser（子用户）、ListPoliciesForRole（假设角色用户）或 ListControlPolicies（根用户）。对于自定义策略，使用 GetPolicyVersion 获取策略文档；系统策略则使用内置知识，不调用 GetPolicyVersion。

当权限不足时：若 DecodeDiagnosticMessage 失败（L0）或策略查询失败（L1），向用户说明限制情况，并提供可供 RAM 管理员使用的权限申请材料——两种独立选项：① 申请解码权限（ram:DecodeDiagnosticMessage）作为自定义策略；② 通过系统策略 AliyunRAMReadOnlyAccess 获取 RAM 读取权限（覆盖差距分析）。两者可独立请求，也可同时请求。随后进入第 3 步，无需等待。

第 3 步：生成建议

生成建议前，请检查调用者技能权限提示（参见 references/diagnose-flow.md → 覆盖范围检查）。

知识来源优先级：

1. 内置知识 — 针对常用服务（ECS、OSS、RDS、FC、SLB、VPC、SLS、STS 等），直接使用已知的操作语义。参考 references/hot-services-ram.md。
2. 调用者技能提示 — 若发现 ram-policies.md，可作为补充上下文使用
3. 网络搜索 — 搜索 {产品} RAM 授权 site:help.aliyun.com；优先选择人工维护的文档及包含业务示例的内容，而非自动生成的操作表
4. 系统策略回退 — 推荐使用 AliyunXxxReadOnlyAccess 或 AliyunXxxFullAccess，并注明后续需进一步收紧权限

自定义策略命名：根据服务和任务语义建议名称（例如 ai-agent-ecs-permissions），确认一次后，在本会话中重复使用。

系统策略：直接附加，无需命名。

针对“信任策略”根本原因路径的建议有所不同——请参见 references/diagnose-flow.md → 各类根本原因处理方式。

提出建议后，添加简要说明：当前方案仅为起点，用户可在任意时间请求进一步优化，例如缩小作用范围至特定资源、添加条件，或使用资源级策略（如 OSS 存储桶策略）替代身份级授权。

第 4 步：执行修复

在执行任何写操作前，向用户提供变更摘要及所有可用路径，并等待用户选择路径——在用户选定前不得继续或输出任何命令：

• 目标（用户或角色名称）
• 变更摘要（策略名称、操作内容、撤销方法）
• 路径选项（始终列出当前层级所有可用路径，不可跳过）：

- A. 直接 CLI 执行 — 代理立即运行命令（仅限 L2）

- B. 输出 CLI 命令 — 用户复制并在自身终端运行（所有层级）

- C. 控制台指引 — 提供 RAM 控制台中的分步操作指导（所有层级）

- 跳过 — 不执行

关于写操作前的预查询要求及完整 CLI 命令示例，请参阅 references/ram-cli-commands.md 和 references/diagnose-flow.md。

路径 A：由代理通过 Bash 执行。成功后 → 标记为 L3 确认；报告结果及撤销命令。若出现权限不足 → 自动切换至路径 B。

路径 B 在 L0/L1 时：仅输出增量 Statement JSON，并注明因无法读取现有策略，用户需手动合并。

路径 B 在 L2 时：提供两个子选项：① 仅增量 Statement；② 完整合并后的策略 JSON。

路径 C：提供 RAM 控制台入口链接（https://ram.console.aliyun.com/policies）及在控制台界面完成变更的分步说明。

修复完成后，建议用户重试之前失败的操作。如用户请求，可代为重试。