dsh-mobile-plugin 0.5.23 → 0.5.26

package/lib/mobile/phone/irreversible.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * 不可逆动作判定：纯函数，只回答「这一下点下去是不是收不回来」，不做任何动作。
+ *
+ * 给 tools 层做单步提示、给 batch 做熔断用。判据刻意窄：只有 **tap** 且能读到「点的是哪个
+ * 按钮的文字」才算数。读不到文字（只有 ref、只有坐标而没 target）就判不了，宁可放过也不
+ * 误判 —— 把整屏文字当成这一下的目标，会把「聊天页里恰好有『删除』两个字」判成删除，
+ * 那比漏判更烦人（每次点都停下来问）。
+ *
+ * 词表繁简两边都认，加上英文的 send / submit / order / pay / buy / delete。分成五类，
+ * 但输出的 kind 只有 payment / submit / send / delete / none —— 下单、购买、付款这类收钱的
+ * 都归 payment（对熔断来说它们是一回事：都花钱）。
+ *
+ * 已知局限：这是词表兜底，不看语义。订单状态一类的文字（「待付款」「付款成功」「订单记录」）
+ * 里也有付款 / 订单词，会被当成对外动作 —— 方向是「宁可多停一次」，不会误执行。
+ */
+
+/** 只有点屏幕才有「点的是哪个按钮」这回事。 */
+const TAP_ACTIONS = new Set(['tap']);
+
+/**
+ * 词表按 kind 分组，顺序即优先级：先看样子最重的付款 / 下单，再提交、发送、删除。
+ * 中文按包含判；纯英文词按单词边界判，免得 order 在 reorder、delete 在 undelete 里误命中。
+ */
+const WORD_TABLE = [
+  {
+    kind: 'payment',
+    words: [
+      '支付', '付款', '买单', '买單', '下单', '下單', '购买', '購買',
+      '结算', '結算', '订单', '訂單', '收银台', '收銀台',
+      'pay', 'payment', 'order', 'buy', 'purchase', 'checkout',
+    ],
+  },
+  {
+    kind: 'submit',
+    words: ['提交', '确认提交', '確認提交', '送出', 'submit'],
+  },
+  {
+    kind: 'send',
+    words: ['发送', '傳送', '传送', '发布', '發布', '发表', '發表', 'send', 'post'],
+  },
+  {
+    kind: 'delete',
+    words: ['删除', '刪除', '清空', '移除', 'delete', 'remove', 'clear'],
+  },
+];
+
+/** 这些字段可能装着「点的是哪个按钮」的文字；按顺序取，取到非空就用。 */
+const LABEL_FIELDS = [
+  'text', 'target', 'label', 'name', 'description', 'desc',
+  'contentDescription', 'title', 'content', 'value',
+];
+
+function isEnglishWord(word) {
+  return /^[a-z]+$/.test(word);
+}
+
+/** 在一个文字里找第一个命中的词，返回 {kind, word} 或 null。 */
+function matchLabel(label) {
+  const lower = label.toLowerCase();
+  for (const group of WORD_TABLE) {
+    for (const word of group.words) {
+      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 };
+      }
+    }
+  }
+  return null;
+}
+
+/** 从参数里能读到的、像「被点元素文字」的那几条。 */
+function labelsOf(args) {
+  const out = [];
+  for (const key of LABEL_FIELDS) {
+    const value = args[key];
+    if (typeof value === 'string') {
+      const text = value.trim();
+      if (text) out.push(text);
+    }
+  }
+  return out;
+}
+
+/** 一个孤零零的短串才可能是按钮文字；长段多行的是整屏，不能当目标。 */
+function looksLikeLabel(text) {
+  const trimmed = text.trim();
+  if (!trimmed || trimmed.length > 32) return false;
+  return !/[\r\n]/.test(trimmed);
+}
+
+function none(reason) {
+  return { irreversible: false, kind: 'none', reason };
+}
+
+/**
+ * judge({ action, args, screenText }) → { irreversible, kind, reason }。
+ *
+ * `screenText` 只在「既没 ref / 坐标、也没有任何文字字段」且它本身像个按钮短串时才当目标文字；
+ * 有 ref 或坐标却没有文字时一律判不了 —— 这是「ref 点按不误判」那条要求的落点。
+ */
+function judge(input) {
+  const { action, args, screenText } = input || {};
+  const a = args && typeof args === 'object' ? args : {};
+
+  if (typeof action !== 'string' || !TAP_ACTIONS.has(action)) {
+    return none('只判 tap：别的动作没有「点的是哪个按钮」这回事');
+  }
+
+  const hasRef = typeof a.ref === 'string' && a.ref.trim() !== '';
+  const hasPoint = Number.isFinite(a.x) && Number.isFinite(a.y);
+  let labels = labelsOf(a);
+
+  if (labels.length === 0) {
+    if (hasRef || hasPoint) {
+      return none('只有 ref / 坐标、没有说话文字，判定不了');
+    }
+    if (typeof screenText === 'string' && looksLikeLabel(screenText)) {
+      labels = [screenText.trim()];
+    }
+  }
+
+  if (labels.length === 0) return none('没有可判的文字');
+
+  for (const label of labels) {
+    const hit = matchLabel(label);
+    if (hit) {
+      return {
+        irreversible: true,
+        kind: hit.kind,
+        reason: `「${label}」命中不可逆词「${hit.word}」`,
+      };
+    }
+  }
+  return none('没有命中不可逆词表');
+}
+
+module.exports = {
+  judge,
+  // 下面几个给守卫直接用真值表，不重复实现匹配逻辑。
+  WORD_TABLE,
+  matchLabel,
+};

package/lib/mobile/phone/pacing.js

@@ -0,0 +1,173 @@
+'use strict';
+
+/**
+ * 操作节奏：决定「动作之间停多久」「对外动作之间至少隔多久」。
+ *
+ * 三档 fast / standard / human，默认 standard，存在插件设置里（与播报开关同一处：
+ * `<DSH_HOME>/storages/mobile-plugin/phone-pacing.json`）。这里只给数字，**自己不 sleep**：
+ * 真正等待的是执行动作的那一层，本模块一睡就把测试和宿主都拖住。
+ *
+ * 对外动作的间隔照 Mika 的 OutwardPacing：最近 30 分钟内做得越多，间隔越往上涨，
+ * 上下限各 +0.5s / +1s，封顶 30s。第一次不额外等 —— 一条消息本来就要花那几个动作，
+ * 从第一条起就硬等只会让人以为手机卡了。
+ *
+ * 落盘失败不抛：节奏是锦上添花，写不进去也要让这一轮按新节奏继续跑。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../../shared/paths');
+
+/** 可选的三档。 */
+const MODES = ['fast', 'standard', 'human'];
+const DEFAULT_MODE = 'standard';
+
+/** 对外动作计数的时间窗：只算最近半小时做过的。 */
+const OUTWARD_WINDOW_MS = 30 * 60 * 1000;
+/** 每多做一次对外动作，间隔下限 / 上限各加这么多毫秒。 */
+const PER_ACTION_MS = [500, 1000];
+/** 间隔封顶，再密也不等超过半分钟。 */
+const MAX_OUTWARD_MS = 30 * 1000;
+
+/**
+ * 三档的具体数字。
+ *
+ * `betweenActionsMs`：同一轮里相邻两个动作之间的停留范围；
+ * `outwardMinMs`：两个对外动作（发送 / 提交 / 下单这类）之间的最小间隔范围，起点也会被
+ *   noteOutward 按次数往上加；
+ * `typingChunkMs`：一段一段打字时每段之间停多久（fast 一次写全文，所以是 0）。
+ */
+const TABLES = {
+  fast: {
+    betweenActionsMs: [0, 0],
+    outwardMinMs: [0, 0],
+    typingChunkMs: 0,
+  },
+  standard: {
+    betweenActionsMs: [500, 1200],
+    outwardMinMs: [8000, 20000],
+    typingChunkMs: 40,
+  },
+  human: {
+    betweenActionsMs: [1000, 2000],
+    outwardMinMs: [15000, 30000],
+    typingChunkMs: 90,
+  },
+};
+
+function settingsFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'phone-pacing.json');
+}
+
+/** 把大小写 / 空白各异的输入收成一个合法档名；认不出返回 null。 */
+function normalizeMode(mode) {
+  if (typeof mode !== 'string') return null;
+  const m = mode.trim().toLowerCase();
+  return MODES.includes(m) ? m : null;
+}
+
+/** 上一轮写盘失败时记住的档名：写不进去也不能让调用方读回旧值。 */
+let memoryMode = null;
+
+function readStoredMode() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(settingsFile(), 'utf8'));
+    return normalizeMode(raw && raw.mode);
+  } catch {
+    // 文件不存在 / 读坏 / 字段不对都当没设过，走默认档。
+    return null;
+  }
+}
+
+/** 当前档。读不到就是 standard（坏文件同样落在这里）。 */
+function get() {
+  if (memoryMode) return memoryMode;
+  return readStoredMode() || DEFAULT_MODE;
+}
+
+/**
+ * 改成某一档并落盘。非法档名是调用方写错了，直接抛；写盘失败只记住内存值、不抛。
+ * 返回改后的当前档，方便调用方直接回给界面。
+ */
+function set(mode) {
+  const m = normalizeMode(mode);
+  if (!m) throw new RangeError(`未知的操作节奏：${String(mode)}（可选 ${MODES.join(' / ')}）`);
+  try {
+    const file = settingsFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ mode: m }, null, 2)}\n`);
+    memoryMode = null;
+  } catch {
+    memoryMode = m;
+  }
+  return m;
+}
+
+/** 某一档的数字。认不出的档按 standard 给，避免调用方拿到 undefined 再炸开。 */
+function paceFor(mode) {
+  const table = TABLES[normalizeMode(mode) || DEFAULT_MODE];
+  return {
+    betweenActionsMs: [...table.betweenActionsMs],
+    outwardMinMs: [...table.outwardMinMs],
+    typingChunkMs: table.typingChunkMs,
+  };
+}
+
+/** 最近做过的对外动作时间点（升序）。只有一台手机，不按包名分组。 */
+let outwardAt = [];
+
+function prune(now) {
+  while (outwardAt.length > 0 && now - outwardAt[0] > OUTWARD_WINDOW_MS) outwardAt.shift();
+}
+
+/**
+ * 记一次「现在要做对外动作」，返回这一发至少要等多少毫秒。
+ *
+ * 返回的是**最小**值（下限），不是随机值：调用方自己决定要不要在这个余量之外再多停。
+ * 第一次对外动作返回 0；之后按最近 30 分钟已做的次数把下限往上抬（每次 +0.5s），
+ * 封顶 30s；如果从上一次到现在已经隔够了，返回 0。
+ */
+function noteOutward(nowMs) {
+  const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+  const pace = paceFor(get());
+  prune(now);
+
+  let minWaitMs = 0;
+  const baseLowMs = pace.outwardMinMs[0];
+  // fast 档下限是 0：不计数、不加码，永远不等（与 Mika 的 Off 一个意思）。
+  if (outwardAt.length > 0 && baseLowMs > 0) {
+    const extra = outwardAt.length - 1;
+    const required = Math.min(baseLowMs + extra * PER_ACTION_MS[0], MAX_OUTWARD_MS);
+    const elapsed = now - outwardAt[outwardAt.length - 1];
+    minWaitMs = Math.max(0, required - elapsed);
+  }
+
+  outwardAt.push(now);
+  return minWaitMs;
+}
+
+/** 单测用：清掉对外动作的计数。 */
+function resetOutwardForTest() {
+  outwardAt = [];
+}
+
+/** 单测用：把内存里「写盘失败留下的档」也清掉。 */
+function resetCacheForTest() {
+  memoryMode = null;
+}
+
+module.exports = {
+  get,
+  set,
+  paceFor,
+  noteOutward,
+  resetOutwardForTest,
+  resetCacheForTest,
+  settingsFile,
+  MODES,
+  DEFAULT_MODE,
+  OUTWARD_WINDOW_MS,
+  PER_ACTION_MS,
+  MAX_OUTWARD_MS,
+};

package/lib/mobile/phone/route-hint.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * `phone_route_hint`：只读地翻出「这个 App 以前成功过的路线」。
+ *
+ * 用法是打开一个 App 之后问一句「以前有没有做成过、怎么做的」。**只给参考，不自动执行**：
+ * 这里既不连手机、也不发任何动作，模型看过之后还得自己按当前屏幕重新判断。之所以只给摘要不给
+ * 原始步骤，是因为界面会变，照抄旧路线比没有更危险 —— 摘要让模型看懂大意，具体每一步仍要现读屏。
+ *
+ * 注册形状照 `phone/tools.js` 里的那套：走 `ctx.inject(['tools'], …)` 再 `defineTool`，
+ * 不能直接读 `ctx.tools`（宿主里那是个影子对象，`register` 一调就抛，被容错吞掉后一条工具都交不到
+ * 模型手上）。缺 tools 注入的 profile 静默跳过，别把整块装配掀翻。
+ */
+
+const routesMemory = require('./routes-memory.js');
+
+/** 一次最多回几条路线。 */
+const MAX_ROUTES = 5;
+/** 摘要里单段文字最长多少字。 */
+const MAX_TEXT = 60;
+
+/** 动作名换成一句人话动词。 */
+const ACTION_VERBS = {
+  tap: '点击',
+  type: '输入',
+  key: '按键',
+  swipe: '滑动',
+  gesture: '手势',
+  'screen.wait': '等待',
+  'screen.read': '读屏',
+  'screen.screenshot': '截图',
+  'app.open': '打开',
+  'app.close': '关闭',
+};
+
+function clip(text) {
+  const value = typeof text === 'string' ? text.trim() : '';
+  if (!value) return '';
+  return value.length > MAX_TEXT ? `${value.slice(0, MAX_TEXT)}…` : value;
+}
+
+/**
+ * 把一步压成一句摘要。只取最有辨识度的一个参数，不要把小箭头变成一段代码。
+ */
+function summarizeStep(step) {
+  if (!step || typeof step !== 'object') return '';
+  const action = typeof step.action === 'string' ? step.action.trim() : '';
+  if (!action) return '';
+  const args = step.args && typeof step.args === 'object' ? step.args : {};
+  const verb = ACTION_VERBS[action] || action;
+
+  let object = '';
+  if (action === 'type') {
+    const text = clip(args.text);
+    if (text) object = `「${text}」`;
+  } else if (action === 'tap') {
+    const target = clip(args.target);
+    if (target) object = `「${target}」`;
+    else if (typeof args.ref === 'string' && args.ref.trim()) object = args.ref.trim();
+  } else if (action === 'key') {
+    object = typeof args.key === 'string' ? args.key : '';
+  } else if (action === 'app.open') {
+    object = clip(args.packageName);
+  } else if (action === 'swipe') {
+    object = typeof args.direction === 'string' ? args.direction : '';
+  } else {
+    object = clip(args.target) || clip(args.text) || clip(args.packageName) || (typeof args.ref === 'string' ? args.ref.trim() : '');
+  }
+  return object ? `${verb}${object}` : verb;
+}
+
+/**
+ * 把一条路线压成可读的摘要对象：步骤数、时间、整条路线的一句话。
+ */
+function summarizeRoute(route) {
+  const steps = route && Array.isArray(route.steps) ? route.steps : [];
+  const parts = steps.map(summarizeStep).filter(Boolean);
+  return {
+    at: route && Number.isFinite(route.at) ? route.at : 0,
+    stepCount: steps.length,
+    summary: parts.join(' → '),
+  };
+}
+
+/** 取这个 App 最近成功的几条，压成摘要。没有记录回空数组。 */
+function hintFor(packageName) {
+  const routes = routesMemory.list(packageName);
+  // 最近的先给：新近成功的路线更贴近现在这个版本的界面。
+  return routes
+    .slice()
+    .sort((a, b) => b.at - a.at)
+    .slice(0, MAX_ROUTES)
+    .map(summarizeRoute);
+}
+
+/**
+ * 注册 `phone_route_hint`。与 `installPhoneTools` 同一口径：拿不到 tools 注入就静静不装。
+ */
+function installRouteHint(ctx) {
+  if (!ctx || typeof ctx.inject !== 'function') return;
+  let defineTool;
+  try {
+    ({ defineTool } = require('@deepseek-ai/dsh-tools'));
+  } catch {
+    return;
+  }
+
+  ctx.inject(['tools'], (scoped) => {
+    if (!scoped || !scoped.tools || typeof scoped.tools.register !== 'function') return;
+    scoped.tools.register(defineTool({
+      name: 'phone_route_hint',
+      description: 'Look up routes this app has succeeded with before, as short step summaries. This is reference only — nothing is executed. After opening an app, use it to recall a past successful path, then re-read the screen and decide each step yourself; the UI may have changed.',
+      parameters: {
+        packageName: {
+          type: 'string',
+          required: true,
+          description: 'Android package name of the app, e.g. "com.tencent.mm".',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean' },
+            packageName: { type: 'string' },
+            count: { type: 'number' },
+            // 一条路线是「步骤数 + 摘要」，形状固定，但为了紧凑允许附加字段。
+            routes: { type: 'array', items: { type: 'object', additionalProperties: true } },
+            note: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          const count = Array.isArray(value.routes) ? value.routes.length : 0;
+          const lines = [`这个 App 以前成功过 ${count} 条路线（仅供参考，不会自动执行）：`];
+          for (const route of value.routes || []) lines.push(`- ${route.summary}`);
+          if (!count) lines.push('- 还没有记录。');
+          return [{ type: 'text', text: lines.join('\n') }];
+        },
+      },
+      execute: async (args) => {
+        const pkg = typeof args.packageName === 'string' ? args.packageName.trim() : '';
+        if (!pkg) throw new Error('要给一个包名（例如 com.tencent.mm）才能查历史路线。');
+        const routes = hintFor(pkg);
+        const value = {
+          ok: true,
+          packageName: pkg,
+          count: routes.length,
+          routes,
+        };
+        if (routes.length === 0) value.note = '这个 App 还没有成功过的路线记录。';
+        return value;
+      },
+    }));
+  });
+}
+
+module.exports = {
+  installRouteHint,
+  summarizeStep,
+  summarizeRoute,
+  hintFor,
+  MAX_ROUTES,
+};

package/lib/mobile/phone/routes-memory.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * 成功路线记忆：把「这个 App 上一轮是怎么一步步做成的」记下来，下次打开同一个 App 时能翻出
+ * 以前成功过的路线给模型参考。
+ *
+ * 存一份 JSON 在 `<DSH_HOME>/storages/mobile-plugin/phone-routes.json`，按包名分桶：
+ *
+ *   { "<包名>": [ { steps: [...], at: 1794…, hits: 0 } ] }   // 每个包最多 20 条
+ *
+ * 三条边界：
+ * - **只在成功时记**：`record` 由调用方在结局判定为成功后调；失败、超时、取消一律不记。
+ * - **每个包封顶 20 条**：旧记录满了就挤掉最旧的，避免一个常用 App 把文件越攒越大。
+ * - **加载失败安静退化**：文件不存在、读坏、形状不对，都当「还没有记录」，绝不抛 —— 记忆是
+ *   锦上添花，不能因为它把一次操作或者整个插件装载掀翻。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../../shared/paths');
+
+/** 每个包名最多留这么多条历史路线。 */
+const MAX_PER_PACKAGE = 20;
+
+/** 落盘文件：`<DSH_HOME>/storages/mobile-plugin/phone-routes.json`，调用时解析。 */
+function routesFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'phone-routes.json');
+}
+
+/** 只保留能落盘、也有意义的字段，别把整个 args 原样塞进去（可能很大）。 */
+function normalizeSteps(steps) {
+  if (!Array.isArray(steps)) return [];
+  const out = [];
+  for (const step of steps) {
+    if (!step || typeof step !== 'object') continue;
+    const entry = {};
+    if (typeof step.action === 'string' && step.action.trim()) entry.action = step.action.trim();
+    if (step.args && typeof step.args === 'object' && !Array.isArray(step.args)) entry.args = step.args;
+    if (step.until && typeof step.until === 'object' && !Array.isArray(step.until)) entry.until = step.until;
+    if (entry.action) out.push(entry);
+  }
+  return out;
+}
+
+/** 读整份账本。读不到 / 读坏 / 形状不对都当空。 */
+function readStore() {
+  let raw;
+  try {
+    raw = fs.readFileSync(routesFile(), 'utf8');
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+  return parsed;
+}
+
+/** 写整份账本。写不进去就安静放弃：这一轮照样算完成，只是这条没记住。 */
+function writeStore(store) {
+  const file = routesFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(store, null, 2)}\n`);
+}
+
+/** 归一化包名。 */
+function normalizePackage(packageName) {
+  return typeof packageName === 'string' ? packageName.trim() : '';
+}
+
+/**
+ * 记一条成功路线。只在成功时由调用方调；包名为空或步骤为空时不记。
+ * 返回这个包当前的全部记录（方便调用方/测试看结果）。
+ */
+function record(packageName, steps) {
+  const pkg = normalizePackage(packageName);
+  const cleaned = normalizeSteps(steps);
+  if (!pkg || cleaned.length === 0) return [];
+
+  const store = readStore();
+  const bucket = Array.isArray(store[pkg]) ? store[pkg].filter((item) => item && Array.isArray(item.steps)) : [];
+  bucket.push({ steps: cleaned, at: Date.now(), hits: 0 });
+  // 只留最近的 MAX_PER_PACKAGE 条：新记录在尾部，超了从头挤掉最旧的。
+  store[pkg] = bucket.slice(-MAX_PER_PACKAGE);
+  try {
+    writeStore(store);
+  } catch {
+    // 写失败不抛，记忆丢一条不影响这一轮已经成功的结果。
+  }
+  return store[pkg].map(copyRecord);
+}
+
+function copyRecord(item) {
+  return {
+    steps: Array.isArray(item.steps) ? item.steps.map((step) => ({ ...step })) : [],
+    at: Number.isFinite(item.at) ? item.at : 0,
+    hits: Number.isFinite(item.hits) ? item.hits : 0,
+  };
+}
+
+/**
+ * 读回某个 App 以前成功过的路线（按记录先后，旧的在前）。包名为空或没记录都回空数组。
+ * 返回的是副本，调用方改不到账本上。
+ */
+function list(packageName) {
+  const pkg = normalizePackage(packageName);
+  if (!pkg) return [];
+  const store = readStore();
+  const bucket = Array.isArray(store[pkg]) ? store[pkg] : [];
+  return bucket.filter((item) => item && Array.isArray(item.steps)).map(copyRecord);
+}
+
+/** 单测用：删掉落盘文件，回到「还没有任何记录」。 */
+function resetForTest() {
+  try {
+    fs.rmSync(routesFile(), { force: true });
+  } catch {
+    // 本来就没有。
+  }
+}
+
+module.exports = {
+  routesFile,
+  record,
+  list,
+  resetForTest,
+  MAX_PER_PACKAGE,
+};