@jayfong/x-utils 1.0.0-202410181400 → 3.3.0

package/lib/case.d.mts

@@ -0,0 +1,184 @@
+import { Options, PascalCaseOptions } from "change-case";
+/**
+ * `XCase.camel` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `PascalCaseOptions`，支持
+ * `mergeAmbiguousCharacters` 等全部配置项，属性语义与默认行为
+ * 同 change-case，调用时原样透传。
+ */
+export interface XCaseCamelOptions extends PascalCaseOptions {}
+/**
+ * `XCase.pascal` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `PascalCaseOptions`，支持
+ * `mergeAmbiguousCharacters` 等全部配置项，属性语义与默认行为
+ * 同 change-case，调用时原样透传。
+ */
+export interface XCasePascalOptions extends PascalCaseOptions {}
+/**
+ * `XCase.pascalSnake` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCasePascalSnakeOptions extends Options {}
+/**
+ * `XCase.capital` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseCapitalOptions extends Options {}
+/**
+ * `XCase.constant` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseConstantOptions extends Options {}
+/**
+ * `XCase.dot` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseDotOptions extends Options {}
+/**
+ * `XCase.kebab` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseKebabOptions extends Options {}
+/**
+ * `XCase.path` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCasePathOptions extends Options {}
+/**
+ * `XCase.sentence` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseSentenceOptions extends Options {}
+/**
+ * `XCase.snake` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseSnakeOptions extends Options {}
+/**
+ * `XCase.train` 的 options 参数。
+ *
+ * 继承自 `change-case` 的 `Options`，支持 `locale`、`delimiter`、
+ * `split` 等全部配置项，属性语义与默认行为同 change-case，
+ * 调用时原样透传。
+ */
+export interface XCaseTrainOptions extends Options {}
+/**
+ * 字符串大小写风格转换工具。
+ *
+ * 所有方法均委托给 `change-case` 包实现，方法名去掉了原函数名的 `Case`
+ * 后缀（如 `camelCase` → `camel`，`pascalSnakeCase` → `pascalSnake`）。
+ *
+ * 各方法的 `options` 参数会原样透传给 `change-case` 对应函数，
+ * 类型分别为导出的 `XCaseCamelOptions`、`XCasePascalOptions`、
+ * `XCasePascalSnakeOptions`、`XCaseCapitalOptions`、`XCaseConstantOptions`、
+ * `XCaseDotOptions`、`XCaseKebabOptions`、`XCasePathOptions`、
+ * `XCaseSentenceOptions`、`XCaseSnakeOptions`、`XCaseTrainOptions`，
+ * 可配置 `locale`、`delimiter`、`split` 等（`camel`/`pascal` 额外支持
+ * `mergeAmbiguousCharacters`）。
+ *
+ * 以 `Hello World` 为例，各方法的输出：
+ * - `camel` → `helloWorld`
+ * - `pascal` → `HelloWorld`
+ * - `pascalSnake` → `Hello_World`
+ * - `capital` → `Hello World`
+ * - `constant` → `HELLO_WORLD`
+ * - `dot` → `hello.world`
+ * - `kebab` → `hello-world`
+ * - `path` → `hello/world`
+ * - `sentence` → `Hello world`
+ * - `snake` → `hello_world`
+ * - `train` → `Hello-World`
+ */
+export declare class XCase {
+  /**
+   * 转换为 camelCase（小驼峰）命名。
+   *
+   * @example XCase.camel('Hello World') // 'helloWorld'
+   */
+  static camel(text: string, options?: XCaseCamelOptions): string;
+  /**
+   * 转换为 PascalCase（大驼峰）命名。
+   *
+   * @example XCase.pascal('hello world') // 'HelloWorld'
+   */
+  static pascal(text: string, options?: XCasePascalOptions): string;
+  /**
+   * 转换为 Pascal_Snake_Case（大驼峰 + 下划线）命名。
+   *
+   * @example XCase.pascalSnake('hello world') // 'Hello_World'
+   */
+  static pascalSnake(text: string, options?: XCasePascalSnakeOptions): string;
+  /**
+   * 转换为 Capital Case（首字母大写的空格分隔）命名。
+   *
+   * @example XCase.capital('hello world') // 'Hello World'
+   */
+  static capital(text: string, options?: XCaseCapitalOptions): string;
+  /**
+   * 转换为 CONSTANT_CASE（全大写下划线）命名。
+   *
+   * @example XCase.constant('hello world') // 'HELLO_WORLD'
+   */
+  static constant(text: string, options?: XCaseConstantOptions): string;
+  /**
+   * 转换为 dot.case（点号分隔）命名。
+   *
+   * @example XCase.dot('hello world') // 'hello.world'
+   */
+  static dot(text: string, options?: XCaseDotOptions): string;
+  /**
+   * 转换为 kebab-case（短横线分隔）命名。
+   *
+   * @example XCase.kebab('Hello World') // 'hello-world'
+   */
+  static kebab(text: string, options?: XCaseKebabOptions): string;
+  /**
+   * 转换为 path/case（斜杠分隔）命名。
+   *
+   * @example XCase.path('hello world') // 'hello/world'
+   */
+  static path(text: string, options?: XCasePathOptions): string;
+  /**
+   * 转换为 Sentence case（首字母大写的句子）命名。
+   *
+   * @example XCase.sentence('hello world') // 'Hello world'
+   */
+  static sentence(text: string, options?: XCaseSentenceOptions): string;
+  /**
+   * 转换为 snake_case（小写下划线）命名。
+   *
+   * @example XCase.snake('Hello World') // 'hello_world'
+   */
+  static snake(text: string, options?: XCaseSnakeOptions): string;
+  /**
+   * 转换为 Train-Case（短横线分隔、各单词首字母大写）命名。
+   *
+   * @example XCase.train('hello world') // 'Hello-World'
+   */
+  static train(text: string, options?: XCaseTrainOptions): string;
+}

package/lib/case.mjs

@@ -0,0 +1,120 @@
+import { camelCase, capitalCase, constantCase, dotCase, kebabCase, pascalCase, pascalSnakeCase, pathCase, sentenceCase, snakeCase, trainCase } from "change-case";
+// src/case.ts
+/**
+* 字符串大小写风格转换工具。
+*
+* 所有方法均委托给 `change-case` 包实现，方法名去掉了原函数名的 `Case`
+* 后缀（如 `camelCase` → `camel`，`pascalSnakeCase` → `pascalSnake`）。
+*
+* 各方法的 `options` 参数会原样透传给 `change-case` 对应函数，
+* 类型分别为导出的 `XCaseCamelOptions`、`XCasePascalOptions`、
+* `XCasePascalSnakeOptions`、`XCaseCapitalOptions`、`XCaseConstantOptions`、
+* `XCaseDotOptions`、`XCaseKebabOptions`、`XCasePathOptions`、
+* `XCaseSentenceOptions`、`XCaseSnakeOptions`、`XCaseTrainOptions`，
+* 可配置 `locale`、`delimiter`、`split` 等（`camel`/`pascal` 额外支持
+* `mergeAmbiguousCharacters`）。
+*
+* 以 `Hello World` 为例，各方法的输出：
+* - `camel` → `helloWorld`
+* - `pascal` → `HelloWorld`
+* - `pascalSnake` → `Hello_World`
+* - `capital` → `Hello World`
+* - `constant` → `HELLO_WORLD`
+* - `dot` → `hello.world`
+* - `kebab` → `hello-world`
+* - `path` → `hello/world`
+* - `sentence` → `Hello world`
+* - `snake` → `hello_world`
+* - `train` → `Hello-World`
+*/
+var XCase = class {
+	/**
+	* 转换为 camelCase（小驼峰）命名。
+	*
+	* @example XCase.camel('Hello World') // 'helloWorld'
+	*/
+	static camel(text, options) {
+		return camelCase(text, options);
+	}
+	/**
+	* 转换为 PascalCase（大驼峰）命名。
+	*
+	* @example XCase.pascal('hello world') // 'HelloWorld'
+	*/
+	static pascal(text, options) {
+		return pascalCase(text, options);
+	}
+	/**
+	* 转换为 Pascal_Snake_Case（大驼峰 + 下划线）命名。
+	*
+	* @example XCase.pascalSnake('hello world') // 'Hello_World'
+	*/
+	static pascalSnake(text, options) {
+		return pascalSnakeCase(text, options);
+	}
+	/**
+	* 转换为 Capital Case（首字母大写的空格分隔）命名。
+	*
+	* @example XCase.capital('hello world') // 'Hello World'
+	*/
+	static capital(text, options) {
+		return capitalCase(text, options);
+	}
+	/**
+	* 转换为 CONSTANT_CASE（全大写下划线）命名。
+	*
+	* @example XCase.constant('hello world') // 'HELLO_WORLD'
+	*/
+	static constant(text, options) {
+		return constantCase(text, options);
+	}
+	/**
+	* 转换为 dot.case（点号分隔）命名。
+	*
+	* @example XCase.dot('hello world') // 'hello.world'
+	*/
+	static dot(text, options) {
+		return dotCase(text, options);
+	}
+	/**
+	* 转换为 kebab-case（短横线分隔）命名。
+	*
+	* @example XCase.kebab('Hello World') // 'hello-world'
+	*/
+	static kebab(text, options) {
+		return kebabCase(text, options);
+	}
+	/**
+	* 转换为 path/case（斜杠分隔）命名。
+	*
+	* @example XCase.path('hello world') // 'hello/world'
+	*/
+	static path(text, options) {
+		return pathCase(text, options);
+	}
+	/**
+	* 转换为 Sentence case（首字母大写的句子）命名。
+	*
+	* @example XCase.sentence('hello world') // 'Hello world'
+	*/
+	static sentence(text, options) {
+		return sentenceCase(text, options);
+	}
+	/**
+	* 转换为 snake_case（小写下划线）命名。
+	*
+	* @example XCase.snake('Hello World') // 'hello_world'
+	*/
+	static snake(text, options) {
+		return snakeCase(text, options);
+	}
+	/**
+	* 转换为 Train-Case（短横线分隔、各单词首字母大写）命名。
+	*
+	* @example XCase.train('hello world') // 'Hello-World'
+	*/
+	static train(text, options) {
+		return trainCase(text, options);
+	}
+};
+export { XCase };

package/lib/chinese.d.mts

@@ -0,0 +1,39 @@
+/**
+ * 中文拼音转换工具。
+ *
+ * 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
+ * - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
+ * - `pinyinWithTone`：带声调拼音（声调标在韵母上），
+ *   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`。
+ *
+ * 处理规则：
+ * - 每个汉字对应数组中的一个拼音元素；
+ * - 非汉字字符（字母、数字、符号、空白等）原样保留在结果中；
+ * - 多音字按 `pinyin-pro` 默认的逆向最大匹配分词规则取常用读音；
+ * - 空字符串返回空数组 `[]`。
+ */
+export declare class XChinese {
+  /**
+   * 获取无声调拼音。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 拼音字符串数组，每个汉字对应一个元素，非汉字原样保留。
+   *
+   * @example
+   * XChinese.pinyin('我们') // ['wo', 'men']
+   * XChinese.pinyin('我爱你') // ['wo', 'ai', 'ni']
+   * XChinese.pinyin('我爱ABC') // ['wo', 'ai', 'A', 'B', 'C']
+   */
+  static pinyin(text: string): string[];
+  /**
+   * 获取带声调拼音（声调标在韵母上，如 `wǒ`、`ài`、`nǐ`）。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 拼音字符串数组，每个汉字对应一个带声调元素，非汉字原样保留。
+   *
+   * @example
+   * XChinese.pinyinWithTone('我们') // ['wǒ', 'men']
+   * XChinese.pinyinWithTone('我爱你') // ['wǒ', 'ài', 'nǐ']
+   */
+  static pinyinWithTone(text: string): string[];
+}

package/lib/chinese.mjs

@@ -0,0 +1,52 @@
+import { pinyin } from "pinyin-pro";
+// src/chinese.ts
+/**
+* 中文拼音转换工具。
+*
+* 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
+* - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
+* - `pinyinWithTone`：带声调拼音（声调标在韵母上），
+*   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`。
+*
+* 处理规则：
+* - 每个汉字对应数组中的一个拼音元素；
+* - 非汉字字符（字母、数字、符号、空白等）原样保留在结果中；
+* - 多音字按 `pinyin-pro` 默认的逆向最大匹配分词规则取常用读音；
+* - 空字符串返回空数组 `[]`。
+*/
+var XChinese = class {
+	/**
+	* 获取无声调拼音。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 拼音字符串数组，每个汉字对应一个元素，非汉字原样保留。
+	*
+	* @example
+	* XChinese.pinyin('我们') // ['wo', 'men']
+	* XChinese.pinyin('我爱你') // ['wo', 'ai', 'ni']
+	* XChinese.pinyin('我爱ABC') // ['wo', 'ai', 'A', 'B', 'C']
+	*/
+	static pinyin(text) {
+		return pinyin(text, {
+			type: "array",
+			toneType: "none"
+		});
+	}
+	/**
+	* 获取带声调拼音（声调标在韵母上，如 `wǒ`、`ài`、`nǐ`）。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 拼音字符串数组，每个汉字对应一个带声调元素，非汉字原样保留。
+	*
+	* @example
+	* XChinese.pinyinWithTone('我们') // ['wǒ', 'men']
+	* XChinese.pinyinWithTone('我爱你') // ['wǒ', 'ài', 'nǐ']
+	*/
+	static pinyinWithTone(text) {
+		return pinyin(text, {
+			type: "array",
+			toneType: "symbol"
+		});
+	}
+};
+export { XChinese };

package/lib/cli.d.mts

@@ -0,0 +1,64 @@
+/**
+ * 支持的交互提问类型：
+ * - `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];
+}
+/**
+ * 命令行交互与表格输出工具。
+ *
+ * 基于 `inquirer` 与 `cli-table3` 封装：
+ * - `prompt`：发起一次确认或文本输入交互，并返回强类型结果；
+ * - `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]>;
+  /**
+   * 将二维数组渲染为对齐的文本表格。
+   *
+   * 返回纯文本（不含 ANSI 颜色码），保证在任意终端环境下输出一致。
+   *
+   * @param data 表格行数据，每行为一个单元格数组。
+   * @returns 使用 Unicode 边框绘制的表格字符串。
+   *
+   * @example
+   * XCli.table([
+   *   ['姓名', '年龄'],
+   *   ['张三', '18'],
+   * ])
+   * // ┌──────┬──────┐
+   * // │ 姓名 │ 年龄 │
+   * // ├──────┼──────┤
+   * // │ 张三 │ 18   │
+   * // └──────┴──────┘
+   */
+  static table(data: any[][]): string;
+}

package/lib/cli.mjs

@@ -0,0 +1,59 @@
+import Table from "cli-table3";
+import inquirer from "inquirer";
+// src/cli.ts
+/**
+* 命令行交互与表格输出工具。
+*
+* 基于 `inquirer` 与 `cli-table3` 封装：
+* - `prompt`：发起一次确认或文本输入交互，并返回强类型结果；
+* - `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;
+	}
+	/**
+	* 将二维数组渲染为对齐的文本表格。
+	*
+	* 返回纯文本（不含 ANSI 颜色码），保证在任意终端环境下输出一致。
+	*
+	* @param data 表格行数据，每行为一个单元格数组。
+	* @returns 使用 Unicode 边框绘制的表格字符串。
+	*
+	* @example
+	* XCli.table([
+	*   ['姓名', '年龄'],
+	*   ['张三', '18'],
+	* ])
+	* // ┌──────┬──────┐
+	* // │ 姓名 │ 年龄 │
+	* // ├──────┼──────┤
+	* // │ 张三 │ 18   │
+	* // └──────┴──────┘
+	*/
+	static table(data) {
+		const table = new Table({ style: {
+			head: [],
+			border: []
+		} });
+		table.push(...data);
+		return table.toString();
+	}
+};
+export { XCli };

package/lib/clipboard.d.mts

@@ -0,0 +1,50 @@
+/**
+ * 剪贴板文本/HTML 读写工具。
+ *
+ * 说明：
+ * - `readText` / `writeText` 使用 `clipboardy`，跨平台处理纯文本；
+ * - `readHtml` / `writeHtml` 在不同平台走不同实现：
+ *   - macOS：`osascript` + AppleScript HTML 数据；
+ *   - Windows：`powershell` + `HTML Format`（CF_HTML）；
+ *   - 其他平台：抛出不支持错误。
+ */
+export declare class XClipboard {
+  /**
+   * 构建 Windows CF_HTML 文本。
+   *
+   * 参考规范中 Start/End 偏移均按字节计数（UTF-8）。
+   */
+  private static toWindowsCfHtml;
+  /**
+   * 从 Windows `HTML Format` 文本中提取 fragment。
+   *
+   * 若缺少偏移字段，会尝试用标记提取；再失败时返回原始文本。
+   */
+  private static fromWindowsCfHtml;
+  /**
+   * 将 PowerShell 脚本编码为 `-EncodedCommand` 可执行格式（UTF-16LE）。
+   */
+  private static buildPowerShellCommand;
+  /**
+   * 读取纯文本剪贴板内容。
+   */
+  static readText(): Promise<string>;
+  /**
+   * 读取 HTML 剪贴板内容（macOS / Windows）。
+   *
+   * - macOS：读取 AppleScript `«data HTML...»` 十六进制文本并解码；
+   * - Windows：读取 `HTML Format`（CF_HTML）并提取 fragment。
+   */
+  static readHtml(): Promise<string>;
+  /**
+   * 写入纯文本到剪贴板。
+   */
+  static writeText(text: string): Promise<void>;
+  /**
+   * 写入 HTML 到剪贴板（macOS / Windows）。
+   *
+   * - macOS：将 HTML 编码为十六进制后写入 AppleScript HTML 数据；
+   * - Windows：封装为 CF_HTML（`HTML Format`）后调用 PowerShell 写入。
+   */
+  static writeHtml(html: string): Promise<void>;
+}

package/lib/clipboard.mjs

@@ -0,0 +1,122 @@
+import { XCmd } from "./cmd.mjs";
+import clipboardy from "clipboardy";
+// src/clipboard.ts
+/**
+* 剪贴板文本/HTML 读写工具。
+*
+* 说明：
+* - `readText` / `writeText` 使用 `clipboardy`，跨平台处理纯文本；
+* - `readHtml` / `writeHtml` 在不同平台走不同实现：
+*   - macOS：`osascript` + AppleScript HTML 数据；
+*   - Windows：`powershell` + `HTML Format`（CF_HTML）；
+*   - 其他平台：抛出不支持错误。
+*/
+var XClipboard = class XClipboard {
+	/**
+	* 构建 Windows CF_HTML 文本。
+	*
+	* 参考规范中 Start/End 偏移均按字节计数（UTF-8）。
+	*/
+	static toWindowsCfHtml(fragmentHtml) {
+		const htmlPrefix = "<!DOCTYPE html><html><body><!--StartFragment-->";
+		const html = `${htmlPrefix}${fragmentHtml}<!--EndFragment--></body></html>`;
+		const startHtml = Buffer.byteLength("Version:0.9\r\nStartHTML:0000000000\r\nEndHTML:0000000000\r\nStartFragment:0000000000\r\nEndFragment:0000000000\r\n", "utf8");
+		const startFragment = startHtml + Buffer.byteLength(htmlPrefix, "utf8");
+		const endFragment = startFragment + Buffer.byteLength(fragmentHtml, "utf8");
+		const endHtml = startHtml + Buffer.byteLength(html, "utf8");
+		const pad = (num) => num.toString().padStart(10, "0");
+		return `${`Version:0.9\r
+StartHTML:${pad(startHtml)}\r\nEndHTML:${pad(endHtml)}\r\nStartFragment:${pad(startFragment)}\r\nEndFragment:${pad(endFragment)}\r\n`}${html}`;
+	}
+	/**
+	* 从 Windows `HTML Format` 文本中提取 fragment。
+	*
+	* 若缺少偏移字段，会尝试用标记提取；再失败时返回原始文本。
+	*/
+	static fromWindowsCfHtml(value) {
+		const startMatch = value.match(/StartFragment:(\d+)/);
+		const endMatch = value.match(/EndFragment:(\d+)/);
+		if (startMatch && endMatch) {
+			const start = Number(startMatch[1]);
+			const end = Number(endMatch[1]);
+			if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+				const bytes = Buffer.from(value, "utf8");
+				if (start >= 0 && end <= bytes.length) return bytes.subarray(start, end).toString("utf8");
+			}
+		}
+		const markerMatch = value.match(/<!--StartFragment-->([\s\S]*?)<!--EndFragment-->/);
+		if (markerMatch) return markerMatch[1];
+		return value;
+	}
+	/**
+	* 将 PowerShell 脚本编码为 `-EncodedCommand` 可执行格式（UTF-16LE）。
+	*/
+	static buildPowerShellCommand(script) {
+		return `powershell -NoProfile -NonInteractive -STA -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+	}
+	/**
+	* 读取纯文本剪贴板内容。
+	*/
+	static async readText() {
+		return clipboardy.read();
+	}
+	/**
+	* 读取 HTML 剪贴板内容（macOS / Windows）。
+	*
+	* - macOS：读取 AppleScript `«data HTML...»` 十六进制文本并解码；
+	* - Windows：读取 `HTML Format`（CF_HTML）并提取 fragment。
+	*/
+	static async readHtml() {
+		if (process.platform === "darwin") {
+			const { result: hex } = await XCmd.exec(`osascript -e "the clipboard as «class HTML»"`);
+			const normalized = hex.trim();
+			const matched = normalized.match(/^«data HTML([0-9a-fA-F]*)»$/);
+			if (!matched) throw new Error(`读取剪贴板 HTML 失败，返回内容格式无效: ${normalized}`);
+			return Buffer.from(matched[1], "hex").toString();
+		}
+		if (process.platform === "win32") {
+			const command = XClipboard.buildPowerShellCommand([
+				"[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+				"Add-Type -AssemblyName System.Windows.Forms",
+				"$data = [System.Windows.Forms.Clipboard]::GetData('HTML Format')",
+				"if ($null -eq $data) { return }",
+				"Write-Output $data"
+			].join("; "));
+			const { result } = await XCmd.exec(command);
+			return XClipboard.fromWindowsCfHtml(result.trim());
+		}
+		throw new Error(`当前平台不支持读取 HTML 剪贴板: ${process.platform}`);
+	}
+	/**
+	* 写入纯文本到剪贴板。
+	*/
+	static async writeText(text) {
+		await clipboardy.write(text);
+	}
+	/**
+	* 写入 HTML 到剪贴板（macOS / Windows）。
+	*
+	* - macOS：将 HTML 编码为十六进制后写入 AppleScript HTML 数据；
+	* - Windows：封装为 CF_HTML（`HTML Format`）后调用 PowerShell 写入。
+	*/
+	static async writeHtml(html) {
+		if (process.platform === "darwin") {
+			const hex = Buffer.from(html).toString("hex");
+			await XCmd.exec(`osascript -e "set the clipboard to «data HTML${hex}»"`);
+			return;
+		}
+		if (process.platform === "win32") {
+			const cfHtml = XClipboard.toWindowsCfHtml(html);
+			const cfHtmlBase64 = Buffer.from(cfHtml, "utf8").toString("base64");
+			const command = XClipboard.buildPowerShellCommand([
+				"$cfHtml = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('" + cfHtmlBase64 + "'))",
+				"Add-Type -AssemblyName System.Windows.Forms",
+				"[System.Windows.Forms.Clipboard]::SetData('HTML Format', $cfHtml)"
+			].join("; "));
+			await XCmd.exec(command);
+			return;
+		}
+		throw new Error(`当前平台不支持写入 HTML 剪贴板: ${process.platform}`);
+	}
+};
+export { XClipboard };