huaweicloud/huawei-cloud-ges-graph

⚠️ 実行方法（必読）: このスキルはローカルの Python または Node.js スクリプト (scripts/) を介してクエリを実行します。直接 API を呼び出すことは禁止されています。

• クエリスクリプトはスキルディレクトリ scripts/ にあります（例: scripts/ges_graph_skill.py）。
• すべてのスクリプトと環境確認スクリプトはスキルパッケージ内にあります。skill action=exec を使用して実行してください。シェルで直接実行しないでください。
• 一時ファイルを作成せずにインライン実行（python -c または node -e）を推奨します。以下の「インライン実行（一時ファイルなし）」セクションを参照してください。
• すべてのパスは、この SKILL.md が配置されているスキルディレクトリを基準とした相対パスです。

GES グラフアクセスガイダンス

概要

Huawei Cloud Graph Engine Service (GES) 永続版のアトミック機能を提供し、グラフデータベース操作のアクセスガイドを提供します。 Cypher クエリ、GQL クエリ、スキーマ/ラベル管理、サマリー情報クエリ、グラフデータ編集などのコア機能をカバーします。

ディレクトリ構造

ディレクトリの規約は次のとおりです（すべてのパスはスキルディレクトリを基準とした相対パスです）:

1. scripts/ - Python および Node.js 実行スクリプトを含む
   • ges_graph_skill.py - GES グラフ操作用 Python SDK
   • ges_graph_skill.js - GES グラフ操作用 Node.js SDK
2. references/ - ドキュメントと設定例を含む
   • ges_env.csv.example - 環境設定テンプレート
   • cypher-gql-guide.md - Cypher/GQL 完全使用ガイド（例、テーブル、インライン実行）
   • cli-installation-guide.md - ランタイム（Python/Node.js）インストールおよび設定ガイド
   • iam-policies.md - GES/OBS の最小 IAM 許可ポリシー
   • verification-method.md - 検証手順とチェックリスト
   • acceptance-criteria.md - 合格基準（合格/不合格しきい値）
   • user-guide-authentication.md - IAM トークン方式と GitCode API トークン認証
   • chaining-protocol.md - 統一結果エンベロープとチェーン呼び出し契約

前提条件

このスキルを使用する前に、次の条件が満たされていることを確認してください:

1. ランタイム環境

Python または Node.js ランタイムをサポートします。 Python 3.8+ または Node.js 14+ が必要です。

Python の依存関係: requests（pip install requests）。オプションで huaweicloudsdkges をインストール可能（pip install huaweicloudsdkges）で SDK レベルの呼び出しが可能ですが（ISSUE-013）、 組み込みの HTTP クライアントを使用するため、それがなくてもスキルは動作します。Node.js には、外部の npm パッケージは不要です（stdlib の https/http のみを使用）。

2. グラフインスタンス設定

このスキルは、環境変数と設定ファイルの両方をサポートします。環境変数は設定ファイルよりも優先されます。

環境変数とパラメータ

環境変数	説明	必須
GES_GRAPH_IP	GES サービス IP	はい
GES_GRAPH_PORT	GES サービスポート	はい
GES_PROJECT_ID	プロジェクト ID	はい
GES_GRAPH_NAME	グラフ名	はい
GES_IAM_URL	IAM サービス URL	はい
GES_REGION	リージョン	はい
HUAWEI_CLOUD_AK	アクセスキー	はい*
HUAWEI_CLOUD_SK	シークレットキー	はい*
GES_USERNAME	ユーザー名	条件付き**
GES_PASSWORD	パスワード	条件付き**
GES_DOMAIN_NAME	ドメイン名	条件付き**
GES_TOKEN	トークン（最高優先度）	オプション

• AK/SK 必須: AKSK 認証の場合。 ** ユーザー名/パスワードは条件付きで必須: AKSK が利用できない場合。

設定ファイル (config/ges_env.csv)

設定ファイルのパス: config/ges_env.csv

設定項目	説明	必須	値の例
graph_ip	GES サービス IP	はい	100.95.xxx.xxx
graph_port	GES サービスポート	はい	80
project_id	プロジェクト ID	はい	your_project_id
graph_name	グラフ名	はい	your_graph_name
iam_url	IAM サービス URL	はい	（下記リージョンテーブルを参照）
access_key	アクセスキー	はい*	your_access_key
secret_key	シークレットキー	はい*	your_secret_key
username	ユーザー名	条件付き**	your_username
password	パスワード	条件付き**	your_password
domain_name	ドメイン名	条件付き**	your_domain_name
region	リージョン	はい	cn-north-4

• access_key/secret_key 必須: AKSK 認証の場合。 ** username/password/domain_name は条件付きで必須: AKSK が利用できない場合。

リージョン別 IAM URL

リージョン	URL	プロトコル
cn-north-4	iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens	HTTPS
ap-southeast-1	iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens	HTTPS

3 つの方法がサポートされています（優先度順）:

1. 環境変数 GES_TOKEN
2. AKSK 方式（HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK または access_key + secret_key）
3. パスワード方式（username + password + domain_name）

⛔ 禁止操作（安全ガードレール）

本スキルはコードレベルで安全ガードレール（ISSUE-002）を強制します。ドキュメント上の制約だけではありません。

• scripts/ges_graph_skill.py / ges_graph_skill.js 内の validateCypher() は、未限定の全削除/クリア文（MATCH (n) DETACH DELETE n、 MATCH ()-[r]->() DELETE r、DROP ALL など）をインターセプトします。
• 対象を指定した追加/更新/削除（WHERE ... id(n)=... または element_id(...) を含むもの）は影響を受けません。
• すべての属性値は JSON スカラー（str/int/float/bool/None）のみ許可され、dict/list/bytes は拒否されます。
• どうしても全量クリアが必要な場合は、clear_graph()（または clearGraph()）専用インターフェースを使用し、 まずユーザーの明確な確認を得た上で、allow_destructive=True を指定して実行してください。

禁止操作	説明	理由
❌ 機密認証情報の出力	AK/SK、パスワード、トークン、その他の機密情報の出力	機密情報漏洩のリスク

以下の高リスク操作は、実行前にエージェントの明示的な確認が必要です:

高リスク操作	説明	確認プロンプト
⚠️ グラフデータの全消去	clear_graph() または類似のクリア操作	「グラフ内のすべてのデータを削除してもよろしいですか？この操作は元に戻せません。」
⚠️ ノード/エッジの一括削除	すべてのノードまたはエッジの無条件一括削除	「すべてのノード/エッジを一括削除してもよろしいですか？この操作は元に戻せません。」

ユーザーが上記の高リスク操作を要求した場合は、明示的な確認を得る必要があります: 「これは高リスク操作です。実行するには明示的な確認が必要です。続行するには「confirm」と返信してください。」

Cypher および GQL クエリ言語

GES は 2 つのクエリ言語をサポートしています: Cypher（Neo4j 互換）と GQL（国際標準グラフクエリ言語）。

完全な使用ガイド（Python/Node.js の例、インライン skill action=exec 実行、 一般的な Cypher/GQL ステートメント、Cypher↔GQL の違いの表）は、 references/cypher-gql-guide.md にあります。

ワークフロー

タスク 1: グラフのクエリ（読み取り専用、エージェントが自動実行可能）

1. ランタイムを選択します: Python（`ges_graph_skill.py`）または Node.js（`ges_graph_skill.js`）。どちらも同じ API を公開しています。
2. 設定を読み込みます（環境変数 > `references/ges_env.csv.example`）— 以下のインラインチェックをセッションごとに 1 回実行します。
3. `execute_query()` / `execute_gql()`（Node.js の場合は `executeCypher` / `executeGql`）を使用して Cypher または GQL クエリを実行します。
4. 統一 JSON エンベロープ `{"results": [...], "errors": []}` をユーザーに返します。

インライン実行（一時ファイルなし）: 一時的なスクリプトファイルを作成するよりも、インライン実行を推奨します。たとえば、スキルディレクトリから Python クエリを実行します:

python3 - <<'PY'
import sys; sys.path.insert(0, "scripts")
from ges_graph_skill import get_skill
s = get_skill()
print(s.execute_query("MATCH (n) RETURN n LIMIT 10"))
PY

node -e 'const { GESGraphSkill } = require("./scripts/ges_graph_skill.js");
const s = new GESGraphSkill(); s.executeQuery("MATCH (n) RETURN n LIMIT 10").then(console.log);'

インライン skill action=exec の例については、references/cypher-gql-guide.md を参照してください。

タスク 2: グラフデータの編集（ノードとエッジの追加/更新/削除）

1. プロパティ値が JSON スカラー（文字列/数値/ブール値/null）であることを検証します — コードがこれを強制します（ISSUE-002）。
2. 対応する CRUD メソッドを呼び出します（`add_node`/`update_node`/`delete_node`、`add_edge`/`delete_edge`）。
3. 一括インポートの場合は、1 回の呼び出しあたり 500 ノードの制限を守ります（チャンクに分割、ISSUE-010）。
4. 操作結果を返します（統一エンベロープまたは `{id, ...}` サマリー）。

タスク 3: 高リスク操作（明示的なユーザー確認が必要）

1. `clear_graph()` または未限定の一括削除は、Cypher レベルで `validateCypher()` によって BLOCK されます。
2. グラフ全体をクリアするには、`allow_destructive=True` を指定して `clear_graph()`（または Node.js の `clearGraph()`）を呼び出します。
3. 実行する前に、ユーザーに確認を求めます: 「これは高リスク操作です。実行するには明示的な確認が必要です。続行するには「confirm」と返信してください。」
4. 確認後、実行し、ジョブ ID / 結果を返します。

タスク 4: グラフデータのインポート / エクスポート（非同期ジョブ）

1. スキーマ/頂点/エッジファイル用の OBS パス（`import_graph`）またはエクスポートパス（`export_graph`）を準備します。
2. ジョブを送信します — `{"jobId": ...}` がすぐに返されます。
3. `get_job_status(jobId)` をポーリングして、ジョブが終了状態になるまで待機します。
4. ステータスとジョブからのエラーメッセージをユーザーに報告します。

検証と合格基準: 詳細な合格/不合格チェックは、 references/verification-method.md と references/acceptance-criteria.md にあります。

コアインターフェース（コアコマンド）

Cypher クエリ

# Cypher クエリを実行
result = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# パラメータ付き Cypher クエリを実行
result = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "张三"}
)

頂点（ノード）操作

# ノードを追加
result = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "User said Hello", "timestamp": 1234567890}
)

# ノードを冫等に追加（アップサート）。ノードが存在する場合はプロパティを更新、存在しない場合は作成（ISSUE-004）
result = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory"],
    properties={"content": "Updated content"},
    upsert=True
)

# ノードを一括追加（1 回の呼び出しあたり最大 500、境界ガード ISSUE-010）
result = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "test1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "test2"}}
])

# ノードを取得
result = skill.client.get_node("mem_001")

# ノードを更新
result = skill.client.update_node("mem_001", {"content": "New content"})

# ノードを削除
result = skill.client.delete_node("mem_001")

エッジ操作

# エッジを追加
result = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELATED_TO",
    properties={"weight": 0.8}
)

# エッジを削除
result = skill.client.delete_edge("mem_001", "mem_002", "RELATED_TO")

# ノードのエッジを取得
result = skill.client.get_edges("mem_001", direction="both")

ラベル操作

# ノードにラベルを追加
result = skill.client.add_label_to_node("mem_001", "important")

# ラベルでノードをクエリ
result = skill.client.get_nodes_by_label("Memory", limit=100)

グラフ管理

# スキーマ情報を取得
result = skill.get_schema_info()

# グラフ統計情報を取得
result = skill.get_statistics()

# グラフ内のすべてのデータをクリア（危険な操作。ユーザーの確認が必要）
result = skill.client.clear_graph()

インポート/エクスポート

# グラフデータをインポート
job_id = skill.client.import_graph(
    schema_path="obs://bucket/schema.xml",
    vertex_path="obs://bucket/vertex",
    edge_path="obs://bucket/edge"
)

# グラフデータをエクスポート（access_key/secret_key は config/ges_env.csv から自動読み取り）
job_id = skill.client.export_graph(
    export_path="obs://bucket/export",
    vertex_set_name="set_vertex",
    edge_set_name="set_edge"
)

GES 構文ガイド

ノード ID の取り扱い

GES は特別な _ID_ プロパティを使用して文字列型のノード ID を処理します:

• ノードの作成 では _ID_ プロパティを使用します:

  CREATE (n:Memory{_ID_: 'mem_001', content: 'test'})
  

• その他の操作 では id() 関数を使用します:

  MATCH (n) WHERE id(n) = 'mem_001' RETURN n
  MATCH (n)-[r]->(m) WHERE id(n) = 'mem_001' RETURN r
  

スキーマ要件

GES では、対応するノードを作成する前に、スキーマ（ラベルとプロパティ）を定義する必要があります。スキーマは次の方法で定義できます:

1. GES 管理コンソールを介してラベルとプロパティを作成する
2. インポートインターフェースを介してスキーマを含むデータをインポートする

パラメータ確認

タスクを実行する前に、次のパラメータをユーザーに確認する必要があります。推測は禁止されています。

パラメータ	必須/オプション	説明	デフォルト
グラフインスタンス	必須	GES_GRAPH_IP / GES_GRAPH_PORT / GES_GRAPH_NAME / GES_PROJECT_ID — 操作する GES インスタンス	環境変数/CSV 設定から
クエリステートメント	必須	Cypher または GQL ステートメント、および JSON スカラー値のパラメータ辞書	-
ノード/エッジのプロパティ	書き込み時に必須	JSON スカラー（文字列/数値/ブール値/null）のみ受け付け	-
操作範囲	高リスク操作時に必須	clear_graph / 一括削除には明示的なユーザー確認が必要	-
インポート/エクスポートパス	必須	スキーマ/頂点/エッジファイルの OBS バケット/オブジェクトパス	-

注: 接続パラメータは環境または config/ges_env.csv（references/ges_env.csv.example）から読み取られます。呼び出しごとに渡す必要はありません。

レスポンス形式

すべての Cypher インターフェースは、統一された JSON 形式を返します:

{
  "results": [
    {
      "columns": ["column1", "column2"],
      "data": [
        {"row": ["value1", "value2"], "meta": [null, null]}
      ]
    }
  ],
  "errors": []
}

エラーハンドリング

エラーは統一エンベロープの errors フィールドで報告されるか、例外としてスローされます。