DeepSeek Harness Desktop 高级 ShellmacOS 与 Windows 原生材质架构与实现全解析【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop本文是 DSH Desktop「高级模式Advanced Shell」的完整技术指南基于仓库内已落地的架构决策笔记 .agents/notes/implemented/architecture/2026-08-15-desktop-advanced-shell.md 展开。高级模式在不修改 pinned 上游 checkout、不复制官方 Web 应用的约束下为 macOS 与 Windows 提供真正的原生材质呈现macOS vibrancy、Windows Mica。读完本文你将掌握dsh-desktop.mode: advanced的单一配置事实源与重启边界、desktop 自有 Client 组合root slot 与layoutservice 替换、DesktopThemePresenter主题投影机制、两大平台原生窗口材质参数的精确取值以及它的安全边界与验证体系。背景与问题为什么需要「高级 Shell」DSH Desktop 面临一个两难要在 macOS 与 Windows 上提供原生材质native material呈现但有两个硬约束——不能编辑 pinned 上游 checkoutdeepseek-harness子模块保持原样也不能把官方 Web 应用整个复制进 desktop 包。问题在于这种「原生呈现」不是单点改动而是多个维度必须同时变化原生窗口构造BrowserWindow的材质与 chrome 选项root/sidebar slot 的所有权归属layoutservice 的提供方document 级 theme 投影渲染层不再由官方 layout 负责。如果只应用其中一部分或者试图在运行中的 renderer 里热修改Host 组合与 Client 呈现就会不一致。另一个要求是模式选择必须只有一个持久化事实源——无论用户是通过托盘命令切换还是手工编辑 settings 文件都要落到同一个值并跨过同一条重启边界。这一设计在仓库中已标记为Status: implemented对应的 Host/Client 实现集中在dsh-plugin-desktop包中。设计决策总览高级模式Advanced mode是一个完全由 desktop 拥有的 generation由设置dsh-desktop.mode: advanced选中。它仍然复用上游 loopback Web carrierHTTP/WebSocket普通 Client 模块 Loader不引入第二套插件或 transport 系统。它只改变明确由 desktop 拥有的两处 seam呈现presentation与原生窗口native window。作为对照仓库中还存在兼容模式compatibility全官方组成与扩展模式extended可见命令栏窗口高级模式与它们在 窗口选项构造 中分别由compatibilityWindowOptions/extendedWindowOptions/advancedWindowOptions三个独立工厂构建。单一配置事实源settings.yaml中的dsh-desktop命名空间文件、命名空间与 schemasettings.yaml是唯一的事实源。Launcher 通过当前 profile 激活的deepseek-ai/dsh-settings-filerow 解析该文件并在生成最终 Loader patch 之前读取dsh-desktop.mode。它不会在以下任何位置持久化平行模式值profile manifestElectron preference命令行 flag其他 desktop 配置文件。在 Host 侧dsh-plugin-desktop的入口 dsh-plugin-desktop/src/index.ts 通过标准 settings 服务注册了settingsNamespace(dsh-desktop)schema 如下来自 DesktopSettingsSchema字段取值默认值说明modecompatibility|extended|advancedcompatibility原生呈现模式macosMaterialoff|transparenttransparentmacOS 透明/毛玻璃材质偏好windowsMaterialoff|acrylic|micaoffWindows 背景材质偏好acrylic为兼容遗留值见下文port0–65535整数自动loopback Web 端口0表示随机端口openBrowser布尔false是否对外暴露兼容模式 ClientnetworkExposureloopback|lanloopback下一 generation 的监听范围logLeveldebug|info|warn|errorinfo文件日志级别该注册带有applies: restart语义意味着任何值变化都要通过一次重启生效。托盘调用已注册 scope 的受限settings.update({ mode })路径用户也可以直接编辑同一份settings.yaml文档——file provider 与已注册 namespace 观察的是同一个持久化值两条路径天然收敛。Linux 边界只支持兼容模式Linux 只支持兼容模式。托盘在该平台禁用模式命令validate钩子会直接拒绝 advanced/extended 值见 dsh-plugin-desktop/src/index.tsif (value.mode ! compatibility runtime.platform linux) { throw new Error(dsh-plugin-desktop: custom desktop shell modes are supported on macOS and Windows) }即 advanced 值会被拒绝而不是被降级映射到另一种呈现——配置语义在各平台保持一致不会出现「同一个模式名在不同平台行为不同」的误导。材质值的平台能力门控window-material.ts 承担材质解析与 Windows 能力门控WINDOWS_MICA_MIN_BUILD 22_621Electron 只在 Windows 11 22H2NT build 22621及更高版本支持系统绘制的 Mica 背景windowsSupportsSystemBackdrop(build)负责构建号判断parseWindowsWindowMaterial对遗留的acrylic值读入后按off处理——注释说明 Acrylic 实现曾被移除因为两种 Windows 实现都可能破坏原生窗口行为持久化值保留可读性但 fail closed 到普通不透明窗口effectiveDesktopWindowMaterial最终按平台收敛Linux 恒为offmacOS 取macosMaterialWindows 在 build 不支持 Mica 时退回off。重启是组合边界无热切换应用绝不会热切换模式。原生材质选项在BrowserWindow构造时固定window-options.ts的desktopWindowOptions在构造前选择好整组选项当前 Client graph 必须与启动前选定的 Loader row 与 root slot 声明保持一致。机制上Settings watcher比较已提交模式与当前 generation 的活动模式两者不同时请求一次Electron 重启Restart coordinator把 exit 标记为 relaunch然后走普通的有界 shutdown 路径Cordis disposal 先释放 Client effect、Host row、托盘与BrowserWindow仅当该 generation 以零代码退出完成最终退出时才调用app.relaunch()失败 generation 直接退出、不 relaunch重复 restart 请求幂等既有的强制 shutdown 截止时间仍约束整个 disposal 过程。在 electron-shell-generation.ts 的release()中可以看到完整的释放顺序停止 renderer 监控 → 清理窗口监听 → 释放CompatibilityShell→ 销毁托盘 → 销毁BrowserWindow。这正是「先释放全部 generation 资源、再决定是否 relaunch」的实现骨架。高级 Client 组合替换 layout row保留官方 sidebar 与 conversationLoader 层面的 row 投影在 bundle、profile 与 home patch 完成组合后Launcher 验证预期官方 row 身份其最终高级 overlay禁用官方ui-layoutrow明确保持ui-sidebar与ui-conversation启用兼容模式则保持三个官方 row 全部启用。这样做的动机在「备选方案」章节有清晰说明如果保留官方 layout 激活、只 shadow 其 root occupant官方 plugin 仍会提供layoutservice 并拥有 root 子声明造成分裂所有权与含糊的 disposal。高级模式彻底替换 service 与 root 声明同时让独立 sidebar occupant 继续存活。Renderer 侧环境校验desktop Client 在安装任何高级 effect 之前先校验 Host 通过 URL marker 提供的模式与平台信息。environment.ts 的parseDesktopClientEnvironment解析并严格校验五个 query 参数dsh-desktop-modecompatibility/extended/advanceddsh-desktop-platformdarwin/win32/linuxdsh-desktop-version严格 semver 模式dsh-desktop-materialoff/transparent/acrylic/micaacrylic渲染为安全的不透明材质dsh-desktop-micaWindows 能力标记0/1。任意值非法例如 Linux 上 material 不为off、macOS 上 material 为mica、声明mica但系统不支持都会直接抛错拒绝启动。URL 由 Host 侧 desktopRendererUrl 在构造窗口前拼装。layoutservice 的替换DesktopLayoutState在 Client 侧advanced-shell.ts 负责装配整个高级 shell通过 Cordis reflection 在一个 plugin fiber 生命期内提供layoutservice底层是 layout-state.ts 的DesktopLayoutState该 service 拥有 sidebar toggle、details open/close transition它与安装它的同一 effect 一起消失dispose()只 abort 挂起的导航。DesktopLayoutState还实现了标准ILayout接口getPanelInfo/selectPanel/retainMainPanels/beginNavigation并维护一个不可变快照getSnapshot/subscribe驱动useSyncExternalStore。其关键几何常量集中在 layout-state.ts常量值含义SIDEBAR_COLLAPSED56官方 compact rail 宽度CSS pxMACOS_SIDEBAR_COLLAPSED90高级模式 macOS 的加宽 rail容纳居中后的官方 56px rail 与红绿灯 insetSIDEBAR_DEFAULT280默认展开宽度SIDEBAR_MIN/SIDEBAR_MAX264 / 420侧栏宽度夹取范围SIDEBAR_AUTO_COLLAPSE1024自动折叠断点CENTER_MIN400中心会话列的下限防止 rightbar 挤压会话RIGHTBAR_MIN/RIGHTBAR_MAX_RATIO300 / 0.7details 列下限与最大占比computeDesktopColumns在给定 viewport 下求解三列几何并保证 center 不低于CENTER_MIN。root occupant 与子 seat 声明advanced-shell.ts注册rootoccupant组件为 AdvancedFrame.tsx 中的AdvancedFrame并声明子 seatsidebar单值scope: rootmainkeyedscope: rootrightbar单值scope: rootshell.overlay列表scope: root纯新增。所有权边界非常明确advanced-shell.ts 的inject只提供layout与platform官方ui-sidebar仍是 sidebar occupant继续拥有其 workspace、settings 与纯新增 footer-action seat官方ui-conversation继续拥有 conversation 与 details surface第三方 feature 仍可向与兼容模式相同的已文档化 seat 贡献内容。AdvancedFrame内部AdvancedFrame.tsx通过ResizeObserver跟踪 frame 宽度、处理窄屏自动折叠、提供 sidebar/rightbar 的ResizeHandle拖拽pointer capture rAF 节流并把几何输出到 CSS gridgridTemplateColumns。desktop frame只拥有几何与 chrome可折叠 sidebar 列、中心列、可选 details 列、resize handle 与原生 drag region——它不复制 sidebar 控件、session、workspace、conversation、settings 或任何 feature 状态这也是与「把 feature surface 复制进 desktop 包」这一备选方案的关键区别。Theme 投影范围受限的DesktopThemePresenter禁用官方 layout 会移除通常把当前主题投影到 document 的呈现层因此高级模式内置了一个窄DesktopThemePresentertheme-presenter.ts装配见 advanced-shell.ts读取普通上游 theme service把解析后的 color scheme 与 token 值应用到 document维护深色 theme marker 与theme-colormetadata订阅标准theme/change事件ctx.on(theme/change, snapshot presenter.apply(snapshot))disposal 只移除该 presenter 拥有的 attribute、token 与 metadata不触碰其他样式。原生外观与内置主题的同步原生 adapter 在 Host boot 稳定后单独读取已注册的ui-theme.preferencelight/dark/system并在构造高级窗口前应用到 Electronif (platform.platform ! linux) nativeTheme.themeSource spec.readThemeSource()见 electron-shell-generation.ts。之后它会在当前 generation 内观察已提交的 preference 变化使 macOS vibrancy 与 Windows 原生材质与内置 Client theme 使用同一个外观来源释放 generation 时恢复此前的 Electron 外观。注意仅存在于 Client 侧的第三方 theme id 没有可同步的 Host preference因此不会改变原生材质外观。原生材质macOS vibrancy 与 Windows Mica原生窗口选项全部集中在 window-options.ts 的advancedWindowOptions中几何常量定义于 window-chrome.ts常量值用途ADVANCED_MACOS_TRAFFIC_LIGHT_TOP16macOS 红绿灯按钮顶边ADVANCED_MACOS_CONTENT_INSET20macOS conversation/details 列上方的 caption 保留间距ADVANCED_MACOS_DRAG_REGION_HEIGHT32macOS 透明窗口拖动命中区高度ADVANCED_WINDOWS_TITLEBAR_HEIGHT32Windows caption row 高度WINDOWS_CAPTION_CONTROLS_WIDTH138Windows 原生三键预留宽度CSS pxmacOS高级BrowserWindow使用window-options.tstitleBarStyle: hiddenInsettrafficLightPosition: { x: 16, y: 16 }transparent: truebackgroundColor: #00000000vibrancy: sidebarvisualEffectState: followWindow。Renderer 侧配套sidebar surface 保持透明覆盖在原生 vibrancy 之上并在官方 sidebar 外加红绿灯 inset90 CSS px 的收起列把官方 56 px rail 居中MACOS_SIDEBAR_COLLAPSED仅高级模式 macOS 生效见 collapsedSidebarWidthsidebar surface 本身不可拖动内容上方、红绿灯右侧的 desktop 自有透明条提供 32 CSS px 窗口拖动目标ADVANCED_MACOS_DRAG_REGION_HEIGHT另一条 caption row 在 conversation 与 details 列上方保留 20 CSS px 间距同时透明原生拖动命中区保持 32 CSS px 高——因此 desktop shell 能保留紧凑视觉间距无需检查或重排 feature 自有的 Header 节点语义化控件与显式 no-drag contribution 保持可交互顶部 32 px 内的自定义 pointer target 必须显式退出原生拖动区域。desktop sidebar surface 还把官方 sidebar-fill token 局部置为透明官方 sidebar 与 session 列表保留组件行为、滚动、间距与渐隐但不再把 Web 不透明填充绘制到原生材质上。Windows高级窗口使用window-options.tstitleBarStyle: hiddentitleBarOverlaycolor: #00000000、symbolColor: #7f858f、height: 32即原生标题栏 overlay 控件transparent背景 backgroundMaterial: mica仅当windowsSupportsSystemBackdrop(windowsBuild)且material mica否则退回不透明窗口见 window-material.tshasShadow: true、roundedCorners: true、thickFrame: true。注意 Electron 仅在Windows 11 22H2build 22621及更高版本支持系统绘制的 Mica。Renderer 侧配套官方 sidebar 保留兼容模式的几何与过渡56 px compact rail、280 px 默认展开宽度透明 surface 透出 Micadesktop frame 在 conversation 与 details 两列上方拥有标准高度 32 CSS px 的 caption row在该行内避让原生控件区域把两个完整 slot surface 放到下一行该 caption 几何不检查也不重排 feature 自有的 Header 节点因此上游与第三方 slot contribution 整体移动控件、输入框、对话框与交互内容保持不可拖动。AdvancedFrame中dshDesktopMacCaptionRow与dshDesktopWindowsCaptionRow两个 aria-hidden 占位AdvancedFrame.tsx、AdvancedFrame.tsx正是按平台插入的 caption 几何shell.overlay容器被显式放在 DOM 末尾注释说明「Electron 按 DOM 顺序解析 app regionDesktop overlay 必须保持在后面」保证拖拽区域判定不被 overlay 干扰。安全边界与 carrier 约束高级模式不增加任何 renderer 权限不添加 preload script复用既有 preload 路径不引入 Electron IPC transport 或 Node 能力保留contextIsolation、Chromium sandbox、禁用 Node integrationbaseWindowOptions中webPreferences明确设置见 window-options.ts保留精确 loopback origin 导航will-frame-navigate/will-redirect拦截非 carrier origin见 electron-shell-generation.ts外部链接委托给操作系统setWindowOpenHandler仅放行https:/http:/mailto:并shell.openExternal其余deny。HTTP/WebSocket carrier 与第三方 package 发现路径与兼容模式完全一致。renderer 访问头installRendererAccessHeader也只对当前 renderer 所属的 carrier origin 附加重定向无法把能力带离本地 carrier。验证体系仓库为高级模式建立了分层测试证据Profile 测试向临时settings.yaml写入dsh-desktop.mode: advanced验证其投影到desktop-shell、官方ui-layout被禁用、官方ui-sidebar与ui-conversationrow 保持启用Host 测试覆盖共享 settings namespace、值变化后重启、托盘更新路径、持久化前的 Linux 拒绝Client 测试覆盖环境校验、作用域化 layout-service disposal、平台专属 rail 几何、Windows 外层 slot caption 几何、theme 投影——对应 client-environment.spec.ts、client-layout-service.spec.ts窗口选项与 Electron-runtime 测试window-options.spec.ts、electron-runtime.spec.ts验证 macOS hidden-inset vibrancy、Windows Mica/原生控件、内置原生 theme 初始化与实时更新、generation 范围的外观恢复、Linux 拒绝、托盘切到相反模式Shutdown 测试shutdown.spec.ts验证仅在成功零退出码 disposal 后 relaunch失败 generation 不 relaunch类型检查以已发布的 rc.6 slot 与 service contract 验证 desktop 声明。Client 与 Host bundle 均可 headless 构建图形化原生材质外观仍是目标真机验证边界——macOS vibrancy 与 Windows Mica 的实际观感依赖操作系统支持必须在真实目标机器上确认。备选方案回顾为什么这样设计决策记录对比了六种备选方案并说明取舍备选方案否决原因就地 patch 官方 layout/sidebar修改上游拥有的实现或让浏览器 DSH 依赖 Electron 呈现规则只替换 layout row、把官方 sidebar 承载进透明 surface 才能保留组件兼容性保留官方 layout、仅 shadow root occupant官方 plugin 仍提供layoutservice 并拥有 root 子声明造成分裂所有权与含糊 disposal把 conversation/workspace 等 feature surface 复制进 desktop 包它们是 feature surface 而非 desktop chrome保持官方 plugin 激活可避免重复状态让上游与第三方改进继续流入托盘写入独立 Electron preference两个 store 可能不一致托盘更新 Host 注册的dsh-desktopnamespace手工修改也指向同一份settings.yaml改模式后热重载 Client shell无法原子重建原生窗口材质、Loader row、service 所有权与 root 声明有界 relaunch 是最小一致 transitionLinux 提供无原生材质的高级模式同一个模式名在不同平台语义不同会误导配置在明确 Linux 高级设计出现前Linux 只暴露兼容模式结果与后续关注点最终收益DSH Desktop 在不修改上游 submodule、不复制 Web 应用、不引入第二套插件或 transport 系统的前提下获得了 macOS 与 Windows 原生材质呈现托盘修改与手工编辑settings.yaml聚合到一个持久化值一次重启创建一致的 Host、Client 与原生窗口 generation。代价与关注点同样明确desktop 包现在拥有真实 Client 呈现代码必须持续跟踪它使用的已发布 slot、theme 与 service contract这正是 advanced-shell.ts、AdvancedFrame.tsx 这类文件存在的意义高级模式按设计与浏览器 Web 及兼容模式具有不同的呈现 row 组合这是刻意的行为差异原生外观依赖操作系统支持需在真实目标机器上验证Linux 保持 compatibility-only。相关实现文件索引窗口选项 · 材质门控 · chrome 几何常量 · Client 环境校验 · 布局状态 · root 组件 · 高级 shell 装配 · Host 设置注册 · 原生 generation【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考