前言¶

DSH 的理念是「一切皆插件」，插件多了，設置界面也會跟着多起來。給插件寫設置界面是一件重複勞動：組件要自己寫，樣式要自己調，還要處理 load / save / busy / error / saved 提示、revision 衝突這一整套狀態邏輯。每個插件各寫各的，風格和官方設置頁對不上，用戶在不同插件之間來回切換時體驗也是割裂的。

dsh-settings-ui 解決的就是這個問題：它把設置頁 UI 和狀態邏輯抽成一個可複用的服務，插件通過 ctx.settingsUi 拿到現成的組件、聲明式表單和設置狀態機，不必再手寫 UI。下面介紹它的定位、功能和用法。

這是什麼¶

dsh-settings-ui 是一個面向 DeepSeek Harness 插件的統一設置頁 UI 套件加浮層面板套件，由 KaramachiA217 維護，MIT 許可證，倉庫附 LICENSE 文件。從 package.json 的 dsh.client.platform 字段看，它面向 web 平臺。

它對外暴露 ctx.settingsUi 服務，其他插件用這個服務構建設置區塊和浮層面板，風格與 dsh-better-sidebar 及 --dsw-* 語義令牌對齊——不需要自己寫組件、CSS，也不需要自己處理 load / save / busy / error / saved / revision 衝突的狀態邏輯。

核心功能¶

三級 API¶

• ui.pluginCard()：rc7 官方 Plugins 標籤頁的插件配置卡片，經官方 ctx.settingsScope 持久化；
• ui.section()：經典設置頁卡片；
• ui.overlay() / ui.Panel / createPanelStore：自由浮層，支持拖拽、最小化、z-order、位置持久化，經 storage 事件跨標籤頁同步。

原子組件族¶

套件提供一組原子組件：SectionHeader / Field / TextInput / TextArea / Select / Button / Switch / Checkbox / Radio / Card / StatusDot / Badge / Spinner / Tabs / Banner / EmptyState / List / Dialog / ErrorBoundary / toast。

聲明式表單¶

Rows 渲染字段描述；createSettingsStore + useSettings 處理 load / save / busy / error / saved-flash / revision 衝突，後端可跑在 fenced route 或官方 settingsScope 上。

向後兼容與自愈¶

向後兼容：這個插件只新增服務，直接 ctx.slots.inject('settings.section', ...) 的舊用法不變。

自愈能力：section() / overlay() / pluginCard() 自動包裹錯誤邊界，單個卡片渲染崩潰只摺疊該卡片，不影響整個設置頁。

與官方契約對齊¶

套件只通過官方槽位/服務註冊（settings.plugin.item / settings.section / shell.overlay / settingsScope / locale），.sui-* 樣式從 --dsw-* 令牌解析，不導入官方卡片 chrome（value-import purity gate），自己渲染令牌對齊的外殼並自持表單、狀態與可訪問性。pluginCard 的 chrome 默認採用官方卡片模型：collapsed layer-3 → expanded layer-2、disclosure header、字段分隔線、discard/save footer。

安裝與啓用¶

先做安裝。用官方 CLI 一步完成：添加依賴，reconcile 後追加到 dsh.profile.bundles：

dsh plugin --profile <profile-name> add dsh-settings-ui

後續升級用同一命令加 @latest 後綴即可。

再把它加入 profile bundles。host 已提供 peers 時，消費者不需要把它聲明爲 peer dependency。下面是 README 給出的示例，dependencies 裏的版本號按實際情況填寫：

{
  "dependencies": { "dsh-settings-ui": "^0.2.22" },
  "dsh": { "profile": { "bundles": ["dsh-base", "dsh-web-app", "dsh-settings-ui", "..."] } }
}

一個安裝時的小坑：pnpm v11 的 minimumReleaseAge 供應鏈冷卻機制，會讓全新發布後 24 小時內的安裝靜默回退到上一版本。可以在 profile 的 pnpm-workspace.yaml 里加 minimumReleaseAge: 0，或者等一天再裝。

本地開發時，先用 npm pack 構建 tarball，再用同一命令從本地安裝，也可以用 file: 依賴：

npm pack
dsh plugin --profile <profile-name> add ./dsh-settings-ui-<ver>.tgz

注意 rc.6 下的已知差異：link: 開發掛載會 ESM 解析失敗，需改用 file: tarball。

典型用法：pluginCard()¶

rc7 下，官方給插件設置的推薦路徑是 Plugins 標籤頁的配置卡片（按 settings 命名空間 keyed 的 settings.plugin.item 槽位），經官方 ctx.settingsScope 持久化。pluginCard() 在這個契約之上提供帶套件外殼的卡片，不用手寫 scope 綁定和狀態邏輯：

const card = ctx.settingsUi.pluginCard({
  key: 'my-plugin',                 // 必填，等於 settings 命名空間，也是標籤頁 key
  header: { title: '我的插件', desc: '一句話說明' },
  fields: [
    { key: 'enabled', type: 'switch', label: '啓用' },
    { key: 'endpoint', type: 'text', label: '服務地址' },
  ],
})
// card.store.setField('enabled', true)

調用之後不需要再做別的：store 內部調用 ctx.settingsScope.bind({ namespace: key })，每次修改經官方 revision fence 即改即存。

幾個可選項：

• content: (ctx) => ...：完全自定義主體；
• showIn: 'both' / 'settings-page'：讓卡片同時在經典設置頁露出；
• chrome: 'minimal'：去掉套件的卡片外殼。

關於家族單軌：新的設置卡片建議優先用 pluginCard()（官方 Plugins 標籤頁），避免一半在設置頁、一半在 Plugins 標籤頁的家族分裂。section() 對既有消費者和 rc6 / headless 環境繼續完全支持，已經在用的不需要遷移。

兼容性與環境要求¶

• 已在 dsh 0.1.0-rc.5（官方桌面 shell、完整 profile 測試）驗證；
• rc.6 已驗證（2026-08-17）：rc.5 與 rc.6 共享同一上游提交 47f9438，僅 npm 版本號變化，零適配；
• rc.7（0.3.0，2026-08-20）已適配：pluginCard() 面向 keyed settings.plugin.item 槽位 + 官方 ctx.settingsScope；經典面（settings.section / settings.general.item / shell.overlay）在 rc.7 不變，section() / overlay() 繼續可用。

依賴方面：peerDependencies 爲 @deepseek-ai/cordis >=4.0.0-rc.0、@deepseek-ai/dsh-client-runtime >=0.1.0-rc.0、@deepseek-ai/dsh-client-ui-slots >=0.1.0-rc.0、react ^18.2.0；engines 要求 node >=20；dsh.client.platform 爲 web，會 inject 三個 @deepseek-ai 客戶端運行時/UI 包。

已知限制：同一頁面掛載多個 ToastHost 會顯示相同的 toast，每頁只應掛載一個 host。範圍外（官方契約限制）：並行側邊欄席位（sidebar.workspaces / sidebar.settings 爲單例）和淺色主題。

開發與質量門禁¶

如果要參與開發或本地驗證，倉庫提供三步命令：

pnpm install
npm run ci
npm test

npm run ci 是 5 步門禁：語法 + 單元測試 + 密鑰掃描 + 淨化 + pack 白名單；npm test 基於 node:test，共 45 個單元測試。

Roadmap 方面：1.0.0 計劃提供 ui.describeForm，消費官方 settings.describe 的 schemastery schema 自動渲染表單，支持 redactSecrets 只寫輸入與 revision 衝突處理；工程上計劃對 .d.ts 與實現的漂移做自動檢查；維護承諾是上游 rc 漂移時重跑 contract-diff 方法論，反饋走 GitHub discussions。

適用場景與注意事項¶

適合誰：要給自己的 DSH 插件加設置界面、但不想手寫組件和狀態邏輯的插件作者；希望多個插件的設置風格保持一致、並跟隨官方設置頁演進的場景。

安裝前必須清楚一點：插件以當前 dsh 進程的權限運行，裝一個插件等於把它的代碼跑進你自己的環境。dsh-settings-ui 是 MIT 許可證，源碼公開在 GitHub，安裝前應自行檢查源碼與許可證，確認可信再裝。

小結¶

dsh-settings-ui 把 DSH 插件設置界面裏重複的部分——組件、樣式、狀態機——收進一個 ctx.settingsUi 服務：三級 API 覆蓋從官方 Plugins 卡片到經典設置頁再到自由浮層的需求，與官方契約對齊、向後兼容，單個卡片崩潰也不會拖垮整個設置頁。如果你在寫帶設置的 DSH 插件，可以直接從 pluginCard() 試起。

• 社區插件目錄頁：https://www.skillhub.cn/plugins/KaramachiA217/dsh-settings-ui （獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）
• GitHub 倉庫：https://github.com/KaramachiA217/dsh-settings-ui