侧边栏 DIY 布局 G57651/dsh-diy-layout

dsh-diy-layout · 侧边栏 DIY 布局

一个 DeepSeek Harness 客户端 UI 插件：无需修改 Harness 任何源码，即可自定义主页侧边栏「全局面板」（插件入口列表）的展示方式与排列布局。

- 单栏 / 双栏排列
- 图标+名称 / 仅图标（仅图标时鼠标悬浮显示插件名称 Tooltip）
- 逐条目排序（上移/下移）
- 逐条目显示/隐藏
- 配置持久化在浏览器 localStorage（dsh.diy-layout.v1），重启应用后仍然保留
- 明暗主题自动适配（全部使用官方 --dsw-alias- 设计令牌）

使用方法

安装后（见下），打开 设置 → 侧边栏 DIY 布局：

| 配置项 | 说明 |
| 布局模式 | 单栏（默认）/ 双栏（按侧边栏宽度自动分列） |
| 名称显示 | 图标 + 名称（默认）/ 仅图标——悬浮图标 500ms 后显示名称气泡 |
| 插件排列与显示 | 每个侧边栏插件一行：↑ 上移、↓ 下移、开关 = 在侧边栏显示/隐藏 |
| 恢复默认 | 清除排序与隐藏记录（布局模式与名称显示保留） |

折叠侧边栏（56px 图标栏）有自己的官方图标态与 Tooltip，本插件不干预其中；隐藏与排序在折叠栏中保持一致。

安装（bundle 通道，推荐）

方式 A · Release 安装包（从 Releases 下载或直接用 URL）：

dsh plugin --profile <你的 profile> add \
https://github.com/G57651/dsh-diy-layout/releases/latest/download/dsh-diy-layout-0.1.0.tgz
例如桌面版：dsh plugin --profile desktop add <上面的 URL>（或经应用内插件管理器安装）

方式 B · GitHub 仓库直接安装（仓库内已含构建产物 lib/，无需授权构建脚本）：

dsh plugin --profile <你的 profile> add github:G57651/dsh-diy-layout

安装后重启 Harness（桌面 App 或 dsh web）即生效。卸载：dsh plugin --profile <profile> remove dsh-diy-layout。

本地试跑（不改 profile）：

dsh web --patch ./test/diy-layout.local.patch.yml # patch 内为插件 lib/index.js 的绝对路径

实现原理（为什么零侵入）

Harness 的侧边栏由 ui-sidebar 的 SidebarRoot 渲染，插件入口来自 sidebar.panellist list slot（每个 entry 的组件即图标，行按钮/标签由 shell 渲染）。slots 系统不授权重排或替换他人的行 DOM，因此本插件采用三条官方增量通道：

1. 注入式样式：apply 侧维护一个 ，订阅「配置 store + sidebar.panellist 台账 + locale」重新生成规则。选择器锚定 DSH CSS Modules 的 [hash]_<local> 编译模式（如 hHd-Xa_panelRow），用 [class="_panelList"] 等属性选择器定位；双栏=容器 grid、仅图标=隐藏标签 span、隐藏=display:none、排序=flex/grid order（nth-child 键接自然 DOM 位次，与 ui-sidebar 的投影算法一致）。选择器匹配不到时插件静默失效，不可能破坏 UI。
2. 悬浮 Tooltip：注册进 shell.overlay（官方加法式浮层），document 级委托监听，对「标签 span 被样式隐藏」的行延迟 500ms 显示气泡（createPortal 到 body，样式逐值复刻官方 Tooltip.module.css）。折叠 rail 的行没有标签 span，继续走 shell 自带 Tooltip，不会出现双重气泡。
3. 设置页：注册 settings.section（id diy-layout），控件全部来自 ui-primitives。

不做的事：不注册/遮蔽任何已存在的 slot entry，不改 DOM 结构，不 import 其他插件代码。侧边栏宽度调节未实现——ctx.layout 不暴露宽度写入（需求项为可选，强改会与拖拽/clamp 逻辑冲突）；侧边栏宽度请用自带拖拽手柄。

兼容性

- 锁定 dsh >= 0.2.0-rc.1（在 0.2.0-rc.2 上开发并测试）。DSH 处于 developer preview，升级后若类名/结构变化，样式锚点失效表现为「布局功能不生效」，不影响原 UI。
- 新装第三方侧边栏插件自动纳入排序/隐藏/双栏；其卸载后残留的记录惰性存在，可用「恢复默认」清除。
- 已知取舍：CSS order 改变视觉顺序，Tab 焦点顺序仍按 DOM 序（条目个位数时影响极小）；display:none 的行同时移出 Tab 序与无障碍树。

开发

pnpm pack 之前先构建：使用 Harness 仓库工具链
<repo>/node_modules/.bin/tsdown # 产出 lib/index.js + lib/client.js <repo>/node_modules/.bin/tsc -p tsconfig.json # 类型检查（paths 指向 0.2.0-rc.2 类型）

源码结构：

src/index.ts # Node 半（Loader 加载，空 apply） src/client/index.tsx # apply：词典/存储/样式/投影/两个 slot 注册 src/client/store.ts # defineStore（persist: dsh.diy-layout.v1） src/client/sidebar-css.ts # CSS 生成器（锚点 + 规则） src/client/tooltip-overlay.tsx src/client/settings-page.tsx src/client/locales.ts # zh/en docs/ANALYSIS.md # 阶段一分析与阶段二方案 test/fixture-panels/ # 测试夹具：4 个额外侧边栏插件入口（非交付物）