⚠️ 執行方式（必讀）：此技能透過
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/標籤管理、摘要資訊查詢、圖形資料編輯等核心功能。
目錄結構
目錄慣例如下（所有路徑皆相對於技能目錄）：
scripts/- 包含 Python 和 Node.js 執行腳本ges_graph_skill.py- 用於 GES 圖形操作的 Python SDKges_graph_skill.js- 用於 GES 圖形操作的 Node.js SDK
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 Token 方法與 GitCode API Token 認證chaining-protocol.md- 統一回傳封裝與鏈式呼叫合約
先決條件
使用此技能前，請確保符合以下條件：
1. 執行環境
支援 Python 或 Node.js 執行環境。 需要 Python 3.8+ 或 Node.js 14+。
Python 依賴：requests（pip install requests）。可選擇安裝 huaweicloudsdkges
（pip install huaweicloudsdkges）以進行 SDK 層級呼叫（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 | 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 |
支援三種方法（優先權由高至低）：
- 環境變數
GES_TOKEN - AKSK 方法（
HUAWEI_CLOUD_AK+HUAWEI_CLOUD_SK或access_key+secret_key） - 密碼方法（使用者名稱 + 密碼 + 網域名稱）
⛔ 禁止操作（安全護欄）
本技能在程式碼層面強制執行安全護欄（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、密碼、Token 或其他敏感資訊 | 存在敏感資訊洩露風險 |
以下高風險操作需要在執行前取得代理明確確認：
| 高風險操作 | 說明 | 確認提示 |
|---|---|---|
| ⚠️ 清除所有圖形資料 | clear_graph() 或類似的清除操作 | 「您確定要清除圖形中的所有資料嗎？此操作不可逆。」 |
| ⚠️ 批次刪除節點/邊 | 無條件的大量刪除所有節點或邊 | 「您確定要批次刪除所有節點/邊嗎？此操作不可逆。」 |
如果使用者要求執行上述任何高風險操作，必須取得明確確認： 「這是一項高風險操作，需要您的明確確認。請回覆 'confirm' 以繼續。」
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()` 或任何無條件的批次刪除會在 Cypher 層級被 `validateCypher()` 攔截。
2. 若要清除整個圖形，請呼叫 `clear_graph()`（或在 Node.js 中為 `clearGraph()`），並帶入 `allow_destructive=True`。
3. 在執行之前，詢問使用者：「這是一項高風險操作，需要您的明確確認。請回覆 'confirm' 以繼續。」
4. 只有在收到確認後，才執行並回傳任務 ID / 結果。
任務 4：匯入/匯出圖形資料（非同步任務）
1. 準備好 Schema/頂點/邊檔案的 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)
圖形管理
# 取得 Schema 資訊
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
Schema 需求
GES 要求在建立對應節點之前，必須先定義 Schema（標籤和屬性）。Schema 可以透過以下方式定義：
- 透過 GES 管理主控台建立標籤和屬性
- 透過匯入介面匯入帶有 Schema 的資料
參數確認
在執行任何任務之前，必須先與使用者確認以下參數。禁止猜測。
| 參數 | 必要/可選 | 說明 | 預設值 |
|---|---|---|---|
| 圖形實例 | 必要 | GES_GRAPH_IP / GES_GRAPH_PORT / GES_GRAPH_NAME / GES_PROJECT_ID — 要操作哪個 GES 實例 | 來自環境/CSV 配置 |
| 查詢語句 | 必要 | Cypher 或 GQL 語句，以及 JSON 純量參數字典 | - |
| 節點/邊屬性 | 寫入時必要 | 僅接受 JSON 純量（字串/數字/布林/null） | - |
| 操作範圍 | 高風險操作時必要 | clear_graph / 批次刪除需要使用者明確確認 | - |
| 匯入/匯出路徑 | 必要 | Schema/頂點/邊檔案的 OBS 儲存桶/物件路徑 | - |
注意：連線參數會從環境變數或
config/ges_env.csv(references/ges_env.csv.example) 讀取；每次呼叫時不需要傳遞。
回應格式
所有 Cypher 介面都會回傳統一的 JSON 格式：
{
"results": [
{
"columns": ["column1", "column2"],
"data": [
{"row": ["value1", "value2"], "meta": [null, null]}
]
}
],
"errors": []
}
詳細的暴力攻擊防護、金鑰輪換、會話管理、IAM 政策等內容已從此文件移除，以利翻譯。 完整的安全與操作指南請參閱
references/目錄。
支援的語言
| 語言 | 執行腳本 | 備註 |
|---|---|---|
| Python | ges_graph_skill.py | 建議使用，語法簡潔 |
| Node.js | ges_graph_skill.js | 適用於 JavaScript/TypeScript 生態系統 |
疑難排解
常見問題
-
連線被拒：檢查
GES_GRAPH_IP和GES_GRAPH_PORT是否正確，以及 GES 實例是否正在執行。 -
認證失敗：
- 確認 AK/SK 或使用者名稱/密碼是否正確
- 檢查
GES_PROJECT_ID和GES_REGION是否與您的 GES 實例相符 - 嘗試使用
GES_TOKEN環境變數直接設定 Token
-
查詢逾時：
- 較大的圖形可能需要更長的查詢時間，請考慮使用 LIMIT 子句
- 透過管理主控台檢查 GES 實例的資源使用情況
-
Schema 錯誤：
- 確保在建立節點之前已經定義了標籤和屬性
- 使用
get_schema_info()檢查目前的 Schema 狀態
安全注意事項
- 永遠不要在日誌或錯誤訊息中列印或記錄憑證
- 使用環境變數或安全的金鑰管理系統管理憑證
- 對於生產環境，建議使用 IAM 角色或服務帳戶，而不是長期金鑰
- 定期輪換存取金鑰
相關技能
huaweicloud/huawei-cloud-obs：用於管理 OBS 儲存桶，這是匯入/匯出圖形資料的必備條件huaweicloud/huawei-cloud-iam：用於管理 IAM 使用者和權限，這是 GES 存取控制的必備條件