@bettergi/utils 0.0.11 → 0.1.1

package/dist/mouse.d.ts

@@ -1,3 +1,52 @@
+type MouseWaypointsOptions = {
+    /** 是否按住鼠标左键拖动 */
+    shouldDrag?: boolean;
+    /** 超时时间（毫秒，默认: 不超时） */
+    timeout?: number;
+};
+/**
+ * 沿着指定路径点移动鼠标
+ * @param waypoints 鼠标路径点
+ * @param options 鼠标移动选项
+ */
+export declare const mouseMoveAlongWaypoints: (waypoints: {
+    x: number;
+    y: number;
+    delay?: number;
+}[], options?: MouseWaypointsOptions) => Promise<boolean>;
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export declare const mouseDrag: (x1: number, y1: number, x2: number, y2: number) => Promise<boolean>;
+type NaturalMouseMoveOptions = {
+    /** 移动持续时间（毫秒，默认: 800） */
+    duration: number;
+    /** 摆动幅度（默认: 30） */
+    wiggle?: number;
+    /** 随机种子（可选） */
+    seed?: number;
+    /** 缓动函数（默认: ease-out-cubic） */
+    easing?: (progress: number) => number;
+};
+/** 贝塞尔曲线生成鼠标移动路径点 */
+export declare const bezierWaypoints: (x1: number, y1: number, x2: number, y2: number, options?: NaturalMouseMoveOptions) => Promise<{
+    x: number;
+    y: number;
+    delay: number;
+}[]>;
+/**
+ * 自然地移动鼠标到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ * @param options 鼠标移动选项
+ */
+export declare const naturalMouseMove: (x1: number, y1: number, x2: number, y2: number, options?: NaturalMouseMoveOptions & MouseWaypointsOptions) => Promise<boolean>;
 /**
  * 鼠标滚轮向上滚动指定高度
  * @param height 滚动高度
@@ -22,25 +71,4 @@ export declare const mouseScrollUpLines: (lines: number, lineHeight?: number) =>
  * @param lineHeight 行高（默认值为175像素）
  */
 export declare const mouseScrollDownLines: (lines: number, lineHeight?: number) => Promise<void>;
-/**
- * 鼠标拖拽滑动到指定位置
- * @param x1 起始水平方向偏移量（像素）
- * @param y1 起始垂直方向偏移量（像素）
- * @param x2 终止水平方向偏移量（像素）
- * @param y2 终止垂直方向偏移量（像素）
- */
-export declare const mouseSlide: (x1: number, y1: number, x2: number, y2: number) => Promise<void>;
-/**
- * 鼠标水平拖拽滑动指定距离
- * @param x 起始水平方向偏移量（像素）
- * @param y 起始垂直方向偏移量（像素）
- * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
- */
-export declare const mouseSlideX: (x: number, y: number, distance: number) => Promise<void>;
-/**
- * 鼠标垂直拖拽滑动指定距离
- * @param x 起始水平方向偏移量（像素）
- * @param y 起始垂直方向偏移量（像素）
- * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
- */
-export declare const mouseSlideY: (x: number, y: number, distance: number) => Promise<void>;
+export {};

package/dist/mouse.js

@@ -1,7 +1,81 @@
-const _simulateScroll = async (scrollAmountInClicks, times) => {
+/**
+ * 沿着指定路径点移动鼠标
+ * @param waypoints 鼠标路径点
+ * @param options 鼠标移动选项
+ */
+export const mouseMoveAlongWaypoints = async (waypoints, options) => {
+    const { shouldDrag = false, timeout = 0 } = options || {};
+    try {
+        const startTime = Date.now();
+        for (let i = 0; i < waypoints.length; i++) {
+            // 开始拖拽
+            if (i === 0 && shouldDrag)
+                leftButtonDown();
+            moveMouseTo(Math.trunc(waypoints[i].x), Math.trunc(waypoints[i].y));
+            // 等待指定延迟
+            const delay = Math.trunc(waypoints[i].delay || 50);
+            if (delay > 0)
+                await sleep(delay);
+            // 超时检查
+            if (timeout > 0 && Date.now() - startTime > timeout)
+                return false;
+        }
+    }
+    finally {
+        // 结束拖拽
+        if (shouldDrag)
+            leftButtonUp();
+    }
+    return true;
+};
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export const mouseDrag = async (x1, y1, x2, y2) => {
+    return mouseMoveAlongWaypoints([
+        { x: x1, y: y1 },
+        { x: x2, y: y2 }
+    ], { shouldDrag: true });
+};
+/** 贝塞尔曲线生成鼠标移动路径点 */
+export const bezierWaypoints = async (x1, y1, x2, y2, options) => {
+    const { duration = 800, wiggle = 30, seed = Math.random(), easing = (t) => 1 - Math.pow(1 - t, 3) // ease-out-cubic
+     } = options || {};
+    const random = () => ((seed * 9301 + 49297) % 233280) / 233280;
+    const controlX = (x1 + x2) / 2 + random() * wiggle * 2 - wiggle;
+    const controlY = (y1 + y2) / 2 + random() * wiggle * 2 - wiggle;
+    const steps = Math.max(duration / 16, 10);
+    return Array.from({ length: steps + 1 }, (_, i) => {
+        const t = easing(i / steps);
+        const u = 1 - t;
+        return {
+            x: u * u * x1 + 2 * u * t * controlX + t * t * x2,
+            y: u * u * y1 + 2 * u * t * controlY + t * t * y2,
+            delay: Math.round((duration / steps) * (0.8 + Math.random() * 0.4))
+        };
+    }).concat([{ x: x2, y: y2, delay: 0 }]);
+};
+/**
+ * 自然地移动鼠标到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ * @param options 鼠标移动选项
+ */
+export const naturalMouseMove = async (x1, y1, x2, y2, options) => {
+    const waypoints = await bezierWaypoints(x1, y1, x2, y2, options);
+    return mouseMoveAlongWaypoints(waypoints, options);
+};
+/** 使用回放脚本模拟滚动 */
+const simulateScroll = async (scrollAmountInClicks, times) => {
     const script = {
         macroEvents: Array(times).fill({ type: 6, mouseX: 0, mouseY: scrollAmountInClicks, time: 0 }),
-        info: { name: "", description: "", x: 0, y: 0, width: 1920, height: 1080, recordDpi: 1.25 }
+        info: { name: "", description: "", x: 0, y: 0, width: 1920, height: 1080, recordDpi: 1.5 }
     };
     await keyMouseScript.run(JSON.stringify(script));
 };
@@ -11,7 +85,7 @@ const _simulateScroll = async (scrollAmountInClicks, times) => {
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
 export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 18)) => {
-    return _simulateScroll(120, algorithm(height));
+    return simulateScroll(120, algorithm(height));
 };
 /**
  * 鼠标滚轮向下滚动指定高度
@@ -19,7 +93,7 @@ export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 18)) => {
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
 export const mouseScrollDown = (height, algorithm = h => Math.floor(h / 18)) => {
-    return _simulateScroll(-120, algorithm(height));
+    return simulateScroll(-120, algorithm(height));
 };
 /**
  * 鼠标滚轮向上滚动指定行数
@@ -37,37 +111,3 @@ export const mouseScrollUpLines = (lines, lineHeight = 175) => {
 export const mouseScrollDownLines = (lines, lineHeight = 175) => {
     return mouseScrollDown(lines * lineHeight);
 };
-/**
- * 鼠标拖拽滑动到指定位置
- * @param x1 起始水平方向偏移量（像素）
- * @param y1 起始垂直方向偏移量（像素）
- * @param x2 终止水平方向偏移量（像素）
- * @param y2 终止垂直方向偏移量（像素）
- */
-export const mouseSlide = async (x1, y1, x2, y2) => {
-    moveMouseTo(x1, y1);
-    await sleep(100);
-    leftButtonDown();
-    await sleep(100);
-    moveMouseTo(x2, y2);
-    await sleep(100);
-    leftButtonUp();
-};
-/**
- * 鼠标水平拖拽滑动指定距离
- * @param x 起始水平方向偏移量（像素）
- * @param y 起始垂直方向偏移量（像素）
- * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
- */
-export const mouseSlideX = (x, y, distance) => {
-    return mouseSlide(x, y, x + distance, y);
-};
-/**
- * 鼠标垂直拖拽滑动指定距离
- * @param x 起始水平方向偏移量（像素）
- * @param y 起始垂直方向偏移量（像素）
- * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
- */
-export const mouseSlideY = (x, y, distance) => {
-    return mouseSlide(x, y, x, y + distance);
-};

package/dist/ocr.d.ts

@@ -1,73 +1,83 @@
-type Direction = "north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west";
+import { RetryOptions } from "./workflow";
+type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上四分之一 */ | "east" /** 右半边 */ | "south-east" /** 右下四分之一 */ | "south" /** 下半边 */ | "south-west" /** 左下四分之一 */ | "west" /** 左半边 */ | "north-west"; /** 左上四分之一 */
 /**
  * 在整个画面内搜索图片
  * @param path 图片路径
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImage: (path: string) => globalThis.Region | undefined;
+export declare const findImage: (path: string) => Region | undefined;
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平方向偏移量（像素）
- * @param y - 垂直方向偏移量（像素）
+ * @param x 水平方向偏移量（像素）
+ * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImageWithinBounds: (path: string, x: number, y: number, w: number, h: number) => globalThis.Region | undefined;
+export declare const findImageWithinBounds: (path: string, x: number, y: number, w: number, h: number) => Region | undefined;
 /**
  * 在指定方向上搜索图片
  * @param path 图片路径
  * @param direction 搜索方向
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImageInDirection: (path: string, direction: Direction) => globalThis.Region | undefined;
+export declare const findImageInDirection: (path: string, direction: MatchDirection) => Region | undefined;
+/** 文本搜索选项 */
+type TextMatchOptions = {
+    /** 是否忽略大小写（默认: 是） */
+    ignoreCase?: boolean;
+    /** 是否非完全匹配（默认: 否） */
+    contains?: boolean;
+};
 /**
  * 在整个画面内搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findText: (text: string, contains: boolean, ignoreCase: boolean) => globalThis.Region | undefined;
+export declare const findText: (text: string, options?: TextMatchOptions) => Region | undefined;
 /**
  * 在指定区域内搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param x 水平方向偏移量（像素）
- * @param x - 水平方向偏移量（像素）
- * @param y - 垂直方向偏移量（像素）
+ * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findTextWithinBounds: (text: string, contains: boolean, ignoreCase: boolean, x: number, y: number, w: number, h: number) => globalThis.Region | undefined;
+export declare const findTextWithinBounds: (text: string, x: number, y: number, w: number, h: number, options?: TextMatchOptions) => Region | undefined;
 /**
  * 在指定方向上搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param direction 搜索方向
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findTextInDirection: (text: string, contains: boolean, ignoreCase: boolean, direction: Direction) => globalThis.Region | undefined;
+export declare const findTextInDirection: (text: string, direction: MatchDirection, options?: TextMatchOptions) => Region | undefined;
+/** 列表视图参数 */
+export type ListView = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** 列表项高度 */
+    lineHeight: number;
+    /** 每次滚动的行数（默认: 1） */
+    scrollLines?: number;
+    /** 横向内边距 （默认: 10） */
+    paddingX?: number;
+    /** 纵向内边距 （默认: 10） */
+    paddingY?: number;
+};
 /**
  * 在列表视图中滚动搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param listView 列表视图参数
+ * @param matchOptions 搜索选项
  * @param timeout 搜索超时
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export declare const findTextWithinListView: (text: string, contains: boolean, ignoreCase: boolean, listView: {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    maxListItems: number;
-    lineHeight: number;
-    padding?: number;
-}, timeout?: number) => Promise<globalThis.Region | undefined>;
+export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions) => Promise<Region | undefined>;
 export {};

package/dist/ocr.js

@@ -1,5 +1,5 @@
-import { waitUntil } from "./flow";
 import { mouseScrollDownLines } from "./mouse";
+import { waitForAction } from "./workflow";
 const findFirst = (ir, ro, predicate) => {
     const candidates = ir.findMulti(ro);
     for (let i = 0; i < candidates.count; i++) {
@@ -18,7 +18,7 @@ const directionToBounds = (direction) => {
 /**
  * 在整个画面内搜索图片
  * @param path 图片路径
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
 export const findImage = (path) => {
     try {
@@ -33,11 +33,11 @@ export const findImage = (path) => {
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平方向偏移量（像素）
- * @param y - 垂直方向偏移量（像素）
+ * @param x 水平方向偏移量（像素）
+ * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
 export const findImageWithinBounds = (path, x, y, w, h) => {
     try {
@@ -53,7 +53,7 @@ export const findImageWithinBounds = (path, x, y, w, h) => {
  * 在指定方向上搜索图片
  * @param path 图片路径
  * @param direction 搜索方向
- * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ * @returns 如果找到匹配的图片区域，则返回该区域
  */
 export const findImageInDirection = (path, direction) => {
     const { x, y, w, h } = directionToBounds(direction);
@@ -62,11 +62,11 @@ export const findImageInDirection = (path, direction) => {
 /**
  * 在整个画面内搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findText = (text, contains, ignoreCase) => {
+export const findText = (text, options) => {
+    const { ignoreCase = true, contains = false } = options || {};
     const searchText = ignoreCase ? text.toLowerCase() : text;
     const ir = captureGameRegion();
     const ro = RecognitionObject.ocrThis;
@@ -79,16 +79,15 @@ export const findText = (text, contains, ignoreCase) => {
 /**
  * 在指定区域内搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param x 水平方向偏移量（像素）
- * @param x - 水平方向偏移量（像素）
- * @param y - 垂直方向偏移量（像素）
+ * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findTextWithinBounds = (text, contains, ignoreCase, x, y, w, h) => {
+export const findTextWithinBounds = (text, x, y, w, h, options) => {
+    const { ignoreCase = true, contains = false } = options || {};
     const searchText = ignoreCase ? text.toLowerCase() : text;
     const ir = captureGameRegion();
     const ro = RecognitionObject.ocr(x, y, w, h);
@@ -101,49 +100,47 @@ export const findTextWithinBounds = (text, contains, ignoreCase, x, y, w, h) =>
 /**
  * 在指定方向上搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param direction 搜索方向
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param options 搜索选项
+ * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findTextInDirection = (text, contains, ignoreCase, direction) => {
+export const findTextInDirection = (text, direction, options) => {
     const { x, y, w, h } = directionToBounds(direction);
-    return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
+    return findTextWithinBounds(text, x, y, w, h, options);
 };
 /**
  * 在列表视图中滚动搜索文本
  * @param text 待搜索文本
- * @param contains 是否包含
- * @param ignoreCase 是否忽略大小写
  * @param listView 列表视图参数
+ * @param matchOptions 搜索选项
  * @param timeout 搜索超时
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export const findTextWithinListView = async (text, contains, ignoreCase, listView, timeout = 30 * 1000) => {
-    const { x, y, w, h, maxListItems, lineHeight, padding = 10 } = listView;
-    const find = () => {
-        return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
-    };
-    let firstRegion;
-    const isBottomTouched = () => {
-        const ro = RecognitionObject.ocr(x, y, w, h);
-        const list = captureGameRegion().findMulti(ro);
-        if (list.count > 0) {
-            if (firstRegion?.text === list[0].text && Math.abs(list[0].y - firstRegion.y) < lineHeight) {
+export const findTextWithinListView = async (text, listView, matchOptions, retryOptions) => {
+    const { x, y, w, h, lineHeight, scrollLines = 1, paddingX = 10, paddingY = 10 } = listView;
+    const { maxAttempts = 30, retryInterval = 1000 } = retryOptions || {};
+    const findTargetText = () => findTextWithinBounds(text, x, y, w, h, matchOptions);
+    let lastTextRegion;
+    const isReachedBottom = () => {
+        const textRegion = findFirst(captureGameRegion(), RecognitionObject.ocr(x, y, w, h), region => {
+            return region.isExist() && region.text.trim().length > 0;
+        });
+        if (textRegion) {
+            if (lastTextRegion?.text === textRegion.text &&
+                Math.abs(textRegion.y - lastTextRegion.y) < lineHeight) {
                 return true;
             }
             else {
-                firstRegion = list[0];
+                lastTextRegion = textRegion;
                 return false;
             }
         }
-        else {
-            return true;
-        }
+        // 异常情况: 找不到任何文本
+        return true;
     };
-    const ok = await waitUntil(() => find() != undefined || isBottomTouched(), timeout, 1000, async () => {
-        moveMouseTo(x + w - padding, y + padding);
-        await mouseScrollDownLines(maxListItems, lineHeight);
-    });
-    return ok ? find() : undefined;
+    const isTextFoundOrBottomReached = await waitForAction(() => findTargetText() != undefined || isReachedBottom(), async () => {
+        moveMouseTo(x + w - paddingX, y + paddingY); // 移动到滚动条附近
+        await mouseScrollDownLines(scrollLines, lineHeight); // 滚动指定行数
+    }, { maxAttempts, retryInterval });
+    return isTextFoundOrBottomReached ? findTargetText() : undefined;
 };

package/dist/store.d.ts

@@ -1,6 +1,7 @@
 /**
  * 创建一个持久化存储对象，用于管理应用状态数据
  * 该函数会创建一个代理对象，对该对象的所有属性的修改都会自动同步到相应的JSON文件（脚本的 `store` 目录下）中。
+ * 支持深层嵌套对象的代理。
  * @param name 存储对象的名称，将作为文件名（不包扩展名）
  */
 export declare const useStore: <T extends Record<string, any>>(name: string) => T;

package/dist/store.js

@@ -1,20 +1,52 @@
 /**
  * 创建一个持久化存储对象，用于管理应用状态数据
  * 该函数会创建一个代理对象，对该对象的所有属性的修改都会自动同步到相应的JSON文件（脚本的 `store` 目录下）中。
+ * 支持深层嵌套对象的代理。
  * @param name 存储对象的名称，将作为文件名（不包扩展名）
  */
 export const useStore = (name) => {
-    const path = `store/${name}.json`;
+    const filePath = `store/${name}.json`;
+    // 读取文件数据
     const obj = (() => {
         try {
-            const text = file.readTextSync(path);
+            const text = file.readTextSync(filePath);
             return JSON.parse(text);
         }
         catch {
-            return {};
+            return {}; // 创建空对象
         }
     })();
-    return new Proxy(obj, {
-        set: (target, key, value) => Reflect.set(target, key, value) && file.writeTextSync(path, JSON.stringify(target, null, 2))
-    });
+    // 创建代理函数
+    const createProxy = (target, parentPath = []) => {
+        if (typeof target !== "object" || target === null) {
+            return target;
+        }
+        return new Proxy(target, {
+            get: (target, key) => {
+                const value = Reflect.get(target, key);
+                return typeof value === "object" && value !== null
+                    ? createProxy(value, [...parentPath, key]) // 递归创建代理
+                    : value;
+            },
+            set: (target, key, value) => {
+                const success = Reflect.set(target, key, value);
+                if (success) {
+                    Promise.resolve().then(() => {
+                        file.writeTextSync(filePath, JSON.stringify(obj, null, 2));
+                    });
+                }
+                return success;
+            },
+            deleteProperty: (target, key) => {
+                const success = Reflect.deleteProperty(target, key);
+                if (success) {
+                    Promise.resolve().then(() => {
+                        file.writeTextSync(filePath, JSON.stringify(obj, null, 2));
+                    });
+                }
+                return success;
+            }
+        });
+    };
+    return createProxy(obj);
 };

package/dist/workflow.d.ts

@@ -0,0 +1,52 @@
+export type Action = () => Promise<void> | void;
+export type RetryOptions = {
+    /** 重试次数（默认: 5） */
+    maxAttempts?: number;
+    /** 重试间隔（毫秒，默认: 1000） */
+    retryInterval?: number;
+};
+/**
+ * 等待直到条件满足或超时，期间执行重试操作
+ * @param condition 返回条件是否满足的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  条件满足
+ *          - false 达到最大重试次数
+ */
+export declare const waitForAction: (condition: () => boolean, retryAction?: Action, options?: RetryOptions) => Promise<boolean>;
+/**
+ * 等待某个区域出现，期间执行重试操作
+ * @param regionProvider 返回区域的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  区域出现
+ *          - false 达到最大重试次数
+ */
+export declare const waitForRegionAppear: (regionProvider: () => Region | null | undefined, retryAction?: Action, options?: RetryOptions) => Promise<boolean>;
+/**
+ * 等待某个区域消失，期间执行重试操作
+ * @param regionProvider 返回区域的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  区域消失
+ *          - false 达到最大重试次数
+ */
+export declare const waitForRegionDisappear: (regionProvider: () => Region | null | undefined, retryAction?: Action, options?: RetryOptions) => Promise<boolean>;
+/**
+ * 等待整个画面上某个元素出现，期间执行重试操作
+ * @param recognitionObject 识别对象
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  整个画面上某个元素出现
+ *          - false 达到最大重试次数
+ */
+export declare const waitForElementAppear: (recognitionObject: RecognitionObject, retryAction?: Action, options?: RetryOptions) => Promise<boolean>;
+/**
+ * 等待整个画面上某个元素消失，期间执行重试操作
+ * @param recognitionObject 识别对象
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  整个画面上某个元素消失
+ *          - false 达到最大重试次数
+ */
+export declare const waitForElementDisappear: (recognitionObject: RecognitionObject, retryAction?: Action, options?: RetryOptions) => Promise<boolean>;