dsh-mobile-plugin 0.5.28 → 0.5.29

package/lib/mobile/phone/tools.js

@@ -168,6 +168,43 @@ function betweenDelay() {
   }
 }
 
+/**
+ * 这一批交给手机侧的节奏参数 `{mode, place}`（见协议 §1.2/§3.3）。
+ *
+ * mode 来自插件设置的三档（pacing.js 的 get()，默认 standard）；place 来自 App 知识里那个 App 的
+ * `pace`（careful 的 App 手机侧停更久、按字数读）。手机侧按它把「步间停留 / type 分片」放到批循环里跑，
+ * 电脑侧插不进 sleep（批是一次下发、手机侧 for 循环）。拿不到就给空，手机侧按 standard / normal 兜底。
+ */
+function pacingModeOf() {
+  if (pacing && typeof pacing.get === 'function') {
+    try {
+      const m = pacing.get();
+      if (typeof m === 'string' && m) return m;
+    } catch {
+      /* 读不到就走默认 */
+    }
+  }
+  return 'standard';
+}
+
+function batchPlaceOf(steps) {
+  if (!phoneKnowledge || typeof phoneKnowledge.matchApp !== 'function') return '';
+  let pkg = '';
+  for (const s of steps) {
+    if (s && s.action === 'app.open' && s.args && typeof s.args.packageName === 'string' && s.args.packageName) {
+      pkg = s.args.packageName;
+      break;
+    }
+  }
+  if (!pkg) return '';
+  try {
+    const doc = phoneKnowledge.matchApp(pkg);
+    return doc && typeof doc.pace === 'string' ? doc.pace : '';
+  } catch {
+    return '';
+  }
+}
+
 /** 这台手机报没报某项能力；拿不到能力接口时按「支持」放过，别凭空白挡一条路径。 */
 function supports(service, deviceId, cap) {
   if (!service || typeof service.hasCapability !== 'function') return true;
@@ -401,6 +438,7 @@ async function run(service, deviceId, sessionId, action, args, signal) {
     if (code === 'offline') throw withCode('那台手机在这期间断开了连接，这一步没有做。');
     if (code === 'timeout') throw withCode(`那台手机 ${message}。可以再试一次，或者先 phone_screen 看看它现在停在哪。`);
     if (code === 'unsupported') throw withCode(`那台手机上装的 App 版本还不支持 ${action}，需要把手机上的 App 升级到最新。`);
+    if (code === 'not-supported') throw withCode('这台手机上没有一个 App 能接这个动作，退回操作界面去做吧。');
     if (code === 'adb-unavailable') throw withCode('那台手机的无线调试没连上（可能被系统关了），让用户在手机上重新打开无线调试。');
     if (code === 'warming') throw withCode('手机正在准备后台屏，大约还要几秒，稍等再试。');
     if (code === 'aborted') throw withCode('这一步被取消了。');
@@ -1308,6 +1346,8 @@ function installPhoneTools(ctx, deps) {
         const batchArgs = {
           steps: runnable.map((s) => ({ action: s.action, args: s.args, ...(s.until ? { until: s.until } : {}) })),
           quiet: args.quiet !== false,
+          // 节奏跟着批一起下去：mode 来自设置三档，place 来自 App 知识；手机侧在批循环里消费（协议 §1.2 / §3.3）。
+          pacing: { mode: pacingModeOf(), place: batchPlaceOf(runnable) },
         };
         const data = await run(service, deviceId, sessionId, 'batch', batchArgs, exec.signal);
         finalData = data;
@@ -1640,6 +1680,555 @@ function installPhoneTools(ctx, deps) {
     },
   });
 
+  // ── 结构化：提取 / 查询 / 查找 / 采集 / 滚轮 ──────────────────────────────
+
+  register({
+    name: 'phone_extract',
+    description: 'Extract structured data from the current screen in one read on the phone. mode=text pulls visible text; mode=list groups a scrollable list/recycler into rows with bounds and parents; mode=form returns only editable fields (secret fields show a boolean, never the value). It reads the accessibility tree on the phone, so list rows beyond the first 160 elements come back with bounds but no tappable ref (best-effort).',
+    parameters: {
+      mode: { type: 'string', enum: ['text', 'list', 'form'], description: 'What to extract: text, list rows, or form fields.' },
+      maxItems: { type: 'integer', description: 'Maximum records, 1-200 (default 100).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          mode: { type: 'string' },
+          items: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          count: { type: 'number' },
+          truncated: { type: 'boolean' },
+          packageName: { type: 'string' },
+          revision: { type: 'number' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `提取了 ${value.count || 0} 条（${value.mode || ''}）${value.truncated ? '，已截断' : ''}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const mode = ['text', 'list', 'form'].includes(args.mode) ? args.mode : 'text';
+      const maxItems = Number.isInteger(args.maxItems) ? Math.min(200, Math.max(1, args.maxItems)) : 100;
+      const data = await run(service, deviceId, sessionId, 'extract', { mode, maxItems }, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'extract')) notes.push(unsupportedNote('结构化提取（extract）'));
+      const value = {
+        ok: true,
+        mode,
+        items: Array.isArray(data && data.items) ? data.items : [],
+        count: Number.isFinite(data && data.count) ? data.count : (Array.isArray(data && data.items) ? data.items.length : 0),
+        truncated: Boolean(data && data.truncated),
+      };
+      if (data && typeof data.packageName === 'string' && data.packageName) value.packageName = textOf(data.packageName, MAX_TEXT);
+      if (data && Number.isFinite(data.revision)) value.revision = data.revision;
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_query',
+    description: 'Find controls on the current screen by text, resource id, or role without scrolling, returning ref, bounds, parents and whether each is clickable/editable. Use it when the same text appears many places or a control has no visible label. limit up to 100 (default 30).',
+    parameters: {
+      text: { type: 'string', description: 'Case-insensitive text or accessibility description to find.' },
+      resourceId: { type: 'string', description: 'Full or partial Android resource id to find.' },
+      role: { type: 'string', description: 'Full or partial role/class to find.' },
+      limit: { type: 'integer', description: 'Maximum results, 1-100 (default 30).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          total: { type: 'number' },
+          truncated: { type: 'boolean' },
+          matches: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          packageName: { type: 'string' },
+          revision: { type: 'number' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `找到 ${value.total || 0} 个匹配（返回 ${Array.isArray(value.matches) ? value.matches.length : 0} 条）。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const queryArgs = {};
+      if (typeof args.text === 'string' && args.text.trim()) queryArgs.text = textOf(args.text, 200);
+      if (typeof args.resourceId === 'string' && args.resourceId.trim()) queryArgs.resourceId = textOf(args.resourceId, 200);
+      if (typeof args.role === 'string' && args.role.trim()) queryArgs.role = textOf(args.role, 100);
+      if (!queryArgs.text && !queryArgs.resourceId && !queryArgs.role) {
+        throw new Error('要查什么？给 text / resourceId / role 其中至少一个。');
+      }
+      queryArgs.limit = Number.isInteger(args.limit) ? Math.min(100, Math.max(1, args.limit)) : 30;
+      const data = await run(service, deviceId, sessionId, 'query', queryArgs, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'query')) notes.push(unsupportedNote('按字段查询（query）'));
+      const value = {
+        ok: true,
+        total: Number.isFinite(data && data.total) ? data.total : 0,
+        truncated: Boolean(data && data.truncated),
+        matches: Array.isArray(data && data.matches) ? data.matches : [],
+      };
+      if (data && typeof data.packageName === 'string' && data.packageName) value.packageName = textOf(data.packageName, MAX_TEXT);
+      if (data && Number.isFinite(data.revision)) value.revision = data.revision;
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_find',
+    description: 'Scroll on the phone until an element matching text/resourceId/role is visible, then return its ref. It reads, matches, swipes and waits for the screen to settle in a loop on the phone. Stopped reason is one of found / screen_needs_review / app_switched / content_unchanged / scroll_limit / read_failed. maxScrolls 1-200 (default 30).',
+    parameters: {
+      text: { type: 'string', description: 'Text or accessibility description to find.' },
+      resourceId: { type: 'string', description: 'Full or partial Android resource id.' },
+      role: { type: 'string', description: 'Full or partial role/class.' },
+      direction: { type: 'string', enum: ['up', 'down'], description: 'Where the target is: down means scroll down to see lower content (default down).' },
+      maxScrolls: { type: 'integer', description: 'Maximum scrolls, 1-200 (default 30).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          found: { type: 'boolean' },
+          stoppedBecause: { type: 'string' },
+          scrolls: { type: 'number' },
+          match: { type: 'object', additionalProperties: true },
+          packageName: { type: 'string' },
+          revision: { type: 'number' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.found ? '找到了。' : `没找到（${value.stoppedBecause || '未知'}，滚了 ${value.scrolls || 0} 次）。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const findArgs = { direction: args.direction === 'up' ? 'up' : 'down' };
+      if (typeof args.text === 'string' && args.text.trim()) findArgs.text = textOf(args.text, 200);
+      if (typeof args.resourceId === 'string' && args.resourceId.trim()) findArgs.resourceId = textOf(args.resourceId, 200);
+      if (typeof args.role === 'string' && args.role.trim()) findArgs.role = textOf(args.role, 100);
+      if (!findArgs.text && !findArgs.resourceId && !findArgs.role) throw new Error('要找什么？给 text / resourceId / role 其中至少一个。');
+      findArgs.maxScrolls = Number.isInteger(args.maxScrolls) ? Math.min(200, Math.max(1, args.maxScrolls)) : 30;
+      const data = await run(service, deviceId, sessionId, 'find', findArgs, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'find')) notes.push(unsupportedNote('滚动查找（find）'));
+      const value = {
+        ok: Boolean(data && data.found),
+        found: Boolean(data && data.found),
+        stoppedBecause: textOf(data && data.stoppedBecause, 40) || 'scroll_limit',
+        scrolls: Number.isFinite(data && data.scrolls) ? data.scrolls : 0,
+      };
+      if (data && data.match && typeof data.match === 'object') value.match = data.match;
+      if (data && typeof data.packageName === 'string' && data.packageName) value.packageName = textOf(data.packageName, MAX_TEXT);
+      if (data && Number.isFinite(data.revision)) value.revision = data.revision;
+      if (!value.found) notes.push(`滚了 ${value.scrolls} 次也没找到（${value.stoppedBecause}），如实说没找到，别猜它在哪。`);
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_collect',
+    description: 'Scroll 1-30 screens and merge the text across them with de-duplication on the phone, returning one merged list. Use it to read a long list or chat without one round-trip per screen. Has both a maxItems and a 50KB byte cap.',
+    parameters: {
+      direction: { type: 'string', enum: ['up', 'down'], description: 'Direction of newer content: up or down (default down).' },
+      pages: { type: 'integer', description: 'Maximum screens to inspect, 1-30 (default 10).' },
+      maxItems: { type: 'integer', description: 'Maximum lines to return, 1-1000 (default 300).' },
+      fromY: { type: 'integer', description: 'Top of the content area, normalized 0-999 (default 50).' },
+      toY: { type: 'integer', description: 'Bottom of the content area, normalized 0-999 (default 950).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          pagesInspected: { type: 'number' },
+          scrolls: { type: 'number' },
+          stoppedBecause: { type: 'string' },
+          count: { type: 'number' },
+          items: { type: 'array', items: { type: 'string' } },
+          text: { type: 'string' },
+          truncated: { type: 'boolean' },
+          currentApp: { type: 'string' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `采集了 ${value.pagesInspected || 0} 屏，合并 ${value.count || 0} 行（${value.stoppedBecause || ''}）${value.truncated ? '，已截断' : ''}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const collectArgs = {
+        direction: args.direction === 'up' ? 'up' : 'down',
+        pages: Number.isInteger(args.pages) ? Math.min(30, Math.max(1, args.pages)) : 10,
+        maxItems: Number.isInteger(args.maxItems) ? Math.min(1000, Math.max(1, args.maxItems)) : 300,
+        fromY: Number.isInteger(args.fromY) ? Math.min(999, Math.max(0, args.fromY)) : 50,
+        toY: Number.isInteger(args.toY) ? Math.min(999, Math.max(0, args.toY)) : 950,
+      };
+      const data = await run(service, deviceId, sessionId, 'collect', collectArgs, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'collect')) notes.push(unsupportedNote('多屏采集（collect）'));
+      const items = Array.isArray(data && data.items) ? data.items.map((x) => String(x)) : [];
+      const value = {
+        ok: Boolean(data && data.ok !== false),
+        pagesInspected: Number.isFinite(data && data.pagesInspected) ? data.pagesInspected : 0,
+        scrolls: Number.isFinite(data && data.scrolls) ? data.scrolls : 0,
+        stoppedBecause: textOf(data && data.stoppedBecause, 40) || 'page_limit',
+        count: Number.isFinite(data && data.count) ? data.count : items.length,
+        items,
+        text: textOf(data && data.text, 50_000) || items.join('\n'),
+        truncated: Boolean(data && data.truncated),
+      };
+      if (data && typeof data.currentApp === 'string' && data.currentApp) value.currentApp = textOf(data.currentApp, MAX_TEXT);
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_wheel',
+    description: 'Turn a wheel picker (time / date / region) straight to a value in one call. The phone reads the column, scrolls or drags, and reads back to verify. Give ref (from phone_screen) and value. Error codes: not_a_wheel, wheel_at_end, wheel_unreadable, wheel_not_moving.',
+    parameters: {
+      ref: { type: 'string', required: true, description: 'Element ref of the wheel column (from phone_screen).' },
+      value: { type: 'string', required: true, description: 'The value to reach, e.g. "14", "30", "November".' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          reached: { type: 'boolean' },
+          target: { type: 'string' },
+          value: { type: 'string' },
+          from: { type: 'string' },
+          attempts: { type: 'number' },
+          method: { type: 'string' },
+          error: { type: 'object', additionalProperties: true },
+          effect: { type: 'string' },
+          packageName: { type: 'string' },
+          elements: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.reached ? `已转到 ${value.value || value.target}。` : `没转到位：${value.error ? value.error.code : '未知'}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const ref = textOf(args.ref, 40);
+      const target = textOf(args.value, 100);
+      if (!ref) throw new Error('给滚轮那一列的 ref（phone_screen 里的编号）。');
+      if (!target) throw new Error('要转到哪个值？给 value。');
+      const data = await run(service, deviceId, sessionId, 'wheel.set', { ref, value: target }, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'wheel.set')) notes.push(unsupportedNote('滚轮选择器（wheel.set）'));
+      const value = {
+        ok: Boolean(data && data.reached),
+        reached: Boolean(data && data.reached),
+        target,
+        attempts: Number.isFinite(data && data.attempts) ? data.attempts : 0,
+        method: textOf(data && data.method, 20) || 'none',
+      };
+      if (data && typeof data.value === 'string') value.value = data.value;
+      if (data && typeof data.from === 'string') value.from = data.from;
+      if (data && data.error && typeof data.error === 'object') value.error = data.error;
+      if (data && typeof data.effect === 'string') value.effect = data.effect;
+      if (data && typeof data.packageName === 'string' && data.packageName) value.packageName = textOf(data.packageName, MAX_TEXT);
+      if (data && Array.isArray(data.elements)) value.elements = data.elements.slice(0, 120);
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  // ── 分享文字 / 系统动作 / App 去留 ────────────────────────────────────────
+
+  register({
+    name: 'phone_share_text',
+    description: 'Share a piece of text to an app via ACTION_SEND (text/plain), landing on that app\'s share page. Parameters are only the package and the text.',
+    parameters: {
+      packageName: { type: 'string', required: true, description: 'Android package name of the app to share into.' },
+      text: { type: 'string', required: true, description: 'The text to share.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          packageName: { type: 'string' },
+          handledBy: { type: 'string' },
+          effect: { type: 'string' },
+          elements: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `已把文字分享到 ${value.packageName || '那个 App'}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const pkg = textOf(args.packageName, 200);
+      if (!/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$/.test(pkg)) throw new Error('packageName 看起来不像安卓包名。');
+      const body = textOf(args.text, 20_000);
+      if (!body) throw new Error('要分享的文字是空的。');
+      const data = await run(service, deviceId, sessionId, 'share.text', { packageName: pkg, text: body }, exec.signal);
+      const notes = [mentionMismatch(sessionId, deviceId)];
+      if (!supports(service, deviceId, 'share.text')) notes.push(unsupportedNote('分享文字（share.text）'));
+      const value = {
+        ok: true,
+        packageName: pkg,
+        handledBy: textOf(data && data.share && data.share.handledBy, 200) || pkg,
+      };
+      if (data && typeof data.effect === 'string') value.effect = data.effect;
+      if (data && Array.isArray(data.elements)) value.elements = data.elements.slice(0, 120);
+      const note = notes.filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  const weekdayNames = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+  const systemNotes = (sessionId, deviceId, cap) => {
+    const notes = [mentionMismatch(sessionId, deviceId)];
+    if (!supports(service, deviceId, cap)) notes.push(unsupportedNote('这类系统动作'));
+    return notes;
+  };
+
+  register({
+    name: 'phone_set_alarm',
+    description: 'Set an alarm through the standard Android clock interface without touching its UI. If no clock app handles it, returns not-supported and you should fall back to operating the UI.',
+    parameters: {
+      hour: { type: 'integer', required: true, description: 'Hour of day, 0-23.' },
+      minute: { type: 'integer', required: true, description: 'Minute, 0-59.' },
+      label: { type: 'string', description: 'Optional label shown with the alarm.' },
+      days: { type: 'array', items: { type: 'string' }, description: 'Optional repeat days: MON..SUN. Omit for a one-time alarm.' },
+      vibrate: { type: 'boolean', description: 'Optional: vibrate when it rings.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          requested: { type: 'object', additionalProperties: true },
+          handledBy: { type: 'string' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `已把闹钟交给 ${value.handledBy || '时钟 App'}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      if (!Number.isInteger(args.hour) || args.hour < 0 || args.hour > 23) throw new Error('hour 要是 0-23 的整数。');
+      if (!Number.isInteger(args.minute) || args.minute < 0 || args.minute > 59) throw new Error('minute 要是 0-59 的整数。');
+      const payload = { hour: args.hour, minute: args.minute };
+      if (typeof args.label === 'string' && args.label.trim()) payload.label = textOf(args.label, 100);
+      if (Array.isArray(args.days) && args.days.length > 0) {
+        const days = args.days.map((d) => {
+          const idx = weekdayNames.indexOf(String(d).trim().toUpperCase().slice(0, 3));
+          if (idx < 0) throw new Error(`days 里只能是 ${weekdayNames.join(' / ')}。`);
+          return idx + 1;
+        });
+        payload.days = [...new Set(days)].sort((a, b) => a - b);
+      }
+      if (args.vibrate === true) payload.vibrate = true;
+      const data = await run(service, deviceId, sessionId, 'system.alarm', payload, exec.signal);
+      const value = { ok: true, requested: { time: `${String(args.hour).padStart(2, '0')}:${String(args.minute).padStart(2, '0')}` } };
+      if (payload.label) value.requested.label = payload.label;
+      const handledBy = textOf(data && data.system && data.system.handledBy, 200);
+      if (handledBy) value.handledBy = handledBy;
+      const note = systemNotes(sessionId, deviceId, 'system.alarm').filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_set_timer',
+    description: 'Start a timer through the standard Android clock interface without touching its UI. If no clock app handles it, returns not-supported and you should fall back to operating the UI.',
+    parameters: {
+      seconds: { type: 'integer', required: true, description: 'Length of the timer in seconds, 1-86400.' },
+      label: { type: 'string', description: 'Optional label shown with the timer.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          requested: { type: 'object', additionalProperties: true },
+          handledBy: { type: 'string' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `已把计时器交给 ${value.handledBy || '时钟 App'}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      if (!Number.isInteger(args.seconds) || args.seconds < 1 || args.seconds > 86400) throw new Error('seconds 要是 1-86400 的整数。');
+      const payload = { seconds: args.seconds };
+      if (typeof args.label === 'string' && args.label.trim()) payload.label = textOf(args.label, 100);
+      const data = await run(service, deviceId, sessionId, 'system.timer', payload, exec.signal);
+      const value = { ok: true, requested: { seconds: args.seconds } };
+      if (payload.label) value.requested.label = payload.label;
+      const handledBy = textOf(data && data.system && data.system.handledBy, 200);
+      if (handledBy) value.handledBy = handledBy;
+      const note = systemNotes(sessionId, deviceId, 'system.timer').filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_show_alarms',
+    description: 'Open the clock app\'s alarm list on the phone so alarms can be inspected or edited there. If no clock app handles it, returns not-supported.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          handledBy: { type: 'string' },
+          effect: { type: 'string' },
+          elements: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `已打开闹钟列表（${value.handledBy || '时钟 App'}）。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const data = await run(service, deviceId, sessionId, 'system.show_alarms', {}, exec.signal);
+      const value = { ok: true };
+      const handledBy = textOf(data && data.system && data.system.handledBy, 200);
+      if (handledBy) value.handledBy = handledBy;
+      if (data && typeof data.effect === 'string') value.effect = data.effect;
+      if (data && Array.isArray(data.elements)) value.elements = data.elements.slice(0, 120);
+      const note = systemNotes(sessionId, deviceId, 'system.show_alarms').filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_add_calendar_event',
+    description: 'Open a pre-filled new-event page in the calendar app (nothing is saved until you tap save there). Standard Android Intent, no calendar permission needed. If no calendar app handles it, returns not-supported.',
+    parameters: {
+      title: { type: 'string', required: true, description: 'Event title.' },
+      start: { type: 'string', required: true, description: 'Start as local date-time yyyy-MM-ddTHH:mm, or a date yyyy-MM-dd with allDay=true.' },
+      end: { type: 'string', description: 'Optional end, same format as start. Defaults to one hour after start (one day for all-day).' },
+      allDay: { type: 'boolean', description: 'All-day event (default false).' },
+      location: { type: 'string', description: 'Optional location.' },
+      description: { type: 'string', description: 'Optional notes.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          requested: { type: 'object', additionalProperties: true },
+          handledBy: { type: 'string' },
+          effect: { type: 'string' },
+          elements: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `已打开新日程页（${value.handledBy || '日历 App'}），还没保存。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const title = textOf(args.title, 200);
+      if (!title) throw new Error('日程要有 title。');
+      const allDay = args.allDay === true;
+      const parseLocal = (raw) => {
+        let s = String(raw || '').trim();
+        if (!s) return null;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(s)) s += allDay ? 'T00:00' : 'T09:00';
+        const ms = Date.parse(s);
+        return Number.isFinite(ms) ? ms : null;
+      };
+      const beginMs = parseLocal(args.start);
+      if (beginMs === null) throw new Error('start 要是 yyyy-MM-ddTHH:mm 或 yyyy-MM-dd。');
+      let endMs = parseLocal(args.end);
+      if (endMs === null || endMs <= beginMs) endMs = beginMs + (allDay ? 24 * 3_600_000 : 3_600_000);
+      const payload = { title, beginMs, endMs, allDay };
+      if (typeof args.location === 'string' && args.location.trim()) payload.location = textOf(args.location, 200);
+      if (typeof args.description === 'string' && args.description.trim()) payload.description = textOf(args.description, 2000);
+      const data = await run(service, deviceId, sessionId, 'system.calendar_insert', payload, exec.signal);
+      const value = { ok: true, requested: { title, start: new Date(beginMs).toISOString().slice(0, 16).replace('T', ' ') } };
+      if (allDay) value.requested.allDay = true;
+      const handledBy = textOf(data && data.system && data.system.handledBy, 200);
+      if (handledBy) value.handledBy = handledBy;
+      if (data && typeof data.effect === 'string') value.effect = data.effect;
+      if (data && Array.isArray(data.elements)) value.elements = data.elements.slice(0, 120);
+      const note = systemNotes(sessionId, deviceId, 'system.calendar_insert').filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
+  register({
+    name: 'phone_app_after_task',
+    description: 'Decide whether an app should be left running or closed when the task ends, with a reason. It only records the mark; nothing is touched now. Default (when unmarked) is to keep a quiet app in the background and close one that is playing sound.',
+    parameters: {
+      packageName: { type: 'string', required: true, description: 'Exact package name of the app.' },
+      action: { type: 'string', required: true, enum: ['keep', 'close'], description: 'keep: leave it running after the task (even if playing sound). close: close it when the task ends.' },
+      reason: { type: 'string', required: true, description: 'Why, in a few words.' },
+      user: { type: 'integer', description: 'Only for another copy of the app (clone / work profile): that copy\'s user value. Leave out for the main app.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          packageName: { type: 'string' },
+          action: { type: 'string' },
+          replaces: { type: 'string' },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `${value.packageName || '这个 App'} 任务后${value.action === 'close' ? '关掉' : '留着'}。` }],
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const pkg = textOf(args.packageName, 200);
+      if (!/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$/.test(pkg)) throw new Error('packageName 看起来不像安卓包名。');
+      if (args.action !== 'keep' && args.action !== 'close') throw new Error('action 只能是 keep / close。');
+      const reason = textOf(args.reason, 200);
+      if (!reason) throw new Error('给一句原因（reason）。');
+      const payload = { packageName: pkg, action: args.action, reason };
+      if (Number.isInteger(args.user)) payload.user = args.user;
+      const data = await run(service, deviceId, sessionId, 'app.after_task', payload, exec.signal);
+      const value = { ok: true, packageName: pkg, action: args.action };
+      if (data && typeof data.replaces === 'string') value.replaces = data.replaces;
+      const note = [mentionMismatch(sessionId, deviceId), '只记下了，任务结束时才按它处置，不会当场关掉。'].filter(Boolean).join(' ');
+      if (note) value.note = note;
+      return value;
+    },
+  });
+
   register({
     name: 'phone_target',
     description: 'Show or change which phone this conversation operates. Without arguments it reports the binding and the phones currently connected. With a deviceId it rebinds — only do that when the user asked to switch phones.',