@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/pay.mjs

@@ -0,0 +1,343 @@
+import { xr } from "@jayfong/x-request";
+import crypto from "node:crypto";
+import { AlipaySdk } from "alipay-sdk";
+// src/pay.ts
+/**
+* 支付工具。
+*
+* 封装支付宝（网页支付）与微信支付（JSAPI 支付）的下单、回调验签与
+* 订单查询能力：
+* - 支付宝：`prepareAlipay` 生成支付链接、`getOrderInfo` 查询订单；
+* - 微信支付：`prepareWepay` 生成 JSSDK 支付参数、`getOrderInfo` 查询订单；
+* - 回调：`verifyNotifyData` 统一校验并解析两个渠道的回调数据。
+*
+* 支付宝 SDK 按需惰性创建，只有首次使用支付宝能力时才初始化。
+* 注意：微信支付回调目前只做 AES-GCM 解密，未实现签名验签，
+* 业务方如需严格校验身份，请自行补充。
+*
+* @example
+* const pay = new XPay({
+*   alipay: {
+*     appId: '2021000000000000',
+*     privateKey: '应用私钥',
+*     publicKey: '支付宝公钥',
+*   },
+*   wepay: {
+*     appId: 'wx1234567890',
+*     merchantId: '1234567890',
+*     privateKey: '商户 API 证书私钥',
+*     certificateSerialNumber: '证书序列号',
+*     secretKey: '32 字节 APIv3 密钥',
+*   },
+* });
+*
+* const { payUrl } = await pay.prepareAlipay({
+*   goodsName: '测试商品',
+*   tradeNumber: 'T20260101001',
+*   totalMoney: 0.01,
+*   notifyUrl: 'https://example.com/notify/alipay',
+* });
+* // 跳转到 payUrl 完成支付
+*/
+var XPay = class {
+	options;
+	alipaySdk;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 支付宝网页支付下单，生成支付链接。
+	*
+	* 调用支付宝 `alipay.trade.page.pay` 接口生成 GET 形式的支付地址，
+	* 用户跳转到该地址即可在支付宝收银台完成支付。订单金额会格式化为
+	* 两位小数字符串，并通过 `passback_params` 标记渠道为 `alipay`，
+	* 以便回调时识别。
+	*
+	* @param options 下单参数，见 {@link XPayPrepareAlipayOptions}。
+	* @returns 支付地址，见 {@link XPayPrepareAlipayResult}。
+	*
+	* @example
+	* const { payUrl } = await pay.prepareAlipay({
+	*   goodsName: '测试商品',
+	*   tradeNumber: 'T20260101001',
+	*   totalMoney: 0.01,
+	*   notifyUrl: 'https://example.com/notify/alipay',
+	* });
+	*/
+	async prepareAlipay(options) {
+		return { payUrl: this.getAlipaySdk().pageExecute("alipay.trade.page.pay", "GET", {
+			notifyUrl: options.notifyUrl,
+			...options.returnUrl ? { returnUrl: options.returnUrl } : {},
+			bizContent: {
+				outTradeNo: options.tradeNumber,
+				productCode: "FAST_INSTANT_TRADE_PAY",
+				totalAmount: options.totalMoney.toFixed(2),
+				subject: options.goodsName,
+				goodsType: "0",
+				passbackParams: "alipay"
+			}
+		}) };
+	}
+	/**
+	* 微信支付 JSAPI 下单，生成 JSSDK 支付参数。
+	*
+	* 调用微信支付 `v3/pay/transactions/jsapi` 接口获取 `prepay_id`，
+	* 再按 JSSDK 规则签名得到支付参数，可直接传给前端
+	* `wx.requestPayment`。金额由元转换为分（乘以 100 后四舍五入），
+	* 避免浮点误差；下单请求会通过 `attach` 字段标记渠道为 `wepay`。
+	*
+	* @param options 下单参数，见 {@link XPayPrepareWepayOptions}。
+	* @returns 支付参数，见 {@link XPayPrepareWepayResult}。
+	*
+	* @example
+	* const { payParams } = await pay.prepareWepay({
+	*   goodsName: '测试商品',
+	*   tradeNumber: 'T20260101002',
+	*   totalMoney: 0.01,
+	*   notifyUrl: 'https://example.com/notify/wepay',
+	*   openid: 'oABC123',
+	* });
+	*/
+	async prepareWepay(options) {
+		const wepay = this.getWepayConfig();
+		const res = await this.wepayRequest("https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi", {
+			appid: wepay.appId,
+			mchid: wepay.merchantId,
+			description: options.goodsName,
+			out_trade_no: options.tradeNumber,
+			attach: "wepay",
+			notify_url: options.notifyUrl,
+			amount: {
+				total: Math.round(options.totalMoney * 100),
+				currency: "CNY"
+			},
+			payer: { openid: options.openid }
+		});
+		if (!res || !res.prepay_id) throw new Error(res?.message || "微信支付下单失败，未返回 prepay_id");
+		const params = {
+			appId: wepay.appId,
+			timestamp: String(Math.round(Date.now() / 1e3)),
+			nonceStr: this.generateNonceStr(),
+			package: `prepay_id=${res.prepay_id}`,
+			signType: "RSA",
+			paySign: ""
+		};
+		params.paySign = this.wepaySign([
+			params.appId,
+			params.timestamp,
+			params.nonceStr,
+			params.package
+		]);
+		return { payParams: params };
+	}
+	/**
+	* 校验并解析支付回调通知数据。
+	*
+	* 先判断数据是否为对象，再按渠道标记识别：
+	* - 支付宝：当 `passback_params` 为 `alipay` 时，调用支付宝 SDK 验签，
+	*   验签通过后返回支付宝交易号；
+	* - 微信支付：当存在 `resource` 字段时，先 AES-GCM 解密，再校验
+	*   `attach` 是否为 `wepay`，通过后返回微信支付订单号。
+	*
+	* 任何一步失败（数据非法、未配置渠道、验签失败、解密失败）都会
+	* 返回 `false`，不会抛出异常。
+	*
+	* @param data 支付平台 POST 过来的回调数据（支付宝为表单 JSON，
+	*   微信支付为通知报文 JSON）。
+	* @returns 校验通过时返回渠道订单号，否则返回 `false`。
+	*
+	* @example
+	* const res = pay.verifyNotifyData(req.body);
+	* if (res) {
+	*   // 校验通过，res.channelOrderNo 为渠道订单号
+	* }
+	*/
+	verifyNotifyData(data) {
+		try {
+			if (!data || typeof data !== "object") return false;
+			if (data.passback_params === "alipay") {
+				if (!this.getAlipaySdk().checkNotifySign(data)) return false;
+				return { channelOrderNo: data.trade_no };
+			}
+			if (data.resource) {
+				const params = JSON.parse(this.wepayDecrypt(data.resource));
+				if (params.attach === "wepay" && params.transaction_id) return { channelOrderNo: params.transaction_id };
+				return false;
+			}
+			return false;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* 校验并解析支付回调通知数据，失败时抛出错误。
+	*
+	* 行为与 {@link verifyNotifyData} 一致，区别在于校验失败时抛出
+	* `Error`，便于在需要强制校验的流程中使用。
+	*
+	* @param data 支付平台 POST 过来的回调数据。
+	* @param message 校验失败时抛出的错误信息。
+	* @returns 校验通过时的渠道订单号。
+	*
+	* @example
+	* const res = pay.verifyNotifyDataOrFail(req.body, '回调验签失败');
+	*/
+	verifyNotifyDataOrFail(data, message) {
+		const res = this.verifyNotifyData(data);
+		if (!res) throw new Error(message);
+		return res;
+	}
+	/**
+	* 查询订单状态。
+	*
+	* 按渠道分别调用微信支付订单查询接口或支付宝 `alipay.trade.query`：
+	* - 优先使用 `orderNo`（商家订单号）查询，未提供时使用
+	*   `channelOrderNo`（渠道订单号）；
+	* - 微信支付 `trade_state` 为 `SUCCESS` 时视为成功；
+	* - 支付宝 `trade_status` 为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时
+	*   视为成功，其余状态视为失败。
+	*
+	* @param payload 查询条件，见 {@link XPayGetOrderInfoPayload}。
+	* @returns 订单信息，见 {@link XPayGetOrderInfoResult}。
+	*
+	* @example
+	* await pay.getOrderInfo({ channel: 'alipay', orderNo: 'T20260101001' });
+	* // { channelOrderNo: '2026...', orderNo: 'T20260101001', status: 'success' }
+	*/
+	async getOrderInfo(payload) {
+		if (payload.channel === "wepay") {
+			const wepay = this.getWepayConfig();
+			const res = await this.wepayRequest(payload.orderNo ? `https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/${payload.orderNo}?mchid=${wepay.merchantId}` : `https://api.mch.weixin.qq.com/v3/pay/transactions/id/${payload.channelOrderNo}?mchid=${wepay.merchantId}`);
+			return {
+				channelOrderNo: res.transaction_id,
+				orderNo: res.out_trade_no,
+				status: res.trade_state === "SUCCESS" ? "success" : "fail"
+			};
+		}
+		const res = await this.getAlipaySdk().exec("alipay.trade.query", { biz_content: payload.orderNo ? { out_trade_no: payload.orderNo } : { trade_no: payload.channelOrderNo } });
+		return {
+			channelOrderNo: res.tradeNo,
+			orderNo: res.outTradeNo,
+			status: res.tradeStatus === "TRADE_SUCCESS" || res.tradeStatus === "TRADE_FINISHED" ? "success" : "fail"
+		};
+	}
+	/**
+	* 获取（并按需创建）支付宝 SDK 实例。
+	*
+	* 首次调用时才初始化 SDK，后续复用同一实例；未配置支付宝时抛出
+	* 明确错误。
+	*/
+	getAlipaySdk() {
+		const alipay = this.getAlipayConfig();
+		if (!this.alipaySdk) this.alipaySdk = new AlipaySdk({
+			appId: alipay.appId,
+			privateKey: alipay.privateKey,
+			alipayPublicKey: alipay.publicKey
+		});
+		return this.alipaySdk;
+	}
+	/**
+	* 获取支付宝配置，未配置时抛出错误。
+	*/
+	getAlipayConfig() {
+		if (!this.options.alipay) throw new Error("未配置支付宝(alipay)，无法使用支付宝相关能力");
+		return this.options.alipay;
+	}
+	/**
+	* 获取微信支付配置，未配置时抛出错误。
+	*/
+	getWepayConfig() {
+		if (!this.options.wepay) throw new Error("未配置微信支付(wepay)，无法使用微信支付相关能力");
+		return this.options.wepay;
+	}
+	/**
+	* 生成随机字符串，用于微信支付请求的 `nonce_str` 与支付参数。
+	*
+	* 使用密码学安全的随机字节生成 12 位十六进制字符串。
+	*/
+	generateNonceStr() {
+		return crypto.randomBytes(6).toString("hex");
+	}
+	/**
+	* 微信支付 RSA 签名。
+	*
+	* 将每个字段拼接换行符（`\n`）后使用 `RSA-SHA256` 私钥签名，返回
+	* base64 编码的签名；同一方法同时用于请求头签名与 JSSDK 支付参数
+	* 签名。
+	*
+	* @param data 待签名字段，按顺序依次拼接，每个字段后追加换行符。
+	* @returns base64 编码的签名串。
+	*/
+	wepaySign(data) {
+		return crypto.createSign("RSA-SHA256").update(data.map((v) => `${v}\n`).join("")).sign(this.getWepayConfig().privateKey, "base64");
+	}
+	/**
+	* 微信支付回调数据解密。
+	*
+	* 使用 APIv3 密钥对 `resource` 做 AES-256-GCM 解密：密文末尾 16
+	* 字节为认证标签，前面为加密数据，`nonce` 作为 IV，
+	* `associated_data` 作为附加认证数据。
+	*
+	* @param resource 回调数据中的 `resource` 字段。
+	* @returns 解密后的 JSON 字符串。
+	*/
+	wepayDecrypt(resource) {
+		const ciphertext = Buffer.from(resource.ciphertext, "base64");
+		const authTag = ciphertext.subarray(ciphertext.length - 16);
+		const encryptedData = ciphertext.subarray(0, ciphertext.length - 16);
+		const decipher = crypto.createDecipheriv("aes-256-gcm", Buffer.from(this.getWepayConfig().secretKey, "utf8"), Buffer.from(resource.nonce, "utf8"));
+		decipher.setAuthTag(authTag);
+		decipher.setAAD(Buffer.from(resource.associated_data ?? "", "utf8"));
+		return Buffer.concat([decipher.update(encryptedData), decipher.final()]).toString("utf8");
+	}
+	/**
+	* 发起微信支付 APIv3 请求。
+	*
+	* 根据 URL 计算请求路径，按 `方法\nURL\n时间戳\n随机串\n请求体\n`
+	* 构造签名并生成 `Authorization` 请求头；GET 请求体为空字符串，
+	* POST 请求体为 `data` 的 JSON 字符串。
+	*
+	* @param url 完整请求地址。
+	* @param data 请求体，缺省表示 GET 请求。
+	* @returns 响应数据。
+	*/
+	async wepayRequest(url, data) {
+		const wepay = this.getWepayConfig();
+		const path = url.replace(/^https?:\/\/[^/]+/, "");
+		const method = data == null ? "GET" : "POST";
+		const body = method === "POST" ? JSON.stringify(data) : "";
+		const params = {
+			method,
+			url: path,
+			time: String(Math.round(Date.now() / 1e3)),
+			rand: this.generateNonceStr(),
+			body,
+			signature: ""
+		};
+		params.signature = this.wepaySign([
+			params.method,
+			params.url,
+			params.time,
+			params.rand,
+			params.body
+		]);
+		const Authorization = [
+			`WECHATPAY2-SHA256-RSA2048 `,
+			`mchid="${wepay.merchantId}",`,
+			`nonce_str="${params.rand}",`,
+			`signature="${params.signature}",`,
+			`timestamp="${params.time}",`,
+			`serial_no="${wepay.certificateSerialNumber}"`
+		].join("");
+		const { data: res } = method === "POST" ? await xr.postJson({
+			url,
+			headers: { Authorization },
+			data
+		}) : await xr.getJson({
+			url,
+			headers: { Authorization }
+		});
+		return res;
+	}
+};
+export { XPay };

package/lib/puppeteer.mjs

@@ -1,7 +1,7 @@
 import { XClipboard } from "./clipboard.mjs";
+import { XDispose } from "./dispose.mjs";
 import { xr } from "@jayfong/x-request";
 import { asyncMemoize, isFunction, isRegExp } from "vtils";
-import { asyncExitHook } from "exit-hook";
 import puppeteer from "puppeteer";
 // src/puppeteer.ts
 var XPuppeteer = class XPuppeteer {
@@ -19,7 +19,7 @@ var XPuppeteer = class XPuppeteer {
 			}
 		});
 		this.browser = browser;
-		asyncExitHook(() => this.disconnect(), { wait: 1e3 });
+		XDispose.exit.add(() => this.disconnect());
 		return browser;
 	}
 	/**
@@ -36,7 +36,7 @@ var XPuppeteer = class XPuppeteer {
 			args: options.proxy ? [`--proxy-server=${options.proxy}`] : void 0
 		});
 		this.browser = browser;
-		asyncExitHook(() => this.close(), { wait: 1e3 });
+		XDispose.exit.add(() => this.close());
 		return browser;
 	}
 	/**

package/lib/random.d.mts

@@ -0,0 +1,71 @@
+/**
+ * 随机 ID 与随机字符串生成工具。
+ *
+ * 提供碰撞概率极低的全局唯一 ID（CUID2）以及基于指定字符集的随机
+ * 字符串生成能力（字母数字、纯字母、纯数字）。所有方法均为静态方法，
+ * 可直接通过 `XRandom.xxx()` 调用。
+ *
+ * @example
+ * XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+ * XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+ * XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+ * XRandom.generateNumeric(6) // '386251'
+ *
+ * @remarks
+ * - `cuid2()` 生成的 ID 长度固定为 24 位，仅包含小写字母与数字，
+ *   适用于数据库主键、文件名等需要高唯一性的场景；
+ * - 随机字符串基于 `randomstring` 生成，各方法的字符集见对应说明；
+ * - 随机字符串不保证密码学安全，请勿用于令牌、密钥等安全敏感场景。
+ */
+export declare class XRandom {
+  /**
+   * 生成 24 位 CUID2 全局唯一 ID。
+   *
+   * CUID2 是 CUID 的改进版本，专为水平扩展与防碰撞设计，默认由
+   * 24 位小写字母与数字组成，无需配置即可直接使用。
+   *
+   * @returns 24 位小写字母与数字组成的唯一 ID 字符串。
+   *
+   * @example
+   * XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+   *
+   * @see https://github.com/paralleldrive/cuid2
+   */
+  static cuid2(): string;
+  /**
+   * 生成由大小写字母与数字组成的随机字符串。
+   *
+   * 字符集为 `[0-9 a-z A-Z]`，共 62 种字符。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的字母数字随机字符串。
+   *
+   * @example
+   * XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+   */
+  static generateAlphanumeric(length: number): string;
+  /**
+   * 生成由大小写英文字母组成的随机字符串。
+   *
+   * 字符集为 `[a-z A-Z]`，不包含数字。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的字母随机字符串。
+   *
+   * @example
+   * XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+   */
+  static generateAlphabetic(length: number): string;
+  /**
+   * 生成由数字组成的随机字符串。
+   *
+   * 字符集为 `[0-9]`，首位允许为 0（例如 `'086251'`）。
+   *
+   * @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+   * @returns 指定长度的数字随机字符串。
+   *
+   * @example
+   * XRandom.generateNumeric(6) // '386251'
+   */
+  static generateNumeric(length: number): string;
+}

package/lib/random.mjs

@@ -0,0 +1,92 @@
+import { createId } from "@paralleldrive/cuid2";
+import * as randomstring from "randomstring";
+// src/random.ts
+/**
+* 随机 ID 与随机字符串生成工具。
+*
+* 提供碰撞概率极低的全局唯一 ID（CUID2）以及基于指定字符集的随机
+* 字符串生成能力（字母数字、纯字母、纯数字）。所有方法均为静态方法，
+* 可直接通过 `XRandom.xxx()` 调用。
+*
+* @example
+* XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+* XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+* XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+* XRandom.generateNumeric(6) // '386251'
+*
+* @remarks
+* - `cuid2()` 生成的 ID 长度固定为 24 位，仅包含小写字母与数字，
+*   适用于数据库主键、文件名等需要高唯一性的场景；
+* - 随机字符串基于 `randomstring` 生成，各方法的字符集见对应说明；
+* - 随机字符串不保证密码学安全，请勿用于令牌、密钥等安全敏感场景。
+*/
+var XRandom = class {
+	/**
+	* 生成 24 位 CUID2 全局唯一 ID。
+	*
+	* CUID2 是 CUID 的改进版本，专为水平扩展与防碰撞设计，默认由
+	* 24 位小写字母与数字组成，无需配置即可直接使用。
+	*
+	* @returns 24 位小写字母与数字组成的唯一 ID 字符串。
+	*
+	* @example
+	* XRandom.cuid2() // 'dj8fyuqt57ejnnbsnik8q1d6'
+	*
+	* @see https://github.com/paralleldrive/cuid2
+	*/
+	static cuid2() {
+		return createId();
+	}
+	/**
+	* 生成由大小写字母与数字组成的随机字符串。
+	*
+	* 字符集为 `[0-9 a-z A-Z]`，共 62 种字符。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的字母数字随机字符串。
+	*
+	* @example
+	* XRandom.generateAlphanumeric(8) // 'a3Fk9Zx2'
+	*/
+	static generateAlphanumeric(length) {
+		return randomstring.generate({
+			charset: "alphanumeric",
+			length
+		});
+	}
+	/**
+	* 生成由大小写英文字母组成的随机字符串。
+	*
+	* 字符集为 `[a-z A-Z]`，不包含数字。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的字母随机字符串。
+	*
+	* @example
+	* XRandom.generateAlphabetic(8) // 'AbCdEfGh'
+	*/
+	static generateAlphabetic(length) {
+		return randomstring.generate({
+			charset: "alphabetic",
+			length
+		});
+	}
+	/**
+	* 生成由数字组成的随机字符串。
+	*
+	* 字符集为 `[0-9]`，首位允许为 0（例如 `'086251'`）。
+	*
+	* @param length 生成字符串的长度，需为不小于 0 的整数，传 0 时返回空字符串。
+	* @returns 指定长度的数字随机字符串。
+	*
+	* @example
+	* XRandom.generateNumeric(6) // '386251'
+	*/
+	static generateNumeric(length) {
+		return randomstring.generate({
+			charset: "numeric",
+			length
+		});
+	}
+};
+export { XRandom };

package/lib/redis.d.mts

@@ -0,0 +1,32 @@
+import { Redis, RedisOptions } from "ioredis";
+/**
+ * Redis 连接与行为配置项。
+ *
+ * 直接继承 ioredis 的 `RedisOptions`，作为 {@link XRedis} 构造时的入参类型。
+ * 保留为空继承的原因：
+ * - 调用方可继续使用 ioredis 原生的全部配置项（如 `host`、`port`、`db`、
+ *   `password`、`keyPrefix` 等）；
+ * - 后续若需追加项目级默认配置或扩展字段，只需在此声明，无需改动调用方。
+ */
+export interface XRedisOptions extends RedisOptions {}
+/**
+ * Redis 客户端封装。
+ *
+ * 直接继承 ioredis 的 `Redis`，完整保留其命令、事件与类型定义，当前仅作为
+ * 统一入口存在，便于：
+ * - 集中管理连接实例的创建与复用；
+ * - 在需要时统一注入默认配置、日志或监控逻辑，而不影响调用方；
+ * - 后续按需覆写/扩展方法，同时保持对原有 API 的兼容。
+ *
+ * @example
+ * const redis = new XRedis({
+ *   host: '127.0.0.1',
+ *   port: 6379,
+ * });
+ *
+ * await redis.set('key', 'value');
+ * // 'OK'
+ * const value = await redis.get('key');
+ * // 'value'
+ */
+export declare class XRedis extends Redis {}

package/lib/redis.mjs

@@ -0,0 +1,24 @@
+import { Redis } from "ioredis";
+// src/redis.ts
+/**
+* Redis 客户端封装。
+*
+* 直接继承 ioredis 的 `Redis`，完整保留其命令、事件与类型定义，当前仅作为
+* 统一入口存在，便于：
+* - 集中管理连接实例的创建与复用；
+* - 在需要时统一注入默认配置、日志或监控逻辑，而不影响调用方；
+* - 后续按需覆写/扩展方法，同时保持对原有 API 的兼容。
+*
+* @example
+* const redis = new XRedis({
+*   host: '127.0.0.1',
+*   port: 6379,
+* });
+*
+* await redis.set('key', 'value');
+* // 'OK'
+* const value = await redis.get('key');
+* // 'value'
+*/
+var XRedis = class extends Redis {};
+export { XRedis };

package/lib/runner.d.mts

@@ -1,52 +1,80 @@
-import { Answers, DistinctQuestion } from "inquirer";
 import { MsValue } from "vtils";
-/**
- * `XRunner` 交互问题定义。
- *
- * 为了让配置回填逻辑可安全工作，要求问题必须包含 `name` 与 `message`。
- */
-export interface XRunnerQuestion<TConfig extends Answers> extends Omit<DistinctQuestion<TConfig>, 'name' | 'message'> {
-  /** 问题对应的配置字段名。 */
-  name: Extract<keyof TConfig, string>;
-  /** 展示给用户的问题文案。 */
-  message: string;
-}
+import { AsyncOrSync } from "vtils/types";
 /**
  * `XRunner` 的运行配置。
  */
-export interface XRunnerOptions<TConfig extends Answers> {
-  /** 交互配置持久化文件路径（JSON）。 */
+export interface XRunnerOptions<TConfig extends Record<string, any>> {
+  /**
+   * 交互配置持久化文件路径（JSON）。
+   *
+   * 启动时若文件不存在会自动创建；读取到的历史配置会传给 `provideConfig`，
+   * 收集到的新配置最终以 2 空格缩进写回该文件，供下次运行复用。
+   */
   configFile: string;
   /**
    * 失败重试间隔。
    *
    * - 固定值：每次失败都等待同一个时长；
    * - 函数：可按重试次数动态计算，`retryCount` 从 `1` 开始计数。
+   *
+   * 时长取值与 `vtils.ms` 一致：数字表示毫秒，字符串需带单位
+   * （如 `'500ms'`、`'1s'`）；值非法时 `ms` 会抛错并终止重试循环。
    */
   delay: MsValue | ((retryCount: number) => MsValue);
-  /** inquirer 交互问题列表。 */
-  questions: Array<XRunnerQuestion<TConfig>>;
   /**
-   * 核心执行函数。
+   * 收集本次运行配置的交互函数。
+   *
+   * 入参 `prevConfig` 为启动时读取到的历史配置（文件缺失或内容非法时兜底为 `{}`），
+   * 通常用于回填交互默认值；返回最终配置，支持同步或异步返回。
+   */
+  provideConfig: (prevConfig: Partial<TConfig>) => AsyncOrSync<TConfig>;
+  /**
+   * 核心执行函数，接收 `provideConfig` 收集到的最终配置。
    *
-   * 返回成功（resolve）时结束运行；抛错（reject）时进入重试分支。
+   * - 成功（resolve）：结束运行，`run()` 正常返回；
+   * - 失败（reject）：进入重试分支，按 `delay` 等待后再次调用。
    */
   run: (config: TConfig) => Promise<void> | void;
 }
 /**
  * 带配置持久化与失败重试能力的交互式运行器。
  *
- * 行为概要：
- * 1. 启动时读取历史配置，作为本次提问默认值；
- * 2. 用户确认后回写配置文件，保证下次可复用；
- * 3. 执行业务函数，成功即退出；
- * 4. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
+ * 典型用法：CLI 启动时先询问用户配置并落盘复用，随后循环执行业务函数，
+ * 失败时自动等待并重试。
+ *
+ * 运行流程（详见 {@link XRunner.run}）：
+ * 1. 确保配置文件存在（缺失时自动创建）；
+ * 2. 读取历史配置，作为本次提问默认值；
+ * 3. 用户确认后回写配置文件，保证下次可复用；
+ * 4. 执行业务函数，成功即退出；
+ * 5. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
  */
-export declare class XRunner<TConfig extends Answers> {
+export declare class XRunner<TConfig extends Record<string, any>> {
   private options;
+  /**
+   * 创建运行器实例。
+   *
+   * @param options 运行配置，各字段语义见 {@link XRunnerOptions}。
+   */
   constructor(options: XRunnerOptions<TConfig>);
   /**
    * 启动运行器。
+   *
+   * 依次执行：确保配置文件存在 → 读取历史配置 → 通过 `provideConfig`
+   * 收集本次配置 → 写回配置文件 → 循环执行 `run`。
+   *
+   * 边界与异常说明：
+   * - 配置文件缺失时由 `XFs.ensureFile` 自动补齐目录并创建空文件；
+   * - 配置内容非法（非 JSON）时 `readJson(..., { throws: false })` 返回
+   *   `null`，经 `|| {}` 兜底为空对象，不阻断启动；
+   * - `provideConfig` 抛错或写回配置失败时，错误直接向外抛出，不进入重试；
+   * - `run` 抛错时进入重试分支：`retryCount` 自增后计算等待时长，打印
+   *   错误与重试提示，等待后重新执行；
+   * - `delay` 为函数时按 `retryCount`（从 `1` 开始）动态计算；其返回值
+   *   若无法被 `ms` 解析，`ms` 会抛错并终止重试循环。
+   *
+   * @returns 业务函数成功后 resolve 为 `undefined`；仅在成功或抛出
+   *          不可恢复错误时返回，否则持续重试。
    */
   run(): Promise<void>;
 }