1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | managed-airflow-dag-troubleshooting-google-skills |
| 作者/维护者 | Google（google/skills 官方仓库） |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/managed-airflow-dag-troubleshooting |
| 许可证 | Apache License 2.0（数据来自 GitHub API，仓库级） |
| GitHub Stars | 18,705（合集仓库整体，非本技能独立热度，数据来自 GitHub API） |
| Forks | 1,502（合集仓库整体，数据来自 GitHub API） |
| 最新版本 | 无独立版本号，随仓库主干持续更新；本技能最近一次提交 2026-08-25 |
| 安装方式 | npx skills add google/skills（选择本技能）或手动复制该子目录到 agent 的 skills 目录 |
2. 功能介绍与亮点
本技能面向 Google Cloud 的 Managed Service for Apache Airflow（MSAA，原 Cloud Composer），为失败的 DAG 运行（DAG run）和任务实例（task instance）提供系统化排查方法。
核心流程分三步：① 用 gcloud logging read 抓取相关任务日志，识别 Python 报错堆栈、API 错误码或 Airflow 信号；② 用 gcloud composer environments run 查询 DAG 运行或具体任务的状态与执行元数据；③ 用 gcloud storage cp 下载远程 DAG 源码，与错误信息中的参数逐一比对，定位代码层面的具体问题。
亮点：
- 内置 6 种已知平台级故障模式的现成诊断手册，每种都配有可直接复制执行的
gcloud logging查询语句与对应修复建议：DAG 运行超时、任务排队超时、任务卡在队列、BigQuery 任务失败、僵尸任务（心跳丢失）、Worker 磁盘空间耗尽。 - 全程只做只读诊断（读日志、读状态、读源码），不执行任何修改性操作，误操作风险极低。
- 要求诊断结论必须扎根于实际抓取的日志与元数据，不允许凭空猜测故障原因。
3. 适用场景
所属分类：数据分析与可视化
适用于使用 Google Cloud Managed Service for Apache Airflow（Cloud Composer）编排数据管道的数据工程师与平台运维人员，典型场景包括：定位某次 DAG 运行为何失败、排查某个任务反复超时或卡在队列的根因、以及在 BigQuery 相关任务出错时快速定位是权限问题还是 SQL 本身的问题。
4. 跨 Agent 兼容性
- Claude Code：原生支持——标准 SKILL.md 格式，可直接放入
.claude/skills/或经npx skills add安装。 - Codex：原生支持——
npx skills官方支持列表明确列出 Codex 及专用安装路径。 - OpenClaw：原生支持——同一安装器官方支持列表列出 OpenClaw，并有专用路径
~/.openclaw/skills/。 - Hermes Agent：原生支持——同一安装器官方支持列表列出 Hermes Agent，并有专用路径
~/.hermes/skills/。
（核验依据：npx skills/skills.sh 项目 README 的受支持 agent 列表与路径映射表。）
5. 推荐理由
Apache Airflow 的故障现象五花八门，但很多是平台层面的重复性问题（超时、排队、僵尸任务、存储耗尽），本技能把这些已知模式和对应的日志查询语句直接沉淀了下来，用户不需要从零摸索该查哪条日志、用什么过滤条件，遇到匹配的报错特征可以直接照抄命令定位。诊断流程全程只读，不会因排查动作本身引入新的风险，适合数据工程团队在生产环境中放心使用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 由 Google 官方发布；所属仓库为多技能合集，18,705 星是仓库整体数字，不代表本技能自身热度；未查到该技能自身的独立第三方讨论或采用数据 |
| 可用性 | 9 | 内容详尽（SKILL.md 约 16KB），含完整三阶段诊断流程与 6 种具体故障模式的现成查询语句和修复建议；最近一次提交为 2026-08-25，维护活跃；复制即用，无付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单： ① 执行的 gcloud 命令均为只读操作（读日志、读环境/任务状态、下载源码用于比对），不涉及任何修改性动作 ② 无外部网络外发，全部调用官方 Google Cloud API ③ 使用标准 gcloud 身份认证，不涉及明文凭据存储 ④ 通读全文，未发现可疑指令或隐蔽外发 ⑤ 作者为 Google 官方仓库，信誉最高档 ⑥ 许可证明确（Apache-2.0） ⑦ 最近一次提交 2026-08-25，维护活跃
7. 跟同类 Skills 相比的优势
| 技能 | 平台/范围 | 与本技能的差异 |
|---|---|---|
| airflow-astronomer-agents | Astronomer 官方 Airflow 技能，依赖其自研 af CLI |
面向 Astronomer 自家 Astro 平台，需额外安装 af 命令行工具；本技能直接用 GCP 用户已有的 gcloud 完成全部诊断，无需额外安装 |
| dagster-expert-dagster-io-skills | Dagster 编排框架通用专家技能 | 服务的是 Dagster 而非 Airflow，编排模型与故障排查方式完全不同，两者不可互相替代 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 安装使用方式
- 命令行安装：
npx skills add google/skills，安装时勾选managed-airflow-dag-troubleshooting - 手动安装：将
skills/cloud/managed-airflow-dag-troubleshooting整个目录复制进所用 agent 的 skills 目录（如 Claude Code 的.claude/skills/） - 使用前提：需已启用 Cloud Composer 与 Cloud Logging API，且当前身份具备对目标 Composer 环境的查看权限与相应的日志读取权限
- 安装后无需重启，在对话中描述 DAG 运行失败或任务出错的情况即会触发诊断流程
10. 注意事项
- 仅适用于 Google Cloud 的 Managed Service for Apache Airflow（Cloud Composer），不覆盖自建 Airflow 或其他云厂商的托管 Airflow 服务
- 内置的 6 种故障模式覆盖常见平台级问题，但非平台性质的业务逻辑错误（如 DAG 代码本身的逻辑缺陷）仍需结合下载的源码人工判断
- 技能本身不会自动执行修复，只给出诊断结论与修复建议，具体修复动作需使用者自行决定并执行