LocalWhale for macOS

平台版本 / Platform editions
macOS（本仓库）：0.1.0-preview.1 · Windows 版 penglai-doll/LocalWhale
macOS (this repository): 0.1.0-preview.1 · Windows edition penglai-doll/LocalWhale

用原生 macOS “壳”承载可独立更新、重启和回滚的 DeepSeek Harness（DSH）内核。

A native macOS Shell for an independently updatable, restartable, and rollback-capable DeepSeek Harness (DSH) Core.

中文说明

项目定位

LocalWhale 把官方 DeepSeek Harness WebUI 放进原生 WKWebView，并负责用户原本需要在终端完成的启动、端口、退出、更新和故障恢复工作。它不会注入 CSS、修改 DOM、套 iframe 或 fork DSH 前端。

首个 macOS Preview 面向 Apple Silicon 与 macOS 14 以上版本。当前 Preview 暂未加入 Developer ID 与 Apple 公证；自动更新归档使用 Sparkle EdDSA，公开下载同时提供 SHA-256。

壳 + DSH 内核

flowchart LR
    A[LocalWhale Shell] --> B[独立进程组启动器]
    B --> C[DSH Core Capsule]
    C --> D[随机 127.0.0.1 端口]
    D --> E[鉴权 Desktop Bridge]
    E --> F[WKWebView 官方 WebUI]
    A --> G[壳更新 / 完整重启]
    A --> H[DSH 更新 / 仅重启 DSH]

每个 Core Capsule 是不可变的完整运行单元：

Node + pnpm + DSH + desktop bridge + lockfile + runtime manifest

• 壳更新：完整重启 LocalWhale。
• DSH 更新：只重启 DSH，当前 macOS 窗口保持存在并重新连接。
• 更新来源：用户可选择 npm 或 GitHub；默认 npm。
• 预发布版：DSH 默认包含 prerelease；壳默认不包含 prerelease。
• 回滚：保留上一内核；默认连续两次启动失败后自动回滚，也可关闭自动行为或手动回退。

本机通信

Desktop Bridge 通过官方 --patch 插件机制加载，只增加：

• GET /__localwhale/v1/health
• POST /__localwhale/v1/shutdown

两个端点都要求每次启动随机生成的 X-LocalWhale-Token。DSH 仅监听随机 127.0.0.1 端口，token、端口和 PID 不写入磁盘。退出时先请求优雅关闭，超时后终止整个独立进程组。

数据边界

数据	位置	壳是否删除
DSH 会话、配置与凭据	~/.dsh	从不
LocalWhale 设置与运行状态	~/Library/Application Support/LocalWhale/	由用户决定
DSH Core Capsules	~/Library/Application Support/LocalWhale/runtimes/	壳管理活动版、上一版与候选版
脱敏日志	~/Library/Logs/LocalWhale/	自动限制为 14 天 / 50 MiB
WKWebView 数据	WebKit 的 LocalWhale 数据目录	可单独清除

LocalWhale 默认不收集遥测。“导出诊断”不会包含 ~/.dsh。

当前固定运行时

项目	版本
LocalWhale macOS	0.1.0-preview.1
DeepSeek Harness	0.1.1-rc.1
Node.js	24.18.1 arm64
pnpm	11.7.0
Desktop Bridge protocol	1

安装 Preview

1. 从本仓库的 Releases 下载 Apple Silicon DMG（推荐）或 ZIP。
2. 将 LocalWhale.app 拖到 /Applications。
3. 当前 Preview 尚未 Developer ID 签名或 Apple 公证；首次启动请在 Finder 中按住 Control 点按 App，选择“打开”，再确认一次。
4. LocalWhale 首次运行会把自包含 Core Capsule 复制到自己的 Application Support；无需预装 Node.js、pnpm 或 DSH。

下载页同时提供 SHA256SUMS。壳会在后台检查并准备更新，但不会自行重启正在运行的 DSH 会话。

开发

要求：Xcode 26、macOS 14+ SDK、Homebrew xcodegen、Node.js 24+。

brew install xcodegen
xcodegen generate
xcodebuild \
  -project LocalWhale.xcodeproj \
  -scheme LocalWhaleApp \
  -destination 'platform=macOS,arch=arm64' \
  -only-testing:LocalWhaleCoreTests \
  test
node --test bridge/test/bridge.test.mjs

准备可离线运行的初始 DSH 胶囊：

./tools/prepare-runtime.sh

构建 Preview .app、ZIP、DMG 与校验文件：

./tools/build-preview.sh
./tools/verify-preview.sh

生成物位于 artifacts/release/。验证脚本会检查 SHA-256、Sparkle EdDSA、代码封装、arm64 架构、ZIP/DMG 一致性，并从最终 ZIP 中实际启动一次 DSH。工程结构和运行状态机见 docs/architecture.md。

English

What it is

LocalWhale presents the official DeepSeek Harness WebUI in a native WKWebView while owning process startup, a random loopback port, graceful termination, independent updates, and rollback. It does not inject CSS or scripts, wrap the UI in an iframe, or fork the upstream frontend.

The first Preview targets Apple Silicon on macOS 14 or later. Developer ID signing and Apple notarization are deferred; Sparkle update archives use EdDSA and release downloads include SHA-256 checksums.

Lifecycle and updates

• The Shell and DSH Core have independent versions.
• A Shell update performs a full LocalWhale restart.
• A DSH update restarts only DSH and reconnects the existing window.
• Users may track npm or GitHub directly; npm is the default Runtime Source.
• Candidate Cores are smoke-tested without showing a window unless the user disables that gate.
• The Previous Core remains available for automatic or manual rollback.
• Closing the last window exits by default; optional menu-bar mode keeps DSH alive.

Build

Run xcodegen generate, then build or test the LocalWhaleApp scheme. Use tools/prepare-runtime.sh for the bundled arm64 Core, tools/build-preview.sh for release artifacts, and tools/verify-preview.sh for end-to-end package verification.

Project boundary

LocalWhale is an independent community project and is not affiliated with or endorsed by DeepSeek. DeepSeek Harness remains under its upstream license. The LocalWhale mark and WhaleGirl character are original project assets reused from the Windows edition.

License

LocalWhale is MIT licensed. Third-party notices are collected under licenses/.