huaweicloud/huawei-cloud-ges-graph

⚠️ Método de Ejecución (Lectura Obligatoria): Esta habilidad ejecuta consultas a través de scripts locales de Python o Node.js ubicados en scripts/. Está prohibido el uso de llamadas API directas.

• Los scripts de consulta se encuentran bajo el directorio de la habilidad scripts/ (ej., scripts/ges_graph_skill.py)
• Todos los scripts y scripts de verificación del entorno están dentro del paquete de la habilidad. Debe usar skill action=exec para ejecutarlos; no los ejecute directamente en el shell
• Prefiera la ejecución inline (python -c o node -e) en lugar de crear archivos de script temporales. Consulte la sección "Ejecución Inline (Sin Archivos Temporales)" más abajo.
• Todas las rutas son relativas al directorio de la habilidad, que es el directorio donde reside este SKILL.md

Guía de Acceso a Grafos GES

Resumen

Capacidad atómica de la edición persistente del Servicio de Motor de Grafos (GES) de Huawei Cloud, proporcionando una guía de acceso para operaciones de bases de datos de grafos. Cubre consultas Cypher, consultas GQL, gestión de esquemas/etiquetas, consultas de información resumida, edición de datos de grafos y otras capacidades principales.

Estructura de Directorios

Las convenciones de directorio son las siguientes (todas las rutas son relativas al directorio de la habilidad):

1. scripts/ - Contiene los scripts de ejecución de Python y Node.js
   • ges_graph_skill.py - SDK de Python para operaciones de grafos GES
   • ges_graph_skill.js - SDK de Node.js para operaciones de grafos GES
2. references/ - Contiene documentación y ejemplos de configuración
   • ges_env.csv.example - Plantilla de configuración de entorno
   • cypher-gql-guide.md - Guía completa de uso de Cypher/GQL (ejemplos, tablas, ejecución inline)
   • cli-installation-guide.md - Guía de instalación y configuración del runtime (Python/Node.js)
   • iam-policies.md - Políticas de permisos IAM mínimas para GES/OBS
   • verification-method.md - Pasos de verificación y lista de comprobación
   • acceptance-criteria.md - Criterios de aceptación (umbrales de aprobado/fallo)
   • user-guide-authentication.md - Métodos de token IAM y autenticación mediante Token API de GitCode
   • chaining-protocol.md - Envoltura de resultados uniforme y contrato de llamadas encadenadas

Requisitos Previos

Antes de usar esta habilidad, asegúrese de que se cumplan las siguientes condiciones:

1. Entorno de Ejecución

Soporta runtime de Python o Node.js. Requiere Python 3.8+ o Node.js 14+.

Dependencias de Python: requests (pip install requests). Opcionalmente, huaweicloudsdkges puede instalarse (pip install huaweicloudsdkges) para llamadas a nivel de SDK (ISSUE-013); la habilidad funciona sin él a través de su cliente HTTP integrado. Para Node.js, no se requieren paquetes npm externos (usa solo https/http de la biblioteca estándar).

2. Configuración de la Instancia de Grafo

Esta habilidad soporta tanto variables de entorno como archivos de configuración. Las variables de entorno tienen prioridad sobre los archivos de configuración.

Variables de Entorno y Parámetros

Variable de Entorno	Descripción	Requerido
GES_GRAPH_IP	IP del servicio GES	Sí
GES_GRAPH_PORT	Puerto del servicio GES	Sí
GES_PROJECT_ID	ID del proyecto	Sí
GES_GRAPH_NAME	Nombre del grafo	Sí
GES_IAM_URL	URL del servicio IAM	Sí
GES_REGION	Región	Sí
HUAWEI_CLOUD_AK	Clave de acceso	Sí*
HUAWEI_CLOUD_SK	Clave secreta	Sí*
GES_USERNAME	Nombre de usuario	Condicional**
GES_PASSWORD	Contraseña	Condicional**
GES_DOMAIN_NAME	Nombre de dominio	Condicional**
GES_TOKEN	Token (máxima prioridad)	Opcional

• Se requiere AK/SK para autenticación AKSK. ** Nombre de usuario/contraseña condicionalmente requerido cuando AKSK no está disponible.

Archivo de Configuración (config/ges_env.csv)

Ruta del archivo de configuración: config/ges_env.csv

Elemento de Configuración	Descripción	Requerido	Valor de Ejemplo
graph_ip	IP del servicio GES	Sí	100.95.xxx.xxx
graph_port	Puerto del servicio GES	Sí	80
project_id	ID del proyecto	Sí	your_project_id
graph_name	Nombre del grafo	Sí	your_graph_name
iam_url	URL del servicio IAM	Sí	(ver tabla de regiones abajo)
access_key	Clave de acceso	Sí*	your_access_key
secret_key	Clave secreta	Sí*	your_secret_key
username	Nombre de usuario	Condicional**	your_username
password	Contraseña	Condicional**	your_password
domain_name	Nombre de dominio	Condicional**	your_domain_name
region	Región	Sí	cn-north-4

• access_key/secret_key requeridos para autenticación AKSK. ** username/password/domain_name condicionalmente requeridos cuando AKSK no está disponible.

URLs de IAM por Región

Región	URL	protocolo
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

Se soportan tres métodos (prioridad de mayor a menor):

1. Variable de entorno GES_TOKEN
2. Método AKSK (HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK o access_key + secret_key)
3. Método de contraseña (username + password + domain_name)

⛔ Operaciones Prohibidas (Barrera de Seguridad)

Esta habilidad impone una barrera de seguridad a nivel de código (ISSUE-002), más allá de las restricciones documentales:

• validateCypher() en scripts/ges_graph_skill.py / ges_graph_skill.js intercepta sentencias de eliminación/vaciado total sin restricciones (como MATCH (n) DETACH DELETE n, MATCH ()-[r]->() DELETE r, DROP ALL, etc.);
• Las inserciones, actualizaciones y eliminaciones dirigidas (con WHERE ... id(n)=... o element_id(...)) no se ven afectadas;
• Todos los valores de propiedades solo permiten escalares JSON (str/int/float/bool/None), rechazando dict/list/bytes;
• Si realmente se necesita un vaciado completo, use la interfaz dedicada clear_graph() (o clearGraph()), y primero obtenga la confirmación explícita del usuario, luego ejecute con allow_destructive=True.

Operación Prohibida	Descripción	Razón
❌ Imprimir credenciales sensibles	Imprimir AK/SK, contraseña, token u otra información sensible	Riesgo de fuga de información sensible

Las siguientes operaciones de alto riesgo requieren confirmación explícita del agente antes de la ejecución:

Operación de Alto Riesgo	Descripción	Mensaje de Confirmación
⚠️ Limpiar todos los datos del grafo	clear_graph() o operaciones de limpieza similares	"¿Está seguro de que desea limpiar todos los datos en el grafo? Esta operación es irreversible."
⚠️ Eliminar nodos/aristas en lote	Eliminación masiva incondicional de todos los nodos o aristas	"¿Está seguro de que desea eliminar en lote todos los nodos/aristas? Esta operación es irreversible."

Si un usuario solicita alguna de las operaciones de alto riesgo anteriores, se debe obtener confirmación explícita: "Esta es una operación de alto riesgo y requiere su confirmación explícita. Por favor, responda 'confirmar' para continuar."

Lenguajes de Consulta Cypher y GQL

GES soporta dos lenguajes de consulta: Cypher (compatible con Neo4j) y GQL (lenguaje de consulta de grafos estándar internacional).

La guía de uso completa (ejemplos de Python/Node.js, ejecución inline con skill action=exec, sentencias Cypher/GQL comunes y la tabla de diferencias Cypher↔GQL) se encuentra en references/cypher-gql-guide.md.

Flujo de Trabajo

Tarea 1: Consultar el Grafo (solo lectura, el agente puede ejecutarla automáticamente)

1. Elija un runtime: Python (`ges_graph_skill.py`) o Node.js (`ges_graph_skill.js`). Ambos exponen la misma API.
2. Cargue la configuración (vars de entorno > `references/ges_env.csv.example`) — ejecute las comprobaciones inline a continuación una vez por sesión.
3. Ejecute una consulta Cypher o GQL mediante `execute_query()` / `execute_gql()` (o `executeCypher` / `executeGql` en Node.js).
4. Devuelva la envoltura JSON unificada `{"results": [...], "errors": []}` al usuario.

Ejecución inline (sin archivos temporales): prefiera la ejecución inline en lugar de crear archivos de script temporales. Por ejemplo, ejecute la consulta Python desde el directorio de la habilidad:

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

Consulte references/cypher-gql-guide.md para más ejemplos de inline skill action=exec.

Tarea 2: Editar Datos del Grafo (añadir/actualizar/eliminar nodos y aristas)

1. Valide que los valores de las propiedades sean escalares JSON (cadena/número/booleano/nulo) — el código lo impone (ISSUE-002).
2. Llame al método CRUD correspondiente (`add_node`/`update_node`/`delete_node`, `add_edge`/`delete_edge`).
3. Para importaciones masivas, respete el límite de 500 nodos por llamada (divida en fragmentos, ISSUE-010).
4. Devuelva el resultado de la operación (la envoltura unificada o un resumen `{id, ...}`).

Tarea 3: Operaciones de Alto Riesgo (requieren confirmación explícita del usuario)

1. `clear_graph()` o cualquier eliminación masiva sin calificar es BLOQUEADA a nivel Cypher por `validateCypher()`.
2. Para limpiar todo el grafo, llame a `clear_graph()` (o `clearGraph()` en Node.js) con `allow_destructive=True`.
3. ANTES de ejecutar, pregunte al usuario: "Esta es una operación de alto riesgo y requiere su confirmación explícita. Por favor, responda 'confirmar' para continuar."
4. Solo después de la confirmación, ejecute y devuelva el id del trabajo / resultado.

Tarea 4: Importar / Exportar Datos del Grafo (trabajos asíncronos)

1. Prepare las rutas OBS para los archivos de esquema/vértice/arista (`import_graph`) o una ruta de exportación (`export_graph`).
2. Envíe el trabajo — se devuelve inmediatamente un `{"jobId": ...}`.
3. Consulte `get_job_status(jobId)` hasta que el trabajo alcance un estado terminal.
4. Informe al usuario sobre el estado y cualquier mensaje de error del trabajo.

Verificación y aceptación: las comprobaciones detalladas de aprobado/fallo están en references/verification-method.md y references/acceptance-criteria.md.

Interfaces Principales (Comandos Principales)

Consulta Cypher

# Ejecutar una consulta Cypher
resultado = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Ejecutar una consulta Cypher con parámetros
resultado = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "张三"}
)

Operaciones con Vértices

# Añadir un nodo
resultado = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "El usuario dijo Hola", "timestamp": 1234567890}
)

# Añadir un nodo de forma idempotente (upsert). Nodo existe → actualiza propiedades; si no → crea (ISSUE-004)
resultado = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory"],
    properties={"content": "Contenido actualizado"},
    upsert=True
)

# Añadir nodos en lote (máximo 500 por llamada, barrera de límite ISSUE-010)
resultado = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "prueba1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "prueba2"}}
])

# Obtener un nodo
resultado = skill.client.get_node("mem_001")

# Actualizar un nodo
resultado = skill.client.update_node("mem_001", {"content": "Nuevo contenido"})

# Eliminar un nodo
resultado = skill.client.delete_node("mem_001")

Operaciones con Aristas

# Añadir una arista
resultado = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELATED_TO",
    properties={"weight": 0.8}
)

# Eliminar una arista
resultado = skill.client.delete_edge("mem_001", "mem_002", "RELATED_TO")

# Obtener aristas de un nodo
resultado = skill.client.get_edges("mem_001", direction="both")

Operaciones con Etiquetas

# Añadir una etiqueta a un nodo
resultado = skill.client.add_label_to_node("mem_001", "important")

# Consultar nodos por etiqueta
resultado = skill.client.get_nodes_by_label("Memory", limit=100)

Gestión del Grafo

# Obtener información del esquema
resultado = skill.get_schema_info()

# Obtener estadísticas del grafo
resultado = skill.get_statistics()

# Limpiar todos los datos en el grafo (operación peligrosa, requiere confirmación del usuario)
resultado = skill.client.clear_graph()

Importar/Exportar

# Importar datos del grafo
job_id = skill.client.import_graph(
    schema_path="obs://bucket/schema.xml",
    vertex_path="obs://bucket/vertex",
    edge_path="obs://bucket/edge"
)

# Exportar datos del grafo (access_key/secret_key se leen automáticamente de 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"
)

Guía de Sintaxis GES

Manejo de ID de Nodo

GES usa la propiedad especial _ID_ para manejar IDs de nodo de tipo cadena:

• Crear nodos usa la propiedad _ID_:

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

• Otras operaciones usan la función id():

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

Requisitos de Esquema

GES requiere que el esquema (Etiquetas y Propiedades) se defina antes de que se puedan crear los nodos correspondientes. El esquema se puede definir mediante:

1. Crear Etiquetas y propiedades a través de la consola de gestión de GES
2. Importar datos con esquema a través de la interfaz de importación

Confirmación de Parámetros

Antes de ejecutar cualquier tarea, los siguientes parámetros deben ser confirmados con el usuario. Está prohibido adivinar.

Parámetro	Requerido/Opcional	Descripción	Valor por Defecto
Instancia de grafo	Requerido	GES_GRAPH_IP / GES_GRAPH_PORT / GES_GRAPH_NAME / GES_PROJECT_ID — qué instancia de GES operar	De la configuración env/CSV
Sentencia de consulta	Requerido	Sentencia Cypher o GQL, más un diccionario de parámetros escalares JSON	-
Propiedades de nodo/arista	Requerido para escrituras	Solo se aceptan escalares JSON (cadena/número/booleano/nulo)	-
Ámbito de operación	Requerido para operaciones de alto riesgo	clear_graph / eliminación masiva requieren confirmación explícita del usuario	-
Rutas de importación/exportación	Requerido	Rutas de bucket/objeto OBS para los archivos de esquema/vértice/arista	-

Nota: los parámetros de conexión se leen del entorno o de config/ges_env.csv (references/ges_env.csv.example); nunca es necesario pasarlos por llamada.

Formato de Respuesta

Todas las interfaces Cypher devuelven un formato JSON unificado:

{
  "results": [
    {
      "columns": ["columna1", "columna2"],
      "data": [
        {"row": ["valor1", "valor2"], "meta": [null, null]}
      ]
    }
  ],
  "error"