dsh-mobile-plugin 0.5.27 → 0.5.29

package/lib/mobile/phone/guard.js

@@ -0,0 +1,465 @@
+'use strict';
+
+/**
+ * 操作停滞守卫：手机每一步结束之后记一笔，判断模型是不是「原地打转」，并在合适的级别提醒
+ * 或直接叫停。纯逻辑、无 IO、无时钟、可单测 —— 所有计数都在这一份实例里，外部每步喂一条事实。
+ *
+ * 分级照 Mika 的 GuardRules / OperationGuards：同一动作+同一目标重复 3/6/12；动作没有效果
+ * 3/6/9/12；页面没变却重读 5/8/12；连续失败 2/4/8（不可恢复 1/3）；在两三个状态之间兜圈
+ * 2/4/...（安全网按步数上限），回到同一状态、连续没到过新状态也各有阶梯。每一级先「提醒」，
+ * 最后一级才是「叫停」—— 叫停是安全网，门槛远在提醒之后。提醒里附三条出路：换一条明显不同
+ * 的路 / 问用户 / 把已经拿到的交出来并说明还缺什么。
+ *
+ * 界面指纹用元素表文本（去掉会变的 ref）的 64 位 FNV-1a，照 Mika 的 Fingerprints.kt：纯文本
+ * 模型没有截图，也能判断「画面没变」。
+ *
+ * 用法：
+ *   const guard = createGuard({ budget: 60 });
+ *   const v = guard.noteStep({ tool:'phone_tap', args:{ref:'e3'}, kind:'action',
+ *                              effect:'no_effect', elements });
+ *   if (v) { value.note = (value.note ? value.note + ' ' : '') + v.advice; } // warn 才带 advice
+ *   if (guard.shouldStop()) { /* 把这一轮收掉 *\/ }
+ *
+ * noteStep 接受的 step 字段（除 tool 外都可缺，缺了只是少一维判定）：
+ *   tool       工具名，参与「同一动作同一目标」的签名
+ *   args       参数，参与签名（忽略 reason，坐标按 50 取整，滑动只记方向）
+ *   kind       'action'（默认）| 'read' | 'diagnostic'
+ *   effect     'changed' | 'small_change' | 'place_changed' | 'no_effect'（动作实际效果）
+ *   fingerprint 已经算好的界面指纹（字符串/数字）；也可直接给 elements
+ *   elements   这一屏的元素表，本模块自己算指纹
+ *   fresh      读动作这次是否读到了之前没读到的新内容（read/diagnostic 用）
+ *   ok         false 记一次失败，true 清零失败计数，缺省表示这份结果不表态
+ *   recoverable false 记为不可恢复失败
+ *   treeBlind  这次动作是在读不出控件树的情况下点的（无效果时更早提醒）
+ *   diagnostic true 时按「诊断类工具」的更高门槛计重复
+ */
+
+const SEVERITY = { NONE: 'none', WARN: 'warn', STOP: 'stop' };
+
+/** 不知道任务步数上限时按这么多步算（与 Mika 一致）。 */
+const DEFAULT_BUDGET = 60;
+/** 「同一动作同一目标」看最近多少个动作。 */
+const LOOP_WINDOW = 16;
+/** 兜圈最多看几个状态一圈。 */
+const MAX_CYCLE = 3;
+/** 兜圈 trail 最多记多少（够看出最长的安全网）。 */
+const TRAIL_KEEP = 64;
+/** 元素里这些字段每次都变，算指纹前先去掉。 */
+const VOLATILE_ELEMENT_KEYS = ['ref'];
+
+/**
+ * 阈值表（导出给交付报告与单测真值）。每条的最后一级是「叫停」，其余是「提醒」。
+ * 带 divisor/floor 的是「按步数上限的安全网」：lateStop(budget, divisor, floor)。
+ */
+const THRESHOLDS = {
+  repeat: [3, 6, 12],
+  repeatDiagnostic: [6, 9, 15],
+  noEffect: [3, 6, 9, 12],
+  reread: [5, 8, 12],
+  failure: [2, 4, 8],
+  unrecoverable: [1, 3],
+  failureWaysOut: 4,
+  sameState: { base: [3, 6], divisor: 4, floor: 10 },
+  cycle: { base: [2, 4], divisor: 5, floor: 6 },
+  noNewState: { base: [8, 16], divisor: 2, floor: 24 },
+};
+
+/** 提醒里给的三条出路。 */
+const WAYS_OUT =
+  '给你三条路：换一条明显不同的做法（换工具、换入口、换说法）；还是不行就直接问用户；' +
+  '或者把已经拿到的结果交出来，并说清还缺哪一步。';
+
+/** 各条提醒开头「卡在哪」那句。 */
+const LEADS = {
+  repeating_action: (n) => `同一个动作（同一目标）已经重复 ${n} 次，屏幕上没有给你新东西。`,
+  no_progress: (n) => `连续 ${n} 个动作都没有效果，屏幕没有变化。`,
+  read_loop: (n) => `页面没有变，你已经重读了 ${n} 次，读不出新内容。`,
+  too_many_failures: (n) => `工具已经连续失败 ${n} 次，原样重试大概率还是失败。`,
+  same_state: (n) => `这是第 ${n} 次回到同一个界面状态。`,
+  state_cycle: (n, p) => `在 ${p} 个状态之间兜圈子，已经转了 ${n} 圈。`,
+  no_new_state: (n) => `连续 ${n} 个动作都没有走到新状态。`,
+};
+
+function lateStop(budget, divisor, floor) {
+  const b = Number.isFinite(budget) && budget > 0 ? budget : DEFAULT_BUDGET;
+  return Math.max(floor, Math.floor(b / divisor));
+}
+
+function sameStateLadder(budget) {
+  return THRESHOLDS.sameState.base.concat(lateStop(budget, THRESHOLDS.sameState.divisor, THRESHOLDS.sameState.floor));
+}
+function cycleLadder(budget) {
+  return THRESHOLDS.cycle.base.concat(lateStop(budget, THRESHOLDS.cycle.divisor, THRESHOLDS.cycle.floor));
+}
+function noNewStateLadder(budget) {
+  return THRESHOLDS.noNewState.base.concat(lateStop(budget, THRESHOLDS.noNewState.divisor, THRESHOLDS.noNewState.floor));
+}
+
+/**
+ * count 在升序阶梯 ladder 上到了哪一级。没到第一级、或这一级（warnedAt 是已提醒到的门槛）已提醒过
+ * 返回 null；到最高一级且 canStop 时叫停，否则提醒。照 Mika GuardRules.climb。
+ */
+function climb(count, ladder, warnedAt, canStop) {
+  let threshold = null;
+  for (const t of ladder) if (count >= t) threshold = t;
+  if (threshold === null) return null;
+  if (threshold <= warnedAt) return null;
+  const last = ladder[ladder.length - 1];
+  return { threshold, severity: threshold === last && canStop ? SEVERITY.STOP : SEVERITY.WARN };
+}
+
+/** 64 位 FNV-1a（照 Mika Fingerprints.kt 的初值与素数）。返回 16 位十六进制串。 */
+function fnv1a64(str) {
+  let h = 0xcbf29ce484222325n;
+  const bytes = Buffer.from(String(str), 'utf8');
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= BigInt(bytes[i]);
+    h = BigInt.asUintN(64, h * 0x100000001b3n);
+  }
+  return h.toString(16).padStart(16, '0');
+}
+
+/** 稳定序列化：对象键排序，数组保序。让同样的元素表每次得到同样的指纹。 */
+function stableStringify(value) {
+  if (value === undefined) return 'null';
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+
+/** 去掉元素表里每次都变的字段（ref），留下真正的界面内容。 */
+function stripVolatile(el) {
+  if (!el || typeof el !== 'object' || Array.isArray(el)) return el;
+  const copy = {};
+  for (const k of Object.keys(el)) {
+    if (VOLATILE_ELEMENT_KEYS.indexOf(k) === -1) copy[k] = el[k];
+  }
+  return copy;
+}
+
+/**
+ * 画面指纹：元素表文本（去掉 ref）的 64 位 FNV。elements 不是数组返回 null。
+ * @param {Array} elements
+ * @returns {string|null}
+ */
+function elementsFingerprint(elements) {
+  if (!Array.isArray(elements)) return null;
+  return fnv1a64(stableStringify(elements.map(stripVolatile)));
+}
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * 动作签名：tool + 参数（忽略 reason；坐标按 50 取整；滑动只记方向）。参数顺序不影响结果。
+ * @param {string} tool
+ * @param {object} args
+ * @returns {string}
+ */
+function actionSignature(tool, args) {
+  const a = args && typeof args === 'object' && !Array.isArray(args) ? Object.assign({}, args) : {};
+  delete a.reason;
+  const x = num(a.x);
+  const y = num(a.y);
+  if (x !== null && y !== null) {
+    a.x = Math.floor(x / 50);
+    a.y = Math.floor(y / 50);
+  }
+  const swipeKeys = ['startX', 'startY', 'endX', 'endY'];
+  const s = swipeKeys.map((k) => num(a[k]));
+  if (s.every((v) => v !== null)) {
+    const dx = s[2] - s[0];
+    const dy = s[3] - s[1];
+    const vertical = Math.abs(dy) >= Math.abs(dx);
+    const major = vertical ? dy : dx;
+    a.swipeDirection = (vertical ? 'V' : 'H') + (major < 0 ? '-' : '+');
+    for (const k of swipeKeys) delete a[k];
+  }
+  return String(tool == null ? '' : tool) + '|' + stableStringify(a);
+}
+
+/** 在 trail（相邻不同的状态序列）末尾找「在 2–3 个状态间兜圈」。照 Mika GuardRules.cycle。 */
+function detectCycle(trail) {
+  let best = null;
+  for (let p = 2; p <= MAX_CYCLE; p++) {
+    if (trail.length < p + 1) continue;
+    const tail = trail.slice(-p);
+    if (new Set(tail).size !== p) continue;
+    let len = p;
+    let i = trail.length - 1;
+    while (i - p >= 0 && trail[i] === trail[i - p]) {
+      len++;
+      i--;
+    }
+    if (len > p && (best === null || len > best.length)) {
+      best = { period: p, length: len, rounds: Math.floor(len / p) };
+    }
+  }
+  return best;
+}
+
+function fingerprintOf(step) {
+  if (step.fingerprint !== undefined && step.fingerprint !== null) return String(step.fingerprint);
+  if (Array.isArray(step.elements)) return elementsFingerprint(step.elements);
+  return null;
+}
+
+/**
+ * 建一份守卫。options.budget 是这一轮允许的步数上限（影响兜圈/回同状态/无新状态的安全网）。
+ * @param {{budget?: number}} [options]
+ */
+function createGuard(options) {
+  const opts = options || {};
+  const budget = Number.isFinite(opts.budget) ? opts.budget : null;
+
+  let state;
+
+  function reset() {
+    state = {
+      lastFingerprint: null,
+      seenStates: new Set(),
+      visits: new Map(),
+      visitsWarnedAt: new Map(),
+      trail: [],
+      cycleWarnedAt: 0,
+      sinceNewState: 0,
+      sinceNewWarnedAt: 0,
+      unchanged: 0,
+      unchangedWarnedAt: 0,
+      treeBlindActions: 0,
+      window: [],
+      repeatWarned: new Map(),
+      rereads: 0,
+      rereadWarnedAt: 0,
+      consecutiveFailures: 0,
+      unrecoverableFailures: 0,
+      failureWarnedAt: 0,
+      unrecoverableWarnedAt: 0,
+      stopped: null,
+      level: SEVERITY.NONE,
+      lastAdvice: null,
+      lastVerdict: null,
+      emitted: [],
+    };
+  }
+  reset();
+
+  function buildAdvice(code, count, period) {
+    const lead = LEADS[code] ? LEADS[code](count, period) : `卡住了（${code}，${count} 次）。`;
+    return `${lead}${WAYS_OUT}`;
+  }
+
+  function report(code, severity, count, period) {
+    const advice = severity === SEVERITY.WARN ? buildAdvice(code, count, period) : null;
+    const verdict = { code, severity, count, advice };
+    state.lastVerdict = verdict;
+    state.emitted.push(verdict);
+    if (severity === SEVERITY.STOP) {
+      state.stopped = verdict;
+      state.level = SEVERITY.STOP;
+    } else if (state.level !== SEVERITY.STOP) {
+      state.level = SEVERITY.WARN;
+    }
+    if (advice) state.lastAdvice = advice;
+    return verdict;
+  }
+
+  function resetNoEffect() {
+    state.unchanged = 0;
+    state.unchangedWarnedAt = 0;
+    state.treeBlindActions = 0;
+  }
+
+  function progress() {
+    resetNoEffect();
+    state.sinceNewState = 0;
+    state.sinceNewWarnedAt = 0;
+    if (state.stopped && (state.stopped.code === 'no_progress' || state.stopped.code === 'read_loop')) {
+      state.stopped = null;
+      state.level = SEVERITY.NONE;
+    }
+  }
+
+  function noProgress() {
+    if (state.treeBlindActions >= 2) {
+      const severity = state.unchanged >= 3 ? SEVERITY.STOP : SEVERITY.WARN;
+      return report('no_progress', severity, state.unchanged);
+    }
+    const rung = climb(state.unchanged, THRESHOLDS.noEffect, state.unchangedWarnedAt, true);
+    if (!rung) return null;
+    state.unchangedWarnedAt = rung.threshold;
+    return report('no_progress', rung.severity, state.unchanged);
+  }
+
+  function sameState(fp, n) {
+    const rung = climb(n, sameStateLadder(budget), state.visitsWarnedAt.get(fp) || 0, true);
+    if (!rung) return null;
+    state.visitsWarnedAt.set(fp, rung.threshold);
+    return report('same_state', rung.severity, n);
+  }
+
+  function cycleCheck(cyc) {
+    if (!cyc) {
+      state.cycleWarnedAt = 0;
+      return null;
+    }
+    const rung = climb(cyc.rounds, cycleLadder(budget), state.cycleWarnedAt, true);
+    if (!rung) return null;
+    state.cycleWarnedAt = rung.threshold;
+    return report('state_cycle', rung.severity, cyc.rounds, cyc.period);
+  }
+
+  function noNewState() {
+    const rung = climb(state.sinceNewState, noNewStateLadder(budget), state.sinceNewWarnedAt, false);
+    if (!rung) return null;
+    state.sinceNewWarnedAt = rung.threshold;
+    return report('no_new_state', rung.severity, state.sinceNewState);
+  }
+
+  function noteRepeat(step) {
+    const diag = step.diagnostic === true;
+    const sig = diag ? String(step.tool == null ? '' : step.tool) : actionSignature(step.tool, step.args);
+    state.window.push(sig);
+    if (state.window.length > LOOP_WINDOW) state.window.shift();
+    let count = 0;
+    for (const s of state.window) if (s === sig) count++;
+    const ladder = diag ? THRESHOLDS.repeatDiagnostic : THRESHOLDS.repeat;
+    const rung = climb(count, ladder, state.repeatWarned.get(sig) || 0, true);
+    if (!rung) return null;
+    state.repeatWarned.set(sig, rung.threshold);
+    return report('repeating_action', rung.severity, count);
+  }
+
+  function noteFailure(step) {
+    const recoverable = step.recoverable !== false;
+    state.consecutiveFailures += 1;
+    if (!recoverable) state.unrecoverableFailures += 1;
+    const r1 = climb(state.consecutiveFailures, THRESHOLDS.failure, state.failureWarnedAt, true);
+    if (r1) {
+      state.failureWarnedAt = r1.threshold;
+      report('too_many_failures', r1.severity, state.consecutiveFailures);
+    }
+    const r2 = climb(state.unrecoverableFailures, THRESHOLDS.unrecoverable, state.unrecoverableWarnedAt, true);
+    if (r2) {
+      state.unrecoverableWarnedAt = r2.threshold;
+      report('too_many_failures', r2.severity, state.consecutiveFailures);
+    }
+  }
+
+  function resetFailures() {
+    state.consecutiveFailures = 0;
+    state.unrecoverableFailures = 0;
+    state.failureWarnedAt = 0;
+    state.unrecoverableWarnedAt = 0;
+  }
+
+  /**
+   * 收到一屏。[didAct] 表示这屏是不是一个动作之后拿到的；[effectNoted] 表示这个动作的「有没有效果」
+   * 已经按 effect 字段记过，别再用「指纹没变」重复记一次。
+   */
+  function handleFrame(fp, didAct, effectNoted) {
+    if (fp === state.lastFingerprint) {
+      if (didAct && !effectNoted) {
+        state.unchanged += 1;
+        noProgress();
+      }
+      return;
+    }
+    state.lastFingerprint = fp;
+    state.rereads = 0;
+    state.rereadWarnedAt = 0;
+    if (state.trail.length === 0 || state.trail[state.trail.length - 1] !== fp) state.trail.push(fp);
+    if (state.trail.length > TRAIL_KEEP) state.trail.shift();
+    const seenBefore = state.seenStates.has(fp);
+    let cyc = null;
+    if (!seenBefore) {
+      state.seenStates.add(fp);
+      state.visits.set(fp, 1);
+      progress();
+    } else {
+      const n = (state.visits.get(fp) || 1) + 1;
+      state.visits.set(fp, n);
+      cyc = detectCycle(state.trail);
+      if (!cyc) sameState(fp, n);
+    }
+    if (cyc === null) cyc = detectCycle(state.trail);
+    cycleCheck(cyc);
+    if (didAct) noNewState();
+  }
+
+  /**
+   * 喂一步。返回这一步给出的最重要一条结论（stop 优先，否则最后一条 warn），没有则 null。
+   * 返回对象形如 { code, severity, count, advice }；advice 只有 warn 才有（三出路那段）。
+   * @param {object} step
+   */
+  function noteStep(step) {
+    if (state.stopped) return state.stopped;
+    const s = step && typeof step === 'object' ? step : {};
+    state.emitted = [];
+
+    if (s.ok === false) noteFailure(s);
+    else if (s.ok === true) resetFailures();
+
+    const fp = fingerprintOf(s);
+    const kind = s.kind || (s.tool === 'phone_screen' ? 'read' : 'action');
+
+    if (kind === 'read' || kind === 'diagnostic') {
+      if (s.fresh === true) progress();
+      if (fp !== null) {
+        if (fp === state.lastFingerprint && s.fresh !== true) {
+          state.rereads += 1;
+          const rung = climb(state.rereads, THRESHOLDS.reread, state.rereadWarnedAt, true);
+          if (rung) {
+            state.rereadWarnedAt = rung.threshold;
+            report('read_loop', rung.severity, state.rereads);
+          }
+        }
+        handleFrame(fp, false, true);
+      }
+    } else {
+      state.sinceNewState += 1;
+      noteRepeat(s);
+      const effect = typeof s.effect === 'string' ? s.effect : null;
+      if (effect === 'no_effect') {
+        state.unchanged += 1;
+        if (s.treeBlind === true) state.treeBlindActions += 1;
+        noProgress();
+      } else if (effect !== null) {
+        resetNoEffect();
+      }
+      if (fp !== null) handleFrame(fp, true, effect !== null);
+    }
+
+    const made = state.emitted;
+    if (state.stopped && state.stopped.severity === SEVERITY.STOP) return state.stopped;
+    if (made.length === 0) return null;
+    const stop = made.find((v) => v.severity === SEVERITY.STOP);
+    return stop || made[made.length - 1];
+  }
+
+  return {
+    noteStep,
+    level: () => state.level,
+    shouldStop: () => state.level === SEVERITY.STOP || state.stopped !== null,
+    advice: () => state.lastAdvice,
+    reset,
+  };
+}
+
+module.exports = {
+  createGuard,
+  actionSignature,
+  elementsFingerprint,
+  fnv1a64,
+  stableStringify,
+  detectCycle,
+  climb,
+  lateStop,
+  SEVERITY,
+  THRESHOLDS,
+  DEFAULT_BUDGET,
+  LOOP_WINDOW,
+  MAX_CYCLE,
+};

package/lib/mobile/phone/irreversible.js

@@ -8,12 +8,26 @@
  * 误判 —— 把整屏文字当成这一下的目标，会把「聊天页里恰好有『删除』两个字」判成删除，
  * 那比漏判更烦人（每次点都停下来问）。
  *
- * 词表繁简两边都认，加上英文的 send / submit / order / pay / buy / delete。分成五类，
- * 但输出的 kind 只有 payment / submit / send / delete / none —— 下单、购买、付款这类收钱的
- * 都归 payment（对熔断来说它们是一回事：都花钱）。
+ * ## 从 Mika 借来的三条判据（词表与阈值按我们自己的口径重定，没有照抄）
+ *
+ * 1. **订单状态不算动作。** 词前面紧挨着「待」「已」、或后面跟着状态/入口一类的尾巴
+ *    （成功、记录、明细、方式、列表、中心、入口、码、售后），这条词就不是一个可点的动作，
+ *    而是状态或入口：`待付款`、`付款成功`、`订单记录`、`付款方式` 一律不算。我们只认
+ *    「这一下点下去会改世界」的那种写法，宁可漏判一次也不把每个列表页都拦下来。
+ * 2. **优惠金额不算应付金额。** 紧挨着 优惠 / 减 / 抵扣 / 运费 / 券 / 红包 / 已省（或前面带
+ *    负号）的金额不参与金额核对；否则「满25减3」会被当成「应付 25」。
+ * 3. **金额与合计识别单列出来。** `payableAmounts` / `hasTotalLabel` / `TOTAL_LABELS` 给
+ *    gate 核对「申报的金额在屏上」用；只有合计/实付/应付/总计/总价/小计/总额这类字样，或带
+ *    币种/元的数，才算金额。单独一个价格、待遇、区间不是应付金额。
+ *
+ * 与 Mika 的差别：Mika 的 `IrreversibleDetector.kt` 六百多行，认回车/组合键/横滑/资源 ID/
+ * 下拉/拖拽/看图找点等十几种信号；我们只有 tap 的那一条路，其余信号在手机执行器里由
+ * `ScreenTree` 压平后本来就拿不到。所以这里只搬规则、不搬那六百行：状态前缀/后缀、优惠排除、
+ * 合计识别这三条最容易被误判的补进来，词表仍用我们自己那份（下单、购买、付款、发送、提交、
+ * 删除等），阈值（状态尾巴、优惠窗口、英文整词）都按上面重定。
  *
- * 已知局限：这是词表兜底，不看语义。订单状态一类的文字（「待付款」「付款成功」「订单记录」）
- * 里也有付款 / 订单词，会被当成对外动作 —— 方向是「宁可多停一次」，不会误执行。
+ * 输出的 kind 仍只有 payment / submit / send / delete / none —— 下单、购买、付款这类收钱的
+ * 都归 payment（对熔断来说它们是一回事：都花钱）。
  */
 
 /** 只有点屏幕才有「点的是哪个按钮」这回事。 */
@@ -52,10 +66,39 @@ const LABEL_FIELDS = [
   'contentDescription', 'title', 'content', 'value',
 ];
 
+/** 紧挨在词前面时，说明它是一个状态而不是动作：「待付款」「已付款」。 */
+const STATUS_PREFIXES = new Set(['待', '已']);
+
+/** 紧跟在词后面（跳过标点后）时，说明它是状态或入口：「付款成功」「订单记录」「付款方式」。 */
+const STATUS_SUFFIXES = ['成功', '记录', '明细', '方式', '列表', '中心', '入口', '码', '售后'];
+
+/** 合计一类的字样：这后面的数才是应付金额。 */
+const TOTAL_LABELS = ['合计', '实付', '应付', '总计', '总价', '小计', '总额', '待付款金额'];
+
+/** 紧挨在金额前面的优惠一类字样：这类金额不是应付金额。 */
+const DISCOUNTS = ['优惠', '减', '抵扣', '运费', '券', '红包', '已省'];
+/** 往前看几个字判断是不是优惠金额。 */
+const DISCOUNT_WINDOW = 4;
+
+/** 带币种（¥/￥/$/＄）或「元」的金额；小数允许 . 或 , 作分隔。 */
+const CURRENCY = /[¥￥$＄]\s*(\d+(?:[.,]\d+)?)|(\d+(?:[.,]\d+)?)\s*元/g;
+
 function isEnglishWord(word) {
   return /^[a-z]+$/.test(word);
 }
 
+/** 去掉标点后的后续文字，用来判状态尾巴。 */
+function afterWord(text, end) {
+  return text.slice(end).replace(/^[^\p{L}\p{N}]+/u, '');
+}
+
+/** 这一处词是不是一个「动作」，而不是状态/入口（见文件头第 1 条）。 */
+function isActionOccurrence(label, word, index) {
+  if (index > 0 && STATUS_PREFIXES.has(label[index - 1])) return false;
+  const rest = afterWord(label, index + word.length);
+  return !STATUS_SUFFIXES.some((suffix) => rest.startsWith(suffix));
+}
+
 /** 在一个文字里找第一个命中的词，返回 {kind, word} 或 null。 */
 function matchLabel(label) {
   const lower = label.toLowerCase();
@@ -64,8 +107,15 @@ function matchLabel(label) {
       if (isEnglishWord(word)) {
         // 英文按整词匹配，避免 order 命中 reorder / preorder。
         if (new RegExp(`\\b${word}\\b`, 'i').test(lower)) return { kind: group.kind, word };
-      } else if (label.includes(word)) {
-        return { kind: group.kind, word };
+        continue;
+      }
+      // 中文可能有多个出现位置，逐个判是不是动作（跳过「待付款」「付款成功」这类）。
+      let from = 0;
+      let index = label.indexOf(word, from);
+      while (index !== -1) {
+        if (isActionOccurrence(label, word, index)) return { kind: group.kind, word };
+        from = index + 1;
+        index = label.indexOf(word, from);
       }
     }
   }
@@ -96,6 +146,33 @@ function none(reason) {
   return { irreversible: false, kind: 'none', reason };
 }
 
+/**
+ * 从一段文字里认出带币种/元的金额（去掉优惠一类、带负号的）。给 gate 核对金额用。
+ * @returns {number[]} 数字数组
+ */
+function payableAmounts(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const out = [];
+  CURRENCY.lastIndex = 0;
+  let m;
+  while ((m = CURRENCY.exec(text)) !== null) {
+    const raw = (m[1] || m[2] || '').replace(/,/g, '');
+    const value = Number(raw);
+    if (!Number.isFinite(value)) continue;
+    const before = text.slice(Math.max(0, m.index - DISCOUNT_WINDOW), m.index);
+    if (DISCOUNTS.some((w) => before.includes(w))) continue;
+    if (before.trimEnd().endsWith('-')) continue;
+    out.push(value);
+  }
+  return out;
+}
+
+/** 这段文字里有没有「合计/实付/应付/总计…」这类字样（金额核对是否绑定用它）。 */
+function hasTotalLabel(text) {
+  if (typeof text !== 'string' || !text) return false;
+  return TOTAL_LABELS.some((label) => text.includes(label));
+}
+
 /**
  * judge({ action, args, screenText }) → { irreversible, kind, reason }。
  *
@@ -140,7 +217,10 @@ function judge(input) {
 
 module.exports = {
   judge,
-  // 下面几个给守卫直接用真值表，不重复实现匹配逻辑。
+  // 下面几个给守卫和 gate 直接用真值表，不重复实现匹配逻辑。
   WORD_TABLE,
   matchLabel,
+  payableAmounts,
+  hasTotalLabel,
+  TOTAL_LABELS,
 };