@dshfly/remote-connector 0.2.1 → 0.3.0

package/core/connector-core.js

@@ -21,6 +21,22 @@ import { deriveSessionKey, pairFingerprint, pairShortCode, signPairingConfirm, s
 // 解析信封 → bridge.handleRpc → 组 server-response 回包。bridge 未接入时返回 null（回落反代）。
 const MOBILE_PREFIX = '/api/mobile.';
 
+/**
+ * 本 connector 插件向手机端声明的能力清单（三端兼容 / 能力协商）。
+ *
+ * 背景（docs/compatibility.md G5、docs/session-archive-plan.md §12）：App 与插件**独立升级**，
+ * "新 App × 旧插件"是常态。新功能若不可探测，App 只能靠"调一次看报不报错"来猜——用户会看到
+ * 一个永远不会成功的按钮。因此：**新增手机端能力时，在这里加一个字符串**，App 侧用
+ * `features.includes(...)` 决定入口显隐（fail-closed：字段缺失/不含即视为不支持）。
+ *
+ * 现有能力：
+ *   · `session-archive` —— `workspace.archiveSession`（会话归档，2026-09）
+ *   · `history-slim`     —— 历史响应已剥 chunk 家族 + 大响应已 deflate（2026-09，0.3.0）。
+ *     **注意它门控的是"页大小"而非入口**：App 有该能力 → 上翻 50 / 跳转 200；
+ *     无（旧插件）→ 自动降到 20 / 60，避免一页 ~10.9MB 过中继（docs/turn-navigation-plan.md §8.2）。
+ */
+const CONNECTOR_FEATURES = ['session-archive', 'history-slim'];
+
 /** PC 计算机名（去 .local 后缀；2026-08：手机端"我"页显示可读 PC 名）。 */
 function hostnameClean() {
   return String(os.hostname() || '').replace(/\.local$/, '') || null;
@@ -126,7 +142,13 @@ export async function handleMobileLocal(bridge, inner, { fullDisk = true, resolv
 }
 
 export class ConnectorCore {
-  constructor({ relayUrl, deviceName, keysFile, target, controlPath = '/control', dshAdapter = null }) {
+  constructor({ relayUrl, deviceName, keysFile, target, controlPath = '/control', dshAdapter = null, featureProbe = true }) {
+    /**
+     * 是否暴露能力协商路由（`mobile.getFeatures`）。**仅用于测试**：置 false 可精确模拟
+     * "旧版插件"（能力协商引入之前的 connector）——因为路由由本插件核心代码直接处理，
+     * 不受 dshAdapter/gateway 影响，没有这个开关就无法回归"旧插件 × 新 App"路径。
+     */
+    this.featureProbe = featureProbe !== false;
     this.keys = loadOrCreateKeys(keysFile);
     // 2026-09：DSH web 0.1.2 起 /api 需要 browser-session cookie 且协议结构性改动（斜杠端点、
     // {args} 包装、事件走 remote.mux、/api/respond 移除）。connector 同进程 —— 改为进程内
@@ -232,6 +254,11 @@ export class ConnectorCore {
       devices,
       tokenState: tok.state, // device token 健康（2026-08 自愈）
       deviceTokenExpiringAt: tok.expiringAt,
+      // 三端兼容（docs/compatibility.md / session-archive-plan §12）：本插件支持的手机端能力。
+      // ⚠️ 手机 App 与 connector 插件是**独立升级**的（App 走 Expo/商店，插件走 dsh plugin add），
+      // 所以"新 App × 旧插件"是随时会发生的常态——新功能必须能被探测，否则 App 只能靠猜。
+      // App 侧契约：**只有明确读到 true 才显示入口**（fail-closed）；字段缺失 = 旧插件 = 不支持。
+      features: CONNECTOR_FEATURES.slice(),
     };
   }
 
@@ -525,7 +552,48 @@ export class ConnectorCore {
           result: { ok: true, value: { name: this.keys.deviceNames?.[phonePk] || null } },
         });
       }
-      if (!this.mobileBridge) return null;
+      // 能力协商（2026-09，docs/session-archive-plan.md §12）：手机 App 探测本插件支持哪些
+      // 手机端能力。**旧插件没有这条路由** → 手机侧请求会落到通用分支（返 unknown-method）或
+      // 被 adapter 判为未知方法 → App 侧据此把新功能入口隐藏（fail-closed），而不是给用户一个
+      // 永远点不成功的按钮。响应形状与 /dshfly/status 的 features 一致。
+      if (this.featureProbe && inner?.url === '/api/mobile.getFeatures') {
+        let req = null;
+        try {
+          req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+        } catch {
+          return null;
+        }
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: { ok: true, value: { features: CONNECTOR_FEATURES.slice() } },
+        });
+      }
+      // 未知 `mobile.*` 方法一律在此明确失败（**不回落 HTTP 反代**）。
+      // 反代会把 /api/mobile.xxx 当普通 DSH 端点去 fetch target —— 而 mobile.* 是本插件
+      // 自己扩展的手机端方法，DSH 从来没有这些端点，结果只是把"方法不存在"变成
+      // "fetch failed" 这种无法诊断的传输错误（三端兼容排查时实测踩到）。
+      // 落在这里的典型场景：**旧插件 × 新 App**（App 调了新插件才有的 mobile.getFeatures）。
+      if (!this.mobileBridge) {
+        let req = null;
+        try {
+          req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+        } catch {
+          req = null;
+        }
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: {
+            ok: false,
+            error: {
+              code: 'unhandled',
+              message: `dshfly: unsupported mobile method ${String(inner?.url || '').replace('/api/', '')}`,
+              details: {},
+            },
+          },
+        });
+      }
       return handleMobileLocal(this.mobileBridge, inner, {
         fullDisk: this.getPermission(phonePk).fullDisk,
         resolveRoots: this._roots,

package/core/deps-check-cli.js

@@ -0,0 +1,33 @@
+// packages/remote-connector/core/deps-check-cli.js
+// 依赖预检 CLI 入口（发布面把关）。
+//
+// 为什么 CLI 放在 core/ 而不是 scripts/：**`scripts/` 不进 npm 包**（package.json `files` 只有
+// index/config/http-api/core/dist/mobile-bridge），而 npm 的 `prepack` 是在**打包出的 tarball
+// 目录里**执行的——若 prepack 指向 scripts/，tarball 里找不到脚本，发布/安装即失败。
+// core/ 会随包发布，所以 CLI 放这里，`scripts/check-deps.mjs` 只做薄转发（仓库内直跑用）。
+//
+// 用法：
+//   node core/deps-check-cli.js          # 检查（失败 exit 1 + 修复指引）
+//   node core/deps-check-cli.js --json   # 机器可读（CI）
+
+import { checkDependencies, dependencyFixHint } from './deps-check.js';
+
+const asJson = process.argv.includes('--json');
+const result = checkDependencies();
+
+if (asJson) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`✅ 插件依赖可解析（${result.checked.length} 个裸导入）`);
+  if (result.hostOptional.length) {
+    console.log(`   ℹ 宿主提供（本机未安装，运行时由 DSH 注入）：${result.hostOptional.join(', ')}`);
+  }
+} else {
+  console.error(`❌ ${dependencyFixHint(result.missing)}`);
+  if (result.error) console.error(`   （解析起点初始化失败：${result.error}）`);
+  if (result.hostOptional.length) {
+    console.error(`   ℹ 宿主提供（跳过）：${result.hostOptional.join(', ')}`);
+  }
+}
+
+process.exit(result.ok ? 0 : 1);

package/core/deps-check.js

@@ -0,0 +1,103 @@
+// packages/remote-connector/core/deps-check.js
+// 插件依赖可解析性预检（2026-09）。
+//
+// 为什么需要（真机事故）：`dsh plugin --profile web add .` 把插件目录以 **link:** 方式装进
+// profile（符号链接到仓库源码），pnpm **不会**为 link: 目标安装它自己的依赖。于是仓库工作区
+// node_modules 不完整时（`pnpm install` 没跑过 / 跑过被过滤安装），插件 apply 阶段
+// `import '@dshfly/crypto'` 抛 ERR_MODULE_NOT_FOUND → DSH fail-loud → **整个 dsh web 起不来**，
+// 且错误只有一行 ERR_MODULE_NOT_FOUND，看不出"去仓库跑 pnpm install"这一步。
+//
+// 这里把扫描/解析抽成纯 Node 函数（无 cordis 依赖），供三处共用：
+//   ① `scripts/check-deps.mjs`（CLI / CI）；
+//   ② `/dshfly/doctor` 端点（设置页把"缺依赖 + 怎么修"直接显示出来）；
+//   ③ 单测。
+//
+// 注意：本模块必须在**任何可能失败的第三方 import 之前**可用（它自己只用 node: 内置 + 相对路径）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+/** 插件包根（本文件位于 <pkg>/core/）。 */
+export const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 扫描根（插件运行时代码；dist/ 是前端 bundle，test/ 是测试，均不参与）。 */
+const SCAN_ROOTS = ['index.js', 'config.js', 'http-api.js', 'core', 'mobile-bridge'];
+const SCAN_EXT = new Set(['.js', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', 'test', 'dist']);
+
+/** node: 内置模块无需解析。 */
+const BUILTIN_RE = /^node:/;
+/** 宿主（DSH）注入的包：本机没装也不算故障，只在报告里标注。 */
+const HOST_PROVIDED_RE = /^@deepseek-ai\/(cordis|dsh-|schemastery)/;
+
+const IMPORT_RE =
+  /(?:^|[\s;{}()])(?:import|export)\s[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|[\s;{}()])import\s*\(\s*['"]([^'"]+)['"]\s*\)|require\(\s*['"]([^'"]+)['"]\s*\)/gm;
+
+function walk(rel, out = []) {
+  const abs = path.join(PLUGIN_ROOT, rel);
+  if (!fs.existsSync(abs)) return out;
+  if (fs.statSync(abs).isDirectory()) {
+    for (const name of fs.readdirSync(abs)) {
+      if (SKIP_DIRS.has(name)) continue;
+      walk(path.join(rel, name), out);
+    }
+    return out;
+  }
+  if (SCAN_EXT.has(path.extname(abs))) out.push(abs);
+  return out;
+}
+
+/** 收集运行时代码里的裸导入（去重、排除相对路径与 node: 内置）。 */
+export function collectBareImports() {
+  const specs = new Set();
+  for (const file of SCAN_ROOTS.flatMap((e) => walk(e))) {
+    let src = '';
+    try {
+      src = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(IMPORT_RE)) {
+      const spec = m[1] || m[2] || m[3];
+      if (!spec || spec.startsWith('.') || spec.startsWith('/') || BUILTIN_RE.test(spec)) continue;
+      specs.add(spec);
+    }
+  }
+  return [...specs].sort();
+}
+
+/**
+ * 从插件目录解析每个依赖（与运行时 import 同一条解析链：以 core/keys.js 为起点）。
+ * @returns {{ ok: boolean, missing: string[], hostOptional: string[], checked: string[], error?: string }}
+ */
+export function checkDependencies() {
+  let req;
+  try {
+    req = createRequire(path.join(PLUGIN_ROOT, 'core', 'keys.js'));
+  } catch (e) {
+    return { ok: false, missing: [], hostOptional: [], checked: [], error: e?.message || String(e) };
+  }
+  const checked = collectBareImports();
+  const missing = [];
+  const hostOptional = [];
+  for (const spec of checked) {
+    try {
+      req.resolve(spec);
+    } catch {
+      if (HOST_PROVIDED_RE.test(spec)) hostOptional.push(spec);
+      else missing.push(spec);
+    }
+  }
+  return { ok: missing.length === 0, missing, hostOptional, checked };
+}
+
+/** 缺依赖时的可操作提示（CLI 与设置页共用同一文案，禁止两处漂移）。 */
+export function dependencyFixHint(missing) {
+  return (
+    `插件依赖未安装（缺少：${missing.join(', ')}）。` +
+    '本地开发安装（dsh plugin add .）走 link:，pnpm 不会为链接目录安装依赖——' +
+    '请在仓库根目录执行 `pnpm install` 后重启 dsh web。'
+  );
+}

package/core/dsh-web.js

@@ -20,6 +20,8 @@
 // 纯翻译函数（mapInvoke / buildEventFrames / buildApprovalResult）可单测；gateway 与 ctx
 // 依赖注入（测试注入 mock，生产传 Cordis 真服务）。
 
+import { stripHistoryEvents } from './history-slim.js';
+
 const LEGACY_OK_FIELD = Symbol('ok');
 
 /** 生成 requestId（DSH session/prompt 必填字段；手机端未发时由 connector 补一个）。 */
@@ -93,6 +95,15 @@ export function mapInvoke(legacyMethod, payload) {
 
     case 'workspace.create': return { endpoint: 'workspace/create', args: req({ path: p.path }) };
     case 'workspace.list': return { synthesizeWorkspaceList: true };
+    // 会话归档（docs/session-archive-plan.md）：DSH 原生 workspace/archiveSession，参数为单
+    // request 对象（与 workspace/create 同族）。**幂等**（已归档再调直接 return 不写盘）、
+    // 返回**完整归档集** { archivedSessionIds:[…] }——手机端据此直接覆盖本地归档集，无需等刷新。
+    // 归档是显示层过滤（不动工作区账本/不删日志/不搬目录），因此**不纳入 fullDisk 门禁**。
+    // 0.1.5-rc.1 起 workspace 命名空间**无 unarchive 方法**（归档单向，见方案 §2.4）。
+    case 'workspace.archiveSession': return {
+      endpoint: 'workspace/archiveSession',
+      args: req({ sessionId: p.sessionId }),
+    };
 
     case 'agentPreset.list': return { endpoint: 'agentPresets/list', args: {} };
     // agentPresets/select 实测：实参**直接** {agentId, agentPreset}（不包 request；包了报
@@ -315,7 +326,10 @@ export function createDshAdapter({ gateway, ctx, dshVersion = null, connectorVer
         const args = { request: { ...req, throughSeq } };
         const r = await g.invokeRpc('session/page', { args });
         if (!r?.ok) return r;
-        return { ok: true, value: translateResult('session.history', r.value) };
+        // 历史瘦身（**生产路径**）：剥 chunk 家族事件（按消息对齐窗口口径省 62% 字节）。
+        // 2026-09 修复：此前只写在 tunnel.js 的 replayInner（旧 HTTP 反代）里，而进程内迁移
+        // （9b9e13d）后本函数才是默认路径 → 瘦身成了死代码（见 history-slim.js 头注释）。
+        return { ok: true, value: stripHistoryEvents(translateResult('session.history', r.value)) };
       }
       // session.prompt：requestId 必填（实测契约），手机端未发 → 补生成一个（mode:'queue' 已实测有效）
       if (method === 'session.prompt' && mapped.endpoint === 'session/prompt' && !mapped.args.request?.requestId) {

package/core/history-slim.js

@@ -0,0 +1,59 @@
+// packages/remote-connector/core/history-slim.js
+// 会话历史响应瘦身：剥除手机端**零消费**的流式 chunk 家族事件。
+//
+// 为什么单独成模块：现在有**两条**产生 session.history 响应的路径，都必须瘦身——
+//   ① 进程内适配层（`dsh-web.js` 的 `invoke()` → typertGateway）——**生产路径**；
+//   ② 旧 HTTP 反代（`tunnel.js` 的 `replayInner`）——仅在适配层缺失时兜底。
+// 历史上瘦身只写在 ② 里，而 2026-09-04 的进程内迁移（9b9e13d）把 ① 变成了默认路径，
+// 于是瘦身与压缩双双变成死代码（详见 docs/turn-navigation-plan.md §3.2.2）。
+//
+// 背景（2026-09 实测，本机 3 个真实大会话逐事件类型统计）：`session/page` 返回窗口内
+// **全部事件**，而手机端只消费 `user/message` / `assistant/message` / `assistant/chunk`（实时）/
+// `turn/start` / `turn/end`。chunk 家族按条数占 91.6%；**按"消息对齐窗口"口径占 62% 字节**：
+//   · `assistant/chunk`   旧形态（逐条流式帧）
+//   · `reasoning-chunks`  ┐
+//   · `tool-call-chunks`  ├ 0.1.5 的 `AssistantStreamRecord` 批量形态
+//   · `text-chunks`       ┘
+//   · `chunk`             该联合类型里的单条形态
+//
+// **必须保留** `turn/start`（轮次锚点：目录面板与跳转定位依赖）、消息级事件与 `hasMore`
+// ——只丢流式预览，权威内容零损失。
+// （注：宿主 `session/page` 只返回 `{records,hasMore}`，历史页响应本就**不携带 projections**；
+//   导航大纲走 `session/follow` 开流快照那条路。）
+
+/** 手机端零消费、可安全剥除的事件类型集合。 */
+export const HISTORY_CHUNK_EVENT_TYPES = new Set([
+  'assistant/chunk',
+  'reasoning-chunks',
+  'text-chunks',
+  'tool-call-chunks',
+  'chunk',
+]);
+
+/**
+ * 值级瘦身（**生产路径用**）：`{ events, hasMore, projections? }` → 去掉 chunk 家族事件。
+ * 没有可剥项时返回原对象（保持引用，调用方无需额外判等）。非目标结构原样返回。
+ */
+export function stripHistoryEvents(value, chunkTypes = HISTORY_CHUNK_EVENT_TYPES) {
+  if (!value || !Array.isArray(value.events)) return value;
+  const kept = value.events.filter((e) => !chunkTypes.has(e?.event?.type));
+  if (kept.length === value.events.length) return value;
+  return { ...value, events: kept };
+}
+
+/**
+ * JSON 级瘦身（旧 HTTP 反代 `replayInner` 用：那里拿到的只有响应体字节）。
+ * 非目标结构 / 解析失败 → 原样返回（**绝不破坏响应**）。
+ */
+export function stripHistoryChunks(jsonStr, chunkTypes = HISTORY_CHUNK_EVENT_TYPES) {
+  try {
+    const full = JSON.parse(jsonStr);
+    if (full?.result?.ok) {
+      const value = stripHistoryEvents(full.result.value, chunkTypes);
+      if (value === full.result.value) return jsonStr;
+      full.result.value = value;
+      return JSON.stringify(full);
+    }
+  } catch { /* 解析失败原样返回 */ }
+  return jsonStr;
+}

package/core/tunnel.js

@@ -11,6 +11,7 @@ import { promisify } from 'node:util';
 import { TYPE, encode, decodeFrame, toJson, jsonFrame } from '@dshfly/tunnel-protocol';
 import { sealEnvelope, openEnvelope, deriveDirectionalKeys, ReplayGuard, utf8Decode, utf8, verifyUnpair } from '@dshfly/crypto';
 import { claimOutSeq, saveKeys } from './keys.js';
+import { stripHistoryChunks } from './history-slim.js';
 
 // C2（P2-8）：异步 deflate（大响应压缩不阻塞宿主主线程）
 const zlibDeflate = promisify(zlib.deflate);
@@ -73,6 +74,30 @@ export function stripSessionListJson(jsonStr) {
   } catch { /* 解析失败原样返回 */ }
   return jsonStr;
 }
+
+// 会话历史瘦身（chunk 家族剥离）已抽到独立模块：进程内适配层与旧 HTTP 反代**两条路径**都要用
+// （历史上只写在 replayInner 里，2026-09-04 进程内迁移后变成死代码——见 history-slim.js 头注释）。
+export { HISTORY_CHUNK_EVENT_TYPES, stripHistoryChunks } from './history-slim.js';
+
+/**
+ * RES 统一压缩（大响应 deflate，App 侧 pako inflate）。
+ * - 已有 `enc`（如 replayInner 已压缩）→ 原样返回；
+ * - body（base64）解出 < COMPRESS_THRESHOLD → 原样返回（小响应不值得压缩）；
+ * - 否则 deflate（**异步**，不阻塞宿主主线程）并打 `enc:'deflate'`。
+ * 非目标结构（无 body / 非 base64）原样返回，绝不破坏响应。纯函数（除解压外无副作用），可单测。
+ */
+export async function maybeDeflateRes(innerRes) {
+  if (!innerRes || innerRes.enc || typeof innerRes.body !== 'string' || innerRes.body.length === 0) return innerRes;
+  let buf;
+  try {
+    buf = Buffer.from(innerRes.body, 'base64');
+  } catch {
+    return innerRes;
+  }
+  if (buf.length < COMPRESS_THRESHOLD) return innerRes;
+  return { ...innerRes, body: (await zlibDeflate(buf)).toString('base64'), enc: 'deflate' };
+}
+
 async function replayInner(target, inner, sessionTitles = null) {
   // A5（P0-4，SSRF 修复）：反代目标必须与 target 同源。
   // inner.url 是手机 E2EE 明文，可被恶意手机/被劫持会话设置为任意绝对 URL——
@@ -89,20 +114,16 @@ async function replayInner(target, inner, sessionTitles = null) {
     body: inner.body ? Buffer.from(inner.body, 'base64') : undefined,
   });
   let buf = Buffer.from(await res.arrayBuffer());
-  // D 项 history 响应瘦身（docs/bug-report-phone-duplicate-stream.md §9.4-D）：
-  // session.history 响应含"该区间全部事件"（含每条消息的全部 chunk——实测 10 条消息
-  // ≈2.3 万事件 ≈4.3MB，密集会话尾页可达 10MB+），其中 chunk 对手机端历史重建零消费
-  // （消息级事件才是权威内容）却贡献 99% 字节与 JSON.parse 时间——进入会话加载变长的
-  // 主因。代理层剥掉 assistant/chunk（保留 hasMore/projections 等全部协议字段）。
+  // history 响应瘦身（本函数 = **旧 HTTP 反代兜底路径**；生产路径的瘦身在 dsh-web.js 的
+  // `invoke()` 里，两条路都走同一个 history-slim.js 单一事实源——见该文件头注释）。
+  // session.history 响应含"该区间全部事件"，其中流式 chunk 家族对手机端历史重建零消费
+  // （消息级事件才是权威内容）却占"消息对齐窗口"62% 字节与 JSON.parse 时间——进入会话变慢 /
+  // 上翻翻不动的主因。剥掉 chunk 家族（保留 turn/start 轮次锚点、消息级事件与 hasMore）。
   if (inner.body) {
     try {
       const req = JSON.parse(Buffer.from(inner.body, 'base64').toString('utf8'));
       if (req?.method === 'session.history') {
-        const full = JSON.parse(buf.toString('utf8'));
-        if (full?.result?.ok && Array.isArray(full.result.value?.events)) {
-          full.result.value.events = full.result.value.events.filter((e) => e?.event?.type !== 'assistant/chunk');
-          buf = Buffer.from(JSON.stringify(full));
-        }
+        buf = Buffer.from(stripHistoryChunks(buf.toString('utf8')));
       } else if (req?.method === 'session.list') {
         // 2026-08 性能：剥除 App 无消费的投影字段（goal/subagentTiming/subagent/plan/
         // todos，实测合计约 21.5% 字节中的大头）——列表刷新体量与解析随会话数线性增长。
@@ -323,8 +344,12 @@ export function connectConnector({ relayWsUrl, deviceToken, keys, keysFile, sess
       } catch {}
     }
     dshStreams = [];
-    // 2026-09：DSH 0.1.2 起 /api/events.mux|.host 已移除（改 /api/remote.mux）。connector 用
-    // 进程内 cordis 订阅注入事件（见 connector-core），不再连已死端点。
+    // 2026-09 协议迁移（已核实 DSH 0.1.5-rc.1 源码，修正旧注释）：`/api` 的**全部**端点（含
+    // events.mux/.host）现在都要求 browser-session 签名 cookie，裸请求 401；且事件改走
+    // `$events` 远程流（remote.mux 是 Web 客户端专用入口）。connector 是 dsh web 的**同进程**
+    // cordis 插件 → 改为进程内订阅 + typertGateway 直调（见 core/dsh-web.js 与 connector-core
+    // 的 startEventPump），**不再连任何 /api HTTP/WS 端点**（下面两条只在 eventsDisabled=false
+    // 的降级/测试路径保留）。
     if (eventsDisabled) return;
     const wsBase = target.replace(/^http/, 'ws');
     for (const p of ['/api/events.mux', '/api/events.host']) openDshStream(controlWs, wsBase + p);
@@ -509,7 +534,11 @@ export function connectConnector({ relayWsUrl, deviceToken, keys, keysFile, sess
             safeSend(ws, encode(TYPE.RES, f.streamId, out));
             return;
           }
-          const innerRes = local ?? (await replayInner(target, inner, sessionTitles));
+          // 进程内响应统一压缩（2026-09 修复）：进程内迁移后 `local` 响应不经过 replayInner，
+          // 于是 RES 的 ≥4KB deflate 也随之失效——手机端拿到的是未压缩 JSON（历史/列表响应尤其大）。
+          // 这里在两条路径的汇合点统一补上（replayInner 已压缩则原样返回），并用**异步** deflate
+          // 避免阻塞 dsh web 主线程。App 侧契约不变：innerRes.enc === 'deflate' → pako.inflate(body)。
+          const innerRes = await maybeDeflateRes(local ?? (await replayInner(target, inner, sessionTitles)));
           const resEnv = sealEnvelope(
             dirOf(sessionKey).down,
             {

package/core/version.js

@@ -0,0 +1,63 @@
+// packages/remote-connector/core/version.js
+// 版本比较（纯函数，零依赖；Node + 单测 + 前端 bundle 通用）。
+//
+// 为什么需要它（2026-09 缺陷修复）：
+//   设置页「检查更新」原先用 `latest !== version` 判"有新版本"——**只比相等、不比大小**。
+//   开发环境用 `dsh plugin --profile web add .` 装的是仓库里的 0.3.0，而 npm 上最新是 0.2.1，
+//   于是页面显示"发现新版本 v0.2.1"，点「一键升级」反而把本地开发版**降级**成 npm 旧版。
+//   修复：一律按 semver 顺序比较（数字三元组 + 预发布后缀），只有 registry 确实更新才提示/允许升级。
+//
+// 口径（与 docs/compatibility.md 公约 7 一致，并作为其 API 层扩写）：
+//   - 只解析**数字三元组**；`-rc/-beta/-alpha` 等预发布后缀**不参与**主序比较
+//     （0.1.0-rc.6 == 0.1.0），避免把 dev/RC 装机包判成"低于"目标版本。
+//   - 数字位允许不足三位（`0.2` 视作 `0.2.0`，`1` 视作 `1.0.0`）。
+//   - 比较失败（空值/非法格式）返回 `null`，调用方 fail-closed（不提示、不自动升级）。
+
+const SEMVER_RE = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/i;
+
+/**
+ * 解析版本号为主序三元组。
+ * @returns {[number, number, number] | null} 解析失败返回 null。
+ */
+export function parseVersion(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = SEMVER_RE.exec(raw.trim());
+  if (!m) return null;
+  const major = Number(m[1]);
+  const minor = m[2] === undefined ? 0 : Number(m[2]);
+  const patch = m[3] === undefined ? 0 : Number(m[3]);
+  if (![major, minor, patch].every((n) => Number.isSafeInteger(n) && n >= 0)) return null;
+  return [major, minor, patch];
+}
+
+/** 主序三元组比较。任一侧不可解析 → null。 */
+export function compareVersion(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * candidate 是否比 current **更新**（严格大于）。
+ * 不可解析（任一侧）→ false（fail-closed：宁可少提示，绝不误导升级/降级）。
+ */
+export function isNewerVersion(candidate, current) {
+  return compareVersion(candidate, current) === 1;
+}
+
+/**
+ * 更新检查的统一判定（/dshfly/plugins/checkUpdate 与前端共用口径）。
+ * @returns {{ updateAvailable: boolean, localAhead: boolean, comparable: boolean }}
+ *   - comparable=false：版本号无法解析 → 一律不提示更新（fail-closed）
+ *   - localAhead=true：本地（开发/预发布）版本比 registry 更新 → 不提示更新，
+ *     且 UI 需明示"本地版本更新（开发版）"，避免用户以为检查坏了
+ */
+export function summarizeUpdate({ current, latest }) {
+  const cmp = compareVersion(latest, current);
+  if (cmp === null) return { updateAvailable: false, localAhead: false, comparable: false };
+  return { updateAvailable: cmp === 1, localAhead: cmp === -1, comparable: true };
+}

package/dist/client.js

@@ -51,6 +51,11 @@ var zh = {
   upgradeFailed: "\u5347\u7EA7\u5931\u8D25",
   upToDate: "\u5DF2\u662F\u6700\u65B0\u7248\u672C",
   checkFailed: "\u68C0\u67E5\u66F4\u65B0\u5931\u8D25",
+  localAhead: "\u5F53\u524D\u4E3A\u672C\u5730\u5F00\u53D1\u7248\uFF0C\u6BD4 npm \u4E0A\u7684\u7248\u672C\u66F4\u65B0\uFF08\u4E0D\u4F1A\u964D\u7EA7\uFF09",
+  localAheadShort: "\u672C\u5730\u5F00\u53D1\u7248\uFF08\u65E0\u66F4\u65B0\uFF09",
+  depsBroken: "\u63D2\u4EF6\u4F9D\u8D56\u7F3A\u5931\uFF0Cdsh web \u53EF\u80FD\u65E0\u6CD5\u542F\u52A8",
+  depsMissing: "\u7F3A\u5C11\uFF1A",
+  depsFix: "\u8BF7\u5728\u63D2\u4EF6\u4ED3\u5E93\u6839\u76EE\u5F55\u6267\u884C pnpm install\uFF0C\u7136\u540E\u91CD\u542F dsh web\u3002",
   accountName: "\u8D26\u53F7",
   deviceId: "\u8BBE\u5907 ID",
   hostname: "\u8BA1\u7B97\u673A\u540D",
@@ -118,6 +123,11 @@ var en = {
   upgradeFailed: "Upgrade failed",
   upToDate: "Up to date",
   checkFailed: "Update check failed",
+  localAhead: "Local dev build is newer than the npm release (downgrade blocked)",
+  localAheadShort: "Local dev build (no update)",
+  depsBroken: "Plugin dependencies missing \u2014 dsh web may fail to start",
+  depsMissing: "Missing: ",
+  depsFix: "Run pnpm install at the plugin repo root, then restart dsh web.",
   accountName: "Account",
   deviceId: "Device ID",
   hostname: "Hostname",
@@ -202,6 +212,7 @@ var getRecommendedPlugins = () => request("/dshfly/plugins/recommended");
 var installPlugin = (id) => request("/dshfly/plugins/install", { method: "POST", body: JSON.stringify({ id }) });
 var checkUpdate = () => request("/dshfly/plugins/checkUpdate");
 var upgrade = () => request("/dshfly/plugins/upgrade", { method: "POST" });
+var doctor = () => request("/dshfly/doctor");
 
 // src/client/SettingsSection.jsx
 var sectionStyle = {
@@ -307,6 +318,7 @@ function SettingsSection({ t }) {
   const [installNotice, setInstallNotice] = (0, import_react.useState)(null);
   const [updateInfo, setUpdateInfo] = (0, import_react.useState)(null);
   const [updateBusy, setUpdateBusy] = (0, import_react.useState)(false);
+  const [doctorInfo, setDoctorInfo] = (0, import_react.useState)(null);
   const [toast, setToast] = (0, import_react.useState)(null);
   const toastTimer = (0, import_react.useRef)(null);
   const showToast = (0, import_react.useCallback)((text, kind = "ok") => {
@@ -321,6 +333,7 @@ function SettingsSection({ t }) {
       if (manual) {
         if (r.updateAvailable) showToast(t("updateAvailable") + ` v${r.latest}`, "ok");
         else if (r.error) showToast(`${t("checkFailed")}\uFF1A${r.error}`, "err");
+        else if (r.localAhead) showToast(t("localAhead"), "ok");
         else showToast(t("upToDate"), "ok");
       }
     } catch (e) {
@@ -331,17 +344,33 @@ function SettingsSection({ t }) {
   (0, import_react.useEffect)(() => {
     void loadUpdate(false);
   }, [loadUpdate]);
+  (0, import_react.useEffect)(() => {
+    let alive = true;
+    void (async () => {
+      try {
+        const r = await doctor();
+        if (alive) setDoctorInfo(r);
+      } catch {
+        if (alive) setDoctorInfo(null);
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, []);
   const onUpgrade = (0, import_react.useCallback)(async () => {
     setUpdateBusy(true);
     try {
       await upgrade();
       showToast(t("upgradeDone"), "ok");
+      void loadUpdate(false);
     } catch (e) {
       showToast(`${t("upgradeFailed")}\uFF1A${e.message}`, "err");
+      void loadUpdate(false);
     } finally {
       setUpdateBusy(false);
     }
-  }, [t, showToast]);
+  }, [t, showToast, loadUpdate]);
   const loadRecommended = (0, import_react.useCallback)(async () => {
     try {
       const r = await getRecommendedPlugins();
@@ -487,7 +516,7 @@ function SettingsSection({ t }) {
       }
     },
     /* @__PURE__ */ import_react.default.createElement("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.2", strokeLinecap: "round", strokeLinejoin: "round" }, /* @__PURE__ */ import_react.default.createElement("path", { d: "M21 12a9 9 0 1 1-2.64-6.36" }), /* @__PURE__ */ import_react.default.createElement("polyline", { points: "21 3 21 9 15 9" }))
-  ))), /* @__PURE__ */ import_react.default.createElement("p", { style: { margin: 0, fontSize: 13, color: "var(--dsw-alias-label-tertiary, inherit)", lineHeight: 1.6, maxWidth: 560 } }, t("intro")), updateInfo?.updateAvailable && /* @__PURE__ */ import_react.default.createElement("div", { style: { ...cardStyle, borderColor: "#e8890c", padding: "10px 16px" } }, /* @__PURE__ */ import_react.default.createElement("div", { style: { ...rowStyle, gap: 10 } }, /* @__PURE__ */ import_react.default.createElement("span", { style: { fontSize: 13, color: "#e8890c" } }, t("updateAvailable"), " v", updateInfo.latest), /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8 } }, /* @__PURE__ */ import_react.default.createElement("button", { style: btnStyle, onClick: onUpgrade, disabled: updateBusy }, updateBusy ? t("upgrading") : t("upgrade"))))), /* @__PURE__ */ import_react.default.createElement("div", { style: cardStyle }, /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("relayServer")), /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8 } }, statusBadge(status?.connection, t, status?.relayUrl), tokenBadge(status?.tokenState, t))), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("accountName")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.accountName || "\u2026")), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("deviceId")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.deviceId ? status.deviceId.slice(0, 12) + "\u2026" : "\u2026")), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("hostname")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.hostname || "\u2026"))), recommendedPending.length > 0 && /* @__PURE__ */ import_react.default.createElement("div", { style: cardStyle }, /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 15, fontWeight: "600" } }, t("recommendedTitle")), /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 13, opacity: 0.7, lineHeight: 1.5 } }, t("recommendedHint")), recommendedPending.map((p) => /* @__PURE__ */ import_react.default.createElement("div", { key: p.id, style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8, fontSize: 13 } }, /* @__PURE__ */ import_react.default.createElement("span", null, p.icon ? /* @__PURE__ */ import_react.default.createElement("span", { style: { fontSize: 16 } }, "\u{1F4E6}") : null), /* @__PURE__ */ import_react.default.createElement("span", null, /* @__PURE__ */ import_react.default.createElement("strong", null, p.title), " \u2014 ", p.description)), /* @__PURE__ */ import_react.default.createElement(
+  ))), /* @__PURE__ */ import_react.default.createElement("p", { style: { margin: 0, fontSize: 13, color: "var(--dsw-alias-label-tertiary, inherit)", lineHeight: 1.6, maxWidth: 560 } }, t("intro")), doctorInfo && doctorInfo.dependencies && !doctorInfo.dependencies.ok && /* @__PURE__ */ import_react.default.createElement("div", { style: { ...cardStyle, borderColor: "#d93025", padding: "10px 16px" } }, /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 13, color: "#d93025", fontWeight: 600 } }, t("depsBroken")), /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 12, lineHeight: 1.6, opacity: 0.85 } }, doctorInfo.dependencies.missing.length ? `${t("depsMissing")}${doctorInfo.dependencies.missing.join(", ")}` : t("depsBroken")), /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 12, opacity: 0.7 } }, t("depsFix"))), updateInfo?.updateAvailable && /* @__PURE__ */ import_react.default.createElement("div", { style: { ...cardStyle, borderColor: "#e8890c", padding: "10px 16px" } }, /* @__PURE__ */ import_react.default.createElement("div", { style: { ...rowStyle, gap: 10 } }, /* @__PURE__ */ import_react.default.createElement("span", { style: { fontSize: 13, color: "#e8890c" } }, t("updateAvailable"), " v", updateInfo.latest), /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8 } }, /* @__PURE__ */ import_react.default.createElement("button", { style: btnStyle, onClick: onUpgrade, disabled: updateBusy }, updateBusy ? t("upgrading") : t("upgrade"))))), updateInfo?.localAhead && /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 12, color: "var(--dsw-alias-label-tertiary, inherit)", display: "flex", alignItems: "center", gap: 6 } }, /* @__PURE__ */ import_react.default.createElement("span", { "aria-hidden": true }, "\u2022"), /* @__PURE__ */ import_react.default.createElement("span", null, t("localAhead"))), /* @__PURE__ */ import_react.default.createElement("div", { style: cardStyle }, /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("relayServer")), /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8 } }, statusBadge(status?.connection, t, status?.relayUrl), tokenBadge(status?.tokenState, t))), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("accountName")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.accountName || "\u2026")), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("deviceId")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.deviceId ? status.deviceId.slice(0, 12) + "\u2026" : "\u2026")), /* @__PURE__ */ import_react.default.createElement("div", { style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: labelStyle }, t("hostname")), /* @__PURE__ */ import_react.default.createElement("code", null, status?.hostname || "\u2026"))), recommendedPending.length > 0 && /* @__PURE__ */ import_react.default.createElement("div", { style: cardStyle }, /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 15, fontWeight: "600" } }, t("recommendedTitle")), /* @__PURE__ */ import_react.default.createElement("div", { style: { fontSize: 13, opacity: 0.7, lineHeight: 1.5 } }, t("recommendedHint")), recommendedPending.map((p) => /* @__PURE__ */ import_react.default.createElement("div", { key: p.id, style: rowStyle }, /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "flex", alignItems: "center", gap: 8, fontSize: 13 } }, /* @__PURE__ */ import_react.default.createElement("span", null, p.icon ? /* @__PURE__ */ import_react.default.createElement("span", { style: { fontSize: 16 } }, "\u{1F4E6}") : null), /* @__PURE__ */ import_react.default.createElement("span", null, /* @__PURE__ */ import_react.default.createElement("strong", null, p.title), " \u2014 ", p.description)), /* @__PURE__ */ import_react.default.createElement(
     "button",
     {
       style: btnStyle,