@bettergi/utils 0.0.11 → 0.1.0

package/README.md

@@ -21,8 +21,6 @@ pnpm install @bettergi/utils
 > 常见游戏内操作封装，省去手动实现的繁琐。
 
 ```ts
-import { openMenu, openMenuPage, openPaimonMenu, setTime } from "@bettergi/utils";
-
 // 打开派蒙菜单
 await openPaimonMenu();
 
@@ -32,7 +30,10 @@ await openMenu("邮件");
 // 打开菜单页面
 await openMenuPage("问卷");
 
-// 调整游戏时间
+// 调整游戏到指定时间
+await setTimeTo(12, 35);
+
+// 调整游戏时间段
 await setTime("evening");
 ```
 
@@ -41,16 +42,6 @@ await setTime("evening");
 > 对 RecognitionObject 代码的封装，对于简单的找图、找字操作，不再需要编写复杂的代码。
 
 ```ts
-import {
-  findImage,
-  findImageInDirection,
-  findImageWithinBounds,
-  findText,
-  findTextInDirection,
-  findTextWithinBounds
-} from "@bettergi/utils";
-
-// 在整个画面内搜索图片，找不到返回 undefined
 const i1 = findImage("assets/关闭.png");
 
 // 在指定方向上搜索图片，找不到返回 undefined
@@ -60,13 +51,13 @@ const i2 = findImageInDirection("assets/关闭.png", "north-east");
 const i3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
 
 // 在整个画面内搜索文本（不包含、忽略大小写），找不到返回 undefined
-const t1 = findText("购买", false, true);
+const t1 = findText("购买");
 
 // 在指定方向上搜索文本（包含、忽略大小写），找不到返回 undefined
-const t2 = findTextInDirection("师傅", true, true, "east");
+const t2 = findTextInDirection("师傅", "east", { contains: true, ignoreCase: true });
 
 // 在指定区域内搜索文本（不包含、忽略大小写），找不到返回 undefined
-const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
+const t3 = findTextWithinBounds("确认", 960, 540, 960, 540);
 ```
 
 ### 行为流程
@@ -74,36 +65,28 @@ const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
 > 对脚本开发过程中常见工作流的抽象，例如：等待 XXX 完成/出现/消失。
 
 ```ts
-import {
-  assertExists,
-  assertNotExists,
-  findImageInDirection,
-  findTextInDirection,
-  findTextWithinBounds,
-  waitUntil
-} from "@bettergi/utils";
-
 // 等待直到找不到[关闭按钮] 或 5秒后超时，每隔1秒检查一次，期间按 Esc 键
-const done = await waitUntil(
+const done = await waitForAction(
   () => findImageInDirection("assets/关闭.png", "north-east") === undefined,
-  5000,
-  1000,
-  () => keyPress("ESCAPE")
+  () => keyPress("ESCAPE"),
+  { maxAttempts: 5, retryInterval: 1000 }
 );
 if (!done) throw new Error("关闭页面超时");
 
-// 断言 "世界等级" 区域存在 或 5秒后超时抛出异常，每隔1秒检查一次，期间按 Esc 键
-await assertExists(
-  () => findTextInDirection("世界等级", false, true, "north-west"),
+// 断言 "世界等级" 区域即将出现 或 5秒后超时抛出异常，每隔1秒检查一次，期间按 Esc 键
+await assertRegionAppearing(
+  () => findTextInDirection("世界等级", "north-west"),
   "打开派蒙菜单超时",
-  5000,
-  1000,
-  () => keyPress("ESCAPE")
+  () => keyPress("ESCAPE"),
+  { maxAttempts: 5, retryInterval: 1000 }
 );
 
 // 断言 "购买" 区域不存在 或 5秒后超时抛出异常，每隔1秒检查一次，期间如果存在 "购买" 按钮则点击
-const findButton = () => findTextWithinBounds("购买", true, true, 500, 740, 900, 110);
-await assertNotExists(findButton, "点击购买按钮超时", 5000, 1000, () => findButton()?.click());
+const findButton = () => findTextWithinBounds("购买", 500, 740, 900, 110);
+await assertRegionDisappearing(findButton, "点击购买按钮超时", () => findButton()?.click(), {
+  maxAttempts: 5,
+  retryInterval: 1000
+});
 ```
 
 ### 鼠标操作
@@ -111,15 +94,11 @@ await assertNotExists(findButton, "点击购买按钮超时", 5000, 1000, () =>
 > 对常见鼠标操作的封装，如鼠标滚动、拖拽等。
 
 ```ts
-import {
-  mouseScrollDown,
-  mouseScrollDownLines,
-  mouseScrollUp,
-  mouseScrollUpLines,
-  mouseSlide,
-  mouseSlideX,
-  mouseSlideY
-} from "@bettergi/utils";
+// 鼠标从 (745, 610) 平滑自然地移动 (1920, 1080)
+await naturalMouseMove(0, 0, 1920, 1080);
+
+// 鼠标从 (745, 610) 拖拽到 (1280, 610)
+await mouseDrag(745, 610, 1280, 610);
 
 // 鼠标滚轮向上滚动 175 像素
 await mouseScrollUp(175);
@@ -132,15 +111,6 @@ await mouseScrollUpLines(99);
 
 // 鼠标滚轮向下滚动 1 行，行高 115（自定义：商店物品行高）
 await mouseScrollDownLines(1, 115);
-
-// 鼠标从 (745, 610) 拖拽到 (1280, 610)
-await mouseSlide(745, 610, 1280, 610);
-
-// 鼠标从 (745, 610) 向右拖拽 435 像素
-await mouseSlideX(745, 610, 435);
-
-// 鼠标从 (1290, 140) 向下拖拽 175 像素
-await mouseSlideY(1290, 140, 175);
 ```
 
 ### 数据存储
@@ -174,8 +144,8 @@ import { getForBody, postForBody } from "@bettergi/utils";
 
 // 发送 GET 请求获取响应体内容
 // 提示：需要在 `manifest.json` 文件中配置 `http_allowed_urls`，并在 调度器 -> 修改通用配置 中启用
-const body1 = await getForBody("https://example.com/", null, { "User-Agent": "BetterGI" });
-const body2 = await postForBody("https://example.com/", null, { "User-Agent": "BetterGI" });
+const body1 = await getForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
+const body2 = await postForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
 log.info(`GET 请求响应体内容${body1}`);
 log.info(`POST 请求响应体内容${body2}`);
 ```

package/dist/asserts.d.ts

@@ -0,0 +1,57 @@
+import { type Action, type RetryOptions } from "./workflow";
+/**
+ * 断言某个区域当前存在，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ */
+export declare const assertRegionPresent: (regionProvider: () => Region | null | undefined, message: string) => Promise<void>;
+/**
+ * 断言某个区域当前不存在，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ */
+export declare const assertRegionAbsent: (regionProvider: () => Region | null | undefined, message: string) => Promise<void>;
+/**
+ * 断言整个画面上某个元素当前存在，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ */
+export declare const assertElementPresent: (recognitionObject: RecognitionObject, message: string) => Promise<void>;
+/**
+ * 断言整个画面上某个元素当前不存在，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ */
+export declare const assertElementAbsent: (recognitionObject: RecognitionObject, message: string) => Promise<void>;
+/**
+ * 断言某个区域即将出现，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export declare const assertRegionAppearing: (regionProvider: () => Region | null | undefined, message: string, retryAction?: Action, options?: RetryOptions) => Promise<void>;
+/**
+ * 断言某个区域即将消失，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export declare const assertRegionDisappearing: (regionProvider: () => Region | null | undefined, message: string, retryAction?: Action, options?: RetryOptions) => Promise<void>;
+/**
+ * 断言整个画面上某个元素即将出现，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export declare const assertElementAppearing: (recognitionObject: RecognitionObject, message: string, retryAction?: Action, options?: RetryOptions) => Promise<void>;
+/**
+ * 断言整个画面上某个元素即将消失，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export declare const assertElementDisappearing: (recognitionObject: RecognitionObject, message: string, retryAction?: Action, options?: RetryOptions) => Promise<void>;

package/dist/asserts.js

@@ -0,0 +1,91 @@
+import { waitForElementAppear, waitForElementDisappear, waitForRegionAppear, waitForRegionDisappear } from "./workflow";
+/**
+ * 断言某个区域当前存在，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ */
+export const assertRegionPresent = async (regionProvider, message) => {
+    const region = regionProvider();
+    if (region == null || !region.isExist()) {
+        throw new Error(message);
+    }
+};
+/**
+ * 断言某个区域当前不存在，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ */
+export const assertRegionAbsent = async (regionProvider, message) => {
+    const region = regionProvider();
+    if (region != null && region.isExist()) {
+        throw new Error(message);
+    }
+};
+/**
+ * 断言整个画面上某个元素当前存在，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ */
+export const assertElementPresent = async (recognitionObject, message) => {
+    return assertRegionPresent(() => captureGameRegion().find(recognitionObject), message);
+};
+/**
+ * 断言整个画面上某个元素当前不存在，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ */
+export const assertElementAbsent = async (recognitionObject, message) => {
+    return assertRegionAbsent(() => captureGameRegion().find(recognitionObject), message);
+};
+/**
+ * 断言某个区域即将出现，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export const assertRegionAppearing = async (regionProvider, message, retryAction, options) => {
+    const isAppeared = await waitForRegionAppear(regionProvider, retryAction, options);
+    if (!isAppeared) {
+        throw new Error(message);
+    }
+};
+/**
+ * 断言某个区域即将消失，否则抛出异常
+ * @param regionProvider 返回区域的函数
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export const assertRegionDisappearing = async (regionProvider, message, retryAction, options) => {
+    const isDisappeared = await waitForRegionDisappear(regionProvider, retryAction, options);
+    if (!isDisappeared) {
+        throw new Error(message);
+    }
+};
+/**
+ * 断言整个画面上某个元素即将出现，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export const assertElementAppearing = async (recognitionObject, message, retryAction, options) => {
+    const isAppeared = await waitForElementAppear(recognitionObject, retryAction, options);
+    if (!isAppeared) {
+        throw new Error(message);
+    }
+};
+/**
+ * 断言整个画面上某个元素即将消失，否则抛出异常
+ * @param recognitionObject 识别对象
+ * @param message 错误信息
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ */
+export const assertElementDisappearing = async (recognitionObject, message, retryAction, options) => {
+    const isDisappeared = await waitForElementDisappear(recognitionObject, retryAction, options);
+    if (!isDisappeared) {
+        throw new Error(message);
+    }
+};

package/dist/game.d.ts

@@ -1,3 +1,13 @@
+import { ListView } from "./ocr";
+/**
+ * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
+ * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作
+ * @param w 游戏宽度
+ * @param y 游戏高度
+ * @param dpi 系统屏幕的DPI缩放比例
+ * @param action 执行动作
+ */
+export declare const withGameMetrics: <T>(w: number, y: number, dpi: number, action: () => Promise<T> | T) => Promise<T>;
 /**
  * 打开派蒙菜单
  */
@@ -5,34 +15,37 @@ export declare const openPaimonMenu: () => Promise<void>;
 /**
  * 打开游戏菜单（左侧按钮）
  * @param name 菜单名称
- * @param reverse 是否反向搜索（可选）
- * @param config 搜索参数（可选）
+ * @param stepBackwards 是否反向步进（可选）
+ * @param options 搜索参数（可选）
  */
-export declare const openMenu: (name: "\u62CD\u7167" | "\u516C\u544A" | "\u90AE\u4EF6" | "\u65F6\u95F4" | "\u8BBE\u7F6E" | (string & {}), reverse?: boolean, config?: {
-    x?: number;
-    step?: number;
-    timeout?: number;
+export declare const openMenu: (name: "\u62CD\u7167" | "\u516C\u544A" | "\u90AE\u4EF6" | "\u65F6\u95F4" | "\u8BBE\u7F6E" | (string & {}), stepBackwards?: boolean, options?: {
+    navWidth?: number;
+    steps?: number;
 }) => Promise<void>;
 /**
  * 打开游戏菜单页面（菜单按钮列表）
  * @param name 菜单页面名称
- * @param config 菜单页面视图参数
- */
-export declare const openMenuPage: (name: string, config?: {
-    x?: number;
-    y?: number;
-    w?: number;
-    h?: number;
-    lineHeight?: number;
-}) => Promise<void>;
-/**
- * 调整游戏时间
- * @param period 时间段
- * @param config 时钟参数
+ * @param listView 菜单页面视图参数
  */
-export declare const setTime: (period: "night" | "morning" | "noon" | "evening", config?: {
+export declare const openMenuPage: (name: string, listView?: ListView) => Promise<void>;
+type ClockOptions = {
     centerX?: number;
     centerY?: number;
+    offsetHours?: number;
     radius?: number;
-    offset?: number;
-}) => Promise<void>;
+    smooth?: number;
+};
+/**
+ * 调整游戏时间到指定时分
+ * @param hour 小时
+ * @param minute 分钟
+ * @param options 时钟参数
+ */
+export declare const setTimeTo: (hour: number, minute: number, options?: ClockOptions) => Promise<void>;
+/**
+ * 调整游戏时间到指定时间段
+ * @param period 时间段
+ * @param options 时钟参数
+ */
+export declare const setTime: (period: "night" | "morning" | "noon" | "evening", options?: ClockOptions) => Promise<void>;
+export {};

package/dist/game.js

@@ -1,6 +1,24 @@
-import { assertExists, assertNotExists } from "./flow";
-import { mouseSlide } from "./mouse";
+import { assertRegionAppearing, assertRegionDisappearing } from "./asserts";
+import { mouseMoveAlongWaypoints } from "./mouse";
 import { findTextInDirection, findTextWithinBounds, findTextWithinListView } from "./ocr";
+/**
+ * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
+ * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作
+ * @param w 游戏宽度
+ * @param y 游戏高度
+ * @param dpi 系统屏幕的DPI缩放比例
+ * @param action 执行动作
+ */
+export const withGameMetrics = async (w, y, dpi, action) => {
+    const { width, height, screenDpiScale } = genshin;
+    try {
+        setGameMetrics(w, y, dpi);
+        return await action();
+    }
+    finally {
+        setGameMetrics(width, height, screenDpiScale);
+    }
+};
 /**
  * 打开派蒙菜单
  */
@@ -8,34 +26,36 @@ export const openPaimonMenu = async () => {
     // 1.返回主界面
     await genshin.returnMainUi();
     // 2.打开派蒙菜单
-    await assertExists(() => findTextInDirection("世界等级", false, true, "north-west"), "打开派蒙菜单超时", 5000, 1000, () => keyPress("ESCAPE"));
+    await assertRegionAppearing(() => findTextWithinBounds("世界等级", 300, 230, 440, 100), "打开派蒙菜单超时", () => keyPress("ESCAPE"));
 };
 /**
  * 打开游戏菜单（左侧按钮）
  * @param name 菜单名称
- * @param reverse 是否反向搜索（可选）
- * @param config 搜索参数（可选）
+ * @param stepBackwards 是否反向步进（可选）
+ * @param options 搜索参数（可选）
  */
-export const openMenu = async (name, reverse = false, config = {}) => {
+export const openMenu = async (name, stepBackwards = false, options = {}) => {
     // 1.打开派蒙菜单
     await openPaimonMenu();
-    // 2.搜索菜单按钮
-    const { x = 50, step = 30, timeout = 3000 } = config;
-    const findTooltip = () => findTextWithinBounds(name, false, true, 0, 0, x + 150, genshin.height);
-    let result = undefined;
-    const steps = Math.ceil(genshin.height / step);
-    for (let i = 0; i < steps; i++) {
-        const o = i * step;
-        const y = reverse ? genshin.height - o : o;
-        moveMouseTo(x, y);
-        await sleep(30); // 等待提示文字出现
-        if ((result = findTooltip()) !== undefined)
-            break;
-    }
+    // 2.步进搜索菜单按钮
+    const { navWidth = 95, steps: step = 30 } = options;
+    const findTooltip = () => findTextWithinBounds(name, navWidth, 0, 20 + name.length * 20, genshin.height);
+    const tooltip = await withGameMetrics(1920, 1080, 1.5, async () => {
+        let result = undefined;
+        const steps = Math.ceil(genshin.height / step);
+        for (let i = 0; i < steps; i++) {
+            const o = i * step;
+            const y = stepBackwards ? genshin.height - o : o;
+            moveMouseTo(Math.round(navWidth / 2), y);
+            await sleep(30); // 等待提示文字出现
+            if ((result = findTooltip()) !== undefined)
+                return result;
+        }
+    });
     // 3.点击菜单按钮
-    if (result != undefined) {
-        await assertNotExists(findTooltip, `打开菜单 ${name} 超时`, timeout, 1000, () => {
-            click(x, result.y);
+    if (tooltip != undefined) {
+        await assertRegionDisappearing(findTooltip, `打开菜单 ${name} 超时`, () => {
+            click(Math.round(navWidth / 2), tooltip.y);
         });
     }
     else {
@@ -45,50 +65,67 @@ export const openMenu = async (name, reverse = false, config = {}) => {
 /**
  * 打开游戏菜单页面（菜单按钮列表）
  * @param name 菜单页面名称
- * @param config 菜单页面视图参数
+ * @param listView 菜单页面视图参数
  */
-export const openMenuPage = async (name, config = {}) => {
+export const openMenuPage = async (name, listView) => {
     // 1.打开派蒙菜单
     await openPaimonMenu();
-    // 2.搜索菜单页面
-    const { x = 100, y = 330, w = 670, h = 730, lineHeight = 142 } = config;
-    const pageButton = await findTextWithinListView(name, false, true, {
-        x,
-        y,
-        w,
-        h,
-        maxListItems: 5,
-        lineHeight
+    // 2.搜索菜单页面按钮
+    const button = await withGameMetrics(1920, 1080, 1.5, async () => {
+        const { x = 95, y = 330, w = 670, h = 730, lineHeight = 142 } = listView || {};
+        return await findTextWithinListView(name, { x, y, w, h, lineHeight, scrollLines: 2 });
     });
-    if (!pageButton)
+    if (!button)
         throw new Error(`搜索菜单页面 ${name} 失败`);
-    // 3.点击菜单页面
-    pageButton.click();
+    // 3.点击打开菜单页面
+    await assertRegionDisappearing(() => findTextWithinBounds(name, button.x, button.y, button.width, button.height), `打开菜单页面 ${name} 超时`, () => {
+        button.click();
+    });
 };
 /**
- * 调整游戏时间
- * @param period 时间段
- * @param config 时钟参数
+ * 调整游戏时间到指定时分
+ * @param hour 小时
+ * @param minute 分钟
+ * @param options 时钟参数
  */
-export const setTime = async (period, config = {}) => {
+export const setTimeTo = async (hour, minute, options) => {
     // 1.打开时间页面
     await openMenu("时间", true);
-    // 2.拨动指针
-    const { centerX = 1440, centerY = 502, radius = 400, offset = 5 } = config;
-    const index = ["night", "morning", "noon", "evening"].indexOf(period);
-    const periodsDirections = [
-        () => mouseSlide(centerX, centerY, centerX - offset, centerY + radius),
-        () => mouseSlide(centerX, centerY, centerX - radius, centerY - offset),
-        () => mouseSlide(centerX, centerY, centerX + offset, centerY - radius),
-        () => mouseSlide(centerX, centerY, centerX + radius, centerY + offset)
-    ];
-    const jobs = Array.from({ length: 4 }, (_, i) => periodsDirections[(index + i + 1) % periodsDirections.length]);
-    for (const job of jobs)
-        await job();
-    // 3.点击确认按钮，等待调整结束
-    await assertExists(() => findTextInDirection("时间少于", true, true, "south-east"), "调整时间超时", 20 * 1000, 1000, () => {
-        findTextInDirection("确认", false, true, "south-east")?.click();
+    // 2.计算调整时钟的路径点
+    const { centerX = 1440, centerY = 502, offsetHours = 6, radius = 154, smooth = 3 } = options || {};
+    const radian = ((((hour + offsetHours) * 60 + minute) % 1440) / 1440) * Math.PI * 2;
+    const waypoints = [{ x: centerX, y: centerY }].concat(Array.from({ length: Math.max(smooth, 3) })
+        // 计算弧度
+        .map((_, i) => radian + (1 + i / (Math.max(smooth, 3) - 1)) * Math.PI)
+        // 计算相对圆点坐标
+        .map(rad => ({ x: radius * Math.cos(rad), y: radius * Math.sin(rad) }))
+        // 计算绝对坐标
+        .map(p => ({ x: Math.round(p.x + centerX), y: Math.round(p.y + centerY) })));
+    // 3.拨动指针
+    await withGameMetrics(1920, 1080, 1.5, async () => {
+        await mouseMoveAlongWaypoints(waypoints, { shouldDrag: true });
+        // 3.点击确认按钮，等待调整结束
+        await assertRegionAppearing(() => findTextInDirection("时间少于", "south-east", { contains: true }), "调整时间超时", () => {
+            findTextInDirection("确认", "south-east")?.click();
+        }, { maxAttempts: 20, retryInterval: 1000 });
     });
     // 4.返回主界面
     await genshin.returnMainUi();
 };
+/**
+ * 调整游戏时间到指定时间段
+ * @param period 时间段
+ * @param options 时钟参数
+ */
+export const setTime = async (period, options) => {
+    switch (period) {
+        case "night":
+            return setTimeTo(0, 0, options);
+        case "morning":
+            return setTimeTo(6, 0, options);
+        case "noon":
+            return setTimeTo(12, 0, options);
+        case "evening":
+            return setTimeTo(18, 0, options);
+    }
+};

package/dist/http.js

@@ -6,8 +6,8 @@
  * @param headers 请求头
  * @returns 响应体内容
  */
-export const requestForBody = async (method, url, body = "null", headers) => {
-    const resp = await http.request(method, url, body, headers ? JSON.stringify(headers) : "null");
+export const requestForBody = async (method, url, body, headers) => {
+    const resp = await http.request(method, url, body ?? "null", headers ? JSON.stringify(headers) : "null");
     if (resp.status_code >= 200 && resp.status_code < 400) {
         return resp.body;
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export * from "./flow";
+export * from "./asserts";
+export * from "./workflow";
 export * from "./game";
 export * from "./http";
 export * from "./mouse";

package/dist/index.js

@@ -1,4 +1,5 @@
-export * from "./flow";
+export * from "./asserts";
+export * from "./workflow";
 export * from "./game";
 export * from "./http";
 export * from "./mouse";

package/dist/mouse.d.ts

@@ -1,3 +1,50 @@
+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 = {
+    /** 移动持续时间（毫秒） */
+    duration: number;
+    /** 摆动幅度（像素） */
+    wiggle?: number;
+    /** 随机种子 */
+    seed?: number;
+    /** 缓动函数 */
+    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 +69,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;
+    /** 每次滚动的行数 */
+    scrollLines?: number;
+    /** 横向内边距 */
+    paddingX?: number;
+    /** 纵向内边距 */
+    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 = {
+    /** 重试次数 */
+    maxAttempts?: number;
+    /** 重试间隔（毫秒） */
+    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>;

package/dist/workflow.js

@@ -0,0 +1,72 @@
+/** 默认最大重试次数 */
+const defaultMaxAttempts = 5;
+/** 默认重试间隔（毫秒） */
+const defaultRetryInterval = 1000;
+/**
+ * 等待直到条件满足或超时，期间执行重试操作
+ * @param condition 返回条件是否满足的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  条件满足
+ *          - false 达到最大重试次数
+ */
+export const waitForAction = async (condition, retryAction, options) => {
+    const { maxAttempts = defaultMaxAttempts, retryInterval = defaultRetryInterval } = options || {};
+    for (let i = 0; i < maxAttempts; i++) {
+        if (condition())
+            return true;
+        await retryAction?.();
+        await sleep(retryInterval);
+    }
+    return false;
+};
+/**
+ * 等待某个区域出现，期间执行重试操作
+ * @param regionProvider 返回区域的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  区域出现
+ *          - false 达到最大重试次数
+ */
+export const waitForRegionAppear = async (regionProvider, retryAction, options) => {
+    return waitForAction(() => {
+        const region = regionProvider();
+        return region != null && region.isExist();
+    }, retryAction, options);
+};
+/**
+ * 等待某个区域消失，期间执行重试操作
+ * @param regionProvider 返回区域的函数
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  区域消失
+ *          - false 达到最大重试次数
+ */
+export const waitForRegionDisappear = async (regionProvider, retryAction, options) => {
+    return waitForAction(() => {
+        const region = regionProvider();
+        return !region || !region.isExist();
+    }, retryAction, options);
+};
+/**
+ * 等待整个画面上某个元素出现，期间执行重试操作
+ * @param recognitionObject 识别对象
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  整个画面上某个元素出现
+ *          - false 达到最大重试次数
+ */
+export const waitForElementAppear = async (recognitionObject, retryAction, options) => {
+    return waitForRegionAppear(() => captureGameRegion().find(recognitionObject), retryAction, options);
+};
+/**
+ * 等待整个画面上某个元素消失，期间执行重试操作
+ * @param recognitionObject 识别对象
+ * @param retryAction 每次重试时执行的操作（可选）
+ * @param options 配置选项
+ * @returns - true  整个画面上某个元素消失
+ *          - false 达到最大重试次数
+ */
+export const waitForElementDisappear = async (recognitionObject, retryAction, options) => {
+    return waitForRegionDisappear(() => captureGameRegion().find(recognitionObject), retryAction, options);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -33,7 +33,7 @@
     "build": "tsc"
   },
   "devDependencies": {
-    "@bettergi/types": "^0.0.14",
+    "@bettergi/types": "^0.1.1",
     "typescript": "^5.9.3"
   }
 }