[xiaoyumuxi]

关联 Issue / Linked issue

• Refs [Feature] Windows/macOS 统一 Viva 工作台与原生编辑器，保留 Rust Core 和插件体系（分阶段重构） #1794（Viva 统一工作台：Markdown 预览目录。feat(desktop): Markdown 目录改为 web view 页内的浮动大纲 #1912 合入后的跟进修复）

PR 类型 / Type

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

改动说明 / What changes

背景 / Why

#1912 把 Markdown 预览的目录画进了 web view 页面，但目录是浮在正文上方的面板，存在两个问题：

1. 宽预览中，目录挡住正文右侧。旧 macOS 预览在目录打开时会让正文让出宽度，不会挡字。
2. 设置了工作台背景图时，页面底色是透明的，目录面板也跟着透明。下面的正文透过面板显示，和目录标题、条目叠在一起，看不清。

改动 / Changes

• 宽预览让出正文位置（assets/markdown.css、assets/markdown.js）
  • 预览宽于 680 像素时，打开目录给 body 加 outline-open，正文右侧让出目录栏的宽度（280 + 2×12 像素）。阈值与旧 macOS 预览相同。
  • 目录栏贴右侧、上下占满高度，底色与页面相同。有背景图时目录栏也透出背景图，和正文一致。
  • 打开或关闭目录时正文重新换行，页面保持顶部那一行源码不动，不会跳。
  • 目录树改为在栏内伸展（flex: 1 1 auto），长目录在栏内独立滚动。
• 窄预览浮层底色不透明（assets/markdown.css）
  • 预览窄于 680 像素（常见于分栏）时，目录仍浮在正文上方并带阴影。
  • 底色改用 --lithe-popup-background（新的 --popup 变量），不再用页面底色。
• 宿主弹层颜色改为 Ground（workbench/pluginpages.go）
  • --lithe-popup-background 从 colors.Editor 改为 colors.Ground。
  • 有背景图时 applyLook 会把 Panel、Editor 设为透明，Ground 始终不透明。
  • 没有背景图时浅色、深色主题的 Editor 和 Ground 是同一个颜色，外观不变。
  • 插件页的弹层也读这个变量，背景图下同样不再透字。
• 回归测试：新增 TestPagePopupColorStaysOpaqueOverTheBackground（workbench_background_test.go），断言背景图下页面表面透明、弹层颜色等于不透明的 Ground。
• 功能矩阵 markdown-preview-outline：更新能力描述、证据、验收步骤和说明。新增的验收步骤是宽页正文避让、窄页不透明浮层和背景图下不叠字。
• Agent Note 2026-11-14-web-view-previews.md：新增“目录不遮挡正文”决策，并把“目录始终浮在正文上方”记为被否方案。验证列表补上新测试，适用范围补上 pluginpages.go。

不在本 PR 范围内 / Out of scope

无。

---

类型专属：fix

复现与根因

• 复现步骤、实际结果、期望结果：
  1. 在 Viva 桌面端打开含多级标题的 Markdown，切到预览，点标签栏的“目录”。
     • 实际：宽预览中目录面板挡住正文右侧。
     • 期望：正文让出位置，与旧 macOS 预览一致。
  2. 在设置里选择工作台背景图，重复上一步。
     • 实际：目录面板透明，正文和目录文字叠在一起。
     • 期望：宽预览不遮挡；窄预览浮层底色不透明。
• 根因：
  • feat(desktop): Markdown 目录改为 web view 页内的浮动大纲 #1912（b582e206a）的 .outline 用 position: fixed 浮在页面上，正文没有避让。它的底色是 var(--page)，也就是 --lithe-surface。
  • pluginPageTheme() 把 --lithe-surface 和 --lithe-popup-background 都映射为 colors.Editor。该映射由 Epic(0.7.0): 基于 Viva 框架的跨平台方案的迁移（#1794） #1799（0faecba49）引入，有背景图时 Editor 是透明的，所以面板也透明。
• 影响平台：macOS、Windows（两端都用同一份 web 页面和宿主主题变量）。Linux 走原生弹出列表，不受影响。

检查项

• 已先写回归测试，确认它在修复前失败、修复后通过。测试路径为 desktop/internal/workbench/workbench_background_test.go。把映射改回 Editor 时的失败输出：popup color over the background = "rgba(0, 0, 0, 0)", want the opaque ground "rgba(25, 26, 28, 1)"。
• 无法自动化时，已写明手动复现与验证步骤。页面布局部分已用无头 Chrome 驱动 markdown.js 和 markdown.css 自动断言，见“验证”；整机步骤写在功能矩阵的 verification 里。
• 已搜索被修改函数、类型、契约字段的全部调用方。pluginPageTheme() 只被插件页（pluginpages.go）和预览页（preview_pages.go）调用。--lithe-popup-background 在本仓库只有 Markdown 页面使用，插件页从同一个变量取值。
• 已检查另一平台是否有同类缺陷。Windows 与 macOS 共用页面和主题变量，本 PR 一并修复。
• 只改了修复所需的代码，没有夹带重构；修复过程中没有发现其他问题。
• [N/A] 修复改变了行为约束或容易复发，已在 .agents/notes/implemented/bug-fix/ 记录：约束已写进现有的 web 预览架构 Note（“目录不遮挡正文”决策与被否方案），没有另建 bug-fix Note。

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

• 已更新 shared/platform-feature-matrix/features/markdown-preview-outline.json。两端证据补上 pluginpages.go 与 workbench_background_test.go，验证状态保持不变（整机验收未做）。
• 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh 和 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD
• 没有提交 .artifacts/ 下生成的矩阵视图
• [N/A] 没有更新矩阵的理由：已更新

插件归属 / Plugin ownership

• 已在仓库根目录运行 develop-lithe 第三节“插件归属与宿主零依赖”的自查命令，结果为空
• 新增的测试只用宿主自身的背景图和主题，不涉及任何插件
• 没有为具体插件提供的能力新建或更新宿主功能矩阵条目
• 没有插件文案或插件构建内容
• [N/A] 修改了通用扩展点、可能影响已发布插件的，已在受影响插件的仓库运行它的测试：插件页主题变量 --lithe-popup-background 只在有背景图时由透明改为不透明，没有背景图时取值不变，不改变插件接口

统一日志系统 / Structured logging

N/A：没有新增或改动生命周期里程碑、终态、降级或失败路径。

界面文案 / i18n

• [N/A] 宿主文案都走共享 i18n：没有新增界面文案
• [N/A] 插件提供的文字由插件自己翻译：不涉及插件
• 已运行 node scripts/i18n/verify-app-language-localization.mjs 和 node scripts/i18n/generate-i18n.mjs --check，没有放宽脚本或扩大豁免名单

逻辑归属 / Logic placement

• [N/A] 可共享的逻辑在 Rust Core：改动只是目录栏的布局和颜色，属于视图呈现，不是可共享的业务逻辑
• [N/A] 修改平台层已有的可共享逻辑时已迁入 Core：没有修改可共享逻辑
• 宿主和 Core 没有按工具名加分支

性能与内存 / Performance and memory

• 没有新增后台功能、定时器或缓存。打开或关闭目录时只切换一个 class，并重算一次滚动映射，复用页面已有的 ResizeObserver 路径。
• 主线程没有新增文件读写；宿主到页面只多了一个颜色值的变化
• [N/A] 性能基线：没有改动启动、输入、滚动、大文件或搜索路径，也不涉及 Viva 编辑器模块

设置 / Settings

N/A：没有新增或修改设置项。

插件契约 / Plugin contract

N/A：不涉及 Rust Core 插件契约、能力版本或宿主方法；--lithe-* 主题变量名不变。

发行包与资源 / Bundle and resources

• 运行时不向 app bundle 或安装目录写入，页面资源仍从二进制读取；已运行 ./scripts/desktop/verify/verify-runtime-bundle-immutability.sh
• [N/A] 资源复用清单：没有新增下载、解压、生成或缓存资源

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

• 本次改动没有留下无用代码，浮动面板原来的定位和阴影规则已改写为宽、窄两套规则
• [N/A] 本次之前就存在的无用代码或可重构之处：未发现

---

验证 / Verification

命令或操作	平台	结果
scripts/desktop/desktop-go.sh test ./internal/workbench ./internal/webpreview -count=1（基于最新 preview）	macOS	通过（workbench 147.7s，webpreview 0.9s）
TestPagePopupColorStaysOpaqueOverTheBackground：把映射临时改回 colors.Editor 再运行	macOS	修复前失败，修复后通过（输出见上）
无头 Chrome 驱动 markdown.js、markdown.css，1100 像素宽页	macOS（Chrome）	37/37 通过，包含新增的 6 项：打开目录后正文右缘不越过目录栏左缘、目录栏占满高度、关闭时正文变宽、打开时正文变窄，以及关闭和打开时顶部标题都保持在原位
无头 Chrome，600 像素宽页，模拟背景图（--lithe-surface 透明、--lithe-popup-background 不透明）	macOS（Chrome）	5/5 通过：正文宽度不变、目录浮在正文上方、浮层底色 alpha 为 255、页面本身仍透明
截图检查：浅色宽页、深色宽页、背景图宽页、背景图窄页	macOS（Chrome）	宽页目录栏贴右、正文不被遮挡；窄页浮层不透字
gofmt -l desktop/internal/workbench desktop/internal/webpreview	macOS	无输出
node scripts/i18n/verify-app-language-localization.mjs、node scripts/i18n/generate-i18n.mjs --check	macOS	通过
./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh	macOS	通过（189 项）
./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD	macOS	通过
./scripts/agent-notes/verify-agent-notes.sh	macOS	通过（224 个 Note）
./scripts/desktop/verify/verify-runtime-bundle-immutability.sh	macOS	通过

未能执行的检查和原因：

• 没有在 macOS 原生 Lithe（WKWebView）里做整机验收：页面行为在无头 Chrome 中验证，WKWebView 的 color-mix 与固定定位行为待整机确认。
• Windows（WebView2）没有真机验证，当前机器没有 Windows 环境。

提交前确认 / Final checks

• 分支从最新的 preview 创建，目标分支为 preview
• 以 Draft 提交，本地验证通过后才标记 ready
• 没有无关改动，没有提交产物、凭据、个人路径或未脱敏的日志、截图
• 本次没有启动 Lithe 应用；无头 Chrome 由驱动脚本在结束时关闭并删除临时配置目录，已确认没有残留进程