Data Engineering Agent 任务诊断指南
任务诊断用于定位任务运行失败、超时、结果异常或调度未触发的原因。Data Engineering Agent 可以结合任务配置、运行实例、错误信息、SQL 内容、依赖关系和调度状态，帮助输出根因判断、证据、影响范围和修复建议。
诊断的目标不是简单复述错误信息，而是回答四个问题：
- 为什么失败
- 影响了什么
- 是否需要重跑
- 下一步怎么修复
先探索，再深入排查
任务诊断是最典型的“先探索，再执行”场景之一。
很多时候，用户一开始并不知道：
- 最近一次失败发生在哪个实例
- 是临时执行失败，还是调度运行失败
- 问题出在 SQL、权限、资源、依赖还是数据本身
因此更自然的方式通常不是一开始就要求 Agent 诊断某个具体实例，而是先探索运行状态，再逐步深入。
更适合先探索的起手方式包括：
- 帮我看看这个任务最近一次运行状态怎么样。
- 帮我看看最近 24 小时有没有失败或超时实例。
- 帮我看看这个任务是不是根本没有运行历史。
当运行实例、失败时间和错误摘要已经清楚后，再进入根因诊断会更稳。
适用场景
以下场景适合使用任务诊断：
- 任务运行失败
- 任务长时间运行或超时
- 任务运行成功但结果为空或明显异常
- 任务没有按调度时间触发
- 下游任务没有运行
- 发布后首次运行需要确认状态
- 补数、重跑、下线前需要确认影响范围
如果只是检查任务是否已发布或下一次运行时间，可以先查看任务状态，不必直接进入失败诊断。
监控为空并不等于异常
在新工作空间、测试工作空间或仅创建了草稿但从未运行的空间中，运行监控可能出现以下结果：
- 最近 24 小时无运行实例
- 最近 30 天无运行实例
- 无失败实例
- 无补数任务
这类结果首先应解释为“当前没有运行历史”，而不是产品故障。
遇到空监控时，应先确认：
- 任务是否只是创建草稿但从未执行
- 任务是否从未发布到调度系统
- 查询时间范围是否过短
- 当前工作空间是否主要用于测试或开发
诊断前准备信息
提问时尽量提供以下信息：
| 信息 | 作用 |
|---|---|
| 任务 ID 或任务名称 | 定位任务配置和代码 |
| 运行实例 ID | 定位某一次运行 |
| 执行实例 ID | 定位某一次尝试或重试 |
| 失败时间 | 缩小查询范围 |
| 错误摘要 | 帮助快速分类 |
| 是否已发布 | 判断是否涉及调度系统 |
| 是否有上下游依赖 | 判断影响范围 |
如果不知道实例 ID，可以先让 Agent 查询最近运行历史。
推荐提问：
如果最近 24 小时为空，可以继续：
推荐诊断流程
先确认运行状态
Agent 应先确认任务当前状态：
- 是否运行成功、失败、取消或超时
- 是临时执行还是调度执行
- 是否已发布到调度系统
- 使用哪个 VCluster
- 是否有运行实例和执行实例
- 是否产生下游影响
如果没有运行实例，也应直接说明“当前无实例可诊断”，而不是继续输出泛化的失败分析。
推荐提问：
再做根因分类
常见失败类型包括：
| 类型 | 典型表现 | 常见处理 |
|---|---|---|
| 表不存在 | | 检查 catalog、schema、表名和上游产出 |
| 字段不存在 | | 检查字段名、表结构、SQL 版本 |
| SQL 语法错误 | | 修正 SQL 语法 |
| 权限不足 | | 检查角色和资源权限 |
| 计算集群问题 | VCluster 不可用、资源不足 | 检查集群状态和资源 |
| 调度依赖问题 | 上游未完成、依赖未触发 | 检查上下游关系 |
| 超时 | 运行时间超过限制 | 优化 SQL、增加资源或调整超时 |
| 数据异常 | 成功但结果为空或波动异常 | 检查过滤条件、分区和数据质量 |
诊断报告应明确属于哪一类，不要只返回原始错误。
输出证据
好的诊断报告需要列出证据：
- 错误摘要
- 失败阶段，例如语义分析、权限校验、执行阶段、调度阶段
- 相关 SQL 片段
- 涉及的表、字段、VCluster
- 运行实例和执行实例
- 上下游依赖状态
- 是否已经写入数据
例如，表不存在类错误通常发生在语义分析阶段，SQL 未进入真正执行阶段，通常不会写入业务数据。
判断影响范围
任务失败后，应先判断影响范围，而不是立即重跑。
重点检查：
- 任务是否已发布
- 是否是临时执行
- 是否有下游任务
- 是否已经写入部分数据
- 是否影响业务看板或数据服务
- 是否需要补数
如果是只读临时执行失败，通常不影响业务数据和下游任务。如果是生产调度任务失败，则需要检查下游链路和数据产出时间。
决定是否重跑
不要把重跑当成默认处理方式。
适合重跑的情况：
- 临时资源问题已恢复
- 上游数据已经补齐
- 权限或配置已修复
- SQL 已修正
不适合立即重跑的情况：
- 表名、字段名或 SQL 逻辑仍然错误
- 权限问题未解决
- 上游依赖仍未成功
- 目标表可能已经部分写入，需先确认幂等性
- 失败是预期测试行为
推荐提问：
诊断报告结构
建议要求 Agent 输出固定结构，便于团队排查和沉淀。
示例：表不存在错误
如果 SQL 引用了不存在的表，Agent 应能判断为表不存在类错误。
示例错误：
诊断要点：
- 错误发生在语义分析阶段
- SQL 引用了不存在的表或错误的 catalog / schema
- 如果是只读查询，通常没有写入数据
- 如果任务未发布，通常不会影响调度系统
- 修复前不建议重跑，因为重跑会得到相同结果
修复建议：
- 检查表名、catalog 和 schema 是否正确
- 确认上游任务是否应该先产出该表
- 如果表名变更，更新 SQL 并重新运行
- 如果是权限导致无法访问，应检查角色和授权