dsh-plugin-core 0.2.14 → 0.4.0

package/docs/design/structure.md

@@ -38,16 +38,18 @@ dsh-plugin-core/
 ├── ui/                  ② 基础控件 —— 纯零件 + 可复用基础能力（依赖 design）
 │   ├── official.ts         ✅ 全仓唯一 import 官方 primitives 的入口（L1）
 │   ├── 表单                ✅ Input / NumberInput / PrefixedInput / Textarea /
-│   │                          Checkbox / Segmented / Picker（下拉选择）
+│   │                          Checkbox / Segmented / Picker（下拉选择）/
+│   │                          DateTimePicker（日期时间：单值 / 时间段 × 精度到秒）
 │   ├── 动作                ✅ Button / IconButton
-│   ├── 反馈                ✅ Modal / Toast / EmptyState / ErrorBoundary
+│   ├── 反馈                ✅ Modal / Toast
 │   │   └── Loading         ⚪ 暂缓
 │   ├── 展示                ✅ Card / StripCard / Chip / MarqueeText /
 │   │                          SectionHead / FieldHint / LiveText / BackToTop
-│   ├── 选择                ✅ WorkspacePicker（选工作区）/ FilePicker（选文件）
-│   │                          数据由调用方给，只是选择器，不含浏览逻辑
-│   └── 布局                🟡 SidebarLayout / SplitPane（侧边栏 + 拖拽拉栏）
-│                              现在只有底层函数 resizer（startResizeLayoutWidth），组件待补
+│   ├── 选择                ✅ WorkspacePicker（选工作区，自取宿主快照）
+│   │                          通用 Picker 是纯零件；领域选择器经 connectHost 自取数（2026-10-20）
+│   └── 布局                ✅ PanelDock / createPanelDock（可停靠分栏：多面板 + 拖拽拉栏）
+│                              组名 = 窗口一对一、同名覆盖、默认上限 3 超限拒绝；
+│                              不做 tab 切换 / 自动淘汰 / 浮动层（用户 2026-10-20 定案）
 │
 ├── utils/               ③ 纯方法 —— 零 React / 零 DOM（谁都能用，它不依赖谁）
 │   ├── date                ✅ 日期 / 相对时间 / 时间区间
@@ -55,13 +57,14 @@ dsh-plugin-core/
 │   ├── string              ⚪ 暂缓
 │   ├── number              ⚪ 暂缓（注：formatBytes 已被 adv.session 附件卡使用，只「不对外承诺」，不删）
 │   ├── http                ⚪ 暂缓
-│   └── path                🟡 纯路径方法（无 UI）：joinPath / parentOf / crumbsOf / extOf / mimeOf
-│                              现在散在 explorer/types.ts，建议迁入这里（待你确认）
+│   └── path                ✅ 纯路径方法（无 UI）：joinPath / parentOf / crumbsOf / extOf / mimeOf
+│                              （已从 explorer/types.ts 迁入，2026-10-20）
 │
 ├── adv.explorer/        ④ 高级空间①：文件浏览（依赖 ui + utils）
-│   └── ExplorerPanel       ✅ 成品：目录树 + 面包屑 + 文件预览
-│                              （内部组合 ui 的侧栏/拉栏与 Picker；不对外暴露它们）
-│                              `previewKindOf`（决定用哪种预览器）是业务判断，留内部
+│   ├── FileBrowser        ✅ 面板本体：面包屑（▾ 选层）+ 内联展开树 + 预览（+ picker 形态）
+│   ├── open               ✅ 两命令式能力：openFilePreview（侧边栏预览）/ pickWorkspaceFile（锚定弹窗选文件）
+│   ├── types              ✅ 纯逻辑层（零 React / 零官方件）：预览分发 / 错误码 / 根反推 / 过滤
+│   └── preview            ✅ 预览体家族：md / 代码 / HTML / PDF / Office / 图片
 │
 └── adv.session/         ⑤ 高级空间②：会话记录（依赖 ui + utils）
     └── SessionPreview      ✅ 成品：ui.Modal 承载会话消息（modal / sidebar / page）
@@ -72,7 +75,7 @@ dsh-plugin-core/
 | 成品 | 用到的 `ui` 基础能力 | 定制了什么 |
 |---|---|---|
 | `adv.session` · `SessionPreview` | `Modal` | 把会话消息放进弹窗 |
-| `adv.explorer` · `ExplorerPanel` | `SidebarLayout` / `SplitPane` + `WorkspacePicker` / `FilePicker` | 目录树 + 面包屑 + 文件预览 |
+| `adv.explorer` · `FileBrowser` | `Button`（面包屑 ghost / 行尾 outline）/ `IconButton` / `Segmented` / `MarqueeText` / `PanelDock`（浏览态外壳与拖宽）+ 官方件（`FileTypeIcon` / `MarkdownText` / `CodeBlock`，经 `ui/official`） | 面包屑 + 内联展开树 + 预览体家族 + 两命令式能力 |
 
 `adv.*` 只做「拼装 + 业务定制」，不重新实现按钮 / 下拉 / 弹窗 / 侧栏。
 
@@ -105,14 +108,14 @@ utils（谁都不依赖，谁都可以用）
 │     （只摆值，不点交互）
 │
 ├─ ② 基础控件
-│   ├─ 表单    Input / NumberInput / PrefixedInput / Textarea / Checkbox / Segmented / Picker
+│   ├─ 表单    Input / NumberInput / PrefixedInput / Textarea / Checkbox / Segmented / Picker / DateTimePicker
 │   ├─ 动作    Button / IconButton
-│   ├─ 反馈    Modal / Toast / EmptyState / ErrorBoundary
+│   ├─ 反馈    Modal / Toast
 │   ├─ 展示    Card / StripCard / Chip / MarqueeText / SectionHead / FieldHint / LiveText / BackToTop
-│   └─ 布局    侧边栏 / 拉栏
+│   └─ 布局    PanelDock / 拉栏
 │
 ├─ ③ 高级空间
-│   ├─ 文件浏览   ExplorerPanel（点文件夹、点文件看预览）
+│   ├─ 文件浏览   FileBrowser + openFilePreview / pickWorkspaceFile（点文件夹、点文件看预览）
 │   └─ 会话预览   SessionPreview（弹窗里放会话记录）
 │
 └─ ④ 工具方法
@@ -139,12 +142,12 @@ utils（谁都不依赖，谁都可以用）
 - **目录改名**：`src/explorer` → `src/adv.explorer`、`src/session` → `src/adv.session`；同步改
   `package.json` 的 `exports`、各 `index.ts`、`packages/demo` 的 import、`docs/design/architecture.md` 的树。
   代码现在仍是旧名。
-- **收窄导出**：`adv.explorer` 只暴露 `ExplorerPanel`；`WorkspacePicker` / `FilePicker` 留在 `ui`（已在那）。
-- **路径方法归基础**：`joinPath` / `parentOf` / `crumbsOf` / `extOf` / `mimeOf` 是纯方法（无 UI），
-  建议迁入 `utils/`（`path` 域）；`previewKindOf`（选哪种预览器）是文件浏览的业务判断，留在 `ExplorerPanel` 内部。
-  待你确认。
-- **补基础组件**：`ui` 目前只有拖拽函数 `resizer`（`startResizeLayoutWidth`），需补 `SidebarLayout` / `SplitPane`
-  组件，供 `ExplorerPanel` 组合使用。
+- ~~**收窄导出**：`adv.explorer` 只暴露 `ExplorerPanel`~~ → 已定（2026-10-20）：暴露 `FileBrowser` 面板 +
+  `openFilePreview` / `pickWorkspaceFile` 两命令式能力 + 纯逻辑层；`WorkspacePicker` 留在 `ui`。
+- ~~**路径方法归基础**~~ → **已落地**（2026-10-20）：`joinPath` / `parentOf` / `crumbsOf` / `extOf` / `mimeOf`
+  在 `utils/path`；`previewInfoOf` 等业务判断留 `explorer/types.ts`（纯逻辑层，node 单测直接引）。
+- ~~**补基础组件**：`ui` 需补 `SidebarLayout` / `SplitPane`~~ → **已落地为 `PanelDock`**（2026-10-20），
+  `resizer` 保留为它的底层函数。
 - **暂缓项**：`utils/string`、`utils/number`、`utils/http`、`ui/feedback/Loading` —— 只标注，未删代码。
 - **库里没有的**：
   - 表格 Table —— 待真实需求再定，不预造；

package/docs/design/style.md

@@ -1,77 +1,51 @@
-# 样式规范
+# 样式规范（本仓内部）
 
-token 口径、注入器、明暗判据、定制边界。规则依据见 `docs/design/architecture.md` §样式注入。
+> EN: Style conventions (internal)
+
+使用侧内容（token 清单、明暗判据、定制边界）在帮助文档区 `docs/help/`。
+本文件只留**改动本仓样式时要守的东西**。
+EN: The caller-facing material (token inventory, dark predicate, customization surface) lives in `docs/help/`.
+What stays here is what you must honour when **changing styles in this repo**.
 
 ## 为什么样式只能运行时注入
 
+> EN: Why styles can only be injected at runtime
+
 客户端产物是 `window.__ModuleLoader__.load({ id, factory })` 的 CJS 闭包，
 `import './x.css'` 只会产出独立 css 资源、**内核不加载它** ⇒ CSS 只能以 TS 字符串在运行时打进 `<style>`。
 
-## 前缀规则
-
-变量与类名**全生态统一 `dshpc`**，代码里直接写死，不存在按插件替换这回事。
-
-| 名称 | 规则 |
-|---|---|
-| 变量 `--dshpc-*` | 直接使用；token 定义与控件样式都写这个前缀 |
-| 类名 `dshpc-*` | 必须与控件里硬编码的 className 逐字一致，改一处就得全改 |
-
-> **已知限制**：两个插件若引的 core 版本不同，`.dshpc-*` 规则会互相覆盖（同版本内容一致、无害）。
-> 隔离靠 style 标签 id（`createStyleKit({ id })`）。
-
-## 明暗判据（硬约束）
-
-```ts
-export const DARK_THEME_SELECTOR = 'body[data-ds-dark-theme]'
-```
-
-- 由**宿主启动脚本** `toggleAttribute` 写入 body，反映的是**用户在客户端里的选择**。
-- **禁止用 `prefers-color-scheme`**：它跟的是系统，不是用户在宿主里的选择。
-  两者会分叉——系统亮色 + 用户在 DSH 里选暗色时，跟 `prefers-color-scheme` 会显示成亮色，与宿主不一致。
-
-## token 清单
-
-token 原文提取自 `dsh-task-dispatch-table/src/client/ui/tokens.ts`，含深色覆盖段。
-分类（命名口径保持原样，只换前缀）：
-
-| 类别 | 例 |
-|---|---|
-| 前景 / 背景面 | `--dshpc-fg` `--dshpc-fg-3` `--dshpc-fg-4` `--dshpc-surface-1` `--dshpc-surface-2` `--dshpc-surface-sunken` `--dshpc-surface-menu` `--dshpc-surface-base` |
-| 边框 | `--dshpc-border` `--dshpc-border-faint` |
-| 间距 | `--dshpc-space-1` … `--dshpc-space-3` |
-| 字号 / 行高 | `--dshpc-font-sm` `--dshpc-font-lg` `--dshpc-line-sm` `--dshpc-line-md` `--dshpc-line-lg` |
-| 语义色 | `--dshpc-business` `--dshpc-success` `--dshpc-danger` `--dshpc-warning` `--dshpc-link` |
-| 语义面 | `--dshpc-open-bg` `--dshpc-open-bg-soft` `--dshpc-chip-bg` `--dshpc-chip-bg-hover` |
-| 代码 | `--dshpc-code-surface` `--dshpc-code-font` |
-
-完整清单以 `src/design/tokens-css.ts` 为准（**真源在代码，不在这里抄第二份**）。
-消费方查某个变量叫什么：`kit.cssVar('fg')` 或直接 grep `tokens-css.ts`。
+EN: The client bundle is a CJS closure loaded by `window.__ModuleLoader__.load`, so `import './x.css'` produces a
+separate asset the kernel never loads — CSS must be injected at runtime as a TS string.
 
 ## 交互态颜色（hover / active）
 
-**实心控件不许用 `opacity` 表达 hover**（2026-10-19 用户点名：「黑色和红色的按钮移上去变化太小，
-完全感觉不到颜色变了」）。压 10% opacity 与底色无关，几乎不可见。
+> EN: Interaction colors (hover / active)
 
+**实心控件不用 `opacity` 表达 hover**：压 10% opacity 与底色无关，几乎不可见。
 改用 token 层的**派生色**（`--dshpc-{accent,danger,success,warning,business}-hover / -active`）：
 
+EN: Solid controls never use `opacity` for hover — it barely reads against the base color. Use the derived
+token colors instead.
+
 | 主题 | 黑底（accent） | 红 / 绿 / 黄 / 蓝底 |
 |---|---|---|
 | 亮色 | 掺白提亮（黑 → 灰） | 掺黑压深（红 → 暗红） |
 | 暗色 | 掺黑压深（近白 → 灰） | 掺白提亮 |
 
 - 幅度 22% / 36%（hover / active），两种主题下都「一眼看出变了」。
-- 混色对象写成**固定中性色字面量** `#fff` / `#000`，不依赖宿主 `--dsw-static-neutral-*` 是否存在。
+- 混色对象写成**固定中性色字面量** `#fff` / `#000`，不依赖宿主静态中性色是否存在。
 - 旧内核不认 `color-mix` 时整条声明作废 ⇒ 回落该档原色（仍有基本可用性，只是没有 hover 反馈）。
 
+EN: 22% / 36% for hover / active. Mix against literal `#fff` / `#000`, not host-provided neutrals. If an old
+core ignores `color-mix`, the declaration drops and falls back to the base tier.
+
 ## 三条硬规矩
 
+> EN: Three hard rules
+
 1. 不许再有第二处 `document.createElement('style')` —— 一律走 kit。
 2. 不许再出现第二套 style 标签 id —— 一个插件一套 kit。
 3. 域内的规则只能消费 `var(--dshpc-*)`，颜色 / 尺寸 / 字号一律来自 token 层，不写死值。
 
-## 定制边界
-
-- **换肤**：给同一批变量名赋新值（在插件自己的样式域里覆盖），不需要 fork。
-- **加域**：`kit.registerStyle('widget', css)`，同一域重复登记 = 覆盖。
-- **`tokens` 域恒排最前**（变量定义必须先于消费它的规则），kit 内部已保证。
-- 皮肤写在调用方自己的样式域里；组件只认 token，不认调用方的具体颜色。
+EN: No second `document.createElement('style')` — always go through the kit. No second style tag id — one kit
+per plugin. Rules inside a domain consume `var(--dshpc-*)` only; never hard-code colors, sizes or fonts.

package/docs/help/design.doc.ts

@@ -0,0 +1,112 @@
+// design 子包的使用帮助 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
+import type { DocTopic } from '../design/doc-format.js'
+
+const minimal = `import { createStyleKit } from 'dsh-plugin-core/design'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
+kit.applyStyle('tokens', kit.tokensCss)
+// 之后自己的样式域：
+kit.applyStyle('widget', '.widget{color:var(--dshpc-fg)}')`
+
+const doc: DocTopic = {
+  title: { zh: 'design —— 样式层', en: 'design — styling layer' },
+  exports: ['createStyleKit', 'DARK_THEME_SELECTOR', 'StyleKit', 'StyleKitOptions'],
+  sections: [
+    {
+      id: 'foundation',
+      heading: { zh: '概览', en: 'Overview' },
+      prose: [
+        {
+          zh: '零 React、无组件。装的是「值 + 注入机制」：token 变量表、注入器工厂、主题判据。',
+          en: 'Zero React, no components. It ships values plus an injection mechanism: the token variable table, the injector factory, and the theme predicate.',
+        },
+        {
+          zh: '只想统一配色/尺寸但自己写组件的插件，只引这一个就够。',
+          en: 'A plugin that wants unified color/size but writes its own components needs only this subpath.',
+        },
+      ],
+    },
+    {
+      id: 'foundation-exports',
+      heading: { zh: '导出', en: 'Exports' },
+      api: [
+        {
+          id: 'design-exports',
+          rows: [
+            { name: 'createStyleKit(options)', type: '', def: '', desc: { zh: '领一套本插件专属的样式设施（必调）', en: 'Acquire a plugin-scoped styling kit (must call)' } },
+            { name: 'DARK_THEME_SELECTOR', type: '', def: '', desc: { zh: '明暗判据选择器常量 `body[data-ds-dark-theme]`', en: 'Dark-mode predicate selector constant `body[data-ds-dark-theme]`' } },
+            { name: 'type StyleKit / StyleKitOptions', type: '', def: '', desc: { zh: '类型', en: 'Types' } },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'foundation-createStyleKit',
+      heading: { zh: 'createStyleKit(options)', en: 'createStyleKit(options)' },
+      api: [
+        {
+          id: 'createStyleKit-params',
+          rows: [
+            {
+              name: 'id',
+              type: 'string',
+              required: '是',
+              def: '—',
+              desc: {
+                zh: '`<style>` 标签 id，多插件同页靠它互不覆盖，必须插件内唯一。空串抛错',
+                en: 'The `<style>` tag id; on a page with multiple plugins it prevents overlaps and must be unique within the plugin. Empty string throws',
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'foundation-styleKit',
+      heading: { zh: '返回的 StyleKit', en: 'Returned StyleKit' },
+      api: [
+        {
+          id: 'styleKit-members',
+          rows: [
+            { name: 'id', type: 'string', def: '—', desc: { zh: '回显', en: 'Echoed back' } },
+            { name: 'tokensCss', type: 'string', def: '—', desc: { zh: '已替换前缀的 token CSS 文本', en: 'Token CSS text with the prefix already substituted' } },
+            { name: 'cssVar(name)', type: '(name: string) => string', def: '—', desc: { zh: '拼变量名：`cssVar(\'fg\')` ⇒ `--acme-fg`', en: 'Build a var name: `cssVar(\'fg\')` ⇒ `--acme-fg`' } },
+            { name: 'registerStyle(domain, css)', type: '(domain: string, css: string) => void', def: '—', desc: { zh: '登记一个域的 CSS；同名重复登记 = 覆盖', en: 'Register a domain’s CSS; re-registering the same domain overwrites' } },
+            { name: 'ensureStyles()', type: '() => void', def: '—', desc: { zh: '确保标签已挂载且内容最新（幂等；无 document 静默跳过）', en: 'Ensure the tag is mounted and current (idempotent; silently skips without document)' } },
+            { name: 'applyStyle(domain, css)', type: '(domain: string, css: string) => void', def: '—', desc: { zh: '登记 + 立刻挂载', en: 'Register and mount immediately' } },
+            { name: 'dispose()', type: '() => void', def: '—', desc: { zh: '撤掉标签并清空登记域（插件卸载 / HMR 时用）', en: 'Remove the tag and clear registered domains (on plugin unload / HMR)' } },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'foundation-minimal',
+      heading: { zh: '最小可用', en: 'Minimal usage' },
+      code: [{ id: 'design-minimal', lang: 'ts', src: minimal }],
+    },
+    {
+      id: 'foundation-tokens',
+      heading: { zh: 'token 口径', en: 'Token conventions' },
+      prose: [
+        {
+          zh: 'token 覆盖颜色 / 尺寸 / 字号 / 层级，**含深色覆盖段**。取值一律走 `var(--dshpc-*)`，不在规则里写死颜色值。',
+          en: 'Tokens cover color / size / font-size / elevation, **including the dark-mode override block**. Always read values via `var(--dshpc-*)`, never hard-code colors in rules.',
+        },
+        { zh: '完整清单与命名口径：前景 / 背景 / 边框 / 间距 / 字号 / 语义色七类，`--dshpc-` 前缀，含深色覆盖段。', en: 'Full inventory and naming: seven families (foreground / surface / border / spacing / font / semantic color / semantic surface), all `--dshpc-` prefixed, with a dark-mode override block.' },
+      ],
+    },
+    {
+      id: 'foundation-customize',
+      heading: { zh: '定制边界', en: 'Customization boundary' },
+      prose: [
+        {
+          zh: 'token 的**前缀固定 `dshpc`**（不参数化、不按插件改名）；token 的**内容**（有哪些变量、值是什么）是本包定的审美标准，消费方通过覆盖变量值来适配，不要改本包源码。',
+          en: 'The token **prefix is fixed to `dshpc`** (not parameterized, not renamed per plugin); the token **content** (which variables exist, what values) is this package’s aesthetic standard — consumers adapt by overriding variable values, not by editing this package’s source.',
+        },
+        { zh: '要整套换肤：给同一批变量名赋新值即可，不需要 fork。', en: 'To reskin entirely: assign new values to the same variable names; no fork needed.' },
+      ],
+    },
+  ],
+}
+
+export default doc

package/docs/help/design.md

@@ -0,0 +1,88 @@
+<!-- 本文件由 scripts/gen-docs.mjs 自动生成，请勿手改；改对应的 .doc.ts 后重跑 node scripts/gen-docs.mjs -->
+
+# design —— 样式层
+
+> EN: design — styling layer
+
+导出：createStyleKit、DARK_THEME_SELECTOR、StyleKit、StyleKitOptions
+
+## 概览
+
+> EN: Overview
+
+零 React、无组件。装的是「值 + 注入机制」：token 变量表、注入器工厂、主题判据。
+
+> EN: Zero React, no components. It ships values plus an injection mechanism: the token variable table, the injector factory, and the theme predicate.
+
+只想统一配色/尺寸但自己写组件的插件，只引这一个就够。
+
+> EN: A plugin that wants unified color/size but writes its own components needs only this subpath.
+
+## 导出
+
+> EN: Exports
+
+| 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|
+| `createStyleKit(options)` | `` |  | 领一套本插件专属的样式设施（必调） | Acquire a plugin-scoped styling kit (must call) |
+| `DARK_THEME_SELECTOR` | `` |  | 明暗判据选择器常量 `body[data-ds-dark-theme]` | Dark-mode predicate selector constant `body[data-ds-dark-theme]` |
+| `type StyleKit / StyleKitOptions` | `` |  | 类型 | Types |
+
+## createStyleKit(options)
+
+> EN: createStyleKit(options)
+
+| 参数 | 类型 | 必填 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|---|
+| `id` | `string` | 是 | — | `<style>` 标签 id，多插件同页靠它互不覆盖，必须插件内唯一。空串抛错 | The `<style>` tag id; on a page with multiple plugins it prevents overlaps and must be unique within the plugin. Empty string throws |
+
+## 返回的 StyleKit
+
+> EN: Returned StyleKit
+
+| 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|
+| `id` | `string` | — | 回显 | Echoed back |
+| `tokensCss` | `string` | — | 已替换前缀的 token CSS 文本 | Token CSS text with the prefix already substituted |
+| `cssVar(name)` | `(name: string) => string` | — | 拼变量名：`cssVar('fg')` ⇒ `--acme-fg` | Build a var name: `cssVar('fg')` ⇒ `--acme-fg` |
+| `registerStyle(domain, css)` | `(domain: string, css: string) => void` | — | 登记一个域的 CSS；同名重复登记 = 覆盖 | Register a domain’s CSS; re-registering the same domain overwrites |
+| `ensureStyles()` | `() => void` | — | 确保标签已挂载且内容最新（幂等；无 document 静默跳过） | Ensure the tag is mounted and current (idempotent; silently skips without document) |
+| `applyStyle(domain, css)` | `(domain: string, css: string) => void` | — | 登记 + 立刻挂载 | Register and mount immediately |
+| `dispose()` | `() => void` | — | 撤掉标签并清空登记域（插件卸载 / HMR 时用） | Remove the tag and clear registered domains (on plugin unload / HMR) |
+
+## 最小可用
+
+> EN: Minimal usage
+
+```ts id="design-minimal"
+import { createStyleKit } from 'dsh-plugin-core/design'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
+kit.applyStyle('tokens', kit.tokensCss)
+// 之后自己的样式域：
+kit.applyStyle('widget', '.widget{color:var(--dshpc-fg)}')
+```
+
+## token 口径
+
+> EN: Token conventions
+
+token 覆盖颜色 / 尺寸 / 字号 / 层级，**含深色覆盖段**。取值一律走 `var(--dshpc-*)`，不在规则里写死颜色值。
+
+> EN: Tokens cover color / size / font-size / elevation, **including the dark-mode override block**. Always read values via `var(--dshpc-*)`, never hard-code colors in rules.
+
+完整清单与命名口径：前景 / 背景 / 边框 / 间距 / 字号 / 语义色七类，`--dshpc-` 前缀，含深色覆盖段。
+
+> EN: Full inventory and naming: seven families (foreground / surface / border / spacing / font / semantic color / semantic surface), all `--dshpc-` prefixed, with a dark-mode override block.
+
+## 定制边界
+
+> EN: Customization boundary
+
+token 的**前缀固定 `dshpc`**（不参数化、不按插件改名）；token 的**内容**（有哪些变量、值是什么）是本包定的审美标准，消费方通过覆盖变量值来适配，不要改本包源码。
+
+> EN: The token **prefix is fixed to `dshpc`** (not parameterized, not renamed per plugin); the token **content** (which variables exist, what values) is this package’s aesthetic standard — consumers adapt by overriding variable values, not by editing this package’s source.
+
+要整套换肤：给同一批变量名赋新值即可，不需要 fork。
+
+> EN: To reskin entirely: assign new values to the same variable names; no fork needed.

package/docs/help/explorer.doc.ts

@@ -0,0 +1,136 @@
+// explorer 子包的使用帮助 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
+import type { DocTopic } from '../design/doc-format.js'
+
+const explorerUsage = `import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+
+// 右侧分栏预览（占宽度、挤窄主区）
+openFilePreview({ mount, workspaceFiles, officeToPdf, sessionId, path, rootName })
+
+// path 传绝对路径时：按最长前缀匹配所属工作区，面包屑 / 目录树与 ▾「切工作区」自动可用
+openFilePreview({ mount, workspaceFiles, sessionId, path: '/abs/path.md' })
+// 要覆盖宿主快照才显式传 workspaceAnchors（带 path + sessionIds）
+openFilePreview({ mount, workspaceFiles, sessionId, path: '/abs/path.md', workspaceAnchors })
+
+// 锚定弹窗选文件（Promise 返回路径，不自己挂 dock）
+const r = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor, rootName })`
+
+const doc: DocTopic = {
+  title: { zh: 'explorer —— 工作区浏览', en: 'explorer — Workspace browsing' },
+  exports: ['openFilePreview', 'pickWorkspaceFile', 'FileBrowser', 'FilePreview'],
+  sections: [
+    {
+      id: 'explorer',
+      heading: { zh: '概览', en: 'Overview' },
+      prose: [
+        {
+          zh: '提供工作区文件浏览与选择，数据来自宿主提供的工作区文件快照。',
+          en: 'Workspace file browsing and picking, driven by the host-provided workspace file snapshot.',
+        },
+        {
+          zh: '浏览态停靠是布局成员（占宽度、挤窄主区），不要挂 `document.body` 再自己套 fixed。',
+          en: 'The browse dock is a layout member (takes width, narrows the main area); never mount it on `document.body` with your own fixed positioning.',
+        },
+      ],
+    },
+    {
+      id: 'explorer-install',
+      heading: { zh: '0. 装包', en: '0. Install' },
+      code: [{ id: 'explorer-install-code', lang: 'bash', src: 'pnpm add dsh-plugin-core' }],
+    },
+    {
+      id: 'explorer-usage',
+      heading: { zh: '1. 接入示例', en: '1. Usage' },
+      prose: [
+        {
+          zh: '从 ctx 取出工作区快照再传给能力接口，不要传整个 ctx。',
+          en: 'Pull the workspace snapshot out of ctx and hand it to the capability APIs; do not pass the whole ctx.',
+        },
+      ],
+      code: [{ id: 'explorer-usage-code', lang: 'tsx', src: explorerUsage }],
+    },
+    {
+      id: 'explorer-api',
+      heading: { zh: 'API', en: 'API' },
+      api: [
+        {
+          id: 'explorer-api-table',
+          rows: [
+            {
+              name: 'openFilePreview(opts)',
+              type: 'OpenFilePreviewOptions => FilePreviewHandle',
+              def: '—',
+              desc: {
+                zh: '在右侧分栏打开文件 / 文件夹预览，返回可关闭它的句柄。预览内容二选一：`path`（核心解析并渲染）或 `content`（由调用方给内容）',
+                en: '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)',
+              },
+            },
+            {
+              name: 'opts.mount',
+              type: 'HTMLElement',
+              def: '—',
+              required: '是',
+              desc: { zh: '页面里的 flex 行；预览靠它占宽而不是浮在页面上方', en: 'The page’s flex row; the preview takes width there instead of floating' },
+            },
+            {
+              name: 'opts.workspaceFiles',
+              type: 'WorkspaceFilesFace',
+              def: '—',
+              desc: { zh: '从 ctx 取出的工作区文件服务；传 `content` 时可省', en: 'Workspace file service taken from ctx; optional when passing `content`' },
+            },
+            {
+              name: 'opts.sessionId',
+              type: 'string',
+              def: '—',
+              desc: { zh: '该工作区的真实会话 id（服务是会话作用域的）；传 `content` 时可省', en: 'A real session id of that workspace (the service is session-scoped); optional when passing `content`' },
+            },
+            {
+              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`' },
+            },
+            {
+              name: 'opts.content',
+              type: '() => ReactNode',
+              def: '—',
+              desc: { zh: '自定义预览内容，塞进同一个右侧 dock；传它时不需要 `path`', en: 'Custom preview body rendered in the same dock; no `path` needed when set' },
+            },
+            {
+              name: 'opts.officeToPdf',
+              type: 'OfficeToPdfFace',
+              def: '—',
+              desc: { zh: 'Office 转 PDF 能力；缺失则该格式走「不支持」而不是报错', en: 'Office→PDF capability; without it that format shows "unsupported" instead of erroring' },
+            },
+            {
+              name: 'opts.rootName',
+              type: 'string',
+              def: '—',
+              desc: { zh: '兜底显示名（路径匹配不出工作区时用）', en: 'Fallback display name, used when no workspace matches the path' },
+            },
+            {
+              name: 'pickWorkspaceFile(opts)',
+              type: 'PickWorkspaceFileOptions => Promise<PickedFile>',
+              def: '—',
+              desc: { zh: '锚定按钮弹出模态选文件，解析出 `{ path, isDir }`', en: 'Anchored modal picker that resolves `{ path, isDir }`' },
+            },
+            {
+              name: 'opts.anchor',
+              type: 'HTMLElement',
+              def: '—',
+              required: '是',
+              desc: { zh: '模态贴着它弹', en: 'The modal anchors next to it' },
+            },
+            {
+              name: 'opts.filter',
+              type: 'PickFilter',
+              def: '—',
+              desc: { zh: '按扩展名过滤 `{ exts: [\'md\'] }`；`dirs: true` 则只允许选文件夹', en: 'Filter by extension `{ exts: [\'md\'] }`; `dirs: true` restricts picking to folders' },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}
+
+export default doc

package/docs/help/explorer.md

@@ -0,0 +1,68 @@
+<!-- 本文件由 scripts/gen-docs.mjs 自动生成，请勿手改；改对应的 .doc.ts 后重跑 node scripts/gen-docs.mjs -->
+
+# explorer —— 工作区浏览
+
+> EN: explorer — Workspace browsing
+
+导出：openFilePreview、pickWorkspaceFile、FileBrowser、FilePreview
+
+## 概览
+
+> EN: Overview
+
+提供工作区文件浏览与选择，数据来自宿主提供的工作区文件快照。
+
+> EN: Workspace file browsing and picking, driven by the host-provided workspace file snapshot.
+
+浏览态停靠是布局成员（占宽度、挤窄主区），不要挂 `document.body` 再自己套 fixed。
+
+> EN: The browse dock is a layout member (takes width, narrows the main area); never mount it on `document.body` with your own fixed positioning.
+
+## 0. 装包
+
+> EN: 0. Install
+
+```bash id="explorer-install-code"
+pnpm add dsh-plugin-core
+```
+
+## 1. 接入示例
+
+> EN: 1. Usage
+
+从 ctx 取出工作区快照再传给能力接口，不要传整个 ctx。
+
+> EN: Pull the workspace snapshot out of ctx and hand it to the capability APIs; do not pass the whole ctx.
+
+```tsx id="explorer-usage-code"
+import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+
+// 右侧分栏预览（占宽度、挤窄主区）
+openFilePreview({ mount, workspaceFiles, officeToPdf, sessionId, path, rootName })
+
+// path 传绝对路径时：按最长前缀匹配所属工作区，面包屑 / 目录树与 ▾「切工作区」自动可用
+openFilePreview({ mount, workspaceFiles, sessionId, path: '/abs/path.md' })
+// 要覆盖宿主快照才显式传 workspaceAnchors（带 path + sessionIds）
+openFilePreview({ mount, workspaceFiles, sessionId, path: '/abs/path.md', workspaceAnchors })
+
+// 锚定弹窗选文件（Promise 返回路径，不自己挂 dock）
+const r = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor, rootName })
+```
+
+## API
+
+> EN: API
+
+| 参数 | 类型 | 必填 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|---|
+| `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 行；预览靠它占宽而不是浮在页面上方 | The page’s flex row; the preview takes width there instead of floating |
+| `opts.workspaceFiles` | `WorkspaceFilesFace` | — | — | 从 ctx 取出的工作区文件服务；传 `content` 时可省 | Workspace file service taken from ctx; optional when passing `content` |
+| `opts.sessionId` | `string` | — | — | 该工作区的真实会话 id（服务是会话作用域的）；传 `content` 时可省 | A real session id of that workspace (the service is session-scoped); 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.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 }` |
+| `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 |