testing-mwaa-workflow

测试 MWAA 工作流

AWS MCP 服务（可选，但建议使用）： 通过 AWS MCP 服务运行此技能中的 AWS CLI 命令，可实现沙盒执行和审计日志记录。这里的每条命令也都可通过普通 AWS CLI 运行，因此此技能不依赖 MCP 服务或任何仅限 MCP 的工具。

端到端测试 Amazon MWAA 工作流的执行：触发一次运行，轮询直至进入终止状态；如果失败，则执行有上限的“调试 -> 修复 -> 重测”循环。此技能只触发运行并读取状态；所有诊断都交由 debugging-mwaa-workflow 处理，所有变更（编辑构件、重新部署、创建/更新环境）都交由 authoring-mwaa-workflow 处理。先按类型分流，再运行一套共享流程。

执行说明 — 分步轮询： 每当等待 AWS 操作达到终止或就绪状态时，每次调用只发出 一次状态检查，并在自己的循环中决定是否再次检查。无论操作类型或耗时多久，都不要让单个命令或脚本阻塞等待（不要使用 while+sleep 直到完成）。

防护措施 — 此技能自身的文件存放位置（MCP 与本地安装）

此技能可以通过两种方式加载，而这两种方式会从不同位置解析技能自带的文件。读取参考文件前，先确定此技能的加载方式：

• 通过 AWS MCP retrieve_skill 工具加载： 此技能未安装在本地文件系统中。必须使用 retrieve_skill 并通过 file 参数获取每个参考文件（例如 file="references/provisioned-testing.md"），然后读取返回的内容。不要在本地对这些路径使用 file_read——它们在磁盘上不存在。
• 本地安装（例如 .kiro/skills/testing-mwaa-workflow/ 或 ~/.claude/skills/testing-mwaa-workflow/）：使用相对路径从本地技能目录读取文件。

此区别仅适用于技能自带的文件。用户数据和会话构件始终从用户的工作目录读取并写入该目录。切勿通过 retrieve_skill 获取或写入客户数据。

步骤 0：检测类型、模式和复杂度

类型（沿用调试技能的逻辑）

1. 可通过 aws mwaa get-environment 解析的环境名称 -> Provisioned。
2. workflow/... ARN 或任何 aws mwaa-serverless 上下文 -> Serverless。
3. 两种信号都没有 -> 询问：**MWAA Provisioned（Python DAG）**还是 MWAA Serverless（YAML 工作流）？

调用模式

• 独立调用 — 用户指定一个现有且已部署的目标。
• 委派调用 — authoring-mwaa-workflow 已完成部署，并移交已解析的目标（环境名称 + dag_id，或工作流 ARN）。“现在部署并测试？”的审批仅满足首次触发确认的要求。

复杂度

• 简单 — 目标已部署且已知就绪 -> 跳至步骤 2。
• 标准 — 刚完成部署，就绪状态未知 -> 执行完整流程。
• 复杂 — 在正在进行的修复循环中重测。

步骤 1：就绪检查（首次触发前）

确认制品已部署且可解析。不要盲目触发。即使你计划采用现有运行，也必须执行此步骤——就绪数据（last_parsed_time、is_active、has_import_errors）会用于步骤 2 的新鲜度检查。

• **已预置：**确认存在 dag_id 且 has_import_errors: false，然后通过 /dags 集合端点执行版本感知的就绪检查。根据环境配置的扫描间隔确定轮询时长：检查 get-environment -> AirflowConfigurationOptions 中的 scheduler.dag_dir_list_interval（AF2）或 dag_processor.refresh_interval（AF3）。如果未设置，默认使用 300s。以 15s 为间隔轮询，最长不超过该间隔 + 30s（按 DAG 查询的端点可能有延迟）。在 AF2（REST API v1） 中，要求 is_active: true。在 AF3（REST API v2） 中，不存在 is_active 字段——应改为要求 is_stale: false，绝不要等待 is_active（它会一直显示为缺失/false）。已解析但尚未就绪的 DAG 会在尝试触发时返回含糊的 RestApiClientException。未能及时就绪 -> 转交给 debugging-mwaa-workflow。
• **无服务器：**确认 WorkflowStatus 为 READY（通过 get-workflow --workflow-arn）。尚未就绪 -> 转交给 debugging-mwaa-workflow。

此就绪等待时长与步骤 3 的运行超时相互独立。准确命令请参阅 references/provisioned-testing.md 和 references/serverless-testing.md。

步骤 2：确认后再触发（安全门）

说明解析出的目标并判定其环境类型。除非你确定目标是开发/测试环境（名称或标签明确表明是开发/测试），否则应视为生产环境：发出生产环境警告，并要求用户明确确认后再触发。如果已确认目标为生产环境（名称或标签中包含 prod、prd 或 production，或用户明确说明是生产环境），则每个会改变状态的步骤都必须获得明确批准——每次触发、重新触发和清除/重新运行都需要，而非只批准一次。对于你确定属于开发/测试环境的目标，首次触发和每次重新触发前都必须获得用户明确确认。

如果用户已明确批准该操作，则此安全门视为已满足：在委派模式下，编写阶段的“现在部署并测试？”批准涵盖首次触发；明确预先授权触发特定运行也视为已确认——已获批准时不要再次询问。

触发前，检查调度器创建的运行（参阅预置环境测试参考文档）。采用任何先前运行前，先执行新鲜度检查：

• **委派模式：**始终触发新的运行。先前运行必定早于部署——无论其状态如何，都不要采用。
• **独立模式：**将 run.start_date 与步骤 1 就绪检查已获取的 /dags 集合响应中的 dag.last_parsed_time 进行比较（v1 和 v2 中，集合响应都会返回每个 DAG 的 last_parsed_time——无需单独调用 DAG 端点）。如果 start_date < last_parsed_time，该运行测试的是先前版本的制品——视为过时，并触发新的运行。只采用 start_date >= last_parsed_time 的运行。

对于通过安全门且未过时的新运行：如果目标时间段已有运行，则采用该运行，而不是发送 POST 请求。通过步骤 3 进行监控。

重新测试时，所有运行标识符都必须是新的（已预置：dag_run_id 和 logical_date 都必须是新的；无服务器：重新调用 start-workflow-run）。重新触发前，确认所有先前运行都已进入终止状态——仍在运行的先前运行可能会阻止新运行启动。

准确的触发命令和重新测试规范请参阅参考文档。

步骤 3：轮询至终态

持续轮询已触发的运行，直至其达到终态。有关确切的轮询命令和错误回退方案，请参阅参考资料。

超时处理：

• **已预置且设置了 dagrun_timeout：**如果已过时间超过 dagrun_timeout，而运行仍未进入终态，则视为失败 -> 步骤 4。 （dagrun_timeout 是 DAG 级别的 Airflow 参数，不适用于 MWAA Serverless。）
• **Serverless：**持续轮询，直到服务返回终态——无需设置调用方上限，因为 MWAA Serverless 服务会强制执行自身的运行时长上限，并将其显示为 TIMEOUT 终态。
• 已预置但未设置 dagrun_timeout：DAG 级别或服务级别均无截止时间，因此请在轮询前与用户商定最长等待时间（他们了解 DAG 的预期运行时长；如果他们没有偏好，默认设为 1h）。轮询直至进入终态或达到最长等待时间。达到上限时，停止轮询并报告——不要悄悄将其标记为失败，也不要无限期继续轮询：

  运行 <run-id> 在商定的 <max-wait> 内尚未进入终态。它可能仍在运行——我没有将其判定为失败。请选择： (a) 延长等待时间，（b）检查日志 / Airflow UI，或（c）将此测试视为无法得出结论。

轮询间隔随已过时间调整：

已过时间	轮询间隔
<= 5 min	15s
> 5-15 min	30s
> 15-30 min	60s
> 30-60 min	2 min
> 60 min	5 min

通过 = 仅限终态 SUCCESS；不检查输出数据。通过后 -> 步骤 6。

步骤 4：失败时，委派调试

将运行标识符交给 debugging-mwaa-workflow。它会返回标准结构（根本原因 / 影响 / 立即修复 / 预防 / 命令）。此处不要重新诊断。

步骤 5：分类修复并循环

5a. 对每项操作将调试返回结果分类到以下类别之一：

类别	示例	处理方式
ARTIFACT	运算符参数错误、缺少导入、YAML 架构/timedelta 错误、任务连线错误、Serverless 代码包修复（缺少依赖/平台不匹配的 wheel/zip 布局错误）	委派给 authoring-mwaa-workflow：重新生成合规构件（对于 Serverless，还要重建/重新部署 --code 包），然后重新部署。自动继续。
ENVIRONMENT	requirements.txt 依赖、plugins.zip、环境配置/工作进程规格	委派给 authoring 的部署流程（负责环境变更及其自身的审批）。通过该审批关卡后自动继续。
HUMAN-GATED	新 IAM 权限、VPC/网络配置、缺少数据资产、提高配额	无法自动应用。提供准确命令，暂停循环，并等待用户确认问题已解决后再进行任何重测。

测试过程绝不直接修改任何内容。

5b. 重新测试。 应用可自动修复类别的修复并重新部署后，循环 回到步骤 1（重新部署会触发新的 S3 同步/解析）-> 步骤 2（重新确认） -> 步骤 3。应用步骤 2 中的重新触发注意事项：使用新的 dag_run_id 和 logical_date，并在新触发前确认上一次运行已进入终态（而不只是仍在 退避重试）。

5c. 同一周期内存在混合操作项时（并行处理）。 启动可自动修复的 修复（通过 authoring 重新生成 + 重新部署），同时提供需要人工处理的项目； 不要完全串行处理。两项防护措施：(1) 只有在两项都完成后才能重测—— 自动修复已重新部署且用户已确认人工处理项完成后，才可重新触发；(2) 如果 自动修复依赖某个人工处理项（重新生成的构件引用了用户必须先创建的 资源/权限），则应按顺序处理，而非并行。

5d. 循环上限和停止条件。 上限计算的是无进展的尝试次数，而非 原始尝试总数——默认值为 3（可覆盖为“最多重试 N 次”）。将进展 定义为以下任一情况：之前失败的任务现在达到 SUCCESS（流水线向前推进），或 调试报告的根本原因与上一次尝试不同。取得进展的尝试会重置计数器——多任务 流水线每次运行消除一个阻塞因素也属于推进，而僵硬的原始次数上限可能会在修复 过程中途放弃任务。出现以下任一情况时停止并总结：(1) 运行达到 SUCCESS -> 步骤 6 通过；(2) 无进展计数器达到上限；(3) 出现 HUMAN-GATED 项 -> 暂停并等待用户。连续两次运行出现相同根本原因时， 每次各计为一次无进展——这表示计数器递增，而不是一条独立规则。

步骤 6：报告

Test Result: PASS | FAIL | STOPPED (<reason>)
Target: <env-name + dag_id | workflow ARN>  [PROD WARNING if applicable]
Attempts: <n>/<cap>
Run History:
  Attempt 1: <run_id> -> <state> (<duration>) [-> root cause if failed]
Fixes Applied: <artifact/env fixes auto-applied via authoring, per attempt> | none
Outstanding Action Items: <human-gated items, exact commands> | none
Next Step: <re-invoke to retest after resolving | passed, nothing needed>

通过要求终态为 SUCCESS。STOPPED 表示达到上限/无进展/因人工处理项而暂停， 每种情况都应明确说明。

注意事项

• 刚部署的构件不能立即运行——它必须先从 S3 同步并解析（Provisioned）， 或在创建/更新时经过验证（Serverless）。首次触发前必须执行步骤 1， Simple 情况除外。
• 本技能绝不编辑构件、更改 requirements 或创建/更新环境。这些都由 authoring-mwaa-workflow 负责，并受其审批关卡约束。测试只负责触发（经确认） 和读取状态。
• 只有运行状态为 SUCCESS 才算通过。输出数据的正确性不在范围内。

故障排查

症状	原因	操作
GET /dags 中没有 DAG	S3 同步延迟或导入错误	触发前交由 debugging-mwaa-workflow 处理
--path 被拒绝 / 截断	路径超过 64 个字符（https://docs.aws.amazon.com/cli/latest/reference/mwaa/invoke-rest-api.html）	使用 --query-parameters 轮询集合路径
轮询时出现 RestApiClientException	Web 服务器无法访问	改为查看 DAGProcessing/Scheduler 日志组
dagRuns POST 时出现 RestApiClientException（消息为空）	DAG 尚未就绪——AF2：is_active=false（尚未完成激活）；AF3：is_stale=true（v2 中不存在 is_active）	轮询 /dags 集合，直到就绪（AF2 为 is_active=true / AF3 为 is_stale=false）；不要盲目重试触发
手动运行已创建，但卡在 queued，始终未启动（AF3）	DAG 已暂停——AF3 不会在暂停时执行手动运行（AF2 会执行）	取消暂停（PATCH /dags/<dag_id> {"is_paused": false}）后再触发；在 DAG 以暂停状态部署的升级后，此情况很常见
Serverless get-workflow 状态不是 READY	仍在创建 / 更新，或已失败	等待 READY；如果是 FAILED，则交由调试处理
两次尝试都在运行时出现相同故障	修复未能解决根本原因	无进展时停止；总结情况；不要耗尽重试上限

参考资料

• references/provisioned-testing.md — 精确的 invoke-rest-api 命令（就绪检查、触发、轮询）、64 字符路径限制、重测规范、日志回退方案
• references/serverless-testing.md — 精确的 mwaa-serverless 命令（get-workflow、start-workflow-run、get-workflow-run）、终止状态

安全注意事项

• 会触发真实运行（会更改状态）：每次触发和重新触发都需要明确确认；对于名称中带有 prod 的目标，须先发出警告。
• 不得自主修改：此技能绝不编辑制品、要求或环境，也不会更改 IAM——这些工作会委托给编写流程（该流程有自己的关卡）。需要人工把关的修复会暂停循环，等待用户操作。
• 不得泄露机密：运行和日志检查不得将凭据或连接字符串暴露在输出中。