assistsx-js 0.2.1 → 0.2.3

package/src/step-flow/payload.ts

@@ -0,0 +1,23 @@
+import type { Step, StepData } from "../step";
+import type { StepFlowData } from "./types";
+
+function asFlowData(step: Step): StepFlowData {
+    return step.data as StepFlowData;
+}
+
+/** 读取业务 payload（不存在时返回空对象） */
+export function getFlowPayload<T extends StepData = StepData>(step: Step): T {
+    const data = asFlowData(step);
+    const payload = data.payload;
+    if (payload !== null && payload !== undefined && typeof payload === "object" && !Array.isArray(payload)) {
+        return payload as T;
+    }
+    return {} as T;
+}
+
+/** 浅合并写入 payload */
+export function assignFlowPayload(step: Step, partial: StepData): void {
+    const data = asFlowData(step);
+    const current = getFlowPayload(step);
+    data.payload = { ...current, ...partial };
+}

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-flow/types.ts

@@ -0,0 +1,41 @@
+import type { Step, StepData } from "../step";
+
+/** 流程步骤执行结果：事件 / 重复 / 结束 / 委托 legacy StepImpl */
+export type StepFlowOutcome =
+    | { type: "event"; name: string }
+    | { type: "repeat" }
+    | { type: "end" }
+    | { type: "legacy"; impl: import("../step").StepImpl };
+
+/** 流程步骤实现：只描述 UI 与分支事件，不直接决定下一状态 */
+export type FlowStepImpl = (step: Step) => Promise<StepFlowOutcome>;
+
+/** 单个流程状态定义 */
+export interface FlowStateDef {
+    run: FlowStepImpl;
+    /** 事件名 -> 下一状态名 */
+    on: Record<string, string>;
+}
+
+/** StepFlow 运行配置 */
+export interface StepFlowConfig {
+    id?: string;
+    initial: string;
+    states: Record<string, FlowStateDef>;
+    /** 写入 step.data.payload 的初始业务数据 */
+    data?: StepData;
+}
+
+/** 库写入 step.data.__flow 的结构 */
+export interface StepFlowMeta {
+    id?: string;
+    state: string;
+}
+
+/** step.data 推荐结构（payload 用户读写，__flow 库维护） */
+export interface StepFlowData {
+    payload?: StepData;
+    __flow?: StepFlowMeta;
+    finishMethod?: import("../step").StepImpl;
+    [key: string]: unknown;
+}

package/src/step.ts

@@ -6,9 +6,14 @@ 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;
@@ -26,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
      */
@@ -59,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;
@@ -83,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,
             });
@@ -227,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);
@@ -401,7 +436,7 @@ export class Step {
     /**
      * 步骤数据
      */
-    data: any | undefined;
+    data: StepData;
 
     /**
      * 步骤延迟时间(毫秒)
@@ -434,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;
@@ -442,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;
@@ -471,7 +506,7 @@ export class Step {
             exceptionRetryCountMax = Step.exceptionRetryCountMaxDefault,
         }: {
             tag?: string | undefined;
-            data?: any | undefined;
+            data?: StepData;
             delayMs?: number;
             repeatCountMax?: number;
             exceptionRetryCountMax?: number;
@@ -482,7 +517,7 @@ export class Step {
             stepId: this.stepId,
             impl,
             tag,
-            data: data ?? this.data ?? {},
+            data: Step.resolveStepData(data, this.data),
             delayMs,
             repeatCountMax,
             exceptionRetryCountMax,
@@ -497,7 +532,7 @@ export class Step {
             exceptionRetryCountMax = Step.exceptionRetryCountMaxDefault,
         }: {
             tag?: string | undefined;
-            data?: any | undefined;
+            data?: StepData;
             delayMs?: number;
             repeatCountMax?: number;
             exceptionRetryCountMax?: number;
@@ -508,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,
@@ -527,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;
@@ -543,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;
@@ -631,11 +666,13 @@ export class Step {
         filterViewId,
         filterDes,
         filterText,
+        scope,
     }: {
         filterClass?: string;
         filterViewId?: string;
         filterDes?: string;
         filterText?: string;
+        scope?: NodeLookupScope;
     } = {}): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.getAllNodes({
@@ -643,6 +680,7 @@ export class Step {
             filterViewId,
             filterDes,
             filterText,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -663,11 +701,11 @@ export class Step {
 
     /**
      * 获取当前应用包名
-     * @returns 包名
+     * @param options.scope 节点查找范围（可选）
      */
-    public getPackageName(): string {
+    public getPackageName(options: { scope?: NodeLookupScope } = {}): string {
         Step.assert(this.stepId);
-        const result = AssistsX.getPackageName();
+        const result = AssistsX.getPackageName(options);
         Step.assert(this.stepId);
         return result;
     }
@@ -686,10 +724,21 @@ export class Step {
             filterClass,
             filterText,
             filterDes,
-        }: { filterClass?: string; filterText?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterText?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
-        const nodes = AssistsX.findById(id, { filterClass, filterText, filterDes });
+        const nodes = AssistsX.findById(id, {
+            filterClass,
+            filterText,
+            filterDes,
+            scope,
+        });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
         return nodes;
@@ -709,13 +758,20 @@ export class Step {
             filterClass,
             filterViewId,
             filterDes,
-        }: { filterClass?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.findByText(text, {
             filterClass,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -736,13 +792,20 @@ export class Step {
             filterText,
             filterViewId,
             filterDes,
-        }: { filterText?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterText?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.findByTags(className, {
             filterText,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -752,11 +815,14 @@ export class Step {
     /**
      * 查找所有匹配文本的节点
      * @param text 要查找的文本
-     * @returns 节点数组
+     * @param options.scope 节点查找范围（可选）
      */
-    public findByTextAllMatch(text: string): Node[] {
+    public findByTextAllMatch(
+        text: string,
+        { scope }: { scope?: NodeLookupScope } = {}
+    ): Node[] {
         Step.assert(this.stepId);
-        const nodes = AssistsX.findByTextAllMatch(text);
+        const nodes = AssistsX.findByTextAllMatch(text, { scope });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
         return nodes;