@yezack/dsh-remote-mobile 1.10.0 → 1.10.2

package/lib/bridge/directory-picker.d.ts

@@ -0,0 +1,118 @@
+/**
+ * DSH 目录选择器（Directory Picker）配置检测与幂等补丁管理模块
+ *
+ * 【背景与问题】
+ * DSH 官方默认的 `id: directory-picker`（`@deepseek-ai/dsh-host-directory-picker-auto`）
+ * 仅在进程启动时根据 `webServer.host` 是否为 127.0.0.1 回环地址来判断“本机 / 远程”：
+ * - 本插件默认采用安全接入代理模式（DSH 核心保持 127.0.0.1:3080 回环，由 3081 代理对外）；
+ * - `auto` 因此将所有来自手机端 3081 的请求误判为“本机桌面操作”，直接调用 PC 的系统原生文件选择窗（native）；
+ * - 最终导致弹窗出现在 PC 屏幕上，手机浏览器一直转圈等待，无法在手机端选择文件夹或添加工作区。
+ *
+ * 【解决方案】
+ * 1. 运行时检测：结合 Cordis loader 激活树与 `~/.dsh/profiles/web/cordis.patch.yml` 配置文件，
+ *    精准判断当前是否已启用网页内目录选择器（`browse` 模式）；
+ * 2. 幂等补丁写入：支持在设置页一键开启/恢复，写入时对 `directory-picker`、`directory-picker-browse`、
+ *    `ui-directory-picker-browse` 三项分别执行严格结构化去重，绝不产生重复条目，且完整保留用户其它配置。
+ */
+export declare const AUTO_DIRECTORY_PICKER_ID = "directory-picker";
+export declare const AUTO_DIRECTORY_PICKER_PKG = "@deepseek-ai/dsh-host-directory-picker-auto";
+export declare const HOST_DIRECTORY_PICKER_BROWSE_ID = "directory-picker-browse";
+export declare const HOST_DIRECTORY_PICKER_BROWSE_PKG = "@deepseek-ai/dsh-host-directory-picker-browse";
+export declare const UI_DIRECTORY_PICKER_BROWSE_ID = "ui-directory-picker-browse";
+export declare const UI_DIRECTORY_PICKER_BROWSE_PKG = "@deepseek-ai/dsh-client-ui-directory-picker-browse";
+/** 标准可复制/可注入的 YAML 配置片段 */
+export declare const DIRECTORY_PICKER_YAML_SNIPPET: string;
+export interface DirectoryPickerPatchInspection {
+    /** `- id: directory-picker` 是否已设置 `disabled: true` */
+    autoDisabled: boolean;
+    /** 是否存在 `- id: directory-picker` 条目 */
+    hasAutoEntry: boolean;
+    /** `@deepseek-ai/dsh-host-directory-picker-browse` 是否已插入且未禁用 */
+    hostBrowseInserted: boolean;
+    /** `@deepseek-ai/dsh-client-ui-directory-picker-browse` 是否已插入且未禁用 */
+    uiBrowseInserted: boolean;
+    /** 三项配置是否已在 patch 文件中全部就绪 */
+    configured: boolean;
+    /** 是否仅配置了其中一部分（缺失其余项） */
+    partial: boolean;
+}
+export interface DirectoryPickerRuntimeInspection {
+    /** 是否能够从 Cordis loader 探测到目录选择器相关条目 */
+    detected: boolean;
+    /** 运行时中 `browse` 目录选择器（前后端）是否已激活生效 */
+    browseActive: boolean;
+    /** 运行时中 `auto` 目录选择器是否仍处于启用状态 */
+    autoActive: boolean;
+}
+export interface DirectoryPickerStatus {
+    /** 配置文件中是否已完整开启 browse 补丁 */
+    patchEnabled: boolean;
+    /** 配置文件中是否仅开启了部分项 */
+    patchPartial: boolean;
+    /** 当前运行时中网页目录选择器是否已生效 */
+    runtimeActive: boolean;
+    /** 配置已变更但当前进程尚未生效（需要重启 DSH 或等待 HMR 重载） */
+    restartRequired: boolean;
+    /** 当前是否需要向用户展示醒目提醒（回环核心且未开启 browse 时为 true） */
+    needsWarning: boolean;
+    /** 目标 cordis.patch.yml 的绝对路径 */
+    patchFilePath: string;
+    /** 标准可复制的 YAML 配置片段 */
+    yamlSnippet: string;
+}
+/**
+ * 绑定 Cordis 运行时上下文与回环核心判定函数（供 /status 路由实时查询）
+ */
+export declare function bindDirectoryPickerRuntime(ctx: any, isLoopbackCore?: () => boolean): void;
+/**
+ * 定位当前 DSH 的 web profile `cordis.patch.yml` 路径
+ *
+ * 优先使用 `~/.dsh/profiles/web/cordis.patch.yml`；若存在其他单 profile 则按优先级兜底。
+ */
+export declare function resolveDirectoryPickerPatchPath(customPath?: string): string;
+/**
+ * 解析 `cordis.patch.yml` 文本内容，检查目录选择器相关配置状态
+ */
+export declare function inspectDirectoryPickerPatchContent(content: string): DirectoryPickerPatchInspection;
+/**
+ * 检查 Cordis 运行时 loader 中的目录选择器插件激活状态
+ */
+export declare function inspectRuntimeDirectoryPicker(ctx?: any): DirectoryPickerRuntimeInspection;
+/**
+ * 幂等合并网页目录选择器配置到 `cordis.patch.yml` 内容中（严格去重）
+ *
+ * 去重规则：
+ * 1. 若已存在一个或多个 `- id: directory-picker`：就地将其设为 `disabled: true`，合并重复项；
+ * 2. 若已存在 `directory-picker-browse` 或 `ui-directory-picker-browse`（无论在哪个 `insert` 块下）：
+ *    不重复插入，仅补充缺失的那一项（若原项被设为 `disabled: true` 则移除禁用标记）；
+ * 3. 若三项均已就绪，原样返回，`changed: false`。
+ */
+export declare function applyDirectoryPickerBrowsePatch(rawContent: string): {
+    content: string;
+    changed: boolean;
+};
+/**
+ * 从 `cordis.patch.yml` 内容中安全移除网页目录选择器补丁（恢复 PC 原生目录选择器）
+ *
+ * 仅移除与 directory-picker 相关的禁用项与两个 browse 插入项，100% 保留用户其他配置。
+ */
+export declare function removeDirectoryPickerBrowsePatch(rawContent: string): {
+    content: string;
+    changed: boolean;
+};
+/**
+ * 获取目录选择器当前综合状态（供 `/api/remote-mobile/status` 与设置页消费）
+ */
+export declare function getDirectoryPickerStatus(customPatchPath?: string): DirectoryPickerStatus;
+/**
+ * 在目标 `cordis.patch.yml` 中一键开启网页目录选择器（幂等去重）
+ */
+export declare function enableDirectoryPickerBrowse(customPatchPath?: string): DirectoryPickerStatus & {
+    changed: boolean;
+};
+/**
+ * 从目标 `cordis.patch.yml` 中移除网页目录选择器配置（恢复 PC 原生目录选择器）
+ */
+export declare function disableDirectoryPickerBrowse(customPatchPath?: string): DirectoryPickerStatus & {
+    changed: boolean;
+};