dsh-plugin-core 0.1.4 → 0.2.1

package/docs/design/style.md

@@ -7,16 +7,17 @@ token 口径、注入器、明暗判据、定制边界。规则依据见 `docs/d
 客户端产物是 `window.__ModuleLoader__.load({ id, factory })` 的 CJS 闭包，
 `import './x.css'` 只会产出独立 css 资源、**内核不加载它** ⇒ CSS 只能以 TS 字符串在运行时打进 `<style>`。
 
-## 前缀要换几处？—— 只换变量，不换类名
+## 前缀规则
 
-| 前缀 | 处理 | 原因 |
-|---|---|---|
-| 变量 `--tdt-` | **换**成 `--<插件前缀>-` | 多插件同页必须隔离，否则变量互相覆盖 |
-| 类名 `dsh-tdt-` | **保持原样** | 控件里的 className 是硬编码字面量，只换 CSS 侧会让选择器与 className 对不上、样式整片失效 |
+变量与类名**全生态统一 `dshpc`**，代码里直接写死，不存在按插件替换这回事。
+
+| 名称 | 规则 |
+|---|---|
+| 变量 `--dshpc-*` | 直接使用；token 定义与控件样式都写这个前缀 |
+| 类名 `dshpc-*` | 必须与控件里硬编码的 className 逐字一致，改一处就得全改 |
 
-> 这条是踩过坑定下来的（曾因两处一起换导致控件样式全丢，见 `ledger` 缺陷修复任务）。
-> **已知限制**：两个插件若引的 core 版本不同，`.dsh-tdt-*` 规则会互相覆盖（同版本内容一致、无害）。
-> 主防线是 style 标签 id（`createStyleKit({ id })`）与变量前缀隔离。
+> **已知限制**：两个插件若引的 core 版本不同，`.dshpc-*` 规则会互相覆盖（同版本内容一致、无害）。
+> 隔离靠 style 标签 id（`createStyleKit({ id })`）。
 
 ## 明暗判据（硬约束）
 
@@ -35,26 +36,42 @@ token 原文提取自 `dsh-task-dispatch-table/src/client/ui/tokens.ts`，含深
 
 | 类别 | 例 |
 |---|---|
-| 前景 / 背景面 | `--tdt-fg` `--tdt-fg-3` `--tdt-fg-4` `--tdt-surface-1` `--tdt-surface-2` `--tdt-surface-sunken` `--tdt-surface-menu` `--tdt-surface-base` |
-| 边框 | `--tdt-border` `--tdt-border-faint` |
-| 间距 | `--tdt-space-1` … `--tdt-space-3` |
-| 字号 / 行高 | `--tdt-font-sm` `--tdt-font-lg` `--tdt-line-sm` `--tdt-line-md` `--tdt-line-lg` |
-| 语义色 | `--tdt-business` `--tdt-success` `--tdt-danger` `--tdt-warning` `--tdt-link` |
-| 语义面 | `--tdt-open-bg` `--tdt-open-bg-soft` `--tdt-chip-bg` `--tdt-chip-bg-hover` |
-| 代码 | `--tdt-code-surface` `--tdt-code-font` |
+| 前景 / 背景面 | `--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`。
 
+## 交互态颜色（hover / active）
+
+**实心控件不许用 `opacity` 表达 hover**（2026-10-19 用户点名：「黑色和红色的按钮移上去变化太小，
+完全感觉不到颜色变了」）。压 10% opacity 与底色无关，几乎不可见。
+
+改用 token 层的**派生色**（`--dshpc-{accent,danger,success,warning,business}-hover / -active`）：
+
+| 主题 | 黑底（accent） | 红 / 绿 / 黄 / 蓝底 |
+|---|---|---|
+| 亮色 | 掺白提亮（黑 → 灰） | 掺黑压深（红 → 暗红） |
+| 暗色 | 掺黑压深（近白 → 灰） | 掺白提亮 |
+
+- 幅度 22% / 36%（hover / active），两种主题下都「一眼看出变了」。
+- 混色对象写成**固定中性色字面量** `#fff` / `#000`，不依赖宿主 `--dsw-static-neutral-*` 是否存在。
+- 旧内核不认 `color-mix` 时整条声明作废 ⇒ 回落该档原色（仍有基本可用性，只是没有 hover 反馈）。
+
 ## 三条硬规矩
 
 1. 不许再有第二处 `document.createElement('style')` —— 一律走 kit。
 2. 不许再出现第二套 style 标签 id —— 一个插件一套 kit。
-3. 域内的规则只能消费 `var(--<prefix>-*)`，颜色 / 尺寸 / 字号一律来自 token 层，不写死值。
+3. 域内的规则只能消费 `var(--dshpc-*)`，颜色 / 尺寸 / 字号一律来自 token 层，不写死值。
 
 ## 定制边界
 
 - **换肤**：给同一批变量名赋新值（在插件自己的样式域里覆盖），不需要 fork。
-- **加域**：`kit.registerStyle('reminder-widget', css)`，同一域重复登记 = 覆盖。
+- **加域**：`kit.registerStyle('widget', css)`，同一域重复登记 = 覆盖。
 - **`tokens` 域恒排最前**（变量定义必须先于消费它的规则），kit 内部已保证。
 - 皮肤写在调用方自己的样式域里；组件只认 token，不认调用方的具体颜色。

package/docs/examples/integration.md

@@ -19,14 +19,12 @@ pnpm add dsh-plugin-core
 import { createStyleKit } from 'dsh-plugin-core/design'
 import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
 
-const kit = createStyleKit({ id: 'dsh-task-reminder-ui', prefix: 'reminder' })
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
 setStyleKit(kit)
 ensureControls()
 ```
 
-`id` 必须插件内唯一；`prefix` 是变量前缀（`reminder` ⇒ `--reminder-fg`）。
-两者取值按**项目规范**定（多插件同页必须互不冲突）——示例里的 `dsh-task-reminder` / `reminder`
-只是演示命名规律（前缀取插件名缩写），不是可用值的枚举。
+`id` 必须插件内唯一（多插件同页靠它互不覆盖）；变量与类名统一使用 `dshpc` 前缀，不需要传参。
 
 ## 2. 用一个控件
 
@@ -97,7 +95,7 @@ kit.dispose()   // 撤掉 <style> 标签并清空登记域（插件卸载 / HMR
 
 | 坑 | 现象 | 解法 |
 |---|---|---|
-| 忘了 `setStyleKit` 就渲染控件 | 样式晚一帧或串到默认前缀 | 入口处先调，再渲染 |
+| 忘了 `setStyleKit` 就渲染控件 | 样式晚一帧或落到默认 style id | 入口处先调，再渲染 |
 | 直接 `import` 官方 `@deepseek-ai/*` 并指望本包帮你引 | Node 下 `ERR_MODULE_NOT_FOUND` | 本包 `ui` 已零官方依赖；你要用官方件就在插件侧自己处理平台模块 |
 | 给 `read` 少传第三参 `range` | 远端拒：`expected 3 business argument(s) … got 2` | 一律显式传 `{}` |
 | 用 `relativePast` 显示未来时间 | 「3 分钟后」显示成「刚刚」 | 用 `relativeFuture` |

package/docs/requirements.md

@@ -38,8 +38,8 @@ dsh-plugin-core/
 
 ### 2.1 design
 
-- token 变量表，**前缀参数化**（`--tdt-` / `--dtl-` / `--stp-` → 由调用方给的 prefix 决定）
-- 样式注入器工厂 `createStyleKit({ id, prefix })`
+- token 变量表，**变量前缀全生态统一为 `dshpc`**
+- 样式注入器工厂 `createStyleKit({ id })`
 - 主题判据
 - **零 React、没有组件**
 
@@ -76,7 +76,7 @@ dsh-plugin-core/
 - 设置页骨架（**候补**：等出现第二个愿意用它的消费者再抽；`stp` 目前走官方 `SettingsForm`）
 - `host` 子包（**已取消**）
 - `llm/` 独立子包（**已取消**，ModelPicker 进 ui）
-- 业务件：`TaskPicker` / 日历 / `CodeViewer` 审美 / 业务 token（`--tdt-cal-*` / chip-bg /
+- 业务件：`TaskPicker` / 日历 / `CodeViewer` 审美 / 业务 token（`--dshpc-cal-*` / chip-bg /
   filechip / PROCESS_FILES_CSS）/ 页面几何 / 插件私有路由 / DB 表 / `mirror/` 之外的业务 UI
 
 ## 4. 立包判据（防止子包无限膨胀）
@@ -104,8 +104,7 @@ dsh-plugin-core/
 现 `dsh-task-dispatch-table/src/client/ui/style.ts:25` 是模块级单例 + 固定 style id
 `dsh-task-dispatch-table-ui`，多插件同页必然互相覆盖。
 
-⇒ 必须是 `createStyleKit({ id, prefix })`：每个插件调一次领一套自己的
-（自己的 `<style>` 标签 id + 自己的变量前缀），互不干扰。
+⇒ 必须是 `createStyleKit({ id })`：每个插件调一次领一套自己的（`<style>` 标签 id 按插件唯一）。
 
 ### 5.3 明暗色判据（别跟错）
 
@@ -134,15 +133,12 @@ dsh-plugin-core/
 
 | 位置 | 约定 |
 |---|---|
-| design | `createStyleKit({ id, prefix })` → `{ registerStyle, ensureStyles, applyStyle }` |
-| ui / ModelPicker | `variant: 'cascade' \| 'flat'`（级联：先厂商后模型 / 平铺：一个下拉列全部）；
-数据统一为 `groups: [{ value, label, options }]`，一份数据两种渲染。**禁止用数字或无意义名** |
+| 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，**组件自己取不到**） |
-| session | `SessionPreview({ sessionId, source, variant })` —— `source` = 取数能力接口
-（会话预览内部有交互：传输文件等，光有静态消息流不够） |
+| explorer / WorkspacePicker | `WorkspacePicker({ workspaces, mode, max, onChange })` —— 数据调用方给（工作区列表是 host 侧 `ctx.workspaceRegistry.list()` 取的，要经插件私有通道送到 client，**组件自己取不到**） |
+| session | `SessionPreview({ sessionId, source, variant })` —— `source` = 取数能力接口（会话预览内部有交互：传输文件等，光有静态消息流不够） |
 
 ## 7. 分期与任务切分
 

package/package.json

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