analyzing-release-readiness

Name: analyzing-release-readiness
Author: aws

github.com/aws测试与质量3.3k1.5k 次安装今天更新

代码仓库

关于 analyzing-release-readiness

通过 AWS DevOps Agent 对代码变更进行发布就绪审查的技能，面向需要评估发布风险的团队。它处理 GitHub PR、GitLab MR 或本地分支，并可选择静态分析或包含自动化测试的完整分析。

主要功能

01审查代码风险、正确性与回滚问题
02解析 GitHub PR 与 GitLab MR 信息
03支持本地分支审查工作流
04选择静态分析或自动化测试
05轮询任务并展示审查进展

适用场景

01发布前评估代码变更风险
02检查 PR 或 MR 的发布就绪情况
03审查尚未创建 PR 或 MR 的本地变更

MCP 相关

该技能调用 AWS DevOps Agent 的发布就绪审查、任务状态、日志记录和报告工具。若所需远程服务工具不可用，说明中指定使用 aws-mcp 回退路径。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aws/agent-toolkit-for-aws --skill analyzing-release-readiness

安装后在 Claude Code 中输入/analyzing-release-readiness确认已加载。

详细介绍

发布就绪情况审查

AgentSpace 路由（仅限 SigV4）： 如果工具列表中有 list_agent_spaces，且本会话尚未调用多空间编排技能，请先调用该技能以确定要使用的 agent_space_id。然后在下面的所有工具调用中传入 agent_space_id。对于 Bearer 令牌身份验证，无需这样做——令牌已限定在一个空间内。

通过 AWS DevOps Agent 执行发布就绪情况审查。分析代码变更的风险、正确性和潜在回滚问题，并返回包含可操作发现的结构化报告。

规则：

如果提供了 PR/MR URL：从 URL 中提取所有字段。不要检查本地工作区或 Git 状态。
绝不要使用 gh CLI、glab CLI 或任何外部工具获取 PR/MR 详情。 所有必需字段（repository、prNumber/mergeRequestIid、hostname）都必须直接从 URL 或用户输入中解析。DevOps Agent 会自行获取内容——你只需传入标识符。
只有在用户提及仓库或软件包，但未提供 PR/MR 链接时，才使用本地工作区流程。

收集执行参数

根据用户的请求自动推断所有信息——不要询问可以推断出的参数。

输入来源决策树：

Has the user provided a pull request/merge request link or ID?
├── Yes: github.com PR URL               → use "GitHub PR" flow below
├── Yes: gitlab.com MR URL               → use "GitLab MR" flow below
└── No link provided — repo name only    → use "Local GitHub/GitLab repo" flow below

GitHub PR（github.com URL 或 PR 引用）

解析输入以提取字段——除非无法从输入中确定字段，否则不要尝试联网获取。
repository（必需）：PR URL 中的 owner/repo
以下至少一项为必需：headSha（提交 SHA）、headBranch（分支名称）、prNumber（PR 编号，必须是字符串，例如 "8"，不能是 8）
hostname：从 URL 中提取（例如 github.com 或自托管主机名）
将这些字段作为对象数组传入 create_release_readiness_review 下的 content.githubPrContent（即使只有一个 PR，也必须使用数组）。

示例：

{
  "content": {
    "githubPrContent": [
      {
        "repository": "owner/repo",
        "prNumber": "8",
        "hostname": "github.com"
      }
    ]
  }
}

关键格式规则：githubPrContent 必须是数组（不能是单个对象）。prNumber 必须是字符串（不能是整数）。

GitLab MR（gitlab.com URL）

解析输入以提取字段——除非无法从输入中确定字段，否则不要尝试联网获取。
repository（必需）：MR URL 中的 owner/repo
以下至少一项为必需：headSha（提交 SHA）、headBranch（分支名称）、mergeRequestIid（MR 编号，必须是字符串，例如 "1"，不能是 1）
hostname：从 URL 中提取（例如 gitlab.com 或自托管主机名）
将这些字段作为对象数组传入 create_release_readiness_review 下的 content.gitlabMrContent（即使只有一个 MR，也必须使用数组）。

示例：

{
  "content": {
    "gitlabMrContent": [
      {
        "repository": "namespace/repo",
        "mergeRequestIid": "1",
        "hostname": "gitlab.com"
      }
    ]
  }
}

关键格式规则：gitlabMrContent 必须是数组（不能是单个对象）。mergeRequestIid 必须是字符串（不能是整数）。违反任一规则都会导致任务立即失败，且不生成任何日志记录。

本地 GitHub/GitLab 仓库（未提供 PR/MR URL——仅限本地工作区）

必须遵循：当用户提及仓库或分支但未提供 PR/MR 链接时，必须按顺序执行以下所有步骤。不要走捷径，直接获取远程 URL 和 SHA——审查 Agent 需要从已推送的分支读取内容。跳过推送步骤会导致分析失败或结果不完整。

进入仓库目录：cd 到仓库根目录（例如克隆目录）。如有需要，请询问用户。
确定基准分支：除非用户指定其他分支，否则使用 main。验证远程跟踪分支是否存在：
```
BASE_BRANCH="main"
if ! git show-ref --verify --quiet refs/remotes/origin/$BASE_BRANCH; then
    git fetch origin $BASE_BRANCH
fi
```
如果获取失败（例如出现“couldn't find remote ref”），请让用户指定基准分支并停止。
检查本地变更：运行 git status --short 和 git rev-list --count origin/$BASE_BRANCH..HEAD，确定状态并据此告知用户：
- 工作区干净且无领先提交：告知用户没有新的内容可供分析，然后停止。
- 有未提交的更改（无论是否有尚未推送的提交）：
  - 如果有一个或多个尚未推送的提交（rev-list 计数 >= 1），请告知用户：
    
    "你有未提交的更改和 N 个尚未推送的提交。我会先在这些提交之上提交你的未提交更改，然后将全部 N+1 个提交推送到一个新分支，以供分析。所有更改都会显示为相对于基础分支的单个差异。要继续吗？"
  - 如果没有其他尚未推送的提交（rev-list 计数 = 0），请告知用户：
    
    "我会提交你的未提交更改，并将其推送到一个新分支，以供发布就绪情况审查。要继续吗？"
  - 在用户批准之前，请勿继续。 如果用户拒绝，请停止。
- 工作区干净，但领先于远程分支（rev-list 计数 > 0，没有未提交的更改）：
  - 如果领先超过 1 个提交，请告知用户：
    
    "你有 N 个尚未推送的提交。我会将它们全部推送到一个新分支，以供分析。所有更改都会显示为相对于基础分支的单个差异。要继续吗？"
  - 如果恰好领先 1 个提交，请告知用户：
    
    "我会将你的最新提交推送到一个新分支，以供发布就绪情况审查。要继续吗？"
  - 在用户批准之前，请勿继续。 如果用户拒绝，请停止。

暂存未提交的更改（如果工作目录干净，则跳过此步骤）：

git stash push --include-untracked -m "release-analysis: preserve working changes"

创建审查分支（务必在提交之前执行此操作，这样快照提交就只存在于可丢弃的分支上）：

ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
BRANCH_NAME="feat/release-readiness-review"
git checkout -b $BRANCH_NAME 2>/dev/null || { BRANCH_NAME="feat/release-readiness-review-$(date +%Y%m%d-%H%M%S)"; git checkout -b $BRANCH_NAME; }

应用暂存的更改并在审查分支上提交（如果工作目录原本干净，则跳过此步骤，直接执行步骤 7）：
```
git stash apply
```
暂存之前，检查是否有敏感文件：
```
git status --short | grep -iE '\.(env|pem|key|p12|pfx|credentials|secret)'
```
如果检测到敏感文件，请警告用户并在继续之前征求确认。如果用户拒绝，请中止：
```
git checkout $ORIGINAL_BRANCH && git branch -D $BRANCH_NAME && git stash drop
```
用户确认后（或未发现敏感文件时）：
```
git add -A
git commit -m "chore: snapshot for release readiness review"
```
推送所有尚未推送的提交（需要事先获得用户批准）：如果用户已在步骤 3 中批准推送，则直接继续。否则（例如，流程到达此处时尚未明确征求批准），请在推送前确认：

"我即将把分支 $BRANCH_NAME 推送到 origin。这是一个前置步骤，可以继续吗？" 在用户批准之前，请勿推送。 如果用户拒绝，请中止并跳至步骤 11。

获得批准后（或已在步骤 3 中获得批准时）：
```
git push -u origin HEAD
```
确定仓库标识符和主机名：运行 git remote get-url origin | sed 's|://[^@]*@|://|'，以提取 owner/repo 和主机名。
- GitHub URL（github.com 或自托管）→ 使用 githubPrContent，主机名取自 URL
- GitLab URL（gitlab.com 或自托管）→ 使用 gitlabMrContent，主机名取自 URL
构建内容：将 headBranch 设为 $BRANCH_NAME，将 repository 设为提取到的 owner/repo，并将 hostname 设为步骤 8 中的值。将对象包装在数组中：
- GitHub：{"githubPrContent": [{"repository": "owner/repo", "headBranch": "feat/release-readiness-review", "hostname": "github.com"}]}
- GitLab：{"gitlabMrContent": [{"repository": "namespace/repo", "headBranch": "feat/release-readiness-review", "hostname": "gitlab.com"}]}
告知用户：告诉用户创建并推送了哪个分支，然后继续执行下面的核心工作流。

分析完成后：清理并恢复工作状态：

git checkout $ORIGINAL_BRANCH
git push origin --delete $BRANCH_NAME 2>/dev/null || true
git branch -D $BRANCH_NAME 2>/dev/null || true

如果执行了步骤 4（未提交的更改已暂存），还需运行：

git stash pop

重要：请勿创建 PR/MR——只需推送分支。发布就绪情况审查 Agent 会直接读取该分支。

核心工作流

严格按顺序执行：以下步骤已编号。你必须完成每个步骤后才能进入下一步。特别是，步骤 1（自动化测试提示）必须等到上方的“收集执行参数”流程全部完成后才能进行——所有 Git 操作均已完成、本地流程中的分支已推送、内容对象已构建，并且已告知用户分支信息。只有此时才能继续步骤 1。

1. 确定 `skip_automated_testing`（仅在内容准备就绪后询问）

skip_automated_testing 参数用于控制 Agent 是运行自动化测试（自动验证测试），还是仅运行静态分析。

值	行为
`true`	跳过自动化测试，仅运行静态分析（速度快——代码审查、风险评估、依赖项检查）
`false`	进行完整分析，包括自动化测试（耗时较长——启动测试环境、构建代码并运行自动验证测试）

向用户提供选项并等待回复：

“你希望进行快速静态分析（代码审查、风险评估、依赖项检查），还是进行也包含自动化测试的完整分析？自动化测试会启动测试环境、构建代码并运行自动验证测试——更全面，但耗时更长。”

用户回答前，不得继续。

如果用户说“是”/“包含测试”/“完整分析”/“运行测试” → 使用 skip_automated_testing=false
如果用户说“不”/“仅静态分析”/“跳过测试”/“快速分析”/拒绝 → 使用 skip_automated_testing=true
如果回复含糊（例如“继续吧”“好的”“开始”）→ 询问用户希望选择哪个选项。

2. 检查工具是否可用

确认以下工具可用：aws_devops_agent__create_release_readiness_review、aws_devops_agent__get_task、aws_devops_agent__list_journal_records、aws_devops_agent__get_release_readiness_report。这些工具不会延迟加载或惰性加载——如果它们未出现在工具列表中，就表示不可用。不要通过 ToolSearch 搜索它们。如果缺少任何工具，请跳过本节剩余步骤，改用下方的“回退方案（aws-mcp）”。告知用户：“远程服务不可用——将使用直接 aws-mcp 服务回退方案。”

3. 启动任务

aws_devops_agent__create_release_readiness_review(
    content={...},
    skip_automated_testing=true/false
)
→ {"taskId": "...", "executionId": "...", "status": "started"}

记录响应中的 taskId 和 executionId。

4. 轮询状态

每隔 30 秒调用一次 aws_devops_agent__get_task(task_id=TASK_ID)，直到状态变为 IN_PROGRESS 或终止状态（COMPLETED、FAILED、CANCELED、TIMED_OUT）。

5. 监控直至完成

状态变为 IN_PROGRESS 后，循环轮询进度：

调用 aws_devops_agent__list_journal_records(execution_id=EXEC_ID, order="ASC") 获取新发现。
向用户展示每条记录，并附上友好的进度更新。
后续轮询时使用响应中的 next_token，仅获取新记录。
每次轮询间隔 15 秒。
定期检查 aws_devops_agent__get_task(task_id=TASK_ID)——状态变为终止状态时停止。

6. 呈现结果

当任务达到终止状态后：

如果状态为 COMPLETED：
1. 调用 aws_devops_agent__get_release_readiness_report(execution_id=EXEC_ID) 获取完整报告。
2. 将报告内容写入 Markdown 文件：
```
release-readiness-review-<YYYY-MM-DD-HHmmss>.md
```
3. 告知用户报告已保存，并提供文件路径。
4. 自动修复流程（必须执行）：保存报告后，必须尝试为所有可操作风险生成并呈现修复方案——这是评审工作流的主要价值，不是可选步骤。
  - 首先，在当前工作区中查找经过分析的代码仓库：
    1. 运行 ls 列出工作区中可用的目录。
    2. 按仓库名称匹配（owner/repo 或 namespace/repo 的最后一段）。例如，testgroupadthiru/repo1updated → 查找名为 repo1updated 的目录。
    3. 如果找到一个匹配项，请向用户确认：“我找到了 <match>——这是 <namespace/repo> 的正确本地副本吗？”
    4. 如果找到多个匹配项，请询问用户哪个是正确的。
    5. 如果没有明显匹配项，请询问用户：“我找不到与 <repo-name> 匹配的本地目录。它是否以其他名称保存在本地，或者我只展示建议的修复方案？”
  - 如果在本地找到：
    - 验证分支：运行 git -C <repo-directory> branch --show-current，确认当前位于预期分支。如果不在预期分支上，请先切换到正确的分支。
    - 扫描相关代码，并解读报告中的风险和问题。然后告知用户：
      
      “报告指出了 N 个可操作问题。我可以在你的本地代码仓库中生成修复，并将其推送到新分支 feat/release-readiness-fix。是否继续？”
    - 未经用户批准，不得继续。 如果用户拒绝，请停止。
    - 获得批准后，生成修复。然后：
```
cd <repo-directory>
git checkout -b feat/release-readiness-fix 2>/dev/null || { git checkout -b "feat/release-readiness-fix-$(date +%Y%m%d-%H%M%S)"; }
# 应用修复
git add -A
git commit -m "fix: Address issues identified by release readiness review"
```
    - 推送前再次验证分支：运行 git branch --show-current，确认显示的是 feat/release-readiness-fix*。如果当前位于其他分支，不要推送。
```
git push -u origin HEAD
```
      告知用户修复了哪些问题、创建了哪个分支，以及修复已推送。
  - 如果未在本地找到：将报告中的建议修复方案整理为具体、可直接应用的代码补丁。使用每个风险的 suggestedFix 字段。将补丁放在代码块中，方便用户直接复制粘贴。逐一说明每项可操作风险，展示准确的修复方案，并指出目标文件和行号。
  - 如果报告中没有风险或问题：告知用户分析已完成，且没有发现可操作的问题。
如果状态为 FAILED 或 TIMED_OUT：呈现错误信息并建议后续步骤。
如果状态为 CANCELED：告知用户任务已取消，且没有可用报告。

取消任务

aws_devops_agent__cancel_release_readiness_review(task_id=TASK_ID)

错误处理

如果状态为 FAILED 或 TIMED_OUT，请停止并呈现错误。如果任务很快失败（在前一两次轮询内），调用 aws_devops_agent__list_associations()，检查目标代码仓库的托管服务（GitHub/GitLab 主机名）是否已与 Agent 空间关联。
如果任务在 5 分钟内未达到 IN_PROGRESS，请使用 cancel_release_readiness_review 取消任务。
如果遇到限流（429 或 ThrottlingException），等待 30 秒后重试，最多重试 3 次。
如果错误不符合上述任何已知模式，请向用户呈现原始错误输出。

回退方案（aws-mcp）

如果 aws-devops-agent 远程服务不可用，请直接使用 AWS CLI：

告知用户：“远程服务不可用 — 正在使用 aws-mcp 服务作为回退方案。”

1. 选择 Agent Space

列出可用的 Agent Space：

aws devops-agent list-agent-spaces --region us-east-1

向用户展示列表，并询问他们想使用哪个 Agent Space。**在用户选择之前，不要继续。**在后续所有调用中，将选定的 agentSpaceId 用作 SPACE_ID。

2. 启动作业

aws devops-agent create-backlog-task \
  --agent-space-id SPACE_ID \
  --task-type RELEASE_READINESS_REVIEW \
  --title 'Release Readiness Review' \
  --priority MEDIUM \
  --description '{\"agentInput\": {\"content\": <CONTENT_JSON>, \"metadata\": {\"skipAutomatedTesting\": true}}}' \
  --region us-east-1

重要： content 值必须是单个对象，不能用列表包装。正确示例："content": {"githubPrContent": [...]}。错误示例："content": [{"githubPrContent": [...]}]。用列表包装会导致后端发生 Pydantic 验证失败。content 中的所有值都应为字符串格式，例如，PR 编号应为字符串。

默认值为 "skipAutomatedTesting": true（仅静态检查）。只有在用户明确选择自动化测试时，才将其设为 false。

3. 轮询状态

aws devops-agent get-backlog-task \
  --agent-space-id SPACE_ID \
  --task-id TASK_ID \
  --region us-east-1

每 30 秒 轮询一次，直到状态变为 IN_PROGRESS 或终态（COMPLETED、FAILED、CANCELED、TIMED_OUT）。

4. 持续监控直至完成