dsh-mobile-plugin 0.5.10 → 0.5.11

package/lib/cli/pair.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 在终端里把配对二维码打出来（`dsh-mobile-plugin-pair`）。
+ *
+ * 为什么需要它：二维码那条路由只在本机屏幕或者两小时窗口里给码，而**服务器部署**上
+ * 「本机屏幕」这个概念是空的 —— 那台机器的设置页往往开不了，人也够不到它的回环地址。
+ * 能在服务器终端里敲命令的人本来就有这台机器的权限，把码打给他，信任量级与「在本机屏幕
+ * 上看码」相同，也不新增任何对外的口子。
+ *
+ * 载荷与面板同一份（`../relay/pairing-payload.cjs`），所以打出来的码一定和面板里那张能
+ * 配上同一台机器；这里只负责画图与说人话，不碰配对流程。
+ *
+ * 用法：
+ *   dsh-mobile-plugin-pair              在终端里打出二维码
+ *   dsh-mobile-plugin-pair --svg qr.svg 另外存一份 SVG（终端太窄、想发给别人时用）
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const QRCode = require('qrcode');
+const core = require('../relay/core.js');
+const { pairingPayload } = require('../relay/pairing-payload.cjs');
+
+const USAGE = `用法：
+  dsh-mobile-plugin-pair               在终端里打印配对二维码
+  dsh-mobile-plugin-pair --svg <路径>  同时把二维码存成 SVG 图片`;
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const out = { svg: '' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--svg') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) return { error: '--svg 后面要跟一个文件路径' };
+      out.svg = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') return { help: true };
+    return { error: `不认识的参数：${arg}` };
+  }
+  return out;
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+  if (args.error) {
+    fail(`${args.error}\n\n${USAGE}`);
+    return;
+  }
+
+  // 状态文件是宿主与这里唯一的交接口：宿主每次换码换票据都会落盘，所以读到的那份就是
+  // 跑着的宿主手上那份。文件不存在时**不替它建**（`loadState()` 会建），直接说清楚。
+  if (!fs.existsSync(core.STATE_FILE)) {
+    fail(`这台机器上还没跑过这个插件（找不到 ${core.STATE_FILE}）。先启动 DSH，并在移动端插件里启用远程控制。`);
+    return;
+  }
+  const state = core.loadState();
+  if (!state.enabled) {
+    fail('远程控制还没启用：先在 DSH 的移动端设置页（或面板）里打开远程控制并保存配置。');
+    return;
+  }
+  const { payload, text } = pairingPayload(state, state.lanPort);
+  if (!payload.relayUrl && payload.lanUrls.length === 0) {
+    fail('没有可用的中转或直连地址：先在面板上配好中转地址，或打开局域网直连，再回来打码。');
+    return;
+  }
+
+  const lines = [];
+  lines.push(`宿主：${payload.name}`);
+  lines.push(`配对码：${payload.code}`);
+  lines.push(`中转地址：${payload.relayUrl || '（没配）'}`);
+  if (payload.lanUrls.length > 0) {
+    lines.push(`直连地址：${payload.lanUrls.join('  ')}`);
+    lines.push(`局域网端口：${state.lanPort}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n\n`);
+
+  if (args.svg) {
+    const target = path.resolve(args.svg);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, await QRCode.toString(text, { type: 'svg', errorCorrectionLevel: 'M', margin: 2, width: 480 }));
+    process.stdout.write(`二维码已存成图片：${target}\n如果终端太窄扫不动，把这个文件拿下来用看图软件打开再扫。\n\n`);
+  }
+
+  // small: true 让一个字符带两行模块，绝大多数终端一行装得下；扫不动就加 --svg。
+  process.stdout.write(`${await QRCode.toString(text, { type: 'terminal', small: true, errorCorrectionLevel: 'M' })}\n`);
+  process.stdout.write('用 DSH App 扫这张码即可配对。它等于一次配对权限，别截图发给别人；配完可以在面板上点「重新生成配对码」。\n');
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  fail(`打码失败：${error && error.message ? error.message : String(error)}`);
+});

package/lib/client.js

@@ -482,6 +482,16 @@ window.__ModuleLoader__.load({
         hostHalfRetrying: '它还在后台自己重试，过几分钟刷新这一页就能看到结果；也可以点下面的按钮立刻再试一次。',
         hostHalfReload: '重新装载',
         hostHalfReloadFailed: '重新装载没成：',
+        hostHalfUnreachable: '宿主侧的自检口也没有回应：这一版插件可能还没带它（较老的版本）——先更新插件，再完整重启一次 DSH。',
+        hostHalfNoError: '宿主侧自检没报错，控制面路由却确实不在：把 DSH 完整重启一次；还不行请把这句连同插件版本发给我们。',
+        hostHalfVersion: '自检版本：',
+        diagHostReturned: '宿主返回：',
+        diagSelfCheck: '自检：',
+        diagSelfCheckNoAnswer: '没有回应（这一版可能还没带它）',
+        diagSelfCheckNoError: '没有报错',
+        diagSelfCheckRetry: '后台重试 ',
+        diagOnDisk: '碟上版本 ',
+        diagShellRestartAtStartup: '外壳改过，要重启一次 DSH',
         webAccessOn: '公网网页管理已开放，到期时间',
         webAccessOff: '公网网页管理已关闭',
         webAccessOpen: '开放网页管理 2 小时',
@@ -504,6 +514,16 @@ window.__ModuleLoader__.load({
         hostHalfRetrying: 'It is still retrying on its own in the background — reopen this item in a few minutes, or press the button below to retry right now.',
         hostHalfReload: 'Reload now',
         hostHalfReloadFailed: 'Reload failed: ',
+        hostHalfUnreachable: 'The host-side self-check did not answer either: this version of the plugin may not ship it yet (older build) — update the plugin, then restart DSH completely.',
+        hostHalfNoError: 'The host self-check reports no error, yet the control-plane routes really are missing: restart DSH completely; if that does not help, send us this line together with the plugin version.',
+        hostHalfVersion: 'self-check version: ',
+        diagHostReturned: 'Host returned: ',
+        diagSelfCheck: 'Self-check: ',
+        diagSelfCheckNoAnswer: 'no answer (this build may not ship it)',
+        diagSelfCheckNoError: 'no error reported',
+        diagSelfCheckRetry: 'background retries: ',
+        diagOnDisk: 'on disk: ',
+        diagShellRestartAtStartup: 'shell changed — DSH needs one restart',
         webAccessOn: 'Public web management is open until',
         webAccessOff: 'Public web management is closed',
         webAccessOpen: 'Open web management for 2 hours',
@@ -573,15 +593,17 @@ window.__ModuleLoader__.load({
               refreshTimer = null;
             }
             // 404 = 实现那一半没装载。它为什么没装载，只有外壳答得出来（这两条路由挂在
-            // 外壳上，实现挂了它们还在）；老版本宿主没有这条口，问不到就当没有，别报错。
+            // 外壳上，实现挂了它们还在）；老版本宿主没有这条口，问不到也得把这个事实留住
+            // （`unavailable`）——「自检口都没有回应」和「自检说没事」是两种不同的现场，
+            // 都缩成一句「重启/重装」的话，用户只能对着空白猜（2026-11-01 现场）。
             if (problem?.status === 404) {
               try {
                 const picture = await call(HOST_HALF_ENDPOINT);
                 if (!alive) return;
-                setHalf(picture && typeof picture.half === 'object' ? picture.half : null);
+                setHalf(picture && typeof picture.half === 'object' ? picture.half : { unavailable: true });
               } catch {
                 if (!alive) return;
-                setHalf(null);
+                setHalf({ unavailable: true });
               }
             } else {
               setHalf(null);
@@ -648,16 +670,59 @@ window.__ModuleLoader__.load({
 
       const missing = errorStatus === 404;
 
+      /**
+       * 诊断读数：宿主回了什么 + 外壳那份自检说了什么。
+       *
+       * 只拼进这一屏、不落盘也不上报：它的用途是让人截图发给我们（2026-11-01 用户原话：
+       * 「以后用户发过来 我也不好去排查」）。字段名用 `version=` / `source=` 这种记号而不是
+       * 翻成中文，是因为它要能贴进日志里对得上宿主那一侧。
+       */
+      const diagLines = [];
+      if (missing) {
+        diagLines.push(`${t('diagHostReturned')}${error}`);
+        if (half && half.unavailable === true) {
+          diagLines.push(`${t('diagSelfCheck')}${t('diagSelfCheckNoAnswer')}`);
+        } else if (half) {
+          const bits = [];
+          if (half.version) bits.push(`version=${half.version}`);
+          if (half.source) bits.push(`source=${half.source}`);
+          if (half.activatedAt) bits.push(`at=${half.activatedAt}`);
+          if (half.retrying) {
+            const attempts = Number.isFinite(half.retryAttempts) ? half.retryAttempts : 0;
+            bits.push(`${t('diagSelfCheckRetry')}${attempts}${half.nextRetryAt ? `→${half.nextRetryAt}` : ''}`);
+          }
+          if (half.installedVersion && half.installedVersion !== half.version) {
+            bits.push(`${t('diagOnDisk')}${half.installedVersion}`);
+          }
+          if (half.shellChanged) bits.push(t('diagShellRestartAtStartup'));
+          diagLines.push(`${t('diagSelfCheck')}${bits.length ? bits.join(' · ') : t('diagSelfCheckNoError')}`);
+        }
+      }
+
       return h('div', { className: 'dshm_root' }, [
         h('h2', { className: 'dshm_heading' }, t('heading')),
         error
           ? h('p', { className: 'dshm_error' }, missing ? t('loadMissing') : `${t('loadFailed')}: ${error}`)
           : null,
+        // 404 那屏必须自带「能拿去排查」的读数（2026-11-01 用户要求）：只写一句「宿主侧没起来」
+        // 的话，用户截图发过来我们还是不知道坏在哪一层，只能让他一次次试。
+        // 两行足够定位：宿主到底回了什么、外壳那份自检说了什么。
+        ...diagLines.map((line) => h('p', { className: 'dshm_note', key: line.slice(0, 24) }, line)),
         // 404 时把宿主那半边自己的说法贴出来：重启 / 重装这两句提示在「装载超时」那种
         // 现场是帮倒忙的，真正该做的是等它后台补齐、或者点一下重新装载。
         missing && half && typeof half.lastError === 'string' && half.lastError
           ? h('p', { className: 'dshm_note' }, `${t('hostHalfReason')}${half.lastError}`)
           : null,
+        // 问不到自检口：说明这一版插件压根没带它（比 0.5.11 老），用户这时最该做的是更新
+        // 插件，而不是继续重启 —— 原先这一支是一片空白，只留一句「重启/重装」。
+        missing && half && half.unavailable === true
+          ? h('p', { className: 'dshm_note' }, t('hostHalfUnreachable'))
+          : null,
+        // 自检说没事、路由却不在：这是「同一份 DSH 里跑着两份插件」那种现场，报出版本
+        // 才查得下去。
+        missing && half && half.unavailable !== true && !(typeof half.lastError === 'string' && half.lastError)
+          ? h('p', { className: 'dshm_note' }, `${t('hostHalfNoError')}${typeof half.version === 'string' && half.version ? `（${t('hostHalfVersion')}${half.version}）` : ''}`)
+          : null,
         missing && half && half.retrying === true
           ? h('p', { className: 'dshm_note' }, t('hostHalfRetrying'))
           : null,

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_ 凭据，
@@ -93,6 +95,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 +116,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 +172,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`（守卫记、控制面状态读）。
@@ -490,7 +458,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;