鲸窗桌面端 penglai-doll/LocalWhale

[!IMPORTANT]
项目已归档 · 停止维护（2026-09-30）

官方 DeepSeek Harness Desktop（dsh-desktop） 已推出，LocalWhale 为 DSH 提供桌面宿主的历史使命已经完成。本仓库停止维护，不再发布更新或修复；代码、文档和历史版本保留，供学习与参考。

请转向 DeepSeek Harness 官方入口；官方桌面端源码与说明见 deepseek-ai/deepseek-harness/apps/desktop。感谢所有使用、反馈和支持 LocalWhale 的朋友。

Archived · No longer maintained (2026-09-30)

The official DeepSeek Harness Desktop (dsh-desktop) is now available, and LocalWhale has fulfilled its purpose as a desktop host for DSH. This repository is no longer maintained and will receive no further updates or fixes. Its code, documentation, and past releases remain available for learning and reference.

Please use the official DeepSeek Harness page. The official desktop source and documentation are available in deepseek-ai/deepseek-harness/apps/desktop. Thank you to everyone who used, tested, and supported LocalWhale.

LocalWhale

用 WinUI 3 把 DeepSeek Harness 带到 Windows 桌面。
A native WinUI 3 desktop home for DeepSeek Harness.

平台版本 / Platform editions Windows（本仓库）v0.1.3
· macOS 0.1.0-preview.1

下载最新版 / Download
· v0.1.5 更新日志 / Release notes
· DeepSeek Harness

LocalWhale 是一个原生 Windows 11 桌面宿主，基于 .NET 10、WinUI 3 和 Windows App SDK。运行 LocalWhale.exe 后，它会隐藏启动随包携带的 Node/Harness 服务，通过带鉴权的健康检查确认就绪，再由 WebView2 显示未修改的官方 WebUI。

LocalWhale is a native Windows 11 host built with .NET 10, WinUI 3, and the Windows App SDK. Launching LocalWhale.exe starts the bundled Node/Harness service invisibly, waits for an authenticated health check, and then presents the unchanged upstream WebUI in WebView2.

| 特点 / Highlight | 实现 / What it means |
| 原生 WinUI 3 / Native WinUI 3 | Windows App SDK TitleBar、Mica、Fluent 控件、系统托盘、Snap 与高 DPI。 |
| 官方插件机制 / Official plugin model | desktop bridge 通过 Harness --patch 作为 Cordis 插件加载，遵循上游 “Everything is a Plugin” 架构。 |
| 官方界面原样保留 / Upstream UI preserved | 不注入 CSS、不套 iframe、不 fork Harness 前端；主题仅作用于 WinUI 宿主。 |
| 离线即用 / Self-contained | 安装包内置 Node、pnpm、Harness、.NET 运行文件和 WebView2 Evergreen 离线安装器。 |
| 桌面级生命周期 / Desktop lifecycle | 隐藏启动、单实例、随机本机端口、托盘、优雅关闭、Job Object 清场、更新验证与回滚。 |
| 本地客户端自更新 / Shell self-update | 检查 GitHub 最新发布，点击下载并逐字节校验 SHA-256；下次重启静默安装并自动回到新版。 |
| 独立重启与设置 / Restart & settings | 标题栏独立的 Harness 重启按钮与设置对话框；关闭到托盘、主题、更新检查与日志收纳于设置。 |

LocalWhale 是独立的社区项目，与 DeepSeek 没有隶属或官方背书关系。DeepSeek Harness 页面及信息架构保持原样，不注入 CSS，不使用 iframe，也不 fork 官方前端。LocalWhale 图标与鲸鱼娘角色是本项目的原创社区视觉资产，不代表 DeepSeek 官方形象。

| 默认 Fluent 主题 / Original | 可选鲸鱼娘主题 / WhaleGirl |
| LocalWhale v0.1.1 默认主题 | LocalWhale v0.1.1 鲸鱼娘主题 |

中文说明

为什么做 LocalWhale

官方 Harness 提供的是本地 WebUI，直接使用时通常需要自己管理 Node、包管理器、终端窗口、端口和服务退出。LocalWhale 把这些“启动器日常任务”收进一个原生 WinUI 3 本地客户端：

- WinUI 3 原生桌面体验： 使用 Windows App SDK TitleBar、Mica、Fluent 控件、系统窗口按钮、Snap 和高 DPI 命中区。
- 双击 EXE 即用： 不要求系统已安装 Node、pnpm 或 .NET Runtime。
- 遵循官方插件架构： desktop bridge 通过 --patch 作为 Cordis 插件加载；仓库按照官方建议使用 dsh-plugin topic。
- 后台服务不弹终端窗口；随机监听 127.0.0.1 端口，不暴露到局域网。
- EXE、任务栏、Alt+Tab、托盘和安装器统一使用简洁的 LocalWhale 鲸尾图标。
- 默认保持克制的 Fluent 外观，也可以从标题栏菜单切换到鲸鱼娘主题。
- WebView2 直接加载官方 Harness 页面，宿主不修改官方前端。
- 默认关闭窗口即完全退出；可切换为关闭到系统托盘。
- 退出时优先请求 Harness 优雅关闭，超时后由 Job Object 清理整棵子进程树。
- Harness 与本地客户端独立版本管理，候选 Harness 更新需先通过隔离冒烟测试。
- 首次创建官方 profile 时若遇到已知的模块链接竞态，LocalWhale 会保留诊断并仅自动重试一次。

下载与安装

支持范围：Windows 11 x64。

1. 打开本仓库的 Releases 页面。
2. 下载 LocalWhale-Setup-x64.exe，可同时下载 SHA256SUMS.txt 校验文件。
3. 运行标准安装向导。安装目录页始终显示，可选择任意有写入权限的位置；默认目录为 %LOCALAPPDATA%\Programs\LocalWhale。
4. 可选创建桌面快捷方式，安装完成后启动 LocalWhale。
安装器按用户安装，不请求管理员权限；Node 24、pnpm、Harness、WinUI 运行文件和 WebView2 Evergreen 离线安装器都已随包携带。首个个人发布版本未进行商业代码签名，因此 Windows 可能显示「未知发布者」提示，请只从本仓库 Release 下载并核对 SHA-256。

外观与主题

v0.1.1 使用 Windows App SDK 的原生 TitleBar、Mica、Fluent 卡片和 InfoBar 重新整理了桌面宿主。默认的「默认主题」跟随 Windows 浅色、深色与高对比度设置；「鲸鱼娘主题」使用海军蓝、长春花蓝与冰青配色，并只在启动、恢复与关于界面显示本项目原创角色。窗口窄于 760 逻辑像素或系统处于高对比度模式时，角色装饰会自动隐藏，让文字和操作按钮保持清晰。

主题只影响 LocalWhale 自己的标题栏、启动/恢复卡片、更新提示和设置界面。WebView2 中的官方 Harness DOM、CSS、页面结构及插件界面完全不变。可在右上角设置按钮（齿轮）打开设置对话框，在「外观」中即时切换；选择会写入 %LOCALAPPDATA%\LocalWhale\settings.json，重启后继续使用。

从 v0.1.0 覆盖安装时，旧设置文件没有主题字段也能直接读取，并默认选择「默认主题」；关闭行为、忽略的 Harness 版本与上次更新检查时间都会保留。此迁移不会读取、移动或重写 %USERPROFILE%\.dsh。

启动与退出流程

flowchart LR
A["LocalWhale.exe"] --> B["单实例检查"]
B --> C["隐藏启动随包 Node"]
C --> D["DeepSeek Harness + desktop bridge"]
D --> E["随机 127.0.0.1 端口"]
E --> F["Token 鉴权健康检查"]
F --> G["WebView2 显示官方 WebUI"]
G --> H["优雅关闭，超时由 Job Object 清场"]

bridge 只增加两个本机宿主端点：

- GET /__localwhale/v1/health
- POST /__localwhale/v1/shutdown

它们要求每次启动随机生成、仅驻留内存的 X-LocalWhale-Token。端口、PID 和 token 都不会写入磁盘。

数据边界

| 数据 | 位置 | 卸载行为 |
| DeepSeek Harness 会话、设置与凭据 | %USERPROFILE%\.dsh | 始终保留 |
| LocalWhale 设置与运行状态 | %LOCALAPPDATA%\LocalWhale | 删除 |
| WebView2 用户数据 | %LOCALAPPDATA%\LocalWhale\webview2 | 删除 |
| Harness 版本与更新 staging | %LOCALAPPDATA%\LocalWhale\runtimes | 删除 |
| 本地客户端更新安装包暂存 | %LOCALAPPDATA%\LocalWhale\updates | 删除 |
| 脱敏日志 | %LOCALAPPDATA%\LocalWhale\logs | 删除 |

LocalWhale 不读取、复制或迁移 Harness API Key。插件兼容性评估只读取 .dsh 下的 dsh-plugin.json 清单文件。日志会脱敏 token、密钥形式的参数和敏感环境变量，并保留最多 14 天、总量不超过 50 MiB。

Harness 更新保护

应用成功启动后会检查官方 npm registry，自动检查最多每 24 小时一次，也可以从设置对话框手动检查。发现新版后可更新、稍后或忽略该版本。

候选版本不会直接覆盖当前版本。更新器会在临时目录中生成锁文件、验证 registry integrity、预取并离线安装，然后使用临时 DSH_HOME 和 WebView2 数据目录执行 bridge、首页加载、前端启动错误与优雅关闭冒烟测试。未知生命周期脚本会使候选版被拒绝；验证失败时当前会话和当前已知良好版本保持不变。新版连续启动失败时运行状态策略会回滚到上一版本。

插件生态与版本适配（dsh-ecosystem-spec）

LocalWhale 实现了 dsh-ecosystem-spec（DSH 社区生态互操作规范）0.15 的插件准入模型，规范原文与 Host Descriptor JSON Schema 已随仓库引入 third-party/dsh-ecosystem-spec/。在 .dsh 目录（或 DSH_HOME）中带有 dsh-plugin.json 清单的插件，会在每次发现或验证 Harness 更新时按五状态准入模型评估：兼容、降级运行（缺失的可选契约按清单声明的 fallback 回退，不影响更新）、需授权、不兼容或无法判定，结果逐项写入日志并在更新提示中汇总显示。

- 插件使用者：dsh 升级不再让插件「无声失效」——更新卡片会先告诉你哪些插件兼容、哪些降级运行。评估只读取 dsh-plugin.json 清单文件，不触碰会话、凭据或其他 .dsh 数据。
- 插件开发者：为插件提供符合规范的 dsh-plugin.json（声明 manifestVersion: "0.15"、facets.host.apiVersion 与 requires.contracts；可选契约务必附带 fallback 描述），即可获得跨 dsh 版本的兼容性判定。LocalWhale 通过 HarnessContractProfile 适配表把每个 Harness 版本映射到它向插件暴露的契约坐标；新 dsh 版本未登记时回退到最新已知适配，不会因此阻断评估或更新。
- 生命周期脚本白名单同样遵循「内容锁定而非版本锁定」：同一依赖在新版本中脚本内容不变即自动放行。

本地客户端更新（v0.1.2 起）

LocalWhale 自身的更新独立于 Harness。设置里可以开关「自动检查本地客户端更新」，默认开启，最多每 24 小时查询一次 GitHub 最新发布，也可以在设置里立即检查。发现新版本时会弹出右下角系统通知和应用内更新卡片；点击「下载更新」后，LocalWhale 会下载新版安装包并逐字节校验 SHA-256（与 Release 的 SHA256SUMS.txt 比对），校验通过后暂存到 %LOCALAPPDATA%\LocalWhale\updates。此后任意一次重启 LocalWhale，都会在进入界面前再次校验暂存包并静默完成覆盖安装，随后自动回到新版；暂存损坏或安装失败会自动清理并照常启动，不影响当前版本。也可以忽略指定版本或选择稍后。

常见问题

显示「Harness 启动失败」

先打开右上角设置按钮（齿轮），在「诊断」中选择「打开日志」。v0.1.0 已修复官方 Harness 首次创建 profile 链接时可能出现的 ERR_MODULE_NOT_FOUND：只在错误来源确实位于当前 DSH_HOME\profiles 时自动启动第二次，端口占用和其他启动错误不会被误判重试。

如仍失败，请在 Issue 中附上：

- LocalWhale 与 Harness 版本；
- Windows 版本；
- 脱敏后的日志末尾；
- 安装路径是否包含中文或空格；
- 是否能够稳定复现。

请勿上传 %USERPROFILE%\.dsh、API Key、完整环境变量或私人会话内容。

重启后配置像「消失」了

正常发布版始终使用官方默认 %USERPROFILE%\.dsh，卸载也不会删除它。开发验收时可通过 DSH_HOME 启动隔离配置；这只会显示另一个配置目录，不代表原数据被删除。

3080 端口被占用

无影响。LocalWhale 使用 --port 0 让系统分配空闲端口，不依赖固定的 3080。

从源码构建

要求：

- Windows 11 x64；
- .NET 10 SDK；
- Inno Setup 6（仅构建安装包需要）；
- 网络连接（首次准备固定版本的发布运行包时需要）。

dotnet test .\LocalWhale.slnx -c Release
dotnet build .\LocalWhale.slnx -c Release
node --test .\bridge\test\bridge.test.mjs
.\tools\Build-Release.ps1

生成结果：

- unpackaged self-contained 应用：artifacts\publish\
- 标准安装包：artifacts\installer\LocalWhale-Setup-x64.exe

Build-Release.ps1 会下载并校验固定版本的 Node、pnpm、Harness 和 WebView2 离线安装器。CI 只构建和测试源码，不发布未经本地验收的安装包。

工程结构

src/LocalWhale.App/ WinUI 3、TitleBar、Mica、WebView2、托盘与更新卡片 src/LocalWhale.Core/ 生命周期、Job Object、持久化、日志、更新与回滚策略 bridge/ 通过 Harness --patch 加载的 Cordis 桌面 bridge installer/ Inno Setup 脚本与简体中文语言文件 tests/ xUnit 单元/集成测试与 Node bridge 测试 tools/ 运行包准备、发布构建和验收脚本 licenses/ 上游 MIT License 与第三方声明

固定的初始运行版本：

| 组件 | 版本 |
| LocalWhale | 0.1.5 |
| DeepSeek Harness | 0.1.0-rc.6 |
| Node.js | 24.18.1 |
| pnpm | 11.7.0 |
| Windows App SDK | 2.3.1 |

当前状态与资源观测

这是面向个人本机使用的公开 preview。v0.1.0 开发机 Release x64 二次稳定验收样本中，启动约 1.85 秒、Harness Node 私有内存约 121 MiB、空闲 CPU 约 0.013%、完全退出约 0.53 秒；安装发布目录约 395 MiB。本地客户端私有内存约 110 MiB，本地客户端、Harness 与 WebView2 后代进程的工作集直接求和约 684 MiB（其中会重复计算共享页），尚未达到最初的 90 MiB / 350 MiB 资源目标。v0.1.1 的鲸鱼娘 PNG 解码后理论像素占用约 5.2 MiB，并且默认主题不会加载该图片。WebView2 版本、页面内容、GPU 和系统缓存都会显著影响这些数字；它们是单机观测，不是跨机器保证。

当前不支持 Windows 10、ARM64、Microsoft Store、跨平台、公开更新签名或完整 DeepSeek fork。

LocalWhale 提供什么

LocalWhale 把官方 DeepSeek Harness WebUI 打包成原生 Windows 11 x64 桌面体验：

- 原生 WinUI 3 与 Windows App SDK 外壳，带 TitleBar、Mica、Fluent 控件、Snap、托盘集成和高 DPI 行为；
- 通过官方 Harness --patch 插件机制加载的 Cordis 桌面 bridge；本仓库遵循上游建议，使用 dsh-plugin 话题；
- 可执行文件、任务栏、Alt+Tab、托盘和安装程序统一使用一个简洁的 LocalWhale 标记；
- 默认提供 Original 主题，另有可选的 WhaleGirl 宿主主题；
- 托管 WebView2，不注入 CSS、不套 iframe、不改动上游 UI；
- 内置 Node、pnpm、Harness，以及离线 WebView2 安装程序；
- 服务在随机 loopback 端口上隐藏启动；
- 桌面健康检查/关闭桥接每次启动都做 token 认证；
- 优雅关闭，随后由 Job Object 清理进程树；
- 单实例激活、可选托盘行为、脱敏的轮转日志；
- Harness 更新前先做隔离验证，并带回滚保护；
- 针对上游首次 profile 模块链接竞态，只做一次有上限的重试；
- 专门的 Harness 重启按钮，外加原生设置对话框，可配置关闭到托盘、主题、更新检查和日志；
- 外壳自更新：检查 GitHub release（24 小时一次，可开关），点击下载并做字节级 SHA-256 校验，下次启动时静默重装并重启更新后的外壳。

安装

从本仓库的 Releases 页面下载 LocalWhale-Setup-x64.exe。按用户安装的 Inno Setup 向导始终显示目标目录页，默认路径为 %LOCALAPPDATA%\Programs\LocalWhale。首次启动不需要系统 Node、pnpm、.NET Runtime，也不需要联网。

首个个人版本未签名。请只从本仓库下载；当 Windows 提示未知发布者时，把安装程序与 SHA256SUMS.txt 比对一下。

外观与 v0.1.0 升级

0.1.1 版采用 Windows App SDK 的 TitleBar、Fluent 风格的启动/恢复卡片，以及用于 Harness 更新的原生 InfoBar。Original 仍是默认主题，跟随 Windows 的浅色、深色和高对比度模式。WhaleGirl 需在设置对话框（标题栏的齿轮按钮）的 Appearance 下手动开启，只在宿主自有的启动、恢复和关于界面加入项目原创、AI 辅助设计的社区角色。窗口变窄时插画会收起，高对比度模式下禁用。

两个主题都不会向 WebView2 注入样式或脚本。上游 Harness 的 DOM、CSS、信息架构和客户端插件保持原样。v0.1.0 的 settings.json 若没有主题字段，会迁移到 Original，同时保留关闭行为、忽略的 Harness 版本和上次更新检查时间。%USERPROFILE%\.dsh 中的官方数据和凭据，本次迁移绝不读取、移动或改写。

隐私与本地数据

官方 Harness 数据保留在 %USERPROFILE%\.dsh；卸载时 LocalWhale 绝不删除它。外壳设置、运行时包、WebView2 数据、暂存文件和脱敏日志位于 %LOCALAPPDATA%\LocalWhale，由卸载程序删除。桥接 token、端口和 PID 只存在内存中。

构建与测试

在 Windows 11 x64 上，使用 .NET 10 SDK：

dotnet test .\LocalWhale.slnx -c Releasepowershell
dotnet build .\LocalWhale.slnx -c Release
node --test .\bridge\test\bridge.test.mjs
.\tools\Build-Release.ps1

安装程序会输出到 artifacts\installer\LocalWhale-Setup-x64.exe。架构、更新安全模型、数据边界、故障排查清单、仓库结构和实测资源说明，见上面的中文章节。

参与贡献

欢迎提交 bug 报告和聚焦的 pull request。请附上可复现的用例，并让改动留在项目边界之内：WinUI 桌面宿主可以通过文档里写的补丁/插件机制与 Harness 集成，但不能悄悄 fork 官方 WebUI，也不能给它换皮。参照 DeepSeek Harness 社区指引，兼容的集成可以用 dsh-plugin 话题方便别人发现。

提交改动之前，先跑一遍 .NET 和 bridge 两套测试。绝对不要提交 API key、%USERPROFILE%\.dsh、生成的运行时、WebView2 用户数据、日志或安装程序产物。

许可证

LocalWhale 源码基于 MIT License 提供。DeepSeek Harness 仍遵循其上游 MIT License；它的许可证副本和其他再分发组件的声明都在 licenses/ 里。

DeepSeek 及相关标识归各自所有者所有。LocalWhale 是独立的社区项目，与 DeepSeek 无隶属关系，也未获其认可或赞助。LocalWhale 标识和 WhaleGirl 角色是社区项目的原创素材，并非 DeepSeek 官方品牌。