dsh-mobile-plugin 0.5.24 → 0.5.27

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

package/lib/mobile/phone/routes.js

@@ -20,6 +20,9 @@
 
 const { sendJson, readJsonBody } = require('../../shared/http-util');
 const binding = require('./binding.js');
+const pacing = require('./pacing.js');
+const routeHint = require('./route-hint.js');
+const knowledge = require('../phone-knowledge.js');
 
 /** 设备标题：机型优先，没有机型才用 deviceId 的短尾巴。与凭据面板同一口径。 */
 function deviceLabel(row) {
@@ -60,6 +63,9 @@ function listDevices(deps) {
       osVersion: row.osVersion || '',
       appVersion: row.appVersion || '',
       online: Boolean(live),
+      // 能力清单只对「此刻连着」的那台有意义：设置页据此说「这台手机支持什么」。
+      // 没连上时报空表，界面那边按「还没连上」处理，不拿上一次的旧清单冒充。
+      capabilities: live && Array.isArray(live.capabilities) ? live.capabilities : [],
       lastSeenAt: row.lastSeenAt || 0,
     });
     if (live) online.delete(row.deviceId);
@@ -74,6 +80,7 @@ function listDevices(deps) {
       osVersion: device.osVersion || '',
       appVersion: device.appVersion || '',
       online: true,
+      capabilities: Array.isArray(link.capabilities) ? link.capabilities : [],
       lastSeenAt: Date.now(),
     });
   }
@@ -105,6 +112,12 @@ async function handlePhoneStatus(deps, _ctx, req, res) {
       lastSender: binding.lastSenderOf(sessionId) || '',
     };
   }
+  // 顶层再带一份「这台手机能做什么」：设置页问的是「我现在操作的是哪台、它能做什么」，
+  // 那条会话绑了就看绑的那台，没绑就看唯第一台在线的。都没有就是空表。
+  const focus = (payload.binding && payload.binding.deviceId)
+    ? devices.find((row) => row.deviceId === payload.binding.deviceId)
+    : devices.find((row) => row.online);
+  payload.capabilities = focus && Array.isArray(focus.capabilities) ? focus.capabilities : [];
   sendJson(res, 200, payload);
 }
 
@@ -141,6 +154,71 @@ async function handlePhoneUnbind(deps, _ctx, req, res) {
   sendJson(res, 200, { ok: true, clearedSession: false, clearedBindings: cleared, disconnected: targets, localReset: 'requested' });
 }
 
+/**
+ * GET /phone/knowledge?package=… —— 知识库里有哪些 App、有哪些网站，各自包名 / 域名，以及按就
+ * 包名查询时的命中情况。
+ *
+ * 只读：把 `knowledge/apps/*.md` 与 `knowledge/sites/*.md` 的目录清单摊平给设置页看，不碰手机、
+ * 不发任何动作。`package` 是可选的前台包名；给了就标出哪一条 App 命中（`hit`），并回填 `matched`。
+ */
+async function handlePhoneKnowledge(deps, _ctx, req, res) {
+  const url = new URL(req.url || '/', 'http://x');
+  const pkg = (url.searchParams.get('package') || '').trim();
+  const matched = pkg ? knowledge.matchApp(pkg) : null;
+  const apps = knowledge.listApps().map((app) => ({
+    name: app.name,
+    display: app.display,
+    packages: app.packages,
+    aliases: app.aliases,
+    open: app.open,
+    hit: Boolean(matched && matched.name === app.name),
+  }));
+  const sites = knowledge.listSites().map((site) => ({
+    name: site.name,
+    display: site.display,
+    description: site.description,
+    sites: site.sites,
+    aliases: site.aliases,
+  }));
+  sendJson(res, 200, { ok: true, apps, sites, matched: matched ? matched.name : '' });
+}
+
+/**
+ * GET /phone/routes?package=… —— 某个 App 以前成功过的路线（最多 5 条，只给步骤摘要）。
+ *
+ * 只读：从成功路线账本里读回，不碰手机、不发任何动作。**这些只是参考，不会自动执行** ——
+ * 模型看过之后仍要按当前屏重新判断。
+ */
+async function handlePhoneRoutes(_deps, _ctx, req, res) {
+  const url = new URL(req.url || '/', 'http://x');
+  const pkg = (url.searchParams.get('package') || '').trim();
+  const routes = pkg ? routeHint.hintFor(pkg) : [];
+  sendJson(res, 200, { ok: true, packageName: pkg, count: routes.length, routes });
+}
+
+/**
+ * GET / POST /phone/pacing —— 读或改「操作节奏」那一档。
+ *
+ * 和上面几条一样只碰设置，不往手机上发动作：节奏改了下一轮动作才生效，正在跑的那一批
+ * 不跟着变（动作中途改停留会让边界很奇怪，重开一轮才干净）。
+ */
+async function handlePhonePacing(_deps, _ctx, req, res) {
+  if (req.method === 'GET' || !req.method) {
+    const mode = pacing.get();
+    return sendJson(res, 200, { ok: true, mode, pace: pacing.paceFor(mode) });
+  }
+  const body = await readJsonBody(req);
+  const wanted = body && typeof body.mode === 'string' ? body.mode.trim().toLowerCase() : '';
+  if (!wanted) return sendJson(res, 400, { ok: false, error: 'missing-mode' });
+  try {
+    const mode = pacing.set(wanted);
+    sendJson(res, 200, { ok: true, mode, pace: pacing.paceFor(mode) });
+  } catch {
+    // 不认识的档名：如实回 400 并把可选值带上，别让设置页自己维护一份枚举。
+    sendJson(res, 400, { ok: false, error: 'unknown-mode', modes: pacing.MODES });
+  }
+}
+
 /**
  * 造出路由表要的那组 handler。
  *
@@ -154,6 +232,9 @@ function createPhoneRoutes(deps) {
     status: (ctx, req, res) => handlePhoneStatus(deps, ctx, req, res),
     devices: (ctx, req, res) => handlePhoneDevices(deps, ctx, req, res),
     unbind: (ctx, req, res) => handlePhoneUnbind(deps, ctx, req, res),
+    knowledge: (ctx, req, res) => handlePhoneKnowledge(deps, ctx, req, res),
+    routes: (ctx, req, res) => handlePhoneRoutes(deps, ctx, req, res),
+    pacing: (ctx, req, res) => handlePhonePacing(deps, ctx, req, res),
   };
 }
 
@@ -162,6 +243,9 @@ module.exports = {
   handlePhoneStatus,
   handlePhoneDevices,
   handlePhoneUnbind,
+  handlePhoneKnowledge,
+  handlePhoneRoutes,
+  handlePhonePacing,
   listDevices,
   describeDevice,
   deviceLabel,

package/lib/mobile/phone/service.js

@@ -69,8 +69,24 @@ const ACTIONS = new Map([
   ['app.list', 20_000],
   ['wait', 30_000],
   ['task.release', 20_000],
+  // `batch` 是多个动作打包：这里的数字只是它作为「一个动作」登记进表时的占位 seed，
+  // 真实预算由 budgetForBatch 按步数与等待上限单独算（见下），不走单动作那套。
+  ['batch', 120_000],
+  ['screen.wait', 30_000],
+  ['gesture', 20_000],
+  ['app.link', 20_000],
 ]);
 
+/**
+ * 帧压缩的测量开关，默认关。
+ *
+ * 宿主端 deflate 是「CPU 换带宽」：手机常在弱网，压缩看着划算，但每一帧都要在宿主上现算，
+ * 低端机与高频小帧下 CPU 代价明显，而这条通道的大头（截图 base64）早就一帧一封。到底值不值
+ * 要真机量过 p50/p99 延迟与宿主的占用才能定，所以默认维持原样关闭，只留一个环境变量把压缩
+ * 打开来测量，不擅自改线上默认。
+ */
+const COMPRESS_FRAMES = process.env.DSH_MOBILE_PHONE_COMPRESS === '1';
+
 function text(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -112,7 +128,8 @@ function createPhoneService({ authorized, onLog } = {}) {
    * 冷启动抬到 seed*1.5 兜底，最后夹进 [max(2500, seed/2), min(120000, max(seed*8, floor))]。
    * `ACTIONS` 里的数字只是这个 seed，不再直接当预算。
    */
-  function budgetFor(link, action) {
+  function budgetFor(link, action, args) {
+    if (action === 'batch') return budgetForBatch(link, args);
     const seed = ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS;
     const lat = link.latency;
     const pa = lat.perAction.get(action);
@@ -128,16 +145,56 @@ function createPhoneService({ authorized, onLog } = {}) {
     return Math.round(Math.min(Math.max(budget, floor), ceil));
   }
 
+  /**
+   * `batch` 的预算要按整批放，不能沿用单动作的估法 —— 一批十几步，每步都可能带一段等待，
+   * 单步预算乘一乘就把手机端「整批共用宿主下发 timeout」的约定撑破了。
+   *
+   * 累加三样：每步各自的估时（有实测 EWMA 就用实测，没有就用该动作的 seed），每步 `until`
+   * 声明的等待上限（与手机侧同口径：默认 8000、封顶 20000），以及每步一次往返的网络余量。
+   * 结果夹在 [5s, 180s]：低于 5s 连正常几步都装不下；高于 180s 基本是手机卡死，再等没意义。
+   */
+  function budgetForBatch(link, args) {
+    const steps = args && Array.isArray(args.steps) ? args.steps : [];
+    const lat = link.latency;
+    const rtt = lat.rtt > 0 ? lat.rtt : 0;
+    let total = 0;
+    for (const step of steps) {
+      const action = text(step && step.action);
+      const seed = ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS;
+      const pa = lat.perAction.get(action);
+      let est = seed;
+      if (pa && pa.n >= 2) est = pa.value;
+      else if (lat.all && lat.all.n >= 2) est = lat.all.value;
+      total += est;
+      const until = step && step.until;
+      if (until && typeof until === 'object') {
+        const t = Number(until.timeoutMs);
+        total += Number.isFinite(t) && t > 0 ? Math.min(t, 20_000) : 8_000;
+      }
+    }
+    total += rtt * 2 * steps.length;
+    return Math.round(Math.min(Math.max(total, 5_000), 180_000));
+  }
+
   const log = (message) => { try { onLog?.(message); } catch { /* 日志失败不影响搬运 */ } };
 
-  const wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: MAX_PAYLOAD });
+  const wss = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: COMPRESS_FRAMES ? { threshold: 1024 } : false,
+    maxPayload: MAX_PAYLOAD,
+  });
 
   function nextId() {
     seq += 1;
     return `p${seq}`;
   }
 
-  /** 关掉一条连接并结算它的在途 op。 */
+  /**
+   * 关掉一条连接并结算它的在途 op。
+   *
+   * 这里不区分动作：`batch` 和单步一样挂在 `link.pending` 上，走到一半断线就连同它的结果一起
+   * 以 offline 结算，手机侧那套「整批共用宿主 timeout」不需要宿主特殊对待。
+   */
   function drop(deviceId, reason) {
     const link = devices.get(deviceId);
     if (!link) return;
@@ -273,7 +330,7 @@ function createPhoneService({ authorized, onLog } = {}) {
     if (!ACTIONS.has(action)) return Promise.reject({ code: 'unknown-action', message: `不支持的动作 ${action}` });
 
     const opId = nextId();
-    const budget = Number.isFinite(timeoutMs) ? timeoutMs : budgetFor(link, action);
+    const budget = Number.isFinite(timeoutMs) ? timeoutMs : budgetFor(link, action, args);
     return new Promise((resolve, reject) => {
       let settled = false;
       const settle = (fn, value) => {
@@ -290,6 +347,8 @@ function createPhoneService({ authorized, onLog } = {}) {
         settleOk: (data) => settle(resolve, { ok: true, data }),
         settleErr: (error) => settle(reject, error),
       };
+      // 超时 / 取消都发同一条 `cancel` 帧 —— 帧里只带 id，手机侧自己按 id 找那条 op，
+      // 所以正在跑的 `batch` 也能被这一步撤销，不需要另加批专用的停止帧。
       const timer = setTimeout(() => {
         settle(reject, { code: 'timeout', message: '迟迟没有回应这一步' });
         try { link.socket.send(JSON.stringify({ t: 'cancel', id: opId })); } catch { /* 已断 */ }
@@ -318,6 +377,20 @@ function createPhoneService({ authorized, onLog } = {}) {
     return Boolean(link && statusOf(link.socket));
   }
 
+  /**
+   * 这台手机报没报某项能力（工具层据此决定某个参数是否生效）。
+   *
+   * 手机在 hello / attached 帧里上行 `capabilities`，没连上或没报过就一律当作不支持 ——
+   * 「没听说」和「不支持」在这里是同一件事，宁可让工具层多说一句「需要升级手机上的 App」，
+   * 也不要凭空假定它能做。
+   */
+  function hasCapability(deviceId, capName) {
+    const link = devices.get(text(deviceId));
+    if (!link || !statusOf(link.socket)) return false;
+    const name = text(capName);
+    return name !== '' && Array.isArray(link.capabilities) && link.capabilities.includes(name);
+  }
+
   /** 一台手机的连接信息（给 App 的状态页用）。 */
   function statusOfDevice(deviceId) {
     const link = devices.get(text(deviceId));
@@ -367,7 +440,19 @@ function createPhoneService({ authorized, onLog } = {}) {
     wss.close?.();
   }
 
-  return { handleUpgrade, call, isOnline, statusOfDevice, kick, close, ACTIONS, devices };
+  return {
+    handleUpgrade,
+    call,
+    isOnline,
+    statusOfDevice,
+    hasCapability,
+    kick,
+    close,
+    ACTIONS,
+    devices,
+    // 测量开关的当前取值，供自检 / 日志读出（真实压缩在 wss 构造时就定了）。
+    compressionEnabled: COMPRESS_FRAMES,
+  };
 }
 
 function refuse(socket, status, reason, bodyText) {