dsh-mobile-plugin 0.5.9 → 0.5.11

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/host-settings.js

@@ -12,6 +12,7 @@
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { unwrap } = require('./sessions.js');
 
 const HOST_SETTINGS_MAX_NAMESPACES = 60; // 命名空间数量上限（避免异常宿主把响应撑爆）
@@ -245,7 +246,12 @@ async function handleHostSettings(ctx, req, res) {
   });
 }
 
-/** GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。 */
+/**
+ * GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。
+ *
+ * 带 `?rev=` 时按内容指纹走条件响应：名单没变就只回一句 `unchanged`（几十字节），
+ * 不再把整份重传一遍。手机那边把它当设备级目录缓存，进页面先摆上次那份、再拿指纹问一次。
+ */
 async function handleLlmProviders(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.providers({
     rpcId: 'mobile',
@@ -257,7 +263,8 @@ async function handleLlmProviders(ctx, req, res) {
   const list = Array.isArray(value && value.providers) ? value.providers : [];
   const providers = list.map(normalizeProvider).filter(Boolean);
 
-  sendJson(res, 200, { ok: true, providers });
+  const body = { ok: true, providers, revision: stableRevision(providers) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 /**
@@ -303,6 +310,9 @@ function normalizeModelGroup(group) {
  *
  * 与 `/llm/providers` 的区别：那条只说「有哪些提供方 / 哪个在生效」，这条给出每个提供方
  * 下面真正可请求的模型 id。手机上没有活动会话时（比如从 Git 页打开选择器）也能拿到。
+ *
+ * 这一份是全仓最大的一份目录响应（每个提供方下面几十上百条模型），而它只在用户加渠道、
+ * 换模型时变，所以同样吃 `?rev=` 的条件响应：没变时几十字节说清，别整份重传。
  */
 async function handleLlmModels(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.models({
@@ -314,7 +324,8 @@ async function handleLlmModels(ctx, req, res) {
 
   const list = Array.isArray(value && value.groups) ? value.groups : [];
   const groups = list.map(normalizeModelGroup).filter(Boolean).slice(0, HOST_SETTINGS_MAX_NAMESPACES);
-  sendJson(res, 200, { ok: true, groups });
+  const body = { ok: true, groups, revision: stableRevision(groups) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 const HOST_SETTINGS_MAX_OPS = 40;   // 一次写入的 op 数量上限

package/lib/mobile/local-images.js

@@ -133,6 +133,56 @@ function createTextImageBudget(limit = MAX_TEXT_IMAGES) {
   return { remaining: limit };
 }
 
+/**
+ * JPEG 的 EXIF 朝向（0x0112），没有就返回 0。
+ *
+ * 手机相机竖着拍出来的照片，像素本身是横的，靠 EXIF 里的朝向告诉播放器「先转 90°」。
+ * 宽高只按像素读的话，正文里就会出现「横盒子装竖图」：App 按 `resizeMode="contain"` 画，
+ * 图缩成中间一条、两侧一大片空白（2026-10-31 平板实测）。所以 5–8 这四档要对调宽高。
+ *
+ * 只认 JPEG：PNG / WebP 里带 eXIf 的极少，不值得为它多扫一遍。
+ */
+function jpegOrientation(buf) {
+  let at = 2;
+  while (at + 4 < buf.length) {
+    if (buf[at] !== 0xff) { at += 1; continue; }
+    const marker = buf[at + 1];
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { at += 2; continue; }
+    // 到扫描数据了，后面不会再有 APP 段。
+    if (marker === 0xda) return 0;
+    const length = buf.readUInt16BE(at + 2);
+    if (length < 2) return 0;
+    if (marker === 0xe1 && at + 10 <= buf.length && buf.toString('latin1', at + 4, at + 10) === 'Exif\0\0') {
+      return tiffOrientation(buf, at + 10);
+    }
+    at += 2 + length;
+  }
+  return 0;
+}
+
+/** EXIF 里的 TIFF 头 → 朝向值；字节序按 `II` / `MM` 判，读不到返回 0。 */
+function tiffOrientation(buf, base) {
+  if (base + 8 > buf.length) return 0;
+  const order = buf.toString('latin1', base, base + 2);
+  if (order !== 'II' && order !== 'MM') return 0;
+  const little = order === 'II';
+  const u16 = (at) => (little ? buf.readUInt16LE(at) : buf.readUInt16BE(at));
+  const u32 = (at) => (little ? buf.readUInt32LE(at) : buf.readUInt32BE(at));
+  if (u16(base + 2) !== 42) return 0;
+  const ifd = base + u32(base + 4);
+  if (ifd + 2 > buf.length) return 0;
+  const count = u16(ifd);
+  for (let i = 0; i < count; i += 1) {
+    const entry = ifd + 2 + i * 12;
+    if (entry + 12 > buf.length) return 0;
+    if (u16(entry) === 0x0112) {
+      const value = u16(entry + 8);
+      return value >= 1 && value <= 8 ? value : 0;
+    }
+  }
+  return 0;
+}
+
 /** 从文件头解析宽高；认不出来返回 null（不是错误：App 那边照旧现量）。 */
 function imageSizeOf(buf) {
   if (buf.length >= 24 && buf[0] === 0x89 && buf.toString('latin1', 1, 4) === 'PNG') {
@@ -152,6 +202,10 @@ function imageSizeOf(buf) {
     return null;
   }
   if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    // 竖拍照片的像素本身是横的，朝向 5–8 时播放器会转 90° 再画 —— 宽高必须跟着对调，
+    // 否则正文那个盒子是横的、图是竖的（见 jpegOrientation）。
+    const orientation = jpegOrientation(buf);
+    const swap = orientation >= 5 && orientation <= 8;
     let at = 2;
     while (at + 9 < buf.length) {
       if (buf[at] !== 0xff) { at += 1; continue; }
@@ -159,7 +213,9 @@ function imageSizeOf(buf) {
       if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { at += 2; continue; }
       const length = buf.readUInt16BE(at + 2);
       if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
-        return { width: buf.readUInt16BE(at + 7), height: buf.readUInt16BE(at + 5) };
+        const width = buf.readUInt16BE(at + 7);
+        const height = buf.readUInt16BE(at + 5);
+        return swap ? { width: height, height: width } : { width, height };
       }
       if (length < 2) return null;
       at += 2 + length;

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,
+};