dsh-plugin-core 0.2.14 → 0.3.0

package/docs/requirements.md

@@ -48,11 +48,16 @@ dsh-plugin-core/
 - 零件：Button / Input 家族 / Textarea / Checkbox / Segmented / 下拉框 / 搜索框 / 滑轨 /
   MarqueeText / LiveText / Field（含错误提示）/ resizer / DateTime / TimeRange
 - 选择器：`Picker`（通用：单选/多选/上限/搜索/分组/空态/降级）、`ModelPicker`、
-  `WorkspacePicker`（选工作区）、`FilePicker`（选文件）
+  `WorkspacePicker`（选工作区）；`FilePicker` 已删（2026-10-20 用户：文件选择框没有用）
+- 日期时间：`DateTimePicker`（2026-10-24 新增：单值 / 时间段 × 精度 day/hour/minute/second；
+  数据恒完整本地 ISO 到毫秒、**显示只到精度**；起始端 floor、结束端 ceil）
 - 「统一某类元素」的控件：`SectionHead` 等
-- 反馈件：`Modal` / `Loading` / `toast` / 空态 / 错误边界
-- 布局基础：`SidebarLayout` / `SplitPane`（侧栏 + 拖拽拉栏；现只有 `resizer` 函数，组件待补）
-- **纯零件，不自己取数** —— 数据由调用方传入
+- 反馈件：`Modal` / `Loading` / `toast` / 空态
+- 布局基础：`PanelDock` / `DockPanel` / `createPanelDock`（**可停靠分栏容器**：多面板并存、按组名寻址、拖拽拉栏、宽度记忆；2026-10-20 拍板用此名，替代早先的 `SidebarLayout` / `SplitPane`）。只做右侧；组名与窗口一对一；默认上限 3，超限拒绝新开；不做 tab 切换 / 自动淘汰 / 浮动层 / 多份同名。**结构照成熟库口径写 children，`open/close` 只传 id，不把页面树塞进调用参数**
+- **通用控件是纯零件，数据由调用方传入**；**领域选择器例外**（2026-10-20 用户拍板反转）：
+  `ModelPicker` / `WorkspacePicker` 是「现成的包」，接线后**自己取数自己显示**，消费方不再拿数组传 props。
+  接线两处、共用同一 path 常量：宿主 `serveModelCatalog(ctx,{path})`（`llm.listModels` 挂只读路由，
+  client 侧 remote 拿不到模型列表）+ client `connectHost(ctx,{modelsPath})`（工作区走官方 `workspaces` 快照）
 
 ### 2.3 utils
 
@@ -62,8 +67,9 @@ dsh-plugin-core/
 
 ### 2.4 adv.explorer
 
-- `ExplorerPanel`：文件浏览成品（目录树 + 面包屑 + 文件预览），内部组合 `ui` 的侧栏/拉栏与 Picker
-- 选工作区 / 选文件（`WorkspacePicker` / `FilePicker`）在 `ui`，不在这里
+- `FileBrowser` 面板 + 两命令式能力：`openFilePreview`（侧边栏预览，外壳 = 核心 `PanelDock`，2026-10-21 拍板不许自绘外壳 / 拖拽条）/ `pickWorkspaceFile`（锚定弹窗选文件，Promise 返回工作区相对路径），2026-10-20 移植自重做
+- 控件纪律（2026-10-21）：核心有的控件一律核心（`Button` ghost 面包屑 / `IconButton` / `Segmented` / `MarqueeText` / `PanelDock`）；核心没有的那一项（▾ 选层浮层）严格按兄弟项目度量照抄
+- 选工作区（`WorkspacePicker`）在 `ui`，不在这里；`FilePicker` 已删（2026-10-20）
 
 ### 2.5 adv.session
 
@@ -129,15 +135,25 @@ dsh-plugin-core/
   （`WorkspaceFilesFace` / `source` 这类最小接口）
 - 好处：宿主 breaking 时改的是插件「取出那一小块」的一行，包不用动；包也能用假实现做单测
 
+### 5.6 第三方依赖（**非**绝对禁止）
+
+> **不是「绝对不允许引第三方包」。默认优先用官方件（`@deepseek-ai/dsh-client-ui-primitives`）；当某个外部包明显比我们自己手搓的实现更好（更成熟 / 更稳 / 更省事 / 观感更好）时，可以引入——但必须先向用户提建议并说明理由，用户明确拍板后才可引入。**
+
+- **引入前提**：该能力确实值得（如 toast 这类成熟库、文件预览要的解释器），自研没有性价比。
+- **引入方式**：作为 core 的**内部依赖封装**，对外只暴露 core 自己的 API（如 `showToast`），**不 re-export 第三方包**，使消费者无法直接引用第三方、保持单点管控。
+- **引入后必须真机验证**：在真实 DSH profile 加载，确认渲染 / 暗色跟随 `body[data-ds-dark-theme]` / 回调 / 与宿主层级无冲突。
+- **仍硬禁止**（与「能否引第三方」是两条独立规则，本条不动）：把 `react` / `react-dom` / 官方 `@deepseek-ai/*` 打进包（见 §5.1，会产生第二份 React 实例、Node 下 import 崩）。这条 `external + optional peer` 是宿主运行时决定的。
+
 ## 6. 关键接口约定
 
 | 位置 | 约定 |
 |---|---|
 | design | `createStyleKit({ id })` → `{ registerStyle, ensureStyles, applyStyle }` |
-| ui / ModelPicker | `variant: 'cascade' \| 'flat'`（级联：先厂商后模型 / 平铺：一个下拉列全部）；数据统一为 `groups: [{ value, label, options }]`，一份数据两种渲染。**禁止用数字或无意义名** |
-| ui / Picker | `mode: 'single' \| 'multiple'`、`max`、分组、搜索、空态、降级 |
-| explorer | `WorkspaceFilesFace` 由插件注入（`list` / `stat` / `read` 最小面），组件不抓宿主全局 |
-| explorer / WorkspacePicker | `WorkspacePicker({ workspaces, mode, max, onChange })` —— 数据调用方给（工作区列表是 host 侧 `ctx.workspaceRegistry.list()` 取的，要经插件私有通道送到 client，**组件自己取不到**） |
+| ui / ModelPicker | `variant: 'grouped' \| 'cascade'`（分组：一个下拉、完全独立 / 联动：供应商与模型两个下拉联动；2026-10-20 用户拍板两形态都要）；**两种形态 onChange 都发最终模型 value**；「默认模型」选项默认提供（`allowDefault:false` 关），选中发 `''`。默认读 connectHost 喂入的真实目录，`groups` 仅作覆盖。**禁止用数字或无意义名** |
+| ui / Picker | `mode: 'single' \| 'multiple'`、`max`（到上限已选项仍可反选）、`searchable`（搜索框开关）、`icon`（触发器前置 icon）、选项级 `icon`、`hint`（问号提示内置）、分组、空态、降级 |
+| ui / DateTimePicker | `mode: 'single' \| 'range'`、`precision: 'day' \| 'hour' \| 'minute' \| 'second'`（同时管弹层步进、显示截断与默认宽度）；single 传 `string \| null`、range 传 `[start, end] \| null`（本地 ISO 到毫秒）；草稿态「确定」才 onChange，没选日期不传数据；起端补零 / 止端补满（day ⇒ 止 `23:59:59.999`） |
+| explorer | `WorkspaceFilesFace` 由插件注入（`list` / `stat` / `read` 最小面），组件不抓宿主全局；对外 = 两命令式能力 `openFilePreview`（侧边栏预览）+ `pickWorkspaceFile`（Promise 选文件，回传工作区相对路径），共用同一 `FileBrowser` 面板（2026-10-20 拍板） |
+| explorer / WorkspacePicker | `WorkspacePicker({ mode, max, onChange, allowDefault, defaultLabel, … })` —— **无数据参数**：connectHost 接线后自动订官方 `workspaces` 服务快照，选中值为 `workspaceId`；「所有工作区」默认项默认提供、选中发 `''`（2026-10-20） |
 | session | `SessionPreview({ sessionId, source, variant })` —— `source` = 取数能力接口（会话预览内部有交互：传输文件等，光有静态消息流不够） |
 
 ## 7. 分期与任务切分
@@ -147,14 +163,19 @@ dsh-plugin-core/
 | 期 | 内容 | 状态 |
 |---|---|---|
 | 骨架 | package.json exports / tsconfig / 构建出 dist | ✅ 已完成（`tsc` 出 ESM + d.ts，不走 tsdown） |
-| v1 | `design` + `utils` + `ui` | ✅ 已完成（零件 + Picker / ModelPicker + Modal / toast / 空态 / 错误边界） |
+| v1 | `design` + `utils` + `ui` | ✅ 已完成（零件 + Picker / ModelPicker + Modal / toast / 空态） |
 | v2 | `explorer`（用户拍板要抽） | ✅ 已完成（浏览面板 + 预览；**选择器后移至 ui**，见 §2.4） |
+| v2+ | `explorer` 重做（2026-10-20） | ✅ 已完成（FileBrowser 面板 + `openFilePreview` / `pickWorkspaceFile` 两能力 + 全量预览：md / 代码高亮 / HTML / PDF / Office；官方件经 `./ui/official` 子路径） |
 | v3 | `session` | ⚠️ **半完成**：契约与三种承载已好，**官方会话 UI 镜像未搬**（只做最简渲染） |
 | 文档 | README 接入指南 | ✅ 已完成 |
 
-**未做**（按重要性）：真实插件接入验证 / 会话 UI 镜像 / 代码高亮与 PDF 预览 / 类名隔离 /
+**未做**（按重要性）：消费者插件接入 / 会话 UI 镜像 / 类名隔离 /
 设置页骨架（等第二个消费者）/ npm 发布流程。详见 README「还没做的事」。
 
+> 说明：`dsh-plugin-core-demo` 作为真实插件已在宿主内跑通配置面板、侧栏入口、整页预览，
+> 已证明 core 在宿主里可用；上面「消费者插件接入」专指把 `dsh-task-dispatch-table` 等迁到 core、
+> 删掉它们各自维护的副本——那是另一桩事，不在本轮范围。
+
 ## 8. 验收口径
 
 - 每个子包：构建通过 + 类型检查通过 + 一个 smoke 自检（新逻辑必留）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-core",
-  "version": "0.2.14",
+  "version": "0.3.0",
   "packageManager": "pnpm@12.3.4",
   "description": "Shared base for DSH plugins: design tokens, UI controls, utils, workspace explorer, session preview",
   "keywords": [
@@ -28,6 +28,18 @@
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
     },
+    "./ui/official": {
+      "types": "./dist/ui/official.d.ts",
+      "default": "./dist/ui/official.js"
+    },
+    "./ui/code-viewer": {
+      "types": "./dist/ui/CodeViewer.d.ts",
+      "default": "./dist/ui/CodeViewer.js"
+    },
+    "./ui/host": {
+      "types": "./dist/ui/host-toast.d.ts",
+      "default": "./dist/ui/host-toast.js"
+    },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "default": "./dist/utils/index.js"
@@ -43,6 +55,10 @@
     "./session": {
       "types": "./dist/session/index.d.ts",
       "default": "./dist/session/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
     }
   },
   "files": [
@@ -50,9 +66,15 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "gen:css": "node scripts/gen-css.mjs",
+    "build": "node scripts/gen-css.mjs && node scripts/gen-docs.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.demo.json --noEmit",
+    "typecheck:demo": "tsc -p tsconfig.demo.json --noEmit",
+    "pretest": "node scripts/gen-css.mjs --check && node scripts/gen-docs.mjs --check && tsc -p tsconfig.json && tsc -p tsconfig.demo.json --noEmit",
     "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "pnpm run build && pnpm test",
+    "typecheck:docs": "tsc -p tsconfig.docs.json",
+    "gen:docs": "node scripts/gen-docs.mjs",
     "build:demo": "node packages/demo/build.mjs"
   },
   "peerDependencies": {
@@ -67,9 +89,28 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.13.1",
+    "@codemirror/legacy-modes": "^6.5.5",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.15",
+    "@floating-ui/react": "^0.27.20",
+    "@lezer/highlight": "^1.2.5",
+    "@uiw/react-codemirror": "^4.25.12",
+    "sonner": "^2.0.8"
+  },
   "devDependencies": {
     "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.7",
     "esbuild": "^0.28.2",
+    "lightningcss": "^1.33.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "typescript": "5.9.3"

package/dist/ui/ErrorBoundary.d.ts

@@ -1,22 +0,0 @@
-import { Component, type ErrorInfo, type ReactNode } from 'react';
-import { type Translate } from '../utils/i18n.js';
-export interface ErrorBoundaryProps {
-    children?: ReactNode;
-    /** 兜底渲染；不传就用内置错误块（带「重试」）。 */
-    fallback?: (error: Error, retry: () => void) => ReactNode;
-    onError?: (error: Error, info: ErrorInfo) => void;
-    translate?: Translate;
-}
-interface State {
-    error: Error | null;
-}
-/** 错误边界：子组件渲染抛错时不让整个插件白屏。 */
-export declare class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
-    state: State;
-    static getDerivedStateFromError(error: Error): State;
-    componentDidCatch(error: Error, info: ErrorInfo): void;
-    private readonly retry;
-    render(): ReactNode;
-}
-export {};
-//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/ui/ErrorBoundary.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/ui/ErrorBoundary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAErF,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAA;IACzD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,UAAU,KAAK;IACb,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED,6BAA6B;AAC7B,qBAAa,aAAc,SAAQ,SAAS,CAAC,kBAAkB,EAAE,KAAK,CAAC;IAC5D,KAAK,EAAE,KAAK,CAAkB;IAEvC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAI3C,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAI/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAErB;IAEQ,MAAM,IAAI,SAAS;CAiB7B"}

package/dist/ui/ErrorBoundary.js

@@ -1,30 +0,0 @@
-import { Component, createElement as h } from 'react';
-import { ensureControls } from './css.js';
-import { t } from '../utils/i18n.js';
-/** 错误边界：子组件渲染抛错时不让整个插件白屏。 */
-export class ErrorBoundary extends Component {
-    constructor() {
-        super(...arguments);
-        this.state = { error: null };
-        this.retry = () => {
-            this.setState({ error: null });
-        };
-    }
-    static getDerivedStateFromError(error) {
-        return { error };
-    }
-    componentDidCatch(error, info) {
-        this.props.onError?.(error, info);
-    }
-    render() {
-        const err = this.state.error;
-        if (err === null)
-            return this.props.children ?? null;
-        ensureControls();
-        if (this.props.fallback !== undefined)
-            return this.props.fallback(err, this.retry);
-        const tt = this.props.translate ?? t;
-        return h('div', { className: 'dshpc-error' }, h('div', null, `${tt('errorTitle')}：${err.message}`), h('button', { type: 'button', className: 'dshpc-error__retry', onClick: this.retry }, tt('errorRetry')));
-    }
-}
-//# sourceMappingURL=ErrorBoundary.js.map

package/dist/ui/ErrorBoundary.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ErrorBoundary.js","sourceRoot":"","sources":["../../src/ui/ErrorBoundary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,IAAI,CAAC,EAAkC,MAAM,OAAO,CAAA;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,CAAC,EAAkB,MAAM,kBAAkB,CAAA;AAcpD,6BAA6B;AAC7B,MAAM,OAAO,aAAc,SAAQ,SAAoC;IAAvE;;QACW,UAAK,GAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QAUtB,UAAK,GAAG,GAAS,EAAE;YAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAChC,CAAC,CAAA;IAmBH,CAAC;IA7BC,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC1C,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAe;QACtD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACnC,CAAC;IAMQ,MAAM;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAA;QAC5B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAA;QACpD,cAAc,EAAE,CAAA;QAChB,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QAClF,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,CAAA;QACpC,OAAO,CAAC,CACN,KAAK,EACL,EAAE,SAAS,EAAE,aAAa,EAAE,EAC5B,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC,EACpD,CAAC,CACC,QAAQ,EACR,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,oBAAoB,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,EACxE,EAAE,CAAC,YAAY,CAAC,CACjB,CACF,CAAA;IACH,CAAC;CACF"}

package/docs/design/features/design.md

@@ -1,55 +0,0 @@
-# design —— 样式层
-
-零 React、无组件。装的是「值 + 注入机制」：token 变量表、注入器工厂、主题判据。
-
-只想统一配色/尺寸但自己写组件的插件，只引这一个就够。
-
-## 导出
-
-| 符号 | 说明 |
-|---|---|
-| `createStyleKit(options)` | 领一套本插件专属的样式设施（**必调**） |
-| `DARK_THEME_SELECTOR` | 明暗判据选择器常量 `body[data-ds-dark-theme]` |
-| `type StyleKit` / `StyleKitOptions` | 类型 |
-
-## `createStyleKit(options)`
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|---|---|---|---|---|
-| `id` | `string` | 是 | — | `<style>` 标签 id，**多插件同页靠它互不覆盖**，必须插件内唯一。空串抛错 |
-
-返回的 `StyleKit`：
-
-| 成员 | 说明 |
-|---|---|
-| `id` | 回显 |
-| `tokensCss` | 已替换前缀的 token CSS 文本 |
-| `cssVar(name)` | 拼变量名：`cssVar('fg')` ⇒ `--acme-fg` |
-| `registerStyle(domain, css)` | 登记一个域的 CSS；同名重复登记 = 覆盖 |
-| `ensureStyles()` | 确保标签已挂载且内容最新（幂等；无 document 静默跳过） |
-| `applyStyle(domain, css)` | 登记 + 立刻挂载 |
-| `dispose()` | 撤掉标签并清空登记域（插件卸载 / HMR 时用） |
-
-## 最小可用
-
-```ts
-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 口径
-
-token 来自 `dsh-task-dispatch-table/src/client/ui/tokens.ts` 的整段提取（颜色 / 尺寸 / 字号 /
-层级），**含深色覆盖段**。取值一律走 `var(--<prefix>-*)`，不在规则里写死颜色值。
-
-完整清单与命名口径见 [`../style.md`](../style.md)。
-
-## 定制边界
-
-- token 的**前缀固定 `dshpc`**（不参数化、不按插件改名）；token 的**内容**（有哪些变量、值是什么）
-  是本包定的审美标准，消费方通过覆盖变量值来适配，不要改本包源码。
-- 要整套换肤：给同一批变量名赋新值即可，不需要 fork。

package/docs/design/features/explorer.md

@@ -1,73 +0,0 @@
-# explorer —— 工作区浏览
-
-依赖 `ui` + `design`。装的是「文件浏览」这个成品：目录树 + 面包屑 + 文件预览。
-选工作区 / 选文件在 `ui`（`WorkspacePicker` / `FilePicker`），不在这里。
-
-## 宿主契约：`WorkspaceFilesFace`
-
-**由插件从 `ctx` 取出这一小块传进来**（不要传整个 `ctx`——那会把本包和宿主版本焊死）。
-宿主 breaking 时改的是插件「取出」的一行。
-
-| 方法 | 签名要点 |
-|---|---|
-| `read` | `(sessionId, path, range, signal?)` —— ⚠️ `range` **必传**（官方按位置参数个数校验，省了会被远端拒），读全量传 `{}` |
-| `readBytes` | `(sessionId, path, options, signal?)` —— `options` 同样必传；不传 range 读全量 |
-| `list` | `(sessionId, path, signal?)` ⇒ `{ path, entries: [{ name, type, size? }], truncated }`；list 一个文件会报 not-directory |
-| `stat?` | 可选；宿主过旧没有此方法时降级。只认普通文件，目录会抛 |
-
-类型与工具（`types.ts`）：`WorkspaceFilesFace` / `DirEntry` / `Listing` / `PreviewKind`。
-
-路径方法 `crumbsOf` / `parentOf` / `joinPath` / `extOf` / `mimeOf` 是纯方法（无 UI），
-建议迁入 `utils/`（`path` 域，待定）；`previewKindOf`（决定用哪种预览器）是文件浏览的业务判断，留在内部。
-
-## `ExplorerPanel`
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `workspaceFiles` | `WorkspaceFilesFace` | — | 必填，注入的宿主能力 |
-| `sessionId` | `string` | — | 必填 |
-| `path` | `string` | `''` | 起始路径，`''` = 工作区根 |
-| `onSelect` | `(path: string \| null) => void` | — | 选中文件 / 清空选中时回调 |
-| `onOpenFile` | `(path: string) => void` | — | 点文件时回调（与 `onSelect` 同时触发） |
-| `emptyText` | `string` | 内置「空目录」 | — |
-| `translate` | `Translate` | 内置 | — |
-
-提供：面包屑（可点回跳，含上一级 / 刷新）、目录树（目录优先排序 + 显示体积）、
-预览区（文本 / 图片 / 不支持兜底）。
-
-```tsx
-import { ExplorerPanel } from 'dsh-plugin-core/explorer'
-
-h(ExplorerPanel, {
-  workspaceFiles,           // 从 ctx 取出
-  sessionId,
-  path: '',
-  onSelect: (p) => setCurrent(p),
-})
-```
-
-## 选工作区 / 选文件 —— 在 `ui`，不在这里
-
-`WorkspacePicker` / `FilePicker` 已移到 `dsh-plugin-core/ui`（见 [`ui.md`](ui.md#workspacepicker--filepicker)）。
-
-理由：它们只是 `Picker` 的薄封装（select），不碰目录树 / 预览 / `WorkspaceFilesFace`——
-放在 ui 里，需要「选工作区」的地方不必引入整个 explorer。explorer 内部要用，一样从 ui 引。
-
-## 单文件预览（`dsh-plugin-core/explorer/preview`）
-
-`FilePreview({ workspaceFiles, sessionId, path, translate? })` —— 按扩展名分派：
-图片 ⇒ `readBytes` 转 Blob（卸载时 `revokeObjectURL`）；文本类 ⇒ `read` 取正文；
-认不出的二进制 ⇒ 明确「暂不支持预览」，不硬撑。
-
-## 已知限制（选型前必读）
-
-- **无代码语法高亮**（不引 `@codemirror/*`），代码文件按纯文本渲染。
-- **不支持 PDF / Office 预览**（那要依赖宿主 `officeToPdf`）。
-- 目录树**无懒加载 / 虚拟滚动**，超大目录（官方上限 2000 条）会一次渲染完。
-- 面包屑超宽时**简单换行**，没有「折叠为当前层名 + 下拉选层」。
-
-## 定制边界
-
-- 宿主能力接口稳定 ⇒ 换宿主版本通常只改插件侧「取出」那一行。
-- 要加预览类型：在调用方自己渲染（用 `previewKindOf` 判断），或提需求进本包。
-- 不要 fork 面板：内部与 `ui` 的样式域耦合，fork 后跟不上 token 调整。

package/docs/design/features/session.md

@@ -1,70 +0,0 @@
-# session —— 会话预览
-
-依赖 `ui`。把「看一眼某个会话、看完即关」这件事封装起来：自动执行的任务想回看这次会话，
-不想开新窗口（回来还得找）。
-
-## 定位
-
-**弹窗只是当前的呈现方式**，不是这个包的定义。将来也可能是侧边栏或整页 ⇒ 用 `variant` 切换。
-「纯 Modal 控件」在 `ui` 里，这里装的是「会话预览」这个功能。
-
-## 宿主契约：`SessionSource`
-
-| 方法 | 签名 | 必填 |
-|---|---|---|
-| `listMessages` | `(sessionId, signal?) => Promise<SessionMessage[]>` | 是 |
-| `download?` | `(sessionId, path, signal?) => Promise<Uint8Array>` | 否（宿主没这能力就不显示下载钮） |
-
-数据形状：
-
-```ts
-interface SessionMessage {
-  id: string
-  role: 'user' | 'assistant' | 'tool' | 'system'
-  text: string                 // 纯文本正文
-  createdAt?: string
-  attachments?: { name: string; path: string; bytes?: number }[]
-}
-```
-
-**为什么注入能力而不是传静态数据**：会话预览内部有交互（附件下载 / 打开文件），
-光有消息流不够用，它必须能回调宿主。
-
-## `SessionPreview`
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `sessionId` | `string` | — | 必填 |
-| `source` | `SessionSource` | — | 必填，注入的取数能力 |
-| `variant` | `'modal' \| 'sidebar' \| 'page'` | `modal` | 承载方式 |
-| `title` | `ReactNode` | `sessionId` | modal 形态的标题 |
-| `onClose` | `() => void` | — | 关闭回调 |
-| `renderMessage` | `(m: SessionMessage) => ReactNode` | 内置最简渲染 | ★ **定制扩展点**：富内容（工具卡 / 代码块 / 推理行）走这里 |
-| `onOpenFile` | `(path: string) => void` | — | 点附件「打开」（通常交给 explorer） |
-| `translate` | `Translate` | 内置 | — |
-
-三态齐备：加载中 / 失败（带重试）/ 空。
-
-```tsx
-import { SessionPreview } from 'dsh-plugin-core/session'
-
-h(SessionPreview, {
-  sessionId,
-  source,                    // 从 ctx 取出后注入
-  variant: 'modal',
-  onClose: () => setOpen(false),
-  renderMessage: (m) => h(RichMessage, { message: m }),  // 可选
-})
-```
-
-## 已知限制（重要）
-
-- **默认渲染只有「角色 + 纯文本 + 附件」**——官方会话 UI 的完整镜像（工具卡 / 代码块 / 推理行等）
-  **还没搬进本包**。要长得像官方会话，请用 `renderMessage` 自己渲染，或等后续版本。
-- 无消息分页 / 增量加载，长会话一次全渲染。
-
-## 定制边界
-
-- `renderMessage` 就是为「特殊定制」留的口子：换渲染器不用 fork 面板。
-- 换承载方式用 `variant`，不用改调用方结构。
-- `SessionSource` 的方法签名若与宿主对不上，在插件侧做适配层——**不要改本包接口去贴某个宿主导出版本**。