dsh-plugin-core 0.35.8 → 0.35.10

package/docs/design/external/dsh-host.md

@@ -283,7 +283,7 @@
 
 | 项 | 值 |
 |---|---|
-| 端点 | `GET <path>?op=list\|read\|readBytes\|roots&path=<绝对路径>&offset&limit` |
+| 端点 | `GET {path}?op=list\|read\|readBytes\|roots&path=<绝对路径>&offset&limit` |
 | 只读 | 只有这 4 个 op，没有任何写/删/改入口 |
 | 鉴权 | 不加 token：宿主 HTTP 面本来就能调 `remote.workspaceFiles.read`（允许工作区外绝对路径），本路由不引入新暴露面；静态 token 写在同一个 bundle 里是装饰 |
 | 每层上限 | 500 条（`FS_PAGE_LIMIT`），服务端先按名排序再切片，翻页不重复/不漏 |
@@ -404,3 +404,7 @@
 `official-classes.ts` 的前缀表补 `@deepseek-ai/dsh-client-ui-attachment/`；
 用户消息与助手内联图片都改为真图，loader 缺席时才退回「[图片]」文本占位。
 未接：`tool.call.images`（`read_image` 工具卡内的图片区，官方 = `imageBody` + 槽 + `imageMeta` 路径/尺寸）。
+
+## 更新日志
+
+- 2026-11-08 23:34:50：按文档库规范建立版本元数据与统一目录索引

package/docs/design/features.md

@@ -4,3 +4,7 @@
 并在随包发布时直接作为引用方与 Agent 的入口。本文件不再维护第二份内容。
 
 本槽位在上级规则里是**路径固定**的，故保留文件与槽位行，不删、不改名、不挪位。
+
+## 更新日志
+
+- 2026-11-08 23:34:49：按文档库规范建立版本元数据与统一目录索引

package/docs/design/methods.md

@@ -20,3 +20,7 @@ only what you must honour when **adding a helper to `utils`**.
 EN: Failure path has a clear, overridable fallback; edge cases (empty / 0 / negative / NaN) covered by tests;
 exported from `src/utils/index.ts`; text goes through `t()` + `translate`; registered as a row in the
 matching parameter table under `docs/help/`.
+
+## 更新日志
+
+- 2026-11-08 23:34:49：按文档库规范建立版本元数据与统一目录索引

package/docs/design/structure.md

@@ -167,3 +167,7 @@ utils（谁都不依赖，谁都可以用）
 - **库里没有的**：
   - Switch 开关 —— 官方 primitives 有，归「包官方」批次；
   - Select 下拉 —— 用 `Picker` 代替（`SelectField` 曾因依赖官方 Menu 被删，属已反转的旧决策）。
+
+## 更新日志
+
+- 2026-11-08 23:34:49：按文档库规范建立版本元数据与统一目录索引

package/docs/design/style.md

@@ -296,6 +296,25 @@ EN: `Surface` is a pure frame and deliberately inherits typography, but any cont
 own default `font-size` / `line-height` from tokens (same tier as `Table` / `Input md`). Do not make every consumer
 repeat it; callers can still override that tier inline.
 
+## 图标尺寸：一条基线、一个放大档
+
+> EN: Icon sizing — one baseline, one enlargement tier
+
+2026-11-08 用户拍板：**图标尺寸只有一个真源** —— `button.css` 的 `svg{width:1em;height:1em}`
+（`.dshpc-iconbtn` / `.dshpc-btn__icon`），跟随各档 `--dshpc-font-*` token。调用方给图标组件传
+`size={N}`、组件局部 CSS 写 `font-size:16px` 或 `svg{width:16px}`，都不许再决定图标大小。
+非按钮的图标容器（`overlay__lead` / `quick-toolbar__item` / `fb__row-icon`）补同一条 `1em` 后代规则，
+让 `size` 传参自动失效。**要放大只走 `dense`**：`1.25em`（`button.css` 两处），由 `Button` /
+`IconButton` 的 `dense` prop 开启，正方形盒与高度档都不动，不新增第二套皮肤。
+曾经 `code-viewer.css` 给复制钮写死 `svg{16px}`、`panel-dock.css` 给箭头写死 `font-size:16px`，
+都是在核心之外另立一套尺寸，真机上就是「同一个界面里图标忽大忽小」。
+
+EN: Icon size has a single source — `button.css`'s `svg{width:1em;height:1em}` following the control's
+font token. Callers must not pass `size={N}` and component CSS must not hard-code `font-size:16px` or
+`svg{width:16px}`. Non-button icon containers repeat the same `1em` descendant rule so caller-supplied
+sizes stop taking effect. Enlargement exists only as `dense` (`1.25em`, via the `dense` prop); the box
+and height tier never change.
+
 ## 行控件的两槽居中
 
 > EN: Symmetric alignment for row slots
@@ -383,3 +402,7 @@ area stay symmetric. The StripCard rail is absolutely positioned against the roo
 (`top:0` / `bottom:0`), so it stays full-height across the expanded area too. `:has()` and "paint a resting-fill snapshot over the
 expanded area" are forbidden — semi-transparent tokens stacked twice render darker. Callers must put
 expandable content in `panel`; `children` belongs to the header block.
+
+## 更新日志
+
+- 2026-11-08 23:34:50：按文档库规范建立版本元数据与统一目录索引

package/docs/help/methods.md

@@ -56,3 +56,7 @@ negatives. HTTP: 10s timeout, `AbortError` on timeout, `HttpError` with `status`
 
 EN: Built-in prompts ship with zh/en (`setLocale` to switch); any API that renders text takes
 `translate: Translate` to override; your plugin’s own UI copy is yours to manage.
+
+## 更新日志
+
+- 2026-11-08 23:34:50：按文档库规范建立版本元数据与统一目录索引

package/docs/help/style.md

@@ -113,3 +113,7 @@ optional.
 EN: (1) Never namespace-import or `require` the barrel − it defeats tree-shaking (62.3 KB difference); use named
 imports. (2) Do not concatenate several CSS constants into one domain − that rebuilds full injection. (3) Never
 rely on injection order; override with higher specificity. (4) Never go back to `import './x.css'`.
+
+## 更新日志
+
+- 2026-11-08 23:34:50：按文档库规范建立版本元数据与统一目录索引

package/docs/help/ui.doc.ts

@@ -28,7 +28,8 @@ const cardExample = `import { Card, Chip, StripCard } from 'dsh-plugin-core/ui'
 h(Card, {
   accent: 'warning',
   bar: { side: 'left', inset: 12, gap: 12 },   // 色条可放 left / right / top / bottom
-  hoverable: true,                             // 头部区整块悬停变色（默认关）
+  // 传 onClick 才让卡片可点；hover 默认跟着它开，不用再手写光标与 :hover
+  onClick: () => openTask(id),
   action: h(Button, { size: 'sm', variant: 'ghost' }, '跳过'),
 },
   h('div', null, '标题'),
@@ -151,8 +152,8 @@ h(InputGroup, {
 h(InputGroup, {
   size: 'md', value: kw, onChange: setKw,
   actions: [
-    { icon: h(IconRefreshOutlineRegular, { size: 14 }), ariaLabel: '重置', onClick: reset },
-    { icon: h(IconSearchOutlineRegular, { size: 14 }), label: '搜索', onClick: search },
+    { icon: h(IconRefreshOutlineRegular, null), ariaLabel: '重置', onClick: reset },
+    { icon: h(IconSearchOutlineRegular, null), label: '搜索', onClick: search },
   ],
 })
 
@@ -371,8 +372,8 @@ const doc: DocTopic = {
           rows: [
             { name: 'variant', type: "上表 18 档（primary/secondary/danger/success/warning/info/outline/danger-outline/ghost/link + 扩展 purple/pink/cyan/teal/orange/indigo/rose/slate）", def: "'outline'", desc: { zh: '外观档', en: 'Appearance tier' } },
             { name: 'size', type: "'sm' | 'md' | 'lg'", def: "'lg'", desc: { zh: '高度档（24 / 28 / 32，有边无边同高）', en: 'Height tier (24 / 28 / 32, same height with or without border)' } },
-            { name: 'dense', type: 'boolean', def: 'false', desc: { zh: '紧凑图标档：高度不变，图标放大、内距收紧（Button / IconButton 同名同义）', en: 'Compact-icon tier: same height, larger icon and tighter padding (same prop on Button and IconButton)' } },
-            { name: 'icon', type: 'ReactNode', def: '—', desc: { zh: '前置图标（官方图标组件 / 字符串均可）', en: 'Leading icon (official icon component or string)' } },
+            { name: 'dense', type: 'boolean', def: 'false', desc: { zh: '**唯一放大档**：高度不变，图标放大、内距收紧（Button / IconButton 同名同义）；不要改成给图标传 size', en: '**Only enlargement tier**: same height, larger icon and tighter padding (same prop on Button and IconButton); do not pass size to the icon instead' } },
+            { name: 'icon', type: 'ReactNode', def: '—', desc: { zh: '前置图标（官方图标组件 / 字符串均可）；尺寸由核心 CSS 的 1em 接管，不要传 size，要放大用 dense', en: 'Leading icon (official icon component or string); size is owned by the core 1em rule — do not pass size, use dense to enlarge' } },
             { name: 'iconRight', type: 'ReactNode', def: '—', desc: { zh: '后置图标（展开箭头、外链）', en: 'Trailing icon (expand arrow, external link)' } },
             { name: 'color', type: 'string', def: '—', desc: { zh: '自定义主色：实心档作底色，线框 / 无底档作主色', en: 'Custom main color: background for solid tiers, main color for outline/bare' } },
             { name: 'loading', type: 'boolean', def: "'false'", desc: { zh: '受控 loading：文案前显示同色小圈并自动 disabled（别处刷新也能点亮它）；与「点击自动 loading」取或', en: 'Controlled loading: same-color spinner before the label plus auto-disable (an external refresh can light it up too); OR-ed with automatic click loading' } },
@@ -639,12 +640,16 @@ const doc: DocTopic = {
           en: 'The header centers vertically as a whole; drop a bare element into `action` and it centers. Colors come from tokens, so light/dark follows the host.',
         },
         {
-          zh: '`hoverable` 开启后悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝），默认关；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则。',
-          en: '`hoverable` (default off) changes the fill on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules.',
+          zh: '`hoverable` 开启后悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝）；默认跟随 `onClick`（给了点击回调即自动开），可显式传 `false` 关掉；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则。',
+          en: "`hoverable` changes the fill on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). It defaults to on when `onClick` is provided, and can be turned off explicitly. `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules.",
         },
         {
-          zh: '展开的卡片用 `hoverScope` 选作用域，默认 `\'head\'`：根节点零内距并统一裁圆角，`__body` 作为「上面那一整块」独立承担内距、边到边变色；展开态不改内距，上下两圈留白对称，两块之间的间隔也属于头部区、跟着一起变色；`__panel` 是它的兄弟节点，不铺背景、不画分隔线、不参与 hover，鼠标在展开区里操作时整卡都不触发；需要分隔线时由调用方在 `panel` 内容里自绘。展开区的 `margin-top` 与 `padding-top` 都是 0，自绘线紧贴头部区下沿、中间不夹不变色的带子；四根 `--card-pad-t/r/b/l` 是内距唯一真源，`style.padding` 会摊成这四根轴，头部区与展开区左右始终对称。StripCard 的通高色条相对根节点定位，展开后仍贯穿整卡（包括展开区）。想要整卡含展开区一起变色，才显式传 `\'card\'`。**展开内容必须放进 `panel`**（`children` 属于头部区），核心才有分区信号。',
-          en: 'For expandable cards, `hoverScope` selects the scope. The default `\'head\'` gives the root zero padding and clips the radius, while `__body` — the header block owning all padding — changes color edge to edge; expanding keeps its top and bottom padding symmetric, so the gap between the two blocks changes color too. `__panel` is a sibling with no background, no divider and no hover, so operating inside the expanded area triggers nothing; draw a divider inside `panel` content yourself when you need one. Both `margin-top` and `padding-top` on the expanded area are 0, so a caller-drawn line sits flush against the header with no uncoloured strip between them. The four `--card-pad-t/r/b/l` axes are the single source of padding truth: `style.padding` expands into them, keeping the header and expanded area symmetric. The StripCard rail is positioned against the root and stays full-height across the expanded area. Pass `\'card\'` explicitly to include it. **Expandable content must go into `panel`**; `children` belongs to the header block.',
+          zh: '展开的卡片用 `hoverScope` 选作用域，默认 `\'head\'`：根节点零内距并统一裁圆角，`__body` 作为「上面那一整块」独立承担内距、边到边变色；展开态不改内距，上下两圈留白对称，两块之间的间隔也属于头部区、跟着一起变色；`__panel` 是它的兄弟节点，不铺背景、不画分隔线、不参与 hover；默认作用域下鼠标在展开区里操作既不变色也不触发点击（点击契约见下段）；需要分隔线时由调用方在 `panel` 内容里自绘。展开区的 `margin-top` 与 `padding-top` 都是 0，自绘线紧贴头部区下沿、中间不夹不变色的带子；四根 `--card-pad-t/r/b/l` 是内距唯一真源，`style.padding` 会摊成这四根轴，头部区与展开区左右始终对称。StripCard 的通高色条相对根节点定位，展开后仍贯穿整卡（包括展开区）。想要整卡含展开区一起变色，才显式传 `\'card\'`。**展开内容必须放进 `panel`**（`children` 属于头部区），核心才有分区信号。',
+          en: 'For expandable cards, `hoverScope` selects the scope. The default `\'head\'` gives the root zero padding and clips the radius, while `__body` — the header block owning all padding — changes color edge to edge; expanding keeps its top and bottom padding symmetric, so the gap between the two blocks changes color too. `__panel` is a sibling with no background, no divider and no hover, so in the default scope operating inside the expanded area neither changes color nor triggers a click (see the click contract below); draw a divider inside `panel` content yourself when you need one. Both `margin-top` and `padding-top` on the expanded area are 0, so a caller-drawn line sits flush against the header with no uncoloured strip between them. The four `--card-pad-t/r/b/l` axes are the single source of padding truth: `style.padding` expands into them, keeping the header and expanded area symmetric. The StripCard rail is positioned against the root and stays full-height across the expanded area. Pass `\'card\'` explicitly to include it. **Expandable content must go into `panel`**; `children` belongs to the header block.',
+        },
+        {
+          zh: '`onClick` 让整块卡片可点，命中范围与 `hoverScope` 完全一致：默认 `head` 时点击层是 `__body`（内距圈四边都在里面），展开区 `__panel` 是它的兄弟节点、不绑任何事件，里面拖选复制也不受影响；显式 `card` 时点击层上提到根节点，整卡含展开区都响应。点击层拿 `role="button"`、`tabIndex=0` 与 Enter / Space，并有键盘焦点环；刻意不渲染成 `<button>`，因为调用方要在里面放按钮。`action` 与 `onToggle` 折叠箭头同在右侧槽，一层挡住冒泡，不会连带触发。不传 `onClick` 时外观与行为完全不变。',
+          en: '`onClick` makes the whole card clickable over exactly the same area as `hoverScope`: with the default `head`, the hit layer is `__body` (all four padding edges included), while `__panel` is its sibling with no handlers at all, so text selection inside the expanded area is untouched. With explicit `card`, the hit layer moves up to the root and the expanded area responds too. The hit layer gets `role="button"`, `tabIndex=0`, Enter / Space and a keyboard focus ring. It is deliberately not a `<button>`, because callers put buttons inside. `action` and the `onToggle` arrow share the right-hand slot, which stops propagation so they never trigger the card. Without `onClick`, appearance and behaviour are unchanged.',
         },
       ],
       api: [
@@ -658,8 +663,9 @@ const doc: DocTopic = {
             { name: 'action', type: 'ReactNode', def: '—', desc: { zh: '右上角操作区', en: 'Top-right action area' } },
             { name: 'children', type: 'ReactNode', def: '—', desc: { zh: '主内容，排版随你', en: 'Main content, layout is yours' } },
             { name: 'panel', type: 'ReactNode', def: '—', desc: { zh: '展开后才显示的额外内容；必须放这里，核心才能把展开区与头部区分开', en: 'Extra content shown only when expanded; must live here so the core can separate it from the header' } },
-            { name: 'hoverable', type: 'boolean', def: "'false'", desc: { zh: '悬停变色 + 光标变 pointer，统一 --dshpc-card-hover；默认关', en: 'Hover color plus a pointer cursor, using --dshpc-card-hover; default off' } },
-            { name: 'hoverScope', type: "'head' | 'card'", def: "'head'", desc: { zh: "'head'（默认）只让上面头部区整块边到边变色、展开区不受影响；'card' 整卡含展开区一起变色。仅 hoverable 为 true 时生效", en: "'head' (default) changes only the header block and leaves the expanded area untouched; 'card' includes it. Applies only when hoverable is true" } },
+            { name: 'onClick', type: '() => void', def: '—', desc: { zh: '传了才让卡片可点：命中范围同 hoverScope，点击层挂 role=button / tabIndex / Enter·Space；action 与折叠箭头不连带触发；hover 默认跟着开', en: 'Makes the card clickable. Hit area follows hoverScope; the hit layer gets role=button, tabIndex and Enter/Space; action and the collapse arrow never bubble into it; hover turns on by default' } },
+            { name: 'hoverable', type: 'boolean', def: '跟随 onClick', desc: { zh: '悬停变色 + 光标变 pointer，统一 --dshpc-card-hover；可显式传 false 关掉', en: 'Hover color plus a pointer cursor, using --dshpc-card-hover; defaults to on when onClick is set, pass false to disable' } },
+            { name: 'hoverScope', type: "'head' | 'card'", def: "'head'", desc: { zh: "'head'（默认）只有头部区变色并可点、展开区完全不受影响；'card' 整卡含展开区一起变色、一起可点。变色只在 hover 开时生效", en: "'head' (default) limits both color and clicks to the header block, leaving the expanded area untouched; 'card' includes it in both. Color applies only when hover is on" } },
             { name: 'filled', type: 'boolean', def: "'true'", desc: { zh: '是否带底色；false 时底透明、边框仍在。默认有底（Card = surface-1 / StripCard = accent 浅底）', en: 'Background fill; false makes it transparent while keeping the border. Default on (Card = surface-1 / StripCard = accent tint)' } },
             { name: 'className / style', type: '—', def: '—', desc: { zh: '追加类 / 样式；`style.padding` 摊成四根内距轴，同步头部区与展开区', en: 'Append class / style; `style.padding` expands into the four padding axes so the header and expanded area stay aligned' } },
           ],

package/docs/help/ui.md

@@ -67,8 +67,8 @@ Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三
 |---|---|---|---|---|
 | `variant` | `上表 18 档（primary/secondary/danger/success/warning/info/outline/danger-outline/ghost/link + 扩展 purple/pink/cyan/teal/orange/indigo/rose/slate）` | 'outline' | 外观档 | Appearance tier |
 | `size` | `'sm' \| 'md' \| 'lg'` | 'lg' | 高度档（24 / 28 / 32，有边无边同高） | Height tier (24 / 28 / 32, same height with or without border) |
-| `dense` | `boolean` | false | 紧凑图标档：高度不变，图标放大、内距收紧（Button / IconButton 同名同义） | Compact-icon tier: same height, larger icon and tighter padding (same prop on Button and IconButton) |
-| `icon` | `ReactNode` | — | 前置图标（官方图标组件 / 字符串均可） | Leading icon (official icon component or string) |
+| `dense` | `boolean` | false | **唯一放大档**：高度不变，图标放大、内距收紧（Button / IconButton 同名同义）；不要改成给图标传 size | **Only enlargement tier**: same height, larger icon and tighter padding (same prop on Button and IconButton); do not pass size to the icon instead |
+| `icon` | `ReactNode` | — | 前置图标（官方图标组件 / 字符串均可）；尺寸由核心 CSS 的 1em 接管，不要传 size，要放大用 dense | Leading icon (official icon component or string); size is owned by the core 1em rule — do not pass size, use dense to enlarge |
 | `iconRight` | `ReactNode` | — | 后置图标（展开箭头、外链） | Trailing icon (expand arrow, external link) |
 | `color` | `string` | — | 自定义主色：实心档作底色，线框 / 无底档作主色 | Custom main color: background for solid tiers, main color for outline/bare |
 | `loading` | `boolean` | 'false' | 受控 loading：文案前显示同色小圈并自动 disabled（别处刷新也能点亮它）；与「点击自动 loading」取或 | Controlled loading: same-color spinner before the label plus auto-disable (an external refresh can light it up too); OR-ed with automatic click loading |
@@ -250,8 +250,8 @@ h(InputGroup, {
 h(InputGroup, {
   size: 'md', value: kw, onChange: setKw,
   actions: [
-    { icon: h(IconRefreshOutlineRegular, { size: 14 }), ariaLabel: '重置', onClick: reset },
-    { icon: h(IconSearchOutlineRegular, { size: 14 }), label: '搜索', onClick: search },
+    { icon: h(IconRefreshOutlineRegular, null), ariaLabel: '重置', onClick: reset },
+    { icon: h(IconSearchOutlineRegular, null), label: '搜索', onClick: search },
   ],
 })
 
@@ -369,13 +369,17 @@ h(Surface, { tone: 'sunken', border: 'dashed', padding: 'lg' }, '还没做的东
 
 > EN: The header centers vertically as a whole; drop a bare element into `action` and it centers. Colors come from tokens, so light/dark follows the host.
 
-`hoverable` 开启后悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝），默认关；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则。
+`hoverable` 开启后悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝）；默认跟随 `onClick`（给了点击回调即自动开），可显式传 `false` 关掉；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则。
 
-> EN: `hoverable` (default off) changes the fill on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules.
+> EN: `hoverable` changes the fill on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). It defaults to on when `onClick` is provided, and can be turned off explicitly. `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules.
 
-展开的卡片用 `hoverScope` 选作用域，默认 `'head'`：根节点零内距并统一裁圆角，`__body` 作为「上面那一整块」独立承担内距、边到边变色；展开态不改内距，上下两圈留白对称，两块之间的间隔也属于头部区、跟着一起变色；`__panel` 是它的兄弟节点，不铺背景、不画分隔线、不参与 hover，鼠标在展开区里操作时整卡都不触发；需要分隔线时由调用方在 `panel` 内容里自绘。展开区的 `margin-top` 与 `padding-top` 都是 0，自绘线紧贴头部区下沿、中间不夹不变色的带子；四根 `--card-pad-t/r/b/l` 是内距唯一真源，`style.padding` 会摊成这四根轴，头部区与展开区左右始终对称。StripCard 的通高色条相对根节点定位，展开后仍贯穿整卡（包括展开区）。想要整卡含展开区一起变色，才显式传 `'card'`。**展开内容必须放进 `panel`**（`children` 属于头部区），核心才有分区信号。
+展开的卡片用 `hoverScope` 选作用域，默认 `'head'`：根节点零内距并统一裁圆角，`__body` 作为「上面那一整块」独立承担内距、边到边变色；展开态不改内距，上下两圈留白对称，两块之间的间隔也属于头部区、跟着一起变色；`__panel` 是它的兄弟节点，不铺背景、不画分隔线、不参与 hover；默认作用域下鼠标在展开区里操作既不变色也不触发点击（点击契约见下段）；需要分隔线时由调用方在 `panel` 内容里自绘。展开区的 `margin-top` 与 `padding-top` 都是 0，自绘线紧贴头部区下沿、中间不夹不变色的带子；四根 `--card-pad-t/r/b/l` 是内距唯一真源，`style.padding` 会摊成这四根轴，头部区与展开区左右始终对称。StripCard 的通高色条相对根节点定位，展开后仍贯穿整卡（包括展开区）。想要整卡含展开区一起变色，才显式传 `'card'`。**展开内容必须放进 `panel`**（`children` 属于头部区），核心才有分区信号。
 
-> EN: For expandable cards, `hoverScope` selects the scope. The default `'head'` gives the root zero padding and clips the radius, while `__body` — the header block owning all padding — changes color edge to edge; expanding keeps its top and bottom padding symmetric, so the gap between the two blocks changes color too. `__panel` is a sibling with no background, no divider and no hover, so operating inside the expanded area triggers nothing; draw a divider inside `panel` content yourself when you need one. Both `margin-top` and `padding-top` on the expanded area are 0, so a caller-drawn line sits flush against the header with no uncoloured strip between them. The four `--card-pad-t/r/b/l` axes are the single source of padding truth: `style.padding` expands into them, keeping the header and expanded area symmetric. The StripCard rail is positioned against the root and stays full-height across the expanded area. Pass `'card'` explicitly to include it. **Expandable content must go into `panel`**; `children` belongs to the header block.
+> EN: For expandable cards, `hoverScope` selects the scope. The default `'head'` gives the root zero padding and clips the radius, while `__body` — the header block owning all padding — changes color edge to edge; expanding keeps its top and bottom padding symmetric, so the gap between the two blocks changes color too. `__panel` is a sibling with no background, no divider and no hover, so in the default scope operating inside the expanded area neither changes color nor triggers a click (see the click contract below); draw a divider inside `panel` content yourself when you need one. Both `margin-top` and `padding-top` on the expanded area are 0, so a caller-drawn line sits flush against the header with no uncoloured strip between them. The four `--card-pad-t/r/b/l` axes are the single source of padding truth: `style.padding` expands into them, keeping the header and expanded area symmetric. The StripCard rail is positioned against the root and stays full-height across the expanded area. Pass `'card'` explicitly to include it. **Expandable content must go into `panel`**; `children` belongs to the header block.
+
+`onClick` 让整块卡片可点，命中范围与 `hoverScope` 完全一致：默认 `head` 时点击层是 `__body`（内距圈四边都在里面），展开区 `__panel` 是它的兄弟节点、不绑任何事件，里面拖选复制也不受影响；显式 `card` 时点击层上提到根节点，整卡含展开区都响应。点击层拿 `role="button"`、`tabIndex=0` 与 Enter / Space，并有键盘焦点环；刻意不渲染成 `<button>`，因为调用方要在里面放按钮。`action` 与 `onToggle` 折叠箭头同在右侧槽，一层挡住冒泡，不会连带触发。不传 `onClick` 时外观与行为完全不变。
+
+> EN: `onClick` makes the whole card clickable over exactly the same area as `hoverScope`: with the default `head`, the hit layer is `__body` (all four padding edges included), while `__panel` is its sibling with no handlers at all, so text selection inside the expanded area is untouched. With explicit `card`, the hit layer moves up to the root and the expanded area responds too. The hit layer gets `role="button"`, `tabIndex=0`, Enter / Space and a keyboard focus ring. It is deliberately not a `<button>`, because callers put buttons inside. `action` and the `onToggle` arrow share the right-hand slot, which stops propagation so they never trigger the card. Without `onClick`, appearance and behaviour are unchanged.
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
@@ -386,8 +390,9 @@ h(Surface, { tone: 'sunken', border: 'dashed', padding: 'lg' }, '还没做的东
 | `action` | `ReactNode` | — | 右上角操作区 | Top-right action area |
 | `children` | `ReactNode` | — | 主内容，排版随你 | Main content, layout is yours |
 | `panel` | `ReactNode` | — | 展开后才显示的额外内容；必须放这里，核心才能把展开区与头部区分开 | Extra content shown only when expanded; must live here so the core can separate it from the header |
-| `hoverable` | `boolean` | 'false' | 悬停变色 + 光标变 pointer，统一 --dshpc-card-hover；默认关 | Hover color plus a pointer cursor, using --dshpc-card-hover; default off |
-| `hoverScope` | `'head' \| 'card'` | 'head' | 'head'（默认）只让上面头部区整块边到边变色、展开区不受影响；'card' 整卡含展开区一起变色。仅 hoverable 为 true 时生效 | 'head' (default) changes only the header block and leaves the expanded area untouched; 'card' includes it. Applies only when hoverable is true |
+| `onClick` | `() => void` | — | 传了才让卡片可点：命中范围同 hoverScope，点击层挂 role=button / tabIndex / Enter·Space；action 与折叠箭头不连带触发；hover 默认跟着开 | Makes the card clickable. Hit area follows hoverScope; the hit layer gets role=button, tabIndex and Enter/Space; action and the collapse arrow never bubble into it; hover turns on by default |
+| `hoverable` | `boolean` | 跟随 onClick | 悬停变色 + 光标变 pointer，统一 --dshpc-card-hover；可显式传 false 关掉 | Hover color plus a pointer cursor, using --dshpc-card-hover; defaults to on when onClick is set, pass false to disable |
+| `hoverScope` | `'head' \| 'card'` | 'head' | 'head'（默认）只有头部区变色并可点、展开区完全不受影响；'card' 整卡含展开区一起变色、一起可点。变色只在 hover 开时生效 | 'head' (default) limits both color and clicks to the header block, leaving the expanded area untouched; 'card' includes it in both. Color applies only when hover is on |
 | `filled` | `boolean` | 'true' | 是否带底色；false 时底透明、边框仍在。默认有底（Card = surface-1 / StripCard = accent 浅底） | Background fill; false makes it transparent while keeping the border. Default on (Card = surface-1 / StripCard = accent tint) |
 | `className / style` | `—` | — | 追加类 / 样式；`style.padding` 摊成四根内距轴，同步头部区与展开区 | Append class / style; `style.padding` expands into the four padding axes so the header and expanded area stay aligned |
 
@@ -397,7 +402,8 @@ import { Card, Chip, StripCard } from 'dsh-plugin-core/ui'
 h(Card, {
   accent: 'warning',
   bar: { side: 'left', inset: 12, gap: 12 },   // 色条可放 left / right / top / bottom
-  hoverable: true,                             // 头部区整块悬停变色（默认关）
+  // 传 onClick 才让卡片可点；hover 默认跟着它开，不用再手写光标与 :hover
+  onClick: () => openTask(id),
   action: h(Button, { size: 'sm', variant: 'ghost' }, '跳过'),
 },
   h('div', null, '标题'),

package/docs/requirements.md

@@ -59,3 +59,7 @@
 ## 6. 发布
 
 npm 公开包（私有包会让用户装插件时配 token）；OIDC 发布，打 `vX.Y.Z` tag 触发，流程见 `AGENTS.md`。
+
+## 更新日志
+
+- 2026-11-08 23:34:50：按文档库规范建立版本元数据与统一目录索引

package/package.json

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