assistsx-js 0.2.2 → 0.2.3

package/README.md

@@ -110,6 +110,52 @@ export default defineConfig({
 
 **[API开发文档](https://github.com/ven-coder/assistsx-js/blob/main/README-DEV.md)**
 
+## StepFlow（流程编排，`assistsx-js/step-flow`）
+
+在保留原有 `Step.run` / `StepImpl` 的前提下，提供基于**状态 + 事件 + on 转移表**的流程编排，适合非线性跳转、多流程共用同一步骤实现。
+
+```ts
+import { Step } from "assistsx-js";
+import {
+  StepFlow,
+  flowEvent,
+  flowRepeat,
+  flowEnd,
+  createFlowDispatcher,
+  buildFlowInitialData,
+  createLaunchState,
+} from "assistsx-js/step-flow";
+
+// 1. 定义流程（launch 可衔接 legacy finishMethod）
+const config = {
+  id: "my.flow",
+  initial: "launch",
+  states: {} as Record<string, import("assistsx-js/step-flow").FlowStateDef>,
+  data: { appName: "抖音", packageName: "com.ss.android.ugc.aweme" },
+};
+const dispatcher = createFlowDispatcher(config);
+config.states = {
+  launch: createLaunchState(dispatcher, appLaunch.launch, "mainPage"),
+  mainPage: {
+    run: async (step) => (isHome(step) ? flowEvent("home") : flowRepeat()),
+    on: { home: "next", retry: "mainPage" },
+  },
+  next: { run: async () => flowEnd(), on: {} },
+};
+
+await Step.run(dispatcher, { data: buildFlowInitialData(config) });
+// 或使用：await StepFlow.run(config); // 需在 config.states 填充后再 run，见 createLaunchState 文档
+```
+
+要点：
+
+- **步骤实现**（`FlowStepImpl`）只返回 `flowEvent` / `flowRepeat` / `flowEnd`，或 `legacy` 委托旧版 `StepImpl`。
+- **跳转**由当前状态的 `on` 表决定；同一 `run` 可在不同 Flow 中配置不同的 `on`。
+- **业务数据**建议放在 `step.data.payload`；`getFlowPayload` / `assignFlowPayload` 可读写。
+- **与 legacy 共存**：`import { Step } from "assistsx-js"` 不变；StepFlow 从 `assistsx-js/step-flow` 单独导入。
+
+完整示例见 [ais-douyin-simple](https://github.com/ven-coder/assists-examples) 中 `src/v1/flows/check-unread.ts`。
+
 ## 示例
 
 示例源码及使用教程：[assistsx-js-simple](https://github.com/ven-coder/assists-examples/tree/main/assistsx-js-simple)

package/dist/index.cjs

@@ -59,6 +59,7 @@ __export(index_exports, {
   barUtils: () => barUtils,
   callbacks: () => callbacks,
   decodeBase64UTF8: () => decodeBase64UTF8,
+  ensureAssistsXPinia: () => ensureAssistsXPinia,
   fileIO: () => fileIO,
   fileUtils: () => fileUtils,
   float: () => float,
@@ -1486,6 +1487,17 @@ var useStepStore = (0, import_pinia.defineStore)("step", {
   }
 });
 
+// src/pinia-ensure.ts
+var import_pinia2 = require("pinia");
+var fallbackPinia = null;
+function ensureAssistsXPinia() {
+  if ((0, import_pinia2.getActivePinia)() !== void 0) return;
+  if (fallbackPinia === null) {
+    fallbackPinia = (0, import_pinia2.createPinia)();
+  }
+  (0, import_pinia2.setActivePinia)(fallbackPinia);
+}
+
 // src/step-error.ts
 var StepError = class extends Error {
   constructor(message, data, impl, tag, originalError, currentStep) {
@@ -1847,13 +1859,31 @@ var _Step = class _Step {
     this.delayMs = _Step.delayMsDefault;
     this.tag = tag;
     this.stepId = stepId;
-    this.data = data != null ? data : {};
+    this.data = _Step.resolveStepData(data);
     this.impl = impl;
     this.delayMs = delayMs;
     this.repeatCountMax = repeatCountMax;
     this.exceptionRetryCountMax = exceptionRetryCountMax;
     this.isEnd = isEnd;
   }
+  /**
+   * 判断步骤数据是否有效（非空且为普通对象）
+   */
+  static isValidStepData(data) {
+    return data !== null && data !== void 0 && typeof data === "object" && !Array.isArray(data);
+  }
+  /**
+   * 解析步骤数据：优先使用传入值，否则使用当前值，均无效时返回空对象
+   */
+  static resolveStepData(provided, fallback) {
+    if (provided !== void 0 && _Step.isValidStepData(provided)) {
+      return provided;
+    }
+    if (fallback !== void 0 && _Step.isValidStepData(fallback)) {
+      return fallback;
+    }
+    return {};
+  }
   /**
    * 运行步骤实现
    * @param impl 步骤实现函数
@@ -1870,7 +1900,9 @@ var _Step = class _Step {
   } = {}) {
     var _a2, _b, _c, _d, _e, _f;
     this.exception = void 0;
+    ensureAssistsXPinia();
     const stepStore = useStepStore();
+    const resolvedData = _Step.resolveStepData(data);
     let implnName = impl.name;
     let currentStep;
     let nextStep;
@@ -1886,12 +1918,12 @@ var _Step = class _Step {
           console.log(`\u751F\u6210\u6B65\u9AA4ID: ${this._stepId}`);
         }
       }
-      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
       });
@@ -2000,7 +2032,7 @@ var _Step = class _Step {
       const errorMsg = JSON.stringify({
         impl: implnName,
         tag,
-        data,
+        data: resolvedData,
         error: (_f = e == null ? void 0 : e.message) != null ? _f : String(e)
       });
       stepStore.setError(errorMsg);
@@ -2143,13 +2175,12 @@ var _Step = class _Step {
     repeatCountMax = _Step.repeatCountMaxDefault,
     exceptionRetryCountMax = _Step.exceptionRetryCountMaxDefault
   } = {}) {
-    var _a2;
     _Step.assert(this.stepId);
     return new _Step({
       stepId: this.stepId,
       impl,
       tag,
-      data: (_a2 = data != null ? data : this.data) != null ? _a2 : {},
+      data: _Step.resolveStepData(data, this.data),
       delayMs,
       repeatCountMax,
       exceptionRetryCountMax
@@ -2162,13 +2193,12 @@ var _Step = class _Step {
     repeatCountMax = _Step.repeatCountMaxDefault,
     exceptionRetryCountMax = _Step.exceptionRetryCountMaxDefault
   } = {}) {
-    var _a2;
     _Step.assert(this.stepId);
     return new _Step({
       stepId: this.stepId,
       impl: void 0,
       tag,
-      data: (_a2 = data != null ? data : this.data) != null ? _a2 : {},
+      data: _Step.resolveStepData(data, this.data),
       delayMs,
       repeatCountMax,
       exceptionRetryCountMax,
@@ -2186,7 +2216,7 @@ var _Step = class _Step {
   repeat({
     stepId = this.stepId,
     tag = this.tag,
-    data = ((_a2) => (_a2 = this.data) != null ? _a2 : {})(),
+    data,
     delayMs = this.delayMs,
     repeatCountMax = this.repeatCountMax,
     exceptionRetryCountMax = this.exceptionRetryCountMax
@@ -2195,7 +2225,7 @@ var _Step = 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;
@@ -7815,6 +7845,17 @@ var Log = class {
     );
     return res.isSuccess();
   }
+  /**
+   * 追加日志（appendTimestampedEntry / appendLine 简写）。
+   * 默认带时间戳；`timestamped: false` 时走 appendLine。
+   */
+  async append(text, options) {
+    const { timestamped = true, maxLength, timeout } = options != null ? options : {};
+    if (timestamped) {
+      return this.appendTimestampedEntry(text, timeout);
+    }
+    return this.appendLine(text, maxLength, timeout);
+  }
   /** 替换全部内容 */
   async replaceAll(content, timeout) {
     const res = await this.asyncCall(
@@ -8021,6 +8062,7 @@ var log = new Log();
   barUtils,
   callbacks,
   decodeBase64UTF8,
+  ensureAssistsXPinia,
   fileIO,
   fileUtils,
   float,