@cloudbase/manager-node 4.11.0-alpha.1 → 4.11.0-alpha.10

package/lib/cloudApp/index.js

@@ -0,0 +1,243 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudAppService = void 0;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const error_1 = require("../error");
+const utils_1 = require("../utils");
+const http_request_1 = require("../utils/http-request");
+__exportStar(require("./types"), exports);
+/**
+ * CloudApp 统一部署服务
+ * 提供 Web 应用的创建、查询、删除、版本管理等功能
+ */
+class CloudAppService {
+    constructor(environment) {
+        this.environment = environment;
+        this.tcbService = new utils_1.CloudService(environment.cloudBaseContext, 'tcb', '2018-06-08');
+    }
+    // =========== 应用管理 API ===========
+    /**
+     * 创建/更新 CloudApp 应用
+     * @param params 创建参数
+     */
+    async createApp(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('CreateCloudApp', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    /**
+     * 获取 CloudApp 应用列表
+     * @param params 查询参数
+     */
+    async describeAppList(params) {
+        const { envId } = this.getEnvInfo();
+        return this.tcbService.request('DescribeCloudAppList', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    /**
+     * 获取 CloudApp 应用详情
+     * @param params 查询参数
+     */
+    async describeAppInfo(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('DescribeCloudAppInfo', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    /**
+     * 删除 CloudApp 应用
+     * @param params 删除参数
+     */
+    async deleteApp(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('DeleteCloudApp', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    // =========== 版本管理 API ===========
+    /**
+     * 获取 CloudApp 版本详情
+     * 不指定 versionName 或 buildId 时返回最新版本
+     * @param params 查询参数
+     */
+    async describeAppVersion(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('DescribeCloudAppVersion', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    /**
+     * 获取 CloudApp 版本列表
+     * @param params 查询参数
+     */
+    async describeAppVersionList(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('DescribeCloudAppVersionList', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    /**
+     * 删除 CloudApp 版本
+     * @param params 删除参数
+     */
+    async deleteAppVersion(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType', 'versionName']);
+        return this.tcbService.request('DeleteCloudAppVersion', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId })));
+    }
+    // =========== COS 上传相关 API ===========
+    /**
+     * 获取 CloudApp COS 上传信息（预签名 URL）
+     * @param params 查询参数
+     */
+    async describeCosInfo(params) {
+        const { envId } = this.getEnvInfo();
+        this.validateRequiredParams(params, ['serviceName', 'deployType']);
+        return this.tcbService.request('DescribeCloudAppCosInfo', (0, utils_1.upperCaseObjKey)(Object.assign(Object.assign({}, params), { envId: params.envId || envId, suffix: params.suffix || '.zip' })));
+    }
+    // =========== 辅助方法 ===========
+    /**
+     * 上传本地代码到 COS
+     * 自动打包 ZIP 并上传到预签名 URL
+     *
+     * 注意：此方法不依赖应用是否已创建，可在创建应用前调用
+     * 返回的 cosTimestamp 用于 createApp 时传入 staticConfig.cosTimestamp
+     *
+     * @param params 上传参数
+     */
+    async uploadCode(params) {
+        const { serviceName, localPath, ignore = [] } = params;
+        // 1. 验证本地路径
+        if (!fs_1.default.existsSync(localPath)) {
+            throw new error_1.CloudBaseError(`本地路径不存在: ${localPath}`);
+        }
+        const stat = fs_1.default.statSync(localPath);
+        if (!stat.isDirectory()) {
+            throw new error_1.CloudBaseError(`localPath 必须是目录: ${localPath}`);
+        }
+        // 2. 打包本地文件为 ZIP
+        const tmpZipPath = path_1.default.join(os_1.default.tmpdir(), `cloudapp-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`);
+        const defaultIgnore = ['node_modules/**', '.git/**', '.DS_Store', '**/.DS_Store'];
+        await (0, utils_1.compressToZip)({
+            dirPath: localPath,
+            outputPath: tmpZipPath,
+            ignore: [...defaultIgnore, ...ignore]
+        });
+        try {
+            // 3. 获取上传凭证
+            const cosInfo = await this.describeCosInfo({
+                deployType: params.deployType,
+                serviceName,
+                suffix: '.zip'
+            });
+            // 4. 读取 ZIP 文件
+            const zipBuffer = fs_1.default.readFileSync(tmpZipPath);
+            // 5. 构建请求头
+            const headers = {
+                'Content-Type': 'application/zip'
+            };
+            if (cosInfo.UploadHeaders && cosInfo.UploadHeaders.length > 0) {
+                for (const h of cosInfo.UploadHeaders) {
+                    headers[h.Key] = h.Value;
+                }
+            }
+            // 6. 使用预签名 URL 上传
+            const response = await (0, http_request_1.fetchStream)(cosInfo.UploadUrl, {
+                method: 'PUT',
+                body: zipBuffer,
+                headers
+            });
+            if (!response.ok) {
+                let errorDetail = '';
+                try {
+                    const responseText = await response.text();
+                    errorDetail = responseText ? ` - ${responseText.substring(0, 500)}` : '';
+                }
+                catch (_a) {
+                    // 解析失败时 errorDetail 保持空串，不影响主错误抛出
+                }
+                throw new error_1.CloudBaseError(`上传失败: ${response.status} ${response.statusText}${errorDetail}`);
+            }
+            // 7. 返回结果（返回 cosTimestamp，用于创建应用）
+            return {
+                cosTimestamp: cosInfo.UnixTimestamp,
+                unixTimestamp: cosInfo.UnixTimestamp
+            };
+        }
+        finally {
+            // 8. 清理临时文件
+            if (fs_1.default.existsSync(tmpZipPath)) {
+                fs_1.default.unlinkSync(tmpZipPath);
+            }
+        }
+    }
+    /**
+     * 获取环境信息
+     */
+    getEnvInfo() {
+        const envConfig = this.environment.lazyEnvironmentConfig;
+        return {
+            envId: envConfig.EnvId
+        };
+    }
+    /**
+     * 校验必填参数
+     * @param params 参数对象
+     * @param fields 必填字段列表
+     */
+    validateRequiredParams(params, fields) {
+        for (const field of fields) {
+            if (!params[field]) {
+                throw new error_1.CloudBaseError(`${field} 是必填参数`);
+            }
+        }
+    }
+}
+exports.CloudAppService = CloudAppService;
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "createApp", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "describeAppList", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "describeAppInfo", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "deleteApp", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "describeAppVersion", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "describeAppVersionList", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "deleteAppVersion", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "describeCosInfo", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudAppService.prototype, "uploadCode", null);

package/lib/cloudApp/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * CloudApp 统一部署服务类型定义
+ * 支持 static-hosting（静态托管）和 http-function（预留）两种部署类型
+ *
+ * 命名规范：
+ * - 入参接口（IXxxParams）：camelCase，通过 upperCaseObjKey 转换后透传给 API
+ * - 返回值接口（IXxxResult）：PascalCase，与 API 响应字段保持一致
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/database/index.js

@@ -217,6 +217,70 @@ class DatabaseService {
         }
         return this.dbOpService.request('DatabaseMigrateExport', Object.assign({ CollectionName: collectionName, FilePath: filePath, FileType: fileType, EnvId: this.envId }, options));
     }
+    /**
+     * 获取可回档表格
+     * @param time 回档时间，格式 YYYY-MM-DD HH:MM:SS
+     * @param filters 过滤器（可选）
+     * @param instanceId 实例ID（可选，不传则自动使用当前环境的数据库实例 ID）
+     * @returns 可回档表格列表
+     */
+    async describeRestoreTables(time, filters, instanceId) {
+        const { Tag } = this.getDatabaseConfig();
+        const params = {
+            InstanceId: instanceId || Tag,
+            Time: time
+        };
+        if (filters && filters.length > 0) {
+            params.Filters = filters;
+        }
+        return this.dbOpService.request('DescribeRestoreTables', params);
+    }
+    /**
+     * 获取回档任务
+     * @param instanceId 实例ID（可选，不传则自动使用当前环境的数据库实例 ID）
+     * @returns 回档任务列表
+     */
+    async describeRestoreTask(instanceId) {
+        const { Tag } = this.getDatabaseConfig();
+        return this.dbOpService.request('DescribeRestoreTask', {
+            InstanceId: instanceId || Tag
+        });
+    }
+    /**
+     * 获取可回档时间
+     * @param instanceId 实例ID（可选，不传则自动使用当前环境的数据库实例 ID）
+     * @returns 可回档时间列表及任意时间回档列表
+     */
+    async describeRestoreTime(instanceId) {
+        const { Tag } = this.getDatabaseConfig();
+        return this.dbOpService.request('DescribeRestoreTime', {
+            InstanceId: instanceId || Tag
+        });
+    }
+    /**
+     * 实例表格回档
+     * @param time 回档时间，格式 YYYY-MM-DD HH:MM:SS
+     * @param modifyTableNamesInfo 回档表格信息（原表名 → 新表名映射）
+     * @param instanceId 实例ID（可选，不传则自动使用当前环境的数据库实例 ID）
+     * @returns 流程ID
+     */
+    async restoreTables(time, modifyTableNamesInfo, instanceId) {
+        const { Tag } = this.getDatabaseConfig();
+        return this.dbOpService.request('RestoreTCBTables', {
+            InstanceId: instanceId || Tag,
+            Time: time,
+            ModifyTableNamesInfo: modifyTableNamesInfo
+        });
+    }
+    /**
+     * 执行文档型数据库命令
+     * @param options 命令参数（命令列表、可选的 Tag/EnvId/MongoConnector）
+     * @returns 执行结果，Data 为 JSON 字符串数组
+     */
+    async runCommands(options) {
+        let { Tag } = this.getDatabaseConfig();
+        return this.dbOpService.request('RunCommands', Object.assign({ MgoCommands: options.MgoCommands, Tag: options.Tag || Tag, EnvId: options.EnvId || this.envId }, (options.MongoConnector ? { MongoConnector: options.MongoConnector } : {})));
+    }
 }
 exports.DatabaseService = DatabaseService;
 DatabaseService.tcbServiceVersion = {
@@ -242,3 +306,18 @@ __decorate([
 __decorate([
     preLazy()
 ], DatabaseService.prototype, "listCollections", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describeRestoreTables", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describeRestoreTask", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describeRestoreTime", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "restoreTables", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "runCommands", null);

package/lib/docs/index.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsService = void 0;
+const http_request_1 = require("../utils/http-request");
+const DOCS_BASE_URL = 'https://docs.cloudbase.net';
+const CATEGORY_URL = `${DOCS_BASE_URL}/category.json`;
+const ALGOLIA_SEARCH_URL = 'https://70wjvl90pg-dsn.algolia.net/1/indexes/*/queries' +
+    '?x-algolia-agent=Algolia%20for%20JavaScript%20(4.19.1)%3B%20Browser%20(lite)%3B%20docsearch%20(3.6.1)%3B%20docsearch-react%20(3.6.1)%3B%20docusaurus%20(2.4.3)' +
+    '&x-algolia-api-key=69281afd904cb72b399c92fb62b3ce25' +
+    '&x-algolia-application-id=70WJVL90PG';
+const ALGOLIA_SEARCH_PARAMS = 'attributesToRetrieve=["hierarchy.lvl0","hierarchy.lvl1","hierarchy.lvl2","hierarchy.lvl3","hierarchy.lvl4","hierarchy.lvl5","hierarchy.lvl6","content","type","url"]' +
+    '&attributesToSnippet=["hierarchy.lvl1:10","hierarchy.lvl2:10","hierarchy.lvl3:10","hierarchy.lvl4:10","hierarchy.lvl5:10","hierarchy.lvl6:10","content:10"]' +
+    '&snippetEllipsisText=\u2026' +
+    '&highlightPreTag=<mark>&highlightPostTag=</mark>' +
+    '&hitsPerPage=20' +
+    '&clickAnalytics=false' +
+    '&facetFilters=["language:zh-Hans",["docusaurus_tag:default","docusaurus_tag:docs-default-current"]]';
+class DocsService {
+    async listModules() {
+        const category = await this.getCategory();
+        // 列出所有二级目录模块
+        const modules = new Set();
+        for (const topModule of Object.values(category)) {
+            if (typeof topModule === 'object') {
+                for (const key of Object.keys(topModule)) {
+                    modules.add(key);
+                }
+            }
+        }
+        return Array.from(modules).sort();
+    }
+    /**
+     * Case: tcb docs read 快速开始
+     * 根据模块名获取该模块下的所有文档（返回嵌套的对象结构）
+     */
+    async listModuleDocs(moduleName) {
+        const category = await this.getCategory();
+        // 先尝试直接匹配顶级模块
+        const moduleData = category[moduleName];
+        if (moduleData !== undefined) {
+            return moduleData;
+        }
+        // 递归搜索嵌套模块
+        const found = this.findNestedModule(category, moduleName);
+        if (found) {
+            return found;
+        }
+        throw new Error(`Module "${moduleName}" not found`);
+    }
+    /**
+     * Case: tcb docs read <任意输入>
+     * 统一的查找入口，自动识别输入格式并返回模块数据或文档URL
+     *
+     * 支持的输入格式：
+     * 1. URL路径格式（包含 /，相对或完整）: tcb docs read quick-start/create-env
+     * 2. 点分隔路径: tcb docs read 云托管.快速开始..NET 快速开始
+     * 3. 模块名: tcb docs read 快速开始 「命中第一个 底下其他同理」
+     * 4. 嵌套模块名: tcb docs read 微信生态（嵌套在"社区.最佳实践"下）
+     * 5. 文档标题: tcb docs read 小程序快速开始
+     * 6. 前缀模糊匹配: tcb docs read PHP（匹配 "PHP 快速开始"）
+     */
+    async findByName(input) {
+        const category = await this.getCategory();
+        // 模式1: URL路径格式（包含 /），直接作为文档URL返回
+        if (input.includes('/')) {
+            // 直接返回 URL 路径，交给 readDoc 处理
+            return { type: 'doc', data: input };
+        }
+        // 模式2: 点分隔的层级导航，如 "云托管.快速开始..NET 快速开始" 处理多点情况
+        if (input.includes('.')) {
+            const result = this.findByDotPath(category, input);
+            if (result) {
+                return result;
+            }
+            throw new Error(`未找到模块或文档 "${input}"`);
+        }
+        // 模式3: 模块名查找（顶级或嵌套）复用上面已获取的 category
+        const topLevelModule = category[input];
+        if (topLevelModule && typeof topLevelModule === 'object') {
+            return { type: 'module', data: topLevelModule };
+        }
+        const nestedModule = this.findNestedModule(category, input);
+        if (nestedModule) {
+            return { type: 'module', data: nestedModule };
+        }
+        // 模式4: 文档标题精确搜索
+        const docPath = this.findDocPathByTitle(category, input);
+        if (docPath) {
+            return { type: 'doc', data: docPath };
+        }
+        // 模式5: 前缀模糊搜索（处理含空格的 key 被命令行截断的情况）
+        const prefixResult = this.findByKeyPrefix(category, input);
+        if (prefixResult) {
+            return prefixResult;
+        }
+        throw new Error(`未找到模块或文档 "${input}"`);
+    }
+    async readDoc(docPath) {
+        const normalizedPath = docPath.endsWith('.md') ? docPath : `${docPath}/index.md`;
+        // 支持完整URL和相对路径
+        const url = normalizedPath.startsWith('http') ? normalizedPath : `${DOCS_BASE_URL}/${normalizedPath}`;
+        const res = await (0, http_request_1.fetchStream)(url);
+        let text = await res.text();
+        // 移除 UTF-8 BOM
+        if (text.charCodeAt(0) === 0xFEFF) {
+            text = text.slice(1);
+        }
+        return text;
+    }
+    async searchDocs(query) {
+        var _a, _b, _c;
+        const body = JSON.stringify({
+            requests: [
+                {
+                    query,
+                    indexName: 'cloudbase',
+                    params: ALGOLIA_SEARCH_PARAMS
+                }
+            ]
+        });
+        const res = await (0, http_request_1.fetch)(ALGOLIA_SEARCH_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body
+        });
+        const hits = (_c = (_b = (_a = res === null || res === void 0 ? void 0 : res.results) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.hits) !== null && _c !== void 0 ? _c : [];
+        return hits.map((hit) => {
+            var _a, _b;
+            const levels = ['lvl6', 'lvl5', 'lvl4', 'lvl3', 'lvl2', 'lvl1', 'lvl0'];
+            const title = (_a = levels.map(l => { var _a; return (_a = hit.hierarchy) === null || _a === void 0 ? void 0 : _a[l]; }).find(Boolean)) !== null && _a !== void 0 ? _a : '';
+            return {
+                url: hit.url,
+                title,
+                content: (_b = hit.content) !== null && _b !== void 0 ? _b : null
+            };
+        });
+    }
+    async getCategory() {
+        return (0, http_request_1.fetch)(CATEGORY_URL);
+    }
+    // Case: tcb docs read PHP（模糊匹配出 "PHP 快速开始"，处理命令行空格截断问题）
+    // 在整棵树中查找以 prefix + 空格 开头的唯一 key
+    findByKeyPrefix(node, prefix) {
+        if (typeof node === 'string') {
+            return null;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key.startsWith(prefix + ' ')) {
+                if (typeof value === 'string') {
+                    return { type: 'doc', data: value };
+                }
+                else if (typeof value === 'object') {
+                    return { type: 'module', data: value };
+                }
+            }
+            if (typeof value === 'object') {
+                const found = this.findByKeyPrefix(value, prefix);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    }
+    // Case: tcb docs read 云托管.快速开始..NET 快速开始
+    // 使用贪心匹配策略：优先匹配最长的 key（避免 ".NET" 被错误分割）按分隔路径查找
+    // 若从根节点无法匹配，则在整棵树中深度优先搜索，支持输入中间路径段
+    findByDotPath(category, dotPath) {
+        const rootResult = this.matchDotPath(category, dotPath);
+        if (rootResult) {
+            return rootResult;
+        }
+        return this.searchDotPathInTree(category, dotPath);
+    }
+    // 从每个子节点尝试匹配 dotPath 支持中间路径段搜索
+    searchDotPathInTree(node, dotPath) {
+        if (typeof node !== 'object' || node === null) {
+            return null;
+        }
+        for (const value of Object.values(node)) {
+            if (typeof value === 'object' && value !== null) {
+                const result = this.matchDotPath(value, dotPath);
+                if (result) {
+                    return result;
+                }
+                const nested = this.searchDotPathInTree(value, dotPath);
+                if (nested) {
+                    return nested;
+                }
+            }
+        }
+        return null;
+    }
+    // 递归匹配点分隔路径
+    matchDotPath(node, remainingPath) {
+        if (!remainingPath) {
+            if (typeof node === 'string') {
+                return { type: 'doc', data: node };
+            }
+            else if (typeof node === 'object' && node !== null) {
+                return { type: 'module', data: node };
+            }
+            return null;
+        }
+        // 当前节点不是对象，无法继续匹配
+        if (typeof node !== 'object' || node === null) {
+            return null;
+        }
+        // 获取所有 key，按长度降序排序（贪心策略：优先匹配长 key）
+        const keys = Object.keys(node).sort((a, b) => b.length - a.length);
+        for (const key of keys) {
+            // 情况1: 完全匹配（路径末尾）
+            if (remainingPath === key) {
+                const value = node[key];
+                if (typeof value === 'string') {
+                    return { type: 'doc', data: value };
+                }
+                else if (typeof value === 'object') {
+                    return { type: 'module', data: value };
+                }
+            }
+            // 情况2: 前缀匹配（还有下级路径）
+            if (remainingPath.startsWith(key + '.')) {
+                const nextPath = remainingPath.slice(key.length + 1);
+                const result = this.matchDotPath(node[key], nextPath);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+        // 情况3: 模糊前缀匹配（key 含空格，命令行未加引号时 remainingPath 被空格截断）
+        // 例如: remainingPath = "PHP" 匹配 key = "PHP 快速开始" 避免含空格时无法匹配 case：云托管.快速开始.PHP 快速开始
+        // 仅在 remainingPath 不含点时使用（确保是最后一个路径段）
+        if (!remainingPath.includes('.')) {
+            const fuzzyMatches = keys.filter(k => k.startsWith(remainingPath + ' '));
+            if (fuzzyMatches.length === 1) {
+                const value = node[fuzzyMatches[0]];
+                if (typeof value === 'string') {
+                    return { type: 'doc', data: value };
+                }
+                else if (typeof value === 'object') {
+                    return { type: 'module', data: value };
+                }
+            }
+        }
+        return null;
+    }
+    // Case: tcb docs read 微信生态（"微信生态"是嵌套在"社区/最佳实践"下的二级模块）
+    // 递归查找嵌套模块（不一定是顶级key）
+    findNestedModule(node, targetName) {
+        if (typeof node === 'string') {
+            return null;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key === targetName && typeof value === 'object') {
+                return value;
+            }
+            // 继续递归搜索
+            if (typeof value === 'object') {
+                const found = this.findNestedModule(value, targetName);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    }
+    // Case: tcb docs read 小程序快速开始（通过文档标题精确查找）
+    // 递归查找文档路径（匹配key而不是value）
+    findDocPathByTitle(node, targetTitle) {
+        if (typeof node === 'string') {
+            return null;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key === targetTitle && typeof value === 'string') {
+                return value;
+            }
+            if (typeof value === 'object') {
+                const found = this.findDocPathByTitle(value, targetTitle);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    }
+}
+exports.DocsService = DocsService;

package/lib/docs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });