前言¶
DeepSeek Harness（DSH）把能力拆成插件，但 macOS 桌面上的 WidgetKit 小組件跑在系統宿主裏，既不能直接用 dsh-app://，也拿不到 DSH 頁面的會話 Cookie。若每個業務插件各自實現一套橋接和原生擴展，重複工作多、接口也難統一。
dsh-macos-widget（維護者 LXD-8）是社區插件目錄中的客戶端類基礎設施：它本身不定義小組件外觀，只負責註冊表、本機橋接和通用的 WidgetKit 伴侶應用；具體樣式由註冊方插件通過 style 字段提供。下面介紹其定位、組成與安裝用法。
這是什麼¶
一句話：DSH 的 macOS 桌面小組件基礎設施——展示其他插件註冊的小組件樣式，自身沒有獨立 widget。
- 倉庫：LXD-8/dsh-macos-widget
- 目錄頁：skillhub.cn 插件頁
- 包版本（
package.json）：0.1.0，許可證 MIT
用戶在 Settings → macOS Widgets 裏選擇要展示的已註冊插件；WidgetKit 伴侶在下次時間線刷新（約 15 分鐘）時渲染該選擇。文檔中的 quota-windows 是第一個示例，並非本插件硬依賴。
核心功能¶
三層分工¶
| 部分 | 文件 | 作用 |
|---|---|---|
| Host | index.js |
註冊服務 ctx.macosWidgets；固定迴環橋 127.0.0.1:47823（GET /widgets、GET /widget、GET /widgets/<id>）；DSH Host 上 GET /macos-widget/api/status 與 POST /macos-widget/api/select |
| Web | client.js |
Settings → macOS Widgets：橋狀態、已註冊小組件列表與當前選中項 |
| Native | macos/ |
SwiftUI 宿主 + 通用 WidgetKit 種類「DSH 小組件」（小 / 中 / 大），讀取所選 payload |
橋接刻意保持最小面：僅迴環、僅 GET、無憑證——因爲擴展在系統 widget 宿主中運行，在 DSH 頁面之外。
插件契約¶
任意 Host 插件可向 macosWidgets 註冊小組件；外觀歸屬註冊方，通過 read() 返回的數據裏的 style 描述。示例（摘自 README，quota-windows）：
ctx.inject(['macosWidgets'], (scope) => {
scope.effect(() => scope.macosWidgets.register({
id: 'quota-windows',
title: '額度窗口',
subtitle: '訂閱與餘額狀態',
read: async () => ({
title: '額度窗口',
subtitle: '訂閱與餘額狀態',
updatedAt: new Date().toISOString(),
style: { layout: 'list', accent: '#4D6BFE', background: null, showUpdated: true },
sections: [{
id: 'opencode',
title: 'OpenCode',
subtitle: 'Go 訂閱',
accent: '#10B981',
rows: [{ label: '本月', value: 44, max: 100, unit: '%', detail: '重置 3 天后' }],
}],
}),
}), 'quota-windows: macOS widget')
})
style 字段含義（模板化，非 per-plugin 完全自定義視圖）：
| 字段 | 含義 |
|---|---|
layout |
list（分區與行）或 single（單一最緊值） |
accent |
分區標記回退色 #RRGGBB |
background |
可選卡片背景 #RRGGBB |
showUpdated |
標題區是否顯示更新時間 |
分區與行可覆蓋 accent；行的 detail 爲自由文本。原生側不按具體提供方寫死 UI。
選擇與持久化¶
在 Settings → macOS Widgets 中點擊應出現在桌面上的插件；選擇保存在 Host 橋接側，寫入 $DSH_HOME/macos-widget/selection.json，下次 Host 啓動時恢復。橋接端口固定。
安裝與啓用¶
官方 README 未給出 dsh plugin add github:... 一類命令，安裝按下列步驟（與資料原文一致）：
- 將插件鏈入所用 profile，並在
dsh.profile.bundles中加入dsh-macos-widget。 - 構建 WidgetKit 伴侶（需 Xcode 與
xcodegen）：
bash macos/build.sh
package.json 亦提供 npm run build:widget，內部調用同一腳本。
- 重啓 DSH；在 Settings → macOS Widgets 中應能看到所有已註冊 widget 的插件。
- 桌面右鍵 → Edit Widgets → 搜索
DSH Widgets→ 添加「DSH 小組件」；顯示內容與 Settings 中的選中插件一致。
典型用法小結¶
- 業務插件在 Host 側
injectmacosWidgets並register，在read()裏返回標題、分區、style等結構化數據。 - 用戶在本插件設置頁選定要展示的註冊 id。
- 在 macOS 小組件編輯器添加「DSH 小組件」，等待 WidgetKit 刷新後查看桌面。
適用場景與注意¶
適合誰：需要在 macOS 桌面展示 DSH 插件數據的開發者；願接受模板化 layout + token 樣式，而非在 WidgetKit 內嵌入各插件完整 Web 界面。
運行與信任：插件在 DSH 當前進程權限 下運行；安裝前請閱讀倉庫源碼與 MIT 許可證，自行判斷是否接入生產環境。
已知限制（README）：
- 插件無法在運行時加載 WidgetKit 擴展；擴展隨伴侶應用分發，直至 DSH 自帶捆綁（見 deepseek-harness 討論 #12763）。
- 伴侶爲 ad-hoc 簽名，僅適合本地使用；對外分發需 Developer ID。
- 橋接端口固定；樣式爲模板契約，完全自定義視圖需 Host 側渲染插件 Web 面等額外方案。
結尾¶
dsh-macos-widget 把「誰提供數據與樣式」和「誰負責桌面渲染」拆開：一套迴環橋 + 通用 WidgetKit 種類，業務插件只註冊與 read。進一步瞭解可從 插件目錄頁 進入，或直接查看 GitHub 倉庫 的 README 與 macos/ 構建說明。
