dsh-mobile-plugin 0.5.14 → 0.5.15

package/lib/mobile/approvals.js

@@ -156,6 +156,20 @@ function hasPending(sessionId) {
   return openEntries(sessionId).length > 0;
 }
 
+/**
+ * 这条会话此刻挂着的审批卡（形状与推送帧一字不差），没有就 undefined。
+ *
+ * 与提问桥的 `pendingCardOf` 同一用途：手机回前台时先问原生要卡，不必等流重新接上
+ * （见 `questions.js` 那一处的说明）。只认已绑定的项 —— 与 `attachSession` 的补发口径
+ * 一致：没绑上钩子的卡答不动，送上去只会让人点出一个 409。
+ */
+function pendingCardOf(sessionId) {
+  for (const entry of openEntries(sessionId)) {
+    if (entry.bound) return cardFrame(entry);
+  }
+  return undefined;
+}
+
 /** 测试用：清空全部进程内状态（真实运行时由插件卸载时的 disposer 收尾）。 */
 function resetForTest() {
   watchers.clear();
@@ -367,5 +381,6 @@ module.exports = {
   handleApprovalRespond,
   attachSession,
   hasPending,
+  pendingCardOf,
   resetForTest,
 };

package/lib/mobile/canvas-store.js

@@ -0,0 +1,365 @@
+'use strict';
+
+/**
+ * 无限画布的库（`/api/mobile/v1/canvas/*`）。
+ *
+ * 为什么要有它：画布整个活在 App 的 WebView 里，项目和素材全在页面的 IndexedDB 中 ——
+ * 清一次缓存、换一台手机就没了，桌面端也看不见。这个模块把「库」搬到宿主机上，App 负责
+ * 把本机那份推上来、把远端那份拉下去，桌面端以后读的是同一份。
+ *
+ * 存两样东西，各管一件事：
+ *  · **清单**（每个域一份 JSON）：项目图、资产行、工作台记录这些「结构」，加上一份
+ *    `files: [{storageKey, hash, mimeType, bytes}]` —— 结构里引用了哪些字节、各是哪一份。
+ *  · **字节**（`objects/<哈希前两位>/<其余>`）：按内容哈希落盘，只增不改。同一个 storageKey
+ *    在手机上是不可变的（键是随机串），所以判「要不要传」只看远端清单里有没有这个键。
+ *
+ * 清单永远在字节之后写：先传缺的文件、再写清单。写清单这一步会逐个 stat 文件，缺一个就
+ * 整份拒绝（`missing-file`）—— 一份指向不存在字节的清单在手机上表现为「画布能打开、图全是
+ * 坏的」，而且它会把下一次同步判成「已同步」，坏得无声无息。
+ *
+ * 能力面：只有一个固定目录，**客户端给不了任何路径**，也只会拿到哈希。文件名是 64 位十六
+ * 进制（不是哈希形状的一律不认，顺带挡住路径穿越），与分片上传那条通道同一口径。
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { pipeline } = require('node:stream/promises');
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { dshHome } = require('../shared/paths.js');
+const { writeEncryptedFile, encryptedLengthOf } = require('./session-file.js');
+
+/**
+ * 四个域与画布自己的同步引擎一一对应（`app/vendor/canvas-src` 的 app-sync）。
+ *
+ * 域是清单的分片，不是权限：每个域一份文件，谁变了推谁，别把整库塞进一份 JSON。
+ */
+const DOMAINS = new Set(['canvas', 'assets', 'image-workbench', 'video-workbench']);
+
+/** 清单请求体上限（**明文**字节）：与分片上传同一个 8MB 预算，够装几万个节点。 */
+const MAX_MANIFEST_BYTES = Math.ceil(8 * 1024 * 1024 * 4 / 3);
+/** 一份清单最多认多少个文件条目：再多也传不完，早报错比传到一半失败好。 */
+const MAX_FILES = 20000;
+/** 单份字节的上限：与「会话文件」同一条口径，超过的整份传不回来。 */
+const MAX_OBJECT_BYTES = 512 * 1024 * 1024;
+/** 内容哈希：64 位小写十六进制。别的形状一律不认（这一条同时挡住路径穿越）。 */
+const HASH_RE = /^[0-9a-f]{64}$/;
+/** storageKey 只当清单里的键用、不拼路径，但仍然要求是干净的字符串。 */
+const STORAGE_KEY_MAX = 300;
+/** 清单版本号取内容哈希的前 16 位：同一份内容算出同一个号，不需要另存一个自增计数。 */
+const REVISION_CHARS = 16;
+
+/** 库根：插件自己的数据目录，`DSH_MOBILE_CANVAS` 只给测试用。 */
+function rootDir() {
+  return process.env.DSH_MOBILE_CANVAS || path.join(dshHome(), 'storages', 'mobile-plugin', 'canvas');
+}
+
+/** 某个域的清单文件。 */
+function manifestPath(domain) {
+  return path.join(rootDir(), `manifest-${domain}.json`);
+}
+
+/** 字节区根。 */
+function objectsRoot() {
+  return path.join(rootDir(), 'objects');
+}
+
+/**
+ * 哈希 → 盘上路径。形状不对回 null：这个值要拼进文件路径，校验放在这里，不靠调用方记得。
+ */
+function objectPathOf(hash) {
+  if (typeof hash !== 'string' || !HASH_RE.test(hash)) return null;
+  return path.join(objectsRoot(), hash.slice(0, 2), hash.slice(2));
+}
+
+/** 域 → 规范值；不认识回 null。 */
+function domainOf(value) {
+  const domain = typeof value === 'string' ? value.trim() : '';
+  return DOMAINS.has(domain) ? domain : null;
+}
+
+/** 内容 → 版本号（内容变了才对不上，所以不需要另记时间）。 */
+function revisionOf(payload) {
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, REVISION_CHARS);
+}
+
+/**
+ * 读某个域的清单。没有回 null；盘上有但读不懂**如实抛**，不当成「没有」——
+ * 当成没有会让手机把本机那份推上来，把远端那份直接盖掉（那是最不该发生的静默失败）。
+ */
+async function readManifest(domain) {
+  let text;
+  try {
+    text = await fsp.readFile(manifestPath(domain), 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw Object.assign(new Error(`读画布清单失败：${error.message}`), { code: 'canvas-store-unavailable' });
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || parsed.domain !== domain) throw new Error('形状不对');
+    return parsed;
+  } catch (error) {
+    throw Object.assign(new Error(`画布清单已损坏（${domain}）：${error.message}`), { code: 'manifest-corrupt' });
+  }
+}
+
+/** 哈希对应的字节在不在盘上（清单落盘之前要逐个确认）。 */
+async function objectExists(hash) {
+  const target = objectPathOf(hash);
+  if (!target) return false;
+  try {
+    const info = await fsp.stat(target);
+    return info.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 校验并规范化一份要写进来的清单。
+ *
+ * @returns {{ status: number, code: string, message: string, missing?: string[] } | { files: Array<object>, data: unknown }}
+ */
+function normalizePayload(body) {
+  const domain = domainOf(body.domain);
+  if (!domain) return { status: 400, code: 'bad-domain', message: 'domain 只能是 canvas / assets / image-workbench / video-workbench' };
+  if (!body.data || typeof body.data !== 'object' || Array.isArray(body.data)) {
+    return { status: 400, code: 'bad-data', message: '需要 { data }（一个对象）' };
+  }
+  const rawFiles = body.files === undefined ? [] : body.files;
+  if (!Array.isArray(rawFiles)) return { status: 400, code: 'bad-files', message: 'files 必须是数组' };
+  if (rawFiles.length > MAX_FILES) {
+    return { status: 413, code: 'too-many-files', message: `一份清单最多 ${MAX_FILES} 个文件` };
+  }
+  // 同一个 storageKey 只留最后一条：清单是整份替换的，重复条目只会在下发时变成两行。
+  const byKey = new Map();
+  for (const item of rawFiles) {
+    if (!item || typeof item !== 'object') return { status: 400, code: 'bad-files', message: 'files 里每一项都得是对象' };
+    const storageKey = typeof item.storageKey === 'string' ? item.storageKey : '';
+    if (!storageKey || storageKey.length > STORAGE_KEY_MAX || /[\u0000-\u001f\u007f]/.test(storageKey)) {
+      return { status: 400, code: 'bad-files', message: 'storageKey 必须是 1..300 个可见字符' };
+    }
+    if (!HASH_RE.test(String(item.hash || ''))) {
+      return { status: 400, code: 'bad-files', message: `文件 ${storageKey} 的 hash 不是 64 位十六进制` };
+    }
+    const bytes = Number(item.bytes);
+    if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > MAX_OBJECT_BYTES) {
+      return { status: 400, code: 'bad-files', message: `文件 ${storageKey} 的字节数不合法` };
+    }
+    const mimeType = typeof item.mimeType === 'string' ? item.mimeType.slice(0, 120) : 'application/octet-stream';
+    byKey.set(storageKey, { storageKey, hash: String(item.hash), mimeType, bytes });
+  }
+  return { files: [...byKey.values()], data: body.data };
+}
+
+/**
+ * 写清单：先确认每个哈希都在盘上，再整份原子替换。
+ *
+ * 为什么逐个 stat：清单是「库里有哪些字节」的账，账上有一笔盘上没有的单子，手机下次同步会
+ * 因为「清单里有」而不再上传，那张图标就一直坏着。
+ */
+async function writeManifest(domain, data, files) {
+  const missing = [];
+  for (const file of files) {
+    if (!(await objectExists(file.hash))) missing.push(file.storageKey);
+  }
+  if (missing.length) {
+    const shown = missing.slice(0, 5).join('、');
+    return {
+      status: 409,
+      code: 'missing-file',
+      message: `这些文件还没传上来：${shown}${missing.length > 5 ? ` 等 ${missing.length} 个` : ''}`,
+      missing,
+    };
+  }
+  const revision = revisionOf({ data, files });
+  const manifest = {
+    app: 'infinite-canvas',
+    version: 1,
+    domain,
+    revision,
+    updatedAt: new Date().toISOString(),
+    data,
+    files,
+  };
+  const target = manifestPath(domain);
+  const tmp = `${target}.tmp-${crypto.randomBytes(6).toString('hex')}`;
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  try {
+    await fsp.writeFile(tmp, JSON.stringify(manifest), 'utf8');
+    // 原子替换：手机随时可能来读，读到的要么是上一份、要么是这一份。
+    await fsp.rename(tmp, target);
+  } catch (error) {
+    try { await fsp.unlink(tmp); } catch { /* 已经不在了 */ }
+    throw Object.assign(new Error(`写画布清单失败：${error.message}`), { code: 'canvas-store-unavailable' });
+  }
+  return { revision, updatedAt: manifest.updatedAt, files: files.length };
+}
+
+/** 一份文件的 sha256（流式，不把整份读进内存）。 */
+function sha256OfFile(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath, { highWaterMark: 256 * 1024 });
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+/**
+ * 把一份刚落进暂存区的字节收进库里，回它的哈希。
+ *
+ * 分片上传（`uploads.js`）传完一份画布素材就交给这里：算哈希 → 落进 objects。同内容的文件
+ * 已经在库里就直接丢暂存的那份 —— 画布里的图经常是同一张被引用了好几次，哈希天然去重。
+ *
+ * @returns {Promise<{ hash: string, bytes: number }>}
+ */
+async function storeUploadedFile(stagingPath) {
+  const info = await fsp.stat(stagingPath);
+  if (info.size > MAX_OBJECT_BYTES) {
+    const error = Object.assign(new Error('这份文件太大，画布库装不下'), { code: 'too-large', status: 413 });
+    throw error;
+  }
+  const hash = await sha256OfFile(stagingPath);
+  const target = objectPathOf(hash);
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  if (await objectExists(hash)) {
+    try { await fsp.unlink(stagingPath); } catch { /* 已经不在了 */ }
+    return { hash, bytes: info.size };
+  }
+  try {
+    await fsp.rename(stagingPath, target);
+  } catch {
+    // 跨设备（暂存根被 `DSH_MOBILE_INBOX` 挪到别的盘）时 rename 会 EXDEV：复制一份再删。
+    await fsp.copyFile(stagingPath, target);
+    try { await fsp.unlink(stagingPath); } catch { /* 已经不在了 */ }
+  }
+  return { hash, bytes: info.size };
+}
+
+/**
+ * GET /api/mobile/v1/canvas/manifest?domain=canvas&rev=<版本号>
+ *
+ * 带 `rev` 且与盘上那份一致时只回一句 `unchanged` —— 画布每开一次就同步一次，稳态那一发
+ * 不该把整份项目图再传一遍（跟会话列表那条条件刷同一个口径）。
+ */
+async function handleCanvasManifestGet(_ctx, req, res) {
+  const query = new URL(req.url || '/', 'http://x').searchParams;
+  const domain = domainOf(query.get('domain'));
+  if (!domain) return sendJson(res, 400, { ok: false, error: { code: 'bad-domain', message: 'domain 只能是 canvas / assets / image-workbench / video-workbench' } });
+  let manifest;
+  try {
+    manifest = await readManifest(domain);
+  } catch (error) {
+    return sendJson(res, 500, { ok: false, error: { code: (error && error.code) || 'canvas-store-unavailable', message: String(error && error.message) } });
+  }
+  if (!manifest) return sendJson(res, 200, { ok: true, domain, revision: null, empty: true, files: [] });
+  const rev = String(query.get('rev') || '');
+  if (rev && rev === manifest.revision) {
+    return sendJson(res, 200, { ok: true, domain, revision: manifest.revision, updatedAt: manifest.updatedAt, unchanged: true });
+  }
+  sendJson(res, 200, {
+    ok: true,
+    domain,
+    revision: manifest.revision,
+    updatedAt: manifest.updatedAt,
+    data: manifest.data,
+    files: Array.isArray(manifest.files) ? manifest.files : [],
+  });
+}
+
+/**
+ * POST /api/mobile/v1/canvas/manifest { domain, data, files }
+ *
+ * 整份替换、不做字段级合并：合并是客户端的事（它手上有本机那份，也有刚拉下去的远端那份）。
+ * 宿主只负责「存下来、版本号算清楚、缺字节就拒绝」。
+ */
+async function handleCanvasManifestSave(_ctx, req, res) {
+  const body = await readJsonBody(req, MAX_MANIFEST_BYTES);
+  if (!body || typeof body !== 'object') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '请求体不是合法 JSON，或超过体积上限' } });
+  }
+  const normalized = normalizePayload(body);
+  if (normalized.status) {
+    return sendJson(res, normalized.status, { ok: false, error: { code: normalized.code, message: normalized.message, ...(normalized.missing ? { missing: normalized.missing } : {}) } });
+  }
+  let result;
+  try {
+    result = await writeManifest(domainOf(body.domain), normalized.data, normalized.files);
+  } catch (error) {
+    return sendJson(res, 500, { ok: false, error: { code: (error && error.code) || 'canvas-store-unavailable', message: String(error && error.message) } });
+  }
+  if (result.status) {
+    return sendJson(res, result.status, { ok: false, error: { code: result.code, message: result.message, ...(result.missing ? { missing: result.missing } : {}) } });
+  }
+  sendJson(res, 200, { ok: true, domain: domainOf(body.domain), revision: result.revision, updatedAt: result.updatedAt, files: result.files });
+}
+
+/**
+ * POST /api/mobile/v1/canvas/file { hash } → 那份字节。
+ *
+ * 按哈希取、不按路径：客户端构造不出一个能读到别的东西的请求。响应形状与 `/session/file`
+ * 逐字节同形（含协议 v2 的分块信封与 `content-length`）—— 手机那边用的是同一个原生下载器，
+ * 换一个形状就要在 App 里再写一条下载路。
+ */
+async function handleCanvasFile(_ctx, req, res) {
+  const body = await readJsonBody(req);
+  const hash = body && typeof body.hash === 'string' ? body.hash.trim().toLowerCase() : '';
+  const target = objectPathOf(hash);
+  if (!target) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { hash }（64 位十六进制）' } });
+  }
+  let info;
+  try {
+    info = await fsp.stat(target);
+  } catch {
+    return sendJson(res, 404, { ok: false, error: { code: 'missing', message: '这份字节不在电脑上了' } });
+  }
+  if (!info.isFile()) {
+    return sendJson(res, 404, { ok: false, error: { code: 'missing', message: '这份字节不在电脑上了' } });
+  }
+
+  const header = { 'content-type': 'application/octet-stream', 'cache-control': 'no-store' };
+  const opened = req && req.__dshE2ee;
+  if (opened && opened.keys && opened.req) {
+    res.writeHead(200, {
+      ...header,
+      'content-type': 'application/x-dsh-e2ee-chunks',
+      'content-length': String(encryptedLengthOf(info.size)),
+      'x-dsh-file-size': String(info.size),
+      'x-dsh-proto': '2',
+      'x-dsh-content-type': 'application/octet-stream',
+    });
+    await writeEncryptedFile(req, res, target, opened);
+    return;
+  }
+
+  res.writeHead(200, { ...header, 'content-length': String(info.size) });
+  if (info.size === 0) return res.end();
+  const stream = fs.createReadStream(target);
+  res.on('close', () => stream.destroy());
+  try {
+    await pipeline(stream, res);
+  } catch {
+    // 头已经发出去了，改不了状态码，只能断开让对端按截断处理（与会话文件那条一致）。
+    try { res.destroy(); } catch { /* 连接已关闭 */ }
+  }
+}
+
+module.exports = {
+  DOMAINS,
+  MAX_OBJECT_BYTES,
+  rootDir,
+  objectPathOf,
+  objectExists,
+  readManifest,
+  writeManifest,
+  storeUploadedFile,
+  handleCanvasManifestGet,
+  handleCanvasManifestSave,
+  handleCanvasFile,
+};

package/lib/mobile/monitor.js

@@ -26,7 +26,7 @@ const {
 const { updateCompletionStates, confirmCompletionFromHistory } = require('./completion.js');
 const { lastTurnOf } = require('./session-last-turn.js');
 const { sessionPreviewFor } = require('./session-preview.js');
-const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags.js');
+const { workspaceSessionFlags, pendingInteractionOf, pendingCardOf } = require('./session-flags.js');
 
 /**
  * 一条会话在监控视图里的那几格。
@@ -35,8 +35,10 @@ const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags
  * lastTurnError），因为原生那边解析的是同一套字段：换名字就得同步改 Kotlin，而那段代码
  * 在 App 之外，改错一次是「后台永远不提醒」这种看不见的故障。
  *
- * 另有一个可选字段 `lastMessage`：只给可能要提醒的那几条带上一句「这一轮跑出了什么」，
- * 供原生完成提醒的横幅正文用；拿不到预览就不出这个字段。
+ * 另有两个可选字段：`lastMessage` 只给可能要提醒的那几条带上一句「这一轮跑出了什么」，
+ * 供原生完成提醒的横幅正文用；`pendingCard` 是**等你处理的那张卡本身**（与实时流推的帧
+ * 一字不差），只在那几条待处理的条目上带 —— 手机回前台时先问原生要它，就不必等流重新
+ * 接上才有卡（见 `session-flags.js` 的 pendingCardOf）。拿不到都不出字段。
  */
 function monitorItem(summary, state, fact) {
   const running = summary.running === true;
@@ -60,7 +62,19 @@ function monitorItem(summary, state, fact) {
     completed,
   };
   const pending = pendingInteractionOf(summary.sessionId, summary);
-  if (pending) item.pendingInteraction = pending;
+  if (pending) {
+    item.pendingInteraction = pending;
+    // 卡的内容跟着一起走：它在上面这个判据之外没有第二条路能到手机上（推送只在流接入时
+    // 补发一次）。进指纹是名正言顺的 —— 换一道新题就是真的变了，原生那一拍该被唤醒。
+    const card = pendingCardOf(summary.sessionId, summary);
+    if (card) item.pendingCard = card;
+  } else {
+    // **显式写 null**：原生那头靠「这一格在不在」判「这台宿主认不认识它」，并据此决定
+    // 要不要把「看过了、没有挂起」记成账。不在就永远是「不知道」，回前台也就永远撤不掉
+    // 那张已经在电脑上答掉的旧卡。待处理但没有帧可给（0.1.x 摘要自带口径）时仍然不写，
+    // 那格含义是「不知道」，不是「没有」。
+    item.pendingCard = null;
+  }
   const failure = fact
     ? (fact.status === 'failed' && settledForThisDevice
       ? { turn: fact.turn, code: fact.code ?? null, message: fact.message ?? null }
@@ -74,6 +88,11 @@ function monitorItem(summary, state, fact) {
       turn: fact.turn,
       endedAt: fact.endedAt,
       status: fact.status,
+      // 这一轮是不是**已经有人读过了**（桌面 / 另一台手机 / 这台都算）。与设备无关的
+      // 事实，跟着事实走；上面那个 `completed` 用的是按设备的 `clearedAt`，而桌面点开
+      // 只看 `/api/relay/desktop-read`，它不动那个水位 —— 后台把「已经看过的这一轮」
+      // 弹出来之后，只有这个水位能让它自己消失（见原生那条撤销）。
+      ...(typeof fact.readAt === 'number' && fact.readAt > 0 ? { readAt: fact.readAt } : {}),
       ...(fact.status === 'failed' ? { code: fact.code ?? null, message: fact.message ?? null } : {}),
     };
   }

package/lib/mobile/questions.js

@@ -157,6 +157,20 @@ function attachSession(sessionId, sink) {
   };
 }
 
+/**
+ * 这条会话此刻挂着的提问卡（形状与推送帧一字不差），没有就 undefined。
+ *
+ * 给 `/monitor` 用：手机回前台时可以**先问原生要这张卡**，不必等流重新接上。挂起项本来
+ * 只在进程内、推送只有「接入补发」那一次，回前台那条重连一旦落空卡就缺到下次重进对话；
+ * 让后台轮询顺手把卡的内容带回去，这条缺口才补得上。
+ */
+function pendingCardOf(sessionId) {
+  for (const entry of openEntries(sessionId)) {
+    if (entry.bound) return cardFrame(entry);
+  }
+  return undefined;
+}
+
 /** 会话摘要里的待处理标记（0.2.x 的宿主不会再下发这个字段，见 sessions.js 的用法）。 */
 function pendingKind(sessionId) {
   const open = openEntries(sessionId);
@@ -371,5 +385,6 @@ module.exports = {
   handleQuestionRespond,
   attachSession,
   pendingKind,
+  pendingCardOf,
   resetForTest,
 };

package/lib/mobile/session-flags.js

@@ -54,4 +54,22 @@ function pendingInteractionOf(sessionId, summary) {
   return questions.pendingKind(sessionId);
 }
 
-module.exports = { workspaceSessionFlags, pendingInteractionOf };
+/**
+ * 这条会话挂着的卡**本身**（推送帧原样），拿不到就 undefined。
+ *
+ * 给 `/monitor` 用：手机上那张「等你回答 / 等你审批」的卡只有一条来路 —— 实时流重新
+ * 接上时插件的补发。回前台那条重连一旦落空（退避中、宿主把流收了、网络还没被采纳），
+ * 卡就缺到用户切一次会话为止。后台轮询顺手把卡的内容一起带回去，回前台问原生就能取到，
+ * 不必等网络。审批优先，与 `pendingInteractionOf` 同序 —— 两处判据分家会让「黄点写着
+ * 审批、卡片却是提问」。
+ *
+ * 摘要自己带了 `pendingInteraction`（0.1.x / 桌面口径）时没帧可给：那时候的卡是宿主
+ * 直接推的，本桥手上没有。
+ */
+function pendingCardOf(sessionId, summary) {
+  const reported = summary && summary.pendingInteraction;
+  if (reported === 'approval' || reported === 'plan-review' || reported === 'question') return undefined;
+  return approvals.pendingCardOf(sessionId) || questions.pendingCardOf(sessionId);
+}
+
+module.exports = { workspaceSessionFlags, pendingInteractionOf, pendingCardOf };

package/lib/mobile/uploads.js

@@ -39,6 +39,7 @@ const { sendJson, readJsonBody, readRawBody } = require('../shared/http-util');
 // 头名的大小写不保证（中转会压成小写，Node 版本之间也有差异），复用信封那一份读法。
 const { headerOf } = require('../shared/e2ee-request');
 const { allowedRoots, inAllowedZone } = require('./allowed-zone.js');
+const canvasStore = require('./canvas-store.js');
 
 // 片大小的**起步值** 256KB（base64 后约 341KB）：客户端一次请求的硬预算是 8s
 // （`app/src/api/core.ts` 的 REQUEST_TIMEOUT_MS），一上来就给大片的机器会在慢速上行
@@ -108,7 +109,10 @@ function rememberFinishedUpload(uploadId, record) {
 /**
  * 按 uploadId 取刚落盘的上传。过期 / 不存在返回 null。
  *
- * @returns {{ path: string, name: string, bytes: number } | null}
+ * 记录有两种：收件箱那份带 `path`（图片内联要用它），画布素材那份带 `hash`（没有路径 ——
+ * 画布库只按内容哈希认文件）。两种都要能原样回放给重收一次口的客户端。
+ *
+ * @returns {{ path?: string, hash?: string, purpose?: string, name: string, bytes: number } | null}
  */
 function resolveFinishedUpload(uploadId) {
   const id = String(uploadId || '');
@@ -118,7 +122,8 @@ function resolveFinishedUpload(uploadId) {
     finishedUploads.delete(id);
     return null;
   }
-  return { path: record.path, name: record.name, bytes: record.bytes };
+  const { at, ...rest } = record;
+  return rest;
 }
 
 /**
@@ -345,8 +350,16 @@ async function handleUploadBegin(ctx, req, res) {
   }
   const caps = resolveCaps(body);
   if (caps.status) return fail(res, caps.status, caps.code, caps.message);
+  // 画布库的素材也走这条通道（`purpose: 'canvas'`）：传完不落收件箱，而是按内容哈希收进
+  // 画布库（见 `canvas-store.js`）。它与 `destPath` 互斥：一个是「收件箱里的一份文件」，
+  // 一个是「库里的一份字节」，同时给说明调用方把两件事搞混了。
+  const purpose = body.purpose === undefined || body.purpose === null ? '' : String(body.purpose);
+  if (purpose && purpose !== 'canvas') return fail(res, 400, 'bad-purpose', 'purpose 只认 canvas');
+  if (purpose && body.destPath !== undefined && body.destPath !== null) {
+    return fail(res, 400, 'bad-request', 'purpose 与 destPath 不能同时给');
+  }
   // 落点先判：越界 / 不是目录在这一步就回，不先建暂存再报错 —— 残片要躺满 7 天才清。
-  const destination = await resolveDestDir(ctx, body);
+  const destination = purpose ? { dir: '' } : await resolveDestDir(ctx, body);
   if (destination.status) return fail(res, destination.status, destination.code, destination.message);
   const stagingDir = path.join(inboxRoot(), '.staging');
   try {
@@ -366,6 +379,8 @@ async function handleUploadBegin(ctx, req, res) {
   }
   const job = {
     name: sanitizeName(body.name),
+    // 画布素材：finish 时按内容哈希收进画布库，不进收件箱（见 `canvas-store.js`）。
+    purpose,
     // 指定落点就记在这里，finish 才用得上（中途不再判一次范围：begin 已经认过）。
     destDir: destination.dir,
     stagingPath,
@@ -560,6 +575,9 @@ async function handleUploadFinish(_ctx, req, res) {
   const job = uploads.get(uploadId);
   if (!job) {
     const replay = resolveFinishedUpload(uploadId);
+    if (replay && replay.purpose === 'canvas') {
+      return sendJson(res, 200, { ok: true, hash: replay.hash, bytes: replay.bytes, name: replay.name, uploadId });
+    }
     if (replay) return sendJson(res, 200, { ok: true, ...replay, uploadId });
     return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
   }
@@ -574,6 +592,19 @@ async function handleUploadFinish(_ctx, req, res) {
   }
   removeUpload(uploadId, job);
 
+  // 画布素材：不进收件箱，按内容哈希收进画布库，回哈希而不是路径（客户端拿不到也拼不出路径）。
+  if (job.purpose === 'canvas') {
+    try {
+      const stored = await canvasStore.storeUploadedFile(job.stagingPath);
+      // 与收件箱那条同一个理由：回包丢了，手机只会拿同一个 uploadId 再收一次口。
+      rememberFinishedUpload(uploadId, { purpose: 'canvas', hash: stored.hash, bytes: stored.bytes, name: job.name });
+      return sendJson(res, 200, { ok: true, hash: stored.hash, bytes: stored.bytes, name: job.name, uploadId });
+    } catch (error) {
+      try { await fsp.unlink(job.stagingPath); } catch { /* 已经不在了 */ }
+      return fail(res, (error && error.status) || 500, (error && error.code) || 'canvas-store-unavailable', `收进画布库失败：${error.message}`);
+    }
+  }
+
   const dir = job.destDir || path.join(inboxRoot(), today());
   try {
     // 指定落点时目录在 begin 已确认存在：中途被删了就该按落盘失败报，不能悄悄重建一个
@@ -621,7 +652,8 @@ async function inlineUploadedImageBlocks(content) {
     if (!block || block.type !== 'image') continue;
     if (typeof block.data === 'string' && block.data) continue;
     const record = resolveFinishedUpload(block.uploadId);
-    if (!record) return UPLOAD_EXPIRED_MESSAGE;
+    // 画布素材那份没有 `path`（只按哈希躺在画布库里），不能拿来内联：照旧报「过期」。
+    if (!record || !record.path) return UPLOAD_EXPIRED_MESSAGE;
     try {
       const bytes = await fsp.readFile(record.path);
       if (!bytes.length) return UPLOAD_EXPIRED_MESSAGE;

package/lib/routes/mobile-api.js

@@ -46,6 +46,7 @@ const pluginSelf = require('../mobile/plugin-self.js');
 const pluginMarket = require('../mobile/plugin-market.js');
 const { createRelayControlHandlers } = require('../mobile/relay-control.js');
 const uploads = require('../mobile/uploads.js');
+const canvasStore = require('../mobile/canvas-store.js');
 const inboxClean = require('../mobile/inbox-clean.js');
 const git = require('../mobile/git.js');
 const pairing = require('../mobile/pairing.js');
@@ -482,6 +483,14 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/upload/chunk', uploads.handleUploadChunk)
   route('/api/mobile/v1/upload/finish', uploads.handleUploadFinish)
   route('/api/mobile/v1/upload/abort', uploads.handleUploadAbort)
+
+  // 无限画布的库（App 那页 WebView 里的项目与素材，见 mobile/canvas-store.js）。
+  // 每个域一份清单、字节按内容哈希落在插件自己的目录里；手机推上来、拉下去都走这三条。
+  // 素材字节不另开通道，走上面的分片上传（`purpose: 'canvas'`）—— 断点续传与片大小
+  // 自适应那一套已经在那条路上，再写一份只是多一条会漂的实现。
+  route('/api/mobile/v1/canvas/manifest', canvasStore.handleCanvasManifestGet)
+  route('/api/mobile/v1/canvas/manifest/save', canvasStore.handleCanvasManifestSave)
+  route('/api/mobile/v1/canvas/file', canvasStore.handleCanvasFile)
   // 同一个收件目录的出口：上面四条只往里放，这两条报占用、按龄清掉（见 mobile/inbox-clean.js）。
   // 落盘的文件不认识会话，所以没有「删掉这条对话就顺带清掉它传上来的文件」这条路 ——
   // 唯一的出口只能按龄，口径写在那个文件头。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",