@yezack/dsh-remote-mobile 1.9.2 → 1.10.2

package/lib/index.js

@@ -12,14 +12,30 @@
  * 7. 配置持久化于插件自有文件 ~/.dsh/remote-mobile/settings.json（DSH 0.1.7+ 起官方已弃用 settings.yaml），
  *    启动时一次性兼容迁移旧 settings.yaml / settings.yaml.imported 中的配置。
  */
+import { createRequire } from 'node:module';
+import { installStartupFailureHint } from './startup-hint.js';
 import { SessionStore } from './auth/token.js';
 import { createGlobalAuthGate } from './auth/gate.js';
 import { createRoutes } from './routes/api.js';
+import { registerWebRoutes } from './routes/register.js';
 import { StyleSnippetStore } from './styles/style-snippets.js';
 import { getLocalTailscaleIp, getLocalLanIp } from './auth/tailscale.js';
-import { patchHttpServerWithVirtualizer, mountIndexInjections, registerRemoteWebUiPairingBridge, takeOverConnectionAuth, } from './bridge/compat.js';
+import { patchHttpServerWithVirtualizer, mountIndexInjections, registerRemoteWebUiPairingBridge, takeOverConnectionAuth, injectTrustedHosts, } from './bridge/compat.js';
+import { bindDirectoryPickerRuntime, getDirectoryPickerStatus } from './bridge/directory-picker.js';
+import { detectServerMode } from './gateway/detector.js';
+import { GatewayServer } from './gateway/server.js';
+import { generateGatewaySecret, setGatewaySecret, clearGatewaySecret } from './gateway/secret.js';
+// 该 hook 必须在模块顶层注册，才能捕获 webserver 在插件 apply 前的启动失败。
+installStartupFailureHint();
 /** Cordis 插件名称标识 */
 export const name = 'dsh-remote-mobile';
+/** 服务端 Banner 使用的插件版本（从安装包 package.json 读取，避免与客户端版本常量重复维护） */
+let pluginVersion = '';
+try {
+    const require = createRequire(import.meta.url);
+    pluginVersion = String(require('../package.json').version || '');
+}
+catch { }
 /** DSH 设置命名空间 */
 export const REMOTE_MOBILE_SETTINGS_NAMESPACE = 'dsh-remote-mobile';
 /** Cordis 依赖注入声明：声明注入底座内置的 webServer 服务 */
@@ -79,10 +95,15 @@ function bindDshSettings(ctx, store) {
  * @param config - 插件持久化配置选项 (SessionStoreOptions)
  */
 export function apply(ctx, config = {}) {
-    // 1. 初始化会话与令牌持久化管理器
+    // 1. 初始化会话与令牌持久化管理器及内部握手密钥
     const store = new SessionStore(config);
     const styleStore = new StyleSnippetStore();
     const gateMiddleware = createGlobalAuthGate(store);
+    // 为本次插件生命周期生成高强度握手 Secret，并绑定到底座 Server
+    const gatewaySecret = generateGatewaySecret();
+    if (ctx.webServer?.server) {
+        setGatewaySecret(ctx.webServer.server, gatewaySecret);
+    }
     // 2. 接入 DSH Settings 服务 (命名空间: dsh-remote-mobile)
     bindDshSettings(ctx, store);
     // 3. 挂载底座 WebServer 相关的门禁拦截与路由注册
@@ -90,14 +111,12 @@ export function apply(ctx, config = {}) {
         if (ctx.webServer.server) {
             patchHttpServerWithVirtualizer(ctx.webServer.server, gateMiddleware, store, styleStore);
         }
-        // 挂载 HTML 模板层的 Crypto Polyfill 注入钩子
-        mountIndexInjections(ctx);
-        // 注册插件专属的 HTTP & SSE API 路由
+        // 挂载 HTML 模板层的样式与 Polyfill 注入钩子（在 Gzip 压缩前注入）
+        mountIndexInjections(ctx, styleStore);
+        // 注册插件专属的 HTTP & SSE API 路由。registerWebRoutes 会通过 ctx.effect
+        // 收集 DSH WebServer 返回的撤销函数，保证插件重新激活/热重载时不残留路由。
         if (typeof ctx.webServer.register === 'function') {
-            const routes = createRoutes(store, styleStore);
-            for (const route of routes) {
-                ctx.webServer.register(route);
-            }
+            registerWebRoutes(ctx, createRoutes(store, styleStore));
         }
     }
     // 4. 向 Cordis 容器桥接注册 remoteWebUiPairing 服务（延迟裁决：与其他远程接入
@@ -113,10 +132,18 @@ export function apply(ctx, config = {}) {
      * takeOverConnectionAuth 内部通过 __dsh_rm_auth_takeover__ 标记保证幂等，
      * 同一 connection 实例不会被重复接管。
      */
+    let connectionAuthAttached = false;
     const attachConnectionAuth = (conn) => {
-        if (conn) {
+        if (!conn)
+            return false;
+        try {
             takeOverConnectionAuth(conn, store);
+            connectionAuthAttached = Boolean(conn.__dsh_rm_auth_takeover__);
+        }
+        catch {
+            connectionAuthAttached = false;
         }
+        return connectionAuthAttached;
     };
     // 1) 优先通过 ctx.get 安全获取（未注入时不抛错返回 undefined）
     try {
@@ -146,7 +173,76 @@ export function apply(ctx, config = {}) {
             ctx.logger?.debug?.('[dsh-remote-mobile] 注册 connection 动态注入失败:', e);
         }
     }
-    // 6. 服务就绪时输出提示横幅与接入地址
+    // 动态同步受信任主机到所有底层运行时（webRuntime、connection、webStartup）
+    const syncTrustedHosts = (target) => {
+        try {
+            injectTrustedHosts(target || ctx, [store.getActivePort(), 3080, 3081], store.getOptions().trustedHosts);
+        }
+        catch { }
+    };
+    syncTrustedHosts();
+    if (typeof ctx.inject === 'function') {
+        try {
+            ctx.inject(['webRuntime'], (runtimeCtx) => {
+                syncTrustedHosts(runtimeCtx);
+            });
+        }
+        catch { }
+    }
+    // 6. 探测 DSH 底座网络暴露姿态：默认 proxy；核心已对外监听时回退 direct。
+    // 检测逻辑本身不抛错，异常时仍保留兜底，避免插件 apply 崩溃。
+    let modeFallbackError = '';
+    let detection;
+    try {
+        detection = detectServerMode(ctx, store.getOptions().mode, ctx.webServer?.port ?? 3080);
+    }
+    catch (err) {
+        modeFallbackError = err?.message || String(err);
+        ctx.logger?.error?.('[dsh-remote-mobile] 安全接入代理配置不可用，已回退 direct 模式:', err);
+        detection = detectServerMode(ctx, 'direct', ctx.webServer?.port ?? 3080);
+    }
+    // proxy 是默认模式，但核心已对外监听时会回退 direct：
+    // - 旧版 webserver 配置（0.0.0.0 / 具体网卡 IP）继续可用；
+    // - direct + 回环核心时，外部手机无法直连，仅适合同机反向代理。
+    bindDirectoryPickerRuntime(ctx, () => detection.isLoopback);
+    const requestedMode = store.getOptions().mode ?? 'proxy';
+    const legacyDirectFallback = requestedMode === 'proxy' && detection.mode === 'direct' && !detection.isLoopback;
+    const directLoopbackWarning = detection.mode === 'direct' && detection.isLoopback;
+    const modeWarning = legacyDirectFallback
+        ? `检测到底座监听 ${detection.rawCoreHost}，已自动使用 direct 模式；3080 直接对外，如需 proxy 请恢复 127.0.0.1 监听。`
+        : directLoopbackWarning
+            ? 'direct 模式 + 回环核心：外部手机无法直连，仅适合同机反向代理。'
+            : '';
+    let gatewayServer = null;
+    let gatewayReadyPromise = null;
+    if (detection.mode === 'proxy') {
+        const opts = store.getOptions();
+        gatewayServer = new GatewayServer({
+            port: opts.proxyPort ?? 3081,
+            host: opts.proxyHost ?? '0.0.0.0',
+            corePort: detection.corePort,
+            coreHost: detection.coreHost,
+        }, store, gateMiddleware, ctx.logger);
+        // 初始标记为正在启动中
+        store.setActiveGatewayInfo('proxy', opts.proxyPort ?? 3081, detection.corePort, false);
+        gatewayReadyPromise = gatewayServer.start().then(({ port }) => {
+            if (gatewayServer?.getServer()) {
+                setGatewaySecret(gatewayServer.getServer(), gatewaySecret);
+            }
+            store.setActiveGatewayInfo('proxy', port, detection.corePort, true);
+            syncTrustedHosts();
+            return port;
+        }).catch((err) => {
+            store.setActiveGatewayInfo('proxy', opts.proxyPort ?? 3081, detection.corePort, false, err?.message || String(err));
+            ctx.logger?.error?.('[dsh-remote-mobile] 安全接入代理启动失败:', err);
+            return opts.proxyPort ?? 3081;
+        });
+    }
+    else {
+        store.setActiveGatewayInfo('direct', detection.corePort, detection.corePort, true);
+        gatewayReadyPromise = Promise.resolve(detection.corePort);
+    }
+    // 7. 服务就绪时输出提示横幅与接入地址
     let printed = false;
     let disposed = false;
     let timer1 = null;
@@ -158,18 +254,42 @@ export function apply(ctx, config = {}) {
                 clearTimeout(timer1);
             if (timer2)
                 clearTimeout(timer2);
+            if (gatewayServer) {
+                clearGatewaySecret(gatewayServer.getServer());
+                gatewayServer.close().catch(() => { });
+            }
+            const webServer = (typeof ctx.get === 'function' ? ctx.get('webServer') : undefined) || ctx.webServer;
+            if (webServer?.server) {
+                clearGatewaySecret(webServer.server);
+            }
         });
     }
     catch { }
-    const printReadyBanner = () => {
+    const printReadyBanner = async () => {
         // 生命周期守卫：若上下文已废弃/进入 dispose，放弃回调
         if (disposed || printed)
             return;
         printed = true;
+        // 等待安全接入代理就绪以获得准确的对外端口（避免端口自增探测竞态）
+        try {
+            if (gatewayReadyPromise) {
+                await Promise.race([
+                    gatewayReadyPromise,
+                    new Promise((r) => setTimeout(r, 2000)),
+                ]);
+            }
+        }
+        catch { }
+        // 等待期间插件可能已被 dispose / 热重载；此时绝不能再 setGatewaySecret / patch / mount
+        if (disposed)
+            return;
         try {
+            syncTrustedHosts();
             const webServer = (typeof ctx.get === 'function' ? ctx.get('webServer') : undefined) || ctx.webServer;
             if (webServer?.server) {
+                setGatewaySecret(webServer.server, gatewaySecret);
                 patchHttpServerWithVirtualizer(webServer.server, gateMiddleware, store, styleStore);
+                mountIndexInjections(ctx, styleStore);
             }
             try {
                 const conn = typeof ctx.get === 'function' ? ctx.get('connection') : undefined;
@@ -181,28 +301,84 @@ export function apply(ctx, config = {}) {
             }
             const tsIp = getLocalTailscaleIp();
             const lanIp = getLocalLanIp();
-            const port = webServer?.port ?? 3080;
+            const activePort = store.getActivePort();
+            const activeMode = store.getActiveMode();
+            const corePort = store.getCorePort();
+            const coreHost = detection.coreHost;
             const opts = store.getOptions();
+            const proxyHost = opts.proxyHost ?? '0.0.0.0';
+            const proxyStatus = store.getGatewayStatus();
+            const versionLabel = pluginVersion ? `v${pluginVersion}` : 'unknown';
+            const coreLabel = detection.isLoopback ? '回环' : '对外监听';
+            const modeLabel = activeMode === 'proxy'
+                ? 'proxy（默认）'
+                : legacyDirectFallback
+                    ? 'direct（旧配置回退）'
+                    : 'direct（显式配置）';
             const divider = '─'.repeat(72);
             console.log(`\n┌${divider}`);
-            console.log(`│ [dsh-remote-mobile] 官方临时 Token 鉴权已接管，PC/移动端访问无需携带官方token`);
-            console.log(`│ 远程安全网关已就绪，支持手机浏览器访问:`);
-            console.log(`│   • 本机回环:   http://127.0.0.1:${port}`);
-            if (lanIp && lanIp !== '127.0.0.1') {
-                console.log(`│   • 局域网:     http://${lanIp}:${port} (同 Wi-Fi 局域网直连)`);
+            console.log(connectionAuthAttached
+                ? `│ [dsh-remote-mobile] ${versionLabel} 官方临时 Token 鉴权已接管，PC/移动端访问无需携带官方token`
+                : `│ [dsh-remote-mobile] ${versionLabel} ⚠️ 官方临时 Token 鉴权接管未完成，请检查 DSH 版本或启动日志`);
+            console.log(`│ DSH 核心: ${detection.rawCoreHost}:${corePort} (${coreLabel})`);
+            console.log(`│ 运行模式: ${modeLabel}`);
+            if (modeFallbackError) {
+                console.log(`│ ⚠️ 安全接入代理配置不可用，已回退 direct 模式: ${modeFallbackError}`);
             }
-            if (tsIp) {
-                console.log(`│   • 虚拟私网:   http://${tsIp}:${port} (Tailscale 私网异地直连)`);
+            if (modeWarning) {
+                console.log(`│ ⚠️ ${modeWarning}`);
+            }
+            if (activeMode === 'proxy') {
+                if (proxyStatus.running) {
+                    console.log(`│ 安全接入代理已激活 (${proxyHost}:${activePort} -> ${coreHost}:${corePort})`);
+                    console.log(`│ 手机/远程设备请访问安全接入代理地址:`);
+                    if (lanIp && lanIp !== '127.0.0.1') {
+                        console.log(`│   • 局域网:     http://${lanIp}:${activePort} (同 Wi-Fi 局域网直连)`);
+                    }
+                    if (tsIp) {
+                        console.log(`│   • 虚拟私网:   http://${tsIp}:${activePort} (Tailscale 私网异地直连)`);
+                    }
+                    console.log(`│ 电脑本机浏览器访问控制台:`);
+                    console.log(`│   • 核心直连:   http://127.0.0.1:${corePort}`);
+                    if (proxyHost === '0.0.0.0' || proxyHost === '::' || proxyHost === '127.0.0.1' || proxyHost === 'localhost') {
+                        const localProxyHost = proxyHost === '::' ? '[::1]' : '127.0.0.1';
+                        console.log(`│   • 代理入口:   http://${localProxyHost}:${activePort}`);
+                        console.log(`│     本机直连不校验配对码/长期密码`);
+                    }
+                }
+                else {
+                    console.log(`│ ⚠️ 安全接入代理未成功启动: ${proxyStatus.error || '端口占用'}`);
+                    console.log(`│ 外部手机设备当前暂时无法连接，请检查 ${opts.proxyPort ?? 3081} 端口占用`);
+                    console.log(`│ 电脑本机浏览器仍可直接访问:`);
+                    console.log(`│   • 本机回环:   http://127.0.0.1:${corePort}`);
+                }
+            }
+            else {
+                console.log(`│ 直连模式已启用（无独立安全接入代理），支持手机浏览器访问:`);
+                console.log(`│   • 本机回环:   http://127.0.0.1:${corePort}`);
+                if (lanIp && lanIp !== '127.0.0.1') {
+                    console.log(`│   • 局域网:     http://${lanIp}:${corePort} (同 Wi-Fi 局域网直连)`);
+                }
+                if (tsIp) {
+                    console.log(`│   • 虚拟私网:   http://${tsIp}:${corePort} (Tailscale 私网异地直连)`);
+                }
+            }
+            const dirPickerStatus = getDirectoryPickerStatus();
+            if (dirPickerStatus.needsWarning) {
+                console.log(`│ ⚠️ 移动端选目录提示: 当前未开启网页内目录选择器，手机点「选择文件夹」会在电脑弹窗`);
+                console.log(`│   可在 Web「设置」->「远程与移动端」顶部一键开启网页目录选择器`);
             }
             console.log(`│ 访问与配置说明:`);
             console.log(`│   - 手机/远程设备打开对应地址即可直接访问`);
             console.log(`│   - 在本机打开 Web 界面 ->「设置」->「远程与移动端」进行安全管理:`);
             console.log(`│     可开启免密直连(局域网/Tailscale)、查看 6 位临时配对码或设置长期密码`);
+            console.log(`│   - 高级接入参数: settings.json 中的 mode / proxyPort / proxyHost / trustedHosts`);
+            console.log(`│     修改后需要重启 DSH`);
             console.log(`│   - 项目文档:   https://github.com/IceApriler/dsh-remote-mobile`);
             console.log(`└${divider}\n`);
-            ctx.logger?.info?.(`[dsh-remote-mobile] 移动端远程控制与安全门禁已激活 (上下文虚拟化桥接就绪，样式片段: ${styleStore.list().length} 个)`);
+            ctx.logger?.info?.(`[dsh-remote-mobile] 移动端远程控制与安全门禁已激活 (运行模式: ${activeMode}, 对外端口: ${activePort})`);
             if (tsIp) {
-                ctx.logger?.info?.(`[dsh-remote-mobile] Tailscale 地址: http://${tsIp}:${port} (免密直连: ${opts.allowTailscale ? '已开启' : '已关闭'})`);
+                ctx.logger?.info?.(`[dsh-remote-mobile] Tailscale 地址: http://${tsIp}:${activePort} (免密直连: ${opts.allowTailscale ? '已开启' : '已关闭'})`);
             }
         }
         catch (e) {
@@ -233,4 +409,7 @@ export * from './auth/token.js';
 export * from './auth/gate.js';
 export * from './routes/api.js';
 export * from './bridge/compat.js';
+export * from './bridge/directory-picker.js';
 export * from './styles/style-snippets.js';
+export * from './gateway/detector.js';
+export * from './gateway/server.js';

package/lib/routes/api.d.ts

@@ -1,16 +1,19 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type SessionStore } from '../auth/token.js';
 import { type StyleSnippetStore } from '../styles/style-snippets.js';
-export declare function createRoutes(store: SessionStore, styleStore?: StyleSnippetStore): ({
-    method: string;
+/**
+ * DSH 0.2.1+ WebServer 的路由契约：`kind` 决定注册到 exact 还是 prefixes 表。
+ * 当前所有接口都是字面路径，因此统一使用 exact；`method` 保留给旧宿主兼容。
+ */
+export interface WebRoute {
+    kind: 'exact' | 'prefix';
+    /** 旧版 DSH 使用；DSH 0.2.1+ 的 WebServer 不按 method 分派。 */
+    method?: 'GET' | 'POST';
     path: string;
-    handler: (_req: IncomingMessage, res: ServerResponse) => Promise<void>;
-} | {
-    method: string;
-    path: string;
-    handler: (req: IncomingMessage, res: ServerResponse) => Promise<ServerResponse<IncomingMessage> | undefined>;
-} | {
-    method?: undefined;
-    path: string;
-    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-})[];
+    handler: (req: IncomingMessage, res: ServerResponse) => unknown;
+}
+export interface CreateRoutesOptions {
+    /** 测试环境注入的自定义 cordis.patch.yml 路径（避免污染宿主配置） */
+    patchFilePath?: string;
+}
+export declare function createRoutes(store: SessionStore, styleStore?: StyleSnippetStore, routeOptions?: CreateRoutesOptions): WebRoute[];

package/lib/routes/api.js

@@ -1,9 +1,11 @@
+import { isIP } from 'node:net';
 import { AUTH_COOKIE_NAME, readGlobalLocale } from '../auth/token.js';
 import { getLocalTailscaleIp, getLocalLanIp, getAllNetworkIps, getClientIp, isTailscaleIp, isLanIp } from '../auth/tailscale.js';
 import { getPublicKeyPem, decryptWithPrivateKey, validateSecretStrength, RSA_KEY_FILE } from '../auth/crypto.js';
 import { getLoginPageHtml } from './login-page.js';
 import { DEFAULT_STYLE_FILE } from '../styles/style-snippets.js';
 import { getPairingBridgeState } from '../bridge/compat.js';
+import { getDirectoryPickerStatus, enableDirectoryPickerBrowse, disableDirectoryPickerBrowse, } from '../bridge/directory-picker.js';
 import { resolveRedirectPath } from '../auth/prefix.js';
 function jsonResponse(res, status, data) {
     res.writeHead(status, {
@@ -37,10 +39,11 @@ function parseJsonBody(req) {
         req.on('error', () => resolve({}));
     });
 }
-export function createRoutes(store, styleStore) {
+export function createRoutes(store, styleStore, routeOptions) {
     return [
         // 0. RSA 公钥获取接口 (RSA-OAEP-SHA256)
         {
+            kind: 'exact',
             method: 'GET',
             path: '/api/remote-mobile/public-key',
             handler: async (_req, res) => {
@@ -53,6 +56,7 @@ export function createRoutes(store, styleStore) {
         },
         // 1. 状态查询接口 (返回 Tailscale IP、局域网 LAN IP 与 IP 防暴破安全统计)
         {
+            kind: 'exact',
             method: 'GET',
             path: '/api/remote-mobile/status',
             handler: async (_req, res) => {
@@ -86,11 +90,23 @@ export function createRoutes(store, styleStore) {
                     pairingBridgeMode: bridgeState.mode,
                     pairingBridgeConflict: bridgeState.conflictWith || '',
                     pairingBridgeConflictId: bridgeState.conflictEntryId || '',
+                    // 目录选择器（移动端添加工作区/选择文件夹）状态与补丁信息
+                    directoryPicker: getDirectoryPickerStatus(routeOptions?.patchFilePath),
+                    // 安全接入代理运行状态
+                    proxy: {
+                        ...store.getGatewayStatus(),
+                        activePort: store.getActivePort(),
+                        configuredMode: opts.mode,
+                        proxyPort: opts.proxyPort || 3081,
+                        proxyHost: opts.proxyHost || '0.0.0.0',
+                        trustedHosts: opts.trustedHosts,
+                    },
                 });
             },
         },
         // 2. 生成 6 位短期配对码
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/generate-code',
             handler: async (_req, res) => {
@@ -104,6 +120,7 @@ export function createRoutes(store, styleStore) {
         },
         // 3. 手机端验证与换取长效 Cookie (支持 RSA-OAEP 密文解密 + 防暴力破解 429 拦截)
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/verify',
             handler: async (req, res) => {
@@ -143,6 +160,7 @@ export function createRoutes(store, styleStore) {
         },
         // 3.1 手动解除某个 IP 的防暴破锁定
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/unlock-ip',
             handler: async (req, res) => {
@@ -154,6 +172,7 @@ export function createRoutes(store, styleStore) {
         },
         // 3.2 一键清空所有 IP 访问与安全审计日志
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/clear-ip-stats',
             handler: async (_req, res) => {
@@ -163,6 +182,7 @@ export function createRoutes(store, styleStore) {
         },
         // 4. 切换 Tailscale / 局域网免密直连开关
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/toggle-bypass',
             handler: async (req, res) => {
@@ -187,11 +207,46 @@ export function createRoutes(store, styleStore) {
             },
         },
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/update-options',
             handler: async (req, res) => {
                 const body = await parseJsonBody(req);
                 const updates = {};
+                if (body.mode !== undefined) {
+                    if (body.mode !== 'proxy' && body.mode !== 'direct') {
+                        return jsonResponse(res, 400, { success: false, reason: 'mode 必须为 proxy 或 direct' });
+                    }
+                    updates.mode = body.mode;
+                }
+                if (body.proxyPort !== undefined) {
+                    const port = Number(body.proxyPort);
+                    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                        return jsonResponse(res, 400, { success: false, reason: 'proxyPort 必须是 1-65535 的整数' });
+                    }
+                    updates.proxyPort = port;
+                }
+                if (body.proxyHost !== undefined) {
+                    const host = String(body.proxyHost || '').trim();
+                    const bareHost = host.replace(/^\[/, '').replace(/\]$/, '');
+                    if (!host || host.length > 255 || (bareHost !== 'localhost' && isIP(bareHost) === 0)) {
+                        return jsonResponse(res, 400, { success: false, reason: 'proxyHost 必须是有效 IP 地址或 localhost' });
+                    }
+                    updates.proxyHost = host;
+                }
+                if (body.trustedHosts !== undefined) {
+                    if (!Array.isArray(body.trustedHosts)) {
+                        return jsonResponse(res, 400, { success: false, reason: 'trustedHosts 必须是字符串数组' });
+                    }
+                    const hosts = body.trustedHosts
+                        .filter((h) => typeof h === 'string')
+                        .map((h) => h.trim())
+                        .filter(Boolean);
+                    if (hosts.some((h) => h.length > 255 || /[\s]/.test(h))) {
+                        return jsonResponse(res, 400, { success: false, reason: 'trustedHosts 中包含无效域名' });
+                    }
+                    updates.trustedHosts = Array.from(new Set(hosts));
+                }
                 if (typeof body.allowTailscale === 'boolean') {
                     updates.allowTailscale = body.allowTailscale;
                 }
@@ -210,6 +265,10 @@ export function createRoutes(store, styleStore) {
                 if (typeof body.lockDurationMs === 'number' && body.lockDurationMs > 0) {
                     updates.lockDurationMs = Math.floor(body.lockDurationMs);
                 }
+                const restartRequired = updates.mode !== undefined ||
+                    updates.proxyPort !== undefined ||
+                    updates.proxyHost !== undefined ||
+                    updates.trustedHosts !== undefined;
                 store.updateOptions(updates);
                 const opts = store.getOptions();
                 jsonResponse(res, 200, {
@@ -219,11 +278,19 @@ export function createRoutes(store, styleStore) {
                     maxVisitsPerMinute: opts.maxVisitsPerMinute,
                     maxFailedAttempts: opts.maxFailedAttempts,
                     lockDurationMs: opts.lockDurationMs,
+                    mode: opts.mode,
+                    proxyPort: opts.proxyPort,
+                    proxyHost: opts.proxyHost,
+                    trustedHosts: opts.trustedHosts,
+                    activeMode: store.getActiveMode(),
+                    activePort: store.getActivePort(),
+                    restartRequired,
                 });
             },
         },
         // 5. 设置并持久化长期访问密码 (支持 RSA 密文 + 6位以上字母数字复杂度校验)
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/set-secret',
             handler: async (req, res) => {
@@ -249,6 +316,7 @@ export function createRoutes(store, styleStore) {
         },
         // 5.1 清除长期访问密码
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/clear-secret',
             handler: async (_req, res) => {
@@ -258,6 +326,7 @@ export function createRoutes(store, styleStore) {
         },
         // 6. 撤销单个设备授权
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/revoke-device',
             handler: async (req, res) => {
@@ -269,6 +338,7 @@ export function createRoutes(store, styleStore) {
         },
         // 7. 一键撤销所有设备
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/revoke-all',
             handler: async (_req, res) => {
@@ -278,6 +348,7 @@ export function createRoutes(store, styleStore) {
         },
         // 8. 独立手机登录引导页面（已授权或 Tailscale/局域网免密设备访问时自动 302 跳转回工作区，支持 IP 访问计数与限频）
         {
+            kind: 'exact',
             method: 'GET',
             path: '/auth',
             handler: async (req, res) => {
@@ -298,16 +369,16 @@ export function createRoutes(store, styleStore) {
                 const visitCheck = store.recordAuthVisit(clientIp, ua);
                 if (!visitCheck.allowed) {
                     res.writeHead(429, { 'Content-Type': 'text/html; charset=utf-8' });
-                    return res.end(`
-            <!DOCTYPE html>
-            <html>
-            <head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>安全限制 - DSH</title>
-            <style>body{background:#0f172a;color:#fff;font-family:-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;padding:20px;box-sizing:border-box;text-align:center;}
-            .card{background:rgba(255,255,255,0.06);border:1px solid rgba(239,68,68,0.4);border-radius:16px;padding:28px 20px;max-width:380px;box-shadow:0 8px 32px rgba(0,0,0,0.4);}
-            h2{color:#ef4444;margin:0 0 10px 0;font-size:20px;}p{color:#94a3b8;font-size:14px;line-height:1.6;margin:0;}</style>
-            </head>
-            <body><div class="card"><h2>⚠️ 访问限制 (429)</h2><p>${visitCheck.reason || '当前 IP 请求过于频繁或已被临时锁定，请稍后刷新重试。'}</p></div></body>
-            </html>
+                    return res.end(`
+            <!DOCTYPE html>
+            <html>
+            <head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>安全限制 - DSH</title>
+            <style>body{background:#0f172a;color:#fff;font-family:-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;padding:20px;box-sizing:border-box;text-align:center;}
+            .card{background:rgba(255,255,255,0.06);border:1px solid rgba(239,68,68,0.4);border-radius:16px;padding:28px 20px;max-width:380px;box-shadow:0 8px 32px rgba(0,0,0,0.4);}
+            h2{color:#ef4444;margin:0 0 10px 0;font-size:20px;}p{color:#94a3b8;font-size:14px;line-height:1.6;margin:0;}</style>
+            </head>
+            <body><div class="card"><h2>⚠️ 访问限制 (429)</h2><p>${visitCheck.reason || '当前 IP 请求过于频繁或已被临时锁定，请稍后刷新重试。'}</p></div></body>
+            </html>
           `);
                 }
                 const acceptLang = req.headers['accept-language'] || '';
@@ -322,6 +393,7 @@ export function createRoutes(store, styleStore) {
         },
         // 9. SSE 实时事件监听通道 (Server-Sent Events 0延时推送，彻底告别轮询)
         {
+            kind: 'exact',
             method: 'GET',
             path: '/api/remote-mobile/events',
             handler: async (req, res) => {
@@ -379,6 +451,7 @@ export function createRoutes(store, styleStore) {
         },
         // 10. 移动端样式片段（样式小插件）管理 API（合并 GET 与 POST 处理，避免 webserver.register 重复 path 冲突）
         {
+            kind: 'exact',
             path: '/api/remote-mobile/styles',
             handler: async (req, res) => {
                 if (!styleStore) {
@@ -416,6 +489,7 @@ export function createRoutes(store, styleStore) {
             },
         },
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/styles/toggle',
             handler: async (req, res) => {
@@ -429,6 +503,7 @@ export function createRoutes(store, styleStore) {
             },
         },
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/styles/delete',
             handler: async (req, res) => {
@@ -441,6 +516,7 @@ export function createRoutes(store, styleStore) {
             },
         },
         {
+            kind: 'exact',
             method: 'POST',
             path: '/api/remote-mobile/styles/reset',
             handler: async (_req, res) => {
@@ -451,5 +527,44 @@ export function createRoutes(store, styleStore) {
                 jsonResponse(res, 200, { success: true, snippets: styleStore.list() });
             },
         },
+        // 11. 移动端网页目录选择器（browse 模式）一键开启与还原（严格幂等去重写入 cordis.patch.yml）
+        {
+            kind: 'exact',
+            method: 'POST',
+            path: '/api/remote-mobile/directory-picker',
+            handler: async (req, res) => {
+                const body = await parseJsonBody(req);
+                if (typeof body.enabled !== 'boolean') {
+                    return jsonResponse(res, 400, {
+                        success: false,
+                        reason: 'enabled 必须为布尔值 (true 开启网页目录选择器 / false 恢复原生目录选择器)',
+                    });
+                }
+                try {
+                    const result = body.enabled
+                        ? enableDirectoryPickerBrowse(routeOptions?.patchFilePath)
+                        : disableDirectoryPickerBrowse(routeOptions?.patchFilePath);
+                    return jsonResponse(res, 200, {
+                        success: true,
+                        changed: result.changed,
+                        directoryPicker: {
+                            patchEnabled: result.patchEnabled,
+                            patchPartial: result.patchPartial,
+                            runtimeActive: result.runtimeActive,
+                            restartRequired: result.restartRequired,
+                            needsWarning: result.needsWarning,
+                            patchFilePath: result.patchFilePath,
+                            yamlSnippet: result.yamlSnippet,
+                        },
+                    });
+                }
+                catch (err) {
+                    return jsonResponse(res, 500, {
+                        success: false,
+                        reason: err?.message || '写入 cordis.patch.yml 失败',
+                    });
+                }
+            },
+        },
     ];
 }