@jayfong/x-utils 1.0.0-202410181400 → 3.3.0

package/lib/fs.mjs

@@ -0,0 +1,65 @@
+import fs from "fs-extra";
+import mime from "mime";
+// src/fs.ts
+/**
+* 额外的文件类型辅助方法：
+* - `getMimeType`：将扩展名 / 文件名 / MIME 字符串统一转换为 MIME 类型；
+* - `getExtension`：将 MIME 字符串 / 文件名统一转换为扩展名。
+*
+* 这些方法会被合并到 `XFs` 中，与 `fs-extra` 的 API 一起导出。
+*/
+const XFsExtra = {
+	/**
+	* 获取 MIME 类型。
+	*
+	* 入参支持以下形式：
+	* - 扩展名：`json`、`png`
+	* - 文件名：`file.txt`、`archive.tar.gz`
+	* - MIME 字符串：`application/json`
+	*
+	* 处理规则：
+	* 1. 去除首尾空白后，如果为空，返回通用兜底值 `application/octet-stream`；
+	* 2. 如果已是 MIME 形式（包含 `/`），直接返回原值；
+	* 3. 否则交给 `mime.getType` 推断；
+	* 4. 推断失败时，返回 `application/octet-stream`。
+	*/
+	getMimeType(extOrName) {
+		const value = extOrName.trim();
+		if (!value) return "application/octet-stream";
+		if (value.includes("/")) return value;
+		return mime.getType(value) || "application/octet-stream";
+	},
+	/**
+	* 获取扩展名（不带 `.`）。
+	*
+	* 入参支持以下形式：
+	* - MIME 字符串：`image/png`、`text/plain`
+	* - 文件名：`file.txt`、`archive.tar.gz`
+	* - 扩展名：`json`
+	*
+	* 处理规则：
+	* 1. 去除首尾空白后，如果为空，返回空字符串；
+	* 2. 如果是 MIME 形式（包含 `/`），优先通过 `mime.getExtension` 推断，
+	*    若推断失败则退化为取 `/` 右侧片段；
+	* 3. 如果是文件名（包含 `.`），返回最后一段后缀；
+	* 4. 否则按扩展名/MIME 简写尝试 `mime.getExtension`，失败返回空字符串。
+	*/
+	getExtension(typeOrName) {
+		const value = typeOrName.trim();
+		if (!value) return "";
+		if (value.includes("/")) return mime.getExtension(value) || value.split("/").pop() || "";
+		if (value.includes(".")) return value.split(".").pop();
+		return mime.getExtension(value) || "";
+	}
+};
+/**
+* `XFs` = `fs-extra` + 轻量文件类型工具。
+*
+* 这样调用方既可以直接使用完整的文件系统 API（如 `readFile`、`writeFile`），
+* 也可以在同一对象上使用 `getMimeType` 和 `getExtension`。
+*/
+const XFs = {
+	...fs,
+	...XFsExtra
+};
+export { XFs };

package/lib/json.d.mts

@@ -0,0 +1,50 @@
+/**
+ * JSON 文本与文件读写工具。
+ *
+ * 提供两类能力：
+ * - 严格方法：`parse` / `read`，遇到非法 JSON 或文件异常时抛错；
+ * - 安全方法：`safeParse` / `safeRead`，遇到异常时返回 `undefined`，适合可选配置读取场景。
+ */
+export declare class XJson {
+  /**
+   * 严格解析 JSON 文本。
+   *
+   * - 解析成功：返回目标类型值；
+   * - 解析失败：抛出 `SyntaxError`。
+   */
+  static parse<T>(value: string): T;
+  /**
+   * 安全解析 JSON 文本。
+   *
+   * - 解析成功：返回目标类型值；
+   * - 解析失败：返回 `undefined`。
+   *
+   * 适用于“配置可缺省、失败可兜底”的场景，例如从环境变量读取可选 JSON。
+   */
+  static safeParse<T>(value: string): T | undefined;
+  /**
+   * 序列化为 JSON 字符串。
+   *
+   * @param compact `true` 时输出紧凑格式（无缩进）；`false`（默认）时输出 2 空格缩进，便于阅读与 git diff。
+   */
+  static stringify(value: unknown, compact?: boolean): string;
+  /**
+   * 严格读取并解析 JSON 文件（UTF-8）。
+   *
+   * 读取失败（如文件不存在）或解析失败时会抛错。
+   */
+  static read<T>(file: string): Promise<T>;
+  /**
+   * 安全读取并解析 JSON 文件（UTF-8）。
+   *
+   * - 文件不存在、权限问题、JSON 非法等任意异常：返回 `undefined`；
+   * - 读取和解析都成功：返回目标类型值。
+   *
+   * 适合读取“可选存在”的本地缓存、临时状态文件。
+   */
+  static safeRead<T>(file: string): Promise<T | undefined>;
+  /**
+   * 将值写入 JSON 文件（UTF-8）。
+   */
+  static write(file: string, value: unknown, compact?: boolean): Promise<void>;
+}

package/lib/json.mjs

@@ -0,0 +1,74 @@
+import * as fs from "node:fs";
+// src/json.ts
+/**
+* JSON 文本与文件读写工具。
+*
+* 提供两类能力：
+* - 严格方法：`parse` / `read`，遇到非法 JSON 或文件异常时抛错；
+* - 安全方法：`safeParse` / `safeRead`，遇到异常时返回 `undefined`，适合可选配置读取场景。
+*/
+var XJson = class XJson {
+	/**
+	* 严格解析 JSON 文本。
+	*
+	* - 解析成功：返回目标类型值；
+	* - 解析失败：抛出 `SyntaxError`。
+	*/
+	static parse(value) {
+		return JSON.parse(value);
+	}
+	/**
+	* 安全解析 JSON 文本。
+	*
+	* - 解析成功：返回目标类型值；
+	* - 解析失败：返回 `undefined`。
+	*
+	* 适用于“配置可缺省、失败可兜底”的场景，例如从环境变量读取可选 JSON。
+	*/
+	static safeParse(value) {
+		try {
+			return XJson.parse(value);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 序列化为 JSON 字符串。
+	*
+	* @param compact `true` 时输出紧凑格式（无缩进）；`false`（默认）时输出 2 空格缩进，便于阅读与 git diff。
+	*/
+	static stringify(value, compact = false) {
+		return JSON.stringify(value, null, compact ? void 0 : 2);
+	}
+	/**
+	* 严格读取并解析 JSON 文件（UTF-8）。
+	*
+	* 读取失败（如文件不存在）或解析失败时会抛错。
+	*/
+	static async read(file) {
+		const value = await fs.promises.readFile(file, "utf8");
+		return XJson.parse(value);
+	}
+	/**
+	* 安全读取并解析 JSON 文件（UTF-8）。
+	*
+	* - 文件不存在、权限问题、JSON 非法等任意异常：返回 `undefined`；
+	* - 读取和解析都成功：返回目标类型值。
+	*
+	* 适合读取“可选存在”的本地缓存、临时状态文件。
+	*/
+	static async safeRead(file) {
+		try {
+			return await XJson.read(file);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 将值写入 JSON 文件（UTF-8）。
+	*/
+	static async write(file, value, compact = false) {
+		await fs.promises.writeFile(file, XJson.stringify(value, compact));
+	}
+};
+export { XJson };

package/lib/puppeteer.d.mts

@@ -0,0 +1,88 @@
+import { Browser, ElementHandle, Frame, Page } from "puppeteer";
+export type XPuppeteerBrowser = Browser;
+export type XPuppeteerPage = Page;
+export interface XPuppeteerOpenBrowserOptions {
+  /** 是否以有头模式启动浏览器；默认 `false`（无头）。 */
+  headful?: boolean;
+  /** 代理地址，例如 `http://127.0.0.1:7890`。 */
+  proxy?: string;
+  /** 浏览器用户数据目录。 */
+  dataDir?: string;
+}
+export interface XPuppeteerOpenPageOptions {
+  /**
+   * 当目标 URL 已在现有页面中打开时的匹配规则。
+   *
+   * - `string`：匹配 `pathname + search` 是否包含该片段；
+   * - `RegExp`：匹配 `pathname + search`。
+   */
+  match?: string | RegExp;
+  /** 是否拦截图片/字体/样式资源，以提升打开速度。 */
+  blockAssets?: boolean;
+  /** `goto` 时使用的 referer；未传则使用目标 URL。 */
+  referer?: string;
+}
+export interface XPuppeteerGetPageHtmlOptions extends XPuppeteerOpenBrowserOptions, XPuppeteerOpenPageOptions {
+  /** 复用浏览器实例的标识；传入后会命中 memoized 实例。 */
+  instanceId?: string | number;
+  /** 是否连接系统已启动的调试浏览器（默认 `false`）。 */
+  useSystemBrowser?: boolean;
+  /**
+   * 页面打开后的扩展逻辑钩子，例如等待某个 selector 出现再取 HTML。
+   */
+  afterOpenPage?: (payload: {
+    /** 当前 `XPuppeteer` 实例。 */
+    browser: XPuppeteer;
+    /** 已打开的页面实例。 */
+    page: XPuppeteerPage;
+  }) => any;
+}
+export declare class XPuppeteer {
+  browser: Browser;
+  /**
+   * 连接系统中已开启远程调试端口（9222）的浏览器。
+   */
+  connectSystemBrowser(): Promise<XPuppeteerBrowser>;
+  /**
+   * 启动新的浏览器实例并绑定退出钩子。
+   */
+  openBrowser(options?: XPuppeteerOpenBrowserOptions): Promise<XPuppeteerBrowser>;
+  /**
+   * 打开 URL 或直接渲染 HTML。
+   *
+   * 当入参为 URL 时，会优先尝试复用已打开且匹配的页面。
+   */
+  openPage(urlOrHtml: string, options?: XPuppeteerOpenPageOptions): Promise<XPuppeteerPage>;
+  input(page: Page, selector: string, textOrHtml: string, frameIndex?: number): Promise<void>;
+  /**
+   * 在当前激活元素上执行“全选”。
+   */
+  selectAll(page: Page | Frame): Promise<void>;
+  /**
+   * 通过键盘事件执行粘贴（Shift + Insert）。
+   */
+  paste(page: Page): Promise<void>;
+  queryByText<T extends Node = HTMLDivElement>(page: Page, text: string | RegExp | ((el: T) => boolean)): Promise<ElementHandle<T>>;
+  /**
+   * 断开与浏览器的连接（不关闭浏览器进程）。
+   */
+  disconnect(): Promise<void>;
+  /**
+   * 关闭当前浏览器实例。
+   */
+  close(): Promise<void>;
+  /**
+   * 创建并打开浏览器，返回 `XPuppeteer` 实例。
+   */
+  static openBrowser(options?: XPuppeteerOpenBrowserOptions): Promise<XPuppeteer>;
+  /**
+   * 便捷方法：打开页面并返回 `Page`。
+   *
+   * 返回的 `page.close()` 会被替换为关闭整个浏览器实例。
+   */
+  static openPage(urlOrHtml: string, options?: XPuppeteerGetPageHtmlOptions): Promise<XPuppeteerPage>;
+  static getPageHtmlXp: ((options: XPuppeteerGetPageHtmlOptions) => Promise<XPuppeteer>) & {
+    cache: import("vtils").AsyncMemoizeCacheMap;
+  };
+  static getPageHtml(url: string, options?: XPuppeteerGetPageHtmlOptions): Promise<string>;
+}

package/lib/puppeteer.mjs

@@ -0,0 +1,219 @@
+import { XClipboard } from "./clipboard.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 {
+	browser;
+	/**
+	* 连接系统中已开启远程调试端口（9222）的浏览器。
+	*/
+	async connectSystemBrowser() {
+		const { data: { webSocketDebuggerUrl } } = await xr.getJson({ url: "http://localhost:9222/json/version" });
+		const browser = await puppeteer.connect({
+			browserWSEndpoint: webSocketDebuggerUrl,
+			defaultViewport: {
+				width: 0,
+				height: 0
+			}
+		});
+		this.browser = browser;
+		asyncExitHook(() => this.disconnect(), { wait: 1e3 });
+		return browser;
+	}
+	/**
+	* 启动新的浏览器实例并绑定退出钩子。
+	*/
+	async openBrowser(options = {}) {
+		const browser = await puppeteer.launch({
+			headless: !options.headful,
+			defaultViewport: {
+				width: 1440,
+				height: 900
+			},
+			userDataDir: options.dataDir,
+			args: options.proxy ? [`--proxy-server=${options.proxy}`] : void 0
+		});
+		this.browser = browser;
+		asyncExitHook(() => this.close(), { wait: 1e3 });
+		return browser;
+	}
+	/**
+	* 打开 URL 或直接渲染 HTML。
+	*
+	* 当入参为 URL 时，会优先尝试复用已打开且匹配的页面。
+	*/
+	async openPage(urlOrHtml, options = {}) {
+		const isUrl = /^https?:\/\//i.test(urlOrHtml);
+		const pages = await this.browser.pages();
+		if (isUrl) {
+			const inputUrl = new URL(urlOrHtml);
+			const foundPage = pages.find((item) => {
+				const pageUrl = item.url();
+				if (!/^https?:\/\//i.test(pageUrl)) return false;
+				const url = new URL(pageUrl);
+				return inputUrl.origin === url.origin && (pageUrl === urlOrHtml || !!options.match && (typeof options.match === "string" ? `${url.pathname}${url.search}`.includes(options.match) : options.match.test(`${url.pathname}${url.search}`)));
+			});
+			if (foundPage) return foundPage;
+		}
+		const page = await this.browser.newPage();
+		await page.setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36");
+		if (options.blockAssets) {
+			await page.setRequestInterception(true);
+			page.on("request", (req) => {
+				const resourceType = req.resourceType();
+				if (resourceType === "stylesheet" || resourceType === "font" || resourceType === "image") req.abort();
+				else req.continue();
+			});
+		}
+		if (isUrl) await page.goto(urlOrHtml, { referer: options.referer || urlOrHtml });
+		else await page.setContent(urlOrHtml);
+		return page;
+	}
+	async input(page, selector, textOrHtml, frameIndex) {
+		const mainPage = page;
+		const keyboard = page.keyboard;
+		let queryRoot = page;
+		if (frameIndex != null) {
+			const frame = page.frames()[frameIndex];
+			if (!frame) throw new Error(`Frame 不存在: ${frameIndex}`);
+			queryRoot = frame;
+		}
+		const el = await queryRoot.$(selector);
+		if (!el) throw new Error(`未找到输入元素: ${selector}`);
+		if (await el.evaluate((el) => {
+			return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SPAN";
+		})) await XClipboard.writeText(textOrHtml);
+		else await XClipboard.writeHtml(textOrHtml);
+		await el.click();
+		await this.selectAll(queryRoot);
+		await keyboard.press("Backspace");
+		await this.paste(mainPage);
+	}
+	/**
+	* 在当前激活元素上执行“全选”。
+	*/
+	async selectAll(page) {
+		await page.evaluate(() => {
+			const isMac = /Mac|iPod|iPhone|iPad/.test(window.navigator.platform);
+			document.activeElement.dispatchEvent(new KeyboardEvent("keydown", {
+				bubbles: true,
+				cancelable: true,
+				key: isMac ? "Meta" : "Control",
+				code: isMac ? "MetaLeft" : "ControlLeft",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_LEFT,
+				getModifierState: (keyArg) => keyArg === (isMac ? "Meta" : "Control"),
+				ctrlKey: !isMac,
+				metaKey: isMac,
+				charCode: 0,
+				keyCode: isMac ? 93 : 17,
+				which: isMac ? 93 : 17
+			}));
+			const preventableEvent = new KeyboardEvent("keydown", {
+				bubbles: true,
+				cancelable: true,
+				key: "a",
+				code: "KeyA",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_STANDARD,
+				getModifierState: (keyArg) => keyArg === (isMac ? "Meta" : "Control"),
+				ctrlKey: !isMac,
+				metaKey: isMac,
+				charCode: 0,
+				keyCode: 65,
+				which: 65
+			});
+			if (!(!document.activeElement.dispatchEvent(preventableEvent) || preventableEvent.defaultPrevented)) document.execCommand("selectall", false, null);
+			document.activeElement.dispatchEvent(new KeyboardEvent("keyup", {
+				bubbles: true,
+				cancelable: true,
+				key: isMac ? "Meta" : "Control",
+				code: isMac ? "MetaLeft" : "ControlLeft",
+				location: window.KeyboardEvent.DOM_KEY_LOCATION_LEFT,
+				getModifierState: () => false,
+				charCode: 0,
+				keyCode: isMac ? 93 : 17,
+				which: isMac ? 93 : 17
+			}));
+		});
+	}
+	/**
+	* 通过键盘事件执行粘贴（Shift + Insert）。
+	*/
+	async paste(page) {
+		await page.keyboard.down("Shift");
+		await page.keyboard.press("Insert");
+		await page.keyboard.up("Shift");
+	}
+	async queryByText(page, text) {
+		const el = await page.evaluateHandle((text, isRegExp, isFunction) => {
+			const textRe = isRegExp ? (() => {
+				const m = text.match(/^\/(.+)\/([^/]*)$/);
+				return new RegExp(m[1], m[2] || void 0);
+			})() : void 0;
+			const textFn = isFunction ? eval(`(() => {return ${text}})()`) : void 0;
+			const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, { acceptNode: (node) => {
+				return (isRegExp ? textRe.test(node.textContent) : isFunction ? textFn(node) : node.textContent.includes(text)) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
+			} });
+			walker.nextNode();
+			return walker.currentNode.parentElement;
+		}, String(text), isRegExp(text), isFunction(text));
+		return el;
+	}
+	/**
+	* 断开与浏览器的连接（不关闭浏览器进程）。
+	*/
+	async disconnect() {
+		await this.browser.disconnect();
+	}
+	/**
+	* 关闭当前浏览器实例。
+	*/
+	async close() {
+		await this.browser.close();
+	}
+	/**
+	* 创建并打开浏览器，返回 `XPuppeteer` 实例。
+	*/
+	static async openBrowser(options = {}) {
+		const xp = new XPuppeteer();
+		await xp.openBrowser(options);
+		return xp;
+	}
+	/**
+	* 便捷方法：打开页面并返回 `Page`。
+	*
+	* 返回的 `page.close()` 会被替换为关闭整个浏览器实例。
+	*/
+	static async openPage(urlOrHtml, options = {}) {
+		const xp = new XPuppeteer();
+		await xp.openBrowser(options);
+		const page = await xp.openPage(urlOrHtml, options);
+		page.close = () => xp.close();
+		return page;
+	}
+	static getPageHtmlXp = asyncMemoize(async (options) => {
+		const xp = new XPuppeteer();
+		await (options.useSystemBrowser ? xp.connectSystemBrowser() : xp.openBrowser(options));
+		return xp;
+	}, { cacheKey: (options) => options.instanceId });
+	static async getPageHtml(url, options = {}) {
+		const hasInstanceId = !!options.instanceId;
+		options.instanceId ||= Date.now();
+		const xp = await XPuppeteer.getPageHtmlXp(options);
+		try {
+			const page = await xp.openPage(url, options);
+			if (options.afterOpenPage) await options.afterOpenPage({
+				browser: xp,
+				page
+			});
+			return await page.content();
+		} finally {
+			if (!hasInstanceId) {
+				if (options.useSystemBrowser) await xp.disconnect();
+				else await xp.close();
+			}
+		}
+	}
+};
+export { XPuppeteer };

package/lib/runner.d.mts

@@ -0,0 +1,52 @@
+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;
+}
+/**
+ * `XRunner` 的运行配置。
+ */
+export interface XRunnerOptions<TConfig extends Answers> {
+  /** 交互配置持久化文件路径（JSON）。 */
+  configFile: string;
+  /**
+   * 失败重试间隔。
+   *
+   * - 固定值：每次失败都等待同一个时长；
+   * - 函数：可按重试次数动态计算，`retryCount` 从 `1` 开始计数。
+   */
+  delay: MsValue | ((retryCount: number) => MsValue);
+  /** inquirer 交互问题列表。 */
+  questions: Array<XRunnerQuestion<TConfig>>;
+  /**
+   * 核心执行函数。
+   *
+   * 返回成功（resolve）时结束运行；抛错（reject）时进入重试分支。
+   */
+  run: (config: TConfig) => Promise<void> | void;
+}
+/**
+ * 带配置持久化与失败重试能力的交互式运行器。
+ *
+ * 行为概要：
+ * 1. 启动时读取历史配置，作为本次提问默认值；
+ * 2. 用户确认后回写配置文件，保证下次可复用；
+ * 3. 执行业务函数，成功即退出；
+ * 4. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
+ */
+export declare class XRunner<TConfig extends Answers> {
+  private options;
+  constructor(options: XRunnerOptions<TConfig>);
+  /**
+   * 启动运行器。
+   */
+  run(): Promise<void>;
+}

package/lib/runner.mjs

@@ -0,0 +1,50 @@
+import { XFs } from "./fs.mjs";
+import inquirer from "inquirer";
+import { ms, wait } from "vtils";
+// src/runner.ts
+/**
+* 带配置持久化与失败重试能力的交互式运行器。
+*
+* 行为概要：
+* 1. 启动时读取历史配置，作为本次提问默认值；
+* 2. 用户确认后回写配置文件，保证下次可复用；
+* 3. 执行业务函数，成功即退出；
+* 4. 失败时按 `delay` 等待后重试，直到成功或出现不可恢复错误。
+*/
+var XRunner = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 启动运行器。
+	*/
+	async run() {
+		await XFs.ensureFile(this.options.configFile);
+		const savedConfig = await XFs.readJson(this.options.configFile, { throws: false }) || {};
+		const questions = this.options.questions.map((item) => {
+			const defaultValue = savedConfig[item.name];
+			if (defaultValue === void 0) return item;
+			return {
+				...item,
+				default: defaultValue
+			};
+		});
+		const config = await inquirer.prompt(questions);
+		await XFs.writeJson(this.options.configFile, config, { spaces: 2 });
+		let retryCount = 0;
+		while (true) try {
+			await this.options.run(config);
+			return;
+		} catch (err) {
+			retryCount++;
+			const delay = typeof this.options.delay === "function" ? this.options.delay(retryCount) : this.options.delay;
+			const delayMs = ms(delay);
+			if (delayMs == null) throw new Error(`无效的重试等待时长: ${String(delay)}`);
+			console.error(err);
+			console.log(`执行报错, 第${retryCount}次重试前等待${delay}`);
+			await wait(delayMs);
+		}
+	}
+};
+export { XRunner };

package/lib/task.d.mts

@@ -0,0 +1,37 @@
+/**
+ * 可复用任务基类。
+ *
+ * 封装了进程退出时的资源清理与退出码处理：
+ * 1. `run()` 启动前注册退出钩子，进程退出时自动调用 `dispose()` 释放资源；
+ * 2. `start()` 成功后以退出码 `0` 优雅退出；
+ * 3. `start()` 失败时记录错误日志，并以退出码 `1` 优雅退出。
+ *
+ * 使用方式：
+ * - 继承并实现 `start()`，将任务主逻辑放入其中；
+ * - 可选地覆写 `dispose()` 以释放连接、文件句柄等资源。
+ */
+export declare abstract class XTask {
+  /** 日志实例，子类可直接通过 `this.log` 输出日志。 */
+  log: import("consola").ConsolaInstance;
+  /**
+   * 任务主入口，子类必须实现。
+   *
+   * 成功 resolve 视为任务成功；抛错（reject）则触发错误日志与失败退出码。
+   */
+  abstract start(): Promise<void>;
+  /**
+   * 进程退出前的资源清理钩子，默认无操作。
+   *
+   * 子类可覆写以释放数据库连接、临时文件等资源；退出钩子最多等待 3000ms。
+   */
+  dispose(): Promise<void>;
+  /**
+   * 运行任务。
+   *
+   * 行为说明：
+   * 1. 注册退出钩子：进程退出时调用 `dispose()`，等待时长 3000ms；
+   * 2. 执行 `start()`，成功后以退出码 `0` 优雅退出；
+   * 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
+   */
+  run(): Promise<void>;
+}

package/lib/task.mjs

@@ -0,0 +1,43 @@
+import { asyncExitHook, gracefulExit } from "exit-hook";
+import { consola } from "consola";
+// src/task.ts
+/**
+* 可复用任务基类。
+*
+* 封装了进程退出时的资源清理与退出码处理：
+* 1. `run()` 启动前注册退出钩子，进程退出时自动调用 `dispose()` 释放资源；
+* 2. `start()` 成功后以退出码 `0` 优雅退出；
+* 3. `start()` 失败时记录错误日志，并以退出码 `1` 优雅退出。
+*
+* 使用方式：
+* - 继承并实现 `start()`，将任务主逻辑放入其中；
+* - 可选地覆写 `dispose()` 以释放连接、文件句柄等资源。
+*/
+var XTask = class {
+	/** 日志实例，子类可直接通过 `this.log` 输出日志。 */
+	log = consola;
+	/**
+	* 进程退出前的资源清理钩子，默认无操作。
+	*
+	* 子类可覆写以释放数据库连接、临时文件等资源；退出钩子最多等待 3000ms。
+	*/
+	async dispose() {}
+	/**
+	* 运行任务。
+	*
+	* 行为说明：
+	* 1. 注册退出钩子：进程退出时调用 `dispose()`，等待时长 3000ms；
+	* 2. 执行 `start()`，成功后以退出码 `0` 优雅退出；
+	* 3. 执行失败时记录错误并以退出码 `1` 优雅退出。
+	*/
+	run() {
+		asyncExitHook(() => this.dispose(), { wait: 3e3 });
+		return this.start().then(() => {
+			gracefulExit(0);
+		}).catch((err) => {
+			consola.error(err);
+			gracefulExit(1);
+		});
+	}
+};
+export { XTask };