@cloudbase/cloudbase-mcp 2.27.0 → 2.28.1

package/dist/index.js

@@ -32,8 +32,17 @@ import * as __WEBPACK_EXTERNAL_MODULE_node_fs_75ed2103__ from "node:fs";
 
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.DEFAULT_CREATE_ENV_RESOURCES = exports.CREATE_ENV_RESOURCE_VALUES = void 0;
+exports.GATEWAY_ENV_QPS_DEFAULT_RESOURCE_ID = exports.ENV_METRIC_PERIOD_VALUES = exports.ENV_METRIC_NAME_VALUES = exports.ENV_USAGE_MODULE_VALUES = exports.DEFAULT_CREATE_ENV_RESOURCES = exports.CREATE_ENV_RESOURCE_VALUES = void 0;
 exports.resolveCreateEnvResources = resolveCreateEnvResources;
+exports.resolveEnvUsageModules = resolveEnvUsageModules;
+exports.extractAccountCircleDate = extractAccountCircleDate;
+exports.resolveEnvUsageDateRange = resolveEnvUsageDateRange;
+exports.formatEnvMetricTime = formatEnvMetricTime;
+exports.resolveEnvMetricName = resolveEnvMetricName;
+exports.resolveEnvMetricPeriod = resolveEnvMetricPeriod;
+exports.resolveEnvMetricTimeRange = resolveEnvMetricTimeRange;
+exports.resolveEnvMetricResourceId = resolveEnvMetricResourceId;
+exports.summarizeEnvMetricCurve = summarizeEnvMetricCurve;
 exports.simplifyEnvList = simplifyEnvList;
 exports.isUsableNoSqlDatabaseEntry = isUsableNoSqlDatabaseEntry;
 exports.registerEnvTools = registerEnvTools;
@@ -65,6 +74,245 @@ function resolveCreateEnvResources(resources) {
     }
     return [...exports.DEFAULT_CREATE_ENV_RESOURCES];
 }
+/**
+ * Resource-usage modules aligned with tcb CLI `USAGE_MODULES`
+ * (`tcb env usage` / `tcb env info --type`).
+ */
+exports.ENV_USAGE_MODULE_VALUES = [
+    "FLEXDB",
+    "TDSQL",
+    "SCF",
+    "EKS",
+    "COS",
+    "AI",
+    "HOSTING",
+    "Auth",
+    "APIInvocation",
+    "HTTPInvocation",
+    "VM",
+    "Workflow",
+    "Other",
+];
+const ENV_USAGE_MODULE_SET = new Set(exports.ENV_USAGE_MODULE_VALUES);
+const ENV_USAGE_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function resolveEnvUsageModules(type) {
+    if (!Array.isArray(type) || type.length === 0) {
+        return [...exports.ENV_USAGE_MODULE_VALUES];
+    }
+    const normalized = type
+        .map((item) => (typeof item === "string" ? item.trim() : ""))
+        .filter(Boolean);
+    const invalid = normalized.filter((item) => !ENV_USAGE_MODULE_SET.has(item));
+    if (invalid.length > 0) {
+        throw new Error(`无效的用量模块 type: ${invalid.join(", ")}。可选值：${exports.ENV_USAGE_MODULE_VALUES.join(", ")}`);
+    }
+    return normalized;
+}
+function extractAccountCircleDate(rawTime) {
+    if (typeof rawTime !== "string" || rawTime.trim().length === 0) {
+        return undefined;
+    }
+    const datePart = rawTime.trim().split(/\s+/)[0];
+    return ENV_USAGE_DATE_RE.test(datePart) ? datePart : undefined;
+}
+function normalizeUsageDateInput(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function resolveEnvUsageDateRange(options) {
+    const startFromParams = normalizeUsageDateInput(options.startDate);
+    const endFromParams = normalizeUsageDateInput(options.endDate);
+    if (startFromParams || endFromParams) {
+        if (!startFromParams || !endFromParams) {
+            throw new Error("查询资源用量时 startDate 与 endDate 必须同时提供，格式为 YYYY-MM-DD。");
+        }
+        if (!ENV_USAGE_DATE_RE.test(startFromParams) || !ENV_USAGE_DATE_RE.test(endFromParams)) {
+            throw new Error("startDate / endDate 格式必须为 YYYY-MM-DD。");
+        }
+        if (startFromParams > endFromParams) {
+            throw new Error("startDate 不能晚于 endDate。");
+        }
+        return {
+            startDate: startFromParams,
+            endDate: endFromParams,
+            dateSource: "params",
+        };
+    }
+    const startDate = extractAccountCircleDate(options.accountCircle?.StartTime);
+    const endDate = extractAccountCircleDate(options.accountCircle?.EndTime);
+    if (!startDate || !endDate) {
+        throw new Error("无法从计费周期推导用量日期范围。请显式传入 startDate/endDate（YYYY-MM-DD），或确认环境计费周期可用。");
+    }
+    return { startDate, endDate, dateSource: "accountCircle" };
+}
+/**
+ * Monitor metric names for queryEnv(action=metrics).
+ * Subset of TCB DescribeCurveData MetricName from the CloudBase monitor catalog
+ * (gateway/env QPS, functions, NoSQL, MySQL, CloudRun).
+ */
+exports.ENV_METRIC_NAME_VALUES = [
+    "GatewayTraceEnvQPS",
+    "EnvQPSAll",
+    "FunctionInvocation",
+    "FunctionError",
+    "FunctionTimeout",
+    "FunctionThrottle",
+    "FunctionDuration",
+    "FunctionConcurrentExecutions",
+    "DbRead",
+    "DbWrite",
+    "DbSizepkg",
+    "MysqlCpuUsageRate",
+    "MysqlMemoryUse",
+    "MysqlStorageUsage",
+    "MysqlQps",
+    "MysqlSlowQueries",
+    "MysqlDbConnections",
+    "TkeCpuUsedService",
+    "TkeMemUsedService",
+    "TkeQPSService",
+    "TkeHttpErrorService",
+    "TkeInvokeNumService",
+];
+exports.ENV_METRIC_PERIOD_VALUES = [300, 3600, 86400];
+/** Console default ResourceID for environment-level gateway QPS. */
+exports.GATEWAY_ENV_QPS_DEFAULT_RESOURCE_ID = "all|:|all|:|all|:|all";
+const ENV_METRIC_NAME_SET = new Set(exports.ENV_METRIC_NAME_VALUES);
+const ENV_METRIC_PERIOD_SET = new Set(exports.ENV_METRIC_PERIOD_VALUES);
+const ENV_METRICS_REQUIRING_RESOURCE_ID = new Set([
+    "TkeCpuUsedService",
+    "TkeMemUsedService",
+    "TkeQPSService",
+    "TkeHttpErrorService",
+    "TkeInvokeNumService",
+]);
+const ENV_METRIC_TIME_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+const ENV_METRIC_MIN_RANGE_MS = 5 * 60 * 1000;
+function padMetricTimeUnit(value) {
+    return value.toString().padStart(2, "0");
+}
+function formatEnvMetricTime(date) {
+    return `${date.getFullYear()}-${padMetricTimeUnit(date.getMonth() + 1)}-${padMetricTimeUnit(date.getDate())} ${padMetricTimeUnit(date.getHours())}:${padMetricTimeUnit(date.getMinutes())}:${padMetricTimeUnit(date.getSeconds())}`;
+}
+function resolveEnvMetricName(metricName) {
+    const normalized = typeof metricName === "string" && metricName.trim().length > 0
+        ? metricName.trim()
+        : undefined;
+    if (!normalized) {
+        throw new Error(`查询监控指标时 metricName 为必填参数。可选值：${exports.ENV_METRIC_NAME_VALUES.join(", ")}`);
+    }
+    if (!ENV_METRIC_NAME_SET.has(normalized)) {
+        throw new Error(`无效的 metricName: ${normalized}。可选值：${exports.ENV_METRIC_NAME_VALUES.join(", ")}`);
+    }
+    return normalized;
+}
+function resolveEnvMetricPeriod(period) {
+    if (period === undefined || period === null || period === "") {
+        return undefined;
+    }
+    const numericPeriod = typeof period === "number"
+        ? period
+        : typeof period === "string" && /^\d+$/.test(period.trim())
+            ? Number(period.trim())
+            : Number.NaN;
+    if (!ENV_METRIC_PERIOD_SET.has(numericPeriod)) {
+        throw new Error(`period 仅支持 300、3600、86400（秒）。当前值：${String(period)}`);
+    }
+    return numericPeriod;
+}
+function resolveEnvMetricTimeRange(options) {
+    const startFromParams = typeof options.startTime === "string" && options.startTime.trim().length > 0
+        ? options.startTime.trim()
+        : undefined;
+    const endFromParams = typeof options.endTime === "string" && options.endTime.trim().length > 0
+        ? options.endTime.trim()
+        : undefined;
+    if (startFromParams || endFromParams) {
+        if (!startFromParams || !endFromParams) {
+            throw new Error("查询监控指标时 startTime 与 endTime 必须同时提供，格式为 YYYY-MM-DD HH:mm:ss。");
+        }
+        if (!ENV_METRIC_TIME_RE.test(startFromParams) || !ENV_METRIC_TIME_RE.test(endFromParams)) {
+            throw new Error("startTime / endTime 格式必须为 YYYY-MM-DD HH:mm:ss。");
+        }
+        const startMs = Date.parse(startFromParams.replace(" ", "T"));
+        const endMs = Date.parse(endFromParams.replace(" ", "T"));
+        if (Number.isNaN(startMs) || Number.isNaN(endMs)) {
+            throw new Error("startTime / endTime 无法解析为有效时间。");
+        }
+        if (endMs - startMs < ENV_METRIC_MIN_RANGE_MS) {
+            throw new Error("结束时间需要晚于开始时间至少五分钟（监控最小粒度为 5 分钟）。");
+        }
+        return {
+            startTime: startFromParams,
+            endTime: endFromParams,
+            timeSource: "params",
+        };
+    }
+    const now = options.now ?? new Date();
+    const start = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    return {
+        startTime: formatEnvMetricTime(start),
+        endTime: formatEnvMetricTime(now),
+        timeSource: "defaultLast24h",
+    };
+}
+function resolveEnvMetricResourceId(metricName, resourceID) {
+    const normalized = typeof resourceID === "string" && resourceID.trim().length > 0
+        ? resourceID.trim()
+        : undefined;
+    if (normalized) {
+        return normalized;
+    }
+    if (metricName === "GatewayTraceEnvQPS") {
+        return exports.GATEWAY_ENV_QPS_DEFAULT_RESOURCE_ID;
+    }
+    if (ENV_METRICS_REQUIRING_RESOURCE_ID.has(metricName)) {
+        throw new Error(`查询 ${metricName} 时 resourceID 为必填（云托管服务名）。请先 queryCloudRun(action="list") 获取服务名后再查询。`);
+    }
+    return undefined;
+}
+function summarizeEnvMetricCurve(curve) {
+    const newValues = Array.isArray(curve.NewValues) ? curve.NewValues : [];
+    const values = Array.isArray(curve.Values) ? curve.Values : [];
+    const times = Array.isArray(curve.Time) ? curve.Time : [];
+    const series = (newValues.length > 0 ? newValues : values).filter((item) => typeof item === "number" && Number.isFinite(item));
+    if (series.length === 0) {
+        return {
+            sampleCount: 0,
+            max: null,
+            min: null,
+            avg: null,
+            latest: null,
+            peakTimestamp: null,
+            allZero: true,
+        };
+    }
+    let max = series[0];
+    let min = series[0];
+    let sum = 0;
+    let peakIndex = 0;
+    for (let i = 0; i < series.length; i++) {
+        const value = series[i];
+        sum += value;
+        if (value > max) {
+            max = value;
+            peakIndex = i;
+        }
+        if (value < min) {
+            min = value;
+        }
+    }
+    return {
+        sampleCount: series.length,
+        max,
+        min,
+        avg: sum / series.length,
+        latest: series[series.length - 1],
+        peakTimestamp: typeof times[peakIndex] === "number" ? times[peakIndex] : null,
+        allZero: series.every((value) => value === 0),
+    };
+}
 /**
  * Simplify environment list data by keeping only essential fields for AI assistant
  * This reduces token consumption when returning environment lists via MCP tools
@@ -918,6 +1166,19 @@ function buildEnvQueryErrorMessage(error, action) {
     if (hasNetworkError) {
         suggestions.push("网络错误：请检查网络连接，稍后重试。");
     }
+    if (action === "usage" && suggestions.length === 0) {
+        suggestions.push("查询环境资源用量失败，建议：");
+        suggestions.push("1. 先调用 auth(action=\"status\") 确认登录状态；未登录则 auth(action=\"start_auth\")");
+        suggestions.push("2. 使用 queryEnv(action=\"list\") 确认 envId 正确且可访问");
+        suggestions.push(`3. 再调用 queryEnv(action=\"usage\", envId=\"<EnvId>\")；可用 type 过滤模块（${exports.ENV_USAGE_MODULE_VALUES.join(", ")}）`);
+    }
+    if (action === "metrics" && suggestions.length === 0) {
+        suggestions.push("查询环境监控指标失败，建议：");
+        suggestions.push("1. 先调用 auth(action=\"status\") 确认登录状态；未登录则 auth(action=\"start_auth\")");
+        suggestions.push("2. 使用 queryEnv(action=\"list\") 确认 envId 正确且可访问");
+        suggestions.push(`3. 再调用 queryEnv(action=\"metrics\", envId=\"<EnvId>\", metricName=\"GatewayTraceEnvQPS\")；metricName 可选值：${exports.ENV_METRIC_NAME_VALUES.join(", ")}`);
+        suggestions.push("4. startTime/endTime 格式为 YYYY-MM-DD HH:mm:ss，须成对传入；period 仅 300/3600/86400");
+    }
     // If no specific pattern matched, provide general guidance
     if (suggestions.length === 0) {
         suggestions.push("查询环境信息时出错，建议：");
@@ -1828,8 +2089,8 @@ function registerEnvTools(server) {
             }
         });
     } // end: wxide guard for auth tool
-    // queryEnv - 环境查询（合并 listEnvs + getEnvInfo + getEnvAuthDomains）
-    const queryEnvHandler = async ({ action, alias, aliasExact, envId, limit, offset, fields, }) => {
+    // queryEnv - 环境查询（合并 listEnvs + getEnvInfo + getEnvAuthDomains + usage + metrics）
+    const queryEnvHandler = async ({ action, alias, aliasExact, envId, limit, offset, fields, type, startDate, endDate, needUsageDetails, metricName, startTime, endTime, period, resourceID, subresourceID, }) => {
         try {
             let result;
             switch (action) {
@@ -1991,6 +2252,94 @@ function registerEnvTools(server) {
                         };
                     }
                     break;
+                case "usage": {
+                    // Explicit EnvId is required (DescribeEnvPostpayPackage / credits APIs reject missing EnvId).
+                    const usageEnvId = normalizeOptionalToolString(envId);
+                    if (!usageEnvId) {
+                        throw new Error('查询资源用量时 envId 为必填参数。请先调用 queryEnv(action="list") 获取 EnvId，再调用 queryEnv(action="usage", envId="<EnvId>")。');
+                    }
+                    const modules = resolveEnvUsageModules(type);
+                    const includeDetails = typeof needUsageDetails === "boolean" ? needUsageDetails : true;
+                    const cloudbaseUsage = await getManagerForEnvQuery(usageEnvId);
+                    const accountCircle = await cloudbaseUsage.env.describeEnvAccountCircle({
+                        EnvId: usageEnvId,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, accountCircle);
+                    const dateRange = resolveEnvUsageDateRange({
+                        startDate,
+                        endDate,
+                        accountCircle,
+                    });
+                    const usageDetail = await cloudbaseUsage.env.describeCreditsUsageDetail({
+                        EnvId: usageEnvId,
+                        Modules: modules,
+                        StartDate: dateRange.startDate,
+                        EndDate: dateRange.endDate,
+                        NeedUsageDetails: includeDetails,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, usageDetail);
+                    result = {
+                        EnvId: usageEnvId,
+                        Modules: modules,
+                        StartDate: dateRange.startDate,
+                        EndDate: dateRange.endDate,
+                        DateSource: dateRange.dateSource,
+                        NeedUsageDetails: includeDetails,
+                        AccountCircle: {
+                            StartTime: accountCircle?.StartTime,
+                            EndTime: accountCircle?.EndTime,
+                            HistoryTime: accountCircle?.HistoryTime ?? [],
+                            RequestId: accountCircle?.RequestId,
+                        },
+                        Usages: usageDetail?.Usages ?? [],
+                        RequestId: usageDetail?.RequestId,
+                    };
+                    break;
+                }
+                case "metrics": {
+                    const metricsEnvId = normalizeOptionalToolString(envId);
+                    if (!metricsEnvId) {
+                        throw new Error('查询监控指标时 envId 为必填参数。请先调用 queryEnv(action="list") 获取 EnvId，再调用 queryEnv(action="metrics", envId="<EnvId>", metricName="GatewayTraceEnvQPS")。');
+                    }
+                    const resolvedMetricName = resolveEnvMetricName(metricName);
+                    const timeRange = resolveEnvMetricTimeRange({ startTime, endTime });
+                    const resolvedPeriod = resolveEnvMetricPeriod(period);
+                    const resolvedResourceId = resolveEnvMetricResourceId(resolvedMetricName, resourceID);
+                    const resolvedSubresourceId = normalizeOptionalToolString(subresourceID);
+                    const cloudbaseMetrics = await getManagerForEnvQuery(metricsEnvId);
+                    if (typeof cloudbaseMetrics?.monitor?.describeCurveData !== "function") {
+                        throw new Error("当前 CloudBase Manager 不支持 monitor.describeCurveData。请升级 @cloudbase/manager-node。");
+                    }
+                    const curveParams = {
+                        MetricName: resolvedMetricName,
+                        StartTime: timeRange.startTime,
+                        EndTime: timeRange.endTime,
+                    };
+                    if (resolvedPeriod !== undefined) {
+                        curveParams.Period = resolvedPeriod;
+                    }
+                    if (resolvedResourceId) {
+                        curveParams.ResourceID = resolvedResourceId;
+                    }
+                    if (resolvedSubresourceId) {
+                        curveParams.SubresourceID = resolvedSubresourceId;
+                    }
+                    const curve = await cloudbaseMetrics.monitor.describeCurveData(curveParams);
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, curve);
+                    result = {
+                        EnvId: metricsEnvId,
+                        MetricName: resolvedMetricName,
+                        StartTime: timeRange.startTime,
+                        EndTime: timeRange.endTime,
+                        TimeSource: timeRange.timeSource,
+                        Period: resolvedPeriod ?? curve?.Period,
+                        ResourceID: resolvedResourceId,
+                        SubresourceID: resolvedSubresourceId,
+                        Curve: curve,
+                        Summary: summarizeEnvMetricCurve(curve ?? {}),
+                    };
+                    break;
+                }
                 default:
                     throw new Error(`不支持的查询类型: ${action}`);
             }
@@ -2023,20 +2372,63 @@ function registerEnvTools(server) {
     // Register primary tool name (queryEnv)
     const queryEnvToolSchema = {
         title: "CloudBase 环境查询",
-        description: "查询 CloudBase 环境相关信息，支持查询环境列表、指定环境详情和安全域名。（曾用名：envQuery、listEnvs、getEnvInfo、getEnvAuthDomains）当 action=list 时，会按 DescribeEnvs 语义做列表/筛选，标准返回字段为 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，并支持通过 fields 白名单裁剪这些字段；aliasExact=true 时会按别名精确筛选，避免把前缀相近的环境误当作候选；即使传入 envId，action=list 也只返回摘要，不会返回完整资源明细或 expiry。如需查询某个已知 EnvId 对应环境的详细信息（包括资源字段和计费信息），必须使用 action=info 并传入目标环境的 envId 参数。action=info 会在可用时补充 BillingInfo（如 ExpireTime、PayMode、IsAutoRenew 等计费字段）。\n\n🔍 action=info 还会派生三个用于后端选型的字段：\n- `EnvInfo.RuntimeMode`：'postgresql' 或 'nosql'，表示新业务建议默认使用的后端（PG 已开通时为 postgresql，否则为 nosql）。\n- `EnvInfo.RuntimeBackends`：`{postgresql, nosql, mysql}` 三个布尔值，描述当前环境实际并存的后端。\n- `EnvInfo.RuntimeModeHints`：每个后端对应的 API/工具/skill 提示。\n\n🌐 action=info 还会在不改写 `StaticStorages[].StaticDomain`（云 API 名义域名）的前提下，投影网关路由 Enable 状态：`StaticStorages[].staticDomainRouteEnabled` 与 `EnvInfo.staticDomainRouteEnabled`（与 queryHosting websiteConfig 同源）。`false` 表示默认静态域名根路由已禁用（访问会返回 GATEWAY_ROUTE_DISABLED），勿把名义域名当成可达 URL。\n\nAI 在写业务/权限/存储代码前必须先看这三项：PG 模式下新业务推荐 `app.rdb()` + RLS（`managePgDatabase action=execute` 跑 `CREATE POLICY`）+ pgstore；已存在的 NoSQL 集合 / 旧 storage / `managePermissions(resourceType=\"noSqlDatabase\")` 在 PG 环境下仍然有效。真正不适用的是 MySQL：当 `RuntimeBackends.mysql === false` 时，`manageMysqlDatabase` / `queryMysqlDatabase` / `relational-database-mcp-cloudbase` skill 都不该使用。",
+        description: "查询 CloudBase 环境相关信息，支持查询环境列表、指定环境详情、安全域名、资源用量与监控指标。（曾用名：envQuery、listEnvs、getEnvInfo、getEnvAuthDomains）当 action=list 时，会按 DescribeEnvs 语义做列表/筛选，标准返回字段为 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，并支持通过 fields 白名单裁剪这些字段；aliasExact=true 时会按别名精确筛选，避免把前缀相近的环境误当作候选；即使传入 envId，action=list 也只返回摘要，不会返回完整资源明细或 expiry。如需查询某个已知 EnvId 对应环境的详细信息（包括资源字段和计费信息），必须使用 action=info 并传入目标环境的 envId 参数。action=info 会在可用时补充 BillingInfo（如 ExpireTime、PayMode、IsAutoRenew 等计费字段）。\n\n📊 action=usage 对齐 tcb env usage/info：透传 Manager SDK describeEnvAccountCircle + describeCreditsUsageDetail，返回计费周期与各模块资源点用量（FLEXDB/SCF/COS 等）。envId 必填；type 可选过滤模块；未传 startDate/endDate 时自动使用当前计费周期。\n\n📈 action=metrics 对齐 TCB DescribeCurveData（manager.monitor.describeCurveData，不是云监控 GetMonitorData）：查询环境/网关 QPS、云函数调用与错误、数据库 CPU/内存/磁盘、云托管 CPU/QPS 等时序。envId 与 metricName 必填；startTime/endTime 格式 YYYY-MM-DD HH:mm:ss，须成对传入，不传则默认最近 24 小时；period 仅 300/3600/86400。GatewayTraceEnvQPS 未传 resourceID 时自动填环境级 all|:|all|:|all|:|all；云托管 Tke* 指标必须传服务名 resourceID。禁止用 callCloudApi 猜测监控 Action。\n\n🔍 action=info 还会派生三个用于后端选型的字段：\n- `EnvInfo.RuntimeMode`：'postgresql' 或 'nosql'，表示新业务建议默认使用的后端（PG 已开通时为 postgresql，否则为 nosql）。\n- `EnvInfo.RuntimeBackends`：`{postgresql, nosql, mysql}` 三个布尔值，描述当前环境实际并存的后端。\n- `EnvInfo.RuntimeModeHints`：每个后端对应的 API/工具/skill 提示。\n\n🌐 action=info 还会在不改写 `StaticStorages[].StaticDomain`（云 API 名义域名）的前提下，投影网关路由 Enable 状态：`StaticStorages[].staticDomainRouteEnabled` 与 `EnvInfo.staticDomainRouteEnabled`（与 queryHosting websiteConfig 同源）。`false` 表示默认静态域名根路由已禁用（访问会返回 GATEWAY_ROUTE_DISABLED），勿把名义域名当成可达 URL。\n\nAI 在写业务/权限/存储代码前必须先看这三项：PG 模式下新业务推荐 `app.rdb()` + RLS（`managePgDatabase action=execute` 跑 `CREATE POLICY`）+ pgstore；已存在的 NoSQL 集合 / 旧 storage / `managePermissions(resourceType=\"noSqlDatabase\")` 在 PG 环境下仍然有效。真正不适用的是 MySQL：当 `RuntimeBackends.mysql === false` 时，`manageMysqlDatabase` / `queryMysqlDatabase` / `relational-database-mcp-cloudbase` skill 都不该使用。",
         inputSchema: {
             action: zod_1.z
-                .enum(["list", "info", "domains"])
-                .describe("查询类型：list=环境列表/摘要筛选（按 DescribeEnvs 语义筛选，支持通过 envId 筛选，返回 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，不支持 expiry），info=指定环境的详细信息（必须传入 envId，返回资源字段和计费信息），domains=安全域名列表"),
+                .enum(["list", "info", "domains", "usage", "metrics"])
+                .describe("查询类型：list=环境列表/摘要筛选（按 DescribeEnvs 语义筛选，支持通过 envId 筛选，返回 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，不支持 expiry），info=指定环境的详细信息（必须传入 envId，返回资源字段和计费信息），domains=安全域名列表，usage=环境资源用量（必须传入 envId，对齐 tcb env usage/info），metrics=环境监控时序（必须传入 envId 与 metricName，对齐 TCB DescribeCurveData）"),
             alias: zod_1.z.string().optional().describe("按环境别名筛选。action=list 时可选"),
             aliasExact: zod_1.z.boolean().optional().describe("按环境别名精确筛选。action=list 时可选；与 alias 配合使用"),
-            envId: zod_1.z.string().optional().describe("按环境 ID 筛选。action=list 时可选（仅按 DescribeEnvs 语义做筛选，仍返回摘要）；action=info 时必填（返回该环境的详细信息，包含资源字段和计费信息）。如果任务已经给出了明确的 EnvId 并要求查询详情，请直接使用 action=info + envId，而不是 action=list"),
+            envId: zod_1.z
+                .string()
+                .optional()
+                .describe("环境 ID。action=list 时可选（仅按 DescribeEnvs 语义做筛选，仍返回摘要）；action=info / action=usage / action=metrics 时必填。"),
             limit: zod_1.z.number().int().positive().optional().describe("返回数量上限。action=list 时可选"),
             offset: zod_1.z.number().int().min(0).optional().describe("分页偏移。action=list 时可选"),
             fields: zod_1.z
                 .array(zod_1.z.enum(DEFAULT_ENV_FIELDS))
                 .optional()
                 .describe("返回字段白名单。仅支持 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault。action=list 时可选"),
+            type: zod_1.z
+                .array(zod_1.z.enum(exports.ENV_USAGE_MODULE_VALUES))
+                .optional()
+                .describe("用量模块过滤。仅 action=usage 时有效；不传则查询全部模块。可选值对齐 tcb CLI：FLEXDB、TDSQL、SCF、EKS、COS、AI、HOSTING、Auth、APIInvocation、HTTPInvocation、VM、Workflow、Other。"),
+            startDate: zod_1.z
+                .string()
+                .optional()
+                .describe("用量开始日期（YYYY-MM-DD）。仅 action=usage 时有效；与 endDate 成对传入。不传则使用当前计费周期。"),
+            endDate: zod_1.z
+                .string()
+                .optional()
+                .describe("用量结束日期（YYYY-MM-DD）。仅 action=usage 时有效；与 startDate 成对传入。不传则使用当前计费周期。"),
+            needUsageDetails: zod_1.z
+                .boolean()
+                .optional()
+                .describe("是否返回每日用量明细。仅 action=usage 时有效；默认 true。"),
+            metricName: zod_1.z
+                .enum(exports.ENV_METRIC_NAME_VALUES)
+                .optional()
+                .describe("监控指标名。仅 action=metrics 时有效且必填。GatewayTraceEnvQPS/EnvQPSAll=环境与网关 QPS；FunctionInvocation/FunctionError/FunctionTimeout/FunctionThrottle=云函数调用、错误、超时、限流；DbRead/DbWrite/DbSizepkg=文档库读写与容量；MysqlCpuUsageRate/MysqlMemoryUse/MysqlStorageUsage=SQL 库 CPU/内存/磁盘；TkeCpuUsedService/TkeQPSService/TkeHttpErrorService=云托管 CPU/QPS/错误。"),
+            startTime: zod_1.z
+                .string()
+                .optional()
+                .describe("监控开始时间（YYYY-MM-DD HH:mm:ss）。仅 action=metrics 时有效；与 endTime 成对传入。不传则默认最近 24 小时。结束时间须晚于开始时间至少五分钟。"),
+            endTime: zod_1.z
+                .string()
+                .optional()
+                .describe("监控结束时间（YYYY-MM-DD HH:mm:ss）。仅 action=metrics 时有效；与 startTime 成对传入。不传则默认最近 24 小时。"),
+            period: zod_1.z
+                .union([zod_1.z.literal(300), zod_1.z.literal(3600), zod_1.z.literal(86400)])
+                .optional()
+                .describe("统计周期（秒）。仅 action=metrics 时有效；仅支持 300、3600、86400。不传则由后端按时间范围自动选择。时间范围 ≤1 天不可用 86400；>3 天不可用 300。"),
+            resourceID: zod_1.z
+                .string()
+                .optional()
+                .describe("资源 ID。仅 action=metrics 时有效。云函数传函数名，文档库传集合名，云托管必须传服务名；GatewayTraceEnvQPS 不传则使用环境级 all|:|all|:|all|:|all。"),
+            subresourceID: zod_1.z
+                .string()
+                .optional()
+                .describe("子资源 ID。仅 action=metrics 时有效；查询云托管某版本监控时传入版本名。"),
         },
         annotations: {
             readOnlyHint: true,
@@ -2552,8 +2944,11 @@ function registerEnvTools(server) {
 
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.CAM_AUTH_ERROR_PATTERN = void 0;
 exports.assertTcbCloudRunActionAllowed = assertTcbCloudRunActionAllowed;
 exports.removeEmptyStringParams = removeEmptyStringParams;
+exports.buildCamAuthGuidance = buildCamAuthGuidance;
+exports.isCamAuthError = isCamAuthError;
 exports.buildCapiErrorMessage = buildCapiErrorMessage;
 exports.registerCapiTools = registerCapiTools;
 const zod_1 = __webpack_require__(2971);
@@ -2573,27 +2968,30 @@ const ALLOWED_SERVICES = [
     "vpc",
 ];
 /**
- * tcb 旧版小租户云托管（CloudBase Run）API 族，统一禁用。
+ * Legacy tcb small-tenant CloudRun (CloudBase Run) API family — blocked.
  *
- * 云托管一律走 tcbr 新逻辑（CreateCloudRunEnv / CreateCloudRunServer）。tcb 的
- * CreateCloudBaseRunResource 是 2018 旧小租户开通接口：在无大租户记录的环境上调用
- * 会把服务创建到小租户，产生错误的服务与版本（2026-08-13 用户实测，ATO 调研
- * efec7cc5 结论）。同族 Describe/Delete 一并拦截，避免 AI 误以为与 tcbr 环境相关。
+ * CloudRun must use tcbr (CreateCloudRunEnv / CreateCloudRunServer). tcb
+ * CreateCloudBaseRunResource is the 2018 small-tenant open API and is no longer
+ * publicly listed; calling it on an env without a large-tenant record creates
+ * wrong small-tenant services/versions (user incident 2026-08-13; ATO research
+ * efec7cc5). Describe/Delete of the same family are blocked too. Matching is
+ * case-insensitive so Action casing variants cannot bypass the check.
  */
 const TCB_CLOUDRUN_FORBIDDEN_ACTIONS = [
     "CreateCloudBaseRunResource",
     "DescribeCloudBaseRunResource",
     "DeleteCloudBaseRunResource",
 ];
+const TCB_CLOUDRUN_FORBIDDEN_ACTIONS_LOWER = new Set(TCB_CLOUDRUN_FORBIDDEN_ACTIONS.map((name) => name.toLowerCase()));
 const TCB_CLOUDRUN_FORBIDDEN_HINT = `云托管（CloudBase Run）统一走 tcbr 新逻辑（CreateCloudRunEnv / CreateCloudRunServer），` +
     `不要使用 tcb 旧小租户接口（${TCB_CLOUDRUN_FORBIDDEN_ACTIONS.join(" / ")}）。` +
     `新环境请先初始化云托管：callCloudApi(service="tcbr", version="2022-02-17", action="CreateCloudRunEnv", params={EnvId:"..."})，` +
     `再通过 manageCloudRun(action="deploy") 创建服务；查询单个环境基础信息/是否已开通云托管用 callCloudApi(service="tcbr", version="2022-02-17", action="DescribeEnvBaseInfo", params={EnvId:"..."})，查询环境列表/资源信息用 DescribeCloudRunEnvs。`;
 /**
- * 拒绝 tcb 旧版小租户云托管 API。命中黑名单时抛出带 tcbr 引导的错误。
+ * Reject legacy tcb small-tenant CloudRun APIs; throw with tcbr guidance when blocked.
  */
 function assertTcbCloudRunActionAllowed(service, action) {
-    if (service === "tcb" && TCB_CLOUDRUN_FORBIDDEN_ACTIONS.includes(action)) {
+    if (service === "tcb" && TCB_CLOUDRUN_FORBIDDEN_ACTIONS_LOWER.has(action.toLowerCase())) {
         throw new Error(`[${service}/${action}] 已禁用：${TCB_CLOUDRUN_FORBIDDEN_HINT}`);
     }
 }
@@ -2677,6 +3075,21 @@ function buildCapiDocGuidance(service) {
     }
     return `请优先核对对应官方云 API 文档；若你的场景其实是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode="openapi")，不要继续猜测管控面 Action。`;
 }
+/** Match CAM / authorization failures from Tencent Cloud control-plane APIs. */
+exports.CAM_AUTH_ERROR_PATTERN = /UnauthorizedOperation|AuthFailure|not authorized|cam.*denied|Forbidden/i;
+/**
+ * Guidance when control-plane calls fail due to CAM / API Key scope limits.
+ * Shared by callCloudApi and manageCloudRun error builders.
+ */
+function buildCamAuthGuidance() {
+    return ("这通常是 CAM 权限不足（常见于 API Key 登录仅授权数据面：DB/函数/存储）。请任选其一：" +
+        "1) 改用 device code 登录管控面：auth(action=\"start_auth\", authMode=\"device\")；" +
+        "2) 或使用腾讯云 SecretId/SecretKey（确认子账号已授 CAM 策略，如 QcloudTCBFullAccess、QcloudVPCReadOnlyAccess）；" +
+        "3) 确认目标资源属于当前登录账号。");
+}
+function isCamAuthError(message) {
+    return exports.CAM_AUTH_ERROR_PATTERN.test(message);
+}
 function buildCapiErrorMessage(service, action, error) {
     const baseMessage = error instanceof Error ? error.message : String(error);
     const suggestions = [];
@@ -2684,6 +3097,10 @@ function buildCapiErrorMessage(service, action, error) {
     const hasInvalidActionError = /invalid or not found|does not exist|not recognized/i.test(baseMessage);
     const hasParameterError = /parameter\s+`?.+?`?\s+is not recognized|MissingParameter|missing parameter|missing required/i.test(baseMessage);
     const hasInvalidParameterValueError = /invalid parameter value/i.test(baseMessage);
+    const hasCamAuthError = isCamAuthError(baseMessage);
+    if (hasCamAuthError) {
+        suggestions.push(buildCamAuthGuidance());
+    }
     if (hasInvalidActionError) {
         suggestions.push(`Action \`${action}\` 可能不存在或不对外开放。请不要继续猜测 Action 名称，先确认 service=\`${service}\` 下该 Action 在当前 API 版本是否真实存在。`);
         if (service === "tcb") {
@@ -2801,9 +3218,13 @@ function registerCapiTools(server) {
             }
             if (service === 'tcb') {
                 const tcbCapiForbidList = [
-                    // 未明确对外的云API
+                    // Cloud APIs not clearly public
                     'DescribeStorageACL', 'ModifyStorageACL', 'DescribeSecurityRule',
-                    // 要下线的云API
+                    // Legacy small-tenant CloudRun open/query/delete (no longer public; also blocked by assertTcbCloudRunActionAllowed)
+                    "CreateCloudBaseRunResource",
+                    "DescribeCloudBaseRunResource",
+                    "DeleteCloudBaseRunResource",
+                    // Cloud APIs scheduled for retirement
                     "ListTables",
                     "DescribeCloudBaseGWAPI",
                     "DescribeCloudBaseGWService",
@@ -2939,7 +3360,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || ( true ? "2.27.0" : 0)}
+- MCP 版本：${process.env.npm_package_version || ( true ? "2.28.1" : 0)}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -3020,7 +3441,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.27.0" : 0;
+            const mcpVersion =  true ? "2.28.1" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -5384,6 +5805,181 @@ function logCloudBaseResult(logger, result) {
 }
 
 
+/***/ }),
+
+/***/ 3656:
+/***/ ((__unused_webpack_module, exports) => {
+
+
+/**
+ * Guidance + bounded wait when a cloud function is not Active.
+ * SCF rejects UpdateFunctionConfiguration / UpdateFunctionCode while Status=Updating.
+ */
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.functionUpdatingRuntime = exports.FUNCTION_UPDATING_WAIT = exports.FUNCTION_BUSY_STATUSES = exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS = exports.FUNCTION_UPDATING_ERROR_CODE = void 0;
+exports.getErrorMessage = getErrorMessage;
+exports.isFunctionBusyStatus = isFunctionBusyStatus;
+exports.isFunctionUpdatingError = isFunctionUpdatingError;
+exports.buildFunctionUpdatingMessage = buildFunctionUpdatingMessage;
+exports.buildFunctionUpdatingNextActions = buildFunctionUpdatingNextActions;
+exports.buildFunctionUpdatingPayload = buildFunctionUpdatingPayload;
+exports.waitUntilFunctionActive = waitUntilFunctionActive;
+exports.FUNCTION_UPDATING_ERROR_CODE = "FUNCTION_UPDATING";
+/** Agents must wait at least this long before retrying the same write. */
+exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS = 10;
+exports.FUNCTION_BUSY_STATUSES = [
+    "Updating",
+    "Creating",
+    "Publishing",
+    "Deleting",
+];
+exports.FUNCTION_UPDATING_WAIT = {
+    intervalMs: 2000,
+    maxAttempts: 5,
+    timeoutMs: 12_000,
+};
+/**
+ * Injectable sleep for unit tests. Production uses setTimeout.
+ * Tests must restore the original function in afterEach.
+ */
+exports.functionUpdatingRuntime = {
+    sleep: (ms) => new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    }),
+};
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function isFunctionBusyStatus(status) {
+    if (typeof status !== "string") {
+        return false;
+    }
+    return exports.FUNCTION_BUSY_STATUSES.includes(status);
+}
+const UPDATING_ERROR_PATTERNS = [
+    /当前函数处于\s*Updating/i,
+    /函数处于\s*Updating/i,
+    /currently\s+(?:in\s+)?updating/i,
+    /function\s+is\s+(?:currently\s+)?updating/i,
+    /Status\s*(?:is|=|:)?\s*Updating/i,
+    /scf\/UpdateFunction(?:Configuration|Code).{0,80}Updating/i,
+    /函数状态异常，检查超时/,
+];
+function isFunctionUpdatingError(error) {
+    const message = getErrorMessage(error);
+    return UPDATING_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+function buildFunctionUpdatingMessage(params) {
+    const namePart = params.functionName
+        ? `函数 \`${params.functionName}\``
+        : "目标函数";
+    const statusPart = params.status ? `（当前 Status=${params.status}）` : "";
+    const lines = [
+        `${namePart} 尚未就绪${statusPart}，无法执行 manageFunctions(action="${params.action}")。`,
+        `不要立即重试同一写操作（SCF 会在 Updating 期间连续拒绝 UpdateFunctionConfiguration / UpdateFunctionCode）。`,
+        `请等待 ${exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS} 秒后重试，或先调用 queryFunctions(action="getFunctionDetail") 确认 Status 为 Active。`,
+    ];
+    if (params.rawMessage) {
+        lines.push(`原始错误: ${params.rawMessage}`);
+    }
+    return lines.join("\n");
+}
+function buildFunctionUpdatingNextActions(params) {
+    const functionName = params.functionName;
+    return [
+        {
+            tool: "queryFunctions",
+            action: "getFunctionDetail",
+            reason: "查看函数 Status，等到 Active 后再写配置/代码",
+            suggested_args: {
+                action: "getFunctionDetail",
+                ...(functionName ? { functionName } : {}),
+            },
+        },
+        {
+            tool: "manageFunctions",
+            action: params.action,
+            reason: `等待 ${exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS} 秒且 Status=Active 后，用相同参数重试；禁止立刻连打`,
+            suggested_args: {
+                action: params.action,
+                ...(functionName ? { functionName } : {}),
+            },
+        },
+    ];
+}
+function buildFunctionUpdatingPayload(params) {
+    return {
+        success: false,
+        errorCode: exports.FUNCTION_UPDATING_ERROR_CODE,
+        retryAfterSeconds: exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS,
+        message: buildFunctionUpdatingMessage(params),
+        data: {
+            action: params.action,
+            ...(params.functionName ? { functionName: params.functionName } : {}),
+            ...(params.status ? { status: params.status } : {}),
+            retryAfterSeconds: exports.FUNCTION_UPDATING_RETRY_AFTER_SECONDS,
+            doNotRetryImmediately: true,
+            ...(typeof params.waitedAttempts === "number"
+                ? { waitedAttempts: params.waitedAttempts }
+                : {}),
+            ...(params.timedOut ? { waitTimedOut: true } : {}),
+            ...(params.rawMessage ? { rawError: params.rawMessage.slice(0, 500) } : {}),
+        },
+        nextActions: buildFunctionUpdatingNextActions(params),
+    };
+}
+/**
+ * Poll function Status until it leaves a busy state.
+ * Always bounded: maxAttempts AND timeoutMs; never spins without a sleep between polls.
+ */
+async function waitUntilFunctionActive(getStatus, options = {}) {
+    const intervalMs = options.intervalMs ?? exports.FUNCTION_UPDATING_WAIT.intervalMs;
+    const maxAttempts = options.maxAttempts ?? exports.FUNCTION_UPDATING_WAIT.maxAttempts;
+    const timeoutMs = options.timeoutMs ?? exports.FUNCTION_UPDATING_WAIT.timeoutMs;
+    const sleep = options.sleep ?? ((ms) => exports.functionUpdatingRuntime.sleep(ms));
+    const now = options.now ?? Date.now;
+    if (maxAttempts < 1) {
+        throw new Error("waitUntilFunctionActive maxAttempts must be >= 1");
+    }
+    if (intervalMs < 0 || timeoutMs < 0) {
+        throw new Error("waitUntilFunctionActive intervalMs/timeoutMs must be >= 0");
+    }
+    if (options.initialStatus !== undefined &&
+        !isFunctionBusyStatus(options.initialStatus)) {
+        return {
+            ready: true,
+            status: options.initialStatus,
+            attempts: 0,
+            timedOut: false,
+        };
+    }
+    const startedAt = now();
+    let attempts = 0;
+    let status = options.initialStatus;
+    while (attempts < maxAttempts) {
+        if (now() - startedAt >= timeoutMs) {
+            return { ready: false, status, attempts, timedOut: true };
+        }
+        attempts += 1;
+        status = await getStatus();
+        if (!isFunctionBusyStatus(status)) {
+            return { ready: true, status, attempts, timedOut: false };
+        }
+        if (attempts >= maxAttempts) {
+            break;
+        }
+        if (now() - startedAt + intervalMs >= timeoutMs) {
+            return { ready: false, status, attempts, timedOut: true };
+        }
+        await sleep(intervalMs);
+    }
+    return { ready: false, status, attempts, timedOut: false };
+}
+
+
 /***/ }),
 
 /***/ 3782:
@@ -5412,6 +6008,15 @@ const logger_js_1 = __webpack_require__(3039);
 const CATEGORY = "NoSQL database";
 const COLLECTION_READY_TIMEOUT_MS = 10000;
 const COLLECTION_READY_POLL_INTERVAL_MS = 500;
+/** Default page size for QueryRecords (unchanged; overrun tuning is a separate track). */
+const QUERY_RECORDS_DEFAULT_LIMIT = 100;
+/** Cloud API MgoLimit `lte` upper bound (aligned with ListTables / SDK limit docs). */
+const QUERY_RECORDS_MAX_LIMIT = 1000;
+const PROJECTION_EXAMPLE = '{"_id":1,"name":1,"createdAt":1}';
+const PROJECTION_EXCLUDE_EXAMPLE = '{"password":0}';
+const PROJECTION_GUIDANCE = `projection 必须是字段投影对象（或对应 JSON 字符串），值只能是 1/0/true/false。` +
+    `合法示例：${PROJECTION_EXAMPLE}（只返回这些字段），或 ${PROJECTION_EXCLUDE_EXAMPLE}（排除字段）。` +
+    `不要传字段名数组、逗号分隔字符串、查询条件，也不要在同一投影里混用包含(1/true)与排除(0/false)（_id 除外）。`;
 /** Convert object values to JSON strings for API calls */
 const toJSONString = (v) => typeof v === "object" && v !== null ? JSON.stringify(v) : v;
 function delay(ms) {
@@ -5482,6 +6087,95 @@ function normalizeSortInput(sort) {
     }
     return JSON.stringify(parsed.map((item) => normalizeSortItem(item)));
 }
+function isProjectionFlag(value) {
+    return value === 0 || value === 1 || value === true || value === false;
+}
+function normalizeProjectionInput(projection) {
+    if (projection === undefined || projection === null) {
+        return undefined;
+    }
+    let parsed = projection;
+    if (typeof parsed === "string") {
+        const trimmed = parsed.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`projection 必须是合法 JSON 对象字符串。${PROJECTION_GUIDANCE}`);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        throw new Error(`projection 不支持字段名数组。请改为对象，例如 ${PROJECTION_EXAMPLE}。${PROJECTION_GUIDANCE}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`projection 必须是对象。请改为例如 ${PROJECTION_EXAMPLE}。${PROJECTION_GUIDANCE}`);
+    }
+    const entries = Object.entries(parsed);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    let hasInclude = false;
+    let hasExclude = false;
+    const normalized = {};
+    for (const [key, value] of entries) {
+        if (typeof key !== "string" || key.trim() === "") {
+            throw new Error(`projection 字段名必须是非空字符串。${PROJECTION_GUIDANCE}`);
+        }
+        if (!isProjectionFlag(value)) {
+            throw new Error(`projection["${key}"] 的值非法（当前为 ${JSON.stringify(value)}），仅支持 1/0/true/false。` +
+                `合法示例：${PROJECTION_EXAMPLE}。${PROJECTION_GUIDANCE}`);
+        }
+        const flag = value === true || value === 1 ? 1 : 0;
+        normalized[key] = flag;
+        if (key === "_id") {
+            continue;
+        }
+        if (flag === 1) {
+            hasInclude = true;
+        }
+        else {
+            hasExclude = true;
+        }
+    }
+    if (hasInclude && hasExclude) {
+        throw new Error(`projection 不能同时混用包含(1/true)与排除(0/false)（_id 除外）。` +
+            `请只保留一种模式，例如 ${PROJECTION_EXAMPLE} 或 ${PROJECTION_EXCLUDE_EXAMPLE}。`);
+    }
+    return JSON.stringify(normalized);
+}
+function normalizeQueryLimit(limit) {
+    if (limit === undefined || limit === null) {
+        return QUERY_RECORDS_DEFAULT_LIMIT;
+    }
+    if (typeof limit !== "number" || !Number.isFinite(limit)) {
+        throw new Error(`limit 必须是数字，取值范围 1-${QUERY_RECORDS_MAX_LIMIT}（默认 ${QUERY_RECORDS_DEFAULT_LIMIT}）。` +
+            `超出上限时请用 offset 分页，例如 limit=${QUERY_RECORDS_MAX_LIMIT}, offset=0，再 offset+=limit。`);
+    }
+    if (!Number.isInteger(limit)) {
+        throw new Error(`limit 必须是整数，取值范围 1-${QUERY_RECORDS_MAX_LIMIT}。当前值：${limit}`);
+    }
+    if (limit < 1 || limit > QUERY_RECORDS_MAX_LIMIT) {
+        throw new Error(`limit 超出上限：当前 ${limit}，允许范围 1-${QUERY_RECORDS_MAX_LIMIT}（Cloud API MgoLimit lte）。` +
+            `请将 limit 调整为 ≤${QUERY_RECORDS_MAX_LIMIT}，并用 offset 分页拉取更多数据` +
+            `（例如 limit=${QUERY_RECORDS_MAX_LIMIT}, offset=0，下一页 offset=${QUERY_RECORDS_MAX_LIMIT}）。`);
+    }
+    return limit;
+}
+function enhanceQueryRecordsError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    if (/Query projection.*illegal|projection entered in the request is illegal/i.test(message)) {
+        throw new Error(`QueryRecords 投影非法：${message}。修正建议：${PROJECTION_GUIDANCE}`);
+    }
+    if (/MgoLimit.*lte|Field validation for 'MgoLimit' failed on the 'lte'/i.test(message)) {
+        throw new Error(`QueryRecords MgoLimit 超限：${message}。` +
+            `limit 最大为 ${QUERY_RECORDS_MAX_LIMIT}，请缩小 limit 并用 offset 分页` +
+            `（例如 limit=${QUERY_RECORDS_MAX_LIMIT}, offset=0）。`);
+    }
+    throw error instanceof Error ? error : new Error(message);
+}
 function withCollectionName(collectionName, payload) {
     return {
         ...payload,
@@ -6016,7 +6710,9 @@ deleteCollection: 删除集合`),
     // readNoSqlDatabaseContent
     server.registerTool?.("readNoSqlDatabaseContent", {
         title: "查询并获取 CloudBase NoSQL 数据库数据记录",
-        description: "查询 CloudBase NoSQL 数据库中的数据记录。支持按条件筛选、分页、排序，适用于管理端数据查询与运维。",
+        description: "查询 CloudBase NoSQL 数据库中的数据记录。支持按条件筛选、分页、排序，适用于管理端数据查询与运维。" +
+            `limit 默认 ${QUERY_RECORDS_DEFAULT_LIMIT}、最大 ${QUERY_RECORDS_MAX_LIMIT}；超出请用 offset 分页。` +
+            `projection 仅支持 { field: 1|0 } 对象（示例 ${PROJECTION_EXAMPLE}），不要传字段数组。`,
         inputSchema: {
             collectionName: zod_1.z.string().describe("集合名称"),
             instanceId: zod_1.z
@@ -6030,7 +6726,9 @@ deleteCollection: 删除集合`),
             projection: zod_1.z
                 .union([zod_1.z.object({}).passthrough(), zod_1.z.string()])
                 .optional()
-                .describe("返回字段投影(对象或字符串,推荐对象)"),
+                .describe(`返回字段投影，仅支持对象或对应 JSON 字符串，值只能是 1/0/true/false。` +
+                `合法示例：${PROJECTION_EXAMPLE}（包含）或 ${PROJECTION_EXCLUDE_EXAMPLE}（排除）。` +
+                `不要传 ["name","age"] 这类字段数组，也不要混用包含与排除（_id 除外）。`),
             sort: zod_1.z
                 .union([
                 zod_1.z.array(zod_1.z
@@ -6043,7 +6741,11 @@ deleteCollection: 删除集合`),
             ])
                 .optional()
                 .describe('排序条件，仅支持数组 [{"key":"createdAt","direction":-1}] 或对应 JSON 字符串。'),
-            limit: zod_1.z.number().optional().describe("返回数量限制"),
+            limit: zod_1.z
+                .number()
+                .optional()
+                .describe(`返回数量限制，整数，范围 1-${QUERY_RECORDS_MAX_LIMIT}，默认 ${QUERY_RECORDS_DEFAULT_LIMIT}。` +
+                `超过 ${QUERY_RECORDS_MAX_LIMIT} 会被 Cloud API MgoLimit lte 校验拒绝；请用 offset 分页。`),
             offset: zod_1.z.number().optional().describe("跳过的记录数"),
         },
         annotations: {
@@ -6059,46 +6761,53 @@ deleteCollection: 删除集合`),
             durationMs: Date.now() - managerStartedAt,
         });
         const normalizedSort = normalizeSortInput(sort);
-        const result = await callNoSqlContentApi({
-            toolName: "readNoSqlDatabaseContent",
-            action: "QueryRecords",
-            collectionName,
-            cloudbase,
-            cloudBaseOptions,
-            instanceIdOverride: instanceId,
-            param: {
-                MgoQuery: toJSONString(query),
-                MgoProjection: toJSONString(projection),
-                MgoSort: normalizedSort,
-                MgoLimit: limit ?? 100,
-                MgoOffset: offset,
-            },
-        });
-        (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-        const parseStartedAt = Date.now();
-        const documents = normalizeNoSqlDocuments(result.Data);
-        logNoSqlLatency("readNoSqlDatabaseContent", "parseResult", {
-            collectionName,
-            durationMs: Date.now() - parseStartedAt,
-            documentCount: documents.length,
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(withCollectionName(collectionName, {
-                        success: true,
-                        requestId: result.RequestId,
-                        data: documents,
-                        total: typeof result.Pager?.Total === "number"
-                            ? result.Pager.Total
-                            : documents.length,
-                        pager: result.Pager,
-                        message: "文档查询成功",
-                    }), null, 2),
+        const normalizedProjection = normalizeProjectionInput(projection);
+        const normalizedLimit = normalizeQueryLimit(limit);
+        try {
+            const result = await callNoSqlContentApi({
+                toolName: "readNoSqlDatabaseContent",
+                action: "QueryRecords",
+                collectionName,
+                cloudbase,
+                cloudBaseOptions,
+                instanceIdOverride: instanceId,
+                param: {
+                    MgoQuery: toJSONString(query),
+                    MgoProjection: normalizedProjection,
+                    MgoSort: normalizedSort,
+                    MgoLimit: normalizedLimit,
+                    MgoOffset: offset,
                 },
-            ],
-        };
+            });
+            (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+            const parseStartedAt = Date.now();
+            const documents = normalizeNoSqlDocuments(result.Data);
+            logNoSqlLatency("readNoSqlDatabaseContent", "parseResult", {
+                collectionName,
+                durationMs: Date.now() - parseStartedAt,
+                documentCount: documents.length,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(withCollectionName(collectionName, {
+                            success: true,
+                            requestId: result.RequestId,
+                            data: documents,
+                            total: typeof result.Pager?.Total === "number"
+                                ? result.Pager.Total
+                                : documents.length,
+                            pager: result.Pager,
+                            message: "文档查询成功",
+                        }), null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            enhanceQueryRecordsError(error);
+        }
     });
     // writeNoSqlDatabaseContent
     server.registerTool?.("writeNoSqlDatabaseContent", {
@@ -8222,7 +8931,10 @@ 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") ??
+        return (candidates.find((item) => item.Enable !== false &&
+            // Platform may return Success/success; normalize before matching.
+            typeof item.Status === "string" &&
+            item.Status.toLowerCase() === "success") ??
             candidates.find((item) => item.Enable !== false) ??
             candidates[0]);
     };
@@ -9630,9 +10342,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.CLOUDRUN_PACKAGE_TYPES = exports.CLOUDRUN_ACCESS_TYPES = exports.CLOUDRUN_SERVICE_TYPES = void 0;
+exports.CLOUDRUN_ENV_TYPE = exports.CLOUDRUN_DEPLOY_REGISTRATION_INTERVAL_MS = exports.CLOUDRUN_DEPLOY_REGISTRATION_MAX_WAIT_MS = exports.CLOUDRUN_PACKAGE_TYPES = exports.CLOUDRUN_ACCESS_TYPES = exports.CLOUDRUN_SERVICE_TYPES = void 0;
+exports.buildManageCloudRunErrorMessage = buildManageCloudRunErrorMessage;
+exports.isValidCloudRunBuildId = isValidCloudRunBuildId;
+exports.isValidCloudRunRunId = isValidCloudRunRunId;
+exports.waitForCloudRunDeployRegistration = waitForCloudRunDeployRegistration;
+exports.buildCloudRunDeployNextStep = buildCloudRunDeployNextStep;
+exports.buildCloudRunDeployProgressHint = buildCloudRunDeployProgressHint;
 exports.queryCloudRunEnvStatus = queryCloudRunEnvStatus;
 exports.describeCloudRunEnvStatus = describeCloudRunEnvStatus;
+exports.extractEnvBaseInfoVpc = extractEnvBaseInfoVpc;
+exports.resolveCloudRunDeployVpcInfo = resolveCloudRunDeployVpcInfo;
+exports.buildCreateCloudRunEnvParam = buildCreateCloudRunEnvParam;
 exports.ensureCloudRunEnvInitialized = ensureCloudRunEnvInitialized;
 exports.detectCloudRunDbNetworkRisk = detectCloudRunDbNetworkRisk;
 exports.extractCloudRunImageInfo = extractCloudRunImageInfo;
@@ -9645,6 +10366,7 @@ const cloudbase_manager_js_1 = __webpack_require__(3431);
 const logger_js_1 = __webpack_require__(3039);
 const gateway_access_urls_js_1 = __webpack_require__(2435);
 const notification_js_1 = __webpack_require__(2720);
+const capi_js_1 = __webpack_require__(738);
 const cloudrun_config_js_1 = __webpack_require__(8266);
 // CloudRun service types
 exports.CLOUDRUN_SERVICE_TYPES = ['function', 'container'];
@@ -9654,7 +10376,7 @@ exports.CLOUDRUN_ACCESS_TYPES = ['OA', 'PUBLIC', 'MINIAPP', 'VPC'];
 exports.CLOUDRUN_PACKAGE_TYPES = ['Trial', 'Standard', 'Professional', 'Enterprise'];
 // Input schema for queryCloudRun tool
 const queryCloudRunInputSchema = {
-    action: zod_1.z.enum(['list', 'detail', 'templates', 'getDeployLog', 'envStatus']).describe('查询操作类型：list=获取云托管服务列表（支持分页和筛选），detail=查询指定服务的详细信息（包含服务配置和最新部署状态），templates=获取可用的项目模板列表（用于初始化新项目），getDeployLog=获取指定服务最近一次或指定构建的部署日志，envStatus=查询当前环境云托管是否已开通及开通状态（Status=creating开通中/normal已开通），用于initEnv之后轮询进度或deploy之前确认环境是否就绪'),
+    action: zod_1.z.enum(['list', 'detail', 'templates', 'getDeployLog', 'getProcessLog', 'getDeployRecords', 'envStatus']).describe('查询操作类型：list=获取云托管服务列表（支持分页和筛选），detail=查询指定服务的详细信息（包含服务配置和最新部署状态），templates=获取可用的项目模板列表（用于初始化新项目），getDeployLog=获取构建日志（仅云端源码构建有意义，走 CODING/DescribeCloudRunBuildLog；已有镜像部署无构建过程；未登录 CODING 的账号会报错），getProcessLog=获取运行日志（部署阶段步骤+容器启动/运行日志，走 tcbr/DescribeCloudRunProcessLog；镜像部署与源码构建均可用，不依赖 CODING；RunId 来自 detail/getDeployRecords 的 latestDeploy.RunId），getDeployRecords=获取指定服务的部署记录列表（按部署时间倒序，含 BuildId/RunId/FlowRatio/Status 等字段，用于查看历史发布与回滚上下文），envStatus=查询当前环境云托管是否已开通及开通状态（Status=creating开通中/normal已开通），用于initEnv之后轮询进度或deploy之前确认环境是否就绪'),
     // List operation parameters
     pageSize: zod_1.z.number().min(1).max(100).optional().default(10).describe('分页大小，控制每页返回的服务数量。取值范围：1-100，默认值：10。建议根据网络性能和显示需求调整'),
     pageNum: zod_1.z.number().min(1).optional().default(1).describe('页码，用于分页查询。从1开始，默认值：1。配合pageSize使用可实现分页浏览'),
@@ -9662,19 +10384,26 @@ const queryCloudRunInputSchema = {
     serverType: zod_1.z.enum(exports.CLOUDRUN_SERVICE_TYPES).optional().describe('服务类型筛选条件：function=函数型云托管（仅支持Node.js，有特殊的开发要求和限制，适合简单的API服务），container=容器型服务（推荐使用，支持任意语言和框架如Java/Go/Python/PHP/.NET等，适合大多数应用场景）'),
     envId: zod_1.z.string().optional().describe('环境 ID（action=envStatus 时使用；不传则使用当前配置的环境）。格式如 env-xxxxxx'),
     // Detail and log operation parameters
-    detailServerName: zod_1.z.string().optional().describe('要查询详细信息或部署日志的服务名称。当action为detail或getDeployLog时建议提供，必须是已存在的服务名称。可通过list操作获取可用的服务名称列表'),
-    buildId: zod_1.z.number().optional().describe('构建ID，仅在action=getDeployLog时使用。不传时默认返回最近一次部署的构建日志'),
+    detailServerName: zod_1.z.string().optional().describe('要查询详细信息、部署记录、构建日志或运行日志的服务名称。当action为detail、getDeployLog、getProcessLog或getDeployRecords时建议提供，必须是已存在的服务名称。可通过list操作获取可用的服务名称列表'),
+    buildId: zod_1.z.number().optional().describe('构建ID，仅在action=getDeployLog时使用（构建日志，仅云端源码构建）。不传时默认返回最近一次部署的构建日志'),
+    runId: zod_1.z.string().optional().describe('运行ID（RunId），仅在action=getProcessLog时使用。不传时默认取该服务最近一次部署记录的 RunId（与 detail/getDeployRecords 的 latestDeploy.RunId 同源）。镜像部署与源码构建均可查询运行日志'),
 };
 // Input schema for manageCloudRun tool
 const ManageCloudRunInputSchema = {
-    action: zod_1.z.enum(['init', 'download', 'run', 'deploy', 'delete', 'createAgent', 'updateConfig', 'initEnv']).describe('云托管服务管理操作类型：init=从模板初始化新的云托管项目代码（在targetPath目录下创建以serverName命名的子目录，支持多种语言和框架模板），download=从云端下载现有服务的代码到本地进行开发，run=在本地运行函数型云托管服务（用于开发和调试，仅支持函数型服务），deploy=将本地代码部署到云端云托管服务（支持函数型和容器型；传 imageUrl 时改为已有镜像部署，走 DeployType=image 容器型，targetPath 可省略；已存在服务会 Read-Merge-Write 保留远程 VpcConf/EnvParams/OpenAccessTypes），updateConfig=仅更新服务配置不重新上传代码（对齐控制台服务设置，走 SubmitServerConfigChangeDiff；不需要 targetPath），delete=删除指定的云托管服务（不可恢复，需要确认），createAgent=创建函数型Agent（基于函数型云托管开发AI智能体），initEnv=开通当前环境的云托管（异步创建云托管环境，幂等：已开通直接返回；适合新环境首次部署前使用）'),
+    action: zod_1.z.enum(['init', 'download', 'run', 'deploy', 'delete', 'createAgent', 'updateConfig', 'initEnv', 'traffic']).describe('云托管服务管理操作类型：init=从模板初始化新的云托管项目代码（在targetPath目录下创建以serverName命名的子目录，支持多种语言和框架模板），download=从云端下载现有服务的代码到本地进行开发，run=在本地运行函数型云托管服务（用于开发和调试，仅支持函数型服务），deploy=触发部署并轻量等待任务注册（不会 hang 等完整构建）。源码构建（targetPath）返回 buildId，用 getDeployLog 轮询后再 getProcessLog；已有镜像部署（imageUrl，DeployType=image，BuildId 常为 0）跳过 getDeployLog，用 detail/getDeployRecords 取 RunId 后 getProcessLog。传 imageUrl 时 targetPath 可省略；已存在服务会 Read-Merge-Write 保留远程 VpcConf/EnvParams/OpenAccessTypes），updateConfig=仅更新服务配置不重新上传代码（对齐控制台服务设置，走 SubmitServerConfigChangeDiff；不需要 targetPath），delete=删除指定的云托管服务（不可恢复，需要确认），createAgent=创建函数型Agent（基于函数型云托管开发AI智能体），initEnv=开通当前环境的云托管（异步创建云托管环境，幂等：已开通直接返回；适合新环境首次部署前使用），traffic=流量管理与灰度发布（set=调整稳定版/灰度版流量比例，promote=将灰度版本升级为全量，rollback=回滚到上一个稳定版本；对应 tcb cloudrun traffic 命令）'),
     serverName: zod_1.z.string().describe('云托管服务名称，用于标识和管理服务。命名规则：支持大小写字母、数字、连字符和下划线，必须以字母开头，长度3-45个字符。在init操作中会作为在targetPath下创建的子目录名，在其他操作中作为目标服务名。initEnv 操作不需要此参数'),
+    // Traffic management operation parameters (action=traffic)
+    trafficOp: zod_1.z.enum(['set', 'promote', 'rollback']).optional().describe('流量管理子操作（action=traffic 时使用）：set=调整灰度流量比例（需先部署新版本至灰度，通过 stablePercent/canaryPercent 设置稳定版与灰度版流量比例，两者之和必须等于100）；promote=将灰度版本全量发布（灰度版本流量置为100%并关闭灰度发布，等价于 tcb cloudrun traffic promote）；rollback=回滚到上一个稳定版本（停止当前灰度/发布中的版本，回到稳定版本，等价于 tcb cloudrun traffic rollback）'),
+    stablePercent: zod_1.z.number().min(0).max(100).optional().describe('稳定版本流量比例（trafficOp=set 时使用），取值范围0-100。与 canaryPercent 之和必须等于100。例如希望 90% 流量打到稳定版、10% 打到灰度版，则 stablePercent=90, canaryPercent=10'),
+    canaryPercent: zod_1.z.number().min(0).max(100).optional().describe('灰度版本流量比例（trafficOp=set 时使用），取值范围0-100。与 stablePercent 之和必须等于100。例如希望 90% 流量打到稳定版、10% 打到灰度版，则 stablePercent=90, canaryPercent=10'),
     // InitEnv operation parameters
     envId: zod_1.z.string().optional().describe('环境 ID（action=initEnv 时使用；不传则使用当前配置的环境）。格式如 env-xxxxxx'),
     packageType: zod_1.z.enum(exports.CLOUDRUN_PACKAGE_TYPES).optional().default('Trial').describe('云托管环境套餐类型（action=initEnv 时使用）：Trial=试用，Standard=标准，Professional=专业，Enterprise=企业。默认 Trial'),
+    vpcId: zod_1.z.string().optional().describe('VPC 网络 ID（action=initEnv 时可选）。当平台拒绝系统创建网络时必填，格式如 vpc-xxxxxxxx。与 subnetIds 一起透传给 CreateCloudRunEnv 的 VpcId/SubNetIds。多数场景可不传（由系统创建网络）'),
+    subnetIds: zod_1.z.array(zod_1.z.string()).optional().describe('子网 ID 列表（action=initEnv 时可选）。当需指定自有 VPC 时必填，如 ["subnet-xxxxxxxx"]。与 vpcId 一起透传给 CreateCloudRunEnv 的 SubNetIds'),
     // Deploy operation parameters
-    targetPath: zod_1.z.string().optional().describe('本地代码路径，必须是绝对路径。在deploy操作中指定要部署的代码目录，在download操作中指定下载目标目录，在init操作中指定云托管服务的上级目录（会在该目录下创建以serverName命名的子目录）。updateConfig 不需要此参数。建议约定：项目根目录下的cloudrun/目录，例如：/Users/username/projects/my-project/cloudrun。使用 imageUrl 部署已有镜像时此参数可省略'),
-    imageUrl: zod_1.z.string().optional().describe('已有镜像部署（action=deploy 时使用）：直接指定容器镜像地址，如 ccr.ccs.tencentyun.com/ns/img:v1 或公网 registry 地址。传入后走 DeployType="image"（容器型）部署，无需本地源码目录（targetPath 可省略）。支持：1) 公网匿名可拉取的镜像直填地址；2) 私有/需登录的镜像（如 ghcr.io）需先在本地 docker pull → docker tag/push 到腾讯云 CCR → 填入 CCR 地址。不传则维持源码构建（本地代码打包上传）。注意：无论哪种部署方式，环境都需先开通云托管（未开通时先调用 initEnv，Status=normal 后再部署）'),
+    targetPath: zod_1.z.string().optional().describe('本地代码路径，必须是绝对路径。在deploy操作中指定要部署的代码目录，在download操作中指定下载目标目录，在init操作中指定云托管服务的上级目录（会在该目录下创建以serverName命名的子目录）。updateConfig 不需要此参数。建议约定：项目根目录下的cloudrun/目录，例如：/Users/username/projects/my-project/cloudrun。使用 imageUrl 部署已有镜像时此参数可省略。注意：本地有源码目录不等于必须走源码构建；若用户指定镜像请优先传 imageUrl，不要仅因存在 targetPath 就回退到源码构建'),
+    imageUrl: zod_1.z.string().optional().describe('已有镜像部署（action=deploy 时使用）：直接指定容器镜像地址，如 ccr.ccs.tencentyun.com/ns/img:v1 或公网 registry 地址。传入后走 DeployType="image"（容器型）部署，无需本地源码目录（targetPath 可省略）。支持：1) 公网匿名可拉取的镜像直填地址；2) 私有/需登录的镜像（如 ghcr.io）需先在本地 docker pull → docker tag/push 到腾讯云 CCR → 填入 CCR 地址。不传则维持源码构建（本地代码打包上传）。约束：若用户明确提到使用某个镜像、或无需重新构建代码，则必须传 imageUrl 走镜像部署，不要回退到源码构建。注意：无论哪种部署方式，环境都需先开通云托管（未开通时先调用 initEnv，Status=normal 后再部署）'),
     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内可访问）。可配置多个类型'),
@@ -9695,7 +10424,7 @@ const ManageCloudRunInputSchema = {
         InternalDomain: zod_1.z.string().optional().describe('内网域名配置，用于配置服务的内网访问域名。仅在启用内网访问时有效'),
         EntryPoint: zod_1.z.array(zod_1.z.string()).optional().describe('Dockerfile EntryPoint参数配置，仅容器型服务需要。指定容器启动时的入口程序数组，如["node","app.js"]'),
         Cmd: zod_1.z.array(zod_1.z.string()).optional().describe('Dockerfile Cmd参数配置，仅容器型服务需要。指定容器启动时的默认命令数组，如["npm","start"]'),
-        InitialDelaySeconds: zod_1.z.number().min(0).optional().describe('延迟检测时间（秒），用于配置服务启动后的健康检查延迟。在此期间内不会将请求路由到该实例，适用于启动时间较长的服务'),
+        InitialDelaySeconds: zod_1.z.number().min(0).optional().describe('端口健康检查初始延迟（秒）。部署完成后先等待 N 秒才开始端口探测，之后约每 5s 检查一次、连续约 30 次；30 次全失败才判定部署失败（约 150s 探测窗口），不是「N 秒后立即失败」。启动耗时长的应用建议调到 60–120'),
         LogType: zod_1.z.string().optional().describe('日志类型配置，指定服务的日志收集类型。影响日志的采集方式和存储格式'),
         LogSetId: zod_1.z.string().optional().describe('CLS日志集ID配置，指定日志服务（CLS）的日志集ID。需要先开通CLS日志服务'),
         LogTopicId: zod_1.z.string().optional().describe('CLS日志主题ID配置，指定日志服务（CLS）的日志主题ID。需要先开通CLS日志服务'),
@@ -9809,20 +10538,233 @@ function validateAndNormalizePath(inputPath) {
 function buildManageCloudRunErrorMessage(action, serverName, error) {
     const baseMessage = error instanceof Error ? error.message : String(error);
     const suggestions = [];
+    if ((0, capi_js_1.isCamAuthError)(baseMessage)) {
+        suggestions.push((0, capi_js_1.buildCamAuthGuidance)());
+    }
     if (/已有部署发布任务运行中|部署发布任务运行中/i.test(baseMessage)) {
         suggestions.push(`服务 \`${serverName}\` 当前已有部署任务在执行，请等待现有任务完成后再重试。`);
         suggestions.push("如果你确认要覆盖当前流程，可在合适时机使用 `force=true` 再次发起。");
     }
+    if (/云托管资源未开通|无法使用系统创建网络|VpcInfo/i.test(baseMessage)) {
+        suggestions.push("CreateCloudRunServer 需要有效 VPC：请传 serverConfig.VpcConf（VpcId+SubnetId），" +
+            "或在 initEnv 时传入 vpcId/subnetIds（环境开通后 deploy 会自动从 EnvBaseInfo 回填）。" +
+            "若平台拒绝系统创建网络，必须指定上海地域 VPC。");
+    }
     if (suggestions.length === 0) {
         suggestions.push("请检查服务状态、部署参数和目标目录后重试。");
     }
     return `[manageCloudRun/${action}] ${baseMessage}\n建议：${suggestions.join(" ")}`;
 }
-const CLOUDRUN_DB_ENV_KEY_PATTERN = /^(DATABASE_URL|DB_HOST|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|MYSQL_|POSTGRES_|PGHOST|PGPORT|PGUSER|PGPASSWORD|PGDATABASE|PG_|REDIS_|MONGO_|MONGODB_|SQLALCHEMY_DATABASE_URI|SPRING_DATASOURCE_)/i;
-const CLOUDRUN_DB_URL_PATTERN = /(mysql|mariadb|postgres|postgresql|mongodb(\+srv)?|redis|rediss):\/\//i;
-async function queryCloudRunEnvStatus(options) {
-    const manager = await (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions: options.cloudBaseOptions });
-    if (!manager?.commonService) {
+/**
+ * Lightweight wait after manageCloudRun deploy: poll until the platform has
+ * registered the manage task / assigned identifiers for follow-up log queries.
+ * - source builds: prefer BuildId > 0 (getDeployLog)
+ * - image deploys: prefer RunId (getProcessLog; BuildId is often 0)
+ * Does NOT wait for the full build/deploy (that can take 5–30 minutes).
+ * Aligns with tcb CLI's DescribeServerManageTask polling entrypoint, but with
+ * a short timeout suitable for MCP tool calls.
+ */
+exports.CLOUDRUN_DEPLOY_REGISTRATION_MAX_WAIT_MS = 45_000;
+exports.CLOUDRUN_DEPLOY_REGISTRATION_INTERVAL_MS = 3_000;
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isValidCloudRunBuildId(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isValidCloudRunRunId(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function extractServerManageTaskInfo(resp) {
+    const data = (resp ?? {});
+    const task = (data.Task ?? data.task ?? {});
+    const rawId = task.Id ?? task.id;
+    const rawStatus = task.Status ?? task.status;
+    const taskId = typeof rawId === "number" && rawId > 0
+        ? rawId
+        : typeof rawId === "string" && /^\d+$/.test(rawId) && Number(rawId) > 0
+            ? Number(rawId)
+            : undefined;
+    const taskStatus = typeof rawStatus === "string" && rawStatus.trim()
+        ? rawStatus.trim()
+        : undefined;
+    return {
+        ...(taskId !== undefined ? { taskId } : {}),
+        ...(taskStatus ? { taskStatus } : {}),
+    };
+}
+/**
+ * Poll DescribeServerManageTask + getDeployRecords until the preferred
+ * identifier appears:
+ * - source (default): BuildId > 0 for getDeployLog
+ * - image: RunId for getProcessLog (BuildId is often 0)
+ * If only taskId is seen, keeps polling for the preferred id until maxWaitMs.
+ */
+async function waitForCloudRunDeployRegistration(options) {
+    const mode = options.mode ?? "source";
+    const maxWaitMs = options.maxWaitMs ?? exports.CLOUDRUN_DEPLOY_REGISTRATION_MAX_WAIT_MS;
+    const intervalMs = options.intervalMs ?? exports.CLOUDRUN_DEPLOY_REGISTRATION_INTERVAL_MS;
+    const sleepFn = options.sleepFn ?? sleepMs;
+    const startAt = Date.now();
+    let lastTaskId;
+    let lastTaskStatus;
+    let lastBuildId;
+    let lastRunId;
+    // Immediate first probe, then interval retries until timeout.
+    for (;;) {
+        if (options.manager.commonService) {
+            try {
+                const resp = await options.manager
+                    .commonService("tcbr", "2022-02-17")
+                    .call({
+                    Action: "DescribeServerManageTask",
+                    Param: {
+                        EnvId: options.envId,
+                        ServerName: options.serverName,
+                        TaskId: lastTaskId ?? 0,
+                    },
+                });
+                const info = extractServerManageTaskInfo(resp);
+                if (info.taskId !== undefined) {
+                    lastTaskId = info.taskId;
+                }
+                if (info.taskStatus) {
+                    lastTaskStatus = info.taskStatus;
+                }
+            }
+            catch {
+                // Task may not be queryable yet; retry until timeout.
+            }
+        }
+        if (typeof options.cloudrunService.getDeployRecords === "function") {
+            try {
+                const recordsResult = (await options.cloudrunService.getDeployRecords({
+                    serverName: options.serverName,
+                }));
+                const latest = recordsResult?.DeployRecords?.[0];
+                if (isValidCloudRunBuildId(latest?.BuildId)) {
+                    lastBuildId = latest.BuildId;
+                }
+                if (isValidCloudRunRunId(latest?.RunId)) {
+                    lastRunId = latest.RunId.trim();
+                }
+            }
+            catch {
+                // Deploy record may lag behind task registration; retry.
+            }
+        }
+        const preferredReady = mode === "image"
+            ? isValidCloudRunRunId(lastRunId)
+            : isValidCloudRunBuildId(lastBuildId);
+        if (preferredReady) {
+            return {
+                registered: true,
+                timedOut: false,
+                taskId: lastTaskId,
+                ...(isValidCloudRunBuildId(lastBuildId) ? { buildId: lastBuildId } : {}),
+                ...(isValidCloudRunRunId(lastRunId) ? { runId: lastRunId } : {}),
+                taskStatus: lastTaskStatus,
+                waitMs: Date.now() - startAt,
+            };
+        }
+        if (Date.now() - startAt >= maxWaitMs) {
+            break;
+        }
+        await sleepFn(intervalMs);
+    }
+    const registered = isValidCloudRunBuildId(lastBuildId) ||
+        isValidCloudRunRunId(lastRunId) ||
+        (typeof lastTaskId === "number" && lastTaskId > 0);
+    return {
+        registered,
+        timedOut: true,
+        taskId: lastTaskId,
+        ...(isValidCloudRunBuildId(lastBuildId) ? { buildId: lastBuildId } : {}),
+        ...(isValidCloudRunRunId(lastRunId) ? { runId: lastRunId } : {}),
+        taskStatus: lastTaskStatus,
+        waitMs: Date.now() - startAt,
+    };
+}
+/**
+ * Build manageCloudRun(deploy) next_step by DeployType:
+ * - source: getDeployLog (+ follow-up getProcessLog)
+ * - image: skip getDeployLog; getProcessLog via RunId (or getDeployRecords first)
+ */
+function buildCloudRunDeployNextStep(options) {
+    const { deployType, serverName, registered } = options;
+    if (deployType === "image") {
+        if (isValidCloudRunRunId(options.runId)) {
+            return {
+                tool: "queryCloudRun",
+                action: "getProcessLog",
+                suggested_args: {
+                    action: "getProcessLog",
+                    detailServerName: serverName,
+                    runId: options.runId.trim(),
+                },
+                note: "Image deploy has no CODING build process; skip getDeployLog. Poll getProcessLog for deploy-step and container runtime logs.",
+            };
+        }
+        return {
+            tool: "queryCloudRun",
+            action: "getDeployRecords",
+            suggested_args: {
+                action: "getDeployRecords",
+                detailServerName: serverName,
+            },
+            note: registered
+                ? "Image deploy: read latestDeploy.RunId, then queryCloudRun(action=\"getProcessLog\", runId=...). Skip getDeployLog."
+                : "Image deploy registration still queueing; retry getDeployRecords for RunId, then getProcessLog. Skip getDeployLog.",
+        };
+    }
+    if (isValidCloudRunBuildId(options.buildId)) {
+        return {
+            tool: "queryCloudRun",
+            action: "getDeployLog",
+            suggested_args: {
+                action: "getDeployLog",
+                detailServerName: serverName,
+                buildId: options.buildId,
+            },
+            note: "Source build: poll getDeployLog for build progress, then getProcessLog (RunId from detail/getDeployRecords) for runtime/deploy-step logs.",
+        };
+    }
+    return {
+        tool: "queryCloudRun",
+        action: "getDeployLog",
+        suggested_args: {
+            action: "getDeployLog",
+            detailServerName: serverName,
+        },
+        note: registered
+            ? "BuildId not yet available; omit buildId to use the latest deploy record. After build, use getProcessLog for runtime logs."
+            : "Registration timed out; wait a moment then retry getDeployLog, or open consoleUrl. After build, use getProcessLog for runtime logs.",
+    };
+}
+function buildCloudRunDeployProgressHint(options) {
+    const { deployType, serverName, consoleUrl } = options;
+    if (deployType === "image") {
+        if (isValidCloudRunRunId(options.runId)) {
+            return ` Image deploy: use queryCloudRun(action="getProcessLog", detailServerName="${serverName}", runId="${options.runId.trim()}") for runtime/deploy-step logs (skip getDeployLog).`;
+        }
+        if (options.registered) {
+            return ` Image deploy registered${typeof options.taskId === "number" ? ` (taskId=${options.taskId})` : ""}; RunId not yet available — use queryCloudRun(action="getDeployRecords", detailServerName="${serverName}") then getProcessLog (skip getDeployLog), or check ${consoleUrl}.`;
+        }
+        return ` Image deploy registration timed out after ${Math.round(options.waitMs / 1000)}s — retry getDeployRecords for RunId then getProcessLog (skip getDeployLog), or check ${consoleUrl}.`;
+    }
+    if (isValidCloudRunBuildId(options.buildId)) {
+        return ` Use queryCloudRun(action="getDeployLog", detailServerName="${serverName}", buildId=${options.buildId}) to poll build progress, then getProcessLog for runtime logs.`;
+    }
+    if (options.registered) {
+        return ` Task registered (taskId=${options.taskId ?? "unknown"}); BuildId not yet available — retry queryCloudRun(action="getDeployLog", detailServerName="${serverName}") shortly, then getProcessLog, or check ${consoleUrl}.`;
+    }
+    return ` Build registration timed out after ${Math.round(options.waitMs / 1000)}s — deployment may still be queueing. Check ${consoleUrl} or retry queryCloudRun(action="getDeployLog", detailServerName="${serverName}") later.`;
+}
+const CLOUDRUN_DB_ENV_KEY_PATTERN = /^(DATABASE_URL|DB_HOST|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|MYSQL_|POSTGRES_|PGHOST|PGPORT|PGUSER|PGPASSWORD|PGDATABASE|PG_|REDIS_|MONGO_|MONGODB_|SQLALCHEMY_DATABASE_URI|SPRING_DATASOURCE_)/i;
+const CLOUDRUN_DB_URL_PATTERN = /(mysql|mariadb|postgres|postgresql|mongodb(\+srv)?|redis|rediss):\/\//i;
+async function queryCloudRunEnvStatus(options) {
+    const manager = await (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions: options.cloudBaseOptions });
+    if (!manager?.commonService) {
         throw new Error("Current CloudBase Manager does not support commonService; cannot query CloudRun env status.");
     }
     return describeCloudRunEnvStatus(manager, options.envId);
@@ -9844,11 +10786,80 @@ async function describeCloudRunEnvStatus(manager, envId) {
         return { isExist: false, status: "unopened", baseInfo };
     }
     const rawStatus = typeof baseInfo.Status === "string" ? baseInfo.Status : "";
-    const status = rawStatus === "creating" || rawStatus === "normal"
-        ? rawStatus
+    // Platform may return NORMAL/CREATING (uppercase); normalize before matching.
+    const normalizedStatus = rawStatus.toLowerCase();
+    const status = normalizedStatus === "creating" || normalizedStatus === "normal"
+        ? normalizedStatus
         : "unknown";
     return { isExist: true, status, baseInfo };
 }
+/** CloudRun EnvType for CreateCloudRunEnv (baas DescribeEnvBaseInfo enum). */
+exports.CLOUDRUN_ENV_TYPE = "baas";
+/**
+ * Extract VPC binding from DescribeEnvBaseInfo.EnvBaseInfo when the env was
+ * opened with an explicit VPC.
+ */
+function extractEnvBaseInfoVpc(baseInfo) {
+    if (!baseInfo) {
+        return undefined;
+    }
+    const vpcId = typeof baseInfo.VpcId === "string" ? baseInfo.VpcId.trim() : "";
+    const rawSubnets = baseInfo.SubNetIds ?? baseInfo.SubnetIds;
+    const subnetIds = Array.isArray(rawSubnets)
+        ? rawSubnets
+            .filter((item) => typeof item === "string" && item.trim().length > 0)
+            .map((item) => item.trim())
+        : [];
+    if (!vpcId || subnetIds.length === 0) {
+        return undefined;
+    }
+    return { VpcId: vpcId, SubnetIds: subnetIds };
+}
+/**
+ * Resolve CreateCloudRunServer.VpcInfo: prefer explicit serverConfig.VpcConf,
+ * otherwise fall back to env-level VPC from DescribeEnvBaseInfo.
+ */
+function resolveCloudRunDeployVpcInfo(options) {
+    const conf = options.vpcConf;
+    if (conf?.VpcId?.trim() && conf?.SubnetId?.trim()) {
+        return {
+            VpcId: conf.VpcId.trim(),
+            CreateType: 2,
+            SubnetIds: [conf.SubnetId.trim()],
+        };
+    }
+    const fromEnv = extractEnvBaseInfoVpc(options.envBaseInfo);
+    if (!fromEnv) {
+        return undefined;
+    }
+    return {
+        VpcId: fromEnv.VpcId,
+        CreateType: 2,
+        SubnetIds: fromEnv.SubnetIds,
+    };
+}
+/**
+ * Build CreateCloudRunEnv Param, always including EnvType=baas.
+ * Optional vpcId/subnetIds are used when the platform requires an explicit VPC.
+ */
+function buildCreateCloudRunEnvParam(options) {
+    const param = {
+        EnvId: options.envId,
+        PackageType: options.packageType,
+        EnvType: exports.CLOUDRUN_ENV_TYPE,
+    };
+    const vpcId = options.vpcId?.trim();
+    const subnetIds = (options.subnetIds ?? [])
+        .filter((id) => typeof id === "string" && id.trim().length > 0)
+        .map((id) => id.trim());
+    if (vpcId) {
+        param.VpcId = vpcId;
+    }
+    if (subnetIds.length > 0) {
+        param.SubNetIds = subnetIds;
+    }
+    return param;
+}
 /**
  * 探测当前环境云托管（大租户）是否已初始化。
  *
@@ -10058,7 +11069,7 @@ function registerCloudRunTools(server) {
     // Tool 1: Get CloudRun service information (read operations)
     server.registerTool("queryCloudRun", {
         title: "查询 CloudRun 服务信息",
-        description: "查询云托管服务信息，支持获取服务列表、查询服务详情、获取可用模板列表、获取部署日志以及查询环境云托管开通状态（envStatus）。返回的服务信息包括服务名称、状态、访问类型、配置详情以及最近部署上下文。",
+        description: "查询云托管服务信息，支持获取服务列表、查询服务详情、获取可用模板列表、获取构建日志（getDeployLog，仅云端源码构建/依赖 CODING）、获取运行日志（getProcessLog，镜像与源码部署均可/不依赖 CODING）、获取部署记录以及查询环境云托管开通状态（envStatus）。返回的服务信息包括服务名称、状态、访问类型、配置详情以及最近部署上下文。",
         inputSchema: queryCloudRunInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -10146,10 +11157,13 @@ function registerCloudRunTools(server) {
                     if (!latestDeploy) {
                         message = `Retrieved details for service '${serverName}'. No deploy records found yet.`;
                     }
-                    else if (typeof latestDeploy.Status === 'string' && latestDeploy.Status.includes('failed')) {
-                        message = `Service '${serverName}' latest deploy failed. Please use queryCloudRun(action="getDeployLog") for details.`;
+                    else if (typeof latestDeploy.Status === "string" &&
+                        // Platform may return FAILED/CREATING (uppercase); normalize before matching.
+                        latestDeploy.Status.toLowerCase().includes("failed")) {
+                        message = `Service '${serverName}' latest deploy failed. Use queryCloudRun(action="getProcessLog") for runtime/deploy-step logs (RunId from latestDeploy); use getDeployLog only for cloud source-build logs (CODING).`;
                     }
-                    else if (typeof latestDeploy.Status === 'string' && latestDeploy.Status.includes('creating')) {
+                    else if (typeof latestDeploy.Status === "string" &&
+                        latestDeploy.Status.toLowerCase().includes("creating")) {
                         message = `Service '${serverName}' latest deploy is still running. Please check again later or query the deploy log for progress.`;
                     }
                     else {
@@ -10232,6 +11246,9 @@ function registerCloudRunTools(server) {
                     };
                 }
                 const buildId = input.buildId ?? latestDeploy.BuildId;
+                // Build log (CODING / DescribeCloudRunBuildLog). Meaningful only for
+                // cloud source builds; image deploys have no build process. Accounts
+                // without a CODING user may fail here — use getProcessLog for runtime logs.
                 const buildLogResult = await cloudrunService.getBuildLog({
                     serverName,
                     buildId,
@@ -10262,11 +11279,130 @@ function registerCloudRunTools(server) {
                                     buildId,
                                     deployRecord: latestDeploy,
                                     buildLog: buildLogResult?.Log || null,
+                                    // Optional best-effort attach; prefer dedicated getProcessLog for runtime diagnosis
                                     processLogs,
                                     combinedLogText,
                                     ...(processLogsWarning ? { processLogsWarning } : {})
                                 },
-                                message: `Retrieved deploy log for service '${serverName}'`
+                                message: `Retrieved build log for service '${serverName}' (getDeployLog=构建日志; for 运行日志 use getProcessLog with RunId)`
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case 'getProcessLog': {
+                const serverName = getCloudRunQueryServerName(input);
+                if (!serverName && !input.runId?.trim()) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "runId is required, or provide detailServerName/serverName to resolve latest RunId",
+                                    message: "Pass runId from detail/getDeployRecords latestDeploy.RunId, or provide a service name to use the latest deploy RunId."
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                let runId = input.runId?.trim() || "";
+                let deployRecord = null;
+                if (serverName) {
+                    const deployRecordsResult = await cloudrunService.getDeployRecords({ serverName });
+                    const deployRecords = Array.isArray(deployRecordsResult?.DeployRecords)
+                        ? deployRecordsResult.DeployRecords
+                        : [];
+                    deployRecord = deployRecords[0] ?? null;
+                    if (!runId) {
+                        runId = typeof deployRecord?.RunId === "string" ? deployRecord.RunId.trim() : "";
+                    }
+                    else if (deployRecord?.RunId && deployRecord.RunId !== runId) {
+                        // Keep latest deploy as context only; explicit runId wins
+                    }
+                }
+                if (!runId) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: serverName
+                                        ? `Service '${serverName}' has no RunId on the latest deploy record.`
+                                        : "runId is required for getProcessLog action",
+                                    message: "Deploy the service first, then read RunId from queryCloudRun(action=\"detail\") or getDeployRecords (latestDeploy.RunId)."
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                if (typeof cloudrunService.getProcessLog !== "function") {
+                    throw new Error("Current CloudBase Manager SDK does not support getProcessLog; please upgrade @cloudbase/manager-node.");
+                }
+                const processLogResult = await cloudrunService.getProcessLog({
+                    RunId: runId,
+                });
+                const processLogs = Array.isArray(processLogResult?.Logs)
+                    ? processLogResult.Logs
+                    : [];
+                const processLogText = processLogs.length > 0
+                    ? normalizeProcessLogText(processLogs)
+                    : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                data: {
+                                    serverName: serverName || undefined,
+                                    runId,
+                                    deployRecord,
+                                    processLogs,
+                                    processLogText,
+                                    requestId: processLogResult?.RequestId,
+                                },
+                                message: `Retrieved process/runtime log for RunId='${runId}' (getProcessLog=运行日志; getDeployLog=构建日志且仅云端构建/依赖 CODING)`
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case 'getDeployRecords': {
+                const serverName = getCloudRunQueryServerName(input);
+                if (!serverName) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "detailServerName or serverName is required for getDeployRecords action",
+                                    message: "Please provide detailServerName or serverName."
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                const deployRecordsResult = await cloudrunService.getDeployRecords({ serverName });
+                const deployRecords = Array.isArray(deployRecordsResult?.DeployRecords)
+                    ? deployRecordsResult.DeployRecords
+                    : [];
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                data: {
+                                    serverName,
+                                    deployRecords,
+                                    // 部署记录按部署时间倒序（最新在前），首条为最近一次部署
+                                    total: deployRecords.length,
+                                    latestDeploy: deployRecords[0] ?? null
+                                },
+                                message: `Retrieved ${deployRecords.length} deploy records for service '${serverName}'`
                             }, null, 2)
                         }
                     ]
@@ -10340,7 +11476,7 @@ function registerCloudRunTools(server) {
     // Tool 2: Manage CloudRun services (write operations)
     server.registerTool("manageCloudRun", {
         title: "管理 CloudRun 服务",
-        description: "管理云托管服务，按开发顺序支持：开通云托管环境（initEnv）、初始化项目（可从模板开始，模板列表可通过 queryCloudRun 查询）、下载服务代码、本地运行（仅函数型服务）、部署代码、仅更新配置（updateConfig，无需重新上传代码）、删除服务。deploy 支持两种方式：1) 源码构建（传入 targetPath，本地代码打包上传，默认路径）；2) 已有镜像部署（传入 imageUrl，如 ccr.ccs.tencentyun.com/ns/img:v1，走 DeployType=image 容器型部署，targetPath 可省略）。deploy 对已存在服务会先读取远程配置再合并（保留 VpcConf/EnvParams/OpenAccessTypes）。updateConfig 对齐控制台服务设置页。删除操作需要确认，建议设置force=true。新环境首次部署前若提示未开通云托管，先调用 initEnv 开通（异步、幂等）。",
+        description: "管理云托管服务，按开发顺序支持：开通云托管环境（initEnv）、初始化项目（可从模板开始，模板列表可通过 queryCloudRun 查询）、下载服务代码、本地运行（仅函数型服务）、部署代码、仅更新配置（updateConfig，无需重新上传代码）、删除服务。deploy 支持两种方式：1) 源码构建（传入 targetPath，本地代码打包上传，默认路径）；2) 已有镜像部署（传入 imageUrl，如 ccr.ccs.tencentyun.com/ns/img:v1，走 DeployType=image 容器型部署，targetPath 可省略）。deploy 语义为「触发部署 + 轻量等待任务注册」（最多约 45s）。源码构建返回 buildId，用 getDeployLog 轮询构建进度后再 getProcessLog；镜像部署（imageUrl）BuildId 常为 0，跳过 getDeployLog，返回 runId/next_step 引导 getProcessLog（或先 getDeployRecords 取 RunId）。若用户明确指定镜像或无需重新构建，必须传 imageUrl，不要仅因本地有源码目录就回退到源码构建。deploy 对已存在服务会先读取远程配置再合并（保留 VpcConf/EnvParams/OpenAccessTypes）。updateConfig 对齐控制台服务设置页。删除操作需要确认，建议设置force=true。新环境首次部署前若提示未开通云托管，先调用 initEnv 开通（异步、幂等）。",
         inputSchema: ManageCloudRunInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -10420,13 +11556,19 @@ function registerCloudRunTools(server) {
                     };
                 }
                 // 未开通 → 发起异步开通（CreateCloudRunEnv 异步，不阻塞等待）。
+                // Always pass EnvType=baas; optional vpcId/subnetIds when an explicit VPC is required.
                 let createResult;
                 try {
                     createResult = await manager
                         .commonService("tcbr", "2022-02-17")
                         .call({
                         Action: "CreateCloudRunEnv",
-                        Param: { EnvId: envId, PackageType: packageType },
+                        Param: buildCreateCloudRunEnvParam({
+                            envId,
+                            packageType,
+                            vpcId: input.vpcId,
+                            subnetIds: input.subnetIds,
+                        }),
                     });
                 }
                 catch (error) {
@@ -10454,6 +11596,98 @@ function registerCloudRunTools(server) {
                     ]
                 };
             }
+            case 'traffic': {
+                const trafficOp = input.trafficOp;
+                if (!trafficOp) {
+                    throw new Error("trafficOp is required for traffic operation (set | promote | rollback)");
+                }
+                if (trafficOp === 'set') {
+                    const stable = input.stablePercent;
+                    const canary = input.canaryPercent;
+                    if (typeof stable !== 'number' ||
+                        typeof canary !== 'number') {
+                        throw new Error("stablePercent and canaryPercent are required for trafficOp=set");
+                    }
+                    if (stable + canary !== 100) {
+                        throw new Error(`stablePercent + canaryPercent must equal 100 (got ${stable} + ${canary} = ${stable + canary}). ` +
+                            `Example: 90/10 means 90% to stable version, 10% to canary version.`);
+                    }
+                    let setResult;
+                    try {
+                        setResult = await cloudrunService.setTraffic(input.serverName, stable, canary);
+                    }
+                    catch (error) {
+                        throw new Error(buildManageCloudRunErrorMessage('traffic/set', input.serverName, error));
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        serverName: input.serverName,
+                                        trafficOp: 'set',
+                                        stablePercent: stable,
+                                        canaryPercent: canary,
+                                        result: setResult ?? null
+                                    },
+                                    message: `Set traffic for service '${input.serverName}': stable ${stable}% / canary ${canary}%`
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                if (trafficOp === 'promote') {
+                    let promoteResult;
+                    try {
+                        promoteResult = await cloudrunService.promote(input.serverName);
+                    }
+                    catch (error) {
+                        throw new Error(buildManageCloudRunErrorMessage('traffic/promote', input.serverName, error));
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        serverName: input.serverName,
+                                        trafficOp: 'promote',
+                                        result: promoteResult ?? null
+                                    },
+                                    message: `Promoted canary version to full release for service '${input.serverName}' (100% traffic). This is irreversible.`
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                // rollback
+                let rollbackResult;
+                try {
+                    rollbackResult = await cloudrunService.rollback(input.serverName);
+                }
+                catch (error) {
+                    throw new Error(buildManageCloudRunErrorMessage('traffic/rollback', input.serverName, error));
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                data: {
+                                    serverName: input.serverName,
+                                    trafficOp: 'rollback',
+                                    result: rollbackResult ?? null
+                                },
+                                message: `Rolled back service '${input.serverName}' to the previous stable version.`
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
             case 'createAgent': {
                 if (!targetPath) {
                     throw new Error("targetPath is required for createAgent operation");
@@ -10719,14 +11953,30 @@ for await (let x of res.textStream) {
                     deployParams.serverConfig = effectiveServerConfig;
                 }
                 // Manager SDK create path prefers top-level vpcInfo (CreateCloudRunServer.VpcInfo).
-                // Map serverConfig.VpcConf → vpcInfo so first-time create actually binds VPC.
+                // Prefer serverConfig.VpcConf; if missing, auto-fill from env DescribeEnvBaseInfo
+                // (envs opened with vpcId/subnetIds already carry VpcId/SubNetIds).
                 const vpcConf = effectiveServerConfig?.VpcConf;
-                if (vpcConf?.VpcId?.trim() && vpcConf?.SubnetId?.trim()) {
-                    deployParams.vpcInfo = {
-                        VpcId: vpcConf.VpcId.trim(),
-                        CreateType: 2,
-                        SubnetIds: [vpcConf.SubnetId.trim()],
-                    };
+                let envBaseInfoForVpc = null;
+                const explicitVpcId = vpcConf?.VpcId?.trim() ?? "";
+                const explicitSubnetId = vpcConf?.SubnetId?.trim() ?? "";
+                if (!explicitVpcId || !explicitSubnetId) {
+                    try {
+                        const envIdForVpc = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                        const envStatusForVpc = await describeCloudRunEnvStatus(manager, envIdForVpc);
+                        if (envStatusForVpc.isExist) {
+                            envBaseInfoForVpc = envStatusForVpc.baseInfo;
+                        }
+                    }
+                    catch {
+                        // Best-effort: deploy may still succeed without vpcInfo when the platform creates the network.
+                    }
+                }
+                const resolvedVpcInfo = resolveCloudRunDeployVpcInfo({
+                    vpcConf,
+                    envBaseInfo: envBaseInfoForVpc,
+                });
+                if (resolvedVpcInfo) {
+                    deployParams.vpcInfo = resolvedVpcInfo;
                 }
                 let result;
                 try {
@@ -10737,6 +11987,18 @@ for await (let x of res.textStream) {
                 }
                 // Generate cloudbaserc.json configuration file (source-build only; image deploy has no local project dir)
                 const currentEnvId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                // Lightweight wait for task / BuildId (source) or RunId (image) registration.
+                // Does not wait for full build/deploy completion.
+                const deployType = input.imageUrl
+                    ? "image"
+                    : "source";
+                const registration = await waitForCloudRunDeployRegistration({
+                    manager,
+                    cloudrunService,
+                    envId: currentEnvId,
+                    serverName: input.serverName,
+                    mode: deployType,
+                });
                 let cloudbasercGenerated = false;
                 if (targetPath) {
                     const cloudbasercPath = path_1.default.join(targetPath, 'cloudbaserc.json');
@@ -10812,6 +12074,24 @@ for await (let x of res.textStream) {
                 const warningSuffix = dbNetworkRisk
                     ? ` Warning: ${dbNetworkRisk.message} Set serverConfig.VpcConf before relying on DB connectivity.`
                     : "";
+                const progressHint = buildCloudRunDeployProgressHint({
+                    deployType,
+                    serverName: input.serverName,
+                    buildId: registration.buildId,
+                    runId: registration.runId,
+                    registered: registration.registered,
+                    timedOut: registration.timedOut,
+                    waitMs: registration.waitMs,
+                    consoleUrl,
+                    taskId: registration.taskId,
+                });
+                const nextStep = buildCloudRunDeployNextStep({
+                    deployType,
+                    serverName: input.serverName,
+                    buildId: registration.buildId,
+                    runId: registration.runId,
+                    registered: registration.registered,
+                });
                 return {
                     content: [
                         {
@@ -10821,12 +12101,30 @@ for await (let x of res.textStream) {
                                 data: {
                                     serviceName: input.serverName,
                                     status: 'deploying',
-                                    deployType: input.imageUrl ? 'image' : 'source',
+                                    deployType,
                                     ...(targetPath ? { deployPath: targetPath } : {}),
                                     ...(input.imageUrl ? { imageUrl: input.imageUrl } : {}),
                                     serverType: serverType,
                                     cloudbasercGenerated,
                                     consoleUrl,
+                                    ...(isValidCloudRunBuildId(registration.buildId)
+                                        ? { buildId: registration.buildId }
+                                        : {}),
+                                    ...(isValidCloudRunRunId(registration.runId)
+                                        ? { runId: registration.runId }
+                                        : {}),
+                                    ...(typeof registration.taskId === "number"
+                                        ? { taskId: registration.taskId }
+                                        : {}),
+                                    registration: {
+                                        registered: registration.registered,
+                                        timedOut: registration.timedOut,
+                                        waitMs: registration.waitMs,
+                                        ...(registration.taskStatus
+                                            ? { taskStatus: registration.taskStatus }
+                                            : {}),
+                                    },
+                                    next_step: nextStep,
                                     ...(existingService
                                         ? {
                                             configMerge: {
@@ -10847,8 +12145,10 @@ for await (let x of res.textStream) {
                                         ? { accessUrlSource: preferredAccessSource }
                                         : {}),
                                     ...(warnings.length > 0 ? { warnings } : {}),
+                                    // Keep raw SDK result for debugging without implying build finished.
+                                    ...(result != null ? { deployAccepted: true } : {}),
                                 },
-                                message: `Triggered deployment for ${serverType} service '${input.serverName}' ${input.imageUrl ? `from image ${input.imageUrl}` : `from ${targetPath}`}. You can follow the progress in ${consoleUrl}.${warningSuffix}`
+                                message: `Triggered deployment for ${serverType} service '${input.serverName}' ${input.imageUrl ? `from image ${input.imageUrl}` : `from ${targetPath}`}. Deployment is registering/${deployType === "image" ? "starting" : "building"} (status=deploying); this call does not wait for full completion.${progressHint}${warningSuffix}`
                             }, null, 2)
                         }
                     ]
@@ -11983,7 +13283,7 @@ class TelemetryReporter {
         const arch = os_1.default.arch(); // 系统架构
         // Build-time injected version; guard for vitest / non-webpack runtimes.
         const mcpVersion = process.env.npm_package_version ||
-            ( true ? "2.27.0" : 0);
+            ( true ? "2.28.1" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -12333,6 +13633,8 @@ const cloud_mode_js_1 = __webpack_require__(9684);
 const gateway_access_urls_js_1 = __webpack_require__(2435);
 const json_content_js_1 = __webpack_require__(4365);
 const logger_js_1 = __webpack_require__(3039);
+const tool_result_js_1 = __webpack_require__(9835);
+const function_updating_js_1 = __webpack_require__(3656);
 const fs_1 = __webpack_require__(4421);
 const path_1 = __importDefault(__webpack_require__(2521));
 exports.SUPPORTED_RUNTIMES = {
@@ -12653,6 +13955,10 @@ function buildFunctionOperationErrorMessage(operation, functionName, functionRoo
         suggestions.push("如果 HTTP 函数只使用原生 Node.js API 且没有第三方依赖，可以保留函数目录中的 index.js 和 scf_bootstrap，工具会跳过依赖安装。");
         suggestions.push("如果你确实依赖 npm 包，请在函数目录下补充 package.json 后重试。");
     }
+    if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+        suggestions.push(`函数当前处于 Updating/非 Active，不要立即重试 ${operation}。` +
+            `请等待约 10 秒，或先 queryFunctions(action="getFunctionDetail") 确认 Status 为 Active 后再重试。`);
+    }
     // Handle invalid parameter value errors from CloudBase API
     if (/invalid parameter value/i.test(baseMessage)) {
         suggestions.push("检测到参数值格式错误。请重点检查以下配置项：");
@@ -12680,6 +13986,24 @@ function wrapFunctionOperationError(operation, functionName, functionRootPath, e
     }
     return wrappedError;
 }
+async function waitForManageWriteOrGuide(action, functionName, getFunctionDetail, initialDetail) {
+    const waitResult = await (0, function_updating_js_1.waitUntilFunctionActive)(async () => {
+        const latest = await getFunctionDetail(functionName);
+        return typeof latest?.Status === "string" ? latest.Status : undefined;
+    }, {
+        initialStatus: typeof initialDetail?.Status === "string" ? initialDetail.Status : undefined,
+    });
+    if (waitResult.ready) {
+        return undefined;
+    }
+    return (0, function_updating_js_1.buildFunctionUpdatingPayload)({
+        action,
+        functionName,
+        status: waitResult.status,
+        waitedAttempts: waitResult.attempts,
+        timedOut: waitResult.timedOut,
+    });
+}
 function registerFunctionTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const deployOverrides = server.pluginOptions?.functions;
@@ -12702,6 +14026,15 @@ function registerFunctionTools(server) {
             return (0, json_content_js_1.jsonContent)(await handler());
         }
         catch (error) {
+            if ((0, tool_result_js_1.isToolPayloadError)(error)) {
+                return (0, json_content_js_1.jsonContent)(error.payload);
+            }
+            if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+                return (0, json_content_js_1.jsonContent)((0, function_updating_js_1.buildFunctionUpdatingPayload)({
+                    action: "manageFunctions",
+                    rawMessage: (0, function_updating_js_1.getErrorMessage)(error),
+                }));
+            }
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
         }
     };
@@ -13256,6 +14589,24 @@ function registerFunctionTools(server) {
                     throw new Error("updateFunctionCode 操作时，functionName 参数是必需的");
                 }
                 const cloudbase = await getManager();
+                if (typeof cloudbase.functions.getFunctionDetail === "function") {
+                    try {
+                        const currentDetail = await cloudbase.functions.getFunctionDetail(input.functionName);
+                        const waited = await waitForManageWriteOrGuide("updateFunctionCode", input.functionName, (name) => cloudbase.functions.getFunctionDetail(name), currentDetail);
+                        if (waited) {
+                            return waited;
+                        }
+                    }
+                    catch (error) {
+                        if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+                            return (0, function_updating_js_1.buildFunctionUpdatingPayload)({
+                                action: "updateFunctionCode",
+                                functionName: input.functionName,
+                                rawMessage: (0, function_updating_js_1.getErrorMessage)(error),
+                            });
+                        }
+                    }
+                }
                 // 镜像更新分支：后续迭代只需用新镜像 tag 更新函数。
                 const updateImageConfig = input.imageConfig ??
                     input.func?.imageConfig;
@@ -13274,6 +14625,13 @@ function registerFunctionTools(server) {
                         });
                     }
                     catch (error) {
+                        if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+                            return (0, function_updating_js_1.buildFunctionUpdatingPayload)({
+                                action: "updateFunctionCode",
+                                functionName: input.functionName,
+                                rawMessage: (0, function_updating_js_1.getErrorMessage)(error),
+                            });
+                        }
                         throw wrapFunctionOperationError("updateFunctionCode", input.functionName, undefined, error);
                     }
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, imageResult);
@@ -13331,6 +14689,13 @@ function registerFunctionTools(server) {
                     result = await cloudbase.functions.updateFunctionCode(updateParams);
                 }
                 catch (error) {
+                    if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+                        return (0, function_updating_js_1.buildFunctionUpdatingPayload)({
+                            action: "updateFunctionCode",
+                            functionName: input.functionName,
+                            rawMessage: (0, function_updating_js_1.getErrorMessage)(error),
+                        });
+                    }
                     throw wrapFunctionOperationError("updateFunctionCode", input.functionName, processedRootPath, error);
                 }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -13375,6 +14740,10 @@ function registerFunctionTools(server) {
                 if (!functionDetail) {
                     throw new Error(`函数 ${input.functionName} 不存在或无法获取详情`);
                 }
+                const configBusy = await waitForManageWriteOrGuide("updateFunctionConfig", input.functionName, (name) => cloudbase.functions.getFunctionDetail(name), functionDetail);
+                if (configBusy) {
+                    return configBusy;
+                }
                 const currentVpc = typeof functionDetail.VpcConfig === "object" &&
                     functionDetail.VpcConfig !== null &&
                     functionDetail.VpcConfig.SubnetId &&
@@ -13384,27 +14753,39 @@ function registerFunctionTools(server) {
                         vpcId: functionDetail.VpcConfig.VpcId,
                     }
                     : undefined;
-                const result = await cloudbase.functions.updateFunctionConfig({
-                    name: input.functionName,
-                    envVariables: Object.assign({}, (functionDetail.Environment?.Variables || []).reduce((acc, curr) => {
-                        acc[curr.Key] = curr.Value;
-                        return acc;
-                    }, {}), input.envVariables ?? {}),
-                    timeout: input.timeout ?? functionDetail.Timeout,
-                    vpc: Object.assign({}, currentVpc, input.vpc ?? {}),
-                });
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action: input.action,
-                    functionName: input.functionName,
-                    raw: result,
-                }, `已更新函数 ${input.functionName} 的配置`, [
-                    {
-                        tool: "queryFunctions",
-                        action: "getFunctionDetail",
-                        reason: "确认配置变更结果",
-                    },
-                ]);
+                try {
+                    const result = await cloudbase.functions.updateFunctionConfig({
+                        name: input.functionName,
+                        envVariables: Object.assign({}, (functionDetail.Environment?.Variables || []).reduce((acc, curr) => {
+                            acc[curr.Key] = curr.Value;
+                            return acc;
+                        }, {}), input.envVariables ?? {}),
+                        timeout: input.timeout ?? functionDetail.Timeout,
+                        vpc: Object.assign({}, currentVpc, input.vpc ?? {}),
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    return buildEnvelope({
+                        action: input.action,
+                        functionName: input.functionName,
+                        raw: result,
+                    }, `已更新函数 ${input.functionName} 的配置`, [
+                        {
+                            tool: "queryFunctions",
+                            action: "getFunctionDetail",
+                            reason: "确认配置变更结果",
+                        },
+                    ]);
+                }
+                catch (error) {
+                    if ((0, function_updating_js_1.isFunctionUpdatingError)(error)) {
+                        return (0, function_updating_js_1.buildFunctionUpdatingPayload)({
+                            action: "updateFunctionConfig",
+                            functionName: input.functionName,
+                            rawMessage: (0, function_updating_js_1.getErrorMessage)(error),
+                        });
+                    }
+                    throw error;
+                }
             }
             case "invokeFunction": {
                 if (!input.functionName) {
@@ -13934,6 +15315,98 @@ async function resolvePgDbContext(cloudBaseOptions, args) {
         role: args?.role ?? "cloudbase_admin",
     };
 }
+/** Default / recommended roles for CloudBase PG ExecutePGSql.Role */
+const PG_DEFAULT_ROLE = "cloudbase_admin";
+const PG_RECOMMENDED_ROLES = [
+    "cloudbase_admin",
+    "anon",
+    "authenticated",
+    "service_role",
+];
+/**
+ * Roles that look like login/instance principals and routinely fail SET ROLE
+ * in beacon data (e.g. postgres, postgres_pgdb_<id>). Reject before the API call.
+ */
+function isLikelyInvalidPgExecuteRole(role) {
+    const normalized = role.trim();
+    if (!normalized) {
+        return true;
+    }
+    if (normalized === "postgres") {
+        return true;
+    }
+    // Instance-derived login principals, not valid ExecutePGSql Role targets
+    if (/^postgres_pgdb_[a-z0-9]+$/i.test(normalized)) {
+        return true;
+    }
+    // AI-invented concatenations such as cloudbase_admin_pgdb_xxx_pgdb_xxx
+    if (/_pgdb_[a-z0-9]+(_pgdb_[a-z0-9]+)?$/i.test(normalized) &&
+        !PG_RECOMMENDED_ROLES.includes(normalized)) {
+        return true;
+    }
+    return false;
+}
+function extractPgRoleNameFromError(message) {
+    const missing = message.match(/role\s+"([^"]+)"\s+does\s+not\s+exist/i);
+    if (missing?.[1]) {
+        return missing[1];
+    }
+    const setRole = message.match(/set\s+role\s+([^\s:]+)/i);
+    if (setRole?.[1]) {
+        return setRole[1].replace(/^"|"$/g, "");
+    }
+    const denied = message.match(/permission\s+denied\s+to\s+set\s+role\s+"([^"]+)"/i);
+    if (denied?.[1]) {
+        return denied[1];
+    }
+    return null;
+}
+function isPgRoleExecutionError(message) {
+    const lower = message.toLowerCase();
+    return ((lower.includes("set role") &&
+        (lower.includes("does not exist") ||
+            lower.includes("permission denied"))) ||
+        /role\s+"[^"]+"\s+does\s+not\s+exist/i.test(message) ||
+        /permission\s+denied\s+to\s+set\s+role/i.test(message));
+}
+function buildPgRoleGuidanceMessage(attemptedRole) {
+    const recommended = PG_RECOMMENDED_ROLES.join(", ");
+    return (`PostgreSQL role "${attemptedRole}" cannot be used with ExecutePGSql (SET ROLE failed or role does not exist). ` +
+        `Do not invent roles like postgres / postgres_pgdb_* from env or instance names. ` +
+        `Omit role (defaults to ${PG_DEFAULT_ROLE}) or pass one of: ${recommended}. ` +
+        `To list roles that exist in this database, retry with role=${PG_DEFAULT_ROLE} and SQL: SELECT rolname FROM pg_roles ORDER BY rolname;`);
+}
+function buildPgRoleErrorPayload(attemptedRole, rawMessage) {
+    return {
+        success: false,
+        errorCode: "PG_ROLE_NOT_AVAILABLE",
+        message: buildPgRoleGuidanceMessage(attemptedRole),
+        data: {
+            attemptedRole,
+            defaultRole: PG_DEFAULT_ROLE,
+            recommendedRoles: [...PG_RECOMMENDED_ROLES],
+            listRolesSql: "SELECT rolname FROM pg_roles ORDER BY rolname;",
+            ...(rawMessage ? { rawError: rawMessage.slice(0, 500) } : {}),
+        },
+        nextActions: [
+            buildNextAction(MANAGE_PG_DATABASE, "execute", `Retry without a custom role (defaults to ${PG_DEFAULT_ROLE}), or pass role=${PG_DEFAULT_ROLE} explicitly.`, {
+                action: "execute",
+                role: PG_DEFAULT_ROLE,
+                sql: "SELECT rolname FROM pg_roles ORDER BY rolname;",
+                confirm: true,
+            }),
+            buildNextAction(QUERY_PG_DATABASE, "context", "Inspect the auto-derived PG context (includes default role) before retrying.", { action: "context" }),
+        ],
+    };
+}
+function tryBuildPgRoleErrorPayload(error, fallbackRole) {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    if (!isPgRoleExecutionError(rawMessage)) {
+        return null;
+    }
+    const attemptedRole = extractPgRoleNameFromError(rawMessage) ?? fallbackRole;
+    return buildPgRoleErrorPayload(attemptedRole, rawMessage);
+}
 function normalizeLimit(limit, fallback = 20, max = 200) {
     if (!Number.isFinite(limit)) {
         return fallback;
@@ -15158,7 +16631,26 @@ async function handleReadOnlySql(args, context, deps) {
     }
     const limit = normalizeLimit(args.limit);
     const limitedSql = buildLimitedReadOnlySql(args.sql, limit);
-    const result = await withPgClient(context, deps, (client) => client.query(limitedSql));
+    let result;
+    try {
+        result = await withPgClient(context, deps, (client) => client.query(limitedSql));
+    }
+    catch (error) {
+        const rolePayload = tryBuildPgRoleErrorPayload(error, context.role);
+        if (rolePayload) {
+            return buildPgToolResult(rolePayload);
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        return buildPgToolResult({
+            success: false,
+            errorCode: "PG_SQL_EXEC_FAILED",
+            message: `PostgreSQL read-only SQL execution failed: ${reason}`,
+            data: {
+                role: context.role,
+                sqlPreview: limitedSql.trim().slice(0, 500),
+            },
+        });
+    }
     const summary = summarizeQueryResult(result, limit);
     return buildPgToolResult({
         success: true,
@@ -15213,6 +16705,9 @@ async function handleExecuteSql(args, context, deps) {
             ],
         });
     }
+    if (args.role !== undefined && isLikelyInvalidPgExecuteRole(args.role)) {
+        return buildPgToolResult(buildPgRoleErrorPayload(args.role.trim() || "(empty)"));
+    }
     if (!classification.readOnly && !args.confirm) {
         return buildPgToolResult({
             success: false,
@@ -15232,7 +16727,26 @@ async function handleExecuteSql(args, context, deps) {
             ],
         });
     }
-    const result = await withPgClient(context, deps, (client) => client.query(args.sql));
+    let result;
+    try {
+        result = await withPgClient(context, deps, (client) => client.query(args.sql));
+    }
+    catch (error) {
+        const rolePayload = tryBuildPgRoleErrorPayload(error, context.role);
+        if (rolePayload) {
+            return buildPgToolResult(rolePayload);
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        return buildPgToolResult({
+            success: false,
+            errorCode: "PG_SQL_EXEC_FAILED",
+            message: `PostgreSQL SQL execution failed: ${reason}`,
+            data: {
+                role: context.role,
+                sqlPreview: args.sql.trim().slice(0, 500),
+            },
+        });
+    }
     const targetTable = parseTargetTableFromSql(args.sql, context.defaultSchema);
     return buildPgToolResult({
         success: true,
@@ -16125,7 +17639,9 @@ function registerPGDatabaseTools(server, providedDeps) {
             role: zod_1.z
                 .string()
                 .optional()
-                .describe("可选的 PostgreSQL role，会传给 Manager SDK executePGSql；例如需要管理策略时可传 postgres。"),
+                .describe(`可选的 PostgreSQL role，传给 Manager SDK executePGSql 的 Role（平台会 SET ROLE）。默认 ${PG_DEFAULT_ROLE}。` +
+                `推荐取值：${PG_RECOMMENDED_ROLES.join(" / ")}。` +
+                `不要传 postgres、postgres_pgdb_* 或从环境名臆造的角色；不确定时省略本字段，或先用 ${PG_DEFAULT_ROLE} 执行 SELECT rolname FROM pg_roles。`),
             objectName: zod_1.z
                 .string()
                 .optional()
@@ -16229,6 +17745,10 @@ function registerPGDatabaseTools(server, providedDeps) {
                         return handleExecuteSql(args, context, deps);
                     }
                 }
+                // Reject known-bad Role values before readiness probe / ExecutePGSql SET ROLE.
+                if (args.role !== undefined && isLikelyInvalidPgExecuteRole(args.role)) {
+                    return buildPgToolResult(buildPgRoleErrorPayload(args.role.trim() || "(empty)"));
+                }
                 try {
                     await ensurePgReadyOnce(cbOpts, deps);
                 }
@@ -16285,6 +17805,7 @@ function registerPGDatabaseTools(server, providedDeps) {
 
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.validateUserRegoContent = validateUserRegoContent;
 exports.registerPermissionTools = registerPermissionTools;
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
@@ -16296,6 +17817,9 @@ const QUERY_PERMISSION_ACTIONS = [
     "getRole",
     "listUsers",
     "getUser",
+    // Align with CLI `tcb policy list/get` (OPA gateway authz)
+    "listPolicy",
+    "getPolicy",
 ];
 const MANAGE_PERMISSION_ACTIONS = [
     "updateResourcePermission",
@@ -16309,7 +17833,14 @@ const MANAGE_PERMISSION_ACTIONS = [
     "createUser",
     "updateUser",
     "deleteUsers",
+    // Align with CLI `tcb policy set` (OPA Rego; disables legacy gateway auth)
+    "setPolicy",
 ];
+/** Keys accepted by Manager SDK describeEnvAuthzConfig / modifyEnvAuthzConfig. */
+const AUTHZ_USER_REGO_KEY = "authz.user.rego";
+const AUTHZ_PLATFORM_EXTENSION_REGO_KEY = "authz.platform.extension.rego";
+/** CLI `tcb policy list --resource-type` only documents `policy`. */
+const POLICY_LIST_RESOURCE_TYPES = ["policy"];
 function buildWriteVerificationHint(resourceId) {
     return `对于 ${resourceId} 这类有后端权限控制的集合，前端调用 .doc(id).update() / .doc(id).remove() 后，不能只看是否没有抛异常。请显式检查返回结果中的 updated / deleted 是否大于 0；如果 result.code、result.message 存在，或 updated / deleted 为 0，要把它当作真实失败并向上抛错。`;
 }
@@ -16348,10 +17879,32 @@ function isPostgresqlPermissionApiUnsupported(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /does not support PostgreSQL type environments/i.test(message);
 }
-const AUTHZ_USER_REGO_KEY = "authz.user.rego";
 function looksLikeUserRego(value) {
     return /^\s*package\s+authz\.user\b/m.test(value);
 }
+/**
+ * Validate user Rego before setPolicy / modifyEnvAuthzConfig.
+ * Aligns with CLI docs (must start with `package authz.user`) and CLI non-empty check.
+ * Does not run a full OPA compiler; backend still owns deep syntax validation.
+ */
+function validateUserRegoContent(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("action=setPolicy 需要非空 regoContent（对齐 CLI `tcb policy set <regoContent>`）。");
+    }
+    const trimmed = value.trim();
+    if (!looksLikeUserRego(trimmed)) {
+        throw new Error("Rego 策略必须以 `package authz.user` 开头（对齐 https://docs.cloudbase.net/cli-v1/policy/management ）。");
+    }
+    const open = (trimmed.match(/\{/g) || []).length;
+    const close = (trimmed.match(/\}/g) || []).length;
+    if (open !== close) {
+        throw new Error(`Rego 策略花括号不匹配（{=${open}, }=${close}）。请检查语法后再调用 setPolicy。`);
+    }
+    return trimmed;
+}
+function resolveAuthzConfigKey(extension) {
+    return extension ? AUTHZ_PLATFORM_EXTENSION_REGO_KEY : AUTHZ_USER_REGO_KEY;
+}
 /** Detect legacy function securityRule shapes that mean "public invoke". */
 function isPublicFunctionInvokeRule(securityRule) {
     if (!securityRule || securityRule.trim() === "") {
@@ -16423,29 +17976,38 @@ function resolveFunctionAuthzRegoInput(securityRule, resourceId) {
         `2) permission="CUSTOM" with securityRule='{"invoke":true}' to generate a public-functions allow policy.\n` +
         `See https://docs.cloudbase.net/cli-v1/policy/management`);
 }
-async function describeEnvAuthzUserRego(cloudbase) {
+async function describeEnvAuthzConfigByKey(cloudbase, key = AUTHZ_USER_REGO_KEY) {
     if (!cloudbase?.permission?.describeEnvAuthzConfig) {
         throw new Error("Current @cloudbase/manager-node does not expose permission.describeEnvAuthzConfig. Upgrade manager-node (>= 5.5.5) to align with CLI tcb policy get.");
     }
-    const result = await cloudbase.permission.describeEnvAuthzConfig({
-        key: AUTHZ_USER_REGO_KEY,
-    });
+    const result = await cloudbase.permission.describeEnvAuthzConfig({ key });
     const value = typeof result?.Item?.Value === "string"
         ? result.Item.Value
         : typeof result?.Value === "string"
             ? result.Value
             : "";
-    return { value, raw: result };
+    return { key, value, raw: result };
+}
+async function describeEnvAuthzUserRego(cloudbase) {
+    const result = await describeEnvAuthzConfigByKey(cloudbase, AUTHZ_USER_REGO_KEY);
+    return { value: result.value, raw: result.raw };
 }
 async function modifyEnvAuthzUserRego(cloudbase, value) {
     if (!cloudbase?.permission?.modifyEnvAuthzConfig) {
         throw new Error("Current @cloudbase/manager-node does not expose permission.modifyEnvAuthzConfig. Upgrade manager-node (>= 5.5.5) to align with CLI tcb policy set.");
     }
+    const validated = validateUserRegoContent(value);
     return cloudbase.permission.modifyEnvAuthzConfig({
         key: AUTHZ_USER_REGO_KEY,
-        value,
+        value: validated,
     });
 }
+async function describeResourcePolicyListAligned(cloudbase, policyResourceType) {
+    if (!cloudbase?.permission?.describeResourcePolicyList) {
+        throw new Error("Current @cloudbase/manager-node does not expose permission.describeResourcePolicyList. Upgrade manager-node (>= 5.5.5) to align with CLI tcb policy list.");
+    }
+    return cloudbase.permission.describeResourcePolicyList(policyResourceType ? { resourceType: policyResourceType } : undefined);
+}
 async function describeResourcePermissionWithFunctionPgFallback(options) {
     const { cloudbase, envId, resourceType, resources } = options;
     try {
@@ -16679,7 +18241,7 @@ function registerPermissionTools(server) {
     };
     server.registerTool?.("queryPermissions", {
         title: "查询 CloudBase 权限与用户配置",
-        description: "查询 CloudBase 权限与用户配置，支持查询资源权限（数据库/云函数/存储桶等）、角色列表/详情、应用用户列表/详情。\n\n示例：\n- 查询存储桶权限：`action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`。`resourceType=\"noSqlDatabase\"` 查询的是 CloudBase NoSQL 集合规则，与 CloudBase PostgreSQL（PG）表的行级安全（RLS）是两套独立机制——同一个 PG 环境里 NoSQL 集合若仍在使用，对那些集合查询本工具结果**仍然有效**。要查 PG 表 RLS，请改用 `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")`。本工具不涉及 MySQL 权限。\n\n⚠️ PostgreSQL 环境：平台 `DescribeResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `describeEnvAuthzConfig`（与 CLI `tcb policy get` 一致，读取 `authz.user.rego`）。",
+        description: "查询 CloudBase 权限与用户配置，支持查询资源权限（数据库/云函数/存储桶等）、角色列表/详情、应用用户列表/详情，以及网关 OPA 授权策略（对齐 CLI `tcb policy list/get`）。\n\n示例：\n- 查询存储桶权限：`action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`\n- 列出旧网关策略：`action=\"listPolicy\"`（PG / OPA 引擎环境返回空列表，与 CLI 一致）\n- 读取用户 Rego：`action=\"getPolicy\"`；平台扩展策略：`action=\"getPolicy\", extension=true`\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`。`resourceType=\"noSqlDatabase\"` 查询的是 CloudBase NoSQL 集合规则，与 CloudBase PostgreSQL（PG）表的行级安全（RLS）是两套独立机制——同一个 PG 环境里 NoSQL 集合若仍在使用，对那些集合查询本工具结果**仍然有效**。要查 PG 表 RLS，请改用 `queryPgDatabase(action=\"sql\", sql=\"SELECT * FROM pg_policies WHERE tablename=...\")`。本工具不涉及 MySQL 权限。\n\n⚠️ PostgreSQL 环境：平台 `DescribeResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `describeEnvAuthzConfig`（与 CLI `tcb policy get` 一致，读取 `authz.user.rego`）。显式 OPA 策略请用 `listPolicy` / `getPolicy`。",
         inputSchema: {
             action: zod_1.z.enum(QUERY_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -16694,13 +18256,21 @@ function registerPermissionTools(server) {
             username: zod_1.z.string().optional(),
             pageNo: zod_1.z.number().optional(),
             pageSize: zod_1.z.number().optional(),
+            extension: zod_1.z
+                .boolean()
+                .optional()
+                .describe("仅 action=getPolicy。true=读取平台为该环境单独配置的策略（authz.platform.extension.rego），默认 false=用户策略（authz.user.rego），对齐 CLI `tcb policy get --extension`。"),
+            policyResourceType: zod_1.z
+                .enum(POLICY_LIST_RESOURCE_TYPES)
+                .optional()
+                .describe("仅 action=listPolicy。按资源类型过滤，当前仅支持 `policy`，对齐 CLI `tcb policy list --resource-type policy`。"),
         },
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
             category: "permissions",
         },
-    }, async ({ action, resourceType, resourceId, resourceIds, roleId, roleIdentity, roleName, uid, username, pageNo, pageSize, }) => withEnvelope(async () => {
+    }, async ({ action, resourceType, resourceId, resourceIds, roleId, roleIdentity, roleName, uid, username, pageNo, pageSize, extension, policyResourceType, }) => withEnvelope(async () => {
         const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
         const cloudbase = await getManager();
         switch (action) {
@@ -16846,11 +18416,43 @@ function registerPermissionTools(server) {
                     raw: result,
                 }, "应用用户详情查询成功");
             }
+            case "listPolicy": {
+                const result = await describeResourcePolicyListAligned(cloudbase, policyResourceType);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const data = result
+                    ?.Data;
+                const policyList = data?.PolicyList ?? [];
+                const total = data?.Total ?? policyList.length;
+                return buildEnvelope({
+                    action,
+                    envId,
+                    policyResourceType: policyResourceType ?? null,
+                    policies: policyList,
+                    total,
+                    note: "PG 环境与 authz_engine=opa 的环境会返回空列表（与 CLI `tcb policy list` / SDK describeResourcePolicyList 一致）。读取用户 Rego 请用 action=getPolicy。",
+                    raw: result,
+                }, "网关授权策略列表查询成功");
+            }
+            case "getPolicy": {
+                const key = resolveAuthzConfigKey(extension);
+                const result = await describeEnvAuthzConfigByKey(cloudbase, key);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result.raw);
+                return buildEnvelope({
+                    action,
+                    envId,
+                    key: result.key,
+                    extension: Boolean(extension),
+                    rego: result.value,
+                    raw: result.raw,
+                }, extension
+                    ? "平台扩展 OPA 策略查询成功（authz.platform.extension.rego）"
+                    : "用户 OPA 策略查询成功（authz.user.rego）");
+            }
         }
     }));
     server.registerTool?.("managePermissions", {
         title: "管理 CloudBase 权限与用户配置",
-        description: "管理 CloudBase 权限与用户配置，支持修改资源权限（数据库/云函数/存储桶等）、角色管理、成员与策略增删、应用用户 CRUD。\n\n示例：\n- 设置存储桶为私有：`action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- 创建角色：`action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- 放开云函数匿名/未登录访问（PG 会走 OPA，对齐 CLI `tcb policy set`）：`action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n\n注意：`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。直接在浏览器里用 `auth.signUp` 创建用户名密码用户取决于 SDK/provider 支持，使用前必须验证；不支持时应走后端或管理端边界，不能在浏览器暴露密钥。`securityRule` 的详细语义取决于 `resourceType`：`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则；配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`：\n- `resourceType=\"noSqlDatabase\"` 仅作用于 CloudBase NoSQL 文档数据库的集合；CloudBase PostgreSQL（PG）表的行级权限**不**受它控制——PG 表请改用 RLS：`managePgDatabase(action=\"execute\", confirm=true)` 跑 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` 与 `CREATE POLICY ...`。同一个 PG 环境里如果还有 NoSQL 集合在用，对那些**集合**继续使用 `noSqlDatabase` 规则是正确的——不是\"PG 环境就禁用本工具\"。\n- `resourceType=\"storage\"` 控制的是 NoSQL/COS 存储桶 ACL；PG 的 `pgstore` bucket 不在此 `resourceType` 覆盖范围内。\n- 本工具不涉及 MySQL；MySQL 数据库权限请走 MySQL 自身的 GRANT/REVOKE 语句（通过 `manageMysqlDatabase`）。\n\n⚠️ PostgreSQL 环境：平台 `ModifyResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `modifyEnvAuthzConfig`（与 CLI `tcb policy set` 一致，写入 `authz.user.rego`）。`securityRule` 可传完整 Rego（`package authz.user`）或 `'{\"invoke\":true}'`（自动生成放通 anonymous/unauthenticated 调 functions 的策略）。设置 Rego 后旧网关鉴权会失效，行为与 CLI 相同。",
+        description: "管理 CloudBase 权限与用户配置，支持修改资源权限（数据库/云函数/存储桶等）、角色管理、成员与策略增删、应用用户 CRUD，以及设置网关 OPA Rego 策略（对齐 CLI `tcb policy set`）。\n\n示例：\n- 设置存储桶为私有：`action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- 创建角色：`action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n- 放开云函数匿名/未登录访问（PG 会走 OPA，对齐 CLI `tcb policy set`）：`action=\"updateResourcePermission\", resourceType=\"function\", resourceId=\"myFn\", permission=\"CUSTOM\", securityRule='{\"invoke\":true}'`\n- 直接设置用户 Rego：`action=\"setPolicy\", regoContent=\"package authz.user\\n\\ndefault allow := false\\n\", confirm=true`（⚠️ 立即禁用旧网关鉴权）\n\n注意：`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。直接在浏览器里用 `auth.signUp` 创建用户名密码用户取决于 SDK/provider 支持，使用前必须验证；不支持时应走后端或管理端边界，不能在浏览器暴露密钥。`securityRule` 的详细语义取决于 `resourceType`：`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则；配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。\n\n📌 跨后端边界提示：调用前先用 `envQuery(action=\"info\", envId=...)` 看 `EnvInfo.RuntimeBackends`：\n- `resourceType=\"noSqlDatabase\"` 仅作用于 CloudBase NoSQL 文档数据库的集合；CloudBase PostgreSQL（PG）表的行级权限**不**受它控制——PG 表请改用 RLS：`managePgDatabase(action=\"execute\", confirm=true)` 跑 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` 与 `CREATE POLICY ...`。同一个 PG 环境里如果还有 NoSQL 集合在用，对那些**集合**继续使用 `noSqlDatabase` 规则是正确的——不是\"PG 环境就禁用本工具\"。\n- `resourceType=\"storage\"` 控制的是 NoSQL/COS 存储桶 ACL；PG 的 `pgstore` bucket 不在此 `resourceType` 覆盖范围内。\n- 本工具不涉及 MySQL；MySQL 数据库权限请走 MySQL 自身的 GRANT/REVOKE 语句（通过 `manageMysqlDatabase`）。\n\n⚠️ PostgreSQL 环境：平台 `ModifyResourcePermission` 对 PG 环境会直接拒绝。当 `resourceType=\"function\"` 时，本工具会自动回退到 Manager SDK `modifyEnvAuthzConfig`（与 CLI `tcb policy set` 一致，写入 `authz.user.rego`）。`securityRule` 可传完整 Rego（`package authz.user`）或 `'{\"invoke\":true}'`（自动生成放通 anonymous/unauthenticated 调 functions 的策略）。设置 Rego 后旧网关鉴权会失效，行为与 CLI 相同。显式 OPA 策略请优先用 `action=\"setPolicy\"`。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -16881,6 +18483,14 @@ function registerPermissionTools(server) {
             username: zod_1.z.string().optional(),
             password: zod_1.z.string().optional(),
             userStatus: zod_1.z.enum(["ACTIVE", "BLOCKED"]).optional(),
+            regoContent: zod_1.z
+                .string()
+                .optional()
+                .describe("仅 action=setPolicy。用户 OPA Rego 全文，必须以 `package authz.user` 开头，对齐 CLI `tcb policy set <regoContent>`。"),
+            confirm: zod_1.z
+                .boolean()
+                .optional()
+                .describe("仅 action=setPolicy。设置 Rego 后会立即禁用旧网关鉴权，必须显式传 confirm=true（对齐 CLI 确认提示）。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -16889,7 +18499,7 @@ function registerPermissionTools(server) {
             openWorldHint: true,
             category: "permissions",
         },
-    }, async ({ action, resourceType, resourceId, permission, securityRule, roleId, roleIds, roleName, roleIdentity, description, memberUids, policies, policyIds, uid, uids, username, password, userStatus, }) => withEnvelope(async () => {
+    }, async ({ action, resourceType, resourceId, permission, securityRule, roleId, roleIds, roleName, roleIdentity, description, memberUids, policies, policyIds, uid, uids, username, password, userStatus, regoContent, confirm, }) => withEnvelope(async () => {
         const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
         const cloudbase = await getManager();
         const normalizedPolicies = normalizeRecordArray(policies, "policies");
@@ -17070,6 +18680,26 @@ function registerPermissionTools(server) {
                     raw: result,
                 }, "应用用户删除成功");
             }
+            case "setPolicy": {
+                if (confirm !== true) {
+                    throw new Error("action=setPolicy 会立即禁用旧网关鉴权（对齐 CLI `tcb policy set`），必须显式传 confirm=true。");
+                }
+                const validated = validateUserRegoContent(regoContent ?? "");
+                const result = await modifyEnvAuthzUserRego(cloudbase, validated);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                return buildEnvelope({
+                    action,
+                    envId,
+                    key: AUTHZ_USER_REGO_KEY,
+                    rego: validated,
+                    sideEffect: "Setting authz.user.rego immediately disables legacy gateway authorization.",
+                    nextSteps: [
+                        'queryPermissions(action="getPolicy")',
+                        'queryPermissions(action="listPolicy")',
+                    ],
+                    raw: result,
+                }, "用户 OPA Rego 策略设置成功（旧网关鉴权已失效）");
+            }
         }
     }));
 }
@@ -17560,7 +19190,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.27.0" : 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.28.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -17916,7 +19546,9 @@ function registerAppTools(server) {
                 buildId,
             });
             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-            const isFailed = result.Status === "FAILED";
+            // Platform may return Failed/failed; normalize before matching.
+            const isFailed = typeof result.Status === "string" &&
+                result.Status.toLowerCase() === "failed";
             const payload = {
                 action,
                 serviceName,