dsh-plugin-core 0.20.4 → 0.20.6

package/docs/design/style.md

@@ -172,7 +172,8 @@ border-right: 1px solid transparent;
 缝 + 圆角）当场被否：用户要的就是「让出 1 像素」，不是换一套滚动条外观。所以口径只有一条 ——
 让位量固定 1px，颜色 / 粗细 / 圆角全部归浏览器。
 
-- 已有实色边框的容器（如 Picker 菜单的 `border:1px solid`）滚动条贴的就是那条线，算已让位，**不要叠加**。
+- 已有实色边框的容器（如 Picker 菜单的 `border:1px solid`，或挂 `.dshpc-panel` 后由面板提供的边框）
+  滚动条贴的就是那条线，算已让位，**不要叠加**。
 - 消费方自己的滚动容器（主区 / 侧栏）不在本仓代码里，配方相同：自己加那条 `border-right`。
   2026-11-02 起 `--dshpc-dock-gap` 已删，dock 不再替主区让 margin，改由主区容器自己让。
 - 自检：`test/quality.test.mjs` 扫 `src/**/*.css`，滚动规则缺边框即红。
@@ -185,6 +186,30 @@ a `::-webkit-scrollbar` thumb (3px gap + radius) was tried on 2026-11-02 and rej
 Containers that already have a solid border count as done. Consumer-owned scroll containers use the same
 one-liner; `--dshpc-dock-gap` was removed on 2026-11-02. A test enforces the border.
 
+## 浮层三档：模态 / 锚点面板 / 菜单
+
+> EN: Three tiers for floating surfaces — modal / popover / menu
+
+所有「浮起来的框」的**表面**（底色 · 描边宽 · 圆角 · 阴影）只在 `src/ui/panel.css` 定义，档位只有三个
+（2026-11-03 用户定：样式统一，交互各家自己管）：
+
+| 档位 | 用在 | 底色 | 描边 | 圆角 | 阴影 |
+|---|---|---|---|---|---|
+| `--modal` | `Modal` / `ConfirmModal` / `AlertModal` | `surface-1` | 3px | `radius-xl` | `shadow-2` |
+| `--popover` | 选文件弹窗（`pickWorkspaceFile`） | `surface-1` | 1px | `radius-lg` | `shadow-2` |
+| `--menu` | ▾ 选层、`Picker` 下拉 | `surface-menu` | 1px | `radius-sm` | `shadow-1` |
+
+- 组件里**不许**再写这四个值；要改外观只改 `panel.css`。
+- **定位不归档位管**：Modal 居中、选文件弹窗贴锚点并上下翻转、菜单挂触发器下方，各自实现。
+- 关闭钮只有一枚 `.dshpc-panel__close`；旧类名 `.dshpc-overlay-head__close` 保留作别名（消费方覆盖不失效）。
+- 层序只许用 `--dshpc-z-panel`（面板本体）/ `--dshpc-z-popmenu`（叠在面板上的菜单与其透明遮罩），不许写字面量。
+- **不并入三档**：`PanelDock` 与 `SideSheet` 属贴边家族（`side-panel.css` 的 `.dshpc-side-surface`，
+  2026-11-02 拍板两者皮肤一模一样），一个是布局成员、一个是贴边抽屉，都不是浮层。
+- 组件**内部**的微层序（缩略按钮 5、拖拽条 7、dock 关闭钮 8、Segmented 的 0/1）不走 token ——
+  它们只在各自 stacking context 里排序，跟页面浮层层级无关。
+- 自检：`test/css-discipline.test.mjs` 盯「色值只进 `tokens.css`」「`--dshpc-panel-*` 只在 `panel.css`」；
+  `test/css-contract.test.mjs` 盯「一个类名一套皮肤」。
+
 ## 三条硬规矩
 
 > EN: Three hard rules

package/docs/help/explorer.doc.ts

@@ -1,20 +1,25 @@
 // explorer 子包的使用帮助 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
 import type { DocTopic } from '../design/doc-format.js'
 
-const explorerUsage = `import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+const explorerUsage = `import { connectFs, openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { serveFsRoute } from 'dsh-plugin-core/host'
+import { FS_PATH } from './paths'   // 你自己的常量：宿主与 client 必须用同一个
 
-// 只在 client apply 里接线一次（接工作区快照 + 读文件服务），之后不用再碰服务
+// ── 宿主半边（apply）：挂一条只读文件路由（不限工作区；读文件/列目录都在它上面） ──
+serveFsRoute(ctx, { path: FS_PATH })
+
+// ── client 半边（apply）：接一次（connectHost 照旧负责工作区快照） ──
 connectHost(ctx)
+connectFs({ path: FS_PATH })
 
 // 右侧分栏预览（占宽度、挤窄主区）：一个容器 + 一个路径就够
-openFilePreview({ mount, path: '/abs/ledger' })   // 文件夹 ⇒ 目录树；文件 ⇒ 直接预览
-openFilePreview({ mount, path: 'docs/README.md' }) // 工作区相对路径也行
-
-// 覆盖项：指定工作区快照 / 指定会话 / Office 转 PDF / 与别处共用的根缓存
-openFilePreview({ mount, path, workspaceAnchors, sessionId, officeToPdf, rootCache })
+openFilePreview({ mount, path: '/abs/ledger' })    // 文件夹 ⇒ 目录树；文件 ⇒ 直接预览
+openFilePreview({ mount, path: 'docs/README.md' }) // 工作区相对路径也行（相对谁见下）
+openFilePreview({ mount })                         // 不给路径 ⇒ 根节点（工作区清单 + 盘符）
 
-// 锚定弹窗选文件（Promise 返回路径，不自己挂 dock）
-const r = await pickWorkspaceFile({ anchor, filter: { exts: ['md'] } })`
+// 锚定弹窗选文件（Promise 返回**绝对路径**，不自己挂 dock）
+const r = await pickWorkspaceFile({ anchor, filter: { exts: ['md'] } })
+const dir = await pickWorkspaceFile({ anchor, filter: { dirs: true } })  // 只选文件夹`
 
 const doc: DocTopic = {
   title: { zh: 'explorer —— 工作区浏览', en: 'explorer — Workspace browsing' },
@@ -25,20 +30,20 @@ const doc: DocTopic = {
       heading: { zh: '概览', en: 'Overview' },
       prose: [
         {
-          zh: '提供工作区文件浏览与选择，数据来自宿主提供的工作区文件快照。',
-          en: 'Workspace file browsing and picking, driven by the host-provided workspace file snapshot.',
+          zh: '提供文件浏览与选择；数据走宿主侧只读 FS 路由，**不限工作区**（工作区之外也能浏览）。界面与原版一致。',
+          en: 'File browsing and picking **not limited to workspaces**: one root tree (workspace nodes + the real root), served by a host-side read-only FS route.',
         },
         {
-          zh: '**接线归核心**：client `apply` 里调一次 `connectHost(ctx)`，读文件服务、会话 id、工作区快照都由核心自己解，调用时只给容器和路径。',
-          en: '**Wiring belongs to core**: call `connectHost(ctx)` once in the client apply; the file service, session id and workspace snapshot are resolved by core — you only pass a container and a path.',
+          zh: '**接线归核心，但要两条**：宿主 `apply` 调 `serveFsRoute({ path })`，client `apply` 用同一个常量调 `connectFs({ path })`（`connectHost(ctx)` 照旧负责工作区快照）。浏览**不需要会话**。',
+          en: '**Core does the wiring, but with two calls**: `serveFsRoute({ path })` on the host side and `connectFs({ path })` with the same constant on the client side (`connectHost(ctx)` still covers the workspace snapshot). Browsing needs **no session**.',
         },
         {
           zh: '落点只给一个元素：页面里**包住主区**的那个（核心会补成 flex 行、让主区伸展，关闭时还原），不要传 `document.body` 再自己套 fixed——那是浮层，不是分栏。',
           en: 'Pass one element: the one wrapping the main area. Core makes it a flex row and lets the main area stretch, restoring it on close. Never pass `document.body` with your own fixed positioning — that is an overlay, not a split.',
         },
         {
-          zh: '绝对路径按最长前缀匹配所属工作区；落在任何工作区外时，文件照样能预览（官方 read 允许工作区外文件），只有目录树退化成只读路径栏。',
-          en: 'Absolute paths are matched to their workspace by longest prefix. Outside every workspace the file still previews (official read allows it); only the directory tree degrades to a read-only path bar.',
+          zh: '面包屑口径不变：路径所属工作区名作根名，其下按相对层级展开。▾ 下拉**根层置顶**（其余仍列各工作区）：POSIX 是一条「根目录」，**Windows 没有根目录这东西，列的是盘符**（`C:/`、`D:/`…，由宿主 `op:roots` 探出来）。点其他工作区 = 直接列该区根目录（不需要会话）。',
+          en: 'Inside a workspace the breadcrumb starts at its name and the ▾ menu nests it there; outside it starts at the real root (`/` or a drive). A workspace root still appears in the real path, tagged “Workspace”.',
         },
       ],
     },
@@ -84,29 +89,23 @@ const doc: DocTopic = {
                 en: 'The element wrapping the main area; no flex needed (core turns it into a flex row, stretches the main area, and restores it on close). Never `document.body`',
               },
             },
-            {
-              name: 'opts.workspaceFiles',
-              type: 'WorkspaceFilesFace',
-              def: '—',
-              desc: {
-                zh: '读文件服务。**一般不用传**：`connectHost(ctx)` 接线后核心自己持有；传了以传入为准。传 `content` 时可省',
-                en: 'File service. **Usually unnecessary**: core holds it after `connectHost(ctx)`; when passed it wins. Optional when passing `content`',
-              },
-            },
             {
               name: 'opts.sessionId',
               type: 'string',
               def: '—',
               desc: {
-                zh: '该工作区的真实会话 id。**一般不用传**：按路径匹配所属工作区，匹配不出就取最近有会话的工作区；传 `content` 时可省',
-                en: 'A real session id. **Usually unnecessary**: resolved from the path’s workspace, else the most recently updated workspace with a session; optional when passing `content`',
+                zh: '**只在两种情况下需要**：① 相对路径的基准工作区；② Office 预览（转 PDF 要一条有效会话，缺省由核心取最近有会话的工作区）',
+                en: 'Needed in exactly two cases: (1) the base workspace for a relative path; (2) Office preview (conversion needs one valid session; core falls back to the most recent workspace with one)',
               },
             },
             {
               name: 'opts.path',
               type: 'string',
               def: '—',
-              desc: { zh: '工作区相对路径；绝对路径会自动按最长前缀匹配所属工作区。与 `content` 二选一', en: 'Workspace-relative path; absolute paths are matched to their workspace by longest prefix. Mutually exclusive with `content`' },
+              desc: {
+                zh: '绝对路径或工作区相对路径（相对路径要有可解析的基准，否则返回 `null` 并 warn）；不传 ⇒ 根节点。与 `content` 二选一',
+                en: 'Absolute or workspace-relative (a relative one needs a resolvable base, else `null` + a warning); omitted ⇒ the root node. Mutually exclusive with `content`',
+              },
             },
             {
               name: 'opts.content',
@@ -128,9 +127,12 @@ const doc: DocTopic = {
             },
             {
               name: 'pickWorkspaceFile(opts)',
-              type: 'PickWorkspaceFileOptions => Promise<PickedFile>',
+              type: 'PickWorkspaceFileOptions => Promise<PickedPath | null>',
               def: '—',
-              desc: { zh: '锚定按钮弹出模态选文件，解析出 `{ path, isDir }`', en: 'Anchored modal picker that resolves `{ path, isDir }`' },
+              desc: {
+                zh: '锚定按钮弹出模态选文件，解析出 `{ path, isDir, workspaceRel?, workspace? }`；`path` 是**绝对路径**',
+                en: 'Anchored modal picker resolving `{ path, isDir, workspaceRel?, workspace? }`; `path` is **absolute**',
+              },
             },
             {
               name: 'opts.anchor',
@@ -143,7 +145,10 @@ const doc: DocTopic = {
               name: 'opts.filter',
               type: 'PickFilter',
               def: '—',
-              desc: { zh: '按扩展名过滤 `{ exts: [\'md\'] }`；`dirs: true` 则只允许选文件夹', en: 'Filter by extension `{ exts: [\'md\'] }`; `dirs: true` restricts picking to folders' },
+              desc: {
+                zh: '`exts` 只要这些扩展名（目录仍可展开导航）；`dirs: true` 只允许选文件夹（文件不渲染）',
+                en: '`exts` limits files (folders still expand); `dirs: true` picks folders only (files hidden, plus a “Select this folder” action in the crumb bar)',
+              },
             },
           ],
         },

package/docs/help/explorer.md

@@ -10,21 +10,21 @@
 
 > EN: Overview
 
-提供工作区文件浏览与选择，数据来自宿主提供的工作区文件快照。
+提供文件浏览与选择；数据走宿主侧只读 FS 路由，**不限工作区**（工作区之外也能浏览）。界面与原版一致。
 
-> EN: Workspace file browsing and picking, driven by the host-provided workspace file snapshot.
+> EN: File browsing and picking **not limited to workspaces**: one root tree (workspace nodes + the real root), served by a host-side read-only FS route.
 
-**接线归核心**：client `apply` 里调一次 `connectHost(ctx)`，读文件服务、会话 id、工作区快照都由核心自己解，调用时只给容器和路径。
+**接线归核心，但要两条**：宿主 `apply` 调 `serveFsRoute({ path })`，client `apply` 用同一个常量调 `connectFs({ path })`（`connectHost(ctx)` 照旧负责工作区快照）。浏览**不需要会话**。
 
-> EN: **Wiring belongs to core**: call `connectHost(ctx)` once in the client apply; the file service, session id and workspace snapshot are resolved by core — you only pass a container and a path.
+> EN: **Core does the wiring, but with two calls**: `serveFsRoute({ path })` on the host side and `connectFs({ path })` with the same constant on the client side (`connectHost(ctx)` still covers the workspace snapshot). Browsing needs **no session**.
 
 落点只给一个元素：页面里**包住主区**的那个（核心会补成 flex 行、让主区伸展，关闭时还原），不要传 `document.body` 再自己套 fixed——那是浮层，不是分栏。
 
 > EN: Pass one element: the one wrapping the main area. Core makes it a flex row and lets the main area stretch, restoring it on close. Never pass `document.body` with your own fixed positioning — that is an overlay, not a split.
 
-绝对路径按最长前缀匹配所属工作区；落在任何工作区外时，文件照样能预览（官方 read 允许工作区外文件），只有目录树退化成只读路径栏。
+面包屑口径不变：路径所属工作区名作根名，其下按相对层级展开。▾ 下拉**根层置顶**（其余仍列各工作区）：POSIX 是一条「根目录」，**Windows 没有根目录这东西，列的是盘符**（`C:/`、`D:/`…，由宿主 `op:roots` 探出来）。点其他工作区 = 直接列该区根目录（不需要会话）。
 
-> EN: Absolute paths are matched to their workspace by longest prefix. Outside every workspace the file still previews (official read allows it); only the directory tree degrades to a read-only path bar.
+> EN: Inside a workspace the breadcrumb starts at its name and the ▾ menu nests it there; outside it starts at the real root (`/` or a drive). A workspace root still appears in the real path, tagged “Workspace”.
 
 ## 0. 装包
 
@@ -43,20 +43,25 @@ pnpm add dsh-plugin-core
 > EN: `connectHost(ctx)` takes just that one slice; the whole ctx never enters core.
 
 ```tsx id="explorer-usage-code"
-import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { connectFs, openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { serveFsRoute } from 'dsh-plugin-core/host'
+import { FS_PATH } from './paths'   // 你自己的常量：宿主与 client 必须用同一个
 
-// 只在 client apply 里接线一次（接工作区快照 + 读文件服务），之后不用再碰服务
+// ── 宿主半边（apply）：挂一条只读文件路由（不限工作区；读文件/列目录都在它上面） ──
+serveFsRoute(ctx, { path: FS_PATH })
+
+// ── client 半边（apply）：接一次（connectHost 照旧负责工作区快照） ──
 connectHost(ctx)
+connectFs({ path: FS_PATH })
 
 // 右侧分栏预览（占宽度、挤窄主区）：一个容器 + 一个路径就够
-openFilePreview({ mount, path: '/abs/ledger' })   // 文件夹 ⇒ 目录树；文件 ⇒ 直接预览
-openFilePreview({ mount, path: 'docs/README.md' }) // 工作区相对路径也行
-
-// 覆盖项：指定工作区快照 / 指定会话 / Office 转 PDF / 与别处共用的根缓存
-openFilePreview({ mount, path, workspaceAnchors, sessionId, officeToPdf, rootCache })
+openFilePreview({ mount, path: '/abs/ledger' })    // 文件夹 ⇒ 目录树；文件 ⇒ 直接预览
+openFilePreview({ mount, path: 'docs/README.md' }) // 工作区相对路径也行（相对谁见下）
+openFilePreview({ mount })                         // 不给路径 ⇒ 根节点（工作区清单 + 盘符）
 
-// 锚定弹窗选文件（Promise 返回路径，不自己挂 dock）
+// 锚定弹窗选文件（Promise 返回**绝对路径**，不自己挂 dock）
 const r = await pickWorkspaceFile({ anchor, filter: { exts: ['md'] } })
+const dir = await pickWorkspaceFile({ anchor, filter: { dirs: true } })  // 只选文件夹
 ```
 
 ## API
@@ -67,12 +72,11 @@ const r = await pickWorkspaceFile({ anchor, filter: { exts: ['md'] } })
 |---|---|---|---|---|---|
 | `openFilePreview(opts)` | `OpenFilePreviewOptions => FilePreviewHandle` | — | — | 在右侧分栏打开文件 / 文件夹预览，返回可关闭它的句柄。预览内容二选一：`path`（核心解析并渲染）或 `content`（由调用方给内容） | Opens a file/folder preview in the right-side dock and returns a handle to close it. Body is one of two: `path` (resolved and rendered by core) or `content` (rendered from your own node) |
 | `opts.mount` | `HTMLElement` | 是 | — | 页面里**包住主区**的那个元素；不必自己写 flex（核心补成 flex 行并让主区伸展，关闭时还原）。不要传 `document.body` | The element wrapping the main area; no flex needed (core turns it into a flex row, stretches the main area, and restores it on close). Never `document.body` |
-| `opts.workspaceFiles` | `WorkspaceFilesFace` | — | — | 读文件服务。**一般不用传**：`connectHost(ctx)` 接线后核心自己持有；传了以传入为准。传 `content` 时可省 | File service. **Usually unnecessary**: core holds it after `connectHost(ctx)`; when passed it wins. Optional when passing `content` |
-| `opts.sessionId` | `string` | — | — | 该工作区的真实会话 id。**一般不用传**：按路径匹配所属工作区，匹配不出就取最近有会话的工作区；传 `content` 时可省 | A real session id. **Usually unnecessary**: resolved from the path’s workspace, else the most recently updated workspace with a session; optional when passing `content` |
-| `opts.path` | `string` | — | — | 工作区相对路径；绝对路径会自动按最长前缀匹配所属工作区。与 `content` 二选一 | Workspace-relative path; absolute paths are matched to their workspace by longest prefix. Mutually exclusive with `content` |
+| `opts.sessionId` | `string` | — | — | **只在两种情况下需要**：① 相对路径的基准工作区；② Office 预览（转 PDF 要一条有效会话，缺省由核心取最近有会话的工作区） | Needed in exactly two cases: (1) the base workspace for a relative path; (2) Office preview (conversion needs one valid session; core falls back to the most recent workspace with one) |
+| `opts.path` | `string` | — | — | 绝对路径或工作区相对路径（相对路径要有可解析的基准，否则返回 `null` 并 warn）；不传 ⇒ 根节点。与 `content` 二选一 | Absolute or workspace-relative (a relative one needs a resolvable base, else `null` + a warning); omitted ⇒ the root node. Mutually exclusive with `content` |
 | `opts.content` | `() => ReactNode` | — | — | 自定义预览内容，塞进同一个右侧 dock；传它时不需要 `path` | Custom preview body rendered in the same dock; no `path` needed when set |
 | `opts.officeToPdf` | `OfficeToPdfFace` | — | — | Office 转 PDF 能力；缺失则该格式走「不支持」而不是报错 | Office→PDF capability; without it that format shows "unsupported" instead of erroring |
 | `opts.rootName` | `string` | — | — | 兜底显示名（路径匹配不出工作区时用） | Fallback display name, used when no workspace matches the path |
-| `pickWorkspaceFile(opts)` | `PickWorkspaceFileOptions => Promise<PickedFile>` | — | — | 锚定按钮弹出模态选文件，解析出 `{ path, isDir }` | Anchored modal picker that resolves `{ path, isDir }` |
+| `pickWorkspaceFile(opts)` | `PickWorkspaceFileOptions => Promise<PickedPath \| null>` | — | — | 锚定按钮弹出模态选文件，解析出 `{ path, isDir, workspaceRel?, workspace? }`；`path` 是**绝对路径** | Anchored modal picker resolving `{ path, isDir, workspaceRel?, workspace? }`; `path` is **absolute** |
 | `opts.anchor` | `HTMLElement` | 是 | — | 模态贴着它弹 | The modal anchors next to it |
-| `opts.filter` | `PickFilter` | — | — | 按扩展名过滤 `{ exts: ['md'] }`；`dirs: true` 则只允许选文件夹 | Filter by extension `{ exts: ['md'] }`; `dirs: true` restricts picking to folders |
+| `opts.filter` | `PickFilter` | — | — | `exts` 只要这些扩展名（目录仍可展开导航）；`dirs: true` 只允许选文件夹（文件不渲染） | `exts` limits files (folders still expand); `dirs: true` picks folders only (files hidden, plus a “Select this folder” action in the crumb bar) |

package/docs/help/integration.doc.ts

@@ -26,16 +26,21 @@ const useUtils = `import { formatDateTime, relativeFuture, formatBytes } from 'd
 formatDateTime(task.runAt, { seconds: true })   // 2026-10-18 09:30:05
 relativeFuture(task.runAt, Date.now())          // 3 分钟后（未来时间用这个）
 formatBytes(file.size)                          // 12 KB`
-const useExplorer = `import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+const useExplorer = `import { connectFs, openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { serveFsRoute } from 'dsh-plugin-core/host'
+import { FS_PATH } from './paths'   // 自己的常量，宿主与 client 共用
 
-// 从 ctx 取出这一小块（不要传整个 ctx）
-const workspaceFiles = ctx.remote.workspaceFiles
+// 宿主 apply：挂只读文件路由（列目录 / 读文件都在它上面，不限工作区）
+serveFsRoute(ctx, { path: FS_PATH })
+// client apply：接同一个常量（connectHost(ctx) 照旧负责工作区快照）
+connectFs({ path: FS_PATH })
 
-// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）
-openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path: 'docs/requirements.md' })
+// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）；绝对 / 相对都收
+openFilePreview({ mount: pageRowEl, path: '/abs/ws/docs/requirements.md' })
 
-// 让用户选文件：锚定按钮旁弹模态，Promise 返回 { path, isDir }（工作区相对路径）
-const picked = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor: btn, filter: { exts: ['ts'] } })`
+// 让用户选：锚定按钮旁弹模态，Promise 返回 { path: 绝对路径, isDir, workspaceRel?, workspace? }
+const picked = await pickWorkspaceFile({ anchor: btn, filter: { exts: ['ts'] } })
+const folder = await pickWorkspaceFile({ anchor: btn, filter: { dirs: true } })   // 只选文件夹`
 const useSession = `import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
 
 // sessions / uiConversation 同样从 ctx 取出（懒得取就用官方 client 服务）
@@ -45,7 +50,7 @@ if (view !== null) {
     sessionId, view,
     // 关闭必须释放 retain 引用
     onClose: () => { view.dispose(); setOpen(false) },
-    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path }),
+    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, path, sessionId }),
   })
 }`
 const cleanup = `kit.dispose()   // 撤掉 <style> 标签并清空登记域（插件卸载 / HMR）`
@@ -69,8 +74,8 @@ const doc: DocTopic = {
         { zh: '§2 用一个控件', en: '§2 Use a control' },
         { zh: '§3 用通用方法', en: '§3 Use helpers' },
         {
-          zh: '§4 接工作区浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行。`sessionId` 必须属于该工作区。',
-          en: '§4 Wire workspace browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. `sessionId` must belong to that workspace.',
+          zh: '§4 接文件浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行；数据面要在宿主 `serveFsRoute` + client `connectFs` 用同一个 path 常量接上，浏览本身不需要会话。',
+          en: '§4 Wire file browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. Wire the data face with the same path constant on both sides (`serveFsRoute` / `connectFs`) — browsing itself needs no session.',
         },
         {
           zh: '§5 接会话预览：`openSessionView` 返回 `null` 表示该会话不可解析；拿到 view 后交给 `SessionViewModal`，关闭时记得 `dispose()`。',

package/docs/help/integration.md

@@ -28,9 +28,9 @@
 
 > EN: §3 Use helpers
 
-§4 接工作区浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行。`sessionId` 必须属于该工作区。
+§4 接文件浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行；数据面要在宿主 `serveFsRoute` + client `connectFs` 用同一个 path 常量接上，浏览本身不需要会话。
 
-> EN: §4 Wire workspace browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. `sessionId` must belong to that workspace.
+> EN: §4 Wire file browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. Wire the data face with the same path constant on both sides (`serveFsRoute` / `connectFs`) — browsing itself needs no session.
 
 §5 接会话预览：`openSessionView` 返回 `null` 表示该会话不可解析；拿到 view 后交给 `SessionViewModal`，关闭时记得 `dispose()`。
 
@@ -78,16 +78,21 @@ formatBytes(file.size)                          // 12 KB
 ```
 
 ```tsx id="integration-use-explorer"
-import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { connectFs, openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+import { serveFsRoute } from 'dsh-plugin-core/host'
+import { FS_PATH } from './paths'   // 自己的常量，宿主与 client 共用
 
-// 从 ctx 取出这一小块（不要传整个 ctx）
-const workspaceFiles = ctx.remote.workspaceFiles
+// 宿主 apply：挂只读文件路由（列目录 / 读文件都在它上面，不限工作区）
+serveFsRoute(ctx, { path: FS_PATH })
+// client apply：接同一个常量（connectHost(ctx) 照旧负责工作区快照）
+connectFs({ path: FS_PATH })
 
-// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）
-openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path: 'docs/requirements.md' })
+// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）；绝对 / 相对都收
+openFilePreview({ mount: pageRowEl, path: '/abs/ws/docs/requirements.md' })
 
-// 让用户选文件：锚定按钮旁弹模态，Promise 返回 { path, isDir }（工作区相对路径）
-const picked = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor: btn, filter: { exts: ['ts'] } })
+// 让用户选：锚定按钮旁弹模态，Promise 返回 { path: 绝对路径, isDir, workspaceRel?, workspace? }
+const picked = await pickWorkspaceFile({ anchor: btn, filter: { exts: ['ts'] } })
+const folder = await pickWorkspaceFile({ anchor: btn, filter: { dirs: true } })   // 只选文件夹
 ```
 
 ```tsx id="integration-use-session"
@@ -100,7 +105,7 @@ if (view !== null) {
     sessionId, view,
     // 关闭必须释放 retain 引用
     onClose: () => { view.dispose(); setOpen(false) },
-    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path }),
+    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, path, sessionId }),
   })
 }
 ```

package/docs/requirements.md

@@ -247,7 +247,8 @@ dsh-plugin-core/
 | 文档 | README 接入指南 | ✅ 已完成 |
 
 **未做**（按重要性）：消费者插件接入 / 会话 UI 镜像 / 类名隔离 /
-设置页骨架（等第二个消费者）/ npm 发布流程。详见 README「还没做的事」。
+设置页骨架（等第二个消费者）/ npm 发布流程。落地进度一律以任务台账（task-ledger）为准，
+本文只记需求与已拍板的结论，不跟进度。
 
 > 说明：`dsh-plugin-core-demo` 作为真实插件已在宿主内跑通配置面板、侧栏入口、整页预览，
 > 已证明 core 在宿主里可用；上面「消费者插件接入」专指把 `dsh-task-dispatch-table` 等迁到 core、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-core",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "packageManager": "pnpm@12.3.4",
   "description": "Shared base for DSH plugins: design tokens, UI controls, utils, workspace explorer, session preview",
   "keywords": [