dsh-plugin-core 0.2.13 → 0.3.0

package/docs/design/features/ui.md

@@ -1,225 +0,0 @@
-# ui —— 基础控件
-
-依赖 `design`。装的是「用 token 搭出来的零件」——直接用，不再自己写原生控件。
-
-**纯零件，不自己取数**：选项、当前值都经 props 给（数据要跨 host↔client 边界，通道是插件私有的）。
-
-## 使用前必做（一次）
-
-```ts
-import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
-
-setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' }))
-ensureControls()
-```
-
-漏了也不白屏（控件内部会补调），但样式可能晚一帧。
-
-## 控件清单与 props
-
-> 完整签名以 TypeScript 声明为准（`src/ui/*.ts`），下表是导读。
-> 「追加 class/style」类参数一律**只允许补布局，不许覆盖皮肤**。
-
-### Button / IconButton
-
-10 档外观（2026-10-19 扩充，对齐主流 UI 框架的分类口径）：
-
-| 类别 | `variant` 档 |
-|---|---|
-| 实心（语义色底） | `primary`（黑）/ `secondary`（灰）/ `danger`（红）/ `success`（绿）/ `warning`（黄）/ `info`（蓝） |
-| 线框 | `outline`（中性描边）/ `danger-outline`（红字描边，旧别名 `danger-ink` 仍可用） |
-| 无底 | `ghost`（灰字，hover 起底）/ `link`（行内链接） |
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `variant` | 上表 10 档 | `outline` | 外观档 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `lg` | 高度档（24 / 28 / 32，有边无边同高） |
-| `icon` | `ReactNode` | — | 前置图标（官方图标组件 / 字符串均可） |
-| `iconRight` | `ReactNode` | — | 后置图标（展开箭头、外链） |
-| `color` | `string` | — | 自定义主色（任意 CSS 色值）：实心档作底色，线框 / 无底档作主色 |
-| `loading` | `boolean` | `false` | 文案前显示同色小圈，并自动 `disabled` |
-| `block` | `boolean` | `false` | 撑满父宽 |
-| `children` | `ReactNode` | — | 文案（由调用方按语言给：中文出中文、英文出英文，中英混排也支持） |
-| `…rest` | 原生 button 属性 | — | `type` / `disabled` / `title` / `aria-*` / `onClick` 原样透传 |
-
-hover / active 走 token 派生色（**不用 opacity**），幅度见 `docs/design/style.md` §交互态颜色。
-
-`IconButton`：`variant: 'plain' | 'outline' | 'danger'`（默认 `plain`）、`size`（默认 `lg`）、`icon`（必填）、
-`label`（必填，无障碍名兼 title）。
-
-### Segmented
-
-`items: readonly { value: T; label: ReactNode }[]`（必填）+ 单选（`value: T` / `onChange: (v: T) => void`）
-或多选（`multiple: true` + `value: T[]`）。另有 `size`（默认 `lg`）、`variant: 'default' | 'inset'`、
-`block`（撑满等分）、`label`（无障碍组名）、`id`、`disabled`。
-
-选中片 = `--dshpc-surface-raised`（与兄弟项目同取法）+ 1px 描边 + 浮起阴影：两种主题下都比轨道亮一档，
-在卡片面上靠描边与阴影分界。未选中项 hover 起浅底（inset 用深一档，避免与轨道同色）。
-
-### Input 家族（`Field.ts`）
-
-| 组件 | 关键参数 | 说明 |
-|---|---|---|
-| `Input` | `value` `onChange(v)` `size`（默认 `sm`）`error` `disabled` `type` `placeholder` `inputRef` `onKeyDown` `onBlur` `aria-label` `title` | 基础输入框；`error` 描红 |
-| `PrefixedInput` | 同 `Input` + `prefix: string` | 前置文案（`https://` / `C:\`） |
-| `NumberInput` | `value: number` `onChange(v)` `min` `max` `step`（默认 1）`inputWidth` `suffix` `label` `decreaseLabel` `increaseLabel` | 已 clamp；失焦回弹草稿 |
-| `Textarea` | `value` `onChange(v)` `placeholder` `error` `disabled` `rows` `spellCheck`（默认关）`aria-label` | — |
-| `Checkbox` | `checked` `onChange(next)` `label` `accentColor` `disabled` | — |
-| `fieldMetricsOf(size)` | `→ { height, font, line, icon, gap }` | 自己搭同款输入框时对齐尺寸 |
-
-### Picker（通用选择器）
-
-单选 / 多选 / 上限 / 搜索 / 分组 / 空态 / 降级，**自绘**（不依赖官方 Menu）。
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `groups` / `options` | `PickerGroup[]` / `PickerOption[]` | — | 二选一；`options` 会被当成一个无标题组 |
-| `value` / `defaultValue` | `string \| string[]` | — | 给了 `value` 即受控；否则内部管 |
-| `onChange` | `(v: string \| string[]) => void` | — | 单选回 `string`，多选回 `string[]` |
-| `mode` | `'single' \| 'multiple'` | `single` | — |
-| `max` | `number` | — | 多选上限；到上限其余项置灰 + 提示（不静默截断） |
-| `searchable` | `boolean` | `false` | 显示搜索框 |
-| `clearable` | `boolean` | `false` | 单选时列表顶部多一项「不选」 |
-| `placeholder` | `string` | 内置「请选择」 | — |
-| `degraded` | `boolean` | `false` | 候选可能不完整 ⇒ 顶部如实提示，不编造 |
-| `disabled` | `boolean` | `false` | — |
-| `size` | `'sm' \| 'md' \| 'lg'` | `md` | — |
-| `placement` | `'down' \| 'up'` | `down` | 触发器靠近视口底部时用 `up` |
-| `closeOnSelect` | `boolean` | 多选 `false` / 单选恒关 | 选中后是否收起 |
-| `showLabels` | `boolean` | `true` | 多选时触发器列出已选项，而非只显示「已选 N 项」 |
-| `className` | `string` | — | 定制宽度 / 外边距 |
-| `ariaLabel` | `string` | — | 无障碍名 |
-| `translate` | `Translate` | 内置 | 覆盖文案 |
-
-键盘：`Esc` 关、`↑↓` 移游标、`Enter` 选。
-
-纯逻辑也可单用：`toGroups` / `flattenOptions` / `filterGroups` / `toggleValue` / `labelsOf` / `groupOf`。
-
-### WorkspacePicker / FilePicker
-
-领域选择器——`Picker` 的薄封装（**领域数据 + 通用选择器交互**，与 explorer 的浏览/预览无关）。
-
-| 组件 | 数据参数 | 其余 |
-|---|---|---|
-| `WorkspacePicker` | `workspaces: readonly string[]` | `value` `defaultValue` `mode` `max` `onChange` `clearable` `searchable` `disabled` `size` `placement` `className` `placeholder` `translate` |
-| `FilePicker` | `files: readonly string[]` | 同上 |
-
-**为什么在 ui 而不在 explorer**：它俩只是 select，不碰目录树 / 预览 / `WorkspaceFilesFace`。
-放在 ui 里，需要「选工作区」的地方不必引入整个 explorer；explorer 内部要用也一样从 ui 引。
-
-**数据由调用方给**：工作区列表是 host 侧 `ctx.workspaceRegistry.list()` 取的，要经插件自己的 HTTP 通道
-送到 client，那条通道是插件私有的，组件取不到。
-
-```tsx
-import { WorkspacePicker } from 'dsh-plugin-core/ui'
-
-h(WorkspacePicker, { workspaces: wsList, value: cur, onChange: setCur })
-```
-
-### ModelPicker
-
-`groups: PickerGroup[]`（一组 = 一个供应商）+ `variant: 'cascade' | 'flat'`（默认 `flat`）。
-
-- `flat`：一个下拉列全部
-- `cascade`：一行两个下拉，先选供应商再选模型；换供应商会自动清空已选模型
-
-其余参数透传给 `Picker`：`value` / `defaultValue` / `onChange` / `clearable` / `searchable` /
-`size` / `placement` / `className` / `disabled` / `degraded` / `translate`。
-
-「跟随宿主」这类默认项由调用方自己往 `groups` 里塞一项——编码口径（如 `provider/id`）也归调用方。
-
-### Card / StripCard / Chip
-
-**两种卡片外观，拆成两个独立组件**（消费方要用哪个拖哪个，不搞 variant 二合一）：
-
-| 组件 | 外观 | 色条 |
-|---|---|---|
-| `Card` | 圆角 + 1px 边框 | 短条，上下留距 8px |
-| `StripCard` | 无圆角、无边框（贴边） | **通高**（贴顶到底） |
-
-两者共享同一套 props：
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `accent` | 5 档 or 任意 CSS 色值 | `'business'` | 档位：`business`(蓝) / `success`(绿) / `warning`(黄) / `danger`(红) / `neutral`(灰)，映射到 design 的 token；也可传 `'#f59e0b'` 这类自定义值 |
-| `expanded` | `boolean` | `false` | 展开态（箭头朝向 + `panel` 显隐） |
-| `onToggle` | `() => void` | — | 传了才显示右侧折叠箭头；**展开状态由调用方管** |
-| `action` | `ReactNode` | — | 右上角操作区（「跳过」「查看会话」） |
-| `children` | `ReactNode` | — | 主内容，排版随你 |
-| `panel` | `ReactNode` | — | 展开后才显示的额外内容 |
-| `className` / `style` | — | — | 追加类 / 样式 |
-
-色条是绝对定位 + `top/bottom`，**跟着内容高度自适应**；上下是否留距由外观决定（`Card` 留 8px、`StripCard` 通高）。
-颜色全走 token ⇒ **亮暗自动跟随宿主**（`body[data-ds-dark-theme]`），不需要调用方处理。
-
-```tsx
-import { Card, Chip, StripCard } from 'dsh-plugin-core/ui'
-
-h(Card, {
-  accent: 'warning',
-  action: h(Button, { size: 'sm', variant: 'ghost' }, '跳过'),
-},
-  h('div', null, '标题'),
-  h(Chip, null, '#npm'),
-)
-
-h(StripCard, {
-  accent: 'success',
-  expanded: open, onToggle: () => setOpen(!open),
-  panel: h('div', null, '展开详情'),
-}, h('div', null, '标题 + 元信息'))
-```
-
-`Chip`：小标签，token 用现成的 `--dshpc-chip-bg`；传 `onClick` 才是可点的。
-
-**语义边界**：`Chip` 只管「胶囊标签」这一件事。**只给图标的小按钮请用 `IconButton`**（`.dshpc-iconbtn`），
-不要拿 `Chip` 当图标底板——同一个类名两套皮肤（28px 定宽 vs 胶囊形）会互相覆盖、把文字挤成一列。
-现在一套皮肤只允许出现一次，由 `test/css-contract.test.mjs` 盯着。
-
-### Modal
-
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `title` | `ReactNode` | — | 标题 |
-| `onClose` | `() => void` | — | 不传则不显示关闭钮 |
-| `closeOnMask` | `boolean` | `true` | 点遮罩关闭；误触代价大的场景设 `false` |
-| `escClose` | `boolean` | `true` | Esc 关闭 |
-| `maxWidth` | `string` | `min(960px, 92vw)` | — |
-| `hideHeader` | `boolean` | `false` | 不渲染头部（沉浸式） |
-| `footer` | `ReactNode` | — | 底栏（按钮区） |
-| `children` | `ReactNode` | — | 主体 |
-
-自绘 overlay，**不用 react-dom 的 portal**（避免多一个必需依赖）。
-
-### 反馈件
-
-**FieldHint（问号提示）**：独立组件，不属于 Input 家族——标题后、按钮后、文字后、输入框后随处可挂。
-气泡 = **官方 Tooltip 本体**（2026-10-19 拍板「必须与悬停提示用同一个」）：插件启动时
-`setTooltipRenderer((props) => h(OfficialTooltip, props))` 把官方组件交给 core，`side` / `align` / `maxWidth` 可透传。
-**不做降级兜底**（用户同日明确：宿主内官方包恒在；官方改版 = 重新适配，不另造一套）——
-未注入 renderer 的非宿主环境（node 自检）只出问号图标、没有气泡。
-
-core 保持零官方依赖：官方 Tooltip 只能由插件侧注入（`src/ui/tooltip.ts`），不许静态 import。
-
-### 反馈件
-
-| 组件 / 函数 | 说明 |
-|---|---|
-| `showToast(message, opts?)` | **命令式**，不要求挂组件。`opts: { variant?: 'info' \| 'success' \| 'error', durationMs? }`（默认 2600ms）。无 `document` 静默跳过 |
-| `Loading({ anchorId? })` | 贴到主内容容器右下角的加载指示；`anchorId` 默认 `dshpc-main` |
-| `RunningBlocks()` | 运行中的占位块 |
-| `EmptyState({ text?, icon?, action?, translate? })` | 统一空态 |
-| `ErrorBoundary({ fallback?, onError?, translate? })` | class 组件；子组件抛错不让整个插件白屏，默认给「出错了 + 重试」 |
-| `SectionHead({ icon, title, right? })` | 分区标题 |
-| `MarqueeText({ text, style?, title?, className? })` | 超长省略、hover 滚动 |
-| `LiveText({ render, style? })` | 定时重渲染（相对时间这类） |
-| `BackToTop({ anchorId? })` | 回到顶部，贴主容器右缘外侧 |
-| `startResizeLayoutWidth(opts)` | 拖拽调整布局宽度 |
-
-## 定制边界
-
-- props 就是定制面：要改行为请**组合 props**，不要 fork 源码（fork 会跟不上后续修复）。
-- 「追加 class/style」只允许补布局，皮肤一律走 token 覆盖。
-- 缺控件时先提需求；实在要自己写，请按 `docs/design/style.md` 的口径用同一套 token，
-  并考虑提到本包（一个控件的复用价值高于一次性的私有实现）。

package/docs/design/features/utils.md

@@ -1,64 +0,0 @@
-# utils —— 通用方法
-
-零 React、零 DOM、零 `design` 依赖。装的是「和界面无关的纯方法」。
-
-## 日期（`date.ts`）
-
-全部走**本机时区**；解析失败一律不抛错、按兜底返回，不编造时间。
-
-| 函数 | 签名 | 边界行为 |
-|---|---|---|
-| `pad2` | `(value: number \| string) => string` | `9` ⇒ `'09'` |
-| `formatDateTime` | `(iso, opts?: { seconds?, fallback? }) => string` | 解析失败 ⇒ `opts.fallback`，缺省**原串**；`seconds: true` 补 `:ss` |
-| `formatYmd` | `(iso, opts?: { fallback? }) => string` | 解析失败 ⇒ `opts.fallback`，缺省 `—` |
-| `formatClock` | `(iso: string \| null \| undefined, opts?: { fallback? }) => string` | 空值/解析失败 ⇒ `opts.fallback`，缺省 `-` |
-| `formatDurationHms` | `(ms: number) => string` | 有小时 ⇒ `H:MM:SS`，否则 `MM:SS`；负数/NaN ⇒ `-` |
-| `sameCalendarDay` | `(a: Date, b: Date) => boolean` | 本机时区比年月日 |
-| `relativePast` | `(iso, nowMs, translate?) => string` | 过去时间 ⇒ 「3 分钟前」；未来/解析失败 ⇒ 「刚刚」 |
-| `relativeFuture` | `(iso, nowMs, translate?) => string` | 未来时间 ⇒ 「3 分钟后」；解析失败回退 `formatYmd` |
-| `formatRange` | `(fromIso, toIso, opts?: { seconds? }) => string` | 同天 ⇒ `09:00 – 10:30`；跨天两端带日期 |
-| `overlaps` | `(aFrom, aTo, bFrom, bTo) => boolean` | 半开区间 `[from, to)`；NaN ⇒ 不重叠 |
-
-> `relativePast` 与 `relativeFuture` 是**对偶**的：调度表这类展示未来时间的场景必须用
-> `relativeFuture`——用 `relativePast` 会把「3 分钟后」显示成「刚刚」，直接丢语义。
-
-## 字符串 / 数字
-
-| 函数 | 签名 | 边界行为 |
-|---|---|---|
-| `baseNameOf` | `(path: string) => string` | 取末段；目录尾斜杠不会取成空串 |
-| `safeTrim` | `(s: string) => string` | 去首尾空白 |
-| `truncateBytes` | `(s: string, maxBytes: number) => string` | 按 **UTF-8 字节**截断，不切半个字 |
-| `formatBytes` | `(bytes: number) => string` | `12 KB` / `3.4 MB`；0 与负数 ⇒ `—` |
-| `formatCount` | `(n: number) => string` | 千分位 |
-
-## HTTP
-
-| 函数 | 签名 | 说明 |
-|---|---|---|
-| `request` | `(url, opts?: RequestOptions) => Promise<Response>` | 带超时（默认 10s）与 `AbortSignal` |
-| `requestJson` | `<T>(url, opts?) => Promise<T>` | 自动解析 JSON |
-| `HttpError` | `class extends Error` | 带 `status`；超时抛 `AbortError` |
-
-`RequestOptions`：`{ timeoutMs?, signal?, method?, body?, headers? }`。
-
-## 多语言（`i18n.ts`）
-
-核心提供的固定提示语（控件错误、加载中、空态…）由本包内置中英字典管。
-
-| 函数 | 说明 |
-|---|---|
-| `setLocale(locale)` | `'zh'`（默认）/ `'en'` |
-| `getLocale()` | 当前语言 |
-| `t(key, vars?)` | 取文案；`{n}` 占位由 `vars` 填 |
-| `type Translate` | `(key, vars?) => string`，组件都收这个参数供覆盖 |
-
-**边界**：插件自己界面的文案由插件自己管，本包不提供插件级 i18n 框架。
-想覆盖某条文案：给组件传 `translate` prop，或给自己的场景直接用 `t` + 自定义字典。
-
-可用 key 全集见 `src/utils/i18n.ts` 的 `UtilMessageKey`。
-
-## 定制边界
-
-- 这些是纯函数，**直接调用即可**，没有需要 fork 的场景。
-- 时区口径固定本机时区（沿用三家现有口径）—— 要显式时区请在调用方转换后再传进来。

package/docs/examples/integration.md

@@ -1,103 +0,0 @@
-# 样例：从零接入一个插件
-
-一个插件从装包到用上各子包的完整路径。复制粘贴级别的最小可用示例。
-
-## 0. 装包
-
-```bash
-pnpm add dsh-plugin-core
-```
-
-（npm 也能用；推荐 pnpm。）
-`react` 是 optional peer——只用 `utils` / `design` 的插件不必装。
-包里带预编译 `dist`（宿主以 git/npm 装插件**不跑构建脚本**，产物必须随包发布）。
-
-## 1. 初始化样式（一次）
-
-```ts
-// 插件 client 入口
-import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
-
-const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
-setStyleKit(kit)
-ensureControls()
-```
-
-`id` 必须插件内唯一（多插件同页靠它互不覆盖）；变量与类名统一使用 `dshpc` 前缀，不需要传参。
-
-## 2. 用一个控件
-
-```tsx
-import { Button, Input, Picker, showToast } from 'dsh-plugin-core/ui'
-
-h(Input, { value: name, onChange: setName, placeholder: '任务名', error: nameError })
-h(Button, { variant: 'primary', onClick: save }, '保存')
-h(Picker, {
-  options: models,                 // [{ value, label }]
-  value: current,
-  onChange: (v) => setCurrent(v as string),
-  searchable: true,
-  clearable: true,
-})
-showToast('已保存', { variant: 'success' })
-```
-
-## 3. 用通用方法
-
-```ts
-import { formatDateTime, relativeFuture, formatBytes } from 'dsh-plugin-core/utils'
-
-formatDateTime(task.runAt, { seconds: true })   // 2026-10-18 09:30:05
-relativeFuture(task.runAt, Date.now())          // 3 分钟后（未来时间用这个）
-formatBytes(file.size)                          // 12 KB
-```
-
-## 4. 接工作区浏览（要宿主能力）
-
-```tsx
-import { ExplorerPanel } from 'dsh-plugin-core/explorer'
-
-// 从 ctx 取出这一小块（不要传整个 ctx）
-const workspaceFiles = ctx.remote.workspaceFiles
-
-h(ExplorerPanel, { workspaceFiles, sessionId, path: '', onSelect: (p) => setFile(p) })
-```
-
-选工作区的下拉（数据由你给——它要经插件私有通道送到 client）：
-
-```tsx
-import { WorkspacePicker } from 'dsh-plugin-core/ui'
-
-h(WorkspacePicker, { workspaces: wsList, value: cur, onChange: setCur })
-```
-
-## 5. 接会话预览
-
-```tsx
-import { SessionPreview } from 'dsh-plugin-core/session'
-
-const source = {
-  listMessages: async (id) => (await api.get(`/sessions/${id}/messages`)).data,
-  download: async (id, path) => api.getBytes(`/sessions/${id}/file?path=${path}`),
-}
-
-h(SessionPreview, { sessionId, source, variant: 'modal', onClose: close })
-```
-
-## 6. 卸载清理（可选）
-
-```ts
-kit.dispose()   // 撤掉 <style> 标签并清空登记域（插件卸载 / HMR）
-```
-
-## 接入坑（按踩频排序）
-
-| 坑 | 现象 | 解法 |
-|---|---|---|
-| 忘了 `setStyleKit` 就渲染控件 | 样式晚一帧或落到默认 style id | 入口处先调，再渲染 |
-| 直接 `import` 官方 `@deepseek-ai/*` 并指望本包帮你引 | Node 下 `ERR_MODULE_NOT_FOUND` | 本包 `ui` 已零官方依赖；你要用官方件就在插件侧自己处理平台模块 |
-| 给 `read` 少传第三参 `range` | 远端拒：`expected 3 business argument(s) … got 2` | 一律显式传 `{}` |
-| 用 `relativePast` 显示未来时间 | 「3 分钟后」显示成「刚刚」 | 用 `relativeFuture` |
-| 想让组件自己取工作区 / 模型列表 | 取不到（通道是插件私有的） | 数据经 props 给，宿主能力经接口注入 |
-| 暗色不跟随宿主 | 插件固守一种明暗 | 判据是 `body[data-ds-dark-theme]`，别用 `prefers-color-scheme` |