@cloudbase/cloudbase-mcp 2.25.4 → 2.25.5

package/dist/index.cjs

@@ -138355,7 +138355,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.25.4" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.5" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -162268,6 +162268,14 @@ function collectMigrationVersions(value, found = new Set()) {
 /** Brief retries before concluding a pushed migration never landed (Push can be async). */
 const MIGRATION_VERIFY_ATTEMPTS = 4;
 const MIGRATION_VERIFY_DELAY_MS = 1500;
+/** Page size when hydrating remote migration history into a Push/Preview payload. */
+const MIGRATION_LIST_PAGE_SIZE = 100;
+/**
+ * PushPGUserMigrations is async: poll DescribeTaskResult until Succeed/Failed.
+ * Aligns with CLI `tcb db pg migration up` and Manager SDK docs.
+ */
+const MIGRATION_TASK_POLL_INTERVAL_MS = 1500;
+const MIGRATION_TASK_MAX_WAIT_MS = 90_000;
 /**
  * Confirm a pushed migration version is present in the remote migration history.
  *
@@ -162301,6 +162309,99 @@ async function verifyMigrationApplied(context, version, cloudBaseOptions) {
     }
     return { applied: null, error: lastError };
 }
+function extractMigrationSummaries(history) {
+    const raw = history.Migrations;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const summaries = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const row = item;
+        const version = typeof row.Version === "string" ? row.Version.trim() : "";
+        const name = typeof row.Name === "string" ? row.Name.trim() : "";
+        if (version) {
+            summaries.push({ Version: version, Name: name || version });
+        }
+    }
+    return summaries;
+}
+/**
+ * List every remote migration summary (paginated). Required before Push/Preview:
+ * submitting only the pending migration while remote history exists yields
+ * Executable=false with Conflicts reason remote_history_not_found_locally, and the
+ * async task fails with "migration plan is not executable".
+ */
+async function listAllRemoteMigrationSummaries(context, cloudBaseOptions) {
+    const summaries = [];
+    let offset = 0;
+    let latestVersion = "";
+    let total = 0;
+    while (true) {
+        const page = await callPgMigrationApi(context, "ListPGUserMigrations", { Limit: MIGRATION_LIST_PAGE_SIZE, Offset: offset }, cloudBaseOptions);
+        const pageItems = extractMigrationSummaries(page);
+        summaries.push(...pageItems);
+        if (typeof page.LatestVersion === "string" && page.LatestVersion.trim()) {
+            latestVersion = page.LatestVersion.trim();
+        }
+        if (typeof page.Total === "number" && Number.isFinite(page.Total)) {
+            total = page.Total;
+        }
+        else {
+            total = summaries.length;
+        }
+        if (pageItems.length < MIGRATION_LIST_PAGE_SIZE) {
+            break;
+        }
+        offset += MIGRATION_LIST_PAGE_SIZE;
+    }
+    return { summaries, latestVersion, total };
+}
+/**
+ * Build Push/Preview Migrations = remote history Queries + the pending migration.
+ * Matches CLI behavior (submit full set; server skips already-applied versions).
+ */
+async function buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions) {
+    const { summaries, latestVersion } = await listAllRemoteMigrationSummaries(context, cloudBaseOptions);
+    const migrations = [];
+    for (const summary of summaries) {
+        if (summary.Version === pending.Version) {
+            // Caller supplies the authoritative SQL for this version.
+            continue;
+        }
+        const detail = await callPgMigrationApi(context, "DescribePGUserMigration", { MigrationVersion: summary.Version }, cloudBaseOptions);
+        const query = typeof detail.Query === "string" ? detail.Query : "";
+        if (!query.trim()) {
+            throw new Error(`DescribePGUserMigration returned empty Query for version=${summary.Version} (${summary.Name}). ` +
+                "Cannot hydrate remote history for PushPGUserMigrations.");
+        }
+        migrations.push({
+            Version: typeof detail.Version === "string" && detail.Version.trim() ? detail.Version.trim() : summary.Version,
+            Name: typeof detail.Name === "string" && detail.Name.trim() ? detail.Name.trim() : summary.Name,
+            Query: query,
+        });
+    }
+    migrations.push(pending);
+    return { migrations, remoteCount: summaries.length, latestVersion };
+}
+async function waitPgMigrationTask(context, taskId, cloudBaseOptions) {
+    const deadline = Date.now() + MIGRATION_TASK_MAX_WAIT_MS;
+    let last = { TaskId: taskId };
+    while (Date.now() <= deadline) {
+        last = (await callPgMigrationApi(context, "DescribeTaskResult", { TaskId: taskId }, cloudBaseOptions));
+        const status = String(last.Status || "").toLowerCase();
+        if (status === "succeed" || status === "failed") {
+            return last;
+        }
+        await sleep(MIGRATION_TASK_POLL_INTERVAL_MS);
+    }
+    const error = new Error(`DescribeTaskResult timed out after ${Math.floor(MIGRATION_TASK_MAX_WAIT_MS / 1000)}s ` +
+        `for TaskId=${taskId} (last Status=${last.Status || "-"}, Phase=${last.Phase || "-"}).`);
+    error.lastTask = last;
+    throw error;
+}
 const MIGRATION_VERSION_REQUIRED_MESSAGE = "migrationVersion is required (14-digit UTC timestamp YYYYMMDDHHMMSS). " +
     "Decide the version first, write local file migrations/<version>_<migrationName>.sql, " +
     "then call planMigration/applyMigration with the same migrationVersion and migrationName.";
@@ -163087,29 +163188,38 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
+        pending.Rollback = args.rollbackSql;
     }
     try {
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
         const result = await callPgMigrationApi(context, "PreviewPGUserMigrations", {
-            Migrations: [migration],
+            Migrations: hydrated.migrations,
         }, cloudBaseOptions);
+        const executable = result.Executable === true;
         return buildPgToolResult({
             success: true,
             data: {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                hydratedRemoteCount: hydrated.remoteCount,
+                latestRemoteVersion: hydrated.latestVersion || null,
+                executable,
                 apiResult: result,
             },
-            message: `Migration plan generated via PreviewPGUserMigrations. Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`,
+            message: executable
+                ? `Migration plan generated via PreviewPGUserMigrations (hydrated ${hydrated.remoteCount} remote migration(s)). Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`
+                : `Migration plan is NOT executable (PreviewPGUserMigrations.Executable=false after hydrating ${hydrated.remoteCount} remote migration(s)). Inspect apiResult.Conflicts before applyMigration. Common causes: version older than latest remote (${hydrated.latestVersion || "unknown"}), or checksum mismatch.`,
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion.", {
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", executable
+                    ? "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion."
+                    : "Resolve Conflicts (often pick a migrationVersion newer than LatestVersion), then retry planMigration/applyMigration.", {
                     action: "applyMigration",
                     migrationName: args.migrationName,
                     migrationVersion: version,
@@ -163156,26 +163266,118 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
-    }
-    const params = { Migrations: [migration] };
-    if (args.lockTimeoutMs !== undefined) {
-        params.LockTimeoutMs = args.lockTimeoutMs;
-    }
-    if (args.statementTimeoutMs !== undefined) {
-        params.StatementTimeoutMs = args.statementTimeoutMs;
+        pending.Rollback = args.rollbackSql;
     }
     try {
+        // Pushing only the pending migration while remote history exists makes the plan
+        // non-executable (remote_history_not_found_locally). Hydrate remote Queries first,
+        // matching CLI `tcb db pg migration up` (full list; server skips applied).
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
+        const preview = await callPgMigrationApi(context, "PreviewPGUserMigrations", { Migrations: hydrated.migrations }, cloudBaseOptions);
+        if (preview.Executable !== true) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_NOT_EXECUTABLE",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
+                    latestRemoteVersion: hydrated.latestVersion || null,
+                    previewResult: preview,
+                    verified: false,
+                },
+                message: `PreviewPGUserMigrations reported Executable=false for migrationVersion=${version} ` +
+                    `(latest remote=${hydrated.latestVersion || "unknown"}, hydratedRemoteCount=${hydrated.remoteCount}). ` +
+                    "Push was NOT submitted. Inspect previewResult.Conflicts — common reasons: " +
+                    "local_migration_before_latest_remote (pick a newer 14-digit version) or checksum_mismatch. " +
+                    "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
+                nextActions: [
+                    buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check LatestVersion and pick a migrationVersion strictly newer than it.", { action: "listMigrations", limit: 20 }),
+                    buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Re-run planMigration after adjusting migrationVersion/SQL.", {
+                        action: "planMigration",
+                        migrationName: args.migrationName,
+                        migrationVersion: version,
+                        sql: args.sql,
+                        ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                    }),
+                ],
+            });
+        }
+        const params = { Migrations: hydrated.migrations };
+        if (args.lockTimeoutMs !== undefined) {
+            params.LockTimeoutMs = args.lockTimeoutMs;
+        }
+        if (args.statementTimeoutMs !== undefined) {
+            params.StatementTimeoutMs = args.statementTimeoutMs;
+        }
         const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
-        // PushPGUserMigrations may return a TaskId without the migration having taken
-        // effect. Confirm against the remote history before reporting success, so callers
-        // never get a false-positive success for a silently dropped migration.
+        const taskId = typeof result.TaskId === "string" ? result.TaskId.trim() : "";
+        let taskResult = null;
+        if (taskId) {
+            try {
+                taskResult = await waitPgMigrationTask(context, taskId, cloudBaseOptions);
+            }
+            catch (error) {
+                const lastTask = error.lastTask;
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_TIMEOUT",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: lastTask ?? { TaskId: taskId },
+                        verified: null,
+                    },
+                    message: `PushPGUserMigrations returned TaskId=${taskId}, but waiting for DescribeTaskResult timed out: ` +
+                        `${error instanceof Error ? error.message : String(error)}. ` +
+                        "The migration may still be running — check action=listMigrations before retrying or falling back to execute.",
+                    nextActions: [
+                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check whether the migrationVersion eventually landed.", { action: "listMigrations", limit: 20 }),
+                    ],
+                });
+            }
+            const status = String(taskResult.Status || "").toLowerCase();
+            if (status === "failed") {
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_FAILED",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: taskResult,
+                        verified: false,
+                    },
+                    message: `PushPGUserMigrations TaskId=${taskId} failed at phase=${taskResult.Phase || "-"}: ` +
+                        `${taskResult.Reason || "unknown reason"}. ` +
+                        "The migration did NOT take effect. Fix Conflicts/SQL (or use a newer migrationVersion), then retry applyMigration. " +
+                        "Urgent bypass: action=execute with allowDdlViaExecute=true (skips migration history).",
+                    nextActions: [
+                        buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview again to inspect Conflicts before retrying apply.", {
+                            action: "planMigration",
+                            migrationName: args.migrationName,
+                            migrationVersion: version,
+                            sql: args.sql,
+                            ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                        }),
+                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Confirm the version is still absent from remote history.", { action: "listMigrations", limit: 20 }),
+                    ],
+                });
+            }
+        }
+        // Task Succeed (or sync response without TaskId): confirm history records the version.
         const verification = await verifyMigrationApplied(context, version, cloudBaseOptions);
         if (verification.applied === false) {
             return buildPgToolResult({
@@ -163185,10 +163387,12 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: false,
                 },
-                message: `PushPGUserMigrations returned without error, but migrationVersion=${version} is not present in the remote migration history, ` +
+                message: `PushPGUserMigrations completed (TaskId=${taskId || "none"}), but migrationVersion=${version} is not present in the remote migration history, ` +
                     "so the migration did NOT take effect. Do not assume the schema change is applied. " +
                     "Re-check the SQL and migrationVersion, inspect the migration with action=migrationDetail, and retry action=applyMigration. " +
                     "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
@@ -163206,7 +163410,9 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: null,
                 },
                 message: `PushPGUserMigrations was submitted, but verifying migrationVersion=${version} against the remote history failed: ${verification.error}. ` +
@@ -163222,10 +163428,12 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                hydratedRemoteCount: hydrated.remoteCount,
                 apiResult: result,
+                taskResult: taskResult,
                 verified: true,
             },
-            message: `Migrations applied via PushPGUserMigrations and verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
+            message: `Migrations applied via PushPGUserMigrations (hydrated ${hydrated.remoteCount} remote migration(s)), task ${taskId ? `TaskId=${taskId} ` : ""}verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
         });
     }
     catch (error) {
@@ -198768,7 +198976,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.4" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.5" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -198849,7 +199057,7 @@ function createWrappedHandler(name, handler, server) {
                 requestId: (typeof error === 'object' && error && 'requestId' in error) ? error.requestId : '',
                 ide: server.ide || process.env.INTEGRATION_IDE || ''
             });
-            const mcpVersion =  true ? "2.25.4" : 0;
+            const mcpVersion =  true ? "2.25.5" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -215437,7 +215645,7 @@ function registerSetupTools(server) {
     server.registerTool("downloadTemplate", {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。
-**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.25.4" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.25.5" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -232661,7 +232869,11 @@ function registerGatewayTools(server) {
         return result ?? {};
     };
     const buildPrivilegeDescription = (privilege) => {
-        const serviceStatus = privilege.EnableService === true ? "已开启" : "未开启";
+        const serviceStatus = privilege.EnableService === undefined
+            ? "未知"
+            : privilege.EnableService === true
+                ? "已开启"
+                : "未开启";
         const authStatus = privilege.EnableAuth === undefined
             ? "未知"
             : privilege.EnableAuth === true
@@ -233001,12 +233213,28 @@ function registerGatewayTools(server) {
                 if (!input.domain || !input.certificateId) {
                     throw new Error("action=bindCustomDomain 时必须提供 domain 和 certificateId");
                 }
+                const accessType = input.accessType ?? "DIRECT";
+                if (accessType === "CUSTOM" && !input.customCname) {
+                    throw new Error("action=bindCustomDomain 且 accessType=CUSTOM 时必须提供 customCname（自有 CDN/WAF 的回源/回填地址，不是 DNS 解析目标）。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
+                if (accessType !== "CUSTOM" && input.customCname) {
+                    throw new Error("customCname 仅在 accessType=CUSTOM 时可用；普通绑定用默认 DIRECT，不要传 customCname。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
                 const cloudbase = await getManager();
                 const result = await cloudbase.env.bindCustomDomain({
                     EnvId: await resolveEnvId(),
                     Domain: {
                         Domain: input.domain,
                         CertId: input.certificateId,
+                        AccessType: accessType,
+                        ...(input.enable !== undefined
+                            ? { Enable: input.enable }
+                            : {}),
+                        ...(input.customCname
+                            ? { CustomCname: input.customCname }
+                            : {}),
                     },
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -233014,24 +233242,64 @@ function registerGatewayTools(server) {
                     action: input.action,
                     domain: input.domain,
                     certificateId: input.certificateId,
+                    accessType,
+                    ...(input.customCname
+                        ? { customCname: input.customCname }
+                        : {}),
+                    ...(input.enable !== undefined
+                        ? { enable: input.enable }
+                        : {}),
                     raw: result,
-                }, "自定义域名绑定成功");
+                }, `自定义域名绑定成功（${accessType}）`, [
+                    {
+                        tool: "manageGateway",
+                        action: "createRoute",
+                        reason: "绑定后需 createRoute 添加访问路径，并完成 DNS CNAME 解析后才可访问",
+                    },
+                ]);
             }
             case "deleteCustomDomain": {
                 if (!input.domain) {
                     throw new Error("action=deleteCustomDomain 时必须提供 domain");
                 }
                 const cloudbase = await getManager();
-                const result = await cloudbase.env.deleteCustomDomain({
-                    EnvId: await resolveEnvId(),
-                    Domain: input.domain,
-                });
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action: input.action,
-                    domain: input.domain,
-                    raw: result,
-                }, "自定义域名删除成功");
+                try {
+                    const result = await cloudbase.env.deleteCustomDomain({
+                        EnvId: await resolveEnvId(),
+                        Domain: input.domain,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    return buildEnvelope({
+                        action: input.action,
+                        domain: input.domain,
+                        raw: result,
+                    }, "自定义域名删除成功");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    // SDK 在域名下仍有路由绑定时抛错，需先删路由再删域名
+                    if (/route binding/i.test(message)) {
+                        return {
+                            success: false,
+                            data: { action: input.action, domain: input.domain },
+                            message: `域名 ${input.domain} 下仍有路由绑定，需先删除路由再删除域名。` +
+                                `原始错误：${message}`,
+                            nextActions: [
+                                {
+                                    tool: "queryGateway",
+                                    action: "listRoutes",
+                                    reason: "查看该域名下的路由，确认需要删除的路径",
+                                },
+                                {
+                                    tool: "manageGateway",
+                                    action: "deleteRoute",
+                                    reason: "先删除该域名下的全部路由（逐个 deleteRoute），再重试 deleteCustomDomain",
+                                },
+                            ],
+                        };
+                    }
+                    throw error;
+                }
             }
             case "enableService": {
                 if (typeof input.enable !== "boolean") {
@@ -233144,7 +233412,8 @@ function registerGatewayTools(server) {
                 "enableService/authSwitch 开关 HTTP 网关总开关与访问鉴权（需配合 enable 参数）。" +
                 "createRoute/updateRoute 必须提供 upstreamResourceType。" +
                 "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
-                "bindCustomDomain 仅用于首次绑定新域名。"),
+                "bindCustomDomain 仅用于首次绑定新域名（需 certificateId；可选 accessType=DIRECT|CDN|CUSTOM，CUSTOM 需 customCname；普通场景用默认 DIRECT）。" +
+                "接入说明：https://docs.cloudbase.net/service/custom-domain"),
             targetName: zod_1.z
                 .string()
                 .optional()
@@ -233207,11 +233476,24 @@ function registerGatewayTools(server) {
                 .optional()
                 .describe("证书 ID。仅首次 bindCustomDomain 必填。" +
                 "在已有自定义域名上 createRoute / updateRoute / deleteRoute 不需要 certificateId。"),
+            accessType: zod_1.z
+                .enum(["DIRECT", "CDN", "CUSTOM"])
+                .optional()
+                .describe("绑定类型（仅 bindCustomDomain，默认 DIRECT）。" +
+                "DIRECT=直连（普通绑域名用这个）；CDN=云开发 CDN；CUSTOM=自有 CDN/WAF（需 customCname）。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
+            customCname: zod_1.z
+                .string()
+                .optional()
+                .describe("自有 CDN/WAF 的回源/回填地址（仅 bindCustomDomain 且 accessType=CUSTOM）。" +
+                "不是 DNS 里用户域名要解析到的那个 CNAME；DIRECT/CDN 不要传。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
             enable: zod_1.z
                 .boolean()
                 .optional()
-                .describe("开关目标状态（仅 enableService / authSwitch 使用，必填）：" +
-                "enable=true 开启，enable=false 关闭。省略或非布尔值会返回参数错误。"),
+                .describe("开关目标状态（enableService / authSwitch 必填）：enable=true 开启，enable=false 关闭。" +
+                "bindCustomDomain 可选：enable=false 表示绑定后禁用域名（默认启用）。" +
+                "省略或非布尔值会返回参数错误。"),
         },
         annotations: {
             readOnlyHint: false,