mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-18 13:23:33 +08:00
5cf4480d22
Summarize the v0.3.2 to v0.4.0 Electron migration window and document the installer paths users should follow. Tested: bun run scripts/release.ts 0.4.0 --dry Tested: git diff --check Tested: bun run check:docs Confidence: high Scope-risk: narrow
130 lines
7.6 KiB
Markdown
130 lines
7.6 KiB
Markdown
# Claude Code Haha v0.4.0
|
||
|
||
这是一个以**桌面端底层框架迁移**为核心的大版本。相比 `v0.3.2`，本次最重要的变化是桌面端从 Tauri 2 迁移到 Electron：React/Vite 渲染层、本地 server/sidecar、REST/WebSocket 业务协议继续保留，系统能力改由 Electron main/preload 和 `desktopHost` typed bridge 承载。
|
||
|
||
这次迁移不是简单换壳。原先 Tauri 负责的自动更新、系统通知、文件选择、外链打开、窗口/托盘/菜单、PTY 终端、sidecar 进程、内置浏览器预览、应用模式和窗口状态持久化，都已经被重新映射到 Electron 运行时，并补了对应的 IPC、安全和 package-smoke 验证。
|
||
|
||
## Highlights
|
||
|
||
- **桌面底层迁移到 Electron**：新增 Electron main/preload/preview-preload，以及 sidecar、updater、notification、dialog、shell、window、tray、menu、terminal、preview、app mode、zoom 等主进程服务。
|
||
- **保留业务边界，降低迁移风险**：前端继续使用现有 Zustand store、HTTP API 和 WebSocket 流式协议；不会把会话、聊天、workspace、team 等业务协议改成 Electron IPC。
|
||
- **跨平台打包链路切换为 electron-builder**：macOS 产出 DMG/ZIP，Windows 产出 NSIS 安装器，Linux 同时产出 AppImage 和 deb；release workflow 会校验完整资产和 update metadata。
|
||
- **Electron updater 元数据重建**：从 Tauri 的 `latest.json` 迁移到 Electron 的 `latest-mac.yml`、`latest.yml`、`latest-linux.yml`、`latest-linux-arm64.yml`；macOS 会合并 x64/arm64 update metadata。
|
||
- **打包结构验证加强**：新增 package-smoke 检查，覆盖 `app.asar`、sidecar、`node-pty`、update metadata、blockmap 和 canonical release artifact set，避免缺资源的包被上传或发布。
|
||
- **桌面安全边界重建**：renderer 不暴露 Node/Electron 原始 API；preload 只暴露固定 `desktopHost` contract；IPC channel 和 payload 走 allowlist；外链、本地路径、预览消息和导航都有守卫。
|
||
- **系统交互稳定性修复**：修复 Windows PowerShell 选择未传给 agent sidecar、退出时 sidecar 残留、macOS 外接屏菜单栏异常、窗口拖拽区域、sidebar/titlebar 交互和 Windows AppUserModelID。
|
||
- **Workbench 和聊天体验继续打磨**：agent slash 走正常聊天链路并流式展示进度，选择气泡更稳定，会话标题按用户语言生成，thinking summary 支持 Markdown 且默认收起。
|
||
- **Provider 与输入兼容性改进**：MiniMax preset 升级到 MiniMax-M3，并使用 provider context window 估算；恢复大图和常见长截图读取；桌面 stale auth/socket 会自动恢复。
|
||
- **发布质量治理收口**：恢复 quarantine quality gates，pre-push 改为非阻塞提示，server 测试避免固定端口冲突，Linux deb metadata 和 Linux package-smoke artifact 匹配已修复。
|
||
|
||
## 底层框架迁移说明
|
||
|
||
`v0.4.0` 是第一个 Electron 桌面版本。迁移前桌面端基于 Tauri 2 和系统 WebView；迁移后桌面端使用 Electron/Chromium，宿主能力由 Electron main process 管理，renderer 通过 preload 暴露的 typed bridge 调用。
|
||
|
||
这带来几个用户能感知到的变化：
|
||
|
||
- 安装包体积会比 Tauri 版本明显变大，这是 Electron 自带 Chromium runtime 的正常结果。
|
||
- macOS release assets 里会同时出现 `.dmg` 和 `.zip`。普通用户手动安装只需要 DMG；ZIP、blockmap 和 `latest-mac.yml` 是 Electron auto-update 需要的发布资产，不应该从 GitHub Release 里删除。
|
||
- 旧 Tauri 版本的自动更新 feed 是 `latest.json`，Electron 版本使用 `latest*.yml`。因此从旧 Tauri 版本升级到第一个 Electron 版本时，推荐手动下载安装 `v0.4.0`，把它作为后续 Electron 自更新的基线。
|
||
- 应用 bundle id 仍保持 `com.claude-code-haha.desktop`。直接替换 `/Applications/Claude Code Haha.app` 不会删除 `~/.claude`、`~/.claude/cc-haha` 或用户选择的便携数据目录；少量窗口/UI 本地状态可能会按 Electron 首次运行重新生成。
|
||
|
||
## 下载安装
|
||
|
||
前往 GitHub Release 下载对应系统和架构的文件：
|
||
|
||
| 平台 | 推荐下载 |
|
||
| --- | --- |
|
||
| macOS Apple Silicon | `Claude-Code-Haha-0.4.0-mac-arm64.dmg` |
|
||
| macOS Intel | `Claude-Code-Haha-0.4.0-mac-x64.dmg` |
|
||
| Windows x64 | `Claude-Code-Haha-0.4.0-win-x64.exe` |
|
||
| Linux x64 | `Claude-Code-Haha-0.4.0-linux-x86_64.AppImage` 或 `Claude-Code-Haha-0.4.0-linux-amd64.deb` |
|
||
| Linux ARM64 | `Claude-Code-Haha-0.4.0-linux-arm64.AppImage` 或 `Claude-Code-Haha-0.4.0-linux-arm64.deb` |
|
||
|
||
### macOS
|
||
|
||
正式签名并公证的 DMG：
|
||
|
||
1. 下载与你 Mac 架构匹配的 DMG。
|
||
2. 打开 DMG，把 `Claude Code Haha.app` 拖到 `Applications`。
|
||
3. 从 `Applications` 打开应用。
|
||
|
||
如果本次 0.4.0 因 Apple Developer ID 还未准备好，只能先发布未签名构建，macOS 可能提示 DMG "已损坏"或"无法验证开发者"。这时不要直接双击反复尝试，按下面命令安装。
|
||
|
||
Apple Silicon 示例：
|
||
|
||
```bash
|
||
ARTIFACT_DIR="$HOME/Downloads/Claude-Code-Haha-v0.4.0-macos-arm64"
|
||
DMG="$ARTIFACT_DIR/Claude-Code-Haha-0.4.0-mac-arm64.dmg"
|
||
APP="/Applications/Claude Code Haha.app"
|
||
|
||
xattr -dr com.apple.quarantine "$ARTIFACT_DIR" 2>/dev/null || true
|
||
xattr -dr com.apple.quarantine "$DMG" 2>/dev/null || true
|
||
|
||
MOUNT_OUTPUT="$(hdiutil attach "$DMG" -nobrowse -readonly)"
|
||
VOLUME="$(printf '%s\n' "$MOUNT_OUTPUT" | sed -n 's#^.*\(/Volumes/.*\)$#\1#p' | head -n 1)"
|
||
if [ -z "$VOLUME" ]; then
|
||
echo "未找到 DMG 挂载目录"
|
||
exit 1
|
||
fi
|
||
|
||
osascript -e 'quit app "Claude Code Haha"' >/dev/null 2>&1 || true
|
||
|
||
if [ -d "$APP" ]; then
|
||
BACKUP="$HOME/.Trash/Claude Code Haha.$(date +%Y%m%d%H%M%S).app"
|
||
mv "$APP" "$BACKUP"
|
||
fi
|
||
|
||
ditto "$VOLUME/Claude Code Haha.app" "$APP"
|
||
hdiutil detach "$VOLUME"
|
||
xattr -dr com.apple.quarantine "$APP" 2>/dev/null || true
|
||
open "$APP"
|
||
```
|
||
|
||
如果你是直接从 GitHub Release 下载 DMG，而不是从 GitHub Actions 的 artifact 外层 ZIP 解压出来，把前两行改成：
|
||
|
||
```bash
|
||
ARTIFACT_DIR="$HOME/Downloads"
|
||
DMG="$ARTIFACT_DIR/Claude-Code-Haha-0.4.0-mac-arm64.dmg"
|
||
```
|
||
|
||
Intel Mac 把 `macos-arm64` / `mac-arm64` 替换为 `macos-x64` / `mac-x64`。
|
||
|
||
### Windows
|
||
|
||
下载 `Claude-Code-Haha-0.4.0-win-x64.exe` 后双击安装。如果 Windows SmartScreen 提示未知发布者，选择"更多信息"再选择"仍要运行"。
|
||
|
||
### Linux
|
||
|
||
AppImage：
|
||
|
||
```bash
|
||
chmod +x Claude-Code-Haha-0.4.0-linux-x86_64.AppImage
|
||
./Claude-Code-Haha-0.4.0-linux-x86_64.AppImage
|
||
```
|
||
|
||
deb：
|
||
|
||
```bash
|
||
sudo apt install ./Claude-Code-Haha-0.4.0-linux-amd64.deb
|
||
```
|
||
|
||
ARM64 Linux 对应把文件名替换为 `Claude-Code-Haha-0.4.0-linux-arm64.AppImage` 或 `Claude-Code-Haha-0.4.0-linux-arm64.deb`。
|
||
|
||
## 发布者备注
|
||
|
||
- GitHub Release 正文继续以 `release-notes/v0.4.0.md` 作为来源。
|
||
- 发布前请确认 `desktop/package.json` 版本、tag `v0.4.0` 和本文件名完全一致。
|
||
- 正式 release workflow 目前要求 macOS Developer ID 签名和 notarization secrets；如果缺少 Apple ID / team / app-specific password，正式 signed release 会被 preflight 阻止。
|
||
- 如果需要在签名就绪前先给用户一个临时迁移包，请在 GitHub Release 文案中明确这是 unsigned build，并保留上面的 macOS 命令安装步骤。
|
||
- 不要只上传 DMG 后删除 ZIP、blockmap 或 `latest*.yml`。DMG 是手动安装入口，ZIP 和 metadata 是 Electron auto-update 链路需要的资产。
|
||
|
||
发布前建议先运行：
|
||
|
||
```bash
|
||
bun run scripts/release.ts 0.4.0 --dry
|
||
bun run verify
|
||
bun run quality:gate --mode release --allow-live --provider-model <provider:model[:label]>
|
||
```
|
||
|
||
如果 live provider、Apple Developer ID 或平台实机不可用，请在 release 记录里把 blocker 写清楚。
|