基于VSCode插件开发实现多语言API文档实时查阅工具-VSCode-PHP中文网

vscode.languages.registerHoverProvider 是实现光标悬停查文档的核心入口，需显式指定 language ID（如 "python"），配合语义符号提取、分层缓存与跨源适配策略，确保精准、快速、可靠。

基于vscode插件开发实现多语言api文档实时查阅工具

为什么 `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

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

推荐结构：

缓存目录：~/.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，比爬网页稳定十倍