@cloudbase/cloudbase-mcp 2.25.5 → 2.25.6

package/dist/index.cjs

@@ -1962,13 +1962,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: {
@@ -1987,13 +1987,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: {
@@ -3701,7 +3701,7 @@ function registerEnvTools(server) {
     if (server.ide !== 'wxide') {
         server.registerTool?.("envDomainManagement", {
             title: "CloudBase 环境域名管理（安全域名 / CORS 白名单）",
-            description: "管理 CloudBase 环境的安全域名（安全域名 / CORS 白名单），支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 直接访问 CloudBase 资源时，应先用 queryEnv(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。新增或删除后通常需要继续轮询 queryEnv(action=domains) 确认状态收敛；安全域名一般约 10 分钟生效。⚠️ 重要：此工具仅用于 CORS/请求来源验证，不涉及 SSL 证书。自定义域名公网 HTTPS：先 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"])
@@ -63516,6 +63516,177 @@ class DatabaseService {
         }
         return this.dbOpService.request('ExecutePGSql', params);
     }
+    /**
+     * 预览 PG 用户 migrations 的远端执行计划（不实际执行 SQL）
+     * @param options 预览参数
+     * @returns 预览结果（Pending、Applied、Conflicts、Executable）
+     */
+    async previewPGUserMigrations(options) {
+        var _a;
+        const { EnvId, Migrations, IncludeAll } = options;
+        if (!Array.isArray(Migrations) || Migrations.length === 0) {
+            throw new error_1.CloudBaseError('Migrations 至少需要 1 条');
+        }
+        for (const migration of Migrations) {
+            if (!/^\d{14}$/.test(migration.Version)) {
+                throw new error_1.CloudBaseError('Migration.Version 必须是 14 位数字');
+            }
+            if (!/^[a-z_]+$/.test(migration.Name)) {
+                throw new error_1.CloudBaseError('Migration.Name 只允许小写字母和下划线');
+            }
+            if (!((_a = migration.Query) === null || _a === void 0 ? void 0 : _a.trim())) {
+                throw new error_1.CloudBaseError('Migration.Query 不能为空');
+            }
+        }
+        return this.dbOpService.request('PreviewPGUserMigrations', Object.assign({ EnvId: EnvId || this.envId, Migrations }, (IncludeAll !== undefined ? { IncludeAll } : {})));
+    }
+    /**
+     * 批量应用 PG 用户 migrations
+     * @param options 批量 migration 参数
+     * @returns 任务信息（TaskId、RequestId）
+     */
+    async pushPGUserMigrations(options) {
+        var _a;
+        const { EnvId, Migrations, LockTimeoutMs, StatementTimeoutMs, IncludeAll } = options;
+        if (!Array.isArray(Migrations) || Migrations.length === 0) {
+            throw new error_1.CloudBaseError('Migrations 至少需要 1 条');
+        }
+        for (const migration of Migrations) {
+            if (!/^\d{14}$/.test(migration.Version)) {
+                throw new error_1.CloudBaseError('Migration.Version 必须是 14 位数字');
+            }
+            if (!/^[a-z_]+$/.test(migration.Name)) {
+                throw new error_1.CloudBaseError('Migration.Name 只允许小写字母和下划线');
+            }
+            if (!((_a = migration.Query) === null || _a === void 0 ? void 0 : _a.trim())) {
+                throw new error_1.CloudBaseError('Migration.Query 不能为空');
+            }
+        }
+        if (LockTimeoutMs !== undefined && LockTimeoutMs < 0) {
+            throw new error_1.CloudBaseError('LockTimeoutMs 不能小于 0');
+        }
+        if (StatementTimeoutMs !== undefined && StatementTimeoutMs < 0) {
+            throw new error_1.CloudBaseError('StatementTimeoutMs 不能小于 0');
+        }
+        return this.dbOpService.request('PushPGUserMigrations', Object.assign(Object.assign(Object.assign({ EnvId: EnvId || this.envId, Migrations }, (LockTimeoutMs !== undefined ? { LockTimeoutMs } : {})), (StatementTimeoutMs !== undefined ? { StatementTimeoutMs } : {})), (IncludeAll !== undefined ? { IncludeAll } : {})));
+    }
+    /**
+     * 修复 PG 用户 migration history，仅维护 user_schema_migrations 记录，不执行 SQL
+     * @param options 修复参数
+     * @returns RequestId
+     */
+    async repairPGUserMigrationHistory(options) {
+        const { EnvId, MigrationVersion, Name, Status, Reason, Query } = options;
+        if (!/^\d{14}$/.test(MigrationVersion)) {
+            throw new error_1.CloudBaseError('MigrationVersion 必须是 14 位数字');
+        }
+        if (!/^[a-z_]+$/.test(Name)) {
+            throw new error_1.CloudBaseError('Name 只允许小写字母和下划线');
+        }
+        if (Status !== 'applied' && Status !== 'reverted') {
+            throw new error_1.CloudBaseError('Status 只允许 applied 或 reverted');
+        }
+        if (!(Reason === null || Reason === void 0 ? void 0 : Reason.trim())) {
+            throw new error_1.CloudBaseError('Reason 不能为空');
+        }
+        if (Status === 'applied' && !(Query === null || Query === void 0 ? void 0 : Query.trim())) {
+            throw new error_1.CloudBaseError('Status=applied 时 Query 不能为空');
+        }
+        const params = {
+            EnvId: EnvId || this.envId,
+            MigrationVersion,
+            Name,
+            Status,
+            Reason
+        };
+        if (Status === 'applied') {
+            params.Query = Query;
+        }
+        return this.dbOpService.request('RepairPGUserMigrationHistory', params);
+    }
+    /**
+     * 查询目标环境已应用的用户 migration 列表
+     * @param options 查询参数（EnvId 可选、Limit、Offset）
+     * @returns 已应用 migration 列表、总数量、最新版本号
+     */
+    async listPGUserMigrations(options = {}) {
+        const { EnvId, Limit, Offset } = options;
+        if (Limit !== undefined && (Limit < 1 || Limit > 500)) {
+            throw new error_1.CloudBaseError('Limit 取值范围为 [1, 500]');
+        }
+        if (Offset !== undefined && Offset < 0) {
+            throw new error_1.CloudBaseError('Offset 不能小于 0');
+        }
+        return this.dbOpService.request('ListPGUserMigrations', Object.assign(Object.assign({ EnvId: EnvId || this.envId }, (Limit !== undefined ? { Limit } : {})), (Offset !== undefined ? { Offset } : {})));
+    }
+    /**
+     * 查询目标环境全部已应用的用户 migration 列表
+     * @param options 查询参数（EnvId 可选、PageSize）
+     * @returns 已应用 migration 列表、总数量、最新版本号
+     */
+    async listAllPGUserMigrations(options = {}) {
+        const { EnvId, PageSize = 500 } = options;
+        if (PageSize < 1 || PageSize > 500) {
+            throw new error_1.CloudBaseError('PageSize 取值范围为 [1, 500]');
+        }
+        const migrations = [];
+        let offset = 0;
+        let latestVersion = '';
+        let total = 0;
+        let requestId = '';
+        while (true) {
+            const page = await this.listPGUserMigrations({
+                EnvId,
+                Limit: PageSize,
+                Offset: offset
+            });
+            const pageMigrations = page.Migrations || [];
+            migrations.push(...pageMigrations);
+            latestVersion = page.LatestVersion || latestVersion;
+            total += pageMigrations.length;
+            requestId = page.RequestId || requestId;
+            if (pageMigrations.length < PageSize) {
+                break;
+            }
+            offset += PageSize;
+        }
+        return {
+            Total: total,
+            LatestVersion: latestVersion,
+            Migrations: migrations,
+            RequestId: requestId
+        };
+    }
+    /**
+     * 查询目标环境指定 migration 详情
+     * @param options 查询参数（EnvId 可选、MigrationVersion 必填）
+     * @returns migration 详情（Version、Name、Query）
+     */
+    async describePGUserMigration(options) {
+        const { EnvId, MigrationVersion } = options;
+        if (!/^\d{14}$/.test(MigrationVersion)) {
+            throw new error_1.CloudBaseError('MigrationVersion 必须是 14 位数字');
+        }
+        return this.dbOpService.request('DescribePGUserMigration', {
+            EnvId: EnvId || this.envId,
+            MigrationVersion
+        });
+    }
+    /**
+     * 查询任务结果
+     * @param options 查询参数（EnvId 可选、TaskId 必填）
+     * @returns 任务状态详情（TaskType、Status、Phase、Reason 等）
+     */
+    async describeTaskResult(options) {
+        const { EnvId, TaskId } = options;
+        if (!(TaskId === null || TaskId === void 0 ? void 0 : TaskId.trim())) {
+            throw new error_1.CloudBaseError('TaskId 不能为空');
+        }
+        return this.dbOpService.request('DescribeTaskResult', {
+            EnvId: EnvId || this.envId,
+            TaskId
+        });
+    }
 }
 exports.DatabaseService = DatabaseService;
 DatabaseService.tcbServiceVersion = {
@@ -63559,6 +63730,27 @@ __decorate([
 __decorate([
     preLazy()
 ], DatabaseService.prototype, "executePGSql", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "previewPGUserMigrations", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "pushPGUserMigrations", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "repairPGUserMigrationHistory", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "listPGUserMigrations", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "listAllPGUserMigrations", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describePGUserMigration", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describeTaskResult", null);
 
 
 /***/ }),
@@ -90876,6 +91068,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;
@@ -91104,6 +91297,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 [];
@@ -91570,7 +91776,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": {
@@ -92276,7 +92487,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("配置更新时的超时时间"),
@@ -106113,7 +106329,7 @@ class CloudAppService {
      * @param params 上传参数
      */
     async uploadCode(params) {
-        const { serviceName, localPath, ignore = [] } = params;
+        const { serviceName, localPath, ignore = [], onPhase } = params;
         // 1. 验证本地路径
         if (!fs_1.default.existsSync(localPath)) {
             throw new error_1.CloudBaseError(`本地路径不存在: ${localPath}`);
@@ -106125,20 +106341,27 @@ class CloudAppService {
         // 2. 打包本地文件为 ZIP
         const tmpZipPath = path_1.default.join(os_1.default.tmpdir(), `cloudapp-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`);
         const defaultIgnore = ['node_modules/**', '.git/**', '.DS_Store', '**/.DS_Store'];
+        const packStart = Date.now();
         await (0, utils_1.compressToZip)({
             dirPath: localPath,
             outputPath: tmpZipPath,
             ignore: [...defaultIgnore, ...ignore]
         });
+        const zipSize = fs_1.default.statSync(tmpZipPath).size;
+        onPhase === null || onPhase === void 0 ? void 0 : onPhase({ phase: 'pack', durationMs: Date.now() - packStart, bytes: zipSize });
         try {
             // 3. 获取上传凭证
+            const credStart = Date.now();
             const cosInfo = await this.describeCosInfo({
                 deployType: params.deployType,
                 serviceName,
                 suffix: '.zip'
             });
+            onPhase === null || onPhase === void 0 ? void 0 : onPhase({ phase: 'credential', durationMs: Date.now() - credStart });
             // 4. 读取 ZIP 文件
+            const readStart = Date.now();
             const zipBuffer = fs_1.default.readFileSync(tmpZipPath);
+            onPhase === null || onPhase === void 0 ? void 0 : onPhase({ phase: 'read', durationMs: Date.now() - readStart, bytes: zipBuffer.length });
             // 5. 构建请求头
             const headers = {
                 'Content-Type': 'application/zip'
@@ -106149,6 +106372,7 @@ class CloudAppService {
                 }
             }
             // 6. 使用预签名 URL 上传
+            const putStart = Date.now();
             const response = await (0, http_request_1.fetchStream)(cosInfo.UploadUrl, {
                 method: 'PUT',
                 body: zipBuffer,
@@ -106165,6 +106389,7 @@ class CloudAppService {
                 }
                 throw new error_1.CloudBaseError(`上传失败: ${response.status} ${response.statusText}${errorDetail}`);
             }
+            onPhase === null || onPhase === void 0 ? void 0 : onPhase({ phase: 'upload', durationMs: Date.now() - putStart, bytes: zipBuffer.length });
             // 7. 返回结果（返回 cosTimestamp，用于创建应用）
             return {
                 cosTimestamp: cosInfo.UnixTimestamp,
@@ -138355,7 +138580,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.5" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.6" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -162049,13 +162274,48 @@ exports["default"] = applicator;
 /***/ }),
 
 /***/ 56473:
-/***/ ((__unused_webpack_module, exports, __webpack_require__) => {
+/***/ (function(__unused_webpack_module, exports, __webpack_require__) {
 
 "use strict";
 
+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__(29021));
+const path = __importStar(__webpack_require__(39902));
 const zod_1 = __webpack_require__(21614);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const tool_result_js_1 = __webpack_require__(9835);
@@ -162076,6 +162336,8 @@ const MANAGE_ACTIONS = [
     "applyMigration",
     "listMigrations",
     "migrationDetail",
+    "describeMigrationTask",
+    "fetchMigration",
     "rollbackMigration",
     "repairMigration",
 ];
@@ -162236,8 +162498,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;
@@ -162272,10 +162696,27 @@ const MIGRATION_VERIFY_DELAY_MS = 1500;
 const MIGRATION_LIST_PAGE_SIZE = 100;
 /**
  * PushPGUserMigrations is async: poll DescribeTaskResult until Succeed/Failed.
- * Aligns with CLI `tcb db pg migration up` and Manager SDK docs.
+ * 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;
-const MIGRATION_TASK_MAX_WAIT_MS = 90_000;
+/** 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.
  *
@@ -162359,12 +162800,114 @@ async function listAllRemoteMigrationSummaries(context, cloudBaseOptions) {
     }
     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;
+}
 /**
- * Build Push/Preview Migrations = remote history Queries + the pending migration.
- * Matches CLI behavior (submit full set; server skips already-applied versions).
+ * 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) {
@@ -162384,10 +162927,23 @@ async function buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBa
         });
     }
     migrations.push(pending);
-    return { migrations, remoteCount: summaries.length, latestVersion };
+    return {
+        migrations,
+        remoteCount: summaries.length,
+        latestVersion,
+        payloadSource: "hydrate",
+    };
 }
-async function waitPgMigrationTask(context, taskId, cloudBaseOptions) {
-    const deadline = Date.now() + MIGRATION_TASK_MAX_WAIT_MS;
+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));
@@ -162397,13 +162953,21 @@ async function waitPgMigrationTask(context, taskId, cloudBaseOptions) {
         }
         await sleep(MIGRATION_TASK_POLL_INTERVAL_MS);
     }
-    const error = new Error(`DescribeTaskResult timed out after ${Math.floor(MIGRATION_TASK_MAX_WAIT_MS / 1000)}s ` +
+    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();
@@ -162740,6 +163304,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" &&
@@ -162780,13 +163368,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.");
     }
@@ -163027,11 +163624,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).", {
@@ -163140,7 +163737,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: [
@@ -163198,10 +163795,13 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
     }
     try {
         const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
+        const includeAll = Boolean(args.includeAll);
         const result = await callPgMigrationApi(context, "PreviewPGUserMigrations", {
             Migrations: hydrated.migrations,
+            IncludeAll: includeAll,
         }, cloudBaseOptions);
         const executable = result.Executable === true;
+        const payloadSourceLabel = formatMigrationsPayloadSourceLabel(hydrated.payloadSource, hydrated.remoteCount);
         return buildPgToolResult({
             success: true,
             data: {
@@ -163210,22 +163810,25 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
                 localFileHint,
                 hydratedRemoteCount: hydrated.remoteCount,
                 latestRemoteVersion: hydrated.latestVersion || null,
+                payloadSource: hydrated.payloadSource,
+                includeAll,
                 executable,
                 apiResult: result,
             },
             message: executable
-                ? `Migration plan generated via PreviewPGUserMigrations (hydrated ${hydrated.remoteCount} remote migration(s)). Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`
-                : `Migration plan is NOT executable (PreviewPGUserMigrations.Executable=false after hydrating ${hydrated.remoteCount} remote migration(s)). Inspect apiResult.Conflicts before applyMigration. Common causes: version older than latest remote (${hydrated.latestVersion || "unknown"}), or checksum mismatch.`,
+                ? `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", executable
                     ? "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion."
-                    : "Resolve Conflicts (often pick a migrationVersion newer than LatestVersion), then retry planMigration/applyMigration.", {
+                    : "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 } : {}),
                 }),
             ],
         });
@@ -163266,6 +163869,33 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
+    // 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,
@@ -163274,12 +163904,14 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     if (args.rollbackSql?.trim()) {
         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). Hydrate remote Queries first,
-        // matching CLI `tcb db pg migration up` (full list; server skips applied).
+        // 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 preview = await callPgMigrationApi(context, "PreviewPGUserMigrations", { Migrations: hydrated.migrations }, 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,
@@ -163290,27 +163922,33 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     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"}, hydratedRemoteCount=${hydrated.remoteCount}). ` +
+                    `(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 checksum_mismatch. " +
+                    "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.", {
+                    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 };
+        const params = {
+            Migrations: hydrated.migrations,
+            IncludeAll: includeAll,
+        };
         if (args.lockTimeoutMs !== undefined) {
             params.LockTimeoutMs = args.lockTimeoutMs;
         }
@@ -163319,10 +163957,35 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
         }
         const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
         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);
+                taskResult = await waitPgMigrationTask(context, taskId, cloudBaseOptions, pollTimeoutMs);
             }
             catch (error) {
                 const lastTask = error.lastTask;
@@ -163336,14 +163999,16 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                         hydratedRemoteCount: hydrated.remoteCount,
                         apiResult: result,
                         taskResult: lastTask ?? { TaskId: taskId },
+                        taskPollTimeoutMs: pollTimeoutMs,
                         verified: null,
                     },
-                    message: `PushPGUserMigrations returned TaskId=${taskId}, but waiting for DescribeTaskResult timed out: ` +
-                        `${error instanceof Error ? error.message : String(error)}. ` +
-                        "The migration may still be running — check action=listMigrations before retrying or falling back to execute.",
-                    nextActions: [
-                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check whether the migrationVersion eventually landed.", { action: "listMigrations", limit: 20 }),
-                    ],
+                    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();
@@ -163371,6 +164036,7 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                             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 }),
                     ],
@@ -163388,6 +164054,7 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationName: args.migrationName,
                     localFileHint,
                     hydratedRemoteCount: hydrated.remoteCount,
+                    includeAll,
                     apiResult: result,
                     taskResult: taskResult,
                     verified: false,
@@ -163428,12 +164095,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 (hydrated ${hydrated.remoteCount} remote migration(s)), task ${taskId ? `TaskId=${taskId} ` : ""}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) {
@@ -163494,6 +164167,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({
@@ -163708,11 +164531,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()
@@ -163750,7 +164573,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()
@@ -163784,6 +164607,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()
@@ -163792,6 +164630,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()
@@ -163839,6 +164685,8 @@ function registerPGDatabaseTools(server, providedDeps) {
             case "applyMigration":
             case "listMigrations":
             case "migrationDetail":
+            case "describeMigrationTask":
+            case "fetchMigration":
             case "rollbackMigration":
             case "repairMigration": {
                 switch (args.action) {
@@ -163846,6 +164694,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}` });
@@ -185308,7 +186158,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) => {
@@ -193701,10 +194551,11 @@ class AgentService {
     // ==================== 日志查询方法 ====================
     /**
      * 获取 Agent 调用日志（自动判断类型）
+     *
+     * SCF / TCBR 均直接走 CLS `searchClsLog`，返回 CLS 原始检索结果 `ISearchClsLogResponse`。
+     * 分页请透传上次返回的 `LogResults.Context` 到入参 `context`。
      * @param params 查询参数
-     * @returns 日志结果，根据 Agent 类型返回不同结构：
-     *   - SCF: IFunctionLogDetailRes[]
-     *   - TCBR: ISearchClsLogResponse
+     * @returns CLS 检索结果 ISearchClsLogResponse
      * @example
      * ```typescript
      * const logs = await agentService.getAgentLogs({
@@ -193724,25 +194575,18 @@ class AgentService {
         }
         const agentInfo = agentListRes.AgentList[0];
         const agentType = agentInfo.AgentType;
-        // 2. 根据 Agent 类型获取日志
-        if (agentType === 'scf') {
-            const functionService = this.environment.getFunctionService();
-            return functionService.getCompleteFunctionLogs({
-                name: AgentId,
-                offset: params.offset,
-                limit: params.limit,
-                startTime: params.startTime,
-                endTime: params.endTime,
-                requestId: params.requestId
-            });
-        }
-        else if (agentType === 'tcbr') {
+        //    scf / tcbr 均直接走 CLS searchClsLog（getFunctionLogs 系列接口已下线）
+        if (agentType === 'scf' || agentType === 'tcbr') {
             const logService = this.environment.getLogService();
-            const { startTime, endTime, limit = 100, requestId } = params;
+            const { startTime, endTime, limit = 100, requestId, context, sort } = params;
             // 构建查询语句
-            let queryString = `SCF_FunctionName:${AgentId}`;
+            // 采用双引号短语检索保证精确匹配（AgentId/RequestId 含 '-' 会被分词，
+            // 不加引号会因分词命中相似 ID 的其它日志）；并对入参做转义，避免检索语法被注入。
+            // CLS 双引号短语检索下需转义 '"'、'*' 与 '\\'。
+            const escapeClsPhrase = (value) => value.replace(/["*\\]/g, '\\$&');
+            let queryString = `SCF_FunctionName:"${escapeClsPhrase(AgentId)}"`;
             if (requestId) {
-                queryString += ` AND SCF_RequestId:${requestId}`;
+                queryString += ` AND SCF_RequestId:"${escapeClsPhrase(requestId)}"`;
             }
             // 辅助函数：格式化时间
             const formatDateTime = (date) => {
@@ -193756,7 +194600,9 @@ class AgentService {
                 StartTime: startTime || defaultStartTime,
                 EndTime: endTime || defaultEndTime,
                 queryString: queryString,
-                Limit: limit > 100 ? 100 : limit
+                Limit: limit > 100 ? 100 : limit,
+                Context: context,
+                Sort: sort
             });
         }
         else {
@@ -197539,6 +198385,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.AccessService = void 0;
 const utils_1 = __webpack_require__(62358);
+/**
+ * HTTP Service（CloudBaseGW）访问服务。
+ * 注意：HTTP Service 模块自 v5.0.0 起已废弃，建议迁移到 EnvService 的域名与路由能力
+ * （如 createHttpServiceRoute / modifyHttpServiceRoute / deleteHttpServiceRoute）。
+ */
 class AccessService {
     constructor(environment) {
         this.environment = environment;
@@ -198976,7 +199827,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.5" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.6" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -199057,7 +199908,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.5" : 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}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -214477,7 +215328,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 {
@@ -214502,6 +215353,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;
@@ -214677,7 +215693,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
@@ -214709,8 +215725,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);
@@ -214726,8 +215744,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) {
@@ -214736,8 +215757,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);
@@ -214758,8 +215781,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({
@@ -214838,7 +215864,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
@@ -214886,12 +215912,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({
@@ -214901,6 +215944,8 @@ function registerPermissionTools(server) {
                     resourceId,
                     permission,
                     hints,
+                    ...(fallback ? { fallback } : {}),
+                    ...(appliedRego ? { rego: appliedRego } : {}),
                     verificationHint: resourceType === "noSqlDatabase" && permission === "CUSTOM"
                         ? buildWriteVerificationHint(resourceId)
                         : undefined,
@@ -214908,7 +215953,9 @@ function registerPermissionTools(server) {
                         ? buildPermissionPropagationHint(resourceId)
                         : undefined,
                     raw: result,
-                }, "资源权限更新成功");
+                }, fallback
+                    ? "资源权限更新成功（PostgreSQL 环境已回退到 modifyEnvAuthzConfig / tcb policy set）"
+                    : "资源权限更新成功");
             }
             case "createRole": {
                 if (!roleName || !roleIdentity) {
@@ -215645,7 +216692,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.5" : 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"])
@@ -232965,7 +234012,7 @@ function registerGatewayTools(server) {
         {
             tool: "queryGateway",
             action: "getRoute",
-            reason: "等待 30 秒到 3 分钟后再确认访问入口是否已生效",
+            reason: "创建后通常数秒到约 30 秒内生效；请立刻轮询 getRoute 或探测 accessUrl，勿盲等 60 秒以上",
         },
         {
             tool: "queryPermissions",
@@ -233113,7 +234160,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",
@@ -233149,7 +234196,7 @@ function registerGatewayTools(server) {
                         : payload.resolved.enablePathTransmission === false
                             ? "；路径透传关闭（网关会剥掉触发路径前缀后再转发给后端）"
                             : "；路径透传未显式设置（平台默认 false，会剥掉触发路径前缀）") +
-                    `。注意：路由配置传播通常需要等待 30 秒到 3 分钟，请勿立即访问。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。` +
+                    `。注意：路由配置传播通常数秒到约 30 秒；请立刻用 queryGateway(getRoute) 或探测 accessUrl 确认，勿盲等 60 秒以上。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。` +
                     (privilegeHint ? ` ${privilegeHint}` : ""), [
                     ...privilegeNextActions,
                     ...(routeMutationNextActions(payload.resolved.upstreamResourceName) ??
@@ -265760,6 +266807,10 @@ class CloudBase {
     get hosting() {
         return this.currentEnvironment().getHostingService();
     }
+    /**
+     * HTTP Service（CloudBaseGW）访问服务
+     * @deprecated 自 v5.0.0 起 HTTP Service 模块已废弃，请改用 env 下的域名与路由相关 API。
+     */
     get access() {
         return this.currentEnvironment().getAccessService();
     }
@@ -267872,48 +268923,27 @@ class FunctionService {
         return data;
     }
     /**
-     * 获取函数日志
-     * @deprecated 请使用 getFunctionLogsV2 代替
-     * @param {{
-    *         name: string
-    *         offset: number
-    *         limit: number
-    *         order: string
-    *         orderBy: string
-    *         startTime: string
-    *         endTime: string
-    *         requestId: string
-    *     }} options
-    * @returns {Promise<IFunctionLogRes>}
-    */
-    async getFunctionLogs(options) {
-        let { name, offset = 0, limit = 10, order, orderBy, startTime, endTime, requestId } = options;
-        const { namespace } = this.getFunctionConfig();
-        if (startTime && !endTime) {
-            // 自动补 endTime 为 startTime + 1d
-            endTime = (0, utils_1.formatTimeByMs)(new Date(startTime).getTime() + 24 * 3600 * 1000);
-        }
-        if (endTime && !startTime) {
-            // 自动补 startTime 为 endTime - 1d
-            startTime = (0, utils_1.formatTimeByMs)(new Date(endTime).getTime() - 24 * 3600 * 1000);
-        }
-        const params = {
-            Namespace: namespace,
-            FunctionName: name,
-            Offset: offset,
-            Limit: limit,
-            Order: order,
-            OrderBy: orderBy,
-            StartTime: startTime,
-            EndTime: endTime,
-            FunctionRequestId: requestId
-        };
-        const res = await this.scfService.request('GetFunctionLogs', params);
-        return res;
-    }
-    /**
- * 获取函数日志 ID 列表
+ * 获取函数日志
+ * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
  * @param {{
+ *         name: string
+ *         offset: number
+ *         limit: number
+ *         order: string
+ *         orderBy: string
+ *         startTime: string
+ *         endTime: string
+ *         requestId: string
+ *     }} options
+ * @returns {Promise<IFunctionLogRes>}
+ */
+    async getFunctionLogs(_options) {
+        throw new error_1.CloudBaseError('getFunctionLogs 已废弃：底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志');
+    }
+    /**
+    * 获取函数日志 ID 列表
+    * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
+    * @param {{
     *         name: string
     *         offset: number
     *         limit: number
@@ -267924,28 +268954,12 @@ class FunctionService {
     *     }} options
     * @returns {Promise<IFunctionLogResV2>}
     */
-    async getFunctionLogsV2(options) {
-        let { name, offset = 0, limit = 10, startTime, endTime, requestId, qualifier } = options;
-        const { env } = this.getFunctionConfig();
-        ({ startTime, endTime } = (0, utils_1.getCompleteTimeRange)({
-            startTime,
-            endTime
-        }));
-        const params = {
-            EnvId: env,
-            FunctionName: name,
-            Offset: offset,
-            Limit: limit,
-            StartTime: startTime,
-            EndTime: endTime,
-            LogRequestId: requestId,
-            Qualifier: qualifier || "$LATEST" // 云函数版本，不传则用 $LATEST
-        };
-        const res = await this.tcbService.request('GetFunctionLogs', params);
-        return res;
+    async getFunctionLogsV2(_options) {
+        throw new error_1.CloudBaseError('getFunctionLogsV2 已废弃：底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志');
     }
     /**
  * 根据函数日志 ID 查询日志详情
+ * @deprecated 底层 GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
  * @param {{
     *         startTime: string
     *         endTime: string
@@ -267953,46 +268967,18 @@ class FunctionService {
     *     }} options
     * @returns {Promise<IFunctionLogDetailRes>}
     */
-    async getFunctionLogDetail(options) {
-        let { logRequestId, startTime, endTime } = options;
-        ({ startTime, endTime } = (0, utils_1.getCompleteTimeRange)({
-            startTime,
-            endTime
-        }));
-        const params = {
-            StartTime: startTime,
-            LogRequestId: logRequestId,
-            EndTime: endTime
-        };
-        const res = await this.tcbService.request('GetFunctionLogDetail', params);
-        return res;
+    async getFunctionLogDetail(_options) {
+        throw new error_1.CloudBaseError('getFunctionLogDetail 已废弃：底层 GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志');
     }
     /**
      * 获取函数的完整调用日志
      * 该方法会自动完成两步操作：1. 获取日志请求ID列表。 2. 根据ID列表获取每条日志的详细内容。
+     * @deprecated 底层 GetFunctionLogs/GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
      * @param {IFunctionLogOptionsV2} options - 查询选项
      * @returns {Promise<IFunctionLogDetailRes[]>} 返回包含完整日志详情的数组
      */
-    async getCompleteFunctionLogs(options) {
-        // 调用 getFunctionLogsV2 获取日志请求ID列表
-        const { name } = options;
-        const logs = await this.getFunctionLogsV2(options);
-        // 如果没有日志，直接返回空数组
-        if (logs.LogList.length === 0) {
-            return [];
-        }
-        const detailPromises = logs.LogList.map(async (log) => {
-            // 对每一个日志ID，调用 getFunctionLogDetail
-            const res = await this.getFunctionLogDetail({
-                logRequestId: log.RequestId,
-                startTime: options.startTime,
-                endTime: options.endTime
-            });
-            return Object.assign(Object.assign({}, res), { RetCode: log.RetCode, FunctionName: name });
-        });
-        // 并发执行所有详情查询，等待它们全部完成
-        const detailedLogs = await Promise.all(detailPromises);
-        return detailedLogs;
+    async getCompleteFunctionLogs(_options) {
+        throw new error_1.CloudBaseError('getCompleteFunctionLogs 已废弃：底层 GetFunctionLogs/GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志');
     }
     /**
      * 更新云函数配置