@wenbin_wb/dsh-bridge 2.10.12 → 2.10.14

package/client/mobile-styles.js

@@ -20,6 +20,55 @@ export const MOBILE_STYLES_CSS = `
       --dsh-mobile-safe-bottom: env(safe-area-inset-bottom, 0px);
     }
 
+    /* 挂在 <body> 下、自带遮罩的「模态根」必须能盖在设置弹窗之上。
+       —— 这是本插件抬高设置弹窗层叠后必须自己补上的一环（谁抬的谁负责）。
+
+       故障现象：插件市场设置页点「安装」没有任何反应。
+       根因链：
+         1) 本插件把设置弹窗抬到 z-index:10002（见下面 @media 块），以便盖住自己渲染的
+            移动端顶栏(9998)/抽屉遮罩(9999)；
+         2) 插件市场（dshmarket 1.44.0）的安装确认框是挂在 <body> 下的
+            div._root_w1urq_2，position:fixed，但只有 z-index:1000；
+         3) 该浮层内部的对话框 div._dialog_w1urq_22 虽然带 role="dialog"、被下面的
+            10005 规则抬起来了，**但 z-index 无法逃出祖先的层叠上下文** —— 外层模态根
+            只有 1000，整棵子树（连同那个 10005）一起被设置弹窗(10002)盖死；
+         4) 结果：竖屏点安装完全看不到浮层（设置弹窗的遮罩在 elementFromPoint 上命中）；
+            横屏（宽度 > 767 时本插件样式不生效，设置弹窗回落成宿主的 1000）浮层虽出现，
+            却与页面内容互相穿透、显示不完整。
+
+       选择器刻意不硬编码任何第三方类名/哈希，只认模态根的两个**结构特征**：
+       「body 的直接子级」+「自带遮罩子元素（或有 role=dialog 子元素）」。
+       实测在打开设置前/后/点安装后三个阶段，本页面上该选择器**只命中市场那一个浮层**，
+       无误伤；本插件自己的 #dsh-remote-workspace-modal 有 ID 规则(100000)，优先级更高，
+       不受影响。仅在设置弹窗打开时生效（body:has(...)），把影响面压到最小。
+
+       【已知边界】判据只看结构，无法区分「真模态」与「恰好长成这样、且不可关闭的全屏
+       遮罩」。若某个插件往 <body> 下挂一个带 mask 子元素的全屏层，它也会被抬到设置
+       弹窗之上并盖住设置页。这是「模态就该盖在设置弹窗之上」的既定取舍：宁可让真模态
+       可见，也不接受"弹了却点不到"。独立验收已实测该构造会命中；若将来真踩到，
+       应改为按「该浮层是否可关闭」进一步收窄，而不是回退这条规则。 */
+    body:has(div[class*="VOzbGW_overlay"]) > div:has(> div[class*="mask"], > div[role="dialog"]) {
+      z-index: 10050 !important;
+    }
+
+    /* 同上场景的第二个独立问题：第三方模态对话框「比视口还高」。
+       插件市场的安装确认框是固定 584px 高 + overflow-y:hidden，在矮视口（横屏手机
+       320–430px 高，以及 320×480 这类小屏）里被居中撑开 → 上下同时被切掉，底部
+       「Cancel / Confirm install」落到视口之外，用户点不到、流程走不下去
+       （实测 667×375 时对话框 rect y=-116 h=608、按钮 y=432；844×390 同样）。
+
+       修法是让模态对话框不超过视口并允许内部滚动。这条是**自限性**的：
+       max-height 只在「视口比对话框矮」时才起作用 —— 375×667 / 390×844 等正常竖屏下
+       100dvh-16px(=651/828) > 584，声明不产生任何视觉变化。
+       vh 与 dvh 各写一遍：不支持 dvh 的环境退回 vh；两条都失效也只是保持原样。 */
+    body:has(div[class*="VOzbGW_overlay"]) > div:has(> div[role="dialog"]) > div[role="dialog"] {
+      /* 留 32px 而不是 16px：该对话框是 content-box + 24px 纵向内边距，
+         按内容盒算的 max-height 会再多出内边距的边框盒高度，16px 时仍溢出 4px。 */
+      max-height: calc(100vh - 32px) !important;
+      max-height: calc(100dvh - 32px) !important;
+      overflow-y: auto !important;
+    }
+
     /* 断点与宿主判据对齐：宿主用 viewportWidth < 768 决定右侧栏自动全屏
        （dsh-client-ui-sidebar-right/lib/client.js），故移动端样式取 <=767px，
        768px 起彻底交还桌面布局，避免"桥渲染顶栏、宿主却未全屏"的错位。 */
@@ -664,56 +713,91 @@ export const MOBILE_STYLES_CSS = `
         box-shadow: 0 20px 40px rgba(0, 0, 0, 0.25) !important;
         background: var(--dsw-alias-bg-layer-1, #ffffff) !important;
       }
+      /* 6.1 481–767px：保留左侧图标轨道。
+         78px 轨道把 "Agent presets"/"Plugin Market" 挤到两侧只剩 ~5px、标签被压到
+         10.5px 且 word-break:break-all 会从词中间断字，故放宽到 88px / 11.5px，
+         并改用 overflow-wrap 兜底（正常单词不再被拆）。 */
       nav[class*="VOzbGW_nav"] {
-        width: 78px !important;
-        min-width: 78px !important;
-        max-width: 78px !important;
-        padding: 10px 4px !important;
+        width: 88px !important;
+        min-width: 88px !important;
+        max-width: 88px !important;
+        padding: 10px 6px !important;
         box-sizing: border-box !important;
         border-right: 1px solid var(--dsw-alias-border-l2, #e5e7eb) !important;
         display: flex !important;
         flex-direction: column !important;
         gap: 6px !important;
         overflow-y: auto !important;
+        overscroll-behavior: contain !important;
       }
       nav[class*="VOzbGW_nav"] button[class*="VOzbGW_navCell"],
       button[class*="VOzbGW_navCell"] {
-        padding: 8px 2px !important;
+        padding: 7px 2px !important;
         display: flex !important;
         flex-direction: column !important;
         align-items: center !important;
         justify-content: center !important;
         text-align: center !important;
         height: auto !important;
-        min-height: 48px !important;
-        gap: 4px !important;
+        min-height: 46px !important;
+        /* flex:none：单元格不得被压缩，否则矮视口下末项会贴着轨道下沿被切掉 */
+        flex: 0 0 auto !important;
+        gap: 3px !important;
         border-radius: 10px !important;
       }
       span[class*="VOzbGW_navLabel"] {
-        font-size: 10.5px !important;
-        line-height: 1.2 !important;
+        font-size: 11.5px !important;
+        line-height: 1.25 !important;
         white-space: normal !important;
-        word-break: break-all !important;
+        word-break: normal !important;
+        overflow-wrap: anywhere !important;
         text-align: center !important;
       }
+
+      /* 矮视口（横屏手机）：压缩轨道单元格，保证 6 个分类全部落在面板内，
+         而不是靠 nav 自身的 overflow-y 滚动把末项藏起来（当前无任何可滚动提示）。 */
+      @media (max-height: 500px) {
+        nav[class*="VOzbGW_nav"] {
+          padding: 8px 6px !important;
+          gap: 4px !important;
+        }
+        nav[class*="VOzbGW_nav"] button[class*="VOzbGW_navCell"],
+        button[class*="VOzbGW_navCell"] {
+          min-height: 40px !important;
+          padding: 4px 2px !important;
+        }
+        div[class*="VOzbGW_navTitle"] {
+          font-size: 13px !important;
+          line-height: 1.3 !important;
+          padding: 0 4px !important;
+        }
+      }
+
       div[class*="VOzbGW_content"] {
         flex: 1 1 auto !important;
         min-width: 0 !important;
-        width: calc(100% - 78px) !important;
-        max-width: calc(100% - 78px) !important;
+        width: calc(100% - 88px) !important;
+        max-width: calc(100% - 88px) !important;
         display: flex !important;
         flex-direction: column !important;
         overflow: hidden !important;
       }
+      /* overflow-x 必须是 auto 而不是 hidden：宿主原样式只写了 overflow-y:auto，
+         按 CSS Overflow 规范 overflow-x 会计算为 auto（可横滑）。此前插件强制
+         hidden，把「可滚动」降级成「静默裁切」——溢出内容既看不到也滑不出来
+         （实测 375px 下裁掉 42px，Plugin Market 的 Installed/Advanced 两个 Tab
+         直接不可达）。这里恢复宿主默认，保证任何第三方设置节的内容至少可达。 */
       div[class*="VOzbGW_options"] {
         flex: 1 1 auto !important;
         width: 100% !important;
         max-width: 100% !important;
+        min-width: 0 !important;
         box-sizing: border-box !important;
         padding: 0 14px 20px !important;
-        overflow-x: hidden !important;
+        overflow-x: auto !important;
         overflow-y: auto !important;
         -webkit-overflow-scrolling: touch !important;
+        overscroll-behavior: contain !important;
       }
 
       /* 设置中心选项行手机自适应（垂直流式，防文字单字折行） */
@@ -723,12 +807,15 @@ export const MOBILE_STYLES_CSS = `
         align-items: stretch !important;
         gap: 8px !important;
         width: 100% !important;
+        /* min-width:0：让 flex 子项可以真正收缩，而不是把父容器顶宽后溢出 */
+        min-width: 0 !important;
         padding: 12px 0 !important;
         box-sizing: border-box !important;
       }
       div[class*="VOzbGW_options"] div[class*="_rowText"] {
         width: 100% !important;
         max-width: 100% !important;
+        min-width: 0 !important;
       }
       div[class*="VOzbGW_options"] button[class*="_selector"],
       div[class*="VOzbGW_options"] select,
@@ -796,6 +883,209 @@ export const MOBILE_STYLES_CSS = `
       }
     }
 
+    /* 6.2 <=480px 手机竖屏：设置中心改为「两级钻取」。
+       侧边轨道在 375px 屏上要吃掉 88px（21% 宽度），内容列只剩 277px，第三方设置节
+       （Plugin Market 的 Tab 条需 470px）必然溢出。改为：分类列表页 ↔ 内容详情页，
+       内容独占整宽（375px 下由 277px 提升到 355px，+28%），标签回到 15px、触控行 52px。
+
+       【整块由 html[data-dshbr-drilldown="ready"] 门控】
+       本块默认把内容区（options）隐藏、只显示分类列表；能不能从列表走进内容，完全
+       取决于 client/index.js 的点击监听器。所以本块不能以「JS 一定在」为无条件前提：
+       开关没打开时本块整体惰性，<=480px 退回 767 块的 88px 图标轨道（窄，但分类与
+       内容都完整可达），不会出现「内容被藏了、又没人能把用户带进去」的死列表。
+
+       开关何时打开（client/index.js 的 setupSettingsDrilldown）：
+         - 该函数是 apply() 的第一条语句，早于注入本 CSS 的 injectMobileStyles()；
+         - 只有 document.addEventListener('click', …) 成功返回后才打上 ready。
+       因此「本 CSS 已生效、而点击监听器没装上」在可执行路径上不可达；即使将来有人把
+       该调用挪到会抛异常的初始化之后，开关未开也只是退回轨道布局。
+
+       明确未覆盖：无法在脚本内探测「addEventListener 被环境静默丢弃」这类异常 ——
+       要做这种自检就必须在 document 上派发合成 click，而宿主与第三方插件合计有 6 个
+       document 级 click 监听（另有多组 mousedown/pointerdown）会被误触发，得不偿失。
+       插件 JS 完全不执行时本 CSS 也不会注入，同样不会藏内容。
+
+       开关放在 <html> 而非 panel：监听器必须在弹窗出现之前就装好，那时 panel 还不存在。
+
+       panel 上的 data-dshbr-settings-view 只表达「列表页 / 详情页」：
+         - 无该属性（含开关刚打开的首帧）→ 分类列表页
+         - "detail"                        → 内容详情页 */
+    @media (max-width: 480px) {
+      /* 面板由 767 块的横向轨道布局（row）改为纵向：列表页/详情页都是上下结构。
+         漏掉这一条会让 nav 与 content 并排抢宽度，分类列表被压成 0 宽（实测 options
+         只剩 24px），是本方案最容易漏的关键一步。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"] {
+        flex-direction: column !important;
+        /* ✕ 要绝对定位到面板右上角，必须有定位祖先 */
+        position: relative !important;
+      }
+
+      /* 关闭按钮钉在面板右上角，与标题/返回行同处第一行 —— 这是弹窗的常规约定。
+         之所以要绝对定位：宿主 DOM 里 ✕ 属于 content>header，而标题属于 nav，二者是
+         两棵子树。此前靠 order:-1 把 content 提到 nav 之前，结果 ✕ 落在标题上面一行；
+         详情页反过来，✕ 落到返回行下面一行。绝对定位是唯一能在不注入 DOM 的前提下
+         把两者拉回同一行的办法。 */
+      html[data-dshbr-drilldown="ready"] button[class*="VOzbGW_close"] {
+        position: absolute !important;
+        top: 9px !important;
+        right: 9px !important;
+        width: 32px !important;
+        height: 32px !important;
+        z-index: 5 !important;
+      }
+
+      /* 分类列表页：内容区只剩 header（宿主/第三方 action 槽），下沉为底部动作栏。
+         不再用 order:-1 —— 标题回到 DOM 顺序的第一行，顺带让焦点顺序与视觉顺序一致。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"]:not([data-dshbr-settings-view="detail"]) > div[class*="VOzbGW_content"] {
+        flex: 0 0 auto !important;
+        width: 100% !important;
+        max-width: 100% !important;
+        border-top: 1px solid var(--dsw-alias-border-l2, #e5e7eb) !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"]:not([data-dshbr-settings-view="detail"]) div[class*="VOzbGW_options"] {
+        display: none !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"]:not([data-dshbr-settings-view="detail"]) > nav[class*="VOzbGW_nav"] {
+        flex: 1 1 auto !important;
+        min-height: 0 !important;
+        overflow-y: auto !important;
+        overscroll-behavior: contain !important;
+      }
+
+      /* 详情页：折叠导航为「‹ 标题」一行，充当返回入口 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] div[class*="VOzbGW_navList"] {
+        display: none !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] > nav[class*="VOzbGW_nav"] {
+        flex: 0 0 auto !important;
+        overflow: visible !important;
+        cursor: pointer !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] > nav[class*="VOzbGW_nav"]:active {
+        background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.05)) !important;
+      }
+      /* 详情页也把动作栏沉到底部，与列表页保持一致。
+         用 flex order 交换 header/options 的视觉位置：options 仍是那个 overflow:auto
+         的滚动容器，滚动语义不变（不用 column-reverse，避免滚动原点翻转）。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] div[class*="VOzbGW_header"] {
+        order: 2 !important;
+        border-top: 1px solid var(--dsw-alias-border-l2, #e5e7eb) !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] div[class*="VOzbGW_options"] {
+        order: 1 !important;
+      }
+
+      /* 轨道在窄屏改成整宽列表容器 */
+      html[data-dshbr-drilldown="ready"] nav[class*="VOzbGW_nav"] {
+        width: 100% !important;
+        min-width: 0 !important;
+        max-width: 100% !important;
+        padding: 10px 12px 12px !important;
+        gap: 4px !important;
+        border-right: none !important;
+        border-bottom: none !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_navTitle"] {
+        font-size: 17px !important;
+        line-height: 1.3 !important;
+        /* 不可折行的超长 token（无空格长串）会整块溢出、把文字顶到 ✕ 下面。
+           独立验收实测 81 字符无空格标题时文字右端 823px、与 ✕ 交叠 707px²。
+           overflow-wrap: anywhere 让这种 token 也能断行 —— 留白只管盒内，管不住溢出。 */
+        overflow-wrap: anywhere !important;
+        /* 右侧 52px 给绝对定位的 ✕ 让位（紧邻规则里的声明会被后置同名规则覆盖，
+           所以留白必须写在这一条上，不能只写在前面那条） */
+        padding: 0 52px 4px 4px !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_navList"] {
+        flex-direction: column !important;
+        gap: 2px !important;
+        width: 100% !important;
+        min-width: 0 !important;
+      }
+
+      /* 列表行：图标左、文字右、行尾 › 指示 */
+      html[data-dshbr-drilldown="ready"] nav[class*="VOzbGW_nav"] button[class*="VOzbGW_navCell"],
+      html[data-dshbr-drilldown="ready"] button[class*="VOzbGW_navCell"] {
+        flex-direction: row !important;
+        justify-content: flex-start !important;
+        align-items: center !important;
+        text-align: left !important;
+        width: 100% !important;
+        min-height: 52px !important;
+        padding: 12px 14px !important;
+        gap: 12px !important;
+        border-radius: 12px !important;
+      }
+      html[data-dshbr-drilldown="ready"] nav[class*="VOzbGW_nav"] button[class*="VOzbGW_navCell"]::after {
+        content: '' !important;
+        width: 7px !important;
+        height: 7px !important;
+        margin-left: auto !important;
+        flex: none !important;
+        border-right: 1.7px solid var(--dsw-alias-label-tertiary, #9ca3af) !important;
+        border-bottom: 1.7px solid var(--dsw-alias-label-tertiary, #9ca3af) !important;
+        transform: rotate(-45deg) !important;
+      }
+      html[data-dshbr-drilldown="ready"] nav[class*="VOzbGW_nav"] button[class*="VOzbGW_navCell"] svg {
+        width: 20px !important;
+        height: 20px !important;
+      }
+      html[data-dshbr-drilldown="ready"] span[class*="VOzbGW_navLabel"] {
+        font-size: 15px !important;
+        line-height: 1.35 !important;
+        white-space: normal !important;
+        word-break: normal !important;
+        text-align: left !important;
+        flex: 0 1 auto !important;
+      }
+
+      /* 详情页返回行：‹ 箭头 + 标题 */
+      /* 详情页返回行：‹ 箭头 + 标题。右侧同样要留 52px 给 ✕ ——
+         本条比基类多一个属性选择器、特异性更高，会**整体覆盖**基类的 padding，
+         所以留白必须在这里再写一遍（漏写时基类的 52px 会被这条的 4px 顶掉，
+         长标题会钻到 ✕ 下面；独立验收实测注入 61 字符标题后交叠 608/707 px²）。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] div[class*="VOzbGW_navTitle"] {
+        display: flex !important;
+        align-items: center !important;
+        overflow-wrap: anywhere !important;
+        padding: 2px 52px 2px 4px !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_panel"][data-dshbr-settings-view="detail"] div[class*="VOzbGW_navTitle"]::before {
+        content: '' !important;
+        width: 8px !important;
+        height: 8px !important;
+        margin: 0 10px 0 6px !important;
+        flex: none !important;
+        border-left: 2px solid var(--dsw-alias-label-primary, #111827) !important;
+        border-bottom: 2px solid var(--dsw-alias-label-primary, #111827) !important;
+        transform: rotate(45deg) !important;
+      }
+
+      /* content/header 必须是 static —— ✕ 是绝对定位的，它的包含块取决于最近的**定位祖先**。
+         本来这个祖先就是 panel（宿主自带 position:relative）；但一旦 content 或 header 被
+         任何来源（本块、宿主其它规则、第三方插件）设成 relative/absolute，包含块就会下移，
+         ✕ 会从面板右上角跑到内容区里去。独立验收实测：给 content 加 position:relative 后
+         ✕ 的 relTop 由 9 变成 579、并与底部动作栏重叠 837 px²。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_content"] {
+        position: static !important;
+        width: 100% !important;
+        max-width: 100% !important;
+        flex: 1 1 auto !important;
+      }
+      /* header 不再当顶栏用：它现在只承载 action 槽，高度随内容（可能是宿主的一个
+         按钮，也可能是多个插件注入的多行按钮），靠 flex 自然撑开，不设固定高度。 */
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_header"] {
+        position: static !important;
+        height: auto !important;
+        padding: 8px 10px !important;
+        align-items: center !important;
+        justify-content: flex-end !important;
+      }
+      html[data-dshbr-drilldown="ready"] div[class*="VOzbGW_options"] {
+        padding: 0 12px 16px !important;
+      }
+    }
+
     /* 远程工作区选择弹窗移动端/桌面端自适应样式 */
     #dsh-remote-workspace-modal {
       position: fixed !important;

package/client/picker-yield.js

@@ -0,0 +1,77 @@
+// DSH 官方目录选择器的「让位」判定（issue #28 第 2 条）
+//
+// 背景：DSH 0.1.5 起自带官方目录选择器，且注册到与 dsh-bridge 完全相同的两个 Slot：
+//   conversation.hero.workspace.directoryFlow
+//   sidebar.workspaces.directoryFlow
+// 后端由 @deepseek-ai/dsh-host-directory-picker-auto 按宿主事实分发：非回环绑定 /
+// SSH / Linux 无 zenity·kdialog 等图形 chooser → browse（网页树形选择器），
+// macOS·Windows 或 Linux 有 chooser → native（系统对话框）。
+//
+// 而 DSH 的 slots 是 shadow 语义：@deepseek-ai/dsh-cordis-client-runner 的注释明确
+//   "Page-local shadowing rank. A later registration receives a lower priority."
+//   "a dynamically registered entry is assigned a lower priority than the shipped
+//    one, which makes it the winner"
+// 即数值越小越优先、后注册者胜。动态加载的 dsh-bridge 因此天然覆盖内置 picker，
+// 叠加本插件显式写的 `priority: -10`，连本机（127.0.0.1 / Electron）也被插件自己的
+// 远程目录选择器接管：点「添加工作区」弹的是插件的远程抽屉而非 DSH 官方选择器。
+//
+// 让位条件（两者同时成立才让位）：
+//   1. 本机访问（isLocalEnvironment()）—— 本机有完整权限，官方 picker 直接可用；
+//   2. DSH 已自带官方 picker —— 旧版 DSH 没有，必须继续由插件兜底，
+//      否则本机点「添加工作区」将彻底没有反应。
+// 远程 / 移动访问一律继续由插件接管：那里需要管理密码解锁与 local_only 目录策略，
+// 不能换成官方 picker（会绕过插件的访问限制）。
+//
+// 为什么探测用 ctx.get() 而不是 ctx.uiWorkspace：
+//   cordis 本体对**未在插件 inject 中声明**的服务做属性访问会直接抛错：
+//     cannot get property "uiWorkspace" without inject   （cordis/lib/index.js）
+//   —— dsh-bridge 的 client half 是静态 client 插件，其 ctx 是真 cordis Context
+//   （不是动态包的 runner guard facade），所以拦在这里的是 cordis 本体的规则。
+//   而 `ctx.get(name)` 是允许的「可选查找」，不要求声明。
+//   又不能把 uiWorkspace 写进 inject：旧版 DSH（无该 seat）会因此把整个插件 park 掉
+//   （provider 缺失即不 apply），所以只能用 ctx.get() 探测。
+//
+// ⚠️ 已知时序依赖（独立验收记录，真机 6/6 冷启动实测未触发）：
+//   cordis 的 ctx.get() 在 provider fiber 尚未进入 ACTIVE 时会返回 undefined。理论上若
+//   本判定早于 ui-workspace 插件 apply 完成，就会把「有官方 picker」误判为「无」而仍然
+//   注册，让位失效。当前稳定是因为 dsh-bridge 自身 inject 的 workspaces / sessions 由
+//   roster 中排在 ui-workspace **之后**的插件提供，插件真正激活时 ui-workspace 早已
+//   apply 完成 —— 这是对 roster 顺序的**隐式耦合，不是显式保证**。若将来调整 roster
+//   顺序或去掉 workspaces 依赖，需重新评估（加固思路：注册后等 uiWorkspace 可用时
+//   再撤销自己的注册）。
+
+/** 官方 workspace seat 的服务名（DSH 0.1.5 起提供 pickDirectory） */
+export const OFFICIAL_WORKSPACE_SEAT = 'uiWorkspace';
+
+/**
+ * 探测 DSH 是否已提供官方目录选择器。
+ *
+ * 用 `ctx.get()` 做可选查找：seat 不存在（旧版 DSH）、宿主未暴露 pickDirectory、
+ * 查询或属性读取抛错时一律返回 false —— 探测本身绝不外抛影响插件加载。
+ *
+ * @param {{ get?: (name: string) => unknown }} [ctx] cordis 客户端 context
+ * @returns {boolean} 官方 picker 是否可用
+ */
+export function hasOfficialDirectoryPicker(ctx) {
+  try {
+    if (typeof ctx?.get !== 'function') return false;
+    const seat = ctx.get(OFFICIAL_WORKSPACE_SEAT);
+    // typeof 也放在 try 内：seat 可能是带异常 getter 的对象或 Proxy，
+    // 读 pickDirectory 本身就可能抛错。
+    return typeof seat?.pickDirectory === 'function';
+  } catch {
+    // ctx.get 抛错（宿主异常），或属性读取抛错（异常 getter / Proxy）：
+    // 一律按「无官方 picker」处理，保持插件原有兜底行为，探测绝不外抛。
+    return false;
+  }
+}
+
+/**
+ * 是否应让位给 DSH 官方目录选择器。
+ *
+ * @param {{ local?: boolean, officialPicker?: boolean }} [facts]
+ * @returns {boolean} true = 不注册插件选择器，本机交给 DSH 官方处理
+ */
+export function shouldYieldToOfficialPicker(facts) {
+  return Boolean(facts?.local) && Boolean(facts?.officialPicker);
+}