dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/jobs.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * 移动端「后台任务」：把宿主会话的 job 视图收敛成手机能画的形状。
+ *
+ * 桌面端会话头部有一个任务触发器（@deepseek-ai/dsh-client-ui-jobs 的
+ * JobListAction）：只在会话真的有 job 时才出现，显示「进行中 N / 共 M」，
+ * 展开是一行一个任务（状态点 + 标签 + 已用时长）。数据源不是某个 RPC，而是
+ * 宿主事件流上的整帧 `session/jobs`：{ type, sessionId, jobs: taskView[] }。
+ *
+ * 手机端此前**一帧都收不到** —— /session/stream 只转发了
+ * session/event / session/queue / session/projection / question / approval，
+ * `session/jobs` 落进了 else 分支被静默丢掉，于是后台任务在手机上是隐形的。
+ *
+ * 宿主已经把帧按 taskViewSchema 校验过，这里只做形状收敛与限长限条数，
+ * 避免异常宿主把手机端列表撑爆。空的 jobs 数组必须原样转发：它是「任务都结束了」
+ * 的唯一信号（宿主在 jobs.onJobsChanged 里就是靠空数组通知清空的）。
+ */
+
+const JOB_MAX_ITEMS = 50;    // 单帧任务条数上限（桌面端也只是个小列表）
+const JOB_ID_MAX = 200;      // 任务 id 长度上限
+const JOB_KIND_MAX = 60;     // 任务种类（bash / workflow…）
+const JOB_LABEL_MAX = 200;   // 任务标题
+const JOB_DETAIL_MAX = 300;  // 任务副标题
+
+/** 宿主 wire 的封闭状态集（dsh-host-apiproxy taskViewSchema）。 */
+const JOB_STATUSES = new Set(['running', 'stopping', 'completed', 'killed', 'failed']);
+
+/** 必填文本：非字符串或全空白 → ''；超长截断（不补省略号，id/kind 不是给人看的）。 */
+function requiredText(value, max) {
+  if (typeof value !== 'string') return '';
+  const text = value.trim();
+  if (!text) return '';
+  return text.length > max ? text.slice(0, max) : text;
+}
+
+/** 可选文本：非法/空白 → undefined；超长截断补省略号。 */
+function optionalText(value, max) {
+  if (typeof value !== 'string') return undefined;
+  const text = value.trim();
+  if (!text) return undefined;
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/** 非负安全整数，否则 undefined。 */
+function optionalCount(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/**
+ * 把一条 taskView 压成手机需要的形状。
+ *
+ * 必填字段（id / kind / label / status / startedAt）任一不合法就丢掉整条：
+ * 缺了状态或开始时间的任务行画出来只会误导用户。
+ * 可选字段（detail / finishedAt）不合法只丢字段、不丢任务：它不影响这一行
+ * 「是什么、还在不在跑」，而状态本身已经说明任务是否结束。
+ */
+function normalizeJob(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const id = requiredText(item.id, JOB_ID_MAX);
+  if (!id) return null;
+  const kind = requiredText(item.kind, JOB_KIND_MAX);
+  if (!kind) return null;
+  const label = requiredText(item.label, JOB_LABEL_MAX);
+  if (!label) return null;
+  if (typeof item.status !== 'string' || !JOB_STATUSES.has(item.status)) return null;
+  const startedAt = optionalCount(item.startedAt);
+  if (startedAt === undefined) return null;
+  const detail = optionalText(item.detail, JOB_DETAIL_MAX);
+  const finishedAt = optionalCount(item.finishedAt);
+  return {
+    id,
+    kind,
+    label,
+    status: item.status,
+    startedAt,
+    ...(detail === undefined ? {} : { detail }),
+    ...(finishedAt === undefined ? {} : { finishedAt }),
+  };
+}
+
+/** 一帧里的任务数组：非数组 → []；坏条目丢掉；按 id 去重（保留先出现的）；限条数。 */
+function normalizeJobs(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of value) {
+    const job = normalizeJob(item);
+    if (!job || seen.has(job.id)) continue;
+    seen.add(job.id);
+    out.push(job);
+    if (out.length >= JOB_MAX_ITEMS) break;
+  }
+  return out;
+}
+
+module.exports = { normalizeJob, normalizeJobs };

package/lib/mobile/local-images.js

@@ -0,0 +1,153 @@
+'use strict';
+
+/**
+ * 正文图片内联：把消息文本里指向**本机文件**的图片语法（`![](/abs/path.png)`）换成 data URI，
+ * 让手机端能直接把它画出来。
+ *
+ * 为什么只能在这里换：手机拿到的只是文本，`/Users/…/a.png` 既不是手机上的文件，移动 API 也
+ * 没有「按路径读文件」的能力面（见 host-bridge-endpoints 守卫的 forbidden 表），所以地址原样
+ * 过去只会显示成一串字面 markdown。会话里用户自己发的图片本来就是内联形状（宿主把附件解成
+ * base64，见 attachments.js 与 App 侧 chat.ts 的 images[]），这里只是把「正文里写的本机图片」
+ * 拉齐到同一种形状，App 侧因此不需要新增任何通道或依赖。
+ *
+ * 保守取舍（宁可保留原样的字面 markdown，也不给个半截东西）：
+ * - 只认能解析成**绝对路径**的地址：`/x/y.png`、`file:///x/y.png`、`~/y.png`；
+ *   http(s)、`data:`、`www.`、相对路径一律不碰。
+ * - 只认 png/jpg/jpeg/webp/gif（与 app/src/services/viewmodels/image-limits.ts 的 mediaTypes
+ *   同白名单），并且**核对魔术字节**：字节不是图片就放弃，绝不按扩展名撒谎。
+ * - 三级体积预算（单图 / 单段文本 / 单次响应，见下方常量）：超预算的图保持字面 markdown，
+ *   不截断、不缩水成半张图。
+ * - 读不到、不是普通文件、读取失败：原样保留 —— 一条图片取不到不能让整段历史或整帧 SSE 挂掉。
+ */
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * `![alt](dest)`。dest 两种写法都认：裸路径（不含空白与右括号）与 `<>` 包裹（里面可以有空格，
+ * 因为 `![](</a b/图 1.png>)` 是 CommonMark 唯一能给带空格路径的合法写法，而 App 侧解析器认它
+ * ——两边必须一致，否则「App 解析得出地址、插件却没内联」会变成一串死链接）。
+ * 括号内的首尾空白照 mdast 的做法忽略。
+ */
+const IMAGE_RE = /!\[([^\]]*)\]\(\s*(<[^>\n]*>|[^)\s]+)\s*\)/g;
+
+/** 图片类型白名单：扩展名 → mediaType。 */
+const MEDIA_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+/** 单张原图上限（base64 后约 1.33 倍，见下面的字符预算）。 */
+const MAX_IMAGE_BYTES = 2.5 * 1024 * 1024;
+/** 一段文本里内联进去的 data URI 总字符上限。 */
+const MAX_TEXT_CHARS = 3 * 1024 * 1024;
+/** 一次响应（一页历史 / 一帧 SSE / 一次镜像快照）共用的字符上限。 */
+const MAX_RESPONSE_CHARS = 5 * 1024 * 1024;
+/** data URI 复用条数：同一张图常在同一轮里出现多次（历史 + 流式 + 镜像）。 */
+const MAX_CACHE_ENTRIES = 8;
+
+/** path+mtime+size → data URI。会话里同一张图会被反复解析，但文件内容只读一次。 */
+const cache = new Map();
+
+function mediaTypeFor(filePath) {
+  return MEDIA_TYPES[path.extname(filePath).toLowerCase()] || null;
+}
+
+/** 魔术字节判定：只认我们真的能画的那四种位图，不信扩展名。 */
+function sniffMediaType(buf) {
+  if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'image/png';
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
+  if (buf.length >= 6 && buf.toString('latin1', 0, 6).startsWith('GIF8')) return 'image/gif';
+  if (buf.length >= 12 && buf.toString('latin1', 0, 4) === 'RIFF' && buf.toString('latin1', 8, 12) === 'WEBP') return 'image/webp';
+  return null;
+}
+
+/**
+ * `![](…)` 里的地址 → 本机绝对路径；不是本机图片（远程、data、相对路径、非图片后缀）返回 null。
+ * 尖括号包裹的目的地（CommonMark 允许 `![](</abs/a.png>)`）在这里一并剥掉。
+ */
+function localImagePathOf(url) {
+  if (typeof url !== 'string') return null;
+  let value = url.trim();
+  if (!value) return null;
+  if (value.startsWith('<') && value.endsWith('>')) value = value.slice(1, -1).trim();
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+    if (value.slice(0, 7).toLowerCase() !== 'file://') return null;
+    try {
+      value = decodeURIComponent(value.slice(7));
+    } catch {
+      return null;
+    }
+    if (value.startsWith('localhost/')) value = value.slice('localhost'.length);
+  } else if (value === '~' || value.startsWith('~/')) {
+    value = path.join(os.homedir(), value.slice(1));
+  }
+  if (!path.isAbsolute(value)) return null;
+  if (!mediaTypeFor(value)) return null;
+  return path.normalize(value);
+}
+
+/** 一次响应共用的内联预算；不给就按单次调用算一份。 */
+function createTextImageBudget(limit = MAX_RESPONSE_CHARS) {
+  return { remaining: limit };
+}
+
+/** 读文件 → data URI（带缓存）；不满足条件一律 null。 */
+async function dataUriFor(filePath) {
+  let stat;
+  try {
+    stat = await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_IMAGE_BYTES) return null;
+  const key = `${filePath}:${stat.size}:${stat.mtimeMs}`;
+  const hit = cache.get(key);
+  if (hit) {
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+  }
+  let buf;
+  try {
+    buf = await fs.readFile(filePath);
+  } catch {
+    return null;
+  }
+  const mediaType = sniffMediaType(buf);
+  if (!mediaType) return null;
+  const uri = `data:${mediaType};base64,${buf.toString('base64')}`;
+  cache.set(key, uri);
+  while (cache.size > MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value);
+  return uri;
+}
+
+/**
+ * 把一段文本里的本机图片语法换成 data URI。返回原字符串本身（`===`）表示一个字没动，
+ * 调用方据此免掉不必要的对象拷贝。
+ */
+async function inlineTextImages(text, budget) {
+  if (typeof text !== 'string' || text.indexOf('![') < 0) return text;
+  const matches = [...text.matchAll(IMAGE_RE)];
+  if (!matches.length) return text;
+  const pool = budget || createTextImageBudget();
+  let textBudget = MAX_TEXT_CHARS;
+  let out = text;
+  for (const m of matches) {
+    if (textBudget <= 0 || pool.remaining <= 0) break;
+    const filePath = localImagePathOf(m[2]);
+    if (!filePath) continue;
+    const uri = await dataUriFor(filePath);
+    if (!uri || uri.length > textBudget || uri.length > pool.remaining) continue;
+    textBudget -= uri.length;
+    pool.remaining -= uri.length;
+    out = out.replace(m[0], `![${m[1]}](${uri})`);
+  }
+  return out === text ? text : out;
+}
+
+module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf };

package/lib/mobile/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/mobile/plugins.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * 移动端「插件清单」API：把桌面端 设置 → 插件 的只读快照搬到手机上。
+ *
+ * 桌面端由 dsh-client-ui-settings-plugin-inventory 渲染：一个可搜索的紧凑卡片列表，
+ * 每张卡片用模块短名作标题、用小标签表示有效启停、用彩色圆点表示根 fiber 状态，
+ * 展开后展示 Loader 条目 id 与 Cordis 状态；选中该标签页时才懒调用一次
+ * `ctx.remote.pluginInventory.list()`，不订阅 Loader 变化（重新打开设置才取新快照）。
+ *
+ * 关键：这个宿主服务 **不在 apiProxy 上** —— 它是 Typert Remote 服务
+ * （dsh-host-plugin-inventory 的 pluginInventory）。手机侧本来就能到它：
+ * lib/mobile/sessions.js 早已用 `ctx.get('typertGateway')` 派发 commands.execute，
+ * lib/mobile/references.js 通了 fileReferences / sessionReferenceResolver，
+ * 这里照搬同一条路。
+ *
+ * 接口（只转发宿主的部署快照，不做任何加工）：
+ *  - GET /api/mobile/v1/plugins → pluginInventory.list
+ *
+ * 参数：这个方法 **没有声明任何参数**，args 必须是空对象——assertExactArguments
+ * 按声明逐位比对，多给一个字段就会被拒。
+ *
+ * 返回值形状：`gateway.invoke()` 回的是 decode 后的业务结果本体，不是
+ * {ok:true,value} 外壳（那层壳是浏览器传输加的，见 lib/mobile/references.js 里的长注释）。
+ * pluginInventory.list 声明的是 { entries: […] } 对象，所以 invoke 回来就是这个对象。
+ *
+ * 语义按宿主原文透传：
+ *  - moduleName 是 npm 包名（如 @deepseek-ai/dsh-host-directory-picker-native），
+ *    展示用的短名截断属于客户端的事。
+ *  - enabled 是「有效启停状态」，和 fiberPhase 不是一回事：停用的条目 fiberPhase 是 null。
+ *  - fiberPhase 只有 failed/pending/active/loading/unloading 五种，宿主也可能给 null。
+ */
+
+const { sendJson } = require('../shared/http-util');
+
+const PLUGIN_ID_MAX_CHARS = 200;      // entryId 长度上限
+const PLUGIN_NAME_MAX_CHARS = 300;    // moduleName 长度上限
+const PLUGIN_MAX_ITEMS = 500;         // 手机侧兜底上限（真实宿主是几十条）
+const PLUGIN_PHASES = new Set(['failed', 'pending', 'active', 'loading', 'unloading']);
+
+/** 宿主网关；宿主没组合 dsh-api-gateway 时返回 null，调用方回 503。 */
+function gatewayOf(ctx) {
+  return (ctx.get && ctx.get('typertGateway')) || null;
+}
+
+/** 网关缺失/命名空间缺失对客户端是同一件事：宿主这个能力没装。 */
+const UNAVAILABLE = Object.freeze({
+  code: 'plugin-inventory-unavailable',
+  message: '宿主没有组合插件清单服务（dsh-host-plugin-inventory / dsh-api-gateway）',
+});
+
+/** 网关自己抛的错（不是业务失败）的文字化。 */
+function errorText(error) {
+  if (!error) return '未知错误';
+  if (typeof error.message === 'string' && error.message) return error.message;
+  return String(error);
+}
+
+/**
+ * 经 typertGateway 取一次插件清单快照。
+ *
+ * @returns {Promise<{value?: unknown, error?: {code: string, message: string}}>}
+ */
+async function callInventory(ctx) {
+  const gateway = gatewayOf(ctx);
+  if (!gateway) return { error: { ...UNAVAILABLE } };
+  let result;
+  try {
+    // 没有声明参数 → args 必须是空对象；这个方法也没声明 cancellation，不能多塞 signal。
+    result = await gateway.invoke({ namespace: 'pluginInventory', method: 'list', args: {} });
+  } catch (error) {
+    // 0.2.0 的网关错误码带 `gateway/` 前缀（dsh-api-gateway/src/types.ts:117-136）；
+    // 0.1.x 时期是不带前缀的。两种都认，否则「宿主没装这个服务」的降级分支形同虚设。
+    const raw = error && typeof error.code === 'string' ? error.code.replace(/^gateway\//, '') : ''
+    const code = raw === 'invocation-unavailable' || raw === 'service-unavailable' || raw === 'method-unavailable'
+      ? UNAVAILABLE.code
+      : 'plugin-inventory-error';
+    return { error: { code, message: errorText(error) } };
+  }
+  // decode 本体就是 { entries: […] }；另外两种形状只是容错，防宿主以后改成联合。
+  if (result && typeof result === 'object') {
+    if (result.ok === true) return { value: result.value };
+    if (result.ok === false) {
+      const raw = result.error && typeof result.error === 'object' ? result.error : {};
+      const code = typeof raw.code === 'string' && raw.code ? raw.code : 'plugin-inventory-error';
+      return { error: { code, message: errorText(raw) } };
+    }
+    return { value: result };
+  }
+  return { error: { code: 'plugin-inventory-error', message: '宿主插件清单返回了意外的结果' } };
+}
+
+/** 非空字符串、长度受限，否则 null。 */
+function normalizeId(value, max) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text || text.length > max) return null;
+  return text;
+}
+
+/**
+ * 归一化一条清单。entryId 与 moduleName 缺一不可（它们是这张卡的身份与标题）；
+ * fiberPhase 不在枚举里就当 null（桌面端也是「无状态点」的处理）。
+ */
+function normalizePluginEntry(value) {
+  if (!value || typeof value !== 'object') return null;
+  const entryId = normalizeId(value.entryId, PLUGIN_ID_MAX_CHARS);
+  const moduleName = normalizeId(value.moduleName, PLUGIN_NAME_MAX_CHARS);
+  if (!entryId || !moduleName) return null;
+  const fiberPhase = typeof value.fiberPhase === 'string' && PLUGIN_PHASES.has(value.fiberPhase)
+    ? value.fiberPhase
+    : null;
+  return { entryId, moduleName, enabled: value.enabled === true, fiberPhase };
+}
+
+/** 能力缺失 503（客户端据此显示「宿主没装」），其余业务/网关失败 400。 */
+function statusOf(error) {
+  return error && error.code === UNAVAILABLE.code ? 503 : 400;
+}
+
+/**
+ * GET /api/mobile/v1/plugins
+ * 成功：{ ok:true, items:[{ entryId, moduleName, enabled, fiberPhase }] }
+ */
+async function handlePlugins(ctx, req, res) {
+  const result = await callInventory(ctx);
+  if (result.error) return sendJson(res, statusOf(result.error), { ok: false, error: result.error });
+  const raw = result.value && Array.isArray(result.value.entries) ? result.value.entries : [];
+  const items = [];
+  for (const row of raw) {
+    const entry = normalizePluginEntry(row);
+    if (!entry) continue;
+    items.push(entry);
+    if (items.length >= PLUGIN_MAX_ITEMS) break;
+  }
+  sendJson(res, 200, { ok: true, items });
+}
+
+module.exports = {
+  handlePlugins,
+  normalizePluginEntry,
+  normalizeId,
+  statusOf,
+  callInventory,
+  PLUGIN_ID_MAX_CHARS,
+  PLUGIN_NAME_MAX_CHARS,
+  PLUGIN_MAX_ITEMS,
+  PLUGIN_UNAVAILABLE: UNAVAILABLE,
+};

package/lib/mobile/questions.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * dsh-mobile 用户问题回答桥接。
+ *
+ * ask_user_question 通过 apiProxy events mux 以 question/requested 发出，
+ * 原生 App 经本端点回传对应 rpcId 的严格回答载荷。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+
+function validAnswer(answer) {
+  if (!answer || typeof answer.id !== 'string' || !Array.isArray(answer.selected)) return false;
+  if (!answer.selected.every((label) => typeof label === 'string')) return false;
+  return answer.custom === undefined || typeof answer.custom === 'string';
+}
+
+async function handleQuestionRespond(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.rpcId !== 'string' || !body.rpcId || typeof body.sessionId !== 'string' || !body.sessionId) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { rpcId, sessionId, answer }' } });
+  }
+  const answers = body.answer && body.answer.answers;
+  if (!Array.isArray(answers) || !answers.every(validAnswer)) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'answer.answers 格式无效' } });
+  }
+
+  const receipt = await ctx.apiProxy.respond({
+    type: 'client-response',
+    rpcId: body.rpcId,
+    result: {
+      ok: true,
+      value: {
+        sessionId: body.sessionId,
+        answer: {
+          answers: answers.map((answer) => ({
+            id: answer.id,
+            selected: answer.selected,
+            ...(answer.custom === undefined ? {} : { custom: answer.custom }),
+          })),
+        },
+      },
+    },
+  });
+  if (!receipt || receipt.accepted !== true) {
+    return sendJson(res, 409, { ok: false, error: { code: 'not-pending', message: '该问题已完成或不可回答' } });
+  }
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+async function handleApprovalRespond(ctx, req, res) {
+  const body = await readJsonBody(req);
+  const outcomes = new Set(['allowed-once', 'rejected']);
+  if (!body || typeof body.rpcId !== 'string' || !body.rpcId
+    || typeof body.sessionId !== 'string' || !body.sessionId
+    || typeof body.approvalId !== 'string' || !body.approvalId
+    || !outcomes.has(body.outcome)) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { rpcId, sessionId, approvalId, outcome }' } });
+  }
+  const receipt = await ctx.apiProxy.respond({
+    type: 'client-response',
+    rpcId: body.rpcId,
+    result: { ok: true, value: { sessionId: body.sessionId, approvalId: body.approvalId, outcome: body.outcome } },
+  });
+  if (!receipt || receipt.accepted !== true) {
+    return sendJson(res, 409, { ok: false, error: { code: 'not-pending', message: '该审批已完成或不可回答' } });
+  }
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+module.exports = { handleQuestionRespond, handleApprovalRespond };