DSH Desktop 桌面端指南:以 Cordis 插件方式在 Electron 中运行 DeepSeek Harness

原创2026-09-19 23:30:472,234 阅读
文章标签:AI 应用人工智能AI Agent本地部署插件系统dsh-pluginDeepSeek

DSH Desktop 桌面端指南:以 Cordis 插件方式在 Electron 中运行 DeepSeek Harness

dsh-plugin-desktop 是 DeepSeek Harness 插件生态中的桌面端解决方案:它把 DSH 放进 Electron,同时仍然作为普通 Cordis 组合的一部分参与运行,安装后的应用名为 DSH Desktop。本文围绕仓库中的 dsh-plugin-desktop/README.md 展开,结合 dsh-plugin-desktop/src/ 下的真实源码,系统讲解其架构分层、三种呈现模式、settings.yaml 模式配置、Profile 切换、desktopPnpm 包管理服务、插件工作流、桌面操作与打包发布流程,帮助你从零掌握 DSH Desktop 的安装、配置、二次开发与故障诊断。

总体架构:最小 Electron 启动器 + 普通 Cordis 组合

DSH Desktop 的架构核心是最小化 Electron 启动代码与普通 Cordis 组合的分离。Electron 可执行文件只做四件事:

  1. 获取单实例锁;
  2. 解析当前选中的 DSH profile;
  3. 提供原生运行时能力;
  4. 在 Electron main 进程中启动 Host Cordis 根。

之后的工作全部交给 Cordis 插件完成:desktop-shell Host 插件通过 Cordis effect 拥有 BrowserWindow、导航策略、settings namespace 以及"关闭 vs 退出"的生命周期;原生 runtime 拥有实体托盘;desktop-shell、desktop-profiles、desktop-terminal、desktop-updates 通过一个有序 item registry 提供 effect-scoped 命令。这一分工在 cordis.patch.yml 中有直接体现——桌面各能力行(desktop-shell、desktop-terminal、desktop-diagnostics、desktop-notifications、desktop-pnpm、desktop-profiles、desktop-updates)作为补丁插入到现有 Web bundle 组合之中。

Web carrier 与同源边界

三种呈现模式都复用现有 Web carrier。profile 挂载普通 dsh-base 与 dsh-web-app bundle,Host 默认把 HTTP 与 WebSocket surface 绑定到 127.0.0.1 的临时端口;只有明确确认的局域网(LAN)设置才绑定所有接口,此时 Electron 仍然从 loopback 地址在沙箱 renderer 中加载同源页面。Electron 不维护自有插件 roster、不使用 preload bridge,renderer 也拿不到原始 Electron API——所有导航与重定向都被限制在确切的 loopback origin,外部 HTTP、HTTPS 与邮件链接交给操作系统打开,renderer 启用 contextIsolation 与 Chromium sandbox,并关闭 Node integration。

desktop package 拥有普通 Host 与 Web Client 两个 face:Client face 在所有模式下校验 Host 提供的模式、平台与经过能力门槛解析的材质 marker。第三方 Web client 在所有模式下都继续使用普通 DSH 模块图,不需要单独的客户端构建,也没有桌面专用注册 API。

三种呈现模式:兼容、扩展窗口、增强

DSH Desktop 通过 dsh-desktop.mode 提供三种呈现模式,对应源码中 setup-wizard-settings.ts 校验的三个取值:compatibility、extended、advanced。

兼容模式(compatibility,默认)

dsh-desktop.mode 默认是 compatibility。在 macOS 与 Windows 上,它会在官方 Web surface 上方创建一条独立的 36 CSS 像素 Desktop frame,保留原生红绿灯或窗口按钮。居中标识、模式 pill、拖动区域与图标操作只属于这条 frame;完整官方页面从它下方开始,不参与 frame 的布局或安全区计算。Linux 保留普通原生 frame 作为兼容 fallback。

兼容模式下,desktop Client module 只注册独立 frame overlay 与固定 launcher 操作,不替换任何官方呈现:不提供或替换 layout service,不注册 root 或 sidebar occupant,也不改动 conversation surface。因此普通 desktop 与 web profile 会原样保留官方 row。

该模式下的两个平台细节值得注意:

  • Windows 目录选择桥接:Launcher 固定使用 browse 目录选择 backend 并保留完整的应用内目录面板;桌面构建通过补丁加入一个小型系统文件夹图标,经同源路由调用 Electron 的 dialog.showOpenDialog,选中路径后回到面板原有的 workspace 接纳流程,取消则面板保持打开。普通浏览器与远程启动不会获得这个桌面桥。
  • Windows PowerShell 沙箱:所有呈现模式下都保留上游 pwsh-sandbox 行为与 Windows ACL confinement。Launcher 只把该 Host provider 替换为同一 package 的 dsh-plugin-desktop/windows-pwsh-sandbox 子路径:adapter 通过私有 trampoline 以 Node 模式启动打包后的 Electron executable,精确校验上游 runner 后移除 Node-mode 变量,并确保原本无 console 的 Windows 进程拥有隐藏 console,让受限 PowerShell 进程可以继承它。ACL policy 与后续失败处理仍全部委托给上游 runner,confinement 失败时不会自动回退到不受限执行。

扩展窗口模式(extended)

扩展窗口会禁用官方上游 ui-layout root,安装 Desktop 自有 root layout。该 layout 负责 sidebar、conversation、details、overlay 与 resize 几何,同时继续渲染官方 sidebar、conversation、details slot occupant。Desktop root 上方是固定 36 CSS 像素操作栏,操作栏与 Desktop 自有 sidebar surface 只透出一层不会叠色的材质,组成连续的倒 L 形玻璃区域;conversation surface 位于倒 L 内侧,使用 10 像素内圆角,分隔线沿圆角绘制。

第一方操作使用紧凑图标:macOS 放在红绿灯相对的右侧,Windows 放在原生标题栏按钮相对的左侧,用于打开 DSH 终端、普通/恢复模式重启菜单、以及开发者菜单(重载 renderer、切换分离式开发者工具)。这些操作通过私有同源 launcher 边界执行,页面不会获得原始 Electron 或任意命令接口;Web Client 插件在兼容与扩展模式下都不能向操作栏贡献 action。

DOM 层面,操作栏被声明为 Desktop frame,下移后的上游 root 是它的 content viewport:shell.overlay 成为 fixed 插件 surface 的 containing block,直接 portal 到 body 的对话框获得相同内容偏移,两条路径都被限制在 36 像素 frame 下方。

增强模式(advanced)

增强模式是为 macOS 与 Windows 显式组合的桌面呈现。Launcher 读取全部用户 patch 后禁用官方 ui-layout Loader row,保持官方 ui-sidebar 与 ui-conversation row 启用,并把所选模式应用到 desktop-shell。desktop Client 在所有模式中提供不可变 desktopWindow 原生几何 service,增强模式另有独立的 Cordis effects、layout service 与 root slot registration,root 为不变的上游 sidebar、conversation、details 与 overlay contribution 声明 seat,从而保留官方 sidebar 的组件行为、收起动画与第三方扩展点。

增强模式的关键几何(从源码中的 desktopWindow 契约与 plugin-services.md 均可印证):

  • macOS:红绿灯位于 x=16, y=16,紧凑 20 CSS 像素内容 inset,32 CSS 像素原生拖拽区域;90 CSS 像素收起列把官方 56 像素 rail 居中;通过精确的 app-region: no-drag 排除规则让按钮、链接、输入框、菜单、对话框与显式 .dshDesktopNoDrag contribution 保持可交互。
  • Windows:官方 sidebar 保持兼容几何(收起 56 像素、默认展开 280 像素),透明 surface 透出当前支持并选择的材质;窗口保留 32 CSS 像素内部 caption row 与原生 overlay 控件。
  • 增强窗口还读取 ui-theme.preference 并把 light、dark、system 镜像到 Electron 原生外观,订阅普通 theme 变化并在 generation dispose 时恢复。
  • Linux 会拒绝扩展与增强模式,而不是静默降级到与持久化设置不同的呈现。

模式设置与重启边界:settings.yaml 单一事实源

dsh-desktop.mode 字段位于 DSH home 的 settings.yaml 文档中,是单一事实源,profile manifest 中没有平行模式值:

dsh-desktop:
  mode: compatibility # compatibility、extended 或 advanced
  macosMaterial: transparent # off 或 transparent
  windowsMaterial: acrylic # off、acrylic,系统支持时还可用 mica

Launcher 在组合 generation 之前读取当前 @deepseek-ai/dsh-settings-file row 解析到的同一份文件,Host 通过标准 settings service 注册 dsh-desktop namespace(源码见 index.ts 中的 DESKTOP_SETTINGS_NAMESPACE = 'dsh-desktop')。非法取值会被拒绝:parseMode 只接受 compatibility、extended、advanced 三者之一,否则抛出 dsh-desktop.mode must be compatibility, extended, or advanced(见 setup-wizard-settings.ts)。

用户可以:

  • 从托盘选择其他模式(托盘更新已注册的 dsh-desktop settings namespace);
  • 手工编辑 DSH home 的 settings.yaml(settings provider 观察同一文件)。

无论哪种方式,提交变更后都请求一次有序重启:先 dispose 当前 Cordis 树,仅当零退出码 shutdown 成功时才让 Electron relaunch。应用绝不会在存活的 renderer generation 中热切换 root slot、原生窗口材质或 Loader row。Linux 只支持兼容模式:托盘模式命令被禁用,自定义窗口模式值被拒绝。

材质设置独立于模式:macOS 提供 Off / Transparent;Windows 提供 Off / 原生 Acrylic,仅 Windows 11 build 22621 及以上显示 Mica;已持久化但系统不支持的 Mica 按能力门槛回退到 Acrylic。切换模式或材质同样触发有序重启。

启动环境恢复与内置 pnpm

Login-shell PATH 恢复

打包后的 macOS 或 Linux 启动在 profile 准备与 Cordis boot 之前,会以交互式 login 模式运行用户账户配置的 shell,恢复其导出的 PATH——这修补了 Finder、LaunchServices 等图形启动方式通常传入的精简 PATH。细节约束:

  • 只支持绝对路径的 zsh、bash、fish;Bash 遵循标准 login 行为,.bashrc 仅在 login profile 主动 source 它时参与;
  • 除 PATH 外,只从固定 allowlist 补充缺失的 locale、工具链、package manager 与虚拟环境变量;PATH 始终采用 shell 值;
  • 捕获以 @deepseek-ai/dsh-subprocess 的 scrubbedParentEnv() 为输入,变量名须通过 SENSITIVE_ENV_PATTERN 与 DSH_ENV_PREFIX 检查;只在 shell rc 中出现的凭据、DSH_* 值、代理与 SSH agent 设置、进程启动 hook 不会被导入 Electron;
  • Windows 以及未打包/开发启动跳过恢复;shell 不存在、超时、捕获失败或缺少 PATH 时静默保留原环境。

Ambient pnpm 与 desktopPnpm 服务

Login-shell 恢复完成后,Launcher 创建 layered launch-environment snapshot,并把只含固定版本内置 pnpm 命令的私有命令目录前置到 Electron main 进程 PATH——Host 与第三方插件从启动起即可发现该 package manager,无需系统安装 Node.js。该 ambient path 是兼容 surface,不是正式的插件管理 contract。

正式的包管理契约是 desktop-pnpm Host row 提供的 ctx.desktopPnpm.run(argv, signal?)。从 pnpm.ts 源码可以看到它的实现细节:

  • 以激活 Profile 目录作为 cwd,直接执行内置 pnpm entry(不经过 .cmd shim 的 shell lookup);
  • 每次操作都在最终执行 package manager 时加入一次 --config.minimumReleaseAge=0,不会改写用户的 pnpm 配置(见 withDesktopPnpmPolicy);
  • run() 返回实时 stdout/stderr stream、在完整 process tree 退出后才 settle 的 done promise,以及 cancel();
  • 每个 generation 同时最多运行一个 operation,重复调用同步抛错;
  • subprocess 环境只对 child 设置 ELECTRON_RUN_AS_NODE、DSH_HOME、CI、npm_config_runtime=electron 与 Electron ABI 相关变量,公开 runtime path 仍不暴露 node 或 dsh;
  • Launcher 不修改系统 PATH、shell 启动文件、profile 配置或 .env 文档;
  • Desktop 故意不在该接口加入插件专用重试、快照或回滚,恢复统一由三个健康启动 checkpoint 负责。

Profile 管理与 desktopProfiles 服务

托盘中的 profile 选择器列出现有 profile 以及可延迟创建的 desktop、web 默认项。可选 profile 必须直接按顺序组合 dsh-base 与 dsh-web-app;headless、损坏或已内嵌 desktop bundle 的 profile 仍显示但不可选。只有 desktop 是 Launcher 管理的 profile:修复安装方拥有的前缀,同时保留第三方 bundle 相对顺序;Launcher 只会在当前 generation 中把 desktop layer 插到 dsh-web-app 之后,不会把它持久化到被选 bundle 列表。

Profile 选择是保存在 Electron user data 下的 desktop 自有状态,不是被选 profile 内的字段;切换通过有序重启生效,启动失败不会替换成 last-known-good profile,也不会自动改写配置。

ctx.desktopProfiles 是 generation-scoped 的 Host service,其实现见 profile-service.ts:

  • current 是不可变对象(Object.freeze),含激活 profile 的 name 与绝对 dir,一次 generation 内固定不变;
  • list() 只读重读 profile manifest,不改变 patch、依赖或 bundle 顺序;
  • select(name) 是重启操作而非就地变更:先持久化目标,再请求有序 Cordis teardown 与 Electron relaunch;
  • 并发调用同一目标共享同一操作;目标已提交 pending 后,重启前选择其他目标会被拒绝;持久化失败会释放选择槽位,重启失败则保留已提交目标以便重试;
  • service dispose 后通过保留引用调用会抛错,应在新 generation 重新读取 current。

恢复 checkpoint

每次健康启动都会写入三个轮转 checkpoint 之一,包含激活 Profile 的声明式 package 与 patch 文件,以及共享 DSH home 的 settings.yaml 与 cordis.patch.yml。恢复始终打开 Recovery 页面,由用户选择精确槽位;恢复后的下一次健康启动会跳过一次 checkpoint 替换。版本 2 旧槽位仍可恢复但只影响原有五个 Profile 文件。凭据、.env、sessions、storage、缓存与生成的依赖状态绝不写入 checkpoint——官方 profile 默认共用同一 DSH home 的 sessions/settings/storage,切换 profile 不会复制或迁移这些记录,除非显式恢复 checkpoint。

插件工作流与命令行启动

管理插件

用普通 DSH 命令管理任意 profile:

dsh plugin --profile desktop add third-party-plugin
dsh plugin --profile desktop remove third-party-plugin
dsh plugin --profile desktop update

应用默认使用 desktop profile;从托盘 Profile 子菜单选择其他 Web-capable profile 会自动重启。生成的 DSH 终端让裸命令默认作用于当前激活 profile,因此短命令形式等价:

dsh plugin add third-party-plugin
dsh plugin remove third-party-plugin
dsh plugin update

显式 --profile <name> 始终具有更高优先级,适合在切换前先准备另一个 profile。

启动命令

包名注册为 dsh-plugin-desktop,安装两个等价命令 dsh-desktop 与 dsh-plugin-desktop(见 package.json 的 bin 字段),无参数时都启动打包的 Electron launcher lib/main.js:

  • 全局安装:npm install -g dsh-plugin-desktop 自动安装 electron peer,随后直接运行 dsh-desktop;
  • 安装在 profile 内:dsh plugin --profile <name> add dsh-plugin-desktop 后命令位于该 profile 的 node_modules/.bin;pnpm 不自动安装 electron peer,需要命令行启动时手动 dsh plugin --profile <name> add electron。原生构建许可(node-pty、koffi、electron 等)遵循 pnpm 常规 allowBuilds 规则;
  • 缺少 electron 时命令打印简短安装指引而非模块错误;
  • 也可通过 npm 直接启动:npx dsh-plugin-desktop。

注意:如果用普通 dsh 命令直接启动组合了桌面壳的 profile(缺少 launcher 的 desktopRuntime service),会打印提示要求改用 dsh-desktop 或打包应用,此时桌面壳不会注册任何功能。

插件作者扩展点

第三方 Host 插件只需提供普通 dsh.bundle patch;带浏览器 UI 的插件还要发布普通 dsh.client 元数据,platform: "web" 并导出 ./client 产物。增强模式 contribution 必须面向该显式组合中存在的 service 与 slot。完整的插件契约(desktopProfiles、desktopPnpm、desktopWindow 三个公共 service、注入模式、TypeScript 示例、取消与 fallback 指南)见 docs/plugin-services.md。其中 desktopWindow 客户端 service 在浏览器侧提供不可变几何事实:

import type { Context as ClientContext } from '@deepseek-ai/cordis'
import type { DesktopWindowService } from 'dsh-plugin-desktop/client'

export const inject = ['desktopWindow']

export function apply(ctx: ClientContext): void {
  const geometry: DesktopWindowService = ctx.desktopWindow
  document.documentElement.style.setProperty(
    '--example-desktop-safe-top',
    `${geometry.safeAreaInsets.top}px`,
  )
}

desktopWindow 报告 mode、platform、能力门槛后的 material、micaSupported、availableMaterials、safeAreaInsets 与 dragRegion(均为 CSS 像素、一次 generation 内固定);它只报告几何,不暴露窗口修改、焦点、Electron 或 IPC 能力,普通浏览器 boot 中不存在该 service。Host 侧类型从 dsh-plugin-desktop/profile-service 与 dsh-plugin-desktop/pnpm 导入(注意 dsh-plugin-desktop/profiles 是托盘消费者,不是 service 契约)。

桌面操作:通知、更新、终端与对话框

原生通知

当 Desktop 窗口未聚焦时,直接用户回合到达 completed 显示完成通知;error 或 max-tokens 结束显示需要处理的通知;后台任务完成/失败走同一条原生注意力路径。取消、阻塞、中断、被杀、插件发起、仅 continuation、turn 不匹配与 subagent 活动保持静默。点击通知显示并聚焦窗口;macOS/Linux 递增应用角标,Windows 闪烁任务栏按钮,显示/聚焦/释放窗口时清除。dsh-desktop-notifications settings namespace 提供四个独立开关(notifyOnTurnCompletion、notifyOnTurnFailure、notifyOnJobCompletion、notifyOnJobFailure),默认全部开启;通知文案刻意通用,不含提示词、回复、错误、路径、会话 ID、模型名等敏感信息。

自动更新

打包后的 macOS 与 Windows 应用在启动 60 秒后查询版本服务,之后每六小时一次;请求带 X-DSH-Desktop-Channel: stable 与安装版本,与托盘 Check for Updates… 共享同一 in-flight operation,15 秒超时。稳定通道只接受规范 release SemVer,不发现 Beta。选择 Download 会先复查版本未变,再打开原生保存对话框(默认 Downloads,可改绝对路径,取消则不发请求),通过 Electron 网络跟随 redirect,最多流式写入 1 GiB,拒绝不完整 DMG 或 Windows PE。macOS 打开 DMG 由用户替换应用;Windows 在 NSIS 安装器就绪后二次确认,Restart and Install 启动安装器并请求有序 Cordis teardown。开发运行、未打包与 Linux 不会下载安装包。

DSH 终端

macOS 与 Windows 上 Open DSH Terminal 打开以激活 profile 为工作目录的系统终端,欢迎文本显示应用版本、profile、profile 目录与 DSH home;裸 dsh、dsh --dump-config 与无 profile 的 plugin 子命令默认作用于激活 profile,显式 --profile 与上游 web alias 保持原义。DSH Desktop 在 user-data 目录生成按 profile 划分的私有 dsh、pnpm、node shim,设置 DSH_HOME,只把 shim 目录前置到该终端 PATH,不修改全局环境或 shell 启动文件。Windows 依次选择 PowerShell 7、Windows PowerShell、命令提示符,并在新 Windows Terminal 窗口中打开;wt.exe 不可用时由私有 cmd start broker 创建可见控制台。Linux 不组合终端命令。

对话框窗口与恢复模式

确认、警告、错误与结果统一使用基于 shadcn 的 DesktopDialogWindow:每个 dialog 都是独立、沙箱化的模态 BrowserWindow,parent 到当前 Desktop 窗口;纯操作 dialog 不显示窗口按钮,独立 dialog 使用共享 36 像素 utility frame。Escape 或窗口关闭映射为有界取消,只向 main process 返回一次结果;系统文件选择器保持原生。恢复模式同样使用独立窗口,其 shadcn 页面把操作分为 插件管理 / 回滚 / 切换配置 / 诊断 四个 Tab,恢复操作与重启请求都打开 DesktopDialogWindow 确认。

日志、诊断与原生生命周期

  • 日志:UTF-8 写入 Electron user-data 目录——Windows %APPDATA%\DSH Desktop\logs,macOS ~/Library/Application Support/DSH Desktop/logs;完整日志 dsh-YYYY-MM-DD.log,warning/error 另写 dsh-YYYY-MM-DD.error.log;单文件 10 MiB 轮转、启动删除七天前文件、目录上限 200 MiB。dsh-desktop.logLevel 控制详细程度,默认 info。
  • 诊断导出:托盘 Export Diagnostics… 在相邻 diagnostics 目录创建 ZIP,在共享 50 MiB evidence cap 内收集最近自有日志与本地 Crashpad .dmp,可选包含 crash-evidence/active-run.json,加入 system-info.txt,只保留最新三份 ZIP。导出前有隐私边界确认;凭据会脱敏,但日志仍可能含本地路径、会话 ID、提示词与工具输出,crash dump 可能含进程内存片段,分享前应检查。
  • 健康看护:启动健康后主进程每五秒检查可见内容,连续两次空页面或无响应触发有次数上限的自动恢复(至多三次:首次无延迟,随后 1 秒、3 秒;恢复后健康满一分钟才重置预算);界面进程意外退出(含 OOM)静默重载现有窗口而不重启 Host;探测检查 DOM 可见性而非截图像素。
  • 生命周期:关闭窗口只是隐藏,Host Cordis 树继续运行;托盘负责重开窗口、切 profile、打开终端、检查更新、改模式或显式退出。profile 与模式切换都先 dispose 当前 Cordis 树再 relaunch;原生退出、SIGINT、SIGTERM 也在退出前请求 dispose,五秒期限或重复请求强制退出。

开发与打包

该包由仓库根目录的 Yarn workspace 管理(相邻 deepseek-harness/ 是独立上游 pnpm 项目,不属于 Yarn workspace)。从仓库根目录:

yarn install
yarn check

有图形会话时 yarn dev 可显式启动(构建在前,无需手动 build)。headless-safe 的 launcher 入口可直接验证:

node lib/bin.js --help
node lib/bin.js --version

打包矩阵(均可从 dsh-plugin-desktop 目录或 workspace 运行):

  • yarn package:dir:当前宿主平台的未封装目录;packaged-runtime gate 会拒绝缺少 desktop 更新/终端模块、DSH CLI bootstrap、内置 pnpm 入口或物理 deployment package 的产物。Stable 与 Beta 在三个平台均关闭 ASAR(见 package.json 的 asar: false)。
  • WSL Linux 无界面检查:用 WSL 内部 Linux Node.js(不要用继承的 Windows Node.js/Corepack shim),source ~/.nvm/nvm.sh 后依次执行 git submodule update --init --recursive、corepack yarn install --immutable、corepack yarn workspace dsh-plugin-desktop typecheck、... test、corepack yarn build。WSL 不能替代真实 Linux 桌面验证托盘/窗口管理器。
  • Windows x64 安装包:原生 Windows x64 + Git + Node 22.23.2(亦接受 22.19+/24.x),在 v2 checkout 中 git submodule update --init --recursive、corepack.cmd yarn install --immutable、corepack.cmd yarn dist:win。不需要 Python 或 VS C++ Build Tools;dist:win 拒绝非 Windows/x64 宿主,运行 Windows-safe gate 后构建 NSIS 安装器并校验两个 PE。产物为 dsh-plugin-desktop\dist\DSH-Desktop-2.0.5-x64-Setup.exe,未封装程序在 dist\win-unpacked\DSH Desktop.exe。本地命令剥离证书变量并设 signExecutable=false,可能触发 SmartScreen 警告。
  • Windows x64 绿色 ZIP:corepack.cmd yarn dist:win-portable 生成 DSH-Desktop-2.0.5-x64-Portable.zip,解压即用,无需管理员与安装步骤;数据仍写入 Windows 用户数据目录,且便携版不交给 NSIS 更新流程,需手动替换。
  • macOS DMG 冒烟:原生 macOS 上 yarn dist:mac-smoke 构建未签名 universal DMG(Intel 与 Apple Silicon 通用),运行完整产品 gate(含真实 login-shell 测试),剥离全部签名/公证变量、CSC_IDENTITY_AUTO_DISCOVERY=false、从不发布;正式签名并公证的发布仍是 yarn dist:mac,产物写入 dsh-plugin-desktop/dist/mac-release/。

图标处理也值得注意:Windows 专用 build/app-icon.ico 由构建派生(高 DPI 精确帧、小尺寸矢量简化、256 像素以下 DIB payload),macOS 的 build/app-icon-mac.png 由 scripts/generate-mac-app-icon.mjs 生成(源图 824×824 居中于 1024×1024 透明画布),build/tray-icon.svg 是品牌蓝托盘源,macOS 模板图由系统自动着色。

已知限制与注意事项

  • 添加/删除 profile bundle 后必须重启(Launcher 不监听 manifest);托盘切换 profile 会自动重启。
  • 切换模式或材质按设计总是重启,存活 generation 不热切换 Loader row、slot 所有权或原生材质。
  • Linux 仅支持兼容模式,不支持扩展与增强模式。
  • 共享 carrier 是 HTTP/WebSocket 而非 Electron IPC,默认 loopback,支持明确确认的全接口 LAN 绑定;替换 carrier 需要上游 DSH 提供 transport 扩展点。
  • 项目同时固定到已发布的 DSH 0.1.5-rc.2 family 及对应 deepseek-harness/ release 源码,产品构建使用 upstream.json 记录并提交的官方 profile 运行时包,而非直接链接源码 checkout;0.1.5-rc.2 会把受支持的历史会话迁移到 V3,旧 0.1.2-rc.1 运行时无法读取升级后写入的会话。
  • Windows 上 ambient pnpm 与 lifecycle Node helper 是 .cmd shim;第三方插件直接 spawn('pnpm', { shell: false }) 或直接执行 .cmd npm_node_execpath 属于不可移植行为,应改用 desktopPnpm service 或 shell-aware 启动路径。
  • dshmarket@1.2.3 是用户可选安装的第三方包而非内置 marketplace:它既不读取 desktopProfiles 也不使用 desktopPnpm,且不含完整 MIT license 文本,未通过内置再分发 gate。
  • 更新交接只验证下载容器不验证 publisher 身份;签名产物、Authenticode/SmartScreen 信誉与原生升级测试仍是发布 gate。
  • 模型体验保持透明:desktop package 只改变应用组合与原生呈现,不增加任何模型可见的指令、工具、事件或请求字段,KV Cache 也无影响——模型请求仍由同一套 DSH Host 与 client feature plugin 组装。

总体而言,DSH Desktop 的设计哲学是"万物皆插件,桌面本身也是插件":原生窗口、托盘、终端、更新、包管理都作为普通 Cordis 行参与组合,renderer 始终是沙箱化的官方 Web surface,插件作者只需要遵循 plugin-services.md 中记录的三个公共 service 契约即可获得完整的桌面集成能力。

登录后查看全文
deepseek-harness-desktop