@bettergi/types 0.1.14 → 0.1.16

package/bindings/RealtimeTimer.d.ts

@@ -1,4 +1,4 @@
-import type { RealtimeTimerHostType } from "../types/BetterGenshinImpact/Core/Script/Dependence/Model/RealTimeTimer";
+import type { RealtimeTimerHostType } from "../types/BetterGenshinImpact/Core/Script/Dependence/Model/RealtimeTimer";
 
 declare global {
   /**

package/bindings/getAvatars.d.ts

@@ -1,8 +1,9 @@
+import type { AvatarName } from "../types/BetterGenshinImpact/GameTask/AutoFight/Model/Avatar";
 import type { HostArray, HostDelegate } from "../types/Microsoft/ClearScript/HostType";
 
 interface getAvatarsHostDelegate extends HostDelegate {
-  (): HostArray<string>;
-  invoke(): HostArray<string>;
+  (): HostArray<AvatarName>;
+  invoke(): HostArray<AvatarName>;
 }
 
 declare global {

package/bindings/htmlMask.d.ts

@@ -1,3 +1,8 @@
+/**
+ * 脚本侧 HTML 遮罩全局（ClearScript 宿主对象）。
+ * 启用：`import "@bettergi/types/htmlMask/host"` 或整包 `@bettergi/types`。
+ * 遮罩页（WebView）侧见 `@bettergi/types/htmlMask/webview`。
+ */
 import "../types/BetterGenshinImpact/Core/Script/Dependence/HtmlMask";
 
 declare global {

package/bindings/htmlMask.webview.d.ts

@@ -0,0 +1,92 @@
+/**
+ * HTML 遮罩页（WebView2）侧通信桥类型。
+ * 对应宿主 `HtmlMaskWindow` 在 DocumentCreated 时注入的 helper，
+ * 与脚本侧 `@bettergi/types/htmlMask/host`（ClearScript `htmlMask` 全局）相对。
+ *
+ * 启用：`import "@bettergi/types/htmlMask/webview"` 或
+ * `/// <reference types="@bettergi/types/htmlMask/webview" />`
+ *
+ * @see BetterGenshinImpact.View.HtmlMaskWindow
+ * @since 0.61.0
+ */
+
+/**
+ * 遮罩页与脚本之间的消息信封
+ * 宿主 JSON 使用 camelCase（url / data / requestId）
+ * @since 0.61.0
+ */
+export interface HtmlMaskWebViewMessage {
+  /** 消息路径；页→脚本的 request 与脚本→页的推送均使用 */
+  url?: string;
+  /** 业务载荷；解析失败时可能不存在 */
+  data?: unknown;
+  /**
+   * 请求-应答关联 ID
+   * - 页发起 request 时由注入脚本生成（`__req_*`）
+   * - 脚本发起 request 时由宿主生成；页 onMessage 若返回值非 undefined 则自动回传
+   */
+  requestId?: string;
+}
+
+/**
+ * 注入到遮罩页的 `window.htmlMask` 助手
+ * 内部还含 `_callbacks` / `_seq` / `_dispatch`，属实现细节，不纳入公开类型
+ * @since 0.61.0
+ */
+export interface HtmlMaskWebView {
+  /**
+   * 向脚本侧发起请求并等待响应
+   * 经 `chrome.webview.postMessage` 送出 `{ url, data, requestId }`；
+   * 匹配到带同一 requestId 的入站消息后 resolve 整包对象
+   * @param url 消息路径
+   * @param data 载荷，省略时按 `{}` 发送
+   * @since 0.61.0
+   */
+  request(url: string, data?: unknown): Promise<HtmlMaskWebViewMessage>;
+
+  /**
+   * 脚本推送到页的消息回调
+   * - 入站 JSON 解析成功：参数为消息对象
+   * - 解析失败：参数为原始字符串，且仍调用本回调
+   * - 若消息带 `requestId` 且返回值不是 `undefined`，助手会将结果
+   *   （支持 Promise）以 `{ requestId, url: "/__response__", data }` 回传脚本
+   * @since 0.61.0
+   */
+  onMessage: ((msg: HtmlMaskWebViewMessage | string) => unknown) | null;
+}
+
+/**
+ * WebView2 提供的 `chrome.webview` 子集（遮罩页实际使用的面）
+ * @since 0.61.0
+ */
+export interface ChromeWebView {
+  /**
+   * 向宿主发送字符串消息（须为 JSON 文本）
+   * @since 0.61.0
+   */
+  postMessage(message: string): void;
+  /**
+   * 监听宿主 `PostWebMessageAsString` 推送
+   * @since 0.61.0
+   */
+  addEventListener(type: "message", listener: (event: { data: string }) => void): void;
+}
+
+declare global {
+  interface Window {
+    /**
+     * HTML 遮罩页通信桥（宿主注入；非宿主环境可能不存在）
+     * @since 0.61.0
+     */
+    htmlMask?: HtmlMaskWebView;
+    /**
+     * WebView2 宿主对象；仅 WebView 内可用
+     * @since 0.61.0
+     */
+    chrome?: {
+      webview?: ChromeWebView;
+    };
+  }
+}
+
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/types",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "BetterGI TypeScript 类型定义",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -18,6 +18,12 @@
   "exports": {
     ".": {
       "types": "./index.d.ts"
+    },
+    "./htmlMask/host": {
+      "types": "./bindings/htmlMask.d.ts"
+    },
+    "./htmlMask/webview": {
+      "types": "./bindings/htmlMask.webview.d.ts"
     }
   },
   "files": [

package/types/BetterGenshinImpact/Core/BgiVision/BvLocator.d.ts

@@ -6,14 +6,20 @@ import type {
   StrongNumeric
 } from "../../../Microsoft/ClearScript/HostType";
 import "../../../OpenCvSharp/Rect";
-import "../../../System/Action";
 import "../../../System/Collections/Generic/List";
-import "../../../System/Func";
 import "../../../System/Nullable";
 import "../../../System/Threading/CancellationToken";
 import "../../GameTask/Model/Area/Region";
 import "../Recognition/RecognitionObject";
 
+/**
+ * 重试前回调：收到当前匹配区域列表；可为同步或返回 Promise 的异步脚本函数
+ * @since 0.61.0
+ */
+export type BvLocatorRetryAction = (
+  regions: System.Collections.Generic.List<BetterGenshinImpact.GameTask.Model.Area.Region>
+) => void | Promise<void>;
+
 /**
  * BgiVision 定位器，按识别配置查找并操作匹配区域
  * @since 0.57.0
@@ -27,13 +33,10 @@ export interface BvLocator extends ClrHostValue {
    */
   readonly recognitionObject: BetterGenshinImpact.Core.Recognition.RecognitionObject;
   /**
-   * 每次重试前执行的回调
+   * 每次重试前执行的回调；脚本侧可直接赋函数，`null` 清除
    * @since 0.57.0
    */
-  retryAction: System.Func<
-    System.Collections.Generic.List<BetterGenshinImpact.GameTask.Model.Area.Region>,
-    Promise<void>
-  >;
+  retryAction: BvLocatorRetryAction | null;
   /**
    * 按当前识别配置查找全部匹配区域；不建议脚本直接调用
    * @returns 匹配到的区域列表
@@ -118,12 +121,12 @@ export interface BvLocator extends ClrHostValue {
   tryWaitForDisappear(timeout: number | StrongNumeric<Int32Host> | null | null): Promise<void>;
   /**
    * 设置感兴趣区域（ROI），覆盖识别配置中的 RegionOfInterest
-   * @param deltaFunc 由当前最大 1080P 捕获矩形计算 ROI 的回调
+   * @param deltaFunc 由当前最大 1080P 捕获矩形计算 ROI 的脚本回调
    * @returns 当前定位器，便于链式调用
    * @since 0.57.0
    */
   withRoi(
-    deltaFunc: System.Func<OpenCvSharp.Rect, OpenCvSharp.Rect>
+    deltaFunc: (captureRect: OpenCvSharp.Rect) => OpenCvSharp.Rect
   ): BetterGenshinImpact.Core.BgiVision.BvLocator;
   /**
    * 设置感兴趣区域（ROI），覆盖识别配置中的 RegionOfInterest
@@ -151,28 +154,20 @@ export interface BvLocator extends ClrHostValue {
     retryInterval: number | StrongNumeric<Int32Host>
   ): BetterGenshinImpact.Core.BgiVision.BvLocator;
   /**
-   * 设置每次重试前执行的回调；支持同步与异步脚本函数
-   * @param action 收到当前匹配区域列表时调用的回调；传入 null 清除回调
+   * 设置每次重试前执行的回调；支持同步与异步脚本函数（对应上游 `Action` 与 `dynamic` 重载）
+   * @param action 收到当前匹配区域列表时调用的脚本回调；传入 null 清除回调
    * @returns 当前定位器，便于链式调用
    * @since 0.61.0
    */
   withRetryAction(
-    action: System.Action<
-      System.Collections.Generic.List<BetterGenshinImpact.GameTask.Model.Area.Region>
-    > | null
+    action: BvLocatorRetryAction | null
   ): BetterGenshinImpact.Core.BgiVision.BvLocator;
-  /**
-   * 设置每次重试前执行的回调；供脚本传入无法隐式转为 Action 的函数
-   * @param action 脚本回调；可为同步函数或返回 Promise 的异步函数
-   * @returns 当前定位器，便于链式调用
-   * @since 0.61.0
-   */
-  withRetryAction(action: unknown): BetterGenshinImpact.Core.BgiVision.BvLocator;
 }
 
 declare global {
   namespace BetterGenshinImpact.Core.BgiVision {
     type BvLocator = import("./BvLocator").BvLocator;
+    type BvLocatorRetryAction = import("./BvLocator").BvLocatorRetryAction;
   }
 }
 

package/types/BetterGenshinImpact/Core/Script/Dependence/Dispatcher.d.ts

@@ -11,10 +11,11 @@ import "../../../../System/Threading/CancellationTokenSource";
 import "../../../GameTask/AutoBoss/AutoBossParam";
 import "../../../GameTask/AutoDomain/AutoDomainParam";
 import "../../../GameTask/AutoFight/AutoFightParam";
+import type { AvatarName } from "../../../GameTask/AutoFight/Model/Avatar";
 import "../../../GameTask/AutoLeyLineOutcrop/AutoLeyLineOutcropParam";
 import "../../../GameTask/AutoStygianOnslaught/AutoStygianOnslaughtParam";
 import "../../../GameTask/Common/Job/CountInventoryItemParam";
-import "./Model/RealTimeTimer";
+import "./Model/RealtimeTimer";
 import "./Model/SoloTask";
 
 /**
@@ -135,10 +136,10 @@ export interface Dispatcher extends ClrHostValue {
    * @since unreleased
    */
   runCombatScript(script: string): Promise<void>;
-  runCombatScript(script: string, avatarName: string | null): Promise<void>;
+  runCombatScript(script: string, avatarName: AvatarName | null): Promise<void>;
   runCombatScript(
     script: string,
-    avatarName: string | null,
+    avatarName: AvatarName | null,
     customCt: System.Threading.CancellationToken | null | null
   ): Promise<void>;
   /**

package/types/BetterGenshinImpact/Core/Script/Dependence/Genshin.d.ts

@@ -12,8 +12,10 @@ import type { VoidResult } from "../../../../Microsoft/ClearScript/VoidResult";
 import "../../../../OpenCvSharp/Point2f";
 import "../../../../System/Lazy";
 import "../../../../System/Nullable";
+import type { AvatarName } from "../../../GameTask/AutoFight/Model/Avatar";
 import "../../../GameTask/AutoPathing/NavigationInstance";
 import "../../../GameTask/Common/Job/CraftMaterialTask";
+import type { CraftMaterialType } from "../../../GameTask/Common/Job/CraftMaterialTask";
 import type {
   Area,
   CountryName,
@@ -281,18 +283,27 @@ export interface Genshin extends ClrHostValue {
    * 按槽位重组当前队伍角色
    * 未传入或空字符串的槽位跳过；重组队伍槽位角色，不是按数字键切换当前出战角色
    * 示例：`await genshin.switchCharacter("胡桃", "夜兰", "", "钟离")`
-   * @param slot1 1 号位角色名
-   * @param slot2 2 号位角色名
-   * @param slot3 3 号位角色名
-   * @param slot4 4 号位角色名
+   * @param slot1 1 号位角色名，空字符串表示跳过
+   * @param slot2 2 号位角色名，空字符串表示跳过
+   * @param slot3 3 号位角色名，空字符串表示跳过
+   * @param slot4 4 号位角色名，空字符串表示跳过
    * @returns 在任务完成后兑现是否成功的 Promise；完成保存并返回主界面为 true，参数无效、目标角色未找到或流程失败为 false
    * @since unreleased
    */
   switchCharacter(): Promise<boolean>;
-  switchCharacter(slot1: string): Promise<boolean>;
-  switchCharacter(slot1: string, slot2: string): Promise<boolean>;
-  switchCharacter(slot1: string, slot2: string, slot3: string): Promise<boolean>;
-  switchCharacter(slot1: string, slot2: string, slot3: string, slot4: string): Promise<boolean>;
+  switchCharacter(slot1: "" | AvatarName): Promise<boolean>;
+  switchCharacter(slot1: "" | AvatarName, slot2: "" | AvatarName): Promise<boolean>;
+  switchCharacter(
+    slot1: "" | AvatarName,
+    slot2: "" | AvatarName,
+    slot3: "" | AvatarName
+  ): Promise<boolean>;
+  switchCharacter(
+    slot1: "" | AvatarName,
+    slot2: "" | AvatarName,
+    slot3: "" | AvatarName,
+    slot4: "" | AvatarName
+  ): Promise<boolean>;
   /**
    * 清除当前调度器的队伍缓存
    * @returns ClearScript 宿主空结果
@@ -361,7 +372,7 @@ export interface Genshin extends ClrHostValue {
   craftMaterial(
     materialName: string,
     quantity: number | StrongNumeric<Int32Host>,
-    materialType: string | null
+    materialType: CraftMaterialType | null
   ): Promise<BetterGenshinImpact.GameTask.Common.Job.CraftMaterialResult>;
   /**
    * 返回主界面

package/types/BetterGenshinImpact/Core/Script/Dependence/Http.d.ts

@@ -84,6 +84,7 @@ declare global {
 declare global {
   namespace BetterGenshinImpact.Core.Script.Dependence {
     type Http = import("./Http").Http;
+    type HttpMethod = import("./Http").HttpMethod;
   }
 }
 

package/types/BetterGenshinImpact/Core/Script/Dependence/KeyMouseHook.d.ts

@@ -6,15 +6,16 @@ import type {
   ReferenceTypeTrait,
   StrongNumeric
 } from "../../../../Microsoft/ClearScript/HostType";
-import "../../../../Microsoft/ClearScript/ScriptObject";
 import type { VoidResult } from "../../../../Microsoft/ClearScript/VoidResult";
 import "../../../../System/IDisposable";
+import type { Keys } from "../../../../System/Windows/Forms/Keys";
 
 /**
  * 钩子回报的鼠标按键
  * @since 0.55.0
  */
 export type MouseButton =
+  | "None"
   | "Left" // 左键
   | "Right" // 右键
   | "Middle" // 中键
@@ -36,8 +37,9 @@ export interface KeyMouseHook extends ClrHostValue, System.IDisposableInput {
    * @returns ClearScript 宿主空结果
    * @since 0.55.0
    */
-  onKeyDown(callback: Microsoft.ClearScript.ScriptObject): VoidResult;
-  onKeyDown(callback: Microsoft.ClearScript.ScriptObject, useCodeOnly: boolean): VoidResult;
+  onKeyDown(callback: (keyCode: Keys) => void): VoidResult;
+  onKeyDown(callback: (keyCode: Keys) => void, useCodeOnly: true): VoidResult;
+  onKeyDown(callback: string, useCodeOnly: false): VoidResult;
   /**
    * 注册键盘释放事件回调
    * @param callback 回调函数
@@ -45,22 +47,23 @@ export interface KeyMouseHook extends ClrHostValue, System.IDisposableInput {
    * @returns ClearScript 宿主空结果
    * @since 0.55.0
    */
-  onKeyUp(callback: Microsoft.ClearScript.ScriptObject): VoidResult;
-  onKeyUp(callback: Microsoft.ClearScript.ScriptObject, useCodeOnly: boolean): VoidResult;
+  onKeyUp(callback: (keyCode: Keys) => void): VoidResult;
+  onKeyUp(callback: (keyCode: Keys) => void, useCodeOnly: true): VoidResult;
+  onKeyUp(callback: string, useCodeOnly: false): VoidResult;
   /**
    * 注册鼠标按下事件回调
    * @param callback 回调，参数为按键名与游戏窗口局部坐标
    * @returns ClearScript 宿主空结果
    * @since 0.55.0
    */
-  onMouseDown(callback: (button: MouseButton, x: number, y: number) => void): VoidResult;
+  onMouseDown(callback: (button: MouseButton, localX: number, localY: number) => void): VoidResult;
   /**
    * 注册鼠标抬起事件回调
    * @param callback 回调，参数为按键名与游戏窗口局部坐标
    * @returns ClearScript 宿主空结果
    * @since 0.55.0
    */
-  onMouseUp(callback: (button: MouseButton, x: number, y: number) => void): VoidResult;
+  onMouseUp(callback: (button: MouseButton, localX: number, localY: number) => void): VoidResult;
   /**
    * 注册鼠标移动事件回调
    * @param callback 回调函数
@@ -97,6 +100,7 @@ export interface KeyMouseHook extends ClrHostValue, System.IDisposableInput {
 declare global {
   namespace BetterGenshinImpact.Core.Script.Dependence {
     type KeyMouseHook = import("./KeyMouseHook").KeyMouseHook;
+    type MouseButton = import("./KeyMouseHook").MouseButton;
   }
 }
 

package/types/BetterGenshinImpact/Core/Script/Dependence/LimitedFile.d.ts

@@ -64,11 +64,14 @@ export interface LimitedFile extends ClrHostValue {
    * 异步读取文件全部文本
    * 读取失败时通过回调传入错误并返回空字符串
    * @param path 相对工作区的文件路径
-   * @param callbackFunc 回调函数，签名为 (error, text)
+   * @param callbackFunc 脚本回调 `(error, text)`；成功时 `error` 为 null，失败时 `text` 为 null
    * @returns 在任务完成后兑现文件文本的 Promise
    * @since 0.43.1
    */
-  readText(path: string, callbackFunc: unknown): Promise<string>;
+  readText(
+    path: string,
+    callbackFunc: (error: string | null, text: string | null) => void
+  ): Promise<string>;
   /**
    * 异步读取文件全部文本
    * 读取失败时返回空字符串
@@ -130,17 +133,21 @@ export interface LimitedFile extends ClrHostValue {
    * 异步写入文本到文件并触发回调
    * @param path 相对工作区的文件路径
    * @param content 要写入的内容
-   * @param callbackFunc 回调函数，签名为 (error, success)
+   * @param callbackFunc 脚本回调 `(error, success)`；成功时 `error` 为 null，失败时 `success` 为 null
    * @param append 是否追加到文件末尾，默认为 false（覆盖）
    * @returns 在任务完成后兑现是否写入成功的 Promise
    * @since 0.44.4
    */
-  writeText(path: string, content: string, callbackFunc: unknown): Promise<boolean>;
+  writeText(
+    path: string,
+    content: string,
+    callbackFunc: (error: string | null, success: boolean | null) => void
+  ): Promise<boolean>;
   writeText(path: string, content: string, append: boolean): Promise<boolean>;
   writeText(
     path: string,
     content: string,
-    callbackFunc: unknown,
+    callbackFunc: (error: string | null, success: boolean | null) => void,
     append: boolean
   ): Promise<boolean>;
   /**

package/types/BetterGenshinImpact/Core/Script/Dependence/Model/RealtimeTimer.d.ts

@@ -4,6 +4,48 @@ import type {
   PublicDefaultConstructorTrait,
   ReferenceTypeTrait
 } from "../../../../../Microsoft/ClearScript/HostType";
+import "../../../../GameTask/AutoSkip/AutoSkipConfig";
+
+/**
+ * 实时触发器名 → RealtimeTimer.Config（唯一真源；配置一律 inline，无额外 type 名）
+ * 与 `GameTaskManager.AddTrigger` / `RealtimeTimer` 构造对齐
+ * @since 0.43.1
+ */
+export type RealtimeTriggerConfigMap = {
+  /**
+   * 自动拾取
+   * 对应上游 `AutoPickExternalConfig`
+   */
+  AutoPick: {
+    /** 需要 F 的文本（对话、拾取） */
+    textList?: string[];
+    /** 无视文本和图标，遇到 F 就点击；默认 false */
+    forceInteraction?: boolean;
+  };
+  /**
+   * 自动跳过剧情
+   * 构造侧要求传入 `AutoSkipConfig` 实例
+   */
+  AutoSkip: BetterGenshinImpact.GameTask.AutoSkip.AutoSkipConfig;
+  /**
+   * 自动吃药；`AddTrigger` 可按名添加，构造不解析专用 config
+   */
+  AutoEat: void;
+};
+
+/**
+ * 实时触发器注册名 = map key；`(string & {})` 保留未知扩展
+ * @see GameTaskManager.AddTrigger
+ * @since 0.43.1
+ */
+export type RealtimeTriggerName = keyof RealtimeTriggerConfigMap | (string & {});
+
+export type RealtimeTriggerConfigForName<TName extends RealtimeTriggerName> =
+  TName extends keyof RealtimeTriggerConfigMap
+    ? RealtimeTriggerConfigMap[TName] extends void
+      ? undefined
+      : RealtimeTriggerConfigMap[TName]
+    : Record<string, unknown>;
 
 /**
  * 实时任务触发器
@@ -16,22 +58,30 @@ export interface RealtimeTimer extends ClrHostValue {
    * 实时任务触发器名称
    * @since 0.43.1
    */
-  name: string;
+  name: RealtimeTriggerName;
   /**
    * 实时任务触发间隔，单位毫秒，默认 50
    * @since 0.43.1
    */
   interval: number;
   /**
-   * 实时任务配置
+   * 实时任务配置（CLR 存 `object?`，JS 侧 plain object 或宿主配置实例）
    * @since 0.43.1
    */
-  config: unknown;
+  config:
+    | Exclude<RealtimeTriggerConfigMap[keyof RealtimeTriggerConfigMap], void>
+    | Record<string, unknown>
+    | null
+    | undefined;
 }
 
 declare global {
   namespace BetterGenshinImpact.Core.Script.Dependence.Model {
-    type RealtimeTimer = import("./RealTimeTimer").RealtimeTimer;
+    type RealtimeTimer = import("./RealtimeTimer").RealtimeTimer;
+    type RealtimeTriggerConfigForName<TName extends RealtimeTriggerName> =
+      import("./RealtimeTimer").RealtimeTriggerConfigForName<TName>;
+    type RealtimeTriggerConfigMap = import("./RealtimeTimer").RealtimeTriggerConfigMap;
+    type RealtimeTriggerName = import("./RealtimeTimer").RealtimeTriggerName;
   }
 }
 
@@ -45,18 +95,23 @@ export interface RealtimeTimerHostType extends HostType<
    */
   new (): RealtimeTimer;
   /**
-   * 构造实例
+   * 仅名称
    * @param name 实时任务触发器名称
    * @since 0.43.1
    */
-  new (name: string): RealtimeTimer;
+  new (name: RealtimeTriggerName): RealtimeTimer;
   /**
-   * 构造实例
+   * 名称 + 配置（按触发器名收窄）
    * @param name 实时任务触发器名称
    * @param config 实时任务配置
    * @since 0.43.1
    */
-  new (name: string, config: unknown): RealtimeTimer;
+  new <TName extends RealtimeTriggerName>(
+    name: TName,
+    config: RealtimeTriggerConfigForName<TName> extends undefined
+      ? Record<string, unknown> | undefined
+      : RealtimeTriggerConfigForName<TName>
+  ): RealtimeTimer;
 }
 
 export {};