docs: unify client navi struct and streamline GQL docs (EN/CN)

.gitignore

@@ -35,6 +35,7 @@ GEMINI.md
 .gemini/
 WARP.md
 /.goal-task
+/.agents
 
 __pycache__/
 *.pyc

content/cn/blog/hugegraph/toplingdb/_index.md

@@ -6,5 +6,5 @@ icon: fa-solid fa-hard-drive
 ---
 
 > **历史集成。** 2025 年的文章介绍较早的接口，保留供参考。
-> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/toplingdb/)。
+> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/dev-test/toplingdb/)。
 > 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。

content/cn/blog/hugegraph/toplingdb/toplingdb-configuration-yaml.md

@@ -9,7 +9,7 @@ series_weight: 2
 ---
 
 > **历史集成。** 2025 年的文章介绍较早的接口，保留供参考。
-> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/toplingdb/)。
+> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/dev-test/toplingdb/)。
 > 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。
 
 

content/cn/blog/hugegraph/toplingdb/toplingdb-quick-start.md

@@ -10,7 +10,7 @@ series_weight: 1
 ---
 
 > **历史集成。** 2025 年的文章介绍较早的接口，保留供参考。
-> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/toplingdb/)。
+> 候选替代方案见 [ToplingDB 开发版指南](/cn/docs/guides/dev-test/toplingdb/)。
 > 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。
 
 

content/cn/docs/SUMMARY.md

@@ -13,16 +13,17 @@ draft: true
 - [HugeGraph Server](quickstart/hugegraph/hugegraph-server)
 - [PD](quickstart/hugegraph/hugegraph-pd)
 - [HStore](quickstart/hugegraph/hugegraph-hstore)
-- [Java Client](quickstart/client/hugegraph-client)
-- [Go Client](quickstart/client/hugegraph-client-go)
-- [Python Client](quickstart/client/hugegraph-client-python)
+- [Java Client](clients/client/hugegraph-client)
+- [Go Client](clients/client/hugegraph-client-go)
+- [Python Client](clients/client/hugegraph-client-python)
 - [Loader](quickstart/toolchain/hugegraph-loader)
 - [Hubble](quickstart/toolchain/hugegraph-hubble)
 - [Spark Connector](quickstart/toolchain/hugegraph-spark-connector)
 - [Tools](quickstart/toolchain/hugegraph-tools)
 - [Vermeer](quickstart/computing/hugegraph-vermeer)
 - [Computer](quickstart/computing/hugegraph-computer)
 - [HugeGraph-AI](quickstart/hugegraph-ai/quick_start)
+  - [HugeGraph-LLM SDK](quickstart/hugegraph-ai/hugegraph-llm-sdk)
 
 ## Server 配置与 API
 
@@ -35,14 +36,15 @@ draft: true
 
 ## 使用指南
 
-- [架构](guides/architectural)
-- [设计](guides/desgin-concept)
+- [架构](guides/architectural/_index)
+  - [自定义插件](guides/architectural/custom-plugin)
+  - [设计](guides/architectural/desgin-concept)
 - [备份与恢复](guides/backup-restore)
-- [自定义插件](guides/custom-plugin)
 - [Docker 集群](guides/hugegraph-docker-cluster)
 - [安全](guides/security)
-- [Toolchain 本地测试](guides/toolchain-local-test)
-- [ToplingDB（开发版）](guides/toplingdb)
+- [开发测试](guides/dev-test/_index)
+  - [Toolchain 本地测试](guides/dev-test/toolchain-local-test)
+  - [ToplingDB (开发版)](guides/dev-test/toplingdb)
 - [常见问题](guides/faq)
 
 ## 查询语言

content/cn/docs/clients/_index.md

@@ -1,10 +1,24 @@
 ---
 title: "客户端与 API"
-description: "通过 Java 客户端、REST API、Gremlin Console 和其他客户端库连接 HugeGraph。"
+description: "通过 RESTful API、多语言客户端/SDK 与 Gremlin Console 连接并操作 HugeGraph。"
 linkTitle: "客户端与 API"
 weight: 5
-search_keywords: [HugeGraph 客户端, Java 客户端, 客户端库]
+search_keywords: [HugeGraph 客户端, RESTful API, Java 客户端, 客户端/SDK, Gremlin Console]
 search_boost: 1.5
+no_list: true
 ---
 
-本节包含 REST API、Gremlin Console 和客户端说明。当前 Server REST API 使用图空间和图名称组成资源路径；具体路径以各 API 页面和 Server 的 OpenAPI 页面为准。
+HugeGraph 提供多层次的访问与接入方式，涵盖标准化 RESTful API、多语言客户端/SDK 以及命令行交互式控制台。当前 Server REST API 使用图空间（GraphSpace）和图名称组成资源路径；具体路径以各 API 页面和 Server 的 OpenAPI 页面为准。
+
+## 模块指引
+
+- [RESTful API](/cn/docs/clients/restful-api/)
+
+  基于 HTTP 的 REST 接口规范，覆盖图空间管理、元数据定义、顶点与边 CRUD、任务管理、指标监控等全量服务端能力。
+- [客户端/SDK](/cn/docs/clients/client/)
+
+  提供 Java、Python、Go 等语言的官方客户端 SDK，支持管理 Schema、读写顶点与边数据、执行 Gremlin 查询及调用高级图算法。
+- [Gremlin Console](/cn/docs/clients/gremlin-console/)
+
+  基于 Apache TinkerPop 的交互式命令行控制台，适合离线图操作、连接 Server 调试脚本与快速验证图遍历。
+{.cards}

content/cn/docs/clients/client/_index.md

@@ -0,0 +1,30 @@
+---
+title: "客户端/SDK"
+linkTitle: "客户端/SDK"
+weight: 2
+description: "HugeGraph 官方多语言客户端 SDK（Java、Python、Go 等）概览与接入指引。"
+aliases:
+  - /docs/quickstart/client/
+---
+
+HugeGraph 提供多语言客户端 SDK，方便在不同语言与技术栈中连接 HugeGraph Server，进行 Schema 管理、顶点与边数据读写、Gremlin 遍历及高级分析。
+
+## 支持的客户端
+
+- [HugeGraph Java Client](/cn/docs/clients/client/hugegraph-client/)
+
+  官方核心 Java SDK，提供与 Gremlin 语法相近的 API 风格，支持完整的 Schema 管理、CRUD、Gremlin 查询及 Traverser 算法，并支持 GraphSpace 隔离。
+- [HugeGraph Python Client](/cn/docs/clients/client/hugegraph-client-python/)
+
+  官方 Python SDK（`pyhugegraph`），位于 HugeGraph-AI 仓库，支持管理 Schema、读写图数据及提交 Gremlin 查询，深度集成 HugeGraph-LLM 与 HugeGraph-ML。
+- [HugeGraph Go Client](/cn/docs/clients/client/hugegraph-client-go/)
+
+  官方 Go SDK，支持版本查询、Schema 定义（PropertyKey/VertexLabel/EdgeLabel）、顶点操作与 Gremlin 查询。
+{.cards}
+
+## 选择建议
+
+- **生产级 Java/Scala 服务**：推荐使用 **HugeGraph Java Client**，功能最完备，覆盖所有底层能力与连接池管理。
+- **AI/LLM/算法与数据科学应用**：推荐使用 **HugeGraph Python Client**（`pyhugegraph`），深度适配 HugeGraph-LLM、HugeGraph-ML 及 Python 数据科学分析工作流。
+- **微服务与云原生工具构建**：推荐使用 **HugeGraph Go Client** 或直接调用 [RESTful API](/cn/docs/clients/restful-api/)。
+- **终端离线调试或临时查询**：推荐使用 [Gremlin Console](/cn/docs/clients/gremlin-console/)。

content/cn/docs/quickstart/client/hugegraph-client-go.md → content/cn/docs/clients/client/hugegraph-client-go.md

@@ -2,6 +2,8 @@
 title: "HugeGraph Go 客户端快速入门"
 linkTitle: "Go 客户端"
 weight: 3
+aliases:
+  - /docs/quickstart/client/hugegraph-client-go/
 ---
 
 HugeGraph Go Client 是 Toolchain 仓库中的 Go SDK，目前提供版本查询、Schema（PropertyKey、VertexLabel、EdgeLabel）、顶点和 Gremlin API。边数据 API 尚未实现。

content/cn/docs/quickstart/client/hugegraph-client-python.md → content/cn/docs/clients/client/hugegraph-client-python.md

@@ -2,6 +2,8 @@
 title: "HugeGraph Python 客户端快速上手"
 linkTitle: "Python 客户端"
 weight: 2
+aliases:
+  - /docs/quickstart/client/hugegraph-client-python/
 ---
 
 `hugegraph-python-client` 是 HugeGraph 的 Python SDK，可管理 Schema、读写图数据并执行 Gremlin 查询。HugeGraph-LLM 和 HugeGraph-ML 也使用这个客户端。
@@ -10,7 +12,7 @@ weight: 2
 
 ## 环境要求
 
-- 客户端与 HugeGraph-AI workspace 均要求 Python 3.10 或更高版本，CI 在 3.10 和 3.11 上运行客户端测试。
+- 客户端与 HugeGraph-AI workspace 均要求 Python >= 3.12（支持 Python 3.12–3.14）。
 - HugeGraph Server 1.5.0 或更高版本。客户端会拒绝连接更低版本的 Server，此类场景请改用 v1.3.x 客户端。
 - `uv`（推荐）或 `pip`