@cloudbase/cloudbase-mcp 2.25.2 → 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}`);
         }
@@ -137679,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.2" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.3" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -161563,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.";
@@ -162435,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: {
@@ -162442,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) {
@@ -162725,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()
@@ -197989,7 +198748,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.2" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.3" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -198070,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.2" : 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}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -214658,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.2" : 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"])
@@ -231770,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",
@@ -231806,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;
@@ -231859,15 +232618,27 @@ function registerGatewayTools(server) {
                 : {}),
         };
     };
+    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;
     };
@@ -231963,7 +232734,7 @@ 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,
@@ -231978,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;
@@ -232176,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()
@@ -232203,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()
@@ -232268,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,