核心用法
lsp skill 是一个基于 pyright 的 Language Server Protocol 客户端，通过后台守护进程为 Python 代码库提供 IDE 级导航能力。核心工作流：
1. 环境配置：设置 LSP_WORKSPACE 指向仓库根目录，或依赖自动检测（git root/cwd）
2. 守护进程管理：首次查询自动启动后台 pyright 服务，5 分钟空闲后自动关闭
3. 命令行交互：通过 lsp-query 脚本发起各类 LSP 请求
关键命令矩阵：
| 场景 | 命令 | 输出 |
|------|------|------|
| 跳转到定义 | `definition <file> <line> <col>` | 符号源文件位置 |
| 查找引用 | `references <file> <line> <col>` | 全工作区调用点列表 |
| 类型信息 | `hover <file> <line> <col>` | 签名+文档字符串 |
| 文件结构 | `symbols <file>` | 类/函数/变量层级树 |
| 全局搜索 | `workspace-symbols "Name"` | 跨文件符号匹配 |
| 类型诊断 | `diagnostics <file>` | 错误/警告/提示 |
| 代码补全 | `completions <file> <line> <col>` | 可用成员列表 |
| 参数提示 | `signature <file> <line> <col>` | 函数形参详情 |
| 重构预览 | `rename <file> <line> <col> <new>` | 影响范围清单 |
显著优点
- 精准语义：基于 AST 和类型信息，远超文本搜索（grep）的准确性，能识别同名不同义的符号
- 零配置启动：自动检测工作区、自管理守护进程，无需编写 LSP 配置
- 低延迟交互：热守护进程响应约 200ms，支持快速迭代探索
- 全功能覆盖：从定义跳转、引用查找、类型推断到重构预览，覆盖日常代码理解 90% 场景
- 编辑器无关：纯 CLI 输出，可集成任意工作流（终端、脚本、编辑器插件）
潜在缺点与局限性
- Python 专属：底层依赖 pyright，仅支持 Python 代码库
- 环境敏感：诊断结果受当前 Python 环境包安装状态影响，缺失依赖会导致误报 import 错误
- Node 依赖链：需 npm 安装 pyright，在部分沙箱环境可能受限
- 守护进程状态：大幅代码变更（如切换分支）后可能返回陈旧结果，需手动
shutdown刷新 - 1-indexed 坐标：与 LSP 标准 0-indexed 不同，虽"人类友好"但与其他工具集成时需转换
- 无持久缓存：每次守护进程重启需重新索引大仓库，冷启动 1-2 秒
适合人群
- AI 助手/Agent：需要在无 GUI 环境下精准理解代码结构、追踪调用链
- 终端优先开发者：偏好 Vim/Emacs 等编辑器，需要 IDE 级代码导航能力
- 代码审查者：快速评估变更影响范围（rename preview + references）
- 大型 Python 项目维护者：FineWebEduGPT 等复杂仓库的全局符号搜索
常规风险
- 文件系统持久化：在
~/.cache/lsp-query/创建 Unix socket 和日志，多用户环境需注意权限 - 资源占用：后台 pyright 进程持续占用内存（典型 200-500MB），大仓库可能更高
- 命令注入边界：
LSP_SERVER环境变量允许自定义服务器命令，若从不可信输入构造存在注入可能 - 跨仓库污染：同一 socket 可能被不同
LSP_WORKSPACE复用，导致符号解析上下文混乱 - 依赖版本漂移：pyright 版本更新可能改变类型推断行为，影响诊断一致性