huaweicloud/huawei-cloud-ges-graph

⚠️ 실행 방법 (필독): 이 스킬은 scripts/ 디렉토리 아래의 로컬 Python 또는 Node.js 스크립트를 통해 쿼리를 실행합니다. 직접 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). 선택적으로, SDK 수준 호출을 위해 huaweicloudsdkges 를 설치할 수 있습니다 (pip install huaweicloudsdkges, ISSUE-013); 내장 HTTP 클라이언트를 통해 이 패키지 없이도 스킬이 작동합니다. Node.js의 경우, 외부 npm 패키지가 필요하지 않습니다 (표준 라이브러리 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

세 가지 방법이 지원됩니다 (우선순위 높음에서 낮음 순):

1. 환경 변수 GES_TOKEN
2. AKSK 방법 (HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK 또는 access_key + secret_key)
3. 비밀번호 방법 (사용자 이름 + 비밀번호 + 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() 또는 유사한 지우기 작업	"그래프의 모든 데이터를 지우시겠습니까? 이 작업은 되돌릴 수 없습니다."
⚠️ 노드/엣지 일괄 삭제	모든 노드 또는 엣지의 무조건적 대량 삭제	"모든 노드/엣지를 일괄 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다."

사용자가 위 고위험 작업 중 하나를 요청하는 경우, 명시적 확인을 받아야 합니다: "이것은 고위험 작업이므로 명시적 확인이 필요합니다. 계속하려면 '확인'이라고 답변해 주세요."

Cypher 및 GQL 쿼리 언어

GES는 두 가지 쿼리 언어를 지원합니다: 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`) — 세션당 한 번 아래 인라인 검사를 실행합니다.
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. 대량 가져오기의 경우 호출당 500노드 제한을 준수합니다 (청크로 분할, ISSUE-010).
4. 작업 결과를 반환합니다 (통합 봉투 또는 `{id, ...}` 요약).

작업 3: 위험-고 작업 (사용자의 명시적 확인 필요)

1. `clear_graph()` 또는 자격 없는 대량 삭제는 `validateCypher()`에 의해 Cypher 수준에서 차단됩니다.
2. 전체 그래프를 지우려면 `allow_destructive=True`와 함께 `clear_graph()`(또는 Node.js의 `clearGraph()`)를 호출하세요.
3. 실행 전에 사용자에게 물어보세요: "이것은 고위험 작업이므로 명시적 확인이 필요합니다. 계속하려면 '확인'이라고 답변해 주세요."
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}
)

# 멱등적으로 노드 추가 (upsert). 노드가 존재하면 속성 업데이트; 그렇지 않으면 생성 (ISSUE-004)
result = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory"],
    properties={"content": "Updated content"},
    upsert=True
)

# 노드 일괄 추가 (호출당 최대 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": []
}