Skip to content

fix(desktop): 指针离开文本后同一字符可以再次悬浮出 Hover - #2004

Draft
xiaoyumuxi wants to merge 1 commit into
mainfrom
fix/1995-hover-candidate-cache
Draft

xiaoyumuxi wants to merge 1 commit into
mainfrom
fix/1995-hover-candidate-cache

Conversation

@xiaoyumuxi

Copy link
Copy Markdown
Collaborator

关联 Issue / Linked issue

PR 类型 / Type

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

改动说明 / What changes

背景 / Why

指针在一个字符上停留、出现过 Hover 之后,只要指针离开了编辑区的文字(按 Esc、移出窗口、移到标签栏等其他控件、滚动编辑器),再回到同一个字符就不会再出现 Hover,也不会向语言服务器发 textDocument/hover,必须先经过别的字符才能恢复。原因是悬浮候选 hoverCandidate 在这些路径上没有清掉,pointPluginHover 把回来的那次当成“已经问过”直接返回。

改动 / Changes

desktop/internal/workbench/pluginsemantics_hover.go

  • 新增 leaveSemanticHover:关闭弹层、取消正在等的 Hover 请求,并清掉候选字符。
  • 新增 dropHoverCandidate:停止请求前的 500 ms 等待并忘掉候选字符;holdSemanticHover 改为调用它(行为不变)。
  • hoverTrackPointer:指针移到编辑器以外的元素(比如标签栏)时清掉候选;如果有指针打开的 Hover,仍按原来的延迟开始关闭。Viva 只把指针事件交给指针下的元素,编辑器在这种情况下收不到 PointerExit,窗口级的 hoverTrackPointer 是唯一能看到这次移动的地方。顺带修掉一个相关问题:还在 500 ms 等待中的 Hover 不会再在指针离开后于旧位置弹出。

desktop/internal/workbench/pluginsemantics.go

  • Esc(pluginSemanticsKey)、PointerExit、指针下没有文档(d == nil)、视图尚未绘制(PositionAt 返回 !ok)四条路径改为调用 leaveSemanticHover。
  • pluginSemanticsScrolled 先调用 leaveSemanticHover:内容在指针下移动后,等待中的 Hover 会在已经滚走的位置打开。
  • closePluginSemantics 复用 dropHoverCandidate,替换原来的内联取消和清空。
  • hoverCandidate 的注释写明候选在请求后保留(同一字符内移动不重复请求),离开文本时清掉。

desktop/internal/workbench/editor_view.go

  • 编辑器视图的 PointerExit 改为调用 leaveSemanticHover。

desktop/internal/workbench/pluginsemantics_hover_test.go

  • TestPointerHoverAsksAgainOnTheSameCharacterAfterLeavingTheText:表驱动,覆盖 Esc、移出窗口、移到标签栏、滚动四种离开方式,回到同一字符后必须发出第 2 次请求并打开 Hover。
  • TestPointerHoverLeavingTheTextDropsTheWait:等待中的 Hover 在指针移到标签栏后被取消,不发请求。
  • TestPointerHoverDoesNotAskAgainWithinACharacterWithoutHover:服务器返回空 Hover 后,在同一字符内移动不重复请求(防止修复过度)。
  • 新增测试辅助 documentBounds,用于找到编辑区上方的标签栏位置。

shared/platform-feature-matrix/features/lsp-completion-hover.json

  • 在 verification 里补充 2026-11-16 的行为说明;两端状态保持 partial / pending。

没有采用 Issue 里“在 closeSemanticHover 里重置候选”的建议:延迟隐藏(releaseSemanticHover)和空结果路径也会调用 closeSemanticHover,在那里清候选会取消刚在新位置排上的 Hover,或让没有 Hover 的字符内移动反复请求(第三个测试覆盖这一点)。

不在本 PR 范围内 / Out of scope

  • Issue 讨论中提到的 Hover 结果缓存不在桌面端实现:Core 能看到发给语言服务器的全部消息(包括它自己转发的工作区文件变化),缓存失效只有在 Core 里才完整,另开 Core PR 实现,再在本仓库升级 PINNED_CORE_REVISION。
  • 500 ms 停留延迟不变。

类型专属:fix

复现与根因

  • 复现步骤、实际结果、期望结果:打开 Go 文件,指针停在某个字符上等 Hover 出现;按 Esc(或把指针移出窗口、移到标签栏、滚动);把指针移回同一个字符等 500 ms 以上。实际:没有弹窗,也没有 textDocument/hover 请求。期望:和第一次一样请求并显示 Hover。
  • 根因(引入该行为的提交或 PR,用 git log -S 或 git blame 查):git log -S "candidate.active" 指向 0faecba(Epic(0.7.0): 基于 Viva 框架的跨平台方案的迁移(#1794) #1799,Viva 迁移)。pointPluginHover 遇到“和候选同一个位置且 candidate.active”时直接返回,而候选只在 holdSemanticHover 和 closePluginSemantics 里清空。
  • 影响平台:macOS 和 Windows(桌面端共享的 desktop/internal/workbench 代码)。

检查项

  • 已先写回归测试,确认它在修复前失败、修复后通过;测试路径与修复前的失败输出:desktop/internal/workbench/pluginsemantics_hover_test.go。修复前 TestPointerHoverAsksAgainOnTheSameCharacterAfterLeavingTheText 的 escape、out_of_the_window、over_the_tab_bar、scroll 四个子测试都失败(第 2 次请求没有发出,requestCount 一直是 1);TestPointerHoverLeavingTheTextDropsTheWait 失败(指针离开后候选还在)。TestPointerHoverDoesNotAskAgainWithinACharacterWithoutHover 修复前后都通过,用来约束行为不被改过头。
  • [N/A] 无法自动化时,已写明手动复现与验证步骤:已用无头测试自动化。
  • 已搜索被修改函数、类型、契约字段的全部调用方(含另一平台、插件、SDK、脚本和按字符串分发的调用):holdSemanticHover、closeSemanticHover、releaseSemanticHover、hoverTrackPointer、a.semantics.candidate 的调用方都在 desktop/internal/workbench,macOS 和 Windows 共用。
  • 已检查另一平台是否有同类缺陷(有则本 PR 一并修复,或已提交 Issue):两端共用同一份 Go 代码,本 PR 一并修复。
  • 只改了修复所需的代码,没有夹带重构;修复过程中发现的其他问题已提交 Issue:无新问题。
  • [N/A] 修复改变了行为约束或容易复发,已在 .agents/notes/implemented/bug-fix/ 记录:约束(不在 closeSemanticHover 清候选、编辑器收不到跨控件的 PointerExit)写在 leaveSemanticHover 和 hoverTrackPointer 的注释里,并由上面三个回归测试锁定。

范围检查 / Scope checks

功能矩阵 / Feature matrix

  • 已更新 shared/platform-feature-matrix/features/<id>.json:lsp-completion-hover 的 verification 增加本次行为;两端仍为 partial / pending(没有做原生窗口验收)。
  • 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh;改了平台实现路径的,还运行了 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/main HEAD
  • 没有提交 .artifacts/ 下生成的矩阵视图
  • [N/A] 没有更新矩阵的,理由:已更新。

插件归属 / Plugin ownership

  • 已在仓库根目录运行 develop-lithe 第三节“插件归属与宿主零依赖”的自查命令,结果为空
  • 新增或修改的测试只使用测试内联的合成插件、Core 契约 fixture 或插件市场索引快照;没有读取具体插件的插件包、仓库检出、构建产物或清单,没有使用真实插件 ID,没有“缺少插件时跳过”的测试(使用已有的 semanticFixture)
  • 没有为具体插件提供的能力新建或更新宿主功能矩阵条目;宿主条目的证据和验证动作不引用插件的测试、插件包或插件仓库
  • [N/A] 插件文案没有写进 shared/i18n/;插件的构建步骤、资源路径和补丁没有写进 scripts/resources/、docs/ci-builds.md、Agent Note 或 Skill:没有涉及文案和资源。
  • [N/A] 修改了通用扩展点、可能影响已发布插件的,已在受影响插件的仓库运行它的测试:没有改插件扩展点或契约,只改宿主何时发出 Hover 请求。

UI 验证 / UI evidence

  • [N/A] 已运行受影响场景的 Viva 无头测试,生成并检查对应本次实现的截图:没有布局或样式变化,只改 Hover 何时重新请求;行为由无头测试断言请求次数和弹层开关。
  • [N/A] 已在本 PR 嵌入截图或附上可访问的已上传截图 artifact 链接:同上,没有可见的样式变化。
  • [N/A] 布局与视觉变化有改动前后对照:同上。

统一日志系统 / 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

  • 可共享的逻辑在 Rust Core;平台层只做原生 I/O 和呈现:改动的是桌面端指针交互(指针离开文本时何时取消等待和清候选),属于呈现层;Hover 结果缓存放到 Core(见“不在本 PR 范围内”)。
  • [N/A] 修改平台层已有的可共享逻辑时已迁入 Core:没有改动可共享逻辑。
  • 工具或运行时专属的知识放在插件或成熟上游,宿主和 Core 没有按工具名加分支

性能与内存 / Performance and memory

  • 没有新增后台功能、子进程、缓存、定时器或依赖;离开文本时还会取消等待中的计时器,少一次无用请求。
  • 主线程没有文件读写、目录遍历、进程启动
  • [N/A] 性能基线数据:没有改动启动、打开项目、输入、滚动、大文件、长输出或搜索路径。

设置 / Settings

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

插件契约 / Plugin contract

N/A:没有改动插件契约、能力版本、插件函数协议或宿主方法。

发行包与资源 / Bundle and resources

N/A:没有新增或修改运行时资源、缓存、下载物或构建步骤。

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

  • 本次改动导致变成无用的代码已在本 PR 删除(closePluginSemantics 里的内联取消与清空已换成 dropHoverCandidate)
  • 本次之前就存在的无用代码或可重构之处,已提交带 refactor 标签的 Issue,没有在本 PR 顺手处理:未发现。

验证 / Verification

命令或操作 平台 结果
修复前运行 ./scripts/desktop/desktop-go.sh test ./internal/workbench -run 'TestPointerHover' macOS arm64 新增的 5 个用例失败,DoesNotAskAgainWithinACharacterWithoutHover 通过
./scripts/desktop/desktop-go.sh test ./internal/workbench -run 'Hover|Semantic' macOS arm64 通过
./scripts/desktop/desktop-go.sh test ./... macOS arm64 57 个包全部通过
./scripts/desktop/desktop-go.sh test -race ./internal/workbench -run 'Hover|Semantic' -count=1 macOS arm64 通过
./.agents/skills/write-stable-tests/scripts/test-stability-macos.sh --package ./internal/workbench --filter 'TestPointerHover' macOS arm64 通过,11 个用例单个耗时 80–340 ms
./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/main HEAD macOS 通过
./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh macOS 通过(193 项)
develop-lithe 第三节插件零依赖自查 rg macOS 结果为空
node scripts/i18n/verify-app-language-localization.mjs、node scripts/i18n/generate-i18n.mjs --check macOS 通过
gofmt -l desktop/internal/workbench/ macOS 无输出

未能执行的检查和原因:

  • Windows 本机虚拟机上没有运行测试;改动的是两端共用的 Go 代码,由 Draft 转 ready 后的 Windows CI 覆盖。
  • 没有做原生窗口的手动验收,功能矩阵验证状态保持 pending。

提交前确认 / Final checks

  • 分支从最新的 main 创建;目标分支:main
  • 以 Draft 提交,本地验证通过后才标记 ready
  • 没有无关改动,没有提交 .build/、target/、dist/、.artifacts/ 等产物,没有凭据、个人路径和未脱敏的日志或截图
  • 本次构建、测试或预览启动的 Lithe 应用和子进程已全部关闭,没有进程残留(只运行了无头测试,没有启动 Lithe 应用)

指针停在一个字符上请求过 Hover 之后,悬浮候选(hoverCandidate)只在
holdSemanticHover 和关闭语义会话时清掉。按 Esc、指针移出窗口、移到标签栏
等其他控件、滚动编辑器、移到没有文档的区域,都会留下旧候选;指针回到同一个
字符时 pointPluginHover 认为已经问过,不再请求,Hover 不再出现。

- 新增 leaveSemanticHover:关闭弹层、取消正在等的 Hover 请求并清掉候选;
  Esc、编辑器 PointerExit、指针下没有文档、视图尚未绘制(PositionAt 返回
  !ok)和滚动都走这条路径。
- 新增 dropHoverCandidate:停止请求前的等待并忘掉候选字符;
  holdSemanticHover 和 closePluginSemantics 复用它。
- hoverTrackPointer 在指针移到编辑器以外的控件时清掉候选。Viva 只把指针事件
  发给指针下的控件,编辑器收不到 PointerExit,这里是唯一能看到这次移动的
  地方;同时避免还在等待的 Hover 在旧位置弹出。
- 不在 closeSemanticHover 里清候选:延迟隐藏和空结果也会调用它,那样会取消
  刚在新位置排上的 Hover,或让没有 Hover 的字符内移动重复请求。

测试:
- TestPointerHoverAsksAgainOnTheSameCharacterAfterLeavingTheText 覆盖 Esc、
  移出窗口、移到标签栏、滚动四种离开方式,修复前全部失败。
- TestPointerHoverLeavingTheTextDropsTheWait 确认等待中的 Hover 不会在指针
  离开后发出请求。
- TestPointerHoverDoesNotAskAgainWithinACharacterWithoutHover 确认空结果后
  在同一字符内移动不会重复请求。

Refs #1995
@ghfind-review ghfind-review Bot added the review: high ghfind author score; see https://ghfind.com label Nov 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: high ghfind author score; see https://ghfind.com

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] 悬停弹窗按 Esc 关闭或指针离开文字后,回到同一个字符不再触发悬停

1 participant