前言¶

在 DSH（DeepSeek Harness）里做客户端插件时，常见做法是在界面某处挂一个入口按钮。多个插件各自占一块区域，容易显得零散，也和侧栏、标题栏工具条抢位置。社区里已有 dsh-quick-toolbar 聚合标题栏按钮、dsh-sidebar-icon-row 调整侧栏行内图标等方案，但它们要么面向工具条适配器，要么绑定侧栏布局。

dsh-icon-grid（维护者 Boris-boomer，分类：客户端）提供的是与场景、皮肤无关的浮动图标网格：外部插件通过全局注册表推入图标，本插件只负责排列、持久化、拖拽排序和设置面板，配色跟随 DSH 当前主题的 CSS 变量，不依赖单独的皮肤插件。

这是什么¶

一句话定位：把插件入口收进可拖拽排序的浮动网格的 DSH 客户端插件。

本插件不实现各插件的业务逻辑，只维护「注册表 → 槽位」的映射。与 dsh-plugin-namecards（官方插件页展示）职责不重叠；与 dsh-bot-mode 里写死在 Bot 场景的图标网格相比，这里是通用容器。

与其它 DSH 插件的边界¶

• dsh-plugin-namecards：管理 DSH 官方插件页的图标、分组与排序；本插件管理的是任意插件通过 window.__dshIconRegistry 注册的自定义入口。
• dsh-sidebar-icon-row / dsh-agent-grid：调整侧栏布局；本插件是独立浮动网格，不修改侧栏。
• dsh-quick-toolbar：聚合标题栏或悬浮球上的按钮；本插件聚合的是图标入口，并用网格排列。
• dsh-bot-mode：Bot 列表网格绑定 Bot 场景；本插件场景无关。

核心功能¶

下面介绍 README 中已列出的能力。

1. 布局：浮动在输入框右侧；空间不足时自动贴屏幕右边。依赖 DSH DOM 标记 [class*="BynINW_centerCol"]、[data-composer-card] 对齐，找不到时回落到贴右边方案。
2. 交互：拖拽交换格子；越界时保护 +N 溢出格。右键非内建图标可打开或卸载插件。内建 ⚙️ 打开设置面板。无外部图标时，第一个空槽显示半透明 ＋ 提示。
3. 设置面板：列数、行数、格子大小、间距、图标底色、边距、网格线开关与深浅、图标主色。
4. 持久化：localStorage 兜底，DSH settings 为主存储，宿主广播实时同步。首次启动可从旧 dsh-ui 命名空间迁移 iconGrid 配置。
5. 排序：外部图标支持 weight 字段，越大越靠前；内建 ⚙️ 永远排在最前。

当前未实现项（安装前宜知晓）：图标远超可见槽位时无虚拟滚动，只能通过 +N 或设置调大行列；移动端长按拖拽与右键菜单未验证；多端下同账号以本地 localStorage 优先，可能覆盖远端设置直至清空本地。

兼容性与版本¶

• Node.js ≥ 18（推荐 20）
• DSH 宿主 ≥ 0.2.0-rc.1（声明在 package.json 的 engines.dsh）
• 插件包版本：0.1.0（资料中的 package.json）
• 许可：MIT License

安装与启用¶

安装步骤以仓库 README 为准。下面是从源码构建并挂载到宿主的流程（具体挂载路径取决于 DSH 版本，见宿主文档）：

git clone <repo> dsh-icon-grid
cd dsh-icon-grid
pnpm install
pnpm check      # typecheck + lint + test
pnpm build      # tsdown → lib/client.js

构建产物为 lib/client.js；package.json 中 dsh.client.inject 为 dsh-icon-grid，与 cordis.patch.yml、构建 banner 的 id 需保持一致（开发约束见仓库说明）。

DSH 插件在当前 dsh 进程权限下运行。安装前应自行查看源码与 MIT 许可证，确认符合你的环境与安全要求。

典型用法¶

命令行¶

• dsh-icon-grid — 查看当前网格状态
• dsh-icon-grid grid <cols> <rows> — 设置网格行列（列 3–16、行 2–24）

设置面板¶

点击网格右下角 ⚙️ 图标，打开图标网格设置面板。

外部插件接入¶

其它 DSH 插件向全局注册表推入条目即可出现在网格中：

window.__dshIconRegistry ??= []
window.__dshIconRegistry.push({
  id: 'my-plugin',
  icon: '🚀',              // string 或 number，必填
  label: '我的插件',
  weight: 0,               // 可选，越大越靠前；相同 weight 保持注册顺序
  onClick: () => { /* 打开插件 */ },      // 可选，必须是函数
  onUnload: () => { /* 卸载回调 */ },     // 可选，必须是函数
})

readRegistry() 会过滤无效条目：id 非非空字符串、icon 非 string/number、或 onClick / onUnload 存在但不是函数。调试时可直接查看 window.__dshIconRegistry。

配置命名空间¶

单一命名空间 dsh-icon-grid：

{
  iconGrid: {
    order: [],            // 图标 id 排列（'' 为空槽）
    cols: 8, rows: 12,
    cell: 46, gap: 6,
    iconAlpha: 0.08,
    gridAccent: '',       // ''=跟随明暗半透明；'#rrggbb'=主色着色
    marginRight: 24, marginBottom: 24,
    showGridLines: true,
    gridLineAlpha: 0.15,
  },
}

主题色不读皮肤 token 表，由浏览器解析 DSH 当前 CSS 变量（如 var(--dsw-alias-label-primary, ...) 等）；gridAccent 可用 color-mix 着色图标底色。

适用场景与注意¶

适合需要在输入区旁集中展示多个插件图标、并希望自己拖拽排序、行列与样式的 DSH 用户与插件作者。若你主要整理的是官方插件目录页，应使用 dsh-plugin-namecards；若只改侧栏或标题栏工具条，应选对应侧栏/工具条插件。

注意 DSH 大版本若改动上述 DOM 选择器，网格对齐可能暂时只使用贴边兜底；长列表与多端配置同步的限制见上文「当前未实现」。

结尾¶

dsh-icon-grid 用注册表 + 浮动网格的方式，把分散的插件入口收成一块可配置的 UI，并与 DSH 主题变量对齐，适合作为其它客户端插件的图标壳层。

• 社区目录页：https://www.skillhub.cn/plugins/Boris-boomer/dsh-icon-grid
• 源码与文档：https://github.com/Boris-boomer/dsh-icon-grid

社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库与目录页实时信息为准。