前言¶

DSH 的理念是「一切皆插件」，但实际用起来会发现，日常打磨工作区会牵扯不少零散配置：启动画面长什么样、明暗跟谁走、归档的会话怎么找回、浏览器自动化要不要环境自检、手机画面能不能在右侧栏看、会话跑完了怎么提醒、桌宠要不要开。这些事分属不同模块，逐个找包、逐个装，管理成本并不低。

下面介绍的 j62268781-alt/dsh-toolkit 走的是聚合包路线：一个仓库，九个模块分别开关。由 j62268781-alt 维护，解决的是「DSH 界面定制与工具管理过于分散、开关不统一」的问题。插件目录页显示星标 1，规模很小，属于个人维护的社区项目。

这是什么¶

一句话定位：dsh-toolkit 是一个 DSH 插件聚合包，把界面定制（启动动画、外观主题、归档）与工具管理（浏览器自动化、决策服务、移动设备、Skills/MCP、通知、桌面宠物）放进设置面板和右侧栏，安装后可在插件管理中按模块启停。

它不替代包管理工具，也不发布到 npm；当前支持把构建后的本地仓库目录作为 bundle 安装。九个模块各自有独立包名，需要时也可以单独安装其中某一个。

九个模块分别做什么¶

几个模块的边界值得先看清：

• 启动画面提供三款动画：经典描摹、跃浪成标、鲸跃归海，时长固定为 2.4 / 2.9 / 4.5 秒，不支持自定义秒数。
• 桌面主题把明暗和主题分开选：浅色 / 深色 / 跟随系统控制明暗，原始 DSH / Codex / 大海蓝鲸 / 昼夜流光控制主题。Codex 使用自己的工作区布局，其他三款基于 DSH 原始布局；大海蓝鲸与昼夜流光的动态场景只出现在主工作区空白新会话中。
• 浏览器自动化复用 agent-browser CLI 与 Chrome / Chromium，提供环境自检与可选的自动决策，不替你安装这些外部工具。
• 移动设备需要 mobilecli；Android 额外依赖 adb，iOS 需要设备代理与设备端授权。
• Skills / MCP 需要目标运行时、技能目录权限及宿主 Loader / MCP 服务，第三方服务器的连接和授权仍受其自身条件影响。
• 还有八个设置页的侧边栏图标由各模块分别提供（启动=火箭、浏览器=地球、判断=天平、通知=铃铛、桌宠=爪印、外观=调色盘、归档=收纳盒、Skills & MCP=插头），用 currentColor 绘制，跟随侧边栏文字色与高亮，并覆盖原生齿轮图标。

安装与启用¶

插件要求 Node.js ≥ 20 与 pnpm 11.28.5。先从源码构建：

git clone https://github.com/j62268781-alt/dsh-toolkit.git
cd dsh-toolkit
pnpm install
pnpm build

这一步生成九个模块各自的 Host、Client 和运行资源。仓库目录要保留，本地安装会使用这里的工作区依赖。

DSH 桌面端不在命令行里改 profile，而是在 DSH 中请助手安装构建后的仓库根目录：

请把 /absolute/path/to/dsh-toolkit 安装为当前 DSH profile 的插件包，并启用聚合包。

安装完成后，插件管理里会出现「DSH 工具箱」和九个组件开关，只启用需要的功能。桌面宠物与灵动岛还要在自己的设置页里分别开启，初始都是关闭的。Host 代码更新后需要重启 DSH，再刷新页面加载 Client。

自行用 CLI 启动的 profile 用命令安装同一份构建目录：

dsh plugin --profile web add /absolute/path/to/dsh-toolkit

把 web 换成你的 CLI profile 名称。需要单个模块时，可以把已构建的 packages/<module> 目录作为独立 bundle 安装。

如果已经装了九个独立模块，切换路径是这样的：先备份目标 profile 的清单、锁文件和配置，再让 DSH 助手安装聚合包、移除九个独立 bundle 安装项、启用聚合包。聚合包保留相同的模块条目 ID，已有配置与组件开关继续生效。注意别同时启用聚合包和同名模块的独立 bundle，否则会重复声明。

典型用法¶

配置启动动画与外观¶

在设置中选择动画和主题即可，设置页顶部提供实际启动场景预览。三款动画的固定时长不提供配置项，选择后保存即可；如果系统开启了减少动态效果偏好，插件会遵循。切换主题时会同步回收上一款主题的样式。

会话通知¶

在「设置 → 通知」里分别控制完成、失败、等待回答、需要授权四种提醒，并选择声音；系统通知权限在此页检查和申请。

行为上按窗口状态分两条路：窗口在后台或隐藏时走系统通知，点击通知返回对应会话；窗口正在前台使用时改为右上角提醒卡片，点卡片切到对应会话（失败会在卡片上说明原因），8 秒后自动消失，也可以用 Esc 关掉。已归档的会话会先恢复再打开。

桌面宠物与灵动岛¶

1. 打开「设置 → 桌面宠物」，从四套内置形象中选择。
2. 开启「显示悬浮宠物」或「显示灵动岛」，也可以先点「准备桌面运行时」。首次使用需要联网下载 Electron，准备失败时页面会显示原因并提供重试。
3. 按需调整宠物大小、会话气泡宽度、灵动岛收起尺寸，以及是否在其他显示器上同步显示。

两种窗口共用所选形象，开关和尺寸分别保存。悬浮宠物可以拖动；多个显示器上的灵动岛共享会话内容，各窗口的悬停与展开独立响应。窗口由插件自动启动和管理，不需要另开桌宠软件。macOS 通过 AppKit 的真实安全区域数据识别刘海并定位灵动岛，其他平台使用独立的屏幕顶部胶囊布局。

迁移旧单体配置¶

如果从更早的 shell-kit 单体配置升级，先对目标 profile 的配置文件生成预览：

pnpm migrate:config /absolute/path/to/profile/cordis.patch.yml

确认预览后再写回：

pnpm migrate:config /absolute/path/to/profile/cordis.patch.yml --write

命令不会自动选择当前 profile。写入前会创建带时间戳和 UUID 的备份；已有模块配置优先，旧总开关状态会分别保留到九个模块。冲突别名或不安全的 YAML 结构会拒绝自动迁移。从九个独立 bundle 切换到聚合安装不需要跑这个迁移。

工作原理与验证¶

一个仓库同时提供聚合 bundle 和九个模块包。布局如下：

src/modules/<module>/   模块源码
src/host/               公共 Host 逻辑
src/client/             公共 Client 逻辑与样式
packages/<module>/      各模块包的入口、清单与构建产物
cordis.patch.yml        聚合包声明九个模块条目

Host 运行在 Harness 进程中，负责工具、配置与鉴权路由；Client 运行在 DSH 页面里，注册设置页、侧栏和交互。组件开关同时管理该模块的 Host 与 Client。DSH 核心包以可选 peer 声明，由宿主提供。

桌宠运行在独立的 Electron 辅助进程中：通过本机回环连接接收 Host 状态，由辅助进程创建透明置顶窗口，随插件退出，不修改 DSH 安装文件，也不依赖 DSH 私有 Electron IPC。

开发验证在仓库根目录运行：

pnpm install
pnpm verify

pnpm verify 依次执行构建、TypeScript 检查、契约检查、测试与产物一致性检查。修改源码后重新构建，Host ESM 改动需重启 DSH。测试默认跳过真实设备发现，真实 Skills/MCP patch 测试需要显式设置 SMP_REAL_PATCH。

适用场景与注意¶

适合这些情况：想把 DSH 的界面定制和工具管理收敛到设置面板统一开关；需要把手机画面放进右侧栏；会话在后台跑完希望能收到提醒而不是一直盯着窗口；想在桌面上挂一个能反映会话进展的宠物或灵动岛。

用之前需要确认几件事：

• 插件以当前 DSH 进程权限运行，安装前应先检查源码与许可证。代码采用 MIT，桌宠内置的四套程序绘制素材各自声明为 CC0-1.0；未使用 Qoder 官方宠物美术或 dsh-pet 的受限素材。
• 浏览器玩具依赖外部 CLI 与浏览器，移动设备依赖 mobilecli / adb，这些需要自行准备，插件不代装。
• 系统通知受操作系统权限与桌面环境限制；桌宠要求 Host 运行在有图形桌面的本机，远程或无图形 Host 无法把窗口显示到浏览器所在的电脑。
• 插件加载前已经等待的批准、历史失败状态无法完整恢复；新产生的批准和问题会显示为待处理。当前桌宠未接入官方在线 Petdex、语音输入或触觉反馈。
• 目录页显示该仓库星标 1，属于新项目，功能边界仍在演进，接入生产前建议先在预发布 profile 验证。

结尾¶

dsh-toolkit 的价值在于把九个零散能力收到一个聚合包里，统一安装、统一开关、统一入口，需要哪一档开哪一档。它不改变 DSH 的插件机制，只是把重复的配置工作集中了。

目录页：https://www.skillhub.cn/plugins/j62268781-alt/dsh-toolkit
仓库：https://github.com/j62268781-alt/dsh-toolkit