dsh-mobile-plugin 0.5.18 → 0.5.20

package/lib/mobile/magpie-web.js

@@ -0,0 +1,425 @@
+'use strict';
+
+/**
+ * magpie 网页版：把这台电脑上 magpie 自带的那个网页界面端给手机，需要时替它起来。
+ *
+ * **为什么走网页版而不是自己画一页**：magpie 的网页版就是它自己的界面（Agents / Providers /
+ * Routing / Usage / Settings 全在里面），而且它本来就是给手机做的 —— 页面源码里写着
+ * 「加到手机主屏后，作为独立 App 打开」，还有 manifest 与 apple-touch-icon。照着它的
+ * `/api/state` 再画一套，等于把人家已经做好的东西重做一遍，而且每加一个设置项我们就得跟一次。
+ * 所以手机那边直接嵌这个页面：一份实现、永远跟 magpie 同步。
+ *
+ * **为什么要在这里起进程**：网关那个端口（3425）只答 API，不端页面 —— 页面是 `magpie web`
+ * 这个独立进程端出来的，默认 `127.0.0.1:3430`，而且它起来之后要**换一个 key**（每次运行
+ * 随机，除非设了 `MAGPIE_WEB_KEY`）。用户点开那一页时网页版没在跑，这里就替他把进程拉起来，
+ * 拿到地址与 key 再交出去；已经跑着就直接用现成的。
+ *
+ * **key 是凭据**：它只出现在这一条端点与那一次 URL 里，不进日志、不回给别的端点。设了
+ * `MAGPIE_WEB_KEY` 就用它（每次运行同一个，手机那边刷新不用重新要地址）；没有就给这个进程
+ * 临时定一个，随进程走。
+ */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+
+const { sendJson } = require('../shared/http-util');
+
+/** 网页版默认端口（magpie 自己的缺省）。 */
+const DEFAULT_WEB_PORT = 3430;
+/** 起来之后最多等这么久让它把页面端出来。冷启动实测 3~6 秒（要读各家配置与订阅）。 */
+const START_TIMEOUT_MS = 25000;
+/** 探测间隔。 */
+const POLL_MS = 250;
+/** 上面等不到时的退避：同一个端口短时间内不反复起进程。 */
+const START_COOLDOWN_MS = 5000;
+
+/** key 只要够长、能进查询串；magpie 自己要求 16 位以上字母数字与 `-._~`。 */
+const KEY_RE = /^[A-Za-z0-9._~-]{16,}$/;
+
+/** 正在起来的那个：同一时刻只许一个（连点两下不该起两个进程）。 */
+let starting = null;
+/**
+ * 我们自己起的那个进程用的 key（端口 → key）。
+ *
+ * **必须记住**：没设 `MAGPIE_WEB_KEY` 时 key 是这里现造的，而那一次运行之内它一直有效 ——
+ * 第二次点开时进程已经在跑，如果不记得当初用了哪把，就只能回「拿不到凭据」，用户看到的是
+ * 「第一次能开、第二次打不开」。进程随插件重载消失，这份记录跟着进程走，所以重启后重新起
+ * 一个新进程、配一把新 key，也是一致的。
+ */
+const startedKeys = new Map();
+/**
+ * 上次起失败的时刻与原因（按端口记）：失败之后短时间内不再对**同一个端口**反复试。
+ *
+ * 按端口而不是全局：一个端口被别的东西占着起不来，不该把另一个能用的端口也一起封住。
+ */
+const failures = new Map();
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** magpie 的配置目录（与 `magpie.js` 同一口径）。 */
+function configDir(env = process.env) {
+  const xdg = text(env.XDG_CONFIG_HOME);
+  const base = xdg || path.join(os.homedir(), '.config');
+  return path.join(base, 'magpie');
+}
+
+/**
+ * 网页版该占哪个端口。
+ *
+ * magpie 自己的默认是 3430；`settings.json` 里没有单独的「网页版端口」这一项（那是命令行
+ * 参数），所以这里只认 `$MAGPIE_WEB_PORT` 与默认值。端口被别的东西占着时往上找几个。
+ */
+function preferredPort(env = process.env) {
+  const raw = Number(text(env.MAGPIE_WEB_PORT));
+  return Number.isInteger(raw) && raw > 0 && raw < 65536 ? raw : DEFAULT_WEB_PORT;
+}
+
+/**
+ * 这个端口上是不是已经有一个 magpie 网页版在答。
+ *
+ * 判据是它回 303/302（`/?k=` 换 cookie 那一跳）或 401（认得出是它、只是没带 key）——
+ * 别的程序占着这个端口时不会这么答。不带 key 请求，所以这条探测不会泄漏任何东西。
+ */
+function probeWeb(port, timeoutMs = 1200) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch { /* 已经断了 */ }
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs, () => finish(false));
+    socket.on('error', () => finish(false));
+    socket.on('connect', () => {
+      socket.write(
+        'GET / HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n'
+        + 'User-Agent: dsh-mobile-plugin\r\n\r\n',
+      );
+    });
+    let raw = '';
+    socket.on('data', (chunk) => {
+      raw += chunk.toString('latin1');
+      if (raw.length > 2048) raw = raw.slice(0, 2048);
+      const status = raw.match(/^HTTP\/1\.[01] (\d{3})/);
+      if (!status) return;
+      const code = Number(status[1]);
+      // 303/302 = 有 key 就换 cookie 的那一跳；401 = 是它、但这次没给 key。
+      finish(code === 303 || code === 302 || code === 401);
+    });
+    socket.on('close', () => finish(false));
+  });
+}
+
+/** 端口空着没有（起进程前先看一眼，别去撞一个不认识的程序）。 */
+function portFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    let done = false;
+    const finish = (free) => {
+      if (done) return;
+      done = true;
+      try { server.close(); } catch { /* 没起来 */ }
+      resolve(free);
+    };
+    server.once('error', () => finish(false));
+    server.listen(port, '127.0.0.1', () => finish(true));
+    server.unref();
+  });
+}
+
+/** 找一个能用的端口：优先默认，被占了就往上找几个。 */
+async function pickPort(env = process.env) {
+  const base = preferredPort(env);
+  for (let offset = 0; offset < 10; offset += 1) {
+    const port = base + offset;
+    if (await probeWeb(port, 600)) return { port, running: true };
+    if (await portFree(port)) return { port, running: false };
+  }
+  return null;
+}
+
+/**
+ * 找 magpie 可执行文件。
+ *
+ * magpie 三个桌面系统都有（菜单栏 / 窗口 / TUI / 网页 / CLI 是同一个程序的不同入口），
+ * 装法也各不相同，所以按「先 PATH、再各系统的常规落点」找，别只认 macOS 那一个 .app 包：
+ *   - PATH：`install.sh` 与 `go install` 都往某个 bin 目录里放一个 `magpie`（Windows 是
+ *     `magpie.exe`），只要那个目录在 PATH 上就能直接命中。
+ *   - macOS：官方 .app 包里的可执行文件，外加 Homebrew 的两个前缀。
+ *   - Windows：安装器放在 `%LOCALAPPDATA%\Programs\magpie`、`%ProgramFiles%\magpie`；
+ *     `go install` 落在 `%USERPROFILE%\go\bin`。
+ *   - Linux：`~/.local/bin`、`/usr/local/bin`、`/usr/bin`、`/opt/magpie`，以及 `go install`
+ *     的 `~/go/bin`。
+ *
+ * `MAGPIE_BIN` 给了就只认它：用户明确指了一条路径，指错时如实回「找不到」，而不是悄悄去
+ * PATH 里找另一个 —— 那样排查起来是「我明明改了变量，它却还在跑旧的那个」。
+ */
+function findBinary(env = process.env) {
+  const explicit = text(env.MAGPIE_BIN);
+  if (explicit) return isExecutable(explicit) ? explicit : null;
+  const home = os.homedir();
+  const names = process.platform === 'win32' ? ['magpie.exe', 'magpie'] : ['magpie'];
+  const candidates = [];
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const name of names) candidates.push(path.join(dir, name));
+  }
+  if (process.platform === 'darwin') {
+    candidates.push('/Applications/Magpie.app/Contents/MacOS/magpie');
+    candidates.push(path.join(home, 'Applications', 'Magpie.app', 'Contents', 'MacOS', 'magpie'));
+    candidates.push('/opt/homebrew/bin/magpie');
+    candidates.push('/usr/local/bin/magpie');
+  } else if (process.platform === 'win32') {
+    const local = text(env.LOCALAPPDATA);
+    if (local) candidates.push(path.join(local, 'Programs', 'magpie', 'magpie.exe'));
+    for (const key of ['ProgramFiles', 'ProgramW6432', 'ProgramFiles(x86)']) {
+      const base = text(env[key]);
+      if (base) candidates.push(path.join(base, 'magpie', 'magpie.exe'));
+    }
+    candidates.push(path.join(home, 'go', 'bin', 'magpie.exe'));
+  } else {
+    candidates.push(path.join(home, '.local', 'bin', 'magpie'));
+    candidates.push('/usr/local/bin/magpie');
+    candidates.push('/usr/bin/magpie');
+    candidates.push('/opt/magpie/magpie');
+    candidates.push(path.join(home, 'go', 'bin', 'magpie'));
+  }
+  for (const file of candidates) {
+    if (isExecutable(file)) return file;
+  }
+  return null;
+}
+
+/** 这个路径上是不是一个能执行的文件。 */
+function isExecutable(file) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) return false;
+    if (process.platform !== 'win32') fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 网页版这次用的 key。
+ *
+ * 干净的「只按环境变量或现造」判定（纯函数，方便单测）。`ensureWeb` 实际用的是
+ * `resolveKey`：多一层「上次留下的那份」。
+ */
+function webKey(env = process.env) {
+  const given = text(env.MAGPIE_WEB_KEY);
+  if (KEY_RE.test(given)) return given;
+  // 32 位十六进制，够长且只含字母数字。
+  return require('node:crypto').randomBytes(16).toString('hex');
+}
+
+/** 本地存 key 的文件：默认 `~/.dsh/magpie-web-key`，`MAGPIE_WEB_KEY_FILE` 可改（测试用）。 */
+function keyFilePath(env = process.env) {
+  const override = text(env.MAGPIE_WEB_KEY_FILE);
+  if (override) return override;
+  return path.join(os.homedir(), '.dsh', 'magpie-web-key');
+}
+
+/** 读上次留下的 key；没有/不合规就回空串。 */
+function readStoredKey(env = process.env) {
+  try {
+    const value = fs.readFileSync(keyFilePath(env), 'utf8').trim();
+    return KEY_RE.test(value) ? value : '';
+  } catch {
+    return '';
+  }
+}
+
+/** 留一份 key 给下次用（0600，只有当前用户能读）。写不进去就算了，退回「本次进程记住」，不阻断打开。 */
+function writeStoredKey(env, key) {
+  try {
+    const file = keyFilePath(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, key, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+  } catch { /* 落盘失败不致命：startedKeys 在本次进程内仍然记得 */ }
+}
+
+/**
+ * 这次网页版用的 key，按优先级：用户设的 `MAGPIE_WEB_KEY` → 上次留下那份 → 现造并存下。
+ *
+ * **为什么要「上次留下那份」**：插件热重载 / 宿主重启后，内存里那份 `startedKeys` 就没了，
+ * 而网页版进程是 detached 的、还活着。若这时现造一把新 key，就跟那个已经在跑的进程对不上，
+ * 只能回「拿不到登录凭据」——用户被要求自己去设环境变量，这不是我们要的。留一份稳定的 key，
+ * 同一个进程永远对得上，用户什么都不用配（与 magpie 自己把 key 放进 service file 一个路数）。
+ */
+function resolveKey(env = process.env) {
+  const given = text(env.MAGPIE_WEB_KEY);
+  if (KEY_RE.test(given)) return given;
+  const stored = readStoredKey(env);
+  if (stored) return stored;
+  const key = webKey(env);
+  writeStoredKey(env, key);
+  return key;
+}
+
+/**
+ * 带 key 请求一下，看这个端口上跑着的 magpie 认不认这把 key。
+ *
+ * 认（登录那一跳 3xx）就说明正是我们自己起的那一个；401 / 别的都算不认。用来在起进程之前
+ * 先「认领」一个还活着的旧进程，而不是又起一个新的。
+ */
+function probeKey(port, key, timeoutMs = 1200) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try { req.destroy(); } catch { /* 已经断了 */ }
+      resolve(ok);
+    };
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: `/?k=${encodeURIComponent(key)}`,
+      method: 'GET',
+      timeout: timeoutMs,
+    }, (res) => {
+      const code = res.statusCode;
+      res.resume();
+      // 302/303 是换 cookie 的那一跳；3xx 都算「key 被接受」。
+      finish(typeof code === 'number' && code >= 300 && code < 400);
+    });
+    req.on('timeout', () => finish(false));
+    req.on('error', () => finish(false));
+    req.end();
+  });
+}
+
+/** 等网页版在这个端口上答起来。 */
+async function waitForWeb(port, deadline, probe = probeWeb) {
+  for (;;) {
+    if (await probe(port, 800)) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  }
+}
+
+/**
+ * 把这台电脑上的 magpie 网页版拿给手机。
+ *
+ * 三种结局：已经有一个我们对得上 key 的在跑（认领它）、没有就起一个新的、起不来（如实说为什么）。
+ * **失败不抛**：这是一次能力探测，抛出去只会变成一条看不出哪一格缺了的 500。
+ *
+ * 认领优先于新起：网页版进程是 detached 的，插件热重载 / 宿主重启之后它常常还活着，而内存里
+ * 的 `startedKeys` 已经没了 —— 这时用稳定 key 探一下就能把它认回来，不必再起第二个，也不必
+ * 让用户去设环境变量。
+ */
+async function ensureWeb({
+  env = process.env,
+  spawnImpl = spawn,
+  probe = probeWeb,
+  probeKeyFn = probeKey,
+  portFreeFn = portFree,
+  startTimeoutMs = START_TIMEOUT_MS,
+} = {}) {
+  const base = preferredPort(env);
+  const key = resolveKey(env);
+
+  // 一、先看有没有「认得出来是我们的」在跑：本进程记得的、或稳定 key 探得通的，都认领。
+  for (let offset = 0; offset < 10; offset += 1) {
+    const port = base + offset;
+    if (startedKeys.get(port) === key) {
+      return { available: true, port, key };
+    }
+    if (!(await probe(port, 500))) continue;
+    if (await probeKeyFn(port, key, 800)) {
+      startedKeys.set(port, key);
+      return { available: true, port, key };
+    }
+  }
+
+  // 正在起的那一个：搭它的车，别再起第二个。
+  if (starting) {
+    const shared = await starting;
+    return shared;
+  }
+
+  // 二、挑一个空端口起我们自己的。
+  let port = null;
+  for (let offset = 0; offset < 10; offset += 1) {
+    const candidate = base + offset;
+    if (await portFreeFn(candidate)) { port = candidate; break; }
+  }
+  if (port == null) return { available: false, reason: 'no-free-port' };
+
+  const lastFailure = failures.get(port);
+  if (lastFailure && Date.now() - lastFailure.at < START_COOLDOWN_MS) {
+    return { available: false, reason: lastFailure.reason, port };
+  }
+
+  const bin = findBinary(env);
+  if (!bin) return { available: false, reason: 'no-magpie' };
+
+  starting = (async () => {
+    let child;
+    try {
+      child = spawnImpl(bin, ['web', '--addr', `127.0.0.1:${port}`, '--no-open'], {
+        env: { ...env, MAGPIE_WEB_KEY: key },
+        // 脱离父进程：插件重载 / 宿主重启不该把它带走，用户下次点开还能直接连上。
+        // stdout/stderr 丢掉：那是 magpie 自己的日志，插件不替它收（收着不读会堵住管道）。
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+    } catch (error) {
+      failures.set(port, { at: Date.now(), reason: 'spawn-failed' });
+      return { available: false, reason: 'spawn-failed', port };
+    }
+    const ok = await waitForWeb(port, Date.now() + startTimeoutMs, probe);
+    if (!ok) {
+      failures.set(port, { at: Date.now(), reason: 'start-timeout' });
+      return { available: false, reason: 'start-timeout', port };
+    }
+    failures.delete(port);
+    startedKeys.set(port, key);
+    return { available: true, port, key };
+  })().finally(() => { starting = null; });
+  return starting;
+}
+
+/**
+ * GET /api/mobile/v1/magpie/web — 手机要打开 magpie 网页版时问这一条。
+ *
+ * 回 `{ ok: true, available, port, key, reason }`。**key 只在这里出现一次**，App 拿它拼
+ * `http://127.0.0.1:3430/?k=…` 交给预览管道 —— 之后那一跳 magpie 会换成 cookie，
+ * 地址栏里的 key 不会跟着页面里的链接到处跑。
+ */
+async function handleMagpieWeb(ctx, _req, res) {
+  try {
+    const entry = await ensureWeb({});
+    sendJson(res, 200, { ok: true, ...entry });
+  } catch {
+    sendJson(res, 200, { ok: true, available: false, reason: 'unexpected' });
+  }
+}
+
+module.exports = {
+  handleMagpieWeb,
+  ensureWeb,
+  probeWeb,
+  probeKey,
+  portFree,
+  pickPort,
+  findBinary,
+  webKey,
+  resolveKey,
+  readStoredKey,
+  keyFilePath,
+  preferredPort,
+};

package/lib/mobile/phone/tools.js

@@ -106,6 +106,22 @@ function installPhoneTools(ctx, deps) {
   const build = (scoped) => {
   const register = (tool) => scoped.tools.register(defineTool(tool));
 
+  /**
+   * 宿主的附件库：截图要交给它存，编号才是宿主认得的那种（见 `phone_screenshot` 的说明）。
+   *
+   * 取用放在执行时、不在注册时：`attachments` 是宿主后装的，注册这一趟它可能还不在。先问
+   * 注入作用域、再问外层 —— 与 `schedule.js` 同一个口径（那边也是执行时 `ctx.get`）。
+   */
+  const attachmentsOf = () => {
+    for (const source of [scoped, ctx]) {
+      if (!source || typeof source.get !== 'function') continue;
+      let store = null;
+      try { store = source.get('attachments'); } catch { store = null; }
+      if (store && typeof store.saveImage === 'function') return store;
+    }
+    return null;
+  };
+
   /**
    * 所有工具都要的那一步：从执行上下文里认出这条会话。
    *
@@ -182,6 +198,84 @@ function installPhoneTools(ctx, deps) {
     },
   });
 
+  /**
+   * 截一张后台屏的画面。
+   *
+   * **为什么要有它**：读屏拿到的是界面树（文字、控件、坐标），但视频、画布、游戏、部分网页
+   * 根本没有可读的节点 —— 那时候模型只能瞎猜。实测（2026-11-04）：让它去抖音里看内容，
+   * 它连标题都读不到，因为整屏都是自绘的画面。截图这条能力一直在手机侧（读屏读不到时兜底
+   * 用的就是它），只是没交到模型手上。
+   *
+   * 图必须存进**宿主**的附件库：工具结果里的图片引用会随会话历史再发给模型，而宿主只认自己
+   * 发的那种带 `sha256:` 前缀的编号。2026-11-04 真机：图存进了插件自己那份库里、编号是裸的
+   * 哈希，下一轮请求整条挂掉（「附件引用无效」）。插件那份库是给手机端发图用的，两边不是一回事。
+   */
+  register({
+    name: 'phone_screenshot',
+    description: 'Take a picture of the background screen the agent is working on. Use it when the accessibility tree cannot describe what is on screen: videos, canvas, games, image galleries. Returns the picture as an image.',
+    parameters: {
+      target: { type: 'string', description: 'What you are looking at, in a few words.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          deviceId: { type: 'string' },
+          width: { type: 'number' },
+          height: { type: 'number' },
+          note: { type: 'string' },
+          image: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => {
+        const blocks = [{ type: 'text', text: `后台屏截图（${value.width}×${value.height}）` }];
+        if (value.image) blocks.push(value.image);
+        return blocks;
+      },
+    },
+    execute: async (args, exec) => {
+      const sessionId = sessionOf(exec);
+      const { deviceId, service } = targetOf(ctx, deps, sessionId);
+      const data = await run(service, deviceId, sessionId, 'screen.screenshot', {}, exec.signal);
+      const blob = data && typeof data.blob === 'string' ? data.blob : '';
+      if (!blob) throw new Error('没截到画面：手机那边没有回图片。');
+      const store = attachmentsOf();
+      if (!store) throw new Error('宿主没有附件库，这张图存不进去。');
+      let ref;
+      try {
+        ref = await store.saveImage({
+          data: Buffer.from(blob, 'base64'),
+          mediaType: 'image/png',
+          name: textOf(args.target, MAX_TEXT) || 'phone-screen',
+        });
+      } catch (error) {
+        throw new Error(`截到的画面存不下来：${String((error && error.message) || error).slice(0, 200)}`);
+      }
+      // 有值才塞键：宿主不接受值为 undefined 的字段（见 A3-79 的坑）。
+      const value = {
+        deviceId,
+        width: Number(ref.width) || 0,
+        height: Number(ref.height) || 0,
+        note: mentionMismatch(sessionId, deviceId),
+        // 引用块按宿主自己那种形状写（`attachmentId` 带 `sha256:` 前缀、另有字节数与宽高），
+        // 这一块会被原样留在历史里，下一轮请求按它取图。
+        image: {
+          type: 'image',
+          attachment: {
+            attachmentId: ref.attachmentId,
+            mediaType: ref.mediaType,
+            bytes: ref.bytes,
+            width: ref.width,
+            height: ref.height,
+            ...(ref.name ? { name: ref.name } : {}),
+          },
+        },
+      };
+      return value;
+    },
+  });
+
   register({
     name: 'phone_tap',
     description: 'Tap an element on the phone screen by its ref (from phone_screen), or by viewport-relative percentage coordinates when no ref fits. One call taps once.',

package/lib/mobile/questions.js

@@ -255,14 +255,20 @@ function noAnswerer(error) {
  * 撤回那一发，卡会一直悬着直到人手动点。那一发被撤时 `downstream` 会再落一次；上面的
  * race 已经挂着它的处理函数，迟到的那次不会冒成未处理异常，`settle` 本身也是幂等的。
  *
- * `NO_PROVIDER`（桌面没开 / 桌面把请求 delegate 回来）不是结论：手机正在看这个会话时
- * 卡还在手机上等着，继续等手机答；没人看时照旧把失败交回去，纯桌面表现一字不改。
+ * `NO_PROVIDER`（桌面没开 / 桌面把请求 delegate 回来）**任何情况下都不是结论**，也跟
+ * 「手机此刻有没有在看这条会话」无关：手机这条路本来就是「人离开了再看」，通知与侧栏的
+ * 待处理标记就是把人带回来的那两根线。此前只在「有观众」时才据此继续等，于是手机停在
+ * 别的会话 / 在后台时，一条本来还能答的提问当场被判成没人能答，模型当作被跳过继续跑 ——
+ * 用户看到的就是「点通知进来，问题已经自己跳过了」。
+ *
+ * 收尾只有两条：手机作答（`entry.wait`），或者宿主的取消信号（停止这一轮 / 轮次被中止，
+ * 见 `bindRequest` 的 onAbort）。一直没人答也没有取消时，这条提问就停在原地等人回来。
  */
 function holdForPhone(entry, next) {
   const downstream = Promise.resolve().then(() => next()).then(
     (answer) => { settle(entry, null); return answer; },
     (error) => {
-      if (noAnswerer(error) && watcherCount(entry.sessionId) > 0) return new Promise(() => {});
+      if (noAnswerer(error)) return new Promise(() => {});
       settle(entry, null);
       throw error;
     },

package/lib/mobile/session-send.js

@@ -283,25 +283,25 @@ async function handleSessionAttachment(ctx, req, res) {
     || typeof body.attachmentId !== 'string' || !body.attachmentId) {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, attachmentId }' } });
   }
-  // 直读宿主附件库（2026-10-31）：登记过的 id 直接从本地盘流给手机，省掉「等宿主把整张
-  // 读成 base64 再返回」那一段（宿主主线程忙时手机会一个字节都收不到）。前提与回退见
-  // `attachment-store.js` 的 `streamIfRemembered`：不满足就往下走原来的宿主接口。
+  // 直读宿主附件库（2026-10-31）：登记过的 id 直接从本地盘流给手机，省掉「等宿主把整张读成
+  // base64 再返回」那段（宿主主线程忙时手机一个字节都收不到）。回退见 `streamIfRemembered`。
   if (body.raw === true && await attachmentStore.streamIfRemembered(req, res, body.sessionId, body.attachmentId)) return;
-  const { value, error } = unwrap(await callSessions(ctx, 'attachment', { sessionId: body.sessionId, attachmentId: body.attachmentId }));
+  // 要递一份**和盘上字节对得上**的引用：宿主会逐字段比对类型 / 字节数 / 宽高，占位值会被
+  // 挡回 `Stored attachment metadata does not match its reference.`。拼不出来（对象不在）回 404。
+  const ref = attachmentStore.refFor(body.sessionId, body.attachmentId);
+  if (!ref) return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '附件已不可读' } });
+  const { value, error } = unwrap(await callSessions(ctx, 'attachment', { sessionId: body.sessionId, attachment: ref }));
   if (error) return sendJson(res, 400, { ok: false, error });
   const data = value && typeof value.data === 'string' ? value.data : '';
-  // 附件已被会话清理掉时宿主回的是空字节：这不是「稍后再试就好」，如实回 404，
-  // 让 App 那边把重试按钮的失败说清楚，而不是转圈到超时。
+  // 宿主回空字节＝附件已被会话清理掉：如实回 404，别让 App 那边的重试按钮转圈到超时。
   if (!data) return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '附件已不可读' } });
   const attachment = (value && value.attachment) || {};
   const mediaType = typeof attachment.mediaType === 'string' && attachment.mediaType ? attachment.mediaType : 'image/png';
-  // `dims: true` = 只要原始宽高，不要字节。老会话里宿主没存附件的宽高，正文下发时就带不上，
-  // 手机侧只能按 240 方盒先占位、等字节到了再变高（那一行一变高，屏幕上就是「跳」）。这一档
-  // 让手机在挂载那一帧就能按真比例占好：回给它的只有两格数字，整张图的 base64 不出这台电脑。
-  // `raw: true` = 要原始字节，不要 base64（2026-10-30）。宿主给的仍是 base64，这里解成
-  // Buffer 后按分块信封流出去：手机那边落盘的是密文，靠原生解盘口边解边写，整张图的
-  // base64 不进 JS 堆 —— 一张两兆的截图在手机上原本要摊着两兆七的字符串加一份解析副本。
-  // **不封包不许走这一档**：那就成了明文传输，正好把这条路本来的意义抹掉，如实回 400。
+  // `dims: true` = 只要原始宽高，不要字节：老会话里宿主没存宽高，手机得先按兜底盒占位、等字节
+  // 到了再变高（那一行一跳，上面整截就被推走）。回给它的只有两格数字，base64 不出这台电脑。
+  // `raw: true` = 要原始字节（2026-10-30）：宿主给的仍是 base64，这里解成 Buffer 后按分块信封
+  // 流出去，手机那边靠原生解盘口边解边写，整张图的 base64 不进 JS 堆。
+  // **不封包不许走这一档**：那就成了明文传输，如实回 400。
   if (body.raw === true) {
     const opened = req && req.__dshE2ee;
     if (!opened || !opened.keys || !opened.req) {