dsh-mobile-plugin 0.5.10 → 0.5.12

package/lib/impl.js

@@ -28,7 +28,9 @@ const { deviceMetaFromHeaders } = require('./shared/device-headers.js')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
-const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates } = require('./relay/lan-network.cjs')
+const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates, withManualIpv6Candidate } = require('./relay/lan-network.cjs')
+// 配对二维码的载荷：面板与终端命令共用一份，拼装在 `./relay/pairing-payload.cjs`。
+const { pairingPayload } = require('./relay/pairing-payload.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -71,7 +73,20 @@ export const name = 'dsh-mobile-plugin'
 //
 // 旧运行时那一支多一个 `apiProxy`：宿主自己提供它（`@deepseek-ai/dsh-host-apiproxy` 装上
 // 了，就一定会被提供），读 `ctx.apiProxy` 必须有 inject，否则 get trap 直接抛。
-export const inject = runtimeProvidesApiProxy() ? ['webServer', 'apiProxy'] : ['webServer']
+//
+// **但「解析得到那个包」不等于「宿主一定会提供这个服务」**（2026-11-02 反馈 #11）：新版宿主
+// 上包名仍然解析得到，服务却已经删了。把 apiProxy 写进 inject 的代价是这一行**永远 pending**
+// —— apply 整个不跑，一条路由都不注册，手机上连「装了但连不上」都看不到。所以 inject 只剩
+// `webServer`，apiProxy 改由 apply 里按「过一小会儿真服务还没来就自己兜」决定，见下面的装配段。
+export const inject = ['webServer']
+
+/**
+ * 解析到包之后，等真服务的宽限期。
+ *
+ * 旧宿主在启动过程中就会 provide 出 apiProxy（本插件通常比它先挂），所以这段时间只用来看
+ * 「服务到底来不来」。等不到就说明这是新版宿主：包在、服务没了，必须自己挂兼容桥。
+ */
+const API_PROXY_GRACE_MS = 3000
 
 export const REMOTE_CONTROL_SETTINGS_NAMESPACE = 'mobile-remote-control'
 export const RemoteControlSettingsSchema = z.object({
@@ -93,6 +108,9 @@ export const RemoteControlSettingsSchema = z.object({
   preferredLanAddress: z.string().max(64).default(''),
   // 用户手填的直连地址（`manualLanUrl`，内网穿透域名）也随二维码一起走，见 lan-network.cjs。
   manualLanUrl: z.string().max(200).default(''),
+  // 用户手填的 IPv6 直连地址（`manualIpv6Url`，形如 `http://[240e::1]:18787`）：与上一条并列，
+  // 只是拨的是 IPv6；网卡扫不到的那条固定地址靠它兜底，候选口径见 lan-network.cjs。
+  manualIpv6Url: z.string().max(200).default(''),
 })
 
 
@@ -111,6 +129,7 @@ function configOf(state) {
     registerSecret: typeof state.registerSecret === 'string' ? state.registerSecret : '',
     preferredLanAddress: typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : '',
     manualLanUrl: typeof state.manualLanUrl === 'string' ? state.manualLanUrl : '',
+    manualIpv6Url: typeof state.manualIpv6Url === 'string' ? state.manualIpv6Url : '',
   }
 }
 
@@ -166,44 +185,6 @@ function createConfigStore(state) {
   }
 }
 
-function pairingPayload(state, lanPort) {
-  const port = Number.isInteger(lanPort) ? lanPort : state.lanPort
-  // 面板上选过的「手机优先用这条」在这里兑现：只挪到最前，其余继续当兜底（App 按顺序挨个试）。
-  const candidates = state.lanEnabled
-    ? phoneCandidates(advertisedCandidates(port), { preferred: state.preferredLanAddress, manual: state.manualLanUrl })
-    : []
-  const urls = candidates.map(candidate => candidate.url).filter(Boolean)
-  const relayUrl = state.relayUrl || ''
-  const payload = {
-    type: 'dsh-pair',
-    version: 1,
-    name: state.name || os.hostname(),
-    instanceId: state.instanceId,
-    code: state.pairingCode,
-    // 协议版本与一次性票据（§8.3(1)）。
-    //
-    // `proto: 2` 由**宿主**写、也由宿主生成，中转没有任何机会改写它 —— 所以「新 App 被
-    // 中转骗回明文」这个问题从一开始就不存在。`ticket` 是 32 字节随机数，手机拿它派生
-    // 配对密钥；二维码是屏幕对摄像头，这条通道完全绕开中转。
-    //
-    // 老 App 只取自己认识的那几个字段，多出来的两个会被忽略 —— 一张二维码同时服务新旧两种。
-    proto: 2,
-    ticket: state.pairingTicket || '',
-    relayUrl,
-    lanUrls: urls,
-    // 候选列表随二维码一起带走：App 配对后即使换了网段，也能按这份列表
-    // 依次重试而不用先回到公网中转去问。
-    lanCandidates: candidates.map(candidate => candidate.url).filter(Boolean),
-    // IPv6 直连候选（理想情况下是手机**不在同一个 Wi-Fi 里**时唯一能拨到的地址）：不参与上面
-    // 那份的排序，顺序由 App 侧拿它和公网中转实测比出来；直连监听没开就没有这条通道。
-    ipv6Candidates: state.lanEnabled ? ipv6Candidates(port).map(candidate => candidate.url).filter(Boolean) : [],
-  }
-  return {
-    payload,
-    text: `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`,
-  }
-}
-
 // 上报给 App 的候选地址（私网优先、没有私网才退公网）住在 `./relay/lan-network.cjs`
 // 的 `advertisedCandidates`：那是地址策略，不是装配。这里只把它转交给三处消费点。
 // 「手机上最近来过没有」同理，住在 `./mobile/activity.cjs`（守卫记、控制面状态读）。
@@ -264,10 +245,30 @@ function apply(ctx) {
       return undefined
     }
   }
-  if (!hasHostApiProxy) {
-    // `apiProxy` 是公共名字：另一个兼容旧 API 的插件也可能 provide 它。撞上时用对方那份
-    // （同形状、同语义），不跟它抢 —— 抢的结果是我们自己整块装配失败，手机那边全断。
+  /**
+   * 装兼容桥与两条帧桥（审批 / 提问）。
+   *
+   * 三者都只在「宿主这一代没有真 apiProxy」时才装：旧宿主自带真服务，多 provide 一次会让
+   * 整棵树加载失败（`service "apiProxy" has been registered at <dsh-mobile-plugin>`）。
+   * 而 `apiProxy` 是公共名字：另一个兼容旧 API 的插件也可能 provide 它，撞上时用对方那份。
+   */
+  const installCompatBridges = () => {
     mount('apiProxy 兼容桥', () => ctx.reflect.provide('apiProxy', createApiProxy(ctx)))
+    mount('审批桥', () => ctx.effect(() => installApprovalBridge(ctx), `${name}: host approval bridge`))
+    mount('提问桥', () => ctx.effect(() => installQuestionBridge(ctx), `${name}: host question bridge`))
+  }
+  if (!hasHostApiProxy) installCompatBridges()
+  else {
+    // 解析到包只说明「宿主可能是旧版」：新版宿主上包名还在、`apiProxy` 服务已经没了
+    // （2026-11-02 反馈 #11）。先给它一会儿把真服务 provide 出来（旧宿主在本插件装配
+    // 前后就会挂上），到点还没有就当作新版宿主，自己把兼容桥与两条帧桥装上 —— 否则
+    // 十几个移动端模块读到的是一个永远不来的服务，手机侧全程静默失败。
+    const timer = setTimeout(() => {
+      if (typeof ctx.get === 'function' && ctx.get('apiProxy')) return
+      warn('等不到宿主的 apiProxy，按新版宿主装配兼容桥')
+      installCompatBridges()
+    }, API_PROXY_GRACE_MS)
+    timer.unref?.()
   }
 
   const state = core.loadState()
@@ -342,8 +343,6 @@ function apply(ctx) {
   mount('sidecar', () => ctx.effect(() => sidecarLifecycle.start(), `${name}: facade sidecar`))
   mount('镜像推送', () => ctx.effect(() => mirror.start(), `${name}: mobile mirror sync`))
 
-  if (!hasHostApiProxy) mount('审批桥', () => ctx.effect(() => installApprovalBridge(ctx), `${name}: host approval bridge`))
-  if (!hasHostApiProxy) mount('提问桥', () => ctx.effect(() => installQuestionBridge(ctx), `${name}: host question bridge`))
   ctx.effect(() => {
     // Profiles without the optional tools injection still support core remote control.
     try { installSessionCleanup(ctx) } catch (error) {
@@ -490,7 +489,8 @@ function apply(ctx) {
     // 移动端那边的「局域网候选」：私网优先的清单 + 用户手填的直连地址（网卡扫不出的域名）。
     safeLanCandidates: (port) => phoneCandidates(advertisedCandidates(port), { manual: state.manualLanUrl }),
     // IPv6 直连候选单独一份：App 拿它单开一条通道、和公网中转比速度，不掺进上面那份的排序。
-    safeIpv6Candidates: ipv6Candidates,
+    // 手填的那条同样缀在最后（只追加、不删网卡候选），手机每次核对连接信息都重新拿到它。
+    safeIpv6Candidates: (port) => withManualIpv6Candidate(ipv6Candidates(port), state.manualIpv6Url),
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口
     // 配对那条路由自己要签凭据：core 是签 token 的实现，pairingApproval 决定这台机器
     // 收不收新设备（'deny' 时一律拒）。两者本文件都已有，透传给移动端路由。

package/lib/mobile/extension-dev.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * 扩展开发包：让手机直接读作者放在电脑上的本地扩展目录（`$DSH_HOME/extension-dev`）。
+ *
+ * 扩展平时的产物走 App 分发系统，装到手机自己那份扩展目录里；要让作者边写边在手机上看，
+ * 得有一个「从电脑现读」的入口。这个目录就是那个入口：一个子目录一个包，`manifest.json`
+ * 必须在，目录名即 slug。
+ *
+ * 能力面只多了「读这一个固定目录」：根写死在 `dshHome()` 下面，路径由 slug 与包内相对
+ * 路径拼出来，取文件前先 resolve 再判前缀 —— 不接受的是一份任意路径，不是一个被拼坏的
+ * 字符串。仍然不暴露 shell、系统设置、写文件。
+ *
+ * 坏包一律**静默跳过**而不是报错：作者当前正在编辑的那个包大概率是半成品，它不该让整张
+ * 列表变红；超限（20MB / 200 个文件）同理，不列表就是答案。取文件那条才逐个回错误码。
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { sendJson } = require('../shared/http-util');
+const { dshHome } = require('../shared/paths');
+
+/** 开发包根目录名。目录不存在时按需建出来 —— 作者要往里放东西。 */
+const DEV_ROOT_NAME = 'extension-dev';
+/** 目录名直接当 slug 用，所以只认这套字符；别的名字连读都不读。 */
+const SLUG_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** 整包上限：这是「现读现看」的通道，不是分发管道，太重的包手机也不该整份拉。 */
+const MAX_PACKAGE_BYTES = 20 * 1024 * 1024;
+const MAX_PACKAGE_FILES = 200;
+/** 单个文件上限：一条 base64 响应要塞进手机内存，再大就该走别的路（发布到分发系统）。 */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+
+function devRoot() {
+  return path.join(dshHome(), DEV_ROOT_NAME);
+}
+
+/** 400 信封：与其余移动端接口同形，App 按 code 翻人话。 */
+function fail(res, status, code, message) {
+  return sendJson(res, status, { ok: false, error: { code, message } });
+}
+
+/** manifest 里取一个非空字符串，缺了 / 类型不对 / 空串都退回默认值。 */
+function textField(value, fallback) {
+  return typeof value === 'string' && value ? value : fallback;
+}
+
+function sha256Hex(raw) {
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * 递归收集包内的普通文件，`path` 是相对包目录的 POSIX 路径。
+ *
+ * 名字以 `.` 开头的文件与目录一律不看：`.git`、`.DS_Store`、编辑器临时文件都属于作者自
+ * 己的现场，不是包内容。超限当场收手返回 false，让调用方把整包丢掉 —— 先收集完再判超限
+ * 等于把 500MB 的目录整个哈希一遍。
+ */
+function collectFiles(directory, acc) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!collectFiles(full, acc)) return false;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    let raw;
+    try { raw = fs.readFileSync(full); } catch { continue; }
+    acc.bytes += raw.length;
+    acc.files.push({
+      path: path.relative(acc.root, full).split(path.sep).join('/'),
+      size: raw.length,
+      sha256: sha256Hex(raw),
+    });
+    if (acc.bytes > MAX_PACKAGE_BYTES || acc.files.length > MAX_PACKAGE_FILES) return false;
+  }
+  return true;
+}
+
+/**
+ * 扫一遍根目录，把每个子目录读成一个包描述。坏 manifest、超限、slug 不合规都直接跳过。
+ */
+function listPackages(root) {
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  const packages = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !SLUG_PATTERN.test(entry.name)) continue;
+    const directory = path.join(root, entry.name);
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(directory, 'manifest.json'), 'utf8'));
+    } catch { continue; }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) continue;
+    const acc = { root: directory, files: [], bytes: 0 };
+    if (!collectFiles(directory, acc)) continue;
+    packages.push({
+      slug: entry.name,
+      name: textField(manifest.name, entry.name),
+      versionName: textField(manifest.versionName, textField(manifest.version, '0.0.0')),
+      apiVersion: textField(manifest.apiVersion, textField(manifest.api_version, '1')),
+      size: acc.bytes,
+      fileCount: acc.files.length,
+      files: acc.files,
+    });
+  }
+  return packages;
+}
+
+/**
+ * GET /api/mobile/v1/extension/dev/packages（token）
+ *
+ * 根目录不存在就建出来再回空列表：作者第一次打开开发包页时看到的是「目录已经在这儿了」，
+ * 而不是「宿主没给我建」。
+ */
+async function handleDevPackages(_ctx, _req, res) {
+  const root = devRoot();
+  try { fs.mkdirSync(root, { recursive: true }); } catch { /* 建不出来就按空列表回，读的时候自然也没有 */ }
+  sendJson(res, 200, { ok: true, root, packages: listPackages(root) });
+}
+
+/**
+ * GET /api/mobile/v1/extension/dev/file?slug=…&path=…（token）
+ *
+ * 读一个包里的一个文件，回 base64 与 sha256。sha256 与列表里那条是同一份算法，手机据此
+ * 判断「这份和我列表上看到的是不是同一版」。
+ *
+ * 路径检查是两道：先挡明显不该出现的（绝对路径、`..` 段），再 resolve 之后判前缀 ——
+ * 后者才是真正判据，前缀比较必须带上分隔符，否则 `/x/extension-dev/foobar` 会被
+ * `/x/extension-dev/foo` 认成自己的子路径。
+ */
+async function handleDevFile(_ctx, req, res) {
+  const url = new URL(req.url || '/', 'http://x');
+  const slug = (url.searchParams.get('slug') || '').trim();
+  const requested = (url.searchParams.get('path') || '').trim();
+  if (!slug || !requested || !SLUG_PATTERN.test(slug)) {
+    return fail(res, 400, 'bad-request', '需要合法的 slug 与 path（path 是相对包目录的路径）');
+  }
+
+  const directory = path.join(devRoot(), slug);
+  if (!fs.existsSync(path.join(directory, 'manifest.json'))) {
+    return fail(res, 404, 'dev-package-missing', `开发包目录里没有 ${slug} 这个包（缺 manifest.json）`);
+  }
+
+  if (path.isAbsolute(requested) || requested.split(/[\\/]/).includes('..')) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+  const target = path.resolve(directory, requested);
+  if (!target.startsWith(`${directory}${path.sep}`)) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+
+  let stats;
+  try { stats = fs.statSync(target); } catch { stats = null; }
+  if (!stats || !stats.isFile()) {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+  if (stats.size > MAX_FILE_BYTES) {
+    return fail(res, 413, 'file-too-large', `单个文件上限 ${MAX_FILE_BYTES} 字节，这个超了`);
+  }
+
+  let raw;
+  try { raw = fs.readFileSync(target); } catch {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+
+  const relative = path.relative(directory, target).split(path.sep).join('/');
+  sendJson(res, 200, {
+    ok: true,
+    path: relative,
+    size: raw.length,
+    sha256: sha256Hex(raw),
+    content: raw.toString('base64'),
+  });
+}
+
+module.exports = {
+  devRoot,
+  listPackages,
+  handleDevPackages,
+  handleDevFile,
+  MAX_PACKAGE_BYTES,
+  MAX_PACKAGE_FILES,
+  MAX_FILE_BYTES,
+};

package/lib/mobile/history-derive.js

@@ -329,6 +329,14 @@ function retryFailure(failure) {
   return out.code !== undefined || out.message !== undefined ? out : null;
 }
 
+/** 重试行属于哪一步：步骤一关就要把它作废（App 侧按这两个数认）。 */
+function retryOwner(data) {
+  return {
+    ...(typeof data.turn === 'number' ? { turn: data.turn } : {}),
+    ...(typeof data.step === 'number' ? { step: data.step } : {}),
+  };
+}
+
 /** 列表/概览的 lastMessage 预览只取有 role 的消息项（结构化行不参与预览）。 */
 function lastMessageOf(messages) {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -834,6 +842,7 @@ function deriveMessages(events, sessionId, lookbackEvents) {
           failure: retryFailure(e.data.failure),
           seq,
           time,
+          ...retryOwner(e.data),
         };
         if (typeof e.data.delayMs === 'number') item.delayMs = e.data.delayMs;
         retryAt.set(id, out.length);
@@ -854,8 +863,17 @@ function deriveMessages(events, sessionId, lookbackEvents) {
           failure: null,
           seq,
           time,
+          ...retryOwner(e.data),
         });
       }
+    } else if (e.type === 'step/end' && e.data && typeof e.data.turn === 'number' && typeof e.data.step === 'number') {
+      // 这一步关了就把它里面还停在 scheduled 的重试标成 cancelled（桌面 `isClosed` 判的也是这一步
+      // 结束）。只认 turn/end 的话，重开这个会话会看到一条永远「等待重试」的旧行，和新的并排。
+      for (const index of retryAt.values()) {
+        const row = out[index];
+        if (row && row.kind === 'retry' && row.status === 'scheduled'
+          && row.turn === e.data.turn && row.step === e.data.step) row.status = 'cancelled';
+      }
     } else if (e.type === 'command/run' && e.data && typeof e.data.commandId === 'string' && e.data.commandId !== '' && typeof e.data.name === 'string') {
       // 命令行：root 行（running）。同 commandId 重复 run（罕见）只更新位置字段。
       const id = e.data.commandId;

package/lib/mobile/model-caps.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * 模型能力配置（移动端）：公开参数快照 + 把用户选的那份写回这台电脑的渠道。
+ *
+ * 两条路由：
+ *   - `GET /api/mobile/v1/model-meta`（token）：整份公开参数快照（App 拉一次、落盘缓存，
+ *     之后搜索与命中都在 App 端做，断网 / 连不上 GitHub 都不影响）。另带 `overrides`：
+ *     `llm-pi-ai` 里每条自建路由**已经显式写下的**能力字段，弹窗用它把当前值填对。
+ *   - `POST /api/mobile/v1/model-meta/apply`（token）：把一份配置写进那条自建渠道的模型。
+ *
+ * 为什么只在插件这一侧写：渠道真源是宿主的 `llm-pi-ai` 命名空间，手机没有直接读写宿主配置的
+ * 通道，这一层做的与「渠道管理」保存时完全一样 —— `settings.describe` 读出那一条路由、
+ * 合并这一份模型的能力字段、再按路径 `settings.mutate` 写回去（只写 `providers.<id>`，
+ * 不碰别的路由）。内置渠道（别的插件注册的 provider）不在这份清单里，**一律 409 说明改不了**，
+ * 不给一个点了必然失败的保存按钮留后路。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./envelope.js');
+const { dropSessionModelsForDevice } = require('./session-cache.js');
+const modelMeta = require('./model-meta.js');
+
+/** 自建渠道写在这个命名空间里；与 `channels.js` 的 PI_AI_NS 同一个。 */
+const PI_AI_NS = 'llm-pi-ai';
+
+const MAX_PROVIDER_CHARS = 64;
+const MAX_MODEL_CHARS = 200;
+/** 上下文 / 输出上限的合理上限：再大就不是 token 数了（1 千万已经远超人能用的窗口）。 */
+const MAX_TOKENS = 10_000_000;
+
+/** `llm-pi-ai` 的 providers 字典；形状不对就当空表。 */
+function piAiProvidersOf(value) {
+  const providers = value && typeof value === 'object' && !Array.isArray(value) ? value.providers : null;
+  return providers && typeof providers === 'object' && !Array.isArray(providers) ? providers : {};
+}
+
+async function readPiAiProviders(ctx) {
+  const describe = unwrap(await ctx.apiProxy.settings.describe({
+    rpcId: 'mobile',
+    method: 'settings.describe',
+    payload: {},
+  }));
+  if (describe.error) return { error: describe.error };
+  const namespaces = Array.isArray(describe.value && describe.value.namespaces) ? describe.value.namespaces : [];
+  const piAi = namespaces.find((entry) => entry && entry.ns === PI_AI_NS);
+  return { providers: piAiProvidersOf(piAi && piAi.value) };
+}
+
+/** 一条模型上「已经显式写过」的能力字段（只有写过的才算，缺省值不算用户的选择）。 */
+function capabilityOf(model) {
+  if (!model || typeof model !== 'object') return undefined;
+  const caps = {};
+  if (Number(model.contextWindow) > 0) caps.contextWindow = Math.trunc(Number(model.contextWindow));
+  if (Number(model.maxTokens) > 0) caps.maxTokens = Math.trunc(Number(model.maxTokens));
+  if (Array.isArray(model.input) && model.input.includes('image')) caps.vision = true;
+  if (Array.isArray(model.reasoningEfforts)) {
+    const levels = model.reasoningEfforts.filter((level) => modelMeta.MODEL_LEVELS.includes(level));
+    if (levels.length > 0) caps.reasoning = levels;
+  } else if (model.reasoningEfforts && typeof model.reasoningEfforts === 'object') {
+    const levels = modelMeta.MODEL_LEVELS.filter((level) => model.reasoningEfforts[level] !== undefined);
+    if (levels.length === 0) caps.reasoning = [];
+    else caps.reasoning = levels;
+  } else if (model.reasoningEfforts === false) {
+    caps.reasoning = [];
+  }
+  return Object.keys(caps).length === 0 ? undefined : caps;
+}
+
+/** 路由发下来的那份配置里，哪些渠道已经写了能力字段。 */
+function overridesOf(providers) {
+  const out = {};
+  for (const providerId of Object.keys(providers)) {
+    const profile = providers[providerId];
+    const models = profile && Array.isArray(profile.models) ? profile.models : [];
+    for (const model of models) {
+      const id = model && typeof model.id === 'string' ? model.id : '';
+      if (id === '') continue;
+      const caps = capabilityOf(model);
+      if (caps) out[`${providerId}\u0001${id}`] = caps;
+    }
+  }
+  return out;
+}
+
+/**
+ * GET /api/mobile/v1/model-meta[?q=关键词]
+ *
+ * 不带 `q` 回整份快照（App 缓存那一份，约 450KB）；带 `q` 只回这一搜的结果（给不缓存的一次性
+ * 查询用）。两种情况都带 `revision`：内容没变时 App 不必把整份重新落盘。
+ */
+async function handleModelMeta(ctx, req, res) {
+  const url = new URL(req.url, 'http://mobile.local');
+  const query = url.searchParams.get('q') || '';
+  const limit = Number(url.searchParams.get('limit'));
+  const providers = await readPiAiProviders(ctx);
+  if (providers.error) return sendJson(res, 400, { ok: false, error: providers.error });
+  const overrides = overridesOf(providers.providers);
+  const revision = modelMeta.revision;
+  if (query.trim() !== '') {
+    sendJson(res, 200, { ok: true, revision, items: modelMeta.searchModelMeta(query, limit), overrides });
+    return;
+  }
+  const full = modelMeta.fullModelMeta();
+  sendJson(res, 200, { ok: true, revision: full.revision, total: full.total, items: full.items, overrides });
+}
+
+/** 一次提交里哪些字段是「用户真的给了」—— 缺的沿用那台电脑原来的值，别拿缺省值覆盖。 */
+function normalizeApply(body) {
+  const provider = typeof body.provider === 'string' ? body.provider.trim() : '';
+  const model = typeof body.model === 'string' ? body.model.trim() : '';
+  if (provider === '' || provider.length > MAX_PROVIDER_CHARS) {
+    return { error: { code: 'bad-request', message: '渠道 id 不合法' } };
+  }
+  if (model === '' || model.length > MAX_MODEL_CHARS) {
+    return { error: { code: 'bad-request', message: '模型 id 不合法' } };
+  }
+  const patch = {};
+  if (body.contextWindow !== undefined) {
+    const value = Number(body.contextWindow);
+    if (!Number.isInteger(value) || value <= 0 || value > MAX_TOKENS) {
+      return { error: { code: 'bad-request', message: '上下文窗口必须是正整数' } };
+    }
+    patch.contextWindow = value;
+  }
+  if (body.maxTokens !== undefined) {
+    const value = Number(body.maxTokens);
+    if (!Number.isInteger(value) || value <= 0 || value > MAX_TOKENS) {
+      return { error: { code: 'bad-request', message: '输出上限必须是正整数' } };
+    }
+    patch.maxTokens = value;
+  }
+  if (body.vision !== undefined) {
+    if (typeof body.vision !== 'boolean') return { error: { code: 'bad-request', message: '读图能力必须是布尔值' } };
+    patch.vision = body.vision;
+  }
+  if (body.reasoning !== undefined) {
+    if (!Array.isArray(body.reasoning)) return { error: { code: 'bad-request', message: '推理档位必须是数组' } };
+    const levels = [];
+    for (const level of body.reasoning) {
+      if (!modelMeta.MODEL_LEVELS.includes(level)) {
+        return { error: { code: 'bad-request', message: `推理档位不认识：${String(level)}` } };
+      }
+      if (!levels.includes(level)) levels.push(level);
+    }
+    patch.reasoning = modelMeta.MODEL_LEVELS.filter((level) => levels.includes(level));
+  }
+  if (Object.keys(patch).length === 0) {
+    return { error: { code: 'bad-request', message: '没有要改的字段' } };
+  }
+  const context = patch.contextWindow;
+  const output = patch.maxTokens;
+  if (context !== undefined && output !== undefined && output >= context) {
+    return { error: { code: 'bad-request', message: '输出上限必须小于上下文窗口' } };
+  }
+  return { provider, model, patch };
+}
+
+/** 把一份能力配置合进那条模型（其它字段原样保留）。 */
+function mergeModel(model, patch) {
+  const merged = { ...model };
+  if (patch.contextWindow !== undefined) merged.contextWindow = patch.contextWindow;
+  if (patch.maxTokens !== undefined) merged.maxTokens = patch.maxTokens;
+  if (patch.vision !== undefined) merged.input = patch.vision ? ['text', 'image'] : ['text'];
+  if (patch.reasoning !== undefined) {
+    merged.reasoningEfforts = patch.reasoning.length === 0
+      ? false
+      : Object.fromEntries(patch.reasoning.map((level) => [level, level]));
+  }
+  return merged;
+}
+
+/**
+ * POST /api/mobile/v1/model-meta/apply（token）{ provider, model, contextWindow?, maxTokens?, vision?, reasoning? }
+ *
+ * 只写 `llm-pi-ai` 里真的存在的那条渠道的**那一个模型**：读出现有 profile、换掉这一条模型、
+ * 按路径 `set` 回去。不认识的能力字段与渠道层字段（`api` / `baseURL` / `apiKeyEnv`）原样保留，
+ * 所以改一次能力不会把桌面调好的地址或别人的路由冲掉。
+ */
+async function handleModelMetaApply(ctx, req, res) {
+  const body = await readJsonBody(req, 64 * 1024);
+  if (!body || typeof body !== 'object') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要一份模型配置' } });
+  }
+  const normalized = normalizeApply(body);
+  if (normalized.error) return sendJson(res, 400, { ok: false, error: normalized.error });
+
+  const read = await readPiAiProviders(ctx);
+  if (read.error) return sendJson(res, 400, { ok: false, error: read.error });
+  const providers = read.providers;
+  const profile = providers[normalized.provider];
+  if (!profile) {
+    // 不是自建渠道：别的插件注册的 provider，手机这一侧没有归它管的配置。
+    return sendJson(res, 409, {
+      ok: false,
+      error: { code: 'model-meta-external', message: '这条渠道不归本机配置，改不了它的模型参数' },
+    });
+  }
+  const models = Array.isArray(profile.models) ? profile.models : [];
+  const index = models.findIndex((model) => model && model.id === normalized.model);
+  if (index < 0) {
+    return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '这条渠道里没有这个模型' } });
+  }
+  const current = models[index];
+  const context = normalized.patch.contextWindow !== undefined ? normalized.patch.contextWindow : Number(current.contextWindow);
+  const output = normalized.patch.maxTokens !== undefined ? normalized.patch.maxTokens : Number(current.maxTokens);
+  if (Number(context) > 0 && Number(output) > 0 && output >= context) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '输出上限必须小于上下文窗口' } });
+  }
+
+  const nextModels = models.slice();
+  nextModels[index] = mergeModel(current, normalized.patch);
+  const write = unwrap(await ctx.apiProxy.settings.mutate({
+    rpcId: 'mobile',
+    method: 'settings.mutate',
+    payload: { ns: PI_AI_NS, ops: [{ op: 'set', path: ['providers', normalized.provider], value: { ...profile, models: nextModels } }] },
+  }));
+  if (write.error) return sendJson(res, 400, { ok: false, error: write.error });
+
+  // 模型目录（含能力字段投影）是设备级缓存、却按会话存：整批作废，别让别的会话继续吃旧值。
+  dropSessionModelsForDevice(ctx, req);
+  sendJson(res, 200, {
+    ok: true,
+    provider: normalized.provider,
+    model: normalized.model,
+    capability: capabilityOf(nextModels[index]) || {},
+  });
+}
+
+module.exports = {
+  handleModelMeta,
+  handleModelMetaApply,
+  normalizeApply,
+  mergeModel,
+  capabilityOf,
+  overridesOf,
+  PI_AI_NS,
+  MAX_TOKENS,
+};