cc-haha/release-notes/v0.4.0.md

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 示例：

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 解压出来，把前两行改成：

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：

chmod +x Claude-Code-Haha-0.4.0-linux-x86_64.AppImage
./Claude-Code-Haha-0.4.0-linux-x86_64.AppImage

deb：

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 链路需要的资产。

发布前建议先运行：

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 写清楚。