dsh-whale-widget-dock

dsh-whale-widget（小鲸鱼桌宠）的伴生插件：让桌宠跟着 DSH 右侧 Sidebar 走。

右栏状态	桌宠位置
展开	右缘紧贴右栏左缘（gap 默认 0，可配）
折叠	右缘紧贴窗口右缘（edgeGap 默认 24，沿用挂件原来的右边距）
右栏拖动改宽	实时跟随，不做过渡跳变
锁定	强制保持"右侧吸附"，并压制挂件贴左时的整只镜像翻转

只改 dsh-whale-widget 的定位与吸附表现，不改它的任何文件。卸载本插件后挂件立刻恢复原样。

安装

方式一：脚本（推荐）

pwsh -File .\install.ps1

脚本会：

1. 把本目录复制到 %DSH_HOME%\local-plugins\dsh-whale-widget-dock
2. 在 profiles\desktop\node_modules 里建一个指向它的目录联接
3. 在 profiles\desktop\package.json 的 dependencies 与 dsh.profile.bundles 里登记
4. 改动前自动备份 package.json

装完必须重启 DSH Desktop（宿主只在启动时收集一次 Web 外壳注入表）。

卸载：

pwsh -File .\install.ps1 -Uninstall

方式二：手动

1. 把本目录放到 %DSH_HOME%\local-plugins\dsh-whale-widget-dock

2. 在 %DSH_HOME%\profiles\desktop\package.json 里加：

   "dependencies": {
     "dsh-whale-widget-dock": "link:../../local-plugins/dsh-whale-widget-dock"
   },
   "dsh": { "profile": { "bundles": [ "…", "dsh-whale-widget-dock" ] } }
   

3. 确保 profiles\desktop\node_modules\dsh-whale-widget-dock 能解析到该目录（联接或直接复制都行）

4. 重启 DSH Desktop

使用

• 菜单开关：打开挂件主菜单（菜单按钮 / 右键 / 长按小鲸鱼），在「吸附与翻转」下一行勾选 吸附到右栏。 取消勾选即解除接管，位置控制权完整交还给挂件自己。
• 快捷键：Ctrl + Alt + L（macOS 为 ⌘ + Alt + L）。
• 默认锁定（locked: true），即开箱就是"永远贴右边缘"。
• 锁定状态存在 localStorage，刷新与重启后保持。

配置

在开发者工具 Console 里：

// 查看
__dshWhaleDock.config
// 展开时留 6px 间隙、折叠时贴死（0）；负值表示再往里压几个像素
__dshWhaleDock.set({ gap: 6, edgeGap: 0 })
// 解锁 / 上锁
__dshWhaleDock.locked(false)
// 立即重算一次
__dshWhaleDock.refresh()

键	默认	说明
locked	true	锁定右侧吸附；解锁后完全交还给挂件自己
gap	0	展开时，桌宠右缘与右栏左缘的间距（px）；允许负值微调
edgeGap	0	折叠时，桌宠右缘与窗口右缘的间距（px）；0 = 贴死，允许负值
writeWidgetPos	true	同步把 localStorage['dshw-pos'] 写成 hAnchor: "right"，让挂件自己的吸附模型也一致

持久化位置：localStorage['dsh-whale-widget-dock:v1'] （改名前 dsh-pet-sidebar-anchor:v1 / v2 的配置会自动迁移：旧 v1 里仍是旧默认值 24 的 edgeGap 会被改成 0，其余字段原样保留）。 挂件原有位置会被备份到 localStorage['dsh-whale-widget-dock:pos-backup']（只在第一次写入时备份）。

工作原理

• 横向定位软接管：挂件的 express() 只写内联 style.left/top 和 dshwv-left 类，没有 ResizeObserver。 本插件注入一条 .dshwv-root.dshwd-anchored { left: var(--dshwd-left) !important } 规则—— 作者样式表里的 !important 优先级高于内联普通声明，所以挂件怎么写内联 left 都压不过它； 移除 dshwd-anchored 类即完整归还控制权（解锁走的就是这条路）。
• 右栏左缘从哪来：@deepseek-ai/dsh-client-ui-sidebar-right 的面板带 [data-sidebar-right-panel="push"][data-sidebar-right-open] 标记，且 position: absolute; right: 0， 所以它的 getBoundingClientRect().left 就是右栏左缘。 兜底链条：原生右栏面板 → [data-dsh-center-col] 右缘（better-sidebar 的标记）→ 窗口右缘。
• 跟随时机：右栏面板挂 ResizeObserver（拖宽实时）+ MutationObserver（展开/折叠属性变化）； DOM 级 MutationObserver 兜住面板与桌宠的挂载/卸载；另有 500ms 低开销轮询兜底。
• 菜单开关：复用挂件自己的 .dshwv-menu-row / .dshwv-check 样式，插在「吸附与翻转」下一行； 挂件若重建菜单，下一次 tick 会把这一行补回去（data-dsh-whale-dock="menu-row" 是它的标记）。

排查

• 重启后桌宠没动静：确认 profiles\desktop\package.json 的 dsh.profile.bundles 里有 dsh-whale-widget-dock，且 node_modules\dsh-whale-widget-dock\package.json 可读；然后完全退出 DSH Desktop 再启动。
• Console 里 __dshWhaleDock 是 undefined：宿主没把脚本注入进来（注入表只在启动时收集，必须重启）。
• 贴的位置差几个像素：桌宠的可见图像四周有透明留白，"贴死"是按元素盒子算的；用 gap 微调。
• 想完全恢复原状：__dshWhaleDock.locked(false) 立即归还控制权；或卸载插件后 localStorage.removeItem('dsh-whale-widget-dock:v1')，必要时把 localStorage['dsh-whale-widget-dock:pos-backup'] 写回 localStorage['dshw-pos']。

兼容性

• 依赖 dsh-whale-widget 的 .dshwv-root 根节点（该插件也会把节点暴露为 window.__dshWhaleRoot）。
• 依赖右侧 Sidebar 的 data-sidebar-right-panel / data-sidebar-right-open 标记（DSH 0.2.x）。 标记缺失时退化为"贴窗口右缘"，不会报错。