dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/host-bridge/transport.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * 网关传输层：旧 `apiProxy` 的信封形状 ⇄ 宿主 `typertGateway` 的 invoke/stream。
+ *
+ * 这是整座桥里唯一知道「宿主怎么调」的地方，四个上层文件（端点表 / bespoke 翻译 /
+ * 事件合成 / 装配）都只经它出入。三条不能改的语义：
+ *  1. `gateway.invoke()` **不返回信封**，直接返回业务值本体 —— 包回信封是这里的事。
+ *  2. 业务错误的 `code`/`message`/`details` **原样透传**，否则 `promptErrorObject`
+ *     的 code 白名单、`errorDetails` 的 details.reason 契约、agent-preset 的
+ *     `agent-preset-not-found` 分支全部失效。
+ *  3. 网关自己抛的错（服务没装、方法没注册）一律收敛成 `host-unavailable`：对移动端
+ *     来说「宿主没这个能力」只有一种含义。
+ */
+
+const crypto = require('node:crypto');
+
+// 网关层抛的「服务/方法不存在」类错误：前缀随版本变过（0.1.x 时期是无前缀的
+// invocation-unavailable，0.2.0 是 gateway/invocation-unavailable），两种都认。
+const GATEWAY_MISSING = new Set([
+  'invocation-unavailable',
+  'service-unavailable',
+  'method-unavailable',
+  'definition-unavailable',
+  'ambiguous-endpoint',
+]);
+
+const UNAVAILABLE = Object.freeze({
+  code: 'host-unavailable',
+  message: '当前宿主版本没有提供该能力（需要 DSH 0.2.0 的 typertGateway）',
+});
+
+/** 宿主 0.2.0 确实没有这个端点（不是版本问题，是没实现）：如实回报，别假装成功。 */
+function unsupported(what) {
+  return {
+    result: {
+      ok: false,
+      error: {
+        code: 'host-unsupported',
+        message: `当前宿主版本没有提供${what}，请在被控端使用更新版本的 DSH`,
+      },
+    },
+  };
+}
+
+/** 合成流（workspace 跟随 / 历史翻页取游标）没有天然截止时间，这里给一个上限。 */
+const SYNTHETIC_DEADLINE_MS = 8000;
+
+function deadline(signal, ms) {
+  const timer = AbortSignal.timeout(ms);
+  if (!signal) return timer;
+  try {
+    return typeof AbortSignal.any === 'function' ? AbortSignal.any([signal, timer]) : signal;
+  } catch {
+    return signal;
+  }
+}
+
+function gatewayOf(ctx) {
+  try {
+    return (ctx.get && ctx.get('typertGateway')) || null;
+  } catch {
+    return null;
+  }
+}
+
+function warn(ctx, message) {
+  try {
+    const logger = ctx && ctx.logger;
+    if (logger && typeof logger.warn === 'function') logger.warn(`[dsh-mobile-plugin] ${message}`);
+  } catch {
+    /* 桥接层的告警不能反过来弄挂宿主 */
+  }
+}
+
+function pick(source, keys) {
+  const out = {};
+  if (!source || typeof source !== 'object') return out;
+  for (const key of keys) if (source[key] !== undefined) out[key] = source[key];
+  return out;
+}
+
+function ok(value) {
+  return { result: { ok: true, value } };
+}
+
+function errorOf(error, fallbackCode) {
+  if (!error) return { ...UNAVAILABLE };
+  const code = typeof error.code === 'string' && error.code ? error.code : fallbackCode || 'host-call-failed';
+  if (GATEWAY_MISSING.has(code) || GATEWAY_MISSING.has(String(code).replace(/^gateway\//, ''))) {
+    return { ...UNAVAILABLE };
+  }
+  const message = typeof error.message === 'string' && error.message ? error.message : String(error);
+  const details = error.details;
+  const plain =
+    details && typeof details === 'object' && !Array.isArray(details) &&
+    (Object.getPrototypeOf(details) === Object.prototype || Object.getPrototypeOf(details) === null)
+      ? details
+      : undefined;
+  return plain ? { code, message, details: plain } : { code, message };
+}
+
+function fail(error, fallbackCode) {
+  return { result: { ok: false, error: errorOf(error, fallbackCode) } };
+}
+
+function requestId(prefix) {
+  return `${prefix}-randomUUID-${crypto.randomUUID()}`;
+}
+
+/**
+ * args 多一个键就会 gateway/arguments-invalid。这里按宿主文案（形如
+ * `unexpected "clientMessageId"`）把多余的键摘掉重试一次 —— 多出来的键宿主根本
+ * 不会读，摘掉是安全的，也免得为一个拼写差异让整个功能不可用。
+ */
+function dropUnexpectedArgs(args, message) {
+  if (!message || !message.includes('unexpected')) return null;
+  const clause = message.slice(message.indexOf('unexpected'));
+  const keys = [...clause.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  if (!keys.length) return null;
+  const next = { ...args };
+  let removed = 0;
+  for (const key of keys) {
+    if (!Object.hasOwn(next, key)) continue;
+    delete next[key];
+    removed += 1;
+  }
+  return removed ? next : null;
+}
+
+async function invoke(ctx, namespace, method, args, signal) {
+  const gateway = gatewayOf(ctx);
+  if (!gateway) return { error: { ...UNAVAILABLE } };
+  const request = { namespace, method, args };
+  if (signal) request.signal = signal;
+  try {
+    return { value: await gateway.invoke(request) };
+  } catch (error) {
+    if (error && error.code === 'gateway/arguments-invalid') {
+      const retry = dropUnexpectedArgs(args, error.message);
+      if (retry) {
+        warn(ctx, `${namespace}/${method} 去掉多余参数后重试：${JSON.stringify(retry)}`);
+        try {
+          return { value: await gateway.invoke({ ...request, args: retry }) };
+        } catch (second) {
+          return { error: errorOf(second, 'host-call-failed') };
+        }
+      }
+    }
+    return { error: errorOf(error, 'host-call-failed') };
+  }
+}
+
+async function openStream(ctx, namespace, method, args, signal) {
+  const gateway = gatewayOf(ctx);
+  if (!gateway) throw Object.assign(new Error(UNAVAILABLE.message), { code: UNAVAILABLE.code });
+  const request = { namespace, method, args };
+  if (signal) request.signal = signal;
+  return gateway.stream(request);
+}
+
+async function invokeEnvelope(ctx, namespace, method, args, signal) {
+  const result = await invoke(ctx, namespace, method, args, signal);
+  if (result.error) return fail(result.error);
+  return ok(result.value);
+}
+
+module.exports = { GATEWAY_MISSING, UNAVAILABLE, unsupported, deadline, gatewayOf, warn, pick, ok, errorOf, fail, requestId, dropUnexpectedArgs, invoke, openStream, invokeEnvelope, SYNTHETIC_DEADLINE_MS };

package/lib/mobile/host-bridge.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * 0.2.0 兼容桥：旧 `apiProxy` 调用形状 → 宿主 `typertGateway`。
+ *
+ * 背景：DSH 0.2.0 删掉了 `apiProxy` 服务（整个 app.asar 里零命中），宿主 RPC 全部改走
+ * `ctx.get('typertGateway')` 的 `invoke({namespace, method, args, signal})` / `stream(...)`。
+ * 但本插件 17 个移动端模块历史上都是这一套：
+ *
+ *   请求：`ctx.apiProxy.<ns>.<method>({ rpcId, method: '<ns>.<method>', payload }, signal)`
+ *   返回：`{ result: { ok: true, value } }` 或 `{ result: { ok: false, error } }`
+ *
+ * 与其逐个改 55 处调用点（每处都要对上宿主的 wire 参数名，而参数名错了只在运行时
+ * 报 `gateway/arguments-invalid`），这里提供**同名同形状**的服务，内部翻译成
+ * gateway 调用并把结果包回旧信封 —— 17 个文件一行都不用动，将来 DSH 若恢复真
+ * `apiProxy`，把这个目录删掉、apply 里那一行 provide 去掉即可。
+ *
+ * 本文件只剩装配：把端点表铺成 `apiProxy.<ns>.<method>` 的形状。实现分四份：
+ *   host-bridge/transport.js       网关传输与信封翻译（唯一知道「宿主怎么调」的地方）
+ *   host-bridge/endpoints.js       端点表（键 ⇄ 宿主 wire 名与参数形状）
+ *   host-bridge/shims.js           没有 1:1 端点、需要跨端点合成的几处
+ *   host-bridge/event-synthesis.js 旧设备级 events.mux ⇄ 0.2.0 拆开的三条流
+ */
+
+const { ENDPOINTS } = require('./host-bridge/endpoints.js');
+const { muxFrames } = require('./host-bridge/event-synthesis.js');
+const { unsupported, UNAVAILABLE } = require('./host-bridge/transport.js');
+
+// ── 装配 ──────────────────────────────────────────────────────────────────
+
+/**
+ * 把端点表铺成旧的 `apiProxy.<ns>.<method>` 形状。
+ *
+ * 键表直接从 ENDPOINTS 推，不再手写一份 `<ns>` → 方法名数组：两份表迟早会对不上，
+ * 而对不上的后果不是报错，是 `ctx.apiProxy.<ns>.<method> is not a function` 这种在
+ * 别的模块、别的请求里炸出来的 TypeError（新增 sessions.projections 时就漏登记过一次，
+ * /session/stats 会跟着一起挂）。现在新增端点只改 ENDPOINTS 一处。
+ */
+function createApiProxy(ctx) {
+  const namespaces = {};
+  for (const key of Object.keys(ENDPOINTS)) {
+    const dot = key.indexOf('.');
+    if (dot <= 0) continue;
+    const name = key.slice(0, dot);
+    const method = key.slice(dot + 1);
+    if (!namespaces[name]) namespaces[name] = {};
+    const spec = ENDPOINTS[key];
+    namespaces[name][method] = (request, signal) => spec(ctx, (request && request.payload) || {}, signal);
+  }
+
+  return {
+    ...namespaces,
+
+    // 帧流：返回的是异步生成器，调用方直接 for await（不是 Promise）。
+    events: {
+      mux: (request, signal) => muxFrames(ctx, request || {}, signal),
+      host: (request, signal) => muxFrames(ctx, request || {}, signal),
+    },
+
+    // 回答问题 / 审批。0.2.0 没有 approvals 命名空间，问题是 userQuestions/answer
+    // 且必须带 callId —— 而 callId 只在问题事件里出现过，本插件 0.1.x 的问题帧来自
+    // 旧 mux，形状对不上（见 README 的迁移说明），如实回报不支持，别让手机端干等。
+    respond: () => unsupported('远程回答提问/审批的接口'),
+
+    downloads: {
+      sessionLog: () => unsupported('会话日志导出接口'),
+    },
+  };
+}
+
+module.exports = { createApiProxy, UNAVAILABLE };

package/lib/mobile/host-settings.js

@@ -0,0 +1,282 @@
+'use strict';
+
+/**
+ * 移动端「宿主设置」API：只读暴露宿主的模型提供方名单与设置命名空间。
+ *
+ * 桌面端有完整的设置面板（默认模型、提供方配置、凭据是否已设），手机端此前一点都看不到，
+ * 只能看到一个「设置」页里全是 App 自己的偏好项。这里先把「看得到」补齐：
+ * settings.describe 与 llm.providers 都是只读接口，且宿主自己已经做了脱敏
+ * （secrets 只给出 path 与 set，从不返回值），所以可以原样转给手机。
+ *
+ * 命名空间里的 schema 字段是序列化后的 zod 树（几百个 uid/refs），对手机没有任何用处，
+ * 直接丢掉，只保留 value / base / user / applies / revision 与密钥槽。
+ *
+ * 写入侧（POST /host-settings/mutate）与桌面端同一口径：只走宿主的 settings.mutate，
+ * 用「按路径寻址的 op」（set / unset）+ expectedRevision 做乐观并发，绝不整段 replace。
+ * 桌面端就是这么写的：dsh-client-ui-settings/lib/client.js 一次只提交一个 op
+ * （`settings.mutate({ ns, ops: [op], expectedRevision })`），失败后重新 describe 再重试。
+ * 手机上一般一次改好几个字段，所以这里一次收一组 op，但语义与桌面端逐字段提交完全一致。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./sessions.js');
+
+const HOST_SETTINGS_MAX_NAMESPACES = 60; // 命名空间数量上限（避免异常宿主把响应撑爆）
+const HOST_SETTINGS_VALUE_DEPTH = 4;     // 值递归深度上限
+const HOST_SETTINGS_VALUE_KEYS = 40;     // 每层键/元素数量上限
+const HOST_SETTINGS_VALUE_CHARS = 4000;  // 单个字符串长度上限
+
+/**
+ * 把任意设置值压成可安全 JSON 传输的形状。
+ *
+ * 只保留 JSON 原生类型：字符串超长截断、数组/对象限深限宽、函数与 symbol 一律丢弃成 null，
+ * bigint 转成字符串（JSON.stringify 遇到 bigint 会直接抛错）。
+ */
+function boundValue(value, depth = 0) {
+  if (value === null || value === undefined) return null;
+  const type = typeof value;
+  if (type === 'string') {
+    return value.length > HOST_SETTINGS_VALUE_CHARS ? `${value.slice(0, HOST_SETTINGS_VALUE_CHARS)}…` : value;
+  }
+  if (type === 'number') return Number.isFinite(value) ? value : null;
+  if (type === 'boolean') return value;
+  if (type === 'bigint') return String(value);
+  if (Array.isArray(value)) {
+    if (depth >= HOST_SETTINGS_VALUE_DEPTH) return [];
+    return value.slice(0, HOST_SETTINGS_VALUE_KEYS).map((entry) => boundValue(entry, depth + 1));
+  }
+  if (type === 'object') {
+    if (depth >= HOST_SETTINGS_VALUE_DEPTH) return {};
+    const out = {};
+    for (const key of Object.keys(value).slice(0, HOST_SETTINGS_VALUE_KEYS)) {
+      out[key] = boundValue(value[key], depth + 1);
+    }
+    return out;
+  }
+  // function / symbol：设置值里出现这些没有意义，丢掉比抛错好。
+  return null;
+}
+
+/**
+ * 从序列化的 zod 树里读出「这个命名空间的密钥写到哪个凭据引用上」。
+ *
+ * 宿主把两个标记留在 schema 的 meta 里：`.role('secret')` 标出密钥字段，
+ * `.role('credential-ref')` 标出「写着凭据引用名」的那个字段
+ * （见 dsh-web-search-deepseek/lib/index.js:240-241 的 apiKey / apiKeyEnv）。
+ * settings.describe 的 secrets 槽就是由 role('secret') 生成的，而真正写入时
+ * 要用的是 role('credential-ref') 指向字段的值（桌面端也是这么取的：
+ * dsh-client-ui-settings-plugins/lib/client.js 的 refOf() 读 snapshot.value.apiKeyEnv）。
+ *
+ * 这里按同一口径从 schema 推导，不写死任何命名空间；推导不出来就返回 null，
+ * 于是 App 不会给没有密钥槽的设置项画密码框。
+ */
+function credentialRefOf(schema, value) {
+  const refs = schema && typeof schema === 'object' && !Array.isArray(schema) ? schema.refs : null;
+  if (!refs || typeof refs !== 'object' || Array.isArray(refs)) return null;
+  const root = refs[String(schema.uid)];
+  const dict = root && typeof root === 'object' ? root.dict : null;
+  if (!dict || typeof dict !== 'object' || Array.isArray(dict)) return null;
+
+  let refField = '';
+  let refDefault = '';
+  let secretFields = 0;
+  for (const field of Object.keys(dict)) {
+    const entry = refs[String(dict[field])];
+    const meta = entry && typeof entry === 'object' ? entry.meta : null;
+    const role = meta && typeof meta === 'object' ? meta.role : undefined;
+    if (role === 'secret') { secretFields += 1; continue; }
+    if (role === 'credential-ref' && !refField) {
+      refField = field;
+      refDefault = typeof meta.default === 'string' ? meta.default.trim() : '';
+    }
+  }
+  // 只认「恰好一个密钥槽」的命名空间：凭据引用是命名空间级的，两个密钥槽共用一个引用
+  // 时没法知道该往哪个引用写，宁可让手机端不给入口，也不写错地方。
+  if (secretFields !== 1 || !refField) return null;
+
+  const declared = value && typeof value === 'object' && !Array.isArray(value) ? value[refField] : undefined;
+  const ref = typeof declared === 'string' && declared.trim() ? declared.trim() : refDefault;
+  return ref ? { ref, refField } : null;
+}
+
+/**
+ * 把 settings.describe 的一条命名空间视图压成手机需要的形状。
+ *
+ * 畸形条目（没有 ns，或不是对象）返回 null，由调用方过滤掉；settings.describe 的值来自宿主，
+ * 但回放/旧版本宿主仍可能给出意外形状，这里不抛错。
+ */
+function normalizeNamespace(item) {
+  if (!item || typeof item !== 'object') return null;
+  const ns = typeof item.ns === 'string' ? item.ns.trim() : '';
+  if (!ns) return null;
+
+  const secrets = Array.isArray(item.secrets)
+    ? item.secrets
+      .map((slot) => {
+        if (!slot || typeof slot !== 'object') return null;
+        const path = Array.isArray(slot.path)
+          ? slot.path.filter((part) => typeof part === 'string' && part !== '').join('.')
+          : '';
+        if (!path) return null;
+        // 宿主只给「这个密钥槽是否已设置」，永远不给值；这里保持同一口径。
+        return { path, set: slot.set === true };
+      })
+      .filter(Boolean)
+    : [];
+
+  const out = {
+    ns,
+    value: boundValue(item.value),
+    applies: item.applies === 'restart' ? 'restart' : 'live',
+    revision: typeof item.revision === 'number' && Number.isFinite(item.revision) ? item.revision : 0,
+    secrets,
+  };
+  if (item.base !== undefined) out.base = boundValue(item.base);
+  if (item.user !== undefined) out.user = boundValue(item.user);
+  // 只有「宿主确实报了密钥槽」且「schema 里能推导出凭据引用」时才给出引用名；
+  // 两者缺一，App 就不该显示写密钥的入口。
+  if (secrets.length > 0) {
+    const credential = credentialRefOf(item.schema, item.value);
+    if (credential) out.credentialRef = credential.ref;
+  }
+  return out;
+}
+
+/** 把 llm.providers 的一条提供方压成手机需要的形状；缺 provider 的条目丢掉。 */
+function normalizeProvider(item) {
+  if (!item || typeof item !== 'object') return null;
+  const provider = typeof item.provider === 'string' ? item.provider.trim() : '';
+  if (!provider) return null;
+  const displayName = typeof item.displayName === 'string' && item.displayName.trim() ? item.displayName.trim() : provider;
+  return { provider, displayName, active: item.active === true };
+}
+
+/** GET /api/mobile/v1/host-settings —— 宿主设置命名空间（只读、已脱敏）。 */
+async function handleHostSettings(ctx, req, res) {
+  // 宿主的 settings.describe 不接受取消信号（apiproxy 的 invoke 也只传 request），故只传信封。
+  const { value, error } = unwrap(await ctx.apiProxy.settings.describe({
+    rpcId: 'mobile',
+    method: 'settings.describe',
+    payload: {},
+  }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  const list = Array.isArray(value && value.namespaces) ? value.namespaces : [];
+  const namespaces = list
+    .map(normalizeNamespace)
+    .filter(Boolean)
+    .slice(0, HOST_SETTINGS_MAX_NAMESPACES);
+
+  sendJson(res, 200, {
+    ok: true,
+    writable: value != null && value.writable === true,
+    hasDocument: value != null && value.hasDocument === true,
+    namespaces,
+  });
+}
+
+/** GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。 */
+async function handleLlmProviders(ctx, req, res) {
+  const { value, error } = unwrap(await ctx.apiProxy.llm.providers({
+    rpcId: 'mobile',
+    method: 'llm.providers',
+    payload: {},
+  }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  const list = Array.isArray(value && value.providers) ? value.providers : [];
+  const providers = list.map(normalizeProvider).filter(Boolean);
+
+  sendJson(res, 200, { ok: true, providers });
+}
+
+const HOST_SETTINGS_MAX_OPS = 40;   // 一次写入的 op 数量上限
+const HOST_SETTINGS_MAX_PATH = 8;   // 单个路径的层数上限
+
+/**
+ * 校验一条 op 的路径：非空字符串数组。
+ *
+ * 空路径等于改整个命名空间，手机端一律不许（要整段替换就得走 settings.replace，
+ * 这里不暴露那条路）。上层元素也只接受非空字符串，避免 `[0]` 这种数组下标意外命中。
+ */
+function normalizePath(path) {
+  if (!Array.isArray(path) || path.length === 0 || path.length > HOST_SETTINGS_MAX_PATH) return null;
+  const out = [];
+  for (const part of path) {
+    if (typeof part !== 'string' || part === '') return null;
+    out.push(part);
+  }
+  return out;
+}
+
+/**
+ * 校验并原样重建 op 列表；任何一条不合法就整批拒绝。
+ *
+ * `value` 不在这里做类型校验：那是宿主 schema 的活，宿主的 settings-rejected 会带着
+ * 具体原因回来，比在这里猜准得多（值也可能就是 undefined）。
+ */
+function normalizeOps(value) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > HOST_SETTINGS_MAX_OPS) return null;
+  const out = [];
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const path = normalizePath(item.path);
+    if (!path) return null;
+    if (item.op === 'unset') { out.push({ op: 'unset', path }); continue; }
+    if (item.op === 'set') { out.push({ op: 'set', path, value: item.value }); continue; }
+    return null;
+  }
+  return out;
+}
+
+/**
+ * POST /api/mobile/v1/host-settings/mutate（token）
+ * { ns, ops: [{op:'set',path:[...],value}|{op:'unset',path:[...]}], expectedRevision? }
+ * → { ok, namespace }
+ *
+ * 乐观并发：把 App 看到的 revision 原样带上，宿主在 revision 不匹配时回
+ * `settings-conflict`（details 里有 expected/actual），这里如实透传，App 才能提示
+ * 「别处改过了，刷新重试」。写入成功后宿主会回该命名空间的新视图，同样过一遍
+ * normalizeNamespace 再给手机。
+ */
+async function handleHostSettingsMutate(ctx, req, res) {
+  const body = await readJsonBody(req, 64 * 1024);
+  const ns = body && typeof body.ns === 'string' ? body.ns.trim() : '';
+  if (!ns) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { ns, ops }' } });
+  }
+  const ops = normalizeOps(body ? body.ops : undefined);
+  if (!ops) {
+    return sendJson(res, 400, {
+      ok: false,
+      error: { code: 'bad-request', message: 'ops 必须是 [{op:"set",path:[…],value}|{op:"unset",path:[…]}] 的非空数组' },
+    });
+  }
+  const expectedRevision = body && typeof body.expectedRevision === 'number' && Number.isInteger(body.expectedRevision) && body.expectedRevision > 0
+    ? body.expectedRevision
+    : undefined;
+
+  const { value, error } = unwrap(await ctx.apiProxy.settings.mutate({
+    rpcId: 'mobile',
+    method: 'settings.mutate',
+    payload: { ns, ops, ...(expectedRevision === undefined ? {} : { expectedRevision }) },
+  }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  const namespace = normalizeNamespace(value);
+  if (!namespace) {
+    return sendJson(res, 400, { ok: false, error: { code: 'internal', message: '宿主没有返回这个设置项的视图' } });
+  }
+  sendJson(res, 200, { ok: true, namespace });
+}
+
+module.exports = {
+  handleHostSettings,
+  handleHostSettingsMutate,
+  handleLlmProviders,
+  boundValue,
+  credentialRefOf,
+  normalizeNamespace,
+  normalizeProvider,
+  normalizeOps,
+};

package/lib/mobile/idempotency.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * 写操作幂等（requestId 重放）。
+ *
+ * 为什么需要：手机侧的一次写可能在**从未到达宿主**的通道上失败，此时传输内核会换一条
+ * 通道重投同一次请求（见 app/src/api/core.ts 的 routeCandidates/request）。重投的语义
+ * 是「这次写还没执行过」，但内核无法证明这一点 —— 它只知道「第一个候选连不上」。
+ * 一旦第一候选其实已经把请求送到宿主、只是响应回来时通道断了，重投就会让同一次写
+ * 执行两遍。对「新建会话」这类非幂等写，用户看到的就是凭空多出来一个会话。
+ *
+ * 约定与 promptOnce 一致：只缓存**成功**结果；失败必须能被重试（一次瞬时错误不能被
+ * 固化成 5 分钟的静默无响应）；没有 requestId 时直接执行，旧客户端行为不变。
+ *
+ * 存的是结果而不是「已执行」标记：重放要返回和第一次一样的东西，否则 App 会拿到
+ * 一个形状不同的响应（例如新建会话拿不到 sessionId）。
+ */
+
+const { writeIdempotencyStateOf } = require('./session-cache.js');
+
+/** 重放窗口：手机的一次写如果 5 分钟后才重投，那更可能是用户真的想再做一次。 */
+const WRITE_IDEMPOTENCY_TTL_MS = 5 * 60 * 1000;
+const MAX_WRITE_IDEMPOTENCY_ENTRIES = 256;
+
+/**
+ * 取出这次写请求的幂等 id。
+ *
+ * 优先 header：App 在构造请求头时生成一次，之后内核换通道重投用的还是同一个 init
+ * （同一个请求头），因此天然复用同一个 id。body.requestId 是给不方便加头的老客户端
+ * 的回退路径。
+ *
+ * @returns {string} 没有 id 时返回空串（调用方按「不做幂等」处理）
+ */
+function requestIdOf(req, body) {
+  const header = req && req.headers ? req.headers['x-dsh-request-id'] : undefined;
+  if (typeof header === 'string' && header.trim()) return header.trim().slice(0, 128);
+  const value = body && typeof body.requestId === 'string' ? body.requestId.trim() : '';
+  return value ? value.slice(0, 128) : '';
+}
+
+/**
+ * 执行一次幂等写。
+ *
+ * @param {object} ctx 插件上下文
+ * @param {string} deviceKey 设备维度（同一 requestId 在不同手机上互不影响）
+ * @param {string} requestId 请求 id；空串表示不做幂等，直接执行
+ * @param {() => Promise<{status:number, body:object}>} run 真正的写操作
+ * @returns {Promise<{status:number, body:object}>}
+ */
+async function withIdempotency(ctx, deviceKey, requestId, run) {
+  if (!requestId) return run();
+  const state = writeIdempotencyStateOf(ctx);
+  const key = `${deviceKey}\0${requestId}`;
+  const now = Date.now();
+  const existing = state.get(key);
+  if (existing && now - existing.createdAt < WRITE_IDEMPOTENCY_TTL_MS) return existing.result;
+  if (existing) state.delete(key);
+
+  // 并发同 id：两个请求共享同一个在途 promise，都拿到同一个结果。
+  const promise = Promise.resolve().then(run);
+  const record = { createdAt: now, result: promise };
+  state.set(key, record);
+  while (state.size > MAX_WRITE_IDEMPOTENCY_ENTRIES) state.delete(state.keys().next().value);
+  try {
+    const outcome = await promise;
+    record.result = outcome;
+    // 失败态（宿主内部错误/网关不可用）不缓存：它多半是瞬时故障，重投应当真的再试一次。
+    if (!outcome || typeof outcome.status !== 'number' || outcome.status >= 500) {
+      if (state.get(key) === record) state.delete(key);
+    }
+    return outcome;
+  } catch (error) {
+    if (state.get(key) === record) state.delete(key);
+    throw error;
+  }
+}
+
+module.exports = { requestIdOf, withIdempotency, WRITE_IDEMPOTENCY_TTL_MS };