vscode.languages.registerHoverProvider 是实现光标悬停查文档的核心入口，需显式指定 language ID（如 "python"），配合语义符号提取、分层缓存与跨源适配策略，确保精准、快速、可靠。
为什么 vscode.languages.registerHoverProvider 是核心入口
Hover 功能是实现“光标悬停即查文档”的最直接路径，VSCode 原生支持且不依赖编辑器重启。它比自定义命令或侧边栏更轻量、响应更快，也天然适配多语言——只要注册时指定对应 language（如 "python"、"typescript"），VSCode 就只在该语言文件中触发。
常见错误是漏写 documentSelector 或写成通配符 "*"，结果导致 hover 在 JSON、Markdown 里也弹出，干扰用户。正确做法是显式列出目标语言 ID：
vscode.languages.registerHoverProvider(
[{ language: 'python' }, { language: 'typescript' }, { language: 'rust' }],
new ApiHoverProvider()
);
注意：语言 ID 必须与 VSCode 内置或已安装插件注册的一致（例如不是 "ts" 而是 "typescript"），可通过打开对应文件后运行 Developer: Inspect Editor Tokens and Scopes 查看真实值。
如何从光标位置精准提取 API 符号名
Hover 触发时传入的是 TextDocument 和 Position，但原始文本里没有语法树，直接按空格或点号切分极易出错（比如 obj.method().prop 或 foo::bar::baz）。必须借助语言服务器协议（LSP）的 textDocument/semanticTokens 或已有解析能力。
实操建议分三层处理：
- 优先调用
vscode.languages.getFoldingRanges或vscode.languages.getDocumentSymbols获取当前作用域符号结构（适用于 TypeScript/Python 等有良好符号支持的语言） - 若不可用，退回到基于正则的保守提取：对 JS/TS 用
/[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*$/向左匹配；对 Rust 用/[a-zA-Z_]\w*(?:::[a-zA-Z_]\w*)*/ - 始终截断末尾的括号、尖括号、问号（如
fetch()→fetch，Option<t></t>→Option），避免把调用当类型查
本地缓存与远程文档源的协同策略
每次 hover 都实时请求 MDN、Rust Book 或 PyPI 文档，延迟高且易失败。必须本地缓存元数据 + 按需加载正文。
推荐结构：
- 缓存目录：
~/.vscode/extensions/yourname.api-docs/cache/，按语言分文件夹（python/、rust/） - 元数据用 JSON 存符号映射表，如
{"requests": {"url": "https://docs.python.org/3/library/urllib.request.html", "anchor": "urllib.request.urlopen"}} - 正文 HTML 不全量下载，只存摘要和跳转链接；点击「展开全文」再 fetch 并缓存 HTML 片段
- 首次启动时异步预热常用包（
requests、std、React），避免用户第一次 hover 就卡住
关键细节：缓存键必须包含语言 + 符号名 + 文档源版本（如 python-3.12），否则 Python 3.11 的 pathlib.Path 和 3.12 的行为差异会导致文档错位。
跨语言文档源适配的三个硬约束
MDN、Rust Book、PyPI、TypeScript lib.dom.d.ts 的结构天差地别，不能靠一套模板硬套。
每个源必须单独处理：
- MDN：URL 格式固定为
https://developer.mozilla.org/en-US/docs/Web/API/<code>SymbolName，但需处理大小写（getElementById→elementbyid）和别名（fetch实际在global_obj下） - Rust Book：符号在
std或alloc中，需先查https://doc.rust-lang.org/std/?search=xxx获取真实路径，再 GET 具体页面并提取<h1></h1>和<section class="docblock"></section> - TypeScript：直接读取
node_modules/typescript/lib/lib.dom.d.ts中的 JSDoc 注释，用ts.createSourceFile解析 AST，比爬网页稳定十倍
最容易被忽略的是错误降级：当 Rust 文档源不可达时，不能空白返回，而应 fallback 到本地已缓存的上一版摘要，或显示「文档暂不可用，尝试访问 https://doc.rust-lang.org/std/xxx」——用户需要明确知道“不是没做，而是没连上”。
