dsh-mobile-plugin 0.1.96 → 0.1.97

package/lib/mobile/inbox-clean.js

@@ -0,0 +1,337 @@
+'use strict';
+
+/**
+ * 收件目录（`~/.dsh/mobile-inbox`）的占用统计与按龄清理。
+ *
+ * 手机分享进来的文件由 `uploads.js` 落到 `<收件根>/<日期>/<消毒名>`，那条通道**只进不出**：
+ * 它在盘上只认文件名，不认识会话、也不认识工作区，所以没有任何「删掉这条对话就顺带清掉
+ * 它传上来的文件」可言 —— 唯一的引用是会话日志正文里那句 `@路径`，那是文本，宿主不会
+ * 跟着它去回收。不设一个出口，这个目录只会按天堆下去。
+ *
+ * 因此这里的口径是**按龄**：只删 mtime 超过 `keepMs`（24 小时）的文件。
+ *
+ * 为什么是文件而不是日期目录：目录按「上传那天的本地日期」分堆，整段删会把昨天 23:50
+ * 传的、才过 20 分钟的文件一起带走；按每个文件自己的 mtime 判才和「放满一天」这个承诺
+ * 一致。空出来的日期目录顺手删掉。
+ *
+ * 为什么留着 24 小时而不是立刻删：助手拿到路径之后可能在同一个回合里反复读它，用户也可能
+ * 隔一晚上让助手接着看同一份文件。今天传的文件一开始就不在清理范围内，正在跑的那一回合
+ * 因此碰不到这里。
+ *
+ * 与 `session-cleanup.cjs` 的取舍刻意不同：那边进程活着时一条日志都不删（宿主随时可能去
+ * 打开，ENOENT 会带走整个进程）；这里删的是收件目录里的普通文件，宿主只在助手明确要读
+ * 某个路径时才碰它，而那个路径只有在 24 小时窗口内才可能还有人要。
+ *
+ * ## 自动清理是开关，默认关（2026-10-21 用户定）
+ *
+ * 启动时那次自动清理**只有开关打开才跑**；面板上那颗按钮永远可用（那是用户自己按的，
+ * 不需要开关授权）。开关落盘在 `<DSH_HOME>/storages/mobile-plugin/inbox-auto-clear.json`，
+ * 与自动更新开关同一套写法（读不到 / 读坏了都当关）—— 自动删盘这种事，缺省必须在用户
+ * 这一侧，而不是「装了就替你删」。
+ */
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { dshHome } = require('../shared/paths');
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { inboxRoot, sweepStaging, STAGING_TTL_MS } = require('./uploads.js');
+
+/** 保留期：文件落盘之后满这么久才进清理范围。 */
+const INBOX_KEEP_MS = 24 * 60 * 60 * 1000;
+
+/** 收件根下的暂存目录（`uploads.js` 的 `.staging`）：半截上传的残片住在这里。 */
+const STAGING_DIR = '.staging';
+
+/** 日期堆的名字（`uploads.js` 的 `today()`）。不是这个形状的一律当残渣跳过。 */
+const DATE_DIR_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** 自动清理开关的落盘文件：与自动更新开关同一个目录。 */
+function autoClearFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'inbox-auto-clear.json');
+}
+
+/**
+ * 读自动清理开关。读不到 / 读坏了都当「关」—— 无人值守删盘这种事，
+ * 缺省必须在用户这一侧（与 `updater.js` 的 `autoUpdateEnabled` 同一条口径）。
+ */
+function autoClearEnabled() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(autoClearFile(), 'utf8'));
+    return raw?.enabled === true;
+  } catch {
+    return false;
+  }
+}
+
+/** 写开关。 */
+function setAutoClear(enabled) {
+  const file = autoClearFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ enabled: enabled === true }, null, 2)}\n`);
+  return autoClearEnabled();
+}
+
+async function readEntries(dir) {
+  try {
+    return await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 暂存残片的占用：`.staging/*.part` 里已经超过 TTL 的那些。
+ *
+ * 单列一份是因为它们**不归日期堆那份扫描管**（文件名不是按天分堆的、也没有目录名可读），
+ * 但它跟落盘文件是同一个收件根、同样只进不出：`sweepStaging` 只在 `begin` 时跑，手机不再
+ * 上传的机器上残片就一直躺在那儿（实测一份 12MB 的 `.part` 从 10-20 睡到现在）。
+ * 判据与 `sweepStaging` 完全一致（同一个 `STAGING_TTL_MS`），这里只读不删。
+ */
+async function scanStaging(now = Date.now()) {
+  const dir = path.join(inboxRoot(), STAGING_DIR);
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { files: 0, bytes: 0, deletableFiles: 0, deletableBytes: 0 };
+  }
+  const cutoff = now - STAGING_TTL_MS;
+  let files = 0;
+  let bytes = 0;
+  let deletableFiles = 0;
+  let deletableBytes = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.part')) continue;
+    try {
+      const stat = await fsp.stat(path.join(dir, entry.name));
+      files += 1;
+      bytes += stat.size;
+      if (stat.mtimeMs < cutoff) {
+        deletableFiles += 1;
+        deletableBytes += stat.size;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return { files, bytes, deletableFiles, deletableBytes };
+}
+
+/**
+ * 走一遍收件目录，按 mtime 把文件分成「还留着」与「够龄可删」两堆。
+ *
+ * 只走一层日期目录、不进任何子目录：落盘路径是 `<根>/<日期>/<文件>`，客户端给不出更深的
+ * 路径（`sanitizeName` 把 `/` 与 `\` 都换成 `_`）。暂存残片单独算（见 `scanStaging`），
+ * 但**并进同一份读数**：用户问的是「这个收件目录占了多少」，分两行报只会让他去猜哪一行该点。
+ */
+async function scanInbox(now = Date.now(), keepMs = INBOX_KEEP_MS) {
+  const root = inboxRoot();
+  const cutoff = now - keepMs;
+  let bytes = 0;
+  let files = 0;
+  let deletableBytes = 0;
+  let deletableFiles = 0;
+  let oldestMs = 0;
+  for (const dirEntry of await readEntries(root)) {
+    if (!dirEntry.isDirectory() || !DATE_DIR_RE.test(dirEntry.name)) continue;
+    const dir = path.join(root, dirEntry.name);
+    for (const entry of await readEntries(dir)) {
+      if (!entry.isFile()) continue;
+      const file = path.join(dir, entry.name);
+      let stat;
+      try {
+        stat = await fsp.stat(file);
+      } catch {
+        continue;
+      }
+      files += 1;
+      bytes += stat.size;
+      if (!oldestMs || stat.mtimeMs < oldestMs) oldestMs = stat.mtimeMs;
+      if (stat.mtimeMs < cutoff) {
+        deletableFiles += 1;
+        deletableBytes += stat.size;
+      }
+    }
+  }
+  // 暂存残片并进同一份读数，但**它们不是「收件文件」**：多出来的两个字段让界面能分开说。
+  const staging = await scanStaging(now);
+  return {
+    root,
+    files: files + staging.files,
+    bytes: bytes + staging.bytes,
+    deletableFiles: deletableFiles + staging.deletableFiles,
+    deletableBytes: deletableBytes + staging.deletableBytes,
+    stagingFiles: staging.files,
+    stagingBytes: staging.bytes,
+    oldestMs,
+    keepMs,
+  };
+}
+
+/**
+ * 删掉够龄的文件，再把空下来的日期目录收掉。
+ *
+ * 删一个失败不算整轮失败（被别人删掉、权限、占用），照删其余：这个动作的结果本来就是
+ * 「这次腾了多少」，不是「盘上一定干净了」。目录只在真的空了之后才删，`rmdir` 失败同样
+ * 不影响结论。
+ */
+async function clearInbox(now = Date.now(), keepMs = INBOX_KEEP_MS) {
+  const root = inboxRoot();
+  const cutoff = now - keepMs;
+  let deletedFiles = 0;
+  let freedBytes = 0;
+  let failedFiles = 0;
+  for (const dirEntry of await readEntries(root)) {
+    if (!dirEntry.isDirectory() || !DATE_DIR_RE.test(dirEntry.name)) continue;
+    const dir = path.join(root, dirEntry.name);
+    for (const entry of await readEntries(dir)) {
+      if (!entry.isFile()) continue;
+      const file = path.join(dir, entry.name);
+      let stat;
+      try {
+        stat = await fsp.stat(file);
+      } catch {
+        continue;
+      }
+      if (stat.mtimeMs >= cutoff) continue;
+      try {
+        await fsp.unlink(file);
+        deletedFiles += 1;
+        freedBytes += stat.size;
+      } catch {
+        failedFiles += 1;
+      }
+    }
+    // 只剩空壳的日期目录一起收掉；里面还有今天传的文件时 rmdir 会失败，正好留着。
+    try {
+      await fsp.rmdir(dir);
+    } catch { /* 还有文件，或者删不掉：都不是错误 */ }
+  }
+  // 暂存残片交给 `uploads.js` 自己那份判据（同一个 TTL），别在这里抄一遍：抄了就是第二份账，
+  // 改一处忘一处时两边会各删各的。它删不掉的项不进 `failedFiles` —— 那是「收件文件」的账。
+  let stagingDeleted = 0;
+  let stagingBytes = 0;
+  try {
+    const swept = await sweepStaging(path.join(root, STAGING_DIR));
+    stagingDeleted = swept.deleted;
+    stagingBytes = swept.bytes;
+  } catch { /* 残片清不动不影响这一轮：下次启动还会再试 */ }
+  return {
+    deletedFiles: deletedFiles + stagingDeleted,
+    freedBytes: freedBytes + stagingBytes,
+    failedFiles,
+    keepMs,
+  };
+}
+
+function usageView(scan) {
+  return {
+    ok: true,
+    root: scan.root,
+    files: scan.files,
+    bytes: scan.bytes,
+    deletableFiles: scan.deletableFiles,
+    deletableBytes: scan.deletableBytes,
+    /** 其中暂存残片占了多少（半截上传留下的 `.part`，与落盘文件同一份读数、但来源不同）。 */
+    stagingFiles: scan.stagingFiles,
+    stagingBytes: scan.stagingBytes,
+    oldestAt: scan.oldestMs || null,
+    keepHours: Math.round(scan.keepMs / (60 * 60 * 1000)),
+    /**
+     * 自动清理开着没有。两个界面都靠它画那颗开关 —— 不自己猜、也不各自存一份，
+     * 真值只在这台机器的 json 里。**默认 false**（用户 2026-10-21 定）。
+     */
+    autoClear: autoClearEnabled(),
+  };
+}
+
+/**
+ * GET /api/mobile/v1/inbox/status（token）
+ *
+ * 只读：收件目录现在占了多少、其中多少已经够龄可删。App 与网页面板共用这一条，
+ * 两边都不必自己扫盘、也不会各算一套口径。
+ */
+async function handleInboxStatus(_ctx, _req, res) {
+  sendJson(res, 200, usageView(await scanInbox()));
+}
+
+/**
+ * POST /api/mobile/v1/inbox/clear（token）{ confirm: true }
+ *
+ * 与「清理已归档会话」同一条手感：不可恢复的磁盘删除必须显式带 `confirm`，
+ * 手机端少点一次不值得把它变成滑一下就没了的动作。
+ */
+async function handleInboxClear(_ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || body.confirm !== true) {
+    sendJson(res, 400, { ok: false, error: { code: 'confirm-required', message: '清理收件文件不可恢复，请求需要带 confirm: true' } });
+    return;
+  }
+  const result = await clearInbox();
+  sendJson(res, 200, { ok: true, ...result });
+}
+
+/**
+ * POST /api/mobile/v1/inbox/auto（token）{ enabled: boolean }
+ *
+ * 自动清理开关。与自动更新那条（`/api/relay/update/auto`）同一条手感：只收布尔、
+ * 缺省关、写失败就整次失败（回「开好了」却没落盘，下次启动又是关的，用户会以为是坏的）。
+ */
+async function handleInboxAuto(_ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.enabled !== 'boolean') {
+    sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } });
+    return;
+  }
+  try {
+    const enabled = setAutoClear(body.enabled);
+    sendJson(res, 200, { ok: true, autoClear: enabled });
+  } catch (error) {
+    sendJson(res, 500, { ok: false, error: { code: 'write-failed', message: `开关没写进去：${error && error.message ? error.message : error}` } });
+  }
+}
+
+/** 每进程只清一次：代际热替换会再跑一遍装载，但盘上已经清过了。 */
+const CLEARED_ONCE = Symbol.for('dsh-mobile-plugin.inbox-cleared-once');
+
+/**
+ * 宿主刚起来时顺手清一次 —— **只在自动清理开关打开时**。
+ *
+ * 与两个入口（App / 面板）调的是同一个 `clearInbox`，只是不需要确认：这里没有人在按键，
+ * 而够龄这个判据本身就是「这些文件已经放满一天了」。但「没人按键」也正是它必须默认关的
+ * 理由 —— 没有人在场时替用户删盘的，得是他明确打开过的开关。开关关着就直接返回，连盘都
+ * 不扫（扫一遍也是成本，而且开没开是读一个 json 的事）。
+ *
+ * 失败只记一行日志：收尾动作不该把装载拖下水。
+ */
+async function clearInboxOnce(log) {
+  if (globalThis[CLEARED_ONCE]) return null;
+  globalThis[CLEARED_ONCE] = true;
+  if (!autoClearEnabled()) return null;
+  try {
+    const result = await clearInbox();
+    if (result.deletedFiles > 0) {
+      log?.(`inbox cleanup: deleted ${result.deletedFiles} files (${Math.round(result.freedBytes / 1024)} KB)`);
+    }
+    return result;
+  } catch (error) {
+    log?.(`inbox cleanup failed: ${error && error.message ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+module.exports = {
+  scanInbox,
+  clearInbox,
+  clearInboxOnce,
+  autoClearEnabled,
+  setAutoClear,
+  autoClearFile,
+  usageView,
+  handleInboxStatus,
+  handleInboxClear,
+  handleInboxAuto,
+  INBOX_KEEP_MS,
+};

package/lib/mobile/pairing.js

@@ -114,10 +114,13 @@ function readBody(req) {
  * @param {object} deps.core    relay/core.js（签 token 用）
  * @param {object} deps.credentials 设备凭据库（issue 接口）
  * @param {object} deps.pairingApproval pairing-policy.js（决定这台机器收不收新设备）
+ * @param {(port: number) => Array<object>} [deps.lanCandidates] 直连候选（与 `/connection-info` 同一份）
+ * @param {(port: number) => Array<object>} [deps.ipv6Candidates] IPv6 直连候选
+ * @param {() => number} [deps.lanPort] 宿主实绑的直连端口（配置端口被占时会换）
  * @param {(message: string) => void} deps.log
  */
 function createPairHandler(deps) {
-  const { state, core, credentials, pairingApproval, log } = deps;
+  const { state, core, credentials, pairingApproval, lanCandidates, ipv6Candidates, lanPort, log } = deps;
 
   // ⚠️ 签名必须是 `(req, res)` **两个**参数：宿主 webServer 就是 `handler(req, res)` 调的。
   // 写成 `(_ctx, req, res)` 会把 res 挤成 undefined，而 sendJson 的 catch 会把那个
@@ -184,6 +187,18 @@ function createPairHandler(deps) {
     const token = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_BEARER_TTL_SEC);
     const cookieValue = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC);
     const hostPlatform = pairingApproval.hostPlatform().platform;
+    // 宿主自己那批直连候选随配对一起回给手机：手输公网地址（域名 / 公网 IP）配对时没有
+    // 二维码，这是手机拿到内网地址的唯一机会。回家后那个公网地址若打不通（路由器不支持
+    // 回环 / 域名只在外网解析），手机可以靠这批候选找到这台机器，否则只能删设备重配。
+    // 语义与 `/connection-info` 那份一致（`advertisedCandidates`：有私网只给私网），
+    // 关掉局域网直连时两份都为空。App 的 `doPair` 本来就合并这两个字段。
+    const port = typeof lanPort === 'function' ? lanPort() : state.lanPort
+    const directCandidates = state.lanEnabled && typeof lanCandidates === 'function'
+      ? lanCandidates(port).map((candidate) => candidate.url).filter(Boolean)
+      : []
+    const v6Candidates = state.lanEnabled && typeof ipv6Candidates === 'function'
+      ? ipv6Candidates(port).map((candidate) => candidate.url).filter(Boolean)
+      : []
     sendJson(res, 200, {
       ok: true,
       instanceId,
@@ -198,6 +213,8 @@ function createPairHandler(deps) {
       // 局域网那条（lan-proxy.js）给的也是它。`hostPlatform()` 回的是 `{platform}` 对象，
       // 整块展开就变成 `platform` —— App 收不到，设备行退回通用图标（真机上少的就是企鹅）。
       ...(hostPlatform ? { hostPlatform } : {}),
+      ...(directCandidates.length ? { lanUrls: directCandidates } : {}),
+      ...(v6Candidates.length ? { ipv6Candidates: v6Candidates } : {}),
     });
   };
 }

package/lib/mobile/questions.js

@@ -47,24 +47,46 @@ function openEntries(sessionId) {
   return list ? list.filter((entry) => !entry.settled) : [];
 }
 
+/**
+ * 卡片的 `intent`：只带「这是什么」的 kind 与批准按钮的标签。
+ *
+ * `dsh-plan-mode` 的 `exit_plan_mode` 也是走 `ctx.userQuestions.ask()` 提问的，问题带
+ * `intent:{kind:'plan-review', approve:'允许执行', callId}`。手机要靠 kind 把它渲染成
+ * 「计划待审」接管卡而不是一张普通选择题；callId 是宿主的内部句柄，**不许**跟着外泄。
+ * 没有 intent（或 kind 不合法）时返回 undefined，调用方据此不往卡里塞空对象。
+ */
+function intentOf(question) {
+  const intent = question && question.intent;
+  if (!intent || typeof intent !== 'object' || Array.isArray(intent)) return undefined;
+  const kind = typeof intent.kind === 'string' ? intent.kind.trim() : '';
+  if (!kind) return undefined;
+  const approve = typeof intent.approve === 'string' ? intent.approve.trim() : '';
+  return { kind, ...(approve ? { approve } : {}) };
+}
+
 /**
  * 卡片帧。形状严格照 App `streamFrame.ts` 认的那一种：**帧级 rpcId** + 顶层
  * `sessionId` + `questions`（每题至少 `id` 与 `question` 两个字符串）。
- * 只转发 App 认识的字段，宿主的其它内部键（如 `intent` 里的 callId）不外泄。
+ * 只转发 App 认识的字段；`intent` 只留 kind 与 approve，宿主的其它内部键
+ * （如 `intent` 里的 callId）不外泄。
  */
 function cardFrame(entry) {
   return {
     type: 'question/requested',
     sessionId: entry.sessionId,
     rpcId: entry.rpcId,
-    questions: entry.questions.map((question) => ({
-      id: question.id,
-      question: question.question,
-      ...(question.header ? { header: question.header } : {}),
-      ...(question.detail ? { detail: question.detail } : {}),
-      ...(question.options ? { options: question.options } : {}),
-      ...(question.multiSelect ? { multiSelect: question.multiSelect } : {}),
-    })),
+    questions: entry.questions.map((question) => {
+      const intent = intentOf(question);
+      return {
+        id: question.id,
+        question: question.question,
+        ...(question.header ? { header: question.header } : {}),
+        ...(question.detail ? { detail: question.detail } : {}),
+        ...(question.options ? { options: question.options } : {}),
+        ...(question.multiSelect ? { multiSelect: question.multiSelect } : {}),
+        ...(intent ? { intent } : {}),
+      };
+    }),
   };
 }