dsh-mobile-plugin 0.5.17 → 0.5.19

package/lib/mobile/cli/usage.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * 一轮用掉多少 —— ACP 报上来的用量，翻成对话页底部那行指标认识的形状。
+ *
+ * 两个来源，都是协议里现成的，不去猜：
+ *
+ *   - `usage_update` 通知：`used` / `size` 是**上下文窗口**占了多少（两家都给，opencode 实测
+ *     每轮末尾发一条，`size` 20 万）；
+ *   - `session/prompt` 的回包：`usage` 里是**整条会话累计**的输入 / 输出 / 缓存读写 token
+ *     （`inputTokens` 明确写着「across all turns」）。
+ *
+ * 手机上那行指标要三项：token 速度、缓存命中率、上下文占用。对应关系——
+ *
+ *   - 上下文占用 = `used` / `size`；
+ *   - 缓存命中率 = cacheRead / (uncached + cacheRead + cacheWrite)，与宿主那条 `cacheHitPercent`
+ *     同一个公式（那一份在 App 里，插件这边照抄口径，不另立一套）；
+ *   - token 速度 = 这一轮的输出 token / 这一轮花的时间。
+ *
+ * 报不上来的就是**没有**，不补零：`usage_update` 一次都没来过（有的适配器不发）时不给
+ * `contextPressure`，指标行自然少一段，而不是显示「上下文 0%」。
+ */
+
+/** 每个会话一份，挂在 session 对象上（会话收掉时一起没）。 */
+function createUsage() {
+  return {
+    /** 上下文：最近一次 `usage_update`。 */
+    used: null,
+    size: null,
+    /** prompt 回包里的累计用量（最后一次见到的为准）。 */
+    prompt: null,
+    /** 上一轮 prompt 的累计快照：两个相减就是这一轮的量。 */
+    previous: null,
+    /** 累计轮数与耗时。 */
+    turns: 0,
+    llmMs: 0,
+    /** 上一轮的输出量与耗时（token 速度用它）。 */
+    decodeTokens: 0,
+    decodeMs: 0,
+  };
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/** `usage_update` 通知 → 上下文占用。 */
+function applyUsageUpdate(usage, update) {
+  const used = num(update && update.used);
+  const size = num(update && update.size);
+  if (used !== null) usage.used = used;
+  if (size !== null && size > 0) usage.size = size;
+  return used !== null || size !== null;
+}
+
+/**
+ * 一轮结束：记下这一轮的输出量与耗时，并把累计用量换成回包那一份。
+ *
+ * `elapsedMs` 是从发出 prompt 到它 resolve 的墙钟时间 —— ACP 不给逐轮的耗时，这是唯一
+ * 拿得到的口径，所以「token 速度」这一项是**整轮平均**，不是解码瞬时速度。够用：这一行
+ * 存在的意义是「快不快」，不是基准测试。
+ */
+function applyPromptUsage(usage, result, elapsedMs) {
+  const next = result && result.usage;
+  const elapsed = num(elapsedMs) || 0;
+  if (next && typeof next === 'object') {
+    const prev = usage.prompt;
+    const output = num(next.outputTokens);
+    const prevOutput = prev ? (num(prev.outputTokens) || 0) : 0;
+    usage.decodeTokens = output === null ? 0 : Math.max(0, output - prevOutput);
+    usage.prompt = {
+      inputTokens: num(next.inputTokens),
+      outputTokens: output,
+      totalTokens: num(next.totalTokens),
+      cachedReadTokens: num(next.cachedReadTokens),
+      cachedWriteTokens: num(next.cachedWriteTokens),
+      thoughtTokens: num(next.thoughtTokens),
+    };
+  }
+  if (elapsed > 0) {
+    usage.llmMs += elapsed;
+    // 没有累计用量时（适配器不回 `usage`）至少还能给一个耗时：单看它也说明这一轮多久。
+    usage.decodeMs = usage.decodeTokens > 0 ? elapsed : 0;
+  }
+  usage.turns += 1;
+  usage.previous = usage.prompt;
+}
+
+/** 缓存命中率（整数百分比）；没有输入计费量时 null（与 App 的 `cacheHitPercent` 同一个分支）。 */
+function cacheHitPercent(cacheRead, billed) {
+  return billed === 0 ? null : Math.round((cacheRead / billed) * 100);
+}
+
+/**
+ * 会话 → `/session/stats` 的投影。
+ *
+ * 只给**真有数的**那几项，其余不出现（App 那边缺席就是「没有」，不会画成 0）。
+ */
+function statsOf(usage) {
+  const out = {};
+  const prompt = usage.prompt;
+  if (prompt && prompt.inputTokens !== null) {
+    const cachedRead = prompt.cachedReadTokens || 0;
+    const cachedWrite = prompt.cachedWriteTokens || 0;
+    out.tokenUsage = {
+      // ACP 的 `inputTokens` 是**含缓存**的总输入，App 那边三个桶是分开的（`uncached` 是
+      // 真正新读的那部分），所以这里减掉两个缓存桶，别把缓存算成新读。
+      uncachedInputTokens: Math.max(0, prompt.inputTokens - cachedRead - cachedWrite),
+      outputTokens: prompt.outputTokens || 0,
+      cacheReadTokens: cachedRead,
+      cacheWriteTokens: cachedWrite,
+    };
+  }
+  if (usage.used !== null && usage.size !== null) {
+    out.contextPressure = { contextWindow: usage.size, pressureTokens: usage.used };
+  }
+  if (usage.turns > 0) {
+    out.sessionStats = {
+      turns: usage.turns,
+      // 这一版不认工具调用耗时与首字延迟：ACP 不给，编一个比空着更糟。
+      steps: 0,
+      llmMs: usage.llmMs,
+      toolMs: 0,
+      ttftMs: 0,
+      ttftSteps: 0,
+      decodeMs: usage.decodeMs,
+      decodeTokens: usage.decodeTokens,
+    };
+  }
+  return out;
+}
+
+module.exports = { createUsage, applyUsageUpdate, applyPromptUsage, statsOf, cacheHitPercent };

package/lib/mobile/monitor.js

@@ -106,7 +106,7 @@ function monitorItem(summary, state, fact) {
  * `{ error }` —— 两种都由调用方照 `/sessions` 的口径回，别在这里编一个空清单：空清单会被
  * 原生当成「所有会话都没了」，基线一清，下一轮就为所有正在跑的会话重新报一次完成。
  */
-async function buildMonitorState(ctx, deviceKey) {
+async function buildMonitorState(ctx, deviceKey, extraItems = null) {
   const { value, error } = unwrap(await callSessions(ctx, 'list', {}, 'mobile'));
   if (error) return { error };
   const summaries = Array.isArray(value) ? value : (value && Array.isArray(value.items) ? value.items : null);
@@ -174,6 +174,17 @@ async function buildMonitorState(ctx, deviceKey) {
       // 拿不到预览就整个字段不出，老 App 会忽略它。
     }
   }));
+  // CLI 会话（`cli-*`）的监控条目由适配层按同一套字段给（见 mobile/cli/mobile.js 的
+  // monitorItems）：它们是 ACP 子进程、不在宿主的会话清单里，但「在跑 / 刚完成 /
+  // 等你审批」这三件事对后台提醒是一回事。注入成一个取值器，这里不认识 CLI 的任何细节。
+  if (typeof extraItems === 'function') {
+    try {
+      const extra = extraItems();
+      if (Array.isArray(extra) && extra.length > 0) items.push(...extra);
+    } catch {
+      // 适配层取不出来的话就当没有 CLI 会话：后台提醒照旧为宿主会话工作。
+    }
+  }
   // 按 id 排序后再算指纹：宿主是按 updatedAt 排的，聊一句话顺序就换，指纹会跟着每轮都变，
   // 条件刷新等于白做。监控视图不关心顺序。
   items.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
@@ -215,10 +226,10 @@ function waitForChange(timeoutMs, res) {
 }
 
 /** 算一次监控视图，把「宿主出错 / 形状异常」也收成一个可下发的响应。 */
-async function buildMonitorView(ctx, deviceKey) {
+async function buildMonitorView(ctx, deviceKey, extraItems = null) {
   let built;
   try {
-    built = await buildMonitorState(ctx, deviceKey);
+    built = await buildMonitorState(ctx, deviceKey, extraItems);
   } catch (error) {
     return {
       status: 500,
@@ -247,7 +258,7 @@ async function buildMonitorView(ctx, deviceKey) {
  * 只挂一次：醒来之后不管变没变都如实回（变没变由 revision 说了算），由手机自己决定
  * 要不要再挂。这样这里没有循环、没有重试，断线也不会在宿主侧留下一个转不停的请求。
  */
-async function handleMonitor(ctx, req, res) {
+async function handleMonitor(ctx, req, res, extraItems = null) {
   const deviceKey = canonicalDeviceKey(req);
   const url = new URL(req.url, 'http://x');
   const rev = (url.searchParams.get('rev') || '').trim();
@@ -255,7 +266,7 @@ async function handleMonitor(ctx, req, res) {
   // 没有 rev 就不挂：那不是「确认一下有没有变」，而是「给我一份完整状态」，立刻回。
   const waitMs = rev ? Math.max(0, Math.min(WAIT_MAX_MS, Math.round(waitSeconds * 1000))) : 0;
 
-  const first = await buildMonitorView(ctx, deviceKey);
+  const first = await buildMonitorView(ctx, deviceKey, extraItems);
   if (first.status !== 200) {
     return sendJson(res, first.status, first.body);
   }
@@ -272,7 +283,7 @@ async function handleMonitor(ctx, req, res) {
   await waitForChange(waitMs, res);
   // 手机在这段时间里断了（切网 / 进程被杀）：别为一个没人收的响应再算一遍。
   if (res.destroyed || res.writableEnded) return;
-  const again = await buildMonitorView(ctx, deviceKey);
+  const again = await buildMonitorView(ctx, deviceKey, extraItems);
   const body = again.status === 200 ? (unchangedListBody(again.body, rev) || again.body) : again.body;
   // 头已经出去了，不能再走 sendJson（它会再写一次头）：这里只补正文。
   try { res.end(JSON.stringify(body)); } catch { /* 连接已断开 */ }

package/lib/mobile/narration.js

@@ -0,0 +1,205 @@
+'use strict';
+
+/**
+ * 过程播报：让模型在一轮跑久了之后，用一两句话说明它此刻在做什么、卡在哪里。
+ *
+ * 默认关。用户看到的现场是「问完之后 AI 闷头干到底，中途一句话都没有」——模型在工具循环里
+ * 本来没有任何开口的理由（中间没有新的用户消息），而进度条只是一行机器计数。开关打开后，
+ * 插件在模型动手之前往这一步的上下文里递一句提醒，它就会顺带讲一句。
+ *
+ * 递话走 `agent/pre-step` 的 waterfall（与开发地图那套「你卡住了」的补报同一条通道）：
+ * 追加一条 **非 user 来源**的 user 消息，模型下一步就带着它思考。来源不是 `user` 这一条
+ * 不能省：App 直播与历史推导都把非 user 来源当上下文注入丢掉，所以这句话本身不会冒充成
+ * 用户自己发的气泡 —— 用户看到的只有模型因此说出的那几句正文。
+ *
+ * 代价照实说：这些话是真进对话正文的，会留在这一轮的历史里、也花 token。所以缺省关、
+ * 每台电脑各存一份（`<DSH_HOME>/storages/mobile-plugin/process-narration.json`）。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const { dshHome } = require('../shared/paths');
+const { sendJson, readJsonBody } = require('../shared/http-util');
+
+/** 第一句的门槛：一轮至少跑这么久才值得开口（短任务说一句话是纯噪声）。 */
+const NARRATION_FIRST_MS = Number(process.env.DSH_MOBILE_NARRATION_FIRST_MS) || 90 * 1000;
+/** 之后每隔这么久最多再说一句。 */
+const NARRATION_INTERVAL_MS = Number(process.env.DSH_MOBILE_NARRATION_INTERVAL_MS) || 90 * 1000;
+/** 一轮最多说几句：再多就是把工具循环变成播报台。 */
+const NARRATION_MAX_PER_TURN = 3;
+/**
+ * 来源标记。**必须不是 `user`**：App 的 `userMessageOrigin` 与 `history-derive` 都按
+ * `source.kind !== 'user'` 把注入丢掉，改这两处的口径就等于让提醒变成用户气泡。
+ */
+const NARRATION_SOURCE_KIND = 'mobile-narration';
+/** 记「这一轮跑多久了」的表：会话数有限，封顶防慢泄漏。 */
+const TRACKED_SESSIONS = 64;
+
+function settingsFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'process-narration.json');
+}
+
+/**
+ * 读开关。读不到 / 读坏都当「关」—— 会往用户对话里塞消息、花 token 的事，缺省必须在关的
+ * 那一侧（与收件目录自动清理同一个口径，与自动更新的缺省相反）。
+ */
+function narrationEnabled() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(settingsFile(), 'utf8'));
+    return raw?.enabled === true;
+  } catch {
+    return false;
+  }
+}
+
+/** 写开关。写不进去就抛，让调用方如实回失败（回「开好了」却没落盘是最坏的一种）。 */
+function setNarration(enabled) {
+  const file = settingsFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ enabled: enabled === true }, null, 2)}\n`);
+  return narrationEnabled();
+}
+
+/** 造消息的工厂：宿主给的 `createUserMessage` 会品牌化 id 并 deepFreeze，取不到时退回等价对象。 */
+let createUserMessagePromise = null;
+function resolveCreateUserMessage() {
+  if (!createUserMessagePromise) {
+    createUserMessagePromise = import('@deepseek-ai/dsh-llm')
+      .then((llm) => llm?.createUserMessage ?? null)
+      .catch(() => null);
+  }
+  return createUserMessagePromise;
+}
+
+/**
+ * 那一句提醒的正文。
+ *
+ * 写法的三条规矩（与开发地图那套补报同一口径）：
+ *  1. **说清这不是用户说的话**：它长得像系统提示，不说明白模型会当成用户在催它；
+ *  2. **给动作，不给问题**：模型没有「我该不该汇报」这个自我认知，直接说「用一两句话说」；
+ *  3. **允许它说「没什么可说的」**：没有卡点还要硬编一句，读起来比不说更糟。
+ */
+function narrationText() {
+  return [
+    '<system-reminder>',
+    '这是一条进度提醒，**不是用户说的话**。',
+    '请在这一轮继续之前，先用一两句自然的话（就是正常对用户说话的口气，不要写成报告或条目）说清：现在做到哪一步、有没有卡住或绕路。',
+    '没有什么值得说的就继续干活，不用勉强编一句。',
+    '说的时候不要提这条提醒本身。',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+async function buildHint() {
+  const input = {
+    content: [{ type: 'text', text: narrationText() }],
+    source: { kind: NARRATION_SOURCE_KIND },
+  };
+  const create = await resolveCreateUserMessage();
+  if (create) return create(input);
+  return Object.freeze({ ...input, role: 'user', id: randomUUID() });
+}
+
+/** sessionId → { turn, startedAt, lastAt, count }。 */
+const sessions = new Map();
+
+function trackOf(sessionId, turn, now) {
+  const current = sessions.get(sessionId);
+  if (current && current.turn === turn) return current;
+  // 换轮就重开一份：门槛按轮算，不跟上一条消息的水位混在一起。
+  const fresh = { turn, startedAt: now, lastAt: 0, count: 0 };
+  sessions.delete(sessionId);
+  sessions.set(sessionId, fresh);
+  while (sessions.size > TRACKED_SESSIONS) sessions.delete(sessions.keys().next().value);
+  return fresh;
+}
+
+/**
+ * 这一步该不该递话。
+ *
+ * 纯判断，输入是「这一轮跑了多久、已经说过几句、上次说是什么时候」，方便守卫直接真跑。
+ */
+function narrationDecision({ elapsedMs, said, sinceLastMs }) {
+  if (elapsedMs < NARRATION_FIRST_MS) return false;
+  if (said >= NARRATION_MAX_PER_TURN) return false;
+  if (said > 0 && sinceLastMs < NARRATION_INTERVAL_MS) return false;
+  return true;
+}
+
+/**
+ * `agent/pre-step` 的监听：跑得够久就追加一句提醒。
+ *
+ * 任何失败都吞掉 —— 播报是锦上添花，读盘失败或消息造不出来不该让用户这一轮发不出去。
+ * 子代理会话直接跳过：它的上下文更紧，而且那不是用户在等的那个对话。
+ */
+async function onPreStep(payload, next) {
+  const decision = await next();
+  try {
+    // 拒收的那一档没有 messages 可追加（`decision.kind === 'reject'`），原样放行。
+    if (!decision || !Array.isArray(decision.messages)) return decision;
+    if (!narrationEnabled()) return decision;
+    const header = payload?.agent?.session?.header;
+    if (!header?.id || header.origin === 'subagent') return decision;
+    const now = Date.now();
+    const track = trackOf(header.id, payload.turn, now);
+    const wanted = narrationDecision({
+      elapsedMs: now - track.startedAt,
+      said: track.count,
+      sinceLastMs: track.lastAt ? now - track.lastAt : Number.POSITIVE_INFINITY,
+    });
+    if (!wanted) return decision;
+    const hint = await buildHint();
+    track.count += 1;
+    track.lastAt = now;
+    return { ...decision, messages: [...decision.messages, hint] };
+  } catch {
+    return decision;
+  }
+}
+
+/** 挂上钩子。返回清理函数（`ctx.effect` 要的那个）。 */
+function installNarration(ctx) {
+  return ctx.on('agent/pre-step', onPreStep);
+}
+
+/**
+ * GET  /api/mobile/v1/narration —— 当前开关（手机打开菜单时读一次）。
+ * POST /api/mobile/v1/narration —— `{ enabled: boolean }` 拨开关。
+ *
+ * 两条收在同一路径上由 `req.method` 分派（宿主的注册器不按方法分派，与 `/relay/config` 同一条路）。
+ */
+async function handleNarration(_ctx, req, res) {
+  if (req && req.method === 'POST') {
+    const body = await readJsonBody(req);
+    if (!body || typeof body.enabled !== 'boolean') {
+      sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } });
+      return;
+    }
+    try {
+      sendJson(res, 200, { ok: true, enabled: setNarration(body.enabled) });
+    } catch (error) {
+      sendJson(res, 500, {
+        ok: false,
+        error: { code: 'write-failed', message: `开关没写进去：${error && error.message ? error.message : error}` },
+      });
+    }
+    return;
+  }
+  sendJson(res, 200, { ok: true, enabled: narrationEnabled() });
+}
+
+module.exports = {
+  installNarration,
+  narrationEnabled,
+  setNarration,
+  narrationDecision,
+  narrationText,
+  handleNarration,
+  settingsFile,
+  NARRATION_FIRST_MS,
+  NARRATION_INTERVAL_MS,
+  NARRATION_MAX_PER_TURN,
+  NARRATION_SOURCE_KIND,
+};

package/lib/mobile/phone/binding.js

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * 「这条会话操作哪台手机」的绑定账。
+ *
+ * 规则只有一条：**会话第一次收到某台手机发来的消息时，把会话绑到那台手机上**，之后不管
+ * 用户在 B 手机还是平板上继续聊，都还是操作 A。绑定要落盘 —— 宿主重启、插件热替换之后
+ * 它还在，否则用户第二天回来会发现任务跑到另一台手机上去了。
+ *
+ * 另记一本「最近一次发消息的是谁」。它不进绑定，只用来在两件事上有话可说：
+ *
+ *  1. 工具执行时发现「这一轮来自 B、绑着 A」，就把这件事交给模型，让它问一句要不要改绑，
+ *     而不是闷头操纵 A；
+ *  2. 没有任何绑定的老会话（这个功能上线之前就存在的对话）第一次要操作手机时，按最近一次
+ *     发消息的那台算，而不是干等。
+ *
+ * 显式改绑走 `setBinding`（模型调 `phone_target`），它只改绑定，不改最近发消息的人 ——
+ * 后者是事实，改了就成了编。
+ *
+ * 两本账都按 sessionId 存，条目上限与已读回执同一量级：会话被删掉时这里不会跟着删
+ * （宿主不知道），只按最近活动淘汰，留着一条指向已删会话的记录只是几百字节。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('../../shared/paths');
+
+/** sessionId 与 deviceId 的长度上限（真实值都是 UUID 量级）。 */
+const MAX_ID = 200;
+/** 条目上限：按 lastAt 保留最新的。 */
+const MAX_ENTRIES = 2000;
+
+/** 文件：`$DSH_HOME/phone-bindings.json`。DSH_HOME 在调用时解析，测试可注入。 */
+function stateFile() {
+  return path.join(paths.dshHome(), 'phone-bindings.json');
+}
+
+/** null = 还没写过；否则 `{ [sessionId]: { bound, boundAt, last, lastAt } }`。 */
+let table = null;
+
+function load() {
+  if (table) return table;
+  try {
+    const raw = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    table = raw && typeof raw === 'object' && raw.sessions && typeof raw.sessions === 'object'
+      ? raw.sessions
+      : {};
+  } catch {
+    table = {};
+  }
+  return table;
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim().slice(0, MAX_ID) : '';
+}
+
+/** 只留合法形状，并按 lastAt 截断 —— 盘上的文件可能是旧版本或被人手改过。 */
+function normalize(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const bound = text(entry.bound);
+  const last = text(entry.last);
+  if (!bound && !last) return null;
+  const boundAt = Number.isFinite(entry.boundAt) ? entry.boundAt : 0;
+  const lastAt = Number.isFinite(entry.lastAt) ? entry.lastAt : 0;
+  return { bound, boundAt, last, lastAt };
+}
+
+function persist() {
+  const entries = Object.entries(load())
+    .map(([id, entry]) => [id, normalize(entry)])
+    .filter(([, entry]) => entry);
+  if (entries.length > MAX_ENTRIES) {
+    entries.sort((a, b) => (b[1].lastAt || b[1].boundAt) - (a[1].lastAt || a[1].boundAt));
+    entries.length = MAX_ENTRIES;
+  }
+  const sessions = Object.fromEntries(entries);
+  try {
+    fs.mkdirSync(path.dirname(stateFile()), { recursive: true });
+    const tmp = `${stateFile()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ version: 1, sessions }), 'utf8');
+    fs.renameSync(tmp, stateFile());
+  } catch {
+    // 落盘失败不该让一次动作中断：内存里那份仍然是对的，下一次写再试。
+  }
+}
+
+function entryOf(sessionId) {
+  const id = text(sessionId);
+  if (!id) return null;
+  return normalize(load()[id]);
+}
+
+/** 这条会话绑在哪台手机上；没有绑定时为 null。 */
+function boundDeviceOf(sessionId) {
+  const entry = entryOf(sessionId);
+  return entry && entry.bound ? entry.bound : null;
+}
+
+/** 最近一次给这条会话发消息的是哪台手机；没有记录时为 null。 */
+function lastSenderOf(sessionId) {
+  const entry = entryOf(sessionId);
+  return entry && entry.last ? entry.last : null;
+}
+
+/**
+ * 记一次「这台手机发来了消息」。**同时**在会话还没有绑定时把它绑上去。
+ *
+ * 只有 deviceId 非空才动账：没带设备头的调用（桌面端、测试、老客户端）不该把一条已经绑好
+ * 的会话改成「未绑定」，也不该把新会话绑到一台认不出的设备上。
+ *
+ * @returns {{bound: string, changed: boolean}} changed 表示这一次真的建立了绑定
+ */
+function noteSender(sessionId, deviceId, now = Date.now()) {
+  const id = text(sessionId);
+  const device = text(deviceId);
+  const current = entryOf(id);
+  if (!id || !device) return { bound: current ? current.bound : '', changed: false };
+  const entry = current || { bound: '', boundAt: 0, last: '', lastAt: 0 };
+  const changed = !entry.bound;
+  if (changed) {
+    entry.bound = device;
+    entry.boundAt = now;
+  }
+  entry.last = device;
+  entry.lastAt = now;
+  load()[id] = entry;
+  persist();
+  return { bound: entry.bound, changed };
+}
+
+/**
+ * 显式改绑（模型调 `phone_target`）。只改 bound，`last` 原样留着。
+ *
+ * @returns {boolean} 有没有真的写下去（空 deviceId 一律拒）
+ */
+function setBinding(sessionId, deviceId, now = Date.now()) {
+  const id = text(sessionId);
+  const device = text(deviceId);
+  if (!id || !device) return false;
+  const entry = entryOf(id) || { bound: '', boundAt: 0, last: '', lastAt: 0 };
+  entry.bound = device;
+  entry.boundAt = now;
+  if (!entry.lastAt) entry.lastAt = now;
+  load()[id] = entry;
+  persist();
+  return true;
+}
+
+/**
+ * 从一次请求里认出「发消息的是哪台手机」，记进账。
+ *
+ * 挂在**发送成功之后**：发失败的那一发什么都没发生，拿它当「用户在这台手机上说话」会让一条
+ * 会话被一条没送达的消息绑到某台机器上。没带设备头的调用（桌面端、老客户端、测试）落在
+ * `legacy`，那不是任何一台手机，一律不记 —— 记了就会把已经绑好的账改成别的。
+ *
+ * 失败绝不影响调用方：绑定只是「下次操作哪台手机」的默认值，记账出错不该让一条已经交出去的
+ * 消息报失败。
+ */
+function noteRequestSender(req, sessionId) {
+  try {
+    const raw = req && req.headers ? req.headers['x-dsh-device'] : undefined;
+    const deviceId = text(Array.isArray(raw) ? raw[0] : raw);
+    if (!deviceId) return;
+    noteSender(sessionId, deviceId);
+  } catch { /* 绑定账写不进去不影响这一发 */ }
+}
+
+/**
+ * 某台手机不再被操作时（用户解除配对），把**指向它**的绑定一条条清掉。
+ *
+ * 只清 `bound` 指向它的那些；`last` 也指向它的不动 —— 那是「谁发过消息」的事实，不该因为
+ * 解绑就变成另一台。清掉之后这条会话回到「没有绑定」，下一次发消息的设备会重新绑上。
+ *
+ * @returns {number} 清了几条
+ */
+function clearBindingForDevice(deviceId, now = Date.now()) {
+  const device = text(deviceId);
+  if (!device) return 0;
+  const state = load();
+  let removed = 0;
+  for (const [id, entry] of Object.entries(state)) {
+    const normalized = normalize(entry);
+    if (!normalized || normalized.bound !== device) continue;
+    normalized.bound = '';
+    normalized.boundAt = 0;
+    if (!normalized.last) { delete state[id]; continue; }
+    normalized.lastAt = normalized.lastAt || now;
+    state[id] = normalized;
+    removed += 1;
+  }
+  if (removed) persist();
+  return removed;
+}
+
+/** 会话被删 / 用户主动解绑时清掉。 */
+function clearBinding(sessionId) {
+  const id = text(sessionId);
+  if (!id) return false;
+  const state = load();
+  if (!(id in state)) return false;
+  delete state[id];
+  persist();
+  return true;
+}
+
+/**
+ * 这一次要操作哪台手机。
+ *
+ * 顺序：显式 target（调用方本次传入）→ 绑定 → 最近一次发消息的那台。三者都没有就是
+ * `null` —— 调用方必须把这当成「没有目标」报出来，**不许**拿「随便挑一台在线的」顶上：
+ * 那会让一条对话在用户不知情时去操作另一台手机。
+ *
+ * @returns {{deviceId: string, from: 'explicit'|'bound'|'sender'|'', changed: boolean}}
+ */
+function resolveTarget(sessionId, explicit) {
+  const wanted = text(explicit);
+  if (wanted) {
+    const current = boundDeviceOf(sessionId);
+    const changed = current !== wanted;
+    if (changed) setBinding(sessionId, wanted);
+    return { deviceId: wanted, from: 'explicit', changed };
+  }
+  const bound = boundDeviceOf(sessionId);
+  if (bound) return { deviceId: bound, from: 'bound', changed: false };
+  const sender = lastSenderOf(sessionId);
+  if (sender) return { deviceId: sender, from: 'sender', changed: true };
+  return { deviceId: '', from: '', changed: false };
+}
+
+/** 测试用：丢掉内存里那份（下一个用例重新从盘上读）。 */
+function resetForTest() {
+  table = null;
+}
+
+module.exports = {
+  stateFile,
+  boundDeviceOf,
+  lastSenderOf,
+  noteSender,
+  noteRequestSender,
+  setBinding,
+  clearBinding,
+  clearBindingForDevice,
+  resolveTarget,
+  resetForTest,
+};