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

# Claude Code Haha v0.5.0

这是 `v0.4.11` 之后的界面重做版本。桌面端整体视觉按「纸·墨·印」设计稿重构，底层抽出一套组件库替换散落各处的原生控件，品牌标记从位图改为随主题重绘的矢量，并新增跟随系统深色/浅色外观。同时修复了工具拒绝中断整轮、流式传输中断不重试、MCP 父级配置无法删除、用量统计重复计数等一批问题。

版本号从 `0.4.11` 直接跳到 `0.5.0`：本轮改动的主体是表现层的整体替换而不是逐点修补，用 patch 号继续累加会低估变更范围。跳号不影响应用内自动更新，`electron-updater` 按 semver 比较版本，`0.5.0` 对任何 `0.4.x` 都是更新版本。

## Highlights

- **「纸·墨·印」全量 UI 重设计**：6 套主题（纯白、纸墨、经典暖色、青瓷、墨夜、墨夜蓝），采用源色块加单一语义映射层的两层 token 结构；标题改用自托管的 Noto Serif SC 衬线拉丁分片，中文回退系统衬线；圆角、阴影、动效阶梯统一定稿。外壳、零态、活跃会话、composer 全部弹层、技能市场、定时任务、设置全分区、Trace、终端和 ⌘K 均已重做。只换表现层，功能、数据契约与交互逻辑不变；旧的 `light` 主题设置会自动迁移到 `warm-classic`。
- **桌面端组件库**：新增 `components/ui` 原语层（24 个组件）与 `components/composite` 共享部件层，替换此前散落的原生控件——362 个原生 button 只有 22% 复用率，图标按钮存在 15 种圆角、12 种尺寸，41% 没有焦点环，10 个没有可访问名称。组件复用率现为 75%，剩余部分是 `role="tab"`、`menuitem`、整行整卡点击目标等不应组件化的元素。四道守门测试分别校验分层依赖、token 可解析、对比度达 AA 和调用方数量。
- **品牌标记矢量重建**：应用图标从 120KB 位图重建为矢量几何，可以随主题重新着色——两个 C 取墨色，印章条、光标和星芒取朱色。所有消费点按尺寸减件：星芒在 40px 以上、光标在 24px 以上，C 与印章条始终保留。应用图标本身保持一份固定艺术稿（Dock 与任务栏由系统绘制，不感知应用内主题），应用内的标记则是跟随主题重绘的矢量。
- **跟随系统深色/浅色外观**（#1106）：设置 → 通用新增开关。系统只报告 dark/light 而应用有 6 套主题，因此调色板选择器按底色分为「浅色模式使用」和「深色模式使用」两组，各自记住偏好。同时修掉了每次启动先刷白屏的问题——`index.html` 此前硬编码 `data-theme="white"`，而读取已存主题的代码要等应用包动态导入完成才运行；现在有一段同步内联脚本在任何样式表解析前解析主题，Electron 也从缓存的外观预置窗口背景色。新装默认跟随系统，已有安装保持原有固定主题直到用户主动开启。
- **侧边栏宽度可调**：右边缘 8px 拖拽手柄，宽度在 240–480px 之间，持久化到 localStorage，双击回到 300px，方向键可微调。向左拖过 240px 会停住，越过 180px 才收起为窄栏，回来时越过 200px 才展开——20px 的滞回区间避免手抖时反复开合。设置侧栏从 260px 收到 220px（200px 会让日语「コンピューター操作」截断，实测阈值在 210px）。
- **运行位置收敛为单个 pill**：目录、分支、worktree 原本是 composer 下方独立条上的三个按钮，现在合并为工具栏行内的一个 pill，与「+」和模型选择器同行。会话草稿阶段可编辑，发出首条消息后转为只读，位置不变。分支名截断保留尾部（`…use-native-on-main` 而非 `feature/comp…`），因为尾部才是区分度所在。
- **技能市场改为滚动加载**：翻页从「加载更多」按钮改为提前 400px 触发的滚动观察，加载中显示占位卡片；首屏骨架卡数量按可用空间测算而不是固定 6 张。加载失败有独立的内联提示和重试，不再整块清空目录，也不会自动重试撞进同一个失败。
- **宠物动作表放宽为任意尺寸**：导入动画宠物此前要求文件精确为 1536×2288、88 格无缝排布，没有图像模型会输出这个尺寸，所以这条路每次都终止在尺寸校验上；而「AI 生成完整动画」那张卡是硬编码 `disabled` 的死入口。现在任意尺寸的 8×9 动作表都会在浏览器端自动切格、缩放、镜像生成向左跑，并复用行补齐 11 组动作。已经是 1536×2288 的图集原样通过，不做重采样。新增白底检测：透明像素低于 5% 的图集会被拒绝并说明原因，此前这类图会安静地导入并在桌面上渲染成一个矩形。
- **`.agents/skills` 跨客户端约定**（#1093）：识别多个 AI 客户端共用的 `.agents/skills` 目录约定。

## Fixes

- 修复对话框背景可以直接看穿的问题。`.glass-panel` 把半透明填充和模糊写在同一条规则里，只有两者都生效才呈现毛玻璃；而 `backdrop-filter` 不生效时 CSS 不会报错，只是跳过声明，留下 0.84 的填充独自承担，导致 16% 的页面内容清晰透出。对话框现在使用按构造不透明的 `--color-surface-dialog`，完全不依赖模糊。
- 修复拒绝工具权限后整轮对话静默结束的问题（#1051）。桌面端的拒绝以 `interrupt: true` 回给 CLI，触发 abort，拒绝虽然写进了 transcript 却再没有发起后续请求，模型既不知道被拒绝也没机会回应。现在发送 CLI 自己使用的拒绝文案，模型会被再次询问并给出回复。ExitPlanMode 的语义相反——拒绝计划意味着「继续规划」——因此使用单独的文案。
- 修复流式传输被中断后不重试的问题。Grok 上出现的 `The socket connection was closed unexpectedly` 是 Bun 在读取被对端 RST 的响应体时抛的裸 Error，三条恢复路径全部漏过：`withRetry` 只包裹建流不包裹消费，`isRetryableStreamError` 要求 SSE body 里带 `api_error` 的 APIError，而桌面端注入了禁用非流式回退的开关。现在按传输层错误码（ECONNRESET/EPIPE 等）沿 cause 链判定并重建流。重试受与看门狗相同的副作用边界约束：一旦有 tool_use 块完成或服务端工具活动开始，断连会如实上报而不是重放。
- 修复 Grok Responses 请求的四处偏差（对照官方 CLI 逐条用实际请求验证）。指定工具的 `tool_choice` 此前被翻译成 Chat Completions 语法，Responses 端点直接返回 422，导致所有指定工具的请求整体失败；另外补上 `prompt_cache_key` 与 `x-grok-conv-id` 的会话级身份复用，避免每轮重复计费整个前缀。
- 修复父目录 `.mcp.json` 中声明的服务器无法删除的问题（#1107）。读取会从当前目录向上遍历继承所有 `.mcp.json`，删除却只看当前目录自己的文件，于是这类服务器显示为可删除、点删除后报「发生未知错误」。同时修掉一个凭据泄露：新增服务器时会重建整个配置文件，把 `${VAR}` 展开后的值写回磁盘——实测 `"Bearer ${MY_MCP_TOKEN}"` 被写成了明文密钥，而这个文件通常是要提交的。
- 修复后台 agent 工作时思考块被切成多段的问题（#1108）。后台 agent 的工具活动会以带 `parentToolUseId` 的普通事件重新发出并落在消息数组末尾，而流式思考块的合并判断看的是数组尾部是不是思考块——尾部变成了子工具调用，于是之后每个分片都另起一个气泡。现在合并时跳过这些冒泡的子消息。
- 修复 `TaskUpdate` 删除的任务仍留在活动面板的问题（#1101）。`deleted` 是删除动作而不是状态，CLI 会直接删掉任务文件；活动面板把它当状态解析，落到 `pending` 兜底并一直挂在面板上。
- 修复用量统计把一条助手回复重复计算的问题。Claude Code 按 content block 逐行写 JSONL，每行都重复完整的 `usage` 对象，两条统计路径都在累加——本仓库里一条跨 52 行的真实消息带 50.8K token，被统计成 2.65M。同时修掉：成本字段此前是从未赋值的死代码；未知模型不再按 Claude 价格计费（12.7% 的 token 来自第三方 provider）；「最长任务」此前用首尾时间差衡量，跨夜恢复的会话会把整晚算进去，实测出现过 436 小时和 1137 小时的读数，现在按 30 分钟以内的间隔累计有效工作时间；workflow 子 agent 的 transcript 此前从未被索引。
- 修复会话头部占用过高的问题。重设计后的头部把不截断的 22px 标题叠在元信息行上方，长标题会折行把正文推下去；现在标题单行截断、元信息移到标题下方一行，实测从 123.5px 收到 66.75px，完整标题保留在悬停提示里。
- 修复被拖动的宠物无法贴到 macOS 菜单栏的问题。macOS 会把已显示窗口的 frame 交给 `constrainFrameRect:toScreen:` 改写，任何高于工作区的 y 都被静默拉回顶边——实测只有顶边受约束，左右和下边一直正常。`enableLargerThanScreen` 是唯一能跳过该方法的开关。同时修复了重启后位置漂移：窗口在渲染进程报告吉祥物区域之前就已创建，恢复时按整窗裁剪会低开一个内边距的高度。
- 修复 Windows 上被拖动的宠物被裁切、无法贴到显示器边缘、重启后不保持位置的问题（#1099、#1104）。
- 修复粘贴的图片渲染成通用文件卡的问题。粘贴文件统一走原生路径后，所有附件都被标为 `type: 'file'` 且没有预览源，而重开标签页时又能从 transcript 的内联图片块正确显示——实时显示与恢复显示出现分歧。现在按扩展名解析图片附件的显示源，WebSocket 负载仍保持只传路径。
- 修复 Skill frontmatter 被当作 Markdown 渲染的问题。YAML 块的收尾 `---` 被解析成 setext 标题标记，整块 frontmatter 渲染成一个巨大的加粗 `<h2>` 压在文档上方。现在拆出来按结构化行排版。
- 修复插件重载失败仍报告成功的问题。变更已落盘但运行时重载失败的那一半此前完全静默，与正常成功的提示无法区分。
- 修复 loopback 请求在桌面进程令牌存在时全部被拒的问题。此前一旦桌面外壳注入令牌，loopback 地址就不再构成信任依据，而系统浏览器永远拿不到这个令牌——Grok OAuth 成功页、`/preview-fs` 链接和普通 curl 全部返回 401。现在 loopback 恢复为独立可信，令牌只在 `/api/h5-access` 控制面强制要求（同一台机器上的其他程序不得把用户会话发布到网络）。同时补上一个更早就存在的 CSRF 漏洞：`if (!origin) return true` 也接受跨站子资源加载，现在用 Fetch Metadata 区分真实导航与子资源。
- 修复 Windows 上 `taskkill` 缺失时的处理（#1091），以及 `electron:dev` 启动器在 Windows 上不可用的问题。
- 修复同名 skill 在多个根目录下解析不一致的问题，以及 `.agents` 来源标记、doctor 检查和列表安全性的若干偏差。

## Features and Improvements

- 会话元信息、附件画廊、图片灯箱、页内查找的控件补齐可访问名称与键盘操作；灯箱支持方向键和首尾循环，单图时不显示箭头。
- 48 个此前硬编码的用户可见字符串补齐 5 个语言的翻译键（en / zh / zh-TW / jp / kr），包括 `browser/` 下整块硬编码的中文和多处硬编码英文。`TranslationKey` 由 `en.ts` 推导，缺键是编译错误而不是运行时空白。
- 终端配色从硬编码的 20 个十六进制值改为读取按主题定义的 `--color-terminal-*` token。
- 下拉菜单获得 listbox 语义、方向键导航和焦点返回；21 处手写的外部点击处理统一为 `useDismissable`，默认使用 `pointerdown`——`mousedown` 在触屏上不可靠，这正是 H5 上「点外面菜单不关」的成因。
- 新增仅开发环境可用的组件画廊（`/gallery.html`），在三套主题下渲染全部原语。单元测试无法判断 token 是否解析成可读的颜色、浮层是否盖在该盖的东西上方、入场动画是否真的播放——画廊本身就发现了三个测试全绿却存在的缺陷。
- 文档站用 React 重建，落地页文案重写。
- 组件库的使用规则、分层依据与审计证据记录在 `desktop/src/components/AGENTS.md` 和 `docs/component-library-plan.md`。

## Issue 对照

- #1051：拒绝工具权限后把拒绝结果交回模型，而不是中断整轮。
- #1086：支持粘贴文件附件。
- #1091：处理 Windows 上缺失的 taskkill。
- #1093：识别跨客户端的 `.agents/skills` 目录约定。
- #1099 / #1104：修复 Windows 上宠物被裁切与无法贴边。
- #1101：从活动面板移除已被 TaskUpdate 删除的任务。
- #1106：跟随系统深色/浅色外观，并消除启动白闪。
- #1107：删除父级 `.mcp.json` 中声明的 MCP 服务器。
- #1108：后台 agent 工作期间保持思考块完整。

## Verification

- 本机以 release 模式跑完质量门禁，13 条非 live lane 全部通过：Policy 127 项、Desktop 271 文件 / 3331 项通过 1 项跳过、Server 227 文件 / 2447 项、Adapters 406 项、Provider contract 18 组、Chat contract 全组、Native（sidecar 编译 + Electron 检查 + 目录打包 smoke）、Docs 80 页 / 302 处链接与图片、Persistence upgrade、Quarantine（0 条）、Baseline case catalog。
- Coverage 门禁 5/5 套件通过，Desktop React 行覆盖 90.19%。首次运行时该门禁失败，根因是 `nativeAppearance.test.ts` 的用例未传隔离 env：`check:coverage` 在设有 `CLAUDE_CONFIG_DIR` 的沙箱环境中运行，而该变量的优先级高于 `app.getPath('home')`，使各用例本应独立的缓存路径塌缩成同一个文件，一个用例因此读到另一个用例写入的值。已修复为显式传入隔离 env，与 `windows.test.ts` 既有写法一致，并在设与不设该变量的两种环境下各验证一次。这是测试隔离缺陷，不影响产品行为；`Release Desktop` workflow 不运行该门禁，`pr-quality` workflow 会运行。
- 未执行项，不计为通过：6 条 baseline case 与 1 条 provider live/proxy smoke 需要真实 provider 凭据，本机未运行；`desktop-package-smoke` 需要已签名的本机 release 产物，由 CI 的 `Verify packaged app structure` 与 `Verify macOS launch policy` 覆盖；本轮 UI 重构未做真机逐屏走查；`v0.4.11 -> v0.5.0` 的真实自动更新链路需在 Release 发布后验证。
- 上述证据只覆盖本机候选构建与测试，不等同于正式签名、公证或跨平台安装的端到端验证。

## Notes

- GitHub Release 正文以 `release-notes/v0.5.0.md` 作为唯一来源。
- 桌面端发布版本号来源是 `desktop/package.json`；root `package.json` 继续保留本地开发用的 `999.0.0-local`。发布时必须确保版本号、Git tag `v0.5.0` 和本文件严格一致。
- 版本号从 `0.4.11` 跳到 `0.5.0` 不影响自动更新。`electron-updater` 使用 semver 比较（`semver.gt`）而非字符串比较，且更新元数据取自仓库最新 Release，与版本号是否连续无关。`0.5.0` 不带 prerelease 后缀，仍走稳定通道，元数据文件名不变。
- `Release Desktop` workflow 会构建 macOS、Windows 和 Linux 的 x64 / ARM64 安装包，并在完整资产和 updater metadata 校验通过后公开 Release。
- 自动更新验证路径是正式 `v0.4.11 -> v0.5.0`。发布完成后需核对 `latest-mac.yml`、`latest.yml`、`latest-linux.yml` 和 `latest-linux-arm64.yml`。
- macOS 正式公开发布依赖签名和公证 secrets；Windows 未配置签名时仍可安装和自动更新，但可能显示 SmartScreen 提示。
- 本次是表现层的整体替换，功能与数据契约未变更，已有会话、服务商配置、Skills、Agents、记忆和自定义数据目录不需要迁移。旧的 `light` 主题设置会自动迁移到 `warm-classic`。
- 组件画廊（`/gallery.html`）只在 `bun run dev` 下可达，不进入生产包——Vite 的构建入口只有 `index.html`。

## 安装

在本页面底部 Assets 中按系统和 CPU 架构下载：

| 平台 | 文件 |
|------|------|
| macOS Apple Silicon（M 系列） | `Claude-Code-Haha-0.5.0-mac-arm64.dmg` |
| macOS Intel | `Claude-Code-Haha-0.5.0-mac-x64.dmg` |
| Windows x64 | `Claude-Code-Haha-0.5.0-win-x64.exe` |
| Windows ARM64 | `Claude-Code-Haha-0.5.0-win-arm64.exe` |
| Linux x64 | `Claude-Code-Haha-0.5.0-linux-x86_64.AppImage` 或 `Claude-Code-Haha-0.5.0-linux-amd64.deb` |
| Linux ARM64 | `Claude-Code-Haha-0.5.0-linux-arm64.AppImage` 或 `Claude-Code-Haha-0.5.0-linux-arm64.deb` |

### macOS

双击 DMG，把应用拖入「应用程序」。正式签名和公证产物应直接通过正常 Gatekeeper 流程。

### Windows

双击 `.exe` 安装。建议直接以当前用户运行，不要使用「以管理员身份运行」。覆盖升级前先完全退出应用；如果安装器报告相关进程仍在运行，请根据提示关闭对应进程后重试。未签名构建出现 SmartScreen 时可选择「更多信息」→「仍要运行」。

### Linux

AppImage：

```bash
chmod +x Claude-Code-Haha-0.5.0-linux-x86_64.AppImage
./Claude-Code-Haha-0.5.0-linux-x86_64.AppImage
```

deb：

```bash
sudo apt install ./Claude-Code-Haha-0.5.0-linux-amd64.deb
```

ARM64 机器请换用对应的 `linux-arm64` 文件。