@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/captcha.d.mts

@@ -0,0 +1,259 @@
+import { XCache } from "./cache.mjs";
+import { MsValue } from "vtils";
+/**
+ * {@link XCaptcha} 的配置项。
+ */
+export interface XCaptchaOptions {
+  /**
+   * 缓存服务实例。
+   *
+   * 用于保存与读取验证码数据：生成时写入，校验时按 token 读取。建议为验证码
+   * 单独使用一个 {@link XCache} 实例，便于统一管理前缀、TTL 与序列化方式，
+   * 避免与其他业务缓存相互干扰。
+   */
+  cache: XCache;
+}
+/**
+ * 验证码字符集。
+ *
+ * 由若干字符段组合而成，各字符段含义：
+ * - `0`：数字 0-9；
+ * - `1`：数字 1-9（不含 0）；
+ * - `a` / `z`：小写字母 a-z；
+ * - `A` / `Z`：大写字母 A-Z。
+ *
+ * 完整取值：
+ * - `09`：0-9；
+ * - `19`：1-9；
+ * - `az`：小写字母；
+ * - `AZ`：大写字母；
+ * - `aZ`：小写 + 大写字母；
+ * - `0z`：0-9 + 小写字母；
+ * - `0Z`：0-9 + 小写 + 大写字母；
+ * - `1z`：1-9 + 小写字母；
+ * - `1Z`：1-9 + 小写 + 大写字母。
+ */
+export type XCaptchaGenerateCharset = '09' | '19' | 'az' | 'AZ' | 'aZ' | '0z' | '0Z' | '1z' | '1Z';
+/**
+ * {@link XCaptcha.generate} 与 {@link XCaptcha.generateDataUrl} 的入参。
+ */
+export interface XCaptchaGeneratePayload<T> {
+  /**
+   * 场景值。
+   *
+   * 用于区分验证码用途，防止后台验证码图片登录时误用其他场景（如短信）
+   * 下生成的验证码。校验时场景值不一致会直接判定失败。
+   */
+  scene: string;
+  /**
+   * 验证码长度，即生成的字符个数，应为正整数。
+   */
+  size: number;
+  /**
+   * 验证码存活时长。
+   *
+   * 与 `vtils` 的 `ms` 解析规则一致，可为毫秒数或时间字符串
+   * （如 `'5m'`、`'10s'`）。到期后验证码自动失效。
+   */
+  ttl: MsValue;
+  /**
+   * 字符集，决定验证码由哪些字符组成。
+   */
+  charset: XCaptchaGenerateCharset;
+  /**
+   * 可重试次数。
+   *
+   * - 大于 0：每次校验（无论成败）扣减一次，扣到 0 后验证码失效；
+   * - 等于 0：首次校验（无论成败）后即失效；
+   * - 缺省为 0。
+   */
+  retryCount?: number;
+  /**
+   * 其他附加信息。
+   *
+   * 随验证码一起写入缓存，校验时可通过
+   * {@link XCaptchaVerifyOptions.extra} 自定义比对逻辑。
+   */
+  extra?: T;
+}
+/**
+ * {@link XCaptcha.generate} 的返回结果。
+ */
+export interface XCaptchaGenerateResult {
+  /**
+   * 校验凭证。
+   *
+   * 随机生成且 URL 友好，用于在缓存中定位验证码；校验时需原样传回。
+   */
+  token: string;
+  /**
+   * 生成的验证码明文。
+   *
+   * 主要用于调试或日志；生产环境通常只向客户端返回图片
+   * （见 {@link XCaptchaGenerateDataUrlResult.dataUrl}），不应回传明文。
+   */
+  code: string;
+}
+/**
+ * {@link XCaptcha.generateDataUrl} 的返回结果。
+ */
+export interface XCaptchaGenerateDataUrlResult {
+  /**
+   * 校验凭证，语义同 {@link XCaptchaGenerateResult.token}。
+   */
+  token: string;
+  /**
+   * 生成的验证码明文，语义同 {@link XCaptchaGenerateResult.code}。
+   */
+  code: string;
+  /**
+   * 验证码图片的 Data URL。
+   *
+   * 形如 `data:image/svg+xml,...`，可直接作为 `<img>` 的 `src` 展示。
+   */
+  dataUrl: string;
+}
+/**
+ * {@link XCaptcha.verify} 的入参。
+ */
+export interface XCaptchaVerifyOptions<T> {
+  /**
+   * 校验凭证，来自生成结果中的 `token`。
+   */
+  token: string;
+  /**
+   * 待校验的验证码明文。
+   */
+  code: string;
+  /**
+   * 场景值，须与生成时一致。
+   */
+  scene: string;
+  /**
+   * 附加信息比对函数。
+   *
+   * 接收生成时存入缓存的 `extra`，返回是否通过。仅在场景值与验证码均通过
+   * 后才会执行；缺省时不校验附加信息。若生成时未提供 `extra`，回调入参为
+   * `undefined`。
+   */
+  extra?: (extra: T) => boolean;
+}
+/**
+ * 验证码生成与校验工具。
+ *
+ * 提供两种生成方式：
+ * - {@link XCaptcha.generate}：仅生成验证码文本，适合短信、邮件等无需图片的
+ *   场景；
+ * - {@link XCaptcha.generateDataUrl}：生成验证码文本与 SVG 图片 Data URL，
+ *   适合 Web 页面图片验证码。
+ *
+ * 生成时按指定字符集与长度随机拼接验证码，并将验证码明文、场景值、可重试
+ * 次数与附加信息一并写入缓存；校验时依次检查：
+ * 1. token 是否存在；
+ * 2. 场景值是否一致；
+ * 3. 验证码是否一致（大小写不敏感）；
+ * 4. 附加信息是否通过（可选）。
+ *
+ * 任意一项不通过即返回 `false`，且每次校验都会消耗一次重试次数或使验证码
+ * 失效（见 {@link XCaptchaGeneratePayload.retryCount}）。
+ *
+ * @example
+ * const captcha = new XCaptcha({ cache });
+ *
+ * const { token, code, dataUrl } = await captcha.generateDataUrl({
+ *   scene: 'login',
+ *   size: 4,
+ *   ttl: '5m',
+ *   charset: '09',
+ *   retryCount: 3,
+ * });
+ * // dataUrl 形如 'data:image/svg+xml,...'
+ *
+ * await captcha.verify({ token, code, scene: 'login' });
+ * // true
+ */
+export declare class XCaptcha {
+  private readonly cache;
+  /**
+   * 创建验证码工具实例。
+   *
+   * @param options 配置项，包含缓存服务实例。
+   */
+  constructor(options: XCaptchaOptions);
+  /**
+   * 各字符集对应的字符数组。
+   *
+   * 键为 {@link XCaptchaGenerateCharset} 取值，值为可从中随机取样的字符列表；
+   * `generate` 从中逐个 `sample`，`generateDataUrl` 则将其拼接为 svg-captcha
+   * 的 `charPreset`。
+   */
+  private charsetMap;
+  /**
+   * 生成验证码文本。
+   *
+   * 从 {@link XCaptchaGeneratePayload.charset} 对应的字符集中随机抽取
+   * `size` 个字符组成验证码，与场景值、可重试次数、附加信息一起写入缓存，
+   * 并返回缓存 token 与验证码明文。
+   *
+   * 适用于短信、邮件等不需要图片的验证码场景；若需要图片请使用
+   * {@link XCaptcha.generateDataUrl}。
+   *
+   * @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+   * @returns 包含 `token` 与验证码明文 `code` 的结果对象。
+   *
+   * @example
+   * const { token, code } = await captcha.generate({
+   *   scene: 'sms-login',
+   *   size: 6,
+   *   ttl: '5m',
+   *   charset: '09',
+   * });
+   * // token 形如 'X__xxxx'，code 为 6 位数字
+   */
+  generate<T extends Record<string, any>>(payload: XCaptchaGeneratePayload<T>): Promise<XCaptchaGenerateResult>;
+  /**
+   * 生成验证码文本与 SVG 图片 Data URL。
+   *
+   * 使用 svg-captcha 依据 {@link XCaptchaGeneratePayload.charset} 与 `size`
+   * 生成图片，并将验证码文本按与 {@link XCaptcha.generate} 相同的规则写入
+   * 缓存；随后将 SVG 转为 Data URL 一并返回。
+   *
+   * 适用于 Web 页面图片验证码，`dataUrl` 可直接作为 `<img>` 的 `src`。
+   *
+   * @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+   * @returns 包含 `token`、验证码明文 `code` 与图片 `dataUrl` 的结果对象。
+   *
+   * @example
+   * const { token, dataUrl } = await captcha.generateDataUrl({
+   *   scene: 'login',
+   *   size: 4,
+   *   ttl: '5m',
+   *   charset: 'aZ',
+   * });
+   * // dataUrl 形如 'data:image/svg+xml,...'
+   */
+  generateDataUrl<T extends Record<string, any>>(payload: XCaptchaGeneratePayload<T>): Promise<XCaptchaGenerateDataUrlResult>;
+  /**
+   * 校验验证码。
+   *
+   * 按顺序执行以下检查，任意一项不通过即返回 `false`：
+   * 1. token 存在：缓存中找不到 token 对应数据时直接失败；
+   * 2. 场景一致：`scene` 与生成时不一致时失败，防止跨场景误用；
+   * 3. 验证码一致：`code` 与生成时一致（大小写不敏感）；
+   * 4. 附加信息：提供了 `extra` 时执行其回调，返回 `false` 则失败。
+   *
+   * 注意：每次校验（无论最终是否通过）都会消耗一次重试次数——可重试次数
+   * 大于 0 时扣减并写回缓存，等于 0 时直接删除缓存，此后该 token 不可再用。
+   *
+   * @param options 校验参数，包含 token、验证码明文、场景值与可选的附加信息
+   *   比对函数。
+   * @returns 校验是否通过。
+   *
+   * @example
+   * await captcha.verify({ token, code, scene: 'login' });
+   * // true
+   * await captcha.verify({ token, code, scene: 'login' });
+   * // false：该 token 已失效
+   */
+  verify<T extends Record<string, any>>(options: XCaptchaVerifyOptions<T>): Promise<boolean>;
+}

package/lib/captcha.mjs

@@ -0,0 +1,174 @@
+import { sample } from "vtils";
+import svgToDataUrl from "mini-svg-data-uri";
+import svgCaptcha from "svg-captcha";
+// src/captcha.ts
+/**
+* 验证码生成与校验工具。
+*
+* 提供两种生成方式：
+* - {@link XCaptcha.generate}：仅生成验证码文本，适合短信、邮件等无需图片的
+*   场景；
+* - {@link XCaptcha.generateDataUrl}：生成验证码文本与 SVG 图片 Data URL，
+*   适合 Web 页面图片验证码。
+*
+* 生成时按指定字符集与长度随机拼接验证码，并将验证码明文、场景值、可重试
+* 次数与附加信息一并写入缓存；校验时依次检查：
+* 1. token 是否存在；
+* 2. 场景值是否一致；
+* 3. 验证码是否一致（大小写不敏感）；
+* 4. 附加信息是否通过（可选）。
+*
+* 任意一项不通过即返回 `false`，且每次校验都会消耗一次重试次数或使验证码
+* 失效（见 {@link XCaptchaGeneratePayload.retryCount}）。
+*
+* @example
+* const captcha = new XCaptcha({ cache });
+*
+* const { token, code, dataUrl } = await captcha.generateDataUrl({
+*   scene: 'login',
+*   size: 4,
+*   ttl: '5m',
+*   charset: '09',
+*   retryCount: 3,
+* });
+* // dataUrl 形如 'data:image/svg+xml,...'
+*
+* await captcha.verify({ token, code, scene: 'login' });
+* // true
+*/
+var XCaptcha = class {
+	cache;
+	/**
+	* 创建验证码工具实例。
+	*
+	* @param options 配置项，包含缓存服务实例。
+	*/
+	constructor(options) {
+		this.cache = options.cache;
+	}
+	/**
+	* 各字符集对应的字符数组。
+	*
+	* 键为 {@link XCaptchaGenerateCharset} 取值，值为可从中随机取样的字符列表；
+	* `generate` 从中逐个 `sample`，`generateDataUrl` 则将其拼接为 svg-captcha
+	* 的 `charPreset`。
+	*/
+	charsetMap = {
+		"09": "0123456789".split(""),
+		"19": "123456789".split(""),
+		az: "abcdefghijklmnopqrstuvwxyz".split(""),
+		AZ: "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		aZ: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"0z": "0123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"0Z": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"1z": "123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"1Z": "123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split("")
+	};
+	/**
+	* 生成验证码文本。
+	*
+	* 从 {@link XCaptchaGeneratePayload.charset} 对应的字符集中随机抽取
+	* `size` 个字符组成验证码，与场景值、可重试次数、附加信息一起写入缓存，
+	* 并返回缓存 token 与验证码明文。
+	*
+	* 适用于短信、邮件等不需要图片的验证码场景；若需要图片请使用
+	* {@link XCaptcha.generateDataUrl}。
+	*
+	* @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+	* @returns 包含 `token` 与验证码明文 `code` 的结果对象。
+	*
+	* @example
+	* const { token, code } = await captcha.generate({
+	*   scene: 'sms-login',
+	*   size: 6,
+	*   ttl: '5m',
+	*   charset: '09',
+	* });
+	* // token 形如 'X__xxxx'，code 为 6 位数字
+	*/
+	async generate(payload) {
+		const chars = this.charsetMap[payload.charset];
+		let code = "";
+		for (let i = 0; i < payload.size; i++) code += sample(chars);
+		return {
+			token: await this.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount ?? 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code
+		};
+	}
+	/**
+	* 生成验证码文本与 SVG 图片 Data URL。
+	*
+	* 使用 svg-captcha 依据 {@link XCaptchaGeneratePayload.charset} 与 `size`
+	* 生成图片，并将验证码文本按与 {@link XCaptcha.generate} 相同的规则写入
+	* 缓存；随后将 SVG 转为 Data URL 一并返回。
+	*
+	* 适用于 Web 页面图片验证码，`dataUrl` 可直接作为 `<img>` 的 `src`。
+	*
+	* @param payload 生成参数，包含场景值、长度、存活时长、字符集等。
+	* @returns 包含 `token`、验证码明文 `code` 与图片 `dataUrl` 的结果对象。
+	*
+	* @example
+	* const { token, dataUrl } = await captcha.generateDataUrl({
+	*   scene: 'login',
+	*   size: 4,
+	*   ttl: '5m',
+	*   charset: 'aZ',
+	* });
+	* // dataUrl 形如 'data:image/svg+xml,...'
+	*/
+	async generateDataUrl(payload) {
+		const { text: code, data: svg } = svgCaptcha.create({
+			size: payload.size,
+			charPreset: this.charsetMap[payload.charset].join("")
+		});
+		return {
+			token: await this.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount ?? 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code,
+			dataUrl: svgToDataUrl(svg)
+		};
+	}
+	/**
+	* 校验验证码。
+	*
+	* 按顺序执行以下检查，任意一项不通过即返回 `false`：
+	* 1. token 存在：缓存中找不到 token 对应数据时直接失败；
+	* 2. 场景一致：`scene` 与生成时不一致时失败，防止跨场景误用；
+	* 3. 验证码一致：`code` 与生成时一致（大小写不敏感）；
+	* 4. 附加信息：提供了 `extra` 时执行其回调，返回 `false` 则失败。
+	*
+	* 注意：每次校验（无论最终是否通过）都会消耗一次重试次数——可重试次数
+	* 大于 0 时扣减并写回缓存，等于 0 时直接删除缓存，此后该 token 不可再用。
+	*
+	* @param options 校验参数，包含 token、验证码明文、场景值与可选的附加信息
+	*   比对函数。
+	* @returns 校验是否通过。
+	*
+	* @example
+	* await captcha.verify({ token, code, scene: 'login' });
+	* // true
+	* await captcha.verify({ token, code, scene: 'login' });
+	* // false：该 token 已失效
+	*/
+	async verify(options) {
+		const expected = await this.cache.get(options.token);
+		if (expected == null) return false;
+		if (expected.retryCount === 0) await this.cache.remove(options.token);
+		else {
+			expected.retryCount--;
+			const ttl = await this.cache.ttl(options.token);
+			await this.cache.set(options.token, expected, ttl);
+		}
+		return expected.scene === options.scene && options.code.toLowerCase() === expected.code.toLowerCase() && (options.extra ? options.extra(expected.extra) : true);
+	}
+};
+export { XCaptcha };

package/lib/chinese.d.mts

@@ -4,7 +4,9 @@
  * 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
  * - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
  * - `pinyinWithTone`：带声调拼音（声调标在韵母上），
- *   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`。
+ *   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`；
+ * - `pinyinInitials`：拼音首字母缩写（小写字符串），
+ *   如 `XChinese.pinyinInitials('我们')` → `'wm'`。
  *
  * 处理规则：
  * - 每个汉字对应数组中的一个拼音元素；
@@ -36,4 +38,20 @@ export declare class XChinese {
    * XChinese.pinyinWithTone('我爱你') // ['wǒ', 'ài', 'nǐ']
    */
   static pinyinWithTone(text: string): string[];
+  /**
+   * 获取拼音首字母缩写（小写字符串）。
+   *
+   * 每个汉字取对应拼音的首字母，并统一转为小写；非汉字字符原样保留
+   * （其中的英文字母也会被转为小写，如 `ABC` → `abc`）。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 小写拼音首字母字符串，例如 `'我们'` → `'wm'`、`'我爱你'` → `'wan'`。
+   *
+   * @example
+   * XChinese.pinyinInitials('我们') // 'wm'
+   * XChinese.pinyinInitials('我爱你') // 'wan'
+   * XChinese.pinyinInitials('我爱ABC') // 'waabc'
+   * XChinese.pinyinInitials('重庆') // 'cq'
+   */
+  static pinyinInitials(text: string): string;
 }

package/lib/chinese.mjs

@@ -6,7 +6,9 @@ import { pinyin } from "pinyin-pro";
 * 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
 * - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
 * - `pinyinWithTone`：带声调拼音（声调标在韵母上），
-*   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`。
+*   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`；
+* - `pinyinInitials`：拼音首字母缩写（小写字符串），
+*   如 `XChinese.pinyinInitials('我们')` → `'wm'`。
 *
 * 处理规则：
 * - 每个汉字对应数组中的一个拼音元素；
@@ -48,5 +50,30 @@ var XChinese = class {
 			toneType: "symbol"
 		});
 	}
+	/**
+	* 获取拼音首字母缩写（小写字符串）。
+	*
+	* 每个汉字取对应拼音的首字母，并统一转为小写；非汉字字符原样保留
+	* （其中的英文字母也会被转为小写，如 `ABC` → `abc`）。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 小写拼音首字母字符串，例如 `'我们'` → `'wm'`、`'我爱你'` → `'wan'`。
+	*
+	* @example
+	* XChinese.pinyinInitials('我们') // 'wm'
+	* XChinese.pinyinInitials('我爱你') // 'wan'
+	* XChinese.pinyinInitials('我爱ABC') // 'waabc'
+	* XChinese.pinyinInitials('重庆') // 'cq'
+	*/
+	static pinyinInitials(text) {
+		return pinyin(text, {
+			type: "string",
+			pattern: "first",
+			toneType: "none",
+			separator: "",
+			removeNonZh: false,
+			nonZh: "consecutive"
+		}).toLowerCase();
+	}
 };
 export { XChinese };

package/lib/cli.d.mts

@@ -1,46 +1,34 @@
-/**
- * 支持的交互提问类型：
- * - `confirm`：是/否确认，结果为布尔值；
- * - `input`：文本输入，结果为字符串。
- */
-export type XCliPromptType = 'confirm' | 'input';
-/**
- * 提问类型与返回值类型的映射。
- */
-export interface XCliPromptResult {
-  confirm: boolean;
-  input: string;
-}
-/**
- * 单次交互提问的配置。
- */
-export interface XCliPromptOptions<T extends XCliPromptType> {
-  /** 展示给用户的提示文案。 */
-  message: string;
-  /** 提问类型，决定返回值类型。 */
-  type: T;
-  /** 可选的默认值，类型随 `type` 联动。 */
-  default?: XCliPromptResult[T];
-}
+import { checkbox, confirm, editor, expand, input, number, password, rawlist, search, select } from "@inquirer/prompts";
 /**
  * 命令行交互与表格输出工具。
  *
- * 基于 `inquirer` 与 `cli-table3` 封装：
- * - `prompt`：发起一次确认或文本输入交互，并返回强类型结果；
+ * 基于 `@inquirer/prompts` 与 `cli-table3` 封装：
+ * - 以静态属性的形式直接透出 `input`、`select`、`checkbox`、`confirm`、
+ *   `search`、`password`、`expand`、`editor`、`number`、`rawlist` 等交互提问函数，
+ *   签名与返回类型与 `@inquirer/prompts` 保持一致；
  * - `table`：将二维数组渲染为对齐的文本表格。
  */
 export declare class XCli {
-  /**
-   * 发起一次交互提问并返回结果。
-   *
-   * @param options 提问配置，`type` 决定返回值类型。
-   * @returns 根据 `type` 返回 `boolean`（confirm）或 `string`（input）。
-   *
-   * @example
-   * await XCli.prompt({ type: 'confirm', message: '是否继续?' }) // true | false
-   * await XCli.prompt({ type: 'input', message: '请输入名称' }) // 'demo'
-   */
-  static prompt<T extends XCliPromptType>(options: XCliPromptOptions<T>): Promise<XCliPromptResult[T]>;
+  /** 发起一次文本输入交互，返回 `Promise<string>`。 */
+  static input: typeof input;
+  /** 发起一次单选交互，返回选中项的值。 */
+  static select: typeof select;
+  /** 发起一次多选交互，返回选中项的数组。 */
+  static checkbox: typeof checkbox;
+  /** 发起一次是/否确认交互，返回 `Promise<boolean>`。 */
+  static confirm: typeof confirm;
+  /** 发起一次带搜索过滤的单选交互，返回选中项的值。 */
+  static search: typeof search;
+  /** 发起一次隐藏输入的密码交互，返回 `Promise<string>`。 */
+  static password: typeof password;
+  /** 发起一次可展开选项的交互，返回选中项的值。 */
+  static expand: typeof expand;
+  /** 打开外部编辑器进行文本输入，返回 `Promise<string>`。 */
+  static editor: typeof editor;
+  /** 发起一次数字输入交互，返回数字结果（未强制必填时可能为 `undefined`）。 */
+  static number: typeof number;
+  /** 发起一次原始列表单选交互，返回选中项的值。 */
+  static rawlist: typeof rawlist;
   /**
    * 将二维数组渲染为对齐的文本表格。
    *

package/lib/cli.mjs

@@ -1,33 +1,36 @@
+import { checkbox, confirm, editor, expand, input, number, password, rawlist, search, select } from "@inquirer/prompts";
 import Table from "cli-table3";
-import inquirer from "inquirer";
 // src/cli.ts
 /**
 * 命令行交互与表格输出工具。
 *
-* 基于 `inquirer` 与 `cli-table3` 封装：
-* - `prompt`：发起一次确认或文本输入交互，并返回强类型结果；
+* 基于 `@inquirer/prompts` 与 `cli-table3` 封装：
+* - 以静态属性的形式直接透出 `input`、`select`、`checkbox`、`confirm`、
+*   `search`、`password`、`expand`、`editor`、`number`、`rawlist` 等交互提问函数，
+*   签名与返回类型与 `@inquirer/prompts` 保持一致；
 * - `table`：将二维数组渲染为对齐的文本表格。
 */
 var XCli = class {
-	/**
-	* 发起一次交互提问并返回结果。
-	*
-	* @param options 提问配置，`type` 决定返回值类型。
-	* @returns 根据 `type` 返回 `boolean`（confirm）或 `string`（input）。
-	*
-	* @example
-	* await XCli.prompt({ type: 'confirm', message: '是否继续?' }) // true | false
-	* await XCli.prompt({ type: 'input', message: '请输入名称' }) // 'demo'
-	*/
-	static async prompt(options) {
-		const { x } = await inquirer.prompt({
-			name: "x",
-			message: options.message,
-			type: options.type,
-			default: options.default
-		});
-		return x;
-	}
+	/** 发起一次文本输入交互，返回 `Promise<string>`。 */
+	static input = input;
+	/** 发起一次单选交互，返回选中项的值。 */
+	static select = select;
+	/** 发起一次多选交互，返回选中项的数组。 */
+	static checkbox = checkbox;
+	/** 发起一次是/否确认交互，返回 `Promise<boolean>`。 */
+	static confirm = confirm;
+	/** 发起一次带搜索过滤的单选交互，返回选中项的值。 */
+	static search = search;
+	/** 发起一次隐藏输入的密码交互，返回 `Promise<string>`。 */
+	static password = password;
+	/** 发起一次可展开选项的交互，返回选中项的值。 */
+	static expand = expand;
+	/** 打开外部编辑器进行文本输入，返回 `Promise<string>`。 */
+	static editor = editor;
+	/** 发起一次数字输入交互，返回数字结果（未强制必填时可能为 `undefined`）。 */
+	static number = number;
+	/** 发起一次原始列表单选交互，返回选中项的值。 */
+	static rawlist = rawlist;
 	/**
 	* 将二维数组渲染为对齐的文本表格。
 	*

package/lib/crawler.d.mts

@@ -1,6 +1,6 @@
 import { XPuppeteerGetPageHtmlOptions } from "./puppeteer.mjs";
-import { HTMLElement } from "node-html-parser";
 import { EventBus } from "vtils";
+import { HTMLElement } from "node-html-parser";
 import { VaeObjectSchemaShapeOf, v } from "vtils/vae";
 import { AsyncOrSync, OneOrMore } from "vtils/types";
 export type XCrawlerData = Record<any, any>;

package/lib/crawler.mjs

@@ -1,7 +1,7 @@
 import { XPuppeteer } from "./puppeteer.mjs";
 import { xr } from "@jayfong/x-request";
-import { parse } from "node-html-parser";
 import { EventBus, castArray, cloneDeepFast, escape, get, isRegExp, isUrl, keysStrict, memoize, omitStrict } from "vtils";
+import { parse } from "node-html-parser";
 import { v } from "vtils/vae";
 // src/crawler.ts
 /**