MDR-EX1000/dsh-desktop-kit

dsh-desktop-kit

为 DeepSeek Harness（DSH）自有的桌面外壳：一个小型插件，加上一个覆盖在 harness Web 界面之上的原生 Tauri 窗口。macOS arm64 发布包包含原生外壳和可点击的 DSH.app 启动器。

dsh web 启动 → 插件在所服务的回环 URL 上生成外壳 → 你就能在真正的桌面窗口中运行 DSH。你仍然可以自己打开回环 URL，将浏览器作为第二个客户端使用；桌面应用在冷启动期间不会打开那个额外的浏览器窗口。无需 fork，无需重新打包运行时，无需第二个配置文件——一切都作为插件运行在你现有的 harness 之上。

为什么不使用第三方外壳？

dsh-desktop 很棒，也是我们的蓝本。我们重新构建了一个更小的版本，原因很具体：真正的 macOS 全屏。它的窗口是无边框的，标题栏由网页绘制，并且从未接入 setFullscreen——最大化按钮是缩放，而不是原生全屏空间。本外壳使用普通的带装饰窗口，因此绿色交通灯按钮和 Ctrl+Cmd+F 开箱即用，为你提供真正的 macOS 全屏。

特性（v0.2.6）

- 在回环 Web 界面上的已认证原生窗口——插件使用 DSH 的连接服务生成进程令牌 URL，因此 WebKit 客户端可以在 DSH 0.1.2-rc.1 下建立其签名的浏览器 cookie；交换完成后，可见 URL 会变得干净。
- 真正的 macOS 全屏——带装饰窗口、原生全屏空间，无需自定义标题栏。
- 单实例——第二次启动会聚焦现有窗口，而不是再打开一个。
- 生命周期契约——关闭窗口会以退出码 0 退出外壳，插件会关闭 harness；插件拆除时会终止外壳。两侧都不会留下孤儿进程。
- 自安装的 macOS 发布包——打包的 arm64 外壳和原生 Mach-O 启动器会被复制到 ~/.dsh/bin，可点击的 DSH.app 会在首次 dsh web 启动时安装；无需 Rust 构建。启动该应用不会打开 Terminal.app。
- 优雅降级——在不支持的平台上，或没有捆绑资源的源码检出中，harness 会继续在浏览器中提供 Web UI，并输出一条可操作的日志。
- 小巧——使用系统 WebKit（WKWebView），不捆绑 Chromium；外壳二进制文件只有几 MB。
- 可用的外部链接——target="_blank" / 跨源链接会通过外壳的 kit_open_external 命令交给系统浏览器处理（否则裸 WKWebView 会将它们渲染为死链接）。
- 浏览器风格缩放——Cmd/Ctrl + = / - / 0 可缩放页面（持久化），这是裸 WKWebView 不提供的功能。
- 遵循 DSH 语言 — 该窗口渲染与浏览器客户端相同的 DSH Web 应用，并使用相同的由 Host 支持的全局语言偏好。更改 设置 → 语言 会在桌面窗口内实时更新 DSH 以及诸如 dsh-rw 之类的本地化插件；Desktop Kit 没有单独的语言设置，也没有插件自有的 UI 文案。

v0.1 中刻意不包含：托盘、系统通知、文件面板、应用内更新器、控制通道。该架构（通过 stdin/stdout 的控制管道、dshdctl: 协议）已在蓝图中记录，日后可以扩展。

架构

dsh web  (你现有的 Web 配置)
└─ dsh-desktop-kit (本插件，inject: [webServer, connection])
└─ connection.authenticatedUrl(clean URL)
└─ 启动 dsh-desktop-kit
└─ 位于 http://127.0.0.1: 的原生 WKWebView 窗口
窗口关闭 → 退出码 0 → 插件关闭 harness

进程令牌仅用于建立持久化的已签名浏览器 Cookie。日志保留干净的
回环 URL，因此凭据不会被复制到终端输出中。插件按以下顺序解析 shell 二进制文件：
config.bin / DSH_DESKTOP_KIT_BIN → $DSH_HOME/bin/dsh-desktop-kit → PATH → ~/.local/bin/dsh-desktop-kit。

安装

需要 dsh CLI 和 macOS（其他平台未经测试）。版本 0.2.6
支持 DSH 0.1.2-rc.1 及之后兼容的 0.1.x 版本，包括
新的启动令牌认证流程。

1. GitHub 源，在 DSH Market 中显示为紧凑的仓库基名
dsh plugin --profile web add github:MDR-EX1000/dsh-desktop-kit
或使用确切的最新预构建 GitHub Release 归档：
dsh plugin --profile web add https://github.com/MDR-EX1000/dsh-desktop-kit/releases/latest/download/dsh-desktop-kit.tgz
或使用本地检出进行开发：
dsh plugin --profile web add /path/to/dsh-desktop-kit

2. 重启 dsh web — 打包的仓库会安装 shell 和 DSH.app，
然后用它打开原生窗口

GitHub 源仓库跟踪已编译的插件 lib/、arm64
bin/dsh-desktop-kit 和 bin/dsh-launcher，以及 app/ 资源，因此在 Apple Silicon 上通过 DSH Market
GitHub 源安装无需本地 TypeScript 或 Rust 构建。Market 在更新时保留
github: 源，并解析仓库当前默认分支的提交。发布
包包含相同的运行时资源，并使用稳定文件名 dsh-desktop-kit.tgz，因此当需要确切的发布归档时，
releases/latest/download URL 仍然有效。在
首次 dsh web 启动时，插件
会将原生 shell 和启动器安装到 ~/.dsh/bin，
并创建 ~/Applications/DSH.app。已签名的可执行文件会被原子替换，因此 macOS 不会
在本地升级后复用陈旧的代码签名状态，并且完成的应用包会在其资源组装完成后进行 ad-hoc 签名，
以便严格的包验证能够成功。源代码检出仍然需要 cargo build --release
仅当重建原生外壳时；当预构建的 bin/dsh-launcher 不存在时，app/install.sh 会用
clang 编译这个小型原生启动器。

源码安装维护说明

基于 basename 的安装会跟随仓库的默认分支，并且不会在安装期间重建此插件。
已提交的 lib/、bin/dsh-desktop-kit、bin/dsh-launcher 和 app/
文件是可安装的运行时资产，必须保留在 Git 中。

当更改 TypeScript 插件或原生外壳时，在用户从 GitHub 安装之前，重新生成并提交相应的
产物：

pnpm build                         # 刷新 lib/
cd shell && cargo build --release  # 当 shell 代码更改时刷新原生二进制文件
将 target/release/dsh-desktop-kit 复制到 bin/dsh-desktop-kit
当原生启动器更改时，构建/复制 app/dsh-launcher.c 到 bin/dsh-launcher

对于每个发布版本，在推送版本提交和标签之前，提交所有已更改的运行时资产。
这样，现有的基于 basename 的安装就能在未来的 Market
更新中继续使用同一个简洁的 GitHub 源。捆绑的二进制文件目前是 macOS arm64。从 GitHub
源码安装不会为 Intel Mac、Linux 或 Windows 交叉编译它；不受支持的平台会保留上述浏览器回退方案。
仅在需要经过测试的确切归档文件时，才使用 Release tarball。

卸载方法：dsh plugin --profile web remove dsh-desktop-kit，删除
~/.dsh/bin/dsh-desktop-kit，如果已安装，还要移除 ~/Applications/DSH.app。

可点击的应用图标（macOS）

app/install.sh   # 构建 ~/Applications/DSH.app（原生启动器；幂等）

该 bundle 的 CFBundleExecutable 是一个原生 Mach-O 启动器，而不是 shell 脚本。它调用
资源脚本时不附加 TTY，因此 macOS 不会启动 Terminal.app。该 bundle 仍然只是一个轻量启动器，
而不是第二个 harness：如果 127.0.0.1:3080 已经有响应
（例如从终端启动的 dsh web），该图标只会在该实例上打开一个窗口；
否则它会自行启动 dsh web --no-open。服务器仍会正常启动，但
桌面入口不会打开重复的浏览器客户端。启动第二个 dsh web 会
因 EADDRINUSE 而失败——早期手工编写的包装器在实例
已经运行时正是这样做的，这就是为什么现在启动器位于此仓库中。HTTP 401 响应会被视为
“已在运行”，因为 DSH 0.1.2 有意保护其未认证的根 URL。

开发

插件部分（TypeScript）
pnpm install
pnpm build        # tsc → lib/
pnpm test         # vitest — spawn/exit/resolution 逻辑，全部使用假实现
pnpm typecheck

shell 部分（Rust / Tauri v2）
cd shell
cargo build --release   # 二进制文件位于 target/release/dsh-desktop-kit

将构建好的插件安装到你的 harness 中以进行实时运行：

dsh plugin --profile web remove dsh-desktop-kit 2>/dev/null
dsh plugin --profile web add /path/to/dsh-desktop-kit
cp shell/target/release/dsh-desktop-kit ~/.dsh/bin/
重启 dsh web

配置

插件配置键（显示默认值）：

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| bin | '' | 显式指定 shell 二进制路径；为空时按 $DSH_HOME/bin → PATH → ~/.local/bin 的顺序解析。也可通过 DSH_DESKTOP_KIT_BIN 设置。 |
| title | 'DSH' | 窗口标题（作为 argv[2] 传给 shell）。 |

Shell argv：dsh-desktop-kit [url] [title] —— 插件会提供一个已认证的 URL；独立运行时默认值仍为 http://127.0.0.1:3080 和 DSH。
--selftest 会运行一个可脚本化的原生全屏进入/退出检查（通过时退出码为 0）；
DSH_KIT_NO_SINGLE_INSTANCE=1 会运行一个并行实例（用于自测、开发）。

语言

Desktop Kit 不会复制或翻译 DSH 界面。它的 WKWebView 加载正在运行的 DSH
Web 界面，因此 DSH 的全局 locale.preference 和实时语言环境更新会与浏览器中完全一致地保留下来。
通过 @deepseek-ai/dsh-client-locale 注册的插件字典因此可以在 DSH.app 内正常工作，而无需 Desktop Kit 专用代码。
稳定的应用程序和窗口名称 DSH 与语言无关；原生 macOS 窗口控件
继续遵循操作系统语言环境。

已知限制

- macOS 是唯一经过测试的平台（WKWebView）。Linux/Windows 构建尚未验证。
- 在 harness 保持运行期间重载插件不会被处理——重新安装后请重启 dsh web。
- 全新的 WebKit 数据存储无法通过独立的 DSH.app 启动器附加到
未使用 Desktop Kit 启动的服务器：启动器无法访问该服务器进程的启动令牌。
一旦 Desktop Kit 为其 WebKit 数据存储建立了签名 cookie，后续附加即可正常工作。
- 没有关闭到托盘：关闭窗口会关闭 harness（按设计如此，与所参考的行为一致）。

许可证

MIT