@yezack/dsh-remote-mobile 1.10.0 → 1.10.2

package/lib/gateway/detector.d.ts

@@ -2,19 +2,17 @@
  * DSH 底座运行模式探测器
  *
  * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
- * 1. 若宿主仅监听本地回环地址 (127.0.0.1 / localhost)，则外部网络无法直连，
- *    自适应判定为网关模式 ('gateway')，由插件启动独立安全反代网关 (0.0.0.0:3081)；
+ * 1. 默认使用代理模式 ('proxy')：宿主仅监听本地回环地址 (127.0.0.1 / localhost)，
+ *    由插件启动独立安全接入代理 (0.0.0.0:3081)；
  * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
- *    判定为直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
- * 3. 支持用户通过 options.mode ('auto' | 'gateway' | 'direct') 强制覆盖。
+ *    自动回退直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 用户可通过 options.mode ('proxy' | 'direct') 显式选择；不再提供 auto 模式。
  */
-export type GatewayMode = 'gateway' | 'direct';
+export type ProxyMode = 'proxy' | 'direct';
 export interface ServerModeDetectionResult {
     /** 最终生效的运行模式 */
-    mode: GatewayMode;
-    /** 是否为自动探测得出 */
-    isAuto: boolean;
-    /** 底座核心监听的 host（未配置时默认 127.0.0.1，在 gateway 模式下已安全规范化为回环 target） */
+    mode: ProxyMode;
+    /** 底座核心监听的 host（未配置时默认 127.0.0.1，在 proxy 模式下已安全规范化为回环 target） */
     coreHost: string;
     /** 底座核心监听的端口（默认 3080） */
     corePort: number;
@@ -28,7 +26,7 @@ export interface ServerModeDetectionResult {
  */
 export declare function isLoopbackHost(host?: string | null): boolean;
 /**
- * 规范化网关内部转发的目标核心 Host（仅在 gateway 模式下作为 proxy target 使用）
+ * 规范化安全接入代理内部转发的目标核心 Host（仅在 proxy 模式下作为 proxy target 使用）
  * 将通配或 localhost 规范化为明确的回环 IP，消除 Node 18+ 的 Happy Eyeballs IPv6 优先解析 502 隐患
  */
 export declare function normalizeGatewayTargetHost(host: string): string;
@@ -36,7 +34,7 @@ export declare function normalizeGatewayTargetHost(host: string): string;
  * 探测底座运行姿态并裁决插件的工作模式
  *
  * @param ctx Cordis 上下文（含 webServer / webStartup 等服务）
- * @param configuredMode 用户显式配置的运行模式 ('auto' | 'gateway' | 'direct')
+ * @param configuredMode 用户显式配置的运行模式 ('proxy' | 'direct')
  * @param defaultCorePort 底座默认核心端口（3080）
  */
-export declare function detectServerMode(ctx: any, configuredMode?: 'auto' | 'gateway' | 'direct', defaultCorePort?: number): ServerModeDetectionResult;
+export declare function detectServerMode(ctx: any, configuredMode?: 'proxy' | 'direct', defaultCorePort?: number): ServerModeDetectionResult;

package/lib/gateway/detector.js

@@ -2,11 +2,11 @@
  * DSH 底座运行模式探测器
  *
  * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
- * 1. 若宿主仅监听本地回环地址 (127.0.0.1 / localhost)，则外部网络无法直连，
- *    自适应判定为网关模式 ('gateway')，由插件启动独立安全反代网关 (0.0.0.0:3081)；
+ * 1. 默认使用代理模式 ('proxy')：宿主仅监听本地回环地址 (127.0.0.1 / localhost)，
+ *    由插件启动独立安全接入代理 (0.0.0.0:3081)；
  * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
- *    判定为直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
- * 3. 支持用户通过 options.mode ('auto' | 'gateway' | 'direct') 强制覆盖。
+ *    自动回退直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 用户可通过 options.mode ('proxy' | 'direct') 显式选择；不再提供 auto 模式。
  */
 /**
  * 判断指定 host 是否属于本地回环地址（支持 localhost, 127.*, ::1, 0:0:0:0:0:0:0:1 等完整形态）
@@ -29,7 +29,7 @@ export function isLoopbackHost(host) {
     return false;
 }
 /**
- * 规范化网关内部转发的目标核心 Host（仅在 gateway 模式下作为 proxy target 使用）
+ * 规范化安全接入代理内部转发的目标核心 Host（仅在 proxy 模式下作为 proxy target 使用）
  * 将通配或 localhost 规范化为明确的回环 IP，消除 Node 18+ 的 Happy Eyeballs IPv6 优先解析 502 隐患
  */
 export function normalizeGatewayTargetHost(host) {
@@ -48,10 +48,10 @@ export function normalizeGatewayTargetHost(host) {
  * 探测底座运行姿态并裁决插件的工作模式
  *
  * @param ctx Cordis 上下文（含 webServer / webStartup 等服务）
- * @param configuredMode 用户显式配置的运行模式 ('auto' | 'gateway' | 'direct')
+ * @param configuredMode 用户显式配置的运行模式 ('proxy' | 'direct')
  * @param defaultCorePort 底座默认核心端口（3080）
  */
-export function detectServerMode(ctx, configuredMode = 'auto', defaultCorePort = 3080) {
+export function detectServerMode(ctx, configuredMode = 'proxy', defaultCorePort = 3080) {
     const webServer = (typeof ctx?.get === 'function' ? ctx.get('webServer') : undefined) || ctx?.webServer;
     const webStartup = (typeof ctx?.get === 'function' ? ctx.get('webStartup') : undefined) || ctx?.webStartup;
     // 提取宿主底座的 host 与 port 配置（保持原始字面量用于模式判定）
@@ -60,26 +60,13 @@ export function detectServerMode(ctx, configuredMode = 'auto', defaultCorePort =
     const rawCoreHost = String(coreHostRaw || '127.0.0.1').trim();
     const corePort = Number(corePortRaw) || defaultCorePort;
     const isLoopback = isLoopbackHost(rawCoreHost);
-    let finalMode = 'direct';
-    const isAuto = configuredMode === 'auto';
-    if (configuredMode === 'gateway') {
-        if (!isLoopback && rawCoreHost !== '0.0.0.0' && rawCoreHost !== '::') {
-            throw new Error(`[dsh-remote-mobile] 无法在具体外部 IP ("${rawCoreHost}") 上启用网关模式 (mode: 'gateway')。网关模式要求底座监听在本地回环 (127.0.0.1)；若需直接对外开放请使用 direct 模式。`);
-        }
-        finalMode = 'gateway';
-    }
-    else if (configuredMode === 'direct') {
-        finalMode = 'direct';
-    }
-    else {
-        // auto 自适应模式：底座为回环则启用网关，底座已对外开放（0.0.0.0 / 具体外部IP）则直连
-        finalMode = isLoopback ? 'gateway' : 'direct';
-    }
-    // 仅对最终生效的 gateway 模式的目标核心地址执行 proxyTarget 规范化
-    const coreHost = finalMode === 'gateway' ? normalizeGatewayTargetHost(rawCoreHost) : rawCoreHost;
+    // proxy 是默认模式，但只在核心回环时成立；核心已对外监听时回退 direct，
+    // 以兼容旧版 webserver 配置或用户显式绑定的具体网卡 IP。
+    const finalMode = configuredMode === 'direct' || !isLoopback ? 'direct' : 'proxy';
+    // 仅对最终生效的 proxy 模式的目标核心地址执行 proxyTarget 规范化
+    const coreHost = finalMode === 'proxy' ? normalizeGatewayTargetHost(rawCoreHost) : rawCoreHost;
     return {
         mode: finalMode,
-        isAuto,
         coreHost,
         corePort,
         isLoopback,

package/lib/gateway/server.d.ts

@@ -1,19 +1,19 @@
 /**
- * DSH 移动端远程独立安全网关服务 (GatewayServer)
+ * DSH 移动端远程独立安全接入代理服务 (GatewayServer)
  *
  * 架构定位：
  * 解决 DSH 0.2.1+ 底层强行禁止 0.0.0.0 监听的问题。
  * DSH 官方 WebServer 继续保持纯粹、安全的 127.0.0.1:3080 本地回环监听（零外部暴露风险）；
- * 由本服务在 0.0.0.0:3081 启动专用安全反代网关，接纳局域网与 Tailscale 流量，
+ * 由本服务在 0.0.0.0:3081 启动专用安全接入代理，接纳局域网与 Tailscale 流量，
  * 执行端到端 RSA 加密、扫码配对、慢哈希密码认证与防暴力破解 IP 熔断，
  * 并将合法的流量全双工代理至底座核心服务，彻底解决换 Wi-Fi 崩溃、无法兼顾多网卡与本机回环失效的痛点。
  */
 import http, { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { SessionStore } from '../auth/token.js';
 export interface GatewayServerOptions {
-    /** 网关监听端口，默认 3081 */
+    /** 安全接入代理监听端口，默认 3081 */
     port?: number;
-    /** 网关监听网络地址，默认 0.0.0.0 */
+    /** 安全接入代理监听网络地址，默认 0.0.0.0 */
     host?: string;
     /** DSH 宿主核心服务端口，默认 3080 */
     corePort: number;
@@ -42,13 +42,13 @@ export declare class GatewayServer {
     private lastError;
     private logger?;
     constructor(options: GatewayServerOptions, store: SessionStore, gateMiddleware: (req: IncomingMessage, res: ServerResponse, next?: () => void) => boolean, logger?: any);
-    /** 获取网关当前运行状态契约 */
+    /** 获取安全接入代理当前运行状态契约 */
     getStatus(): GatewayServerStatus;
     /** 获取网关最近发生的异常信息 */
     getLastError(): string | null;
-    /** 获取网关实际生效绑定的端口 */
+    /** 获取安全接入代理实际生效绑定的端口 */
     getBoundPort(): number;
-    /** 获取网关监听的 host */
+    /** 获取安全接入代理监听的 host */
     getHost(): string;
     /** 获取内部转发的目标核心端口 */
     getCorePort(): number;
@@ -73,14 +73,14 @@ export declare class GatewayServer {
     /** 请求是否携带反向代理透传头 */
     private hasForwardedHeaders;
     /**
-     * 启动网关服务（带端口冲突自愈探测与状态机落定）
+     * 启动安全接入代理服务（带端口冲突自愈探测与状态机落定）
      */
     start(): Promise<{
         port: number;
         host: string;
     }>;
     /**
-     * 优雅关闭网关服务，立即释放端口与所有客户端 Socket
+     * 优雅关闭安全接入代理，立即释放端口与所有客户端 Socket
      */
     close(): Promise<void>;
     /**

package/lib/gateway/server.js

@@ -1,10 +1,10 @@
 /**
- * DSH 移动端远程独立安全网关服务 (GatewayServer)
+ * DSH 移动端远程独立安全接入代理服务 (GatewayServer)
  *
  * 架构定位：
  * 解决 DSH 0.2.1+ 底层强行禁止 0.0.0.0 监听的问题。
  * DSH 官方 WebServer 继续保持纯粹、安全的 127.0.0.1:3080 本地回环监听（零外部暴露风险）；
- * 由本服务在 0.0.0.0:3081 启动专用安全反代网关，接纳局域网与 Tailscale 流量，
+ * 由本服务在 0.0.0.0:3081 启动专用安全接入代理，接纳局域网与 Tailscale 流量，
  * 执行端到端 RSA 加密、扫码配对、慢哈希密码认证与防暴力破解 IP 熔断，
  * 并将合法的流量全双工代理至底座核心服务，彻底解决换 Wi-Fi 崩溃、无法兼顾多网卡与本机回环失效的痛点。
  */
@@ -46,7 +46,7 @@ export class GatewayServer {
         this.gateMiddleware = gateMiddleware;
         this.logger = logger;
     }
-    /** 获取网关当前运行状态契约 */
+    /** 获取安全接入代理当前运行状态契约 */
     getStatus() {
         return this.status;
     }
@@ -54,11 +54,11 @@ export class GatewayServer {
     getLastError() {
         return this.lastError;
     }
-    /** 获取网关实际生效绑定的端口 */
+    /** 获取安全接入代理实际生效绑定的端口 */
     getBoundPort() {
         return this.boundPort;
     }
-    /** 获取网关监听的 host */
+    /** 获取安全接入代理监听的 host */
     getHost() {
         return this.host;
     }
@@ -113,7 +113,7 @@ export class GatewayServer {
             req.headers['x-real-ip']);
     }
     /**
-     * 启动网关服务（带端口冲突自愈探测与状态机落定）
+     * 启动安全接入代理服务（带端口冲突自愈探测与状态机落定）
      */
     async start() {
         if (this.server && this.status === 'running') {
@@ -149,7 +149,7 @@ export class GatewayServer {
                 const addr = server.address();
                 this.boundPort = addr && typeof addr === 'object' ? addr.port : currentPort;
                 this.status = 'running';
-                this.logger?.info?.(`[dsh-remote-mobile] 独立安全反向代理网关已就绪: http://${this.host}:${this.boundPort} -> 127.0.0.1:${this.corePort}`);
+                this.logger?.info?.(`[dsh-remote-mobile] 安全接入代理已就绪: http://${this.host}:${this.boundPort} -> ${this.coreHost}:${this.corePort}`);
                 return { port: this.boundPort, host: this.host };
             }
             catch (err) {
@@ -166,10 +166,10 @@ export class GatewayServer {
         }
         this.status = 'error';
         this.lastError = `尝试端口均被占用 (${this.configuredPort} ~ ${currentPort})`;
-        throw new Error(`[dsh-remote-mobile] 启动安全网关失败：${this.lastError}`);
+        throw new Error(`[dsh-remote-mobile] 启动安全接入代理失败：${this.lastError}`);
     }
     /**
-     * 优雅关闭网关服务，立即释放端口与所有客户端 Socket
+     * 优雅关闭安全接入代理，立即释放端口与所有客户端 Socket
      */
     async close() {
         if (!this.server) {
@@ -215,7 +215,7 @@ export class GatewayServer {
             return;
         }
         // 网关已完成 Host 白名单校验，通知共享门禁跳过重复 Host 校验
-        // （gatewayHost 可能是自定义域名，不属于核心的 trustedHosts / 网卡 IP）
+        // （proxyHost 可能是自定义域名，不属于核心的 trustedHosts / 网卡 IP）
         ;
         req.__dsh_rm_host_allowed__ = true;
         // 2. 门禁中间件校验与原因标记获取

package/lib/index.d.ts

@@ -31,6 +31,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/index.js

@@ -12,17 +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, 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 服务 */
@@ -100,12 +113,10 @@ export function apply(ctx, config = {}) {
         }
         // 挂载 HTML 模板层的样式与 Polyfill 注入钩子（在 Gzip 压缩前注入）
         mountIndexInjections(ctx, styleStore);
-        // 注册插件专属的 HTTP & SSE API 路由
+        // 注册插件专属的 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 服务（延迟裁决：与其他远程接入
@@ -121,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 {
@@ -170,9 +189,8 @@ export function apply(ctx, config = {}) {
         }
         catch { }
     }
-    // 6. 探测 DSH 底座网络暴露姿态，自适应裁决是否拉起独立安全反向代理网关
-    // 配置错误（如 mode: 'gateway' + 具体 LAN IP）不能把整个插件 apply 抛崩；
-    // 捕获后回退到 direct 模式，让用户仍可通过 3080 本机/局域网访问并修改配置。
+    // 6. 探测 DSH 底座网络暴露姿态：默认 proxy；核心已对外监听时回退 direct。
+    // 检测逻辑本身不抛错，异常时仍保留兜底，避免插件 apply 崩溃。
     let modeFallbackError = '';
     let detection;
     try {
@@ -180,37 +198,44 @@ export function apply(ctx, config = {}) {
     }
     catch (err) {
         modeFallbackError = err?.message || String(err);
-        ctx.logger?.error?.('[dsh-remote-mobile] 网关模式不可用，已回退 direct 模式:', err);
+        ctx.logger?.error?.('[dsh-remote-mobile] 安全接入代理配置不可用，已回退 direct 模式:', err);
         detection = detectServerMode(ctx, 'direct', ctx.webServer?.port ?? 3080);
     }
-    // 强制 gateway 且底座已监听通配地址时，输出安全提醒：核心 3080 仍暴露，
-    // 网关只是附加入口，不能替代核心侧的 Host/Origin 防护。
-    const modeWarning = detection.mode === 'gateway' && !detection.isLoopback
-        ? `底座本身已监听 ${detection.rawCoreHost}，3080 仍是对外入口；网关 3081 为附加入口，建议优先恢复 127.0.0.1 监听。`
-        : '';
+    // 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 === 'gateway') {
+    if (detection.mode === 'proxy') {
         const opts = store.getOptions();
         gatewayServer = new GatewayServer({
-            port: opts.gatewayPort ?? 3081,
-            host: opts.gatewayHost ?? '0.0.0.0',
+            port: opts.proxyPort ?? 3081,
+            host: opts.proxyHost ?? '0.0.0.0',
             corePort: detection.corePort,
             coreHost: detection.coreHost,
         }, store, gateMiddleware, ctx.logger);
         // 初始标记为正在启动中
-        store.setActiveGatewayInfo('gateway', opts.gatewayPort ?? 3081, detection.corePort, false);
+        store.setActiveGatewayInfo('proxy', opts.proxyPort ?? 3081, detection.corePort, false);
         gatewayReadyPromise = gatewayServer.start().then(({ port }) => {
             if (gatewayServer?.getServer()) {
                 setGatewaySecret(gatewayServer.getServer(), gatewaySecret);
             }
-            store.setActiveGatewayInfo('gateway', port, detection.corePort, true);
+            store.setActiveGatewayInfo('proxy', port, detection.corePort, true);
             syncTrustedHosts();
             return port;
         }).catch((err) => {
-            store.setActiveGatewayInfo('gateway', opts.gatewayPort ?? 3081, detection.corePort, false, err?.message || String(err));
-            ctx.logger?.error?.('[dsh-remote-mobile] 独立安全反向代理网关启动失败:', err);
-            return opts.gatewayPort ?? 3081;
+            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 {
@@ -245,7 +270,7 @@ export function apply(ctx, config = {}) {
         if (disposed || printed)
             return;
         printed = true;
-        // 等待网关就绪以获得准确的对外端口（避免端口自增探测竞态）
+        // 等待安全接入代理就绪以获得准确的对外端口（避免端口自增探测竞态）
         try {
             if (gatewayReadyPromise) {
                 await Promise.race([
@@ -279,21 +304,34 @@ export function apply(ctx, config = {}) {
             const activePort = store.getActivePort();
             const activeMode = store.getActiveMode();
             const corePort = store.getCorePort();
+            const coreHost = detection.coreHost;
             const opts = store.getOptions();
-            const gwStatus = store.getGatewayStatus();
+            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(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}`);
+                console.log(`│ ⚠️ 安全接入代理配置不可用，已回退 direct 模式: ${modeFallbackError}`);
             }
             if (modeWarning) {
                 console.log(`│ ⚠️ ${modeWarning}`);
             }
-            if (activeMode === 'gateway') {
-                if (gwStatus.running) {
-                    console.log(`│ 独立安全反代网关已激活 (0.0.0.0:${activePort} -> 127.0.0.1:${corePort})`);
-                    console.log(`│ 手机/远程设备请访问安全网关地址:`);
+            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 局域网直连)`);
                     }
@@ -301,17 +339,22 @@ export function apply(ctx, config = {}) {
                         console.log(`│   • 虚拟私网:   http://${tsIp}:${activePort} (Tailscale 私网异地直连)`);
                     }
                     console.log(`│ 电脑本机浏览器访问控制台:`);
-                    console.log(`│   • 本机回环:   http://127.0.0.1:${corePort}`);
+                    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(`│ ⚠️ 独立安全反代网关未成功启动: ${gwStatus.error || '端口占用'}`);
-                    console.log(`│ 外部手机设备当前暂时无法连接，请检查 3081 端口占用`);
+                    console.log(`│ ⚠️ 安全接入代理未成功启动: ${proxyStatus.error || '端口占用'}`);
+                    console.log(`│ 外部手机设备当前暂时无法连接，请检查 ${opts.proxyPort ?? 3081} 端口占用`);
                     console.log(`│ 电脑本机浏览器仍可直接访问:`);
                     console.log(`│   • 本机回环:   http://127.0.0.1:${corePort}`);
                 }
             }
             else {
-                console.log(`│ 远程安全网关已就绪，支持手机浏览器访问:`);
+                console.log(`│ 直连模式已启用（无独立安全接入代理），支持手机浏览器访问:`);
                 console.log(`│   • 本机回环:   http://127.0.0.1:${corePort}`);
                 if (lanIp && lanIp !== '127.0.0.1') {
                     console.log(`│   • 局域网:     http://${lanIp}:${corePort} (同 Wi-Fi 局域网直连)`);
@@ -320,10 +363,17 @@ export function apply(ctx, config = {}) {
                     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] 移动端远程控制与安全门禁已激活 (运行模式: ${activeMode}, 对外端口: ${activePort})`);
@@ -359,6 +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[];