[Bug] 批注高亮块显示优先级仍高于会话顶栏，选区高亮与编号遮挡顶栏内容（同 #50 / #44 的层级问题）

[Ztyss]

环境

• DSH Desktop 2.0.11（兼容模式窗口）/ 内核 0.1.5-rc.2 / Windows 11
• @changfenhuang/dsh-annotation 1.4.10（npm 最新；已核对 main 上的 1.4.11-preview.1 变更日志，无相关修复）

现象

选中助手回复里靠近会话顶部的文本后，黄色选区高亮块（.dsh-ann-hl）连同蓝色编号胶囊（.dsh-ann-num，如「1」）会绘制在会话顶栏之上，把顶栏那一栏（标题 / 面包屑 / 右上操作按钮，._0cyzDW_header，min-height:76px）压住。

实测截图（窗口标题栏下方）：一条约 230×14px 的黄色高亮横条 + 左端蓝色「1」胶囊，正好落在顶栏所占的横带里，顶栏内容被遮住。

复现

1. 在会话顶部附近（顶栏下方一屏内）选中助手文本 → 出现高亮矩形与编号；
2. 向上滚动，让被批注的原文滚到顶栏之下 —— 高亮矩形仍按视口坐标绘制，于是压在顶栏上；
3. 或：已有批注时切换会话 / 刷新重绘，高亮同样可能落在顶栏区域（标记层是常驻的 body 级图层，不受会话滚动容器裁剪）。

根因（读 1.4.10 出厂 bundle）

• 标记层挂在 document.body 上，是全局图层：overlay.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:900;'（[data-annotation-overlay]）；
• 高亮 .dsh-ann-hl { position: fixed; z-index: 900; ... }；编号 .dsh-ann-num { position: fixed; z-index: 940; ... }；
• renderMarkers() 只用 evenodd clipPath 挖掉了输入框：polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, <composer-card 四角>)，锚点是 [data-composer-card] —— 这是 [Bug] 批注高亮块显示优先级高于输入框，选区高亮遮挡输入内容 #50 的修法，顶栏没有对应的洞；
• 而会话顶栏是普通文档流元素：._0cyzDW_header { box-sizing:border-box; border-bottom:.5px solid var(--dsw-alias-border-l3); flex:none; min-height:76px; padding:10px 28px 0 20px } —— 无 position、无 z-index（z-index:auto），在根层叠上下文里必然被 body 级 fixed 图层（900 / 940）压住；
• 编号定位里还有一处会把胶囊推向顶部：var chipTop = anchor.top - 20; if (chipTop < 4) ...; if (chipTop < 4) chipTop = 4; —— 只有「视口上沿 4px」的保护，没有「顶栏高度」的保护，所以顶栏区域的编号尤其显眼。

建议修法

把 #50 的「挖洞」从「只挖输入框」扩成「挖输入框 + 挖顶栏」，或给标记层加一个顶部 inset：

1. clipPath 再加一个洞覆盖顶栏横带：(0,0) → (100%, headerBottom)。headerBottom 有现成稳定钩子：document.querySelector('[data-conversation-scroll]').getBoundingClientRect().top —— 顶栏（conversation.session.header 槽）渲染在会话根容器的首个子节点，[data-conversation-scroll] 紧随其后，两者边界严丝合缝，不需要新增宿主钩子；
2. 编号同样加 inset：把 chipTop 的下限从 4 改成 headerBottom + 4（保留 window.innerHeight 上限与冲突避让逻辑）；
3. 若希望按元素定位而不是按 scrollBody 推算，可向上游请求一个稳定钩子：目前宿主只给了 data-conversation-header-corner（顶栏内的角标槽），顶栏本体只有 CSS Modules 哈希类名 _0cyzDW_header，插件不宜依赖。

关联

• [Bug] 批注高亮块显示优先级高于输入框，选区高亮遮挡输入内容 #50 —— [Bug] 批注高亮块显示优先级高于输入框（同根因，1.4.9/1.4.10 已用 clipPath 挖洞修好，但只覆盖了输入框）
• [Bug] ①选中高亮块 z-index 过高，打开设置页仍覆盖其上 ②重启后批注胶囊脱离输入框锚点，跳到聊天区其它位置 #44 —— [Bug] ①选中高亮块 z-index 过高，打开设置页仍覆盖其上（同根因：body 级 fixed 图层高于应用内普通元素）
• [bug]annotation框挡住了缓存消息的提交键. #60 —— [bug] annotation 框挡住了缓存消息的提交键（同一族「标记/输入框图层盖住宿主 UI」问题，供一并收口参考）

本次是同一层级问题在会话顶栏上的残留：#44 修的是「高于设置页」，#50 修的是「高于输入框」，这次是「高于顶栏」——建议按「标记层必须被会话内容区裁剪」的思路一次性收口（例如把高亮层挂进会话滚动容器，而不是 document.body）。

[PerryLink]

补充一条定位时会卡住的信息：这个修复建议所依赖的宿主钩子，在插件里并不存在。

我把当前 client.js（1.4.11-preview.1）里所有 data-* 属性做了全量统计，插件实际依赖的宿主钩子只有这些：

data-time-hover-root, data-streaming, data-chat-flow-kind, data-composer-card, data-focus-anchor-key, data-focus-flow, data-chat-anchor-key, data-turn-tail, data-input-scroll, data-composer-input, data-document-markdown, data-code-preview, data-chat-flow, data-pending-steering

而建议里要用的两个选择器，出现次数都是 0：

选择器	在 client.js 中的出现次数
[data-conversation-scroll]	0
[data-conversation-header-corner]	0

也就是说：

1. headerBottom = document.querySelector('[data-conversation-scroll]').getBoundingClientRect().top 这条路径插件从来没走过，它在宿主真实 DOM 里是否存在、是否稳定，从插件侧无法验证。若该选择器不存在，querySelector 返回 null，取 .top 会直接抛错；若写成可选链兜底，就会静默退回现状——顶栏照样被压住，但看起来"修好了"。
2. [data-conversation-header-corner] 同理：插件里没有任何一处用它，因此它目前也不是一个插件已经在消费的契约。

现有的 composer 挖洞之所以可靠，是因为 [data-composer-card] 本来就是插件已经在用的宿主钩子（client.js:1416、:1039、:1158、:1212、:1242、:1647、:1754 都在用它）。顶栏缺的正是这样一个等价物。

所以建议在动手前先确认一件事：宿主能否为会话顶栏提供一个稳定的属性钩子（哪怕是给 _0cyzDW_header 那个根节点加一个 data-conversation-header）。有了它，你提的第 1、2 条修法都能直接落地，且不需要插件去推算 scrollBody；没有它，任何选择器都只是一个猜测——而这正好是本次要修的那类"看起来生效、实际没生效"的问题。

我本来准备直接按建议 1+2 提交补丁，卡在这里，所以先把测量结果放出来。

[PerryLink]

更正：我上一条评论的结论是错的，而且错在方法上。请不要按它去改方向。

[data-conversation-scroll] 确实存在，而且是宿主的稳定契约。 宿主在这里定义它：

packages/client/ui-conversation/src/client/skeleton/ConversationContent.tsx

<div className={css.scrollBody} data-conversation-scroll="">
  {sessionId === undefined ? null : <Views />}
  {composerSeat}
</div>

由 e62587c163（feat(client): open subagent chats in sidebar）引入，从 dsh-v0.1.0-rc.7 起一直存在，并且宿主自己就靠它工作 —— 底部跟随与前置锚定是通过 closest('[data-conversation-scroll]') 解析的；.agents/notes 下另有四份笔记引用它（2026-07-29-sticky-composer-conversation-scroll、2026-08-03-web-sticky-collapsible-headers、2026-08-04-composer-tab-gutter-reservation、2026-08-28-remove-hero-input-glow）。这不是一个待商量的新钩子，是一个已经用了两个月的既有契约。

我错在哪

我统计的是插件自己的打包产物 client.js 里这些字符串的出现次数，然后据此断言宿主 DOM 里没有这些属性。这两件事没有关系 —— 一个还没有消费某个宿主钩子的插件，它的 bundle 里当然不会出现那个钩子的名字。「插件没在用」不等于「宿主没有」，我把前者当成了后者的证据。

而这个错误的实际后果正好是本末倒置的：我用「你这个修法可能静默退回现状」请你先停下来，但那个风险是我自己的测量方式造出来的，不是你的方案带来的。

因此

• 你提的第 1、2 条修法可以直接落地，不需要宿主先加新钩子。
• [data-conversation-header-corner] 那条保留意见我也一并撤回 —— 同样只是「插件还没用过」，不代表宿主没有。
• 我按第 1 条做了一版补丁（给顶栏再挖一个洞，且限制在会话列内，避免误裁侧栏文档预览里的标注），本地测试通过。如果你已经在做，我就让给你；否则我把它作为 PR 发出来，你在这条 issue 里判断。

抱歉让你在这上面多花时间。

[Ztyss]

谢谢这份更正 —— 更要谢谢你把方法上的问题也一并写出来，这比结论本身有价值。

我这边在出厂产物里核了一遍（DSH Desktop 2.0.13 / 内核 0.1.5-rc.2，@deepseek-ai/dsh-client-ui-conversation/lib/client.js），把你的结论再钉实两层；另外有一处你撤回得过了：

1) [data-conversation-scroll] 确实是宿主契约，而且宿主自用

• :14955 渲染时写的就是 "data-conversation-scroll": ""；
• :15907 宿主自己 const host = el.closest("[data-conversation-scroll]") —— 宿主自用即契约，这条没有争议。

2) scrollBody.top 与顶栏下沿是结构上严丝合缝的，不是近似

同一处骨架：:14951 先把 renderSlot("conversation.session.header", {}) 作为 .root 的首个子节点，紧接着才是 .body > .scrollBody。CSS 也支持这个判断：

._0cyzDW_root       { flex-direction:column; position:relative }
._0cyzDW_header     { flex:none; min-height:76px; padding:10px 28px 0 20px }   /* 无 margin */
._0cyzDW_body       { flex:1; min-height:0; display:flex; flex-direction:column }
._0cyzDW_scrollBody { flex:1; overflow-y:auto; margin-right:2px }               /* 无上边距 */

中间没有 margin/padding 夹层，所以 headerBottom = document.querySelector('[data-conversation-scroll]').getBoundingClientRect().top 可以直接当顶栏下沿用。

3) [data-conversation-header-corner] 那条你也撤回，其实撤多了 —— 它真实存在

:15079-15083：一个 className: headerCorner 的 div，上面就写着 "data-conversation-header-corner": ""，内部渲染槽位 conversation.session.header.corner。所以宿主确实提供过这个 DOM 钩子。

不过你的判断仍然成立：它标的是顶栏内的角标容器，不是顶栏根节点。顶栏根节点（._0cyzDW_header，:15030）确实只有 CSS Modules 哈希类名；宿主对外给的是槽位名（conversation.session.header / .actions / .utilities / .corner / .lineage），不是 DOM 属性。所以「按 scrollBody 推算」依然比「按角落容器反推顶栏」更稳。

关于 PR

没有任何人在做，请直接发，欢迎。

几点希望：

1. 就按你的第 1 条（给顶栏再挖一个洞）+ 第 2 条（chipTop 下限改成 headerBottom + 4）落地即可。把挖洞范围限制在会话列内这个处理很对 —— 侧栏文档预览里的标注不该被顶栏的洞裁掉，这点建议在 PR 描述里点明，它是回归重点。
2. 不要在这个 PR 里顺手做「把标记层挂进会话滚动容器」的结构性收口：scrollBody 带 overflow-y:auto，挂进去会牵动滚动 / 裁剪 / 坐标语义，评审面太大。[Bug] ①选中高亮块 z-index 过高，打开设置页仍覆盖其上 ②重启后批注胶囊脱离输入框锚点，跳到聊天区其它位置 #44 / [Bug] 批注高亮块显示优先级高于输入框，选区高亮遮挡输入内容 #50 / [bug]annotation框挡住了缓存消息的提交键. #60 同族的架构性收口建议单开一条，方向可以继续在这条 issue 里讨论。
3. PR 描述里最好带三样：① 依赖的宿主契约 [data-conversation-scroll]（宿主自用，稳定）；② 侧栏文档预览不被误裁的验证；③ #50 的输入框洞与新顶栏洞同时生效的回归（别让新 clipPath 把旧洞覆盖掉）。
4. 需要回归验证的话 @ 我：我这里是 Desktop 2.0.13 / 内核 0.1.5-rc.2 / annotation 1.4.10 出厂 bundle，这条问题在 1.4.10 上稳定复现，可以在同一环境帮你验一版。

最后：那条更正不用道歉。先量化、发现方法有问题就立刻撤回，这比留一条「看起来对」的结论有用得多 —— 也正好是这条 issue 本身要修的那种「看起来生效、实际没生效」。

[PerryLink]

谢谢这份清单 —— 四点都按它落地了；但先更正两件我自己写错的事。

一、PR 早就开了：#63

我在 04:51 就开了 #63 fix: 批注高亮与编号不再压住会话顶栏 (#62) —— 你 10:28 写「没有任何人在做」的时候它已经在队列里，
是我没有回到这条 issue 里说一声。你要求的四点它都覆盖：只挖会话列内的洞（侧栏 #57 不被误裁）、
不做「把标记层挂进会话滚动容器」的结构性收口、描述里带齐宿主契约 + 侧栏不被误裁 + #50 的洞不被覆盖；
#50 的输入框洞与新顶栏洞是同一个 polygon(evenodd, …) 里的两段，有用例断言两个洞同时存在。

二、更正：「这台机器没有浏览器」是我写错的

#63 原来的描述里写着「没有在真实浏览器里确认 —— 这台机器没有浏览器」。这句是错的。
本机装了 Chrome 153.0.8010.52 / Edge 148 / Firefox 156；我把「我没跑」错写成了「跑不了」。已改掉并补跑：

1. 插件自带的 test/overlay-browser.mjs：本机通过（Chrome 153 + Playwright，
   channel: 'chrome'）。但它的分量要说清 —— 同一个脚本在未打补丁的 client.js 上同样 PASS，
   因为它只覆盖 [Bug] 批注高亮块显示优先级高于输入框，选区高亮遮挡输入内容 #50 的输入框洞。它是「没弄坏」的证据，不是「修好了」的证据。
2. 顶栏横带的裁剪，用真实浏览器引擎单独验了：真实布局夹具（顶栏 / [data-conversation-scroll] /
   [data-composer-card] / 会话列之外的侧边栏），把插件实际安装的 clipPath 交给引擎，
   再用 document.elementFromPoint() 逐点验证。补丁后落在顶栏横带里的点不再命中标记层、
   未打补丁时命中（缺陷复现）；输入框洞仍被裁掉；会话正文与侧栏（与横带同 y、在会话列之外）仍可绘制。
   先断言该引擎确实在命中测试里遵守 clip-path，否则整张表没有意义 —— 这条自检通过。
   （坐标层面你第 2 点的结论直接决定了这个洞能不能这么画，谢谢。）

三、顺带发现（与本 issue 无关，没有塞进 #63）

test/overlay-browser.mjs 在 Windows 上根本跑不起来：它用
new URL('../client.js', import.meta.url).pathname 定位 client.js，Windows 上得到 /D:/...，
Playwright 于是去开 D:\D:\... 并报 ENOENT。换成 fileURLToPath(...) 就好了 ——
上面第 1 条就是这么跑通的。要的话我另开一条一行的 PR，不把无关改动混进 #63。

四、还差的那一半，正是你提的 offer

我这边验的是裁剪语义与几何，不是宿主里的观感 —— 本机没有 DSH Desktop。
所以想请你按你第 4 点验一版（Desktop 2.0.13 / 内核 0.1.5-rc.2 / annotation 1.4.10）：

1. 把被批注的原文滚到顶栏之下：高亮与编号不再压住顶栏，而是被那条横带裁掉；
2. 输入框上的胶囊行为与改动前一致（[Bug] 批注高亮块显示优先级高于输入框，选区高亮遮挡输入内容 #50 没有回归）。

若你更愿意在 1.4.10 出厂 bundle 上直接把 #63 的 client.js 覆盖进去跑同一套探针，结论等价。

[taekchef]

感谢你提供了完整的版本、复现步骤和图层分析，也感谢 PR #63 对侧栏裁剪范围的补充！这次按 Web DOM 机制做了前后版本对照，不再把 Windows/macOS 当作验证前提。

已在真实浏览器中复现 1.4.10 的问题：普通文档流顶栏下，把批注原文滚到顶栏后，高亮与编号仍会压在顶栏上；当前 main 的同一测试不再出现遮挡。保存后的重绘恢复、滚回正文、顶栏高度变化及侧栏批注不被误裁也通过了验证。测试与完整 CI 见 #75：https://github.com/omdsh-dev/dsh-annotation/actions/runs/36813657208

当前 main 已有顶栏裁剪与编号可见性修复，因此按这个已复现并验证修复的 Web 问题关闭。此结论覆盖上述图层/滚动场景；后续若仍有其他布局触发的遮挡，欢迎附版本、截图和步骤继续反馈。

注意：修复目前在 main，尚未发布新的 npm/GitHub 版本，原报告的 1.4.10 不含该修复。谢谢帮助把问题说清楚并推动验证！