@cloudbase/cloudbase-mcp 2.16.1-beta.1 → 2.17.0-beta.2

package/dist/index.js

@@ -134,6 +134,40 @@ function buildEnvCandidatePayload(envCandidates, limit = DEFAULT_ENV_CANDIDATE_L
         },
     };
 }
+function buildLocalDevDomainHint() {
+    return {
+        format: "host:port",
+        useActualOrigin: true,
+        requiredValue: "当前浏览器实际访问 origin 对应的 host:port",
+        deriveFrom: ["浏览器地址栏中的当前 origin", "本地 dev server 实际启动输出"],
+        note: "如果你的前端运行在自定义域名或本地开发端口上，请把当前浏览器实际访问地址对应的 host:port 加入安全域名。不要依赖一组固定默认端口，也不要假设已有 localhost/127.0.0.1 条目已经覆盖当前运行端口。",
+    };
+}
+function summarizeConfiguredLocalDevEntries(domains) {
+    const localEntries = domains
+        .map((domain) => String(domain?.Domain ?? "").trim())
+        .filter((domain) => domain.startsWith("127.0.0.1:") || domain.startsWith("localhost:"));
+    return {
+        hasAnyConfiguredLocalEntry: localEntries.length > 0,
+        configuredEntries: localEntries,
+    };
+}
+function simplifyEnvDomains(domains) {
+    if (!Array.isArray(domains)) {
+        return domains;
+    }
+    return domains.map((domain) => {
+        if (!domain || typeof domain !== "object") {
+            return domain;
+        }
+        const source = domain;
+        return {
+            ...(source.Domain !== undefined ? { Domain: source.Domain } : {}),
+            ...(source.Status !== undefined ? { Status: source.Status } : {}),
+            ...(source.Type !== undefined ? { Type: source.Type } : {}),
+        };
+    });
+}
 function formatDeviceAuthHint(deviceAuthInfo) {
     if (!deviceAuthInfo) {
         return "";
@@ -1076,6 +1110,35 @@ function registerEnvTools(server) {
                     const cloudbaseDomains = await getManager();
                     result = await cloudbaseDomains.env.getEnvAuthDomains();
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    if (result && typeof result === "object" && !Array.isArray(result)) {
+                        const domainsResult = result;
+                        const localDevHint = buildLocalDevDomainHint();
+                        const simplifiedDomains = simplifyEnvDomains(domainsResult.Domains);
+                        const localDevSummary = summarizeConfiguredLocalDevEntries(Array.isArray(simplifiedDomains)
+                            ? simplifiedDomains
+                            : []);
+                        result = {
+                            ...domainsResult,
+                            Domains: simplifiedDomains,
+                            localDevHint,
+                            localDevStatus: {
+                                requiresExactCurrentOrigin: true,
+                                browserUploadReady: false,
+                                coverageConfirmed: false,
+                                doNotAssumeConfiguredEntriesAreSufficient: true,
+                                canAutoDetermineCurrentOrigin: false,
+                                hasAnyConfiguredLocalEntry: localDevSummary.hasAnyConfiguredLocalEntry,
+                                configuredEntries: localDevSummary.configuredEntries,
+                                note: "此查询不会自动知道你当前浏览器实际使用的自定义域名或本地端口。即使已经存在一些 localhost/127.0.0.1 条目，也不能据此认定浏览器上传已就绪。若浏览器 Web 应用需要直接上传文件到 CloudBase，请先确认并添加当前访问地址对应的 host:port，再依赖 app.uploadFile()。",
+                            },
+                            next_step_template: {
+                                tool: "envDomainManagement",
+                                action: "create",
+                                domains: ["<actual-browser-host>:<actual-browser-port>"],
+                                note: "请把占位符替换为当前浏览器实际访问 origin 对应的 host:port，再执行添加。",
+                            },
+                        };
+                    }
                     break;
                 case "hosting": {
                     const cloudbaseHosting = await getManager();
@@ -1147,7 +1210,7 @@ function registerEnvTools(server) {
     // envDomainManagement - 环境域名管理（合并 createEnvDomain + deleteEnvDomain）
     server.registerTool?.("envDomainManagement", {
         title: "环境域名管理",
-        description: "管理云开发环境的安全域名，支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）",
+        description: "管理云开发环境的安全域名，支持添加和删除操作。（原工具名：createEnvDomain/deleteEnvDomain，为兼容旧AI规则可继续使用这些名称）当浏览器 Web 应用需要从本地 Vite / dev server 或自定义域名直接访问 CloudBase 资源时，应先用 envQuery(action=domains) 检查当前实际浏览器 origin 对应的 host:port 是否已在白名单中，再按该实际值添加。",
         inputSchema: {
             action: zod_1.z
                 .enum(["create", "delete"])
@@ -1509,7 +1572,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.16.1-beta.1" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.17.0-beta.2" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -1555,6 +1618,7 @@ function createWrappedHandler(name, handler, server) {
             // 执行原始处理函数
             const result = await handler(args);
             success = true;
+            requestId = extractRequestIdFromToolResult(result);
             const duration = Date.now() - startTime;
             (0, logger_js_1.debug)(`工具执行成功: ${name}`, { duration });
             if (!isTestEnvironment) {
@@ -1618,6 +1682,7 @@ function createWrappedHandler(name, handler, server) {
                 (0, telemetry_js_1.reportToolCall)({
                     toolName: name,
                     success,
+                    requestId,
                     duration,
                     error: errorMessage,
                     inputParams: sanitizeArgs(args), // 添加入参上报
@@ -1631,6 +1696,38 @@ function createWrappedHandler(name, handler, server) {
         }
     };
 }
+function extractRequestIdFromToolResult(result) {
+    if (!result || typeof result !== 'object') {
+        return undefined;
+    }
+    if (typeof result.requestId === 'string' && result.requestId.length > 0) {
+        return result.requestId;
+    }
+    if (typeof result.RequestId === 'string' && result.RequestId.length > 0) {
+        return result.RequestId;
+    }
+    const content = Array.isArray(result.content) ? result.content : [];
+    for (const item of content) {
+        if (!item || item.type !== 'text' || typeof item.text !== 'string') {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(item.text);
+            if (parsed && typeof parsed === 'object') {
+                if (typeof parsed.requestId === 'string' && parsed.requestId.length > 0) {
+                    return parsed.requestId;
+                }
+                if (typeof parsed.RequestId === 'string' && parsed.RequestId.length > 0) {
+                    return parsed.RequestId;
+                }
+            }
+        }
+        catch {
+            // Ignore non-JSON text payloads.
+        }
+    }
+    return undefined;
+}
 /**
  * 包装 MCP Server 的 registerTool 方法，添加数据上报功能和条件注册
  * @param server MCP Server 实例
@@ -3084,6 +3181,9 @@ exports.listAvailableEnvCandidates = listAvailableEnvCandidates;
 exports.getEnvId = getEnvId;
 exports.resetCloudBaseManagerCache = resetCloudBaseManagerCache;
 exports.getCachedEnvId = getCachedEnvId;
+exports.resetDatabaseInstanceIdCache = resetDatabaseInstanceIdCache;
+exports.invalidateDatabaseInstanceIdCache = invalidateDatabaseInstanceIdCache;
+exports.getDatabaseInstanceId = getDatabaseInstanceId;
 exports.getCloudBaseManager = getCloudBaseManager;
 exports.createCloudBaseManagerWithOptions = createCloudBaseManagerWithOptions;
 exports.extractRequestId = extractRequestId;
@@ -3116,7 +3216,7 @@ function createManagerFromLoginState(loginState, region) {
         envId: loginState.envId,
         token: loginState.token,
         proxy: process.env.http_proxy,
-        region,
+        region: region ?? process.env.TCB_REGION ?? 'ap-shanghai',
     });
 }
 async function listAvailableEnvCandidates(options) {
@@ -3135,7 +3235,7 @@ async function listAvailableEnvCandidates(options) {
         if (!loginState?.secretId || !loginState?.secretKey) {
             return [];
         }
-        const region = cloudBaseOptions?.region ?? process.env.TCB_REGION ?? undefined;
+        const region = cloudBaseOptions?.region ?? process.env.TCB_REGION ?? 'ap-shanghai';
         cloudbase = createManagerFromLoginState(loginState, region);
     }
     try {
@@ -3339,6 +3439,74 @@ function resetCloudBaseManagerCache() {
 function getCachedEnvId() {
     return envManager.getCachedEnvId();
 }
+const databaseInstanceIdCache = new Map();
+function buildDatabaseInstanceIdCacheKey(options) {
+    const envId = options?.envId ?? options?.cloudBaseOptions?.envId ?? process.env.CLOUDBASE_ENV_ID ?? 'unknown';
+    const region = options?.region ?? options?.cloudBaseOptions?.region ?? process.env.TCB_REGION ?? 'ap-shanghai';
+    return `${region}:${envId}`;
+}
+function resetDatabaseInstanceIdCache() {
+    databaseInstanceIdCache.clear();
+}
+function invalidateDatabaseInstanceIdCache(options) {
+    const cacheKey = options?.cacheKey ?? buildDatabaseInstanceIdCacheKey(options);
+    databaseInstanceIdCache.delete(cacheKey);
+}
+async function getDatabaseInstanceId(options) {
+    if (options?.instanceId) {
+        return {
+            instanceId: options.instanceId,
+            source: 'input',
+        };
+    }
+    const envId = await getEnvId(options?.cloudBaseOptions);
+    const cacheKey = buildDatabaseInstanceIdCacheKey({
+        envId,
+        cloudBaseOptions: options?.cloudBaseOptions,
+    });
+    const cachedEntry = databaseInstanceIdCache.get(cacheKey);
+    if (cachedEntry?.instanceId) {
+        return {
+            instanceId: cachedEntry.instanceId,
+            source: 'cache',
+            cacheKey,
+        };
+    }
+    if (cachedEntry?.inflightPromise) {
+        const instanceId = await cachedEntry.inflightPromise;
+        return {
+            instanceId,
+            source: 'cache',
+            cacheKey,
+        };
+    }
+    const inflightPromise = (async () => {
+        const cloudbase = options?.cloudbase ?? (await getCloudBaseManager({ cloudBaseOptions: options?.cloudBaseOptions }));
+        const { EnvInfo } = await cloudbase.env.getEnvInfo();
+        if (!EnvInfo?.Databases?.[0]?.InstanceId) {
+            throw new Error("无法获取数据库实例ID");
+        }
+        return EnvInfo.Databases[0].InstanceId;
+    })();
+    databaseInstanceIdCache.set(cacheKey, {
+        inflightPromise,
+    });
+    try {
+        const instanceId = await inflightPromise;
+        databaseInstanceIdCache.set(cacheKey, {
+            instanceId,
+        });
+        return {
+            instanceId,
+            source: 'envInfo',
+            cacheKey,
+        };
+    }
+    catch (error) {
+        databaseInstanceIdCache.delete(cacheKey);
+        throw error;
+    }
+}
 /**
  * 每次都实时获取最新的 token/secretId/secretKey
  */
@@ -3379,8 +3547,8 @@ async function getCloudBaseManager(options = {}) {
         });
     }
     try {
-        // Get region from environment variable for auth URL
-        const fallbackRegion = cloudBaseOptions?.region ?? process.env.TCB_REGION;
+        // Region priority: explicit option > env var > ap-shanghai default
+        const fallbackRegion = cloudBaseOptions?.region ?? process.env.TCB_REGION ?? 'ap-shanghai';
         const loginState = authStrategy === 'ensure'
             ? await (0, auth_js_1.getLoginState)({ region: fallbackRegion })
             : await (0, auth_js_1.peekLoginState)();
@@ -3428,24 +3596,19 @@ async function getCloudBaseManager(options = {}) {
                 }
             }
         }
-        // envId priority: envManager.cachedEnvId > envManager.getEnvId() > loginState.envId > undefined
-        // Note: envManager.cachedEnvId has highest priority as it reflects user's latest environment switch
-        // Region priority: envCandidates[].region (actual env region) > process.env.TCB_REGION > undefined
-        // Resolving the environment's own region avoids INVALID_REGION errors when TCB_REGION
-        // is set to a different region than the target environment.
+        // envId priority: explicit option > envManager cache > loginState.envId
         const resolvedEnvId = finalEnvId || loginEnvId;
         let region = fallbackRegion;
         if (resolvedEnvId && !cloudBaseOptions?.region) {
             try {
                 const envCandidates = await listAvailableEnvCandidates({ loginState });
-                const matchedEnv = envCandidates.find(c => c.envId === resolvedEnvId);
+                const matchedEnv = envCandidates.find((candidate) => candidate.envId === resolvedEnvId);
                 if (matchedEnv?.region) {
                     region = matchedEnv.region;
                     (0, logger_js_1.debug)('使用环境实际 region:', { envId: resolvedEnvId, region });
                 }
             }
             catch {
-                // If env listing fails, fall back to TCB_REGION / undefined
                 (0, logger_js_1.debug)('无法获取环境列表，使用 fallback region');
             }
         }
@@ -3478,8 +3641,8 @@ function createCloudBaseManagerWithOptions(cloudBaseOptions) {
         hasSecretKey: !!cloudBaseOptions.secretKey,
         hasToken: !!cloudBaseOptions.token,
     });
-    // Region priority: cloudBaseOptions.region > process.env.TCB_REGION > undefined (use SDK default)
-    const region = cloudBaseOptions.region ?? process.env.TCB_REGION ?? undefined;
+    // Region priority: explicit option > env var > ap-shanghai default
+    const region = cloudBaseOptions.region ?? process.env.TCB_REGION ?? 'ap-shanghai';
     const manager = new manager_node_1.default({
         ...cloudBaseOptions,
         proxy: cloudBaseOptions.proxy || process.env.http_proxy,
@@ -3546,20 +3709,12 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.registerDatabaseTools = registerDatabaseTools;
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
+const logger_js_1 = __webpack_require__(3039);
 const CATEGORY = "NoSQL database";
 const COLLECTION_READY_TIMEOUT_MS = 10000;
 const COLLECTION_READY_POLL_INTERVAL_MS = 500;
 /** Convert object values to JSON strings for API calls */
 const toJSONString = (v) => typeof v === "object" && v !== null ? JSON.stringify(v) : v;
-// 获取数据库实例ID
-async function getDatabaseInstanceId(getManager) {
-    const cloudbase = await getManager();
-    const { EnvInfo } = await cloudbase.env.getEnvInfo();
-    if (!EnvInfo?.Databases?.[0]?.InstanceId) {
-        throw new Error("无法获取数据库实例ID");
-    }
-    return EnvInfo.Databases[0].InstanceId;
-}
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -3635,6 +3790,83 @@ function withCollectionName(collectionName, payload) {
         collectionName,
     };
 }
+function logNoSqlLatency(toolName, phase, details) {
+    (0, logger_js_1.debug)("[nosql-latency]", {
+        toolName,
+        phase,
+        ...details,
+    });
+}
+function isInvalidInstanceIdError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    return /(instance.?id|tag).*(invalid|错误|不存在|not exist|not found)|invalid.*(instance.?id|tag)/i.test(message);
+}
+async function resolveNoSqlInstanceId(options) {
+    const startedAt = Date.now();
+    const resolved = await (0, cloudbase_manager_js_1.getDatabaseInstanceId)({
+        instanceId: options.instanceIdOverride,
+        cloudBaseOptions: options.cloudBaseOptions,
+        cloudbase: options.cloudbase,
+    });
+    logNoSqlLatency(options.toolName, "resolveInstanceId", {
+        collectionName: options.collectionName,
+        durationMs: Date.now() - startedAt,
+        instanceIdSource: resolved.source,
+        cacheKey: resolved.cacheKey,
+    });
+    return resolved;
+}
+async function callNoSqlContentApi(options) {
+    const resolvedInstance = await resolveNoSqlInstanceId({
+        toolName: options.toolName,
+        cloudbase: options.cloudbase,
+        cloudBaseOptions: options.cloudBaseOptions,
+        instanceIdOverride: options.instanceIdOverride,
+        collectionName: options.collectionName,
+    });
+    const startedAt = Date.now();
+    try {
+        const result = await options.cloudbase
+            .commonService("tcb", "2018-06-08")
+            .call({
+            Action: options.action,
+            Param: {
+                ...options.param,
+                TableName: options.collectionName,
+                Tag: resolvedInstance.instanceId,
+            },
+        });
+        logNoSqlLatency(options.toolName, "cloudApiCall", {
+            collectionName: options.collectionName,
+            action: options.action,
+            durationMs: Date.now() - startedAt,
+            instanceIdSource: resolvedInstance.source,
+            requestId: result?.RequestId,
+        });
+        return result;
+    }
+    catch (error) {
+        logNoSqlLatency(options.toolName, "cloudApiError", {
+            collectionName: options.collectionName,
+            action: options.action,
+            durationMs: Date.now() - startedAt,
+            instanceIdSource: resolvedInstance.source,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        if (!options.instanceIdOverride &&
+            resolvedInstance.cacheKey &&
+            isInvalidInstanceIdError(error)) {
+            (0, cloudbase_manager_js_1.invalidateDatabaseInstanceIdCache)({
+                cacheKey: resolvedInstance.cacheKey,
+            });
+            logNoSqlLatency(options.toolName, "invalidateInstanceIdCache", {
+                collectionName: options.collectionName,
+                cacheKey: resolvedInstance.cacheKey,
+            });
+        }
+        throw error;
+    }
+}
 async function waitForCollectionReady({ cloudbase, collectionName, logger, timeoutMs = COLLECTION_READY_TIMEOUT_MS, pollIntervalMs = COLLECTION_READY_POLL_INTERVAL_MS, }) {
     const startedAt = Date.now();
     const deadline = startedAt + timeoutMs;
@@ -3692,7 +3924,7 @@ function registerDatabaseTools(server) {
     // readNoSqlDatabaseStructure
     server.registerTool?.("readNoSqlDatabaseStructure", {
         title: "读取 NoSQL 数据库结构",
-        description: "读取 NoSQL 数据库结构",
+        description: "读取 NoSQL 数据库集合与索引结构，支持列出集合、查看集合详情、列出索引以及检查索引是否存在。",
         inputSchema: {
             action: zod_1.z.enum([
                 "listCollections",
@@ -3701,10 +3933,10 @@ function registerDatabaseTools(server) {
                 "listIndexes",
                 "checkIndex",
             ]).describe(`listCollections: 列出集合列表
-describeCollection: 描述集合
+describeCollection: 描述集合详情（会返回索引摘要）
 checkCollection: 检查集合是否存在
-listIndexes: 列出索引列表
-checkIndex: 检查索引是否存在`),
+listIndexes: 列出指定集合的索引列表
+checkIndex: 检查指定索引是否存在`),
             limit: zod_1.z
                 .number()
                 .optional()
@@ -3840,38 +4072,42 @@ checkIndex: 检查索引是否存在`),
     // writeNoSqlDatabaseStructure
     server.registerTool?.("writeNoSqlDatabaseStructure", {
         title: "修改 NoSQL 数据库结构",
-        description: "修改 NoSQL 数据库结构",
+        description: "修改 NoSQL 数据库结构，支持创建/删除集合，以及通过 updateCollection 的 updateOptions.CreateIndexes / updateOptions.DropIndexes 添加索引和删除索引。",
         inputSchema: {
             action: zod_1.z.enum([
                 "createCollection",
                 "updateCollection",
                 "deleteCollection",
             ]).describe(`createCollection: 创建集合
-updateCollection: 更新集合
+updateCollection: 更新集合配置；添加索引请传 updateOptions.CreateIndexes，删除索引请传 updateOptions.DropIndexes
 deleteCollection: 删除集合`),
             collectionName: zod_1.z.string().describe("集合名称"),
             updateOptions: zod_1.z
                 .object({
                 CreateIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要创建的索引名称"),
                     MgoKeySchema: zod_1.z.object({
-                        MgoIsUnique: zod_1.z.boolean(),
+                        MgoIsUnique: zod_1.z.boolean().describe("是否唯一索引"),
                         MgoIndexKeys: zod_1.z.array(zod_1.z.object({
-                            Name: zod_1.z.string(),
-                            Direction: zod_1.z.string(),
-                        })),
-                    }),
+                            Name: zod_1.z.string().describe("索引字段名"),
+                            Direction: zod_1.z
+                                .string()
+                                .describe("索引方向，通常 1 表示升序，-1 表示降序"),
+                        })).describe("索引字段列表，支持单字段或复合索引"),
+                    }).describe("待创建索引的字段与约束配置"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要添加的索引列表"),
                 DropIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要删除的索引名称"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要删除的索引列表"),
             })
                 .optional()
-                .describe("更新选项(updateCollection 时使用)"),
+                .describe("更新选项(updateCollection 时使用)。CreateIndexes 用于添加索引，DropIndexes 用于删除索引。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -3883,6 +4119,24 @@ deleteCollection: 删除集合`),
     }, async ({ action, collectionName, updateOptions }) => {
         const cloudbase = await getManager();
         if (action === "createCollection") {
+            const existsResult = await cloudbase.database.checkCollectionExists(collectionName);
+            (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, existsResult);
+            if (existsResult.Exists) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(withCollectionName(collectionName, {
+                                success: true,
+                                action,
+                                requestId: existsResult.RequestId,
+                                message: "集合已存在，无需重复创建",
+                                exists: true,
+                            }), null, 2),
+                        },
+                    ],
+                };
+            }
             const result = await cloudbase.database.createCollection(collectionName);
             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
             await waitForCollectionReady({
@@ -3953,6 +4207,10 @@ deleteCollection: 删除集合`),
         description: "查询并获取 NoSQL 数据库数据记录",
         inputSchema: {
             collectionName: zod_1.z.string().describe("集合名称"),
+            instanceId: zod_1.z
+                .string()
+                .optional()
+                .describe("可选：显式指定数据库实例ID；未传时会自动解析并缓存"),
             query: zod_1.z
                 .union([zod_1.z.object({}).passthrough(), zod_1.z.string()])
                 .optional()
@@ -3981,24 +4239,37 @@ deleteCollection: 删除集合`),
             openWorldHint: true,
             category: CATEGORY,
         },
-    }, async ({ collectionName, query, projection, sort, limit, offset }) => {
+    }, async ({ collectionName, instanceId, query, projection, sort, limit, offset }) => {
+        const managerStartedAt = Date.now();
         const cloudbase = await getManager();
-        const instanceId = await getDatabaseInstanceId(getManager);
+        logNoSqlLatency("readNoSqlDatabaseContent", "getManager", {
+            collectionName,
+            durationMs: Date.now() - managerStartedAt,
+        });
         const normalizedSort = normalizeSortInput(sort);
-        const result = await cloudbase.commonService("tcb", "2018-06-08").call({
-            Action: "QueryRecords",
-            Param: {
-                TableName: collectionName,
+        const result = await callNoSqlContentApi({
+            toolName: "readNoSqlDatabaseContent",
+            action: "QueryRecords",
+            collectionName,
+            cloudbase,
+            cloudBaseOptions,
+            instanceIdOverride: instanceId,
+            param: {
                 MgoQuery: toJSONString(query),
                 MgoProjection: toJSONString(projection),
                 MgoSort: normalizedSort,
                 MgoLimit: limit ?? 100,
                 MgoOffset: offset,
-                Tag: instanceId,
             },
         });
         (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+        const parseStartedAt = Date.now();
         const documents = normalizeNoSqlDocuments(result.Data);
+        logNoSqlLatency("readNoSqlDatabaseContent", "parseResult", {
+            collectionName,
+            durationMs: Date.now() - parseStartedAt,
+            documentCount: documents.length,
+        });
         return {
             content: [
                 {
@@ -4020,12 +4291,16 @@ deleteCollection: 删除集合`),
     // writeNoSqlDatabaseContent
     server.registerTool?.("writeNoSqlDatabaseContent", {
         title: "修改 NoSQL 数据库数据记录",
-        description: "修改 NoSQL 数据库数据记录。可按 MongoDB updateOne/updateMany 的心智模型理解：部分更新必须使用 $set/$inc/$push 等更新操作符；如果直接传 { field: value } 这类普通对象，底层会把它当作替换内容，存在覆盖整条文档的风险。更新嵌套对象中的某个字段时必须使用点号路径（如 { \"$set\": { \"address.city\": \"shenzhen\" } }），若写成 { \"$set\": { \"address\": { \"city\": \"shenzhen\" } } } 则整个 address 对象会被替换，同级其他字段将丢失。",
+        description: "修改 NoSQL 数据库数据记录。可按 MongoDB updateOne/updateMany 的心智模型理解：部分更新必须使用 $set/$inc/$push 等更新操作符；如果直接传 { field: value } 这类普通对象，底层会把它当作替换内容，存在覆盖整条文档的风险。更新嵌套对象中的某个字段时必须使用点号路径（如 { \"$set\": { \"address.city\": \"shenzhen\" } }），若写成 { \"$set\": { \"address\": { \"city\": \"shenzhen\" } } } 则整个 address 对象会被替换，同级其他字段将丢失。若集合中的角色/档案文档会在前端通过 `db.collection(...).doc(uid)` 读取，请确保文档 `_id` 就是该 `uid`；不要用 `query={\"uid\":\"...\"}` + `upsert=true` 去更新 `users` / `profiles`，否则经常会生成一个不同的 `_id`，导致后续 `doc(uid)` 读取命中不到。",
         inputSchema: {
             action: zod_1.z
                 .enum(["insert", "update", "delete"])
                 .describe(`insert: 插入数据（新增文档）\nupdate: 更新数据\ndelete: 删除数据`),
             collectionName: zod_1.z.string().describe("集合名称"),
+            instanceId: zod_1.z
+                .string()
+                .optional()
+                .describe("可选：显式指定数据库实例ID；未传时会自动解析并缓存"),
             documents: zod_1.z
                 .array(zod_1.z.object({}).passthrough())
                 .optional()
@@ -4054,16 +4329,18 @@ deleteCollection: 删除集合`),
             openWorldHint: true,
             category: CATEGORY,
         },
-    }, async ({ action, collectionName, documents, query, update, isMulti, upsert, }) => {
+    }, async ({ action, collectionName, instanceId, documents, query, update, isMulti, upsert, }) => {
         if (action === "insert") {
             if (!documents) {
                 throw new Error("insert 操作时必须提供 documents");
             }
             const text = await insertDocuments({
                 collectionName,
+                instanceId,
                 documents,
                 getManager,
                 logger,
+                cloudBaseOptions,
             });
             return {
                 content: [
@@ -4083,12 +4360,14 @@ deleteCollection: 删除集合`),
             }
             const text = await updateDocuments({
                 collectionName,
+                instanceId,
                 query,
                 update,
                 isMulti,
                 upsert,
                 getManager,
                 logger,
+                cloudBaseOptions,
             });
             return {
                 content: [
@@ -4105,10 +4384,12 @@ deleteCollection: 删除集合`),
             }
             const text = await deleteDocuments({
                 collectionName,
+                instanceId,
                 query,
                 isMulti,
                 getManager,
                 logger,
+                cloudBaseOptions,
             });
             return {
                 content: [
@@ -4122,16 +4403,24 @@ deleteCollection: 删除集合`),
         throw new Error(`不支持的操作类型: ${action}`);
     });
 }
-async function insertDocuments({ collectionName, documents, getManager, logger, }) {
+async function insertDocuments({ collectionName, instanceId, documents, getManager, logger, cloudBaseOptions, }) {
+    const managerStartedAt = Date.now();
     const cloudbase = await getManager();
-    const instanceId = await getDatabaseInstanceId(getManager);
+    logNoSqlLatency("writeNoSqlDatabaseContent", "getManager", {
+        collectionName,
+        action: "insert",
+        durationMs: Date.now() - managerStartedAt,
+    });
     const docsAsStrings = documents.map((doc) => JSON.stringify(doc));
-    const result = await cloudbase.commonService("tcb", "2018-06-08").call({
-        Action: "PutItem",
-        Param: {
-            TableName: collectionName,
+    const result = await callNoSqlContentApi({
+        toolName: "writeNoSqlDatabaseContent",
+        action: "PutItem",
+        collectionName,
+        cloudbase,
+        cloudBaseOptions,
+        instanceIdOverride: instanceId,
+        param: {
             MgoDocs: docsAsStrings,
-            Tag: instanceId,
         },
     });
     (0, cloudbase_manager_js_1.logCloudBaseResult)(logger, result);
@@ -4145,18 +4434,31 @@ async function insertDocuments({ collectionName, documents, getManager, logger,
         message: "文档插入成功",
     }), null, 2);
 }
-async function updateDocuments({ collectionName, query, update, isMulti, upsert, getManager, logger, }) {
+async function updateDocuments({ collectionName, instanceId, query, update, isMulti, upsert, getManager, logger, cloudBaseOptions, }) {
+    const managerStartedAt = Date.now();
     const cloudbase = await getManager();
-    const instanceId = await getDatabaseInstanceId(getManager);
-    const result = await cloudbase.commonService("tcb", "2018-06-08").call({
-        Action: "UpdateItem",
-        Param: {
-            TableName: collectionName,
+    logNoSqlLatency("writeNoSqlDatabaseContent", "getManager", {
+        collectionName,
+        action: "update",
+        durationMs: Date.now() - managerStartedAt,
+    });
+    const authLinkedDocWarning = buildAuthLinkedDocWarning({
+        collectionName,
+        query,
+        upsert,
+    });
+    const result = await callNoSqlContentApi({
+        toolName: "writeNoSqlDatabaseContent",
+        action: "UpdateItem",
+        collectionName,
+        cloudbase,
+        cloudBaseOptions,
+        instanceIdOverride: instanceId,
+        param: {
             MgoQuery: toJSONString(query),
             MgoUpdate: toJSONString(update),
             MgoIsMulti: isMulti,
             MgoUpsert: upsert,
-            Tag: instanceId,
         },
     });
     (0, cloudbase_manager_js_1.logCloudBaseResult)(logger, result);
@@ -4166,19 +4468,56 @@ async function updateDocuments({ collectionName, query, update, isMulti, upsert,
         modifiedCount: result.ModifiedNum,
         matchedCount: result.MatchedNum,
         upsertedId: result.UpsertedId,
-        message: "文档更新成功",
+        ...(authLinkedDocWarning ? { warning: authLinkedDocWarning } : {}),
+        message: authLinkedDocWarning ? `文档更新成功；${authLinkedDocWarning}` : "文档更新成功",
     }), null, 2);
 }
-async function deleteDocuments({ collectionName, query, isMulti, getManager, logger, }) {
+function tryParseObjectLike(value) {
+    if (typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function buildAuthLinkedDocWarning({ collectionName, query, upsert, }) {
+    if (!upsert)
+        return null;
+    if (!["users", "profiles", "user_roles", "userProfiles"].includes(collectionName))
+        return null;
+    const queryObject = tryParseObjectLike(query);
+    if (!queryObject)
+        return null;
+    if (!("uid" in queryObject) && !("userId" in queryObject))
+        return null;
+    return "若前端会用 doc(uid) 读取该集合，请改为直接创建 `_id = uid` 的文档；基于 uid 查询再 upsert 往往会生成不同的 `_id`，导致后续 doc(uid) 读取失败。";
+}
+async function deleteDocuments({ collectionName, instanceId, query, isMulti, getManager, logger, cloudBaseOptions, }) {
+    const managerStartedAt = Date.now();
     const cloudbase = await getManager();
-    const instanceId = await getDatabaseInstanceId(getManager);
-    const result = await cloudbase.commonService("tcb", "2018-06-08").call({
-        Action: "DeleteItem",
-        Param: {
-            TableName: collectionName,
+    logNoSqlLatency("writeNoSqlDatabaseContent", "getManager", {
+        collectionName,
+        action: "delete",
+        durationMs: Date.now() - managerStartedAt,
+    });
+    const result = await callNoSqlContentApi({
+        toolName: "writeNoSqlDatabaseContent",
+        action: "DeleteItem",
+        collectionName,
+        cloudbase,
+        cloudBaseOptions,
+        instanceIdOverride: instanceId,
+        param: {
             MgoQuery: toJSONString(query),
             MgoIsMulti: isMulti,
-            Tag: instanceId,
         },
     });
     (0, cloudbase_manager_js_1.logCloudBaseResult)(logger, result);
@@ -5243,6 +5582,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.resolveSkillSearchRoots = resolveSkillSearchRoots;
 exports.getClaudePrompt = getClaudePrompt;
 exports.registerRagTools = registerRagTools;
 const adm_zip_1 = __importDefault(__webpack_require__(2872));
@@ -5251,10 +5591,20 @@ const lockfile_1 = __importDefault(__webpack_require__(959));
 const os = __importStar(__webpack_require__(8116));
 const path = __importStar(__webpack_require__(2521));
 const zod_1 = __webpack_require__(2971);
+const cloudbase_manager_js_1 = __webpack_require__(3431);
 const claude_prompt_js_1 = __webpack_require__(8359);
+const json_content_js_1 = __webpack_require__(4365);
 const logger_js_1 = __webpack_require__(3039);
 // 1. 枚举定义
 const KnowledgeBaseEnum = zod_1.z.enum(["cloudbase", "scf", "miniprogram"]);
+const SearchKnowledgeModeEnum = zod_1.z.enum(["vector", "skill", "openapi", "docs"]);
+const CloudBaseDocsActionEnum = zod_1.z.enum([
+    "listModules",
+    "listModuleDocs",
+    "findByName",
+    "readDoc",
+    "searchDocs",
+]);
 // 2. 枚举到后端 id 的映射
 const KnowledgeBaseIdMap = {
     cloudbase: "ykfzskv4_ad28",
@@ -5314,6 +5664,39 @@ else {
 }
 // 共享的下载 Promise，防止并发重复下载
 let resourceDownloadPromise = null;
+async function filterExistingDirs(pathsToCheck) {
+    const resolved = [];
+    for (const candidate of pathsToCheck) {
+        if (!candidate || resolved.includes(candidate)) {
+            continue;
+        }
+        try {
+            const stat = await fs.stat(candidate);
+            if (stat.isDirectory()) {
+                resolved.push(candidate);
+            }
+        }
+        catch {
+            // Ignore missing candidates and keep checking fallbacks.
+        }
+    }
+    return resolved;
+}
+async function resolveSkillSearchRoots(options = {}) {
+    const cliEntryPath = options.cliEntryPath ?? process.argv[1];
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoot = cliEntryPath
+        ? path.resolve(path.dirname(cliEntryPath), "..", "..")
+        : undefined;
+    return filterExistingDirs([
+        repoRoot
+            ? path.join(repoRoot, ".generated", "compat-config", ".codebuddy", "skills")
+            : undefined,
+        repoRoot ? path.join(repoRoot, "config", "source", "skills") : undefined,
+        options.fallbackSkillsRoot,
+        path.join(homeDir, ".cloudbase-mcp", "web-template", ".claude", "skills"),
+    ]);
+}
 // 检查缓存是否可用（未过期）
 async function canUseCache() {
     try {
@@ -5371,6 +5754,29 @@ function safeStringify(obj) {
         return "";
     }
 }
+function buildDocsEnvelope(action, data, message) {
+    return {
+        success: true,
+        data: {
+            action,
+            ...data,
+        },
+        message,
+    };
+}
+function buildDocsErrorEnvelope(error) {
+    return {
+        success: false,
+        data: {},
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+function requireStringParam(value, fieldName, action) {
+    if (!value?.trim()) {
+        throw new Error(`action=${action} 时必须提供 ${fieldName}`);
+    }
+    return value.trim();
+}
 // OpenAPI 文档 URL 列表
 const OPENAPI_SOURCES = [
     {
@@ -5676,21 +6082,38 @@ async function registerRagTools(server) {
     });
     let openapis = [];
     let skills = [];
+    let fallbackSkillsRoot;
     try {
         const { webTemplateDir, openAPIDocs } = await downloadResources();
         openapis = openAPIDocs;
-        skills = await collectSkillDescriptions(path.join(webTemplateDir, ".claude", "skills"));
+        fallbackSkillsRoot = path.join(webTemplateDir, ".claude", "skills");
     }
     catch (error) {
         (0, logger_js_1.warn)("[downloadResources] Failed to download resources", {
             error,
         });
     }
+    try {
+        const skillRoots = await resolveSkillSearchRoots({
+            fallbackSkillsRoot,
+        });
+        const preferredSkillRoot = skillRoots[0];
+        if (preferredSkillRoot) {
+            skills = await collectSkillDescriptions(preferredSkillRoot);
+        }
+    }
+    catch (error) {
+        (0, logger_js_1.warn)("[registerRagTools] Failed to resolve local skill roots", {
+            error,
+        });
+    }
+    const getDocsManager = () => (0, cloudbase_manager_js_1.createCloudBaseManagerWithOptions)(server.cloudBaseOptions ?? {})
+        ?.docs;
     server.registerTool?.("searchKnowledgeBase", {
         title: "云开发知识库检索",
-        description: `云开发知识库智能检索工具，支持向量查询 (vector)、固定技能文档 (skill) 和 OpenAPI 文档 (openapi) 查询。
+        description: `云开发知识库智能检索工具，支持向量查询 (vector)、固定技能文档 (skill)、OpenAPI 文档 (openapi) 和 CloudBase 官方文档 (docs) 查询。
 
-      强烈推荐始终优先使用固定技能文档 (skill) 或 OpenAPI 文档 (openapi) 模式进行检索，仅当固定技能文档无法覆盖你的问题时，再使用向量查询 (vector) 模式。
+      强烈推荐始终优先使用固定技能文档 (skill)、OpenAPI 文档 (openapi) 或 CloudBase 官方文档 (docs) 模式进行检索，仅当固定文档无法覆盖你的问题时，再使用向量查询 (vector) 模式。
 
       固定技能文档 (skill) 查询当前支持 ${skills.length} 个固定文档，分别是：
       ${skills
@@ -5702,7 +6125,7 @@ async function registerRagTools(server) {
             .map((api) => `API名：${api.name} API介绍：${api.description}`)
             .join("\n")}`,
         inputSchema: {
-            mode: zod_1.z.enum(["vector", "skill", "openapi"]),
+            mode: SearchKnowledgeModeEnum,
             skillName: zod_1.z
                 .enum(skills.map((skill) => path.basename(path.dirname(skill.absolutePath))))
                 .optional()
@@ -5711,6 +6134,23 @@ async function registerRagTools(server) {
                 .enum(openapis.map((api) => api.name))
                 .optional()
                 .describe("mode=openapi 时指定。API 名称。"),
+            action: CloudBaseDocsActionEnum.optional().describe("mode=docs 时指定。CloudBase 文档操作类型：listModules=列出所有文档模块，listModuleDocs=获取指定模块的目录结构，findByName=按名称/路径/URL 智能查找，readDoc=读取指定文档 Markdown，searchDocs=全文搜索官方文档。"),
+            moduleName: zod_1.z
+                .string()
+                .optional()
+                .describe("mode=docs 且 action=listModuleDocs 时指定。模块名称。"),
+            input: zod_1.z
+                .string()
+                .optional()
+                .describe("mode=docs 且 action=findByName 时指定。支持模块名、文档标题、层级路径或 URL。"),
+            docPath: zod_1.z
+                .string()
+                .optional()
+                .describe("mode=docs 且 action=readDoc 时指定。文档相对路径或完整 URL。"),
+            query: zod_1.z
+                .string()
+                .optional()
+                .describe("mode=docs 且 action=searchDocs 时指定。全文检索关键词。"),
             threshold: zod_1.z
                 .number()
                 .default(0.5)
@@ -5740,14 +6180,62 @@ async function registerRagTools(server) {
             openWorldHint: true,
             category: "rag",
         },
-    }, async ({ id, content, options: { chunkExpand = [3, 3] } = {}, limit = 5, threshold = 0.5, mode, skillName, apiName, }) => {
+    }, async ({ id, content, options, limit = 5, threshold = 0.5, mode, skillName, apiName, action, moduleName, input, docPath, query, }) => {
+        const chunkExpand = options?.chunkExpand ?? [3, 3];
+        if (mode === "docs") {
+            try {
+                const resolvedAction = action;
+                if (!resolvedAction) {
+                    throw new Error("mode=docs 时必须提供 action");
+                }
+                const docsManager = getDocsManager();
+                if (!docsManager) {
+                    throw new Error("当前 @cloudbase/manager-node 实例不支持 app.docs，请确认版本 >= 5.0.0。");
+                }
+                if (resolvedAction === "listModules") {
+                    const modules = await docsManager.listModules();
+                    return (0, json_content_js_1.jsonContent)(buildDocsEnvelope(resolvedAction, { modules }, "CloudBase 文档模块列表获取成功"));
+                }
+                if (resolvedAction === "listModuleDocs") {
+                    const resolvedModuleName = requireStringParam(moduleName, "moduleName", resolvedAction);
+                    const docs = await docsManager.listModuleDocs(resolvedModuleName);
+                    return (0, json_content_js_1.jsonContent)(buildDocsEnvelope(resolvedAction, { moduleName: resolvedModuleName, docs }, "CloudBase 模块文档目录获取成功"));
+                }
+                if (resolvedAction === "findByName") {
+                    const resolvedInput = requireStringParam(input, "input", resolvedAction);
+                    const result = await docsManager.findByName(resolvedInput);
+                    return (0, json_content_js_1.jsonContent)(buildDocsEnvelope(resolvedAction, { input: resolvedInput, result }, "CloudBase 文档查找成功"));
+                }
+                if (resolvedAction === "readDoc") {
+                    const resolvedDocPath = requireStringParam(docPath, "docPath", resolvedAction);
+                    const markdown = await docsManager.readDoc(resolvedDocPath);
+                    return (0, json_content_js_1.jsonContent)(buildDocsEnvelope(resolvedAction, { docPath: resolvedDocPath, content: markdown }, "CloudBase 文档读取成功"));
+                }
+                const resolvedQuery = requireStringParam(query, "query", resolvedAction);
+                const results = await docsManager.searchDocs(resolvedQuery);
+                return (0, json_content_js_1.jsonContent)(buildDocsEnvelope(resolvedAction, { query: resolvedQuery, results }, "CloudBase 文档搜索成功"));
+            }
+            catch (error) {
+                return (0, json_content_js_1.jsonContent)(buildDocsErrorEnvelope(error));
+            }
+        }
         if (mode === "skill") {
-            const absolutePath = skills.find((skill) => skill.absolutePath.includes(skillName)).absolutePath;
+            const skill = skills.find((item) => item.absolutePath.includes(skillName));
+            if (!skill) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Skill document "${skillName}" not found. Available skill docs: ${skills.map((item) => path.basename(path.dirname(item.absolutePath))).join(", ") || "none"}`,
+                        },
+                    ],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: `The skill doc's absolute path is: ${absolutePath}. ${(await fs.readFile(absolutePath)).toString()}`,
+                        text: `The skill doc's absolute path is: ${skill.absolutePath}. ${(await fs.readFile(skill.absolutePath)).toString()}`,
                     },
                 ],
             };
@@ -5759,7 +6247,7 @@ async function registerRagTools(server) {
                     content: [
                         {
                             type: "text",
-                            text: `OpenAPI document "${apiName}" not found. Available APIs: ${openapis.map((a) => a.name).join(", ")}`,
+                            text: `OpenAPI document "${apiName}" not found. Available APIs: ${openapis.map((a) => a.name).join(", ") || "none"}`,
                         },
                     ],
                 };
@@ -6106,12 +6594,25 @@ function registerGatewayTools(server) {
                 }
                 const cloudbase = await getManager();
                 const accessPath = normalizeAccessPath(input.path || `/${input.targetName}`);
-                const result = await cloudbase.access.createAccess({
-                    name: input.targetName,
-                    path: accessPath,
-                    type: ((input.type || "Event") === "HTTP" ? 6 : 1),
-                    auth: input.auth,
-                });
+                let result;
+                try {
+                    result = await cloudbase.access.createAccess({
+                        name: input.targetName,
+                        path: accessPath,
+                        type: ((input.type || "Event") === "HTTP" ? 6 : 1),
+                        auth: input.auth,
+                    });
+                }
+                catch (err) {
+                    if (err.message && err.message.includes("An error has occurred")) {
+                        let hint = "为目标资源配置访问路由失败（后端内部错误）。请确保：1) 目标云函数已成功创建并处于 Active 状态；2) 环境默认 HTTP 域名已完成初始化；3) 该访问路径未被占用。";
+                        if (input.type === "HTTP") {
+                            hint += "此外注意：如果目标函数最初是作为 Event 函数创建的，这里 type 必须依然传 Event（或省略），传 HTTP 会导致此错误。";
+                        }
+                        throw new Error(`${hint} 原始错误：${err.message}`);
+                    }
+                    throw err;
+                }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 return buildEnvelope({
                     action: input.action,
@@ -6287,7 +6788,7 @@ function registerGatewayTools(server) {
                 .describe("目标资源类型。当前支持 function，后续可扩展"),
             targetName: zod_1.z.string().optional().describe("目标资源名称"),
             path: zod_1.z.string().optional().describe("访问路径，默认 /{targetName}"),
-            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("函数接入类型"),
+            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("目标函数的本身类型（非接入形式）。如果被访问的函数是 Event 型（默认），此处必须传 Event；只有当被访问函数在创建时就是 HTTP 函数时才传 HTTP。"),
             auth: zod_1.z.boolean().optional().describe("是否开启鉴权"),
             route: zod_1.z
                 .object({
@@ -7524,28 +8025,36 @@ exports.registerAppAuthTools = registerAppAuthTools;
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const json_content_js_1 = __webpack_require__(4365);
+const tool_result_js_1 = __webpack_require__(9835);
 const QUERY_APP_AUTH_ACTIONS = [
     "getLoginConfig",
     "listProviders",
     "getProvider",
     "getClientConfig",
-    "listApiKeyTokens",
+    "getPublishableKey",
     "getStaticDomain",
+    "listApiKeys",
 ];
 const MANAGE_APP_AUTH_ACTIONS = [
-    "updateLoginConfig",
+    "patchLoginStrategy",
+    "addProvider",
     "updateProvider",
+    "deleteProvider",
     "updateClientConfig",
-    "createApiKeyToken",
+    "ensurePublishableKey",
+    "createApiKey",
+    "deleteApiKey",
     "createCustomLoginKeys",
 ];
-function buildEnvelope(data, message) {
-    return {
-        success: true,
-        data,
-        message,
-    };
-}
+const APP_AUTH_KEY_TYPES = ["publish_key", "api_key"];
+const SUPABASE_LIKE_SDK_HINTS = {
+    phoneOtp: "auth.signInWithOtp({ phone })",
+    emailOtp: "auth.signInWithOtp({ email })",
+    password: "auth.signInWithPassword({ username|email|phone, password })",
+    signup: "auth.signUp({ phone|email, ... })",
+    verifyOtp: "verifyOtp({ token })",
+    anonymous: "auth.signInAnonymously()",
+};
 function buildErrorEnvelope(error) {
     return {
         success: false,
@@ -7553,6 +8062,19 @@ function buildErrorEnvelope(error) {
         message: error instanceof Error ? error.message : String(error),
     };
 }
+function buildShortError(error) {
+    return {
+        success: false,
+        error,
+    };
+}
+function buildShortErrorWithCode(error, code) {
+    return {
+        success: false,
+        error,
+        code,
+    };
+}
 function normalizePlainObject(value, label) {
     if (value === undefined) {
         return undefined;
@@ -7562,6 +8084,25 @@ function normalizePlainObject(value, label) {
     }
     return value;
 }
+function normalizeLocalizedMessage(value, label, fallback) {
+    if (typeof value === "string") {
+        return { Message: value };
+    }
+    const normalized = normalizePlainObject(value, label);
+    if (normalized) {
+        return normalized;
+    }
+    if (fallback) {
+        return { Message: fallback };
+    }
+    throw new Error(`${label} 必须是字符串或对象`);
+}
+function omitKeys(value, keys) {
+    if (!value) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !keys.includes(key)));
+}
 function extractLoginStrategyState(value) {
     const source = normalizePlainObject(value, "loginStrategy") ?? {};
     const data = normalizePlainObject(source.Data, "loginStrategy.Data") ?? source;
@@ -7577,13 +8118,154 @@ function extractLoginStrategyState(value) {
     };
 }
 function normalizeLoginConfigPatch(value) {
-    const { PhoneLogin, UsernameLogin, ...rest } = value;
+    const { PhoneLogin, UsernameLogin, usernamePassword, email, anonymous, phone, ...rest } = value;
     return {
         ...rest,
         ...(typeof PhoneLogin === "boolean" ? { PhoneNumberLogin: PhoneLogin } : {}),
         ...(typeof UsernameLogin === "boolean" ? { UserNameLogin: UsernameLogin } : {}),
+        ...(typeof usernamePassword === "boolean" ? { UserNameLogin: usernamePassword } : {}),
+        ...(typeof email === "boolean" ? { EmailLogin: email } : {}),
+        ...(typeof anonymous === "boolean" ? { AnonymousLogin: anonymous } : {}),
+        ...(typeof phone === "boolean" ? { PhoneNumberLogin: phone } : {}),
+    };
+}
+function buildLoginMethods(value) {
+    const state = extractLoginStrategyState(value);
+    return {
+        usernamePassword: Boolean(state.UserNameLogin),
+        email: Boolean(state.EmailLogin),
+        anonymous: Boolean(state.AnonymousLogin),
+        phone: Boolean(state.PhoneNumberLogin),
+    };
+}
+function buildWebSdkHint(loginMethods) {
+    if (!loginMethods.usernamePassword) {
+        return {
+            blocked: true,
+            reason: "plain username-style identifiers require usernamePassword auth",
+            nextStep: 'manageAppAuth({ action: "patchLoginStrategy", patch: { usernamePassword: true } })',
+            accountInputType: "text",
+            avoidEmailHelpers: true,
+        };
+    }
+    return {
+        blocked: false,
+        register: "auth.signUp({ username, password })",
+        login: "auth.signInWithPassword({ username, password })",
+        accountInputType: "text",
+        avoidEmailHelpers: true,
+    };
+}
+function buildLoginConfigNextStep(loginMethods) {
+    if (loginMethods.usernamePassword) {
+        return undefined;
+    }
+    return {
+        tool: "manageAppAuth",
+        action: "patchLoginStrategy",
+        patch: {
+            usernamePassword: true,
+        },
+    };
+}
+function extractProviders(value) {
+    const payload = normalizePlainObject(value, "providersResult");
+    const providers = payload?.Providers ?? payload?.ProviderList ?? payload?.Data ?? [];
+    return Array.isArray(providers) ? providers : [];
+}
+function extractStaticStores(value) {
+    const payload = normalizePlainObject(value, "staticStoreResult");
+    const stores = payload?.Data ?? [];
+    return Array.isArray(stores) ? stores : [];
+}
+function getNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function resolveStaticStoreDomain(store) {
+    return getNonEmptyString(store?.CdnDomain) ?? getNonEmptyString(store?.StaticDomain) ?? null;
+}
+function extractApiKeyList(value) {
+    const payload = normalizePlainObject(value, "apiKeyResult");
+    const items = payload?.ApiKeyList ?? payload?.Data ?? [];
+    return Array.isArray(items) ? items : [];
+}
+function findPublishableKey(value) {
+    const apiKeys = extractApiKeyList(value);
+    return (apiKeys.find((item) => item.Name === "publish_key" ||
+        item.KeyName === "publish_key" ||
+        item.KeyType === "publish_key") ?? null);
+}
+function buildPublishableKeyResponse(envId, record, options) {
+    return {
+        success: true,
+        envId,
+        sdkStyle: "supabase-like",
+        sdkHints: SUPABASE_LIKE_SDK_HINTS,
+        publishableKey: typeof record?.ApiKey === "string" ? record.ApiKey : null,
+        keyId: typeof record?.KeyId === "string" ? record.KeyId : null,
+        keyName: typeof record?.Name === "string"
+            ? record.Name
+            : typeof record?.KeyName === "string"
+                ? record.KeyName
+                : record
+                    ? "publish_key"
+                    : null,
+        expireAt: typeof record?.ExpireAt === "string" ? record.ExpireAt : null,
+        createdAt: typeof record?.CreateAt === "string" ? record.CreateAt : null,
+        ...(typeof options?.created === "boolean" ? { created: options.created } : {}),
+    };
+}
+function buildSupabaseLikeAuthResponse(payload) {
+    return {
+        ...payload,
+        sdkStyle: "supabase-like",
+        sdkHints: SUPABASE_LIKE_SDK_HINTS,
+    };
+}
+function buildClientConfigResponse(envId, clientId, clientConfig) {
+    return {
+        success: true,
+        envId,
+        clientId,
+        clientConfig,
     };
 }
+async function getActiveEnvId(cloudBaseOptions) {
+    try {
+        return await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+    }
+    catch (error) {
+        const payload = (0, tool_result_js_1.isToolPayloadError)(error)
+            ? error.payload
+            : normalizePlainObject(error?.payload, "error.payload");
+        if (payload?.code === "ENV_REQUIRED") {
+            const nextError = new Error("no active environment selected");
+            nextError.code = "ENV_REQUIRED";
+            throw nextError;
+        }
+        if (payload?.code === "AUTH_REQUIRED") {
+            const nextError = new Error("authentication required");
+            nextError.code = "AUTH_REQUIRED";
+            throw nextError;
+        }
+        throw error;
+    }
+}
+function isResourceInUseError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const candidate = error;
+    const code = typeof candidate.code === "string" ? candidate.code : "";
+    const name = typeof candidate.name === "string" ? candidate.name : "";
+    const message = typeof candidate.message === "string" ? candidate.message : "";
+    const haystack = `${code} ${name} ${message}`;
+    return /ResourceInUse/i.test(haystack);
+}
 function registerAppAuthTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions });
@@ -7592,117 +8274,161 @@ function registerAppAuthTools(server) {
             return (0, json_content_js_1.jsonContent)(await handler());
         }
         catch (error) {
+            if (error instanceof Error && (error.message === "no active environment selected" || error.message === "authentication required")) {
+                const code = error.code;
+                if (code) {
+                    return (0, json_content_js_1.jsonContent)(buildShortErrorWithCode(error.message, code));
+                }
+                return (0, json_content_js_1.jsonContent)(buildShortError(error.message));
+            }
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
         }
     };
-    const callControlPlaneAction = async (action, params) => {
-        const cloudbase = await getManager();
-        const service = cloudbase.commonService("tcb", "2018-06-08");
-        const result = await service.call({
-            Action: action,
-            Param: params ?? {},
-        });
-        (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-        return result;
+    const describePublishableKey = async (cloudbase, envId) => {
+        const result = await cloudbase.env.describeApiKeyList({ KeyType: "publish_key", PageNumber: 1, PageSize: 10 });
+        return {
+            result,
+            record: findPublishableKey(result),
+        };
     };
     server.registerTool?.("queryAppAuth", {
         title: "查询应用认证配置",
-        description: "应用侧认证配置只读入口。用于查询登录方式、provider、publishable key、client 配置和静态域名等认证准备状态。",
+        description: "应用侧认证配置只读入口。用于查询登录方式、provider、publishable key、API key、client 配置和静态域名等认证准备状态。若业务要接受普通用户名样式标识符，先查询 action=getLoginConfig；若 usernamePassword=false，下一步应立即调用 manageAppAuth(action=patchLoginStrategy, patch={ usernamePassword: true })，不要直接写 email 登录 API。",
         inputSchema: {
             action: zod_1.z.enum(QUERY_APP_AUTH_ACTIONS),
             providerId: zod_1.z.string().optional().describe("provider 标识，如 email、google"),
+            clientId: zod_1.z
+                .string()
+                .optional()
+                .describe("OAuth client_id / DescribeClient 的 Id；省略时默认使用当前环境 ID（默认客户端）"),
+            keyType: zod_1.z
+                .enum(APP_AUTH_KEY_TYPES)
+                .optional()
+                .describe("API key 类型过滤，可选 publish_key 或 api_key"),
+            pageNumber: zod_1.z.number().int().positive().optional().describe("API key 列表页码，从 1 开始"),
+            pageSize: zod_1.z.number().int().positive().optional().describe("API key 列表每页条数"),
         },
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
             category: "auth",
         },
-    }, async ({ action, providerId, }) => withEnvelope(async () => {
-        const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+    }, async ({ action, providerId, clientId, keyType, pageNumber, pageSize, }) => withEnvelope(async () => {
+        const envId = await getActiveEnvId(cloudBaseOptions);
         const cloudbase = await getManager();
         switch (action) {
             case "getLoginConfig": {
-                // Manager SDK v5 provides a dedicated helper for login config.
-                const result = await cloudbase.env.getLoginConfigListV2();
+                const result = await cloudbase.env.getLoginConfig();
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action,
+                const loginMethods = buildLoginMethods(result);
+                const nextStep = buildLoginConfigNextStep(loginMethods);
+                const webSdkHint = buildWebSdkHint(loginMethods);
+                return buildSupabaseLikeAuthResponse({
+                    success: true,
                     envId,
-                    loginConfig: result,
-                }, "应用登录配置查询成功");
+                    loginMethods,
+                    ...(nextStep ? { next_step: nextStep } : {}),
+                    ...(webSdkHint ? { webSdkHint } : {}),
+                });
             }
             case "listProviders": {
-                const result = await callControlPlaneAction("GetProviders", {
-                    EnvId: envId,
-                });
-                return buildEnvelope({
-                    action,
+                const result = await cloudbase.env.getProviders();
+                return {
+                    success: true,
                     envId,
-                    providers: result.Providers ?? result.ProviderList ?? result.Data ?? result,
-                    raw: result,
-                }, "应用 provider 列表查询成功");
+                    providers: extractProviders(result),
+                };
             }
             case "getProvider": {
                 if (!providerId) {
                     throw new Error("action=getProvider 时必须提供 providerId");
                 }
-                const result = await callControlPlaneAction("GetProviders", {
-                    EnvId: envId,
-                });
-                const providers = (result.Providers ??
-                    result.ProviderList ??
-                    result.Data ??
-                    []);
-                const provider = providers.find((item) => item.Id === providerId || item.id === providerId) ?? null;
-                return buildEnvelope({
-                    action,
+                const result = await cloudbase.env.getProviders();
+                const provider = extractProviders(result).find((item) => item.Id === providerId || item.id === providerId) ?? null;
+                return {
+                    success: true,
                     envId,
                     providerId,
                     provider,
-                    raw: result,
-                }, `应用 provider ${providerId} 查询成功`);
+                };
             }
             case "getClientConfig": {
-                const result = await callControlPlaneAction("DescribeClient", {
-                    EnvId: envId,
-                });
-                return buildEnvelope({
-                    action,
-                    envId,
-                    clientConfig: result,
-                }, "应用 client 配置查询成功");
+                const clientRecordId = clientId ?? envId;
+                const result = await cloudbase.env.describeClient(clientRecordId);
+                return buildClientConfigResponse(envId, clientRecordId, result);
             }
-            case "listApiKeyTokens": {
-                const result = await callControlPlaneAction("DescribeApiKeyTokens", {
-                    EnvId: envId,
+            case "getPublishableKey": {
+                const { record } = await describePublishableKey(cloudbase, envId);
+                return buildPublishableKeyResponse(envId, record);
+            }
+            case "getStaticDomain": {
+                const service = cloudbase.commonService("tcb", "2018-06-08");
+                const result = await service.call({
+                    Action: "DescribeStaticStore",
+                    Param: { EnvId: envId },
                 });
-                return buildEnvelope({
-                    action,
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const stores = extractStaticStores(result);
+                const primaryDomain = resolveStaticStoreDomain(stores[0]);
+                return {
+                    success: true,
                     envId,
-                    apiKeyTokens: result.ApiKeyTokens ?? result.Data ?? result,
-                    raw: result,
-                }, "应用 publishable key 列表查询成功");
+                    cdnDomain: primaryDomain,
+                    staticDomain: primaryDomain,
+                    staticStores: stores,
+                };
             }
-            case "getStaticDomain": {
-                const result = await callControlPlaneAction("DescribeStaticDomain", {
-                    EnvId: envId,
+            case "listApiKeys": {
+                const currentPageNumber = pageNumber ?? 1;
+                const currentPageSize = pageSize ?? 20;
+                const result = await cloudbase.env.describeApiKeyList({
+                    ...(keyType ? { KeyType: keyType } : {}),
+                    PageNumber: currentPageNumber,
+                    PageSize: currentPageSize,
                 });
-                return buildEnvelope({
-                    action,
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const apiKeys = extractApiKeyList(result);
+                return {
+                    success: true,
                     envId,
-                    staticDomain: result,
-                }, "应用静态域名查询成功");
+                    ...(keyType ? { keyType } : {}),
+                    apiKeys,
+                    total: typeof result.Total === "number"
+                        ? result.Total
+                        : apiKeys.length,
+                    pageNumber: currentPageNumber,
+                    pageSize: currentPageSize,
+                };
             }
         }
     }));
     server.registerTool?.("manageAppAuth", {
         title: "管理应用认证配置",
-        description: "应用侧认证配置写入口。用于修改登录方式、provider、client 配置，创建 publishable key 和自定义登录密钥。",
+        description: "应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key，以及创建或删除 API key、自定义登录密钥。若前端要接受普通用户名样式标识符，应先执行 action=patchLoginStrategy 并传入 patch={ usernamePassword: true }，再实现对应前端登录逻辑。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_APP_AUTH_ACTIONS),
-            loginConfig: zod_1.z.record(zod_1.z.any()).optional().describe("updateLoginConfig 使用的登录配置对象"),
-            providerId: zod_1.z.string().optional().describe("provider 标识，如 email、google"),
-            config: zod_1.z.record(zod_1.z.any()).optional().describe("provider / client / api key 的配置对象"),
+            patch: zod_1.z
+                .record(zod_1.z.any())
+                .optional()
+                .describe("patchLoginStrategy 使用的简化登录策略 patch，如 { usernamePassword: true }"),
+            providerId: zod_1.z.string().optional().describe("provider 标识，如 email、google；addProvider 时也可作为自定义 provider Id"),
+            providerType: zod_1.z.string().optional().describe("addProvider 时的 provider 协议类型，如 OAUTH、OIDC、EMAIL"),
+            displayName: zod_1.z
+                .union([zod_1.z.string(), zod_1.z.record(zod_1.z.any())])
+                .optional()
+                .describe("addProvider 时的展示名称，可传字符串或多语言对象"),
+            clientId: zod_1.z
+                .string()
+                .optional()
+                .describe("updateClientConfig 时的客户端 Id；省略时默认使用当前环境 ID"),
+            config: zod_1.z.record(zod_1.z.any()).optional().describe("provider / client 的配置对象"),
+            keyType: zod_1.z
+                .enum(APP_AUTH_KEY_TYPES)
+                .optional()
+                .describe("createApiKey 时的 API key 类型，默认 publish_key"),
+            keyName: zod_1.z.string().optional().describe("createApiKey 时的 API key 名称"),
+            expireIn: zod_1.z.number().int().min(0).optional().describe("createApiKey 时的有效期，单位秒；0 表示不过期"),
+            keyId: zod_1.z.string().optional().describe("deleteApiKey 时的 API key 唯一标识"),
         },
         annotations: {
             readOnlyHint: false,
@@ -7711,86 +8437,165 @@ function registerAppAuthTools(server) {
             openWorldHint: true,
             category: "auth",
         },
-    }, async ({ action, loginConfig, providerId, config, }) => withEnvelope(async () => {
-        const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+    }, async ({ action, patch, providerId, providerType, displayName, clientId, config, keyType, keyName, expireIn, keyId, }) => withEnvelope(async () => {
+        const envId = await getActiveEnvId(cloudBaseOptions);
         const cloudbase = await getManager();
         switch (action) {
-            case "updateLoginConfig": {
-                const normalized = normalizePlainObject(loginConfig, "loginConfig");
+            case "patchLoginStrategy": {
+                const input = normalizePlainObject(patch, "patch");
+                const normalized = input ? normalizeLoginConfigPatch(input) : undefined;
                 if (!normalized) {
-                    throw new Error("action=updateLoginConfig 时必须提供 loginConfig");
+                    throw new Error("action=patchLoginStrategy 时必须提供 patch");
                 }
-                const current = await cloudbase.env.getLoginConfigListV2();
+                const current = await cloudbase.env.getLoginConfig();
                 const merged = {
-                    EnvId: envId,
                     ...extractLoginStrategyState(current),
-                    ...normalizeLoginConfigPatch(normalized),
+                    ...normalized,
                 };
-                // Manager SDK v5 provides a dedicated helper for login config updates.
-                const result = await cloudbase.env.updateLoginConfigV2(merged);
+                const result = await cloudbase.env.modifyLoginConfig(merged);
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action,
+                const confirmed = await cloudbase.env.getLoginConfig();
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, confirmed);
+                const loginMethods = buildLoginMethods(confirmed);
+                const nextStep = buildLoginConfigNextStep(loginMethods);
+                const webSdkHint = buildWebSdkHint(loginMethods);
+                return buildSupabaseLikeAuthResponse({
+                    success: true,
                     envId,
-                    appliedLoginConfig: merged,
-                    raw: result,
-                }, "应用登录配置更新成功");
+                    loginMethods,
+                    ...(nextStep ? { next_step: nextStep } : {}),
+                    ...(webSdkHint ? { webSdkHint } : {}),
+                });
+            }
+            case "addProvider": {
+                const normalized = omitKeys(normalizePlainObject(config, "config"), ["EnvId"]);
+                if (!providerType) {
+                    throw new Error("action=addProvider 时必须提供 providerType");
+                }
+                const localizedDisplayName = normalizeLocalizedMessage(displayName, "displayName", providerId ?? providerType);
+                const result = await cloudbase.env.addProvider({
+                    ...(providerId ? { Id: providerId } : {}),
+                    Name: localizedDisplayName,
+                    ProviderType: providerType,
+                    ...(normalized ? { Config: normalized } : {}),
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const addProviderResult = normalizePlainObject(result, "addProviderResult") ?? {};
+                return {
+                    success: true,
+                    envId,
+                    providerId: providerId ??
+                        (typeof addProviderResult.Id === "string" ? addProviderResult.Id : null),
+                    providerType,
+                };
             }
             case "updateProvider": {
-                const normalized = normalizePlainObject(config, "config");
+                const normalized = omitKeys(normalizePlainObject(config, "config"), ["EnvId", "Id"]);
                 if (!providerId) {
                     throw new Error("action=updateProvider 时必须提供 providerId");
                 }
                 if (!normalized) {
                     throw new Error("action=updateProvider 时必须提供 config");
                 }
-                const result = await callControlPlaneAction("ModifyProvider", {
-                    EnvId: envId,
-                    Id: providerId,
-                    ...normalized,
-                });
-                return buildEnvelope({
-                    action,
+                await cloudbase.env.modifyProvider({ Id: providerId, ...normalized });
+                return {
+                    success: true,
                     envId,
                     providerId,
-                    raw: result,
-                }, `应用 provider ${providerId} 更新成功`);
+                };
+            }
+            case "deleteProvider": {
+                if (!providerId) {
+                    throw new Error("action=deleteProvider 时必须提供 providerId");
+                }
+                const result = await cloudbase.env.deleteProvider(providerId);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                return {
+                    success: true,
+                    envId,
+                    providerId,
+                    deleted: true,
+                };
             }
             case "updateClientConfig": {
-                const normalized = normalizePlainObject(config, "config");
+                const normalized = omitKeys(normalizePlainObject(config, "config"), ["EnvId", "Id"]);
                 if (!normalized) {
                     throw new Error("action=updateClientConfig 时必须提供 config");
                 }
-                const result = await callControlPlaneAction("ModifyClient", {
-                    EnvId: envId,
-                    ...normalized,
+                const clientRecordId = clientId ?? envId;
+                await cloudbase.env.modifyClient({ Id: clientRecordId, ...normalized });
+                const confirmed = await cloudbase.env.describeClient(clientRecordId);
+                return buildClientConfigResponse(envId, clientRecordId, confirmed);
+            }
+            case "ensurePublishableKey": {
+                const existing = await describePublishableKey(cloudbase, envId);
+                if (existing.record) {
+                    return buildPublishableKeyResponse(envId, existing.record, { created: false });
+                }
+                let created;
+                try {
+                    created = await cloudbase.env.createApiKey({ KeyType: "publish_key" });
+                }
+                catch (error) {
+                    if (!isResourceInUseError(error)) {
+                        throw error;
+                    }
+                    const reread = await describePublishableKey(cloudbase, envId);
+                    if (!reread.record) {
+                        throw error;
+                    }
+                    return buildPublishableKeyResponse(envId, reread.record, { created: false });
+                }
+                return buildPublishableKeyResponse(envId, normalizePlainObject(created, "createdApiKey") ?? null, {
+                    created: true,
                 });
-                return buildEnvelope({
-                    action,
-                    envId,
-                    raw: result,
-                }, "应用 client 配置更新成功");
             }
-            case "createApiKeyToken": {
-                const normalized = normalizePlainObject(config, "config");
-                const result = await callControlPlaneAction("CreateApiKeyToken", {
-                    EnvId: envId,
-                    ...(normalized ?? {}),
+            case "createApiKey": {
+                const effectiveKeyType = keyType ?? "publish_key";
+                const result = await cloudbase.env.createApiKey({
+                    KeyType: effectiveKeyType,
+                    ...(keyName ? { KeyName: keyName } : {}),
+                    ...(typeof expireIn === "number" ? { ExpireIn: expireIn } : {}),
                 });
-                return buildEnvelope({
-                    action,
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const createApiKeyResult = normalizePlainObject(result, "createApiKeyResult") ?? {};
+                return {
+                    success: true,
                     envId,
-                    raw: result,
-                }, "应用 publishable key 创建成功");
+                    keyType: effectiveKeyType,
+                    keyId: typeof result.KeyId === "string" ? result.KeyId : null,
+                    keyName: typeof result.Name === "string"
+                        ? result.Name
+                        : typeof createApiKeyResult.KeyName === "string"
+                            ? createApiKeyResult.KeyName
+                            : keyName ?? null,
+                    apiKey: typeof result.ApiKey === "string" ? result.ApiKey : null,
+                    expireAt: typeof result.ExpireAt === "string" ? result.ExpireAt : null,
+                    createdAt: typeof result.CreateAt === "string" ? result.CreateAt : null,
+                };
+            }
+            case "deleteApiKey": {
+                if (!keyId) {
+                    throw new Error("action=deleteApiKey 时必须提供 keyId");
+                }
+                const result = await cloudbase.env.deleteApiKey(keyId);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                return {
+                    success: true,
+                    envId,
+                    keyId,
+                    deleted: true,
+                };
             }
             case "createCustomLoginKeys": {
                 const result = await cloudbase.env.createCustomLoginKeys();
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                return buildEnvelope({
-                    action,
+                return {
+                    success: true,
                     envId,
-                    raw: result,
-                }, "自定义登录密钥创建成功");
+                    privateKey: result.PrivateKey,
+                    keyId: result.KeyID,
+                };
             }
         }
     }));
@@ -7866,7 +8671,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.16.1-beta.1" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.17.0-beta.2" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -8065,7 +8870,7 @@ const reportToolCall = async (params) => {
         toolName: params.toolName,
         success: params.success ? 'true' : 'false',
         requestId: params.requestId,
-        duration: params.duration,
+        duration: params.duration !== undefined ? String(params.duration) : undefined,
         error: params.error ? params.error.substring(0, 200) : undefined, // 限制错误信息长度
         envId: envId || 'unknown',
         nodeVersion,
@@ -8120,8 +8925,8 @@ const reportToolkitLifecycle = async (params) => {
     // 报告 Toolkit 生命周期事件
     const eventData = {
         event: params.event,
-        duration: params.duration,
-        exitCode: params.exitCode,
+        duration: params.duration !== undefined ? String(params.duration) : undefined,
+        exitCode: params.exitCode !== undefined ? String(params.exitCode) : undefined,
         error: params.error ? params.error.substring(0, 200) : undefined, // 限制错误信息长度
         envId: envId || 'unknown',
         nodeVersion,
@@ -9153,11 +9958,11 @@ function registerFunctionTools(server) {
     }, async (input) => withEnvelope(() => handleQueryFunctions(input)));
     server.registerTool?.("manageFunctions", {
         title: "管理云函数域资源",
-        description: "函数域统一写入口。通过 action 管理函数创建、代码更新、配置更新、触发器和层绑定。危险操作需要显式 confirm=true。",
+        description: "函数域统一写入口。通过 action 管理函数创建、代码更新、配置更新、调用函数、触发器和层绑定。危险操作需要显式 confirm=true。",
         inputSchema: {
             action: zod_1.z
                 .enum(exports.MANAGE_FUNCTION_ACTIONS)
-                .describe("写操作类型，例如 createFunction、updateFunctionCode、attachLayer"),
+                .describe("写操作类型，例如 createFunction、invokeFunction、attachLayer"),
             func: CREATE_FUNCTION_SCHEMA.optional().describe("createFunction 操作的函数配置"),
             functionRootPath: zod_1.z.string().optional().describe("函数根目录（父目录绝对路径）"),
             force: zod_1.z.boolean().optional().describe("createFunction 时是否覆盖"),
@@ -9234,6 +10039,12 @@ const MANAGE_PERMISSION_ACTIONS = [
     "updateUser",
     "deleteUsers",
 ];
+function buildWriteVerificationHint(resourceId) {
+    return `对于 ${resourceId} 这类有后端权限控制的集合，前端调用 .doc(id).update() / .doc(id).remove() 后，不能只看是否没有抛异常。请显式检查返回结果中的 updated / deleted 是否大于 0；如果 result.code、result.message 存在，或 updated / deleted 为 0，要把它当作真实失败并向上抛错。`;
+}
+function buildPermissionPropagationHint(resourceId) {
+    return `刚更新完 ${resourceId} 的安全规则时，后端权限可能需要一小段传播时间。若紧接着的真实写操作仍返回 DATABASE_PERMISSION_DENIED，请先等待一小段时间，再用同一登录态重试同一条 .doc(id).update() / .doc(id).remove()；不要立刻连续重写规则，也不要在传播窗口里把旧拒绝直接当成规则表达式仍然错误。`;
+}
 function buildEnvelope(data, message) {
     return {
         success: true,
@@ -9266,6 +10077,142 @@ function normalizeRecordArray(value, label) {
     }
     return value;
 }
+function extractRiskyDocFieldOperations(securityRule) {
+    if (!securityRule) {
+        return [];
+    }
+    const operations = [];
+    const operationPatterns = [
+        ["update", /"update"\s*:\s*"([^"]*)"/],
+        ["delete", /"delete"\s*:\s*"([^"]*)"/],
+    ];
+    for (const [operation, pattern] of operationPatterns) {
+        const match = securityRule.match(pattern);
+        const expression = match?.[1];
+        if (!expression) {
+            continue;
+        }
+        const referencesNonIdDocField = /doc\.(?!_id\b)[A-Za-z_][A-Za-z0-9_]*/.test(expression);
+        const usesGetByDocId = /get\('database\.[^']+'\s*\+\s*doc\._id\)/.test(expression);
+        if (referencesNonIdDocField && !usesGetByDocId) {
+            operations.push(operation);
+        }
+    }
+    return operations;
+}
+function buildRecommendedOwnerWriteRule(resourceId) {
+    return JSON.stringify({
+        create: "auth.uid != null",
+        update: "auth.uid != null && (get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid)",
+        delete: "auth.uid != null && (get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid)",
+    });
+}
+function buildRoleLookupNote() {
+    return "如果你需要 app-level admin override（例如 CMS 中 admin 可编辑所有文章，而 editor 只能编辑自己的文章），CUSTOM 规则通常是必要的。一个已验证可用的模式是：角色集合文档主键就是 auth.uid，并在文章权限里写 get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid。若现有 schema 已经有 users / profiles / user_roles 其一，请复用已存在且能通过 _id == auth.uid 直接 get() 到的那一份；不要把 where({ uid }) 查询得到的集合误写成 get('database.users.' + auth.uid)。";
+}
+function buildRecommendedClientWritePattern(resourceId) {
+    return `对于 CMS 文章这类使用 app-level admin override 的 CUSTOM 规则，前端可继续使用 db.collection('${resourceId}').doc(id).update(...) / remove(...)。关键是安全规则要采用已验证模式：get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid，并且文章文档中要真实写入 authorId。`;
+}
+function buildCreateRuleHint(securityRule, resourceId) {
+    if (!securityRule) {
+        return undefined;
+    }
+    const createMatch = securityRule.match(/"create"\s*:\s*"([^"]*)"/);
+    const writeMatch = securityRule.match(/"write"\s*:\s*"([^"]*)"/);
+    const createExpression = createMatch?.[1];
+    const writeExpression = writeMatch?.[1];
+    if (!createExpression && !writeExpression) {
+        return undefined;
+    }
+    const referencesDoc = (createExpression && /doc\.[A-Za-z_]/.test(createExpression)) ||
+        (writeExpression && /doc\.[A-Za-z_]/.test(writeExpression));
+    if (!referencesDoc) {
+        return undefined;
+    }
+    return {
+        type: "createRuleDocWarning",
+        severity: "warning",
+        summary: "create 规则不应引用 doc.*，因为 create 时文档尚未存在。",
+        detail: "CloudBase 的 create 规则验证的是写入数据（request.data），此时文档尚不存在，doc.* 不可用。" +
+            "请将 create 规则改为仅使用 auth.* 检查（如 auth.uid != null && auth.loginType != 'ANONYMOUS'），" +
+            "或在写入时将 owner 字段（如 _openid / authorId）写入 request.data，然后在 create 规则中用 request.data._openid == auth.openid 做校验。" +
+            "read / update / delete 规则可以使用 doc.* 引用已有文档字段，且客户端查询条件必须是规则约束的子集（如 _openid: '{openid}'）。",
+        recommendedRulePattern: "auth.uid != null && auth.loginType != 'ANONYMOUS'",
+        recommendedPermission: "CUSTOM",
+        recommendedSecurityRule: JSON.stringify({
+            read: "auth.uid != null && auth.loginType != 'ANONYMOUS'",
+            create: "auth.uid != null && auth.loginType != 'ANONYMOUS'",
+            update: "auth.uid != null && auth.loginType != 'ANONYMOUS' && doc._openid == auth.openid",
+            delete: "auth.uid != null && auth.loginType != 'ANONYMOUS' && doc._openid == auth.openid",
+        }),
+    };
+}
+function buildDocIdWriteRuleHint(securityRule, resourceId) {
+    const appliesTo = extractRiskyDocFieldOperations(securityRule);
+    if (!appliesTo.length) {
+        return undefined;
+    }
+    return {
+        type: "docIdWriteRuleWarning",
+        severity: "warning",
+        appliesTo,
+        summary: "当前安全规则在 document-id 写入场景下可能被后端直接拒绝。",
+        detail: "这类规则经常在 owner-only 集合里被写错，但对于 CMS 文章这种“admin 可编辑所有文章、editor 只能编辑自己的文章”的场景，已验证可用的做法是保留 doc.authorId，并通过独立角色集合做 admin override：get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid。不要默认改成 where(...)，也不要把同集合 owner 判断重写成 get('database.collection.' + doc._id)。",
+        recommendedRulePattern: "doc.authorId == auth.uid",
+        recommendedPermission: "CUSTOM",
+        recommendedSecurityRule: buildRecommendedOwnerWriteRule(resourceId),
+        recommendedClientWritePattern: buildRecommendedClientWritePattern(resourceId),
+        roleLookupNote: buildRoleLookupNote(),
+    };
+}
+function buildInvalidGetPathHint(securityRule, resourceId) {
+    if (!securityRule) {
+        return undefined;
+    }
+    const hasFieldEmbeddedInsideGetPath = /get\('database\.[^']+'\s*\+\s*[^)]*\+\s*'\.[A-Za-z_][A-Za-z0-9_]*'\)/.test(securityRule);
+    if (!hasFieldEmbeddedInsideGetPath) {
+        return undefined;
+    }
+    return {
+        type: "invalidGetPathWarning",
+        severity: "warning",
+        summary: "get() 的 path 只应包含 collection 和 documentId，不应把字段名拼进 path 字符串。",
+        detail: "请写成 get('database.collection.' + doc._id).fieldName，而不是 get('database.collection.' + doc._id + '.fieldName')。但在 CMS 文章权限里，不要把 get('database.collection.' + doc._id) 当成默认首选方案；更稳的已验证模式是读取单独的角色集合：get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid。",
+        recommendedRulePattern: "doc.authorId == auth.uid",
+        recommendedPermission: "CUSTOM",
+        recommendedSecurityRule: buildRecommendedOwnerWriteRule(resourceId),
+        recommendedClientWritePattern: buildRecommendedClientWritePattern(resourceId),
+        roleLookupNote: buildRoleLookupNote(),
+    };
+}
+function buildTemplateLiteralRuleHint(securityRule, resourceId) {
+    if (!securityRule) {
+        return undefined;
+    }
+    const usesTemplateLiteralPlaceholderInRule = /\$\{(?:auth\.uid|doc\._id|doc\.[A-Za-z_][A-Za-z0-9_]*)\}/.test(securityRule);
+    if (!usesTemplateLiteralPlaceholderInRule) {
+        return undefined;
+    }
+    return {
+        type: "templateLiteralRuleWarning",
+        severity: "warning",
+        summary: "CloudBase security rule 表达式不支持把 ${...} 当作 JS 模板字符串插值。",
+        detail: "在 securityRule 字符串里，请使用表达式拼接，例如 get('database.user_roles.' + auth.uid).role，而不是 get('database.user_roles.${auth.uid}').role。对于 CMS 文章这类需要 app-level admin override 的规则，请优先使用已验证的 user_roles + doc.authorId 模式。",
+        recommendedRulePattern: "doc.authorId == auth.uid",
+        recommendedPermission: "CUSTOM",
+        recommendedSecurityRule: buildRecommendedOwnerWriteRule(resourceId),
+        recommendedClientWritePattern: buildRecommendedClientWritePattern(resourceId),
+        roleLookupNote: buildRoleLookupNote(),
+    };
+}
+function buildPermissionHints(securityRule, resourceId) {
+    return [
+        buildCreateRuleHint(securityRule, resourceId),
+        buildDocIdWriteRuleHint(securityRule, resourceId),
+        buildInvalidGetPathHint(securityRule, resourceId),
+        buildTemplateLiteralRuleHint(securityRule, resourceId),
+    ].filter(Boolean);
+}
 function registerPermissionTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions });
@@ -9313,12 +10260,17 @@ function registerPermissionTools(server) {
                     resources: [resourceId],
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const permissions = result.Data.PermissionList ?? [];
+                const securityRule = permissions.find((item) => item.Resource === resourceId)?.SecurityRule ??
+                    permissions[0]?.SecurityRule;
+                const hints = buildPermissionHints(securityRule, resourceId);
                 return buildEnvelope({
                     action,
                     envId,
                     resourceType,
                     resourceId,
-                    permissions: result.Data.PermissionList ?? [],
+                    permissions,
+                    hints,
                     raw: result,
                 }, "资源权限查询成功");
             }
@@ -9331,11 +10283,22 @@ function registerPermissionTools(server) {
                     resources: resourceIds,
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const permissions = result.Data.PermissionList ?? [];
+                const resourceHints = permissions
+                    .map((item) => ({
+                    resourceId: item.Resource ?? "",
+                    permission: item.Permission,
+                    hints: item.Permission === "CUSTOM" && item.Resource
+                        ? buildPermissionHints(item.SecurityRule, item.Resource)
+                        : [],
+                }))
+                    .filter((item) => item.resourceId && item.hints.length > 0);
                 return buildEnvelope({
                     action,
                     envId,
                     resourceType,
-                    permissions: result.Data.PermissionList ?? [],
+                    permissions,
+                    resourceHints,
                     total: result.Data.TotalCount ?? 0,
                     raw: result,
                 }, "资源权限列表查询成功");
@@ -9417,17 +10380,24 @@ function registerPermissionTools(server) {
     }));
     server.registerTool?.("managePermissions", {
         title: "管理权限与用户配置",
-        description: "权限域统一写入口。支持修改资源权限、角色管理、成员与策略增删、应用用户 CRUD。",
+        description: "权限域统一写入口。支持修改资源权限、角色管理、成员与策略增删、应用用户 CRUD。`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。注意：`securityRule` 的详细语义取决于 `resourceType`；`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则。配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_PERMISSION_ACTIONS),
             resourceType: zod_1.z
                 .enum(["noSqlDatabase", "sqlDatabase", "function", "storage"])
-                .optional(),
+                .optional()
+                .describe("目标资源类型。`securityRule` 的具体语义依赖这个值；`noSqlDatabase` 使用集合安全规则，`function` 与 `storage` 也有各自独立的安全规则语义，不要套用 NoSQL 规则语法。"),
             resourceId: zod_1.z.string().optional(),
             permission: zod_1.z
                 .enum(["READONLY", "PRIVATE", "ADMINWRITE", "ADMINONLY", "CUSTOM"])
                 .optional(),
-            securityRule: zod_1.z.string().optional(),
+            securityRule: zod_1.z
+                .string()
+                .optional()
+                .describe("资源类型特定的规则内容，详细语义依赖 `resourceType`。当 `resourceType=\"noSqlDatabase\"` 且 `permission=\"CUSTOM\"` 时，应传文档数据库安全规则 JSON（文档型数据库规则：`https://docs.cloudbase.net/database/security-rules`）；键通常为 `read` / `create` / `update` / `delete`，值为表达式。" +
+                "重要：`create` 规则验证写入数据，此时文档尚不存在，不能使用 `doc.*`；`read` / `update` / `delete` 规则可使用 `doc.*` 引用已有文档字段。" +
+                "不要把 `doc._openid`、`auth.openid`、查询条件子集校验或 `create` / `update` / `delete` 模板误用于 `function`、`storage` 或 `sqlDatabase`。" +
+                '如需配置 `function` 或 `storage`，请改查官方安全规则文档：云函数 `https://docs.cloudbase.net/cloud-function/security-rules`，云存储 `https://docs.cloudbase.net/storage/security-rules`。示例：{"read":"auth.uid != null","create":"auth.uid != null && auth.loginType != "ANONYMOUS"","update":"auth.uid != null && doc._openid == auth.openid","delete":"auth.uid != null && doc._openid == auth.openid"}'),
             roleId: zod_1.z.string().optional(),
             roleIds: zod_1.z.array(zod_1.z.string()).optional(),
             roleName: zod_1.z.string().optional(),
@@ -9464,12 +10434,20 @@ function registerPermissionTools(server) {
                     securityRule,
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const hints = permission === "CUSTOM" ? buildPermissionHints(securityRule, resourceId) : [];
                 return buildEnvelope({
                     action,
                     envId,
                     resourceType,
                     resourceId,
                     permission,
+                    hints,
+                    verificationHint: resourceType === "noSqlDatabase" && permission === "CUSTOM"
+                        ? buildWriteVerificationHint(resourceId)
+                        : undefined,
+                    propagationHint: resourceType === "noSqlDatabase" && permission === "CUSTOM"
+                        ? buildPermissionPropagationHint(resourceId)
+                        : undefined,
                     raw: result,
                 }, "资源权限更新成功");
             }
@@ -10062,7 +11040,7 @@ function registerSetupTools(server) {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。⚠️ **MANDATORY FOR NEW PROJECTS** ⚠️
 
-**CRITICAL**: This tool MUST be called FIRST when starting a new project.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.16.1-beta.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**CRITICAL**: This tool MUST be called FIRST when starting a new project.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.17.0-beta.2" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -11016,7 +11994,7 @@ function registerHostingTools(server) {
     // uploadFiles - 上传文件到静态网站托管 (cloud-incompatible)
     server.registerTool("uploadFiles", {
         title: "上传静态文件",
-        description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。",
+        description: "上传文件到静态网站托管，仅用于 Web 站点部署，不用于云存储对象上传。部署前请先完成构建；如果站点会部署到子路径，请检查构建配置中的 publicPath、base、assetPrefix 等是否使用相对路径，避免静态资源加载失败。若需要上传 COS 云存储文件，请使用 manageStorage。对于本地评测、现有脚手架补全或仅需本地开发服务器验证的任务，通常不需要调用此工具，除非用户明确要求部署站点。",
         inputSchema: {
             localPath: zod_1.z.string().optional().describe("本地文件或文件夹路径，需要是绝对路径，例如 /tmp/files/data.txt。"),
             cloudPath: zod_1.z.string().optional().describe("静态托管云端文件或文件夹路径，例如 files/data.txt。若部署到子路径，请同时检查构建配置中的 publicPath、base、assetPrefix 等是否为相对路径。云存储对象路径请改用 manageStorage。"),
@@ -11612,24 +12590,30 @@ alwaysApply: true
 **⚠️ CRITICAL: Read this section first based on your project type**
 
 ### When Developing a Web Project:
-1. **Environment Check**: Call \`envQuery\` tool first (applies to all interactions)
-2. **⚠️ Template Download (MANDATORY for New Projects)**: **MUST call \`downloadTemplate\` tool FIRST when starting a new project** - Do NOT create files manually. Use \`downloadTemplate\` with \`template="react"\` or \`template="vue"\` to get the complete project structure. Only proceed with manual file creation if template download fails or user explicitly requests it.
+1. **Environment Check**: Query environment info only when the task actually needs environment metadata, deployment, or an env ID. For existing applications with active TODOs or unfinished handlers, do not spend turns on hosting or domain queries unless the user explicitly asks for deployment.
+1. **Execution Mode for Existing-Code Tasks**: If the task is to complete an existing application, wire TODO logic, or repair a broken flow, do **not** enter design-only, brainstorming-only, or spec-only flows first. Gather only the minimum context needed, then implement directly. Do not stop after “project exploration complete”.
+1. **Existing File Focus (MANDATORY)**: For an existing Web app with active pages or TODO-bearing files, do not broad-scan the whole repo before coding. First inspect only the task-critical files: \`src/lib/backend.*\`, \`src/lib/auth.*\`, \`src/lib/cms-service.*\`, \`src/lib/storage-service.*\`, and the page/components that already consume those APIs. Then implement those TODOs before doing any wide repo exploration.
+1. **Task Tool Discipline**: For targeted repair tasks, do not spend many turns in \`TaskCreate\`, \`TaskUpdate\`, or project-management loops. At most keep one short checklist. After that, write code. Do not let task-management consume the turn budget.
+1. **No README / UI-Design Detour For Existing Apps**: If the repo already contains the target pages and only backend TODOs are missing, skip README-driven discovery and skip UI-design workflows unless the task explicitly asks for a visual redesign. Backend wiring is the priority.
+1. **No Broad Grep / Glob Sweep**: In targeted repair tasks, do not recursively Grep / Glob the whole repo for long periods. Open the known TODO-bearing files directly and start editing.
 3. **⚠️ UI Design (CRITICAL)**: **MUST read \`rules/ui-design/rule.md\` FIRST before generating any page, interface, component, or style** - This is NOT optional. You MUST explicitly read this file and output the design specification before writing any UI code.
 4. **Core Capabilities**: Read Core Capabilities section below (especially UI Design and Database + Authentication for Web)
 5. **Platform Rules**: Read \`rules/web-development/rule.md\` for platform-specific rules (SDK integration, static hosting, build configuration)
 6. **Authentication**: Read \`rules/auth-web/rule.md\` - **MUST use Web SDK built-in authentication**
+   - \`accessKey\` can only be a real Publishable Key obtained from CloudBase auth/app config. Never use \`envId\`, a username, or any placeholder string as \`accessKey\`.
+   - If you do not have a real Publishable Key yet, do not fabricate one. First query or configure auth readiness, or initialize without \`accessKey\` if the login flow itself is what will establish end-user identity.
+7. **Cloud Storage (when files are uploaded from browser code)**: Read \`rules/cloud-storage-web/rule.md\` before implementing upload / preview / temp URL flows. For local dev origins (for example Vite on \`127.0.0.1\` / \`localhost\`), query current security domains first and compare against the returned whitelist entry format (usually \`host:port\`, such as \`127.0.0.1:4173\` or \`localhost:5173\`). If \`envQuery(action="domains")\` reports missing local entries or returns a \`next_step\`, execute that \`envDomainManagement\` step before relying on \`app.uploadFile()\`. After upload, do not handcraft a storage URL from \`envId\`, bucket domain, or \`cloudPath\`; resolve an actual browser-usable URL through \`app.getTempFileURL()\` using the returned \`fileID\`.
 7. **Database**: 
    - NoSQL: \`rules/no-sql-web-sdk/rule.md\`
    - MySQL: \`rules/relational-database-web/rule.md\` + \`rules/relational-database-mcp/rule.md\`
 
 ### When Developing a Mini Program Project:
 1. **Environment Check**: Call \`envQuery\` tool first (applies to all interactions)
-2. **⚠️ Template Download (MANDATORY for New Projects)**: **MUST call \`downloadTemplate\` tool FIRST when starting a new project** - Do NOT create files manually. Use \`downloadTemplate\` with \`template="miniprogram"\` to get the complete project structure. Only proceed with manual file creation if template download fails or user explicitly requests it.
-3. **⚠️ UI Design (CRITICAL)**: **MUST read \`rules/ui-design/rule.md\` FIRST before generating any page, interface, component, or style** - This is NOT optional. You MUST explicitly read this file and output the design specification before writing any UI code.
-4. **Core Capabilities**: Read Core Capabilities section below (especially UI Design and Database + Authentication for Mini Program)
-5. **Platform Rules**: Read \`rules/miniprogram-development/rule.md\` for platform-specific rules (project structure, WeChat Developer Tools, wx.cloud usage)
-6. **Authentication**: Read \`rules/auth-wechat/rule.md\` - **Naturally login-free, get OPENID in cloud functions**
-7. **Database**: 
+2. **⚠️ UI Design (CRITICAL)**: **MUST read \`rules/ui-design/rule.md\` FIRST before generating any page, interface, component, or style** - This is NOT optional. You MUST explicitly read this file and output the design specification before writing any UI code.
+3. **Core Capabilities**: Read Core Capabilities section below (especially UI Design and Database + Authentication for Mini Program)
+4. **Platform Rules**: Read \`rules/miniprogram-development/rule.md\` for platform-specific rules (project structure, WeChat Developer Tools, wx.cloud usage)
+5. **Authentication**: Read \`rules/auth-wechat/rule.md\` - **Naturally login-free, get OPENID in cloud functions**
+6. **Database**: 
    - NoSQL: \`rules/no-sql-wx-mp-sdk/rule.md\`
    - MySQL: \`rules/relational-database-mcp/rule.md\` (via MCP tools)
 
@@ -11670,6 +12654,10 @@ As the most important part of application development, the following four core c
 **Authentication**:
 - **Web Projects**: 
   - Must use CloudBase Web SDK built-in authentication, refer to \`rules/auth-web/rule.md\`
+  - For username-style accounts, use \`auth.signUp({ username, password })\` and \`auth.signInWithPassword({ username, password })\`
+  - Do not use email-only helpers or email-only input semantics when the account identifier is a plain username string
+  - When an existing schema or fixture already provides role/profile metadata in \`users\`, \`profiles\`, or \`user_roles\`, reuse that collection instead of inventing yet another one. In role-based content-management flows, a \`user_roles\` collection keyed by \`uid\` is an acceptable and validated pattern.
+  - For browser-side file upload / preview flows, read \`rules/cloud-storage-web/rule.md\`; on local dev origins, verify the required local host entries (for example \`127.0.0.1:4173\`, \`localhost:5173\`) are already in the environment security-domain whitelist before depending on \`app.uploadFile()\`. If \`envQuery(action="domains")\` returns missing local entries or a \`next_step\`, execute that \`envDomainManagement\` action first. After upload, use \`app.getTempFileURL()\` to resolve the preview/download URL instead of constructing a URL string manually.
   - Platform development rules: Refer to \`rules/web-development/rule.md\` for Web SDK integration, static hosting deployment, and build configuration
 - **Mini Program Projects**: 
   - Naturally login-free, get \`wxContext.OPENID\` in cloud functions, refer to \`rules/auth-wechat/rule.md\`
@@ -11679,6 +12667,9 @@ As the most important part of application development, the following four core c
 **Database Operations**:
 - **Web Projects**:
   - NoSQL Database: Refer to \`rules/no-sql-web-sdk/rule.md\`
+  - For content collections that only need owner-only writes, simple permissions such as \`READONLY\` can be a good fit. But for CMS-style collections that require **app-level admin users** to edit/delete any record while editors can only edit/delete their own records, a \`CUSTOM\` rule is expected.
+  - A validated CMS article rule shape is: \`{"read":"auth.uid != null","create":"auth.uid != null","update":"auth.uid != null && (get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid)","delete":"auth.uid != null && (get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid)"}\`.
+  - For that CMS pattern, frontend writes can stay on \`.doc(id).update()\` / \`.doc(id).remove()\`. Do not force a \`where(...)\` rewrite unless the task explicitly requires a different rule design.
   - MySQL Relational Database: Refer to \`rules/relational-database-web/rule.md\` (Web application development) and \`rules/relational-database-mcp/rule.md\` (Management via MCP tools)
   - Platform development rules: Refer to \`rules/web-development/rule.md\` for Web SDK database integration patterns
 - **Mini Program Projects**:
@@ -11692,6 +12683,7 @@ As the most important part of application development, the following four core c
 - Use CloudBase static hosting after build completion
 - Deploy using \`uploadFiles\` tool
 - \`uploadFiles\` is only for static hosting deployment; do not use it for COS / cloud storage uploads. For storage objects, use \`manageStorage(action="upload")\`
+- If the task is local verification or an unfinished application repair with a dev server workflow, skip static hosting deployment unless the user explicitly asks for a deployed URL
 - Remind users that CDN has a few minutes of cache after deployment
 - Generate markdown format access links with random queryString
 
@@ -11710,7 +12702,7 @@ As the most important part of application development, the following four core c
 ### 0. Environment Check (First Step)
 After user inputs any content, first check CloudBase environment status:
 - Ensure current CloudBase environment ID is known
-- If not present in conversation history, must call \`envQuery\` tool with parameter \`action=info\` to query current environment information and environment ID
+- If not present in conversation history and the task needs env metadata or deployment, call \`envQuery\` tool with parameter \`action=info\` to query current environment information and environment ID
 - **Important**: When environment ID configuration is involved in code later, automatically use the queried environment ID, no need for manual user input
 
 ### 1. Scenario Identification
@@ -11750,31 +12742,33 @@ Before starting work, suggest confirming with user:
 3. "Please confirm if my understanding is correct"
 
 ## Core Behavior Rules
+0. **Existing-Code Completion Bias**: For existing applications with TODOs or broken flows, implementation is the goal. Do not hand off to a design-only phase, do not stop at exploration, and do not treat a summary of findings as task completion. After minimal context gathering, write code and wire the real backend flow.
+0. **No Broad Exploration For TODO Apps**: When the repo already exposes TODO markers in backend integration files, do not keep globbing, summarizing, or reading unrelated files. Open the TODO-bearing files and implement them.
+0. **No Task-Loop Derailment**: In targeted repair tasks, avoid repeated \`TaskCreate\` / \`TaskUpdate\` cycles. One minimal checklist is enough; the rest of the budget should go to file edits, tool calls, and verification.
+0. **Do Not Delegate Or Defer**: In targeted repair tasks, do not invoke design copilots, brainstorming helpers, or delegated agent flows before the core TODO files are implemented. Finish the direct file edits first.
 1. **Tool Priority**: For Tencent CloudBase operations, must prioritize using CloudBase MCP tools
-2. **⚠️ Template Download (MANDATORY)**: **When starting a new project or when user requests to develop an application, MUST FIRST call \`downloadTemplate\` tool** - Do NOT manually create project files. Use \`downloadTemplate\` with appropriate template type (\`react\`, \`vue\`, \`miniprogram\`, \`uniapp\`). Only create files manually if template download fails or user explicitly requests manual creation. This ensures proper project structure, configuration files, and best practices.
-3. **Project Understanding**: First read current project's README.md, follow project instructions for development
+2. **Project Understanding**: First read current project's README.md, follow project instructions for development. Exception: for existing applications where the missing work is clearly in known backend integration files, skip README-first and go straight to those files.
 4. **Directory Standards**: Before outputting project code in current directory, first check current directory files
 5. **Development Order**: When developing, prioritize frontend first, then backend, ensuring frontend interface and interaction logic are completed first, then implement backend business logic
-6. **⚠️ UI Design Rules Mandatory Application**: When tasks involve generating pages, interfaces, components, styles, or any frontend visual elements, **MUST FIRST explicitly read the file \`rules/ui-design/rule.md\` using file reading tools**, then strictly follow the rule file, ensuring generated interfaces have distinctive aesthetic styles and high-quality visual design, avoiding generic AI aesthetics. **You MUST output the design specification before writing any UI code.**
+6. **⚠️ UI Design Rules Mandatory Application**: When tasks involve generating pages, interfaces, components, styles, or any frontend visual elements, **MUST FIRST explicitly read the file \`rules/ui-design/rule.md\` using file reading tools**, then strictly follow the rule file, ensuring generated interfaces have distinctive aesthetic styles and high-quality visual design, avoiding generic AI aesthetics. **You MUST output the design specification before writing any UI code.** Exception: for existing applications where page structure is already fixed and only backend integration is missing, do not trigger the UI-design workflow.
 7. **Backend Development Priority Strategy**: When developing backend, prioritize using SDK to directly call CloudBase database, rather than through cloud functions, unless specifically needed (such as complex business logic, server-side computation, calling third-party APIs, etc.)
 8. **Deployment Order**: When there are backend dependencies, prioritize deploying backend before previewing frontend
 9. **Interactive Confirmation**: Clarify requirements when needed, and confirm before executing high-risk operations
 10. **Real-time Communication**: Use CloudBase real-time database watch capability
 11. **⚠️ Authentication Rules**: When users develop projects, if user login authentication is needed, must use built-in authentication functions, must strictly distinguish authentication methods by platform
    - **Web Projects**: **MUST use CloudBase Web SDK built-in authentication** (e.g., \`auth.toDefaultLoginPage()\`), refer to \`rules/auth-web/rule.md\`
+   - **Username-style Web accounts**: Use \`auth.signUp({ username, password })\` for registration and \`auth.signInWithPassword({ username, password })\` for login. Do not use \`signInWithEmailAndPassword\` / \`signUpWithEmailAndPassword\` when the identifier is not an email address.
+   - **Web initialization**: Only set \`accessKey\` when you have a real Publishable Key. Never set \`accessKey: envId\` or any made-up string.
    - **Mini Program Projects**: **Naturally login-free**, get \`wxContext.OPENID\` in cloud functions, refer to \`rules/auth-wechat/rule.md\`
 
 ## Development Workflow
 
 ### Development
 
-1. **⚠️ Download CloudBase Templates (MANDATORY for New Projects)**: 
-   - **MUST call \`downloadTemplate\` tool FIRST when starting a new project** - Do NOT manually create project files
-   - For Web projects: Use \`downloadTemplate\` with \`template="react"\` or \`template="vue"\`
-   - For Mini Program projects: Use \`downloadTemplate\` with \`template="miniprogram"\`
-   - For UniApp projects: Use \`downloadTemplate\` with \`template="uniapp"\`
-   - **Only proceed with manual file creation if template download fails or user explicitly requests manual creation**
-   - If unable to download to current directory, can use scripts to copy, note that hidden files also need to be copied
+1. **Project Bootstrap Discipline**: 
+   - Prefer the existing project structure and scripts when they already exist
+   - For new projects, keep the initial structure consistent and avoid mixing unrelated frameworks in one workspace
+   - If you bootstrap or copy an existing starter manually, hidden files and project config must be carried over as well
 
 2. **⚠️ UI Design Document Reading (MANDATORY)**: 
    - **Before generating ANY page, interface, component, or style, MUST FIRST explicitly read the file \`rules/ui-design/rule.md\` using file reading tools**
@@ -11802,7 +12796,7 @@ If remote links are needed in the application, can continue to call uploadFile t
 
 2. **CloudRun Deployment Process**: For non-cloud function backend services (Java, Go, PHP, Python, Node.js, etc.), use manageCloudRun tool for deployment. Ensure backend code supports CORS, prepare Dockerfile, then call manageCloudRun for containerized deployment. For details, refer to \`rules/cloudrun-development/rule.md\`
 
-3. **Static Hosting Deployment Process**: Deploy using uploadFiles tool for static hosting only. If the task needs a COS object that must be queried or polled with the storage SDK, use \`manageStorage\` / \`queryStorage\` instead. After deployment, remind users that CDN has a few minutes of cache. Can generate markdown format access links with random queryString. For details, refer to \`rules/web-development/rule.md\`
+3. **Static Hosting Deployment Process**: Deploy using uploadFiles tool for static hosting only. If the task needs a COS object that must be queried or polled with the storage SDK, use \`manageStorage\` / \`queryStorage\` instead. For local verification or unfinished application repairs, do not deploy hosting unless the user explicitly asks for deployment. After deployment, remind users that CDN has a few minutes of cache. Can generate markdown format access links with random queryString. For details, refer to \`rules/web-development/rule.md\`
 
 ### Documentation Generation Rules
 
@@ -11861,8 +12855,7 @@ To ensure development quality, recommend completing the following checks before
 
 ### Recommended Steps
 0. **[ ] Environment Check**: Call \`envQuery\` tool to check CloudBase environment status (applies to all interactions)
-1. **[ ] Template Download Check (MANDATORY for New Projects)**: If starting a new project, have you called \`downloadTemplate\` tool FIRST? Do NOT manually create project files - use templates.
-2. **[ ] Scenario Identification**: Clearly identify what type of project this is (Web/Mini Program/Database/UI)
+1. **[ ] Scenario Identification**: Clearly identify what type of project this is (Web/Mini Program/Database/UI)
 3. **[ ] Core Capability Confirmation**: Confirm all four core capabilities have been considered
    - UI Design: Have you explicitly read the file \`rules/ui-design/rule.md\` using file reading tools?
    - Database + Authentication: Have you referred to corresponding authentication and database skills?
@@ -11876,7 +12869,6 @@ To ensure development quality, recommend completing the following checks before
 6. **[ ] Rule Execution**: Strictly follow core capability requirements and relevant rule files for development
 
 ### ⚠️ Common Issues to Avoid
-- **❌ DO NOT manually create project files** - Always use \`downloadTemplate\` tool first for new projects
 - **❌ DO NOT skip reading UI design document** - Must explicitly read \`rules/ui-design/rule.md\` file before generating any UI code
 - Avoid skipping core capabilities and starting development directly
 - Avoid mixing APIs and authentication methods from different platforms
@@ -12969,17 +13961,34 @@ async function handleRunQuery(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        ReadOnly: true,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            ReadOnly: true,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running queries.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before querying data.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
         success: true,
@@ -13230,16 +14239,33 @@ async function handleRunStatement(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running statements.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const statementType = getSqlVerb(args.sql) || "UNKNOWN";
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
@@ -13339,16 +14365,33 @@ async function handleInitializeSchema(args, context) {
     const requestIdList = [];
     for (const statement of args.statements) {
         try {
-            const result = await callSqlControlPlane(cloudbase, "RunSql", {
-                EnvId: dbContext.envId,
-                Sql: statement,
-                DbInstance: {
+            let result;
+            try {
+                result = await callSqlControlPlane(cloudbase, "RunSql", {
                     EnvId: dbContext.envId,
-                    InstanceId: dbContext.instanceId,
-                    Schema: dbContext.schema,
-                },
-            });
-            (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+                    Sql: statement,
+                    DbInstance: {
+                        EnvId: dbContext.envId,
+                        InstanceId: dbContext.instanceId,
+                        Schema: dbContext.schema,
+                    },
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            }
+            catch (error) {
+                const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+                if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+                    return buildSqlToolResult({
+                        success: false,
+                        errorCode: "MYSQL_NOT_CREATED",
+                        message: "MySQL is not provisioned yet or not found. Please provision MySQL before initializing schema.",
+                        nextActions: [
+                            buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                        ],
+                    });
+                }
+                throw error;
+            }
             const normalized = normalizeRunSqlResult(result);
             if (typeof normalized.requestId === "string") {
                 requestIdList.push(normalized.requestId);