assistsx-js 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "assistsx-js",
-    "version": "0.2.2",
+    "version": "0.2.3",
     "description": "assistsx-js自动化开发SDK",
     "main": "dist/index.cjs",
     "module": "dist/index.js",
@@ -17,6 +17,11 @@
             "import": "./dist/index.js",
             "require": "./dist/index.cjs"
         },
+        "./step-flow": {
+            "types": "./dist/step-flow/index.d.ts",
+            "import": "./dist/step-flow/index.js",
+            "require": "./dist/step-flow/index.cjs"
+        },
         "./global": {
             "default": "./dist/index.global.js"
         }

package/src/index.ts

@@ -8,6 +8,7 @@ export * from "./utils";
 export * from "./bounds";
 export * from "./step";
 export * from "./step-state-store";
+export { ensureAssistsXPinia } from "./pinia-ensure";
 export * from "./window-flags";
 export * from "./node-async";
 export * from "./assistsx-async";

package/src/log/log.ts

@@ -225,6 +225,26 @@ export class Log {
         return res.isSuccess();
     }
 
+    /**
+     * 追加日志（appendTimestampedEntry / appendLine 简写）。
+     * 默认带时间戳；`timestamped: false` 时走 appendLine。
+     */
+    async append(
+        text: string,
+        options?: {
+            /** @default true */
+            timestamped?: boolean;
+            maxLength?: number;
+            timeout?: number;
+        }
+    ): Promise<boolean> {
+        const { timestamped = true, maxLength, timeout } = options ?? {};
+        if (timestamped) {
+            return this.appendTimestampedEntry(text, timeout);
+        }
+        return this.appendLine(text, maxLength, timeout);
+    }
+
     /** 替换全部内容 */
     async replaceAll(
         content: string,

package/src/pinia-ensure.ts

@@ -0,0 +1,15 @@
+import { createPinia, getActivePinia, setActivePinia, type Pinia } from "pinia";
+
+/**
+ * 当宿主应用未执行 app.use(pinia) 时，为 assistsx-js 内部使用的 Pinia store 提供默认实例，
+ * 避免 useStepStore 等在无 active Pinia 时抛错。
+ */
+let fallbackPinia: Pinia | null = null;
+
+export function ensureAssistsXPinia(): void {
+    if (getActivePinia() !== undefined) return;
+    if (fallbackPinia === null) {
+        fallbackPinia = createPinia();
+    }
+    setActivePinia(fallbackPinia);
+}

package/src/step-flow/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./outcome";
+export * from "./payload";
+export * from "./legacy-handoff";
+export * from "./runner";

package/src/step-flow/legacy-handoff.ts

@@ -0,0 +1,50 @@
+import type { Step, StepImpl } from "../step";
+import type { FlowStateDef, StepFlowData, StepFlowOutcome } from "./types";
+import { getFlowPayload } from "./payload";
+
+/**
+ * 为 legacy 步骤（如 app-launch）创建 finishMethod：
+ * 应用打开成功后跳回 StepFlow dispatcher 并切换到指定状态。
+ */
+export function createFinishHandoff(
+    dispatcher: StepImpl,
+    nextState: string
+): StepImpl {
+    return async (step: Step) => {
+        const data = step.data as StepFlowData;
+        if (!data.__flow) {
+            data.__flow = { state: nextState };
+        } else {
+            data.__flow.state = nextState;
+        }
+        return step.next(dispatcher);
+    };
+}
+
+/**
+ * 创建 launch 类流程状态：写入 finishMethod 后委托执行 legacy StepImpl 链。
+ */
+export function createLaunchState(
+    dispatcher: StepImpl,
+    launchImpl: StepImpl,
+    nextState: string,
+    /** legacy 步骤从 step.data 读取的字段名（默认与 payload 键一致） */
+    legacyDataKeys: string[] = ["appName", "packageName"]
+): FlowStateDef {
+    return {
+        run: async (step): Promise<StepFlowOutcome> => {
+            const payload = getFlowPayload(step);
+            for (const key of legacyDataKeys) {
+                if (payload[key] !== undefined) {
+                    (step.data as StepFlowData)[key] = payload[key];
+                }
+            }
+            (step.data as StepFlowData).finishMethod = createFinishHandoff(
+                dispatcher,
+                nextState
+            );
+            return { type: "legacy", impl: launchImpl };
+        },
+        on: {},
+    };
+}

package/src/step-flow/outcome.ts

@@ -0,0 +1,16 @@
+import type { StepFlowOutcome } from "./types";
+
+/** 产生流程事件，由当前状态的 on 表决定下一状态 */
+export function flowEvent(name: string): StepFlowOutcome {
+    return { type: "event", name };
+}
+
+/** 重复当前流程状态（沿用 Step.repeat 语义） */
+export function flowRepeat(): StepFlowOutcome {
+    return { type: "repeat" };
+}
+
+/** 结束整个流程 */
+export function flowEnd(): StepFlowOutcome {
+    return { type: "end" };
+}

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,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;