penglai-doll/LocalWhale-macOS

LocalWhale for macOS

macOS 14+
Apple Silicon
dsh-plugin
License: MIT

平台版本 / 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。

英文

它是什么

LocalWhale 在原生 WKWebView 中呈现官方 DeepSeek Harness WebUI，同时负责进程启动、随机回环端口、优雅终止、独立更新和回滚。它不会注入 CSS 或脚本，不会将 UI 包裹在 iframe 中，也不会 fork 上游前端。

首个 Preview 面向 macOS 14 或更高版本上的 Apple Silicon。Developer ID 签名和 Apple 公证暂缓；Sparkle 更新归档使用 EdDSA，发布下载包含 SHA-256 校验和。

生命周期与更新

- Shell 和 DSH Core 拥有独立版本。
- Shell 更新会执行完整的 LocalWhale 重启。
- DSH 更新仅重启 DSH 并重新连接现有窗口。
- 用户可以直接跟踪 npm 或 GitHub；npm 是默认的 Runtime Source。
- 候选 Core 会在不显示窗口的情况下进行冒烟测试，除非用户禁用该门控。
- Previous Core 保持可用，以便自动或手动回滚。
- 默认情况下，关闭最后一个窗口即退出；可选的菜单栏模式会让 DSH 保持存活。

构建

运行 xcodegen generate，然后构建或测试 LocalWhaleApp scheme。使用 tools/prepare-runtime.sh 获取捆绑的 arm64 Core，使用 tools/build-preview.sh 生成发布产物，使用 tools/verify-preview.sh 进行端到端包验证。

项目边界

LocalWhale 是一个独立的社区项目，与 DeepSeek 无关联，也未获得其认可。DeepSeek Harness 仍受其上游许可证约束。LocalWhale 标志和 WhaleGirl 角色是原创项目资产，复用自 Windows 版本。

许可证

LocalWhale 采用 MIT 许可证。第三方声明收集在 licenses/ 下。