@cloudbase/cloudbase-mcp 2.32.2 → 2.32.3

package/dist/index.js

@@ -573,6 +573,31 @@ function applyBoundEnvRegion(server, region) {
         server.cloudBaseOptions.region = region;
     }
 }
+/**
+ * 绑定环境后固化站点：region 歧义（如 ap-singapore 同时属于 domestic 与 intl）且
+ * 未显式指定 site 时，若仅一个凭证槽位可用，则将 TCB_SITE 固定为该站点，
+ * 避免后续资源调用再次落入歧义默认分支（issue #960）。
+ */
+async function applyBoundEnvSite(server, region) {
+    if (!region || (0, site_map_js_1.getSite)(region) !== "ambiguous") {
+        return;
+    }
+    if ((0, site_map_js_1.normalizeSite)(process.env.TCB_SITE)) {
+        return; // 已显式指定 site，不覆盖
+    }
+    const usableSites = await (0, auth_js_1.listUsableCredentialSites)();
+    if (usableSites.length !== 1) {
+        return; // 无法唯一判定时不猜测，保持既有歧义回退逻辑
+    }
+    process.env.TCB_SITE = usableSites[0];
+    if (server.cloudBaseOptions) {
+        server.cloudBaseOptions.site = usableSites[0];
+    }
+    (0, logger_js_1.debug)("applyBoundEnvSite: pinned TCB_SITE from the only usable credential slot", {
+        region,
+        site: usableSites[0],
+    });
+}
 const CODEBUDDY_AUTH_ACTIONS = ["status", "set_env", "login_by_api_key"];
 const DEFAULT_AUTH_ACTIONS = [
     "status",
@@ -1847,7 +1872,17 @@ function registerEnvTools(server) {
                                     : {}),
                                 onDeviceCode: deviceOnCode,
                             })
-                                .then(() => {
+                                .then(async () => {
+                                // toolbox 将新凭证写入 flat 'credential'，这里迁移为分槽格式
+                                //（legacy flat 等价 domestic 槽位），对齐 ensureLogin() 的分槽行为
+                                try {
+                                    await (0, auth_js_1.ensureSlottedCredential)();
+                                }
+                                catch (err) {
+                                    (0, logger_js_1.debug)("device auth: slotted credential migration failed", {
+                                        error: err instanceof Error ? err.message : String(err),
+                                    });
+                                }
                                 (0, auth_js_1.resolveAuthProgressState)();
                             })
                                 .catch((err) => {
@@ -2059,7 +2094,17 @@ function registerEnvTools(server) {
                         });
                     }
                     await cloudbase_manager_js_1.envManager.setEnvId(envId);
+                    // 跨客户端通用事件推送（MCP 协议 notification，无 id）：任何客户端
+                    // （如 dsh-plugin 面板）都能通过 notifications/cloudbase/env_changed
+                    // 感知环境变更，替代客户端本地推断与兜底轮询。通知失败不影响主流程。
+                    void server.server
+                        .notification({
+                        method: "notifications/cloudbase/env_changed",
+                        params: { envId },
+                    })
+                        .catch(() => { });
                     applyBoundEnvRegion(server, target?.region);
+                    await applyBoundEnvSite(server, target?.region);
                     const regionHint = target?.region
                         ? `，地域: ${target.region}`
                         : target
@@ -3272,6 +3317,11 @@ function buildCapiErrorMessage(service, action, error) {
 function registerCapiTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const logger = server.logger;
+    // commonService 透传调用只依赖凭据上下文（secretId/secretKey/token/region），
+    // EnvId 由 params 携带，不依赖 MCP 绑定的环境。强制绑定会在「已登录但未绑环境」
+    // 场景把 DescribeEnvs/CreateEnv/CAM 等无 env 依赖的 Action 全部挡在 ENV_REQUIRED，
+    // 并诱发无头客户端原样重试风暴（2026-08-20 单日 15 万次报错），故豁免环境绑定。
+    const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions, requireEnvId: false });
     server.registerTool?.("callCloudApi", {
         title: "调用云API",
         description: `通用的云 API 调用工具，主要用于 CloudBase / 腾讯云管控面与依赖资源相关 API 调用。调用前请先确认 service、Action 与 Param，避免猜测 Action 名称。如果你的目标是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请不要优先使用 callCloudApi，而应优先查看对应 OpenAPI / Swagger。现有 OpenAPI / Swagger 能力不是通用的管控面 Action 集合；管控面 API 请优先参考 CloudBase API 概览 ${CLOUDBASE_CONTROL_PLANE_DOC_URL} 与云开发依赖资源接口指引 ${CLOUDBASE_DEPENDENCY_API_DOC_URL}。对于 tcb service，常用 Action 分类如下：
@@ -3378,6 +3428,86 @@ function registerCapiTools(server) {
 }
 
 
+/***/ }),
+
+/***/ 827:
+/***/ ((__unused_webpack_module, exports) => {
+
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.REPEAT_GUARD_THRESHOLD = void 0;
+exports.applyRepeatGuardToPayload = applyRepeatGuardToPayload;
+exports.resetRepeatGuard = resetRepeatGuard;
+exports.__resetRepeatGuardForTests = __resetRepeatGuardForTests;
+/**
+ * 连续重复错误熔断（repeat guard）。
+ *
+ * 背景：无头自动化客户端收到结构化引导错误（如 ENV_REQUIRED）后，可能不执行
+ * 引导动作而是原样重试，形成重试风暴（2026-08-20 单日 15 万次同文案报错）。
+ * 本模块在同一进程（≈同一 MCP session）内跟踪连续相同错误：
+ * - 连续次数达到阈值后，在 payload 注入 repeat_guard 升级字段，提醒模型
+ *   「原样重试无效，必须先完成 next_step 指向的修复动作」；
+ * - 不改写 message 本身，保持灯塔侧按错误文案聚合的稳定性；
+ * - 任一工具调用成功即整体清零（说明循环已被打破）。
+ */
+exports.REPEAT_GUARD_THRESHOLD = 3;
+const REPEAT_GUARD_KEY_MAX_LENGTH = 200;
+let lastKey = null;
+let consecutiveCount = 0;
+function buildRepeatGuardKey(payload) {
+    const code = typeof payload.code === "string" ? payload.code : "";
+    const message = typeof payload.message === "string" ? payload.message : "";
+    return `${code}|${message.slice(0, REPEAT_GUARD_KEY_MAX_LENGTH)}`;
+}
+function buildRepeatGuardNotice(count) {
+    return (`当前会话已连续 ${count} 次返回相同错误。原样重试不会成功：` +
+        "请停止重试当前调用，先按 payload 中的 message / next_step 完成修复动作" +
+        "（如完成 auth 登录或绑定环境），或调整参数后再继续。");
+}
+/**
+ * 记录一次结构化工具错误；达到阈值时返回注入 repeat_guard 的新 payload。
+ */
+function applyRepeatGuardToPayload(payload) {
+    if (!payload || typeof payload !== "object") {
+        return payload;
+    }
+    const key = buildRepeatGuardKey(payload);
+    if (key === lastKey) {
+        consecutiveCount += 1;
+    }
+    else {
+        lastKey = key;
+        consecutiveCount = 1;
+    }
+    if (consecutiveCount < exports.REPEAT_GUARD_THRESHOLD) {
+        return payload;
+    }
+    const code = typeof payload.code === "string" && payload.code.length > 0
+        ? payload.code
+        : "UNKNOWN";
+    const repeatGuard = {
+        code,
+        consecutive_count: consecutiveCount,
+        threshold: exports.REPEAT_GUARD_THRESHOLD,
+        notice: buildRepeatGuardNotice(consecutiveCount),
+    };
+    return { ...payload, repeat_guard: repeatGuard };
+}
+/**
+ * 工具调用成功时清零计数。
+ */
+function resetRepeatGuard() {
+    lastKey = null;
+    consecutiveCount = 0;
+}
+/**
+ * 测试辅助：恢复初始状态。
+ */
+function __resetRepeatGuardForTests() {
+    resetRepeatGuard();
+}
+
+
 /***/ }),
 
 /***/ 959:
@@ -3403,6 +3533,7 @@ const cloud_mode_js_1 = __webpack_require__(9684);
 const logger_js_1 = __webpack_require__(3039);
 const telemetry_js_1 = __webpack_require__(5880);
 const tool_result_js_1 = __webpack_require__(9835);
+const repeat_error_guard_js_1 = __webpack_require__(827);
 /**
  * Mirror annotations.category into _meta.category.
  *
@@ -3474,7 +3605,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || ( true ? "2.32.2" : 0)}
+- MCP 版本：${process.env.npm_package_version || ( true ? "2.32.3" : 0)}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -3520,6 +3651,8 @@ function createWrappedHandler(name, handler, server) {
             // 执行原始处理函数
             const result = await handler(args);
             success = true;
+            // 任一工具成功说明重复错误循环已被打破，清零连续错误计数
+            (0, repeat_error_guard_js_1.resetRepeatGuard)();
             requestId = extractRequestIdFromToolResult(result);
             const duration = Date.now() - startTime;
             (0, logger_js_1.debug)(`工具执行成功: ${name}`, { duration, requestId: requestId || undefined });
@@ -3544,7 +3677,9 @@ function createWrappedHandler(name, handler, server) {
             // Preserve structured tool guidance such as next_step.
             // These errors are expected control flow and should be serialized by the outer server wrapper.
             if ((0, tool_result_js_1.isToolPayloadError)(error)) {
-                throw error;
+                // 连续相同结构化错误达到阈值时注入 repeat_guard 升级提示，
+                // 打断无头客户端的原样重试循环（不改写 message，保持遥测聚合稳定）
+                throw new tool_result_js_1.ToolPayloadError((0, repeat_error_guard_js_1.applyRepeatGuardToPayload)(error.payload));
             }
             // In tests, avoid any extra work that may block (envId lookup, issue link generation, etc.)
             if (isTestEnvironment) {
@@ -3555,7 +3690,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.32.2" : 0;
+            const mcpVersion =  true ? "2.32.3" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -5581,14 +5716,20 @@ async function throwPendingAuthError() {
 async function throwEnvRequiredError(options) {
     const envCandidates = options?.envCandidates ?? (await listAvailableEnvCandidates(options));
     const singleEnvId = envCandidates.length === 1 ? envCandidates[0].envId : undefined;
+    // 终止性引导：明确「重试当前工具不会成功」，给出可直接执行的替代动作与
+    // 无头/无人值守环境的 fallback（CLOUDBASE_ENV_ID 或宿主配置传入 envId），
+    // 避免客户端把本错误当作可重试错误陷入死循环（2026-08-20 单日 15 万次重试风暴）。
+    const retryHint = "重试当前工具不会成功，请停止原样重试。";
+    const headlessHint = "若运行在无浏览器/无人值守环境而无法交互完成登录绑定，可在启动 MCP 前设置 CLOUDBASE_ENV_ID 环境变量指定默认环境。";
+    const message = envCandidates.length === 0
+        ? `当前已登录，但还没有可用环境。${retryHint}请改为在腾讯云控制台创建 CloudBase 环境后重新绑定；${headlessHint}`
+        : envCandidates.length === 1
+            ? `当前已登录，但尚未绑定环境。${retryHint}请先调用 auth(action="set_env", envId="${singleEnvId}") 完成绑定后再继续；${headlessHint}`
+            : `当前已登录，但尚未绑定环境。${retryHint}请先调用 auth(action="set_env", envId=候选环境之一) 完成绑定后再继续；${headlessHint}`;
     (0, tool_result_js_1.throwToolPayloadError)({
         ok: false,
         code: "ENV_REQUIRED",
-        message: envCandidates.length === 0
-            ? "当前已登录，但还没有可用环境，请先调用 auth 工具完成环境选择或创建环境。"
-            : envCandidates.length === 1
-                ? `当前已登录，但尚未绑定环境。可直接选择环境 ${singleEnvId}。`
-                : "当前已登录，但尚未绑定环境，请先调用 auth 工具选择环境。",
+        message,
         env_candidates: envCandidates,
         next_step: (0, tool_result_js_1.buildAuthNextStep)("set_env", {
             requiredParams: singleEnvId ? undefined : ["envId"],
@@ -13752,7 +13893,7 @@ class TelemetryReporter {
         const arch = os_1.default.arch(); // 系统架构
         // Build-time injected version; guard for vitest / non-webpack runtimes.
         const mcpVersion = process.env.npm_package_version ||
-            ( true ? "2.32.2" : 0);
+            ( true ? "2.32.3" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -15781,20 +15922,26 @@ async function resolvePgDbContext(cloudBaseOptions, args) {
         envId,
         instanceId: args?.instanceId ?? "cloudbase-pg",
         defaultSchema: args?.defaultSchema ?? "public",
-        role: args?.role ?? "cloudbase_admin",
+        role: args?.role ?? PG_DEFAULT_ROLE,
     };
 }
 /** Default / recommended roles for CloudBase PG ExecutePGSql.Role */
-const PG_DEFAULT_ROLE = "cloudbase_admin";
+const PG_DEFAULT_ROLE = "cloudbase_postgres";
 const PG_RECOMMENDED_ROLES = [
-    "cloudbase_admin",
+    "cloudbase_postgres",
     "anon",
     "authenticated",
     "service_role",
 ];
+/**
+ * Platform-owned admin roles. cloudbase_admin is the platform management
+ * account and must not be used by user-facing ExecutePGSql calls.
+ */
+const PG_PLATFORM_RESERVED_ROLES = ["cloudbase_admin"];
 /**
  * Roles that look like login/instance principals and routinely fail SET ROLE
  * in beacon data (e.g. postgres, postgres_pgdb_<id>). Reject before the API call.
+ * Also rejects platform-reserved roles (cloudbase_admin) that are not for user calls.
  */
 function isLikelyInvalidPgExecuteRole(role) {
     const normalized = role.trim();
@@ -15804,6 +15951,10 @@ function isLikelyInvalidPgExecuteRole(role) {
     if (normalized === "postgres") {
         return true;
     }
+    // Platform management account, reserved for the platform itself.
+    if (PG_PLATFORM_RESERVED_ROLES.includes(normalized)) {
+        return true;
+    }
     // Instance-derived login principals, not valid ExecutePGSql Role targets
     if (/^postgres_pgdb_[a-z0-9]+$/i.test(normalized)) {
         return true;
@@ -15840,8 +15991,10 @@ function isPgRoleExecutionError(message) {
 }
 function buildPgRoleGuidanceMessage(attemptedRole) {
     const recommended = PG_RECOMMENDED_ROLES.join(", ");
+    const reserved = PG_PLATFORM_RESERVED_ROLES.join(", ");
     return (`PostgreSQL role "${attemptedRole}" cannot be used with ExecutePGSql (SET ROLE failed or role does not exist). ` +
         `Do not invent roles like postgres / postgres_pgdb_* from env or instance names. ` +
+        `Platform-reserved roles (${reserved}) are the platform management account and must not be used by user calls. ` +
         `Omit role (defaults to ${PG_DEFAULT_ROLE}) or pass one of: ${recommended}. ` +
         `To list roles that exist in this database, retry with role=${PG_DEFAULT_ROLE} and SQL: SELECT rolname FROM pg_roles ORDER BY rolname;`);
 }
@@ -18110,7 +18263,7 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .optional()
                 .describe(`可选的 PostgreSQL role，传给 Manager SDK executePGSql 的 Role（平台会 SET ROLE）。默认 ${PG_DEFAULT_ROLE}。` +
                 `推荐取值：${PG_RECOMMENDED_ROLES.join(" / ")}。` +
-                `不要传 postgres、postgres_pgdb_* 或从环境名臆造的角色；不确定时省略本字段，或先用 ${PG_DEFAULT_ROLE} 执行 SELECT rolname FROM pg_roles。`),
+                `不要传 postgres、postgres_pgdb_*、平台保留角色（${PG_PLATFORM_RESERVED_ROLES.join("、")}，为平台管理账号不对用户开放）或从环境名臆造的角色；不确定时省略本字段，或先用 ${PG_DEFAULT_ROLE} 执行 SELECT rolname FROM pg_roles。`),
             objectName: zod_1.z
                 .string()
                 .optional()
@@ -19659,7 +19812,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.32.2" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.32.3" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -20982,9 +21135,55 @@ function buildUploadErrorMessage(error, localPath) {
     }
     return `[manageHosting(upload)] ${baseMessage}\n建议：${suggestions.join(' ')}`;
 }
+/**
+ * TCB 管控面 DescribeStaticStore 接口 QPS 限流（20 次/秒）。
+ * Manager SDK 的 hosting.deleteFiles / uploadFiles / findFiles 等每次调用
+ * 都会先 checkStatus() → getInfo() → DescribeStaticStore（无缓存），
+ * AI 连续快速删除多个文件或失败后立即重试时极易触发该限流。
+ */
+const DESCRIBE_STATIC_STORE_RATE_LIMIT_RE = /\[DescribeStaticStore\][\s\S]*exceeds the frequency limit `20` for a second/i;
+function buildDeleteErrorMessage(error) {
+    const baseMessage = error instanceof Error ? error.message : String(error);
+    if (DESCRIBE_STATIC_STORE_RATE_LIMIT_RE.test(baseMessage)) {
+        return (`[manageHosting(delete)] ${baseMessage}\n` +
+            '原因：静态托管底层 DescribeStaticStore 管控接口有 20 次/秒的 QPS 限制，' +
+            '连续快速删除多个文件（或失败后立即重试）容易触发限流，删除操作本身可能已经部分生效。\n' +
+            '处理建议：\n' +
+            '1) 等待 1-2 秒后重试本次删除，不要立即连续重试；\n' +
+            '2) 批量删除多个文件时，逐次调用并保持间隔（建议每秒不超过 10 次），不要并发或循环快速重试；\n' +
+            '3) 同一目录下的多个文件可改用 isDir=true 一次删除整个目录，减少调用次数；\n' +
+            '4) 若不确定删除是否已生效，可调用 queryHosting(action="findFiles") 核对。');
+    }
+    return `[manageHosting(delete)] ${baseMessage}`;
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Manager SDK hosting.deleteFiles 对 COS 删除失败不抛异常，返回
+ * { Deleted: [], Error: [e] }；此处提取 Error 数组为可读字符串列表，
+ * 供 delete 路径做失败判定与引导。
+ */
+function extractDeleteErrors(result) {
+    if (!isRecord(result)) {
+        return [];
+    }
+    const rawErrors = result.Error ?? result.error;
+    if (!Array.isArray(rawErrors)) {
+        return [];
+    }
+    return rawErrors
+        .map((item) => {
+        if (typeof item === 'string' && item.trim()) {
+            return item.trim();
+        }
+        if (isRecord(item) && typeof item.message === 'string') {
+            return item.message;
+        }
+        return JSON.stringify(item);
+    })
+        .filter(Boolean);
+}
 function getRecordString(record, keys) {
     for (const key of keys) {
         const value = record[key];
@@ -21209,11 +21408,24 @@ async function getHostingStoreOrThrow(cloudbase, cloudBaseOptions, logger) {
     }
     throw new Error(`当前环境 ${envId} 未发现静态托管资源配置，无法上传文件。请先确认 MCP 已绑定到已开通静态托管的 CloudBase 环境；如需切换环境，请调用 auth(action="set_env", envId="目标环境ID") 后重试。`);
 }
+function enrichRateLimitMessage(message) {
+    // delete 路径已由 buildDeleteErrorMessage 提供完整引导，避免重复追加
+    if (message.includes('QPS 限制') || message.includes('等待 1-2 秒后重试')) {
+        return message;
+    }
+    if (DESCRIBE_STATIC_STORE_RATE_LIMIT_RE.test(message)) {
+        return (`${message}\n` +
+            '原因：静态托管底层 DescribeStaticStore 管控接口有 20 次/秒的 QPS 限制，' +
+            '连续快速调用（或失败后立即重试）容易触发限流，本次查询/操作可能没有完整生效。\n' +
+            '处理建议：等待 1-2 秒后重试，不要连续快速重试；多个文件操作请逐次调用并保持间隔。');
+    }
+    return message;
+}
 function buildFailureResult(action, error) {
     return (0, tool_result_js_1.buildJsonToolResult)({
         success: false,
         errorCode: `HOSTING_${action.toUpperCase()}_FAILED`,
-        message: error instanceof Error ? error.message : String(error),
+        message: enrichRateLimitMessage(error instanceof Error ? error.message : String(error)),
     });
 }
 function normalizeFileFields(files) {
@@ -21393,7 +21605,7 @@ function registerHostingTools(server) {
     });
     server.registerTool('manageHosting', {
         title: '管理 CloudBase 静态托管',
-        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 本工具没有关闭默认域名（*.tcloudbaseapp.com）的 action；要禁用该默认公网域名，请用 manageGateway(action="disableRoute", domain=该 STATIC_STORE IsDefault 域名, path="/")（底层 ModifyHTTPServiceRoute，不是 ModifyGatewayRoute）。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
+        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 底层每次托管操作都会请求 DescribeStaticStore 管控接口（20 次/秒 QPS 限制）：批量删除多个文件请逐次调用并保持间隔（建议每秒不超过 10 次），同一目录下多个文件可优先用 isDir=true 一次删除整个目录；若报错含 "frequency limit" 说明触发了限流，请等待 1-2 秒后重试，不要连续快速重试。⚠️ 本工具没有关闭默认域名（*.tcloudbaseapp.com）的 action；要禁用该默认公网域名，请用 manageGateway(action="disableRoute", domain=该 STATIC_STORE IsDefault 域名, path="/")（底层 ModifyHTTPServiceRoute，不是 ModifyGatewayRoute）。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
         inputSchema: manageHostingInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -21563,14 +21775,27 @@ function registerHostingTools(server) {
                     if (!input.confirm) {
                         throw new Error('manageHosting(action="delete") 是破坏性操作，必须显式传 confirm=true。');
                     }
-                    const result = await cloudbase.hosting.deleteFiles({
-                        cloudPath: input.cloudPath,
-                        isDir: input.isDir ?? false,
-                    });
+                    let result;
+                    try {
+                        result = await cloudbase.hosting.deleteFiles({
+                            cloudPath: input.cloudPath,
+                            isDir: input.isDir ?? false,
+                        });
+                    }
+                    catch (error) {
+                        throw new Error(buildDeleteErrorMessage(error));
+                    }
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    // Manager SDK 的 deleteFiles 对 COS 单文件删除失败不抛异常，
+                    // 而是返回 { Deleted: [], Error: [e] }，需要显式检查 Error 数组。
+                    const deleteErrors = extractDeleteErrors(result);
                     // Post-validation: verify deletion was successful
                     let deleteVerified = true;
                     let verificationError;
+                    if (deleteErrors.length > 0) {
+                        deleteVerified = false;
+                        verificationError = `删除请求未生效：${deleteErrors.join('；')}`;
+                    }
                     try {
                         const checkResult = await cloudbase.hosting.findFiles({
                             prefix: input.cloudPath,
@@ -21578,7 +21803,7 @@ function registerHostingTools(server) {
                         });
                         if (Array.isArray(checkResult) && checkResult.length > 0) {
                             deleteVerified = false;
-                            verificationError = `删除后验证失败：文件仍在静态托管中`;
+                            verificationError = verificationError ?? `删除后验证失败：文件仍在静态托管中`;
                         }
                     }
                     catch (error) {
@@ -21597,7 +21822,11 @@ function registerHostingTools(server) {
                         },
                         message: deleteVerified
                             ? `已删除静态托管${input.isDir ? '目录' : '文件'} \`${input.cloudPath}\`。`
-                            : `删除操作已提交，但验证发现文件可能未完全删除，请手动确认。`,
+                            : `删除操作已提交，但验证发现文件可能未完全删除。` +
+                                `可能原因：底层 COS 删除请求失败（如文件不存在、存储桶权限不足），或触发 DescribeStaticStore 限流后删除未生效。` +
+                                `建议：1) 等待 1-2 秒后用 queryHosting(action="findFiles", prefix="${input.cloudPath}") 核对文件状态；` +
+                                `2) 若确认文件仍存在，重新调用 manageHosting(action="delete", confirm=true) 重试；` +
+                                `3) 批量删除多个文件请逐次调用并保持间隔（DescribeStaticStore 有 20 次/秒 QPS 限制）。`,
                     });
                 }
                 case 'setWebsiteDocument': {
@@ -21766,6 +21995,8 @@ exports.setPendingAuthProgressState = setPendingAuthProgressState;
 exports.resolveAuthProgressState = resolveAuthProgressState;
 exports.rejectAuthProgressState = rejectAuthProgressState;
 exports.resetAuthProgressState = resetAuthProgressState;
+exports.ensureSlottedCredential = ensureSlottedCredential;
+exports.listUsableCredentialSites = listUsableCredentialSites;
 exports.peekLoginState = peekLoginState;
 exports.ensureLogin = ensureLogin;
 exports.getLoginState = getLoginState;
@@ -22113,6 +22344,20 @@ function isUsableCredential(value) {
         typeof value === "object" &&
         Object.keys(value).length > 0);
 }
+/**
+ * 返回当前存在可用凭证的 site 槽位列表（凭证续期失败视为不可用）。
+ * 用于歧义 region（如 ap-singapore）时判定用户实际所属站点。
+ */
+async function listUsableCredentialSites() {
+    const usable = [];
+    for (const site of ["domestic", "intl"]) {
+        const state = await resolveSiteLoginState(site).catch(() => null);
+        if (state) {
+            usable.push(site);
+        }
+    }
+    return usable;
+}
 async function peekLoginState(options) {
     const envVarLoginState = normalizeLoginStateFromEnvVars(options);
     if (envVarLoginState) {
@@ -22135,8 +22380,23 @@ async function peekLoginState(options) {
         return envVarLoginState;
     }
     // 按 site 读取分槽凭证（缺省按 TCB_SITE/region 解析站点，默认 domestic）
-    const site = (0, site_map_js_1.normalizeSite)(options?.site) ?? (0, site_map_js_1.resolveSite)(options?.region, process.env.TCB_SITE);
-    const slotLoginState = await resolveSiteLoginState(site);
+    const explicitSite = (0, site_map_js_1.normalizeSite)(options?.site) ?? (0, site_map_js_1.normalizeSite)(process.env.TCB_SITE);
+    const site = explicitSite ?? (0, site_map_js_1.resolveSite)(options?.region);
+    let slotLoginState = await resolveSiteLoginState(site);
+    // 歧义 region（如 ap-singapore 同时属于 domestic 与 intl）且未显式指定 site 时，
+    // 解析槽位为空则回退检查另一槽位：仅另一槽位有可用凭证时直接使用，
+    // 避免对单站点用户误报 AUTH_REQUIRED（如国内站 ap-singapore 环境场景）。
+    if (!slotLoginState && !explicitSite && (0, site_map_js_1.getSite)(options?.region) === "ambiguous") {
+        const fallbackSite = site === "domestic" ? "intl" : "domestic";
+        const fallbackLoginState = await resolveSiteLoginState(fallbackSite);
+        if (fallbackLoginState) {
+            (0, logger_js_1.debug)("peekLoginState: ambiguous region, using the only usable site slot", {
+                resolvedSite: site,
+                fallbackSite,
+            });
+            return fallbackLoginState;
+        }
+    }
     if (slotLoginState) {
         return slotLoginState;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.32.2",
+  "version": "2.32.3",
   "mcpName": "io.github.TencentCloudBase/cloudbase-mcp",
   "packageManager": "pnpm@10.8.0",
   "description": "CloudBase MCP Server — operate Tencent CloudBase (database, auth, functions, storage, hosting) from AI coding tools via the Model Context Protocol. Part of CloudBase AI Toolkit.",