用途：python-lsp 是一个轻量、无额外依赖的 Python 客户端，负责管理 pyright-langserver --stdio 的 LSP 生命周期，并暴露高价值的语义查询。相比 tree-sitter 或 ripgrep，它能做名称解析、类型推断和跨文件绑定，避免同名符号误报。
主要能力：definition（跨文件/导入跳转定义）、references（绑定解析的引用查找）、hover（推断类型/签名）、diagnostics（pyright 类型与错误诊断）、document_symbols（单文件大纲）、workspace_symbols（项目级模糊符号搜索）。
使用方式：首次使用可运行 sh /mnt/skills/user/python-lsp/scripts/bootstrap.sh 或 command -v pyright-langserver >/dev/null || uv tool install pyright 安装 pyright。CLI 用法为 python3 $LSP <root> definition|references|hover|diagnostics|symbols|wsymbols ...，位置为从零开始的 line/col。库用法可导入 LSPClient，用上下文管理器打开文件、调用 wait_for_index() 后再查询。
限制与注意：查询前必须等待索引完成，否则返回空结果；不要声明 workspace.configuration 或 workspace.workspaceFolders，否则 pyright 会静默；需用上下文管理器或 stop() 回收子进程；跨文件引用应先打开相关文件；根目录应指向项目根而非子包，否则绝对导入解析失败、引用少计，LSPClient 会自动上溯并输出提示，可用 auto_root=False 关闭。需要系统 node v18+，无 node 时可能回退下载但受限环境可能被阻止。测试可运行 python3 -m pytest tests/test_lsp_client.py -v。