RAM 权限诊断与修复

安装

前置检查：需要 Aliyun CLI >= 3.3.3

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

前置检查：需要更新 Aliyun CLI 插件

[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保已有插件始终为最新版本。

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

[必须] 启用 AI-Mode —— AI-mode 是 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-Mode —— 因任何原因交付最终回复之前，始终先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误 / 异常、用户取消、会话结束，或不再执行 CLI 命令的任何其他场景。

AI-mode 仅用于 Agent Skill 调用场景，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。不要将本标志添加到路径 B 输出或路径 C 控制台指引中向用户展示的命令。

概述

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

  1. 快速分析 —— 解析原始错误字段（无工具调用），输出简要摘要，请用户选择分析深度
  2. 深度分析 —— *仅在用户选择路径 B 时* —— 按需解码，运行差距分析，分类根因
  3. 生成建议 —— 最小权限授权方案
  4. 执行修复 —— 呈现修复选项并等待用户选择

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

步骤 1：快速分析

不做任何工具调用，解析原始错误字段，然后让用户决定深入程度。

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，保留以备步骤 2 使用

1b. 输出简要摘要

基于提取的字段，输出简洁摘要：谁受影响、缺少什么动作、初步根因推断。

1c. 呈现深度选择并等待选择

呈现以下内容并等待用户选择——在做出选择前不要继续：

  • A. 快速路径 *（推荐用于：ImplicitDeny + 所有关键字段齐全 + 常见服务）* —— 跳过步骤 2，直接从原始字段和内置知识生成建议
  • B. 深度路径 *（推荐用于：ExplicitDeny、字段缺失或不熟悉的服务）* —— 运行完整步骤 2 分析以获得更精确结果。
> 需要两个可选权限：ram:DecodeDiagnosticMessage（解码编码错误）和系统策略 AliyunRAMReadOnlyAccess（差距分析）。缺失权限会限制特定能力，但流程继续。
  • 跳过 —— 到此停止；输出手动排查链接

清楚标记推荐选项并简要解释原因。

如果用户选 A：进入步骤 3。在建议中注明它基于快速分析；用户可随时请求深度分析。

如果用户选 B：进入步骤 2。

如果用户选跳过：输出错误摘要、RAM 文档链接（https://help.aliyun.com/document_detail/93733.html）和 RAM 控制台（https://ram.console.aliyun.com/policies），以及如何重启诊断的说明。

边界情况 —— ExplicitDeny 但强制走路径 A：如果 NoPermissionType = ExplicitDeny 而用户仍选 A，说明没有深度分析无法识别具体的 Deny 策略，并提供带明确不确定性说明的有限建议。

步骤 2：深度分析

*仅当用户在步骤 1 选择路径 B 时进入。*

先尝试用步骤 1 的原始字段分类。DecodeDiagnosticMessage 是补充——仅当原始数据不足以有把握地分类时才调用。

当原始数据单独无法解析根因时解码：例如存在 ExplicitDeny（需要 MatchedPolicies）、AccessDeniedDetail 缺失，或 PolicyType 缺失。对于 NoPermissionType、AuthAction、AuthPrincipalType 和 PolicyType 都可用且指向清晰根因的情况，跳过解码直接继续。

从原始错误转写 EncodedDiagnosticMessage 并调用：

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

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

如果差距分析前需要解析 SubUser 身份的 UserName，见 references/diagnose-flow.md → 身份解析。如果解析失败，标记为 L0 并继续。

根因类别：

  • MissingAction —— 身份策略缺少所需 Action（最常见）
  • ExplicitDeny —— Deny 语句阻止访问（可能是身份策略或 CP 管控策略）
  • TrustPolicy —— 角色信任策略不允许调用方扮演该角色
  • STSInsufficient —— STS 临时凭证缺少权限；根因在源 Role 上
  • TokenExpired —— STS token 已过期
  • SLRMissing —— 服务关联角色尚未创建
  • ResourcePolicy —— 资源侧策略（例如 OSS Bucket Policy）限制了访问

差距分析触发规则和各根因处理细节，见 references/diagnose-flow.md。

差距分析（触发时）：查询当前身份附加的策略，然后与所需 Action 比较。用 ListPoliciesForUser（SubUser）、ListPoliciesForRole（AssumedRoleUser）或 ListControlPolicies（RootUser）。对自定义策略，用 GetPolicyVersion 获取策略文档。系统策略：使用内置知识，不要调用 GetPolicyVersion。

权限不足时：如果 DecodeDiagnosticMessage 失败（L0）或策略查询失败（L1），告知用户该限制，并为 RAM 管理员提供即用的权限申请材料——两个独立选项：① 解码权限（ram:DecodeDiagnosticMessage）作为自定义策略；② 通过系统策略 AliyunRAMReadOnlyAccess 获得 RAM 读取权限（覆盖差距分析）。可独立申请其中之一或两者。然后继续步骤 3 而不等待。

步骤 3：生成建议

生成前，检查调用方 Skill 权限提示（见 references/diagnose-flow.md → 覆盖检查）。

知识来源优先级：

  1. 内置知识 —— 对热门服务（ECS、OSS、RDS、FC、SLB、VPC、SLS、STS 等），直接使用已知 Action 语义。参考 references/hot-services-ram.md。
  2. 调用方 Skill 提示 —— 如果找到 ram-policies.md，作为补充上下文使用
  3. Web 搜索 —— 搜索 {product} RAM authorization site:help.aliyun.com；优先带业务示例的人工维护文档而非自动生成的 Action 表
  4. 系统策略兜底 —— 推荐 AliyunXxxReadOnlyAccess 或 AliyunXxxFullAccess，并注明需进一步收窄

自定义策略命名：建议基于服务和任务语义的名称（例如 ai-agent-ecs-permissions），确认一次，在同一会话中复用。

系统策略：用单条命令直接附加，无需命名。

对于 Trust Policy 根因路径，建议不同——见 references/diagnose-flow.md → 各根因处理。

呈现建议后，添加简要说明：当前方案是起点；用户可随时请求进一步细化——例如收窄到特定资源、添加条件，或使用资源级策略（如 OSS bucket policy）而非身份级授予。

步骤 4：执行修复

执行任何写操作前，向用户呈现变更摘要和所有可用路径，然后等待用户选择路径——在用户选择前不要继续或输出任何命令：

  • 目标（用户或角色名）
  • 变更摘要（策略名、动作、撤销方式）
  • 路径选项（始终呈现当前级别可用的所有路径——绝不跳过任何一条）：
  • A. 直接 CLI 执行 —— agent 立即运行命令 *（仅 L2）*
  • B. 输出 CLI 命令 —— 用户在自己的终端复制运行 *（所有级别）*
  • C. 控制台指引 —— 在 RAM 控制台逐步操作 *（所有级别）*
  • 跳过 —— 不执行

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

路径 A：agent 通过 Bash 执行。成功 → 确认 L3；报告结果和撤销命令。NoPermission → 自动切换到路径 B。

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

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

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

修复后，建议用户重试此前失败的操作。如被要求，可代为重试。