dsh-mobile-plugin 0.1.69 → 0.1.71

package/README.md

@@ -14,6 +14,9 @@ Electron 运行时**，`node host.js` 即可独立运行。
 
 本仓库是插件的**公开发布仓库**，仓库根就是包根：别人从这里读代码，也从这里核对这份代码的说法。
 
+隐私政策（App Store / Google Play 上架用的那份，描述手机 App 会经手哪些数据）：[PRIVACY.md](PRIVACY.md)。
+技术支持 / 常见问题（上架时填的「技术支持网址」）：[SUPPORT.md](SUPPORT.md)。
+
 开发和 App 客户端、中转服务器放在一起进行（一个私有 monorepo），所以这里的提交历史从拆分那天开始，
 不是项目历史 —— 每次发版，把同一次改动一起推到这里。
 
@@ -83,9 +86,18 @@ DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
 
 本包有两条完全不同的安装路径，别混用。
 
-**服务器 / 无头部署：源码同步。** 直接把仓库目录 rsync 到 `/opt/dsh-mobile/`，依赖只在首次装
-或 `package.json` 变了时重装，然后 `systemctl restart dsh-mobile-host`。这条路的版本号不参与
-任何判断，`package.json` 里的 version 写成什么都不会影响宿主行为。
+**服务器 / 无头部署：启动器 rsync + 插件本体走 npm。**（2026-10-11 改）那一台是**两半**，别混着看：
+
+- **启动器**：`host.js`、两层 patch、`config/`、内嵌的凭据包。把仓库目录 rsync 到 `/opt/dsh-mobile/`，
+  然后 `systemctl restart dsh-mobile-host` —— 它只负责把宿主那棵树拼起来。
+- **插件本体**：装在 profile 里，用 pnpm 从 npm 装：
+  `cd <DSH_HOME>/profiles/<profile> && pnpm add dsh-mobile-plugin@<版本>`。宿主按**绝对路径**挂那份的
+  `lib/index.js`（**稳定外壳**），所以这台面板里也有「检查 / 立即更新」，换代**不用重启宿主**。
+  profile 的 `autoInstallPeers: false` 是刻意的：peer 依赖（`@deepseek-ai/*`）由宿主自己的依赖树供，
+  两边必须解析到**同一份 realpath**，否则会出现两份 cordis（见 `lib/shell/manager.js` 的文件头）。
+- 挂哪一份由 `host.js` 现场判断（`profile` 里有没有这个包，不看环境变量）：装了挂那份外壳；
+  没装就退回**源码树直挂**（没有外壳，面板里更新不了，只能同步源码 + 重启宿主）。两种现场都会在
+  启动日志里打一行「挂载方式 = …」，`npm run test:plugin:server` 会核对它。
 
 **桌面端：从 npm 装，更新交给 DSH 的插件市场。**（2026-10 改的：此前是本包自带的 OTA +
 「稳定外壳 + 可热替换的代」，那套已经删掉。）

package/host.js

@@ -14,7 +14,7 @@
  * package's `cordis.patch.yml`.
  */
 
-import { writeFileSync } from 'node:fs'
+import { existsSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
@@ -59,6 +59,32 @@ try {
   initProfile(profileDir, PROFILE_TEMPLATES.web)
   const profile = loadProfile(BIN_NAME, PROFILE_NAME, INSTALL_ANCHOR, home, { userLayer: true })
 
+  /**
+   * 本插件是**装在这个 profile 里**的，还是「源码树直接跑」的？
+   *
+   * 这两种现场的挂载方式不一样，而差别全在「挂哪一份入口」上（2026-10-11 起两条都留着）：
+   *
+   *  - **装在 profile 里**（桌面端；服务器那台改成 `pnpm 装进 profile` 之后也是）→ 挂
+   *    `<profile>/node_modules/dsh-mobile-plugin/lib/index.js`，也就是**稳定外壳**：
+   *    查更新、装新版、就地换代那一套全在它手里，所以面板上才有「检查 / 立即更新」。
+   *  - **源码树直接跑**（老的无头部署、开发时直接 `node host.js`）→ 插件**就是** Loader 自己
+   *    正跑的那个包，没有任何人把它放进 `node_modules`，于是这一支挂随包发布的
+   *    `lib/impl.js`（真正的实现）。代价是**没有外壳** → 那台的面板里更新不了，只能同步
+   *    源码 + 重启宿主。
+   *
+   * **两处都走「绝对路径」而不是包名**：`cordis.patch.yml` 里那行按包名挂载是给桌面端用的，
+   * 无头宿主这边解析不到 —— loader 是从**它自己所在的位置**解析包名的（实测报错原文：
+   * `Cannot find package 'dsh-mobile-plugin' imported from <…>/@deepseek-ai/cordis-plugin-loader/lib/index.js`），
+   * 而它在宿主自己的依赖树里，profile 里装的那份它根本看不见。而 loader 对解析失败不是留一条
+   * 警告，是**整棵插件树加载失败**（服务器那台当年就是这么完全起不来的）。所以那行在无头宿主
+   * 里一律摘掉，由这里按绝对路径插一行 —— 装没装 profile 决定的是**挂哪一份**，不是挂不挂。
+   *
+   * 判据取「profile 里有没有这个包」，不看环境变量、不看目录名：装没装是事实，改不了口径。
+   */
+  const installedDir = join(profileDir, 'node_modules', BIN_NAME)
+  const selfInstalled = existsSync(join(installedDir, 'package.json'))
+  const selfPatches = loadOverlayPatches(BIN_NAME, join(PACKAGE_DIR, 'cordis.patch.yml'))
+
   // An empty entry list is the composition root: upstream fills the tree from
   // the profile's bundle layers; every plugin arrives via a patch layer.
   const rootConfig = join(profileDir, 'cordis.root.yml')
@@ -67,15 +93,24 @@ try {
   const patches = [
     ...profile.layers.flatMap(layer => layer.patches),
     ...profile.patches,
-    ...dropBareNameSelfMounts(loadOverlayPatches(BIN_NAME, join(PACKAGE_DIR, 'cordis.patch.yml')), BIN_NAME),
+    ...dropBareNameSelfMounts(selfPatches, BIN_NAME),
     // 宿主专属的层（不开浏览器、目录选择器钉成 browse）。刻意不放进
     // cordis.patch.yml：那一层桌面 GUI 也会加载，而桌面操作者就坐在机器前，
     // 不需要把原生目录选择器换成远程用的 browse 交互。
     ...loadOverlayPatches(BIN_NAME, join(PACKAGE_DIR, 'cordis.mobile-host.yml')),
     // The mobile API is this very package. The Loader imports an entry by bare
-    // name from its own location, and `dsh-mobile-plugin` is not installed
-    // there, so the row names the plugin's entry module by absolute path.
-    { insert: [{ id: 'mobile-api', name: join(PACKAGE_DIR, 'lib/impl.js'), config: { enabled: true } }] },
+    // name from its own location, and that location has no `dsh-mobile-plugin`,
+    // so the row names the entry module by absolute path — profile 里装了就挂
+    // 那份的外壳，没装就挂源码树自己的实现（见上）。
+    {
+      insert: [{
+        id: 'mobile-api',
+        name: selfInstalled
+          ? join(installedDir, 'lib', 'index.js')
+          : join(PACKAGE_DIR, 'lib/impl.js'),
+        config: { enabled: true },
+      }],
+    },
     // The DSH Web bundle disables every agent-plane row (shell, files, search,
     // skills, goals, planning, compaction, delegation) and lets each session
     // mount a preset instead — but it leaves the roster's shipped root to
@@ -93,6 +128,10 @@ try {
     },
   ]
 
+  process.stderr.write(
+    `${BIN_NAME}: 挂载方式 = ${selfInstalled ? `profile 里装的那份（${installedDir}，带稳定外壳，面板里能自更新）` : '源码树直挂（无外壳，更新靠同步源码 + 重启宿主）'}\n`,
+  )
+
   const ctx = await boot(BIN_NAME, rootConfig, patches, (hostCtx) => {
     // A headless mobile host has no command line: nothing passes flags and
     // nobody is watching a help screen. The web startup plugin still waits on

package/lib/client.js

@@ -12,15 +12,12 @@
  *    数据方向是单向的：桌面 → 宿主 → 手机。手机上手动折叠/展开只存在 App 本地
  *    （AsyncStorage），不会写回这份 localStorage。
  *
- * 2. **设置 →「移动端」**（设置菜单里的顶层一项，不再挂在内置插件页签下）。这一项现在
- *    只有一个东西：一个通往**网页版配置页面**的入口。界面本体（状态、配对、中转配置、
- *    维护、插件更新）全部在宿主吐出的那页 HTML 里（`GET /api/relay/panel`，源码在 React/）。
+ * 2. **设置 →「移动端」**（设置菜单里的顶层一项，不再挂在内置插件页签下）。保留
+ *    **网页版入口**，并只加一颗由可信本机 DSH 设置页操作的公网访问开关；网页管理默认关闭，
+ *    每次开启固定 2 小时，到期不因访问续时。管理界面本体仍在宿主吐出的 HTML 里。
  *
- *    为什么连「插件更新」都撤掉了：这一半是渲染器直接从 `node_modules` 加载的文件，
- *    **不可热替换** —— 从前插件自己那套热更新只换宿主侧的实现代，换不掉它，于是出现过
- *    「更新报成功、界面一动不动」。2026-10 起插件从 npm 分发、更新交给 DSH 的插件市场，
- *    插件自己不再更新任何一个字节，这条缝隙也就没了。所以这里刻意保持「薄」：改版式只需
- *    重装一次插件（市场里点一下），不用再怀疑哪一半是旧的。
+ *    为什么这里只加开关：这半边不可热替换，管理界面继续留在网页版；本机开关只控制
+ *    网页管理路由，不改手机 App API 或隧道状态。插件更新仍交给 DSH 插件市场。
  *
  * 3. **桌面端已读 → 宿主**（`startDesktopReadSync`）。桌面侧栏的「已完成待读」绿点
  *    只活在渲染进程内存里（`UiSession.completionUnread`），宿主和手机都读不到。
@@ -214,7 +211,11 @@ window.__ModuleLoader__.load({
         throw new Error(String((error && error.message) || error));
       }
       const body = await response.json().catch(() => ({}));
-      if (!response.ok) throw new Error(errorText(body, response.status));
+      if (!response.ok) {
+        const error = new Error(errorText(body, response.status));
+        error.status = response.status;
+        throw error;
+      }
       return body;
     }
 
@@ -505,76 +506,122 @@ window.__ModuleLoader__.load({
         heading: '移动端',
         cardPanel: '配置页面',
         openPanel: '打开配置页面',
-        openHint: '设置、配对、插件更新都在这个页面里。它跟着插件一起更新，改版式不用重装，也不用重启 DSH。',
+        openHint: '设置、配对和相关运维都在这个页面里。',
         panelPending: '正在读取页面地址…',
         panelMissing: '宿主还没给出页面地址，稍后再打开这一页试试。',
         loadFailed: '读取宿主状态失败',
+        webAccessOn: '公网网页管理已开放，到期时间',
+        webAccessOff: '公网网页管理已关闭',
+        webAccessOpen: '开放网页管理 2 小时',
+        webAccessClose: '立即关闭网页管理',
+        webAccessHint: '默认关闭；开启后 2 小时自动关闭，访问不会延长时间，也不影响手机 App。只可从本机 DSH 设置页开关。',
+        webAccessUnavailable: '正在读取本机访问状态…',
+        webAccessError: '更新网页访问状态失败',
       },
       en: {
         nav: 'Mobile',
         heading: 'Mobile',
         cardPanel: 'Configuration page',
         openPanel: 'Open the configuration page',
-        openHint: 'Settings, pairing and plugin updates all live on that page. It ships with the plugin, so layout changes need neither a reinstall nor a DSH restart.',
+        openHint: 'Settings, pairing and plugin maintenance live on this page.',
         panelPending: 'Reading the page address…',
         panelMissing: 'The host has not reported a page address yet — reopen this item in a moment.',
         loadFailed: 'Failed to read host status',
+        webAccessOn: 'Public web management is open until',
+        webAccessOff: 'Public web management is closed',
+        webAccessOpen: 'Open web management for 2 hours',
+        webAccessClose: 'Close web management now',
+        webAccessHint: 'Closed by default; opening lasts 2 hours and visits do not extend it. Mobile app access is unaffected. Only this local DSH settings page can toggle it.',
+        webAccessUnavailable: 'Reading local access status…',
+        webAccessError: 'Failed to update web access status',
       },
     };
 
     /* ── 设置项组件 ───────────────────────────────────────────────────────
-     * 这一项只干一件事：把人送去网页版（`GET /api/relay/panel`）。
-     *
-     * 界面本体（状态、配对、中转配置、维护、更新）全部在宿主吐出的那个网页里
-     * （源码在 `React/`，产物 `lib/panel/index.html`）。为什么只留一个链接：客户端半边
-     * 是渲染器直接读 `node_modules` 里的文件，**不可热替换**，改一次就要完整安装 + 重启
-     * DSH；而网页版跟着插件包一起更新，改版式重装一次插件就生效。
+     * 保持一个薄卡片：一个网页版入口，以及一个可信本机开关，控制网页管理是否短时向公网开放。
+     * 界面本体仍在宿主吐出的 HTML（源码 `React/`，产物 `lib/panel/index.html`）。
      *
-     * 更新也不再由插件自己做（2026-10 起）：一律走 DSH 的插件市场，插件包从 npm 来。
-     * 所以这里那两张卡片（网页入口 + 插件更新）里的更新那张也撤掉了 —— 少一件事就少一次
-     * 「半边是旧的」。
+     * 本机设置项半边来自渲染器的 `node_modules`，不可热替换；插件更新仍走 DSH 市场。
+     * 开关只影响控制面网页路由，不改移动 API、配对凭据或隧道状态。
      */
     function MobileSettingsSection({ t }) {
       /** null = 还没问到；'' = 问到了但这个宿主没给地址（老版本或还没起来）。 */
       const [panelUrl, setPanelUrl] = useState(null);
       const [error, setError] = useState(null);
+      const [webAccess, setWebAccess] = useState(null);
+      const [webAccessError, setWebAccessError] = useState(null);
+      const [webAccessBusy, setWebAccessBusy] = useState(false);
 
       useEffect(() => {
         let alive = true;
-        let timer = null;
-        const stop = () => {
-          if (timer !== null) {
-            clearInterval(timer);
-            timer = null;
-          }
+        let retryTimer = null;
+        let refreshTimer = null;
+        const clearTimer = (timer) => {
+          if (timer !== null) clearInterval(timer);
         };
-        /** 只问一次：地址由请求的 host 头算出来，问到就定了。 */
         const load = async () => {
           try {
             const next = await call('/status');
             if (!alive) return;
             setError(null);
             setPanelUrl(typeof next.panelUrl === 'string' ? next.panelUrl : '');
-            stop();
+            setWebAccess(next.webAccess && typeof next.webAccess.enabled === 'boolean' ? next.webAccess : null);
+            if (retryTimer !== null) {
+              clearTimer(retryTimer);
+              retryTimer = null;
+            }
+            if (refreshTimer === null) {
+              refreshTimer = setInterval(() => {
+                if (typeof document !== 'undefined' && document.hidden) return;
+                void load();
+              }, 15000);
+            }
           } catch (problem) {
-            // 宿主还没挂上控制面路由（刚启动）时问不到，过 3s 再问 —— 不然这一页会永久停在
-            // 「正在读取页面地址…」。真的拿到「这个宿主不给我地址」也算答到了，同样停。
             if (!alive) return;
             setError(String((problem && problem.message) || problem));
+            setWebAccess(null);
+            if (refreshTimer !== null) {
+              clearTimer(refreshTimer);
+              refreshTimer = null;
+            }
+            // 无权的远程设置页不轮询；宿主还没启动等临时故障每 3s 重试。
+            if (problem?.status !== 403 && problem?.status !== 423 && retryTimer === null) {
+              retryTimer = setInterval(() => {
+                if (typeof document !== 'undefined' && document.hidden) return;
+                void load();
+              }, 3000);
+            }
           }
         };
         void load();
-        timer = setInterval(() => {
-          if (typeof document !== 'undefined' && document.hidden) return;
-          void load();
-        }, 3000);
         return () => {
           alive = false;
-          stop();
+          clearTimer(retryTimer);
+          clearTimer(refreshTimer);
         };
       }, []);
 
+      const toggleWebAccess = async () => {
+        if (!webAccess || webAccessBusy) return;
+        setWebAccessBusy(true);
+        setWebAccessError(null);
+        try {
+          const next = await postJson('/web-access', { enabled: !webAccess.enabled });
+          setWebAccess(next.webAccess && typeof next.webAccess.enabled === 'boolean' ? next.webAccess : null);
+        } catch (problem) {
+          setWebAccessError(String((problem && problem.message) || problem));
+        } finally {
+          setWebAccessBusy(false);
+        }
+      };
+
       const url = typeof panelUrl === 'string' ? panelUrl : '';
+      const webAccessEnabled = Boolean(webAccess && webAccess.enabled);
+      const expiresAt = webAccess && Number.isFinite(webAccess.expiresAt)
+        ? new Date(webAccess.expiresAt).toLocaleTimeString()
+        : '';
+      let webAccessStatus = t('webAccessUnavailable');
+      if (webAccess) webAccessStatus = webAccessEnabled ? `${t('webAccessOn')} ${expiresAt}` : t('webAccessOff');
 
       return h('div', { className: 'dshm_root' }, [
         h('h2', { className: 'dshm_heading' }, t('heading')),
@@ -601,6 +648,17 @@ window.__ModuleLoader__.load({
               }, panelUrl === null ? t('panelPending') : t('panelMissing')),
           ]),
           h('p', { className: 'dshm_note' }, t('openHint')),
+          h('p', { className: 'dshm_note' }, webAccessStatus),
+          h('div', { className: 'dshm_actions' }, [
+            h('button', {
+              type: 'button',
+              className: webAccessEnabled ? 'dshm_btn' : 'dshm_btn dshm_btnPrimary',
+              disabled: !webAccess || webAccessBusy,
+              onClick: toggleWebAccess,
+            }, webAccessEnabled ? t('webAccessClose') : t('webAccessOpen')),
+          ]),
+          h('p', { className: 'dshm_note' }, t('webAccessHint')),
+          webAccessError ? h('p', { className: 'dshm_error' }, `${t('webAccessError')}: ${webAccessError}`) : null,
         ]),
       ]);
     }

package/lib/http/routing.js

@@ -13,6 +13,7 @@
  * 挡 token」这个刻意的不对称。
  */
 
+const net = require('node:net');
 const { sendJson, readJsonBody } = require('../shared/http-util');
 
 // Relay pairing cookies and instance headers are routing credentials only;
@@ -39,6 +40,38 @@ const crossSiteRequest = (req) => {
   try { return new URL(origin).host !== host } catch { return true }
 }
 
+// `trustedLocalUi` 是唯一允许开启网页管理窗口的来源判定，不等同于 localOnly：
+// 既要 socket 直连 loopback，也要 Host 是 loopback/localhost，并拒绝常见代理转发头。
+// 代理若改写 Host 且剥掉所有来源标记，后端无法从 HTTP 请求辨认原始客户端；这种代理配置
+// 不支持用它开启窗口（应从本机直连或 SSH 隧道访问）。
+const isLoopbackAddress = (address) => {
+  if (typeof address !== 'string' || !address) return false
+  const value = address.toLowerCase().replace(/^\[|\]$/g, '')
+  if (value === '::1' || value === '0:0:0:0:0:0:0:1') return true
+  const mapped = value.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/)
+  const ipv4 = mapped ? mapped[1] : value
+  if (net.isIP(ipv4) !== 4) return false
+  return Number(ipv4.split('.')[0]) === 127
+}
+
+const trustedLocalUi = (req) => {
+  const socket = req?.socket || req?.connection
+  if (!isLoopbackAddress(socket?.remoteAddress)) return false
+  const headers = req?.headers && typeof req.headers === 'object' ? req.headers : {}
+  for (const [name, value] of Object.entries(headers)) {
+    if (/^(?:forwarded$|x-forwarded-|x-real-ip$|via$|true-client-ip$|cf-connecting-ip$)/i.test(name)
+      && String(value || '').trim()) return false
+  }
+  const host = headers.host
+  if (typeof host !== 'string' || !host) return false
+  try {
+    const hostname = new URL(`http://${host}`).hostname.toLowerCase().replace(/^\[|\]$/g, '')
+    return hostname === 'localhost' || isLoopbackAddress(hostname)
+  } catch {
+    return false
+  }
+}
+
 // `method` 可以是单个方法名，也可以是方法名数组（同一个路径上挂 GET+POST，
 // 例如 /api/relay/desktop-view 既读快照又收回传）。单方法时的 405 文案保持不变。
 const localOnly = (method, handler) => async (req, res) => {
@@ -82,6 +115,8 @@ const createGuarded = (ctx, authorized, note = null) => (handler) => async (req,
 module.exports = {
   remoteRelayRequest,
   crossSiteRequest,
+  isLoopbackAddress,
+  trustedLocalUi,
   localOnly,
   readJson,
   createGuarded,

package/lib/impl.js

@@ -16,7 +16,7 @@ const pairingApproval = require('./relay/pairing-policy.js')
 const { sendJson, sendHtml } = require('./shared/http-util.js')
 // 控制面守卫（localOnly）与移动端守卫（guarded）都住在这里；两套守卫并排放，
 // 「控制面多挡跨站与 method、移动端只挡 token」这个不对称一眼可见。
-const { localOnly, readJson, createGuarded } = require('./http/routing.js')
+const { localOnly, trustedLocalUi, readJson, createGuarded } = require('./http/routing.js')
 const { registerMobileRoutes } = require('./routes/mobile-api.js')
 const { registerControlPlaneRoutes } = require('./routes/control-plane.js')
 const { hostMetadata, createStatusView } = require('./relay/status.js')
@@ -322,7 +322,7 @@ function apply(ctx) {
     // 更新的机制住在外壳（`lib/index.js`）里，代这边只把它开成本机接口。取不到就如实报
     // 不可用（`lib/impl.js` 被单独挂载时就是这样）。
     getPluginRuntime: () => (typeof ctx.get === 'function' ? ctx.get('dshMobilePluginRuntime') : null),
-    localOnly,
+    localOnly, trustedLocalUi,
     readJson,
     sendJson,
     // 面板页（lib/panel/index.html）整页吐给浏览器用；与控制面其它响应一样按注入传，不在这里 require，路由表才保持「只依赖注入项」。

package/lib/mirror/pusher.cjs

@@ -386,6 +386,13 @@ function createMirrorPusher(deps) {
     .sort((a, b) => a[1].dueAt - b[1].dueAt)
     .map(([sessionId]) => sessionId);
 
+  const retainSessionSignals = (sessionsBody) => {
+    if (typeof sessionSignal.retain !== 'function') return;
+    const items = sessionsBody?.body?.items;
+    if (!Array.isArray(items)) return;
+    sessionSignal.retain(items.map((item) => String(item?.sessionId || '')).filter(Boolean));
+  };
+
   const pushSessionNow = (sessionId, priority = 'event') => withSessionBuildSlot(priority, async () => {
     try {
       // 清单与消息快照并行：summary 用 Promise 传进去（见 buildSessionData 的注释），
@@ -407,6 +414,7 @@ function createMirrorPusher(deps) {
         noteSessionPushFailure(sessionId, new Error(reason));
         return;
       }
+      retainSessionSignals(sessionsBody);
       await pushMirrorPayload({
         kind: 'sync', at: Date.now(),
         activeSessionId: sessionId,
@@ -462,6 +470,7 @@ function createMirrorPusher(deps) {
         recordMirrorPush(false, wsBlocked || 'sessions 快照不可用，本次未推送')
         return
       }
+      retainSessionSignals(sessionsBody);
       const list = sessionsBody.body.items || [];
       const highPrio = sessionIds
         ? list.filter(s => sessionIds.includes(String(s.sessionId)))
@@ -521,6 +530,7 @@ function createMirrorPusher(deps) {
       // 判定并记录理由，别再无声无息。
       const sessionsBlocked = guardSessions(sessionsBody);
       if (sessionsBlocked) { if (online) recordMirrorPush(false, sessionsBlocked); return }
+      retainSessionSignals(sessionsBody);
       // 清单内容版本（lib/shared/list-revision.js 的哈希）：既是广播判据，也是下面
       // 「中转镜像里那一版是不是这份」的比对基准 —— 全函数只算这一次。
       const revision = sessionsRevisionOf(sessionsBody && sessionsBody.body);

package/lib/mobile/host-bridge/endpoints.js

@@ -107,6 +107,7 @@ const ENDPOINTS = {
 
   // skills / subagents
   'skills.list': inv('skills', 'list'),
+  'subagents.history': inv('subagents', 'history'),
   'subagents.prompt': inv('subagents', 'prompt', (p) => ({
     request: {
       ...pick(p, ['parentSessionId', 'childSessionId', 'mode', 'content', 'clientTimeZone']),

package/lib/mobile/session-models.js

@@ -84,16 +84,45 @@ function modelsBody(value, fetchedAt) {
   return result;
 }
 
+function startModelsRequest(ctx, entry, sessionId, fresh = false) {
+  // 在途的强制读挂在 entry 自己身上，不另开模块级表：entry 已经按 ctx + 设备 + 会话
+  // 隔离过（session-cache.js 的 sessionModelsStateOf），再建一张 WeakMap 只会多一份
+  // 需要解释归属的状态（见 test/module-split.test.cjs：模块级 WeakMap 只许住在
+  // session-cache.js 与 rpc.js）。
+  if (fresh) {
+    if (entry.freshPromise) return entry.freshPromise;
+    // A forced read supersedes an older normal request. Its eventual result must not overwrite fresh data.
+    entry.generation = (entry.generation || 0) + 1;
+  } else if (entry.promise) {
+    return entry.promise;
+  }
+  const generation = entry.generation || 0;
+  const request = Promise.resolve(callSessions(ctx, 'models', { sessionId })).then((response) => {
+    const { value, error } = unwrap(response);
+    if (error) return { error };
+    const safeValue = safeModelsValue(value);
+    const fetchedAt = Date.now();
+    if (generation === (entry.generation || 0)) {
+      entry.value = safeValue;
+      entry.fetchedAt = fetchedAt;
+    }
+    return { value: safeValue, fetchedAt };
+  });
+  const tracked = request.finally(() => { if (entry.promise === tracked) entry.promise = null; });
+  entry.promise = tracked;
+  if (!fresh) return tracked;
+  const forced = tracked.finally(() => { if (entry.freshPromise === forced) entry.freshPromise = null; });
+  entry.freshPromise = forced;
+  return forced;
+}
+
 async function buildModelsSnapshot(ctx, sessionId) {
   if (!sessionId) return { ok: false };
   const entry = sessionModelsStateOf(ctx, 'legacy', sessionId); const now = Date.now();
   if (entry.value && now - entry.fetchedAt < SESSION_MODELS_CACHE_MS) return modelsBody(entry.value, entry.fetchedAt);
-  if (!entry.promise) {
-    const request = Promise.resolve(callSessions(ctx, 'models', { sessionId })).then(response => { const { value, error } = unwrap(response); if (error) return { error }; entry.value = safeModelsValue(value); entry.fetchedAt = Date.now(); return { value: entry.value, fetchedAt: entry.fetchedAt }; });
-    const tracked = request.finally(() => { if (entry.promise === tracked) entry.promise = null; }); entry.promise = tracked;
-  }
-  if (entry.value) { void entry.promise.catch(() => undefined); return modelsBody(entry.value, entry.fetchedAt); }
-  const result = await entry.promise; return result.error ? { ok: false, error: result.error } : modelsBody(result.value, result.fetchedAt);
+  const request = startModelsRequest(ctx, entry, sessionId);
+  if (entry.value) { void request.catch(() => undefined); return modelsBody(entry.value, entry.fetchedAt); }
+  const result = await request; return result.error ? { ok: false, error: result.error } : modelsBody(result.value, result.fetchedAt);
 }
 
 /** GET /api/mobile/v1/session/models?sessionId=…（token）
@@ -105,31 +134,23 @@ async function handleModels(ctx, req, res) {
   const sessionId = url.searchParams.get('sessionId');
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
   const entry = sessionModelsStateOf(ctx, canonicalDeviceKey(req), sessionId);
+  const fresh = url.searchParams.get('fresh') === '1';
+  if (fresh) {
+    const result = await startModelsRequest(ctx, entry, sessionId, true);
+    if (result.error) return sendJson(res, 400, { ok: false, error: result.error });
+    return sendJson(res, 200, modelsBody(result.value, result.fetchedAt));
+  }
   const now = Date.now();
   if (entry.value && now - entry.fetchedAt < SESSION_MODELS_CACHE_MS) {
     return sendJson(res, 200, modelsBody(entry.value, entry.fetchedAt));
   }
-  if (!entry.promise) {
-    const request = Promise.resolve(callSessions(ctx, 'models', { sessionId })).then((response) => {
-      const { value, error } = unwrap(response);
-      if (error) return { error };
-      entry.value = safeModelsValue(value);
-      entry.fetchedAt = Date.now();
-      return { value: entry.value, fetchedAt: entry.fetchedAt };
-    });
-    // 与上面 buildModelsSnapshot 同一种写法：tracked 必须先声明再赋给 entry.promise。
-    // 反过来写（entry.promise = request.finally(…tracked) 在前）能跑，只因为 finally 的
-    // 回调是在微任务里才执行的，届时 const 已出 TDZ——但换个 await 位置就炸。
-    const tracked = request.finally(() => { if (entry.promise === tracked) entry.promise = null; });
-    entry.promise = tracked;
-  }
-  // Serve stale data immediately while one refresh is in flight. Initial loads
-  // still await the shared request, so concurrent cold requests collapse to one RPC.
+  const request = startModelsRequest(ctx, entry, sessionId);
+  // Normal reads keep stale-while-revalidate. Explicit fresh reads above always await the host.
   if (entry.value) {
-    void entry.promise.catch(() => undefined);
+    void request.catch(() => undefined);
     return sendJson(res, 200, modelsBody(entry.value, entry.fetchedAt));
   }
-  const result = await entry.promise;
+  const result = await request;
   if (result.error) return sendJson(res, 400, { ok: false, error: result.error });
   sendJson(res, 200, modelsBody(result.value, result.fetchedAt));
 }

package/lib/mobile/session-snapshot.js

@@ -4,12 +4,12 @@
  * 消息与统计快照：镜像推送与 /messages 分页共用的两条折叠路径。
  *
  * buildMessagesSnapshot（不解析 query）与 handleMessages（解析 beforeSeq/afterSeq/limit）
- * 是同一套折叠逻辑的两种调用方式，放在一起是为了让「增量水位」的算法改动只发生在
- * 一处——它们此前隔着一百多行，两边各写一遍归一化，迟早会漂移。
+ * 共用消息折叠逻辑。普通会话走 sessions.history；子代理必须携带 durable parent address，
+ * 改走 subagents.history，不能把 child sessionId 当普通会话读。
  *
- * 上游 session.history 不认 afterSeq（只认 beforeSeq/maxMessages），所以增量轮询在
- * 插件内用较大的窗口（Math.max(limit, 200)）拉最近若干事件后再按 seq 过滤；缺口
- * 超过窗口时会漏，此时用 resyncRequired 让客户端回落到权威快照，而不是安静地少消息。
+ * 上游历史接口不认 afterSeq（只认 beforeSeq/maxMessages），所以增量轮询在插件内用较大的
+ * 窗口（Math.max(limit, 200)）拉最近若干事件后再按 seq 过滤；缺口超过窗口时会漏，此时
+ * 用 resyncRequired 让客户端回落到权威快照，而不是安静地少消息。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -21,6 +21,26 @@ const { createTextImageBudget } = require('./local-images.js');
 
 const MESSAGES_DEFAULT_LIMIT = 50;  // /messages 默认条数
 
+function historyHttpStatus(error) {
+  switch (error && error.code) {
+    case 'bad-request': return 400;
+    case 'session-not-found':
+    case 'subagent-not-found': return 404;
+    case 'subagent-unauthorized': return 403;
+    case 'host-unavailable': return 503;
+    default: return 502;
+  }
+}
+
+function normalizeHistoryError(error) {
+  return {
+    code: error && typeof error.code === 'string' ? error.code : 'host-call-failed',
+    message: error && typeof error.message === 'string' && error.message
+      ? error.message
+      : '读取会话历史失败',
+  };
+}
+
 /** 从 history 事件条目取事件序号（entry.event.seq，兼容裸事件 entry.seq）。 */
 function eventSeqOf(entry) {
   if (!entry) return undefined;
@@ -91,6 +111,15 @@ async function handleMessages(ctx, req, res) {
   const url = new URL(req.url, 'http://x');
   const sessionId = url.searchParams.get('sessionId');
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  const parentSessionId = url.searchParams.get('parentSessionId');
+  const mode = url.searchParams.get('mode');
+  const hasSubagentAddress = parentSessionId !== null || mode !== null;
+  if (hasSubagentAddress && (
+    typeof parentSessionId !== 'string' || !parentSessionId.trim()
+    || (mode !== 'one-shot' && mode !== 'continuable')
+  )) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '子代理历史需要 parentSessionId 和有效 mode' } });
+  }
   const beforeSeqRaw = url.searchParams.get('beforeSeq');
   const beforeSeq = beforeSeqRaw !== null && /^\d+$/.test(beforeSeqRaw) && Number.isSafeInteger(Number(beforeSeqRaw))
     ? Number(beforeSeqRaw) : null;
@@ -106,12 +135,34 @@ async function handleMessages(ctx, req, res) {
   }
   const payload = { sessionId, maxMessages: limit };
   if (beforeSeq !== null) payload.beforeSeq = beforeSeq;
-  // 上游 session.history 不支持 afterSeq（只认 beforeSeq/maxMessages），故在插件内
-  // 用较大的窗口（Math.max(limit, 200)）拉最近若干事件后再过滤 seq > afterSeq，覆盖常见轮询缺口；
-  // 若缺口超过窗口才会漏（简单且安全的折中，不动上游分页协议）。
+  // 上游历史接口都不支持 afterSeq（只认 beforeSeq/maxMessages），故在插件内用较大的窗口
+  // 拉最近若干事件后再过滤 seq > afterSeq，覆盖常见轮询缺口；缺口超过窗口时要求客户端全量补齐。
   if (afterSeq !== null) payload.maxMessages = Math.max(limit, 200);
-  const { value, error } = unwrap(await callSessions(ctx, 'history', payload));
-  if (error) return sendJson(res, 400, { ok: false, error });
+
+  let value;
+  let error;
+  try {
+    if (hasSubagentAddress) {
+      const historyPayload = {
+        parentSessionId,
+        childSessionId: sessionId,
+        mode,
+        maxMessages: payload.maxMessages,
+      };
+      if (payload.beforeSeq !== undefined) historyPayload.beforeSeq = payload.beforeSeq;
+      const controller = new AbortController();
+      ({ value, error } = unwrap(await ctx.apiProxy.subagents.history({
+        rpcId: 'mobile',
+        method: 'subagent.history',
+        payload: historyPayload,
+      }, controller.signal)));
+    } else {
+      ({ value, error } = unwrap(await callSessions(ctx, 'history', payload)));
+    }
+  } catch (thrown) {
+    error = normalizeHistoryError(thrown);
+  }
+  if (error) return sendJson(res, historyHttpStatus(error), { ok: false, error });
   const events = (value && value.events) || [];
   // 增量：只保留水位之后的事件；非 afterSeq 调用时 events 原样保留（行为与之前完全一致）。
   const filtered = afterSeq !== null ? events.filter((entry) => (eventSeqOf(entry) ?? -1) > afterSeq) : events;

package/lib/mobile/sessions.js

@@ -67,24 +67,32 @@ const SESSION_LIST_CACHE_MS = 10000;  // 会话列表增料缓存（降低手机
 const RUNNING_PREVIEW_MIN_INTERVAL_MS = 3000;
 
 /**
- * 宿主的归档会话集合（`workspace.list` 的 `archivedSessionIds`）。
+ * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
  *
- * 桌面端侧边栏据此把归档会话藏起来，而 `sessions.list` 自身**不过滤**归档，
- * 所以移动端必须自己读这个集合：此前完全没读，App 的「归档会话」写是写成功了
- * （宿主确实把 id 记进了 archivedSessionIds），列表却照旧把那一行发回手机，
- * 用户看到的就是一次毫无反馈的空操作。
+ *   - `archivedSessionIds`：已归档的会话。桌面端侧边栏据此把它们藏起来，而
+ *     `sessions.list` 自身**不过滤**归档，所以移动端必须自己读这个集合：此前完全没读，
+ *     App 的「归档会话」写是写成功了（宿主确实把 id 记进了 archivedSessionIds），列表却
+ *     照旧把那一行发回手机，用户看到的就是一次毫无反馈的空操作。
+ *   - `pinnedSessionIds`：已置顶的会话（宿主侧「最近置顶的在前」）。桌面端也只从这份
+ *     快照读置顶，`sessions.list` 的摘要里没有置顶字段，所以移动端同样要自己读，
+ *     否则 App 既画不出置顶标记、也排不到工作区最前。
  *
- * 取不到时返回空集合（失败放开）：宁可多显示一行，也不能因为一次 RPC 抖动
- * 让整个会话列表凭空变空。
+ * 两个集合合并成一次 RPC：它们同源同一次快照，而会话列表每 10 秒就会重建一次，
+ * 分两次 `workspace.list` 等于平白给手机多塞一轮往返。
+ *
+ * 取不到时两个集合都回空（失败放开）：宁可多显示几行、少几个置顶，也不能因为一次
+ * RPC 抖动让整个会话列表凭空变空。
  */
-async function archivedSessionIdSet(ctx) {
+async function workspaceSessionFlags(ctx) {
   try {
     const resp = await ctx.apiProxy.workspace.list({ rpcId: 'mobile', method: 'workspace.list', payload: {} });
     const value = unwrap(resp).value;
-    const ids = value && Array.isArray(value.archivedSessionIds) ? value.archivedSessionIds : [];
-    return new Set(ids.filter(id => typeof id === 'string'));
+    const idSetOf = (field) => new Set(
+      value && Array.isArray(value[field]) ? value[field].filter(id => typeof id === 'string') : [],
+    );
+    return { archived: idSetOf('archivedSessionIds'), pinned: idSetOf('pinnedSessionIds') };
   } catch {
-    return new Set();
+    return { archived: new Set(), pinned: new Set() };
   }
 }
 
@@ -139,17 +147,23 @@ async function handleSessions(ctx, req, res) {
   const now = Date.now();
   // 写操作之后的刷新带 ?fresh=1：跳过这层 10s 缓存、在途构建与宿主 list 的合流，直接按最新状态重建。
   const wantFresh = isFreshRequest(req.url);
+  // 「只看已归档」筛选带 ?archived=1（见 buildSessionsResponse 的 archivedOnly）：它返回的
+  // 是同一批会话的**另一个子集**，不能与默认视图共用这份 10 秒缓存——否则 App 点完
+  // 「筛选已归档会话」后，最长 10 秒内拿到的还是那份不含归档行的默认列表。
+  // 与 fresh 的区别：它只绕开这层缓存，不需要作废在途构建，也不 bump 朝代号（没有写入）。
+  const archivedOnly = new URL(req.url, 'http://x').searchParams.get('archived') === '1';
+  const bypassCache = wantFresh || archivedOnly;
   if (wantFresh) {
     // 顺手作废更早发起的构建：它们手里的数据是写入之前的，若在新结果之后才落地会把旧列表又写回缓存。
     cache.value = null;
     cache.updatedAt = 0;
     generation = bumpCompletionGeneration(ctx, deviceKey);
   }
-  if (!wantFresh && cache.value && now - cache.updatedAt < SESSION_LIST_CACHE_MS) {
+  if (!bypassCache && cache.value && now - cache.updatedAt < SESSION_LIST_CACHE_MS) {
     return sendJson(res, 200, cache.value);
   }
 
-  if (!wantFresh && cache.promise) {
+  if (!bypassCache && cache.promise) {
     const response = await cache.promise;
     return sendJson(res, response.status, response.body);
   }
@@ -158,7 +172,7 @@ async function handleSessions(ctx, req, res) {
   // 但「丢掉」挡不住**已经在飞**的那次构建：它手里是变更之前的数据，落地后会在缓存里
   // 再活 10 秒。用缓存自带的朝代号兜住（见 session-cache.js 的 dropSessionListCache）。
   const epoch = cache.droppedAt || 0;
-  const promise = buildSessionsResponse(ctx, deviceKey, generation, wantFresh);
+  const promise = buildSessionsResponse(ctx, deviceKey, generation, wantFresh, archivedOnly);
   cache.promise = promise;
   try {
     const response = await promise;
@@ -169,7 +183,7 @@ async function handleSessions(ctx, req, res) {
       // 周期。15 秒轮询本来就跨过 10 秒窗口，这层缓存的收益只体现在突发刷新上。
       const hasRunning = Array.isArray(response.body && response.body.items)
         && response.body.items.some((item) => item && item.running);
-      if (!hasRunning) {
+      if (!hasRunning && !archivedOnly) {
         cache.value = response.body;
         cache.updatedAt = Date.now();
       }
@@ -180,7 +194,7 @@ async function handleSessions(ctx, req, res) {
   }
 }
 
-async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = completionGenerationOf(ctx, deviceKey), fresh = false) {
+async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = completionGenerationOf(ctx, deviceKey), fresh = false, archivedOnly = false) {
   const { value, error } = unwrap(await callSessions(ctx, 'list', {}, 'mobile', undefined, { fresh }));
   if (error) return { status: 400, body: { ok: false, error } };
   // 形状不对 = 没取到，不是「你一个会话都没有」。旧实现 `(value.items || [])` 把
@@ -199,9 +213,13 @@ async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = com
     };
   }
   // 归档会话在这里剔除，与桌面端侧边栏行为一致：宿主 sessions.list 自己不过滤归档，
-  // 「哪些会话已归档」只存在于 workspaceRegistry.archivedSessionIds（见 archivedSessionIdSet）。
-  const archived = await archivedSessionIdSet(ctx);
-  const allSummaries = summaries.filter(s => s && !archived.has(s.sessionId));
+  // 「哪些会话已归档」只存在于 workspaceRegistry.archivedSessionIds（见 workspaceSessionFlags）。
+  // archivedOnly（App 的「只看已归档」筛选视图）反过来只保留归档里的那些行：默认视图藏
+  // 它们，筛选视图正是为了把它们找回来（查看 / 取消归档）。
+  const { archived, pinned } = await workspaceSessionFlags(ctx);
+  const allSummaries = archivedOnly
+    ? summaries.filter(s => s && archived.has(s.sessionId))
+    : summaries.filter(s => s && !archived.has(s.sessionId));
   // 状态跟踪覆盖完整列表，不能受预览补全上限影响。
   const completionStatesForContext = updateCompletionStates(ctx, allSummaries, deviceKey);
   // 列表完整返回：侧边栏分组依赖全部会话（工作区 sessionIds 排序 + 未分组兜底），
@@ -226,6 +244,10 @@ async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = com
       cwd: s.cwd || null,
       // 会话定档的 Agent 预设（宿主 session.list 摘要里带，用来显示会话当前预设）。
       ...(typeof s.agentPreset === 'string' && s.agentPreset ? { agentPreset: s.agentPreset } : {}),
+      // 置顶来自 workspace.list 的 pinnedSessionIds（宿主 session.list 摘要里没有这个字段），
+      // 与归档同源同一份快照。App 侧栏据此把这条排到工作区最前、并在行尾画图钉标记。
+      // 和归档一样只在真置顶时出现：旧 App 忽略未知字段，行为不变。
+      ...(pinned.has(s.sessionId) ? { pinned: true } : {}),
       updatedAt: s.updatedAt || 0,
       lastMessage: null,
       ...(s.origin === 'subagent' ? { origin: s.origin } : {}),

package/lib/mobile/subagents.js

@@ -10,8 +10,9 @@
  * 于是用户既不知道这个会话派过子代理，也没有任何入口能打开它 —— 子代理在手机上
  * 等于不存在。
  *
- * 子会话本身其实早就读得到：/sessions 会带上 origin/parentSessionId，/session 与
- * /session/messages 也能直接读子会话的记录。缺的只是「这个会话有哪些子代理」——
+ * 子会话在普通消息接口中只有携带 durable parent address 才能读取（parentSessionId + mode）；
+ * /sessions 只给 origin/parentSessionId，mode 则来自这里的子代理目录。缺的只是
+ * 「这个会话有哪些子代理」——
  * 那正是 subagent.list 的返回值（entries + parentAvailable），这里只做形状收敛、
  * 限长与限条数，避免异常宿主把手机端列表撑爆。
  *

package/lib/mobile/workspaces.js

@@ -201,6 +201,58 @@ async function handleArchiveSession(ctx, req, res) {
   sendJson(res, outcome.status, outcome.body);
 }
 
+/**
+ * 会话级开关写的公共骨架（取消归档 / 置顶 / 取消置顶三条共用）。
+ *
+ * 与 handleArchiveSession 完全同一套口径：请求体只要 sessionId；按 requestId 走幂等
+ * 重放（宿主的这三个动词本身幂等，但重投要拿到和第一次一样的响应体）；成功后立刻作废
+ * 会话列表缓存，否则 App 按完最长 10 秒里拿到的还是旧那一行，看着像没生效。
+ *
+ * 宿主回执分别是 `{ archivedSessionIds }` / `{ pinnedSessionIds }`（后者按「最近置顶的
+ * 在前」排序），原样透传给 App——它据此立刻重排侧栏。
+ */
+async function runSessionFlagWrite(ctx, req, res, method) {
+  const body = await readJsonBody(req, 64 * 1024);
+  const sessionId = body && typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+  if (!sessionId) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 sessionId' } });
+  }
+  const outcome = await withIdempotency(ctx, canonicalDeviceKey(req), requestIdOf(req, body), async () => {
+    const { value, error } = unwrap(await callWorkspace(ctx, method, { sessionId }));
+    if (error) return { status: 400, body: { ok: false, error } };
+    invalidateSessionList(ctx);
+    return { status: 200, body: { ok: true, ...(value || {}) } };
+  });
+  sendJson(res, outcome.status, outcome.body);
+}
+
+/**
+ * POST /api/mobile/v1/workspace/unarchive-session（token）{ sessionId }
+ * 透传宿主 workspace.unarchiveSession：把会话移出归档集合（未归档的 id 是 no-op）。
+ * 移动端此前没有任何取消归档入口，而归档又是移动端唯一的「删除」语义——归档错了
+ * 就只能去桌面端捞回来。
+ */
+async function handleUnarchiveSession(ctx, req, res) {
+  return runSessionFlagWrite(ctx, req, res, 'unarchiveSession');
+}
+
+/**
+ * POST /api/mobile/v1/workspace/pin-session（token）{ sessionId }
+ * 透传宿主 workspace.pinSession：把会话加进置顶集合（宿主侧对已归档会话报
+ * `gateway/bad-request`，所以 App 的置顶入口在归档行上不出现）。
+ */
+async function handlePinSession(ctx, req, res) {
+  return runSessionFlagWrite(ctx, req, res, 'pinSession');
+}
+
+/**
+ * POST /api/mobile/v1/workspace/unpin-session（token）{ sessionId }
+ * 透传宿主 workspace.unpinSession：把会话移出置顶集合（未置顶的 id 是 no-op）。
+ */
+async function handleUnpinSession(ctx, req, res) {
+  return runSessionFlagWrite(ctx, req, res, 'unpinSession');
+}
+
 module.exports = {
   buildWorkspacesBody,
   handleWorkspaces,
@@ -211,4 +263,7 @@ module.exports = {
   handleDeleteWorkspace,
   handleMoveSession,
   handleArchiveSession,
+  handleUnarchiveSession,
+  handlePinSession,
+  handleUnpinSession,
 };

package/lib/routes/control-plane.js

@@ -45,6 +45,47 @@ const { clearCompletionForAllDevices, invalidateSessionList } = require('../mobi
 /** 一次 desktop-read 上报最多带多少个会话 id（防灌爆；客户端半边一次最多也就几个）。 */
 const MAX_DESKTOP_READ_IDS = 200;
 
+function createWebAccessWindow({ now = Date.now, monotonicNow = () => performance.now() } = {}) {
+  let deadline = 0;
+  let expiresAt = 0;
+  const status = () => {
+    const current = monotonicNow();
+    if (deadline <= current) {
+      deadline = 0;
+      expiresAt = 0;
+      return { enabled: false, expiresAt: 0 };
+    }
+    return { enabled: true, expiresAt };
+  };
+  return {
+    status,
+    isOpen: () => status().enabled,
+    enable() {
+      deadline = monotonicNow() + WEB_ACCESS_WINDOW_MS;
+      expiresAt = now() + WEB_ACCESS_WINDOW_MS;
+      return status();
+    },
+    disable() {
+      deadline = 0;
+      expiresAt = 0;
+      return status();
+    },
+  };
+}
+
+function createWebAccessLocalOnly({ localOnly, trustedLocalUi, webAccessWindow, sendJson }) {
+  return (method, handler) => localOnly(method, async (req, res) => {
+    const route = String(req?.url || '').split('?', 1)[0];
+    if (WEB_ACCESS_ROUTES.has(route) && !trustedLocalUi(req) && !webAccessWindow.isOpen()) {
+      return sendJson(res, 423, {
+        ok: false,
+        error: { code: 'web_access_closed', message: '网页管理暂未开放，请从 DSH 本机设置页开启 2 小时窗口' },
+      });
+    }
+    return handler(req, res);
+  });
+}
+
 /**
  * 面板页（`React/` 那份 React 源码构建成的单文件 HTML）在包里的位置。
  *
@@ -165,7 +206,8 @@ function panelUrlOf(req) {
 function registerControlPlaneRoutes(deps) {
   const {
     registerRoute,
-    localOnly,
+    localOnly: baseLocalOnly,
+    trustedLocalUi,
     readJson,
     sendJson,
     sendHtml,
@@ -194,6 +236,13 @@ function registerControlPlaneRoutes(deps) {
     // 缺省返回 null：`lib/impl.js` 单独挂载时（测试 / 老宿主）没有外壳，如实报不可用。
     getPluginRuntime = () => null,
   } = deps;
+  const webAccessWindow = createWebAccessWindow();
+  const localOnly = createWebAccessLocalOnly({
+    localOnly: baseLocalOnly,
+    trustedLocalUi: typeof trustedLocalUi === 'function' ? trustedLocalUi : () => false,
+    webAccessWindow,
+    sendJson,
+  });
 
   // Pairing approval. The desktop shell used to answer this with an interactive
   // prompt; a headless host has no surface for one, so `pairingPolicy` decides.
@@ -229,7 +278,17 @@ function registerControlPlaneRoutes(deps) {
     const preferred = typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : ''
     sendJson(res, 200, { ok: true, port, preferred, lan: lanCandidates(port), public: publicCandidates(port) })
   }) })
-  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), ...mobileActivity() })) })
+  // 只有可信本机设置入口可以开 / 关窗口；窗口状态仅驻留进程内，DSH 重启后必定关闭。
+  registerRoute({ kind: 'exact', path: '/api/relay/web-access', handler: localOnly('POST', async (req, res) => {
+    if (typeof trustedLocalUi !== 'function' || !trustedLocalUi(req)) return sendJson(res, 403, { ok: false, error: { code: 'local_ui_only', message: '请从 DSH 本机设置页管理网页访问' } });
+    const body = await readJson(req);
+    if (typeof body?.enabled !== 'boolean') {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } });
+    }
+    const webAccess = body.enabled ? webAccessWindow.enable() : webAccessWindow.disable();
+    return sendJson(res, 200, { ok: true, webAccess });
+  }) });
+  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), webAccess: webAccessWindow.status(), ...mobileActivity() })) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
   // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
   //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
@@ -587,6 +646,38 @@ function registerControlPlaneRoutes(deps) {
   }) })
 }
 
+// 路由字符串清单放在注册区之后，避免被按路由源码切片的契约测试误认为是真正的 handler。
+/** 网页管理的固定开放窗口；按单调时钟计时，系统校时不会把窗口意外延长。 */
+const WEB_ACCESS_WINDOW_MS = 2 * 60 * 60 * 1000;
+const WEB_ACCESS_ROUTES = new Set([
+  '/api/relay/addresses',
+  '/api/relay/status',
+  '/api/relay/panel',
+  '/api/relay/panel/setup',
+  '/api/relay/panel/settings',
+  '/api/relay/faults',
+  '/api/relay/pairing',
+  '/api/relay/toggle',
+  '/api/relay/regenerate',
+  '/api/relay/onboarded',
+  '/api/relay/revoke-all',
+  '/api/relay/config',
+  '/api/relay/check-port',
+  '/api/relay/reconnect',
+  '/api/relay/update/status',
+  '/api/relay/update/check',
+  '/api/relay/update/apply',
+  '/api/relay/update/auto',
+  '/api/relay/restart-sidecar',
+]);
+
 // `panelDiagnosis` 一并导出，只为让 test/panel-artifact.test.cjs 能拿临时目录跑那三条分支：
 // 三种「读不到」的文案分别对应「重启 / 升级 / 构建」，它们混起来就是这个 bug 的原样。
-module.exports = { registerControlPlaneRoutes, panelDiagnosis };
+module.exports = {
+  registerControlPlaneRoutes,
+  panelDiagnosis,
+  WEB_ACCESS_ROUTES,
+  WEB_ACCESS_WINDOW_MS,
+  createWebAccessWindow,
+  createWebAccessLocalOnly,
+};

package/lib/routes/mobile-api.js

@@ -167,6 +167,11 @@ function registerMobileRoutes(deps) {
   // 但插件从来没有注册 → 移动端「重命名工作区」和「归档会话」必然 404。
   route('/api/mobile/v1/workspace/rename', workspaces.handleRenameWorkspace)
   route('/api/mobile/v1/workspace/archive-session', workspaces.handleArchiveSession)
+  // 会话级开关的反向动作：取消归档 / 置顶 / 取消置顶。桌面端这三件事都有入口
+  // （行尾按钮 + 会话菜单），移动端此前一个都没有——归档错了只能回桌面端捞。
+  route('/api/mobile/v1/workspace/unarchive-session', workspaces.handleUnarchiveSession)
+  route('/api/mobile/v1/workspace/pin-session', workspaces.handlePinSession)
+  route('/api/mobile/v1/workspace/unpin-session', workspaces.handleUnpinSession)
   // 桌面端 `/export` 其实是两步：命令本身只留一行 transcript 标记，真正的下载由
   // @deepseek-ai/dsh-session-log-export 在浏览器侧监听 command/executed 后拉
   // `GET /api/session.export` 完成。手机端没有浏览器下载管理器，而那个端点绑在宿主

package/lib/shared/session-signal.js

@@ -26,10 +26,8 @@
 const NOOP_RELEASE = () => {};
 
 /**
- * 最多记多少会话的水位。
- *
- * 键是 sessionId、只增不减：一个长期运行的插件会见过成千上万个会话（归档的、一次性的），
- * 而水位只用来判「这次广播是不是新的」，旧会话的水位没有任何价值。超限时丢最早活动的那条。
+ * 最多额外保留多少个非当前会话水位。当前完整会话清单通过 retain() 保留，不受此上限影响；
+ * 这样长跑插件仍能回放所有未归档会话，同时把归档/一次性会话的尾巴限制在有限范围内。
  */
 const MAX_TRACKED = 512;
 
@@ -37,14 +35,21 @@ function createSessionSignal() {
   const listeners = new Set();
   /** sessionId -> { seq, at }：最近一次广播出去的水位。 */
   const watermarks = new Map();
+  const retainedSessionIds = new Set();
 
   const pruneOldest = () => {
     let oldestKey = null;
     let oldestAt = Infinity;
     for (const [key, value] of watermarks) {
+      if (retainedSessionIds.has(key)) continue;
       if (value.at < oldestAt) { oldestAt = value.at; oldestKey = key; }
     }
     if (oldestKey !== null) watermarks.delete(oldestKey);
+    return oldestKey !== null;
+  };
+
+  const trimWatermarks = () => {
+    while (watermarks.size > MAX_TRACKED && pruneOldest()) { /* keep every current session */ }
   };
 
   return {
@@ -66,13 +71,28 @@ function createSessionSignal() {
       if (previous && value <= previous.seq) return false;
       const at = Date.now();
       watermarks.set(id, { seq: value, at });
-      if (watermarks.size > MAX_TRACKED) pruneOldest();
+      trimWatermarks();
       for (const listener of [...listeners]) {
         try { listener({ sessionId: id, seq: value, at }); } catch { /* 订阅者自己的异常不该影响推送方 */ }
       }
       return true;
     },
 
+    /**
+     * 声明当前完整、未归档会话集合；这些水位必须留到 SSE 重连回放，超出时只淘汰非当前会话。
+     * 同时清除刚从权威列表消失的会话（归档/删除），避免重放幽灵水位。
+     */
+    retain(sessionIds) {
+      const next = new Set(Array.isArray(sessionIds) ? sessionIds.filter((id) => typeof id === 'string' && id.length > 0) : []);
+      for (const id of watermarks.keys()) {
+        if (!next.has(id)) watermarks.delete(id);
+      }
+      retainedSessionIds.clear();
+      for (const id of next) retainedSessionIds.add(id);
+      trimWatermarks();
+      return retainedSessionIds.size;
+    },
+
     /** 订阅水位变化；返回退订函数（可重复调用）。 */
     onBump(listener) {
       if (typeof listener !== 'function') return NOOP_RELEASE;
@@ -101,6 +121,7 @@ function createSessionSignal() {
     /** 测试用：清空状态。 */
     reset() {
       watermarks.clear();
+      retainedSessionIds.clear();
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",