diff --git a/release-notes/v0.4.0.md b/release-notes/v0.4.0.md
new file mode 100644
index 00000000..f14d215d
--- /dev/null
+++ b/release-notes/v0.4.0.md
@@ -0,0 +1,129 @@
+# 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 写清楚。