goodbuddy/docs/development/release-preparation-0.15.0.md

# Desktop 与 Agent 0.15.0 发布准备

日期：2026-09-27。候选验证通过，不代表已发布。

## 范围与批准

- 用户要求 Desktop 与 GoodBuddy Agent 同步升级至 `0.15.0`，明确不构建 LoongArch。
- 源码基线：`0f8bf405db7ca21a85cc70009ad083eb837e1e03`。
- Desktop 差异基线为已发布的 `v0.13.16`，Agent 为 `agent-v0.13.4`。
- 准备两个独立标签 `v0.15.0` 与 `agent-v0.15.0`；尚未创建或推送。
- 用户已批准两份完整双语说明，正式正文仅维护在
  [Desktop 发布资源](../../resources/release-notes.json) 的 `0.15.0` 条目与
  [Agent 发布资源](../../resources/agent-release-notes/0.15.0.md)。
  已逐条核对写入文本与批准草案一致，本记录不再复制正文。
- `FEATURES.md` 与 `FEATURES.zh-CN.md` 已核对本轮能力、限制和候选版本。
- 用户要求两张未跟踪宣传截图保留原位、不提交，打标签前另行处理；
  不移动、删除、暂存或更改忽略规则。
- 2026-09-28 用户更新授权：当前工作区的宣传文档与素材可以一起提交、推送，
  后续候选由代理自行审核确认，不再逐次等待用户批准，继续完成双产品正式发布。
  三张新增候选图已读取检查，保留原始草稿属性，不冒充正式发布截图或对外媒体发文。
  发布说明正文保持不变，`releasedAt` 更新为实际准备发布日期 2026-09-28。

## 本地验证

- `npm run typecheck`：通过。
- `npm run lint`：通过。
- `npm run release:notes:verify`：通过。
- 发布说明相关三个文件定向测试：16 项通过。
- 首轮 `npm test`：5,313 通过、79 跳过、4 失败，耗时 697.61 秒。
  三项失败来自当时尚未批准写入的 0.15.0 Desktop/Agent 发布说明；
  另一项为 `magic-notes-layout.electron.test.ts` 的布尔断言。
  该布局用例单独复验 1 项通过，未修改源码或放宽断言。
  单独通过不替代全量结果。
- 正式说明写入后的最终 `npm test`：**5,317 通过、79 跳过、0 失败**，
  453 个测试文件通过、11 个跳过，耗时 645.49 秒。随后再次执行完整
  `npm run typecheck` 与 `npm run lint`，均通过。
- 最终验证期间出现并行宣传文档编辑及新增 `storygraph.png`，均不属于本次
  发布准备改动，不暂存或覆盖。打标签前仍须处理工作区洁净条件。
- 修改文档的相对文件链接、版本一致性和 `git diff --check` 通过。
- 不运行本地生产构建、打包或安装包启动。准确候选提交须经用户批准，
  然后双远端推送、主分支 CI、生产构建、原生发布与公开核验分别进行。

## Agent 当前源码实机验证

共享 Linux x64 Host 的 LAN/VPN SSH 端口均可达，实际通过 LAN 与既有固定
Host Key、加密凭据连接。重新捆绑当前源码的 Agent CLI、daemon、model bridge
与 Desktop 适配器，仅上传独立 `/root/tmp/gb-lifecycle-*` 测试目录，复用已安装且
版本锁未变的 Node/OpenCode/Continue，不替换原安装，不构建正式包。

最终 OpenCode、Continue 各通过一次 Ask 和一次 Execute，无工具请求，
验证回答、后续历史、空闲 Runtime 回收及测试停止后所属进程为 0。
模型请求时读取所属进程的固定遥测字段，确认 `DO_NOT_TRACK=1`、
`OTEL_SDK_DISABLED=true` 及三个 exporter 均为 `none`，不输出整个环境。
这些结果补齐 `eb53c82` 的 Agent/model bridge 真实链路验证，
但不证明后台没有其他网络流量，也不替代三目标正式包验收。

首轮 Continue 探针沿用了 OpenCode 原生历史持久化假设，未像 Desktop 一样传入
`request.history`，第二轮历史断言失败；当前 Continue 冷启动源码明确要求传入
保存历史。修正测试输入及会话 ID 断言后通过，未修改产品实现。

有完整计数的实机运行共 **8 次**真实模型 HTTP 请求：首次 OpenCode 2 次、
首次 Continue 2 次、最终 Continue 2 次、最终 OpenCode 2 次。
此前一次直接启动 Electron 的探针未捕获子进程输出，不能确认是否实际发出请求，
该次上限 2 次，不纳入通过证据；因此不能把 8 次写成本轮精确总数，总量为 8–10 次。
后续均使用等待退出并记录脱敏输出的启动器；本轮探针 Electron 进程已退出。
本地诊断证据在临时 `opencode/release-015-host/`，不提交脚本、日志或凭据。

## 首次候选 CI 与测试修正

用户批准的首次候选 `5a6ba6c14f5c58f3da5e9afe281b18e0cbdb1ae8`
已推送至 `origin/main` 和 `github/main`，未创建两个发布标签。

- [Agent CI 36329271991](https://github.com/mesalogo/goodbuddy/actions/runs/36329271991)
  源码验证及 Linux x64、Linux arm64、Darwin arm64 原生构建全部通过。
- [Desktop CI 36329271967](https://github.com/mesalogo/goodbuddy/actions/runs/36329271967)
  为 5,342 通过、51 跳过、3 失败。两个 App 长历史场景超过默认 5 秒单用例时限；
  会话采集 Electron 场景等待 Escape 返回笔记列表超时。生产构建未运行。
- 测试修正仅让原生键盘辅助函数显示窗口、获取焦点并等待 `document.hasFocus()`，
  然后发送真实输入；两个长历史场景采用仓库既有的 15 秒单用例时限。
  不修改产品实现、不跳过 Linux、不关闭沙箱、不删除或放宽数据和键盘断言。
- Windows 聚焦复验三个失败场景通过，其中真实 Electron 覆盖完整 502 条历史、
  214px 窄栏键盘操作、浅深主题确认按钮、真实 IPC/SQLite 和重开保留。
  修正后首次全量复验被中断，不计为通过；随后完整重跑为 **5,317 通过、
  79 跳过、0 失败**，453 个文件通过、11 个跳过，耗时 646.48 秒。
  类型检查、lint 和发布说明校验均通过，新候选 Linux CI 仍需独立通过。
- 本次只改测试和验证文档，不改变 Agent、远程 Runtime 或模型桥；
  沿用上方当前源码 Host 验证，不新增真实模型请求。
- 新提交必须重新取得准确 SHA 批准，原发布说明正文保持不变。

## Linux 实机复现与最终同步修正

2026-09-28：第二次批准候选 `12594961fe1e814e89f55de1fbfe245310505115`
的 [Desktop CI 36331853137](https://github.com/mesalogo/goodbuddy/actions/runs/36331853137)
为 5,343 通过、51 跳过、2 失败。两个 App 长历史场景已通过；
Escape 返回列表仍失败，活动历史迁移这次超过默认 5 秒时限，生产构建仍未执行。

按用户要求直接在共享 Linux x64 Host 测试准确候选源码。使用独立磁盘测试目录、
锁定 Node 24.19.0 和 `npm ci`，补齐 Xvfb 与匹配的 X server 系统依赖；
没有创建新账号，使用既有非 root 账号运行测试，保留 Electron 沙箱及其标准 helper 权限。
不替换既有 Agent，不修改其安装或工作区，不执行生产构建或打包。

原测试在 Host 上稳定复现：缩窄窗口会按产品既有行为收起工作栏，隐藏面板仍有非零宽度。
诊断显示 Escape 实际发给 `aria-expanded=false` 的工作栏开关，而不是笔记输入框。
因此仅获取窗口焦点不够；测试改为等待窄视口及响应式渲染完成，按真实按钮打开工作栏，
确认展开状态和目标输入框焦点后再发送键盘输入。临时诊断代码已移除。

迁移测试在 Host 上以原默认时限通过，保留 10,000 条记录、完整迁移、WAL 字节比、
扫描次数与无变化写入断言；仅为这一个大数据场景采用已有的 15 秒单用例时限，
不改数据库实现或全局时限。

- 最终 Linux Host 完整 `npm test`：**5,345 通过、51 跳过、0 失败**，
  449 个文件通过、15 个跳过，耗时 751.09 秒。
- Windows 聚焦回归：3 项通过，包含真实 Electron 和迁移。
- Windows 完整类型检查、lint、发布说明校验：全部通过。
- Linux Electron 实测覆盖 502 条历史、218px 窄栏、Escape/Tab/Enter、
  浅深主题确认按钮、真实 IPC/SQLite 与重开保留；Windows 对应窄栏为约 214px。
- 本阶段不新增真实模型请求，不改变产品代码或双语说明。
  新候选仍须重新批准 SHA 并通过自己的主分支 CI/生产构建，两个标签仍未创建。

## 后续 CI 焦点前提与确定性取消验证

`b8b6007` 的 [CI 36335076841](https://github.com/mesalogo/goodbuddy/actions/runs/36335076841)
两次执行均为 5,344 通过、51 跳过、1 失败，失败点改为 `new title focus`，
生产构建没有运行。该次失败未在 Host 的 10 次带诊断复验中重现，其中 5 次限制单 CPU；
移除临时诊断后再测也通过。这些独立结果不替代 CI。

测试原先直到键盘阶段才显示窗口，前面的自动聚焦检查仍在隐藏窗口执行。
现让测试窗口从开始即显示并确认焦点，保留标题自动聚焦原断言；
超时增加实际焦点、标题禁用/可见/隔离状态和保存状态，避免只报告阶段名称。
可见窗口版本在 Host 连续五次聚焦复验通过。

随后 Host 全量出现一个独立的 Continue 取消测试竞争：
`setTimeout(0)` 没有保证取消发生在子进程启动前，空 mock 已被调用。
用例改在既有启动环境回调处精确取消，仍验证回调执行、子进程未启动和临时配置删除，
不更改 Continue 产品实现或取消机制。

- 最终 Host 完整测试：**5,345 通过、51 跳过、0 失败**，449 个文件通过、
  15 个跳过，耗时 743.34 秒。
- Windows 可见窗口 Electron 回归及确定性取消回归通过。
- 完整类型检查、lint 通过；双语说明正文不变，日期调整后另行验证发布资源。
- 上述均为测试或验证文档调整，不新增真实模型调用，不改变 Agent 发布输入。
  正式发布仍要求当前候选自己的 CI/生产构建通过。

## 完整分支快照重新核对

`d9e1e42` 的 [Desktop CI 36340682594](https://github.com/mesalogo/goodbuddy/actions/runs/36340682594)
已通过原生会话采集焦点测试，但为 5,367 通过、51 跳过、4 失败。
核对祖先后确认准备期间另有四个并行提交进入分支：
`ee1bf8a` 输入区控件样式、`8e60736` 流式会话稳定排序、
`f35198d` 桌面通知开关、`d47f967` 监督结果继续讨论。
它们已随用户授权的当前分支推送；前述 Host 的 5,345 项通过使用较早源码快照，
不能作为包含这四项的新候选验证结果。

本轮已重新核对四个提交的实现和文档，补充两份功能矩阵与双语发布说明：
通知开关默认开启且不影响应用内提示；流式更新不改变排序；
监督结果可直接编辑问题并继续讨论，界面不再提供知识实体写回控件。
Agent 产品源码及 Runtime 锁未因这四项改变，Agent
[CI 36340682607](https://github.com/mesalogo/goodbuddy/actions/runs/36340682607)
源码校验和三个原生构建全部通过。

补齐通知默认值的契约 fixture；Obsidian 多次真实子进程调用使用单用例 15 秒时限，
避免前项超时后的在途调用污染下一项取消断言；笔记来源用例按面板查询控件，
并等前次来源操作释放禁用状态后再发起下一次。
这些修正不改变产品实现。Windows 聚焦回归 19 项通过，类型、lint 和说明校验通过。
从 Git tree `1758ff58a6ff33fcf7ddaa3d35dd2fcc57cd1265` 导出完整快照，
覆盖 Host 测试源码，而非只同步早期快照中的少数文件。
该完整快照 `npm test` 为 **5,371 通过、51 跳过、0 失败**，
451 个文件通过、15 个跳过，耗时 751.42 秒，包含全部四个并行提交。
最终提交前再次核对源码、测试、依赖和发布资源与该已验证 tree 一致，
仅追加本段验证结果；完整候选仍需自己的主分支 CI 与生产构建通过。

### 完整候选后的焦点同步修正

`5cdffee` 的 Agent [CI 36343184917](https://github.com/mesalogo/goodbuddy/actions/runs/36343184917)
三个原生构建和源码校验通过；桌面
[CI 36343184916](https://github.com/mesalogo/goodbuddy/actions/runs/36343184916)
为 5,369 通过、51 跳过、2 失败，生产构建未执行。
会话采集的焦点等待可被 `body` 后代文字误满足，菜单随后被真正的消息聚焦关闭；
另一个原生 Runtime 控件用例在启动完成前打开失焦关闭的菜单。
本轮收紧消息焦点的元素断言，并等待项目能力请求及启动渲染后再打开 Runtime 选项。
不重试菜单、不跳过场景、不改产品实现。

完整冻结 tree `2ddc0da69b6bcb42d8272c44dd11e3e6904d0438` 在 Host 全量
**5,371 通过、51 跳过、0 失败**，耗时 748.21 秒。
Windows 原生 Runtime 聚焦用例、类型检查和 lint 通过。
提交仅追加本段记录；仍须等待修正候选的主分支 CI 和生产构建。

## 数据、兼容与验收边界

Desktop schema 48 新增魔法笔记会话来源元数据。升级前应备份完整用户数据，
包括数据库及相邻 `notes/` 目录；旧客户端不能打开升级后的数据库。
本次发布准备不修改数据库迁移实现，也不直接改写用户数据库。

Agent 发布工作流以候选 `package.json` 设置最低 Desktop 版本，因此
Agent 0.15.0 包要求 Desktop 0.15.0；Node、OpenCode、Continue 锁不变。
Agent 与 Desktop 独立发布，Agent 不替代 Desktop Latest。

原生客户端的远程 coordinator、托管标准 Node 交付整合、Continue/OpenCode
Ask 内置 MCP 映射及完整跨平台安装包验收仍有缺口，见
[原生客户端进度](../features/assistant-workbar/progress.md#2026-09-27-local-native-client-validation)。
本次说明明确标为本地预览，不将这些未完成部分宣称为已提供能力。