datalineage-summary

数据血缘摘要

此技能指导 Agent 调查并总结特定焦点资产（表级血缘）或特定字段（列级血缘）的数据血缘图。它以直观的从左到右的方式，展示数据如何进入和离开该资产，并将复杂的节点和链接细节简化为通俗易懂的说明。

归属信息

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，务必阅读 使用归属信息。对于直接在终端中执行的命令（切勿在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:datalineage-summary)"，并在 User-Agent 标头中添加 agent-skills/1.0 (skill:datalineage-summary)。

前提条件

此技能依赖 Google Cloud 上的 数据血缘（Knowledge Catalog）MCP 服务进行图遍历。请确保能够沿上游和下游两个方向运行 search_lineage 查询。有关连接配置和工具架构的详细信息，请参阅 MCP 用法。

工作流逻辑

1. 获取血缘

从焦点沿两个方向（上游和下游）获取血缘图，方法是分别调用 MCP 工具两次：一次使用 "direction": "UPSTREAM"，另一次使用 "direction": "DOWNSTREAM"。

• 位置策略：必须使用 read_url 工具，从提供的 Knowledge Catalog 位置链接动态获取完整的位置列表。为确保不会遗漏跨区域血缘，在填充 locations 数组之前，始终通过此链接确认当前的 Google Cloud 区域列表。必须使用从此链接获取的所有受支持的物理区域来填充 locations 数组。也可以选择使用 bq show 或 gcloud storage ls 来确定资产当前所在的具体区域。

• 搜索参数：调用 search_lineage 时，建议使用 maxDepth = 10、maxResults = 5000 和 maxProcessPerLink = 10 作为稳健的默认值。例如，DOWNSTREAM 调用的格式如下（根据需要扩展 locations 数组）：

  {
    "parent": "projects/project_id/locations/us",
    "locations": [
      "us",
      "us-central1",
      "us-east1",
      "us-west1",
      "europe-west1",
      "asia-northeast1"
    ],
    "rootCriteria": {
      "entities": {
        "entities": [
          {
            "fullyQualifiedName": "bigquery:project.dataset.table"
          }
        ]
      }
    },
    "direction": "DOWNSTREAM",
    "limits": {
      "maxDepth": 10,
      "maxResults": 5000,
      "maxProcessPerLink": 10
    }
  }
  

  确保使用 "direction": "UPSTREAM" 进行类似调用，以获取上游血缘。

• 列级血缘（CLL）：通过配置 field 数组，search_lineage 工具可以查找所有列级血缘（CLL）。如果请求的是表级血缘（TLL），请利用 "*" 通配符配置调用，以同时获取 CLL 链接和 TLL 链接。例如：

  "rootCriteria": {
    "entities": {
      "entities": [
        {
          "fullyQualifiedName": "bigquery:project.dataset.table",
          "field": [
            "*"
          ]
        }
      ]
    }
  }
  

  如果要评估特定列，请将 "*" 替换为具体的列名（例如 "efficiency_score"）。

2. 生成摘要

请根据以下提示词指南生成摘要。

• 角色设定：扮演一名专业的数据血缘分析师，生成简洁、易懂的从左到右的数据流说明。
• 结构与流程：直接以摘要正文开头，并按以下结构组织：
  • 整体流程类型：说明推断出的工作流类型和数据领域（例如：“这似乎是一个特征工程工作流……”）。
  • 系统概览：开头列出涉及的主要系统。如果请求的是列级血缘，必须开头明确声明分析范围仅限于指定字段。
  • 上游血缘：使用确切的粗体标题 **Upstream Lineage:**。叙述数据如何到达焦点资产，并提及关键源系统、项目和处理任务（例如，Dataproc 上的 Spark）。
  • 下游血缘：使用确切的粗体标题 **Downstream Lineage:**。详细说明数据如何从焦点资产流向最终使用方系统。
  • 分析元数据：展示 API 调用使用的参数，以便说明摘要的范围。输出必须包含：
    • 查询位置：{list_of_locations_queried}
    • 父级位置：{parent_path}
    • 深度限制：{maxDepth}
    • 每条链路的流程数限制：{maxProcessPerLink}
    • 用户提示：提示用户可以要求扩大查询位置范围（如果尚未查询所有位置）或增加深度限制。
• 粒度限制：
  • 优先描述系统、项目和数据集之间的流转，而非单个文件或表。
  • 如果资产少于 5 个，必须明确列出具体资产名称（例如源表、中间视图和使用方表）。资产少于 5 个时，不要只概述数量。否则，如果资产数为 5 个或更多，则按数量汇总（例如“5 个 Cloud Storage 存储桶”）。
  • 仅提及终极数据源、最终使用方和资产总数。
  • 如果只涉及一个项目，不要在每个数据集名称后重复项目名称。
• 语气：避免使用行话和“存在不同的事实点”之类的泛泛表述。表达直接、清晰。最终输出使用 Markdown。

3. 返回摘要

将最终摘要返回给用户。

外部文档

• Knowledge Catalog 数据血缘文档
• 使用 Data Lineage MCP 服务
• Knowledge Catalog 数据血缘 API 参考