前言¶

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