@cloudbase/cloudbase-mcp 2.25.1 → 2.25.3

package/dist/index.cjs

@@ -2218,15 +2218,20 @@ async function prepareAuthEnvironment(params) {
     if (setupContext.createFreeEnvAttempted) {
         envSetupActions.push("create_free_env");
     }
+    // Surface the user-facing notice emitted at checkAndCreateFreeEnv entry.
+    // Informational only — no confirm required. Prepend to the final message so
+    // the user knows an automatic free-env creation was attempted.
+    const userNotice = createResult.userNotice?.trim() || "";
     if (createResult.success && createResult.envId) {
         await cloudbase_manager_js_1.envManager.setEnvId(createResult.envId);
+        const successMessage = `当前已登录，已自动创建并绑定环境: ${createResult.envId}`;
         return {
             currentEnvId: createResult.envId,
             envStatus: "READY",
             envCandidates: [],
             envSetupStatus: "AUTO_CREATED",
             envSetupActions: dedupeActions(envSetupActions),
-            message: `当前已登录，已自动创建并绑定环境: ${createResult.envId}`,
+            message: userNotice ? `${userNotice}\n${successMessage}` : successMessage,
             nextStep: (0, tool_result_js_1.buildAuthNextStep)("status", {
                 suggestedArgs: { action: "status" },
             }),
@@ -2245,6 +2250,9 @@ async function prepareAuthEnvironment(params) {
             message: "环境创建失败，请稍后重试或手动创建环境。",
             helpUrl: "https://buy.cloud.tencent.com/lowcode?buyType=tcb&channel=mcp",
         });
+    const failureMessage = userNotice
+        ? `${userNotice}\n${createFailure.message}`
+        : createFailure.message;
     return {
         currentEnvId: null,
         envStatus: "NONE",
@@ -2252,7 +2260,7 @@ async function prepareAuthEnvironment(params) {
         envSetupStatus: "ACTION_REQUIRED",
         envSetupActions: dedupeActions(envSetupActions),
         envSetupFailure: createFailure,
-        message: createFailure.message,
+        message: failureMessage,
         nextStep: (0, tool_result_js_1.buildAuthNextStep)("status", {
             suggestedArgs: { action: "status" },
         }),
@@ -2574,6 +2582,297 @@ function buildEnvQueryErrorMessage(error, action) {
 function normalizeOptionalToolBoolean(value) {
     return typeof value === "boolean" ? value : undefined;
 }
+/**
+ * 解析用于询价的 region。与 cloudbase-manager.ts 一致：
+ * cloudBaseOptions.region → TCB_REGION → 'ap-shanghai'。
+ */
+function resolvePricingRegion(cloudBaseOptions) {
+    return ((typeof cloudBaseOptions?.region === "string" && cloudBaseOptions.region) ||
+        process.env.TCB_REGION ||
+        "ap-shanghai");
+}
+/**
+ * 从 describeBaasPackageList 查询某个 packageId 的人类可读套餐名。
+ * 失败时返回 undefined，调用方降级为只显示 packageId。
+ */
+async function fetchPackageTitle(manager, packageId) {
+    try {
+        const result = await manager.env.describeBaasPackageList({
+            TargetAction: "new",
+            Source: "qcloud",
+        });
+        const packageList = result?.PackageList || [];
+        const matched = packageList.find((item) => item?.BillTags === packageId || item?.PackageName === packageId);
+        if (matched) {
+            return (matched.PackageTitle || matched.PackageName || matched.BillTags);
+        }
+        return undefined;
+    }
+    catch (error) {
+        (0, logger_js_1.debug)("fetchPackageTitle failed", { packageId, error });
+        return undefined;
+    }
+}
+/**
+ * 查询环境的当前计费/套餐信息（PackageName、PackageId、Region、到期时间、PayMode）。
+ * 失败时返回 undefined。
+ */
+async function fetchEnvBillingSummary(manager, envId) {
+    try {
+        // describeBillingInfo 返回 EnvBillingInfoList；从中挑出 envId 对应项
+        const billingResult = await manager.env.describeBillingInfo({ EnvId: envId });
+        const billingList = billingResult?.EnvBillingInfoList ||
+            billingResult?.Response?.EnvBillingInfoList ||
+            billingResult?.Data?.EnvBillingInfoList ||
+            [];
+        const matched = Array.isArray(billingList)
+            ? billingList.find((item) => item?.EnvId === envId) ?? billingList[0]
+            : undefined;
+        if (!matched) {
+            return undefined;
+        }
+        return {
+            packageName: matched.PackageName,
+            packageId: matched.PackageId,
+            region: matched.Region,
+            expireTime: matched.ExpireTime,
+            payMode: matched.PayMode,
+            isAutoRenew: matched.IsAutoRenew,
+        };
+    }
+    catch (error) {
+        (0, logger_js_1.debug)("fetchEnvBillingSummary failed", { envId, error });
+        return undefined;
+    }
+}
+/**
+ * 询价新购价格。失败时返回 { error }。
+ */
+async function calculateCreatePrice(manager, params) {
+    try {
+        const priceResult = await manager.env.calculatePackageCreatePrice({
+            packageId: params.packageId,
+            region: params.region,
+            period: params.period,
+        });
+        return { priceResult };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        (0, logger_js_1.debug)("calculatePackageCreatePrice failed", { params, error });
+        return { error: message };
+    }
+}
+/**
+ * 询价续费价格。失败时返回 { error }。
+ */
+async function calculateRenewPrice(manager, envId, period) {
+    try {
+        const priceResult = await manager.env.calculatePackageRenewPrice({
+            envId,
+            period,
+        });
+        return { priceResult };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        (0, logger_js_1.debug)("calculatePackageRenewPrice failed", { envId, period, error });
+        return { error: message };
+    }
+}
+/**
+ * 询价变配价格（含退款）。失败时返回 { error }。
+ */
+async function calculateModifyPrice(manager, envId, newPackageId) {
+    try {
+        const priceResult = await manager.env.calculatePackageModifyPrice({
+            envId,
+            newPackageId,
+        });
+        return { priceResult };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        (0, logger_js_1.debug)("calculatePackageModifyPrice failed", { envId, newPackageId, error });
+        return { error: message };
+    }
+}
+/**
+ * 把 PriceResult 格式化为人类可读的价格摘要。
+ * 返回 { summary, detail }：summary 是一行短语，detail 是多行明细。
+ */
+function formatPriceSection(priceResult) {
+    if (!priceResult || typeof priceResult !== "object") {
+        return { summary: "询价返回为空", detail: "" };
+    }
+    const currency = priceResult.Currency === "USD" ? "$" : "￥";
+    const realTotalCost = Number(priceResult.RealTotalCost);
+    const totalCost = Number(priceResult.TotalCost);
+    const unitPrice = Number(priceResult.Price);
+    const timeSpan = priceResult.TimeSpan;
+    const TimeUnit = priceResult.TimeUnit || "";
+    const refund = priceResult.Refund ? Number(priceResult.Refund) : undefined;
+    const lines = [];
+    let summary = "";
+    if (Number.isFinite(realTotalCost) && realTotalCost > 0) {
+        summary = `预计实付 ${currency}${realTotalCost}`;
+        lines.push(`- 实付总价: ${currency}${realTotalCost}`);
+    }
+    else if (Number.isFinite(totalCost) && totalCost > 0) {
+        summary = `预计费用 ${currency}${totalCost}`;
+        lines.push(`- 总价: ${currency}${totalCost}`);
+    }
+    if (Number.isFinite(totalCost) && totalCost > 0 && totalCost !== realTotalCost) {
+        lines.push(`- 原价: ${currency}${totalCost}`);
+    }
+    if (Number.isFinite(unitPrice) && unitPrice > 0) {
+        lines.push(`- 单价: ${currency}${unitPrice}`);
+    }
+    if (timeSpan !== undefined && TimeUnit) {
+        lines.push(`- 时长: ${timeSpan} ${TimeUnit}`);
+    }
+    if (refund !== undefined && Number.isFinite(refund) && refund > 0) {
+        lines.push(`- 退款: ${currency}${refund}（变配降级时退回差价）`);
+        if (summary) {
+            summary += `，退款 ${currency}${refund}`;
+        }
+        else {
+            summary = `退款 ${currency}${refund}`;
+        }
+    }
+    if (priceResult.Formula && typeof priceResult.Formula === "string") {
+        lines.push(`- 计价公式: ${priceResult.Formula}`);
+    }
+    return {
+        summary: summary || "询价返回缺少总价字段",
+        detail: lines.join("\n"),
+    };
+}
+/**
+ * 构建释放方式说明。manageEnv 当前未提供 destroy action，
+ * 指向控制台让用户手动销毁。
+ */
+function buildReleaseMethodHint() {
+    return {
+        method: "手动销毁",
+        consoleUrl: "https://console.cloud.tencent.com/tcb",
+        note: '环境创建后可随时销毁以停止计费。当前 manageEnv 未提供 destroy action，请前往控制台手动销毁，或调用 manageEnv(action="listPackages") 查看其他套餐。',
+    };
+}
+/**
+ * manageEnv 涉及计费的官方文档链接。来源：腾讯云开发 CloudBase 公开文档。
+ * 任何 confirm 消息展示这些链接前不需要再次校验 URL 真实性。
+ */
+const MANAGE_ENV_DOC_LINKS = {
+    // 包年包月套餐说明（个人版 / 标准版 / 企业版 / 企业高级版）
+    package: "https://cloud.tencent.com/document/product/876/39093",
+    // 计费能力项说明
+    billingItems: "https://cloud.tencent.com/document/product/876/120713",
+    // 资源点价格文档
+    resourcePointPrice: "https://cloud.tencent.com/document/product/876/127357",
+    // 预付费计费与到期释放（费用中心通用）
+    prepayExpiry: "https://cloud.tencent.com/document/product/555/9618",
+};
+/**
+ * 把文档链接渲染为多行 markdown 列表文本。
+ * filter 不传时全部展示。
+ */
+function renderDocLinksBlock(filter) {
+    const labels = {
+        package: "包年包月套餐说明",
+        billingItems: "计费能力项说明",
+        resourcePointPrice: "资源点价格文档",
+        prepayExpiry: "预付费计费与到期释放（费用中心通用）",
+    };
+    const entries = (filter ?? Object.keys(MANAGE_ENV_DOC_LINKS))
+        .map((k) => `- [${labels[k]}](${MANAGE_ENV_DOC_LINKS[k]})`)
+        .join("\n");
+    return `参考文档：\n${entries}`;
+}
+/**
+ * 资源清单详细描述（对应控制台购买页"资源清单"段）。
+ */
+function buildResourceListText() {
+    return "资源清单：\n- 云开发环境 ×1（含 云数据库 / 云函数 / 云存储 / 静态托管 / 身份认证 等基础资源）";
+}
+/**
+ * 计费项披露（对应控制台购买页"计费项"段）。
+ * 此处为静态披露，调用方在 confirm 消息中拼接即可。
+ */
+function buildBillingItemsText() {
+    return "计费项：\n- 数据库容量/调用 · 云函数调用/资源/流量 · 存储读写/CDN · 网关/认证/API 调用 · QPS 超限按量 · 日志";
+}
+/**
+ * 计费方式披露（对应控制台购买页"计费方式"段）。
+ * 针对用户传入的 packageId 判断套餐类型：
+ * - 含 free/activity/trial/试用 等关键字视为免费体验版
+ * - 其余视为付费套餐
+ */
+function buildBillingModeText(packageId) {
+    const id = (packageId || "").toLowerCase();
+    const isFree = id.includes("free") ||
+        id.includes("activity") ||
+        id.includes("trial") ||
+        id.includes("试用") ||
+        id.includes("体验");
+    if (isFree) {
+        return ("计费方式：\n- 免费体验版（每月赠送约 3000 资源点 ≈ 3 元，0 元开通）\n" +
+            "- 付费套餐：个人版 / 标准版 / 企业版 / 企业高级版");
+    }
+    return ("计费方式：\n- 付费套餐：个人版 / 标准版 / 企业版 / 企业高级版\n" +
+        "- 免费体验版通过 auth 工具自动创建；本次 manageEnv(create) 不会创建免费版");
+}
+/**
+ * 资源释放方式详细说明（对应控制台购买页"资源释放方式"段）。
+ * - 免费版：1 个月有效期 + 免费续期 + 停服(保留数据) + 1~7天回收站 + 释放(数据不可恢复)
+ * - 付费版：到期未续费 → 停服(保留数据) + 1~7天可回收站找回 + 释放(数据不可恢复)
+ * 任何时候都可在控制台主动销毁、关闭按量、退订加购资源。
+ */
+function buildReleaseMethodDetailText(packageId) {
+    const id = (packageId || "").toLowerCase();
+    const isFree = id.includes("free") ||
+        id.includes("activity") ||
+        id.includes("trial") ||
+        id.includes("试用") ||
+        id.includes("体验");
+    const lines = ["资源释放方式：\n- 可随时在控制台销毁环境、关闭按量、退订加购资源"];
+    if (isFree) {
+        lines.push("- 免费体验版：有效期 1 个月，到期可免费续期 1 个月；未续期则停服(保留数据)→1~7天回收站→释放(数据不可恢复)");
+    }
+    else {
+        lines.push("- 付费套餐到期未续费：停服(保留数据)→1~7天可回收站找回→释放(数据不可恢复)");
+        lines.push("- 主动销毁：随时生效；销毁前请确保已迁移或备份数据");
+    }
+    return lines.join("\n");
+}
+/**
+ * 预计费用披露段：把询价结果 + 周期说明 + 超额按量说明组合成人类可读文本。
+ */
+function buildPricingDisclosureText(packageId, priceSection, priceError, period) {
+    const id = (packageId || "").toLowerCase();
+    const isFree = id.includes("free") ||
+        id.includes("activity") ||
+        id.includes("trial") ||
+        id.includes("试用") ||
+        id.includes("体验");
+    const lines = ["预计费用："];
+    if (isFree) {
+        lines.push(`- 免费体验版：本次开通 0 元；超免费额度后需升级为付费套餐（免费版不支持开按量）`);
+        lines.push("- 实际单价以资源点价格文档为准（3000 资源点 ≈ 3 元）");
+    }
+    else {
+        lines.push(`- 付费套餐：${priceSection?.summary ?? (priceError ? `⚠️ 询价失败（${priceError}），请前往控制台确认` : "询价返回为空")}`);
+        if (priceSection?.detail) {
+            lines.push(priceSection.detail);
+        }
+        if (priceError && priceSection) {
+            lines.push(`- ⚠️ 部分明细缺失：${priceError}`);
+        }
+        lines.push(`- 计费周期：约 ${period} 个月（包年包月），到期可续费或变配`);
+        lines.push("- 超额可另开按量（次日结算），详细计费项以官方文档为准");
+    }
+    return lines.join("\n");
+}
 function resolveToolAuthOptions(server, overrides) {
     return (0, auth_js_1.resolveAuthOptions)({
         ...overrides,
@@ -3402,7 +3701,7 @@ function registerEnvTools(server) {
     if (server.ide !== 'wxide') {
         server.registerTool?.("envDomainManagement", {
             title: "CloudBase 环境域名管理（安全域名 / CORS 白名单）",
-            description: "管理 CloudBase 环境的安全域名（安全域名 / CORS 白名单），支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 直接访问 CloudBase 资源时，应先用 queryEnv(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。新增或删除后通常需要继续轮询 queryEnv(action=domains) 确认状态收敛；安全域名一般约 10 分钟生效。⚠️ 重要：此工具仅用于 CORS/请求来源验证，不涉及 SSL 证书。如需绑定自定义域名供公网 HTTPS 访问，请使用 manageGateway(action=\"bindCustomDomain\")。",
+            description: "管理 CloudBase 环境的安全域名（安全域名 / CORS 白名单），支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 直接访问 CloudBase 资源时，应先用 queryEnv(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。新增或删除后通常需要继续轮询 queryEnv(action=domains) 确认状态收敛；安全域名一般约 10 分钟生效。⚠️ 重要：此工具仅用于 CORS/请求来源验证，不涉及 SSL 证书。自定义域名公网 HTTPS：先 queryGateway(listCustomDomains)；已有域名则 manageGateway(createRoute) 显式传 domain（无需证书）；仅首次绑定新域名才用 bindCustomDomain（需 certificateId）。",
             inputSchema: {
                 action: zod_1.z
                     .enum(["create", "delete"])
@@ -3526,10 +3825,92 @@ function registerEnvTools(server) {
                     // CreateEnv (Manager SDK / Cloud API) accepts Alias, PackageId, Resources, Period, etc.
                     // It does NOT accept Region — region is determined by account/package, not this call.
                     if (!confirmed) {
+                        // 查询套餐名和预计费用（失败降级，不阻塞 confirm 流程）
+                        const packageTitle = packageId
+                            ? await fetchPackageTitle(cloudbase, packageId)
+                            : undefined;
+                        const pricingRegion = resolvePricingRegion(cloudBaseOptions);
+                        const priceProbe = packageId
+                            ? await calculateCreatePrice(cloudbase, {
+                                packageId,
+                                region: pricingRegion,
+                                period: duration,
+                            })
+                            : { error: "缺少 packageId，无法询价" };
+                        const priceSection = priceProbe.priceResult
+                            ? formatPriceSection(priceProbe.priceResult)
+                            : null;
+                        const releaseMethod = buildReleaseMethodHint();
+                        // 组合多段披露文案（对照控制台购买页确认对话框）
+                        const messageLines = [];
+                        messageLines.push("即将为你开通云开发环境");
+                        messageLines.push("本操作会创建腾讯云开发环境资源。");
+                        messageLines.push("为付费套餐后才会产生费用；免费体验版不会立即扣费（每月赠送约 3000 资源点 ≈ 3 元）。");
+                        messageLines.push("请核对以下配置信息后传入 confirm=\"yes\"：");
+                        messageLines.push(`- 别名: ${alias ?? "(未提供)"}`);
+                        messageLines.push(`- 套餐: ${packageId ?? "(未提供)"}` +
+                            (packageTitle ? `（${packageTitle}）` : ""));
+                        messageLines.push(`- 资源类型: ${resolvedResources.join(", ")}`);
+                        messageLines.push(`- 时长: ${duration} 个月`);
+                        messageLines.push("- 说明: CreateEnv 不接受 Region 入参，环境地域由账号与套餐侧决定。");
+                        messageLines.push("");
+                        // 资源清单 / 计费项 / 计费方式
+                        messageLines.push(buildResourceListText());
+                        messageLines.push(buildBillingItemsText());
+                        messageLines.push(buildBillingModeText(packageId));
+                        messageLines.push("");
+                        // 预计费用
+                        messageLines.push(buildPricingDisclosureText(packageId, priceSection, priceProbe.error, duration));
+                        messageLines.push("");
+                        // 资源释放方式
+                        messageLines.push(buildReleaseMethodDetailText(packageId));
+                        messageLines.push("");
+                        // 文档链接
+                        messageLines.push(renderDocLinksBlock([
+                            "package",
+                            "billingItems",
+                            "resourcePointPrice",
+                            "prepayExpiry",
+                        ]));
+                        messageLines.push("");
+                        // 已知晓声明
+                        messageLines.push("☐ 我已知晓将创建付费资源及计费规则，确认按上述配置开通。");
+                        messageLines.push(`（如需取消或修改，请勿传 confirm="yes"，改传其他参数重试）`);
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "CONFIRM_REQUIRED",
-                            message: `创建环境需要您确认。请确认以下配置信息后传入 confirm="yes"：\n别名: ${alias}\n套餐: ${packageId}\n资源类型: ${resolvedResources.join(", ")}\n时长: ${duration} 个月\n说明: CreateEnv 不接受 Region；环境地域由账号与套餐侧决定。`,
+                            message: messageLines.join("\n"),
+                            package_info: packageTitle
+                                ? { packageId, packageTitle }
+                                : packageId
+                                    ? { packageId, packageTitle: null }
+                                    : undefined,
+                            pricing: priceSection
+                                ? {
+                                    summary: priceSection.summary,
+                                    currency: priceProbe.priceResult?.Currency,
+                                    realTotalCost: priceProbe.priceResult?.RealTotalCost,
+                                    totalCost: priceProbe.priceResult?.TotalCost,
+                                    timeSpan: priceProbe.priceResult?.TimeSpan,
+                                    timeUnit: priceProbe.priceResult?.TimeUnit,
+                                    inquiryRegion: pricingRegion,
+                                }
+                                : priceProbe.error
+                                    ? { inquiryFailed: true, error: priceProbe.error }
+                                    : undefined,
+                            release_method: {
+                                ...releaseMethod,
+                                detail: buildReleaseMethodDetailText(packageId),
+                                docLinks: [
+                                    MANAGE_ENV_DOC_LINKS.package,
+                                    MANAGE_ENV_DOC_LINKS.prepayExpiry,
+                                ],
+                            },
+                            doc_links: MANAGE_ENV_DOC_LINKS,
+                            confirmation_acknowledgement: {
+                                text: "我已知晓将创建付费资源及计费规则",
+                                required: true,
+                            },
                             next_step: {
                                 tool: "manageEnv",
                                 action: "create",
@@ -3565,10 +3946,91 @@ function registerEnvTools(server) {
                         if (!envId || !packageId) {
                             throw new Error("变更套餐时 envId 和 packageId 为必填参数");
                         }
+                        // 查询当前套餐名 + 新套餐名 + 询价（失败降级）
+                        const [currentBilling, newPackageTitle] = await Promise.all([
+                            fetchEnvBillingSummary(cloudbase, envId),
+                            fetchPackageTitle(cloudbase, packageId),
+                        ]);
+                        const priceProbe = await calculateModifyPrice(cloudbase, envId, packageId);
+                        const priceSection = priceProbe.priceResult
+                            ? formatPriceSection(priceProbe.priceResult)
+                            : null;
+                        const releaseMethod = buildReleaseMethodHint();
+                        const messageLines = [];
+                        messageLines.push(`变更环境 ${envId} 的套餐需要您确认。变配后不会立即重新计费，但会触发差价结算或退款。`);
+                        messageLines.push("请核对后传入 confirm=\"yes\"：");
+                        messageLines.push(`- 当前套餐: ${currentBilling?.packageName ?? currentBilling?.packageId ?? "(未知)"}` +
+                            (currentBilling?.packageId && currentBilling.packageName
+                                ? `（${currentBilling.packageId}）`
+                                : ""));
+                        if (currentBilling?.expireTime) {
+                            messageLines.push(`- 当前到期时间: ${currentBilling.expireTime}`);
+                        }
+                        messageLines.push(`- 新套餐: ${packageId}` +
+                            (newPackageTitle ? `（${newPackageTitle}）` : ""));
+                        messageLines.push("");
+                        if (priceSection) {
+                            messageLines.push(`预计费用变化：${priceSection.summary}（差价/退款以账单为准）`);
+                            if (priceSection.detail) {
+                                messageLines.push(priceSection.detail);
+                            }
+                        }
+                        else if (priceProbe.error) {
+                            messageLines.push(`预计费用变化：⚠️ 询价失败（${priceProbe.error}），请前往控制台确认价格`);
+                        }
+                        else {
+                            messageLines.push("预计费用变化：询价返回为空，请前往控制台确认价格");
+                        }
+                        messageLines.push("");
+                        // 资源释放方式（变配不影响存续，但与到期/销毁规则相同）
+                        messageLines.push(buildReleaseMethodDetailText(packageId));
+                        messageLines.push("");
+                        // 文档链接（变配与套餐/计费/到期都相关）
+                        messageLines.push(renderDocLinksBlock(["package", "prepayExpiry"]));
+                        messageLines.push("");
+                        messageLines.push("☐ 我已知晓变配将触发差价结算或退款，确认按上述配置变更。");
+                        messageLines.push(`（如需取消或修改，请勿传 confirm="yes"）`);
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "CONFIRM_REQUIRED",
-                            message: `变更环境 ${envId} 的套餐为 ${packageId} 可能产生费用变化。请确认后传入 confirm="yes"。`,
+                            message: messageLines.join("\n"),
+                            env_id: envId,
+                            current_package: currentBilling
+                                ? {
+                                    packageId: currentBilling.packageId,
+                                    packageName: currentBilling.packageName,
+                                    expireTime: currentBilling.expireTime,
+                                    payMode: currentBilling.payMode,
+                                }
+                                : undefined,
+                            new_package: {
+                                packageId,
+                                packageTitle: newPackageTitle ?? null,
+                            },
+                            pricing: priceSection
+                                ? {
+                                    summary: priceSection.summary,
+                                    currency: priceProbe.priceResult?.Currency,
+                                    realTotalCost: priceProbe.priceResult?.RealTotalCost,
+                                    totalCost: priceProbe.priceResult?.TotalCost,
+                                    refund: priceProbe.priceResult?.Refund,
+                                }
+                                : priceProbe.error
+                                    ? { inquiryFailed: true, error: priceProbe.error }
+                                    : undefined,
+                            release_method: {
+                                ...releaseMethod,
+                                detail: buildReleaseMethodDetailText(packageId),
+                                docLinks: [MANAGE_ENV_DOC_LINKS.prepayExpiry],
+                            },
+                            doc_links: {
+                                package: MANAGE_ENV_DOC_LINKS.package,
+                                prepayExpiry: MANAGE_ENV_DOC_LINKS.prepayExpiry,
+                            },
+                            confirmation_acknowledgement: {
+                                text: "我已知晓变配将触发差价结算或退款",
+                                required: true,
+                            },
                             next_step: {
                                 tool: "manageEnv",
                                 action: "modifyPlan",
@@ -3598,10 +4060,87 @@ function registerEnvTools(server) {
                         if (!envId) {
                             throw new Error("续费环境时 envId 为必填参数");
                         }
+                        // 查询当前套餐名 + 到期时间 + 询价（失败降级）
+                        const [currentBilling, priceProbe] = await Promise.all([
+                            fetchEnvBillingSummary(cloudbase, envId),
+                            calculateRenewPrice(cloudbase, envId, duration),
+                        ]);
+                        const priceSection = priceProbe.priceResult
+                            ? formatPriceSection(priceProbe.priceResult)
+                            : null;
+                        const releaseMethod = buildReleaseMethodHint();
+                        const currentPackageId = currentBilling?.packageId;
+                        const messageLines = [];
+                        messageLines.push(`续费环境 ${envId} 需要您确认。续费按当前套餐类型计算，延长到期时间。`);
+                        messageLines.push("请核对后传入 confirm=\"yes\"：");
+                        messageLines.push(`- 当前套餐: ${currentBilling?.packageName ?? currentBilling?.packageId ?? "(未知)"}` +
+                            (currentBilling?.packageId && currentBilling.packageName
+                                ? `（${currentBilling.packageId}）`
+                                : ""));
+                        if (currentBilling?.expireTime) {
+                            messageLines.push(`- 当前到期时间: ${currentBilling.expireTime}`);
+                        }
+                        messageLines.push(`- 续费时长: ${duration} 个月`);
+                        messageLines.push("");
+                        if (priceSection) {
+                            messageLines.push(`预计费用：${priceSection.summary}`);
+                            if (priceSection.detail) {
+                                messageLines.push(priceSection.detail);
+                            }
+                        }
+                        else if (priceProbe.error) {
+                            messageLines.push(`预计费用：⚠️ 询价失败（${priceProbe.error}），请前往控制台确认价格`);
+                        }
+                        else {
+                            messageLines.push("预计费用：询价返回为空，请前往控制台确认价格");
+                        }
+                        messageLines.push("");
+                        // 资源释放方式
+                        messageLines.push(buildReleaseMethodDetailText(currentPackageId));
+                        messageLines.push("");
+                        // 文档链接（续费主要看预付费与到期释放）
+                        messageLines.push(renderDocLinksBlock(["prepayExpiry"]));
+                        messageLines.push("");
+                        messageLines.push("☐ 我已知晓续费将延长当前套餐的到期时间，确认按上述配置续费。");
+                        messageLines.push(`（如需取消或修改，请勿传 confirm="yes"）`);
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "CONFIRM_REQUIRED",
-                            message: `续费环境 ${envId}，时长: ${duration} 个月，可能产生费用。请确认后传入 confirm="yes"。`,
+                            message: messageLines.join("\n"),
+                            env_id: envId,
+                            current_package: currentBilling
+                                ? {
+                                    packageId: currentBilling.packageId,
+                                    packageName: currentBilling.packageName,
+                                    expireTime: currentBilling.expireTime,
+                                    payMode: currentBilling.payMode,
+                                    isAutoRenew: currentBilling.isAutoRenew,
+                                }
+                                : undefined,
+                            pricing: priceSection
+                                ? {
+                                    summary: priceSection.summary,
+                                    currency: priceProbe.priceResult?.Currency,
+                                    realTotalCost: priceProbe.priceResult?.RealTotalCost,
+                                    totalCost: priceProbe.priceResult?.TotalCost,
+                                    timeSpan: priceProbe.priceResult?.TimeSpan,
+                                    timeUnit: priceProbe.priceResult?.TimeUnit,
+                                }
+                                : priceProbe.error
+                                    ? { inquiryFailed: true, error: priceProbe.error }
+                                    : undefined,
+                            release_method: {
+                                ...releaseMethod,
+                                detail: buildReleaseMethodDetailText(currentPackageId),
+                                docLinks: [MANAGE_ENV_DOC_LINKS.prepayExpiry],
+                            },
+                            doc_links: {
+                                prepayExpiry: MANAGE_ENV_DOC_LINKS.prepayExpiry,
+                            },
+                            confirmation_acknowledgement: {
+                                text: "我已知晓续费将延长当前套餐的到期时间",
+                                required: true,
+                            },
                             next_step: {
                                 tool: "manageEnv",
                                 action: "renew",
@@ -29089,6 +29628,31 @@ function registerAppAuthTools(server) {
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
         }
     };
+    // Best-effort inventory read used to verify whether CreateApiKey really produced a new key.
+    // A failure here must not block key creation, so it returns null to mark "unknown"
+    // rather than an empty list, which would be indistinguishable from "no keys exist".
+    const listApiKeyRecords = async (cloudbase, keyType) => {
+        try {
+            const result = await cloudbase.env.describeApiKeyList({
+                KeyType: keyType,
+                PageNumber: 1,
+                PageSize: 50,
+            });
+            return extractApiKeyList(result);
+        }
+        catch {
+            return null;
+        }
+    };
+    const listApiKeyIds = async (cloudbase, keyType) => {
+        const records = await listApiKeyRecords(cloudbase, keyType);
+        if (records === null) {
+            return null;
+        }
+        return new Set(records
+            .map((item) => (typeof item.KeyId === "string" ? item.KeyId : null))
+            .filter((item) => item !== null));
+    };
     const describePublishableKey = async (cloudbase, envId) => {
         const result = await cloudbase.env.describeApiKeyList({ KeyType: "publish_key", PageNumber: 1, PageSize: 10 });
         return {
@@ -29209,7 +29773,7 @@ function registerAppAuthTools(server) {
     }));
     server.registerTool?.("manageAppAuth", {
         title: "管理 CloudBase 应用认证配置",
-        description: "CloudBase 应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key，以及创建或删除 API key、自定义登录密钥。⚠️ 本工具为管理端配置工具，不执行用户登录。当任务要求编写客户端登录代码时（例如「用 JS SDK 登录」），应先通过本工具完成配置（如启用 usernamePassword、获取 publishable key），再在项目代码中编写 @cloudbase/js-sdk 客户端登录代码（如 auth.signInWithPassword()），而非使用本工具完成登录。若前端要接受普通用户名样式标识符，应先执行 action=patchLoginStrategy 并传入 patch={ usernamePassword: true }，再实现对应前端登录逻辑。",
+        description: "CloudBase 应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key，以及创建或删除 API key、自定义登录密钥。⚠️ 本工具为管理端配置工具，不执行用户登录。当任务要求编写客户端登录代码时（例如「用 JS SDK 登录」），应先通过本工具完成配置（如启用 usernamePassword、获取 publishable key），再在项目代码中编写 @cloudbase/js-sdk 客户端登录代码（如 auth.signInWithPassword()），而非使用本工具完成登录。若前端要接受普通用户名样式标识符，应先执行 action=patchLoginStrategy 并传入 patch={ usernamePassword: true }，再实现对应前端登录逻辑。⚠️ action=createApiKey 返回体中的 created 字段表示是否真正新建：created=false 说明复用了环境中已存在的 key，此时 keyName/expireIn 入参不会生效，返回的 keyName/expireAt 均为服务端真实值，并会附带 warnings，切勿把它当作临时凭证分发。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_APP_AUTH_ACTIONS),
             patch: zod_1.z
@@ -29234,8 +29798,16 @@ function registerAppAuthTools(server) {
                 .enum(APP_AUTH_KEY_TYPES)
                 .optional()
                 .describe("createApiKey 时的 API key 类型，默认 publish_key"),
-            keyName: zod_1.z.string().optional().describe("createApiKey 时的 API key 名称"),
-            expireIn: zod_1.z.number().int().min(0).optional().describe("createApiKey 时的有效期，单位秒；0 表示不过期"),
+            keyName: zod_1.z
+                .string()
+                .optional()
+                .describe("createApiKey 时的 API key 名称；服务端可能忽略该值（如 publish_key 每环境唯一时），返回体中的 keyName 一律为服务端实际存储的名称"),
+            expireIn: zod_1.z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("createApiKey 时的有效期，单位秒；0 表示不过期。复用已有 key 时该值不生效，此时返回体会带 created=false 与 warnings"),
             keyId: zod_1.z.string().optional().describe("deleteApiKey 时的 API key 唯一标识"),
         },
         annotations: {
@@ -29360,6 +29932,7 @@ function registerAppAuthTools(server) {
             }
             case "createApiKey": {
                 const effectiveKeyType = keyType ?? "publish_key";
+                const before = await listApiKeyIds(cloudbase, effectiveKeyType);
                 const result = await cloudbase.env.createApiKey({
                     KeyType: effectiveKeyType,
                     ...(keyName ? { KeyName: keyName } : {}),
@@ -29367,19 +29940,44 @@ function registerAppAuthTools(server) {
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 const createApiKeyResult = normalizePlainObject(result, "createApiKeyResult") ?? {};
+                const resultKeyId = typeof createApiKeyResult.KeyId === "string" ? createApiKeyResult.KeyId : null;
+                const created = before === null || resultKeyId === null ? null : !before.has(resultKeyId);
+                // The backend is the only source of truth for the stored name / expiry:
+                // re-read the key record instead of echoing back the request parameters.
+                const serverRecord = resultKeyId
+                    ? (await listApiKeyRecords(cloudbase, effectiveKeyType))?.find((item) => item.KeyId === resultKeyId) ?? null
+                    : null;
+                const keyNameSource = serverRecord ?? createApiKeyResult;
+                const resolvedKeyName = getNonEmptyString(keyNameSource.Name) ??
+                    getNonEmptyString(keyNameSource.KeyName) ??
+                    null;
+                const resolvedExpireAt = getNonEmptyString(serverRecord?.ExpireAt) ??
+                    getNonEmptyString(createApiKeyResult.ExpireAt) ??
+                    null;
+                const resolvedCreatedAt = getNonEmptyString(serverRecord?.CreateAt) ??
+                    getNonEmptyString(createApiKeyResult.CreateAt) ??
+                    null;
+                const warnings = [];
+                if (created === false) {
+                    warnings.push(`keyType=${effectiveKeyType} 未创建新的 key，返回的是环境中已存在的 key（keyId=${resultKeyId}）。若该类型每个环境唯一，请改用 action=ensurePublishableKey 语义理解此结果。`);
+                }
+                if (keyName && resolvedKeyName !== null && resolvedKeyName !== keyName) {
+                    warnings.push(`请求的 keyName="${keyName}" 未生效，服务端实际存储的名称为 "${resolvedKeyName}"。`);
+                }
+                if (typeof expireIn === "number" && created === false) {
+                    warnings.push(`请求的 expireIn=${expireIn} 未生效，返回的 key 使用其原有过期时间 ${resolvedExpireAt ?? "unknown"}。请勿将其视为临时凭证。`);
+                }
                 return {
                     success: true,
                     envId,
                     keyType: effectiveKeyType,
-                    keyId: typeof result.KeyId === "string" ? result.KeyId : null,
-                    keyName: typeof result.Name === "string"
-                        ? result.Name
-                        : typeof createApiKeyResult.KeyName === "string"
-                            ? createApiKeyResult.KeyName
-                            : keyName ?? null,
-                    apiKey: typeof result.ApiKey === "string" ? result.ApiKey : null,
-                    expireAt: typeof result.ExpireAt === "string" ? result.ExpireAt : null,
-                    createdAt: typeof result.CreateAt === "string" ? result.CreateAt : null,
+                    keyId: resultKeyId,
+                    keyName: resolvedKeyName,
+                    apiKey: typeof createApiKeyResult.ApiKey === "string" ? createApiKeyResult.ApiKey : null,
+                    expireAt: resolvedExpireAt,
+                    createdAt: resolvedCreatedAt,
+                    ...(typeof created === "boolean" ? { created } : {}),
+                    ...(warnings.length > 0 ? { warnings } : {}),
                 };
             }
             case "deleteApiKey": {
@@ -34238,6 +34836,17 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
         hasInitTcbError: !!newContext.initTcbError,
         initTcbError: newContext.initTcbError
     });
+    // User-facing notice emitted at the entry: inform the user that an automatic
+    // free-env creation is being attempted. Informational only — no confirm.
+    // Built once up-front so every return path can surface the same notice.
+    const userNotice = [
+        "系统检测到您当前没有可用的 CloudBase 环境，将自动尝试为您创建一个免费环境。",
+        "创建依据：通过 NewUser / ReturningUser / BaasFree 等优惠活动资格检查；",
+        "环境别名：ai-native（默认）；",
+        "费用说明：该环境为免费活动赠送，创建过程不会产生费用；如不符合免费条件，将引导您前往购买页；",
+        "流程说明：此为自动流程，无需您确认；创建成功后将自动绑定到当前会话。"
+    ].join("\n");
+    (0, logger_js_1.debug)('[env-setup] User notice prepared:', { userNotice });
     try {
         // Step 1: Query promotional activities
         (0, logger_js_1.debug)('[env-setup] Checking promotional activity eligibility...');
@@ -34277,7 +34886,8 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
             };
             return {
                 success: false,
-                context: newContext
+                context: newContext,
+                userNotice
             };
         }
         (0, logger_js_1.debug)('[env-setup] User is eligible for free environment, attempting to create...');
@@ -34342,7 +34952,8 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
                 };
                 return {
                     success: false,
-                    context: newContext
+                    context: newContext,
+                    userNotice
                 };
             }
             // Report create success
@@ -34356,7 +34967,8 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
             return {
                 success: true,
                 envId: envId.trim(), // Ensure no whitespace
-                context: newContext
+                context: newContext,
+                userNotice
             };
         }
         catch (createErr) {
@@ -34415,7 +35027,8 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
             });
             return {
                 success: false,
-                context: newContext
+                context: newContext,
+                userNotice
             };
         }
     }
@@ -34436,7 +35049,8 @@ async function checkAndCreateFreeEnv(cloudbase, context) {
         });
         return {
             success: false,
-            context: newContext
+            context: newContext,
+            userNotice
         };
     }
 }
@@ -40844,6 +41458,7 @@ const QUERY_ACTIONS = [
     "describeTaskStatus",
     "getInstanceInfo",
     "describeInstance",
+    "getConnectionInfo",
 ];
 const MANAGE_ACTIONS = [
     "provisionMySQL",
@@ -40851,6 +41466,17 @@ const MANAGE_ACTIONS = [
     "runStatement",
     "initializeSchema",
 ];
+function sanitizeInstanceInfo(instanceInfo) {
+    return {
+        exists: instanceInfo.exists,
+        envId: instanceInfo.envId,
+        instanceId: instanceInfo.instanceId,
+        schema: instanceInfo.schema,
+        rawStatus: instanceInfo.rawStatus,
+        status: instanceInfo.status,
+        ...(instanceInfo.clusterId ? { clusterId: instanceInfo.clusterId } : {}),
+    };
+}
 function buildNextAction(tool, action, reason, suggestedArgs) {
     return {
         tool,
@@ -41299,11 +41925,12 @@ async function handleDescribeTaskStatus(args, context) {
 }
 async function handleGetInstanceInfo(context) {
     const instanceInfo = await getSqlInstanceInfo(context);
+    const sanitized = sanitizeInstanceInfo(instanceInfo);
     return buildSqlToolResult({
         success: true,
-        data: instanceInfo,
+        data: sanitized,
         message: instanceInfo.exists
-            ? "Resolved current SQL database instance context."
+            ? "Resolved current SQL database instance context (lifecycle only; connection credentials are omitted). Prefer SDK or runQuery/runStatement for app data access. Use getConnectionInfo only for explicit TCP migration."
             : "No SQL database instance is currently available for this environment.",
         nextActions: instanceInfo.exists
             ? undefined
@@ -41312,6 +41939,33 @@ async function handleGetInstanceInfo(context) {
             ],
     });
 }
+async function handleGetConnectionInfo(context) {
+    const instanceInfo = await getSqlInstanceInfo(context);
+    if (!instanceInfo.exists) {
+        return buildSqlToolResult({
+            success: false,
+            errorCode: "MYSQL_NOT_CREATED",
+            data: sanitizeInstanceInfo(instanceInfo),
+            message: "No MySQL instance exists for the current environment, so connection details cannot be returned.",
+            nextActions: [
+                buildNextAction(MANAGE_MYSQL_DATABASE, "provisionMySQL", "Provision MySQL before requesting connection details.", { action: "provisionMySQL", confirm: true }),
+            ],
+        });
+    }
+    return buildSqlToolResult({
+        success: true,
+        data: {
+            ...sanitizeInstanceInfo(instanceInfo),
+            // Full backend passthrough for explicit TCP migration only (may include credentials).
+            clusterDetail: instanceInfo.clusterDetail,
+            createResult: instanceInfo.createResult,
+        },
+        message: "Returned raw MySQL connection/cluster payload for explicit TCP migration only. Prefer CloudBase SDK or queryMysqlDatabase(runQuery)/manageMysqlDatabase(runStatement) for normal app CRUD — do not treat this as the default data path.",
+        nextActions: [
+            buildNextAction(QUERY_MYSQL_DATABASE, "runQuery", "Prefer platform-delegated read-only SQL instead of embedding TCP credentials in app code.", { action: "runQuery", sql: "SELECT 1" }),
+        ],
+    });
+}
 async function handleProvisionMySQL(args, context) {
     if (args.confirm !== true) {
         return buildSqlToolResult({
@@ -41329,7 +41983,7 @@ async function handleProvisionMySQL(args, context) {
         existing.status === "RUNNING") {
         return buildSqlToolResult({
             success: true,
-            data: existing,
+            data: sanitizeInstanceInfo(existing),
             message: "A SQL database instance already exists for the current environment.",
             nextActions: existing.status === "READY"
                 ? [
@@ -41662,11 +42316,11 @@ function registerSQLDatabaseTools(server) {
     };
     server.registerTool?.(QUERY_MYSQL_DATABASE, {
         title: "查询 CloudBase MySQL 数据库状态或执行只读 SQL",
-        description: "查询 CloudBase MySQL 数据库信息。支持执行只读 SQL、查询 MySQL 开通结果、查询 MySQL 任务状态，以及获取当前实例上下文信息。",
+        description: "查询 CloudBase MySQL 数据库信息。支持执行只读 SQL、查询 MySQL 开通结果、查询 MySQL 任务状态，以及获取当前实例生命周期上下文。标准 getInstanceInfo/describeInstance 不返回连接凭据；仅 getConnectionInfo 透传原始连接/集群载荷（含可能的凭据），且仅用于显式 TCP 迁移。业务 CRUD 优先使用 SDK 或 runQuery/runStatement。",
         inputSchema: {
             action: zod_1.z
                 .enum(QUERY_ACTIONS)
-                .describe("runQuery=execute read-only SQL; describeCreateResult=query CreateMySQL result; describeTaskStatus=query MySQL task status; getInstanceInfo=get current SQL instance context; describeInstance=alias of getInstanceInfo"),
+                .describe("runQuery=execute read-only SQL; describeCreateResult=query CreateMySQL result; describeTaskStatus=query MySQL task status; getInstanceInfo=get lifecycle context without connection credentials; describeInstance=alias of getInstanceInfo; getConnectionInfo=passthrough raw connection/cluster payload including possible credentials (TCP migration exception only)"),
             sql: zod_1.z
                 .string()
                 .optional()
@@ -41702,6 +42356,8 @@ function registerSQLDatabaseTools(server) {
             case "getInstanceInfo":
             case "describeInstance":
                 return handleGetInstanceInfo(context);
+            case "getConnectionInfo":
+                return handleGetConnectionInfo(context);
             default:
                 throw new Error(`Unsupported SQL query action: ${args.action}`);
         }
@@ -84648,6 +85304,154 @@ exports.colors = {
 })));
 
 
+/***/ }),
+
+/***/ 22435:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.rankGatewayAccessUrls = rankGatewayAccessUrls;
+exports.flattenHttpServiceRoutes = flattenHttpServiceRoutes;
+exports.filterRoutesByUpstream = filterRoutesByUpstream;
+exports.toAccessUrlEnvelope = toAccessUrlEnvelope;
+exports.resolveGatewayAccessUrls = resolveGatewayAccessUrls;
+exports.preferGatewayOrFallback = preferGatewayOrFallback;
+function normalizeAccessPath(path) {
+    if (!path) {
+        return "/";
+    }
+    return path.startsWith("/") ? path : `/${path}`;
+}
+function buildHttpsUrl(domain, path) {
+    return `https://${domain}${normalizeAccessPath(path)}`;
+}
+/**
+ * Rank gateway route URLs: custom domains (IsDefault !== true) before default domain.
+ * Stable within each group; dedupe by full URL.
+ */
+function rankGatewayAccessUrls(routes) {
+    const mapped = routes
+        .filter((route) => Boolean(route.Domain))
+        .map((route) => {
+        const path = normalizeAccessPath(route.Path);
+        const isDefault = route.IsDefault === true;
+        return {
+            url: buildHttpsUrl(route.Domain, path),
+            domain: route.Domain,
+            path,
+            isDefault,
+            source: (isDefault
+                ? "gateway.default"
+                : "gateway.custom"),
+        };
+    });
+    mapped.sort((a, b) => {
+        if (a.isDefault === b.isDefault) {
+            return 0;
+        }
+        return a.isDefault ? 1 : -1;
+    });
+    const seen = new Set();
+    const deduped = [];
+    for (const item of mapped) {
+        if (seen.has(item.url)) {
+            continue;
+        }
+        seen.add(item.url);
+        deduped.push(item);
+    }
+    return deduped;
+}
+function flattenHttpServiceRoutes(result) {
+    return (result.Domains ?? []).flatMap((domainItem) => (domainItem.Routes ?? []).map((route) => ({
+        Domain: domainItem.Domain ?? "",
+        IsDefault: domainItem.IsDefault,
+        Path: typeof route.Path === "string" ? route.Path : undefined,
+        UpstreamResourceType: typeof route.UpstreamResourceType === "string"
+            ? route.UpstreamResourceType
+            : undefined,
+        UpstreamResourceName: typeof route.UpstreamResourceName === "string"
+            ? route.UpstreamResourceName
+            : undefined,
+    })));
+}
+function filterRoutesByUpstream(routes, input) {
+    const name = input.upstreamResourceName;
+    const types = input.upstreamResourceTypes?.map((t) => String(t));
+    return routes.filter((route) => {
+        if (route.UpstreamResourceName !== name) {
+            return false;
+        }
+        if (!types || types.length === 0) {
+            return true;
+        }
+        return Boolean(route.UpstreamResourceType &&
+            types.includes(String(route.UpstreamResourceType)));
+    });
+}
+function toAccessUrlEnvelope(ranked) {
+    if (ranked.length === 0) {
+        return { accessUrls: [], routes: [] };
+    }
+    return {
+        accessUrl: ranked[0].url,
+        accessUrls: ranked.map((item) => item.url),
+        accessUrlSource: ranked[0].source,
+        routes: ranked,
+    };
+}
+/**
+ * Best-effort lookup of gateway access URLs for an upstream resource.
+ * Never throws — returns empty lists on failure.
+ */
+async function resolveGatewayAccessUrls(input) {
+    try {
+        const manager = await input.getManager();
+        const result = await manager.env.describeHttpServiceRoute({
+            EnvId: input.envId,
+            Limit: 1000,
+        });
+        const flattened = flattenHttpServiceRoutes(result);
+        const matched = filterRoutesByUpstream(flattened, {
+            upstreamResourceName: input.upstreamResourceName,
+            upstreamResourceTypes: input.upstreamResourceTypes,
+        });
+        return toAccessUrlEnvelope(rankGatewayAccessUrls(matched));
+    }
+    catch {
+        return { accessUrls: [], routes: [] };
+    }
+}
+/**
+ * Merge ranked gateway URLs with a resource-native fallback URL.
+ * Gateway custom/default always win over the fallback when present.
+ */
+function preferGatewayOrFallback(input) {
+    if (input.gateway.accessUrl) {
+        const urls = [...input.gateway.accessUrls];
+        if (input.fallbackUrl &&
+            !urls.includes(input.fallbackUrl)) {
+            urls.push(input.fallbackUrl);
+        }
+        return {
+            accessUrl: input.gateway.accessUrl,
+            accessUrls: urls,
+            accessUrlSource: input.gateway.accessUrlSource,
+        };
+    }
+    if (input.fallbackUrl) {
+        return {
+            accessUrl: input.fallbackUrl,
+            accessUrls: [input.fallbackUrl],
+            accessUrlSource: input.fallbackSource,
+        };
+    }
+    return { accessUrls: [] };
+}
+
+
 /***/ }),
 
 /***/ 22573:
@@ -90059,6 +90863,7 @@ exports.registerFunctionTools = registerFunctionTools;
 const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const cloud_mode_js_1 = __webpack_require__(89684);
+const gateway_access_urls_js_1 = __webpack_require__(22435);
 const json_content_js_1 = __webpack_require__(4365);
 const logger_js_1 = __webpack_require__(13039);
 const fs_1 = __webpack_require__(29021);
@@ -90903,9 +91708,33 @@ function registerFunctionTools(server) {
                 const message = func.type === "HTTP"
                     ? `已创建 HTTP 函数 ${functionName}。如果后续需要通过 URL 访问，请显式调用 manageGateway(action="createRoute")，并把 upstreamResourceType="WEB_SCF" 一起传入，再按实际路径和鉴权需求创建访问入口。评测或其他外部调用方可能会以匿名身份访问，而且失败后不一定会把 EXCEED_AUTHORITY 再反馈给 AI；交付前请主动确认访问路径和函数安全规则，若已出现 EXCEED_AUTHORITY，请先调用 queryPermissions(action="getResourcePermission", resourceType="function", resourceId="${functionName}") 查看当前规则，再按需要使用 managePermissions(action="updateResourcePermission") 调整权限。`
                     : `已创建函数 ${functionName}`;
+                let accessUrl;
+                let accessUrls = [];
+                let accessUrlSource;
+                if (func.type === "HTTP") {
+                    const envId = cloudBaseOptions?.envId ?? await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                    const gateway = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                        envId,
+                        upstreamResourceName: functionName,
+                        upstreamResourceTypes: ["WEB_SCF", "SCF"],
+                        getManager: async () => {
+                            const manager = await getManager();
+                            if (!manager) {
+                                throw new Error("cloudbase manager unavailable");
+                            }
+                            return manager;
+                        },
+                    });
+                    accessUrl = gateway.accessUrl;
+                    accessUrls = gateway.accessUrls;
+                    accessUrlSource = gateway.accessUrlSource;
+                }
                 return buildEnvelope({
                     action: input.action,
                     functionName,
+                    ...(accessUrl ? { accessUrl } : {}),
+                    ...(accessUrls.length > 0 ? { accessUrls } : {}),
+                    ...(accessUrlSource ? { accessUrlSource } : {}),
                     raw: result,
                 }, message, nextActions);
             }
@@ -90944,11 +91773,33 @@ function registerFunctionTools(server) {
                         throw wrapFunctionOperationError("updateFunctionCode", input.functionName, undefined, error);
                     }
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, imageResult);
+                    const envId = cloudBaseOptions?.envId ?? await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                    const imageGatewayAccess = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                        envId,
+                        upstreamResourceName: input.functionName,
+                        upstreamResourceTypes: ["WEB_SCF", "SCF"],
+                        getManager: async () => {
+                            const manager = await getManager();
+                            if (!manager) {
+                                throw new Error("cloudbase manager unavailable");
+                            }
+                            return manager;
+                        },
+                    });
                     return buildEnvelope({
                         action: input.action,
                         functionName: input.functionName,
                         deployMode: "image",
                         imageUri: updateImageConfig.imageUri,
+                        ...(imageGatewayAccess.accessUrl
+                            ? { accessUrl: imageGatewayAccess.accessUrl }
+                            : {}),
+                        ...(imageGatewayAccess.accessUrls.length > 0
+                            ? { accessUrls: imageGatewayAccess.accessUrls }
+                            : {}),
+                        ...(imageGatewayAccess.accessUrlSource
+                            ? { accessUrlSource: imageGatewayAccess.accessUrlSource }
+                            : {}),
                         raw: imageResult,
                     }, `已将函数 ${input.functionName} 的镜像更新为 ${updateImageConfig.imageUri}。` +
                         `部署后可用 queryFunctions(action="getFunctionDetail") 确认函数已就绪（Active）。`, [
@@ -90979,9 +91830,29 @@ function registerFunctionTools(server) {
                     throw wrapFunctionOperationError("updateFunctionCode", input.functionName, processedRootPath, error);
                 }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const envId = cloudBaseOptions?.envId ?? await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                const gatewayAccess = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                    envId,
+                    upstreamResourceName: input.functionName,
+                    upstreamResourceTypes: ["WEB_SCF", "SCF"],
+                    getManager: async () => {
+                        const manager = await getManager();
+                        if (!manager) {
+                            throw new Error("cloudbase manager unavailable");
+                        }
+                        return manager;
+                    },
+                });
                 return buildEnvelope({
                     action: input.action,
                     functionName: input.functionName,
+                    ...(gatewayAccess.accessUrl ? { accessUrl: gatewayAccess.accessUrl } : {}),
+                    ...(gatewayAccess.accessUrls.length > 0
+                        ? { accessUrls: gatewayAccess.accessUrls }
+                        : {}),
+                    ...(gatewayAccess.accessUrlSource
+                        ? { accessUrlSource: gatewayAccess.accessUrlSource }
+                        : {}),
                     raw: result,
                 }, `已更新函数 ${input.functionName} 的代码`, [
                     {
@@ -114238,7 +115109,9 @@ const path_1 = __importDefault(__webpack_require__(39902));
 const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const logger_js_1 = __webpack_require__(13039);
+const gateway_access_urls_js_1 = __webpack_require__(22435);
 const notification_js_1 = __webpack_require__(32720);
+const cloudrun_config_js_1 = __webpack_require__(48266);
 // CloudRun service types
 exports.CLOUDRUN_SERVICE_TYPES = ['function', 'container'];
 // CloudRun access types
@@ -114257,10 +115130,11 @@ const queryCloudRunInputSchema = {
 };
 // Input schema for manageCloudRun tool
 const ManageCloudRunInputSchema = {
-    action: zod_1.z.enum(['init', 'download', 'run', 'deploy', 'delete', 'createAgent']).describe('云托管服务管理操作类型：init=从模板初始化新的云托管项目代码（在targetPath目录下创建以serverName命名的子目录，支持多种语言和框架模板），download=从云端下载现有服务的代码到本地进行开发，run=在本地运行函数型云托管服务（用于开发和调试，仅支持函数型服务），deploy=将本地代码部署到云端云托管服务（支持函数型和容器型），delete=删除指定的云托管服务（不可恢复，需要确认），createAgent=创建函数型Agent（基于函数型云托管开发AI智能体）'),
+    action: zod_1.z.enum(['init', 'download', 'run', 'deploy', 'delete', 'createAgent', 'updateConfig']).describe('云托管服务管理操作类型：init=从模板初始化新的云托管项目代码（在targetPath目录下创建以serverName命名的子目录，支持多种语言和框架模板），download=从云端下载现有服务的代码到本地进行开发，run=在本地运行函数型云托管服务（用于开发和调试，仅支持函数型服务），deploy=将本地代码部署到云端云托管服务（支持函数型和容器型；已存在服务会 Read-Merge-Write 保留远程 VpcConf/EnvParams/OpenAccessTypes），updateConfig=仅更新服务配置不重新上传代码（对齐控制台服务设置，走 SubmitServerConfigChangeDiff；不需要 targetPath），delete=删除指定的云托管服务（不可恢复，需要确认），createAgent=创建函数型Agent（基于函数型云托管开发AI智能体）'),
     serverName: zod_1.z.string().describe('云托管服务名称，用于标识和管理服务。命名规则：支持大小写字母、数字、连字符和下划线，必须以字母开头，长度3-45个字符。在init操作中会作为在targetPath下创建的子目录名，在其他操作中作为目标服务名'),
     // Deploy operation parameters
-    targetPath: zod_1.z.string().optional().describe('本地代码路径，必须是绝对路径。在deploy操作中指定要部署的代码目录，在download操作中指定下载目标目录，在init操作中指定云托管服务的上级目录（会在该目录下创建以serverName命名的子目录）。建议约定：项目根目录下的cloudrun/目录，例如：/Users/username/projects/my-project/cloudrun'),
+    targetPath: zod_1.z.string().optional().describe('本地代码路径，必须是绝对路径。在deploy操作中指定要部署的代码目录，在download操作中指定下载目标目录，在init操作中指定云托管服务的上级目录（会在该目录下创建以serverName命名的子目录）。updateConfig 不需要此参数。建议约定：项目根目录下的cloudrun/目录，例如：/Users/username/projects/my-project/cloudrun'),
+    envParamsReplaceAll: zod_1.z.boolean().optional().default(false).describe('EnvParams 合并策略（deploy / updateConfig）：false（默认）= 与远程按 key 合并（输入覆盖同名 key，远程其余 key 保留）；true= 用输入 EnvParams 整包替换远程。仅当显式传入 EnvParams 时生效'),
     serverConfig: zod_1.z.object({
         OpenAccessTypes: zod_1.z.array(zod_1.z.enum(exports.CLOUDRUN_ACCESS_TYPES)).optional().describe('公网访问类型配置，控制服务的访问权限：OA=办公网访问，PUBLIC=公网访问（默认，可通过HTTPS域名访问），MINIAPP=小程序访问，VPC=VPC访问（仅同VPC内可访问）。可配置多个类型'),
         Cpu: zod_1.z.number().positive().optional().describe('CPU规格配置，单位为核。可选值：0.25、0.5、1、2、4、8等。注意：内存规格必须是CPU规格的2倍（如CPU=0.25时内存=0.5，CPU=1时内存=2）。影响服务性能和计费'),
@@ -114299,7 +115173,7 @@ const ManageCloudRunInputSchema = {
         VpcConf: zod_1.z.object({
             VpcId: zod_1.z.string().describe('VPC网络ID，格式如 vpc-xxxxxxxx。必须与目标数据库/Redis 处于同一地域，并优先选择同一 VPC。禁止猜测或使用占位符；须来自数据库控制台、已有资源详情、callCloudApi 或用户确认。建议首次创建即配置；已存在服务也可在 deploy 时传入，部署后必须用 queryCloudRun detail 复核是否生效'),
             SubnetId: zod_1.z.string().describe('子网ID，格式如 subnet-xxxxxxxx。云托管实例将占用该子网 IP，需确保有足够可用 IP'),
-        }).optional().describe('VPC网络配置（实例出网/私有网络）。用于让云托管实例接入指定 VPC，从而内网访问 MySQL/PostgreSQL/Redis/CVM 等资源。与 OpenAccessTypes（外部如何访问本服务）是不同概念。TCP 连库场景必须配置。禁止猜测 VpcId/SubnetId，须来自数据库控制台、已有资源详情、callCloudApi 或用户确认。MCP 在创建时会将 VpcConf 映射为 SDK vpcInfo(CreateType=2)；更新后必须用 queryCloudRun detail 复核 ServerConfig.VpcConf，未生效再走控制台网络设置或删建兜底'),
+        }).optional().describe('VPC网络配置（实例出网/私有网络）。用于让云托管实例接入指定 VPC，从而内网访问 MySQL/PostgreSQL/Redis/CVM 等资源。与 OpenAccessTypes（外部如何访问本服务）是不同概念。TCP 连库场景必须配置。禁止猜测 VpcId/SubnetId，须来自数据库控制台、已有资源详情、callCloudApi 或用户确认。创建时映射为 SDK vpcInfo(CreateType=2)；已存在服务可用 updateConfig 或 deploy（RMW 会保留未传入的远程 VpcConf）。部署/更新后必须用 queryCloudRun detail 复核 ServerConfig.VpcConf'),
         VolumesConf: zod_1.z.array(zod_1.z.object({
             VolumeName: zod_1.z.string().describe('存储卷名称'),
             VolumeType: zod_1.z.string().describe('存储卷类型，如CFS表示云文件存储'),
@@ -114309,7 +115183,7 @@ const ManageCloudRunInputSchema = {
             PublicAccess: zod_1.z.boolean().optional().describe('是否开启公网访问，true=开启公网访问，false=关闭公网访问'),
             PublicAccessPath: zod_1.z.string().optional().describe('公网访问路径配置')
         }).optional().describe('公网访问配置，用于控制服务的公网访问策略。可配置是否开启公网访问及访问路径'),
-    }).optional().describe('服务配置项，用于部署时设置服务的运行参数。包括资源规格、访问权限、环境变量、日志、网络等配置。不提供时使用默认配置'),
+    }).optional().describe('服务配置项，用于 deploy / updateConfig。包括资源规格、访问权限、环境变量、日志、网络等。deploy 未提供时对已存在服务仍会从远程合并保留 VpcConf/EnvParams/OpenAccessTypes；updateConfig 至少需要一个配置字段'),
     // Init operation parameters
     template: zod_1.z.string().optional().default('helloworld').describe('项目模板标识符，用于指定初始化项目时使用的模板。可通过queryCloudRun的templates操作获取可用模板列表。常用模板：helloworld=Hello World示例，nodejs=Node.js项目模板，python=Python项目模板等'),
     // Run operation parameters (function services only)
@@ -114493,6 +115367,30 @@ function normalizeProcessLogText(logs) {
     })
         .join("\n");
 }
+function normalizeCloudRunDomainUrl(input) {
+    if (typeof input !== "string" || !input.trim())
+        return undefined;
+    const raw = input.trim();
+    return raw.startsWith("http://") || raw.startsWith("https://")
+        ? raw
+        : `https://${raw}`;
+}
+function resolveCloudRunFallbackAccess(details) {
+    const custom = normalizeCloudRunDomainUrl(details?.BaseInfo?.CustomDomainName);
+    if (custom)
+        return { url: custom, source: "cloudrun.customDomain" };
+    const defaultDomain = normalizeCloudRunDomainUrl(details?.BaseInfo?.DefaultDomainName);
+    if (defaultDomain)
+        return { url: defaultDomain, source: "cloudrun.defaultDomain" };
+    const publicDomain = normalizeCloudRunDomainUrl(details?.BaseInfo?.PublicDomain) ??
+        normalizeCloudRunDomainUrl(details?.AccessInfo?.PublicDomain);
+    if (publicDomain)
+        return { url: publicDomain, source: "cloudrun.publicDomain" };
+    const internal = normalizeCloudRunDomainUrl(details?.BaseInfo?.InternalDomain);
+    if (internal)
+        return { url: internal, source: "cloudrun.internalDomain" };
+    return {};
+}
 /**
  * Format CloudRun service info for display
  */
@@ -114726,7 +115624,7 @@ function registerCloudRunTools(server) {
     // Tool 2: Manage CloudRun services (write operations)
     server.registerTool("manageCloudRun", {
         title: "管理 CloudRun 服务",
-        description: "管理云托管服务，按开发顺序支持：初始化项目（可从模板开始，模板列表可通过 queryCloudRun 查询）、下载服务代码、本地运行（仅函数型服务）、部署代码、删除服务。部署可配置CPU、内存、实例数、访问类型等参数。删除操作需要确认，建议设置force=true。",
+        description: "管理云托管服务，按开发顺序支持：初始化项目（可从模板开始，模板列表可通过 queryCloudRun 查询）、下载服务代码、本地运行（仅函数型服务）、部署代码、仅更新配置（updateConfig，无需重新上传代码）、删除服务。deploy 对已存在服务会先读取远程配置再合并（保留 VpcConf/EnvParams/OpenAccessTypes）。updateConfig 对齐控制台服务设置页。删除操作需要确认，建议设置force=true。",
         inputSchema: ManageCloudRunInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -114917,6 +115815,8 @@ for await (let x of res.textStream) {
                 }
                 // Determine service type - use input.serverType if provided, otherwise auto-detect
                 let serverType;
+                let remoteServerConfig = null;
+                let existingService = false;
                 if (input.serverType) {
                     serverType = input.serverType;
                 }
@@ -114925,6 +115825,8 @@ for await (let x of res.textStream) {
                         // First try to get existing service details
                         const details = await cloudrunService.detail({ serverName: input.serverName });
                         serverType = details.BaseInfo?.ServerType || 'container';
+                        remoteServerConfig = (details.ServerConfig || null);
+                        existingService = true;
                     }
                     catch (e) {
                         // If service doesn't exist, determine by project structure
@@ -114958,20 +115860,40 @@ for await (let x of res.textStream) {
                         }
                     }
                 }
+                // When serverType was provided explicitly, still try to load remote config for RMW.
+                if (!existingService) {
+                    try {
+                        const details = await cloudrunService.detail({ serverName: input.serverName });
+                        remoteServerConfig = (details.ServerConfig || null);
+                        existingService = true;
+                    }
+                    catch {
+                        // New service create path
+                    }
+                }
+                let mergedFromRemote = [];
+                let effectiveServerConfig = input.serverConfig;
+                if (existingService) {
+                    const mergedResult = (0, cloudrun_config_js_1.mergeCloudRunServerConfig)({
+                        remote: remoteServerConfig,
+                        input: input.serverConfig || {},
+                        envParamsReplaceAll: Boolean(input.envParamsReplaceAll),
+                    });
+                    effectiveServerConfig = mergedResult.merged;
+                    mergedFromRemote = mergedResult.mergedFromRemote;
+                }
                 const deployParams = {
                     serverName: input.serverName,
                     targetPath: targetPath,
                     force: input.force,
                     serverType: serverType,
                 };
-                // Add server configuration if provided
-                if (input.serverConfig) {
-                    deployParams.serverConfig = input.serverConfig;
+                if (effectiveServerConfig && Object.keys(effectiveServerConfig).length > 0) {
+                    deployParams.serverConfig = effectiveServerConfig;
                 }
                 // Manager SDK create path prefers top-level vpcInfo (CreateCloudRunServer.VpcInfo).
                 // Map serverConfig.VpcConf → vpcInfo so first-time create actually binds VPC.
-                // Update path still sends Items.VpcConf; platform may ignore VPC changes on existing services.
-                const vpcConf = input.serverConfig?.VpcConf;
+                const vpcConf = effectiveServerConfig?.VpcConf;
                 if (vpcConf?.VpcId?.trim() && vpcConf?.SubnetId?.trim()) {
                     deployParams.vpcInfo = {
                         VpcId: vpcConf.VpcId.trim(),
@@ -115002,47 +115924,46 @@ for await (let x of res.textStream) {
                 catch (error) {
                     (0, logger_js_1.debug)('cloudbaserc.json creation skipped:', error instanceof Error ? error : new Error(String(error)));
                 }
+                let preferredAccessUrl;
+                let preferredAccessUrls = [];
+                let preferredAccessSource;
+                let verifiedConfigSnapshot;
+                try {
+                    const serviceDetails = await cloudrunService.detail({
+                        serverName: input.serverName,
+                    });
+                    verifiedConfigSnapshot = (0, cloudrun_config_js_1.summarizeConfigSnapshot)(serviceDetails?.ServerConfig);
+                    const fallback = resolveCloudRunFallbackAccess(serviceDetails);
+                    const gateway = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                        envId: currentEnvId,
+                        upstreamResourceName: input.serverName,
+                        upstreamResourceTypes: ["CBR"],
+                        getManager: async () => {
+                            const manager = await getManager();
+                            if (!manager) {
+                                throw new Error("cloudbase manager unavailable");
+                            }
+                            return manager;
+                        },
+                    });
+                    const preferred = (0, gateway_access_urls_js_1.preferGatewayOrFallback)({
+                        gateway,
+                        fallbackUrl: fallback.url,
+                        fallbackSource: fallback.source,
+                    });
+                    preferredAccessUrl = preferred.accessUrl;
+                    preferredAccessUrls = preferred.accessUrls;
+                    preferredAccessSource = preferred.accessUrlSource;
+                }
+                catch {
+                    // best-effort URL enrichment only
+                }
                 // Send deployment notification to CodeBuddy IDE
                 try {
-                    // Query service details to get access URL
-                    let serviceUrl = "";
-                    try {
-                        const serviceDetails = await cloudrunService.detail({ serverName: input.serverName });
-                        // Extract access URL from service details
-                        // Priority: DefaultDomainName > CustomDomainName > PublicDomain > InternalDomain
-                        const details = serviceDetails; // Use any to access dynamic properties
-                        if (details?.BaseInfo?.DefaultDomainName) {
-                            // DefaultDomainName is already a complete URL (e.g., https://...)
-                            serviceUrl = details.BaseInfo.DefaultDomainName;
-                        }
-                        else if (details?.BaseInfo?.CustomDomainName) {
-                            // CustomDomainName might be a domain without protocol
-                            const customDomain = details.BaseInfo.CustomDomainName;
-                            serviceUrl = customDomain.startsWith('http') ? customDomain : `https://${customDomain}`;
-                        }
-                        else if (details?.BaseInfo?.PublicDomain) {
-                            serviceUrl = `https://${details.BaseInfo.PublicDomain}`;
-                        }
-                        else if (details?.BaseInfo?.InternalDomain) {
-                            serviceUrl = `https://${details.BaseInfo.InternalDomain}`;
-                        }
-                        else if (details?.AccessInfo?.PublicDomain) {
-                            serviceUrl = `https://${details.AccessInfo.PublicDomain}`;
-                        }
-                        else {
-                            serviceUrl = ""; // URL not available
-                        }
-                    }
-                    catch (detailErr) {
-                        // If query fails, continue with empty URL
-                        serviceUrl = "";
-                    }
-                    // Extract project name from targetPath
                     const projectName = path_1.default.basename(targetPath);
-                    // Send notification
                     await (0, notification_js_1.sendDeployNotification)(server, {
                         deployType: 'cloudrun',
-                        url: serviceUrl,
+                        url: preferredAccessUrl ?? "",
                         projectId: currentEnvId,
                         projectName: projectName,
                         consoleUrl: consoleUrl
@@ -115053,8 +115974,8 @@ for await (let x of res.textStream) {
                     // Error is already logged in sendDeployNotification
                 }
                 const dbNetworkRisk = detectCloudRunDbNetworkRisk({
-                    envParams: input.serverConfig?.EnvParams,
-                    vpcConf: input.serverConfig?.VpcConf,
+                    envParams: effectiveServerConfig?.EnvParams,
+                    vpcConf: effectiveServerConfig?.VpcConf,
                 });
                 const warnings = dbNetworkRisk ? [dbNetworkRisk] : [];
                 const warningSuffix = dbNetworkRisk
@@ -115073,6 +115994,25 @@ for await (let x of res.textStream) {
                                     serverType: serverType,
                                     cloudbasercGenerated: true,
                                     consoleUrl,
+                                    ...(existingService
+                                        ? {
+                                            configMerge: {
+                                                existingService: true,
+                                                mergedFromRemote,
+                                                appliedConfig: (0, cloudrun_config_js_1.summarizeConfigSnapshot)(effectiveServerConfig),
+                                                ...(verifiedConfigSnapshot
+                                                    ? { verifiedAfterDeploy: verifiedConfigSnapshot }
+                                                    : {}),
+                                            },
+                                        }
+                                        : {}),
+                                    ...(preferredAccessUrl ? { accessUrl: preferredAccessUrl } : {}),
+                                    ...(preferredAccessUrls.length > 0
+                                        ? { accessUrls: preferredAccessUrls }
+                                        : {}),
+                                    ...(preferredAccessSource
+                                        ? { accessUrlSource: preferredAccessSource }
+                                        : {}),
                                     ...(warnings.length > 0 ? { warnings } : {}),
                                 },
                                 message: `Triggered deployment for ${serverType} service '${input.serverName}' from ${targetPath}. You can follow the progress in ${consoleUrl}.${warningSuffix}`
@@ -115081,6 +116021,125 @@ for await (let x of res.textStream) {
                     ]
                 };
             }
+            case 'updateConfig': {
+                if (!input.serverConfig || Object.keys(input.serverConfig).length === 0) {
+                    throw new Error("serverConfig with at least one field is required for updateConfig");
+                }
+                let remoteServerConfig = {};
+                try {
+                    const details = await cloudrunService.detail({
+                        serverName: input.serverName,
+                    });
+                    remoteServerConfig = (details.ServerConfig ||
+                        {});
+                }
+                catch (error) {
+                    throw new Error(buildManageCloudRunErrorMessage("updateConfig", input.serverName, error));
+                }
+                // EnvParams on Diff replaces the whole blob — merge keys unless replaceAll.
+                const dirty = { ...input.serverConfig };
+                if (Object.prototype.hasOwnProperty.call(input.serverConfig, "EnvParams")) {
+                    const { merged } = (0, cloudrun_config_js_1.mergeCloudRunServerConfig)({
+                        remote: { EnvParams: remoteServerConfig.EnvParams },
+                        input: { EnvParams: input.serverConfig.EnvParams },
+                        envParamsReplaceAll: Boolean(input.envParamsReplaceAll),
+                    });
+                    if (merged.EnvParams !== undefined) {
+                        dirty.EnvParams = merged.EnvParams;
+                    }
+                }
+                let Items;
+                try {
+                    Items = (0, cloudrun_config_js_1.parseServerConfigToDiffItems)(dirty);
+                }
+                catch (error) {
+                    throw new Error(buildManageCloudRunErrorMessage("updateConfig", input.serverName, error));
+                }
+                if (Items.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        serviceName: input.serverName,
+                                        status: "noop",
+                                        itemsCount: 0,
+                                        appliedConfig: (0, cloudrun_config_js_1.summarizeConfigSnapshot)(dirty),
+                                        verifiedConfig: (0, cloudrun_config_js_1.summarizeConfigSnapshot)(remoteServerConfig),
+                                    },
+                                    message: `No effective config changes for '${input.serverName}'.`,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const currentEnvId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                if (!manager.commonService) {
+                    throw new Error("Current CloudBase Manager does not support commonService; cannot call SubmitServerConfigChangeDiff.");
+                }
+                let diffResult;
+                try {
+                    diffResult = await manager
+                        .commonService("tcbr", "2022-02-17")
+                        .call({
+                        Action: "SubmitServerConfigChangeDiff",
+                        Param: {
+                            EnvId: currentEnvId,
+                            ServerName: input.serverName,
+                            Items,
+                        },
+                    });
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    if (/ResourceInUse|task|running|进行中/i.test(msg)) {
+                        throw new Error(buildManageCloudRunErrorMessage("updateConfig", input.serverName, new Error(`${msg} A deploy or config task may still be running. Wait, then retry; or use queryCloudRun(action="getDeployLog").`)));
+                    }
+                    throw new Error(buildManageCloudRunErrorMessage("updateConfig", input.serverName, error));
+                }
+                let verifiedConfig = (0, cloudrun_config_js_1.summarizeConfigSnapshot)(remoteServerConfig);
+                try {
+                    const after = await cloudrunService.detail({
+                        serverName: input.serverName,
+                    });
+                    verifiedConfig = (0, cloudrun_config_js_1.summarizeConfigSnapshot)(after?.ServerConfig);
+                }
+                catch {
+                    // best-effort verify
+                }
+                const likelyRedeploy = (0, cloudrun_config_js_1.listLikelyRedeployFields)(dirty);
+                const consoleUrl = `https://tcb.cloud.tencent.com/dev?envId=${currentEnvId}#/platform-run/service/detail?serverName=${input.serverName}&tabId=overview&envId=${currentEnvId}`;
+                const taskId = diffResult?.TaskId ??
+                    diffResult?.Response?.TaskId ??
+                    diffResult?.taskId;
+                const redeployHint = likelyRedeploy.length > 0
+                    ? ` Fields that often trigger redeploy-with-online-image: ${likelyRedeploy.join(", ")}.`
+                    : " Change may apply as a hot update (e.g. MinNum/MaxNum/AccessTypes).";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                data: {
+                                    serviceName: input.serverName,
+                                    status: "configUpdating",
+                                    itemsCount: Items.length,
+                                    itemsKeys: Items.map((i) => i.Key),
+                                    ...(taskId ? { taskId } : {}),
+                                    appliedConfig: (0, cloudrun_config_js_1.summarizeConfigSnapshot)(dirty),
+                                    verifiedConfig,
+                                    likelyRedeployFields: likelyRedeploy,
+                                    consoleUrl,
+                                },
+                                message: `Submitted config change for '${input.serverName}'.${redeployHint} Verify with queryCloudRun(action="detail"). Console: ${consoleUrl}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'run': {
                 if (!targetPath) {
                     throw new Error("targetPath is required for run operation");
@@ -117768,6 +118827,7 @@ const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const json_content_js_1 = __webpack_require__(4365);
 const cloud_mode_js_1 = __webpack_require__(89684);
+const gateway_access_urls_js_1 = __webpack_require__(22435);
 const QUERY_APP_ACTIONS = ["listApps", "getApp", "listAppVersions", "getAppVersion", "getBuildLog"];
 const MANAGE_APP_ACTIONS = ["deployApp", "getUploadUrl", "deleteApp", "deleteAppVersion"];
 const APP_FRAMEWORKS = ["vue", "react", "next", "nuxt", "vite", "angular", "static"];
@@ -118144,6 +119204,8 @@ function registerAppTools(server) {
                 let appInfo;
                 let domain;
                 let accessUrl;
+                let accessUrls = [];
+                let accessUrlSource;
                 let accessUrlLookupWarning;
                 try {
                     appInfo = await appService.describeAppInfo({
@@ -118152,9 +119214,34 @@ function registerAppTools(server) {
                     });
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, appInfo);
                     ({ domain, accessUrl } = normalizeAccessUrlFromDomain(appInfo?.Domain));
+                    const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                    const gateway = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                        envId,
+                        upstreamResourceName: serviceName,
+                        upstreamResourceTypes: ["STATIC_STORE"],
+                        getManager: async () => {
+                            const manager = await getManager();
+                            if (!manager) {
+                                throw new Error("cloudbase manager unavailable");
+                            }
+                            return manager;
+                        },
+                    });
+                    const preferred = (0, gateway_access_urls_js_1.preferGatewayOrFallback)({
+                        gateway,
+                        fallbackUrl: accessUrl,
+                        fallbackSource: "describeAppInfo.Domain",
+                    });
+                    accessUrl = preferred.accessUrl;
+                    accessUrls = preferred.accessUrls;
+                    accessUrlSource = preferred.accessUrlSource;
                 }
                 catch (error) {
                     accessUrlLookupWarning = error instanceof Error ? error.message : String(error);
+                    if (accessUrl) {
+                        accessUrls = [accessUrl];
+                        accessUrlSource = "describeAppInfo.Domain";
+                    }
                 }
                 return (0, json_content_js_1.jsonContent)(buildEnvelope({
                     action,
@@ -118163,7 +119250,8 @@ function registerAppTools(server) {
                     buildId: BuildId,
                     domain,
                     accessUrl,
-                    accessUrlSource: accessUrl ? "describeAppInfo.Domain" : undefined,
+                    accessUrls: accessUrls.length > 0 ? accessUrls : undefined,
+                    accessUrlSource,
                     accessUrlLookupWarning,
                     app: appInfo,
                     upload: { cosTimestamp: cosTs },
@@ -119537,6 +120625,7 @@ const path_1 = __importDefault(__webpack_require__(39902));
 const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const cloud_mode_js_1 = __webpack_require__(89684);
+const gateway_access_urls_js_1 = __webpack_require__(22435);
 const notification_js_1 = __webpack_require__(32720);
 const tool_result_js_1 = __webpack_require__(9835);
 const HOSTING_CDN_SWITCH_VALUES = ['on', 'off'];
@@ -120072,9 +121161,48 @@ function registerHostingTools(server) {
                     // StaticDomain there but not in DescribeStaticStore.
                     const cdnFromStore = (store.CdnDomain ?? store.StaticDomain);
                     const staticDomain = cdnFromStore || await resolveHostingStaticDomain(cloudbase, server.logger);
-                    const accessUrl = buildHostingAccessUrl(staticDomain, input.cloudPath, input.localPath);
+                    const fallbackAccessUrl = buildHostingAccessUrl(staticDomain, input.cloudPath, input.localPath);
+                    const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                    const gatewayCandidates = Array.from(new Set([
+                        store.StaticStoreName,
+                        store.Name,
+                        store.StoreName,
+                        store.Bucket,
+                        "staticstore",
+                    ]
+                        .map((item) => (typeof item === "string" ? item.trim() : ""))
+                        .filter(Boolean)));
+                    let accessUrl = fallbackAccessUrl;
+                    let accessUrls = accessUrl ? [accessUrl] : [];
+                    let accessUrlSource = accessUrl
+                        ? "hosting.staticDomain"
+                        : undefined;
+                    for (const upstreamName of gatewayCandidates) {
+                        const gateway = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
+                            envId,
+                            upstreamResourceName: upstreamName,
+                            upstreamResourceTypes: ["STATIC_STORE"],
+                            getManager: async () => {
+                                const manager = await getManager();
+                                if (!manager) {
+                                    throw new Error("cloudbase manager unavailable");
+                                }
+                                return manager;
+                            },
+                        });
+                        const preferred = (0, gateway_access_urls_js_1.preferGatewayOrFallback)({
+                            gateway,
+                            fallbackUrl: fallbackAccessUrl || undefined,
+                            fallbackSource: "hosting.staticDomain",
+                        });
+                        if (preferred.accessUrl) {
+                            accessUrl = preferred.accessUrl;
+                            accessUrls = preferred.accessUrls;
+                            accessUrlSource = preferred.accessUrlSource;
+                            break;
+                        }
+                    }
                     try {
-                        const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
                         let projectName = 'unknown';
                         if (input.localPath) {
                             try {
@@ -120109,6 +121237,8 @@ function registerHostingTools(server) {
                             ignore: input.ignore,
                             staticDomain,
                             accessUrl,
+                            accessUrls,
+                            accessUrlSource,
                             result,
                             nextActions: uploadPrefix ? [buildFindFilesNextStep(uploadPrefix.replace(/^\/+/, ''))] : undefined,
                         },
@@ -137205,7 +138335,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.1" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.3" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -148174,6 +149304,220 @@ function compileAsync(schema, meta, callback) {
 }
 
 
+/***/ }),
+
+/***/ 48266:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+/**
+ * CloudRun serverConfig merge (RMW) and DiffConfigItem helpers.
+ * Aligns with console SubmitServerConfigChangeDiff field mapping.
+ */
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.CONFIG_FIELDS_LIKELY_REDEPLOY = void 0;
+exports.mergeCloudRunServerConfig = mergeCloudRunServerConfig;
+exports.assertCpuMemPair = assertCpuMemPair;
+exports.parseServerConfigToDiffItems = parseServerConfigToDiffItems;
+exports.summarizeConfigSnapshot = summarizeConfigSnapshot;
+exports.listLikelyRedeployFields = listLikelyRedeployFields;
+const SUBMIT_DIFF_MAP = {
+    Cpu: "CpuSpecs",
+    Mem: "MemSpecs",
+    OpenAccessTypes: "AccessTypes",
+    EnvParams: "EnvParam",
+    CustomLogs: "LogPath",
+};
+const STRING_KEYS = new Set([
+    "CustomLogs",
+    "EnvParams",
+    "CreateTime",
+    "Dockerfile",
+    "BuildDir",
+    "LogType",
+    "LogSetId",
+    "LogTopicId",
+    "LogParseType",
+    "Tag",
+    "InternalAccess",
+    "InternalDomain",
+    "OperationMode",
+    "SessionAffinity",
+]);
+const INT_KEYS = new Set(["MinNum", "MaxNum", "InitialDelaySeconds", "Port"]);
+const BOOL_KEYS = new Set(["HasDockerfile"]);
+const FLOAT_KEYS = new Set(["Cpu", "Mem"]);
+const ARRAY_KEYS = new Set(["OpenAccessTypes", "EntryPoint", "Cmd"]);
+function parseEnvParamsObject(raw) {
+    if (!raw || !String(raw).trim()) {
+        return {};
+    }
+    try {
+        const value = JSON.parse(String(raw));
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return {};
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v === undefined || v === null)
+                continue;
+            out[k] = typeof v === "string" ? v : String(v);
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function stringifyEnvParams(obj) {
+    return JSON.stringify(obj);
+}
+function isCompleteVpcConf(vpc) {
+    return Boolean(vpc?.VpcId?.trim() && vpc?.SubnetId?.trim());
+}
+/**
+ * Merge remote ServerConfig with deploy/update input.
+ * Explicit input wins for provided fields; EnvParams merges by key unless replaceAll.
+ */
+function mergeCloudRunServerConfig(options) {
+    const remote = options.remote || {};
+    const input = options.input || {};
+    const mergedFromRemote = [];
+    const merged = { ...input };
+    if (isCompleteVpcConf(input.VpcConf)) {
+        merged.VpcConf = {
+            VpcId: input.VpcConf.VpcId.trim(),
+            SubnetId: input.VpcConf.SubnetId.trim(),
+            ...(input.VpcConf.VpcCIDR ? { VpcCIDR: input.VpcConf.VpcCIDR } : {}),
+            ...(input.VpcConf.SubnetCIDR ? { SubnetCIDR: input.VpcConf.SubnetCIDR } : {}),
+        };
+    }
+    else if (isCompleteVpcConf(remote.VpcConf)) {
+        merged.VpcConf = {
+            VpcId: remote.VpcConf.VpcId.trim(),
+            SubnetId: remote.VpcConf.SubnetId.trim(),
+            ...(remote.VpcConf.VpcCIDR ? { VpcCIDR: remote.VpcConf.VpcCIDR } : {}),
+            ...(remote.VpcConf.SubnetCIDR ? { SubnetCIDR: remote.VpcConf.SubnetCIDR } : {}),
+        };
+        mergedFromRemote.push("VpcConf");
+    }
+    else {
+        delete merged.VpcConf;
+    }
+    const inputHasEnv = Object.prototype.hasOwnProperty.call(input, "EnvParams");
+    const remoteEnv = parseEnvParamsObject(remote.EnvParams);
+    const inputEnv = parseEnvParamsObject(input.EnvParams);
+    if (options.envParamsReplaceAll && inputHasEnv) {
+        merged.EnvParams = stringifyEnvParams(inputEnv);
+    }
+    else if (inputHasEnv || Object.keys(remoteEnv).length > 0) {
+        const combined = options.envParamsReplaceAll
+            ? { ...inputEnv }
+            : { ...remoteEnv, ...inputEnv };
+        if (Object.keys(remoteEnv).length > 0 && !options.envParamsReplaceAll) {
+            const preserved = Object.keys(remoteEnv).filter((k) => !(k in inputEnv));
+            if (preserved.length > 0) {
+                mergedFromRemote.push("EnvParams");
+            }
+        }
+        if (Object.keys(combined).length > 0 || inputHasEnv) {
+            merged.EnvParams = stringifyEnvParams(combined);
+        }
+    }
+    // Must be explicit so Manager SDK update path cannot wipe with OA/PUBLIC/MINIAPP defaults.
+    if (Array.isArray(input.OpenAccessTypes) && input.OpenAccessTypes.length > 0) {
+        merged.OpenAccessTypes = [...input.OpenAccessTypes];
+    }
+    else if (Array.isArray(remote.OpenAccessTypes) && remote.OpenAccessTypes.length > 0) {
+        merged.OpenAccessTypes = [...remote.OpenAccessTypes];
+        mergedFromRemote.push("OpenAccessTypes");
+    }
+    return { merged, mergedFromRemote };
+}
+function assertCpuMemPair(config) {
+    const hasCpu = config.Cpu !== undefined && config.Cpu !== null;
+    const hasMem = config.Mem !== undefined && config.Mem !== null;
+    if (hasCpu !== hasMem) {
+        throw new Error("Cpu and Mem must be provided together when updating CloudRun config (platform requires the pair).");
+    }
+}
+/**
+ * Convert serverConfig object to DiffConfigItem[] for SubmitServerConfigChangeDiff.
+ */
+function parseServerConfigToDiffItems(data) {
+    assertCpuMemPair(data);
+    const Items = [];
+    for (const [k, v] of Object.entries(data)) {
+        if (v === undefined || v === null)
+            continue;
+        const Key = SUBMIT_DIFF_MAP[k] || k;
+        if (STRING_KEYS.has(k)) {
+            if (v !== "") {
+                Items.push({ Key, Value: String(v) });
+            }
+        }
+        else if (INT_KEYS.has(k)) {
+            Items.push({ Key, IntValue: Number(v) });
+        }
+        else if (BOOL_KEYS.has(k)) {
+            Items.push({ Key, BoolValue: Boolean(v) });
+        }
+        else if (FLOAT_KEYS.has(k)) {
+            Items.push({ Key, FloatValue: Number(v) });
+        }
+        else if (ARRAY_KEYS.has(k)) {
+            Items.push({ Key, ArrayValue: v });
+        }
+        else if (k === "PolicyDetails") {
+            Items.push({ Key, PolicyDetails: v });
+        }
+        else if (k === "TimerScale") {
+            Items.push({ Key, TimerScale: v });
+        }
+        else if (k === "VpcConf") {
+            Items.push({ Key, VpcConf: v });
+        }
+        else if (k === "VolumesConf") {
+            Items.push({ Key, VolumesConf: v });
+        }
+        else if (k === "PublicNetConf") {
+            Items.push({ Key, PublicNetConf: v });
+        }
+    }
+    return Items;
+}
+function summarizeConfigSnapshot(config) {
+    const vpc = config?.VpcConf;
+    const envKeys = Object.keys(parseEnvParamsObject(config?.EnvParams));
+    return {
+        hasVpcConf: isCompleteVpcConf(vpc),
+        ...(vpc?.VpcId ? { vpcId: vpc.VpcId } : {}),
+        ...(vpc?.SubnetId ? { subnetId: vpc.SubnetId } : {}),
+        ...(Array.isArray(config?.OpenAccessTypes)
+            ? { openAccessTypes: config.OpenAccessTypes }
+            : {}),
+        envParamKeys: envKeys,
+    };
+}
+exports.CONFIG_FIELDS_LIKELY_REDEPLOY = [
+    "VpcConf",
+    "EnvParams",
+    "Cpu",
+    "Mem",
+    "Port",
+    "Dockerfile",
+    "BuildDir",
+    "VolumesConf",
+    "LogType",
+    "LogSetId",
+    "LogTopicId",
+];
+function listLikelyRedeployFields(config) {
+    return exports.CONFIG_FIELDS_LIKELY_REDEPLOY.filter((k) => Object.prototype.hasOwnProperty.call(config, k));
+}
+
+
 /***/ }),
 
 /***/ 48303:
@@ -160875,6 +162219,68 @@ function isSchemaDdlRisk(risk, sql) {
 function buildLocalMigrationFileHint(version, name) {
     return `migrations/${version}_${name}.sql`;
 }
+/** How many recent migration records to scan when verifying a freshly pushed version. */
+const MIGRATION_VERIFY_LIMIT = 100;
+/**
+ * Collect every migration version mentioned anywhere in a migration-list API response.
+ * The response shape is not strongly typed, so walk it generically and pick up any
+ * `Version` / `MigrationVersion` string field instead of guessing a single container key.
+ */
+function collectMigrationVersions(value, found = new Set()) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectMigrationVersions(item, found);
+        }
+        return found;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            if ((key === "Version" || key === "MigrationVersion") && typeof child === "string" && child.trim()) {
+                found.add(child.trim());
+            }
+            else {
+                collectMigrationVersions(child, found);
+            }
+        }
+    }
+    return found;
+}
+/** Brief retries before concluding a pushed migration never landed (Push can be async). */
+const MIGRATION_VERIFY_ATTEMPTS = 4;
+const MIGRATION_VERIFY_DELAY_MS = 1500;
+/**
+ * Confirm a pushed migration version is present in the remote migration history.
+ *
+ * `PushPGUserMigrations` can return a TaskId without the migration actually being
+ * applied, so the raw API response is not sufficient evidence of success. Retries
+ * briefly to tolerate async application, then returns `true`/`false` when the
+ * history could be read, or `null` when verification itself failed (in which case
+ * the caller must not claim the migration is applied).
+ */
+async function verifyMigrationApplied(context, version, cloudBaseOptions) {
+    let lastError;
+    let sawSuccessfulList = false;
+    for (let attempt = 1; attempt <= MIGRATION_VERIFY_ATTEMPTS; attempt++) {
+        try {
+            const history = await callPgMigrationApi(context, "ListPGUserMigrations", { Limit: MIGRATION_VERIFY_LIMIT }, cloudBaseOptions);
+            sawSuccessfulList = true;
+            if (collectMigrationVersions(history).has(version)) {
+                return { applied: true };
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            // Keep retrying: a transient list failure should not immediately fail verification.
+        }
+        if (attempt < MIGRATION_VERIFY_ATTEMPTS) {
+            await sleep(MIGRATION_VERIFY_DELAY_MS);
+        }
+    }
+    if (sawSuccessfulList) {
+        return { applied: false };
+    }
+    return { applied: null, error: lastError };
+}
 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.";
@@ -161747,6 +163153,49 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
     try {
         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 verification = await verifyMigrationApplied(context, version, cloudBaseOptions);
+        if (verification.applied === false) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_NOT_APPLIED",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    apiResult: result,
+                    verified: false,
+                },
+                message: `PushPGUserMigrations returned without error, 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.",
+                nextActions: [
+                    buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Inspect the remote migration history to confirm the migration is missing.", { action: "listMigrations", limit: 20 }),
+                    buildNextAction(MANAGE_PG_DATABASE, "migrationDetail", "Inspect the backend record for this migrationVersion to find why it was not applied.", { action: "migrationDetail", migrationVersion: version }),
+                ],
+            });
+        }
+        if (verification.applied === null) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_VERIFICATION_FAILED",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    apiResult: result,
+                    verified: null,
+                },
+                message: `PushPGUserMigrations was submitted, but verifying migrationVersion=${version} against the remote history failed: ${verification.error}. ` +
+                    "The migration may or may not have been applied — verify with action=listMigrations before running any dependent SQL.",
+                nextActions: [
+                    buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Manually verify whether the remote migration history records this migrationVersion.", { action: "listMigrations", limit: 20 }),
+                ],
+            });
+        }
         return buildPgToolResult({
             success: true,
             data: {
@@ -161754,11 +163203,9 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                 migrationName: args.migrationName,
                 localFileHint,
                 apiResult: result,
+                verified: true,
             },
-            message: `Migrations applied via PushPGUserMigrations. Ensure local file ${localFileHint} exists and matches.`,
-            nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Verify the remote migration history records the same migrationVersion.", { action: "listMigrations", limit: 20 }),
-            ],
+            message: `Migrations applied via PushPGUserMigrations and verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
         });
     }
     catch (error) {
@@ -162037,7 +163484,7 @@ function registerPGDatabaseTools(server, providedDeps) {
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_ACTIONS)
-                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
+                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true；成功返回前会自动校验该 migrationVersion 已落入远端迁移历史，未落库时返回 success=false 且 errorCode=MIGRATION_NOT_APPLIED）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
             sql: zod_1.z
                 .string()
                 .optional()
@@ -197301,7 +198748,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.1" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.3" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -197382,7 +198829,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.1" : 0;
+            const mcpVersion =  true ? "2.25.3" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -213970,7 +215417,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.1" : 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.3" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -231068,6 +232515,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.registerGatewayTools = registerGatewayTools;
 const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
+const gateway_access_urls_js_1 = __webpack_require__(22435);
 const json_content_js_1 = __webpack_require__(4365);
 const QUERY_GATEWAY_ACTIONS = [
     "listRoutes",
@@ -231081,6 +232529,8 @@ const MANAGE_GATEWAY_ACTIONS = [
     "bindCustomDomain",
     "deleteCustomDomain",
 ];
+/** DomainType of the environment default HTTP service (gateway) domain. */
+const HTTP_SERVICE_DOMAIN_TYPE = "HTTPSERVICE";
 const UPSTREAM_RESOURCE_TYPES = [
     "SCF",
     "WEB_SCF",
@@ -231117,21 +232567,19 @@ function registerGatewayTools(server) {
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
         }
     };
-    const listHttpServiceRoutes = async (domain) => {
+    const listHttpServiceRoutes = async (options) => {
+        const filters = [];
+        if (options?.domain) {
+            filters.push({ Name: "Domain", Values: [options.domain] });
+        }
+        if (options?.domainType) {
+            filters.push({ Name: "DomainType", Values: [options.domainType] });
+        }
         const cloudbase = await getManager();
         const result = await cloudbase.env.describeHttpServiceRoute({
             EnvId: await resolveEnvId(),
             Limit: 1000,
-            ...(domain
-                ? {
-                    Filters: [
-                        {
-                            Name: "Domain",
-                            Values: [domain],
-                        },
-                    ],
-                }
-                : {}),
+            ...(filters.length ? { Filters: filters } : {}),
         });
         (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
         return result;
@@ -231143,18 +232591,54 @@ function registerGatewayTools(server) {
         IsDefault: domainItem.IsDefault,
         ...route,
     })));
-    const buildRouteUrls = (routes) => Array.from(new Set(routes
-        .filter((route) => route.Domain && route.Path)
-        .map((route) => `https://${route.Domain}${normalizeAccessPath(String(route.Path))}`)));
+    const buildRouteUrls = (routes) => {
+        const candidates = routes.map((route) => ({
+            Domain: route.Domain,
+            Path: route.Path,
+            IsDefault: route.IsDefault,
+            UpstreamResourceType: route.UpstreamResourceType,
+            UpstreamResourceName: route.UpstreamResourceName,
+        }));
+        return (0, gateway_access_urls_js_1.rankGatewayAccessUrls)(candidates).map((item) => item.url);
+    };
+    const buildAccessUrlFields = (routes) => {
+        const candidates = routes.map((route) => ({
+            Domain: route.Domain,
+            Path: route.Path,
+            IsDefault: route.IsDefault,
+            UpstreamResourceType: route.UpstreamResourceType,
+            UpstreamResourceName: route.UpstreamResourceName,
+        }));
+        const envelope = (0, gateway_access_urls_js_1.toAccessUrlEnvelope)((0, gateway_access_urls_js_1.rankGatewayAccessUrls)(candidates));
+        return {
+            ...(envelope.accessUrl ? { accessUrl: envelope.accessUrl } : {}),
+            accessUrls: envelope.accessUrls,
+            ...(envelope.accessUrlSource
+                ? { accessUrlSource: envelope.accessUrlSource }
+                : {}),
+        };
+    };
+    const pickUsableDefaultDomain = (domains) => {
+        const candidates = domains.filter((item) => item.IsDefault === true && item.Domain);
+        return (candidates.find((item) => item.Enable !== false && item.Status === "SUCCESS") ??
+            candidates.find((item) => item.Enable !== false) ??
+            candidates[0]);
+    };
     const resolveDefaultHttpDomain = async () => {
-        const routeInfo = await listHttpServiceRoutes();
-        const domains = routeInfo.Domains ?? [];
-        const defaultCandidates = domains.filter((item) => item.IsDefault === true && item.Domain);
-        const preferred = defaultCandidates.find((item) => item.Enable !== false && item.Status === "SUCCESS") ??
-            defaultCandidates.find((item) => item.Enable !== false) ??
-            defaultCandidates[0];
+        // Match console DescribeHTTPServiceRoute usage: filter DomainType=HTTPSERVICE.
+        // Envs often also expose an IsDefault STATIC_STORE domain (*.tcloudbaseapp.com);
+        // that is NOT the default HTTP access entry (*.{region}.app.tcloudbase.com).
+        const httpServiceRoutes = await listHttpServiceRoutes({
+            domainType: HTTP_SERVICE_DOMAIN_TYPE,
+        });
+        // Always re-filter client-side: some SDKs/mocks may ignore Filters.
+        let preferred = pickUsableDefaultDomain((httpServiceRoutes.Domains ?? []).filter((item) => item.DomainType === HTTP_SERVICE_DOMAIN_TYPE));
+        if (!preferred?.Domain) {
+            const allRoutes = await listHttpServiceRoutes();
+            preferred = pickUsableDefaultDomain((allRoutes.Domains ?? []).filter((item) => item.DomainType === HTTP_SERVICE_DOMAIN_TYPE));
+        }
         if (!preferred?.Domain) {
-            throw new Error("环境默认 HTTP 访问域名未就绪或未开通。请先在控制台开通 HTTP 访问服务，或用 queryGateway(action=\"listRoutes\") 确认 Domains 中是否存在 IsDefault=true 的域名；也可以显式传入 domain 后重试 createRoute/updateRoute/deleteRoute。");
+            throw new Error("环境默认 HTTP 访问域名未就绪或未开通。请先在控制台开通 HTTP 访问服务，或用 queryGateway(action=\"listRoutes\") 确认 Domains 中是否存在 DomainType=HTTPSERVICE 且 IsDefault=true 的域名（形如 *.{region}.app.tcloudbase.com）；不要使用静态托管域名（*.tcloudbaseapp.com）。也可以显式传入 domain 后重试 createRoute/updateRoute/deleteRoute。");
         }
         return preferred.Domain;
     };
@@ -231250,12 +232734,13 @@ function registerGatewayTools(server) {
                 }, `已获取 ${customDomains.length} 个自定义域名`);
             }
             case "listRoutes": {
-                const result = await listHttpServiceRoutes(input.domain);
+                const result = await listHttpServiceRoutes({ domain: input.domain });
                 const routes = flattenRoutes(result);
                 return buildEnvelope({
                     action: input.action,
                     routes,
                     urls: buildRouteUrls(routes),
+                    ...buildAccessUrlFields(routes),
                     total: result.TotalCount ?? routes.length,
                     raw: result,
                 }, `已获取 ${result.TotalCount ?? routes.length} 条 HTTP 路由`);
@@ -231264,7 +232749,7 @@ function registerGatewayTools(server) {
                 if (!input.routeId && !input.targetName && !input.path) {
                     throw new Error("action=getRoute 时至少需要提供 routeId、targetName 或 path");
                 }
-                const result = await listHttpServiceRoutes(input.domain);
+                const result = await listHttpServiceRoutes({ domain: input.domain });
                 const normalizedPath = input.path
                     ? normalizeAccessPath(input.path)
                     : undefined;
@@ -231297,6 +232782,7 @@ function registerGatewayTools(server) {
                     routes: matches,
                     total: matches.length,
                     urls,
+                    ...buildAccessUrlFields(matches),
                     raw: result,
                 }, matches.length === 0
                     ? "未找到对应路由"
@@ -231350,6 +232836,11 @@ function registerGatewayTools(server) {
                     upstreamResourceName: payload.resolved.upstreamResourceName,
                     auth: payload.resolved.enableAuth ?? null,
                     enablePathTransmission: payload.resolved.enablePathTransmission ?? null,
+                    accessUrl: `https://${payload.resolved.domain}${payload.resolved.path}`,
+                    accessUrls: [`https://${payload.resolved.domain}${payload.resolved.path}`],
+                    accessUrlSource: input.domain && input.domain === payload.resolved.domain
+                        ? "gateway.custom"
+                        : "gateway.default",
                     raw: result,
                 }, `已为目标 ${payload.resolved.upstreamResourceName} 在域名 ${payload.resolved.domain} 创建路由 ${payload.resolved.path}（${payload.resolved.upstreamResourceType}）` +
                     (payload.resolved.enablePathTransmission === true
@@ -231376,6 +232867,11 @@ function registerGatewayTools(server) {
                     upstreamResourceName: payload.resolved.upstreamResourceName,
                     auth: payload.resolved.enableAuth ?? null,
                     enablePathTransmission: payload.resolved.enablePathTransmission ?? null,
+                    accessUrl: `https://${payload.resolved.domain}${payload.resolved.path}`,
+                    accessUrls: [`https://${payload.resolved.domain}${payload.resolved.path}`],
+                    accessUrlSource: input.domain && input.domain === payload.resolved.domain
+                        ? "gateway.custom"
+                        : "gateway.default",
                     raw: result,
                 }, `HTTP 路由更新成功（${payload.resolved.domain}${payload.resolved.path}` +
                     (payload.resolved.enablePathTransmission === true
@@ -231451,11 +232947,13 @@ function registerGatewayTools(server) {
         title: "查询 CloudBase 网关",
         description: "CloudBase HTTP 网关统一只读入口（Domain/Route）。查询域名下路径路由及其上游：" +
             "WEB_SCF/SCF=云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器。" +
-            "主键为 Domain + Path；listRoutes / getRoute / listCustomDomains。",
+            "主键为 Domain + Path；listRoutes / getRoute / listCustomDomains。" +
+            "实现自定义域名访问前，先 listCustomDomains：若已有自定义域名，优先 createRoute 挂路由（无需证书 ID）；仅在没有可用自定义域名时才 bindCustomDomain。",
         inputSchema: {
             action: zod_1.z
                 .enum(QUERY_GATEWAY_ACTIONS)
-                .describe("只读操作类型：listRoutes、getRoute、listCustomDomains"),
+                .describe("只读操作类型：listRoutes、getRoute、listCustomDomains。" +
+                "自定义域名访问场景先 listCustomDomains 确认是否已有域名可复用。"),
             targetName: zod_1.z
                 .string()
                 .optional()
@@ -231478,18 +232976,23 @@ function registerGatewayTools(server) {
     }, async (input) => withEnvelope(() => handleQueryGateway(input)));
     server.registerTool?.("manageGateway", {
         title: "管理 CloudBase 网关",
-        description: "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；未传 domain 时用 IsDefault 默认域名。" +
+        description: "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；未传 domain 时用 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（形如 *.{region}.app.tcloudbase.com），不会使用静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）。" +
+            "这是网关默认域上的路径路由，不是 STATIC_STORE 上游绑定；STATIC_STORE 上游必须显式传 upstreamResourceType=STATIC_STORE。" +
+            "创建后可用 queryGateway(action=\"listRoutes\") 核对 Domain / DomainType / Path / UpstreamResourceType。" +
             "上游类型只用一个参数 upstreamResourceType（也可写在 route.upstreamResourceType，route 优先）：" +
             "WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器；" +
             "配合 targetName 或 route.serviceName（云函数名/云托管服务名/静态托管实例名，常见 staticstore）。" +
             "createRoute 只建网关入口，不改上游权限。" +
             "enablePathTransmission：默认 false 剥触发路径前缀；true 透传完整路径（CBR 多路由、WEB_SCF 自管子路径常需 true；STATIC_STORE 自定义触发路径映射站点根通常 false）。" +
-            "⚠️ SSL 自定义域名用 bindCustomDomain；CORS/安全域名用 envDomainManagement。",
+            "⚠️ 自定义域名访问：若环境已有自定义域名（先 queryGateway listCustomDomains），优先 createRoute 并显式传入该 domain，无需 certificateId；" +
+            "仅首次绑定全新自定义域名时用 bindCustomDomain（需 certificateId）。CORS/安全域名用 envDomainManagement。",
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_GATEWAY_ACTIONS)
                 .describe("写操作：createRoute/updateRoute/deleteRoute 管理路由；bindCustomDomain/deleteCustomDomain 管理自定义域名。" +
-                "createRoute/updateRoute 必须提供 upstreamResourceType。"),
+                "createRoute/updateRoute 必须提供 upstreamResourceType。" +
+                "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
+                "bindCustomDomain 仅用于首次绑定新域名。"),
             targetName: zod_1.z
                 .string()
                 .optional()
@@ -231543,11 +233046,15 @@ function registerGatewayTools(server) {
             domain: zod_1.z
                 .string()
                 .optional()
-                .describe("域名。省略时自动使用环境 IsDefault 默认 HTTP 域名；自定义域名场景请显式传入"),
+                .describe("域名。省略时自动使用环境 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（*.{region}.app.tcloudbase.com），不会回退到静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）；也不是 STATIC_STORE 上游绑定。" +
+                "可用 queryGateway(action=\"listRoutes\") 核对实际 Domain / DomainType。" +
+                "已有自定义域名时请显式传入该域名并 createRoute/updateRoute/deleteRoute，即可实现自定义域名访问且无需证书 ID；" +
+                "仅 bindCustomDomain 时表示要新绑定的域名。"),
             certificateId: zod_1.z
                 .string()
                 .optional()
-                .describe("证书 ID。bindCustomDomain 时必填"),
+                .describe("证书 ID。仅首次 bindCustomDomain 必填。" +
+                "在已有自定义域名上 createRoute / updateRoute / deleteRoute 不需要 certificateId。"),
         },
         annotations: {
             readOnlyHint: false,