huaweicloud/huawei-cloud-ges-graph

⚠️ Método de Execução (Leitura Obrigatória): Esta skill executa consultas via scripts Python ou Node.js locais em scripts/. O uso de chamadas de API diretas é proibido.

• Os scripts de consulta estão localizados no diretório da skill scripts/ (por exemplo, scripts/ges_graph_skill.py)
• Todos os scripts e scripts de verificação de ambiente estão dentro do pacote da skill. Você deve usar skill action=exec para executá-los; não os execute diretamente no shell
• Prefira a execução inline (python -c ou node -e) em vez de criar arquivos de script temporários. Consulte a seção "Execução Inline (Sem Arquivos Temporários)" abaixo.
• Todos os caminhos são relativos ao diretório da skill, que é o diretório onde este SKILL.md reside

Guia de Acesso ao Grafo GES

Visão Geral

Capacidade atômica da edição persistente do Huawei Cloud Graph Engine Service (GES), fornecendo um guia de acesso para operações de banco de dados de grafo. Abrange consultas Cypher, consultas GQL, gerenciamento de esquema/rótulo, consultas de informações resumidas, edição de dados de grafo e outras capacidades principais.

Estrutura de Diretórios

As convenções de diretório são as seguintes (todos os caminhos são relativos ao diretório da skill):

1. scripts/ - Contém os scripts de execução Python e Node.js
   • ges_graph_skill.py - SDK Python para operações de grafo GES
   • ges_graph_skill.js - SDK Node.js para operações de grafo GES
2. references/ - Contém documentação e exemplos de configuração
   • ges_env.csv.example - Modelo de configuração de ambiente
   • cypher-gql-guide.md - Guia completo de uso Cypher/GQL (exemplos, tabelas, execução inline)
   • cli-installation-guide.md - Guia de instalação e configuração do runtime (Python/Node.js)
   • iam-policies.md - Políticas de permissão IAM mínimas para GES/OBS
   • verification-method.md - Etapas de verificação e checklist
   • acceptance-criteria.md - Critérios de aceitação (limiares de aprovação/reprovação)
   • user-guide-authentication.md - Métodos de token IAM e autenticação GitCode API Token
   • chaining-protocol.md - Envelope de resultado uniforme e contrato de chamada encadeada

Pré-requisitos

Antes de usar esta skill, garanta que as seguintes condições sejam atendidas:

1. Ambiente de Execução

Suporta runtime Python ou Node.js. Requer Python 3.8+ ou Node.js 14+.

Dependências Python: requests (pip install requests). Opcionalmente, huaweicloudsdkges pode ser instalado (pip install huaweicloudsdkges) para chamadas de nível SDK (ISSUE-013); a skill funciona sem ele através de seu cliente HTTP interno. Para Node.js, nenhum pacote npm externo é necessário (usa apenas https/http da stdlib).

2. Configuração da Instância de Grafo

Esta skill suporta tanto variáveis de ambiente quanto arquivos de configuração. As variáveis de ambiente têm precedência sobre os arquivos de configuração.

Variáveis de Ambiente e Parâmetros

Variável de Ambiente	Descrição	Obrigatório
GES_GRAPH_IP	IP do serviço GES	Sim
GES_GRAPH_PORT	Porta do serviço GES	Sim
GES_PROJECT_ID	ID do Projeto	Sim
GES_GRAPH_NAME	Nome do grafo	Sim
GES_IAM_URL	URL do serviço IAM	Sim
GES_REGION	Região	Sim
HUAWEI_CLOUD_AK	Chave de Acesso	Sim*
HUAWEI_CLOUD_SK	Chave Secreta	Sim*
GES_USERNAME	Nome de usuário	Condicional**
GES_PASSWORD	Senha	Condicional**
GES_DOMAIN_NAME	Nome do domínio	Condicional**
GES_TOKEN	Token (maior prioridade)	Opcional

• AK/SK obrigatório para autenticação AKSK. ** Nome de usuário/senha condicionalmente obrigatório quando AKSK não está disponível.

Arquivo de Configuração (config/ges_env.csv)

Caminho do arquivo de configuração: config/ges_env.csv

Item de Configuração	Descrição	Obrigatório	Exemplo de Valor
graph_ip	IP do serviço GES	Sim	100.95.xxx.xxx
graph_port	Porta do serviço GES	Sim	80
project_id	ID do Projeto	Sim	your_project_id
graph_name	Nome do grafo	Sim	your_graph_name
iam_url	URL do serviço IAM	Sim	(consulte a tabela de regiões abaixo)
access_key	Chave de Acesso	Sim*	your_access_key
secret_key	Chave Secreta	Sim*	your_secret_key
username	Nome de usuário	Condicional**	your_username
password	Senha	Condicional**	your_password
domain_name	Nome do domínio	Condicional**	your_domain_name
region	Região	Sim	cn-north-4

• access_key/secret_key obrigatório para autenticação AKSK. ** username/password/domain_name condicionalmente obrigatório quando AKSK não está disponível.

URLs IAM por Região

Região	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

Três métodos são suportados (prioridade do maior para o menor):

1. Variável de ambiente GES_TOKEN
2. Método AKSK (HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK ou access_key + secret_key)
3. Método de senha (username + password + domain_name)

⛔ Operações Proibidas (Barreira de Segurança)

Esta skill impõe barreiras de segurança em nível de código (ISSUE-002), indo além das restrições documentais:

• validateCypher() em scripts/ges_graph_skill.py / ges_graph_skill.js interceptará instruções de exclusão/limpeza total não qualificadas (como MATCH (n) DETACH DELETE n, MATCH ()-[r]->() DELETE r, DROP ALL, etc.);
• Operações direcionadas de adição, alteração e exclusão (com WHERE ... id(n)=... ou element_id(...)) não são afetadas;
• Todos os valores de propriedade permitem apenas escalares JSON (str/int/float/bool/None), rejeitando dict/list/bytes;
• Se houver necessidade de limpeza total, use a interface dedicada clear_graph() (ou clearGraph()), e obtenha a confirmação explícita do usuário antes de prosseguir com allow_destructive=True.

Operação Proibida	Descrição	Motivo
❌ Impressão de credenciais confidenciais	Imprimir AK/SK, senha, token ou outras informações confidenciais	Risco de vazamento de informações confidenciais

As seguintes operações de alto risco exigem confirmação explícita do agente antes da execução:

Operação de Alto Risco	Descrição	Prompt de Confirmação
⚠️ Limpar todos os dados do grafo	clear_graph() ou operações de limpeza semelhantes	"Tem certeza de que deseja limpar todos os dados no grafo? Esta operação é irreversível."
⚠️ Excluir nós/arestas em lote	Exclusão em massa incondicional de todos os nós ou arestas	"Tem certeza de que deseja excluir todos os nós/arestas em lote? Esta operação é irreversível."

Se um usuário solicitar qualquer uma das operações de alto risco acima, a confirmação explícita deve ser obtida: "Esta é uma operação de alto risco e requer sua confirmação explícita. Por favor, responda com 'confirmar' para prosseguir."

Linguagens de Consulta Cypher e GQL

GES suporta duas linguagens de consulta: Cypher (compatível com Neo4j) e GQL (linguagem de consulta de grafo padrão internacional).

O guia de uso completo (exemplos Python/Node.js, execução inline skill action=exec, instruções Cypher/GQL comuns e a tabela de diferenças Cypher↔GQL) está em references/cypher-gql-guide.md.

Fluxo de Trabalho

Tarefa 1: Consultar o Grafo (somente leitura, o agente pode executar automaticamente)

1. Escolha um runtime: Python (`ges_graph_skill.py`) ou Node.js (`ges_graph_skill.js`). Ambos expõem a mesma API.
2. Carregue a configuração (env vars > `references/ges_env.csv.example`) — execute as verificações inline abaixo uma vez por sessão.
3. Execute uma consulta Cypher ou GQL via `execute_query()` / `execute_gql()` (ou `executeCypher` / `executeGql` em Node.js).
4. Retorne o envelope JSON unificado `{"results": [...], "errors": []}` para o usuário.

Execução inline (sem arquivos temporários): prefira execução inline em vez de criar arquivos de script temporários. Por exemplo, execute a consulta Python a partir do diretório da skill:

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 mais exemplos de skill action=exec inline.

Tarefa 2: Editar Dados do Grafo (adicionar/atualizar/excluir nós e arestas)

1. Valide que os valores das propriedades são escalares JSON (string/number/boolean/null) — o código impõe isso (ISSUE-002).
2. Chame o método CRUD correspondente (`add_node`/`update_node`/`delete_node`, `add_edge`/`delete_edge`).
3. Para importações em massa, respeite o limite de 500 nós por chamada (divida em partes, ISSUE-010).
4. Retorne o resultado da operação (o envelope unificado ou um resumo `{id, ...}`).

Tarefa 3: Operações de Alto Risco (exigem confirmação explícita do usuário)

1. `clear_graph()` ou qualquer exclusão em massa não qualificada é BLOQUEADA no nível Cypher por `validateCypher()`.
2. Para limpar todo o grafo, chame `clear_graph()` (ou `clearGraph()` em Node.js) com `allow_destructive=True`.
3. ANTES de executar, pergunte ao usuário: "Esta é uma operação de alto risco e requer sua confirmação explícita. Por favor, responda com 'confirmar' para prosseguir."
4. Somente após a confirmação, execute e retorne o id do job / resultado.

Tarefa 4: Importar / Exportar Dados do Grafo (jobs assíncronos)

1. Prepare os caminhos OBS para os arquivos de esquema/vértice/aresta (`import_graph`) ou um caminho de exportação (`export_graph`).
2. Submeta o job — um `{"jobId": ...}` é retornado imediatamente.
3. Faça polling de `get_job_status(jobId)` até que o job atinja um estado terminal.
4. Reporte o status e qualquer mensagem de erro do job para o usuário.

Verificação e aceitação: verificações detalhadas de aprovação/reprovação estão em references/verification-method.md e references/acceptance-criteria.md.

Interfaces Principais (Comandos Principais)

Consulta Cypher

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

# Executar uma consulta Cypher com parâmetros
resultado = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "João"}
)

Operações com Vértices

# Adicionar um nó
resultado = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "Usuário disse Olá", "timestamp": 1234567890}
)

# Adicionar um nó de forma idempotente (upsert). Nó existe → atualiza propriedades; senão → cria (ISSUE-004)
resultado = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory"],
    properties={"content": "Conteúdo atualizado"},
    upsert=True
)

# Adicionar nós em lote (máx. 500 por chamada, limite de segurança ISSUE-010)
resultado = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "teste1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "teste2"}}
])

# Obter um nó
resultado = skill.client.get_node("mem_001")

# Atualizar um nó
resultado = skill.client.update_node("mem_001", {"content": "Novo conteúdo"})

# Excluir um nó
resultado = skill.client.delete_node("mem_001")

Operações com Arestas

# Adicionar uma aresta
resultado = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELACIONADO_A",
    properties={"weight": 0.8}
)

# Excluir uma aresta
resultado = skill.client.delete_edge("mem_001", "mem_002", "RELACIONADO_A")

# Obter arestas de um nó
resultado = skill.client.get_edges("mem_001", direction="both")

Operações com Rótulos

# Adicionar um rótulo a um nó
resultado = skill.client.add_label_to_node("mem_001", "importante")

# Consultar nós por rótulo
resultado = skill.client.get_nodes_by_label("Memory", limit=100)

Gerenciamento do Grafo

# Obter informações do esquema
resultado = skill.get_schema_info()

# Obter estatísticas do grafo
resultado = skill.get_statistics()

# Limpar todos os dados no grafo (operação perigosa, requer confirmação do usuário)
resultado = skill.client.clear_graph()

Importação/Exportação

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

# Exportar dados do grafo (access_key/secret_key são lidos de config/ges_env.csv automaticamente)
job_id = skill.client.export_graph(
    export_path="obs://bucket/export",
    vertex_set_name="set_vertex",
    edge_set_name="set_edge"
)

Guia de Sintaxe GES

Manipulação de ID de Nó

GES usa a propriedade especial _ID_ para manipular IDs de nós do tipo string:

• Criar nós usa a propriedade _ID_:

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

• Outras operações usam a função 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 exige que o esquema (Rótulos e Propriedades) seja definido antes que os nós correspondentes possam ser criados. O esquema pode ser definido através de:

1. Criando Rótulos e propriedades através do console de gerenciamento GES
2. Importando dados com esquema através da interface de importação

Confirmação de Parâmetros

Antes de executar qualquer tarefa, os seguintes parâmetros devem ser confirmados com o usuário. Adivinhação é proibida.

Parâmetro	Obrigatório/Opcional	Descrição	Padrão
Instância de grafo	Obrigatório	GES_GRAPH_IP / GES_GRAPH_PORT / GES_GRAPH_NAME / GES_PROJECT_ID — em qual instância GES operar	Da configuração env/CSV
Instrução de consulta	Obrigatório	Instrução Cypher ou GQL, mais um dicionário de parâmetros escalares JSON	-
Propriedades de nó/aresta	Obrigatório para escritas	Apenas escalares JSON (string/number/boolean/null) aceitos	-
Escopo da operação	Obrigatório para operações de alto risco	clear_graph / exclusão em massa requerem confirmação explícita do usuário	-
Caminhos de importação/exportação	Obrigatório	Caminhos de bucket/objeto OBS para os arquivos de esquema/vértice/aresta	-

Nota: os parâmetros de conexão são lidos do ambiente ou de config/ges_env.csv (references/ges_env.csv.example); eles nunca precisam ser passados por chamada.

Formato de Resposta

Todas as interfaces Cypher retornam um formato JSON unificado:

{
  "results": [
    {
      "columns": ["coluna1", "coluna2"],
      "data": [
        {"row": ["valor1", "valor2"], "meta": [null, null]}
      ]
    }
  ],
  "errors": []
}