fix(dsh): 插件页改回透明底，用文字光晕与色阶提升保住可读性

docs/adr/0002-dsh-functional-surface-readability.md

@@ -51,6 +51,16 @@ Web 与官方 Desktop 的插件页共用 `readability.js`。以 `data-plugin-pan
 
 `plugin-readability.browser.test.mjs` 用真实语义结构和主题色板覆盖深浅主题、会话阶段、画窗、阴影／磨砂，验证局部不透明、文字对比度、异步状态、关闭／清除恢复、负边距、hover、键盘焦点及控制区域。`plugin-readability-pack.test.mjs` 验证 Web 与 native Desktop 鉴权路径均提供当前共享脚本，并比较独立包和桌面聚合包的 DSH runtime。浏览器 fixture 不替代真实 Web 和官方 Desktop 候选包验收；结果与截图见 [#92 验收记录](../verification/issue-92-plugin-readability.md)。
 
+### 补充：插件页改回透明底（#92 复审，2026-10-18）
+
+独立插件页的实色底板解决了 #92 的对比度问题，但代价是整页被涂成实心色块：用户实测该底板占插件页 73.4% 像素、5×5 局部标准差 0.00，而「自动化任务」等同级页面在同区域标准差为 0.22–1.32（透出壁纸），观感割裂，用户明确要求回到透明底。
+
+因此改为：插件页不再进入不透明名单，继续使用 `client.js` 发布的半透明表面令牌（`--bc-surface-mix`、`--dsw-alias-bg-base:rgba(17,20,27,.10)` 等），壁纸直接透出。可读性改由两项不遮挡背景的辅助承担：页内说明文字与计数提升到次要文字色；页面文字加一层随主题取色的柔和光晕（`--bc-text-halo`，深色 `#000`、浅色 `#fff`，`0 1px 2px`、45% 透明度）。两项辅助同样受「功能面板不透明」开关与 `data-bc-active` 约束。角色面板（dialog／menu／tooltip／composer、提问／计划审核／授权确认）的保护不变，`--bc-readable-fill` 及其局部令牌仍只服务这些面板。
+
+取舍必须写明并**明确接受**：透明底不再具备「任意壁纸上都 ≥4.5:1」的保证，这是几何上的必然——纯白壁纸上的浅色文字无法靠文字色或光晕达标。约束是**分主题**的、且互为镜像：深色主题（浅色文字）要求局部背景保持偏暗（L ≲ 0.10；实测 #555555 L≈0.091 时标题 7.13:1、正文 4.95:1）；浅色主题（深色文字）要求局部背景保持偏亮（L ≳ 0.81；实测 #e8e8e8 L≈0.807 时标题 15.42:1、正文 4.73:1）。越界极值——深色主题遇纯白壁纸 1.05:1、浅色主题遇纯黑壁纸 1.11:1——由回归测试显式断言**失败**，把取舍钉在测试里而不是让门槛空过。参考页（自动化任务）实机为标题 5.31–5.61、次级文字 4.31–4.39；正文达标依赖上述色阶提升（不提升时深色 3.49:1、浅色 3.02:1）。若日后需要「任意壁纸都达标」的强保证，只能回到局部底板或引入用户可选的底板强度，光晕无法替代。
+
+验证：`plugin-readability.browser.test.mjs` 改为断言透明（alpha 0）、光晕随主题取色并被文字继承、说明／计数提升一档、白黑壁纸下页面截图必须不同（壁纸确实透出）、hover 仍是宿主半透明反馈；`readability.test.mjs` 增加源码级守卫，禁止不透明名单重新出现 `[data-plugin-panel]`。数值证据见 [#92 验收记录](../verification/issue-92-plugin-readability.md)。
+
 ## 回滚
 
 用户关闭开关即可回到原有透明效果。版本回滚可移除脚本的拼接、打包项与控制台入口；独立偏好不会影响旧版背景客户端。不会改写 DSH 安装文件或原有背景状态。

docs/verification/issue-92-plugin-readability.md

@@ -59,3 +59,34 @@ Web 在两种主题下验证标题、官方组和已安装组底色分别为 `rg
 提交 PR 前核对发现，当前 `origin/main`（7b23b3a）仍包含 #87 的两处误隐藏渐隐滚动内容规则及错误测试断言，尽管历史 PR #89 显示已合并。为避免后续从主分支打包回退已发布修复，本次恢复 PR #89 的最小变更：删除两处隐藏规则、移除要求隐藏行为的断言，并恢复普通背景／画窗模式连续 90 帧高度、滚动位置和 mask 稳定性回归。新增回归在修复前失败，直接复现普通背景高度被隐藏的问题；不修改已发布 tarball 或其他宿主模块。
 
 PR CI 暴露新增聚合打包回归依赖提前构建其他宿主的产物，而 CI 在全量构建前运行测试。该测试已改为调用聚合打包接口默认的构建流程；临时移出 Cursor 的构建目录后，旧测试以同一 `ENOENT` 失败，修改后能自行重建并通过。没有调整 CI 顺序或产品构建协议。
+
+## 修订：插件页改为透明底（2026-10-18）
+
+#93 的实色底板在真实使用中被判定为观感割裂（该底板占插件页 73.4% 像素、5×5 局部标准差 0.00，同级「自动化任务」页同区域为 0.22–1.32）。本次修订按用户要求改回透明底：`readability.js` 不再把 `[data-plugin-panel] …` 列入不透明名单，改用两项不遮挡背景的辅助（说明／计数提升一档、页面文字光晕），取舍与边界见 ADR 0002 的同日补充。
+
+| 项目 | 结果 |
+| --- | --- |
+| 浏览器回归（真实 Edge，零依赖 CDP 等价复刻仓库内用例） | **7 组 / 131 条断言全绿**：透明（alpha 0）、对比度基准、壁纸透出（白黑壁纸逐像素）、异步状态、亮／暗／复杂／播放中视频、关闭与清除恢复、几何／hover／焦点／控制区域 |
+| 对比度 | 分主题、分背景区间验收，见下节；深色主题在 L≈0.091 背景上标题 7.13:1 / 正文 4.95:1，浅色主题在 L≈0.807 背景上标题 15.42:1 / 正文 4.73:1 |
+| 对照：不提升色阶 | 正文仅 3.04–3.13:1 → 色阶提升是正文达标的前提 |
+| 参考页实机基准（自动化任务） | 标题 5.31–5.61:1、次级文字 4.31–4.39:1 |
+| 单元测试 `test/readability.test.mjs` | 通过；新增源码级守卫（不透明名单不得再含 `[data-plugin-panel]`、光晕与色阶规则必须存在） |
+| 几何／滚动／hover／焦点／拖动属性 | 与修订前逐项一致（回归断言原样保留） |
+| 未跑 | 本机无仓库依赖与 Playwright，未跑 `npm test` / `npm run typecheck` / `npm run build` 与 Playwright 本体；由 CI 与维护者环境复核。真实照片壁纸的现场观感由提出方在其 DSH 上确认 |
+
+### 两种主题各自适用的背景条件（维护者复核意见补充）
+
+透明底把对比度交给了壁纸，因此约束是**分主题**的，且两种主题互为镜像：
+
+| 主题 | 文字色 | 适用背景 | 测试用背景（实测） | 标题 / 正文对比度 | 越界示例（测试断言必然低于门槛） |
+| --- | --- | --- | --- | --- | --- |
+| 深色 | `#f9fafb` / `#cfd3d6` | 局部背景保持偏暗（L ≲ 0.10） | `#555555`（L≈0.091，与 #92 报告实测背景 L≈0.097 同级） | 7.13:1 / 4.95:1 | 纯白壁纸：1.05:1 |
+| 浅色 | `#0f1115` / `#61666b` | 局部背景保持偏亮（L ≳ 0.81） | `#e8e8e8`（L≈0.807） | 15.42:1 / 4.73:1 | 纯黑壁纸：1.11:1 |
+
+两侧越界由 `plugin-readability.browser.test.mjs` 的 `OUT_OF_RANGE_CASES` **显式断言失败**，避免门槛被空过；不提升色阶时两种主题都不达标（深色 3.49:1、浅色 3.02:1），因此 tertiary / caption → secondary 的映射是正文达标的前提。
+
+**明确接受该取舍**：本方案选择「透明优先」——在上述区间之外（深色主题遇明亮壁纸、浅色主题遇暗壁纸），说明文字会低于 4.5:1。这是已知且接受的代价，另一种可能（回到不透明底板，或引入用户可选的底板强度）会牺牲页面与「自动化任务」等页面一致的透明观感。
+
+真实 DSH 中的明亮／复杂壁纸复查见下方「真实应用」小节补充。
+
+复跑方式不变：设置 `BEAUTICODE_PLAYWRIGHT_MODULE` 与 `BEAUTICODE_BROWSER_CHANNEL=msedge` 后 `npm run test -w @beauticode/adapter-dsh`；未配置浏览器环境时浏览器用例显式跳过，不代表完成视觉验收。

integrations/deepseek-harness/README.zh-CN.md

@@ -18,7 +18,7 @@ dsh plugin --profile desktop add beauticode-dsh
 
 ## Web
 
-「设置 → 背景」默认开启「功能面板不透明」，保证设置、弹层、菜单、消息编辑栏与提问窗口（提问、计划审核、授权确认）遮住后方内容。Web 与官方 Desktop 的插件页也使用此开关：标题区、各分组、详情、配置和加载／空／错误状态分别使用局部实色底板，分组间隙和外围继续显示壁纸；说明文字及计数提升到宿主次要文字色。图片、视频、背景阴影、磨砂和画窗模式不会削弱底板。关闭后恢复原有透明效果；选择会保存在当前应用的本地偏好中，清除背景后恢复宿主样式。需要回滚时关闭开关或恢复旧插件版本即可。
+「设置 → 背景」默认开启「功能面板不透明」，保证设置、弹层、菜单、消息编辑栏与提问窗口（提问、计划审核、授权确认）遮住后方内容。Web 与官方 Desktop 的插件页是页面而不是面板，因此与「自动化任务」等页面一样保持透明：标题区、各分组、卡片、详情、配置和加载／空／错误状态都不铺底板，壁纸直接透出。为在小字密集处保住可读性，页内说明文字与计数提升到宿主次要文字色，并给页面文字加一层随主题取色的柔和光晕（深色主题黑色、浅色主题白色）；这两项辅助同样受此开关控制。图片、视频、背景阴影、磨砂和画窗模式都不会让插件页重新变成实色。需要知道的取舍：页面透明后文字对比度取决于壁纸亮度——深色主题适合偏暗的背景、浅色主题适合偏亮的背景；若壁纸很亮（深色主题）或很暗（浅色主题），说明文字会不容易看清，此时可切换主题或调低背景亮度。关闭后，面板回到半透明，插件页也不再应用上述两项辅助；选择会保存在当前应用的本地偏好中，清除背景后恢复宿主样式。需要回滚时关闭开关或恢复旧插件版本即可。
 
 装好插件并运行 `dsh web` 后，打开「设置」，左侧导航里会多出一项「背景」：在 Windows 上点击图片或视频会打开系统文件选择器，选好后在页面内命名，背景立即应用并进入已保存主题；也可以清除、开关声音、切换或删除主题，进入全屏把浏览器的标签页和地址栏收起来，以及打开「皮肤中心」安装 `https://hnnulwh.cn` 上已审核的社区皮肤。本地导入只在 Node 端保存绝对路径，并通过带 Range 支持的回环媒体服务读取原文件，不复制用户选择的图片或整段视频主文件。Windows 强制使用本地引用；原生选择器不可用时会明确报错，不会静默上传或复制媒体。非 Windows 环境保留兼容上传，并明确提示该模式会保存托管副本。网页控制台没有摸鱼；浅色/深色跟 DSH 自己的外观走。下次打开会恢复上次背景。皮肤中心来源固定，不使用 `BEAUTICODE_SKIN_CENTER` 或 `skin-center.json` 改写生产目录。
 

integrations/deepseek-harness/readability.js

@@ -25,9 +25,11 @@
   style.textContent = `
 html[data-bc-active="true"] body{
   --bc-readable-fill:var(--dsw-static-neutral-bluish-800,#232833);
+  --bc-text-halo:#000;
 }
 html[data-bc-active="true"][data-bc-resolved-tone="light"] body{
   --bc-readable-fill:var(--dsw-static-neutral-bluish-00,#fff);
+  --bc-text-halo:#fff;
 }
 /* DSH settings are body portals; its sticky composer sits over the transcript.
    Protect the actual surface, rather than keying readability to a conversation
@@ -45,21 +47,7 @@ html[data-bc-active="true"]:not([data-bc-readable-surfaces="false"]) :is(
      frame instead would produce a solid bar across its side padding. */
   [data-question-key] > section,
   [data-plan-review-key] > section,
-  [data-approval-key] > div,
-  /* The standalone plugin page has separate reading regions. Keep its frame
-     transparent so wallpaper remains visible between groups. Empty/offline
-     states are direct paragraphs; failures wrap an alert and retry control. */
-  [data-plugin-panel] > header,
-  [data-plugin-panel] [data-plugin-group],
-  [data-plugin-panel] [data-plugin-detail],
-  [data-plugin-panel] [data-plugin-item-detail],
-  [data-plugin-panel] [data-plugin-row-detail],
-  [data-plugin-panel] [data-plugin-config],
-  [data-plugin-panel] [data-plugin-loading],
-  [data-plugin-panel] > p,
-  [data-plugin-panel] > div:has(> [role="alert"]),
-  [data-plugin-panel] [data-plugin-package],
-  [data-plugin-panel] [data-plugin-item]
+  [data-approval-key] > div
 ){
   --dsw-alias-bg-base:var(--bc-readable-fill);
   --dsw-alias-bg-layer-1:var(--bc-readable-fill);
@@ -71,16 +59,19 @@ html[data-bc-active="true"]:not([data-bc-readable-surfaces="false"]) :is(
   --dsw-alias-tooltip-bg:var(--bc-readable-fill);
   background-color:var(--bc-readable-fill);
 }
-/* Keep host geometry and radii: groups have no padding, so adding a radius
-   would expose wallpaper behind the first letter of their heading. */
+/* The plugin page is a page, not a panel: DSH lays it out full-bleed like the
+   automation-tasks page, so it keeps the translucent surfaces client.js
+   publishes (--bc-surface-mix, --dsw-alias-bg-base:rgba(17,20,27,.10), ...) and
+   the wallpaper reads through. Painting it opaque turned every group and row
+   into a slab - and, because a host row carries margin:0 -8px with radius-xl,
+   the painted rows' 8px overhang showed up as rounded scallops of wallpaper.
+   Leave host geometry, radii and surfaces alone. Keep only the two legibility
+   aids: captions come up one tier, and a soft halo keeps 13px copy readable
+   over a busy photo without covering the picture. */
 html[data-bc-active="true"]:not([data-bc-readable-surfaces="false"]) [data-plugin-panel]{
   --dsw-alias-label-tertiary:var(--dsw-alias-label-secondary);
   --dsw-alias-label-caption:var(--dsw-alias-label-secondary);
-}
-/* Preserve the host's translucent hover feedback over an opaque base. Using
-   an image layer leaves the reading plate opaque even in gallery/video mode. */
-html[data-bc-active="true"]:not([data-bc-readable-surfaces="false"]) [data-plugin-panel] :is([data-plugin-package],[data-plugin-item]):hover{
-  background-image:linear-gradient(var(--dsw-alias-interactive-bg-hover),var(--dsw-alias-interactive-bg-hover));
+  text-shadow:0 1px 2px color-mix(in srgb, var(--bc-text-halo) 45%, transparent);
 }
 `;
   document.head.append(style);