⚠️ Méthode d'exécution (À lire impérativement) : Cette compétence exécute les requêtes via des scripts Python ou Node.js locaux sous scripts/. L'utilisation d'appels API directs est interdite.

Les scripts de requête se trouvent dans le répertoire de la compétence scripts/ (par exemple, scripts/ges_graph_skill.py)

Tous les scripts et scripts de vérification d'environnement sont dans le package de la compétence. Vous devez utiliser skill action=exec pour les exécuter ; ne les exécutez pas directement dans le shell

Privilégiez l'exécution en ligne (python -c ou node -e) plutôt que la création de fichiers de script temporaires. Voir la section "Exécution en ligne (Pas de fichiers temporaires)" ci-dessous.

Tous les chemins sont relatifs au répertoire de la compétence, qui est le répertoire où se trouve ce SKILL.md

Guide d'accès aux graphes GES

Présentation

Capacité atomique de l'édition persistante du service de moteur graphique Huawei Cloud (GES), fournissant un guide d'accès pour les opérations de base de données graphiques. Couvre les requêtes Cypher, les requêtes GQL, la gestion des schémas/étiquettes, les requêtes d'informations récapitulatives, la modification des données graphiques et d'autres capacités essentielles.

Structure du répertoire

Les conventions de répertoire sont les suivantes (tous les chemins sont relatifs au répertoire de la compétence) :

scripts/ - Contient les scripts d'exécution Python et Node.js
- ges_graph_skill.py - SDK Python pour les opérations de graphes GES
- ges_graph_skill.js - SDK Node.js pour les opérations de graphes GES
references/ - Contient la documentation et les exemples de configuration
- ges_env.csv.example - Modèle de configuration d'environnement
- cypher-gql-guide.md - Guide d'utilisation complet Cypher/GQL (exemples, tableaux, exécution en ligne)
- cli-installation-guide.md - Guide d'installation et de configuration de l'environnement d'exécution (Python/Node.js)
- iam-policies.md - Politiques de permissions IAM minimales pour GES/OBS
- verification-method.md - Étapes de vérification et liste de contrôle
- acceptance-criteria.md - Critères d'acceptation (seuils de réussite/échec)
- user-guide-authentication.md - Méthodes de jeton IAM et authentification par jeton API GitCode
- chaining-protocol.md - Enveloppe de résultat uniforme et contrat d'appel chaîné

Prérequis

Avant d'utiliser cette compétence, assurez-vous que les conditions suivantes sont remplies :

1. Environnement d'exécution

Prend en charge les environnements d'exécution Python ou Node.js. Nécessite Python 3.8+ ou Node.js 14+.

Dépendances Python : requests (pip install requests). Optionnellement, huaweicloudsdkges peut être installé (pip install huaweicloudsdkges) pour les appels de niveau SDK (ISSUE-013) ; la compétence fonctionne sans cela via son client HTTP intégré. Pour Node.js, aucun package npm externe n'est nécessaire (utilise uniquement https/http de la bibliothèque standard).

2. Configuration de l'instance de graphe

Cette compétence prend en charge à la fois les variables d'environnement et les fichiers de configuration. Les variables d'environnement ont priorité sur les fichiers de configuration.

Variables d'environnement et paramètres

Variable d'environnement	Description	Requis
`GES_GRAPH_IP`	IP du service GES	Oui
`GES_GRAPH_PORT`	Port du service GES	Oui
`GES_PROJECT_ID`	ID du projet	Oui
`GES_GRAPH_NAME`	Nom du graphe	Oui
`GES_IAM_URL`	URL du service IAM	Oui
`GES_REGION`	Région	Oui
`HUAWEI_CLOUD_AK`	Clé d'accès	Oui*
`HUAWEI_CLOUD_SK`	Clé secrète	Oui*
`GES_USERNAME`	Nom d'utilisateur	Conditionnel**
`GES_PASSWORD`	Mot de passe	Conditionnel**
`GES_DOMAIN_NAME`	Nom de domaine	Conditionnel**
`GES_TOKEN`	Jeton (priorité la plus élevée)	Facultatif

AK/SK requis pour l'authentification AKSK. ** Nom d'utilisateur/mot de passe conditionnellement requis lorsque AKSK n'est pas disponible.

Fichier de configuration (config/ges_env.csv)

Chemin du fichier de configuration : config/ges_env.csv

Élément de configuration	Description	Requis	Exemple de valeur
graph_ip	IP du service GES	Oui	100.95.xxx.xxx
graph_port	Port du service GES	Oui	80
project_id	ID du projet	Oui	votre_id_projet
graph_name	Nom du graphe	Oui	votre_nom_graphe
iam_url	URL du service IAM	Oui	(voir le tableau des régions ci-dessous)
access_key	Clé d'accès	Oui*	votre_clé_accès
secret_key	Clé secrète	Oui*	votre_clé_secrète
username	Nom d'utilisateur	Conditionnel**	votre_nom_utilisateur
password	Mot de passe	Conditionnel**	votre_mot_de_passe
domain_name	Nom de domaine	Conditionnel**	votre_nom_domaine
region	Région	Oui	cn-north-4

access_key/secret_key requis pour l'authentification AKSK. ** username/password/domain_name conditionnellement requis lorsque AKSK n'est pas disponible.

URL IAM par région

Région	URL	protocole
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

Trois méthodes sont prises en charge (priorité de la plus élevée à la plus faible) :

Variable d'environnement GES_TOKEN
Méthode AKSK (HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK ou access_key + secret_key)
Méthode par mot de passe (nom d'utilisateur + mot de passe + nom de domaine)

⛔ Opérations interdites (Garde-fou de sécurité)

Cette compétence applique des garde-fous de sécurité au niveau du code (ISSUE-002), au-delà des contraintes documentaires :

validateCypher() dans scripts/ges_graph_skill.py / ges_graph_skill.js intercepte les instructions de suppression/vidage intégral non limitées (telles que MATCH (n) DETACH DELETE n, MATCH ()-[r]->() DELETE r, DROP ALL, etc.) ;

Les opérations ciblées d'ajout/suppression/modification (avec WHERE ... id(n)=... ou element_id(...)) ne sont pas affectées ;

Toutes les valeurs de propriétés doivent être des scalaires JSON (str/int/float/bool/None), les dict/list/bytes sont refusés ;

Si un vidage intégral est vraiment nécessaire, veuillez utiliser l'interface dédiée clear_graph() (ou clearGraph()), et obtenez d'abord une confirmation explicite de l'utilisateur, puis autorisez avec allow_destructive=True.

Opération interdite	Description	Raison
❌ Affichage d'identifiants sensibles	Affichage d'AK/SK, mot de passe, jeton ou autres informations sensibles	Risque de fuite d'informations sensibles

Les opérations à haut risque suivantes nécessitent une confirmation explicite de l'agent avant exécution :

Opération à haut risque	Description	Invite de confirmation
⚠️ Effacement de toutes les données du graphe	`clear_graph()` ou opérations d'effacement similaires	"Êtes-vous sûr de vouloir effacer toutes les données du graphe ? Cette opération est irréversible."
⚠️ Suppression par lots de nœuds/arêtes	Suppression en masse inconditionnelle de tous les nœuds ou arêtes	"Êtes-vous sûr de vouloir supprimer par lots tous les nœuds/arêtes ? Cette opération est irréversible."

Si un utilisateur demande l'une des opérations à haut risque ci-dessus, une confirmation explicite doit être obtenue : "Il s'agit d'une opération à haut risque et nécessite votre confirmation explicite. Veuillez répondre par 'confirmer' pour continuer."

Langages de requête Cypher et GQL

GES prend en charge deux langages de requête : Cypher (compatible Neo4j) et GQL (langage de requête graphique standard international).

Le guide d'utilisation complet (exemples Python/Node.js, exécution en ligne skill action=exec, instructions Cypher/GQL courantes et le tableau des différences Cypher↔GQL) se trouve dans references/cypher-gql-guide.md.

Flux de travail

Tâche 1 : Interroger le graphe (lecture seule, l'agent peut s'exécuter automatiquement)

1. Choisissez un environnement d'exécution : Python (`ges_graph_skill.py`) ou Node.js (`ges_graph_skill.js`). Les deux exposent la même API.
2. Chargez la configuration (variables d'environnement > `references/ges_env.csv.example`) — exécutez les vérifications en ligne ci-dessous une fois par session.
3. Exécutez une requête Cypher ou GQL via `execute_query()` / `execute_gql()` (ou `executeCypher` / `executeGql` dans Node.js).
4. Retournez l'enveloppe JSON unifiée `{"results": [...], "errors": []}` à l'utilisateur.

Exécution en ligne (pas de fichiers temporaires) : privilégiez l'exécution en ligne plutôt que la création de fichiers de script temporaires. Par exemple, exécutez la requête Python depuis le répertoire de la compétence :

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);'

Voir references/cypher-gql-guide.md pour plus d'exemples d'exécution en ligne skill action=exec.

Tâche 2 : Modifier les données du graphe (ajouter/mettre à jour/supprimer des nœuds et des arêtes)

1. Validez que les valeurs des propriétés sont des scalaires JSON (chaîne/nombre/booléen/nul) — le code applique cette règle (ISSUE-002).
2. Appelez la méthode CRUD correspondante (`add_node`/`update_node`/`delete_node`, `add_edge`/`delete_edge`).
3. Pour les importations en masse, respectez la limite de 500 nœuds par appel (divisez en lots, ISSUE-010).
4. Retournez le résultat de l'opération (l'enveloppe unifiée ou un résumé `{id, ...}`).

Tâche 3 : Opérations à haut risque (nécessitent une confirmation explicite de l'utilisateur)

1. `clear_graph()` ou toute suppression en masse non qualifiée est BLOQUÉE au niveau Cypher par `validateCypher()`.
2. Pour effacer tout le graphe, appelez `clear_graph()` (ou `clearGraph()` dans Node.js) avec `allow_destructive=True`.
3. AVANT d'exécuter, demandez à l'utilisateur : "Il s'agit d'une opération à haut risque et nécessite votre confirmation explicite. Veuillez répondre par 'confirmer' pour continuer."
4. Après confirmation seulement, exécutez et retournez l'ID du travail / le résultat.

Tâche 4 : Importer / Exporter des données du graphe (travaux asynchrones)

1. Préparez les chemins OBS pour les fichiers de schéma/sommet/arête (`import_graph`) ou un chemin d'exportation (`export_graph`).
2. Soumettez le travail — un `{"jobId": ...}` est retourné immédiatement.
3. Interrogez `get_job_status(jobId)` jusqu'à ce que le travail atteigne un état terminal.
4. Signalez l'état et tout message d'erreur du travail à l'utilisateur.

Vérification et acceptation : les contrôles détaillés de réussite/échec se trouvent dans references/verification-method.md et references/acceptance-criteria.md.

Interfaces principales (Commandes principales)

Requête Cypher

# Exécute une requête Cypher
résultat = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Exécute une requête Cypher avec paramètres
résultat = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "张三"}
)

Opérations sur les sommets

# Ajoute un nœud
résultat = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "User said Hello", "timestamp": 1234567890}
)

# Ajoute un nœud de manière idempotente (upsert). Le nœud existe → met à jour les propriétés ; sinon → crée (ISSUE-004)
résultat = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory"],
    properties={"content": "Updated content"},
    upsert=True
)

# Ajoute des nœuds par lots (max 500 par appel, garde-fou de limite ISSUE-010)
résultat = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "test1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "test2"}}
])

# Récupère un nœud
résultat = skill.client.get_node("mem_001")

# Met à jour un nœud
résultat = skill.client.update_node("mem_001", {"content": "New content"})

# Supprime un nœud
résultat = skill.client.delete_node("mem_001")

Opérations sur les arêtes

# Ajoute une arête
résultat = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELATED_TO",
    properties={"weight": 0.8}
)

# Supprime une arête
résultat = skill.client.delete_edge("mem_001", "mem_002", "RELATED_TO")

# Récupère les arêtes d'un nœud
résultat = skill.client.get_edges("mem_001", direction="both")

Opérations sur les étiquettes

# Ajoute une étiquette à un nœud
résultat = skill.client.add_label_to_node("mem_001", "important")

# Interroge les nœuds par étiquette
résultat = skill.client.get_nodes_by_label("Memory", limit=100)

Gestion du graphe

# Récupère les informations de schéma
résultat = skill.get_schema_info()

# Récupère les statistiques du graphe
résultat = skill.get_statistics()

# Efface toutes les données du graphe (opération dangereuse, nécessite la confirmation de l'utilisateur)
résultat = skill.client.clear_graph()

Import/Export

# Importe des données de graphe
job_id = skill.client.import_graph(
    schema_path="obs://bucket/schema.xml",
    vertex_path="obs://bucket/vertex",
    edge_path="obs://bucket/edge"
)

# Exporte des données de graphe (access_key/secret_key sont lus automatiquement depuis 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"
)

Guide de syntaxe GES

Gestion des ID de nœuds

GES utilise la propriété spéciale _ID_ pour gérer les ID de nœuds de type chaîne :

La création de nœuds utilise la propriété _ID_ :

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

Les autres opérations utilisent la fonction id() :

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

Exigences de schéma

GES nécessite que le schéma (étiquettes et propriétés) soit défini avant que les nœuds correspondants puissent être créés. Le schéma peut être défini via :

Création d'étiquettes et de propriétés via la console de gestion GES
Importation de données avec schéma via l'interface d'importation

Confirmation des paramètres

Avant d'exécuter une tâche, les paramètres suivants doivent être confirmés avec l'utilisateur. Il est interdit de deviner.

Paramètre	Requis/Facultatif	Description	Valeur par défaut
Instance de graphe	Requis	`GES_GRAPH_IP` / `GES_GRAPH_PORT` / `GES_GRAPH_NAME` / `GES_PROJECT_ID` — sur quelle instance GES opérer	Depuis la configuration env/CSV
Instruction de requête	Requis	Instruction Cypher ou GQL, plus un dictionnaire de paramètres scalaires JSON	-
Propriétés de nœud/arête	Requis pour les écritures	Seuls les scalaires JSON (chaîne/nombre/booléen/nul) sont acceptés	-
Périmètre de l'opération	Requis pour les opérations à haut risque	`clear_graph` / suppression en masse nécessitent une confirmation explicite de l'utilisateur	-
Chemins d'import/export	Requis	Chemins OBS bucket/objet pour les fichiers de schéma/sommet/arête	-

Remarque : les paramètres de connexion sont lus depuis l'environnement ou config/ges_env.csv (references/ges_env.csv.example) ; ils ne sont jamais nécessaires à passer par appel.

Format de réponse

Toutes les interfaces Cypher retournent un format JSON unifié :

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

Dépannage

Problèmes courants

Erreur : "Name or service not known"
- Vérifiez que GES_GRAPH_IP est accessible depuis l'environnement actuel. 100.95.x.x sont des IP privées et peuvent ne pas être accessibles.
Erreur : "Invalid token"
- Le jeton IAM a une durée de validité de 24h. Essayez de le régénérer.
Erreur : "Label does not exist"
- Le schéma (étiquette + propriétés) doit être créé avant les données. Créez d'abord le schéma via la console GES ou une importation de schéma.
Erreur : "Only JSON scalar types allowed"
- La valeur d'une propriété doit être un type scalaire JSON (chaîne, nombre, booléen, nul). Les dictionnaires, listes, bytes ne sont pas autorisés.
Script : erreur locale "get_skill" non trouvé
- Assurez-vous que scripts/ est dans sys.path (Python) ou que le chemin est correct (Node.js). Exécutez toujours depuis le répertoire racine de la compétence.

Demander à votre IA préférée

Documentation