penglai-doll/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 是一个基于 .NET 10、WinUI 3 和 Windows App SDK 的原生 Windows 11 桌面宿主。运行 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。

English

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 安装器；
- 在随机回环端口上隐藏启动服务；
- 为桌面健康检查/关闭 bridge 提供每次启动的令牌认证；
- 优雅关闭，随后通过 Job Object 清理进程树；
- 单实例激活、可选托盘行为、脱敏的轮转日志；
- 对 Harness 更新进行隔离验证和回滚保护；
- 针对上游首次配置模块链接竞态的一次有界重试；
- 专用的 Harness 重启按钮，以及用于关闭到托盘、主题、更新检查和日志的原生设置对话框；
- 外壳自更新：GitHub 发布检查（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 在卸载期间绝不会删除它。Shell 设置、运行时包、WebView2 数据、暂存文件和脱敏日志位于 %LOCALAPPDATA%\LocalWhale 下，并由卸载程序删除。桥接令牌、端口和 PID 仅存于内存中。

构建与测试

在搭载 .NET 10 SDK 的 Windows 11 x64 上：

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

安装程序生成到 artifacts\installer\LocalWhale-Setup-x64.exe。有关架构、更新安全模型、数据边界、故障排除清单、仓库地图和实测资源说明，请参阅上方的中文部分。

贡献

欢迎提交错误报告和有针对性的拉取请求。请包含可复现的案例，并将更改保持在项目边界内：WinUI 桌面宿主可以通过文档化的补丁/插件机制与 Harness 集成，但不得静默地分叉或重新设计官方 WebUI 的样式。根据 DeepSeek Harness 社区指南，兼容的集成可以使用 dsh-plugin 主题进行发现。

在提交更改之前，请运行 .NET 和桥接测试套件。切勿提交 API 密钥、%USERPROFILE%\.dsh、生成的运行时、WebView2 用户数据、日志或安装程序产物。

许可证

LocalWhale 源代码在 MIT 许可证 下提供。DeepSeek Harness 仍受其上游 MIT 许可证约束；其许可证副本和其他再分发组件声明位于 licenses/ 中。
DeepSeek 及相关标识归其各自所有者所有。LocalWhale 是一个独立的社区项目，与 DeepSeek 无关联、未获其认可或赞助。LocalWhale 标识和 WhaleGirl 角色是社区项目的原创资产，并非 DeepSeek 的官方品牌标识。