運用代理程式技能建構資料產品

總覽

本指南說明如何搭配使用 AI 程式碼輔助工具 (例如 Gemini 和 Antigravity 代理開發架構)，運用 GitHub 存放區中 Cortex Framework 直接提供的專業代理技能，建構符合 Cortex Framework 最佳做法的自訂資料產品。

Cortex Framework 提供專用代理技能來擴充功能，讓 AI 助理引導您建構資料產品，並遵循 Cortex Framework 最佳做法。有了這些功能，您就能以自然語言，根據特定業務需求要求新的資料產品。舉例來說，您可以要求提供應付帳款消耗資料產品，深入瞭解應付總額、逾期金額和營業額。最終成果是根據客戶特定需求和資料建構的 Cortex Framework 資料產品，可完全整合並執行。

服務專員技能

代理技能是輕量級的開放格式，可運用專業知識和工作流程擴充 AI 代理的功能。從本質上來說，技能就是一個資料夾，內含 SKILL.md 檔案 (包含中繼資料和指令)，以及選用的指令碼、參照和資產，可指示代理程式如何執行特定工作。Skills 會將程序知識和情境封裝到可攜式資料夾中，代理程式可依需求載入，提供領域專業知識和可重複的工作流程。Cortex Framework 技能會儲存在 .agent 目錄中。

Cortex Framework 代理程式技能

代理式資料產品建構工具可自動執行 Cortex Framework 內資料產品的端對端開發生命週期。只要指示 AI 輔助工具執行結構化開發工作流程，您就不必手動架構檔案結構、瀏覽複雜的 SAP 結構定義、設定基礎層、管理自訂命名空間，以及編寫樣板 Dataform SQLX 程式碼。

AI 助理會管理下列核心工作：

  • 規劃和需求對應：將具體的業務需求轉換為可執行的資料模型和開發計畫。
  • 即時結構定義查詢：執行查詢複製的 SAP 資料字典 (DDIC) 資料表的指令碼，提供客戶專屬的內容資訊，例如自訂 Z 欄位。
  • 樣板架構：自動產生所有必要的設定檔、中繼資料，以及 SQLX 或 JavaScript 程式碼構件。
  • 資料品質閘道：執行本機建構、編譯 SQL 程式碼、執行單元和整合測試，以及驗證是否符合命名標準，藉此驗證資料產品。
  • 建立說明文件：自動建立說明文件資產，包括資料產品模組的實體關係 (ER) 圖和主鍵。

運用這些代理能力開發資料產品時，請反覆進行。您可以從初始目標著手，查看代理建議的實作計畫 (包括 ER 圖和結構)，並在過程中要求 AI 助理以對話方式修正邏輯。 代理會加快開發速度，但您仍可全面掌控，在提交至存放區前，先查看並核准所有生成的程式碼。此外，由於這些代理程式指令碼會使用已驗證的憑證在本機執行，因此本質上會遵守現有的 Google Cloud 和 BigQuery 存取限制。

必要條件

使用代理程式技能前，請確認開發環境符合下列需求，以啟用即時結構定義查詢、資料編譯和自動驗證：

  1. Google Cloud SDK (gcloud)： 使用使用者帳戶安裝並驗證 (gcloud) CLI。詳情請參閱部署說明文件

  2. 應用程式預設憑證 (ADC)： 設定本機 ADC 和專案目標，讓本機編譯工具和 pytest 套件可以與 BigQuery 通訊。詳情請參閱「準備預設專案 Google Cloud 」一文。

  3. 複製的 SAP 資料字典 (DDIC) 資料表： 如要讓代理程式執行不區分大小寫的結構定義檢查，並準確驗證欄位長度，請在原始目標 BigQuery 資料集中複製下列 SAP 中繼資料表：

    • DD03L (資料表欄位)
    • DD04T (資料元素文字)
    • DD08L (資料表關係)
    • DD01L (網域)
    • DD07L (網域值 - 選用)
    • DD07T (網域值文字 - 選用)

  4. 本機 Python 環境： 使用 uv 安裝本機依附元件並執行同步工具，確保驗證程式庫和單元測試正常運作。詳情請參閱說明文件。

設定和 IDE 設定

開始前，請參閱偏好的 AI 程式碼輔助工具說明文件，瞭解安裝和設定操作說明 (例如 Antigravity)。

  1. 收集必要的安裝構件，並複製存放區。詳情請參閱「安裝構件」。

  2. 在指定的 AI 程式輔助工具中，開啟複製的 Google Cloud Cortex Framework 原始碼足跡。

Google Cloud Cortex Framework 會透過存放區 .agents/skills/ 目錄中的一組專用技能，公開其代理能力。您可以在多個開發環境中使用這些技能：

  • Antigravity 框架： 啟動時，Antigravity 會自動探索、建立索引及啟用所有工作區技能。無須額外設定。如要驗證，請向 Google 助理下達語音指令：

    你有哪些技能？

  • 在 VSCode 中使用 Gemini Code Assist：

    1. 從 VS Code Marketplace 安裝 Gemini Code Assist 擴充功能。
    2. 開啟 cortex-framework-core 資料夾做為工作區。助理會自動掃描並載入 .agents/skills/ 目錄中的技能。

  • 其他 AI CLI 工具： 在指令提示中，以原生方式參照技能目錄。例如：

    Read the create-data-product skill inside the .agents/skills/ directory and scaffold...

建立自訂資料產品

下列步驟說明結構化開發人員工作流程，如何使用代理程式技能建立自訂資料產品。

步驟 1：提供需求和背景資訊

使用 AI 程式碼助理的對話介面，提供說明特定資料需求的提示。例如：

為應付帳款洞察建立 Cortex Framework 資料產品，目標是 SAP S/4HANA 和 ECC。使用命名空間：custom_finance。主要業務需求是追蹤供應商的應付總金額和逾期金額，並依公司代碼計算應付帳款週轉率。

請注意，您也可以直接在提示中參照現有的需求或規格文件。這些文件 (可以是 Markdown 或其他結構化格式) 可為代理程式提供重要背景資訊，例如：

  • 業務背景和領域：詳細目標、使用者情境和目標消費者。
  • 輸入資料規格：來源資料表清單 (例如 LFA1、BSIK、BSEG、Z...)、版本管理詳細資料 (ECC 與 S/4HANA)、排除規則、自訂欄位等。
  • 轉換邏輯和業務規則：核心對應限制、用戶端篩選 (mandt)、軟刪除 (loekz)、處理付款封鎖指標 (zlspr) 對應，以及對帳規則 (例如排除公司間的供應商交易，避免營收比率失真)。
  • 資料完整性和測試斷言：驗證情境 (例如驗證細微程度的獨特性，並確保最終輸出中未結應付金額的總和與原始來源表格完全相符)。

步驟 2：查看實作計畫

列出需求後，代理程式會使用多項技能 (例如 query-sap-ddic 技能) 查詢原始 BigQuery DDIC 中繼資料表。這樣一來，代理程式就能識別並驗證所需來源資料表，確保欄位型別和關係正確無誤。為確保您的需求完全符合 Cortex Framework 最佳做法，代理程式也可能會叫用其他技能。

在開始實作前，代理會提供簡要的實作計畫供您審查。這項計畫包括已識別的來源資料表、對應，以及資料產品的建議架構結構。請先檢查這項方案，並在確認前要求調整。

步驟 3：產生資料產品

確認實作計畫後，代理會使用 create-data-product 技能架構目錄結構。這項功能可將您新的自訂開發項目與指定自訂命名空間下的核心平台更新項目隔離：

src/data_modules/<custom_namespace>/products/<dataproductname>/
├── manifest.yaml
├── table_settings.default.yaml
├── README.md
├── definitions/
│   └── [ecc|s4]/
│       └── <product_name>.js
└── annotations/
    └── [ecc|s4]/
        └── <product_name>.yaml

如要進一步瞭解資料夾結構和個別檔案，請參閱「擴充性指南」說明文件。

在這個階段，您也可以要求代理程式使用 generate-er-diagram 技能自動呈現關係，或使用 create-python-tests 技能搭建斷言。

步驟 4：執行品質閘並驗證資料

視獲派的權限而定，代理程式會自動執行下列必要驗證閘道，或提示您執行。在整個過程中，代理程式會產生詳細的狀態報告，方便您查看結果：

  1. 建構驗證：執行 uv run cortex-build --config config/config.yaml，確保所有生成的 SQL 模型都能順利編譯，並產生建構摘要。
  2. Pytest 執行：執行整套 Python 單元測試，輸出測試執行報表，驗證核心商業邏輯和斷言。
  3. Linter 和稽核：運用 validate-data-product 技能執行嚴格的欄位同位檢查，並驗證命名慣例是否符合規定，最後提供詳細的準備就緒報告。

步驟 5：部署及執行

審查驗證報告並核准產生的程式碼後，即可部署資料產品資產。

  • 部署資產：在本機執行部署指令碼 (例如 uv run cortex-deploy --config config/config.yaml)，將已編譯的資料產品定義推送至已設定的 Dataform 工作區。
  • 實現資料：完成最終的部署後工作流程，執行產生的 Dataform 管道，直接在 BigQuery 中實現新資料表和檢視區塊。
  • 提供洞察資訊：自訂資料產品具體化後，即可連結至下游分析應用程式 (例如 Gemini Enterprise)，針對原始業務問題提供智慧且可執行的答案。

更新現有資料產品

自訂資料產品建構完成後，您不必從頭開始修改，您可以運用 update-data-product 技能，逐步新增欄位、調整商業邏輯，或整合全新的來源資料表。例如：

更新我的 custom_finance AP 資料產品。從 LFA1 來源資料表新增付款條件欄位 (ZTERM)，並確保該欄位已正確對應至最終輸出檢視畫面。完成後，請執行建構驗證。

代理程式會找出設定、查詢 BigQuery DDIC 的確切欄位需求、更新 Dataform 程式碼，並執行必要的建構檢查來驗證變更。

最佳做法和限制

  • 結構定義查詢失敗：如果代理程式無法擷取 SAP 中繼資料結構定義，請確認本機應用程式預設憑證 (ADC) 處於啟用狀態，且擁有目標原始資料集的 BigQuery 資料檢視者 IAM 角色。
  • 脈絡限制：如果您要建構的資料產品非常龐大，涉及數十個資料表，代理程式可能會失去脈絡。提供較小的原子指令，擴大成功率 (例如，先指示代理程式建構標題層級的維度，然後在後續的個別提示中新增項目層級的事實)。