From d8b613c779cdcc43f0bc857e118198ac42ee2aad Mon Sep 17 00:00:00 2001
From: wklken <wklken@gmail.com>
Date: Tue, 11 Aug 2026 16:48:10 +0800
Subject: [PATCH 1/2] docs(apigw-manager): document AI gateway names

Explain how to set kind: ai for automated gateway sync and list the accepted bkai-, bkaidev, and bkaidev-* creation names.

Clarify near-miss names, the non-AI bkai- restriction, and update compatibility without changing the existing normal gateway example.
---
 sdks/apigw-manager/docs/sync_apigateway.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/sdks/apigw-manager/docs/sync_apigateway.md b/sdks/apigw-manager/docs/sync_apigateway.md
index c250cfb9..946ae59c 100644
--- a/sdks/apigw-manager/docs/sync_apigateway.md
+++ b/sdks/apigw-manager/docs/sync_apigateway.md
@@ -294,6 +294,28 @@ resource_docs:
   basedir: "{{ settings.BK_APIGW_RESOURCE_DOCS_BASE_DIR }}" # 环境变量方式："{{ environ.BK_APIGW_RESOURCE_DOCS_BASE_DIR }}"
 ```
 
+#### AI 网关自动化同步
+
+自动化同步创建 AI 网关时，在 `definition.yaml` 的 `apigateway` 配置中指定 `kind: "ai"`：
+
+```yaml
+apigateway:
+  description: "AI 网关"
+  description_en: "AI Gateway"
+  is_public: true
+  kind: "ai"
+  maintainers:
+    - "admin"
+```
+
+新建 AI 网关时，通过同步命令传入的网关名称须满足以下任一规则：
+
+- 以 `bkai-` 开头，例如 `bkai-chat`
+- 等于 `bkaidev`
+- 以 `bkaidev-` 开头，例如 `bkaidev-chat`
+
+`bkaidevx`、`bkaidevfoo` 等名称不属于 `bkaidev-*` 规则。非 AI 网关不能使用 `bkai-` 前缀；以上名称与类型约束仅在新建网关时生效，更新已有网关不受影响。
+
 **注意：**
 
 - 同步资源或者环境相关配置后，需要创建版本并发布才能生效，发布数据定义于 definition.yaml `release`

From aac51dddaf0b095a4ed065a46d0e0c046e667845 Mon Sep 17 00:00:00 2001
From: wklken <wklken@gmail.com>
Date: Tue, 11 Aug 2026 17:07:55 +0800
Subject: [PATCH 2/2] docs(apigw-manager): keep AI name exceptions implicit

Document only the public bkai- naming rule while retaining the AI gateway kind configuration example.
---
 sdks/apigw-manager/docs/sync_apigateway.md | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/sdks/apigw-manager/docs/sync_apigateway.md b/sdks/apigw-manager/docs/sync_apigateway.md
index 946ae59c..e07624ae 100644
--- a/sdks/apigw-manager/docs/sync_apigateway.md
+++ b/sdks/apigw-manager/docs/sync_apigateway.md
@@ -308,13 +308,7 @@ apigateway:
     - "admin"
 ```
 
-新建 AI 网关时，通过同步命令传入的网关名称须满足以下任一规则：
-
-- 以 `bkai-` 开头，例如 `bkai-chat`
-- 等于 `bkaidev`
-- 以 `bkaidev-` 开头，例如 `bkaidev-chat`
-
-`bkaidevx`、`bkaidevfoo` 等名称不属于 `bkaidev-*` 规则。非 AI 网关不能使用 `bkai-` 前缀；以上名称与类型约束仅在新建网关时生效，更新已有网关不受影响。
+新建 AI 网关时，通过同步命令传入的网关名称须以 `bkai-` 开头，例如 `bkai-chat`。非 AI 网关不能使用 `bkai-` 前缀；以上名称与类型约束仅在新建网关时生效，更新已有网关不受影响。
 
 **注意：**