@cloudbase/cloudbase-mcp 2.23.10 → 2.24.0

package/dist/index.js

@@ -2200,7 +2200,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.23.10" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.24.0" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2281,7 +2281,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.23.10" : 0;
+            const mcpVersion =  true ? "2.24.0" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -7771,6 +7771,7 @@ const os = __importStar(__webpack_require__(8116));
 const path = __importStar(__webpack_require__(2521));
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
+const tool_result_js_1 = __webpack_require__(9835);
 const MAX_INLINE_TEXT_BYTES = 256 * 1024;
 const STORAGE_READ_TEMP_PREFIX = 'cloudbase-mcp-storage-read-';
 // Input schema for queryStorage tool
@@ -7853,7 +7854,7 @@ function registerStorageTools(server) {
     // Tool 1: queryStorage - 查询存储信息（只读操作）
     server.registerTool("queryStorage", {
         title: "查询 CloudBase 存储信息",
-        description: "查询 CloudBase 云存储信息，支持列出目录文件、获取文件信息、获取临时下载链接等只读操作。返回的文件信息包括文件名、大小、修改时间、下载链接等。注意：action=url 返回的 temporaryUrl 是临时签名链接，有效期由 maxAge 参数决定（默认1小时），不要当作永久公网地址使用。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。\n\n📦 CloudBase PG / pgstore 环境：`DescribeEnvs.Storages[]` 列出的 bucket 是旧 NoSQL 后端的，不等于 pgstore bucket。本工具用于查看常规存储；为 PG 浏览器上传准备 bucket 时，请确认目标 bucket 是 pgstore 后端可用的，否则浏览器 `app.storage.from().upload(...)` 会得到 `STORAGE_BUCKET_NOT_FOUND` 并出现 `PUT https://undefined/`。",
+        description: "⚠️ PG 模式环境请使用 queryPgStorage 而非本工具（pgstore 与旧 COS 是两套独立系统）。\n\n查询 CloudBase 云存储信息，支持列出目录文件、获取文件信息、获取临时下载链接等只读操作。返回的文件信息包括文件名、大小、修改时间、下载链接等。注意：action=url 返回的 temporaryUrl 是临时签名链接，有效期由 maxAge 参数决定（默认1小时），不要当作永久公网地址使用。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。\n\n📦 CloudBase PG / pgstore 环境：`DescribeEnvs.Storages[]` 列出的 bucket 是旧 NoSQL 后端的，不等于 pgstore bucket。本工具用于查看常规存储；为 PG 浏览器上传准备 bucket 时，请确认目标 bucket 是 pgstore 后端可用的，否则浏览器 `app.storage.from().upload(...)` 会得到 `STORAGE_BUCKET_NOT_FOUND` 并出现 `PUT https://undefined/`。",
         inputSchema: queryStorageInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -7862,125 +7863,89 @@ function registerStorageTools(server) {
         }
     }, async (args) => {
         const input = args;
-        const manager = await getManager();
-        if (!manager) {
-            throw new Error("Failed to initialize CloudBase manager. Please check your credentials and environment configuration.");
-        }
-        const storageService = manager.storage;
-        switch (input.action) {
-            case 'list': {
-                let files;
-                if (storageOverrides?.listFiles) {
-                    files = await storageOverrides.listFiles({ cloudPath: input.cloudPath });
-                }
-                else {
-                    const result = await storageService.listDirectoryFiles(input.cloudPath);
-                    files = result || [];
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'list',
-                                    cloudPath: input.cloudPath,
-                                    files,
-                                    totalCount: files.length
-                                },
-                                message: `Successfully listed ${files.length} files in directory '${input.cloudPath}'`
-                            }, null, 2)
-                        }
-                    ]
-                };
-            }
-            case 'info': {
-                let fileInfo;
-                if (storageOverrides?.getFileInfo) {
-                    fileInfo = await storageOverrides.getFileInfo({ cloudPath: input.cloudPath });
-                }
-                else {
-                    fileInfo = await storageService.getFileInfo(input.cloudPath);
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'info',
-                                    cloudPath: input.cloudPath,
-                                    fileInfo
-                                },
-                                message: `Successfully retrieved file info for '${input.cloudPath}'`
-                            }, null, 2)
-                        }
-                    ]
-                };
+        try {
+            const manager = await getManager();
+            if (!manager) {
+                throw new Error("Failed to initialize CloudBase manager. Please check your credentials and environment configuration.");
             }
-            case 'url': {
-                let temporaryUrl = "";
-                let fileId = "";
-                if (storageOverrides?.getFileUrl) {
-                    const urlResult = await storageOverrides.getFileUrl({
-                        cloudPath: input.cloudPath,
-                        maxAge: input.maxAge || 3600,
-                    });
-                    temporaryUrl = urlResult.url;
-                    fileId = urlResult.fileId || "";
-                }
-                else {
-                    const result = await storageService.getTemporaryUrl([{
-                            cloudPath: input.cloudPath,
-                            maxAge: input.maxAge || 3600
-                        }]);
-                    temporaryUrl = result[0]?.url || "";
-                    fileId = result[0]?.fileId || "";
+            const storageService = manager.storage;
+            switch (input.action) {
+                case 'list': {
+                    let files;
+                    if (storageOverrides?.listFiles) {
+                        files = await storageOverrides.listFiles({ cloudPath: input.cloudPath });
+                    }
+                    else {
+                        const result = await storageService.listDirectoryFiles(input.cloudPath);
+                        files = result || [];
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        action: 'list',
+                                        cloudPath: input.cloudPath,
+                                        files,
+                                        totalCount: files.length
+                                    },
+                                    message: `Successfully listed ${files.length} files in directory '${input.cloudPath}'`
+                                }, null, 2)
+                            }
+                        ]
+                    };
                 }
-                const publicAccess = await resolveStoragePublicAccess({
-                    cloudPath: input.cloudPath,
-                    cloudBaseOptions,
-                    manager,
-                });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'url',
-                                    cloudPath: input.cloudPath,
-                                    temporaryUrl,
-                                    expireTime: `${input.maxAge || 3600}秒`,
-                                    fileId,
-                                    storageCdnDomain: publicAccess.storageCdnDomain,
-                                    publicUrl: publicAccess.publicUrl,
-                                    note: "temporaryUrl 是临时签名链接，会按 expireTime 过期。publicUrl 基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导，⚠️ 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先将目标路径设置为公有读。"
-                                },
-                                message: `Successfully generated temporary URL for '${input.cloudPath}'`
-                            }, null, 2)
-                        }
-                    ]
-                };
-            }
-            case 'read': {
-                const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), STORAGE_READ_TEMP_PREFIX));
-                const localPath = path.join(tempDir, getStorageTempFileName(input.cloudPath));
-                try {
-                    if (storageOverrides?.downloadFile) {
-                        await storageOverrides.downloadFile({ cloudPath: input.cloudPath, localPath });
+                case 'info': {
+                    let fileInfo;
+                    if (storageOverrides?.getFileInfo) {
+                        fileInfo = await storageOverrides.getFileInfo({ cloudPath: input.cloudPath });
                     }
                     else {
-                        await storageService.downloadFile({
+                        fileInfo = await storageService.getFileInfo(input.cloudPath);
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        action: 'info',
+                                        cloudPath: input.cloudPath,
+                                        fileInfo
+                                    },
+                                    message: `Successfully retrieved file info for '${input.cloudPath}'`
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                case 'url': {
+                    let temporaryUrl = "";
+                    let fileId = "";
+                    if (storageOverrides?.getFileUrl) {
+                        const urlResult = await storageOverrides.getFileUrl({
                             cloudPath: input.cloudPath,
-                            localPath
+                            maxAge: input.maxAge || 3600,
                         });
+                        temporaryUrl = urlResult.url;
+                        fileId = urlResult.fileId || "";
                     }
-                    const buffer = await fs.readFile(localPath);
-                    const decoded = decodeInlineTextContent(buffer);
+                    else {
+                        const result = await storageService.getTemporaryUrl([{
+                                cloudPath: input.cloudPath,
+                                maxAge: input.maxAge || 3600
+                            }]);
+                        temporaryUrl = result[0]?.url || "";
+                        fileId = result[0]?.fileId || "";
+                    }
+                    const publicAccess = await resolveStoragePublicAccess({
+                        cloudPath: input.cloudPath,
+                        cloudBaseOptions,
+                        manager,
+                    });
                     return {
                         content: [
                             {
@@ -7988,33 +7953,80 @@ function registerStorageTools(server) {
                                 text: JSON.stringify({
                                     success: true,
                                     data: {
-                                        action: 'read',
+                                        action: 'url',
                                         cloudPath: input.cloudPath,
-                                        content: decoded.content,
-                                        encoding: decoded.encoding,
-                                        sizeBytes: decoded.sizeBytes,
-                                        truncated: decoded.truncated
+                                        temporaryUrl,
+                                        expireTime: `${input.maxAge || 3600}秒`,
+                                        fileId,
+                                        storageCdnDomain: publicAccess.storageCdnDomain,
+                                        publicUrl: publicAccess.publicUrl,
+                                        note: "temporaryUrl 是临时签名链接，会按 expireTime 过期。publicUrl 基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导，⚠️ 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先将目标路径设置为公有读。"
                                     },
-                                    message: decoded.truncated
-                                        ? `Successfully read text content for '${input.cloudPath}' (truncated to ${MAX_INLINE_TEXT_BYTES} bytes)`
-                                        : `Successfully read text content for '${input.cloudPath}'`
+                                    message: `Successfully generated temporary URL for '${input.cloudPath}'`
                                 }, null, 2)
                             }
                         ]
                     };
                 }
-                finally {
-                    await fs.rm(tempDir, { recursive: true, force: true });
+                case 'read': {
+                    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), STORAGE_READ_TEMP_PREFIX));
+                    const localPath = path.join(tempDir, getStorageTempFileName(input.cloudPath));
+                    try {
+                        if (storageOverrides?.downloadFile) {
+                            await storageOverrides.downloadFile({ cloudPath: input.cloudPath, localPath });
+                        }
+                        else {
+                            await storageService.downloadFile({
+                                cloudPath: input.cloudPath,
+                                localPath
+                            });
+                        }
+                        const buffer = await fs.readFile(localPath);
+                        const decoded = decodeInlineTextContent(buffer);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        success: true,
+                                        data: {
+                                            action: 'read',
+                                            cloudPath: input.cloudPath,
+                                            content: decoded.content,
+                                            encoding: decoded.encoding,
+                                            sizeBytes: decoded.sizeBytes,
+                                            truncated: decoded.truncated
+                                        },
+                                        message: decoded.truncated
+                                            ? `Successfully read text content for '${input.cloudPath}' (truncated to ${MAX_INLINE_TEXT_BYTES} bytes)`
+                                            : `Successfully read text content for '${input.cloudPath}'`
+                                    }, null, 2)
+                                }
+                            ]
+                        };
+                    }
+                    finally {
+                        await fs.rm(tempDir, { recursive: true, force: true });
+                    }
                 }
+                default:
+                    throw new Error(`Unsupported action: ${input.action}`);
             }
-            default:
-                throw new Error(`Unsupported action: ${input.action}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, tool_result_js_1.buildJsonToolResult)({
+                success: false,
+                message: `queryStorage 操作失败: ${message}`,
+                action: input.action,
+                cloudPath: input.cloudPath,
+            });
         }
     });
     // Tool 2: manageStorage - 管理存储文件（写操作）
     server.registerTool("manageStorage", {
         title: "管理 CloudBase 存储文件",
-        description: "管理 CloudBase 云存储文件，仅用于 COS/Storage 对象，不用于静态网站托管。支持上传文件/目录、下载文件/目录、删除文件/目录等操作。删除操作需要设置force=true进行确认，防止误删除重要文件。注意：上传后返回的 temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。\n\n📦 CloudBase PG / pgstore 桶必须先创建后使用（与 Supabase Storage 一致：upload 前 bucket 必须存在）。浏览器 SDK `app.storage.from().upload(path, file)` 不会自动建桶，且 `path` 的第一段就是 bucket 名（例如 `covers/foo.png` → bucket=`covers`）；`from('covers')` 这个参数当前不会被拼到 path 里。如果上传时浏览器看到 `STORAGE_BUCKET_NOT_FOUND` 或 `PUT https://undefined/`（DevTools 表现为 `net::ERR_NAME_NOT_RESOLVED`），先用本工具或控制台确认 / 创建对应的 pgstore bucket，再让前端重试上传，不要让前端把上传失败静默吞掉。`DescribeEnvs.Storages[]` 返回的旧 NoSQL bucket（形如 `<hash>-<envId>-<appId>`）不是可用的 pgstore bucket，切勿当作默认目标使用。",
+        description: "⚠️ PG 模式环境请使用 queryPgStorage 而非本工具（pgstore 与旧 COS 是两套独立系统）。\n\n管理 CloudBase 云存储文件，仅用于 COS/Storage 对象，不用于静态网站托管。支持上传文件/目录、下载文件/目录、删除文件/目录等操作。删除操作需要设置force=true进行确认，防止误删除重要文件。注意：上传后返回的 temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。\n\n📦 CloudBase PG / pgstore 桶必须先创建后使用（与 Supabase Storage 一致：upload 前 bucket 必须存在）。浏览器 SDK `app.storage.from().upload(path, file)` 不会自动建桶，且 `path` 的第一段就是 bucket 名（例如 `covers/foo.png` → bucket=`covers`）；`from('covers')` 这个参数当前不会被拼到 path 里。如果上传时浏览器看到 `STORAGE_BUCKET_NOT_FOUND` 或 `PUT https://undefined/`（DevTools 表现为 `net::ERR_NAME_NOT_RESOLVED`），先用本工具或控制台确认 / 创建对应的 pgstore bucket，再让前端重试上传，不要让前端把上传失败静默吞掉。`DescribeEnvs.Storages[]` 返回的旧 NoSQL bucket（形如 `<hash>-<envId>-<appId>`）不是可用的 pgstore bucket，切勿当作默认目标使用。",
         inputSchema: manageStorageInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -8025,196 +8037,207 @@ function registerStorageTools(server) {
         }
     }, async (args) => {
         const input = args;
-        const manager = await getManager();
-        if (!manager) {
-            throw new Error("Failed to initialize CloudBase manager. Please check your credentials and environment configuration.");
-        }
-        const storageService = manager.storage;
-        switch (input.action) {
-            case 'upload': {
-                const localPath = input.localPath;
-                const cloudPath = input.cloudPath;
-                if (input.isDirectory) {
-                    if (storageOverrides?.uploadDirectory) {
-                        await storageOverrides.uploadDirectory({ localPath, cloudPath });
+        try {
+            const manager = await getManager();
+            if (!manager) {
+                throw new Error("Failed to initialize CloudBase manager. Please check your credentials and environment configuration.");
+            }
+            const storageService = manager.storage;
+            switch (input.action) {
+                case 'upload': {
+                    const localPath = input.localPath;
+                    const cloudPath = input.cloudPath;
+                    if (input.isDirectory) {
+                        if (storageOverrides?.uploadDirectory) {
+                            await storageOverrides.uploadDirectory({ localPath, cloudPath });
+                        }
+                        else {
+                            await storageService.uploadDirectory({
+                                localPath,
+                                cloudPath,
+                                onProgress: (progressData) => {
+                                    console.log("Upload directory progress:", progressData);
+                                }
+                            });
+                        }
                     }
                     else {
-                        await storageService.uploadDirectory({
-                            localPath,
-                            cloudPath,
-                            onProgress: (progressData) => {
-                                console.log("Upload directory progress:", progressData);
-                            }
-                        });
+                        if (storageOverrides?.uploadFile) {
+                            await storageOverrides.uploadFile({ localPath, cloudPath });
+                        }
+                        else {
+                            await storageService.uploadFile({
+                                localPath,
+                                cloudPath,
+                                onProgress: (progressData) => {
+                                    console.log("Upload file progress:", progressData);
+                                }
+                            });
+                        }
                     }
-                }
-                else {
-                    if (storageOverrides?.uploadFile) {
-                        await storageOverrides.uploadFile({ localPath, cloudPath });
+                    // 上传成功后获取临时 URL 和公网访问信息
+                    let temporaryUrl = "";
+                    let fileId = "";
+                    if (storageOverrides?.getFileUrl) {
+                        const urlResult = await storageOverrides.getFileUrl({
+                            cloudPath: input.cloudPath,
+                            maxAge: 3600,
+                        });
+                        temporaryUrl = urlResult.url;
+                        fileId = urlResult.fileId || "";
                     }
                     else {
-                        await storageService.uploadFile({
-                            localPath,
-                            cloudPath,
-                            onProgress: (progressData) => {
-                                console.log("Upload file progress:", progressData);
-                            }
-                        });
+                        try {
+                            const fileUrls = await storageService.getTemporaryUrl([{
+                                    cloudPath: input.cloudPath,
+                                    maxAge: 3600
+                                }]);
+                            temporaryUrl = fileUrls[0]?.url || "";
+                            fileId = fileUrls[0]?.fileId || "";
+                        }
+                        catch {
+                            // StorageOverrides 下 getTemporaryUrl 可能不可用
+                        }
                     }
-                }
-                // 上传成功后获取临时 URL 和公网访问信息
-                let temporaryUrl = "";
-                let fileId = "";
-                if (storageOverrides?.getFileUrl) {
-                    const urlResult = await storageOverrides.getFileUrl({
-                        cloudPath: input.cloudPath,
-                        maxAge: 3600,
-                    });
-                    temporaryUrl = urlResult.url;
-                    fileId = urlResult.fileId || "";
-                }
-                else {
+                    let publicAccess = {};
                     try {
-                        const fileUrls = await storageService.getTemporaryUrl([{
-                                cloudPath: input.cloudPath,
-                                maxAge: 3600
-                            }]);
-                        temporaryUrl = fileUrls[0]?.url || "";
-                        fileId = fileUrls[0]?.fileId || "";
+                        publicAccess = await resolveStoragePublicAccess({
+                            cloudPath: input.cloudPath,
+                            cloudBaseOptions,
+                            manager,
+                        });
                     }
                     catch {
-                        // StorageOverrides 下 getTemporaryUrl 可能不可用
+                        // DescribeEnvs 可能不支持（IDE 模式下会绕过）
+                        publicAccess = {};
                     }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        action: 'upload',
+                                        localPath: input.localPath,
+                                        cloudPath: input.cloudPath,
+                                        isDirectory: input.isDirectory,
+                                        temporaryUrl,
+                                        expireTime: "1小时",
+                                        storageCdnDomain: publicAccess.storageCdnDomain,
+                                        publicUrl: publicAccess.publicUrl,
+                                        note: "temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。publicUrl 基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导，⚠️ 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先将目标路径设置为公有读。"
+                                    },
+                                    message: `Successfully uploaded ${input.isDirectory ? 'directory' : 'file'} from '${input.localPath}' to '${input.cloudPath}'`
+                                }, null, 2)
+                            }
+                        ]
+                    };
                 }
-                let publicAccess = {};
-                try {
-                    publicAccess = await resolveStoragePublicAccess({
-                        cloudPath: input.cloudPath,
-                        cloudBaseOptions,
-                        manager,
-                    });
-                }
-                catch {
-                    // DescribeEnvs 可能不支持（IDE 模式下会绕过）
-                    publicAccess = {};
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'upload',
-                                    localPath: input.localPath,
-                                    cloudPath: input.cloudPath,
-                                    isDirectory: input.isDirectory,
-                                    temporaryUrl,
-                                    expireTime: "1小时",
-                                    storageCdnDomain: publicAccess.storageCdnDomain,
-                                    publicUrl: publicAccess.publicUrl,
-                                    note: "temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。publicUrl 基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导，⚠️ 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先将目标路径设置为公有读。"
-                                },
-                                message: `Successfully uploaded ${input.isDirectory ? 'directory' : 'file'} from '${input.localPath}' to '${input.cloudPath}'`
-                            }, null, 2)
+                case 'download': {
+                    const dlCloudPath = input.cloudPath;
+                    const dlLocalPath = input.localPath;
+                    if (input.isDirectory) {
+                        if (storageOverrides?.downloadDirectory) {
+                            await storageOverrides.downloadDirectory({ cloudPath: dlCloudPath, localPath: dlLocalPath });
+                        }
+                        else {
+                            await storageService.downloadDirectory({
+                                cloudPath: dlCloudPath,
+                                localPath: dlLocalPath
+                            });
                         }
-                    ]
-                };
-            }
-            case 'download': {
-                const dlCloudPath = input.cloudPath;
-                const dlLocalPath = input.localPath;
-                if (input.isDirectory) {
-                    if (storageOverrides?.downloadDirectory) {
-                        await storageOverrides.downloadDirectory({ cloudPath: dlCloudPath, localPath: dlLocalPath });
-                    }
-                    else {
-                        await storageService.downloadDirectory({
-                            cloudPath: dlCloudPath,
-                            localPath: dlLocalPath
-                        });
-                    }
-                }
-                else {
-                    if (storageOverrides?.downloadFile) {
-                        await storageOverrides.downloadFile({ cloudPath: dlCloudPath, localPath: dlLocalPath });
                     }
                     else {
-                        await storageService.downloadFile({
-                            cloudPath: dlCloudPath,
-                            localPath: dlLocalPath
-                        });
-                    }
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'download',
-                                    cloudPath: input.cloudPath,
-                                    localPath: input.localPath,
-                                    isDirectory: input.isDirectory
-                                },
-                                message: `Successfully downloaded ${input.isDirectory ? 'directory' : 'file'} from '${input.cloudPath}' to '${input.localPath}'`
-                            }, null, 2)
+                        if (storageOverrides?.downloadFile) {
+                            await storageOverrides.downloadFile({ cloudPath: dlCloudPath, localPath: dlLocalPath });
                         }
-                    ]
-                };
-            }
-            case 'delete': {
-                if (!input.force) {
+                        else {
+                            await storageService.downloadFile({
+                                cloudPath: dlCloudPath,
+                                localPath: dlLocalPath
+                            });
+                        }
+                    }
                     return {
                         content: [
                             {
                                 type: "text",
                                 text: JSON.stringify({
-                                    success: false,
-                                    error: "Delete operation requires confirmation",
-                                    message: "Please set force: true to confirm deletion. This action cannot be undone."
+                                    success: true,
+                                    data: {
+                                        action: 'download',
+                                        cloudPath: input.cloudPath,
+                                        localPath: input.localPath,
+                                        isDirectory: input.isDirectory
+                                    },
+                                    message: `Successfully downloaded ${input.isDirectory ? 'directory' : 'file'} from '${input.cloudPath}' to '${input.localPath}'`
                                 }, null, 2)
                             }
                         ]
                     };
                 }
-                if (input.isDirectory) {
-                    if (storageOverrides?.deleteDirectory) {
-                        await storageOverrides.deleteDirectory({ cloudPath: input.cloudPath });
-                    }
-                    else {
-                        await storageService.deleteDirectory(input.cloudPath);
+                case 'delete': {
+                    if (!input.force) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        success: false,
+                                        error: "Delete operation requires confirmation",
+                                        message: "Please set force: true to confirm deletion. This action cannot be undone."
+                                    }, null, 2)
+                                }
+                            ]
+                        };
                     }
-                }
-                else {
-                    if (storageOverrides?.deleteFiles) {
-                        await storageOverrides.deleteFiles({ cloudPaths: [input.cloudPath] });
+                    if (input.isDirectory) {
+                        if (storageOverrides?.deleteDirectory) {
+                            await storageOverrides.deleteDirectory({ cloudPath: input.cloudPath });
+                        }
+                        else {
+                            await storageService.deleteDirectory(input.cloudPath);
+                        }
                     }
                     else {
-                        await storageService.deleteFile([input.cloudPath]);
+                        if (storageOverrides?.deleteFiles) {
+                            await storageOverrides.deleteFiles({ cloudPaths: [input.cloudPath] });
+                        }
+                        else {
+                            await storageService.deleteFile([input.cloudPath]);
+                        }
                     }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    data: {
+                                        action: 'delete',
+                                        cloudPath: input.cloudPath,
+                                        isDirectory: input.isDirectory,
+                                        deleted: true
+                                    },
+                                    message: `Successfully deleted ${input.isDirectory ? 'directory' : 'file'} '${input.cloudPath}'`
+                                }, null, 2)
+                            }
+                        ]
+                    };
                 }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                data: {
-                                    action: 'delete',
-                                    cloudPath: input.cloudPath,
-                                    isDirectory: input.isDirectory,
-                                    deleted: true
-                                },
-                                message: `Successfully deleted ${input.isDirectory ? 'directory' : 'file'} '${input.cloudPath}'`
-                            }, null, 2)
-                        }
-                    ]
-                };
+                default:
+                    throw new Error(`Unsupported action: ${input.action}`);
             }
-            default:
-                throw new Error(`Unsupported action: ${input.action}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, tool_result_js_1.buildJsonToolResult)({
+                success: false,
+                message: `manageStorage 操作失败: ${message}`,
+                action: input.action,
+                cloudPath: input.cloudPath,
+            });
         }
     });
 }
@@ -9914,7 +9937,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.23.10" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.24.0" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -11611,6 +11634,7 @@ const MANAGE_ACTIONS = [
     "listMigrations",
     "migrationDetail",
     "rollbackMigration",
+    "repairMigration",
 ];
 function buildPgToolResult(payload) {
     return (0, tool_result_js_1.buildJsonToolResult)(payload);
@@ -11754,6 +11778,38 @@ function classifySqlRisk(sql) {
         requiresConfirm: true,
     };
 }
+/**
+ * Schema DDL that must go through applyMigration by default.
+ * Includes CREATE/ALTER/COMMENT (schema_change) and DROP/TRUNCATE / destructive ALTER.
+ * Excludes DML DELETE and security_change (GRANT/POLICY), which may still use execute.
+ */
+function isSchemaDdlRisk(risk, sql) {
+    if (risk === "schema_change") {
+        return true;
+    }
+    if (risk !== "destructive") {
+        return false;
+    }
+    const verb = getSqlVerb(stripLeadingSqlComments(sql));
+    return ["DROP", "TRUNCATE", "ALTER"].includes(verb);
+}
+function buildLocalMigrationFileHint(version, name) {
+    return `migrations/${version}_${name}.sql`;
+}
+const MIGRATION_VERSION_REQUIRED_MESSAGE = "migrationVersion is required (14-digit UTC timestamp YYYYMMDDHHMMSS). " +
+    "Decide the version first, write local file migrations/<version>_<migrationName>.sql, " +
+    "then call planMigration/applyMigration with the same migrationVersion and migrationName.";
+function requireExplicitMigrationVersion(args, actionLabel) {
+    const version = args.migrationVersion?.trim();
+    if (!version) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_VERSION_REQUIRED",
+            message: `Provide migrationVersion when action=${actionLabel}. ${MIGRATION_VERSION_REQUIRED_MESSAGE}`,
+        });
+    }
+    return version;
+}
 function quoteIdentifier(identifier) {
     return `"${identifier.replace(/"/g, '""')}"`;
 }
@@ -12360,6 +12416,34 @@ async function handleExecuteSql(args, context, deps) {
         });
     }
     const classification = classifySqlRisk(args.sql);
+    if (isSchemaDdlRisk(classification.risk, args.sql) && args.allowDdlViaExecute !== true) {
+        return buildPgToolResult({
+            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. " +
+                "Set allowDdlViaExecute=true only for exceptional one-off ops that intentionally bypass migration history.",
+            data: {
+                classification,
+                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+            },
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview the schema change as a versioned migration (provide migrationVersion + migrationName).", {
+                    action: "planMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                }),
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Apply the schema change via PushPGUserMigrations with the same explicit migrationVersion.", {
+                    action: "applyMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                    confirm: true,
+                }),
+            ],
+        });
+    }
     if (!classification.readOnly && !args.confirm) {
         return buildPgToolResult({
             success: false,
@@ -12369,7 +12453,12 @@ async function handleExecuteSql(args, context, deps) {
                 classification,
             },
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "execute", "Re-issue with confirm=true to actually run the SQL.", { action: "execute", sql: args.sql, confirm: true }),
+                buildNextAction(MANAGE_PG_DATABASE, "execute", "Re-issue with confirm=true to actually run the SQL.", {
+                    action: "execute",
+                    sql: args.sql,
+                    confirm: true,
+                    ...(args.allowDdlViaExecute === true ? { allowDdlViaExecute: true } : {}),
+                }),
                 buildNextAction(QUERY_PG_DATABASE, "metadata", "Inspect table size and shape before destructive changes.", { action: "metadata", limit: 20 }),
             ],
         });
@@ -12386,8 +12475,15 @@ async function handleExecuteSql(args, context, deps) {
                 .slice(0, 5)
                 .map((row) => serializeValue(row)),
             targetTable: targetTable ?? null,
+            ...(args.allowDdlViaExecute === true && isSchemaDdlRisk(classification.risk, args.sql)
+                ? {
+                    warning: "DDL executed via allowDdlViaExecute bypasses migration history. Prefer applyMigration for reproducible schema changes.",
+                }
+                : {}),
         },
-        message: "Write SQL executed successfully.",
+        message: args.allowDdlViaExecute === true && isSchemaDdlRisk(classification.risk, args.sql)
+            ? "Write SQL executed successfully (DDL via allowDdlViaExecute; migration history was bypassed)."
+            : "Write SQL executed successfully.",
         nextActions: classification.risk === "schema_change" && targetTable
             ? [
                 buildNextAction(QUERY_PG_DATABASE, "schema", "Inspect the table schema, columns, indexes, and RLS policies after schema changes.", {
@@ -12415,6 +12511,43 @@ async function handleDryRun(args) {
         });
     }
     const classification = classifySqlRisk(args.sql);
+    const schemaDdl = isSchemaDdlRisk(classification.risk, args.sql);
+    if (classification.readOnly) {
+        return buildPgToolResult({
+            success: true,
+            data: {
+                classification,
+                wouldExecute: false,
+                sqlPreview: args.sql.trim().slice(0, 500),
+            },
+            message: "SQL dry run completed. This statement is read-only; use queryPgDatabase(action=sql) to execute it.",
+            nextActions: [
+                buildNextAction(QUERY_PG_DATABASE, "sql", "Execute the read-only SQL through queryPgDatabase.", { action: "sql", sql: args.sql, limit: 20 }),
+            ],
+        });
+    }
+    if (schemaDdl) {
+        return buildPgToolResult({
+            success: true,
+            data: {
+                classification,
+                wouldExecute: false,
+                sqlPreview: args.sql.trim().slice(0, 500),
+                preferredAction: "applyMigration",
+                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+            },
+            message: "SQL dry run completed. Schema DDL should use applyMigration with an explicit migrationVersion, not execute.",
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Apply schema DDL via versioned migration (provide migrationVersion + migrationName + confirm=true).", {
+                    action: "applyMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                    confirm: true,
+                }),
+            ],
+        });
+    }
     return buildPgToolResult({
         success: true,
         data: {
@@ -12422,15 +12555,9 @@ async function handleDryRun(args) {
             wouldExecute: false,
             sqlPreview: args.sql.trim().slice(0, 500),
         },
-        message: classification.readOnly
-            ? "SQL dry run completed. This statement is read-only; use queryPgDatabase(action=sql) to execute it."
-            : "SQL dry run completed. Write SQL requires managePgDatabase(action=execute, confirm=true).",
+        message: "SQL dry run completed. Write SQL requires managePgDatabase(action=execute, confirm=true).",
         nextActions: [
-            buildNextAction(classification.readOnly ? QUERY_PG_DATABASE : MANAGE_PG_DATABASE, classification.readOnly ? "sql" : "execute", classification.readOnly
-                ? "Execute the read-only SQL through queryPgDatabase."
-                : "Execute the write SQL only after explicit confirmation.", classification.readOnly
-                ? { action: "sql", sql: args.sql, limit: 20 }
-                : { action: "execute", sql: args.sql, confirm: true }),
+            buildNextAction(MANAGE_PG_DATABASE, "execute", "Execute the write SQL only after explicit confirmation.", { action: "execute", sql: args.sql, confirm: true }),
         ],
     });
 }
@@ -12442,16 +12569,49 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
             message: "Provide migration SQL when action=planMigration.",
         });
     }
+    if (!args.migrationName?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_NAME_REQUIRED",
+            message: "Provide migrationName (lowercase letters, digits and underscores, starting with a letter) when action=planMigration.",
+        });
+    }
+    const versionOrError = requireExplicitMigrationVersion(args, "planMigration");
+    if (typeof versionOrError !== "string") {
+        return versionOrError;
+    }
+    const version = versionOrError;
+    const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
+    const migration = {
+        Version: version,
+        Name: args.migrationName,
+        Query: args.sql,
+    };
+    if (args.rollbackSql?.trim()) {
+        migration.Rollback = args.rollbackSql;
+    }
     try {
         const result = await callPgMigrationApi(context, "PreviewPGUserMigrations", {
-            Sql: args.sql,
+            Migrations: [migration],
         }, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
-            data: result,
-            message: "Migration plan generated via PreviewPGUserMigrations.",
+            data: {
+                migrationVersion: version,
+                migrationName: args.migrationName,
+                localFileHint,
+                apiResult: result,
+            },
+            message: `Migration plan generated via PreviewPGUserMigrations. Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`,
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration to execute.", { action: "applyMigration", sql: args.sql, confirm: true }),
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion.", {
+                    action: "applyMigration",
+                    migrationName: args.migrationName,
+                    migrationVersion: version,
+                    sql: args.sql,
+                    confirm: true,
+                    ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                }),
             ],
         });
     }
@@ -12471,6 +12631,13 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
             message: "Provide migration SQL when action=applyMigration.",
         });
     }
+    if (!args.migrationName?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_NAME_REQUIRED",
+            message: "Provide migrationName (lowercase letters, digits and underscores, starting with a letter) when action=applyMigration.",
+        });
+    }
     if (args.confirm !== true) {
         return buildPgToolResult({
             success: false,
@@ -12478,14 +12645,41 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
             message: "PushPGUserMigrations requires confirm=true. Run with confirm=true to proceed.",
         });
     }
+    const versionOrError = requireExplicitMigrationVersion(args, "applyMigration");
+    if (typeof versionOrError !== "string") {
+        return versionOrError;
+    }
+    const version = versionOrError;
+    const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
+    const migration = {
+        Version: version,
+        Name: args.migrationName,
+        Query: args.sql,
+    };
+    if (args.rollbackSql?.trim()) {
+        migration.Rollback = args.rollbackSql;
+    }
+    const params = { Migrations: [migration] };
+    if (args.lockTimeoutMs !== undefined) {
+        params.LockTimeoutMs = args.lockTimeoutMs;
+    }
+    if (args.statementTimeoutMs !== undefined) {
+        params.StatementTimeoutMs = args.statementTimeoutMs;
+    }
     try {
-        const result = await callPgMigrationApi(context, "PushPGUserMigrations", {
-            Sql: args.sql,
-        }, cloudBaseOptions);
+        const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
-            data: result,
-            message: "Migrations applied via PushPGUserMigrations.",
+            data: {
+                migrationVersion: version,
+                migrationName: args.migrationName,
+                localFileHint,
+                apiResult: result,
+            },
+            message: `Migrations applied via PushPGUserMigrations. Ensure local file ${localFileHint} exists and matches.`,
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Verify the remote migration history records the same migrationVersion.", { action: "listMigrations", limit: 20 }),
+            ],
         });
     }
     catch (error) {
@@ -12497,8 +12691,15 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
 }
 async function handleListMigrations(args, context, deps, cloudBaseOptions) {
+    const params = {};
+    if (args.limit !== undefined) {
+        params.Limit = args.limit;
+    }
+    if (args.offset !== undefined) {
+        params.Offset = args.offset;
+    }
     try {
-        const result = await callPgMigrationApi(context, "ListPGUserMigrations", {}, cloudBaseOptions);
+        const result = await callPgMigrationApi(context, "ListPGUserMigrations", params, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
             data: result,
@@ -12514,16 +12715,16 @@ async function handleListMigrations(args, context, deps, cloudBaseOptions) {
     }
 }
 async function handleMigrationDetail(args, context, deps, cloudBaseOptions) {
-    if (!args.objectName?.trim()) {
+    if (!args.migrationVersion?.trim()) {
         return buildPgToolResult({
             success: false,
-            errorCode: "OBJECT_NAME_REQUIRED",
-            message: "Provide objectName (migration ID) when action=migrationDetail.",
+            errorCode: "MIGRATION_VERSION_REQUIRED",
+            message: "Provide migrationVersion (14-digit timestamp YYYYMMDDHHMMSS) when action=migrationDetail.",
         });
     }
     try {
         const result = await callPgMigrationApi(context, "DescribePGUserMigration", {
-            ObjectId: args.objectName,
+            MigrationVersion: args.migrationVersion,
         }, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
@@ -12540,11 +12741,11 @@ async function handleMigrationDetail(args, context, deps, cloudBaseOptions) {
     }
 }
 async function handleRollbackMigration(args, context, deps, cloudBaseOptions) {
-    if (!args.objectName?.trim()) {
+    if (args.lastN === undefined || args.lastN < 1 || !Number.isInteger(args.lastN)) {
         return buildPgToolResult({
             success: false,
-            errorCode: "OBJECT_NAME_REQUIRED",
-            message: "Provide objectName (migration ID) when action=rollbackMigration.",
+            errorCode: "LAST_N_REQUIRED",
+            message: "Provide lastN (positive integer) when action=rollbackMigration.",
         });
     }
     if (args.confirm !== true) {
@@ -12556,7 +12757,7 @@ async function handleRollbackMigration(args, context, deps, cloudBaseOptions) {
     }
     try {
         const result = await callPgMigrationApi(context, "RollbackPGUserMigrations", {
-            ObjectId: args.objectName,
+            LastN: args.lastN,
         }, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
@@ -12572,6 +12773,67 @@ async function handleRollbackMigration(args, context, deps, cloudBaseOptions) {
         });
     }
 }
+async function handleRepairMigration(args, context, deps, cloudBaseOptions) {
+    if (!args.migrationVersion?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_VERSION_REQUIRED",
+            message: "Provide migrationVersion (14-digit timestamp YYYYMMDDHHMMSS) when action=repairMigration.",
+        });
+    }
+    if (!args.migrationName?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_NAME_REQUIRED",
+            message: "Provide migrationName when action=repairMigration.",
+        });
+    }
+    if (!args.repairStatus) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "REPAIR_STATUS_REQUIRED",
+            message: "Provide repairStatus (applied or reverted) when action=repairMigration.",
+        });
+    }
+    if (!args.repairReason?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "REPAIR_REASON_REQUIRED",
+            message: "Provide repairReason when action=repairMigration.",
+        });
+    }
+    if (args.repairStatus === "applied" && !args.sql?.trim()) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "SQL_REQUIRED",
+            message: "Provide sql (Query) when action=repairMigration with repairStatus=applied.",
+        });
+    }
+    const params = {
+        MigrationVersion: args.migrationVersion,
+        Name: args.migrationName,
+        Status: args.repairStatus,
+        Reason: args.repairReason,
+    };
+    if (args.repairStatus === "applied" && args.sql?.trim()) {
+        params.Query = args.sql;
+    }
+    try {
+        const result = await callPgMigrationApi(context, "RepairPGUserMigrationHistory", params, cloudBaseOptions);
+        return buildPgToolResult({
+            success: true,
+            data: result,
+            message: "Migration history repaired via RepairPGUserMigrationHistory.",
+        });
+    }
+    catch (error) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_API_ERROR",
+            message: `RepairPGUserMigrationHistory failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
 async function handleGetPgSchema(args, context, deps) {
     const objectName = args.objectName ?? "";
     const parsed = parseSchemaQualifiedName(objectName);
@@ -12692,15 +12954,15 @@ function registerPGDatabaseTools(server, providedDeps) {
     });
     server.registerTool?.(MANAGE_PG_DATABASE, {
         title: "管理 PostgreSQL 上下文或执行写入 SQL",
-        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL 或 DDL、SQL 风险预检、迁移规划。上下文自动从当前 MCP 环境推导，无需 init。仅支持 CloudBase 内置 PostgreSQL 云端 Manager SDK 执行路径。",
+        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL、SQL 风险预检、迁移管理。建表/ALTER/DROP 等 schema 变更必须使用 applyMigration（显式 migrationVersion + 本地 migrations/ 留档），不要默认用 execute。execute 主要用于 DML 与 GRANT/RLS 等运维 SQL。",
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_ACTIONS)
-                .describe("操作类型：execute=执行已确认的写入 SQL 或 DDL；dryRun=只分析 SQL 风险不执行；planMigration=通过 PreviewPGUserMigrations 预览迁移计划；applyMigration=通过 PushPGUserMigrations 应用迁移；listMigrations=查询已应用的 Migration 列表；migrationDetail=查看单条 Migration 详情；rollbackMigration=回滚指定 Migration"),
+                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
             sql: zod_1.z
                 .string()
                 .optional()
-                .describe("action=execute、dryRun、planMigration 或 applyMigration 使用的 SQL 语句"),
+                .describe("action=execute、dryRun、planMigration、applyMigration 或 repairMigration(applied) 使用的 SQL 语句"),
             confirm: zod_1.z
                 .boolean()
                 .optional()
@@ -12724,7 +12986,62 @@ function registerPGDatabaseTools(server, providedDeps) {
             objectName: zod_1.z
                 .string()
                 .optional()
-                .describe("action=migrationDetail 或 rollbackMigration 时使用的 migration ID。"),
+                .describe("可选的对象名，当前仅用于非 migration 场景。migration 相关操作请使用 migrationName / migrationVersion / lastN。"),
+            migrationName: zod_1.z
+                .string()
+                .regex(/^[a-z][a-z0-9_]*$/)
+                .optional()
+                .describe("plan/apply/repair 必填：migration 名称，小写字母开头，仅允许小写字母、数字和下划线。"),
+            migrationVersion: zod_1.z
+                .string()
+                .regex(/^\d{14}$/)
+                .optional()
+                .describe("14 位时间戳 YYYYMMDDHHMMSS。plan/apply/detail/repair 必填；禁止由服务端静默生成，避免与本地 migrations/<version>_<name>.sql 分叉。"),
+            rollbackSql: zod_1.z
+                .string()
+                .optional()
+                .describe("plan/apply 可选：回滚 SQL 语句。"),
+            lastN: zod_1.z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("rollback 必填：回滚最近 N 条已应用的 Migration，正整数。"),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("list 可选：返回数量上限，1-500，默认 100。"),
+            offset: zod_1.z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("list 可选：分页偏移，默认 0。"),
+            lockTimeoutMs: zod_1.z
+                .number()
+                .int()
+                .optional()
+                .describe("apply 可选：获取数据库锁的最长时间（毫秒），默认 5000。"),
+            statementTimeoutMs: zod_1.z
+                .number()
+                .int()
+                .optional()
+                .describe("apply 可选：单条 SQL 执行最长时间（毫秒），默认 300000。"),
+            repairStatus: zod_1.z
+                .enum(["applied", "reverted"])
+                .optional()
+                .describe("repair 必填：applied=标记为已应用（可补录 Query），reverted=删除 history 记录。"),
+            repairReason: zod_1.z
+                .string()
+                .optional()
+                .describe("repair 必填：修复原因。"),
+            allowDdlViaExecute: zod_1.z
+                .boolean()
+                .optional()
+                .describe("可选，默认 false。仅当需要故意绕过 migration history 时设为 true，才允许 schema DDL 走 execute；正常建表/改 schema 必须用 applyMigration。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -12738,6 +13055,14 @@ function registerPGDatabaseTools(server, providedDeps) {
         const cbOpts = server.cloudBaseOptions;
         switch (args.action) {
             case "execute": {
+                // Soft-block schema DDL before readiness probe so agents get migration guidance immediately.
+                if (args.sql?.trim()) {
+                    const classification = classifySqlRisk(args.sql);
+                    if (isSchemaDdlRisk(classification.risk, args.sql) &&
+                        args.allowDdlViaExecute !== true) {
+                        return handleExecuteSql(args, context, deps);
+                    }
+                }
                 try {
                     await ensurePgReadyOnce(cbOpts, deps);
                 }
@@ -12760,13 +13085,15 @@ function registerPGDatabaseTools(server, providedDeps) {
             case "applyMigration":
             case "listMigrations":
             case "migrationDetail":
-            case "rollbackMigration": {
+            case "rollbackMigration":
+            case "repairMigration": {
                 switch (args.action) {
                     case "planMigration": return handlePlanMigration(args, context, deps, cbOpts);
                     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 "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}` });
                 }
             }
@@ -13478,7 +13805,7 @@ exports.IDE_TYPES = [
     "openai-codex-cli", // OpenAI Codex CLI
     "augment-code", // Augment Code
     "github-copilot", // GitHub Copilot
-    "roocode", // RooCode AI编辑器
+    "roocode", // RooCode AI编辑器（已 deprecated 2026-05，可考虑引导转向 Cline/ZooCode）
     "tongyi-lingma", // 通义灵码
     "trae", // Trae AI编辑器
     "qoder", // Qoder AI编辑器
@@ -13520,7 +13847,6 @@ exports.RAW_IDE_FILE_MAPPINGS = {
     ],
     "baidu-comate": [
         { path: ".comate/rules/cloudbase-rules.mdr" },
-        { path: ".comate/rules/cloudbaase-rules.mdr" },
         { path: ".comate/mcp.json", isMcpConfig: true },
     ],
     "openai-codex-cli": [
@@ -13530,10 +13856,10 @@ exports.RAW_IDE_FILE_MAPPINGS = {
     "augment-code": [{ path: ".augment-guidelines" }],
     "github-copilot": [{ path: ".github/copilot-instructions.md" }],
     roocode: [
-        { path: ".roo/rules/cloudbaase-rules.md" },
+        { path: ".roo/rules/cloudbase-rules.md" },
         { path: ".roo/mcp.json", isMcpConfig: true },
     ],
-    "tongyi-lingma": [{ path: ".lingma/rules/cloudbaase-rules.md" }],
+    "tongyi-lingma": [{ path: ".lingma/rules/cloudbase-rules.md" }],
     trae: [{ path: ".trae/rules/" }],
     qoder: [{ path: ".qoder/rules/" }],
     antigravity: [{ path: ".agent/rules/" }],
@@ -13573,7 +13899,7 @@ const IDE_DESCRIPTIONS = {
     "openai-codex-cli": "OpenAI Codex CLI",
     "augment-code": "Augment Code",
     "github-copilot": "GitHub Copilot",
-    roocode: "RooCode AI编辑器",
+    roocode: "RooCode AI编辑器（deprecated）",
     "tongyi-lingma": "通义灵码",
     trae: "Trae AI编辑器",
     qoder: "Qoder AI编辑器",
@@ -13868,7 +14194,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.23.10" : 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.24.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -16623,6 +16949,7 @@ const STORAGE_ACTIONS = [
     "objectInfo",
     "signUpload",
     "signDownload",
+    "createBucket",
 ];
 function buildPgStorageResult(payload) {
     return (0, tool_result_js_1.buildJsonToolResult)(payload);
@@ -16681,12 +17008,52 @@ async function handleBuckets(server) {
         data: {
             capability: "storageManagerSdkOrHttpApi",
             envId: server.cloudBaseOptions?.envId ?? null,
-            supportedActions: ["buckets", "config", "uploadPlan", "objectInfo"],
+            supportedActions: ["buckets", "config", "uploadPlan", "objectInfo", "createBucket"],
             note: "PG environment storage is exposed as metadata and implementation plans in MCP. Application data-plane upload/download should use SDK or HTTP API code.",
         },
         message: "Resolved PostgreSQL storage capability summary. Use uploadPlan for application-side upload implementation.",
     });
 }
+async function handleCreateBucket(args, server) {
+    if (!args.bucket?.trim()) {
+        return buildPgStorageResult({
+            success: false,
+            errorCode: "BUCKET_REQUIRED",
+            message: "Provide bucket name to create a PG storage bucket.",
+        });
+    }
+    const bucket = args.bucket.trim();
+    const envId = server.cloudBaseOptions?.envId ?? "${envId}";
+    return buildPgStorageResult({
+        success: true,
+        data: {
+            action: "createBucket",
+            bucket,
+            description: `Creates PG storage bucket '${bucket}'`,
+            plans: {
+                sql: `INSERT INTO storage.buckets (id, name, public) VALUES ('${bucket}', '${bucket}', false);`,
+                httpApi: {
+                    method: "POST",
+                    url: `https://${envId}.api.tcloudbasegateway.com/v1/storages/bucket/`,
+                    headers: {
+                        "Authorization": "Bearer {service_role_token}",
+                        "Content-Type": "application/json",
+                    },
+                    body: { name: bucket, public: false },
+                },
+                cli: `tcb db execute -e ${envId} --sql "INSERT INTO storage.buckets (id, name, public) VALUES ('${bucket}', '${bucket}', false);"`,
+            },
+            tokenRequired: "service_role",
+            tokenGuide: "Use manageAppAuth(action='createApiKey', name='storage-server-key') to get a service_role level API key token.",
+            nextSteps: [
+                "Option A: Run the SQL via managePgDatabase(action='execute', confirm=true)",
+                "Option B: Call the HTTP API with a service_role token",
+                "Option C: Use CloudBase CLI: tcb db execute",
+            ],
+        },
+        message: `Generated bucket creation plan for '${bucket}'. Execute one of the provided plans to create the bucket, then configure RLS policies.`,
+    });
+}
 async function handleUploadPlan(args, server) {
     const missingBucket = requireBucket(args);
     if (missingBucket)
@@ -16757,7 +17124,7 @@ function registerPGStorageTools(server) {
         inputSchema: {
             action: zod_1.z
                 .enum(STORAGE_ACTIONS)
-                .describe("操作类型：buckets/config=查询存储能力摘要；uploadPlan=生成 HTTP API/SDK 上传方案；objectInfo=生成对象元信息查询方案；signUpload/signDownload=显式的一次性签名 URL 请求占位"),
+                .describe("操作类型：buckets/config=查询存储能力摘要；createBucket=生成 bucket 创建方案（SQL/HTTP API/CLI）；uploadPlan=生成 HTTP API/SDK 上传方案；objectInfo=生成对象元信息查询方案；signUpload/signDownload=显式的一次性签名 URL 请求占位"),
             bucket: zod_1.z.string().optional().describe("云存储 bucket 名称"),
             objectKey: zod_1.z.string().optional().describe("单个对象 key"),
             objectKeys: zod_1.z.array(zod_1.z.string()).optional().describe("多个对象 key，用于对象元信息查询规划"),
@@ -16781,6 +17148,8 @@ function registerPGStorageTools(server) {
             case "buckets":
             case "config":
                 return handleBuckets(server);
+            case "createBucket":
+                return handleCreateBucket(args, server);
             case "uploadPlan":
                 return handleUploadPlan(args, server);
             case "objectInfo":