[xiaoyumuxi]

关联 Issue / Linked issue

• Refs [Feature] Windows/macOS 统一 Viva 工作台与原生编辑器，保留 Rust Core 和插件体系（分阶段重构） #1794

PR 类型 / Type

• feat：新功能或用户可见的改进
• fix：缺陷修复
• docs：文档、Agent Note、Skill 等规则文件
• release：稳定版发布准备

改动说明 / What changes

背景 / Why

在 Windows 和 Linux 上，Viva 客户端用的是自定义标题栏：最小化、最大化/还原、关闭这三个按钮由 Viva 画、由 Viva 判定点击。

应用不提供样式时，Viva 根据窗口的清屏色（Config.ClearColor）亮度来选字形颜色。Lithe 没有设置清屏色，而 Viva 的默认清屏色是深色，于是字形是白色。在浅色外观下，白色按钮落在浅色标题栏上，看不见。

修法是在应用这一层配置 Viva 已经提供的 app.Config.WindowControls，按每个窗口标题栏实际的文字色来画按钮。Viva 的回退逻辑不需要改：它不知道应用把标题栏画成什么颜色，这个颜色只有应用知道。

改动 / Changes

• 新增 desktop/internal/windowcontrols
  • Style(ink, text) 返回 app.WindowControlsStyle：
    • 字形颜色就是标题栏文字色；
    • 悬停、按下的底色是同一颜色加 10% 和 18% 的透明度，和 Viva 自己的比例一致；
    • 关闭按钮不设颜色，保留 Viva 的红色；
    • 按钮名称（无障碍名称）取自共享 i18n。
  • 窗口还没画第一帧、没有文字色时返回零值样式，交给 Viva 的默认值。
• 三个使用自定义标题栏的窗口都接上这个样式。Viva 每帧都调用 WindowControls，所以按钮会跟着外观和语言切换。
  • workbench/app.go：工作台，颜色取 a.colors.Text。
  • settingswindow/window.go：设置窗口，颜色取 w.pal.text。
  • logwindow/window.go：日志窗口，颜色取 w.pal.tx。
• i18n
  • shared/i18n/messages.json：window.minimize、window.maximize、window.restore、window.close 这四条已有词条加入 desktop 平台。已运行 generate-i18n.mjs，并提交了生成的 shared.generated.go。
  • desktop/internal/i18n：Messages 新增 Window WindowMessages（Minimize/Maximize/Restore/Close），由 windowMessages(language) 从共享词条读取，中英文目录都已接入。
• 测试
  • windowcontrols/style_test.go 有三个用例：字形、悬停和按下的颜色取自标题栏文字色，且不改关闭按钮；中英文的按钮名称；没有文字色和目录时返回零值样式。
  • 三个窗口各新增一个 TestWindowControlsFollowTheTitleBar，检查配置里有 WindowControls，并且返回的字形颜色等于当前外观的标题栏文字色、名称跟随当前语言。设置窗口和日志窗口在测试中途切换外观并重绘；工作台从深色/中文切到浅色/英文。
  • workbench/app_test.go 的 harness 新增 config 字段，保存交给 driver 的那份配置。测试读取同一份回调，不再第二次调用 Config()（它会重新赋值 a.fields）。
• 功能矩阵：window-controls 的 Windows 侧由“尚未盘点”改为 partial / pending，证据换成当前的 Viva 代码。说明里写明：命令面板的窗口操作尚未接入，原生窗口中的按钮行为还没在 Windows 和 Linux 上验证。macOS 不变。

不在本 PR 范围内 / Out of scope

• 日志窗口“级别”列和工具栏把 INFO 显示成 INFC：这是 Viva 在 Windows 上的问题。等宽的 semibold 文字交给 GDI 画，GDI 为 Consolas 合成出来的 600 字重比格子宽。已向上游提交 windows: leave medium and semibold fixed-pitch runs to Direct2D vivaui/viva#188，Lithe 这边不加绕过代码；上游合入后要单独升级 Viva 依赖。
• 按钮功能：不在本次范围。用户报告的“最小化/最大化功能异常”还没有在原生窗口里复现，原因未定，本 PR 只修复了按钮看不见的问题。按代码看，按钮的点击区域在最高层（math.MaxUint16），标题栏右侧已按 app.TitlebarInsets() 让出位置。具体的异常现象需要在 Windows 和 Linux 桌面上实测后再定位。
• 命令面板的窗口操作：最小化、最大化、全屏在 Viva 客户端里还没有接入，已记在功能矩阵里。

---

类型专属：fix

复现与根因

• 复现步骤：在 Windows 或 Linux 上启动 Viva 客户端，使用浅色外观。
  • 实际结果：工作台、设置窗口、日志窗口标题栏右上角的最小化、最大化/还原按钮看不见（白色字形落在浅色底上）。关闭按钮只有悬停时的红底能看见。
  • 期望结果：按钮字形使用标题栏文字色，深色和浅色外观下都能看清；按钮的无障碍名称跟随界面语言。
• 根因：引入自定义标题栏的提交都没有配置 WindowControls，Viva 只能按默认的深色清屏色推出白色字形：
  • 5214dbf：工作台外壳与日志窗口；
  • 29bce82：独立设置窗口。
• 影响平台：Windows、Linux（两者都由 Viva 绘制窗口按钮）。macOS 使用系统红绿灯按钮，不受影响。

检查项

• 已先写回归测试，确认它在修复前失败、修复后通过。测试路径：

  • desktop/internal/logwindow/window_test.go
  • desktop/internal/settingswindow/general_view_test.go
  • desktop/internal/workbench/app_test.go（三处都是 TestWindowControlsFollowTheTitleBar）

  把三个窗口文件换回 base 版本后，修复前的失败输出是：

  window_test.go:54: the log window leaves its window buttons to Viva's default ink
  general_view_test.go:273: the settings window leaves its window buttons to Viva's default ink
  app_test.go:816: the workbench leaves its window buttons to Viva's default ink
  

• [N/A] 无法自动化时的手动步骤：已有自动化测试。原生窗口中的目视检查见“未能执行的检查”。

• 已搜索全部使用方：WindowCustomTitlebar 只有工作台、设置窗口、日志窗口三处使用，已全部接上；i18n.Messages 新字段已加入中英文目录，TestCatalogsAreComplete 通过。

• 已检查另一平台：macOS 由系统绘制红绿灯按钮，不受影响；Linux 和 Windows 走同一条 Viva 绘制路径，本 PR 一并修复。

• 只改了修复所需的代码。顺带发现的 Viva 字形问题已在上游提交 windows: leave medium and semibold fixed-pitch runs to Direct2D vivaui/viva#188。

• [N/A] 行为约束 Note：修复只是配置 Viva 已有的接口，没有新增行为约束；三个窗口的回归测试防止复发。

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

• 已更新 shared/platform-feature-matrix/features/window-controls.json：Windows 侧为 partial / pending，证据换成当前 Viva 代码；macOS 未改动。
• 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh（validated 252 platform capabilities）和 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/feature/1794-viva-workbench-shell HEAD（passed）。
• 没有提交 .artifacts/ 下生成的矩阵视图。
• [N/A] 没有更新矩阵的理由：已更新。

统一日志系统 / Structured logging

N/A：没有新增或改动生命周期、终态、降级或失败路径，也没有日志调用。

界面文案 / i18n

• 按钮名称走共享 i18n：复用已有的 window.* 词条，加入 desktop 平台后运行了 node scripts/i18n/generate-i18n.mjs，并提交了生成结果，没有手改生成文件。
• 已运行 node scripts/i18n/verify-app-language-localization.mjs（passed）和 node scripts/i18n/generate-i18n.mjs --check（exit 0，en-US 和 zh-CN 均为 10524/10524）。没有放宽脚本，也没有扩大豁免名单。

逻辑归属 / Logic placement

• [N/A] 可共享逻辑进 Core：本 PR 只决定按钮的呈现颜色和名称，属于 Viva 界面层，没有解析、校验或状态规则。
• [N/A] 迁入 Core：没有修改平台层已有的可共享逻辑。
• 宿主和 Core 没有按工具名加分支。

性能与内存 / Performance and memory

• Viva 每帧调用一次 WindowControls，它只组装一个值类型结构体：没有分配、I/O 或轮询。没有新增后台功能、子进程、缓存、定时器或依赖。
• 主线程上没有新增文件读写、目录遍历或进程启动。
• [N/A] 性能基线：不涉及启动、打开项目、输入、滚动、大文件、长输出或搜索。

设置 / Settings

N/A：没有新增或修改设置项、设置页或对话框选项。

插件与共享契约 / Plugin and shared contracts

N/A：没有改动 shared/contracts/、插件能力或宿主方法。

发行包与资源 / Bundle and resources

N/A：没有新增或修改运行时资源、缓存或下载物。已顺带运行 ./scripts/macos/verify/verify-runtime-bundle-immutability.sh，结果通过。

无用代码与重构 / Dead code and refactoring

• 本次改动没有让任何代码变成无用代码。
• [N/A] 既有债务：本次没有发现需要建单的无用代码或可重构之处。

---

验证 / Verification

命令或操作	平台	结果
./scripts/desktop/desktop-go.sh test ./... -count=1	macOS	通过：33 个包全部 ok
./scripts/desktop/desktop-go.sh test -race ./internal/windowcontrols/ ./internal/logwindow/ ./internal/settingswindow/ ./internal/workbench/ -count=1	macOS	通过
三个窗口换回 base 版本后运行 -run TestWindowControlsFollowTheTitleBar	macOS	三个包都按预期失败（输出见上），恢复后通过
node scripts/i18n/verify-app-language-localization.mjs	macOS	通过
node scripts/i18n/generate-i18n.mjs --check	macOS	通过
node --test --test-timeout=60000 scripts/i18n/test-i18n.mjs	macOS	40/40 通过
./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh	macOS	通过
./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/feature/1794-viva-workbench-shell HEAD	macOS	通过
./.agents/skills/write-stable-tests/scripts/verify-test-stability.sh	macOS	通过
./scripts/macos/verify/verify-runtime-bundle-immutability.sh	macOS	通过
gofmt -l（改动的包）	macOS	无输出

未能执行的检查和原因：

• Windows 和 Linux 原生窗口的目视检查：没有执行，所以也没有截图或录屏。待检查的是浅色/深色、中/英文下按钮能否看清，以及最小化、最大化/还原、关闭是否正常。

  • macOS 上 Viva 不绘制这些按钮（controlsDrawnByViva 为 false），无头 driver 也就画不出来。
  • Windows 机器只能通过 SSH 访问，这个会话没有交互式桌面。
  • 没有 Linux 桌面环境。

  因此，功能矩阵的验证状态保持 pending。

• Windows 和 Linux 上的 go test：没有执行。改动没有平台专属的 Go 文件，覆盖范围与 macOS 上的测试相同。

提交前确认 / Final checks

• [N/A] 分支从最新的 preview 创建：这是 [Feature] Windows/macOS 统一 Viva 工作台与原生编辑器，保留 Rust Core 和插件体系（分阶段重构） #1794 Viva 客户端迁移的后续修复，从 feature/1794-viva-workbench-shell 创建，目标分支也是它。
• 以 Draft 提交，本地验证通过后才标记 ready。
• 没有无关改动，没有提交产物、凭据、个人路径或未脱敏的日志。
• 本次没有启动 Lithe 应用（只跑了无头测试），没有进程残留。

[xiaoyumuxi]

改动已直接推入 #1799（e82b29c59），不再单独开 PR，关闭。