@cloudbase/cloudbase-mcp 2.10.0 → 2.11.1

package/dist/index.cjs

@@ -22401,11 +22401,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getPort = void 0;
 const portfinder_1 = __importDefault(__webpack_require__(31323));
-const DEFAULT_PORT = 9012;
+// 默认端口
+const LOCAL_DEFAULT_PORT = 9012;
+const REMOTE_DEFAULT_PORT = 19012;
+function isRemoteEnvironment() {
+    return Boolean(process.env.SSH_CONNECTION
+        || process.env.SSH_CLIENT
+        || process.env.SSH_TTY
+        || process.env.VSCODE_IPC_HOOK_CLI
+        || process.env.VSCODE_AGENT_FOLDER
+        || process.env.REMOTE_CONTAINERS
+        || process.env.CODESPACES
+        || process.env.GITPOD_WORKSPACE_ID);
+}
+function getStartPort() {
+    const customStartPort = Number(process.env.TCB_WEB_LOGIN_START_PORT);
+    if (Number.isInteger(customStartPort) && customStartPort > 0 && customStartPort < 65535) {
+        return customStartPort;
+    }
+    return isRemoteEnvironment() ? REMOTE_DEFAULT_PORT : LOCAL_DEFAULT_PORT;
+}
+// 获取本地可用端口
 function getPort() {
     return __awaiter(this, void 0, void 0, function* () {
+        const startPort = getStartPort();
         const port = yield portfinder_1.default.getPortPromise({
-            port: DEFAULT_PORT
+            port: startPort,
+            stopPort: 65535
         });
         return port;
     });
@@ -41982,6 +42004,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getMacAddress = void 0;
 const address_1 = __importDefault(__webpack_require__(56163));
+// 获取本机 Mac 地址
 function getMacAddress() {
     return __awaiter(this, void 0, void 0, function* () {
         return new Promise((resolve) => {
@@ -42617,6 +42640,9 @@ const DefaultCloudBaseConfig = {
     functionRoot: './functions',
     functions: []
 };
+/**
+ * 从配置文件中解析 cloudbase 配置
+ */
 function resolveCloudBaseConfig(options) {
     var _a, _b;
     return __awaiter(this, void 0, void 0, function* () {
@@ -42625,17 +42651,21 @@ function resolveCloudBaseConfig(options) {
             searchFrom,
             moduleName: 'tcb'
         });
+        // 检查旧的配置文件
         if (oldTcbConfig) {
             throw new error_1.CloudBaseError('tcbrc.json 配置文件已废弃，请使用 cloudbaserc 配置文件！');
         }
+        // 可能为 null
         const localCloudBaseConfig = yield (0, cosmiconfig_1.loadConfig)({
             searchFrom,
             configPath
         });
+        // localCloudBaseConfig 不为空，且不存在 envId
         if (localCloudBaseConfig && !localCloudBaseConfig.envId) {
             throw new error_1.CloudBaseError('无效的配置文件，配置文件必须包含环境 Id(envId) 字段');
         }
         const cloudbaseConfig = Object.assign(Object.assign({}, DefaultCloudBaseConfig), localCloudBaseConfig);
+        // 兼容不同形式的配置
         if ((_a = cloudbaseConfig.functions) === null || _a === void 0 ? void 0 : _a.length) {
             cloudbaseConfig.functions = (_b = cloudbaseConfig.functions) === null || _b === void 0 ? void 0 : _b.map((func) => {
                 if (func.config) {
@@ -42653,19 +42683,25 @@ function resolveCloudBaseConfig(options) {
     });
 }
 exports.resolveCloudBaseConfig = resolveCloudBaseConfig;
+/**
+ * 从命令行和配置文件中获取 envId
+ */
 function getEnvId(commandOptions) {
     var _a;
     return __awaiter(this, void 0, void 0, function* () {
         const envId = commandOptions === null || commandOptions === void 0 ? void 0 : commandOptions.envId;
         const configPath = (_a = commandOptions === null || commandOptions === void 0 ? void 0 : commandOptions.parent) === null || _a === void 0 ? void 0 : _a.configFile;
         const cloudbaseConfig = yield resolveCloudBaseConfig(configPath);
+        // 命令行 envId 可以覆盖配置文件 envId
         const assignEnvId = envId || (cloudbaseConfig === null || cloudbaseConfig === void 0 ? void 0 : cloudbaseConfig.envId);
         return assignEnvId;
     });
 }
 exports.getEnvId = getEnvId;
 const renderConfig = (template, view) => {
+    // 渲染时不 escape
     mustache_1.default.escape = (text) => {
+        // 将对象转成 JSON 字符串
         if (typeof text === 'object') {
             try {
                 return JSON.stringify(text).replace(/"/g, '\\"');
@@ -42679,6 +42715,7 @@ const renderConfig = (template, view) => {
     return mustache_1.default.render(template, view, ['"{{', '}}"']);
 };
 exports.renderConfig = renderConfig;
+// cloudbase v2+ 配置文件解析器
 class ConfigParser {
     static get(key, defaultValue, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -42696,14 +42733,22 @@ class ConfigParser {
             return this.instance.options(options).update(key, value);
         });
     }
+    // 解析配置
     static parseRawConfig(rawConfig, cwd = process.cwd()) {
         return __awaiter(this, void 0, void 0, function* () {
             let config = lodash_1.default.cloneDeep(rawConfig);
+            // 命令行中指定的 envId，优先级最高
             const envId = yargs_1.default.argv.e || yargs_1.default.argv.envId;
+            // 加载本地 env 文件
             const env = (0, env_1.loadEnvVariables)(cwd);
+            // 转换成字符串
             let configString = JSON.stringify(config);
             const envs = {
-                env: Object.assign(Object.assign({ ENV_ID: envId || config.envId }, env), process.env),
+                // 环境变量
+                env: Object.assign(Object.assign({ 
+                    // 注入 ENV_ID，同云端部署保持一致
+                    ENV_ID: envId || config.envId }, env), process.env),
+                // 云开发相关的变量
                 tcb: {
                     envId: envId || config.envId
                 },
@@ -42711,14 +42756,17 @@ class ConfigParser {
                     uid: (0, uid_1.uuid)(24)
                 }
             };
+            // --envId 优先级最高
             if (envId) {
                 envs.env.envId = envId;
                 envs.env.ENV_ID = envId;
             }
+            // 使用模板渲染
             configString = (0, exports.renderConfig)(configString, envs);
             config = JSON.parse(configString, (key, value) => {
                 if (typeof value === 'string') {
                     try {
+                        // 只解析对象
                         const parsed = JSON.parse(value);
                         if (typeof parsed === 'object') {
                             return parsed;
@@ -42737,6 +42785,7 @@ class ConfigParser {
     constructor(options = {}) {
         this.options(options);
     }
+    // 重写内部配置
     options(options = {}) {
         const { cwd = process.cwd(), cover = true, configPath } = options;
         this.cwd = cwd;
@@ -42744,21 +42793,28 @@ class ConfigParser {
         this.configPath = configPath;
         return this;
     }
+    // get config value by lodash object paths
+    // https://lodash.com/docs/4.17.15#get
     get(key, defaultValue) {
         return __awaiter(this, void 0, void 0, function* () {
             const config = yield this.getConfig();
+            // 不带 key，返回整个配置
             if (!key) {
                 return config;
             }
+            // 返回具体字段的值
             return lodash_1.default.get(config, key, defaultValue);
         });
     }
+    // update config value by lodash object paths
+    // https://lodash.com/docs/4.17.15#set
     update(key, value, cover) {
         return __awaiter(this, void 0, void 0, function* () {
             const config = yield resolveCloudBaseConfig({
                 configPath: this.configPath
             });
             let unionConfig;
+            // 当 value 为 undefined 且 key 为对象时，直接把 key 作为值更新到 config 中
             if (typeof value === 'undefined' && typeof key === 'object') {
                 unionConfig = Object.assign(Object.assign({}, config), key);
             }
@@ -42768,24 +42824,34 @@ class ConfigParser {
             yield this.updateConfig(unionConfig, cover);
         });
     }
+    // 读配置，支持外部直接调用
     getConfig() {
         return __awaiter(this, void 0, void 0, function* () {
+            // 配置文件路径不存在
             if (!this.configPath) {
+                // 搜索配置，获取配置目录
                 const result = yield (0, cosmiconfig_1.searchConfig)(this.cwd);
+                // 设置 config 路径
                 this.configPath = result === null || result === void 0 ? void 0 : result.filepath;
             }
+            // 读取原配置
             const rawConfig = yield resolveCloudBaseConfig({
                 configPath: this.configPath
             });
             return ConfigParser.parseRawConfig(rawConfig, this.cwd);
         });
     }
+    // 写配置
     updateConfig(config, cover = this.cover) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 配置文件路径不存在
             if (!this.configPath) {
+                // 搜索配置，获取配置目录
                 const result = yield (0, cosmiconfig_1.searchConfig)(this.cwd);
+                // 设置 config 路径，config 可能不存在
                 this.configPath = result === null || result === void 0 ? void 0 : result.filepath;
             }
+            // 原配置
             const baseConfig = yield (0, cosmiconfig_1.loadConfig)({
                 searchFrom: this.cwd,
                 configPath: this.configPath
@@ -42793,14 +42859,17 @@ class ConfigParser {
             const unionConfig = cover
                 ? Object.assign(Object.assign({}, baseConfig), config) : Object.assign(Object.assign({}, config), baseConfig);
             let indent = 2;
+            // 文件存在，检测文件缩进
             if (this.configPath) {
                 const fileContent = yield fs_1.default.promises.readFile(this.configPath);
                 const detectRet = (0, detect_indent_1.detectIndent)(fileContent === null || fileContent === void 0 ? void 0 : fileContent.toString());
                 indent = (detectRet === null || detectRet === void 0 ? void 0 : detectRet.amount) || indent;
             }
             else {
+                // 配置文件可能不存在，设置配置文件路径，直接写内容
                 this.configPath = path_1.default.join(this.cwd, 'cloudbaserc.json');
             }
+            // 写入配置到 json 文件中
             jsonfile_1.default.writeFileSync(this.configPath, unionConfig, { spaces: indent });
         });
     }
@@ -67211,11 +67280,17 @@ module.exports = flatten;
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getPropertyByPath = void 0;
+// Resolves property names or property paths defined with period-delimited
+// strings or arrays of strings. Property names that are found on the source
+// object are used directly (even if they include a period).
+// Nested property names that include periods, within a path, are only
+// understood in array paths.
 function getPropertyByPath(source, path) {
     if (typeof path === 'string' && Object.prototype.hasOwnProperty.call(source, path)) {
         return source[path];
     }
     const parsedPath = typeof path === 'string' ? path.split('.') : path;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return parsedPath.reduce((previous, key) => {
         if (previous === undefined) {
             return previous;
@@ -82787,7 +82862,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.AuthSupevisor = void 0;
+exports.AuthSupevisor = exports.AuthSupervisor = void 0;
 const web_auth_1 = __webpack_require__(76097);
 const common_1 = __webpack_require__(96711);
 const credential_1 = __webpack_require__(99795);
@@ -82795,13 +82870,17 @@ const error_1 = __webpack_require__(64119);
 __exportStar(__webpack_require__(96711), exports);
 __exportStar(__webpack_require__(99795), exports);
 __exportStar(__webpack_require__(76097), exports);
-class AuthSupevisor {
+class AuthSupervisor {
+    /**
+     * 单例模式，全局缓存
+     * @param options
+     */
     static getInstance(options = {}) {
-        if (AuthSupevisor.instance) {
-            return AuthSupevisor.instance;
+        if (AuthSupervisor.instance) {
+            return AuthSupervisor.instance;
         }
-        const instance = new AuthSupevisor(options);
-        AuthSupevisor.instance = instance;
+        const instance = new AuthSupervisor(options);
+        AuthSupervisor.instance = instance;
         return instance;
     }
     constructor(options = {}) {
@@ -82814,11 +82893,15 @@ class AuthSupevisor {
         this.cacheExpiredTime = 0;
         this.throwError = throwError;
     }
+    /**
+     * 获取登录状态信息
+     */
     getLoginState() {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.cacheCredential && this.needCache && !this.isCacheExpire()) {
                 return this.cacheCredential;
             }
+            // 获取本地登录状态
             const credential = yield (0, credential_1.checkAndGetCredential)(this.requestConfig);
             if (this.needCache && credential) {
                 this.cacheCredential = credential;
@@ -82830,17 +82913,25 @@ class AuthSupevisor {
             return credential;
         });
     }
+    /**
+     * 通过网页授权登录
+     * @returns credential
+     */
     loginByWebAuth(options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { getAuthUrl, throwError } = options;
+            const { getAuthUrl, throwError, noBrowser, callbackTimeout } = options;
             if (this.cacheCredential && this.needCache && !this.isCacheExpire()) {
                 return this.cacheCredential;
             }
+            // 校验本地秘钥
             let credential = yield (0, credential_1.checkAndGetCredential)(this.requestConfig);
             if (credential)
                 return credential;
+            // 兼容临时秘钥
             credential = yield (0, web_auth_1.getAuthTokenFromWeb)({
-                getAuthUrl
+                getAuthUrl,
+                noBrowser,
+                callbackTimeout
             });
             try {
                 yield (0, common_1.checkAuth)(credential, this.requestConfig);
@@ -82851,8 +82942,10 @@ class AuthSupevisor {
                 }
                 return null;
             }
+            // 通过 Web 登录时，本地要存储 tmpSecretId 形式，方式 CLI 登录失效
             const webCredential = (0, common_1.resolveWebCredential)(credential);
             yield credential_1.authStore.set('credential', webCredential);
+            // 缓存处理转换后的 credential
             if (this.needCache && credential) {
                 this.cacheCredential = credential;
                 const { accessTokenExpired } = credential;
@@ -82863,26 +82956,41 @@ class AuthSupevisor {
             return credential;
         });
     }
-    loginByApiSecret(secretId, secretKey, token) {
+    /**
+     * 通过 API Secret 登录，支持临时秘钥
+     * @param secretId
+     * @param secretKey
+     * @param token
+     * @param opts 选项配置，包括强制更新和额外的 Credential 字段
+     * @returns credential
+     */
+    // eslint-disable-next-line max-params
+    loginByApiSecret(secretId, secretKey, token, opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.cacheCredential && this.needCache && !this.isCacheExpire()) {
+            const { forceUpdate = false, storeAsWebCredential = false, additionalCredentialFields } = opts || {};
+            if (this.cacheCredential && this.needCache && !this.isCacheExpire() && !forceUpdate) {
                 return this.cacheCredential;
             }
-            let credential = yield (0, credential_1.checkAndGetCredential)(this.requestConfig);
-            if (credential)
-                return credential;
+            // 校验本地秘钥（如果不是强制更新）
+            if (!forceUpdate) {
+                let credential = yield (0, credential_1.checkAndGetCredential)(this.requestConfig);
+                if (credential)
+                    return credential;
+            }
+            // 当本地身份信息不存在时，才使用传入参数进行校验
             if (!secretId || !secretKey) {
                 throw new error_1.CloudBaseError('secretId 或 secretKey 不能为空');
             }
-            credential = {
-                secretId,
+            const credential = Object.assign(Object.assign({}, additionalCredentialFields), { secretId,
                 secretKey,
-                token
-            };
+                token });
             try {
                 yield (0, common_1.checkAuth)(credential, this.requestConfig);
             }
             catch (e) {
+                // CAM 错误视为登录正常
+                // if (isCamRefused(e)) return credential;
+                // 请求超时
                 if (e.type === 'request-timeout') {
                     throw new error_1.CloudBaseError('请求超时，请检查你的网络，如果终端无法直接访问公网，请设置终端 HTTP 请求代理！');
                 }
@@ -82891,7 +82999,12 @@ class AuthSupevisor {
                 }
                 return null;
             }
-            yield credential_1.authStore.set('credential', credential);
+            // 根据选项决定存储格式
+            const credentialToStore = storeAsWebCredential
+                ? (0, common_1.resolveWebCredential)(credential)
+                : credential;
+            // 存储信息
+            yield credential_1.authStore.set('credential', credentialToStore);
             if (this.needCache && credential) {
                 this.cacheCredential = credential;
                 this.cacheExpiredTime = Date.now() + 3600 * 1000;
@@ -82904,10 +83017,11 @@ class AuthSupevisor {
             if (this.cacheCredential) {
                 this.cacheCredential = null;
             }
-            const credentail = yield (0, credential_1.getCredentialWithoutCheck)();
+            const credential = yield (0, credential_1.getCredentialWithoutCheck)();
             try {
-                if (credentail === null || credentail === void 0 ? void 0 : credentail.refreshToken) {
-                    yield (0, credential_1.refreshTmpToken)(Object.assign(Object.assign({}, credentail), { isLogout: true }));
+                // 仅使用 Web 控制台授权登录时才删除 token
+                if (credential === null || credential === void 0 ? void 0 : credential.refreshToken) {
+                    yield (0, credential_1.refreshTmpToken)(Object.assign(Object.assign({}, credential), { isLogout: true }));
                 }
                 yield credential_1.authStore.delete('credential');
             }
@@ -82922,6 +83036,29 @@ class AuthSupevisor {
         return now >= this.cacheExpiredTime;
     }
 }
+exports.AuthSupervisor = AuthSupervisor;
+/**
+ * @deprecated Use `AuthSupervisor` instead. This class has a spelling error and will be removed in a future version.
+ */
+class AuthSupevisor extends AuthSupervisor {
+    /**
+     * @deprecated Use `AuthSupervisor.getInstance` instead
+     */
+    static getInstance(options = {}) {
+        if (AuthSupevisor.instance) {
+            return AuthSupevisor.instance;
+        }
+        const instance = new AuthSupevisor(options);
+        AuthSupevisor.instance = instance;
+        return instance;
+    }
+    /**
+     * @deprecated Use `AuthSupervisor` constructor instead
+     */
+    constructor(options = {}) {
+        super(options);
+    }
+}
 exports.AuthSupevisor = AuthSupevisor;
 
 
@@ -84723,14 +84860,17 @@ exports.getDataFromWeb = void 0;
 const open_1 = __importDefault(__webpack_require__(30353));
 const query_string_1 = __importDefault(__webpack_require__(86663));
 const http_1 = __importDefault(__webpack_require__(81630));
+const child_process_1 = __webpack_require__(79646);
 const system_1 = __webpack_require__(62179);
 const error_1 = __webpack_require__(64119);
 const html_1 = __webpack_require__(74856);
+// 创建本地 Web 服务器，接受 Web 控制台传入的信息
 function createLocalServer() {
     return __awaiter(this, void 0, void 0, function* () {
         const server = http_1.default.createServer();
         const port = yield (0, system_1.getPort)();
         return new Promise((resolve, reject) => {
+            // 服务启动异常
             server.on('error', (e) => {
                 reject(e);
             });
@@ -84743,6 +84883,7 @@ function createLocalServer() {
         });
     });
 }
+// 返回 HTML 响应
 function respondWithFile(options) {
     const { req, res, statusCode, filename } = options;
     return new Promise(function (resolve) {
@@ -84756,20 +84897,108 @@ function respondWithFile(options) {
         resolve();
     });
 }
-function getDataFromWeb(getUrl, type) {
+function isTruthyFlag(value) {
+    if (!value) {
+        return false;
+    }
+    return ['1', 'true', 'yes', 'on'].includes(String(value).trim().toLowerCase());
+}
+function isVSCodeEnvironment() {
+    return Boolean(process.env.VSCODE_IPC_HOOK_CLI
+        || process.env.VSCODE_PID
+        || process.env.TERM_PROGRAM === 'vscode');
+}
+function parseBrowserCommand(browser) {
+    const parts = browser.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+    return parts.map((item) => item.replace(/^"(.*)"$/, '$1'));
+}
+function openUrlByBrowserEnv(url) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const browser = (_a = process.env.BROWSER) === null || _a === void 0 ? void 0 : _a.trim();
+        if (!browser) {
+            return false;
+        }
+        const [command, ...args] = parseBrowserCommand(browser);
+        if (!command) {
+            return false;
+        }
+        const finalArgs = args.map((arg) => (arg === '%s' ? url : arg));
+        if (!args.includes('%s')) {
+            finalArgs.push(url);
+        }
+        return new Promise((resolve) => {
+            (0, child_process_1.execFile)(command, finalArgs, (error) => {
+                resolve(!error);
+            });
+        });
+    });
+}
+function shouldUseBrowserEnvFallback() {
+    return process.platform === 'linux' && isVSCodeEnvironment();
+}
+function openUrl(url) {
     return __awaiter(this, void 0, void 0, function* () {
-        const { server, port } = yield createLocalServer();
-        const url = getUrl(port);
         try {
-            yield (0, open_1.default)(url, { url: true });
+            const child = yield (0, open_1.default)(url, { url: true });
+            if (child === null || child === void 0 ? void 0 : child.once) {
+                child.once('error', (error) => __awaiter(this, void 0, void 0, function* () {
+                    if (shouldUseBrowserEnvFallback()) {
+                        yield openUrlByBrowserEnv(url);
+                    }
+                }));
+            }
+            return true;
         }
         catch (e) {
-            throw new error_1.CloudBaseError('打开浏览器失败，请尝试使用其他登录方式');
+            if (shouldUseBrowserEnvFallback()) {
+                return openUrlByBrowserEnv(url);
+            }
+            return false;
+        }
+    });
+}
+// 从 Web 页面中获取数据
+function getDataFromWeb(getUrl, type, options = {}) {
+    var _a, _b;
+    return __awaiter(this, void 0, void 0, function* () {
+        const { server, port } = yield createLocalServer();
+        const noBrowser = (_a = options.noBrowser) !== null && _a !== void 0 ? _a : isTruthyFlag(process.env.TCB_NO_BROWSER);
+        const callbackTimeout = (_b = options.callbackTimeout) !== null && _b !== void 0 ? _b : 180000;
+        if (!Number.isFinite(callbackTimeout) || callbackTimeout <= 0) {
+            throw new error_1.CloudBaseError('callbackTimeout must be a positive number');
+        }
+        const url = getUrl(port);
+        console.log('\n\n若链接未自动打开，请手动复制至浏览器，或尝试其他登录方式:');
+        console.log(`\n${url}\n`);
+        if (!noBrowser) {
+            // 对 url 转码, 避免 wsl 无法正常打开地址
+            // https://www.npmjs.com/package/open#url
+            // https://github.com/sindresorhus/open/blob/master/index.js#L48
+            yield openUrl(url);
         }
         return new Promise((resolve, reject) => {
+            let finished = false;
+            const timer = setTimeout(() => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                server.close();
+                reject(new error_1.CloudBaseError(`等待浏览器授权回调超时(${Math.floor(callbackTimeout / 1000)}s)!`));
+            }, callbackTimeout);
+            const finish = (fn) => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                clearTimeout(timer);
+                fn();
+            };
             server.on('request', (req, res) => {
-                const { url } = req;
+                const url = req.url || '/';
                 const { query } = query_string_1.default.parseUrl(url);
+                // 响应 HTML 文件
                 if (query === null || query === void 0 ? void 0 : query.html) {
                     return respondWithFile({
                         req,
@@ -84777,25 +85006,33 @@ function getDataFromWeb(getUrl, type) {
                         statusCode: 200,
                         filename: `${type}Success`
                     }).then(() => {
-                        server.close();
-                        resolve(query);
+                        finish(() => {
+                            server.close();
+                            resolve(query);
+                        });
                     }).catch((e) => {
-                        server.close();
-                        reject(e);
+                        finish(() => {
+                            server.close();
+                            reject(e);
+                        });
                     });
                 }
+                // CORS 响应普通文本
                 res.writeHead(200, {
                     'Access-Control-Allow-Origin': '*',
                     'Access-Control-Allow-Methods': '*',
                     'Access-Control-Allow-Headers': '*',
                     'Content-Type': 'text/plain',
+                    // 立即关闭 http 连接
                     Connection: 'close'
                 });
                 res.end();
                 if (req.method !== 'OPTIONS') {
                     server.close();
                 }
-                resolve(query);
+                finish(() => {
+                    resolve(query);
+                });
             });
         });
     });
@@ -89001,6 +89238,7 @@ __exportStar(__webpack_require__(31153), exports);
 __exportStar(__webpack_require__(33283), exports);
 __exportStar(__webpack_require__(79998), exports);
 __exportStar(__webpack_require__(19835), exports);
+// export types
 __exportStar(__webpack_require__(42612), exports);
 
 
@@ -93051,6 +93289,7 @@ const cloud_api_1 = __webpack_require__(2090);
 const constant_1 = __webpack_require__(53393);
 let commonCredential;
 class CloudApiService {
+    // 单例模式
     static getInstance(service) {
         var _a;
         if ((_a = CloudApiService.serviceCacheMap) === null || _a === void 0 ? void 0 : _a[service]) {
@@ -93061,6 +93300,7 @@ class CloudApiService {
         return apiService;
     }
     constructor(service, baseParams, version = '') {
+        // 初始化 API 实例
         this.apiService = new cloud_api_1.CloudApiService({
             service,
             version,
@@ -93089,6 +93329,7 @@ class CloudApiService {
     }
 }
 exports.CloudApiService = CloudApiService;
+// 缓存请求实例
 CloudApiService.serviceCacheMap = {};
 
 
@@ -101388,8 +101629,16 @@ const archiver_1 = __importDefault(__webpack_require__(30989));
 exports.decompress = decompress_1.default;
 const unzip = (zipFile, dest) => (0, exports.decompress)(zipFile, dest);
 exports.unzip = unzip;
+/**
+ * 解压流（使用临时 zip 包）
+ * @param source 可读流
+ * @param dest 解压目标文件夹
+ * @param name 可选的临时 zip 包名
+ */
 const unzipStream = (source, dest, name = 'gape3il5rk8.zip') => __awaiter(void 0, void 0, void 0, function* () {
+    // 确保文件夹存在
     yield (0, fs_2.mkdirAsync)(dest);
+    // 使用一个临时文件下载 zip 包
     const zipPath = path_1.default.join(dest, `${name}.zip`);
     const zip = fs_1.default.createWriteStream(zipPath);
     source.pipe(zip);
@@ -101432,13 +101681,16 @@ function zipFiles(allFilesPath, outputPath, ignore) {
             archive.pipe(output);
             allFilesPath.forEach(filePath => {
                 if (fs_1.default.statSync(filePath).isDirectory()) {
+                    // append files from a glob pattern
                     archive.glob('**/*', {
+                        // 目标路径
                         cwd: filePath,
                         ignore: ignore,
                         dot: true
                     });
                 }
                 else {
+                    // append file
                     archive.file(filePath);
                 }
             });
@@ -112046,7 +112298,11 @@ Promise.PromiseInspection = PromiseInspection;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.AsyncMerge = void 0;
 const cache_1 = __webpack_require__(51995);
+// 使用 Symbol 值，判断缓存结果时，可以准确判断是否为 Error 类型
 const ERROR_KEY = Symbol('ERROR_KEY');
+/**
+ * 异步任务合并
+ */
 class AsyncMerge {
     constructor() {
         this.tasks = {};
@@ -112060,7 +112316,10 @@ class AsyncMerge {
             throw new Error('AsyncMerge taskId could not be empty, it will cause unexpected result!');
         }
         return new Promise((resolve, reject) => {
+            // 取缓存
             const cacheRet = cache_1.nilCache.get(taskId);
+            // 校验缓存，缓存结果可能为 null, undefined 等空值
+            // 使用 Symbol 值做判断
             if (maxAge > 0 && cacheRet !== cache_1.Cache.NIL) {
                 const e = cacheRet[ERROR_KEY];
                 if (e) {
@@ -112082,6 +112341,7 @@ class AsyncMerge {
             }
         });
     }
+    // eslint-disable-next-line
     runTask(fn, taskId, taskOptions, cb) {
         const { tasks } = this;
         const { maxAge = 0, timeout = 60000 } = taskOptions;
@@ -112093,15 +112353,18 @@ class AsyncMerge {
         }
         tasks[taskId].callbacks.push(cb);
         const task = tasks[taskId];
+        // 当前类型的任务没有运行
         if (!task.lock) {
             let timerId = null;
             if (timeout) {
                 timerId = setTimeout(() => {
+                    // 超时回调
                     task.callbacks.forEach((cb) => cb(new Error('TASK_TIMEOUT')));
                     task.lock = false;
                     delete tasks[taskId];
                 }, timeout);
             }
+            // 上锁，标志任务处理开始
             task.lock = true;
             fn()
                 .then((res) => {
@@ -112115,6 +112378,7 @@ class AsyncMerge {
                 clearTimeout(timerId);
                 task.lock = false;
                 delete tasks[taskId];
+                // 任务异常，缓存异常值
                 maxAge > 0 && cache_1.nilCache.set(taskId, { ERROR_KEY: e }, maxAge);
                 task.callbacks.forEach((cb) => cb(e));
             });
@@ -124758,6 +125022,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.md5Encoding = void 0;
 const crypto_1 = __importDefault(__webpack_require__(55511));
 const error_1 = __webpack_require__(64119);
+// MD5
 function md5Encoding(str = '') {
     if (typeof str !== 'string')
         throw new error_1.CloudBaseError('参数必须为字符串！');
@@ -125537,9 +125802,13 @@ const FileAsync_1 = __importDefault(__webpack_require__(19778));
 const FileSync_1 = __importDefault(__webpack_require__(29303));
 const fs_1 = __webpack_require__(96185);
 const homeDir = os_1.default.homedir();
+// 系统配置目录
 const homeAccessible = (0, fs_1.checkFullAccess)(homeDir);
+// 仅当 home 目录可访问时，才使用 home 目录，否则使用临时目录
 const configDir = homeDir && homeAccessible ? path_1.default.join(homeDir, '.config') : path_1.default.join(os_1.default.tmpdir(), '.config');
+// cloudbase 配置目录
 exports.cloudbaseConfigDir = path_1.default.join(configDir, '.cloudbase');
+// 确保目录存在
 make_dir_1.default.sync(exports.cloudbaseConfigDir);
 function getAsyncDB(file) {
     const dbPath = path_1.default.join(exports.cloudbaseConfigDir, `${file}.json`);
@@ -126762,9 +127031,11 @@ function handleTimeout(e) {
         throw new error_1.CloudBaseError('请求超时，请检查你的网络，如果终端无法直接访问公网，请设置终端 HTTP 请求代理！');
     }
     else {
+        // 其他错误，抛出
         throw e;
     }
 }
+// 使用 fetch + 代理
 function fetch(url, config = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const proxy = (0, system_1.getProxy)();
@@ -126787,6 +127058,7 @@ function fetch(url, config = {}) {
     });
 }
 exports.fetch = fetch;
+// 使用 fetch + 代理
 function postFetch(url, data) {
     return __awaiter(this, void 0, void 0, function* () {
         const proxy = (0, system_1.getProxy)();
@@ -126833,6 +127105,7 @@ function fetchStream(url, config = {}) {
     });
 }
 exports.fetchStream = fetchStream;
+// 使用 fetch + 代理
 function putFetch(url, config = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const proxy = (0, system_1.getProxy)();
@@ -136935,7 +137208,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.10.0" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.11.1" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -137261,6 +137534,9 @@ exports.getRegion = exports.getCloudBaseConfig = void 0;
 const yargs_1 = __importDefault(__webpack_require__(5945));
 const path_1 = __importDefault(__webpack_require__(39902));
 const cloudbase_1 = __webpack_require__(10304);
+/**
+ * 获取当前目录下的 cloudbase 配置
+ */
 const getCloudBaseConfig = (configPath) => __awaiter(void 0, void 0, void 0, function* () {
     let specificConfigPath = configPath || yargs_1.default.argv['config-path'];
     specificConfigPath = specificConfigPath ? path_1.default.resolve(specificConfigPath) : undefined;
@@ -137271,7 +137547,11 @@ const getCloudBaseConfig = (configPath) => __awaiter(void 0, void 0, void 0, fun
     return config;
 });
 exports.getCloudBaseConfig = getCloudBaseConfig;
+/**
+ * 从命令行参数和配置文件中读取 region
+ */
 const getRegion = (noDefault = false) => __awaiter(void 0, void 0, void 0, function* () {
+    // region 缩写
     const regionMap = {
         gz: 'ap-guangzhou',
         bj: 'ap-beijing',
@@ -137280,16 +137560,19 @@ const getRegion = (noDefault = false) => __awaiter(void 0, void 0, void 0, funct
         cd: 'ap-chengdu',
         cq: 'ap-chongqing'
     };
+    // 命令行中指定的 region
     const argvRegion = (yargs_1.default.argv.r || yargs_1.default.argv.region);
     if (argvRegion && regionMap[argvRegion]) {
         return regionMap[argvRegion];
     }
     if (argvRegion)
         return argvRegion;
+    // 配置文件中的 region
     const config = yield (0, exports.getCloudBaseConfig)();
     if ((config === null || config === void 0 ? void 0 : config.region) && regionMap[config === null || config === void 0 ? void 0 : config.region]) {
         return regionMap[config.region];
     }
+    // 不使用默认值时，不会默认返回 region
     return noDefault ? config === null || config === void 0 ? void 0 : config.region : (config === null || config === void 0 ? void 0 : config.region) || 'ap-shanghai';
 });
 exports.getRegion = getRegion;
@@ -141824,8 +142107,10 @@ function getJavaScripts(wsPort) {
     }
   }
 
-  // WebSocket connection
-  const ws = new WebSocket('ws://localhost:${wsPort}');
+  // WebSocket: same host as page so it works in remote VS Code / Cloud IDE (no localhost)
+  const wsScheme = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const wsUrl = wsScheme + '//' + window.location.host;
+  const ws = new WebSocket(wsUrl);
   
   ws.onopen = () => {
     console.log('[env-setup] WebSocket connected');
@@ -154757,6 +155042,10 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getOSInfo = exports.getPlatformRelease = void 0;
 const os_1 = __importDefault(__webpack_require__(21820));
 const macOSMap = new Map([
+    [24, 'Sequoia'],
+    [23, 'Sonoma'],
+    [22, 'Ventura'],
+    [21, 'Monterey'],
     [20, 'BigSur'],
     [19, 'Catalina'],
     [18, 'Mojave'],
@@ -154772,9 +155061,19 @@ const macOSMap = new Map([
     [8, 'Tiger'],
     [7, 'Panther'],
     [6, 'Jaguar'],
-    [5, 'Puma']
+    [5, 'Puma'] // macOS 10.1 Puma (2001)
 ]);
 const winMap = new Map([
+    ['10.0.22000', '11'],
+    ['10.0.19041', '10'],
+    ['10.0.18363', '10'],
+    ['10.0.17763', '10'],
+    ['10.0.17134', '10'],
+    ['10.0.16299', '10'],
+    ['10.0.15063', '10'],
+    ['10.0.14393', '10'],
+    ['10.0.10586', '10'],
+    ['10.0.10240', '10'],
     ['10.0', '10'],
     ['6.3', '8.1'],
     ['6.2', '8'],
@@ -154785,28 +155084,55 @@ const winMap = new Map([
     ['5.0', '2000'],
     ['4.9', 'ME'],
     ['4.1', '98'],
-    ['4.0', '95']
+    ['4.0', '95'] // Windows 95 (1995)
 ]);
 function getPlatformRelease(platform, release) {
+    // macOS
     if (platform === 'darwin') {
-        const releaseNum = Number(release.split('.')[0]);
-        const name = macOSMap.get(releaseNum);
+        const releaseParts = release.split('.');
+        const majorNum = Number(releaseParts[0]);
+        const minorNum = Number(releaseParts[1]) || 0;
+        const name = macOSMap.get(majorNum) || 'macOS';
         let version;
-        if (releaseNum >= 20) {
-            version = '11.' + (releaseNum - 20);
+        // macOS 11 及以上版本 (majorNum >= 20)
+        if (majorNum >= 20) {
+            // releaseNum 20 -> macOS 11, 21 -> macOS 12, etc.
+            const majorVersion = majorNum - 9;
+            version = `${majorVersion}.${minorNum}`;
+            // macOS 10.x 版本 (majorNum < 20)
         }
         else {
-            version = '10.' + (releaseNum - 4);
+            // releaseNum 19 -> 10.15, 18 -> 10.14, etc.
+            const minorVersion = majorNum - 4;
+            version = `10.${minorVersion}`;
         }
         return `${name} ${version}`;
     }
+    // windows
     if (platform === 'win32') {
-        const version = (/\d+\.\d/.exec(release) || [])[0];
-        return `Windows ${winMap.get(version)}`;
+        // 尝试精确匹配完整版本号
+        let windowsVersion = winMap.get(release);
+        if (!windowsVersion) {
+            // 如果没有精确匹配，尝试匹配主版本号
+            const majorVersion = (/^\d+\.\d+/.exec(release) || [])[0];
+            windowsVersion = winMap.get(majorVersion);
+        }
+        if (!windowsVersion) {
+            // 如果还是没有匹配，尝试只匹配第一部分
+            const firstPart = (/^\d+/.exec(release) || [])[0];
+            if (firstPart === '10') {
+                windowsVersion = '10';
+            }
+        }
+        // 显示完整的版本信息
+        const versionDisplay = windowsVersion || release;
+        return `Windows ${versionDisplay}`;
     }
+    // 其他 Linux
     return 'Linux';
 }
 exports.getPlatformRelease = getPlatformRelease;
+// 获取 hostname 和平台信息
 function getOSInfo() {
     const hostname = os_1.default.hostname();
     const platform = os_1.default.platform();
@@ -155004,12 +155330,18 @@ function readFile(target) {
         return '';
     }
 }
+// 从 env 文件中加载环境变量
+// 参考 https://cli.vuejs.org/zh/guide/mode-and-env.html
 function loadEnvVariables(from = process.cwd()) {
     const mode = yargs_1.default.argv.mode;
+    // .env
     const baseEnv = dotenv_1.default.parse(readFile(path_1.default.join(from, '.env')));
+    // .env.local
     const localEnv = dotenv_1.default.parse(readFile(path_1.default.join(from, '.env.local')));
+    // .env.mode
     const modeEnv = dotenv_1.default.parse(readFile(path_1.default.join(from, `.env.${mode}`)));
     const unionConfig = lodash_1.default.merge({}, baseEnv, localEnv, modeEnv);
+    // 扩展 dotenv 解析模式，支持 functions.xxx=xxx 形式设置对象
     return Object.keys(unionConfig).reduce((prev, key) => {
         return lodash_1.default.set(prev, key, unionConfig[key]);
     }, {});
@@ -155095,28 +155427,46 @@ module.exports = diff
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.nilCache = exports.memoryCache = exports.Cache = void 0;
 class Entry {
+    // eslint-disable-next-line
     constructor(key, value, now, maxAge) {
         this.key = key;
         this.value = value;
         this.now = now;
         this.maxAge = maxAge;
     }
+    // 当前 entry 是否过期
     isExpired() {
         const now = Date.now();
         return this.now + this.maxAge <= now;
     }
 }
+/**
+ * 缓存模块
+ * 1. 内存缓存
+ * 2. TODO: 本地缓存
+ */
 class Cache {
     constructor(nil) {
+        // use map to cache
         this.store = new Map();
         this.nil = false;
         this.nil = nil;
     }
+    /**
+     * 设置缓存
+     * @param key 缓存 key
+     * @param value 缓存值
+     * @param maxAge 缓存保持时间，单位 ms
+     */
     set(key, value, maxAge = 0) {
         const now = maxAge ? Date.now() : 0;
         const entry = new Entry(key, value, now, maxAge);
         this.store.set(key, entry);
     }
+    /**
+     * 获取缓存结果
+     * @param key 缓存 key
+     */
     get(key) {
         const { nil } = this;
         const entry = this.store.get(key);
@@ -155130,6 +155480,7 @@ class Cache {
     }
 }
 exports.Cache = Cache;
+// 标志缓存不存在或过期
 Cache.NIL = Symbol('NIL');
 exports.memoryCache = new Cache();
 exports.nilCache = new Cache(true);
@@ -162451,6 +162802,7 @@ class Explorer extends ExplorerBase_1.ExplorerBase {
                     return placeResult;
                 }
             }
+            // config not found
             return null;
         });
     }
@@ -181629,12 +181981,15 @@ exports.execWithLoading = exports.loadingFactory = void 0;
 const ora_1 = __importDefault(__webpack_require__(88267));
 class Loading {
     constructor() {
+        // @ts-ignore
         process.on('tcbExit', this.stop.bind(this));
+        // @ts-ignore
         process.on('tcbError', this.stop.bind(this));
         this.spinner = (0, ora_1.default)({
             discardStdin: false
         });
     }
+    // eslint-disable-next-line
     set text(text) {
         this.spinner.text = text;
     }
@@ -181661,9 +182016,15 @@ const loadingFactory = () => {
     return new Loading();
 };
 exports.loadingFactory = loadingFactory;
+/**
+ * 执行异步任务，显示 loading 动画
+ * @param task
+ * @param options
+ */
 const execWithLoading = (task, options = {}) => __awaiter(void 0, void 0, void 0, function* () {
     const { startTip, successTip, failTip } = options;
     const loading = (0, exports.loadingFactory)();
+    // 刷新 loading 提示
     const flush = (text) => {
         loading.text = text;
     };
@@ -196377,6 +196738,7 @@ module.exports = {
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getProxy = void 0;
+// 解析 Proxy 配置
 function getProxy() {
     const httpProxy = process.env.http_proxy ||
         process.env.HTTP_PROXY ||
@@ -203507,7 +203869,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.10.0" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.11.1" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -203892,12 +204254,17 @@ const getSearchPlaces = (moduleName) => [
     `${moduleName}rc.js`,
     `${moduleName}.config.js`
 ];
+/**
+ * 搜索指定配置文件，返回包含路径等信息
+ */
 function searchConfig(dest, moduleName = MODULE_NAME) {
     return __awaiter(this, void 0, void 0, function* () {
         const explorer = (0, explorer_1.cosmiconfig)(moduleName, {
+            // 不向上搜索
             stopDir: process.cwd(),
             searchPlaces: getSearchPlaces(moduleName)
         });
+        // 搜索配置文件
         try {
             return explorer.search(dest || process.cwd());
         }
@@ -203907,14 +204274,21 @@ function searchConfig(dest, moduleName = MODULE_NAME) {
     });
 }
 exports.searchConfig = searchConfig;
+/**
+ * 搜索或指定配置文件路径
+ * 加载配置文件内容
+ */
 function loadConfig(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const { moduleName = MODULE_NAME, configPath, searchFrom } = options;
         const explorer = (0, explorer_1.cosmiconfig)(moduleName, {
+            // 不向上搜索
             stopDir: process.cwd(),
             searchPlaces: getSearchPlaces(moduleName)
         });
+        // 从指定路径加载配置文件
         if (configPath) {
+            // 校验路径是否存在
             (0, fs_1.checkReadable)(configPath, true);
             try {
                 const result = yield explorer.load(configPath);
@@ -203929,6 +204303,7 @@ function loadConfig(options = {}) {
                 });
             }
         }
+        // 搜索配置文件
         try {
             const result = yield searchConfig(searchFrom || process.cwd(), moduleName);
             if (!result)
@@ -205414,6 +205789,7 @@ function cosmiconfig(moduleName, options = {}) {
     };
 }
 exports.cosmiconfig = cosmiconfig;
+// do not allow mutation of default loaders. Make sure it is set inside options
 const defaultLoaders = Object.freeze({
     '.js': loaders_1.loaders.loadJs,
     '.json': loaders_1.loaders.loadJson,
@@ -211109,11 +211485,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.yaml = exports.yamlStringify = exports.yamlParse = void 0;
+// https://github.com/nodeca/js-yaml
 const yaml_1 = __importDefault(__webpack_require__(51381));
+// 解析 YAML 字符串
 const yamlParse = (doc) => {
     return yaml_1.default.parse(doc);
 };
 exports.yamlParse = yamlParse;
+// 导出为 YAML 字符串
 const yamlStringify = (object) => {
     return yaml_1.default.stringify(object);
 };
@@ -211651,8 +212030,11 @@ checkIndex: 检查索引是否存在`),
         title: "修改 NoSQL 数据库结构",
         description: "修改 NoSQL 数据库结构",
         inputSchema: {
-            action: zod_1.z.enum(["createCollection", "updateCollection", "deleteCollection"])
-                .describe(`createCollection: 创建集合
+            action: zod_1.z.enum([
+                "createCollection",
+                "updateCollection",
+                "deleteCollection",
+            ]).describe(`createCollection: 创建集合
 updateCollection: 更新集合
 deleteCollection: 删除集合`),
             collectionName: zod_1.z.string().describe("集合名称"),
@@ -211732,9 +212114,7 @@ deleteCollection: 删除集合`),
                 success: true,
                 requestId: result.RequestId,
                 action,
-                message: result.Exists === false
-                    ? "集合不存在"
-                    : "云开发数据库集合删除成功",
+                message: result.Exists === false ? "集合不存在" : "云开发数据库集合删除成功",
             };
             if (result.Exists === false) {
                 body.exists = false;
@@ -211765,9 +212145,17 @@ deleteCollection: 删除集合`),
                 .optional()
                 .describe("返回字段投影(对象或字符串,推荐对象)"),
             sort: zod_1.z
-                .union([zod_1.z.object({}).passthrough(), zod_1.z.string()])
+                .union([
+                zod_1.z.array(zod_1.z
+                    .object({
+                    key: zod_1.z.string().describe("sort 字段名"),
+                    direction: zod_1.z.number().describe("排序方向,1:升序,-1:降序"),
+                })
+                    .passthrough()),
+                zod_1.z.string(),
+            ])
                 .optional()
-                .describe("排序条件(对象或字符串,推荐对象)"),
+                .describe("排序条件，使用对象或字符串。"),
             limit: zod_1.z.number().optional().describe("返回数量限制"),
             offset: zod_1.z.number().optional().describe("跳过的记录数"),
         },
@@ -211813,7 +212201,8 @@ deleteCollection: 删除集合`),
         title: "修改 NoSQL 数据库数据记录",
         description: "修改 NoSQL 数据库数据记录",
         inputSchema: {
-            action: zod_1.z.enum(["insert", "update", "delete"])
+            action: zod_1.z
+                .enum(["insert", "update", "delete"])
                 .describe(`insert: 插入数据（新增文档）\nupdate: 更新数据\ndelete: 删除数据`),
             collectionName: zod_1.z.string().describe("集合名称"),
             documents: zod_1.z
@@ -217366,24 +217755,38 @@ const common_1 = __webpack_require__(96711);
 const coding_1 = __webpack_require__(40540);
 const web_1 = __webpack_require__(2240);
 const system_1 = __webpack_require__(62179);
-const CliAuthBaseUrl = 'https://tcb.cloud.tencent.com/dev#/cli-auth';
+const CliAuthBaseUrl = 'https://tcb.cloud.tencent.com/dev';
+// 打开云开发控制台，获取授权
 function getAuthTokenFromWeb(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const { getAuthUrl } = options;
+        const { getAuthUrl, noBrowser, callbackTimeout } = options;
         const mac = yield (0, system_1.getMacAddress)();
         const os = (0, system_1.getOSInfo)();
         const macHash = (0, coding_1.md5Encoding)(mac);
         const query = yield (0, web_1.getDataFromWeb)((port) => {
-            let cliAuthUrl = `${CliAuthBaseUrl}?port=${port}&hash=${macHash}&mac=${mac}&os=${os}&from=cli`;
+            const callbackUrl = `http://127.0.0.1:${port}`;
+            const encodedQuery = `port=${encodeURIComponent(String(port))}`
+                + `&hash=${encodeURIComponent(macHash)}`
+                + `&mac=${encodeURIComponent(mac)}`
+                + `&os=${encodeURIComponent(os)}`
+                + '&from=cli';
+            const encodedCallbackUrl = encodeURIComponent(callbackUrl);
+            // 授权链接
+            const rawAuthUrl = `${CliAuthBaseUrl}?authCallbackUrl=${encodedCallbackUrl}#/cli-auth?${encodedQuery}`;
+            let cliAuthUrl = rawAuthUrl;
             if (getAuthUrl) {
                 try {
-                    cliAuthUrl = getAuthUrl(`${CliAuthBaseUrl}?port=${port}&hash=${macHash}&mac=${mac}&os=${os}&from=cli`);
+                    cliAuthUrl = getAuthUrl(rawAuthUrl);
                 }
                 catch (error) {
+                    // 忽略错误
                 }
             }
             return cliAuthUrl;
-        }, 'login');
+        }, 'login', {
+            noBrowser,
+            callbackTimeout
+        });
         const credential = (0, common_1.resolveCredential)(query);
         return credential;
     });
@@ -218223,7 +218626,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.10.0" : 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.11.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -255443,6 +255846,7 @@ module.exports = exports
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.detectIndent = void 0;
+// https://github.com/sindresorhus/detect-indent/blob/master/index.js
 const INDENT_REGEX = /^(?:( )+|\t+)/;
 const INDENT_TYPE_SPACE = 'space';
 const INDENT_TYPE_TAB = 'tab';
@@ -255453,6 +255857,7 @@ function makeIndentsMap(string) {
     let key;
     for (const line of string.split(/\n/g)) {
         if (!line) {
+            // Ignore empty lines
             continue;
         }
         let indent;
@@ -255479,16 +255884,19 @@ function makeIndentsMap(string) {
             weight = 0;
             const indentDifference = indent - previousSize;
             previousSize = indent;
+            // Previous line have same indent?
             if (indentDifference === 0) {
                 weight++;
+                // We use the key from previous loop
             }
             else {
                 const absoluteIndentDifference = indentDifference > 0 ? indentDifference : -indentDifference;
                 key = encodeIndentsKey(indentType, absoluteIndentDifference);
             }
+            // Update the stats
             entry = indents.get(key);
             if (entry === undefined) {
-                entry = [1, 0];
+                entry = [1, 0]; // Init
             }
             else {
                 entry = [++entry[0], entry[1] + weight];
@@ -255498,16 +255906,20 @@ function makeIndentsMap(string) {
     }
     return indents;
 }
+// Encode the indent type and amount as a string (e.g. 's4') for use as a compound key in the indents Map.
 function encodeIndentsKey(indentType, indentAmount) {
     const typeCharacter = indentType === INDENT_TYPE_SPACE ? 's' : 't';
     return typeCharacter + String(indentAmount);
 }
+// Extract the indent type and amount from a key of the indents Map.
 function decodeIndentsKey(indentsKey) {
     const keyHasTypeSpace = indentsKey[0] === 's';
     const type = keyHasTypeSpace ? INDENT_TYPE_SPACE : INDENT_TYPE_TAB;
     const amount = Number(indentsKey.slice(1));
     return { type, amount };
 }
+// Return the key (e.g. 's4') from the indents Map that represents the most common indent,
+// or return undefined if there are no indents.
 function getMostUsedKey(indents) {
     let result;
     let maxUsed = 0;
@@ -256217,11 +256629,43 @@ exports.resetInteractiveServer = resetInteractiveServer;
 exports.getInteractiveServerSafe = getInteractiveServerSafe;
 const express_1 = __importDefault(__webpack_require__(26083));
 const http_1 = __importDefault(__webpack_require__(81630));
+const child_process_1 = __webpack_require__(79646);
 const open_1 = __importDefault(__webpack_require__(45368));
 const ws_1 = __webpack_require__(17699);
 const index_js_1 = __webpack_require__(79529);
 const logger_js_1 = __webpack_require__(13039);
-// 动态导入 open 模块，兼容 ESM/CJS 环境
+function isVSCodeEnvironment() {
+    return Boolean(process.env.VSCODE_IPC_HOOK_CLI ||
+        process.env.VSCODE_PID ||
+        process.env.TERM_PROGRAM === "vscode");
+}
+function parseBrowserCommand(browser) {
+    const parts = browser.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+    return parts.map((item) => item.replace(/^"(.*)"$/, "$1"));
+}
+async function openUrlByBrowserEnv(url) {
+    const browser = process.env.BROWSER?.trim();
+    if (!browser) {
+        return false;
+    }
+    const [command, ...args] = parseBrowserCommand(browser);
+    if (!command) {
+        return false;
+    }
+    const finalArgs = args.map((arg) => (arg === "%s" ? url : arg));
+    if (!args.includes("%s")) {
+        finalArgs.push(url);
+    }
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)(command, finalArgs, (execError) => {
+            resolve(!execError);
+        });
+    });
+}
+function shouldUseBrowserEnvFallback() {
+    return process.platform === "linux" && isVSCodeEnvironment();
+}
+// Dynamic open behavior with IDE awareness and VSCode/Linux fallback
 async function openUrl(url, options, mcpServer) {
     // mcpServer 是 ExtendedMcpServer 实例，它有 server 和 ide 属性
     // server 属性是 MCP server 的内部 server 实例，有 sendLoggingMessage 方法
@@ -256253,13 +256697,28 @@ async function openUrl(url, options, mcpServer) {
             return;
         }
     }
-    // 默认行为：直接打开网页
+    // 默认行为：直接打开网页（带 VSCode/Linux 降级逻辑）
     (0, logger_js_1.debug)(`[openUrl] Opening URL in browser: ${url}`);
     try {
-        return await (0, open_1.default)(url, options);
+        const openOptions = options ? { url: true, ...options } : { url: true };
+        const child = await (0, open_1.default)(url, openOptions);
+        if (child?.once) {
+            child.once("error", async () => {
+                if (shouldUseBrowserEnvFallback()) {
+                    (0, logger_js_1.debug)("[openUrl] open() failed, trying BROWSER fallback");
+                    await openUrlByBrowserEnv(url);
+                }
+            });
+        }
+        return;
     }
     catch (err) {
         (0, logger_js_1.error)(`Failed to open ${url} ${options} ${err instanceof Error ? err.message : err} `, err instanceof Error ? err : new Error(String(err)));
+        if (shouldUseBrowserEnvFallback()) {
+            (0, logger_js_1.debug)("[openUrl] open() threw, trying BROWSER fallback");
+            await openUrlByBrowserEnv(url);
+            return;
+        }
         (0, logger_js_1.warn)(`Please manually open: ${url}`);
     }
 }
@@ -256284,10 +256743,15 @@ class InteractiveServer {
         3722, 3723, 3724, 3725, 3726, 3727, 3728, 3729, 3730, 3731, 3732, 3733,
         3734, 3735,
     ];
+    /** Idle timeout for HTTP/WS connections (e.g. long login). Avoids "connection disconnected" after ~1 min. */
+    static SERVER_IDLE_MS = 30 * 60 * 1000; // 30 minutes
+    /** WebSocket ping interval to keep connection alive past proxies/firewalls. */
+    static WS_PING_INTERVAL_MS = 25 * 1000; // 25 seconds
     constructor(mcpServer) {
         this._mcpServer = mcpServer;
         this.app = (0, express_1.default)();
         this.server = http_1.default.createServer(this.app);
+        this.applyServerTimeouts();
         this.wss = new ws_1.WebSocketServer({ server: this.server });
         this.setupExpress();
         this.setupWebSocket();
@@ -256303,6 +256767,16 @@ class InteractiveServer {
             this.isRunning = false;
         }
     }
+    /** Apply timeouts so long-lived login does not cause "connection disconnected". */
+    applyServerTimeouts() {
+        this.server.timeout = 0;
+        if (typeof this.server.keepAliveTimeout === "number") {
+            this.server.keepAliveTimeout = InteractiveServer.SERVER_IDLE_MS;
+        }
+        if (typeof this.server.headersTimeout === "number") {
+            this.server.headersTimeout = Math.max(this.server.headersTimeout || 0, InteractiveServer.SERVER_IDLE_MS);
+        }
+    }
     setupExpress() {
         this.app.use(express_1.default.json());
         this.app.get("/env-setup/:sessionId", (req, res) => {
@@ -256406,6 +256880,16 @@ class InteractiveServer {
     setupWebSocket() {
         this.wss.on("connection", (ws) => {
             (0, logger_js_1.debug)("WebSocket client connected");
+            // Keep connection alive during long login so proxies/firewalls do not close it
+            const pingInterval = setInterval(() => {
+                if (ws.readyState === ws_1.WebSocket.OPEN) {
+                    ws.ping();
+                }
+            }, InteractiveServer.WS_PING_INTERVAL_MS);
+            ws.on("close", () => {
+                clearInterval(pingInterval);
+                (0, logger_js_1.debug)("WebSocket client disconnected");
+            });
             ws.on("message", async (message) => {
                 try {
                     const data = JSON.parse(message.toString());
@@ -256515,9 +256999,6 @@ class InteractiveServer {
                     (0, logger_js_1.error)("WebSocket message parsing error", err instanceof Error ? err : new Error(String(err)));
                 }
             });
-            ws.on("close", () => {
-                (0, logger_js_1.debug)("WebSocket client disconnected");
-            });
         });
     }
     async start() {
@@ -256559,13 +257040,15 @@ class InteractiveServer {
                         reject(err);
                     }
                 };
+                // Host: default 0.0.0.0 so Cloud IDE / VSCode Remote port-forward can connect; set INTERACTIVE_SERVER_HOST=127.0.0.1 for local-only
+                const host = process.env.INTERACTIVE_SERVER_HOST ?? "0.0.0.0";
                 // 设置成功监听处理
                 const listeningHandler = () => {
                     const address = this.server.address();
                     if (address && typeof address === "object") {
                         this.port = address.port;
                         this.isRunning = true;
-                        (0, logger_js_1.info)(`Interactive server started successfully on http://localhost:${this.port}`);
+                        (0, logger_js_1.info)(`Interactive server started successfully on http://${host}:${this.port}`);
                         // 移除临时监听器
                         this.server.removeListener("error", errorHandler);
                         this.server.removeListener("listening", listeningHandler);
@@ -256580,7 +257063,7 @@ class InteractiveServer {
                 this.server.once("error", errorHandler);
                 this.server.once("listening", listeningHandler);
                 try {
-                    this.server.listen(portToTry, "127.0.0.1");
+                    this.server.listen(portToTry, host);
                 }
                 catch (err) {
                     (0, logger_js_1.error)(`Failed to bind to port ${portToTry}:`, err instanceof Error ? err : new Error(String(err)));
@@ -256621,6 +257104,7 @@ class InteractiveServer {
                             this.port = 0;
                             // 重新创建整个服务器实例以便下次使用
                             this.server = http_1.default.createServer(this.app);
+                            this.applyServerTimeouts();
                             this.wss = new ws_1.WebSocketServer({ server: this.server });
                             this.setupWebSocket();
                             (0, logger_js_1.debug)("HTTP and WebSocket servers recreated for next use");
@@ -256711,11 +257195,9 @@ class InteractiveServer {
                 (0, logger_js_1.warn)(`Please manually open: ${url}`);
             }
             (0, logger_js_1.info)("Waiting for user selection...");
-            // Use shorter timeout for CodeBuddy when notification is sent (2 minutes)
-            // This prevents hanging while still giving users enough time to respond
-            // Otherwise use the default 10 minutes timeout
-            const timeoutDuration = (isCodeBuddy && notificationSent) ? 2 * 60 * 1000 : 10 * 60 * 1000;
-            (0, logger_js_1.debug)(`[collectEnvId] Using timeout duration: ${timeoutDuration / 1000} seconds (CodeBuddy: ${isCodeBuddy}, notification sent: ${notificationSent})`);
+            // Use same 10 minutes for all IDEs so long login (re-auth, switch account) does not close the server
+            const timeoutDuration = 10 * 60 * 1000;
+            (0, logger_js_1.debug)(`[collectEnvId] Using timeout duration: ${timeoutDuration / 1000} seconds`);
             return new Promise((resolve) => {
                 this.currentResolver = (result) => {
                     // 用户选择完成后，关闭服务器
@@ -274943,8 +275425,14 @@ const fs_1 = __importDefault(__webpack_require__(29021));
 const del_1 = __importDefault(__webpack_require__(62958));
 const make_dir_1 = __importDefault(__webpack_require__(55589));
 const error_1 = __webpack_require__(64119);
+/**
+ * 检查路径是否可以访问（读、写）
+ * @param dest 目标路径
+ * @param throwError 无权限时是否抛出异常
+ */
 function checkFullAccess(dest, throwError = false) {
     try {
+        // 可见、可写
         fs_1.default.accessSync(dest, fs_1.default.constants.F_OK);
         fs_1.default.accessSync(dest, fs_1.default.constants.W_OK);
         fs_1.default.accessSync(dest, fs_1.default.constants.R_OK);
@@ -274960,8 +275448,14 @@ function checkFullAccess(dest, throwError = false) {
     }
 }
 exports.checkFullAccess = checkFullAccess;
+/**
+ * 检查路径是否可以读
+ * @param dest 目标路径
+ * @param throwError 无权限时是否抛出异常
+ */
 function checkWritable(dest, throwError = false) {
     try {
+        // 可见、可写
         fs_1.default.accessSync(dest, fs_1.default.constants.F_OK);
         fs_1.default.accessSync(dest, fs_1.default.constants.W_OK);
         return true;
@@ -274976,8 +275470,14 @@ function checkWritable(dest, throwError = false) {
     }
 }
 exports.checkWritable = checkWritable;
+/**
+ * 检查路径是否可以写
+ * @param dest 目标路径
+ * @param throwError 无权限或路径不存在时是否抛出异常
+ */
 function checkReadable(dest, throwError = false) {
     try {
+        // 可见、可读
         fs_1.default.accessSync(dest, fs_1.default.constants.F_OK);
         fs_1.default.accessSync(dest, fs_1.default.constants.R_OK);
         return true;
@@ -274992,10 +275492,18 @@ function checkReadable(dest, throwError = false) {
     }
 }
 exports.checkReadable = checkReadable;
+/**
+ * 检查指定路径是否为文件夹
+ * @param dest 目标路径
+ */
 function isDirectorySync(dest) {
     return fs_1.default.statSync(dest).isDirectory();
 }
 exports.isDirectorySync = isDirectorySync;
+/**
+ * 检查指定路径是否为文件夹，异步
+ * @param dest 目标路径
+ */
 function isDirectoryAsync(dest) {
     return __awaiter(this, void 0, void 0, function* () {
         const stat = yield fs_1.default.promises.stat(dest);
@@ -275003,6 +275511,12 @@ function isDirectoryAsync(dest) {
     });
 }
 exports.isDirectoryAsync = isDirectoryAsync;
+/**
+ * 格式化文件大小，保留两位小数
+ * @param size 原数据，单位 Byte
+ * @param unit 目标单位，支持 KB、MB、GB、TB
+ * @param fixed 保留小数位数，默认 2 位
+ */
 function formateFileSize(size, unit, fixed) {
     const numSize = Number(size);
     const unitMap = {
@@ -275014,6 +275528,7 @@ function formateFileSize(size, unit, fixed) {
     return Number(numSize / unitMap[unit]).toFixed(fixed);
 }
 exports.formateFileSize = formateFileSize;
+// 创建文件夹
 function mkdirSync(dest) {
     make_dir_1.default.sync(dest);
 }
@@ -275024,6 +275539,7 @@ function mkdirAsync(dest) {
     });
 }
 exports.mkdirAsync = mkdirAsync;
+// 转换 Windows 下的反斜杠路径
 const slash = (input) => {
     const isExtendedLengthPath = /^\\\\\?\\/.test(input);
     if (isExtendedLengthPath) {
@@ -275032,8 +275548,10 @@ const slash = (input) => {
     return input.replace(/\\/g, '/');
 };
 exports.slash = slash;
+// 删除文件
 function delSync(patterns) {
     let paths;
+    // 不能再使用反斜杠，修复 Windows 下的问题 https://github.com/sindresorhus/del/releases/tag/v5.0.0
     if (Array.isArray(patterns)) {
         paths = patterns.map((item) => (0, exports.slash)(item));
     }
@@ -275732,8 +276250,10 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.resolveWebCredential = exports.resolveCredential = exports.checkAuth = void 0;
 const cloud_api_1 = __webpack_require__(2090);
 const config_1 = __webpack_require__(88472);
+// 调用 env:list 接口，检查密钥是否有效
 function checkAuth(credential, options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
+        // 兼容原临时秘钥
         const { secretId, secretKey, token } = resolveCredential(credential);
         const { proxy, timeout } = options;
         const region = yield (0, config_1.getRegion)();
@@ -275754,8 +276274,10 @@ function checkAuth(credential, options = {}) {
     });
 }
 exports.checkAuth = checkAuth;
+// 兼容解析旧的登录态
 function resolveCredential(data) {
     let { secretId, secretKey, token, accessTokenExpired, tmpSecretId, tmpSecretKey, tmpToken, tmpExpired, expired, authTime, refreshToken, uin, hash, envId } = data;
+    // 兼容旧的登录态信息
     token = token || tmpToken;
     secretId = secretId || tmpSecretId;
     secretKey = secretKey || tmpSecretKey;
@@ -281712,6 +282234,7 @@ function resolveCredentialFormEnv() {
         token
     };
 }
+// 获取 credential 数据
 function getCredentialData() {
     return __awaiter(this, void 0, void 0, function* () {
         const localData = (yield exports.authStore.get('credential'));
@@ -281720,6 +282243,7 @@ function getCredentialData() {
         const keys = Object.keys(credential)
             .filter((key) => credential[key])
             .filter((key) => key !== '-');
+        // 检查是否为空对象
         if (!credential || keys.length === 0) {
             return null;
         }
@@ -281727,6 +282251,7 @@ function getCredentialData() {
     });
 }
 exports.getCredentialData = getCredentialData;
+// 临时密钥过期后，进行续期
 function refreshTmpToken(metaData) {
     return __awaiter(this, void 0, void 0, function* () {
         const mac = yield (0, system_1.getMacAddress)();
@@ -281735,6 +282260,7 @@ function refreshTmpToken(metaData) {
         const credential = (0, common_1.resolveWebCredential)(metaData);
         const res = yield async_1.AsyncMerge.merge(() => (0, cloud_api_1.fetch)(refreshTokenUrl, {
             method: 'POST',
+            // 超时时间：15S
             timeout: 15000,
             body: JSON.stringify(credential),
             headers: { 'Content-Type': 'application/json' }
@@ -281758,6 +282284,7 @@ function refreshTmpToken(metaData) {
     });
 }
 exports.refreshTmpToken = refreshTmpToken;
+// 是否为 CAM 权限错误
 const isCamRefused = (e) => {
     return (Number(e.code) === 4102 ||
         Number(e.code) === 42 ||
@@ -281765,16 +282292,22 @@ const isCamRefused = (e) => {
         e.code === 'AuthFailure.UnauthorizedOperation');
 };
 exports.isCamRefused = isCamRefused;
+// 报错返回 null 值
 function wrapCheckAuth(credential, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const { timeout = 15000 } = options;
         try {
+            // 合并请求，避免超过接口限频
             yield async_1.AsyncMerge.merge(() => (0, common_1.checkAuth)(credential, options), 'checkAuth', {
+                // 超时时间不能小于发送请求的超时时间
                 timeout: Number(timeout) ? (timeout < 15000 ? 15000 : timeout + 1000) : 15000
             });
             return credential;
         }
         catch (e) {
+            // CAM 错误视为登录正常
+            // if (isCamRefused(e)) return credential;
+            // 请求超时
             if (e.type === 'request-timeout') {
                 throw new error_1.CloudBaseError('请求超时，请检查你的网络，如果终端无法直接访问公网，请设置终端 HTTP 请求代理！');
             }
@@ -281782,38 +282315,50 @@ function wrapCheckAuth(credential, options) {
         }
     });
 }
+// token 将在 n 分钟内过期
 const isTokenExpired = (credential, gap = 120) => credential.accessTokenExpired &&
     Number(credential.accessTokenExpired) < Date.now() + gap * 1000;
+// 获取身份认证信息并校验、自动刷新
 function checkAndGetCredential(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
+        // 从本地存储中读取 credential
         const credential = yield getCredentialData();
         if (!credential) {
             return null;
         }
+        // 存在临时密钥信息
         if (credential.refreshToken) {
+            // 临时密钥在 2 小时有效期内，可以直接使用
             if (!isTokenExpired(credential)) {
+                // 检查 credential
                 return wrapCheckAuth(credential, options);
             }
             else if (Date.now() < Number(credential.expired)) {
+                // 临时密钥超过两小时有效期，但在 1 个月 refresh 有效期内，刷新临时密钥
                 let refreshCredential;
                 try {
                     refreshCredential = yield refreshTmpToken(credential);
                 }
                 catch (e) {
+                    // 登录态失效
                     if (e.code === 'AUTH_FAIL') {
                         return null;
                     }
                     else if (e.code === 'InternalError.GetRoleError') {
+                        // 用户未开通服务，视为登录态失效
                         return null;
                     }
                     else {
+                        // 异常错误
                         throw e;
                     }
                 }
+                // 存储新的秘钥
                 yield exports.authStore.set('credential', refreshCredential || {});
                 return wrapCheckAuth((0, common_1.resolveCredential)(refreshCredential), options);
             }
         }
+        // 存在永久密钥
         if (credential.secretId && credential.secretKey) {
             return wrapCheckAuth(credential, options);
         }
@@ -281821,36 +282366,45 @@ function checkAndGetCredential(options = {}) {
     });
 }
 exports.checkAndGetCredential = checkAndGetCredential;
+// 获取身份认证信息，不校验
 function getCredentialWithoutCheck() {
     return __awaiter(this, void 0, void 0, function* () {
         const credential = yield getCredentialData();
         if (!credential) {
             return null;
         }
+        // 存在临时密钥信息
         if (credential.refreshToken) {
+            // 临时密钥在 2 小时有效期内，可以直接使用
             if (!isTokenExpired(credential)) {
                 return credential;
             }
             else if (Date.now() < Number(credential.expired)) {
+                // 临时密钥超过两小时有效期，但在 1 个月 refresh 有效期内，刷新临时密钥
                 let refreshCredential;
                 try {
                     refreshCredential = yield refreshTmpToken(credential);
                 }
                 catch (e) {
+                    // 登录态失效
                     if (e.code === 'AUTH_FAIL') {
                         return null;
                     }
                     else if (e.code === 'InternalError.GetRoleError') {
+                        // 用户未开通服务，视为登录态失效
                         return null;
                     }
                     else {
+                        // 异常错误
                         throw e;
                     }
                 }
+                // 存储新的秘钥
                 yield exports.authStore.set('credential', refreshCredential || {});
                 return (0, common_1.resolveCredential)(refreshCredential);
             }
         }
+        // 存在永久密钥
         if (credential.secretId && credential.secretKey) {
             return credential;
         }