用途
每个 SageMaker 资源都需要一个执行角色（execution role），即 SageMaker 用来从 S3 读取模型产物、从 ECR 拉取服务容器并写入日志的 IAM 角色。许多部署失败正是因为脚本在未检查是否已有可用角色的情况下尝试创建新角色，随后又因调用方是 SSO 主体而报错。本技能编码了正确的顺序：发现、验证、仅在必要时创建。
主要能力
- 验证用户指定的角色是否可用。
- 发现已有角色：列出匹配常见 SageMaker 命名模式（如 AmazonSageMaker-ExecutionRole-、SageMakerExecutionRole 等）的角色，按最近使用日期排序（最近优先），按该顺序校验信任策略，返回第一个可用 ARN。
- 按最近使用排序的原因：在拥有多个角色的账户中，字母序最靠前的角色往往不是正在维护的那个；最近使用的角色更可能拥有当前策略，包括跨账户 ECR 拉取。脚本会打印排序结果，便于查看选中了哪个。
- IAM 经常完全不报告 RoleLastUsed（仅覆盖近期活动）。当所有候选都并列“从未使用”时，脚本回退到最新创建日期——较新的角色比 2021 年的遗留角色更可能拥有当前策略。
- 仅在发现无结果时创建角色。
使用方式
辅助脚本为 Python，可在 Windows、macOS 和 Linux 上一致运行：
python3 scripts/check_role.py # macOS / Linux
python scripts/check_role.py # Windows (PowerShell / cmd)
请在 AWS CLI 已可用的 shell 中运行它们，即 aws sts get-caller-identity 成功的位置。脚本会调用同一个 aws 二进制文件，并继承该 shell 的 profile、region、SSO 会话、代理和凭证链。
Windows / WSL / Git Bash 注意事项：在 Windows 上不要通过 Bash 垫片（WSL、Git Bash、MSYS）调用这些脚本。这些 Bash 环境通常不共享 Windows 的 AWS 配置、凭证、SSO 会话、环境变量或代理设置，因此即使 aws sts get-caller-identity 在 PowerShell 中原生可用，在 Bash 内也会失败。（这正是旧的 .sh 辅助脚本在 Windows 上失败并被替换为 Python 的原因。）如果你在 PowerShell 中，请直接在 PowerShell 中运行 python ...\check_role.py。如果辅助脚本仍看不到你的身份，请在 aws sts get-caller-identity 能返回 ARN 的 shell 中，原生执行同样的发现流程（见下文“原生 AWS CLI 等价命令”）。
操作顺序
第 1 步 — 用户是否提供了角色？
验证该特定角色：
python3 scripts/check_role.py "<role-name-or-arn>"
成功时它将 ARN 打印到 stdout（退出码 0）。失败时在 stderr 记录原因。不要试图静默修复损坏的角色——要把问题暴露出来。
第 2 步 — 发现已有角色
python3 scripts/check_role.py
列出匹配常见 SageMaker 模式的角色（AmazonSageMaker-ExecutionRole-、SageMakerExecutionRole 等），按最近使用日期排序（最近优先），按该顺序校验信任策略，返回第一个可用 ARN。大多数曾使用过 SageMaker 的账户已经拥有一个。
第 3 步 — 仅在发现无结果时创建
如果用户有创建权限（拥有 IAM 权限）：
python3 scripts/create_role.py "<role-name>" "<model-bucket>"
第二个参数将 S3 访问范围限定到特定存储桶。未知时可省略；脚本会警告，用户可稍后更新策略。
如果用户无法创建（SSO 主体——hf-cloud-aws-context-discovery 会标记这一点）：
停止并明确暴露此问题。不要重试其他 IAM 操作期望某个能成功：
我找不到已有的 SageMaker 执行角色，而你通过 SSO 认证，因此无法直接创建。请任选其一：
向你的 AWS 管理员索取 SageMaker 执行角色 ARN，或
让他们为你的 SSO 权限集授予 iam:CreateRole、iam:PutRolePolicy
具体指令能快速解除阻塞；含糊的“权限被拒绝”消息则不能。
“已验证”的含义
角色可用需满足：(1) 存在；(2) 其信任策略允许 sagemaker.amazonaws.com 执行 sts:AssumeRole；(3) 其权限仅授予本次部署所需的操作和资源。规范信任策略见 references/trust-policy.json。
check_role.py 验证存在性和信任，因为策略评估取决于部署的确切 S3、ECR、日志和可选输出资源。部署前，检查所选角色的策略并与 references/minimum-permissions.json 对比；仅添加缺失的操作，并将其范围限定到所需资源。不要附加 AmazonSageMakerFullAccess，也不要将权限审查推迟到 AccessDenied 失败之后。
最小权限
references/minimum-permissions.json 是用于端点执行的独立内联策略：
- 对模型产物存储桶的 s3:GetObject + s3:ListBucket
- ECR 拉取权限
- CloudWatch 日志和指标
create_role.py 安装此内联策略，而不附加托管的 FullAccess 策略。将模板中的 REPLACE_WITH_MODEL_BUCKET 替换为实际存储桶名称——当第二个参数给出存储桶时，create_role.py 会自动完成此操作。对于异步输出或数据捕获等可选功能，请单独添加范围狭窄的权限。
原生 AWS CLI 等价命令（回退方案）
如果 Python 辅助脚本无法运行或看不到你的身份（罕见——通常是 PATH 损坏或在缺少 AWS 上下文的 Bash 垫片下运行），请在 aws sts get-caller-identity 可用的 shell 中手动执行同样的预检。其逻辑只是 AWS CLI 调用；辅助脚本的存在只是为了打包和排序它们。
PowerShell：
# 1. List candidate SageMaker roles
aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json
# 2. For each candidate, confirm the trust policy allows sagemaker.amazonaws.com
aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json
# 3. Prefer the most-recently-used role with SageMaker-execution naming
# (LastUsedDate is often None for every role — then prefer newest CreateDate)
aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text
选择信任策略包含 sagemaker.amazonaws.com 的最近使用角色。使用得到的 ARN，就像 check_role.py 返回它一样。Bash/macOS/Linux 使用相同命令。
适用场景
- 即将创建 SageMaker 端点、模型或训练任务之前。
- 需要确认账户中是否已有可用的 SageMaker 执行角色。
- 需要在 SSO 环境下判断能否创建角色并给出明确指引。
限制
- 仅验证角色存在性和信任策略；权限是否足够需结合部署的具体 S3、ECR、日志等资源另行审查。
- 在 Windows 上不能通过 WSL、Git Bash、MSYS 等 Bash 垫片调用，否则可能因 AWS 上下文不共享而失败。
- 若调用方为 SSO 主体且无创建权限，本技能无法自行创建角色，只能提示用户联系管理员。
- 关于收费、价格、平台支持范围等更多信息，资料中暂未提供。