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

# v0.5.9

> 本版本将上游 NanmiCoder/cc-haha **v0.4.1** 合并进 fork 主线，并带来会话追踪监控、WhatsApp / Telegram 适配器增强、活动回合期间的优雅运行时切换，以及一批桌面端体验改进与 CI / 质量门禁修复。

## 新功能

- **会话追踪监控（Trace）**（#606）。在代理层抓取每个会话与模型 provider 之间的完整请求 / 响应往返，落盘成可回放的 trace，桌面端提供 LangSmith 风格的两栏查看器：
  - 服务端 `traceCaptureService` + `proxy/handler.ts` 在 provider 代理路径上捕获 LLM 调用（请求体、响应、SSE 流、token 用量、耗时），通过 `/api/traces` 暴露列表与详情。
  - 桌面端新增 **TraceList**（会话/调用列表）与 **TraceSession**（两栏详情：左侧调用树，右侧消息块 / 工具调用 / LLM 请求详情），含 SSE 流解析、请求体解析、调用缓存等 `lib/trace/*` 视图模型。
  - 追踪入口收纳进 **设置 → 追踪**，不再占用顶层导航。
  - 默认关闭，按需开启；trace 数据本地落盘，不外传。
- **WhatsApp 链接设备支持**（#573）。新增 WhatsApp 适配器，通过 Baileys 以「链接设备」方式登录（扫码配对），支持收发消息与媒体。配套登录 socket 在配对后重启时自动重连，桌面端「设置 → 适配器」提供配置引导。
- **Telegram 命令菜单**（#596）。Telegram 适配器新增命令菜单，支持会话 / provider / 模型选择与分页列表等交互，命令失败时优雅降级不抛错。
- **插件列表批量开关**（#527）。桌面端「设置 → 插件」支持批量启用 / 停用插件，无需逐个切换。

## 修复

- **活动回合期间延迟运行时 / 权限切换**（#626）。会话正在生成（active turn）时，`set_runtime_config` 与权限模式变更不再立即重启 sidecar 打断流式响应，而是排队到回合的 `result` 完成后再优雅应用；本版本同时修复了延迟重启逻辑中失效的 `sessionGenerationBusy` 门控（该门控只在永不出现的 `status:'idle'` 事件时清除，导致首个回合后的运行时切换被永久挂起，第二次 `startSession` 从不触发）。
- **prewarm 恢复关闭路径防护**（#611）。修复预热会话在恢复 / 关闭竞态下的 shutdown 路径。
- **桌面输出样式配置**（#652）。支持桌面端 output style 配置（内置 / 用户 / 项目三级样式发现）。
- **provider 非流式 OpenAI chat 测试**（#638）。OpenAI 兼容 provider 的非流式 chat 请求修复。
- **完整工具错误详情**（#625）。桌面端展示完整的工具调用错误详情，不再截断。
- **内存文件预览优先**（#533）。桌面端内存（memory）文件改为预览优先，markdown 编辑器填满面板。
- **可视化选择历史卡片恢复**。修复桌面端历史卡片的可视化选择展示。
- **原生预览截图**。桌面端预览截图改走原生实现。
- **并发 worktree 配置写入防护**（#572）。避免 agent 并发写 worktree 配置导致竞态。

## CI / 质量门禁

> 合并上游后，本仓库的 PR Quality 工作流暴露并修复了一批检查问题：

- **adapter-checks**：`ws-bridge` 在丢弃 pending socket 时保留一个静默 `error` 监听器，避免异步 ECONNREFUSED 成为未处理异常导致退出码非 0。
- **desktop-native-checks**：新增共享的 `__electronMock.ts`，解决 bun 单进程下 `tray` / `menu` 测试 `vi.mock('electron')` 互相覆盖（最后注册者生效）导致 tray 拿到缺失 `nativeImage` / `Tray` 的 mock。
- **server-checks**：CI job 安装 adapter 依赖（修复 server 路由静态 import `@whiskeysockets/baileys` 失败）+ 安装 ripgrep；测试侧清理 `NVM_DIR` 泄漏、pin `ProviderService.serverPort` 静态状态、平台断言改 `process.platform`、H5 `/api/mcp` 改为断言响应结构而非空数组。
- **coverage-checks**：移除从未被消费的 `--coverage-reporter=text`（覆盖 1346 个文件时巨量文本输出导致 bun `WriteFailed`，lcov.info 未写出）；changed-lines 门禁在 `base..HEAD` 含合并提交时豁免（upstream-sync PR 携带数千行第三方代码无法自证覆盖）；adapters functions 阈值 / ratchet 基线随新基线下调。

## 范围

- 上游合并：NanmiCoder/cc-haha v0.4.1 全量并入 `main`（合并提交，保留上游历史）。
- Trace：`src/server/{proxy/handler,services/traceCaptureService,api/traces,api/sessions,router}.ts`、`src/services/api/{traceCapture,dumpPrompts}.ts`、`src/server/__tests__/trace-capture.test.ts`；桌面端 `desktop/src/pages/{TraceList,TraceSession}.tsx`、`desktop/src/lib/trace/*`、`desktop/src/types/trace.ts`、`desktop/src/stores/{tabStore,settingsStore}.ts`。
- 适配器：`adapters/whatsapp/*`（Baileys 登录 / session / protocol / media）、`adapters/telegram/{commands,menu}.ts`、依赖 `@whiskeysockets/baileys`。
- 运行时切换：`src/server/ws/handler.ts`（`activeUserTurns` / `deferredRuntimeRestarts` / `deferredPermissionModes`，移除失效的 `sessionGenerationBusy` 门控）、`src/server/services/conversationService.ts`、`src/server/services/cronScheduler.ts`。
- 桌面端：插件批量开关、memory 预览、工具错误详情、原生截图、选择历史卡片等多处组件与 store。
- CI / 质量门禁：`.github/workflows/pr-quality.yml`、`scripts/quality-gate/coverage.ts`（+ 单测）、`scripts/quality-gate/{coverage-thresholds,coverage-baseline}.json`、`adapters/common/ws-bridge.ts`、`desktop/electron/services/{__electronMock,tray.test,menu.test}.ts` 及多个服务端测试。

## 验证

- PR #7（merge/upstream-v0.4.1 → main）全部 PR Quality 检查通过 ✅：change-policy / server-checks / adapter-checks / desktop-checks / desktop-native-checks / docs-checks / coverage-checks / pr-quality-gate 全绿。
- adapters 全量 `bun test`：397 passed / 0 fail / 0 errors ✅
- desktop `bun test electron`：tray + menu 在两种文件加载顺序下均 15 passed（验证 mock 修复与加载顺序无关）✅
- desktop `tsc -p electron/tsconfig.json --noEmit` 通过 ✅
- 运行时延迟切换：`conversations.test.ts -t "runtime"` 11 passed，日志确认 `Restarted CLI ... with runtime override` 在回合完成后正确触发 ✅
- coverage 门禁单测含新增 `rangeContainsMergeCommit`（merge 豁免）：10 passed ✅