assistsx-js 0.2.2 → 0.2.4

package/src/log/log.ts

@@ -10,6 +10,44 @@ const pendingCallbacks: Map<string, (data: string) => void> = new Map();
 const streamHandlers: Map<string, (data: string) => void> = new Map();
 const subscriptionIdToCallbackId: Map<string, string> = new Map();
 
+/** 日志文件定位：dirPath 为绝对路径目录，fileName 不含 .txt 后缀；均未传时默认 log-default.txt */
+export interface LogTarget {
+    dirPath?: string;
+    fileName?: string;
+}
+
+export interface LogCallOptions extends LogTarget {
+    /** 超时时间（秒），默认 30 */
+    timeout?: number;
+}
+
+function buildLogArguments(
+    target?: LogTarget,
+    extra?: Record<string, unknown>
+): Record<string, unknown> | undefined {
+    const args: Record<string, unknown> = { ...extra };
+    if (target?.dirPath !== undefined) {
+        args.dirPath = target.dirPath;
+    }
+    if (target?.fileName !== undefined) {
+        args.fileName = target.fileName;
+    }
+    return Object.keys(args).length > 0 ? args : undefined;
+}
+
+function resolveTimeout(
+    timeoutOrOptions?: number | LogCallOptions,
+    fallback = 30
+): { timeout: number; target?: LogTarget } {
+    if (typeof timeoutOrOptions === "number") {
+        return { timeout: timeoutOrOptions };
+    }
+    return {
+        timeout: timeoutOrOptions?.timeout ?? fallback,
+        target: timeoutOrOptions,
+    };
+}
+
 if (typeof window !== "undefined" && !window.assistsxLogCallback) {
     window.assistsxLogCallback = (data: string) => {
         try {
@@ -49,7 +87,7 @@ export const logUpdateListeners: Array<
 > = [];
 
 /**
- * Base64 解码后的 CallResponse，data 含 stream / text
+ * Base64 解码后的 CallResponse，data 含 stream / text / logFilePath
  */
 export interface LogUpdateEvent {
     code: number;
@@ -61,15 +99,17 @@ export interface LogUpdateEvent {
 export interface LogUpdateData {
     stream: LogStreamType;
     text: string;
+    logFilePath?: string;
 }
 
 export interface LogSubscribeUpdatePayload {
     text: string;
     stream: string;
     subscriptionId: string;
+    logFilePath?: string;
 }
 
-export interface LogUploadOptions {
+export interface LogUploadOptions extends LogTarget {
     baseUrl?: string;
     /** PNG（默认）| JPEG | JPG | WEBP */
     format?: "PNG" | "JPEG" | "JPG" | "WEBP" | string;
@@ -150,10 +190,13 @@ export class Log {
     }
 
     /** 读取当前日志全文 */
-    async readAllText(timeout?: number): Promise<string> {
+    async readAllText(
+        timeoutOrOptions?: number | LogCallOptions
+    ): Promise<string> {
+        const { timeout, target } = resolveTimeout(timeoutOrOptions);
         const res = await this.asyncCall(
             LogCallMethod.readAllText,
-            undefined,
+            buildLogArguments(target),
             timeout
         );
         const d = res.getDataOrNull() as { text?: string } | null;
@@ -174,21 +217,42 @@ export class Log {
         return d?.baseUrl ?? "";
     }
 
+    /**
+     * 解析日志文件绝对路径（不创建文件）。
+     * AssistsX 插件环境下会经原生拦截追加 log-{packageName} 子目录。
+     */
+    async resolveLogPath(
+        targetOrOptions?: LogTarget | LogCallOptions
+    ): Promise<string> {
+        const { timeout, target } = resolveTimeout(targetOrOptions);
+        const res = await this.asyncCall(
+            LogCallMethod.resolveLogPath,
+            buildLogArguments(target),
+            timeout
+        );
+        const d = res.getDataOrNull() as { logFilePath?: string } | null;
+        return d?.logFilePath ?? "";
+    }
+
     /** 清空日志 */
-    async clear(timeout?: number): Promise<boolean> {
+    async clear(timeoutOrOptions?: number | LogCallOptions): Promise<boolean> {
+        const { timeout, target } = resolveTimeout(timeoutOrOptions);
         const res = await this.asyncCall(
             LogCallMethod.clear,
-            undefined,
+            buildLogArguments(target),
             timeout
         );
         return res.isSuccess();
     }
 
     /** 从文件重新加载到内存 Flow */
-    async refreshFromFile(timeout?: number): Promise<boolean> {
+    async refreshFromFile(
+        timeoutOrOptions?: number | LogCallOptions
+    ): Promise<boolean> {
+        const { timeout, target } = resolveTimeout(timeoutOrOptions);
         const res = await this.asyncCall(
             LogCallMethod.refreshFromFile,
-            undefined,
+            buildLogArguments(target),
             timeout
         );
         return res.isSuccess();
@@ -197,17 +261,25 @@ export class Log {
     /** 追加一行 */
     async appendLine(
         line: string,
-        maxLength?: number,
+        maxLengthOrOptions?:
+            | number
+            | (LogTarget & { maxLength?: number; timeout?: number }),
         timeout?: number
     ): Promise<boolean> {
-        const args: Record<string, unknown> = { line };
-        if (maxLength !== undefined) {
-            args.maxLength = maxLength;
+        let options: (LogTarget & { maxLength?: number; timeout?: number }) | undefined;
+        if (typeof maxLengthOrOptions === "number") {
+            options = { maxLength: maxLengthOrOptions, timeout };
+        } else {
+            options = maxLengthOrOptions;
+        }
+        const args = buildLogArguments(options, { line }) ?? { line };
+        if (options?.maxLength !== undefined) {
+            args.maxLength = options.maxLength;
         }
         const res = await this.asyncCall(
             LogCallMethod.appendLine,
             args,
-            timeout
+            options?.timeout
         );
         return res.isSuccess();
     }
@@ -215,24 +287,48 @@ export class Log {
     /** 追加带时间戳的条目 */
     async appendTimestampedEntry(
         message: string,
-        timeout?: number
+        timeoutOrOptions?: number | LogCallOptions
     ): Promise<boolean> {
+        const { timeout, target } = resolveTimeout(timeoutOrOptions);
+        const args = buildLogArguments(target, { message }) ?? { message };
         const res = await this.asyncCall(
             LogCallMethod.appendTimestampedEntry,
-            { message },
+            args,
             timeout
         );
         return res.isSuccess();
     }
 
+    /**
+     * 追加日志（appendTimestampedEntry / appendLine 简写）。
+     * 默认带时间戳；`timestamped: false` 时走 appendLine。
+     */
+    async append(
+        text: string,
+        options?: LogTarget & {
+            /** @default true */
+            timestamped?: boolean;
+            maxLength?: number;
+            timeout?: number;
+        }
+    ): Promise<boolean> {
+        const { timestamped = true, maxLength, timeout, ...target } = options ?? {};
+        if (timestamped) {
+            return this.appendTimestampedEntry(text, { ...target, timeout });
+        }
+        return this.appendLine(text, { ...target, maxLength, timeout });
+    }
+
     /** 替换全部内容 */
     async replaceAll(
         content: string,
-        timeout?: number
+        timeoutOrOptions?: number | LogCallOptions
     ): Promise<boolean> {
+        const { timeout, target } = resolveTimeout(timeoutOrOptions);
+        const args = buildLogArguments(target, { content }) ?? { content };
         const res = await this.asyncCall(
             LogCallMethod.replaceAll,
-            { content },
+            args,
             timeout
         );
         return res.isSuccess();
@@ -245,7 +341,7 @@ export class Log {
     async subscribe(
         stream: LogStreamType,
         onUpdate: (payload: LogSubscribeUpdatePayload) => void,
-        options?: { timeout?: number }
+        options?: LogCallOptions
     ): Promise<{
         subscriptionId: string;
         dispose: () => Promise<void>;
@@ -253,6 +349,7 @@ export class Log {
         const self = this;
         const callbackId = generateUUID();
         const timeoutSec = options?.timeout ?? 30;
+        const subscribeArgs = buildLogArguments(options, { stream }) ?? { stream };
 
         return new Promise((resolve, reject) => {
             let settled = false;
@@ -273,6 +370,7 @@ export class Log {
                         subscriptionId?: string;
                         stream?: string;
                         text?: string;
+                        logFilePath?: string;
                     };
                 };
                 try {
@@ -318,6 +416,7 @@ export class Log {
                         text: data.text ?? "",
                         stream: data.stream ?? stream,
                         subscriptionId: data.subscriptionId,
+                        logFilePath: data.logFilePath,
                     });
                 }
             });
@@ -326,7 +425,7 @@ export class Log {
                 this.getBridge().call(
                     JSON.stringify({
                         method: LogCallMethod.subscribe,
-                        arguments: { stream },
+                        arguments: subscribeArgs,
                         callbackId,
                     })
                 );
@@ -377,6 +476,12 @@ export class Log {
         if (args.uploadKey !== undefined) {
             payload.uploadKey = args.uploadKey;
         }
+        if (args.dirPath !== undefined) {
+            payload.dirPath = args.dirPath;
+        }
+        if (args.fileName !== undefined) {
+            payload.fileName = args.fileName;
+        }
         const uuid = generateUUID();
         const params = {
             method: LogCallMethod.uploadLogs,

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/plugin-info.ts

@@ -0,0 +1,70 @@
+/**
+ * AssistsX 当前运行插件信息（由宿主拦截 getCurrentPlugin 返回）
+ */
+export class PluginInfo {
+    id: string;
+    name: string;
+    packageName: string;
+    versionName: string;
+    versionCode: number;
+    description: string;
+    path: string;
+    index: string;
+    port: number;
+    needScreenCapture: boolean;
+
+    constructor(
+        id: string = "",
+        name: string = "",
+        packageName: string = "",
+        versionName: string = "",
+        versionCode: number = 0,
+        description: string = "",
+        path: string = "",
+        index: string = "",
+        port: number = 0,
+        needScreenCapture: boolean = false
+    ) {
+        this.id = id;
+        this.name = name;
+        this.packageName = packageName;
+        this.versionName = versionName;
+        this.versionCode = versionCode;
+        this.description = description;
+        this.path = path;
+        this.index = index;
+        this.port = port;
+        this.needScreenCapture = needScreenCapture;
+    }
+
+    static fromJSON(data: unknown): PluginInfo {
+        const record = (data ?? {}) as Record<string, unknown>;
+        return new PluginInfo(
+            String(record.id ?? ""),
+            String(record.name ?? ""),
+            String(record.packageName ?? ""),
+            String(record.versionName ?? ""),
+            Number(record.versionCode ?? 0),
+            String(record.description ?? ""),
+            String(record.path ?? ""),
+            String(record.index ?? ""),
+            Number(record.port ?? 0),
+            Boolean(record.needScreenCapture ?? false)
+        );
+    }
+
+    toJSON(): Record<string, unknown> {
+        return {
+            id: this.id,
+            name: this.name,
+            packageName: this.packageName,
+            versionName: this.versionName,
+            versionCode: this.versionCode,
+            description: this.description,
+            path: this.path,
+            index: this.index,
+            port: this.port,
+            needScreenCapture: this.needScreenCapture,
+        };
+    }
+}

package/src/screenshot/screenshot-call-method.ts

@@ -0,0 +1,16 @@
+/**
+ * 截图相关的 JavascriptInterface 方法常量
+ */
+export const ScreenshotCallMethod = {
+    /** 截取全屏并返回 Base64 */
+    takeScreenshotBase64: "takeScreenshotBase64",
+
+    /** 截取指定节点区域并返回 Base64，需传 node.nodeId */
+    takeNodeScreenshotBase64: "takeNodeScreenshotBase64",
+
+    /** 批量截取节点区域并返回 Base64 数组，nodes 为空时返回全屏 */
+    takeScreenshotNodesBase64: "takeScreenshotNodesBase64",
+} as const;
+
+export type ScreenshotCallMethodType =
+    (typeof ScreenshotCallMethod)[keyof typeof ScreenshotCallMethod];

package/src/screenshot/screenshot.ts

@@ -0,0 +1,200 @@
+/**
+ * 截图专用 Bridge：assistsxScreenshot
+ * 直接返回 Base64 / data URL，无需经过文件保存
+ */
+import { CallResponse } from "../call-response";
+import { Node } from "../node";
+import { decodeBase64UTF8, generateUUID } from "../utils";
+import { ScreenshotCallMethod } from "./screenshot-call-method";
+
+export type ScreenshotImageFormat = "PNG" | "JPEG" | "JPG" | "WEBP";
+
+/** takeScreenshotBase64 / takeNodeScreenshotBase64 返回数据 */
+export interface ScreenshotBase64Data {
+    base64: string;
+    dataUrl: string;
+    mimeType: string;
+}
+
+export interface TakeScreenshotBase64Options {
+    overlayHiddenScreenshotDelayMillis?: number;
+    format?: ScreenshotImageFormat;
+    withDataUrlPrefix?: boolean;
+    timeout?: number;
+}
+
+export interface TakeScreenshotNodesBase64Options extends TakeScreenshotBase64Options {}
+
+// 回调函数存储对象
+const callbacks: Map<string, (data: string) => void> = new Map();
+
+// 初始化全局回调函数
+if (typeof window !== "undefined" && !window.assistsxScreenshotCallback) {
+    window.assistsxScreenshotCallback = (data: string) => {
+        let callbackId: string | undefined;
+        try {
+            const json = decodeBase64UTF8(data);
+            const response = JSON.parse(json);
+            callbackId = response.callbackId;
+            if (callbackId) {
+                const callback = callbacks.get(callbackId);
+                if (callback) {
+                    callback(json);
+                }
+            }
+        } catch (e) {
+            console.error("Screenshot callback error:", e);
+        } finally {
+            if (callbackId) {
+                callbacks.delete(callbackId);
+            }
+        }
+    };
+}
+
+function createNodeStub(nodeId: string): Node {
+    return { nodeId } as Node;
+}
+
+function parseScreenshotBase64Data(data: unknown): ScreenshotBase64Data | null {
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+    const record = data as Record<string, unknown>;
+    const base64 = typeof record.base64 === "string" ? record.base64 : "";
+    const mimeType = typeof record.mimeType === "string" ? record.mimeType : "image/png";
+    const dataUrl =
+        typeof record.dataUrl === "string"
+            ? record.dataUrl
+            : `data:${mimeType};base64,${base64}`;
+    if (!base64) {
+        return null;
+    }
+    return { base64, dataUrl, mimeType };
+}
+
+export class Screenshot {
+    /**
+     * 执行异步调用
+     */
+    private async asyncCall(
+        method: string,
+        {
+            args,
+            node,
+            nodes,
+            timeout = 30,
+        }: {
+            args?: Record<string, unknown>;
+            node?: Node;
+            nodes?: Node[];
+            timeout?: number;
+        } = {}
+    ): Promise<CallResponse> {
+        const uuid = generateUUID();
+        const params = {
+            method,
+            arguments: args ? args : undefined,
+            node: node ? node : undefined,
+            nodes: nodes ? nodes : undefined,
+            callbackId: uuid,
+        };
+        const promise = new Promise<string>((resolve) => {
+            callbacks.set(uuid, (data: string) => {
+                resolve(data);
+            });
+            setTimeout(() => {
+                callbacks.delete(uuid);
+                resolve(JSON.stringify(new CallResponse(0, null, uuid)));
+            }, timeout * 1000);
+        });
+        window.assistsxScreenshot.call(JSON.stringify(params));
+        const promiseResult = await promise;
+        if (typeof promiseResult === "string") {
+            const responseData = JSON.parse(promiseResult);
+            return new CallResponse(
+                responseData.code,
+                responseData.data,
+                responseData.callbackId
+            );
+        }
+        throw new Error("Screenshot call failed");
+    }
+
+    private buildScreenshotArgs(
+        options: TakeScreenshotBase64Options = {}
+    ): Record<string, unknown> {
+        const {
+            overlayHiddenScreenshotDelayMillis = 250,
+            format = "PNG",
+            withDataUrlPrefix = true,
+        } = options;
+        return {
+            overlayHiddenScreenshotDelayMillis,
+            format,
+            withDataUrlPrefix,
+        };
+    }
+
+    /**
+     * 截取全屏并返回 Base64
+     */
+    async takeScreenshotBase64(
+        options: TakeScreenshotBase64Options = {}
+    ): Promise<ScreenshotBase64Data | null> {
+        const { timeout = 30, ...rest } = options;
+        const response = await this.asyncCall(ScreenshotCallMethod.takeScreenshotBase64, {
+            args: this.buildScreenshotArgs(rest),
+            timeout,
+        });
+        if (!response.isSuccess()) {
+            return null;
+        }
+        return parseScreenshotBase64Data(response.getDataOrNull());
+    }
+
+    /**
+     * 截取指定节点区域并返回 Base64
+     */
+    async takeNodeScreenshotBase64(
+        nodeId: string,
+        options: TakeScreenshotBase64Options = {}
+    ): Promise<ScreenshotBase64Data | null> {
+        if (!nodeId) {
+            throw new Error("nodeId is required");
+        }
+        const { timeout = 30, ...rest } = options;
+        const response = await this.asyncCall(ScreenshotCallMethod.takeNodeScreenshotBase64, {
+            args: this.buildScreenshotArgs(rest),
+            node: createNodeStub(nodeId),
+            timeout,
+        });
+        if (!response.isSuccess()) {
+            return null;
+        }
+        return parseScreenshotBase64Data(response.getDataOrNull());
+    }
+
+    /**
+     * 批量截取节点区域；nodeIds 为空时返回全屏截图
+     */
+    async takeScreenshotNodesBase64(
+        nodeIds: string[] = [],
+        options: TakeScreenshotNodesBase64Options = {}
+    ): Promise<string[]> {
+        const { timeout = 30, ...rest } = options;
+        const nodes = nodeIds.map((nodeId) => createNodeStub(nodeId));
+        const response = await this.asyncCall(ScreenshotCallMethod.takeScreenshotNodesBase64, {
+            args: this.buildScreenshotArgs(rest),
+            nodes,
+            timeout,
+        });
+        if (!response.isSuccess()) {
+            return [];
+        }
+        const data = response.getDataOrNull() as { images?: string[] } | null;
+        return Array.isArray(data?.images) ? data.images : [];
+    }
+}
+
+export const screenshot = new Screenshot();

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 };
+}