alibabacloud-quickbi-smartq

Quick BI-SmartQ — QuickBI データ分析アシスタント

QuickBI のすべてのデータ分析機能を網羅する単一のエントリーポイントです。ユーザーの意図に基づいて対応するモジュールへ自動的に振り分けるため、手動で選択する必要はありません。

対象範囲

できること：

• ユーザーの意図を自動的に特定し、対応するデータ分析モジュールへ振り分けます
• Quick BI API（ファイル Q&A）を介して、ユーザーがアップロードした Excel／CSV ファイルを自然言語で分析します
• Quick BI プラットフォームのデータセットに対する自然言語でのクエリ分析を行い、テーブルを自動でインテリジェントに選択・照合します（データセット Q&A）
• PDF／Word／Excel／CSV／画像を解析してテキストを抽出し、主要なフィールドを抽出して構造化された Excel を作成します（ドキュメント解析）
• QuickBI ダッシュボードをデータクエリスキルに自動変換します（ダッシュボードスキル生成）
• データセットの詳細なインサイト分析を行います（データインサイト）
• 分析結果に基づいて専門的なデータレポートを自動生成します（データレポート）

できないこと：

• Q&A のシナリオで、pandas／openpyxl／csv などのライブラリを使用してファイルをローカルで読み込み、分析すること
• ユーザーにモジュールの手動選択や、cubeId などの内部パラメーターの指定を求めること
• QuickBI のデータ分析に関係のないタスクを実行すること

画像出力ルール（必ずお読みください）

このスキルでは、ユーザーへの主要な成果物としてチャート画像（PNG）を生成します。画像は必ずユーザーに表示してください。画像はこのスキルの主要な出力です。

スクリプトの出力に ![Title](path) 形式の画像参照が含まれている場合、エージェントは次のことを必ず守ってください。

1. 返信本文に、すべての ![Title](path) をそのまま含めてください。ユーザーがチャートを見られる方法はこれだけです
2. Read、showFile、present、またはファイル読み取りツールを使用して、チャートの PNG ファイルを読み込んだり表示したりしてはいけません
3. 1 回の返信で提示 — スクリプトが完全に終了するまで待ってから、画像 → 結論 → 解釈を含む返信を 1 回だけ作成してください。複数回に分けて返信してはいけません
4. 送信前に自己確認 — 送信前に、スクリプトの出力にあるすべての ![...](...) が返信本文に含まれていることを確認してください

チャート画像を提示する方法は、Markdown の画像構文 ![...](...) のみです。

タスクの振り分け

ユーザーの入力に基づいて意図を自動的に判断し、対応するモジュールへ振り分けて実行します。

ルーティング判断表

ユーザーの意図	ルーティング先モジュール	参照ドキュメント
Excel/CSV ファイルをアップロードし、特定の指標の検索や特定のデータに関する質問（例：TOP N、比較、フィルタリング）への回答を求めている	ファイル Q&A	module-chat-file.md
ファイルをアップロードしておらず、プラットフォームのデータセットに含まれる特定の指標の検索・分析を求めている	データセット Q&A	module-chat-dataset.md
複数のファイル（PDF/Word/画像など）をアップロードするか、フォルダーを選択し、特定のデータに関する質問（例：TOP N、比較、フィルタリング）への回答を求めている	ドキュメント解析 → ファイル Q&A	module-document-parser.md → module-chat-file.md
PDF/Word/画像などの非構造化ドキュメントをアップロードするか、フォルダーを選択し、すべてのファイル内容の解析やフィールドの抽出を求めている	ドキュメント解析	module-document-parser.md
QuickBI ダッシュボードの URL を提示し、クエリスキルの生成を求めている	ダッシュボードスキル生成	module-dashboard.md
Excel ファイルをアップロードし、データの詳細な解釈・インサイト・トレンド分析を求めている（レポートドキュメントの生成ではない）	データインサイト	module-data-insight.md
QuickBI ダッシュボード／データポータルの URL を提示し、ダッシュボードの詳細な解釈・インサイト・トレンド分析を求めている	データインサイト（ダッシュボードモード）	module-data-insight.md
複数のファイル（PDF/Word/画像など）をアップロードするか、フォルダーを選択し、データの詳細な解釈・インサイト・トレンド分析を求めている（レポートドキュメントの生成ではない）	ドキュメント解析 → データインサイト	module-document-parser.md → module-data-insight.md
ファイルのアップロード有無を問わず、レポート／分析レポート／レビュー報告書の生成を求めている	データレポート	module-data-report.md

ルーティングの優先順位ルール

ユーザーの意図が複数のモジュールに該当する可能性がある場合は、次の優先順位に従って判断してください。

1. 「レポート」というキーワードを最優先：ユーザーの意図に「レポート」「レビュー」「サマリーレポート」「分析レポート」などのキーワードが含まれる場合、ファイルのアップロード有無にかかわらず、必ずデータレポートモジュールにルーティングしてください。データレポートモジュールは、ファイル Q&A とデータインサイトより優先されます。
2. 「解釈」「インサイト」「トレンド」というキーワード：ユーザーがデータの意味を理解したり、トレンドを見つけたり、インサイトを得たりすることを求めている場合は、データインサイトモジュールにルーティングしてください。
3. 特定データの検索：ユーザーが特定の指標（TOP N、合計、比較など）の検索を求めている場合は、Q&A モジュールにルーティングしてください（ファイルの有無に応じて、データセット Q&A またはファイル Q&A を選択します）。
4. ダッシュボード URL：ユーザーがダッシュボード／データポータルのリンクを提示した場合は、ユーザーの意図に応じてルーティングしてください。
   • クエリスキルの生成を求めている → ダッシュボードスキル生成
   • ダッシュボードの解釈／トレンド分析／異常の特定／インサイトの取得を求めている → データインサイト（ダッシュボードモード）
   • 意図が不明確な場合は、デフォルトでダッシュボードスキル生成にルーティングしてください

ルーティング例

ユーザー入力	ルーティング結果	理由
「このデータの中から、売上が最も高い商品を探してください」＋アップロードされたファイル	→ ファイル Q&A（module-chat-file）	特定の指標を問い合わせており、ファイルがある
「この Excel データを分析して、部門別の従業員数 TOP 10 を教えてください」＋アップロードされたファイル	→ ファイル Q&A（module-chat-file）	特定の指標（TOP N）を問い合わせており、ファイルがある
「売上が最も高い地域をトップ 3 で教えてください」	→ データセット Q&A（module-chat-dataset）	特定の指標を問い合わせており、ファイルがない
「これらの契約書を解析して、情報を要約してください」＋フォルダー	→ ドキュメント解析（module-document-parser）
「このダッシュボードをクエリスキルに変換してください」＋URL	→ ダッシュボードスキル生成（module-dashboard）	ダッシュボードの URL が指定されている
「このダッシュボードの傾向を解釈してください」＋ダッシュボード URL	→ データインサイト（module-data-insight、ダッシュボードモード）	ダッシュボードの URL＋解釈／インサイトの意図
「売上データの傾向を解釈してください」＋アップロードされたファイル	→ データインサイト（module-data-insight）	レポートではなく、解釈／インサイトを求めている
「このデータにパターンやインサイトはありますか」＋アップロードされたファイル	→ データインサイト（module-data-insight）	インサイト分析を求めている
「今月の売上データレポートを作成してください」	→ データレポート（module-data-report）	「レポート」というキーワードを含む
「この Excel をもとに分析レポートを作成してください」＋アップロードされたファイル	→ データレポート（module-data-report）	「レポート」というキーワードを含み、ファイルは参照資料として使用される
「これらのデータを要約して、レビュー報告書を作成してください」＋アップロードされたファイル	→ データレポート（module-data-report）	「レビュー報告書」というキーワードを含む
「これらのファイルをまとめて、データ分析レポートを作成してください」＋アップロードされたファイル	→ データレポート（module-data-report）	「レポート」というキーワードを含む
「これら 10 件の請求書 PDF を解析し、項目を抽出して Excel を作成してください」＋複数のファイル	→ ドキュメント解析（module-document-parser）	「項目を抽出」に関連するキーワードを含む
「このデータの中から、売上が最も高い商品を探してください」＋複数のファイルまたはフォルダー	→ ドキュメント解析 → ファイル Q&A（module-chat-file）	特定の指標を問い合わせており、複数のファイルがある
「これらのファイルにパターンやインサイトはありますか」＋複数のファイルまたはフォルダー	→ ドキュメント解析 → データインサイト（module-data-insight）	インサイト分析を求めている
「これらのデータを要約して、レビュー報告書を作成してください」＋ファイル 5 件以下	→ データレポート（module-data-report）	「レビュー報告書」というキーワードを含む
「これらのデータを要約して、レビュー報告書を作成してください」＋ファイル 5 件超	→ ドキュメント解析 → データレポート（module-data-report）	「レビュー報告書」というキーワードを含む

フォールバックルール

• 意図が不明確な場合は、デフォルトでデータセット Q&A（module-chat-dataset）にルーティングします
• ユーザーが複数のモジュールを同時に使用する場合（例：「データを分析してレポートを作成する」）は、順番に実行します
• 特別なケース — Q&A の前に複数ファイルを前処理する場合：
  • ユーザーが非構造化ドキュメント（PDF／Word／画像など）を 5 件以上アップロードして分析を依頼した場合
  • 必ず最初にドキュメント解析を実行します（構造化された Excel を生成）
  • その後、質問の意図に応じて該当する機能モジュールにルーティングします（生成された Excel をインテリジェントに分析）
  • 例：「これらの請求書データを分析してください」＋PDF 10 件 → ドキュメント解析（Excel を生成）→ ファイル Q&A（Excel を分析）
• ルーティングが誤っている場合、ユーザーがモジュールを手動で指定できます

設定

このスキルでは、ユーザー設定とスキルパッケージを分離する階層型設定アーキテクチャを採用しています。スキルパッケージを更新しても、ユーザー設定は上書きされません。

<workspace-dir> の規則：このドキュメントでは、<workspace-dir> は、ユーザーが IDE またはファイルマネージャーで現在開いているフォルダーの絶対パスを指します。エージェントは最初の操作の前に、os.getenv('CODE_AGENT_CURRENT_SESSION_WORK_DIR') を使って Python スクリプトを実行し、このパスを必ず確認する必要があります。スクリプトが何も返さないか、空の場合は、ユーザーが選択したフォルダーの絶対パスを使用してください。$PWD、$CWD、Path.cwd() などの実行時変数を使って推測してはいけません。

<skill-package-dir> の規則：このドキュメントでは、<skill-package-dir> は、このスキルのインストール後のルートディレクトリ（つまり、この SKILL.md ファイルが含まれるディレクトリ）を指します。エージェントはこのファイルのパスから推測できます。

設定の読み込み優先順位（上位が下位を上書き）

1. 環境変数 ACCESS_TOKEN（最優先。コンテナーへのデプロイに適しています）
2. ワークスペースレベルの設定 <workspace-dir>/.qbi/smartq-chat/config.yaml
3. QBI グローバル設定 ~/.qbi/config.yaml（すべてのスキルで共有）
4. デフォルト設定 スキルパッケージ内の default_config.yaml（パッケージのデフォルト値。パッケージとともに更新されます）

server_domain、api_key、api_secret、user_token は、ワークスペースレベルの設定またはグローバル設定に指定できます。両方に存在する場合は、ワークスペースレベルの設定が優先されます。

設定項目の説明

• server_domain：Quick BI サービスのドメイン
• api_key / api_secret：OpenAPI 認証キーのペア（設定されていない場合、トライアルモードでは組み込みのデフォルト値が使用されます）
• user_token：Quick BI プラットフォームのユーザー ID。Q&A インターフェースでは userId が必要です（設定されていない場合は自動的に登録され、書き戻されます）

use_env_property: true が有効な場合、ACCESS_TOKEN 環境変数の JSON にある qbi_api_key、qbi_api_secret、qbi_server_domain、qbi_user_token の各フィールドを使って設定を上書きできます。

トライアル認証情報の自動登録

api_key と api_secret のどちらも設定されていない場合（user_token の有無は問いません）、スクリプトは次の処理を行います。

1. user_token も設定されていない場合、トライアル認証情報が自動登録され、トライアルモードが開始されることをユーザーにわかりやすく通知します
2. 組み込みのデフォルト認証情報を使用して api_key と api_secret を設定します
3. デバイス固有の識別子に基づいてユーザーを自動登録し、userId をグローバル設定 ~/.qbi/config.yaml に書き込みます（スキルパッケージの更新の影響を受けません）

注：自動トライアル登録によってグローバル設定に user_token だけが存在していても、トライアル認証情報の設定は妨げられません。トライアルのフローがスキップされるのは、外部設定に api_key または api_secret が存在する場合のみです。

トライアルの有効期限は、エラーコード AE0579100004 を通じてサーバー側のインターフェースで管理されます。ローカルでの追跡は不要です。

カスタム設定の手順

トライアル認証情報ではなく、ご自身の Quick BI アカウントの認証情報を使用する場合は、Quick BI コンソールにサインインし、アバターのメニューから**「スキル設定をワンクリックでコピー」**をクリックします。以下を参照してください。

現在のロケールに応じた設定のスクリーンショットをユーザーに表示します。

• zh_CN：
• en_US：

コピーした設定をエージェントに貼り付けます。エージェントは server_domain、api_key、api_secret、user_token をワークスペースレベルの設定 <workspace-dir>/.qbi/smartq-chat/config.yaml に自動的に書き込みます（save_global_property スイッチに応じて、グローバル設定に同期するかどうかを判断します）。

エージェント設定の更新ルール（必読）

新規ユーザー向けのゼロコンフィギュレーション初期化：ユーザーが「設定を初期化してください」「新規ユーザーです」などと伝えていても、特定の設定値を指定していない場合、設定ファイルに手動で書き込む必要はありません。ユーザーにそのままQ&Aを実行するよう案内してください。システムが試用登録を自動的に完了します（上記の試用認証情報の自動登録のセクションを参照）。

以下の書き込みルールを適用するのは、ユーザーが特定の設定値を明示的に指定した場合のみです。

既存設定の保護ルール：書き込み前に、エージェントは必ずワークスペースレベルの設定ファイル <workspace-dir>/.qbi/smartq-chat/config.yaml がすでに存在し、有効な設定を含んでいるかを確認してください。ファイルがすでに存在し、空でない場合、ユーザーが「設定を更新して」「この設定に置き換えて」「api_keyをxxxに変更して」など、更新の意図を明示的に示していない限り、エージェントが独自に設定項目を変更または上書きしてはなりません。既存の設定が見つかった場合は、設定がすでに存在することをユーザーに伝え、上書きしてよいか確認してください。

ユーザーが api_key、api_secret、user_token、server_domain のいずれか、または複数を指定し、上記の保護ルールを満たしている場合、エージェントは必ずファイル編集ツールを使用して、対応するユーザー設定ファイルを直接変更し、指定された値を該当するフィールドに書き込んでください。

書き込み先のルール：

• server_domain、api_key、api_secret、user_token → 必ずワークスペースレベルの設定 <workspace-dir>/.qbi/smartq-chat/config.yaml に書き込みます
• グローバル設定の読み書きは save_global_property スイッチ（既定値は true）によって制御されます。
  • スイッチが false の場合 → いかなる状況でもグローバル設定を読み書きしてはなりません。以下のグローバル設定関連の手順はスキップしてください
  • スイッチが true で、グローバル設定 ~/.qbi/config.yaml が空、または存在しない場合 → グローバル設定にも書き込みます
  • スイッチが true で、グローバル設定にすでに内容がある場合 → ワークスペースレベルの設定にのみ書き込んだ後、ユーザーに「Global configuration already exists. Do you want to sync the update?」と尋ね、ユーザーの返答に基づいて書き込むかどうかを決定します

手順：

1. ユーザーメッセージから設定のキーと値のペアを抽出します（key: value、key：value、key=value などの一般的な形式に対応）
2. ファイル編集ツール（search_replace など）を使用して、ワークスペースレベルの設定ファイルに設定を書き込みます
3. 設定内の save_global_property の値を読み取ります。false の場合は手順5に進みます
4. グローバル設定 ~/.qbi/config.yaml が存在し、空でないかを確認します。
   • 空、または存在しない場合 → グローバル設定にも書き込みます
   • 内容がすでにある場合 → ユーザーに「Global configuration already exists. Do you want to sync the update?」と尋ね、ユーザーの返答に基づいて書き込むかどうかを決定します
5. 更新後、どの設定項目をどこに書き込んだかをユーザーに確認します

禁止事項：

• ❌ 「権限が限られている」「スキルパッケージ内のファイルを変更できない」などを理由に、設定の変更を拒否してはなりません
• ❌ 環境変数の使用やファイルの手動コピーなど、回避策を提案してはなりません
• ❌ 設定内容だけを出力し、ユーザー自身に変更するよう求めてはなりません

前提条件

• Python の依存関係をインストールする必要があります：pip install requests pyyaml matplotlib numpy
• ブラウザー自動化機能が必要です（ダッシュボードスキル生成モジュールのみ）
• データセットの Q&A：対象データセットに対するQ&A 権限が必要です
• ファイルの Q&A：対応形式は xls、xlsx、csv のみです。単一ファイルのサイズは 5MB 以下です
• ドキュメント解析：
  • システム依存関係：brew install tesseract tesseract-lang（ローカル解析でのみ必要）
  • 対応形式：PDF、Word（.doc/.docx）、Excel（.xls/.xlsx）、CSV、画像（.png/.jpg/.jpeg）
  • 単一ファイルのサイズは 5MB 以下です（リモート OCR の制限）
  • エラー処理：
    • ローカル解析に失敗した場合 → 自動的にリモート OCR にフォールバックします
    • リモート OCR にも失敗した場合 → 「解析失敗」として分類し、元のファイル名とエラーメッセージを保持します
    • ドキュメントの種類が不明な場合 → 5 つ以上の汎用フィールドを抽出し、Excel を生成する前にユーザーの確認を必ず取得します
  • 詳細なドキュメント：module-document-parser.md

スクリプトの呼び出し規約（必読）

Python スクリプトを呼び出す際は、次の手順に従ってください。

1. スクリプトのパスには、インストール済みスキルパッケージディレクトリの絶対パス（つまり <skill-package-dir>/scripts/...）を使用する必要があります。相対パスは使用しないでください
2. --workspace-dir パラメーターを使って、<workspace-dir> の絶対パスを必ず渡してください（取得方法については、上記の設定セクションの規約を参照してください）
3. パスパラメーターの値は引用符で囲んでください（中国語の文字、スペース、その他の特殊文字によるシェルのトークン分割を防ぐため）
4. smartq_stream_query.py、file_stream_query.py、q_insights.py、create_chat.py、generate_report.py には、ユーザーのロケール判定ルールを参照し、--locale パラメーターを必ず含めてください

呼び出し例：

# File upload
python '<skill-package-dir>/scripts/chat/upload_file.py' '/path/to/data.xlsx' --workspace-dir '<workspace-dir>'

# File Q&A
python '<skill-package-dir>/scripts/chat/file_stream_query.py' <fileId> "headcount distribution by department" --locale zh_CN --workspace-dir '<workspace-dir>'

# Dataset Q&A
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "TOP 3 regions by sales" --locale zh_CN --workspace-dir '<workspace-dir>'

# Dataset Q&A (with dataset name hint — enables name lookup, exact match skips intelligent table selection)
python '<skill-package-dir>/scripts/chat/smartq_stream_query.py' "Based on 'Order Sales Details', what is the sales share by platform in Q1?" --cube-name 'Order Sales Details' --locale zh_CN --workspace-dir '<workspace-dir>'

# Document Parsing - local
python '<skill-package-dir>/scripts/document/document_local_parse.py' '/path/to/folder/' --json --workspace-dir '<workspace-dir>'

# Document Parsing - remote OCR
python '<skill-package-dir>/scripts/document/document_remote_ocr.py' '/path/to/folder/' --workspace-dir '<workspace-dir>'

# Excel generation
python '<skill-package-dir>/scripts/document/generate_excel.py' '<json-path>' --workspace-dir '<workspace-dir>'

# Data Insight
python '<skill-package-dir>/scripts/insight/q_insights.py' "any anomalies in this report?" --excel-file '/path/to/data.xlsx' --locale zh_CN --workspace-dir '<workspace-dir>'

# Data Insight (Dashboard mode — dashboard URL or data portal URL)
python '<skill-package-dir>/scripts/insight/q_insights.py' "what are the sales trends in this dashboard?" --dashboard-url 'https://bi.aliyun.com/dashboard/view/pc.htm?pageId=xxx' --locale zh_CN --workspace-dir '<workspace-dir>'
python '<skill-package-dir>/scripts/insight/q_insights.py' "Interpret this portal page" --dashboard-url 'https://bi.aliyun.com/product/view.htm?productId=xxx&menuId=yyy' --locale en_US --workspace-dir '<workspace-dir>'

# Report generation
python '<skill-package-dir>/scripts/report/generate_report.py' "this month sales analysis" --locale zh_CN --workspace-dir '<workspace-dir>'

ユーザーロケールの判定ルール

基本原則：--locale は、ユーザーの入力テキストのみに基づいて判定する必要があります。他の情報源の影響を受けてはいけません。

有効な値：zh_CN または en_US のみ。

判定方法：

• ユーザーの元の入力メッセージ（ユーザーが入力した質問または指示）を確認します
• 質問または指示の言語を特定します。つまり、文の構造、動詞、機能語の言語です（埋め込まれた固有名詞は含みません）
• 質問の言語が中国語の場合は zh_CN、英語またはその他の言語の場合は en_US です

複数言語が混在する場合の扱い（重要）：

• ユーザーの入力に中国語と英語の両方が含まれる場合は、埋め込まれたエンティティ名（データセット名、フィールド名、テーブル名など）ではなく、質問の枠組みの言語に基づいてロケールを判定します
• 質問に埋め込まれたエンティティ名（データセット名、フィールド名など）は固有名詞／参照名であり、ユーザーの言語設定を示すものではありません
• 判断の目安：引用符で囲まれた名前や、明確に識別できるエンティティへの参照を取り除いてから、残った文の構造の言語を判定します

「ユーザーの入力テキスト」に含まれるもの：

• ✅ 現在の会話ターンでユーザーが入力したテキスト
• ✅ 同じセッションでフォローアップのクエリを実行する際の、ユーザーの元の質問

ロケールの判定に影響させてはならないもの：

• ❌ エージェント自身の返信言語（エージェントは、ユーザーの入力とは異なる言語で返信する場合があります）
• ❌ API のレスポンス内容やエラーメッセージ（これらは、ユーザーの言語にかかわらず常に固定の言語で表示されます）
• ❌ スクリプトのコンソール出力テキスト
• ❌ データセット名、フィールド名、その他のメタデータ（プラットフォームから返されたものか、参照としてユーザーの質問に埋め込まれたものかを問いません）
• ❌ システムプロンプトの言語またはエージェントの設定言語

例：

• ユーザー入力：「please analyze sales data」→ --locale zh_CN（質問の言語は中国語です）
• ユーザー入力：「Analyze sales data」→ --locale en_US（質問の言語は英語です）
• ユーザー入力：「Analyze the sales-dataset」→ --locale en_US（質問の言語は英語です。データセット名は参照名であり、質問の言語ではありません）
• ユーザー入力：「Show me data from 2024-annual-report」→ --locale en_US（質問の言語は英語です。データセット名は参照名です）
• ユーザー入力：「please query Sales Dataset data」→ --locale zh_CN（質問の言語は中国語です。「Sales Dataset」はデータセット名です）
• ユーザー入力：「please analyze sales data」だが、API が英語のエラーメッセージを返す場合 → --locale zh_CN（ロケールは API のレスポンスではなく、ユーザーの入力に基づいて判定します）
• 直前のエージェントの返信は英語で、その後ユーザーが中国語で「query TOP3」と入力した場合 → --locale zh_CN（ロケールはエージェントの直前の返信ではなく、ユーザーの入力に基づいて判定します）

禁止事項：

• ❌ スクリプトの呼び出し時に --workspace-dir パラメーターを省略してはいけません
• ❌ スクリプトの呼び出しに相対パスを使用してはいけません（例：python3 scripts/chat/...）
• ❌ ハードコードされたパスや推測したパスを使用してはいけません
• ❌ --locale を必要とするスクリプトの呼び出し時に、このパラメーターを省略してはいけません
• ❌ エージェント自身の出力言語や API／スクリプトの戻り値の内容に基づいて --locale を判定してはいけません