dsh-plugin-core 0.20.3 → 0.20.6

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/help/ui.doc.ts

@@ -848,8 +848,8 @@ const doc: DocTopic = {
           en: 'Panel height defaults to viewport height; in a fixed-height container the caller sets `--dshpc-dock-h`. Not supported: same-name duplicates, tab bars, auto-eviction — tab switching belongs in the consumer’s own panel content. (The collapsed ear is a standalone `fixed` overlay; the panel itself never floats.)',
         },
         {
-          zh: '占宽契约：已开栏宽之和（外加开着时给主区滚动条留的 1px 缝，可用 `--dshpc-dock-gap` 调）实时写进根元素 `--dshpc-page-inset-right`（拖拽逐帧更新，全关即移除），全屏遮罩据此让位；同页多个 dock 求和。',
-          en: 'Width contract: the sum of open widths plus a 1px scrollbar gutter while open (tunable via `--dshpc-dock-gap`) goes to `--dshpc-page-inset-right` on the root element (every frame while dragging, removed when all close), and full-screen masks yield to it; multiple docks on one page are summed.',
+          zh: '占宽契约：已开栏宽之和实时写进根元素 `--dshpc-page-inset-right`（拖拽逐帧更新，全关即移除），全屏遮罩据此让位；同页多个 dock 求和。滚动条与分隔线的 1px 缝隙不由 dock 让位（`--dshpc-dock-gap` 已删），由主区滚动容器自己的透明右边框提供。',
+          en: 'Width contract: the sum of open widths goes to `--dshpc-page-inset-right` on the root element (every frame while dragging, removed when all close), and full-screen masks yield to it; multiple docks on one page are summed. The 1px gap between the scrollbar and the divider is no longer dock-provided (`--dshpc-dock-gap` is gone) — the main area’s own scroll container supplies it with a transparent right border.',
         },
         {
           zh: '收起 / 展开：`dock.collapse(id)` 让面板退出布局（立刻不占宽）、在右侧出一只固定耳朵；`dock.expand(id)` 把耳朵收回、按记忆宽度还原；`dock.isCollapsed(id)`。耳朵是垂直居中的小图标页签（不放文字），开合带滑入 / 收拢动效；耳朵是独立浮层，与分栏不是一体；`close` 不留耳朵。',

package/docs/help/ui.md

@@ -724,9 +724,9 @@ h(SideSheet, {
 
 > EN: Panel height defaults to viewport height; in a fixed-height container the caller sets `--dshpc-dock-h`. Not supported: same-name duplicates, tab bars, auto-eviction — tab switching belongs in the consumer’s own panel content. (The collapsed ear is a standalone `fixed` overlay; the panel itself never floats.)
 
-占宽契约：已开栏宽之和（外加开着时给主区滚动条留的 1px 缝，可用 `--dshpc-dock-gap` 调）实时写进根元素 `--dshpc-page-inset-right`（拖拽逐帧更新，全关即移除），全屏遮罩据此让位；同页多个 dock 求和。
+占宽契约：已开栏宽之和实时写进根元素 `--dshpc-page-inset-right`（拖拽逐帧更新，全关即移除），全屏遮罩据此让位；同页多个 dock 求和。滚动条与分隔线的 1px 缝隙不由 dock 让位（`--dshpc-dock-gap` 已删），由主区滚动容器自己的透明右边框提供。
 
-> EN: Width contract: the sum of open widths plus a 1px scrollbar gutter while open (tunable via `--dshpc-dock-gap`) goes to `--dshpc-page-inset-right` on the root element (every frame while dragging, removed when all close), and full-screen masks yield to it; multiple docks on one page are summed.
+> EN: Width contract: the sum of open widths goes to `--dshpc-page-inset-right` on the root element (every frame while dragging, removed when all close), and full-screen masks yield to it; multiple docks on one page are summed. The 1px gap between the scrollbar and the divider is no longer dock-provided (`--dshpc-dock-gap` is gone) — the main area’s own scroll container supplies it with a transparent right border.
 
 收起 / 展开：`dock.collapse(id)` 让面板退出布局（立刻不占宽）、在右侧出一只固定耳朵；`dock.expand(id)` 把耳朵收回、按记忆宽度还原；`dock.isCollapsed(id)`。耳朵是垂直居中的小图标页签（不放文字），开合带滑入 / 收拢动效；耳朵是独立浮层，与分栏不是一体；`close` 不留耳朵。
 

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.3",
+  "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": [