@cloudbase/cloudbase-mcp 2.36.0 → 2.36.1

package/dist/index.js

@@ -47,6 +47,7 @@ exports.resolveAuthProgressState = resolveAuthProgressState;
 exports.rejectAuthProgressState = rejectAuthProgressState;
 exports.resetAuthProgressState = resetAuthProgressState;
 exports.getCredentialSource = getCredentialSource;
+exports.isEnvCredentialRemovableByLogout = isEnvCredentialRemovableByLogout;
 exports.peekLoginState = peekLoginState;
 exports.ensureLogin = ensureLogin;
 exports.getLoginState = getLoginState;
@@ -480,6 +481,21 @@ function readProjectCredentialFile(projectRoot) {
         return null;
     }
 }
+/**
+ * 删掉项目级凭据文件。只删这一个文件，目录留着——删目录会顺带清掉同在里面的
+ * `project.json` 等项目配置。
+ *
+ * 不走 toolbox 的 `logout({cwd})`：那个接口会**无条件先删全局凭据**，而「退出本项目」
+ * 不该把用户的账号级登录一起注销掉。
+ */
+function deleteProjectCredentialFile(projectRoot) {
+    try {
+        (0, node_fs_1.unlinkSync)((0, node_path_1.join)((0, toolbox_1.getProjectDir)(projectRoot), "auth.json"));
+    }
+    catch {
+        // 文件本来就不在：登出是幂等的，不报错
+    }
+}
 /**
  * 项目级凭据优先于账号级全局登录态。
  *
@@ -537,6 +553,32 @@ function clearAdoptedProjectEnv() {
 function isAdoptedProjectCredential(apiKey, envId) {
     return adoptedProjectApiKey !== null && apiKey === adoptedProjectApiKey && envId === adoptedProjectEnvId;
 }
+/**
+ * env 里的这一份凭据能不能被 `logout()` 清掉。
+ *
+ * 能清掉的只有两种情况：是我们从项目级凭据文件回填的，或者它与当前项目级凭据文件里
+ * 那一份相同（`auth(login_by_api_key)` 写进程 env 的同时也把同一个 key 落到项目级）。
+ * 这两种都能沿 `logout()` 清掉：删项目级文件、再清 env。
+ *
+ * 其余情况是用户自己在 shell 或宿主配置里设的变量，进程删不掉，只能提示他去源头改。
+ */
+function isEnvCredentialRemovableByLogout() {
+    const apiKey = getCloudBaseApiKeyFromEnv();
+    const envId = process.env.CLOUDBASE_ENV_ID;
+    if (!apiKey || !envId) {
+        return false;
+    }
+    if (isAdoptedProjectCredential(apiKey, envId)) {
+        return true;
+    }
+    try {
+        const stored = readProjectCredentialFile((0, project_config_js_1.requireProjectRoot)());
+        return stored?.apiKey === apiKey && stored?.envId === envId;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 全局凭据文件 `~/.config/.cloudbase/auth.json` 与 CloudBase CLI 共用一份：用户会在终端里
  * `tcb login`，宿主连接器的登录按钮执行的也是 `tcb login --flow web --yes`，两者都在
@@ -578,6 +620,8 @@ async function peekLoginState(options) {
     dropStaleCredentialStoreCache();
     credentialSource = null;
     const envVarLoginState = normalizeLoginStateFromEnvVars(options);
+    // 回填的那份 key 换不出临时密钥时置位：项目级文件里是同一份，不必再试一次
+    let projectCredentialSkipped = false;
     if (envVarLoginState) {
         // API Key 模式：需要先用 API Key 换取临时密钥
         if ('_type' in envVarLoginState && envVarLoginState._type === 'api_key') {
@@ -599,16 +643,28 @@ async function peekLoginState(options) {
             }
             catch (e) {
                 (0, logger_js_1.debug)("peekLoginState: API Key login failed", { error: e instanceof Error ? e.message : String(e) });
-                return null;
+                // 我们回填的那份失效（密钥被撤、环境被删）：先清掉残留，别让它一直占着 env
+                // 把状态查询、登出、重新登录全堵死；项目文件本身不动，用户重新登录会覆盖它。
+                // 清完继续往下走，让账号级登录态接上。
+                if (isAdoptedProjectCredential(envVarLoginState.apiKey, envVarLoginState.envId)) {
+                    clearAdoptedProjectEnv();
+                    projectCredentialSkipped = true;
+                }
+                else {
+                    // 用户自己在 shell / 宿主配置里设的变量，登不登得上由他那边决定
+                    return null;
+                }
             }
         }
-        // 腾讯云密钥模式：直接返回
-        (0, logger_js_1.debug)("loginByApiSecret");
-        credentialSource = "env";
-        return envVarLoginState;
+        if (!projectCredentialSkipped) {
+            // 腾讯云密钥模式：直接返回
+            (0, logger_js_1.debug)("loginByApiSecret");
+            credentialSource = "env";
+            return envVarLoginState;
+        }
     }
     // 项目级凭据优先于账号级登录态（与 readProjectEnvId 同一原则）
-    const projectLoginState = await resolveProjectLoginState();
+    const projectLoginState = projectCredentialSkipped ? null : await resolveProjectLoginState();
     if (projectLoginState) {
         credentialSource = "project";
         return projectLoginState;
@@ -707,21 +763,44 @@ async function ensureLogin(options) {
 async function getLoginState(options) {
     return ensureLogin(options);
 }
+/**
+ * 退出登录：只清「当前生效的那一份」。
+ *
+ * 项目级凭据优先于账号级登录态，所以项目里有 API Key 时，登出只删项目文件、清掉
+ * 回填的环境变量，账号登录原样保留（删完它自动接上）。再调一次才轮到全局。
+ *
+ * 不把 cwd 交给 toolbox 的 `logout()`：那个接口会**无条件先删全局凭据**，
+ * 「退出本项目」不该把用户的账号级登录一起注销掉。
+ */
 async function logout(_options) {
     // 先同步缓存再删：否则 toolbox 会把本进程启动时的陈旧快照写回盘，
     // 把外部（CLI / 宿主登录按钮）刚写入的凭据一起抹掉。
     dropStaleCredentialStoreCache();
-    let cwd;
+    const removed = [];
+    let projectRoot;
     try {
-        cwd = (0, project_config_js_1.requireProjectRoot)();
+        projectRoot = (0, project_config_js_1.requireProjectRoot)();
     }
     catch {
-        cwd = undefined;
+        // 宿主配置目录等非法项目根：没有项目级凭据
+        projectRoot = undefined;
+    }
+    const envApiKey = getCloudBaseApiKeyFromEnv();
+    const hasProjectCredential = !!(projectRoot && readProjectCredentialFile(projectRoot));
+    // env 里那份是用户自己设的（进程删不掉）时，既不算项目级生效，也不该顺手注销账号登录
+    const projectInEffect = hasProjectCredential && (!envApiKey || isEnvCredentialRemovableByLogout());
+    if (projectInEffect && projectRoot) {
+        deleteProjectCredentialFile(projectRoot);
+        clearAdoptedProjectEnv();
+        removed.push("project");
+    }
+    else if (!envApiKey) {
+        await auth.logout();
+        removed.push("global");
     }
-    await auth.logout(cwd ? { cwd } : undefined);
-    clearAdoptedProjectEnv();
     credentialSource = null;
     resetAuthProgressState();
+    return { removed };
 }
 
 
@@ -2880,7 +2959,7 @@ exports.cloudrun = (0, types_js_1.defineModule)({
     "error.envNotInitialized": "当前环境（{envId}）尚未初始化云托管（CloudRun Env）。不能直接创建服务（CreateCloudRunServer 在无大租户记录时会默认创建到小租户，产生错误的小租户服务与版本）。\n请先开通云托管环境，再重试部署：\n- MCP：manageCloudRun(action=\"initEnv\", envId=\"{envId}\")（异步开通，幂等；开通完成后可用 queryCloudRun(action=\"envStatus\", envId=\"{envId}\") 查询 Status=normal）\n- 或控制台：环境 → 云托管 → 开通（https://tcb.cloud.tencent.com/dev?envId={envId}#/platform-run）\n初始化完成后重新调用 manageCloudRun(action=\"deploy\")。",
     "error.actionFailed": "[{context}] {baseMessage}",
     "error.buildManage": "[manageCloudRun/{action}] {baseMessage}\n建议：{suggestions}",
-    "error.deployTaskRunning": "服务 `{serverName}` 当前已有部署任务在执行，请等待现有任务完成后再重试。",
+    "error.deployTaskRunning": "服务 `{serverName}` 当前已有部署任务在执行。**不要再发起 deploy**：先用 queryCloudRun(action=\"getManageTask\", serverName=\"{serverName}\") 读取该任务的真实状态——已结束就重新部署，长时间停在非终态则带上该输出联系 CloudBase 平台排查。",
     "error.deployTaskRunningForce": "注意：`force=true` 仅跳过本工具的确认提示，不会取消或覆盖平台上的发布任务。请先用 queryCloudRun(action=\"getManageTask\", serverName=\"{serverName}\") 确认任务真实状态：若任务已结束却仍报此错，或任务长时间停在非终态，请携带该输出联系 CloudBase 平台排查该环境的发布任务。",
     "error.vpcRequired": "CreateCloudRunServer 需要有效 VPC：请传 serverConfig.VpcConf（VpcId+SubnetId），或在 initEnv 时传入 vpcId/subnetIds（环境开通后 deploy 会自动从 EnvBaseInfo 回填）。若平台拒绝系统创建网络，必须指定上海地域 VPC。",
     "error.genericRetry": "请检查服务状态、部署参数和目标目录后重试。",
@@ -3070,7 +3149,7 @@ exports.cloudrun = (0, types_js_1.defineModule)({
     "error.envNotInitialized": "The current environment ({envId}) has not initialized CloudRun (CloudRun Env). You cannot create services directly (without a large-tenant record, CreateCloudRunServer defaults to the small tenant, producing wrong small-tenant services and versions).\nProvision the CloudRun env first, then retry the deploy:\n- MCP: manageCloudRun(action=\"initEnv\", envId=\"{envId}\") (async, idempotent; once done, query Status=normal via queryCloudRun(action=\"envStatus\", envId=\"{envId}\"))\n- Or console: Environment → CloudRun → Provision (https://tcb.cloud.tencent.com/dev?envId={envId}#/platform-run)\nAfter initialization, call manageCloudRun(action=\"deploy\") again.",
     "error.actionFailed": "[{context}] {baseMessage}",
     "error.buildManage": "[manageCloudRun/{action}] {baseMessage}\nSuggestions: {suggestions}",
-    "error.deployTaskRunning": "Service `{serverName}` already has a deploy task running. Wait for the current task to finish before retrying.",
+    "error.deployTaskRunning": "Service `{serverName}` already has a deploy task running. Do NOT call deploy again: first read the real task state with queryCloudRun(action=\"getManageTask\", serverName=\"{serverName}\") - redeploy once it has finished, or contact the CloudBase platform with that output if it stays in a non-terminal state for a long time.",
     "error.deployTaskRunningForce": "Note: `force=true` only skips this tool's confirmation prompt; it does not cancel or override the platform-side deploy task. First confirm the real task state with queryCloudRun(action=\"getManageTask\", serverName=\"{serverName}\"): if the task has already finished but this error persists, or it stays in a non-terminal state for a long time, contact the CloudBase platform with that output to investigate this environment's deploy task.",
     "error.vpcRequired": "CreateCloudRunServer requires a valid VPC: pass serverConfig.VpcConf (VpcId+SubnetId), or pass vpcId/subnetIds during initEnv (after provisioning, deploy auto-fills from EnvBaseInfo). If the platform rejects system-created networks, you must specify a Shanghai-region VPC.",
     "error.genericRetry": "Check the service status, deploy parameters, and target directory, then retry.",
@@ -4674,9 +4753,12 @@ exports.env = (0, types_js_1.defineModule)({
     "auth.envReadyWithHint": "环境设置成功，当前环境: {envId}{regionHint}",
     "auth.regionHint": "，地域: {region}",
     "auth.regionHintUnverified": "。未在当前探测地域中确认该 envId，已按唯一 ID 直绑；若后续接口仍指向错误地域，请设置 TCB_REGION 或 queryEnv(action=\"list\", region=...)",
-    "auth.logoutNotAllowedApiKey": "当前使用 API Key 认证模式，不支持退出登录。如需切换认证方式，请移除 CLOUDBASE_API_KEY（或兼容的 CLOUDBASE_APIKEY）环境变量后重启。",
+    "auth.logoutNotAllowedApiKey": "当前是 API Key 认证模式，凭据来自环境变量 {varName}。这个变量不是本进程设的、也不由本进程清除，所以没有执行登出。要切换认证方式：在 shell 里 unset {varName}，或从启动本 MCP 的客户端配置里移除它，然后重启。",
     "auth.logoutConfirmRequired": "action=logout 时必须传 confirm=\"yes\"",
     "auth.loggedOut": "✅ 已退出登录",
+    "auth.loggedOutProject": "✅ 已移除本项目的 API Key 登录。这台机器上若还有账号登录，它仍然有效；要一起退出请再执行一次 logout。",
+    "auth.apiKeySwitchHintRemovable": "如需改用账号登录，先执行 logout 退出本项目 API Key，再 start_auth 授权。",
+    "auth.apiKeySwitchHintExternal": "这个 key 来自外部环境变量，MCP 无法退出它；如需改用账号登录，先在 shell 或客户端配置里移除 {varName} 并重启。",
     "auth.tempCredNotLoggedIn": "当前未登录，请先完成管理端认证后再获取临时密钥。",
     "auth.tempCredConfirmRequired": "action=get_temp_credentials 时必须显式传 confirm=\"yes\"，以确认你要导出当前管理端临时密钥。",
     "auth.tempCredUnsupportedType": "当前登录态不是可导出的临时密钥。仅支持通过 Web / device 登录得到的临时密钥，永久密钥登录不允许导出。",
@@ -4937,9 +5019,12 @@ exports.env = (0, types_js_1.defineModule)({
     "auth.envReadyWithHint": "Environment bound successfully. Current env: {envId}{regionHint}",
     "auth.regionHint": ", region: {region}",
     "auth.regionHintUnverified": ". This envId was not confirmed in the probed regions, so it was bound directly by its unique ID; if later APIs still target the wrong region, set TCB_REGION or use queryEnv(action=\"list\", region=...)",
-    "auth.logoutNotAllowedApiKey": "API Key authentication mode is in use and logout is not supported. To switch the authentication method, remove the CLOUDBASE_API_KEY (or the compatible CLOUDBASE_APIKEY) environment variable and restart.",
+    "auth.logoutNotAllowedApiKey": "API Key authentication mode is in use, and the credential comes from the {varName} environment variable. This process neither set nor can remove that variable, so logout was skipped. To switch authentication methods, unset {varName} in your shell or remove it from the MCP client configuration, then restart.",
     "auth.logoutConfirmRequired": "confirm=\"yes\" must be passed when action=logout",
     "auth.loggedOut": "✅ Logged out",
+    "auth.loggedOutProject": "✅ Removed this project's API Key login. An account login on this machine is still active; call logout again to sign out of it.",
+    "auth.apiKeySwitchHintRemovable": "To switch to account login, run logout to remove this project's API Key, then start_auth.",
+    "auth.apiKeySwitchHintExternal": "This key comes from an external environment variable and cannot be removed by MCP. To switch to account login, unset {varName} in your shell or client configuration and restart.",
     "auth.tempCredNotLoggedIn": "Not logged in. Complete management-plane authentication before fetching temporary credentials.",
     "auth.tempCredConfirmRequired": "confirm=\"yes\" must be passed explicitly when action=get_temp_credentials, to confirm that you want to export the current management-plane temporary credentials.",
     "auth.tempCredUnsupportedType": "The current login state is not an exportable temporary credential. Only temporary credentials obtained via Web / device login are supported; permanent key logins cannot be exported.",
@@ -5318,9 +5403,12 @@ exports.functions = (0, types_js_1.defineModule)({
         "\n- `limit`: 分页数量，默认值由后端决定" +
         "\n- `offset`: 分页偏移，从 0 开始" +
         "\n- 示例：`queryFunctions(action=\"listFunctions\", offset=10, limit=10)`" +
-        "\n\n**查询 CloudBase 云函数日志**：使用 `action=\"listFunctionLogs\"`，需要提供 `functionName` 参数。" +
+        "\n\n**查询 CloudBase 云函数日志**：`action=\"listFunctionLogs\"`，需要提供 `functionName`。日志从 CLS 检索（底层 GetFunctionLogs 接口已下线）。" +
         "\n- 示例：`queryFunctions(action=\"listFunctionLogs\", functionName=\"my-function\")`" +
-        "\n- 如需查看日志详情：`queryFunctions(action=\"getFunctionLogDetail\", requestId=\"xxx\")`" +
+        "\n- 不传 startTime/endTime 时默认查最近 1 天；跨度不能超过 1 天，单次最多返回 100 条" +
+        "\n- 返回 `hasMore=true` 表示还有更早的日志：把返回的 `context` 原样传回取下一页（`offset` 只在前 100 条内生效）" +
+        "\n- `logs[]` 已解析成 requestId / log / statusCode / retCode / durationMs / memoryMb / timestamp" +
+        "\n- 想看某一次调用的完整过程（START、业务日志、REPORT）：`queryFunctions(action=\"getFunctionLogDetail\", requestId=\"xxx\")`" +
         "\n\n**定时任务 / cron / 定时跑**：使用 `listFunctionTriggers` 查询函数的 timer 触发器配置。" +
         "\n\n**版本与流量路由**：`listVersionByFunction` 列出已发布版本（对齐 tcb fn list-function-versions）；`getFunctionAlias` 查看别名/灰度配置（对齐 tcb fn get-route，aliasName 默认 `$DEFAULT`）。" +
         "\n\n**层（Layer）说明**：" +
@@ -5390,8 +5478,8 @@ exports.functions = (0, types_js_1.defineModule)({
     endTimeInvalid: "endTime 格式错误: \"{value}\"。必须使用 YYYY-MM-DD HH:mm:ss 格式（如 2024-01-01 23:59:59）",
     logRangeInvalidDatetime: "startTime 和 endTime 必须是有效的日期时间字符串",
     logRangeTooLong: "startTime 和 endTime 间隔不能超过一天",
-    logsInvalidParamTips: "常见原因：\n1. startTime/endTime 格式错误，必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00），不支持 ISO 8601 或时间戳\n2. startTime 和 endTime 间隔超过一天\n3. functionName 不存在或格式不正确\n建议：不传 startTime/endTime 时默认查询最近一天的日志。",
-    logDetailInvalidParamTips: "常见原因：\n1. startTime/endTime 格式错误，必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00），不支持 ISO 8601 或时间戳\n2. startTime 和 endTime 间隔超过一天\n建议：不传 startTime/endTime 时默认查询最近一天的日志。",
+    logsInvalidParamTips: "常见原因：\n1. startTime/endTime 格式错误，必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00），不支持 ISO 8601 或时间戳\n2. startTime 和 endTime 间隔超过一天\n3. functionName 与日志里的 function_name 不一致（大小写敏感），或 qualifier 不匹配\n建议：不传 startTime/endTime 时默认查询最近一天的日志。",
+    logDetailInvalidParamTips: "常见原因：\n1. startTime/endTime 格式错误，必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00），不支持 ISO 8601 或时间戳\n2. startTime 和 endTime 间隔超过一天\n3. requestId 不在该时间窗口内（日志按请求开始时间归档）\n建议：先用 listFunctionLogs 定位到 requestId 再查详情。",
     paramRequired: "{action} 操作时，{param} 参数是必需的",
     "deployStatus.cloudMode": "{action} 在 cloud mode 下不可用：异步部署任务只由 buildStrategy=cloud/local 的真实部署创建，而这两种策略的真实执行在 cloud mode 下都不支持（需要读取本地构建上下文或本地 Docker），因此不会存在任何 taskId。buildStrategy=image 走同步部署，直接在 manageFunctions 的返回里拿结果，也不需要查询部署状态。如需异步镜像构建部署，请改用本地 MCP 模式。",
     deployTaskNotFound: "未找到部署任务 {taskId}；部署任务不存在，可能已过期、不属于当前环境 {envId}，或 MCP Server 已重启（任务仅保存在 MCP 进程内存中）。",
@@ -5406,7 +5494,11 @@ exports.functions = (0, types_js_1.defineModule)({
     "reason.viewLogs": "查看该函数的执行日志",
     "reason.updateConfig": "更新该函数配置",
     "reason.checkGateway": "查看该函数是否已暴露网关访问入口",
-    "reason.logDetail": "按 requestId 查看单条日志详情",
+    "reason.logDetail": "按 requestId 查看该次调用的完整日志",
+    "reason.nextLogPage": "带上 context 取下一页（更早的）日志",
+    "reason.widenLogRange": "放宽时间范围后重新查询该函数的日志",
+    "reason.createLogService": "开通环境日志服务后再查询函数日志",
+    "reason.searchClsFallback": "改用 queryLogs 直接按同一条 CLS 语句检索",
     "reason.attachLayer": "为该函数追加绑定层",
     "reason.reorderLayers": "整体调整层顺序或绑定列表",
     "reason.layerVersions": "查看某个层的版本列表",
@@ -5451,6 +5543,10 @@ exports.functions = (0, types_js_1.defineModule)({
     gotFunctionDetail: "已获取函数 {fnName} 的详情",
     gotFunctionLogs: "已获取函数 {fnName} 的日志列表",
     gotLogDetail: "已获取 requestId={requestId} 的日志详情",
+    "logs.emptyByFunction": "在 {start} ~ {end} 之间没有查到函数 {fnName} 的日志。常见原因：该时间段内函数没有被调用、日志已过保留期、或 functionName / qualifier 不匹配。可以放宽时间范围后重试。",
+    "logs.emptyByRequest": "在 {start} ~ {end} 之间没有查到 requestId={requestId} 的日志。请确认时间范围覆盖了这次调用（日志按请求开始时间归档），或先用 listFunctionLogs 定位到的 requestId。",
+    "logs.serviceNotEnabled": "当前环境还没有开通日志服务，云函数日志查不到。请先调用 manageLogs(action=\"createLogService\", confirm=true) 开通，再重新查询。",
+    "logs.queryFailed": "查询云函数日志失败：{message}",
     gotFunctionLayers: "已获取函数 {fnName} 当前绑定的层",
     gotLayers: "已获取 {count} 条层记录",
     gotLayerVersions: "已获取层 {layerName} 的版本列表",
@@ -5531,16 +5627,17 @@ exports.functions = (0, types_js_1.defineModule)({
     "schema.create.layers": "Layer 配置",
     "schema.manageLayer.name": "层名称",
     "schema.manageLayer.version": "层版本号",
-    "schema.query.action": "只读操作类型：\n- `listFunctions`: 列出所有 CloudBase 云函数\n- `getFunctionDetail`: 获取 CloudBase 云函数详情（需要 functionName）\n- `listFunctionLogs`: 查询 CloudBase 云函数执行日志（需要 functionName）\n- `getFunctionLogDetail`: 获取日志详情（需要 requestId）\n- `listFunctionLayers`: 列出函数绑定的层\n- `listLayers`: 列出所有层（账号级视图，含其他环境创建的层）\n- `listLayerVersions`: 列出层的版本（注意：是 Versions 不是 Version；账号级视图）\n- `getLayerVersionDetail`: 获取层版本详情（账号级视图）\n- `listFunctionTriggers`: 列出函数触发器（用于查看定时任务 / cron / timer 配置）\n- `getFunctionDownloadUrl`: 获取函数代码下载地址\n- `getFunctionDeployStatus`: 按 taskId 查询异步部署状态、阶段进度和最终结果。返回 data.build（构建子状态）、data.deploy（部署子状态）、data.progress（阶段事件）；status=running 时 data.result 与 data.error 一律为 null，不得报告部署完成。调用方必须持续轮询直到 status=succeeded/failed；status=expired 表示任务超过最长保留时间（2 小时）被终结，云端可能仍在部署，需用 getFunctionDetail 确认。任务只保存在 MCP 进程内存中，过期或 MCP Server 重启后返回 errorCode=DEPLOY_TASK_NOT_FOUND；任务按环境隔离，只能查到当前环境自己发起的部署。cloud mode 下本 action 不可用：异步任务只由 buildStrategy=cloud/local 的真实部署创建，而这两种策略在 cloud mode 下都不支持真实执行，image 策略则走同步部署不产生 taskId。\n- `listVersionByFunction`: 列出函数已发布版本（对齐 tcb fn list-function-versions / SDK listVersionByFunction；需要 functionName）\n- `getFunctionAlias`: 查询函数别名与流量路由（对齐 tcb fn get-route / SDK getFunctionAlias；需要 functionName；aliasName 默认 $DEFAULT）\n- `getFunctionUploadUrl`: 获取函数代码包的 COS 预签名上传地址（ZIP 两段式部署阶段 A）：PUT 代码 zip 到 uploadUrl（uploadHeaders 非空时须随请求携带对应请求头），再调用 manageFunctions 的 createFunction/updateFunctionCode 并传 code 三元组（阶段 B）。functionName 可选，仅用于生成上传对象 key。返回的 uploadUrl 含凭据签名，不得写入日志或持久化；阶段 B 会校验三元组的桶与地域必须是本环境自有存储桶，因此该地址只能用于取到它的那个环境；地址默认 300 秒内有效",
+    "schema.query.action": "只读操作类型：\n- `listFunctions`: 列出所有 CloudBase 云函数\n- `getFunctionDetail`: 获取 CloudBase 云函数详情（需要 functionName）\n- `listFunctionLogs`: 查询云函数执行日志（需要 functionName；走 CLS 检索，默认最近 1 天，单次最多 100 条，翻页传 context）\n- `getFunctionLogDetail`: 获取某次调用的完整日志序列（需要 requestId，取自 listFunctionLogs 的 logs[].requestId）\n- `listFunctionLayers`: 列出函数绑定的层\n- `listLayers`: 列出所有层（账号级视图，含其他环境创建的层）\n- `listLayerVersions`: 列出层的版本（注意：是 Versions 不是 Version；账号级视图）\n- `getLayerVersionDetail`: 获取层版本详情（账号级视图）\n- `listFunctionTriggers`: 列出函数触发器（用于查看定时任务 / cron / timer 配置）\n- `getFunctionDownloadUrl`: 获取函数代码下载地址\n- `getFunctionDeployStatus`: 按 taskId 查询异步部署状态、阶段进度和最终结果。返回 data.build（构建子状态）、data.deploy（部署子状态）、data.progress（阶段事件）；status=running 时 data.result 与 data.error 一律为 null，不得报告部署完成。调用方必须持续轮询直到 status=succeeded/failed；status=expired 表示任务超过最长保留时间（2 小时）被终结，云端可能仍在部署，需用 getFunctionDetail 确认。任务只保存在 MCP 进程内存中，过期或 MCP Server 重启后返回 errorCode=DEPLOY_TASK_NOT_FOUND；任务按环境隔离，只能查到当前环境自己发起的部署。cloud mode 下本 action 不可用：异步任务只由 buildStrategy=cloud/local 的真实部署创建，而这两种策略在 cloud mode 下都不支持真实执行，image 策略则走同步部署不产生 taskId。\n- `listVersionByFunction`: 列出函数已发布版本（对齐 tcb fn list-function-versions / SDK listVersionByFunction；需要 functionName）\n- `getFunctionAlias`: 查询函数别名与流量路由（对齐 tcb fn get-route / SDK getFunctionAlias；需要 functionName；aliasName 默认 $DEFAULT）\n- `getFunctionUploadUrl`: 获取函数代码包的 COS 预签名上传地址（ZIP 两段式部署阶段 A）：PUT 代码 zip 到 uploadUrl（uploadHeaders 非空时须随请求携带对应请求头），再调用 manageFunctions 的 createFunction/updateFunctionCode 并传 code 三元组（阶段 B）。functionName 可选，仅用于生成上传对象 key。返回的 uploadUrl 含凭据签名，不得写入日志或持久化；阶段 B 会校验三元组的桶与地域必须是本环境自有存储桶，因此该地址只能用于取到它的那个环境；地址默认 300 秒内有效",
     "schema.query.functionName": "CloudBase 云函数名称。`getFunctionDetail`、`listFunctionLogs`、`listFunctionLayers`、`listFunctionTriggers`、`getFunctionDownloadUrl`、`listVersionByFunction`、`getFunctionAlias` 时必填；`getFunctionUploadUrl` 可选（仅用于生成上传对象 key）",
-    "schema.query.limit": "分页数量（limit）。列表类 action 可选，默认值由后端决定",
-    "schema.query.offset": "分页偏移（offset）。列表类 action 可选，默认 0",
+    "schema.query.limit": "分页数量（limit）。列表类 action 可选，默认值由后端决定；日志类 action 单次最多 100 条，默认 20",
+    "schema.query.offset": "分页偏移（offset）。列表类 action 可选，默认 0。日志类 action 只在前 100 条内生效，更早的日志请用返回的 context 翻页",
     "schema.query.codeSecret": "代码保护密钥，用于解密函数代码",
     "schema.query.revealEnvValues": "getFunctionDetail / listFunctionTriggers / listFunctionLayers 时是否返回环境变量明文值。默认 false：Value 脱敏为 ***，仅保留 Key 与 ValueLength，足以确认配置了哪些变量及变更是否生效；true 时返回明文，敏感变量会进入模型上下文，谨慎使用。如需查看明文，建议优先使用控制台或 CLI",
-    "schema.query.startTime": "日志查询开始时间，格式必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00）。与 endTime 间隔不能超过一天。不传时默认查询最近一天",
-    "schema.query.endTime": "日志查询结束时间，格式必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 23:59:59）。与 startTime 间隔不能超过一天。不传时默认为当前时间",
-    "schema.query.requestId": "日志请求 ID。`getFunctionLogDetail` 操作必填，可从 `listFunctionLogs` 结果中获取",
-    "schema.query.qualifier": "函数版本别名，如 $LATEST、$DEFAULT。日志查询时可选",
+    "schema.query.startTime": "日志查询开始时间，格式必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 00:00:00，按北京时间理解）。与 endTime 间隔不能超过一天。不传时默认查询最近一天",
+    "schema.query.endTime": "日志查询结束时间，格式必须为 YYYY-MM-DD HH:mm:ss（如 2024-01-01 23:59:59，按北京时间理解）。与 startTime 间隔不能超过一天。不传时默认为当前时间",
+    "schema.query.requestId": "日志请求 ID。`getFunctionLogDetail` 操作必填；取自 `listFunctionLogs` 返回的 logs[].requestId，也可传具体业务日志里出现的 RequestId",
+    "schema.query.qualifier": "函数版本别名，如 $LATEST、$DEFAULT。日志查询时可选，作为 CLS 检索条件",
+    "schema.query.context": "日志翻页游标。把上一次 `listFunctionLogs` 返回的 `context` 原样传回即可取下一页；不要自己构造，null 表示没有更多",
     "schema.query.runtime": "层查询的运行时筛选，如 Nodejs18.15",
     "schema.query.searchKey": "层名称搜索关键字",
     "schema.query.layerName": "层名称。`listLayerVersions`、`getLayerVersionDetail` 操作必填。层为账号级共享命名空间；推荐固定格式 `{layerName}_{当前envId}`（如 common_cloud1-d9ghadgak3edf6b36）",
@@ -5599,9 +5696,12 @@ exports.functions = (0, types_js_1.defineModule)({
         "\n- `limit`: page size, the default is decided by the backend" +
         "\n- `offset`: pagination offset, starting from 0" +
         "\n- Example: `queryFunctions(action=\"listFunctions\", offset=10, limit=10)`" +
-        "\n\n**Querying cloud function logs**: use `action=\"listFunctionLogs\"`, which requires the `functionName` parameter." +
+        "\n\n**Querying cloud function logs**: use `action=\"listFunctionLogs\"`, which requires `functionName`. Logs are retrieved from CLS (the underlying GetFunctionLogs API has been retired)." +
         "\n- Example: `queryFunctions(action=\"listFunctionLogs\", functionName=\"my-function\")`" +
-        "\n- To view log details: `queryFunctions(action=\"getFunctionLogDetail\", requestId=\"xxx\")`" +
+        "\n- Without startTime/endTime it queries the last day; the span must not exceed 1 day and a single call returns at most 100 entries" +
+        "\n- `hasMore=true` means older logs exist: pass the returned `context` back unchanged to fetch the next page (`offset` only works within the first 100 entries)" +
+        "\n- Each `logs[]` item is parsed into requestId / log / statusCode / retCode / durationMs / memoryMb / timestamp" +
+        "\n- To see the full sequence of one invocation (START, business logs, REPORT): `queryFunctions(action=\"getFunctionLogDetail\", requestId=\"xxx\")`" +
         "\n\n**Scheduled tasks / cron / timers**: use `listFunctionTriggers` to query a function's timer trigger configuration." +
         "\n\n**Versions and traffic routing**: `listVersionByFunction` lists published versions (aligns with tcb fn list-function-versions); `getFunctionAlias` views alias / canary config (aligns with tcb fn get-route; aliasName defaults to `$DEFAULT`)." +
         "\n\n**Layers**:" +
@@ -5671,8 +5771,8 @@ exports.functions = (0, types_js_1.defineModule)({
     endTimeInvalid: "Invalid endTime: \"{value}\". It must use the YYYY-MM-DD HH:mm:ss format (e.g. 2024-01-01 23:59:59)",
     logRangeInvalidDatetime: "startTime and endTime must be valid datetime strings",
     logRangeTooLong: "The interval between startTime and endTime must not exceed one day",
-    logsInvalidParamTips: "Common causes:\n1. startTime/endTime format error; it must be YYYY-MM-DD HH:mm:ss (e.g. 2024-01-01 00:00:00); ISO 8601 or timestamps are not supported\n2. The interval between startTime and endTime exceeds one day\n3. functionName does not exist or is malformed\nTip: without startTime/endTime, logs from the most recent day are queried by default.",
-    logDetailInvalidParamTips: "Common causes:\n1. startTime/endTime format error; it must be YYYY-MM-DD HH:mm:ss (e.g. 2024-01-01 00:00:00); ISO 8601 or timestamps are not supported\n2. The interval between startTime and endTime exceeds one day\nTip: without startTime/endTime, logs from the most recent day are queried by default.",
+    logsInvalidParamTips: "Common causes:\n1. startTime/endTime format error; it must be YYYY-MM-DD HH:mm:ss (e.g. 2024-01-01 00:00:00); ISO 8601 or timestamps are not supported\n2. The interval between startTime and endTime exceeds one day\n3. functionName does not match function_name in the logs (case-sensitive), or qualifier does not match\nTip: without startTime/endTime, logs from the most recent day are queried by default.",
+    logDetailInvalidParamTips: "Common causes:\n1. startTime/endTime format error; it must be YYYY-MM-DD HH:mm:ss (e.g. 2024-01-01 00:00:00); ISO 8601 or timestamps are not supported\n2. The interval between startTime and endTime exceeds one day\n3. requestId falls outside that window (logs are filed by request start time)\nTip: locate the requestId with listFunctionLogs first.",
     paramRequired: "The {param} parameter is required for the {action} action",
     "deployStatus.cloudMode": "{action} is unavailable in cloud mode: async deployment tasks are only created by real deployments with buildStrategy=cloud/local, and real execution of both strategies is unsupported in cloud mode (they need the local build context or local Docker), so no taskId can exist. buildStrategy=image uses synchronous deployment and returns the result directly from manageFunctions, so no deployment status query is needed. For async image build deployment, switch to local MCP mode.",
     deployTaskNotFound: "Deployment task {taskId} not found; the task does not exist — it may have expired, belong to a different environment than {envId}, or the MCP Server was restarted (tasks are only kept in MCP process memory).",
@@ -5687,7 +5787,11 @@ exports.functions = (0, types_js_1.defineModule)({
     "reason.viewLogs": "View the execution logs of this function",
     "reason.updateConfig": "Update this function's configuration",
     "reason.checkGateway": "Check whether this function has an exposed gateway access URL",
-    "reason.logDetail": "View a single log entry by requestId",
+    "reason.logDetail": "View the full logs of that invocation by requestId",
+    "reason.nextLogPage": "Pass context back to fetch the next (older) page of logs",
+    "reason.widenLogRange": "Query this function's logs again with a wider time range",
+    "reason.createLogService": "Enable the environment log service before querying function logs",
+    "reason.searchClsFallback": "Search CLS directly with queryLogs using the same query string",
     "reason.attachLayer": "Attach an additional layer to this function",
     "reason.reorderLayers": "Adjust layer order or the binding list as a whole",
     "reason.layerVersions": "View the version list of a layer",
@@ -5732,6 +5836,10 @@ exports.functions = (0, types_js_1.defineModule)({
     gotFunctionDetail: "Retrieved details of function {fnName}",
     gotFunctionLogs: "Retrieved the log list of function {fnName}",
     gotLogDetail: "Retrieved the log detail for requestId={requestId}",
+    "logs.emptyByFunction": "No logs found for function {fnName} between {start} and {end}. Common causes: the function was not invoked in that window, the logs have passed their retention period, or functionName / qualifier does not match. Widen the time range and retry.",
+    "logs.emptyByRequest": "No logs found for requestId={requestId} between {start} and {end}. Make sure the window covers that invocation (logs are filed by request start time), or use a requestId located through listFunctionLogs.",
+    "logs.serviceNotEnabled": "The log service is not enabled for this environment, so function logs cannot be read. Call manageLogs(action=\"createLogService\", confirm=true) first, then query again.",
+    "logs.queryFailed": "Failed to query function logs: {message}",
     gotFunctionLayers: "Retrieved the layers currently bound to function {fnName}",
     gotLayers: "Retrieved {count} layer records",
     gotLayerVersions: "Retrieved the version list of layer {layerName}",
@@ -5812,16 +5920,17 @@ exports.functions = (0, types_js_1.defineModule)({
     "schema.create.layers": "Layer configuration",
     "schema.manageLayer.name": "Layer name",
     "schema.manageLayer.version": "Layer version number",
-    "schema.query.action": "Read-only action type:\n- `listFunctions`: list all CloudBase cloud functions\n- `getFunctionDetail`: get function details (requires functionName)\n- `listFunctionLogs`: query function execution logs (requires functionName)\n- `getFunctionLogDetail`: get log details (requires requestId)\n- `listFunctionLayers`: list layers bound to a function\n- `listLayers`: list all layers (account-level view, including layers from other environments)\n- `listLayerVersions`: list layer versions (Versions, not Version; account-level view)\n- `getLayerVersionDetail`: get layer version details (account-level view)\n- `listFunctionTriggers`: list function triggers (scheduled task / cron / timer configuration)\n- `getFunctionDownloadUrl`: get the function code download URL\n- `getFunctionDeployStatus`: query async deployment status, stage progress, and final result by taskId. Returns data.build, data.deploy, and data.progress. While status=running, data.result and data.error are null and deployment must not be reported as complete. Keep polling until status=succeeded/failed. status=expired means the task exceeded the 2-hour retention limit; cloud deployment may still be running, so confirm with getFunctionDetail. Tasks exist only in MCP process memory; expired tasks or a restarted MCP Server return errorCode=DEPLOY_TASK_NOT_FOUND. Tasks are isolated by environment. This action is unavailable in cloud mode because real cloud/local builds cannot run there, while image deployment is synchronous and creates no taskId.\n- `listVersionByFunction`: list published function versions (aligns with tcb fn list-function-versions / SDK listVersionByFunction; requires functionName)\n- `getFunctionAlias`: get function alias and traffic routing (aligns with tcb fn get-route / SDK getFunctionAlias; requires functionName; aliasName defaults to $DEFAULT)\n- `getFunctionUploadUrl`: get a COS presigned upload URL for a function code package (two-phase ZIP deployment phase A): PUT the code zip to uploadUrl (include the corresponding request headers when uploadHeaders is non-empty), then call manageFunctions createFunction/updateFunctionCode with the code triplet (phase B). functionName is optional and only shapes the upload object key. The uploadUrl carries credential-bound signatures; never log or persist it; phase B verifies that the triplet's bucket and region are this environment's own bucket, so an address is only usable in the environment it was minted for; the address is valid for 300 seconds by default",
+    "schema.query.action": "Read-only action type:\n- `listFunctions`: list all CloudBase cloud functions\n- `getFunctionDetail`: get function details (requires functionName)\n- `listFunctionLogs`: query function execution logs (requires functionName; retrieved via CLS, defaults to the last day, at most 100 entries per call, pass context to page)\n- `getFunctionLogDetail`: get the full log sequence of one invocation (requires requestId, taken from logs[].requestId of listFunctionLogs)\n- `listFunctionLayers`: list layers bound to a function\n- `listLayers`: list all layers (account-level view, including layers from other environments)\n- `listLayerVersions`: list layer versions (Versions, not Version; account-level view)\n- `getLayerVersionDetail`: get layer version details (account-level view)\n- `listFunctionTriggers`: list function triggers (scheduled task / cron / timer configuration)\n- `getFunctionDownloadUrl`: get the function code download URL\n- `getFunctionDeployStatus`: query async deployment status, stage progress, and final result by taskId. Returns data.build, data.deploy, and data.progress. While status=running, data.result and data.error are null and deployment must not be reported as complete. Keep polling until status=succeeded/failed. status=expired means the task exceeded the 2-hour retention limit; cloud deployment may still be running, so confirm with getFunctionDetail. Tasks exist only in MCP process memory; expired tasks or a restarted MCP Server return errorCode=DEPLOY_TASK_NOT_FOUND. Tasks are isolated by environment. This action is unavailable in cloud mode because real cloud/local builds cannot run there, while image deployment is synchronous and creates no taskId.\n- `listVersionByFunction`: list published function versions (aligns with tcb fn list-function-versions / SDK listVersionByFunction; requires functionName)\n- `getFunctionAlias`: get function alias and traffic routing (aligns with tcb fn get-route / SDK getFunctionAlias; requires functionName; aliasName defaults to $DEFAULT)\n- `getFunctionUploadUrl`: get a COS presigned upload URL for a function code package (two-phase ZIP deployment phase A): PUT the code zip to uploadUrl (include the corresponding request headers when uploadHeaders is non-empty), then call manageFunctions createFunction/updateFunctionCode with the code triplet (phase B). functionName is optional and only shapes the upload object key. The uploadUrl carries credential-bound signatures; never log or persist it; phase B verifies that the triplet's bucket and region are this environment's own bucket, so an address is only usable in the environment it was minted for; the address is valid for 300 seconds by default",
     "schema.query.functionName": "CloudBase cloud function name. Required for `getFunctionDetail`, `listFunctionLogs`, `listFunctionLayers`, `listFunctionTriggers`, `getFunctionDownloadUrl`, `listVersionByFunction`, and `getFunctionAlias`. Optional for `getFunctionUploadUrl` (only used to generate the upload object key).",
-    "schema.query.limit": "Page size (limit). Optional for list actions; the backend determines the default.",
-    "schema.query.offset": "Pagination offset. Optional for list actions; defaults to 0.",
+    "schema.query.limit": "Page size (limit). Optional for list actions; the backend determines the default. Log actions return at most 100 entries and default to 20.",
+    "schema.query.offset": "Pagination offset. Optional for list actions; defaults to 0. For log actions it only works within the first 100 entries — use the returned context to page further back.",
     "schema.query.codeSecret": "Code protection secret used to decrypt function code.",
     "schema.query.revealEnvValues": "Whether `getFunctionDetail` / `listFunctionTriggers` / `listFunctionLayers` returns plaintext environment variable values. Defaults to false: Value is masked as ***, while Key and ValueLength remain, which is sufficient to verify configured variables and changes. true returns plaintext and may expose secrets to the model context; use cautiously. Prefer the console or CLI for plaintext values.",
-    "schema.query.startTime": "Log query start time in YYYY-MM-DD HH:mm:ss format (for example, 2024-01-01 00:00:00). The interval to endTime must not exceed one day. Defaults to the most recent day when omitted.",
-    "schema.query.endTime": "Log query end time in YYYY-MM-DD HH:mm:ss format (for example, 2024-01-01 23:59:59). The interval from startTime must not exceed one day. Defaults to the current time when omitted.",
-    "schema.query.requestId": "Log request ID. Required for `getFunctionLogDetail`; obtain it from `listFunctionLogs`.",
-    "schema.query.qualifier": "Function version alias, such as $LATEST or $DEFAULT. Optional for log queries.",
+    "schema.query.startTime": "Log query start time in YYYY-MM-DD HH:mm:ss format (for example, 2024-01-01 00:00:00, interpreted as Beijing time). The interval to endTime must not exceed one day. Defaults to the most recent day when omitted.",
+    "schema.query.endTime": "Log query end time in YYYY-MM-DD HH:mm:ss format (for example, 2024-01-01 23:59:59, interpreted as Beijing time). The interval from startTime must not exceed one day. Defaults to the current time when omitted.",
+    "schema.query.requestId": "Log request ID. Required for `getFunctionLogDetail`; take it from logs[].requestId returned by `listFunctionLogs`, or use the RequestId printed in a business log line.",
+    "schema.query.qualifier": "Function version alias, such as $LATEST or $DEFAULT. Optional for log queries; used as a CLS filter.",
+    "schema.query.context": "Log pagination cursor. Pass the `context` returned by the previous `listFunctionLogs` call back unchanged to fetch the next page; never construct it yourself. null means there are no more results.",
     "schema.query.runtime": "Runtime filter for layer queries, such as Nodejs18.15.",
     "schema.query.searchKey": "Layer name search keyword.",
     "schema.query.layerName": "Layer name. Required for `listLayerVersions` and `getLayerVersionDetail`. Layers use an account-level shared namespace; use the fixed format `{layerName}_{current envId}` (for example, common_cloud1-d9ghadgak3edf6b36).",
@@ -5887,9 +5996,9 @@ exports.gateway = void 0;
 const types_js_1 = __webpack_require__(9921);
 exports.gateway = (0, types_js_1.defineModule)({
     "query.title": "查询 CloudBase 网关",
-    "query.description": "CloudBase HTTP 网关统一只读入口（Domain/Route）。查询域名下路径路由及其上游：WEB_SCF/SCF=云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器。主键为 Domain + Path；listRoutes / getRoute / listCustomDomains / getPrivilege。getPrivilege 查询 HTTP 网关总开关（enableService）与访问鉴权（enableAuth）状态。实现自定义域名访问前，先 listCustomDomains：若已有自定义域名，优先 createRoute 挂路由（无需证书 ID）；仅在没有可用自定义域名时才 bindCustomDomain。",
+    "query.description": "CloudBase HTTP 网关统一只读入口（Domain/Route）。查询域名下路径路由及其上游：WEB_SCF/SCF=云函数，CBR=云托管，STATIC_STORE=静态托管，STORAGE=云存储，LH=轻量应用服务器。主键为 Domain + Path；listRoutes / getRoute / listCustomDomains / getPrivilege / cachePurgeTask。getPrivilege 查询 HTTP 网关总开关（enableService）与访问鉴权（enableAuth）状态。cachePurgeTask 查询域名缓存清除任务（先 manageGateway purgeCache 拿 TaskId）。实现自定义域名访问前，先 listCustomDomains：若已有自定义域名，优先 createRoute 挂路由（无需证书 ID）；仅在没有可用自定义域名时才 bindCustomDomain。",
     "manage.title": "管理 CloudBase 网关",
-    "manage.description": "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；enableRoute/disableRoute 启用或禁用已有路由（底层 ModifyHTTPServiceRoute 的 Routes[].Enable，不是 ModifyGatewayRoute）。未传 domain 时用 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（形如 *.{region}.app.tcloudbase.com），不会使用静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）。这是网关默认域上的路径路由，不是 STATIC_STORE 上游绑定；STATIC_STORE 上游必须显式传 upstreamResourceType=STATIC_STORE。关闭静态托管默认域名（*.tcloudbaseapp.com）：先 queryGateway(listRoutes) 找到 DomainType=STATIC_STORE 且 IsDefault=true 的 domain，再 manageGateway(action=\"disableRoute\", domain=该域名, path=\"/\")；勿用 manageHosting。创建后可用 queryGateway(action=\"listRoutes\") 核对 Domain / DomainType / Path / UpstreamResourceType。上游类型只用一个参数 upstreamResourceType（也可写在 route.upstreamResourceType，route 优先）：WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器；配合 targetName 或 route.serviceName（云函数名/云托管服务名/静态托管实例名，常见 staticstore）。createRoute 只建网关入口，不改上游权限。enablePathTransmission：默认 false 剥触发路径前缀；true 透传完整路径（CBR 多路由、WEB_SCF 自管子路径常需 true；STATIC_STORE 自定义触发路径映射站点根通常 false）。⚠️ 自定义域名访问：若环境已有自定义域名（先 queryGateway listCustomDomains），优先 createRoute 并显式传入该 domain，无需 certificateId；仅首次绑定全新自定义域名时用 bindCustomDomain（certificateId 可选：未传时按域名自动检索证书，单证书自动选用、多证书返回选择指引）。createRoute / bindCustomDomain 创建前会调用 VerifyHTTPServiceRoute 做归属权等预检（探测→创建）；失败时返回 data.checks 与 DNS TXT 指引，配置后重试。CORS/安全域名（浏览器跨域白名单，与本工具的网关自定义域名无关）用 manageEnv(action=addSecurityDomain/removeSecurityDomain)。enableService/authSwitch：HTTP 网关总开关与访问鉴权开关；createRoute 后若访问报 HTTPSERVICE_NONACTIVATED，通常是总开关未开启（用 queryGateway getPrivilege 查询、enableService 开启）。",
+    "manage.description": "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；enableRoute/disableRoute 启用或禁用已有路由（底层 ModifyHTTPServiceRoute 的 Routes[].Enable，不是 ModifyGatewayRoute）。未传 domain 时用 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（形如 *.{region}.app.tcloudbase.com），不会使用静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）。这是网关默认域上的路径路由，不是 STATIC_STORE 上游绑定；STATIC_STORE 上游必须显式传 upstreamResourceType=STATIC_STORE。关闭静态托管默认域名（*.tcloudbaseapp.com）：先 queryGateway(listRoutes) 找到 DomainType=STATIC_STORE 且 IsDefault=true 的 domain，再 manageGateway(action=\"disableRoute\", domain=该域名, path=\"/\")；勿用 manageHosting。创建后可用 queryGateway(action=\"listRoutes\") 核对 Domain / DomainType / Path / UpstreamResourceType。上游类型只用一个参数 upstreamResourceType（也可写在 route.upstreamResourceType，route 优先）：WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，STORAGE=云存储，LH=轻量应用服务器；配合 targetName 或 route.serviceName（云函数名/云托管服务名/静态托管实例名，常见 staticstore/云存储实例名）。createRoute 只建网关入口，不改上游权限。enablePathTransmission：默认 false 剥触发路径前缀；true 透传完整路径（CBR 多路由、WEB_SCF 自管子路径常需 true；STATIC_STORE 自定义触发路径映射站点根通常 false）。⚠️ 自定义域名访问：若环境已有自定义域名（先 queryGateway listCustomDomains），优先 createRoute 并显式传入该 domain，无需 certificateId；仅首次绑定全新自定义域名时用 bindCustomDomain（certificateId 可选：未传时按域名自动检索证书，单证书自动选用、多证书返回选择指引）。createRoute / bindCustomDomain 创建前会调用 VerifyHTTPServiceRoute 做归属权等预检（探测→创建）；失败时返回 data.checks 与 DNS TXT 指引，配置后重试。CORS/安全域名（浏览器跨域白名单，与本工具的网关自定义域名无关）用 manageEnv(action=addSecurityDomain/removeSecurityDomain)。enableService/authSwitch：HTTP 网关总开关与访问鉴权开关；createRoute 后若访问报 HTTPSERVICE_NONACTIVATED，通常是总开关未开启（用 queryGateway getPrivilege 查询、enableService 开启）。purgeCache：清除域名缓存（CDN/EO，按 URL/前缀/整站），返回 TaskId 后用 queryGateway cachePurgeTask 查进度。路由级还支持 enableSafeDomain（跨域/合法域名校验）、pathRewrite（路径重写）、qpsPolicy（限频）、extension（自定义请求/响应头与缓存规则）；域名级支持 protocol 与 domainExtension。updateRoute 只传要改的字段即可，未传的 CORS/重写/限频/扩展配置会保持原值。",
     "verify.failWithDns": "HTTP 服务域名配置预检未通过：域名归属权校验失败。请按 data.checks 中 ownership.dnsRecords 配置 DNS TXT 记录后重试。",
     "verify.fail": "HTTP 服务域名配置预检未通过。请根据 data.checks 修复问题后重试。",
     "verify.failWithDnsReason": "配置 DNS TXT（主机记录/记录类型/记录值见 data.checks[].dnsRecords）后重新调用本 action",
@@ -5907,7 +6016,7 @@ exports.gateway = (0, types_js_1.defineModule)({
     "privilege.nonActivatedHint": "；若路由创建成功但访问报 HTTPSERVICE_NONACTIVATED（403），请先开启 HTTP 网关",
     "privilege.enableServiceReason": "开启 HTTP 网关总开关（EnableService），开启后路由即可通过默认域访问",
     "defaultDomain.notReady": "环境默认 HTTP 访问域名未就绪或未开通。请先在控制台开通 HTTP 访问服务，或用 queryGateway(action=\"listRoutes\") 确认 Domains 中是否存在 DomainType=HTTPSERVICE 且 IsDefault=true 的域名（形如 *.{region}.app.tcloudbase.com）；不要使用静态托管域名（*.tcloudbaseapp.com）。也可以显式传入 domain 后重试 createRoute/updateRoute/deleteRoute。",
-    "upstreamTypeRequired": "必须提供 upstreamResourceType（或 route.upstreamResourceType）：WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器。禁止仅凭 targetName/serviceName 推断上游类型。",
+    "upstreamTypeRequired": "必须提供 upstreamResourceType（或 route.upstreamResourceType）：WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，STORAGE=云存储，LH=轻量应用服务器。禁止仅凭 targetName/serviceName 推断上游类型。",
     "upstreamNameRequired": "必须提供 targetName 或 route.serviceName 作为上游资源名称：云函数名、云托管服务名，或静态托管实例名（常见为 staticstore）。",
     "toggle.pathRequired": "action=enableRoute/disableRoute 时必须提供 path 或 route.path（例如 \"/\" 或 \"/api\"）",
     "toggle.notFound": "未找到路径 {path} 的路由{domainSuffix}{upstreamSuffix}。请先用 queryGateway(action=\"listRoutes\") 确认 Domain / Path，再调用 enableRoute/disableRoute。关闭静态托管默认域名（*.tcloudbaseapp.com）时，请显式传 domain=该 STATIC_STORE IsDefault 域名，并通常 path=\"/\"。",
@@ -5973,14 +6082,32 @@ exports.gateway = (0, types_js_1.defineModule)({
     "authSwitch.onMessage": "HTTP 访问服务鉴权开启成功",
     "authSwitch.offMessage": "HTTP 访问服务鉴权关闭成功",
     "authSwitch.verifyReason": "复核 HTTP 网关总开关与访问鉴权状态",
+    "purgeCache.domainRequired": "action=purgeCache 时必须提供 domain",
+    "purgeCache.targetsRequired": "action=purgeCache 时必须提供 targets：PURGE_URL 传完整 URL、PURGE_PREFIX 传路径前缀、PURGE_HOST 传待刷新的域名",
+    "purgeCache.message": "已提交 {count} 个目标的缓存清除任务；CDN/EO 刷新通常数秒到数分钟，请用 queryGateway(action=\"cachePurgeTask\") 按 TaskId 查进度",
+    "purgeCache.verifyReason": "查询缓存清除任务状态",
+    "query.cachePurgeTask": "已获取 {count} 条缓存清除任务记录",
+    "query.cachePurgeTaskDomainRequired": "action=cachePurgeTask 时必须提供 domain",
+    "cache.domainNotFound": "未找到域名 {domain} 的接入配置，无法确定缓存层。请先用 queryGateway(action=\"listRoutes\") 确认域名。",
+    "cache.notManaged": "域名 {domain} 的接入方式是 {accessType}，CloudBase 侧没有该域名的 CDN/EO 缓存，缓存刷新不适用（DIRECT 直连与 CUSTOM 自有 CDN 的缓存不由平台托管）。如需刷新，请先把域名切到 CDN 或 EO 接入。",
+    "cache.typeMismatch": "域名 {domain} 的接入方式是 {accessType}，不能按 cacheType={requested} 刷新。省略 cacheType 就会按接入方式自动匹配。",
     // Input schema parameter descriptions
-    "schema.query.action": "只读操作类型：listRoutes、getRoute、listCustomDomains、getPrivilege。" +
+    "schema.query.action": "只读操作类型：listRoutes、getRoute、listCustomDomains、getPrivilege、cachePurgeTask。" +
         "getPrivilege 无需其他参数，直接返回 HTTP 网关总开关与访问鉴权状态。" +
+        "cachePurgeTask 需要 domain（可选 cacheType/taskId/purgeType/startTime/endTime/offset/limit）。" +
         "自定义域名访问场景先 listCustomDomains 确认是否已有域名可复用。",
     "schema.query.targetName": "上游资源名过滤（UpstreamResourceName）：云函数名、云托管服务名，或静态托管实例名（常见 staticstore）。",
     "schema.query.routeId": "路由 ID。getRoute 时可选",
     "schema.query.path": "路由路径。getRoute / listRoutes 过滤时可选",
-    "schema.query.domain": "域名。getRoute / listRoutes 过滤时可选",
+    "schema.query.domain": "域名。getRoute / listRoutes 过滤时可选；cachePurgeTask 时必填",
+    "schema.query.cacheType": "缓存层（仅 cachePurgeTask）：CDN 或 EO。省略时按域名接入方式自动匹配（EO→EO、CDN→CDN）；" +
+        "DIRECT / CUSTOM / NONE 的域没有 CloudBase 托管的缓存，会直接拒绝并说明原因。",
+    "schema.query.taskId": "缓存清除任务 ID（仅 cachePurgeTask，可选过滤）",
+    "schema.query.purgeType": "清除方式过滤（仅 cachePurgeTask）：PURGE_URL=按 URL、PURGE_PREFIX=按前缀、PURGE_HOST=整站",
+    "schema.query.startTime": "任务开始时间（仅 cachePurgeTask，可选）。格式 YYYY-MM-DD HH:mm:ss",
+    "schema.query.endTime": "任务结束时间（仅 cachePurgeTask，可选）。格式 YYYY-MM-DD HH:mm:ss",
+    "schema.query.offset": "分页偏移（仅 cachePurgeTask，可选）",
+    "schema.query.limit": "返回数量上限（仅 cachePurgeTask，可选）",
     "schema.manage.action": "写操作：createRoute/updateRoute/deleteRoute 管理路由；enableRoute/disableRoute 启用或禁用已有路由（需 path，建议显式传 domain）；" +
         "bindCustomDomain/deleteCustomDomain 管理自定义域名；" +
         "enableService/authSwitch 开关 HTTP 网关总开关与访问鉴权（需配合 enable 参数）。" +
@@ -5990,13 +6117,15 @@ exports.gateway = (0, types_js_1.defineModule)({
         "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
         "bindCustomDomain 仅用于首次绑定新域名（certificateId 可选，未传则按域名自动检索；可选 accessType=DIRECT|CDN|CUSTOM，CUSTOM 需 customCname；普通场景用默认 DIRECT）。" +
         "createRoute/bindCustomDomain 创建前会 VerifyHTTPServiceRoute 预检；失败时按返回的 DNS TXT 指引配置后重试。" +
+        "purgeCache 清除域名缓存：需 domain 与 targets（配 purgeType=PURGE_URL|PURGE_PREFIX|PURGE_HOST，可选 cacheType=CDN|EO）。" +
         "接入说明：https://docs.cloudbase.net/service/custom-domain",
     "schema.manage.targetName": "上游资源名称（UpstreamResourceName），与 route.serviceName 二选一（route 优先）。" +
         "云函数=函数名；云托管=服务名；静态托管=实例名（常见 staticstore）。不会自动推断上游类型。",
     "schema.manage.path": "触发路径（网关匹配前缀），默认 /{上游名}。例：云函数 /api/hello、云托管 /api、静态托管 / 或 /app。" +
         "只建网关入口；与 enablePathTransmission 共同决定上游实际收到的路径。",
     "schema.manage.upstreamResourceType": "上游类型（与 route.upstreamResourceType 二选一，route 优先）。" +
-        "WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器。" +
+        "WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，STORAGE=云存储，LH=轻量应用服务器。" +
+        "STORAGE 的 UpstreamResourceName 是云存储实例名，可先用 queryStorage 查实例。" +
         "createRoute/updateRoute 必填其一；勿把 manageFunctions 的 type=HTTP|Event 传到本字段。",
     "schema.manage.auth": "网关路径鉴权（EnableAuth）。匿名/浏览器公网访问通常 false。" +
         "只控制网关入口；云函数安全规则、云托管鉴权、静态托管权限需各自工具另行配置。",
@@ -6005,6 +6134,30 @@ exports.gateway = (0, types_js_1.defineModule)({
         "CBR 云托管（Express 等自管子路由）与 WEB_SCF 多路径函数常需 true；" +
         "STATIC_STORE 把触发路径映射到站点根目录（如 /app → 托管 /）时通常 false；" +
         "单入口/根路径处理保持 false。也可用 route.enablePathTransmission（route 优先）。",
+    "schema.manage.enableSafeDomain": "跨域/合法域名校验（EnableSafeDomain），即控制台的「跨域设置」。true 时校验请求来源域名，" +
+        "false 时不校验（浏览器直连调用 API 的常见选择）。也可用 route.enableSafeDomain（route 优先）。",
+    "schema.manage.pathRewrite": "路径重写（PathRewrite），形如 {prefix:\"/v1\", staticStorePrefix:\"app\"}。" +
+        "prefix=命中路径前缀后替换为的内容；staticStorePrefix=静态托管场景下的目标前缀。" +
+        "不需要改写就省略；也可用 route.pathRewrite（route 优先）。",
+    "schema.manage.qpsPolicy": "限频（QPSPolicy），即控制台的「频限」。{total:总 QPS, perClient:{limitBy:\"ClientIP\"|\"UserID\", limitValue:单客户端 QPS}}。" +
+        "不传则不限频；也可用 route.qpsPolicy（route 优先）。",
+    "schema.manage.extension": "路由级扩展（Extension），可配自定义请求/响应头与缓存规则。" +
+        "{headersHandler:{requestHeadersToAdd,requestHeadersToRemove,responseHeadersToAdd,responseHeadersToRemove}," +
+        "cache:{rules:[{description,enable,condition:{target,matchType,values},actions:[{type:\"Cache\"|\"CacheKey\",cache,cacheKey}]}]}}。" +
+        "⚠️ 默认域（*.{region}.app.tcloudbase.com）不支持自定义响应头，后端会拒绝（实测 2026-10-21），需要自定义域名才能配。" +
+        "也可用 route.extension（route 优先）。",
+    "schema.manage.extension.header.key": "请求/响应头名称，如 X-Frame-Options",
+    "schema.manage.extension.header.value": "请求/响应头取值，如 SAMEORIGIN",
+    "schema.manage.extension.header.action": "写入策略（可选）：APPEND_IF_EXISTS_OR_ADD 追加；ADD_IF_ABSENT 不存在才加；" +
+        "OVERWRITE_IF_EXISTS_OR_ADD 覆盖或新增；OVERWRITE_IF_EXISTS 仅覆盖已存在的",
+    "schema.manage.extension.cacheCondition": "缓存规则匹配条件：target=url_path/file_extension/full_uri，matchType=prefix/suffix/contains/exact，values=匹配值数组",
+    "schema.manage.extension.cacheActions": "缓存动作数组：type=Cache 配 cache{followOrigin,noCache,cacheTime,maxAgeTime}（三者互斥，需开启其一）；" +
+        "type=CacheKey 配 cacheKey{fullUrlCache,queryStringSwitch,queryStringAction,queryStringValues}",
+    "schema.manage.domainExtension": "域名级扩展（Extension），作用于整个域名（含该域名下所有路径）的自定义头与缓存规则，结构同 extension。" +
+        "缓存规则通常配在域名级；仅 createRoute/updateRoute/bindCustomDomain 生效。" +
+        "⚠️ 同 extension：默认域不支持自定义响应头，需自定义域名。",
+    "schema.manage.protocol": "域名协议（Protocol），仅 createRoute/updateRoute/bindCustomDomain 生效：" +
+        "HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS / HTTPS_TO_HTTP。省略则沿用域名现有配置。",
     "schema.manage.route.serviceName": "上游实例名：云函数名 / 云托管服务名 / 静态托管实例名（常见 staticstore）/ LH 实例。优先于顶层 targetName。",
     "schema.manage.route.upstreamResourceType": "同顶层 upstreamResourceType。route 内设置时优先于顶层。",
     "schema.manage.route.enablePathTransmission": "同顶层 enablePathTransmission。route 内设置时优先于顶层。",
@@ -6012,6 +6165,10 @@ exports.gateway = (0, types_js_1.defineModule)({
         "enable=false 禁用该 Domain+Path（访问返回 GATEWAY_ROUTE_DISABLED）；" +
         "enable=true 重新启用。updateRoute 也可用顶层 enable 表达同一语义；" +
         "也可用专用 action enableRoute/disableRoute。route.enable 优先于顶层 enable。",
+    "schema.manage.route.enableSafeDomain": "同顶层 enableSafeDomain（跨域/合法域名校验）。route 内设置时优先于顶层。",
+    "schema.manage.route.pathRewrite": "同顶层 pathRewrite。route 内设置时优先于顶层。",
+    "schema.manage.route.qpsPolicy": "同顶层 qpsPolicy（限频）。route 内设置时优先于顶层。",
+    "schema.manage.route.extension": "同顶层 extension（路由级自定义头与缓存规则）。route 内设置时优先于顶层。",
     "schema.manage.route": "路由对象（可选写法）。例：云函数 {upstreamResourceType:\"WEB_SCF\",serviceName:\"fn\",path:\"/api\"}；" +
         "云托管 {upstreamResourceType:\"CBR\",serviceName:\"svc\",path:\"/api\"}；" +
         "静态托管 {upstreamResourceType:\"STATIC_STORE\",serviceName:\"staticstore\",path:\"/\"}；" +
@@ -6036,11 +6193,15 @@ exports.gateway = (0, types_js_1.defineModule)({
         "updateRoute 可选：映射到 Routes[].Enable（也可用 route.enable，route 优先；" +
         "也可用专用 action enableRoute/disableRoute）。" +
         "省略或非布尔值在 enableService/authSwitch 会返回参数错误。",
+    "schema.manage.cacheType": "缓存层（仅 purgeCache）：CDN 或 EO。省略时按域名接入方式自动匹配（EO→EO、CDN→CDN）；" +
+        "DIRECT / CUSTOM / NONE 的域没有 CloudBase 托管的缓存，会直接拒绝并说明原因。",
+    "schema.manage.purgeType": "清除方式（仅 purgeCache，默认 PURGE_URL）：PURGE_URL=按完整 URL、PURGE_PREFIX=按路径前缀、PURGE_HOST=整个域名",
+    "schema.manage.targets": "清除目标（仅 purgeCache，必填）：PURGE_URL 传 https://域名/路径 形式；PURGE_PREFIX 传 /static/ 这样的前缀；PURGE_HOST 传域名本身",
 }, {
     "query.title": "Query CloudBase Gateway",
-    "query.description": "Unified read-only entry for the CloudBase HTTP gateway (Domain/Route). Query path routes under a domain and their upstreams: WEB_SCF/SCF=cloud functions, CBR=CloudRun, STATIC_STORE=static hosting, LH=Lighthouse. The primary key is Domain + Path; listRoutes / getRoute / listCustomDomains / getPrivilege. getPrivilege queries the HTTP gateway master switch (enableService) and access auth (enableAuth) status. Before setting up custom domain access, run listCustomDomains first: if a custom domain already exists, prefer createRoute to attach a route (no certificate ID needed); use bindCustomDomain only when no usable custom domain exists.",
+    "query.description": "Unified read-only entry for the CloudBase HTTP gateway (Domain/Route). Query path routes under a domain and their upstreams: WEB_SCF/SCF=cloud functions, CBR=CloudRun, STATIC_STORE=static hosting, STORAGE=cloud storage, LH=Lighthouse. The primary key is Domain + Path; listRoutes / getRoute / listCustomDomains / getPrivilege / cachePurgeTask. getPrivilege queries the HTTP gateway master switch (enableService) and access auth (enableAuth) status. cachePurgeTask queries cache purge tasks for a domain (use the TaskId from manageGateway purgeCache). Before setting up custom domain access, run listCustomDomains first: if a custom domain already exists, prefer createRoute to attach a route (no certificate ID needed); use bindCustomDomain only when no usable custom domain exists.",
     "manage.title": "Manage CloudBase Gateway",
-    "manage.description": "Unified write entry for the CloudBase HTTP gateway (Domain/Route). createRoute/updateRoute/deleteRoute forward a path under a domain to an upstream; enableRoute/disableRoute enable or disable existing routes (Routes[].Enable of ModifyHTTPServiceRoute underneath, not ModifyGatewayRoute). When domain is omitted, the IsDefault default HTTP domain with DomainType=HTTPSERVICE (like *.{region}.app.tcloudbase.com) is used; static-hosting CDN domains (*.tcloudbaseapp.com, DomainType=STATIC_STORE) are never used. These are path routes on the gateway default domain, not STATIC_STORE upstream bindings; a STATIC_STORE upstream must pass upstreamResourceType=STATIC_STORE explicitly. To disable the static-hosting default domain (*.tcloudbaseapp.com): first queryGateway(listRoutes) to find the domain with DomainType=STATIC_STORE and IsDefault=true, then manageGateway(action=\"disableRoute\", domain=that domain, path=\"/\"); do not use manageHosting. After creation, verify Domain / DomainType / Path / UpstreamResourceType via queryGateway(action=\"listRoutes\"). The upstream type uses a single parameter upstreamResourceType (or route.upstreamResourceType, route wins): WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, LH=Lighthouse; together with targetName or route.serviceName (function name / CloudRun service name / static-hosting instance name, commonly staticstore). createRoute only creates the gateway entry and does not change upstream permissions. enablePathTransmission: default false strips the trigger path prefix; true forwards the full path (CBR multi-route and WEB_SCF self-managed sub-paths often need true; STATIC_STORE custom trigger path mapping to site root usually false). ⚠️ Custom domain access: if the env already has a custom domain (queryGateway listCustomDomains first), prefer createRoute with that domain explicitly, no certificateId needed; use bindCustomDomain only when binding a brand-new custom domain for the first time (certificateId optional: when omitted, certificates are auto-searched by domain — a single cert is auto-selected, multiple certs return selection guidance). createRoute / bindCustomDomain call VerifyHTTPServiceRoute for ownership pre-checks before creation (probe → create); on failure, data.checks and DNS TXT guidance are returned; configure and retry. CORS/security domains (browser cross-origin allowlist, unrelated to the gateway custom domains of this tool) use manageEnv(action=addSecurityDomain/removeSecurityDomain). enableService/authSwitch: HTTP gateway master switch and access auth switch; if access returns HTTPSERVICE_NONACTIVATED after createRoute, the master switch is usually off (query via queryGateway getPrivilege, enable via enableService).",
+    "manage.description": "Unified write entry for the CloudBase HTTP gateway (Domain/Route). createRoute/updateRoute/deleteRoute forward a path under a domain to an upstream; enableRoute/disableRoute enable or disable existing routes (Routes[].Enable of ModifyHTTPServiceRoute underneath, not ModifyGatewayRoute). When domain is omitted, the IsDefault default HTTP domain with DomainType=HTTPSERVICE (like *.{region}.app.tcloudbase.com) is used; static-hosting CDN domains (*.tcloudbaseapp.com, DomainType=STATIC_STORE) are never used. These are path routes on the gateway default domain, not STATIC_STORE upstream bindings; a STATIC_STORE upstream must pass upstreamResourceType=STATIC_STORE explicitly. To disable the static-hosting default domain (*.tcloudbaseapp.com): first queryGateway(listRoutes) to find the domain with DomainType=STATIC_STORE and IsDefault=true, then manageGateway(action=\"disableRoute\", domain=that domain, path=\"/\"); do not use manageHosting. After creation, verify Domain / DomainType / Path / UpstreamResourceType via queryGateway(action=\"listRoutes\"). The upstream type uses a single parameter upstreamResourceType (or route.upstreamResourceType, route wins): WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, STORAGE=cloud storage, LH=Lighthouse; together with targetName or route.serviceName (function name / CloudRun service name / static-hosting instance name, commonly staticstore / cloud storage instance name). createRoute only creates the gateway entry and does not change upstream permissions. enablePathTransmission: default false strips the trigger path prefix; true forwards the full path (CBR multi-route and WEB_SCF self-managed sub-paths often need true; STATIC_STORE custom trigger path mapping to site root usually false). ⚠️ Custom domain access: if the env already has a custom domain (queryGateway listCustomDomains first), prefer createRoute with that domain explicitly, no certificateId needed; use bindCustomDomain only when binding a brand-new custom domain for the first time (certificateId optional: when omitted, certificates are auto-searched by domain — a single cert is auto-selected, multiple certs return selection guidance). createRoute / bindCustomDomain call VerifyHTTPServiceRoute for ownership pre-checks before creation (probe → create); on failure, data.checks and DNS TXT guidance are returned; configure and retry. CORS/security domains (browser cross-origin allowlist, unrelated to the gateway custom domains of this tool) use manageEnv(action=addSecurityDomain/removeSecurityDomain). enableService/authSwitch: HTTP gateway master switch and access auth switch; if access returns HTTPSERVICE_NONACTIVATED after createRoute, the master switch is usually off (query via queryGateway getPrivilege, enable via enableService). purgeCache clears domain cache (CDN/EO by URL/prefix/host) and returns a TaskId; check progress with queryGateway cachePurgeTask. Route-level extras: enableSafeDomain (CORS / legit-domain check), pathRewrite (path rewriting), qpsPolicy (rate limiting), extension (custom request/response headers and cache rules); domain-level: protocol and domainExtension. updateRoute only needs the fields you want to change — untouched CORS/rewrite/QPS/extension settings are carried over from the live route.",
     "verify.failWithDns": "HTTP service domain pre-check failed: domain ownership verification failed. Configure the DNS TXT records per ownership.dnsRecords in data.checks, then retry.",
     "verify.fail": "HTTP service domain pre-check failed. Fix the issues per data.checks, then retry.",
     "verify.failWithDnsReason": "Configure the DNS TXT records (host/record type/record value in data.checks[].dnsRecords), then call this action again",
@@ -6058,7 +6219,7 @@ exports.gateway = (0, types_js_1.defineModule)({
     "privilege.nonActivatedHint": "; if the route is created successfully but access returns HTTPSERVICE_NONACTIVATED (403), enable the HTTP gateway first",
     "privilege.enableServiceReason": "Turn on the HTTP gateway master switch (EnableService); once on, routes are accessible via the default domain",
     "defaultDomain.notReady": "The env default HTTP access domain is not ready or not provisioned. Enable the HTTP access service in the console first, or use queryGateway(action=\"listRoutes\") to confirm that Domains contains a domain with DomainType=HTTPSERVICE and IsDefault=true (shaped like *.{region}.app.tcloudbase.com); do not use static-hosting domains (*.tcloudbaseapp.com). You may also pass domain explicitly and retry createRoute/updateRoute/deleteRoute.",
-    "upstreamTypeRequired": "upstreamResourceType (or route.upstreamResourceType) is required: WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, LH=Lighthouse. Do not infer the upstream type from targetName/serviceName alone.",
+    "upstreamTypeRequired": "upstreamResourceType (or route.upstreamResourceType) is required: WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, STORAGE=cloud storage, LH=Lighthouse. Do not infer the upstream type from targetName/serviceName alone.",
     "upstreamNameRequired": "targetName or route.serviceName is required as the upstream resource name: a cloud function name, CloudRun service name, or static-hosting instance name (commonly staticstore).",
     "toggle.pathRequired": "path or route.path is required for action=enableRoute/disableRoute (e.g. \"/\" or \"/api\")",
     "toggle.notFound": "No route found for path {path}{domainSuffix}{upstreamSuffix}. Use queryGateway(action=\"listRoutes\") first to confirm Domain / Path, then call enableRoute/disableRoute. When disabling the static-hosting default domain (*.tcloudbaseapp.com), pass domain=that STATIC_STORE IsDefault domain explicitly, usually with path=\"/\".",
@@ -6124,14 +6285,32 @@ exports.gateway = (0, types_js_1.defineModule)({
     "authSwitch.onMessage": "HTTP access service auth enabled successfully",
     "authSwitch.offMessage": "HTTP access service auth disabled successfully",
     "authSwitch.verifyReason": "Verify the HTTP gateway master switch and access auth status",
+    "purgeCache.domainRequired": "domain is required for action=purgeCache",
+    "purgeCache.targetsRequired": "targets is required for action=purgeCache: full URLs for PURGE_URL, path prefixes for PURGE_PREFIX, or the domain itself for PURGE_HOST",
+    "purgeCache.message": "Submitted a cache purge task for {count} target(s); CDN/EO purges usually take seconds to minutes — check progress with queryGateway(action=\"cachePurgeTask\") by TaskId",
+    "purgeCache.verifyReason": "Query the cache purge task status",
+    "query.cachePurgeTask": "Retrieved {count} cache purge task record(s)",
+    "query.cachePurgeTaskDomainRequired": "domain is required for action=cachePurgeTask",
+    "cache.domainNotFound": "No access configuration found for domain {domain}, so the cache layer is undetermined. Confirm the domain with queryGateway(action=\"listRoutes\") first.",
+    "cache.notManaged": "Domain {domain} uses access type {accessType}; CloudBase does not host a CDN/EO cache for it, so cache purging does not apply (DIRECT and CUSTOM own-CDN caches are not managed by the platform). Switch the domain to CDN or EO access first.",
+    "cache.typeMismatch": "Domain {domain} uses access type {accessType} and cannot be purged with cacheType={requested}. Omit cacheType to match the access type automatically.",
     // Input schema parameter descriptions
-    "schema.query.action": "Read-only action: listRoutes, getRoute, listCustomDomains, getPrivilege. " +
+    "schema.query.action": "Read-only action: listRoutes, getRoute, listCustomDomains, getPrivilege, cachePurgeTask. " +
         "getPrivilege needs no other parameter and returns the HTTP gateway master switch and access auth status directly. " +
+        "cachePurgeTask requires domain (optional cacheType/taskId/purgeType/startTime/endTime/offset/limit). " +
         "For custom domain access, run listCustomDomains first to check whether an existing domain can be reused.",
     "schema.query.targetName": "Upstream resource name filter (UpstreamResourceName): a cloud function name, CloudRun service name, or static-hosting instance name (commonly staticstore).",
     "schema.query.routeId": "Route ID. Optional for getRoute",
     "schema.query.path": "Route path. Optional as a getRoute / listRoutes filter",
-    "schema.query.domain": "Domain. Optional as a getRoute / listRoutes filter",
+    "schema.query.domain": "Domain. Optional as a getRoute / listRoutes filter; required for cachePurgeTask",
+    "schema.query.cacheType": "Cache layer (cachePurgeTask only): CDN or EO. When omitted it is matched from the domain access type (EO→EO, CDN→CDN); " +
+        "DIRECT / CUSTOM / NONE domains have no CloudBase-hosted cache and are rejected with an explanation.",
+    "schema.query.taskId": "Cache purge task ID (cachePurgeTask only, optional filter)",
+    "schema.query.purgeType": "Purge type filter (cachePurgeTask only): PURGE_URL=by URL, PURGE_PREFIX=by path prefix, PURGE_HOST=whole domain",
+    "schema.query.startTime": "Task start time (cachePurgeTask only, optional). Format YYYY-MM-DD HH:mm:ss",
+    "schema.query.endTime": "Task end time (cachePurgeTask only, optional). Format YYYY-MM-DD HH:mm:ss",
+    "schema.query.offset": "Pagination offset (cachePurgeTask only, optional)",
+    "schema.query.limit": "Max records to return (cachePurgeTask only, optional)",
     "schema.manage.action": "Write actions: createRoute/updateRoute/deleteRoute manage routes; enableRoute/disableRoute enable or disable an existing route (path required, passing domain explicitly is recommended); " +
         "bindCustomDomain/deleteCustomDomain manage custom domains; " +
         "enableService/authSwitch toggle the HTTP gateway master switch and access auth (requires the enable parameter). " +
@@ -6141,13 +6320,15 @@ exports.gateway = (0, types_js_1.defineModule)({
         "When a custom domain already exists, prefer createRoute(domain=existing domain) for access instead of calling bindCustomDomain / passing certificateId again; " +
         "bindCustomDomain is only for binding a new domain the first time (certificateId is optional — when omitted, certificates are searched by domain; optional accessType=DIRECT|CDN|CUSTOM, CUSTOM requires customCname; use the default DIRECT for normal cases). " +
         "createRoute/bindCustomDomain run a VerifyHTTPServiceRoute pre-check before creation; on failure, follow the returned DNS TXT guidance and retry. " +
+        "purgeCache clears domain cache: requires domain and targets (with purgeType=PURGE_URL|PURGE_PREFIX|PURGE_HOST, optional cacheType=CDN|EO). " +
         "Setup guide: https://docs.cloudbase.net/service/custom-domain",
     "schema.manage.targetName": "Upstream resource name (UpstreamResourceName); use either this or route.serviceName (route wins). " +
         "Cloud function=function name; CloudRun=service name; static hosting=instance name (commonly staticstore). The upstream type is never inferred automatically.",
     "schema.manage.path": "Trigger path (the gateway match prefix), defaults to /{upstream name}. Examples: cloud function /api/hello, CloudRun /api, static hosting / or /app. " +
         "This only creates the gateway entry; together with enablePathTransmission it determines the path the upstream actually receives.",
     "schema.manage.upstreamResourceType": "Upstream type (use either this or route.upstreamResourceType, route wins). " +
-        "WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, LH=Lighthouse. " +
+        "WEB_SCF=HTTP cloud function, SCF=Event cloud function, CBR=CloudRun, STATIC_STORE=static hosting, STORAGE=cloud storage, LH=Lighthouse. " +
+        "For STORAGE, UpstreamResourceName is the cloud storage instance name — look it up with queryStorage first. " +
         "One of them is required for createRoute/updateRoute; do not pass the manageFunctions type=HTTP|Event value into this field.",
     "schema.manage.auth": "Gateway path auth (EnableAuth). Usually false for anonymous/browser public access. " +
         "It only controls the gateway entry; cloud function security rules, CloudRun auth, and static hosting permissions must be configured with their own tools.",
@@ -6156,6 +6337,31 @@ exports.gateway = (0, types_js_1.defineModule)({
         "CBR CloudRun (Express and similar self-managed sub-routes) and multi-path WEB_SCF functions often need true; " +
         "STATIC_STORE mapping a trigger path to the site root (e.g. /app → hosting /) is usually false; " +
         "keep false for single-entry/root-path handling. route.enablePathTransmission also works (route wins).",
+    "schema.manage.enableSafeDomain": "CORS / legit-domain check (EnableSafeDomain), the console's \"cross-origin settings\". " +
+        "true validates the request origin; false skips the check (common for browser-to-API calls). " +
+        "route.enableSafeDomain also works (route wins).",
+    "schema.manage.pathRewrite": "Path rewriting (PathRewrite), e.g. {prefix:\"/v1\", staticStorePrefix:\"app\"}. " +
+        "prefix replaces the matched path prefix; staticStorePrefix is the target prefix for static hosting. " +
+        "Omit when no rewriting is needed; route.pathRewrite also works (route wins).",
+    "schema.manage.qpsPolicy": "Rate limiting (QPSPolicy), the console's \"frequency limit\". {total: total QPS, perClient:{limitBy:\"ClientIP\"|\"UserID\", limitValue: per-client QPS}}. " +
+        "Omit for no limit; route.qpsPolicy also works (route wins).",
+    "schema.manage.extension": "Route-level extension (Extension): custom request/response headers and cache rules. " +
+        "{headersHandler:{requestHeadersToAdd,requestHeadersToRemove,responseHeadersToAdd,responseHeadersToRemove}," +
+        "cache:{rules:[{description,enable,condition:{target,matchType,values},actions:[{type:\"Cache\"|\"CacheKey\",cache,cacheKey}]}]}}. " +
+        "⚠️ The default domain (*.{region}.app.tcloudbase.com) rejects custom response headers (verified 2026-10-21); a custom domain is required. " +
+        "route.extension also works (route wins).",
+    "schema.manage.extension.header.key": "Header name, e.g. X-Frame-Options",
+    "schema.manage.extension.header.value": "Header value, e.g. SAMEORIGIN",
+    "schema.manage.extension.header.action": "Write strategy (optional): APPEND_IF_EXISTS_OR_ADD appends; ADD_IF_ABSENT only adds when missing; " +
+        "OVERWRITE_IF_EXISTS_OR_ADD overwrites or adds; OVERWRITE_IF_EXISTS only overwrites existing",
+    "schema.manage.extension.cacheCondition": "Cache rule match condition: target=url_path/file_extension/full_uri, matchType=prefix/suffix/contains/exact, values=match value list",
+    "schema.manage.extension.cacheActions": "Cache action list: type=Cache with cache{followOrigin,noCache,cacheTime,maxAgeTime} (mutually exclusive — enable one); " +
+        "type=CacheKey with cacheKey{fullUrlCache,queryStringSwitch,queryStringAction,queryStringValues}",
+    "schema.manage.domainExtension": "Domain-level extension (Extension) applied to the whole domain (all paths): custom headers and cache rules, same shape as extension. " +
+        "Cache rules usually belong here; only effective for createRoute/updateRoute/bindCustomDomain. " +
+        "⚠️ Same as extension: the default domain rejects custom response headers; a custom domain is required.",
+    "schema.manage.protocol": "Domain protocol (Protocol), effective for createRoute/updateRoute/bindCustomDomain only: " +
+        "HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS / HTTPS_TO_HTTP. Omit to keep the domain's current setting.",
     "schema.manage.route.serviceName": "Upstream instance name: cloud function name / CloudRun service name / static-hosting instance name (commonly staticstore) / LH instance. Takes precedence over the top-level targetName.",
     "schema.manage.route.upstreamResourceType": "Same as the top-level upstreamResourceType. When set inside route, it takes precedence over the top level.",
     "schema.manage.route.enablePathTransmission": "Same as the top-level enablePathTransmission. When set inside route, it takes precedence over the top level.",
@@ -6163,6 +6369,10 @@ exports.gateway = (0, types_js_1.defineModule)({
         "enable=false disables this Domain+Path (access returns GATEWAY_ROUTE_DISABLED); " +
         "enable=true re-enables it. updateRoute can express the same semantics with the top-level enable; " +
         "the dedicated actions enableRoute/disableRoute also work. route.enable takes precedence over the top-level enable.",
+    "schema.manage.route.enableSafeDomain": "Same as the top-level enableSafeDomain (CORS / legit-domain check). When set inside route, it takes precedence.",
+    "schema.manage.route.pathRewrite": "Same as the top-level pathRewrite. When set inside route, it takes precedence.",
+    "schema.manage.route.qpsPolicy": "Same as the top-level qpsPolicy (rate limiting). When set inside route, it takes precedence.",
+    "schema.manage.route.extension": "Same as the top-level extension (route-level custom headers and cache rules). When set inside route, it takes precedence.",
     "schema.manage.route": "Route object (an optional form). Examples: cloud function {upstreamResourceType:\"WEB_SCF\",serviceName:\"fn\",path:\"/api\"}; " +
         "CloudRun {upstreamResourceType:\"CBR\",serviceName:\"svc\",path:\"/api\"}; " +
         "static hosting {upstreamResourceType:\"STATIC_STORE\",serviceName:\"staticstore\",path:\"/\"}; " +
@@ -6187,6 +6397,10 @@ exports.gateway = (0, types_js_1.defineModule)({
         "optional for updateRoute: maps to Routes[].Enable (route.enable also works and wins; " +
         "the dedicated actions enableRoute/disableRoute are available too). " +
         "Omitting it or passing a non-boolean returns a parameter error for enableService/authSwitch.",
+    "schema.manage.cacheType": "Cache layer (purgeCache only): CDN or EO. When omitted it is matched from the domain access type (EO→EO, CDN→CDN); " +
+        "DIRECT / CUSTOM / NONE domains have no CloudBase-hosted cache and are rejected with an explanation.",
+    "schema.manage.purgeType": "Purge type (purgeCache only, default PURGE_URL): PURGE_URL=by full URL, PURGE_PREFIX=by path prefix, PURGE_HOST=whole domain",
+    "schema.manage.targets": "Purge targets (purgeCache only, required): full https://domain/path URLs for PURGE_URL; prefixes such as /static/ for PURGE_PREFIX; the domain itself for PURGE_HOST",
 });
 
 
@@ -26499,42 +26713,68 @@ function registerEnvTools(server) {
                     // API Key mode: exchange for temporary credentials
                     const apiKeyFromEnv = (0, auth_js_1.getCloudBaseApiKeyFromEnv)();
                     if (apiKeyFromEnv && process.env.CLOUDBASE_ENV_ID) {
+                        // 项目级 key 与账号登录并存时，项目级优先——设备码/网页授权即使走完也不生效，
+                        // 所以短路段必须说清「怎么切」，否则用户会以为换号成功
+                        const removable = (0, auth_js_1.isEnvCredentialRemovableByLogout)();
+                        const apiKeyEnvId = process.env.CLOUDBASE_ENV_ID;
+                        const switchHint = "\n" +
+                            (removable
+                                ? (0, index_js_1.t)("env.auth.apiKeySwitchHintRemovable", undefined, outLang)
+                                : (0, index_js_1.t)("env.auth.apiKeySwitchHintExternal", {
+                                    varName: process.env.CLOUDBASE_API_KEY
+                                        ? "CLOUDBASE_API_KEY"
+                                        : "CLOUDBASE_APIKEY",
+                                }, outLang));
+                        const logoutNextStep = removable
+                            ? (0, tool_result_js_1.buildAuthNextStep)("logout", {
+                                suggestedArgs: { action: "logout", confirm: "yes" },
+                            })
+                            : undefined;
+                        // peek 发现回填的那份已失效时会把 env 清掉：那就不是「登录失败」，
+                        // 而是「旧 key 已经作废」，直接往下走正常登录流程
+                        let adoptedKeyDropped = false;
                         try {
                             const existingLoginState = await (0, auth_js_1.peekLoginState)();
                             if (existingLoginState) {
                                 return (0, tool_result_js_1.buildJsonToolResult)({
                                     ok: true,
                                     code: "AUTH_READY",
-                                    message: await appendApiKeyCamWarningIfNeeded(existingLoginState, (0, index_js_1.t)("env.auth.apiKeyAutoLogin", undefined, outLang)),
+                                    message: (await appendApiKeyCamWarningIfNeeded(existingLoginState, (0, index_js_1.t)("env.auth.apiKeyAutoLogin", undefined, outLang))) + switchHint,
                                     auth_mode: "api_key",
-                                    envId: process.env.CLOUDBASE_ENV_ID,
+                                    envId: apiKeyEnvId,
+                                    ...(logoutNextStep ? { next_step: logoutNextStep } : {}),
                                 });
                             }
+                            adoptedKeyDropped = !(0, auth_js_1.getCloudBaseApiKeyFromEnv)();
                         }
                         catch (e) {
                             // peekLoginState threw; log and fall through to diagnostic
                             (0, logger_js_1.debug)("start_auth: peekLoginState threw", { error: e instanceof Error ? e.message : String(e) });
                         }
-                        // API Key exchange failed: return diagnostic details
-                        const exchangeRegion = (0, site_map_js_1.resolveApiKeyExchangeRegion)();
-                        const endpoint = process.env.CLOUDBASE_API_ENDPOINT ||
-                            `https://${process.env.CLOUDBASE_ENV_ID}.${exchangeRegion ?? "ap-shanghai"}.tcb-api.tencentcloudapi.com`;
-                        const diagMessage = (0, index_js_1.t)("env.auth.apiKeyEnvExchangeFailed", undefined, outLang) +
-                            (0, index_js_1.t)("env.auth.apiKeyDiagEnv", {
-                                envId: String(process.env.CLOUDBASE_ENV_ID),
-                                apiKeyPrefix: apiKeyFromEnv.slice(0, 20),
-                                site: process.env.TCB_SITE || (0, index_js_1.t)("env.auth.siteUnset", undefined, outLang),
-                                gatewayRegion: exchangeRegion ?? (0, index_js_1.t)("env.auth.gatewayRegionDefault", undefined, outLang),
+                        if (!adoptedKeyDropped) {
+                            // API Key exchange failed: return diagnostic details
+                            const exchangeRegion = (0, site_map_js_1.resolveApiKeyExchangeRegion)();
+                            const endpoint = process.env.CLOUDBASE_API_ENDPOINT ||
+                                `https://${apiKeyEnvId}.${exchangeRegion ?? "ap-shanghai"}.tcb-api.tencentcloudapi.com`;
+                            const diagMessage = (0, index_js_1.t)("env.auth.apiKeyEnvExchangeFailed", undefined, outLang) +
+                                (0, index_js_1.t)("env.auth.apiKeyDiagEnv", {
+                                    envId: String(apiKeyEnvId),
+                                    apiKeyPrefix: apiKeyFromEnv.slice(0, 20),
+                                    site: process.env.TCB_SITE || (0, index_js_1.t)("env.auth.siteUnset", undefined, outLang),
+                                    gatewayRegion: exchangeRegion ?? (0, index_js_1.t)("env.auth.gatewayRegionDefault", undefined, outLang),
+                                    endpoint,
+                                }, outLang) +
+                                switchHint;
+                            return (0, tool_result_js_1.buildJsonToolResult)({
+                                ok: false,
+                                code: "API_KEY_AUTH_FAILED",
+                                message: diagMessage,
+                                auth_mode: "api_key",
+                                envId: apiKeyEnvId,
                                 endpoint,
-                            }, outLang);
-                        return (0, tool_result_js_1.buildJsonToolResult)({
-                            ok: false,
-                            code: "API_KEY_AUTH_FAILED",
-                            message: diagMessage,
-                            auth_mode: "api_key",
-                            envId: process.env.CLOUDBASE_ENV_ID,
-                            endpoint,
-                        });
+                                ...(logoutNextStep ? { next_step: logoutNextStep } : {}),
+                            });
+                        }
                     }
                     const region = server.cloudBaseOptions?.region || process.env.TCB_REGION;
                     const auth = toolbox_1.AuthSupervisor.getInstance({});
@@ -26863,12 +27103,19 @@ function registerEnvTools(server) {
                     });
                 }
                 if (action === "logout") {
-                    // Disallow logout in API Key mode
-                    if ((0, auth_js_1.getCloudBaseApiKeyFromEnv)() && process.env.CLOUDBASE_ENV_ID) {
+                    // 用户自己在 shell / 宿主配置里设的 API Key 变量，进程内删不掉，只能提示去源头改；
+                    // 按项目保存的那一份（我们回填的，或 login_by_api_key 写下的）能清，走正常登出。
+                    if ((0, auth_js_1.getCloudBaseApiKeyFromEnv)() &&
+                        process.env.CLOUDBASE_ENV_ID &&
+                        !(0, auth_js_1.isEnvCredentialRemovableByLogout)()) {
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "LOGOUT_NOT_ALLOWED",
-                            message: (0, index_js_1.t)("env.auth.logoutNotAllowedApiKey", undefined, outLang),
+                            message: (0, index_js_1.t)("env.auth.logoutNotAllowedApiKey", {
+                                varName: process.env.CLOUDBASE_API_KEY
+                                    ? "CLOUDBASE_API_KEY"
+                                    : "CLOUDBASE_APIKEY",
+                            }, outLang),
                             auth_mode: "api_key",
                         });
                     }
@@ -26882,12 +27129,15 @@ function registerEnvTools(server) {
                             }),
                         });
                     }
-                    await (0, auth_js_1.logout)();
+                    const { removed } = await (0, auth_js_1.logout)();
                     (0, cloudbase_manager_js_1.resetCloudBaseManagerCache)();
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         ok: true,
                         code: "LOGGED_OUT",
-                        message: (0, index_js_1.t)("env.auth.loggedOut", undefined, outLang),
+                        removed_scopes: removed,
+                        message: removed.includes("project")
+                            ? (0, index_js_1.t)("env.auth.loggedOutProject", undefined, outLang)
+                            : (0, index_js_1.t)("env.auth.loggedOut", undefined, outLang),
                     });
                 }
                 if (action === "get_temp_credentials") {
@@ -29662,8 +29912,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.CUSTOM_IMAGE_RUNTIME = exports.MASKED_ENV_VALUE = exports.LAYER_SOFT_WARN = exports.DEFAULT_FUNCTION_ALIAS = exports.MANAGE_FUNCTION_ACTIONS = exports.QUERY_FUNCTION_ACTIONS = exports.TRIGGER_CONFIG_EXAMPLES = exports.SUPPORTED_TRIGGER_TYPES = exports.DEFAULT_NODEJS_RUNTIME = exports.SUPPORTED_NODEJS_RUNTIMES = exports.RECOMMENDED_RUNTIMES = exports.DEFAULT_RUNTIME = exports.ALL_SUPPORTED_RUNTIMES = exports.SUPPORTED_RUNTIMES = exports.FUNCTION_UPLOAD_TARGET_NOT_FOUND_ERROR_CODE = void 0;
+exports.CUSTOM_IMAGE_RUNTIME = exports.MASKED_ENV_VALUE = exports.LAYER_SOFT_WARN = exports.FUNCTION_LOG_SERVICE_NOT_ENABLED_ERROR_CODE = exports.FUNCTION_LOG_QUERY_ERROR_CODE = exports.DEFAULT_FUNCTION_ALIAS = exports.MANAGE_FUNCTION_ACTIONS = exports.QUERY_FUNCTION_ACTIONS = exports.TRIGGER_CONFIG_EXAMPLES = exports.SUPPORTED_TRIGGER_TYPES = exports.DEFAULT_NODEJS_RUNTIME = exports.SUPPORTED_NODEJS_RUNTIMES = exports.RECOMMENDED_RUNTIMES = exports.DEFAULT_RUNTIME = exports.ALL_SUPPORTED_RUNTIMES = exports.SUPPORTED_RUNTIMES = exports.FUNCTION_UPLOAD_TARGET_NOT_FOUND_ERROR_CODE = void 0;
 exports.formatRuntimeList = formatRuntimeList;
+exports.formatClsTime = formatClsTime;
+exports.buildFunctionLogClsQuery = buildFunctionLogClsQuery;
+exports.resolveFunctionLogWindow = resolveFunctionLogWindow;
+exports.parseFunctionLogItem = parseFunctionLogItem;
+exports.isLogServiceNotEnabledMessage = isLogServiceNotEnabledMessage;
 exports.layerNameIncludesEnvId = layerNameIncludesEnvId;
 exports.buildCreateLayerNameWarning = buildCreateLayerNameWarning;
 exports.maskFunctionDetailEnvValues = maskFunctionDetailEnvValues;
@@ -29827,6 +30082,125 @@ exports.MANAGE_FUNCTION_ACTIONS = [
 ];
 /** Default SCF traffic alias used by CloudBase CLI `fn get-route` / `fn config-route`. */
 exports.DEFAULT_FUNCTION_ALIAS = "$DEFAULT";
+/**
+ * 云函数日志的 CLS 检索底座。
+ *
+ * 底层 `GetFunctionLogs` / `GetFunctionLogDetail` 已下线（`@cloudbase/manager-node` 5.8.8 起
+ * `getFunctionLogsV2` / `getFunctionLogDetail` 直接抛错），云函数日志只能从 CLS 取。CLS 里每条
+ * 云函数日志是按请求聚合的 JSON，`function_name` / `request_id` / `qualifier` / `src` 都是扁平
+ * 字段，可以直接做检索条件，不需要再扫全量日志。
+ */
+const FUNCTION_LOG_CLS_SOURCE = "(src:app OR src:system)";
+/** SearchClsLog 单次返回上限。 */
+const FUNCTION_LOG_MAX_LIMIT = 100;
+const FUNCTION_LOG_DEFAULT_LIMIT = 20;
+const FUNCTION_LOG_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * CLS 的时间入参固定按北京时间理解（与返回的 `Timestamp` 一致），
+ * 托管形态的服务进程可能是 UTC，所以这里显式加偏移，不依赖进程时区。
+ */
+const CLS_TIME_OFFSET_MS = 8 * 60 * 60 * 1000;
+/** CLS 检索语法里 `key:"value"` 的值需要转义反斜杠与双引号。 */
+function escapeClsValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** CLS 入参/展示用的时间格式：YYYY-MM-DD HH:mm:ss（北京时间）。 */
+function formatClsTime(time) {
+    return new Date(time + CLS_TIME_OFFSET_MS).toISOString().slice(0, 19).replace("T", " ");
+}
+function buildFunctionLogClsQuery(input) {
+    const clauses = [FUNCTION_LOG_CLS_SOURCE];
+    if (input.functionName) {
+        clauses.push(`function_name:"${escapeClsValue(input.functionName)}"`);
+    }
+    if (input.qualifier) {
+        clauses.push(`qualifier:"${escapeClsValue(input.qualifier)}"`);
+    }
+    if (input.requestId) {
+        clauses.push(`request_id:"${escapeClsValue(input.requestId)}"`);
+    }
+    return clauses.join(" AND ");
+}
+/** 只传一端时把窗口收敛到 24 小时以内，CLS 与旧接口都限制单次跨度。 */
+function resolveFunctionLogWindow(startTime, endTime, now = Date.now()) {
+    if (startTime && endTime) {
+        return { StartTime: startTime, EndTime: endTime };
+    }
+    if (startTime) {
+        const start = new Date(startTime).getTime();
+        // 单一 startTime 时至少给出一分钟窗口：起止相同（或 start 在未来）时 CLS 会直接判非法。
+        const end = Number.isFinite(start)
+            ? Math.max(start + 60_000, Math.min(now, start + FUNCTION_LOG_WINDOW_MS))
+            : now;
+        return { StartTime: startTime, EndTime: formatClsTime(end) };
+    }
+    if (endTime) {
+        const end = new Date(endTime).getTime();
+        const start = Number.isFinite(end) ? end - FUNCTION_LOG_WINDOW_MS : now - FUNCTION_LOG_WINDOW_MS;
+        return { StartTime: formatClsTime(start), EndTime: endTime };
+    }
+    return { StartTime: formatClsTime(now - FUNCTION_LOG_WINDOW_MS), EndTime: formatClsTime(now) };
+}
+/**
+ * 把 CLS 的日志条目还原成调用方关心的字段。
+ *
+ * 解析失败时（例如用户自己打的纯文本日志）保留原文放进 `log`，不让一条脏数据毁掉整页结果。
+ */
+function parseFunctionLogItem(item) {
+    const content = typeof item.Content === "string" ? item.Content : "";
+    let parsed = null;
+    try {
+        const value = JSON.parse(content);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            parsed = value;
+        }
+    }
+    catch {
+        parsed = null;
+    }
+    const timestamp = item.Timestamp ?? "";
+    if (!parsed) {
+        return {
+            requestId: "",
+            functionName: "",
+            qualifier: "",
+            source: "",
+            log: content,
+            statusCode: "",
+            retCode: "",
+            durationMs: null,
+            memoryMb: null,
+            memUsageBytes: null,
+            requestSource: "",
+            timestamp,
+        };
+    }
+    const str = (value) => value === undefined || value === null ? "" : String(value);
+    const num = (value) => {
+        const parsedNumber = Number(value);
+        return Number.isFinite(parsedNumber) ? parsedNumber : null;
+    };
+    return {
+        requestId: str(parsed.request_id),
+        functionName: str(parsed.function_name),
+        qualifier: str(parsed.qualifier || parsed.alias),
+        source: str(parsed.src),
+        log: str(parsed.log || parsed.tcb_log),
+        statusCode: str(parsed.status_code),
+        retCode: str(parsed.ret_code),
+        durationMs: num(parsed.duration),
+        memoryMb: num(parsed.memory),
+        memUsageBytes: num(parsed.mem_usage),
+        requestSource: str(parsed.request_source),
+        timestamp,
+    };
+}
+exports.FUNCTION_LOG_QUERY_ERROR_CODE = "FUNCTION_LOG_QUERY_FAILED";
+exports.FUNCTION_LOG_SERVICE_NOT_ENABLED_ERROR_CODE = "LOG_SERVICE_NOT_ENABLED";
+/** 未开通日志服务时 CLS 报的是 topic 不存在，按这个特征把它翻译成可执行的下一步。 */
+function isLogServiceNotEnabledMessage(message) {
+    return /TopicNotExist|TopicIsolated|topic[\s\S]{0,20}not\s*exist|日志服务未开通/i.test(message);
+}
 /** Layer soft-warn copy — account-scoped SCF LayerName guidance (no hard fail). */
 exports.LAYER_SOFT_WARN = {
     createNameFormat: (envId) => (0, index_js_1.t)("functions.layerWarn.createNameFormat", { envId }),
@@ -30294,6 +30668,81 @@ function registerFunctionTools(server) {
             }
         }
     };
+    /**
+     * 云函数日志统一走 CLS。查询失败时分两类给出可执行的下一步：
+     * 日志服务没开通 ⇒ 引导开通；其它失败 ⇒ 引导到 queryLogs 用同一条检索语句重试。
+     */
+    const throwLogQueryError = (error, scope) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (isLogServiceNotEnabledMessage(message)) {
+            (0, tool_result_js_1.throwToolPayloadError)({
+                success: false,
+                errorCode: exports.FUNCTION_LOG_SERVICE_NOT_ENABLED_ERROR_CODE,
+                data: { ...scope },
+                message: (0, index_js_1.t)("functions.logs.serviceNotEnabled"),
+                nextActions: [
+                    {
+                        tool: "manageLogs",
+                        action: "createLogService",
+                        reason: (0, index_js_1.t)("functions.reason.createLogService"),
+                        suggested_args: { action: "createLogService", confirm: true },
+                    },
+                ],
+            });
+        }
+        (0, tool_result_js_1.throwToolPayloadError)({
+            success: false,
+            errorCode: exports.FUNCTION_LOG_QUERY_ERROR_CODE,
+            data: { ...scope, rawError: message },
+            message: (0, index_js_1.t)("functions.logs.queryFailed", { message }),
+            nextActions: [
+                {
+                    tool: "queryLogs",
+                    action: "searchLogs",
+                    reason: (0, index_js_1.t)("functions.reason.searchClsFallback"),
+                    suggested_args: {
+                        action: "searchLogs",
+                        service: "tcb",
+                        queryString: buildFunctionLogClsQuery({
+                            functionName: scope.functionName,
+                            requestId: scope.requestId,
+                        }),
+                        startTime: scope.window.StartTime,
+                        endTime: scope.window.EndTime,
+                    },
+                },
+            ],
+        });
+    };
+    /**
+     * 空结果不等于「函数没被调用」：日志服务没开通时 CLS 同样返回空。
+     * 这里只在真的查到空结果时多做一次开销很小的探活，避免把「没开通」误报成「没日志」。
+     */
+    const assertLogServiceEnabled = async (logService) => {
+        try {
+            if (await logService.checkLogServiceEnabled()) {
+                return;
+            }
+        }
+        catch {
+            // 探活失败不制造新的错误源：保持「该时间段没有日志」的原始结论。
+            return;
+        }
+        (0, tool_result_js_1.throwToolPayloadError)({
+            success: false,
+            errorCode: exports.FUNCTION_LOG_SERVICE_NOT_ENABLED_ERROR_CODE,
+            data: { enabled: false },
+            message: (0, index_js_1.t)("functions.logs.serviceNotEnabled"),
+            nextActions: [
+                {
+                    tool: "manageLogs",
+                    action: "createLogService",
+                    reason: (0, index_js_1.t)("functions.reason.createLogService"),
+                    suggested_args: { action: "createLogService", confirm: true },
+                },
+            ],
+        });
+    };
     const normalizeManageLayers = (layers) => normalizeFunctionLayers((layers ?? []).map((layer) => ({
         LayerName: layer.layerName ?? layer.LayerName,
         LayerVersion: layer.layerVersion ?? layer.LayerVersion,
@@ -30415,39 +30864,86 @@ function registerFunctionTools(server) {
                 }
                 validateLogRange(input.startTime, input.endTime, input.offset, input.limit);
                 const cloudbase = await getManager();
-                let result;
+                const window = resolveFunctionLogWindow(input.startTime, input.endTime);
+                const limit = Math.min(Math.max(input.limit ?? FUNCTION_LOG_DEFAULT_LIMIT, 1), FUNCTION_LOG_MAX_LIMIT);
+                const offset = Math.max(input.offset ?? 0, 0);
+                // SearchClsLog 单次最多 100 条且没有 offset 入参：不带游标时多取 offset+limit 再本地
+                // 切片，带游标（context）时游标本身已经记录了偏移，直接返回当页。
+                const fetchLimit = Math.min(offset + limit, FUNCTION_LOG_MAX_LIMIT);
+                const queryString = buildFunctionLogClsQuery({
+                    functionName: input.functionName,
+                    requestId: input.requestId,
+                    qualifier: input.qualifier,
+                });
+                let logResults = {};
                 try {
-                    result = await cloudbase.functions.getFunctionLogsV2({
-                        name: input.functionName,
-                        offset: input.offset,
-                        limit: input.limit,
-                        startTime: input.startTime,
-                        endTime: input.endTime,
-                        requestId: input.requestId,
-                        qualifier: input.qualifier,
+                    const result = await cloudbase.log.searchClsLog({
+                        queryString,
+                        StartTime: window.StartTime,
+                        EndTime: window.EndTime,
+                        Limit: fetchLimit,
+                        Context: input.context,
+                        Sort: "desc",
+                        service: "tcb",
                     });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    logResults = result.LogResults ?? {};
                 }
                 catch (error) {
-                    const errMsg = error instanceof Error ? error.message : String(error);
-                    if (/invalid parameter/i.test(errMsg)) {
-                        throw new Error(`${errMsg}\n\n${(0, index_js_1.t)("functions.logsInvalidParamTips")}`);
-                    }
-                    throw error;
+                    throwLogQueryError(error, { functionName: input.functionName, window });
                 }
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const entries = (logResults.Results ?? []).map(parseFunctionLogItem);
+                const logs = input.context ? entries : entries.slice(offset, offset + limit);
+                if (logs.length === 0) {
+                    await assertLogServiceEnabled(cloudbase.log);
+                }
+                const hasMore = !logResults.ListOver && Boolean(logResults.Context);
                 return buildEnvelope({
                     action: input.action,
                     functionName: input.functionName,
-                    logs: result.LogList || [],
-                    requestId: result.RequestId,
-                    raw: result,
-                }, (0, index_js_1.t)("functions.gotFunctionLogs", { fnName: input.functionName }), [
-                    {
-                        tool: "queryFunctions",
-                        action: "getFunctionLogDetail",
-                        reason: (0, index_js_1.t)("functions.reason.logDetail"),
-                    },
-                ]);
+                    service: "tcb",
+                    queryString,
+                    startTime: window.StartTime,
+                    endTime: window.EndTime,
+                    logs,
+                    count: logs.length,
+                    context: logResults.Context ?? null,
+                    hasMore,
+                }, logs.length > 0
+                    ? (0, index_js_1.t)("functions.gotFunctionLogs", { fnName: input.functionName })
+                    : (0, index_js_1.t)("functions.logs.emptyByFunction", {
+                        fnName: input.functionName,
+                        start: window.StartTime,
+                        end: window.EndTime,
+                    }), hasMore
+                    ? [
+                        {
+                            tool: "queryFunctions",
+                            action: "listFunctionLogs",
+                            reason: (0, index_js_1.t)("functions.reason.nextLogPage"),
+                            suggested_args: {
+                                action: "listFunctionLogs",
+                                functionName: input.functionName,
+                                context: logResults.Context,
+                                startTime: window.StartTime,
+                                endTime: window.EndTime,
+                                limit,
+                            },
+                        },
+                    ]
+                    : [
+                        {
+                            tool: "queryFunctions",
+                            action: "getFunctionLogDetail",
+                            reason: (0, index_js_1.t)("functions.reason.logDetail"),
+                            suggested_args: {
+                                action: "getFunctionLogDetail",
+                                requestId: logs[0]?.requestId || "<日志里的 requestId>",
+                                startTime: window.StartTime,
+                                endTime: window.EndTime,
+                            },
+                        },
+                    ]);
             }
             case "getFunctionLogDetail": {
                 if (!input.requestId) {
@@ -30455,27 +30951,67 @@ function registerFunctionTools(server) {
                 }
                 validateLogRange(input.startTime, input.endTime);
                 const cloudbase = await getManager();
-                let result;
+                const window = resolveFunctionLogWindow(input.startTime, input.endTime);
+                const queryString = buildFunctionLogClsQuery({
+                    functionName: input.functionName,
+                    requestId: input.requestId,
+                    qualifier: input.qualifier,
+                });
+                let logResults = {};
                 try {
-                    result = await cloudbase.functions.getFunctionLogDetail({
-                        startTime: input.startTime,
-                        endTime: input.endTime,
-                        logRequestId: input.requestId,
+                    const result = await cloudbase.log.searchClsLog({
+                        queryString,
+                        StartTime: window.StartTime,
+                        EndTime: window.EndTime,
+                        Limit: FUNCTION_LOG_MAX_LIMIT,
+                        Sort: "asc",
+                        service: "tcb",
                     });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    logResults = result.LogResults ?? {};
                 }
                 catch (error) {
-                    const errMsg = error instanceof Error ? error.message : String(error);
-                    if (/invalid parameter/i.test(errMsg)) {
-                        throw new Error(`${errMsg}\n\n${(0, index_js_1.t)("functions.logDetailInvalidParamTips")}`);
-                    }
-                    throw error;
+                    throwLogQueryError(error, { requestId: input.requestId, window });
+                }
+                // 一次调用在 CLS 里是多条记录（START / 业务日志 / REPORT），按时间升序拼回完整过程。
+                const entries = (logResults.Results ?? []).map(parseFunctionLogItem);
+                if (entries.length === 0) {
+                    await assertLogServiceEnabled(cloudbase.log);
+                    return buildEnvelope({
+                        action: input.action,
+                        requestId: input.requestId,
+                        queryString,
+                        startTime: window.StartTime,
+                        endTime: window.EndTime,
+                        logs: [],
+                        count: 0,
+                    }, (0, index_js_1.t)("functions.logs.emptyByRequest", {
+                        requestId: input.requestId,
+                        start: window.StartTime,
+                        end: window.EndTime,
+                    }), [
+                        {
+                            tool: "queryFunctions",
+                            action: "listFunctionLogs",
+                            reason: (0, index_js_1.t)("functions.reason.widenLogRange"),
+                            suggested_args: {
+                                action: "listFunctionLogs",
+                                functionName: input.functionName || "<函数名>",
+                                startTime: window.StartTime,
+                                endTime: window.EndTime,
+                            },
+                        },
+                    ]);
                 }
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 return buildEnvelope({
                     action: input.action,
                     requestId: input.requestId,
-                    logDetail: result,
-                    raw: result,
+                    functionName: entries[0]?.functionName || input.functionName || null,
+                    queryString,
+                    startTime: window.StartTime,
+                    endTime: window.EndTime,
+                    logs: entries,
+                    count: entries.length,
                 }, (0, index_js_1.t)("functions.gotLogDetail", { requestId: input.requestId }));
             }
             case "listFunctionLayers": {
@@ -31851,6 +32387,7 @@ function registerFunctionTools(server) {
                 .optional()
                 .describe("functions.schema.query.requestId"),
             qualifier: zod_1.z.string().optional().describe("functions.schema.query.qualifier"),
+            context: zod_1.z.string().optional().describe("functions.schema.query.context"),
             runtime: zod_1.z.string().optional().describe("functions.schema.query.runtime"),
             searchKey: zod_1.z.string().optional().describe("functions.schema.query.searchKey"),
             layerName: zod_1.z
@@ -31977,6 +32514,7 @@ const QUERY_GATEWAY_ACTIONS = [
     "getRoute",
     "listCustomDomains",
     "getPrivilege",
+    "cachePurgeTask",
 ];
 const MANAGE_GATEWAY_ACTIONS = [
     "createRoute",
@@ -31988,6 +32526,7 @@ const MANAGE_GATEWAY_ACTIONS = [
     "deleteCustomDomain",
     "enableService",
     "authSwitch",
+    "purgeCache",
 ];
 /** DomainType of the environment default HTTP service (gateway) domain. */
 const HTTP_SERVICE_DOMAIN_TYPE = "HTTPSERVICE";
@@ -31997,6 +32536,24 @@ const UPSTREAM_RESOURCE_TYPES = [
     "CBR",
     "STATIC_STORE",
     "LH",
+    "STORAGE",
+];
+/** Domain-level protocol accepted by HTTPServiceDomainParam. */
+const DOMAIN_PROTOCOLS = [
+    "HTTP",
+    "HTTPS",
+    "HTTP_AND_HTTPS",
+    "HTTP_TO_HTTPS",
+    "HTTPS_TO_HTTP",
+];
+/** Cache layer that owns the purged objects (CDN vs EdgeOne). */
+const CACHE_TYPES = ["CDN", "EO"];
+const PURGE_TYPES = ["PURGE_URL", "PURGE_PREFIX", "PURGE_HOST"];
+const HEADER_ADD_ACTIONS = [
+    "APPEND_IF_EXISTS_OR_ADD",
+    "ADD_IF_ABSENT",
+    "OVERWRITE_IF_EXISTS_OR_ADD",
+    "OVERWRITE_IF_EXISTS",
 ];
 function normalizeAccessPath(path) {
     if (!path) {
@@ -32004,6 +32561,225 @@ function normalizeAccessPath(path) {
     }
     return path.startsWith("/") ? path : `/${path}`;
 }
+// ---------------------------------------------------------------------------
+// Route/Domain extension schemas (aligned with manager-node HTTPServiceRouteParam)
+// ---------------------------------------------------------------------------
+const headerToAddSchema = zod_1.z.object({
+    key: zod_1.z.string().describe("gateway.schema.manage.extension.header.key"),
+    value: zod_1.z.string().describe("gateway.schema.manage.extension.header.value"),
+    action: zod_1.z
+        .enum(HEADER_ADD_ACTIONS)
+        .optional()
+        .describe("gateway.schema.manage.extension.header.action"),
+});
+const headersHandlerSchema = zod_1.z.object({
+    requestHeadersToAdd: zod_1.z.array(headerToAddSchema).optional(),
+    requestHeadersToRemove: zod_1.z.array(zod_1.z.string()).optional(),
+    responseHeadersToAdd: zod_1.z.array(headerToAddSchema).optional(),
+    responseHeadersToRemove: zod_1.z.array(zod_1.z.string()).optional(),
+});
+const cacheRuleSchema = zod_1.z.object({
+    description: zod_1.z.string().optional(),
+    enable: zod_1.z.boolean().optional(),
+    condition: zod_1.z
+        .object({
+        target: zod_1.z.enum(["url_path", "file_extension", "full_uri"]).optional(),
+        matchType: zod_1.z.enum(["prefix", "suffix", "contains", "exact"]).optional(),
+        values: zod_1.z.array(zod_1.z.string()).optional(),
+    })
+        .describe("gateway.schema.manage.extension.cacheCondition"),
+    actions: zod_1.z
+        .array(zod_1.z.object({
+        type: zod_1.z.enum(["Cache", "CacheKey"]).optional(),
+        cache: zod_1.z
+            .object({
+            followOrigin: zod_1.z.boolean().optional(),
+            noCache: zod_1.z.boolean().optional(),
+            cacheTime: zod_1.z.number().int().min(0).optional(),
+            maxAgeTime: zod_1.z.number().int().min(0).optional(),
+        })
+            .optional(),
+        cacheKey: zod_1.z
+            .object({
+            fullUrlCache: zod_1.z.enum(["on", "off"]).optional(),
+            queryStringSwitch: zod_1.z.enum(["on", "off"]).optional(),
+            queryStringAction: zod_1.z.enum(["includeCustom", "excludeCustom"]).optional(),
+            queryStringValues: zod_1.z.array(zod_1.z.string()).optional(),
+        })
+            .optional(),
+    }))
+        .describe("gateway.schema.manage.extension.cacheActions"),
+});
+const extensionSchema = zod_1.z.object({
+    headersHandler: headersHandlerSchema.optional(),
+    cache: zod_1.z.object({ rules: zod_1.z.array(cacheRuleSchema).optional() }).optional(),
+});
+const pathRewriteSchema = zod_1.z.object({
+    prefix: zod_1.z.string().optional(),
+    staticStorePrefix: zod_1.z.string().optional(),
+});
+const qpsPolicySchema = zod_1.z.object({
+    total: zod_1.z.number().int().min(0).optional(),
+    perClient: zod_1.z
+        .object({
+        limitBy: zod_1.z.enum(["ClientIP", "UserID"]).optional(),
+        limitValue: zod_1.z.number().int().min(1).optional(),
+    })
+        .optional(),
+});
+function toHeadersHandler(input) {
+    if (!input) {
+        return undefined;
+    }
+    const output = {};
+    const toHeader = (item) => item.action
+        ? { Key: item.key, Value: item.value, Action: item.action }
+        : { Key: item.key, Value: item.value };
+    if (input.requestHeadersToAdd?.length) {
+        output.RequestHeadersToAdd = input.requestHeadersToAdd.map(toHeader);
+    }
+    if (input.requestHeadersToRemove?.length) {
+        output.RequestHeadersToRemove = input.requestHeadersToRemove;
+    }
+    if (input.responseHeadersToAdd?.length) {
+        output.ResponseHeadersToAdd = input.responseHeadersToAdd.map(toHeader);
+    }
+    if (input.responseHeadersToRemove?.length) {
+        output.ResponseHeadersToRemove = input.responseHeadersToRemove;
+    }
+    return Object.keys(output).length ? output : undefined;
+}
+function toCacheSet(input) {
+    if (!input?.rules?.length) {
+        return undefined;
+    }
+    return {
+        Rules: input.rules.map((rule) => ({
+            ...(rule.description !== undefined ? { Description: rule.description } : {}),
+            ...(rule.enable !== undefined ? { Enable: rule.enable } : {}),
+            Condition: {
+                ...(rule.condition?.target ? { Target: rule.condition.target } : {}),
+                ...(rule.condition?.matchType ? { MatchType: rule.condition.matchType } : {}),
+                ...(rule.condition?.values ? { Values: rule.condition.values } : {}),
+            },
+            Actions: (rule.actions ?? []).map((action) => ({
+                ...(action.type ? { Type: action.type } : {}),
+                ...(action.cache
+                    ? {
+                        Cache: {
+                            ...(action.cache.followOrigin !== undefined
+                                ? { FollowOrigin: action.cache.followOrigin }
+                                : {}),
+                            ...(action.cache.noCache !== undefined
+                                ? { NoCache: action.cache.noCache }
+                                : {}),
+                            ...(action.cache.cacheTime !== undefined
+                                ? { CacheTime: action.cache.cacheTime }
+                                : {}),
+                            ...(action.cache.maxAgeTime !== undefined
+                                ? { MaxAgeTime: action.cache.maxAgeTime }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                ...(action.cacheKey
+                    ? {
+                        CacheKey: {
+                            ...(action.cacheKey.fullUrlCache
+                                ? { FullURLCache: action.cacheKey.fullUrlCache }
+                                : {}),
+                            ...(action.cacheKey.queryStringSwitch
+                                ? { QueryStringSwitch: action.cacheKey.queryStringSwitch }
+                                : {}),
+                            ...(action.cacheKey.queryStringAction
+                                ? { QueryStringAction: action.cacheKey.queryStringAction }
+                                : {}),
+                            ...(action.cacheKey.queryStringValues
+                                ? { QueryStringValues: action.cacheKey.queryStringValues }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            })),
+        })),
+    };
+}
+function toExtension(input) {
+    if (!input) {
+        return undefined;
+    }
+    const output = {};
+    const headersHandler = toHeadersHandler(input.headersHandler);
+    if (headersHandler) {
+        output.HeadersHandler = headersHandler;
+    }
+    const cache = toCacheSet(input.cache);
+    if (cache) {
+        output.Cache = cache;
+    }
+    return Object.keys(output).length ? output : undefined;
+}
+function toPathRewrite(input) {
+    if (!input) {
+        return undefined;
+    }
+    const output = {};
+    if (typeof input.prefix === "string") {
+        output.Prefix = input.prefix;
+    }
+    if (typeof input.staticStorePrefix === "string") {
+        output.StaticStorePrefix = input.staticStorePrefix;
+    }
+    return Object.keys(output).length ? output : undefined;
+}
+function toQpsPolicy(input) {
+    if (!input) {
+        return undefined;
+    }
+    const output = {};
+    if (typeof input.total === "number") {
+        output.QPSTotal = input.total;
+    }
+    if (input.perClient) {
+        const perClient = {};
+        if (input.perClient.limitBy) {
+            perClient.LimitBy = input.perClient.limitBy;
+        }
+        if (typeof input.perClient.limitValue === "number") {
+            perClient.LimitValue = input.perClient.limitValue;
+        }
+        if (Object.keys(perClient).length) {
+            output.QPSPerClient = perClient;
+        }
+    }
+    return Object.keys(output).length ? output : undefined;
+}
+/**
+ * Route fields that ModifyHTTPServiceRoute replaces wholesale. When an update
+ * omits one of them, the existing value must be carried over — otherwise a
+ * partial update (e.g. only bumping QPS) would silently wipe CORS / rewrite /
+ * headers / cache rules.
+ */
+const PRESERVED_ROUTE_FIELDS = [
+    "EnableAuth",
+    "EnableSafeDomain",
+    "EnablePathTransmission",
+    "PathRewrite",
+    "QPSPolicy",
+    "Extension",
+    "Enable",
+];
+function carryOverRouteFields(route, existing) {
+    if (!existing) {
+        return route;
+    }
+    for (const field of PRESERVED_ROUTE_FIELDS) {
+        if (route[field] === undefined && existing[field] !== undefined) {
+            route[field] = existing[field];
+        }
+    }
+    return route;
+}
 /**
  * Collect FAIL items from VerifyHTTPServiceRoute, mapping DNS records to
  * lowercase field names for MCP structured output (aligned with CLI 3.8.1).
@@ -32446,16 +33222,13 @@ function registerGatewayTools(server) {
         });
         const path = normalizeAccessPath(input.route?.path ?? input.path ?? `/${upstreamResourceName}`);
         const domain = await resolveRouteDomain(input.domain);
-        const enableAuth = input.route?.auth !== undefined
-            ? input.route.auth
-            : input.auth !== undefined
-                ? input.auth
-                : undefined;
-        const enablePathTransmission = input.route?.enablePathTransmission !== undefined
-            ? input.route.enablePathTransmission
-            : input.enablePathTransmission !== undefined
-                ? input.enablePathTransmission
-                : undefined;
+        const pick = (routeValue, topValue) => routeValue !== undefined ? routeValue : topValue;
+        const enableAuth = pick(input.route?.auth, input.auth);
+        const enableSafeDomain = pick(input.route?.enableSafeDomain, input.enableSafeDomain);
+        const enablePathTransmission = pick(input.route?.enablePathTransmission, input.enablePathTransmission);
+        const routePathRewrite = toPathRewrite(pick(input.route?.pathRewrite, input.pathRewrite));
+        const routeQpsPolicy = toQpsPolicy(pick(input.route?.qpsPolicy, input.qpsPolicy));
+        const routeExtension = toExtension(pick(input.route?.extension, input.extension));
         // Route enable: prefer route.enable. For updateRoute only, top-level
         // enable also maps to Route.Enable (enableService/authSwitch use the
         // same field name but different actions).
@@ -32469,18 +33242,35 @@ function registerGatewayTools(server) {
             Path: path,
             UpstreamResourceType: upstreamResourceType,
             UpstreamResourceName: upstreamResourceName,
-            EnableAuth: enableAuth,
         };
+        if (enableAuth !== undefined) {
+            route.EnableAuth = enableAuth;
+        }
+        if (enableSafeDomain !== undefined) {
+            route.EnableSafeDomain = enableSafeDomain;
+        }
         if (enablePathTransmission !== undefined) {
             route.EnablePathTransmission = enablePathTransmission;
         }
+        if (routePathRewrite) {
+            route.PathRewrite = routePathRewrite;
+        }
+        if (routeQpsPolicy) {
+            route.QPSPolicy = routeQpsPolicy;
+        }
+        if (routeExtension) {
+            route.Extension = routeExtension;
+        }
         if (routeEnable !== undefined) {
             route.Enable = routeEnable;
         }
+        const domainExtension = toExtension(input.domainExtension);
         return {
             EnvId: await resolveEnvId(),
             Domain: {
                 Domain: domain,
+                ...(input.protocol ? { Protocol: input.protocol } : {}),
+                ...(domainExtension ? { Extension: domainExtension } : {}),
                 Routes: [route],
             },
             resolved: {
@@ -32489,6 +33279,7 @@ function registerGatewayTools(server) {
                 upstreamResourceType,
                 upstreamResourceName,
                 enableAuth,
+                enableSafeDomain,
                 enablePathTransmission,
                 enable: routeEnable,
             },
@@ -32537,6 +33328,57 @@ function registerGatewayTools(server) {
         }
         return matches[0];
     };
+    /**
+     * Locate the live record (domain + route) so partial updates can carry over
+     * fields the caller did not touch.
+     */
+    const findExistingRouteRecord = async (domain, path) => {
+        const result = await listHttpServiceRoutes({ domain });
+        const domainRecord = (result.Domains ?? []).find((item) => item.Domain === domain);
+        const route = (domainRecord?.Routes ?? []).find((item) => normalizeAccessPath(String(item.Path ?? "")) ===
+            path);
+        return {
+            domainRecord,
+            route: route,
+        };
+    };
+    /** CDN vs EO is decided by the domain's access type; default to CDN. */
+    /**
+     * 缓存层由域名的接入方式决定，不能猜。
+     *
+     * - EO / CDN → 对应缓存层
+     * - DIRECT / CUSTOM / NONE → CloudBase 侧没有托管缓存，刷新不适用。
+     *   实测（2026-10-21）对 DIRECT 域发 CDN 刷新，PurgeHTTPServiceCache 会「成功」登记
+     *   一个任务，而 DescribeHTTPServiceCachePurgeTask 随后抛 Third Service Error ——
+     *   即后端对 DIRECT 域缺校验、返回不可读错误。这里提前拦住并说明原因。
+     */
+    const resolveDomainCacheType = async (domain, preferred) => {
+        const findDomain = (result) => (result.Domains ?? []).find((item) => item.Domain === domain);
+        let record = findDomain(await listHttpServiceRoutes({ domain }));
+        if (!record) {
+            // 域名下暂时没有路由时，筛 Domain 可能查不到，退回全量再找一次。
+            record = findDomain(await listHttpServiceRoutes());
+        }
+        if (!record) {
+            throw new Error((0, index_js_1.t)("gateway.cache.domainNotFound", { domain }));
+        }
+        const accessType = String(record.AccessType ?? "");
+        const boundCacheType = accessType === "EO" ? "EO" : accessType === "CDN" ? "CDN" : undefined;
+        if (!boundCacheType) {
+            throw new Error((0, index_js_1.t)("gateway.cache.notManaged", {
+                domain,
+                accessType: accessType || "UNKNOWN",
+            }));
+        }
+        if (preferred && preferred !== boundCacheType) {
+            throw new Error((0, index_js_1.t)("gateway.cache.typeMismatch", {
+                domain,
+                accessType: boundCacheType,
+                requested: preferred,
+            }));
+        }
+        return boundCacheType;
+    };
     const routeMutationNextActions = (targetName) => [
         {
             tool: "queryGateway",
@@ -32649,6 +33491,34 @@ function registerGatewayTools(server) {
                         },
                     ]);
             }
+            case "cachePurgeTask": {
+                if (!input.domain) {
+                    throw new Error((0, index_js_1.t)("gateway.query.cachePurgeTaskDomainRequired"));
+                }
+                const cacheType = await resolveDomainCacheType(input.domain, input.cacheType);
+                const cloudbase = await getManager();
+                const result = await cloudbase.env.describeHttpServiceCachePurgeTask({
+                    EnvId: await resolveEnvId(),
+                    Domain: input.domain,
+                    CacheType: cacheType,
+                    ...(input.taskId ? { TaskId: input.taskId } : {}),
+                    ...(input.purgeType ? { PurgeType: input.purgeType } : {}),
+                    ...(input.startTime ? { StartTime: input.startTime } : {}),
+                    ...(input.endTime ? { EndTime: input.endTime } : {}),
+                    ...(input.offset !== undefined ? { Offset: input.offset } : {}),
+                    ...(input.limit !== undefined ? { Limit: input.limit } : {}),
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const tasks = Array.isArray(result?.Tasks) ? result.Tasks : [];
+                return buildEnvelope({
+                    action: input.action,
+                    domain: input.domain,
+                    cacheType,
+                    tasks,
+                    total: result?.TotalCount ?? tasks.length,
+                    raw: result,
+                }, (0, index_js_1.t)("gateway.query.cachePurgeTask", { count: tasks.length }));
+            }
             default:
                 throw new Error((0, index_js_1.t)("gateway.error.unsupportedAction", { action: input.action }));
         }
@@ -32757,6 +33627,7 @@ function registerGatewayTools(server) {
                     upstreamResourceType: payload.resolved.upstreamResourceType,
                     upstreamResourceName: payload.resolved.upstreamResourceName,
                     auth: payload.resolved.enableAuth ?? null,
+                    enableSafeDomain: payload.resolved.enableSafeDomain ?? null,
                     enablePathTransmission: payload.resolved.enablePathTransmission ?? null,
                     accessUrl: `https://${payload.resolved.domain}${payload.resolved.path}`,
                     accessUrls: [`https://${payload.resolved.domain}${payload.resolved.path}`],
@@ -32785,6 +33656,14 @@ function registerGatewayTools(server) {
             case "updateRoute": {
                 const cloudbase = await getManager();
                 const payload = await normalizeRoutePayload(input);
+                // Preserve untouched route/domain fields from the live record: the
+                // backend replaces the whole route entry, so a partial update would
+                // otherwise wipe CORS / rewrite / QPS / headers / cache settings.
+                const existing = await findExistingRouteRecord(payload.resolved.domain, payload.resolved.path);
+                carryOverRouteFields(payload.Domain.Routes[0], existing.route);
+                if (!payload.Domain.Protocol && existing.domainRecord?.Protocol) {
+                    payload.Domain.Protocol = existing.domainRecord.Protocol;
+                }
                 const result = await cloudbase.env.modifyHttpServiceRoute({
                     EnvId: payload.EnvId,
                     Domain: payload.Domain,
@@ -32802,6 +33681,7 @@ function registerGatewayTools(server) {
                     upstreamResourceType: payload.resolved.upstreamResourceType,
                     upstreamResourceName: payload.resolved.upstreamResourceName,
                     auth: payload.resolved.enableAuth ?? null,
+                    enableSafeDomain: payload.resolved.enableSafeDomain ?? null,
                     enablePathTransmission: payload.resolved.enablePathTransmission ?? null,
                     enable: payload.resolved.enable ?? null,
                     ...(accessUrl
@@ -32883,6 +33763,11 @@ function registerGatewayTools(server) {
                 if (enablePathTransmission !== undefined) {
                     route.EnablePathTransmission = enablePathTransmission;
                 }
+                if (input.enableSafeDomain !== undefined) {
+                    route.EnableSafeDomain = input.enableSafeDomain;
+                }
+                // Toggling Enable must not drop CORS / rewrite / QPS / headers / cache.
+                carryOverRouteFields(route, existing);
                 const cloudbase = await getManager();
                 const result = await cloudbase.env.modifyHttpServiceRoute({
                     EnvId: await resolveEnvId(),
@@ -32977,6 +33862,7 @@ function registerGatewayTools(server) {
                     CertId: input.certificateId || "",
                     AccessType: accessType,
                     Enable: input.enable !== undefined ? input.enable : true,
+                    ...(input.protocol ? { Protocol: input.protocol } : {}),
                     ...(input.customCname ? { CustomCname: input.customCname } : {}),
                 };
                 const verifyFailure = await verifyHttpServiceRouteOrFail({
@@ -32998,6 +33884,7 @@ function registerGatewayTools(server) {
                         Domain: input.domain,
                         CertId: certificateId,
                         AccessType: accessType,
+                        ...(input.protocol ? { Protocol: input.protocol } : {}),
                         ...(input.enable !== undefined
                             ? { Enable: input.enable }
                             : {}),
@@ -33128,6 +34015,43 @@ function registerGatewayTools(server) {
                     },
                 ]);
             }
+            case "purgeCache": {
+                if (!input.domain) {
+                    throw new Error((0, index_js_1.t)("gateway.purgeCache.domainRequired"));
+                }
+                const targets = (input.targets ?? [])
+                    .map((item) => (typeof item === "string" ? item.trim() : ""))
+                    .filter(Boolean);
+                if (!targets.length) {
+                    throw new Error((0, index_js_1.t)("gateway.purgeCache.targetsRequired"));
+                }
+                const purgeType = input.purgeType ?? "PURGE_URL";
+                const cacheType = await resolveDomainCacheType(input.domain, input.cacheType);
+                const cloudbase = await getManager();
+                const result = await cloudbase.env.purgeHttpServiceCache({
+                    EnvId: await resolveEnvId(),
+                    Domain: input.domain,
+                    CacheType: cacheType,
+                    PurgeType: purgeType,
+                    Targets: targets,
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                return buildEnvelope({
+                    action: input.action,
+                    domain: input.domain,
+                    cacheType,
+                    purgeType,
+                    targets,
+                    taskId: result?.TaskId ?? null,
+                    raw: result,
+                }, (0, index_js_1.t)("gateway.purgeCache.message", { count: targets.length }), [
+                    {
+                        tool: "queryGateway",
+                        action: "cachePurgeTask",
+                        reason: (0, index_js_1.t)("gateway.purgeCache.verifyReason"),
+                    },
+                ]);
+            }
             default:
                 throw new Error((0, index_js_1.t)("gateway.error.unsupportedAction", { action: input.action }));
         }
@@ -33146,6 +34070,19 @@ function registerGatewayTools(server) {
             routeId: zod_1.z.string().optional().describe("gateway.schema.query.routeId"),
             path: zod_1.z.string().optional().describe("gateway.schema.query.path"),
             domain: zod_1.z.string().optional().describe("gateway.schema.query.domain"),
+            cacheType: zod_1.z
+                .enum(CACHE_TYPES)
+                .optional()
+                .describe("gateway.schema.query.cacheType"),
+            taskId: zod_1.z.string().optional().describe("gateway.schema.query.taskId"),
+            purgeType: zod_1.z
+                .enum(PURGE_TYPES)
+                .optional()
+                .describe("gateway.schema.query.purgeType"),
+            startTime: zod_1.z.string().optional().describe("gateway.schema.query.startTime"),
+            endTime: zod_1.z.string().optional().describe("gateway.schema.query.endTime"),
+            offset: zod_1.z.number().int().min(0).optional().describe("gateway.schema.query.offset"),
+            limit: zod_1.z.number().int().min(1).optional().describe("gateway.schema.query.limit"),
         },
         annotations: {
             readOnlyHint: true,
@@ -33175,6 +34112,26 @@ function registerGatewayTools(server) {
                 .boolean()
                 .optional()
                 .describe("gateway.schema.manage.enablePathTransmission"),
+            enableSafeDomain: zod_1.z
+                .boolean()
+                .optional()
+                .describe("gateway.schema.manage.enableSafeDomain"),
+            pathRewrite: pathRewriteSchema
+                .optional()
+                .describe("gateway.schema.manage.pathRewrite"),
+            qpsPolicy: qpsPolicySchema
+                .optional()
+                .describe("gateway.schema.manage.qpsPolicy"),
+            extension: extensionSchema
+                .optional()
+                .describe("gateway.schema.manage.extension"),
+            domainExtension: extensionSchema
+                .optional()
+                .describe("gateway.schema.manage.domainExtension"),
+            protocol: zod_1.z
+                .enum(DOMAIN_PROTOCOLS)
+                .optional()
+                .describe("gateway.schema.manage.protocol"),
             route: zod_1.z
                 .object({
                 path: zod_1.z.string().optional(),
@@ -33191,6 +34148,19 @@ function registerGatewayTools(server) {
                     .boolean()
                     .optional()
                     .describe("gateway.schema.manage.route.enablePathTransmission"),
+                enableSafeDomain: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe("gateway.schema.manage.route.enableSafeDomain"),
+                pathRewrite: pathRewriteSchema
+                    .optional()
+                    .describe("gateway.schema.manage.route.pathRewrite"),
+                qpsPolicy: qpsPolicySchema
+                    .optional()
+                    .describe("gateway.schema.manage.route.qpsPolicy"),
+                extension: extensionSchema
+                    .optional()
+                    .describe("gateway.schema.manage.route.extension"),
                 enable: zod_1.z
                     .boolean()
                     .optional()
@@ -33212,6 +34182,18 @@ function registerGatewayTools(server) {
                 .optional()
                 .describe("gateway.schema.manage.customCname"),
             enable: zod_1.z.boolean().optional().describe("gateway.schema.manage.enable"),
+            cacheType: zod_1.z
+                .enum(CACHE_TYPES)
+                .optional()
+                .describe("gateway.schema.manage.cacheType"),
+            purgeType: zod_1.z
+                .enum(PURGE_TYPES)
+                .optional()
+                .describe("gateway.schema.manage.purgeType"),
+            targets: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe("gateway.schema.manage.targets"),
         },
         annotations: {
             readOnlyHint: false,
@@ -42278,7 +43260,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.36.0" : 0);
+            ( true ? "2.36.1" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -43233,7 +44215,7 @@ function isReturnedFailureResult(result) {
  * 所以两条路径对同一个底层错误得到的文本逐字相同（🆔 RequestId + 📦 版本页脚都在这里）。
  */
 function buildFailureClientText(errorMessage, requestId, server) {
-    const mcpVersion =  true ? "2.36.0" : 0;
+    const mcpVersion =  true ? "2.36.1" : 0;
     const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
     return `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n${contributionHint(server)}`;
 }