@cloudbase/cloudbase-mcp 2.25.4 → 2.25.6

package/dist/index.js

@@ -205,13 +205,13 @@ function buildEnvDomainManagementResult(params) {
             operation: action,
             targetDomains: domains,
             asyncState: "PENDING",
-            message: '安全域名已提交添加请求。该变更通常需要约 10 分钟传播，请继续轮询 queryEnv(action="domains")，直到目标域名状态为 ENABLE。',
+            message: '安全域名已提交添加请求。该变更通常需要数分钟传播（平台侧）；请每 10 秒轮询 queryEnv(action="domains") 直到 Status 为 ENABLE，勿一次 sleep 满 10 分钟。',
             propagation: {
                 requiresPolling: true,
                 pollTool: "queryEnv",
                 pollAction: "domains",
                 pollIntervalSuggestionSeconds: 10,
-                timeoutSuggestionSeconds: 600,
+                timeoutSuggestionSeconds: 300,
                 successCondition: '目标域名出现在 queryEnv(action="domains") 返回中，且 Status 为 ENABLE。',
             },
             next_step: {
@@ -230,13 +230,13 @@ function buildEnvDomainManagementResult(params) {
         operation: action,
         targetDomains: domains,
         asyncState: "PENDING",
-        message: '安全域名已提交删除请求。该变更可能需要数分钟传播，请继续轮询 queryEnv(action="domains")，直到目标域名不再出现。',
+        message: '安全域名已提交删除请求。该变更通常需要数分钟传播；请每 10 秒轮询 queryEnv(action="domains") 直到目标域名不再出现，勿一次 sleep 满数分钟。',
         propagation: {
             requiresPolling: true,
             pollTool: "queryEnv",
             pollAction: "domains",
             pollIntervalSuggestionSeconds: 10,
-            timeoutSuggestionSeconds: 600,
+            timeoutSuggestionSeconds: 300,
             successCondition: '目标域名不再出现在 queryEnv(action="domains") 返回中。',
         },
         next_step: {
@@ -1944,7 +1944,7 @@ function registerEnvTools(server) {
     if (server.ide !== 'wxide') {
         server.registerTool?.("envDomainManagement", {
             title: "CloudBase 环境域名管理（安全域名 / CORS 白名单）",
-            description: "管理 CloudBase 环境的安全域名（安全域名 / CORS 白名单），支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 直接访问 CloudBase 资源时，应先用 queryEnv(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。新增或删除后通常需要继续轮询 queryEnv(action=domains) 确认状态收敛；安全域名一般约 10 分钟生效。⚠️ 重要：此工具仅用于 CORS/请求来源验证，不涉及 SSL 证书。自定义域名公网 HTTPS：先 queryGateway(listCustomDomains)；已有域名则 manageGateway(createRoute) 显式传 domain（无需证书）；仅首次绑定新域名才用 bindCustomDomain（需 certificateId）。",
+            description: "管理 CloudBase 环境的安全域名（安全域名 / CORS 白名单），支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 直接访问 CloudBase 资源时，应先用 queryEnv(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。新增或删除后请每约 10 秒轮询 queryEnv(action=domains) 确认状态收敛，勿一次 sleep 满 10 分钟；多数环境数分钟内可收敛。⚠️ 重要：此工具仅用于 CORS/请求来源验证，不涉及 SSL 证书。自定义域名公网 HTTPS：先 queryGateway(listCustomDomains)；已有域名则 manageGateway(createRoute) 显式传 domain（无需证书）；仅首次绑定新域名才用 bindCustomDomain（需 certificateId）。",
             inputSchema: {
                 action: zod_1.z
                     .enum(["create", "delete"])
@@ -2772,7 +2772,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.4" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.6" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2853,7 +2853,7 @@ function createWrappedHandler(name, handler, server) {
                 requestId: (typeof error === 'object' && error && 'requestId' in error) ? error.requestId : '',
                 ide: server.ide || process.env.INTEGRATION_IDE || ''
             });
-            const mcpVersion =  true ? "2.25.4" : 0;
+            const mcpVersion =  true ? "2.25.6" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -7165,7 +7165,7 @@ const KnowledgeBaseIdMap = {
 const CACHE_BASE_DIR = path.join(os.homedir(), ".cloudbase-mcp");
 const CACHE_META_FILE = path.join(CACHE_BASE_DIR, "cache-meta.json");
 const LOCK_FILE = path.join(CACHE_BASE_DIR, ".download.lock");
-const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 默认 24 小时
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // default 1 hour (was 24h; templates/docs refresh more often)
 // Promise wrapper for lockfile methods
 function acquireLock(lockPath, options) {
     return new Promise((resolve, reject) => {
@@ -7960,7 +7960,11 @@ function registerGatewayTools(server) {
         return result ?? {};
     };
     const buildPrivilegeDescription = (privilege) => {
-        const serviceStatus = privilege.EnableService === true ? "已开启" : "未开启";
+        const serviceStatus = privilege.EnableService === undefined
+            ? "未知"
+            : privilege.EnableService === true
+                ? "已开启"
+                : "未开启";
         const authStatus = privilege.EnableAuth === undefined
             ? "未知"
             : privilege.EnableAuth === true
@@ -8052,7 +8056,7 @@ function registerGatewayTools(server) {
         {
             tool: "queryGateway",
             action: "getRoute",
-            reason: "等待 30 秒到 3 分钟后再确认访问入口是否已生效",
+            reason: "创建后通常数秒到约 30 秒内生效；请立刻轮询 getRoute 或探测 accessUrl，勿盲等 60 秒以上",
         },
         {
             tool: "queryPermissions",
@@ -8200,7 +8204,7 @@ function registerGatewayTools(server) {
                     const privilege = await getGatewayPrivilege();
                     if (privilege.EnableService !== true) {
                         privilegeHint =
-                            "⚠️ HTTP 网关总开关未开启，路由创建成功后访问仍将返回 HTTPSERVICE_NONACTIVATED（403）；请先调用 manageGateway(action=\"enableService\", enable=true) 开启，再等待 30 秒到 3 分钟访问。";
+                            "⚠️ HTTP 网关总开关未开启，路由创建成功后访问仍将返回 HTTPSERVICE_NONACTIVATED（403）；请先调用 manageGateway(action=\"enableService\", enable=true) 开启，再立刻探测 accessUrl（通常数秒到约 30 秒内生效，勿盲等 60 秒以上）。";
                         privilegeNextActions = [
                             {
                                 tool: "manageGateway",
@@ -8236,7 +8240,7 @@ function registerGatewayTools(server) {
                         : payload.resolved.enablePathTransmission === false
                             ? "；路径透传关闭（网关会剥掉触发路径前缀后再转发给后端）"
                             : "；路径透传未显式设置（平台默认 false，会剥掉触发路径前缀）") +
-                    `。注意：路由配置传播通常需要等待 30 秒到 3 分钟，请勿立即访问。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。` +
+                    `。注意：路由配置传播通常数秒到约 30 秒；请立刻用 queryGateway(getRoute) 或探测 accessUrl 确认，勿盲等 60 秒以上。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。` +
                     (privilegeHint ? ` ${privilegeHint}` : ""), [
                     ...privilegeNextActions,
                     ...(routeMutationNextActions(payload.resolved.upstreamResourceName) ??
@@ -8300,12 +8304,28 @@ function registerGatewayTools(server) {
                 if (!input.domain || !input.certificateId) {
                     throw new Error("action=bindCustomDomain 时必须提供 domain 和 certificateId");
                 }
+                const accessType = input.accessType ?? "DIRECT";
+                if (accessType === "CUSTOM" && !input.customCname) {
+                    throw new Error("action=bindCustomDomain 且 accessType=CUSTOM 时必须提供 customCname（自有 CDN/WAF 的回源/回填地址，不是 DNS 解析目标）。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
+                if (accessType !== "CUSTOM" && input.customCname) {
+                    throw new Error("customCname 仅在 accessType=CUSTOM 时可用；普通绑定用默认 DIRECT，不要传 customCname。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
                 const cloudbase = await getManager();
                 const result = await cloudbase.env.bindCustomDomain({
                     EnvId: await resolveEnvId(),
                     Domain: {
                         Domain: input.domain,
                         CertId: input.certificateId,
+                        AccessType: accessType,
+                        ...(input.enable !== undefined
+                            ? { Enable: input.enable }
+                            : {}),
+                        ...(input.customCname
+                            ? { CustomCname: input.customCname }
+                            : {}),
                     },
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -8313,24 +8333,64 @@ function registerGatewayTools(server) {
                     action: input.action,
                     domain: input.domain,
                     certificateId: input.certificateId,
+                    accessType,
+                    ...(input.customCname
+                        ? { customCname: input.customCname }
+                        : {}),
+                    ...(input.enable !== undefined
+                        ? { enable: input.enable }
+                        : {}),
                     raw: result,
-                }, "自定义域名绑定成功");
+                }, `自定义域名绑定成功（${accessType}）`, [
+                    {
+                        tool: "manageGateway",
+                        action: "createRoute",
+                        reason: "绑定后需 createRoute 添加访问路径，并完成 DNS CNAME 解析后才可访问",
+                    },
+                ]);
             }
             case "deleteCustomDomain": {
                 if (!input.domain) {
                     throw new Error("action=deleteCustomDomain 时必须提供 domain");
                 }
                 const cloudbase = await getManager();
-                const result = await cloudbase.env.deleteCustomDomain({
-                    EnvId: await resolveEnvId(),
-                    Domain: input.domain,
-                });
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action: input.action,
-                    domain: input.domain,
-                    raw: result,
-                }, "自定义域名删除成功");
+                try {
+                    const result = await cloudbase.env.deleteCustomDomain({
+                        EnvId: await resolveEnvId(),
+                        Domain: input.domain,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    return buildEnvelope({
+                        action: input.action,
+                        domain: input.domain,
+                        raw: result,
+                    }, "自定义域名删除成功");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    // SDK 在域名下仍有路由绑定时抛错，需先删路由再删域名
+                    if (/route binding/i.test(message)) {
+                        return {
+                            success: false,
+                            data: { action: input.action, domain: input.domain },
+                            message: `域名 ${input.domain} 下仍有路由绑定，需先删除路由再删除域名。` +
+                                `原始错误：${message}`,
+                            nextActions: [
+                                {
+                                    tool: "queryGateway",
+                                    action: "listRoutes",
+                                    reason: "查看该域名下的路由，确认需要删除的路径",
+                                },
+                                {
+                                    tool: "manageGateway",
+                                    action: "deleteRoute",
+                                    reason: "先删除该域名下的全部路由（逐个 deleteRoute），再重试 deleteCustomDomain",
+                                },
+                            ],
+                        };
+                    }
+                    throw error;
+                }
             }
             case "enableService": {
                 if (typeof input.enable !== "boolean") {
@@ -8443,7 +8503,8 @@ function registerGatewayTools(server) {
                 "enableService/authSwitch 开关 HTTP 网关总开关与访问鉴权（需配合 enable 参数）。" +
                 "createRoute/updateRoute 必须提供 upstreamResourceType。" +
                 "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
-                "bindCustomDomain 仅用于首次绑定新域名。"),
+                "bindCustomDomain 仅用于首次绑定新域名（需 certificateId；可选 accessType=DIRECT|CDN|CUSTOM，CUSTOM 需 customCname；普通场景用默认 DIRECT）。" +
+                "接入说明：https://docs.cloudbase.net/service/custom-domain"),
             targetName: zod_1.z
                 .string()
                 .optional()
@@ -8506,11 +8567,24 @@ function registerGatewayTools(server) {
                 .optional()
                 .describe("证书 ID。仅首次 bindCustomDomain 必填。" +
                 "在已有自定义域名上 createRoute / updateRoute / deleteRoute 不需要 certificateId。"),
+            accessType: zod_1.z
+                .enum(["DIRECT", "CDN", "CUSTOM"])
+                .optional()
+                .describe("绑定类型（仅 bindCustomDomain，默认 DIRECT）。" +
+                "DIRECT=直连（普通绑域名用这个）；CDN=云开发 CDN；CUSTOM=自有 CDN/WAF（需 customCname）。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
+            customCname: zod_1.z
+                .string()
+                .optional()
+                .describe("自有 CDN/WAF 的回源/回填地址（仅 bindCustomDomain 且 accessType=CUSTOM）。" +
+                "不是 DNS 里用户域名要解析到的那个 CNAME；DIRECT/CDN 不要传。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
             enable: zod_1.z
                 .boolean()
                 .optional()
-                .describe("开关目标状态（仅 enableService / authSwitch 使用，必填）：" +
-                "enable=true 开启，enable=false 关闭。省略或非布尔值会返回参数错误。"),
+                .describe("开关目标状态（enableService / authSwitch 必填）：enable=true 开启，enable=false 关闭。" +
+                "bindCustomDomain 可选：enable=false 表示绑定后禁用域名（默认启用）。" +
+                "省略或非布尔值会返回参数错误。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -11134,7 +11208,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.25.4" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.6" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -11471,6 +11545,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.CUSTOM_IMAGE_RUNTIME = exports.MANAGE_FUNCTION_ACTIONS = exports.QUERY_FUNCTION_ACTIONS = exports.TRIGGER_CONFIG_EXAMPLES = exports.SUPPORTED_TRIGGER_TYPES = exports.DEFAULT_NODEJS_RUNTIME = exports.SUPPORTED_NODEJS_RUNTIMES = exports.RECOMMENDED_RUNTIMES = exports.DEFAULT_RUNTIME = exports.ALL_SUPPORTED_RUNTIMES = exports.SUPPORTED_RUNTIMES = void 0;
 exports.formatRuntimeList = formatRuntimeList;
 exports.validateTimerCron = validateTimerCron;
+exports.pickManageFunctionName = pickManageFunctionName;
 exports.shouldInstallDependencyForFunction = shouldInstallDependencyForFunction;
 exports.resolveEventFunctionRuntime = resolveEventFunctionRuntime;
 exports.buildFunctionOperationErrorMessage = buildFunctionOperationErrorMessage;
@@ -11699,6 +11774,19 @@ const MANAGE_LAYER_SCHEMA = zod_1.z.object({
     layerName: zod_1.z.string().describe("层名称"),
     layerVersion: zod_1.z.number().describe("层版本号"),
 });
+/**
+ * Prefer top-level functionName; fall back to func.name for the common
+ * mistake of nesting the target name under func (createFunction shape).
+ */
+function pickManageFunctionName(input) {
+    if (typeof input.functionName === "string" && input.functionName.trim()) {
+        return input.functionName.trim();
+    }
+    if (typeof input.func?.name === "string" && input.func.name.trim()) {
+        return input.func.name.trim();
+    }
+    return undefined;
+}
 function normalizeFunctionLayers(layers) {
     if (!Array.isArray(layers)) {
         return [];
@@ -12165,7 +12253,12 @@ function registerFunctionTools(server) {
                 throw new Error(`不支持的操作类型: ${input.action}`);
         }
     };
-    const handleManageFunctions = async (input) => {
+    const handleManageFunctions = async (rawInput) => {
+        // Accept func.name as a fallback for top-level functionName (common agent mistake).
+        const pickedName = pickManageFunctionName(rawInput);
+        const input = pickedName && rawInput.functionName !== pickedName
+            ? { ...rawInput, functionName: pickedName }
+            : rawInput;
         ensureActionAllowedInCloudMode(input);
         switch (input.action) {
             case "createFunction": {
@@ -12871,7 +12964,12 @@ function registerFunctionTools(server) {
                 "此参数传 cloudfunctions 或 functions 目录的绝对路径。" +
                 "SDK 会自动拼接函数名子目录，无需预先压缩 zip 或 base64 编码。"),
             force: zod_1.z.boolean().optional().describe("createFunction 时是否覆盖"),
-            functionName: zod_1.z.string().optional().describe("函数名称。大多数 action 使用该字段作为统一目标"),
+            functionName: zod_1.z
+                .string()
+                .optional()
+                .describe("目标函数名称（顶层）。updateFunctionCode / updateFunctionConfig / invokeFunction 等 action 使用此字段。" +
+                "不要只写在 func.name：createFunction 用 func.name，其它 action 用顶层 functionName。" +
+                "若误传 func.name，也会被识别为 functionName。"),
             zipFile: zod_1.z.string().optional().describe("仅兼容特殊场景：预先准备好的代码包 base64 编码。普通 createFunction/updateFunctionCode 默认不要先压缩 zip，优先使用 functionRootPath。"),
             handler: zod_1.z.string().optional().describe("函数入口"),
             timeout: zod_1.z.number().optional().describe("配置更新时的超时时间"),
@@ -12926,12 +13024,47 @@ module.exports = __WEBPACK_EXTERNAL_MODULE_ws__;
 /***/ }),
 
 /***/ 6473:
-/***/ ((__unused_webpack_module, exports, __webpack_require__) => {
+/***/ (function(__unused_webpack_module, exports, __webpack_require__) {
 
 
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.__resetPgReadyCache = __resetPgReadyCache;
 exports.registerPGDatabaseTools = registerPGDatabaseTools;
+const fs = __importStar(__webpack_require__(4421));
+const path = __importStar(__webpack_require__(2521));
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const tool_result_js_1 = __webpack_require__(9835);
@@ -12952,6 +13085,8 @@ const MANAGE_ACTIONS = [
     "applyMigration",
     "listMigrations",
     "migrationDetail",
+    "describeMigrationTask",
+    "fetchMigration",
     "rollbackMigration",
     "repairMigration",
 ];
@@ -13112,8 +13247,170 @@ function isSchemaDdlRisk(risk, sql) {
     const verb = getSqlVerb(stripLeadingSqlComments(sql));
     return ["DROP", "TRUNCATE", "ALTER"].includes(verb);
 }
+/**
+ * Canonical local migration directory — must match CloudBase CLI
+ * `MIGRATIONS_DIR` (`cloudbase/migrations`) so MCP+CLI mixed workflows share files.
+ * Legacy bare `migrations/` is accepted only when an existing matching file is found.
+ */
+const LOCAL_MIGRATIONS_DIR = "cloudbase/migrations";
+const LOCAL_MIGRATIONS_DIR_LEGACY = "migrations";
+/** Same constraint as applyMigration.migrationName (broader than CLI /^[a-z_]+$/ — digits allowed). */
+const MIGRATION_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+function getMigrationProjectRoot() {
+    const fromEnv = process.env.WORKSPACE_FOLDER_PATHS ||
+        process.env.PROJECT_ROOT ||
+        process.env.GITHUB_WORKSPACE ||
+        process.env.CI_PROJECT_DIR ||
+        process.env.BUILD_SOURCESDIRECTORY;
+    if (fromEnv && fromEnv.trim()) {
+        // IDEs may inject multiple folders separated by path.delimiter.
+        const first = fromEnv.split(path.delimiter).map((p) => p.trim()).find(Boolean);
+        if (first) {
+            return first;
+        }
+    }
+    return process.cwd();
+}
+function buildLocalMigrationFileName(version, name) {
+    return `${version}_${name}.sql`;
+}
 function buildLocalMigrationFileHint(version, name) {
-    return `migrations/${version}_${name}.sql`;
+    return `${LOCAL_MIGRATIONS_DIR}/${buildLocalMigrationFileName(version, name)}`;
+}
+/** Normalize SQL for local file compare/write (LF + single trailing newline). */
+function normalizeMigrationSqlForLocalFile(sql) {
+    const normalized = sql.replace(/\r\n/g, "\n").replace(/\s+$/u, "");
+    return `${normalized}\n`;
+}
+/**
+ * Ensure the workspace has a Git-truth SQL file for this migration before Push.
+ * Prefer write-to-workspace when missing; fail closed on mismatch or write failure
+ * (Supabase MCP#241 class: remote apply without local truth source).
+ */
+function ensureLocalMigrationSqlFile(version, name, sql) {
+    const fileName = buildLocalMigrationFileName(version, name);
+    const expected = normalizeMigrationSqlForLocalFile(sql);
+    const projectRoot = getMigrationProjectRoot();
+    const candidates = [
+        {
+            relativePath: `${LOCAL_MIGRATIONS_DIR}/${fileName}`,
+            absolutePath: path.join(projectRoot, LOCAL_MIGRATIONS_DIR, fileName),
+        },
+        {
+            relativePath: `${LOCAL_MIGRATIONS_DIR_LEGACY}/${fileName}`,
+            absolutePath: path.join(projectRoot, LOCAL_MIGRATIONS_DIR_LEGACY, fileName),
+        },
+    ];
+    for (const candidate of candidates) {
+        if (!fs.existsSync(candidate.absolutePath)) {
+            continue;
+        }
+        let existing;
+        try {
+            existing = fs.readFileSync(candidate.absolutePath, "utf8");
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errorCode: "LOCAL_MIGRATION_FILE_WRITE_FAILED",
+                message: `Failed to read existing local migration file ${candidate.relativePath}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`,
+                relativePath: candidate.relativePath,
+                absolutePath: candidate.absolutePath,
+            };
+        }
+        if (normalizeMigrationSqlForLocalFile(existing) === expected) {
+            return {
+                ok: true,
+                relativePath: candidate.relativePath,
+                absolutePath: candidate.absolutePath,
+                action: "matched",
+            };
+        }
+        return {
+            ok: false,
+            errorCode: "LOCAL_MIGRATION_FILE_MISMATCH",
+            message: `Local migration file ${candidate.relativePath} already exists but its content does not match the sql argument. ` +
+                "Refuse to overwrite (fail closed). Update the local file to match, or use a new migrationVersion / migrationName. " +
+                "Push was NOT submitted.",
+            relativePath: candidate.relativePath,
+            absolutePath: candidate.absolutePath,
+        };
+    }
+    const target = candidates[0];
+    try {
+        fs.mkdirSync(path.dirname(target.absolutePath), { recursive: true });
+        fs.writeFileSync(target.absolutePath, expected, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errorCode: "LOCAL_MIGRATION_FILE_WRITE_FAILED",
+            message: `Failed to write local migration file ${target.relativePath} under workspace ${projectRoot}: ` +
+                `${error instanceof Error ? error.message : String(error)}. ` +
+                "Push was NOT submitted. Fix workspace permissions or write the file manually, then retry applyMigration.",
+            relativePath: target.relativePath,
+            absolutePath: target.absolutePath,
+        };
+    }
+    return {
+        ok: true,
+        relativePath: target.relativePath,
+        absolutePath: target.absolutePath,
+        action: "created",
+    };
+}
+/**
+ * Sync remote migration Query bodies into cloudbase/migrations/ (CLI fetch parity).
+ * Without force, existing files are skipped; with force, overwritten.
+ */
+function syncFetchedMigrationsToLocalFiles(items, force) {
+    const projectRoot = getMigrationProjectRoot();
+    const migrationsDir = path.join(projectRoot, LOCAL_MIGRATIONS_DIR);
+    const files = [];
+    for (const item of items) {
+        const version = item.Version.trim();
+        const name = item.Name.trim();
+        if (!MIGRATION_NAME_PATTERN.test(name)) {
+            return {
+                ok: false,
+                errorCode: "LOCAL_MIGRATION_FETCH_INVALID_NAME",
+                message: `Remote migration name "${name}" (version=${version}) is invalid. ` +
+                    "Names must match /^[a-z][a-z0-9_]*$/ (same as applyMigration.migrationName). " +
+                    "Repair the remote history record, then retry fetchMigration.",
+            };
+        }
+        if (!item.Query.trim()) {
+            return {
+                ok: false,
+                errorCode: "LOCAL_MIGRATION_FETCH_EMPTY_QUERY",
+                message: `DescribePGUserMigration returned empty Query for version=${version} (${name}). ` +
+                    "Refuse to write an empty local migration file (would poison Git checksums).",
+            };
+        }
+        const relativePath = buildLocalMigrationFileHint(version, name);
+        const absolutePath = path.join(migrationsDir, buildLocalMigrationFileName(version, name));
+        const exists = fs.existsSync(absolutePath);
+        if (exists && !force) {
+            files.push({ version, name, relativePath, absolutePath, action: "skipped" });
+            continue;
+        }
+        try {
+            fs.mkdirSync(migrationsDir, { recursive: true });
+            fs.writeFileSync(absolutePath, normalizeMigrationSqlForLocalFile(item.Query), "utf8");
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errorCode: "LOCAL_MIGRATION_FILE_WRITE_FAILED",
+                message: `Failed to write local migration file ${relativePath} under workspace ${projectRoot}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`,
+                relativePath,
+            };
+        }
+        files.push({ version, name, relativePath, absolutePath, action: "written" });
+    }
+    return { ok: true, files };
 }
 /** How many recent migration records to scan when verifying a freshly pushed version. */
 const MIGRATION_VERIFY_LIMIT = 100;
@@ -13144,6 +13441,31 @@ function collectMigrationVersions(value, found = new Set()) {
 /** Brief retries before concluding a pushed migration never landed (Push can be async). */
 const MIGRATION_VERIFY_ATTEMPTS = 4;
 const MIGRATION_VERIFY_DELAY_MS = 1500;
+/** Page size when hydrating remote migration history into a Push/Preview payload. */
+const MIGRATION_LIST_PAGE_SIZE = 100;
+/**
+ * PushPGUserMigrations is async: poll DescribeTaskResult until Succeed/Failed.
+ * Default wait aligns with CLI `tcb db pg migration up` (10 minutes).
+ * Override per call via applyMigration.taskPollTimeoutMs.
+ */
+const MIGRATION_TASK_POLL_INTERVAL_MS = 1500;
+/** CLI parity: `TASK_MAX_WAIT_MS = 10 * 60 * 1000` in cloudbase-cli migration up. */
+const MIGRATION_TASK_DEFAULT_WAIT_MS = 10 * 60 * 1000;
+const MIGRATION_TASK_MIN_WAIT_MS = 5_000;
+const MIGRATION_TASK_MAX_WAIT_MS = MIGRATION_TASK_DEFAULT_WAIT_MS;
+function resolveMigrationTaskPollTimeoutMs(requested) {
+    if (requested === undefined || !Number.isFinite(requested)) {
+        return MIGRATION_TASK_DEFAULT_WAIT_MS;
+    }
+    const rounded = Math.floor(requested);
+    if (rounded < MIGRATION_TASK_MIN_WAIT_MS) {
+        return MIGRATION_TASK_MIN_WAIT_MS;
+    }
+    if (rounded > MIGRATION_TASK_MAX_WAIT_MS) {
+        return MIGRATION_TASK_MAX_WAIT_MS;
+    }
+    return rounded;
+}
 /**
  * Confirm a pushed migration version is present in the remote migration history.
  *
@@ -13177,8 +13499,224 @@ async function verifyMigrationApplied(context, version, cloudBaseOptions) {
     }
     return { applied: null, error: lastError };
 }
+function extractMigrationSummaries(history) {
+    const raw = history.Migrations;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const summaries = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const row = item;
+        const version = typeof row.Version === "string" ? row.Version.trim() : "";
+        const name = typeof row.Name === "string" ? row.Name.trim() : "";
+        if (version) {
+            summaries.push({ Version: version, Name: name || version });
+        }
+    }
+    return summaries;
+}
+/**
+ * List every remote migration summary (paginated). Required before Push/Preview:
+ * submitting only the pending migration while remote history exists yields
+ * Executable=false with Conflicts reason remote_history_not_found_locally, and the
+ * async task fails with "migration plan is not executable".
+ */
+async function listAllRemoteMigrationSummaries(context, cloudBaseOptions) {
+    const summaries = [];
+    let offset = 0;
+    let latestVersion = "";
+    let total = 0;
+    while (true) {
+        const page = await callPgMigrationApi(context, "ListPGUserMigrations", { Limit: MIGRATION_LIST_PAGE_SIZE, Offset: offset }, cloudBaseOptions);
+        const pageItems = extractMigrationSummaries(page);
+        summaries.push(...pageItems);
+        if (typeof page.LatestVersion === "string" && page.LatestVersion.trim()) {
+            latestVersion = page.LatestVersion.trim();
+        }
+        if (typeof page.Total === "number" && Number.isFinite(page.Total)) {
+            total = page.Total;
+        }
+        else {
+            total = summaries.length;
+        }
+        if (pageItems.length < MIGRATION_LIST_PAGE_SIZE) {
+            break;
+        }
+        offset += MIGRATION_LIST_PAGE_SIZE;
+    }
+    return { summaries, latestVersion, total };
+}
+/** `<version>_<name>.sql` — version is the identity key for completeness checks. */
+const LOCAL_MIGRATION_FILENAME_RE = /^(\d{14})_(.+)\.sql$/;
+function listLocalMigrationFilesInDir(dirAbsolute, dirRelative) {
+    const map = new Map();
+    if (!fs.existsSync(dirAbsolute)) {
+        return map;
+    }
+    let stat;
+    try {
+        stat = fs.statSync(dirAbsolute);
+    }
+    catch {
+        return map;
+    }
+    if (!stat.isDirectory()) {
+        return map;
+    }
+    let fileNames;
+    try {
+        fileNames = fs.readdirSync(dirAbsolute);
+    }
+    catch {
+        return map;
+    }
+    for (const fileName of fileNames) {
+        const match = LOCAL_MIGRATION_FILENAME_RE.exec(fileName);
+        if (!match) {
+            continue;
+        }
+        const version = match[1];
+        const name = match[2];
+        const absolutePath = path.join(dirAbsolute, fileName);
+        let query;
+        try {
+            query = fs.readFileSync(absolutePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!query.trim()) {
+            continue;
+        }
+        map.set(version, {
+            version,
+            name,
+            query,
+            relativePath: `${dirRelative}/${fileName}`,
+        });
+    }
+    return map;
+}
+/**
+ * Index local migration SQL by version. Canonical `cloudbase/migrations/` wins over legacy `migrations/`.
+ */
+function listLocalMigrationFilesByVersion() {
+    const projectRoot = getMigrationProjectRoot();
+    const legacy = listLocalMigrationFilesInDir(path.join(projectRoot, LOCAL_MIGRATIONS_DIR_LEGACY), LOCAL_MIGRATIONS_DIR_LEGACY);
+    const canonical = listLocalMigrationFilesInDir(path.join(projectRoot, LOCAL_MIGRATIONS_DIR), LOCAL_MIGRATIONS_DIR);
+    const merged = new Map(legacy);
+    for (const [version, entry] of canonical) {
+        merged.set(version, entry);
+    }
+    return merged;
+}
+function remoteHistoryCoveredByLocalFiles(summaries, localByVersion, pendingVersion) {
+    for (const summary of summaries) {
+        if (summary.Version === pendingVersion) {
+            // Pending SQL comes from the tool args / ensureLocal write.
+            continue;
+        }
+        const local = localByVersion.get(summary.Version);
+        if (!local || !local.query.trim()) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Build Push/Preview Migrations = full candidate set (server skips already-applied).
+ *
+ * Prefer CLI parity when the workspace already has SQL for every remote version:
+ * read local files (no per-version DescribePGUserMigration). Otherwise hydrate
+ * remote Queries via List + N×Describe (agent/remote-first when the local tree is incomplete).
+ */
+async function buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions) {
+    const { summaries, latestVersion } = await listAllRemoteMigrationSummaries(context, cloudBaseOptions);
+    const localByVersion = listLocalMigrationFilesByVersion();
+    if (remoteHistoryCoveredByLocalFiles(summaries, localByVersion, pending.Version)) {
+        const migrations = [];
+        for (const summary of summaries) {
+            if (summary.Version === pending.Version) {
+                continue;
+            }
+            const local = localByVersion.get(summary.Version);
+            migrations.push({
+                Version: local.version,
+                Name: local.name || summary.Name,
+                Query: local.query,
+            });
+        }
+        migrations.push(pending);
+        return {
+            migrations,
+            remoteCount: summaries.length,
+            latestVersion,
+            payloadSource: "local",
+        };
+    }
+    const migrations = [];
+    for (const summary of summaries) {
+        if (summary.Version === pending.Version) {
+            // Caller supplies the authoritative SQL for this version.
+            continue;
+        }
+        const detail = await callPgMigrationApi(context, "DescribePGUserMigration", { MigrationVersion: summary.Version }, cloudBaseOptions);
+        const query = typeof detail.Query === "string" ? detail.Query : "";
+        if (!query.trim()) {
+            throw new Error(`DescribePGUserMigration returned empty Query for version=${summary.Version} (${summary.Name}). ` +
+                "Cannot hydrate remote history for PushPGUserMigrations.");
+        }
+        migrations.push({
+            Version: typeof detail.Version === "string" && detail.Version.trim() ? detail.Version.trim() : summary.Version,
+            Name: typeof detail.Name === "string" && detail.Name.trim() ? detail.Name.trim() : summary.Name,
+            Query: query,
+        });
+    }
+    migrations.push(pending);
+    return {
+        migrations,
+        remoteCount: summaries.length,
+        latestVersion,
+        payloadSource: "hydrate",
+    };
+}
+function formatMigrationsPayloadSourceLabel(source, remoteCount) {
+    if (remoteCount <= 0) {
+        return "no remote history";
+    }
+    return source === "local"
+        ? `local tree covered ${remoteCount} remote migration(s) (CLI parity, skipped Describe hydrate)`
+        : `hydrated ${remoteCount} remote migration(s) via Describe (local tree incomplete)`;
+}
+async function waitPgMigrationTask(context, taskId, cloudBaseOptions, maxWaitMs = MIGRATION_TASK_DEFAULT_WAIT_MS) {
+    const deadline = Date.now() + maxWaitMs;
+    let last = { TaskId: taskId };
+    while (Date.now() <= deadline) {
+        last = (await callPgMigrationApi(context, "DescribeTaskResult", { TaskId: taskId }, cloudBaseOptions));
+        const status = String(last.Status || "").toLowerCase();
+        if (status === "succeed" || status === "failed") {
+            return last;
+        }
+        await sleep(MIGRATION_TASK_POLL_INTERVAL_MS);
+    }
+    const error = new Error(`DescribeTaskResult timed out after ${Math.floor(maxWaitMs / 1000)}s ` +
+        `for TaskId=${taskId} (last Status=${last.Status || "-"}, Phase=${last.Phase || "-"}).`);
+    error.lastTask = last;
+    throw error;
+}
+function buildMigrationTaskPendingNextActions(version, taskId) {
+    const actions = [];
+    if (taskId) {
+        actions.push(buildNextAction(MANAGE_PG_DATABASE, "describeMigrationTask", "FIRST: poll DescribeTaskResult for Status/Phase/Reason. listMigrations alone cannot explain a Failed task (see issue #857).", { action: "describeMigrationTask", taskId }));
+    }
+    actions.push(buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check whether migrationVersion landed in remote history. Do NOT re-push the same version while the task may still be running.", { action: "listMigrations", limit: 20 }), buildNextAction(MANAGE_PG_DATABASE, "migrationDetail", "If listMigrations already shows this version, inspect the applied record. If missing after several minutes and the task is Failed/terminal, inspect Conflicts/SQL before considering a NEW migrationVersion.", { action: "migrationDetail", migrationVersion: version }));
+    return actions;
+}
 const MIGRATION_VERSION_REQUIRED_MESSAGE = "migrationVersion is required (14-digit UTC timestamp YYYYMMDDHHMMSS). " +
-    "Decide the version first, write local file migrations/<version>_<migrationName>.sql, " +
+    "Decide the version first, write local file cloudbase/migrations/<version>_<migrationName>.sql, " +
     "then call planMigration/applyMigration with the same migrationVersion and migrationName.";
 function requireExplicitMigrationVersion(args, actionLabel) {
     const version = args.migrationVersion?.trim();
@@ -13515,6 +14053,30 @@ function createDefaultDependencies(server) {
         createClient: async (context) => createManagerPgClient(context, server?.cloudBaseOptions),
     };
 }
+function isPgMigrationApiDatabase(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "previewPGUserMigrations" in value &&
+        typeof value.previewPGUserMigrations === "function" &&
+        "pushPGUserMigrations" in value &&
+        typeof value.pushPGUserMigrations === "function" &&
+        "listPGUserMigrations" in value &&
+        typeof value.listPGUserMigrations === "function" &&
+        "describeTaskResult" in value &&
+        typeof value.describeTaskResult === "function");
+}
+/**
+ * Actions without a native wrapper in manager-node (e.g. RollbackPGUserMigrations)
+ * are intentionally absent and keep using the commonService fallback.
+ */
+const PgMigrationNativeActionMethods = {
+    PreviewPGUserMigrations: "previewPGUserMigrations",
+    PushPGUserMigrations: "pushPGUserMigrations",
+    RepairPGUserMigrationHistory: "repairPGUserMigrationHistory",
+    ListPGUserMigrations: "listPGUserMigrations",
+    DescribePGUserMigration: "describePGUserMigration",
+    DescribeTaskResult: "describeTaskResult",
+};
 function isExecutePGSqlDatabase(value) {
     return Boolean(value &&
         typeof value === "object" &&
@@ -13555,13 +14117,22 @@ async function executeManagerPGSql(context, sql, cloudBaseOptions) {
     }
     throw new Error("Current @cloudbase/manager-node runtime does not expose database.executePGSql or commonService fallback. Upgrade to @cloudbase/manager-node >= 5.4.0.");
 }
-/** Call a CloudBase PG migration API via commonService fallback */
+/**
+ * Call a CloudBase PG migration API, preferring native manager-node methods
+ * (>= 5.6.5) and falling back to the commonService channel for older runtimes
+ * and actions without a native wrapper (RollbackPGUserMigrations).
+ */
 async function callPgMigrationApi(context, action, params, cloudBaseOptions) {
     const manager = await (0, cloudbase_manager_js_1.getCloudBaseManager)({
         cloudBaseOptions: cloudBaseOptions
             ? { ...cloudBaseOptions, envId: context.envId }
             : { envId: context.envId },
     });
+    const nativeMethod = PgMigrationNativeActionMethods[action];
+    if (nativeMethod && isPgMigrationApiDatabase(manager.database)) {
+        const invoke = manager.database[nativeMethod];
+        return invoke.call(manager.database, { EnvId: context.envId, ...params });
+    }
     if (!isCloudBaseWithCommonService(manager)) {
         throw new Error("Current @cloudbase/manager-node runtime does not support migration APIs. Upgrade to @cloudbase/manager-node >= 5.4.0.");
     }
@@ -13802,11 +14373,11 @@ async function handleExecuteSql(args, context, deps) {
             success: false,
             errorCode: "DDL_USE_APPLY_MIGRATION",
             message: "Schema DDL (CREATE/ALTER/DROP/TRUNCATE/...) must use applyMigration with an explicit migrationVersion, " +
-                "not execute. Write local migrations/<version>_<name>.sql first, then call applyMigration. " +
+                "not execute. Write local cloudbase/migrations/<version>_<name>.sql first, then call applyMigration. " +
                 "Set allowDdlViaExecute=true only for exceptional one-off ops that intentionally bypass migration history.",
             data: {
                 classification,
-                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+                localFileHintPattern: "cloudbase/migrations/<migrationVersion>_<migrationName>.sql",
             },
             nextActions: [
                 buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview the schema change as a versioned migration (provide migrationVersion + migrationName).", {
@@ -13915,7 +14486,7 @@ async function handleDryRun(args) {
                 wouldExecute: false,
                 sqlPreview: args.sql.trim().slice(0, 500),
                 preferredAction: "applyMigration",
-                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+                localFileHintPattern: "cloudbase/migrations/<migrationVersion>_<migrationName>.sql",
             },
             message: "SQL dry run completed. Schema DDL should use applyMigration with an explicit migrationVersion, not execute.",
             nextActions: [
@@ -13963,35 +14534,50 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
+        pending.Rollback = args.rollbackSql;
     }
     try {
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
+        const includeAll = Boolean(args.includeAll);
         const result = await callPgMigrationApi(context, "PreviewPGUserMigrations", {
-            Migrations: [migration],
+            Migrations: hydrated.migrations,
+            IncludeAll: includeAll,
         }, cloudBaseOptions);
+        const executable = result.Executable === true;
+        const payloadSourceLabel = formatMigrationsPayloadSourceLabel(hydrated.payloadSource, hydrated.remoteCount);
         return buildPgToolResult({
             success: true,
             data: {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                hydratedRemoteCount: hydrated.remoteCount,
+                latestRemoteVersion: hydrated.latestVersion || null,
+                payloadSource: hydrated.payloadSource,
+                includeAll,
+                executable,
                 apiResult: result,
             },
-            message: `Migration plan generated via PreviewPGUserMigrations. Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`,
+            message: executable
+                ? `Migration plan generated via PreviewPGUserMigrations (${payloadSourceLabel}${includeAll ? ", includeAll=true" : ""}). Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`
+                : `Migration plan is NOT executable (PreviewPGUserMigrations.Executable=false after ${payloadSourceLabel}${includeAll ? ", includeAll=true" : ""}). Inspect apiResult.Conflicts before applyMigration. Common causes: version older than latest remote (${hydrated.latestVersion || "unknown"}) — retry with includeAll=true (CLI --include-all) if intentionally out-of-order, or pick a newer version; checksum mismatch.`,
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion.", {
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", executable
+                    ? "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion."
+                    : "Resolve Conflicts (often pick a migrationVersion newer than LatestVersion, or set includeAll=true for intentional out-of-order), then retry planMigration/applyMigration.", {
                     action: "applyMigration",
                     migrationName: args.migrationName,
                     migrationVersion: version,
                     sql: args.sql,
                     confirm: true,
                     ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                    ...(includeAll ? { includeAll: true } : {}),
                 }),
             ],
         });
@@ -14032,26 +14618,181 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    // Prefer write-to-workspace (or fail closed) so remote history cannot advance without a Git truth source.
+    const localFile = ensureLocalMigrationSqlFile(version, args.migrationName, args.sql);
+    if (!localFile.ok) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: localFile.errorCode,
+            data: {
+                migrationVersion: version,
+                migrationName: args.migrationName,
+                localFileHint,
+                localFilePath: localFile.relativePath ?? localFileHint,
+                localFileAbsolutePath: localFile.absolutePath ?? null,
+                verified: false,
+            },
+            message: localFile.message,
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "planMigration", "After aligning the local SQL file with the sql argument (or choosing a new migrationVersion), preview again.", {
+                    action: "planMigration",
+                    migrationName: args.migrationName,
+                    migrationVersion: version,
+                    sql: args.sql,
+                    ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                    ...(args.includeAll ? { includeAll: true } : {}),
+                }),
+            ],
+        });
+    }
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
-    }
-    const params = { Migrations: [migration] };
-    if (args.lockTimeoutMs !== undefined) {
-        params.LockTimeoutMs = args.lockTimeoutMs;
-    }
-    if (args.statementTimeoutMs !== undefined) {
-        params.StatementTimeoutMs = args.statementTimeoutMs;
+        pending.Rollback = args.rollbackSql;
     }
+    const includeAll = Boolean(args.includeAll);
     try {
+        // Pushing only the pending migration while remote history exists makes the plan
+        // non-executable (remote_history_not_found_locally). Prefer local tree when complete
+        // (CLI parity); otherwise hydrate remote Queries (List + N×Describe).
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
+        const payloadSourceLabel = formatMigrationsPayloadSourceLabel(hydrated.payloadSource, hydrated.remoteCount);
+        const preview = await callPgMigrationApi(context, "PreviewPGUserMigrations", { Migrations: hydrated.migrations, IncludeAll: includeAll }, cloudBaseOptions);
+        if (preview.Executable !== true) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_NOT_EXECUTABLE",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
+                    latestRemoteVersion: hydrated.latestVersion || null,
+                    payloadSource: hydrated.payloadSource,
+                    includeAll,
+                    previewResult: preview,
+                    verified: false,
+                },
+                message: `PreviewPGUserMigrations reported Executable=false for migrationVersion=${version} ` +
+                    `(latest remote=${hydrated.latestVersion || "unknown"}, ${payloadSourceLabel}, includeAll=${includeAll}). ` +
+                    "Push was NOT submitted. Inspect previewResult.Conflicts — common reasons: " +
+                    "local_migration_before_latest_remote (pick a newer 14-digit version, or set includeAll=true / CLI --include-all for intentional out-of-order) or checksum_mismatch. " +
+                    "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
+                nextActions: [
+                    buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check LatestVersion and pick a migrationVersion strictly newer than it.", { action: "listMigrations", limit: 20 }),
+                    buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Re-run planMigration after adjusting migrationVersion/SQL (or includeAll=true for out-of-order).", {
+                        action: "planMigration",
+                        migrationName: args.migrationName,
+                        migrationVersion: version,
+                        sql: args.sql,
+                        ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                        ...(includeAll ? { includeAll: true } : {}),
+                    }),
+                ],
+            });
+        }
+        const params = {
+            Migrations: hydrated.migrations,
+            IncludeAll: includeAll,
+        };
+        if (args.lockTimeoutMs !== undefined) {
+            params.LockTimeoutMs = args.lockTimeoutMs;
+        }
+        if (args.statementTimeoutMs !== undefined) {
+            params.StatementTimeoutMs = args.statementTimeoutMs;
+        }
         const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
-        // PushPGUserMigrations may return a TaskId without the migration having taken
-        // effect. Confirm against the remote history before reporting success, so callers
-        // never get a false-positive success for a silently dropped migration.
+        const taskId = typeof result.TaskId === "string" ? result.TaskId.trim() : "";
+        const pollTimeoutMs = resolveMigrationTaskPollTimeoutMs(args.taskPollTimeoutMs);
+        const shouldWaitForTask = args.waitForTask !== false;
+        let taskResult = null;
+        if (taskId && !shouldWaitForTask) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_TASK_PENDING",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
+                    payloadSource: hydrated.payloadSource,
+                    apiResult: result,
+                    taskResult: { TaskId: taskId },
+                    taskPollTimeoutMs: pollTimeoutMs,
+                    waitForTask: false,
+                    verified: null,
+                },
+                message: `PushPGUserMigrations accepted TaskId=${taskId} (waitForTask=false). ` +
+                    "TaskId means accepted, not applied. Call action=describeMigrationTask FIRST for Status/Phase/Reason, " +
+                    `then listMigrations to see whether migrationVersion=${version} landed. ` +
+                    "Do NOT re-push the same version while the task may still be running.",
+                nextActions: buildMigrationTaskPendingNextActions(version, taskId),
+            });
+        }
+        if (taskId) {
+            try {
+                taskResult = await waitPgMigrationTask(context, taskId, cloudBaseOptions, pollTimeoutMs);
+            }
+            catch (error) {
+                const lastTask = error.lastTask;
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_TIMEOUT",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: lastTask ?? { TaskId: taskId },
+                        taskPollTimeoutMs: pollTimeoutMs,
+                        verified: null,
+                    },
+                    message: `PushPGUserMigrations returned TaskId=${taskId}, but waiting for DescribeTaskResult timed out ` +
+                        `after ${Math.floor(pollTimeoutMs / 1000)}s: ${error instanceof Error ? error.message : String(error)}. ` +
+                        "The migration may STILL be running in the background (large DDL / lock waits). " +
+                        "Call action=describeMigrationTask FIRST (Status/Phase/Reason), then listMigrations. " +
+                        "Do NOT re-push the same migrationVersion, and do NOT fall back to execute until the task is terminal " +
+                        "and listMigrations confirms the version is missing.",
+                    nextActions: buildMigrationTaskPendingNextActions(version, taskId),
+                });
+            }
+            const status = String(taskResult.Status || "").toLowerCase();
+            if (status === "failed") {
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_FAILED",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: taskResult,
+                        verified: false,
+                    },
+                    message: `PushPGUserMigrations TaskId=${taskId} failed at phase=${taskResult.Phase || "-"}: ` +
+                        `${taskResult.Reason || "unknown reason"}. ` +
+                        "The migration did NOT take effect. Fix Conflicts/SQL (or use a newer migrationVersion), then retry applyMigration. " +
+                        "Urgent bypass: action=execute with allowDdlViaExecute=true (skips migration history).",
+                    nextActions: [
+                        buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview again to inspect Conflicts before retrying apply.", {
+                            action: "planMigration",
+                            migrationName: args.migrationName,
+                            migrationVersion: version,
+                            sql: args.sql,
+                            ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                            ...(includeAll ? { includeAll: true } : {}),
+                        }),
+                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Confirm the version is still absent from remote history.", { action: "listMigrations", limit: 20 }),
+                    ],
+                });
+            }
+        }
+        // Task Succeed (or sync response without TaskId): confirm history records the version.
         const verification = await verifyMigrationApplied(context, version, cloudBaseOptions);
         if (verification.applied === false) {
             return buildPgToolResult({
@@ -14061,10 +14802,13 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
+                    includeAll,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: false,
                 },
-                message: `PushPGUserMigrations returned without error, but migrationVersion=${version} is not present in the remote migration history, ` +
+                message: `PushPGUserMigrations completed (TaskId=${taskId || "none"}), but migrationVersion=${version} is not present in the remote migration history, ` +
                     "so the migration did NOT take effect. Do not assume the schema change is applied. " +
                     "Re-check the SQL and migrationVersion, inspect the migration with action=migrationDetail, and retry action=applyMigration. " +
                     "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
@@ -14082,7 +14826,9 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: null,
                 },
                 message: `PushPGUserMigrations was submitted, but verifying migrationVersion=${version} against the remote history failed: ${verification.error}. ` +
@@ -14098,10 +14844,18 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                localFilePath: localFile.relativePath,
+                localFileAbsolutePath: localFile.absolutePath,
+                localFileAction: localFile.action,
+                hydratedRemoteCount: hydrated.remoteCount,
+                payloadSource: hydrated.payloadSource,
+                includeAll,
                 apiResult: result,
+                taskResult: taskResult,
                 verified: true,
             },
-            message: `Migrations applied via PushPGUserMigrations and verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
+            message: `Migrations applied via PushPGUserMigrations (${payloadSourceLabel}${includeAll ? ", includeAll=true" : ""}), task ${taskId ? `TaskId=${taskId} ` : ""}verified present in the remote migration history. ` +
+                `Local SQL ${localFile.action === "created" ? "written" : "matched"} at ${localFile.relativePath}.`,
         });
     }
     catch (error) {
@@ -14162,6 +14916,156 @@ async function handleMigrationDetail(args, context, deps, cloudBaseOptions) {
         });
     }
 }
+/**
+ * One-shot DescribeTaskResult for a PushPGUserMigrations TaskId.
+ * Complements listMigrations: history shows whether a version landed; task result shows
+ * Status/Phase/Reason while the job is running or after it Failed (issue #857 evidence path).
+ */
+async function handleDescribeMigrationTask(args, context, _deps, cloudBaseOptions) {
+    const taskId = args.taskId?.trim();
+    if (!taskId) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "TASK_ID_REQUIRED",
+            message: "Provide taskId when action=describeMigrationTask " +
+                "(from applyMigration Push / MIGRATION_TASK_PENDING / MIGRATION_TASK_TIMEOUT data.taskResult.TaskId).",
+        });
+    }
+    try {
+        const taskResult = (await callPgMigrationApi(context, "DescribeTaskResult", { TaskId: taskId }, cloudBaseOptions));
+        const status = String(taskResult.Status || "").toLowerCase();
+        const versionHint = args.migrationVersion?.trim();
+        const nextActions = [];
+        if (status === "succeed") {
+            nextActions.push(buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Task Succeed — confirm migrationVersion is present in remote history before dependent SQL.", { action: "listMigrations", limit: 20 }));
+            if (versionHint) {
+                nextActions.push(buildNextAction(MANAGE_PG_DATABASE, "migrationDetail", "Inspect the applied migration record.", { action: "migrationDetail", migrationVersion: versionHint }));
+            }
+        }
+        else if (status === "failed") {
+            nextActions.push(buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Confirm the version is absent from history, then fix Conflicts/SQL and retry with a NEW migrationVersion (do not re-push the failed version blindly).", { action: "listMigrations", limit: 20 }));
+        }
+        else {
+            nextActions.push(buildNextAction(MANAGE_PG_DATABASE, "describeMigrationTask", "Task still running — poll again shortly. Do NOT re-push the same migrationVersion.", { action: "describeMigrationTask", taskId }), buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Optionally check whether the version already landed while Status is still non-terminal.", { action: "listMigrations", limit: 20 }));
+        }
+        const statusLabel = taskResult.Status || "unknown";
+        return buildPgToolResult({
+            success: true,
+            data: {
+                taskId,
+                taskResult: taskResult,
+                terminal: status === "succeed" || status === "failed",
+                ...(versionHint ? { migrationVersion: versionHint } : {}),
+            },
+            message: status === "succeed"
+                ? `DescribeTaskResult TaskId=${taskId} Status=Succeed (Phase=${taskResult.Phase || "-"}). Verify with listMigrations before treating schema as applied.`
+                : status === "failed"
+                    ? `DescribeTaskResult TaskId=${taskId} Status=Failed at phase=${taskResult.Phase || "-"}: ${taskResult.Reason || "unknown reason"}. Do NOT re-push the same migrationVersion until Conflicts/SQL are fixed.`
+                    : `DescribeTaskResult TaskId=${taskId} Status=${statusLabel} Phase=${taskResult.Phase || "-"}. Task is not terminal yet — poll again; do not re-push.`,
+            nextActions,
+        });
+    }
+    catch (error) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_API_ERROR",
+            message: `DescribeTaskResult failed for TaskId=${taskId}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+/**
+ * Pull remote migration history SQL into cloudbase/migrations/ (CLI `tcb db pg migration fetch`).
+ * Optional migrationVersion fetches one record; omit for full history. force overwrites existing files.
+ */
+async function handleFetchMigration(args, context, _deps, cloudBaseOptions) {
+    const force = args.force === true;
+    const singleVersion = args.migrationVersion?.trim();
+    try {
+        const remoteItems = [];
+        if (singleVersion) {
+            const detail = await callPgMigrationApi(context, "DescribePGUserMigration", { MigrationVersion: singleVersion }, cloudBaseOptions);
+            const version = typeof detail.Version === "string" && detail.Version.trim()
+                ? detail.Version.trim()
+                : singleVersion;
+            const name = typeof detail.Name === "string" && detail.Name.trim()
+                ? detail.Name.trim()
+                : "";
+            const query = typeof detail.Query === "string" ? detail.Query : "";
+            remoteItems.push({ Version: version, Name: name || version, Query: query });
+        }
+        else {
+            const { summaries } = await listAllRemoteMigrationSummaries(context, cloudBaseOptions);
+            for (const summary of summaries) {
+                const detail = await callPgMigrationApi(context, "DescribePGUserMigration", { MigrationVersion: summary.Version }, cloudBaseOptions);
+                const version = typeof detail.Version === "string" && detail.Version.trim()
+                    ? detail.Version.trim()
+                    : summary.Version;
+                const name = typeof detail.Name === "string" && detail.Name.trim()
+                    ? detail.Name.trim()
+                    : summary.Name;
+                const query = typeof detail.Query === "string" ? detail.Query : "";
+                remoteItems.push({ Version: version, Name: name, Query: query });
+            }
+        }
+        const sync = syncFetchedMigrationsToLocalFiles(remoteItems, force);
+        if (!sync.ok) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: sync.errorCode,
+                message: sync.message,
+                data: {
+                    migrationsDir: LOCAL_MIGRATIONS_DIR,
+                    force,
+                    localFilePath: sync.relativePath,
+                },
+            });
+        }
+        const written = sync.files.filter((f) => f.action === "written");
+        const skipped = sync.files.filter((f) => f.action === "skipped");
+        return buildPgToolResult({
+            success: true,
+            data: {
+                migrationsDir: LOCAL_MIGRATIONS_DIR,
+                force,
+                migrationVersion: singleVersion || null,
+                total: remoteItems.length,
+                writtenCount: written.length,
+                skippedCount: skipped.length,
+                written: written.map((f) => f.relativePath),
+                skipped: skipped.map((f) => f.relativePath),
+                files: sync.files.map(({ version, name, relativePath, action }) => ({
+                    version,
+                    name,
+                    relativePath,
+                    action,
+                })),
+            },
+            message: remoteItems.length === 0
+                ? "No remote migrations to fetch. Local cloudbase/migrations/ unchanged."
+                : `Fetched ${remoteItems.length} remote migration(s): wrote ${written.length}, skipped ${skipped.length}` +
+                    (skipped.length > 0 && !force
+                        ? " (existing files left untouched; pass force=true to overwrite, matching CLI --force)."
+                        : ".") +
+                    ` Directory: ${LOCAL_MIGRATIONS_DIR}/.`,
+            nextActions: skipped.length > 0 && !force
+                ? [
+                    buildNextAction(MANAGE_PG_DATABASE, "fetchMigration", "Re-run with force=true to overwrite skipped local files from remote history (checksum realign).", {
+                        action: "fetchMigration",
+                        force: true,
+                        ...(singleVersion ? { migrationVersion: singleVersion } : {}),
+                    }),
+                ]
+                : undefined,
+        });
+    }
+    catch (error) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_API_ERROR",
+            message: `fetchMigration failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
 async function handleRollbackMigration(args, context, deps, cloudBaseOptions) {
     if (args.lastN === undefined || args.lastN < 1 || !Number.isInteger(args.lastN)) {
         return buildPgToolResult({
@@ -14376,11 +15280,11 @@ function registerPGDatabaseTools(server, providedDeps) {
     });
     server.registerTool?.(MANAGE_PG_DATABASE, {
         title: "管理 PostgreSQL 上下文或执行写入 SQL",
-        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL、SQL 风险预检、迁移管理。建表/ALTER/DROP 等 schema 变更必须使用 applyMigration（显式 migrationVersion + 本地 migrations/ 留档），不要默认用 execute。execute 主要用于 DML 与 GRANT/RLS 等运维 SQL。",
+        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL、SQL 风险预检、迁移管理。建表/ALTER/DROP 等 schema 变更必须使用 applyMigration（显式 migrationVersion；成功前自动写入或校验本地 cloudbase/migrations/<version>_<name>.sql，与 CLI tcb db pg migration 一致），不要默认用 execute。execute 主要用于 DML 与 GRANT/RLS 等运维 SQL。",
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_ACTIONS)
-                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true；成功返回前会自动校验该 migrationVersion 已落入远端迁移历史，未落库时返回 success=false 且 errorCode=MIGRATION_NOT_APPLIED）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
+                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql；可选 includeAll=true 允许乱序，对齐 CLI --include-all）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true；可选 includeAll；本地 SQL 缺失则自动写入 cloudbase/migrations/，内容不一致则 LOCAL_MIGRATION_FILE_MISMATCH fail-closed；成功返回前会轮询 DescribeTaskResult（默认最长 10 分钟，可用 taskPollTimeoutMs / waitForTask 调整）并校验 migrationVersion 已落入远端历史；超时返回 MIGRATION_TASK_TIMEOUT，必须先 describeMigrationTask 再 listMigrations，禁止立刻重推同 version；未落库时返回 success=false 且 errorCode=MIGRATION_NOT_APPLIED）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；describeMigrationTask=按 TaskId 查询 Push 异步任务状态（DescribeTaskResult：Status/Phase/Reason；需 taskId；用于 waitForTask=false / MIGRATION_TASK_TIMEOUT / 失败诊断，listMigrations 看不到 Reason）；fetchMigration=从远端 history 拉取 SQL 写入本地 cloudbase/migrations/（对齐 CLI tcb db pg migration fetch；可选 migrationVersion 拉单条，省略则全量；force=true 覆盖已存在文件，默认跳过）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
             sql: zod_1.z
                 .string()
                 .optional()
@@ -14418,7 +15322,7 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .string()
                 .regex(/^\d{14}$/)
                 .optional()
-                .describe("14 位时间戳 YYYYMMDDHHMMSS。plan/apply/detail/repair 必填；禁止由服务端静默生成，避免与本地 migrations/<version>_<name>.sql 分叉。"),
+                .describe("14 位时间戳 YYYYMMDDHHMMSS。plan/apply/detail/repair 必填；fetchMigration 可选（传入则只拉该条，省略则拉全量远端 history）；禁止由服务端静默生成，避免与本地 cloudbase/migrations/<version>_<name>.sql 分叉。"),
             rollbackSql: zod_1.z
                 .string()
                 .optional()
@@ -14452,6 +15356,21 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .int()
                 .optional()
                 .describe("apply 可选：单条 SQL 执行最长时间（毫秒），默认 300000。"),
+            taskPollTimeoutMs: zod_1.z
+                .number()
+                .int()
+                .min(MIGRATION_TASK_MIN_WAIT_MS)
+                .max(MIGRATION_TASK_MAX_WAIT_MS)
+                .optional()
+                .describe(`apply 可选：轮询 DescribeTaskResult 的最长等待（毫秒）。默认 ${MIGRATION_TASK_DEFAULT_WAIT_MS}（与 CLI tcb db pg migration up 的 10 分钟对齐）。范围 ${MIGRATION_TASK_MIN_WAIT_MS}-${MIGRATION_TASK_MAX_WAIT_MS}。超时后务必先 describeMigrationTask(taskId) 再 listMigrations，禁止立刻重推同 version。`),
+            waitForTask: zod_1.z
+                .boolean()
+                .optional()
+                .describe("apply 可选，默认 true。设为 false 时 Push 后立即返回 TaskId（errorCode=MIGRATION_TASK_PENDING），由调用方用 describeMigrationTask 轮询任务终态，再用 listMigrations 确认是否落库；适合 MCP host 工具调用超时较短的场景。默认 true 会同步等到任务终态。"),
+            taskId: zod_1.z
+                .string()
+                .optional()
+                .describe("describeMigrationTask 必填：PushPGUserMigrations / applyMigration 返回的 TaskId。用于一次性查询 DescribeTaskResult（Status/Phase/Reason），不轮询等待。"),
             repairStatus: zod_1.z
                 .enum(["applied", "reverted"])
                 .optional()
@@ -14460,6 +15379,14 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .string()
                 .optional()
                 .describe("repair 必填：修复原因。"),
+            force: zod_1.z
+                .boolean()
+                .optional()
+                .describe("fetchMigration 可选，默认 false。true=覆盖本地已存在的同名 SQL 文件（对齐 CLI tcb db pg migration fetch --force）；false=跳过已存在文件。用于从远端 history 重新对齐 Git checksum。"),
+            includeAll: zod_1.z
+                .boolean()
+                .optional()
+                .describe("planMigration / applyMigration 可选，默认 false。true=允许 out-of-order（version 小于远端 LatestVersion）仍可 Preview/Push，对齐 CLI tcb db pg migration up --include-all；仅在确认要补历史/乱序迁移时使用，日常应选更大的 migrationVersion。"),
             allowDdlViaExecute: zod_1.z
                 .boolean()
                 .optional()
@@ -14507,6 +15434,8 @@ function registerPGDatabaseTools(server, providedDeps) {
             case "applyMigration":
             case "listMigrations":
             case "migrationDetail":
+            case "describeMigrationTask":
+            case "fetchMigration":
             case "rollbackMigration":
             case "repairMigration": {
                 switch (args.action) {
@@ -14514,6 +15443,8 @@ function registerPGDatabaseTools(server, providedDeps) {
                     case "applyMigration": return handleApplyMigration(args, context, deps, cbOpts);
                     case "listMigrations": return handleListMigrations(args, context, deps, cbOpts);
                     case "migrationDetail": return handleMigrationDetail(args, context, deps, cbOpts);
+                    case "describeMigrationTask": return handleDescribeMigrationTask(args, context, deps, cbOpts);
+                    case "fetchMigration": return handleFetchMigration(args, context, deps, cbOpts);
                     case "rollbackMigration": return handleRollbackMigration(args, context, deps, cbOpts);
                     case "repairMigration": return handleRepairMigration(args, context, deps, cbOpts);
                     default: return buildPgToolResult({ success: false, errorCode: "UNSUPPORTED_ACTION", message: `Unsupported action: ${args.action}` });
@@ -14566,7 +15497,7 @@ function buildWriteVerificationHint(resourceId) {
     return `对于 ${resourceId} 这类有后端权限控制的集合，前端调用 .doc(id).update() / .doc(id).remove() 后，不能只看是否没有抛异常。请显式检查返回结果中的 updated / deleted 是否大于 0；如果 result.code、result.message 存在，或 updated / deleted 为 0，要把它当作真实失败并向上抛错。`;
 }
 function buildPermissionPropagationHint(resourceId) {
-    return `刚更新完 ${resourceId} 的安全规则时，后端权限可能需要一小段传播时间。若紧接着的真实写操作仍返回 DATABASE_PERMISSION_DENIED，请先等待一小段时间，再用同一登录态重试同一条 .doc(id).update() / .doc(id).remove()；不要立刻连续重写规则，也不要在传播窗口里把旧拒绝直接当成规则表达式仍然错误。`;
+    return `刚更新完 ${resourceId} 的安全规则时，后端权限通常在数秒到约 30 秒内生效。若紧接着的真实写操作仍返回 DATABASE_PERMISSION_DENIED，请先间隔数秒用同一登录态重试同一条 .doc(id).update() / .doc(id).remove()；不要盲等数分钟，也不要立刻连续重写规则，更不要在短暂传播窗口里把旧拒绝直接当成规则表达式仍然错误。`;
 }
 function buildEnvelope(data, message) {
     return {
@@ -14591,6 +15522,171 @@ function mapResourceType(resourceType) {
     };
     return resourceTypeMap[resourceType];
 }
+/**
+ * Platform ModifyResourcePermission / DescribeResourcePermission reject PG envs.
+ * CLI migrated `tcb permission` → `tcb policy` (OPA Rego via
+ * permission.modifyEnvAuthzConfig / describeEnvAuthzConfig).
+ */
+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);
+}
+/** Detect legacy function securityRule shapes that mean "public invoke". */
+function isPublicFunctionInvokeRule(securityRule) {
+    if (!securityRule || securityRule.trim() === "") {
+        return false;
+    }
+    const trimmed = securityRule.trim();
+    if (trimmed === "true") {
+        return true;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed === true || parsed === "true") {
+            return true;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return false;
+        }
+        const obj = parsed;
+        if (obj.invoke === true || obj.invoke === "true") {
+            return true;
+        }
+        for (const value of Object.values(obj)) {
+            if (value &&
+                typeof value === "object" &&
+                !Array.isArray(value) &&
+                (value.invoke === true ||
+                    value.invoke === "true")) {
+                return true;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+/**
+ * Build a CLI-aligned user Rego that opens cloud-function access for
+ * anonymous + unauthenticated callers (tcb policy set example + HTTP no-token).
+ */
+function buildPublicFunctionsUserRego(resourceId) {
+    const comment = resourceId && resourceId !== "*"
+        ? `# Public HTTP/API access for function ${resourceId} (aligned with tcb policy set)`
+        : `# Public HTTP/API access for cloud functions (aligned with tcb policy set)`;
+    return [
+        "package authz.user",
+        "",
+        "default allow := false",
+        "",
+        comment,
+        "allow if {",
+        '  input.cloudbase.resource_type == "functions"',
+        '  input.subject.auth_type in {"anonymous", "unauthenticated"}',
+        "}",
+        "",
+    ].join("\n");
+}
+function resolveFunctionAuthzRegoInput(securityRule, resourceId) {
+    if (securityRule && looksLikeUserRego(securityRule)) {
+        return securityRule;
+    }
+    if (isPublicFunctionInvokeRule(securityRule)) {
+        return buildPublicFunctionsUserRego(resourceId);
+    }
+    throw new Error(`PostgreSQL environments manage HTTP/function gateway auth via OPA Rego ` +
+        `(same as CLI \`tcb policy set\`), not ModifyResourcePermission / function security-rule JSON. ` +
+        `Pass either:\n` +
+        `1) permission="CUSTOM" with securityRule as a full Rego document starting with \`package authz.user\`, or\n` +
+        `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) {
+    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 value = typeof result?.Item?.Value === "string"
+        ? result.Item.Value
+        : typeof result?.Value === "string"
+            ? result.Value
+            : "";
+    return { value, raw: result };
+}
+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.");
+    }
+    return cloudbase.permission.modifyEnvAuthzConfig({
+        key: AUTHZ_USER_REGO_KEY,
+        value,
+    });
+}
+async function describeResourcePermissionWithFunctionPgFallback(options) {
+    const { cloudbase, envId, resourceType, resources } = options;
+    try {
+        const result = await cloudbase.permission.describeResourcePermission({
+            resourceType: mapResourceType(resourceType),
+            resources,
+        });
+        return result;
+    }
+    catch (error) {
+        if (resourceType !== "function" || !isPostgresqlPermissionApiUnsupported(error)) {
+            throw error;
+        }
+        const fallback = await describeEnvAuthzUserRego(cloudbase);
+        const targets = resources && resources.length > 0 ? resources : ["*"];
+        const permissionList = targets.map((resourceId) => ({
+            ResourceType: "function",
+            Resource: resourceId,
+            Permission: "CUSTOM",
+            SecurityRule: fallback.value || "",
+        }));
+        return {
+            Data: {
+                TotalCount: permissionList.length,
+                PermissionList: permissionList,
+            },
+            RequestId: fallback.raw?.RequestId,
+            fallback: "describeEnvAuthzConfig",
+            raw: fallback.raw,
+        };
+    }
+}
+async function modifyFunctionPermissionWithPgFallback(options) {
+    const { cloudbase, resourceId, permission, securityRule } = options;
+    try {
+        const result = await cloudbase.permission.modifyResourcePermission({
+            resourceType: "function",
+            resource: resourceId,
+            permission,
+            securityRule,
+        });
+        return { result };
+    }
+    catch (error) {
+        if (!isPostgresqlPermissionApiUnsupported(error)) {
+            throw error;
+        }
+        if (permission !== "CUSTOM") {
+            throw new Error(`PostgreSQL environments do not support ModifyResourcePermission. ` +
+                `Align with CLI \`tcb policy set\`: use permission="CUSTOM" and pass OPA Rego ` +
+                `(package authz.user) or securityRule='{"invoke":true}' for public functions. ` +
+                `Underlying error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const rego = resolveFunctionAuthzRegoInput(securityRule, resourceId);
+        const result = await modifyEnvAuthzUserRego(cloudbase, rego);
+        return { result, fallback: "modifyEnvAuthzConfig", rego };
+    }
+}
 function normalizeRecordArray(value, label) {
     if (value === undefined) {
         return undefined;
@@ -14766,7 +15862,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 权限。",
+        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`）。",
         inputSchema: {
             action: zod_1.z.enum(QUERY_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -14798,8 +15894,10 @@ function registerPermissionTools(server) {
                 if (resourceType === "storage") {
                     await ensureStorageBucketsExist(cloudbase, [resourceId]);
                 }
-                const result = await cloudbase.permission.describeResourcePermission({
-                    resourceType: mapResourceType(resourceType),
+                const result = await describeResourcePermissionWithFunctionPgFallback({
+                    cloudbase,
+                    envId,
+                    resourceType,
                     resources: [resourceId],
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -14815,8 +15913,11 @@ function registerPermissionTools(server) {
                     aclTag: matchedPermission?.Permission,
                     permissions,
                     hints,
-                    raw: result,
-                }, "资源权限查询成功");
+                    ...(result.fallback ? { fallback: result.fallback } : {}),
+                    raw: result.raw ?? result,
+                }, result.fallback
+                    ? "资源权限查询成功（PostgreSQL 环境已回退到 describeEnvAuthzConfig / tcb policy get）"
+                    : "资源权限查询成功");
             }
             case "listResourcePermissions": {
                 if (!resourceType) {
@@ -14825,8 +15926,10 @@ function registerPermissionTools(server) {
                 if (resourceType === "storage" && resourceIds?.length) {
                     await ensureStorageBucketsExist(cloudbase, resourceIds);
                 }
-                const result = await cloudbase.permission.describeResourcePermission({
-                    resourceType: mapResourceType(resourceType),
+                const result = await describeResourcePermissionWithFunctionPgFallback({
+                    cloudbase,
+                    envId,
+                    resourceType,
                     resources: resourceIds,
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -14847,8 +15950,11 @@ function registerPermissionTools(server) {
                     permissions,
                     resourceHints,
                     total: result.Data.TotalCount ?? 0,
-                    raw: result,
-                }, "资源权限列表查询成功");
+                    ...(result.fallback ? { fallback: result.fallback } : {}),
+                    raw: result.raw ?? result,
+                }, result.fallback
+                    ? "资源权限列表查询成功（PostgreSQL 环境已回退到 describeEnvAuthzConfig / tcb policy get）"
+                    : "资源权限列表查询成功");
             }
             case "listRoles": {
                 const result = await cloudbase.permission.describeRoleList({
@@ -14927,7 +16033,7 @@ function registerPermissionTools(server) {
     }));
     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\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`）。",
+        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 相同。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -14975,12 +16081,29 @@ function registerPermissionTools(server) {
                 if (!resourceType || !resourceId || !permission) {
                     throw new Error("action=updateResourcePermission 时必须提供 resourceType、resourceId 和 permission");
                 }
-                const result = await cloudbase.permission.modifyResourcePermission({
-                    resourceType: mapResourceType(resourceType),
-                    resource: resourceId,
-                    permission,
-                    securityRule,
-                });
+                let result;
+                let fallback;
+                let appliedRego;
+                if (resourceType === "function") {
+                    const updated = await modifyFunctionPermissionWithPgFallback({
+                        cloudbase,
+                        envId,
+                        resourceId,
+                        permission,
+                        securityRule,
+                    });
+                    result = updated.result;
+                    fallback = updated.fallback;
+                    appliedRego = updated.rego;
+                }
+                else {
+                    result = await cloudbase.permission.modifyResourcePermission({
+                        resourceType: mapResourceType(resourceType),
+                        resource: resourceId,
+                        permission,
+                        securityRule,
+                    });
+                }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 const hints = permission === "CUSTOM" ? buildPermissionHints(securityRule, resourceId) : [];
                 return buildEnvelope({
@@ -14990,6 +16113,8 @@ function registerPermissionTools(server) {
                     resourceId,
                     permission,
                     hints,
+                    ...(fallback ? { fallback } : {}),
+                    ...(appliedRego ? { rego: appliedRego } : {}),
                     verificationHint: resourceType === "noSqlDatabase" && permission === "CUSTOM"
                         ? buildWriteVerificationHint(resourceId)
                         : undefined,
@@ -14997,7 +16122,9 @@ function registerPermissionTools(server) {
                         ? buildPermissionPropagationHint(resourceId)
                         : undefined,
                     raw: result,
-                }, "资源权限更新成功");
+                }, fallback
+                    ? "资源权限更新成功（PostgreSQL 环境已回退到 modifyEnvAuthzConfig / tcb policy set）"
+                    : "资源权限更新成功");
             }
             case "createRole": {
                 if (!roleName || !roleIdentity) {
@@ -15616,7 +16743,7 @@ function registerSetupTools(server) {
     server.registerTool("downloadTemplate", {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。
-**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.25.4" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.25.6" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])