assistsx-js 0.2.2 → 0.2.4

package/src/step-flow/runner.ts

@@ -0,0 +1,128 @@
+import { Step, type StepImpl } from "../step";
+import { StepError } from "../step-error";
+import type { StepFlowConfig, StepFlowData, StepFlowOutcome } from "./types";
+
+function ensureFlowMeta(step: Step, config: StepFlowConfig): void {
+    const data = step.data as StepFlowData;
+    if (!data.__flow) {
+        data.__flow = { id: config.id, state: config.initial };
+    }
+}
+
+function setFlowState(step: Step, state: string, config: StepFlowConfig): void {
+    const data = step.data as StepFlowData;
+    if (!data.__flow) {
+        data.__flow = { id: config.id, state };
+    } else {
+        data.__flow.state = state;
+    }
+}
+
+function resolveOutcome(
+    config: StepFlowConfig,
+    currentState: string,
+    outcome: StepFlowOutcome
+): string | null | undefined | "legacy" {
+    if (outcome.type === "end") {
+        return undefined;
+    }
+    if (outcome.type === "repeat") {
+        return null;
+    }
+    if (outcome.type === "legacy") {
+        return "legacy";
+    }
+    const stateDef = config.states[currentState];
+    if (!stateDef) {
+        throw new StepError(`StepFlow: unknown state "${currentState}"`, {
+            flowId: config.id,
+            state: currentState,
+        });
+    }
+    const nextState = stateDef.on[outcome.name];
+    if (!nextState) {
+        throw new StepError(
+            `StepFlow: no transition for event "${outcome.name}" in state "${currentState}"`,
+            { flowId: config.id, state: currentState, event: outcome.name }
+        );
+    }
+    return nextState;
+}
+
+function createDispatcher(config: StepFlowConfig): StepImpl {
+    const dispatcher: StepImpl = async (step) => {
+        ensureFlowMeta(step, config);
+        const data = step.data as StepFlowData;
+        const currentState = data.__flow!.state;
+        const stateDef = config.states[currentState];
+        if (!stateDef) {
+            throw new StepError(`StepFlow: unknown state "${currentState}"`, {
+                flowId: config.id,
+                state: currentState,
+            });
+        }
+
+        const outcome = await stateDef.run(step);
+        const resolved = resolveOutcome(config, currentState, outcome);
+
+        if (resolved === undefined) {
+            return undefined;
+        }
+        if (resolved === null) {
+            return step.repeat();
+        }
+        if (resolved === "legacy") {
+            if (outcome.type !== "legacy") {
+                throw new StepError("StepFlow: internal legacy outcome mismatch");
+            }
+            return step.next(outcome.impl);
+        }
+
+        setFlowState(step, resolved, config);
+        return step.next(dispatcher);
+    };
+    return dispatcher;
+}
+
+/** 创建流程调度 StepImpl（需先填充 config.states，见 createLaunchState） */
+export function createFlowDispatcher(config: StepFlowConfig): StepImpl {
+    return createDispatcher(config);
+}
+
+export function buildFlowInitialData(config: StepFlowConfig): StepFlowData {
+    return {
+        payload: config.data ?? {},
+        __flow: {
+            id: config.id,
+            state: config.initial,
+        },
+    };
+}
+
+export class StepFlow {
+    /**
+     * 按状态机配置运行流程，内部复用 Step.run 与现有步骤循环。
+     */
+    static async run(
+        config: StepFlowConfig,
+        options?: {
+            stepId?: string;
+            tag?: string;
+            delayMs?: number;
+            exceptionRetryCountMax?: number;
+        }
+    ): Promise<Step | undefined> {
+        if (!config.states[config.initial]) {
+            throw new StepError(
+                `StepFlow: initial state "${config.initial}" is not defined`,
+                { flowId: config.id }
+            );
+        }
+        const dispatcher = createDispatcher(config);
+        return Step.run(dispatcher, {
+            ...options,
+            tag: options?.tag ?? config.id,
+            data: buildFlowInitialData(config),
+        });
+    }
+}

package/src/step.ts

@@ -6,11 +6,15 @@ import { AssistsX } from "./assistsx";
 import { Node } from "./node";
 import { CallMethod } from "./call-method";
 import { useStepStore } from "./step-state-store";
+import { ensureAssistsXPinia } from "./pinia-ensure";
 import { generateUUID } from "./utils";
 import { StepError, StepStopError } from "./step-error";
 import { StepAsync } from "./step-async";
 import type { NodeLookupScope } from "./node-lookup-scope";
 
+// 步骤数据类型，始终为普通对象
+export type StepData = Record<string, any>;
+
 // 步骤结果类型，可以是Step实例或undefined
 export type StepResult = Step | undefined;
 
@@ -27,6 +31,34 @@ export class Step {
     static showLog: boolean = false;
     static exceptionRetryCountMaxDefault: number = 3;
 
+    /**
+     * 判断步骤数据是否有效（非空且为普通对象）
+     */
+    private static isValidStepData(data: unknown): data is StepData {
+        return (
+            data !== null &&
+            data !== undefined &&
+            typeof data === "object" &&
+            !Array.isArray(data)
+        );
+    }
+
+    /**
+     * 解析步骤数据：优先使用传入值，否则使用当前值，均无效时返回空对象
+     */
+    private static resolveStepData(
+        provided?: StepData,
+        fallback?: StepData
+    ): StepData {
+        if (provided !== undefined && Step.isValidStepData(provided)) {
+            return provided;
+        }
+        if (fallback !== undefined && Step.isValidStepData(fallback)) {
+            return fallback;
+        }
+        return {};
+    }
+
     /**
      * 当前执行步骤的ID
      */
@@ -60,13 +92,15 @@ export class Step {
         }: {
             stepId?: string | undefined;
             tag?: string | undefined;
-            data?: any | undefined;
+            data?: StepData;
             delayMs?: number;
             exceptionRetryCountMax?: number;
         } = {}
     ): Promise<Step | undefined> {
         this.exception = undefined;
+        ensureAssistsXPinia();
         const stepStore = useStepStore();
+        const resolvedData = Step.resolveStepData(data);
         let implnName = impl.name;
         let currentStep: Step | undefined;
         let nextStep: Step | undefined;
@@ -84,12 +118,12 @@ export class Step {
                 }
             }
 
-            stepStore.startStep(this._stepId, tag, data);
+            stepStore.startStep(this._stepId, tag, resolvedData);
             currentStep = new Step({
                 stepId: this._stepId,
                 impl,
                 tag,
-                data,
+                data: resolvedData,
                 delayMs,
                 exceptionRetryCountMax,
             });
@@ -228,7 +262,7 @@ export class Step {
             const errorMsg = JSON.stringify({
                 impl: implnName,
                 tag: tag,
-                data: data,
+                data: resolvedData,
                 error: e?.message ?? String(e),
             });
             stepStore.setError(errorMsg);
@@ -402,7 +436,7 @@ export class Step {
     /**
      * 步骤数据
      */
-    data: any | undefined;
+    data: StepData;
 
     /**
      * 步骤延迟时间(毫秒)
@@ -435,7 +469,7 @@ export class Step {
         stepId: string;
         impl: StepImpl | undefined;
         tag?: string | undefined;
-        data?: any | undefined;
+        data?: StepData;
         delayMs?: number;
         repeatCountMax?: number;
         exceptionRetryCountMax?: number;
@@ -443,7 +477,7 @@ export class Step {
     }) {
         this.tag = tag;
         this.stepId = stepId;
-        this.data = data ?? {};
+        this.data = Step.resolveStepData(data);
         this.impl = impl;
         this.delayMs = delayMs;
         this.repeatCountMax = repeatCountMax;
@@ -472,7 +506,7 @@ export class Step {
             exceptionRetryCountMax = Step.exceptionRetryCountMaxDefault,
         }: {
             tag?: string | undefined;
-            data?: any | undefined;
+            data?: StepData;
             delayMs?: number;
             repeatCountMax?: number;
             exceptionRetryCountMax?: number;
@@ -483,7 +517,7 @@ export class Step {
             stepId: this.stepId,
             impl,
             tag,
-            data: data ?? this.data ?? {},
+            data: Step.resolveStepData(data, this.data),
             delayMs,
             repeatCountMax,
             exceptionRetryCountMax,
@@ -498,7 +532,7 @@ export class Step {
             exceptionRetryCountMax = Step.exceptionRetryCountMaxDefault,
         }: {
             tag?: string | undefined;
-            data?: any | undefined;
+            data?: StepData;
             delayMs?: number;
             repeatCountMax?: number;
             exceptionRetryCountMax?: number;
@@ -509,7 +543,7 @@ export class Step {
             stepId: this.stepId,
             impl: undefined,
             tag,
-            data: data ?? this.data ?? {},
+            data: Step.resolveStepData(data, this.data),
             delayMs,
             repeatCountMax,
             exceptionRetryCountMax,
@@ -528,14 +562,14 @@ export class Step {
     repeat({
         stepId = this.stepId,
         tag = this.tag,
-        data = this.data ?? {},
+        data,
         delayMs = this.delayMs,
         repeatCountMax = this.repeatCountMax,
         exceptionRetryCountMax = this.exceptionRetryCountMax,
     }: {
         stepId?: string;
         tag?: string | undefined;
-        data?: any | undefined;
+        data?: StepData;
         delayMs?: number;
         repeatCountMax?: number;
         exceptionRetryCountMax?: number;
@@ -544,7 +578,7 @@ export class Step {
         this.repeatCount++;
         this.stepId = stepId;
         this.tag = tag;
-        this.data = data;
+        this.data = Step.resolveStepData(data, this.data);
         this.delayMs = delayMs;
         this.repeatCountMax = repeatCountMax;
         this.exceptionRetryCountMax = exceptionRetryCountMax;

package/src/window-flags.ts

@@ -90,6 +90,27 @@ export class WindowFlags {
         return flags & ~flag;
     }
 
+    /** 输入框获取焦点时使用的悬浮窗 flag 组合（不含 FLAG_NOT_FOCUSABLE） */
+    static getOverlayInputFocusFlagList(): number[] {
+        return [
+            WindowFlags.FLAG_WATCH_OUTSIDE_TOUCH,
+            WindowFlags.FLAG_NOT_TOUCH_MODAL,
+            WindowFlags.FLAG_LAYOUT_NO_LIMITS,
+            WindowFlags.FLAG_LAYOUT_IN_SCREEN,
+        ];
+    }
+
+    /** 输入框失去焦点时使用的悬浮窗 flag 组合（含 FLAG_NOT_FOCUSABLE） */
+    static getOverlayInputBlurFlagList(): number[] {
+        return [
+            WindowFlags.FLAG_WATCH_OUTSIDE_TOUCH,
+            WindowFlags.FLAG_NOT_TOUCH_MODAL,
+            WindowFlags.FLAG_LAYOUT_NO_LIMITS,
+            WindowFlags.FLAG_NOT_FOCUSABLE,
+            WindowFlags.FLAG_LAYOUT_IN_SCREEN,
+        ];
+    }
+
     /**
      * 获取所有标志位的描述信息
      * @returns 标志位描述对象数组