huawei-cloud-ges-graph

⚠️ 执行方式（必读）：此技能通过 scripts/ 下的本地 Python 或 Node.js 脚本执行查询。禁止直接调用 API。

• 查询脚本位于技能目录下的 scripts/ 中（例如 scripts/ges_graph_skill.py）
• 所有脚本和环境检查脚本都位于技能包内。必须使用 skill action=exec 执行；不要直接在 shell 中运行
• 优先使用内联执行（python -c 或 node -e），而不是创建临时脚本文件。请参阅下方的“内联执行（无需临时文件）”部分。
• 所有路径都相对于技能目录，即存放此 SKILL.md 的目录

GES 图访问指南

概述

华为云图引擎服务（GES）持久版的原子能力， 提供图数据库操作访问指南。 涵盖 Cypher 查询、GQL 查询、Schema/标签管理、摘要信息查询、图数据编辑及其他核心能力。

目录结构

目录约定如下（所有路径都相对于技能目录）：

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 - 环境配置模板

先决条件

使用此技能前，请确保满足以下条件：

1. 运行环境

支持 Python 或 Node.js 运行环境。 需要 Python 3.8+ 或 Node.js 14+。

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	Token（优先级最高）	可选

• AK/SK 认证需要 AK/SK。 ** 未提供 AK/SK 时，才需要用户名/密码。

配置文件（.env/ges_env.csv）

配置文件路径：.env/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

• AKSK 认证需要 access_key/secret_key。 ** 未提供 AKSK 时，才需要 username/password/domain_name。

按区域划分的 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）

⛔ 禁止的操作（安全防护）

本技能禁止以下操作：

禁止的操作	描述	原因
❌ 打印敏感凭证	打印 AK/SK、密码、令牌或其他敏感信息	存在敏感信息泄露风险

以下高风险操作需要在执行前获得 Agent 的明确确认：

高风险操作	描述	确认提示
⚠️ 清除所有图数据	clear_graph() 或类似清除操作	“确定要清除图中的所有数据吗？此操作不可逆。”
⚠️ 批量删除节点/边	无条件批量删除所有节点或边	“确定要批量删除所有节点/边吗？此操作不可逆。”

如果用户请求执行上述任何高风险操作，必须先获得明确确认： “此操作属于高风险操作，需要您的明确确认。请回复 ‘confirm’ 以继续。”

Cypher 和 GQL 查询语言

GES 支持两种查询语言：Cypher（兼容 Neo4j）和 GQL（国际标准图查询语言）。

Cypher 用法

Python：

# Execute a Cypher query
result = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Create a node (_ID_ is used only during creation to set a custom ID)
result = skill.execute_query(
    "CREATE (n:Person {_ID_: 'p001', name: '张三'}) RETURN n"
)

# Match query
result = skill.execute_query(
    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = '张三' RETURN m"
)

# Update a node (match via id() function)
result = skill.execute_query(
    "MATCH (n) WHERE id(n) = 123 SET n.name = '李四' RETURN n"
)

# Delete a node
result = skill.execute_query(
    "MATCH (n) WHERE id(n) = 123 DETACH DELETE n"
)

# Aggregate query
result = skill.execute_query(
    "MATCH (n:Person) RETURN n.city, count(*) as cnt ORDER BY cnt DESC"
)

Node.js：

const { GESGraphSkill } = require('./ges_graph_skill.js');
const skill = new GESGraphSkill();

// Execute a Cypher query
const result = await skill.executeQuery("MATCH (n) RETURN n LIMIT 10");

// Create a node (_ID_ is used only during creation to set a custom ID)
const result = await skill.executeQuery(
    "CREATE (n:Person {_ID_: 'p001', name: '张三'}) RETURN n"
);

// Match query
const result = await skill.executeQuery(
    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = '张三' RETURN m"
);

// Update a node
const result = await skill.executeQuery(
    "MATCH (n) WHERE id(n) = 123 SET n.name = '李四' RETURN n"
);

// Delete a node
const result = await skill.executeQuery(
    "MATCH (n) WHERE id(n) = 123 DETACH DELETE n"
);

// Aggregate query
const result = await skill.executeQuery(
    "MATCH (n:Person) RETURN n.city, count(*) as cnt ORDER BY cnt DESC"
);

// Path query
const result = await skill.executeQuery(
    "MATCH p=(n:Person)-[*1..3]->(m) WHERE n.name = '张三' RETURN p"
);

内联执行（无需临时文件）

无需创建任何脚本文件，即可通过 skill action=exec 直接执行 Cypher 查询。

**注意：**通过 skill action=exec 运行时，工作目录为项目根目录。已安装的技能位于 .agents/skills/huawei-cloud-ges-graph 下，而不是 skills/ai/ges/ 下。

Python：

skill exec py -c "
import sys, os; cwd=os.getcwd()
skill_dir = os.path.join(cwd, '.agents', 'skills', 'huawei-cloud-ges-graph')
sys.path.insert(0, os.path.join(skill_dir, 'scripts'))
from ges_graph_skill import get_skill
import json
r = get_skill().execute_query('MATCH (n) RETURN n LIMIT 5')
print(json.dumps(r, ensure_ascii=False, indent=2))
"

Node.js：

skill exec node -e "
const path = require('path');
const cwd = process.cwd();
const scriptPath = path.join(cwd, '.agents', 'skills', 'huawei-cloud-ges-graph', 'scripts', 'ges_graph_skill.js');
const { GESGraphSkill } = require(scriptPath);
(async () => {
    const r = await new GESGraphSkill().executeQuery('MATCH (n) RETURN n LIMIT 5');
    console.log(JSON.stringify(r, null, 2));
})();
"

常见 Cypher 语句

类别	语句	描述
架构	call db.schema()	获取图架构信息
索引	call db.indexes()	查看所有索引
终止查询	call dbms.killQuery('queryId')	终止正在运行的查询
运行中的查询	call dbms.listQueries()	查看当前查询
系统参数	call dbms.parameter('needNodeIndex', false)	移除索引约束（大型图场景）

GQL 用法（本技能支持）

GQL 是 ISO/IEC 39075 标准化的图查询语言。GES 通过 action_id=execute-gql-query 调用它。

# GQL requires the underlying _request method
client = GESClient()
result = client._request('POST', '/action?action_id=execute-gql-query', json={
    "statements": [{
        "statement": "INSERT (n:Person{_ID_:'p001', firstName:'Eywa'}) RETURN n",
        "parameters": {},
        "resultDataContents": ["row"]
    }]
})

常见 GQL 语句

类别	语句	描述
插入	INSERT (n:Person{_ID_:'p001', firstName:'Eywa'}) RETURN n	插入节点
匹配	MATCH (n:Person WHERE element_id(n)='p001') RETURN n	条件匹配
更新	MATCH (n:Person WHERE element_id(n)='p001') SET n.lastName='Higgo' RETURN n	更新属性
移除属性	MATCH (n:Person WHERE element_id(n)='p001') REMOVE n.lastName RETURN n	移除属性
删除节点	MATCH (n:Person WHERE element_id(n)='p001') DELETE n	删除节点
筛选	MATCH (n:Person)-[:KNOWS]->(m) FILTER element_id(n)='7933' AND m.gender='male' RETURN m	筛选结果
FOR 循环	FOR a IN [1,2,3] RETURN a	循环语句
LET 变量	LET a = 1, b = 2 RETURN a, b	变量定义
UNION	... UNION ALL ...	合并结果集

Cypher 与 GQL 的主要区别

特性	Cypher	GQL
内部 ID	id(n)	element_id(n)
自定义 ID（仅插入时）	_ID_ 属性	_ID_ 属性
节点匹配	MATCH (n)	MATCH (n WHERE ...)
SET 语句	SET n.prop = value	SET n.prop = value
移除属性	REMOVE n.prop	REMOVE n.prop
循环	不支持	FOR x IN [...]
变量定义	不支持	LET x = value

Cypher 查询

# Execute a Cypher query
result = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Execute a Cypher query with parameters
result = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "张三"}
)

顶点操作

# Add a node
result = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "User said Hello", "timestamp": 1234567890}
)

# Batch add nodes
result = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "test1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "test2"}}
])

# Get a node
result = skill.client.get_node("mem_001")

# Update a node
result = skill.client.update_node("mem_001", {"content": "New content"})

# Delete a node
result = skill.client.delete_node("mem_001")

边操作

# Add an edge
result = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELATED_TO",
    properties={"weight": 0.8}
)

# Delete an edge
result = skill.client.delete_edge("mem_001", "mem_002", "RELATED_TO")

# Get edges of a node
result = skill.client.get_edges("mem_001", direction="both")

标签操作

# Add a label to a node
result = skill.client.add_label_to_node("mem_001", "important")

# Query nodes by label
result = skill.client.get_nodes_by_label("Memory", limit=100)

图管理

# Get schema information
result = skill.get_schema_info()

# Get graph statistics
result = skill.get_statistics()

# Clear all data in the graph (dangerous operation)
result = skill.clear_all_memories()

导入/导出

# Import graph data
job_id = skill.client.import_graph(
    schema_path="obs://bucket/schema.xml",
    vertex_path="obs://bucket/vertex",
    edge_path="obs://bucket/edge"
)

# Export graph data (access_key/secret_key are read from .env automatically)
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
  

Schema 要求

GES 要求先定义 Schema（标签和属性），然后才能创建对应的节点。可通过以下方式定义 Schema：

1. 通过 GES 管理控制台创建标签和属性
2. 通过导入界面导入包含 Schema 的数据

响应格式

所有 Cypher 接口均返回统一的 JSON 格式：

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

错误处理

from ges_graph_skill import get_skill

skill = get_skill()
try:
    result = skill.execute_query("MATCH (n) RETURN n")
except Exception as e:
    print(f"Error: {e}")

重要说明

1. Token 有效期：Token 的有效期为 24 小时；代码会自动刷新
2. Schema 约束：创建节点前，请确保已定义标签和属性
3. 危险操作：clear_graph() 会删除图中的所有数据；请谨慎使用
4. 异步操作：对于大型数据的导入/导出，建议使用异步模式

参考文档

• 配置文件格式：references/ges_env.csv.example — 环境配置文件模板和字段说明
• 图数据库格式：https://support.huaweicloud.com/usermanual-ges/ges_01_0153.html — GES 图数据格式详细文档
• 如何访问业务 API：https://support.huaweicloud.com/api-ges/ges_03_0112.html — GES 业务 API 访问指南