前言¶
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/ 构建说明。
