LSP Code Navigation

核心用法

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 版本更新可能改变类型推断行为，影响诊断一致性

核心用法

LSP Code Navigation 是一个基于 Pyright 的 Language Server Protocol (LSP) 客户端工具，专为 Python 代码库的智能导航而生。该工具通过管理一个后台守护进程（daemon），为开发者提供 IDE 级别的代码分析能力。

用户通过 lsp-query 命令行接口与守护进程交互，支持多种核心操作：定义跳转（definition）可快速定位符号的原始声明位置；引用查找（references）能扫描整个工作区找出所有使用该符号的地方；悬停提示（hover）实时显示类型签名和文档字符串；文档符号（symbols）生成文件结构概览；工作区符号搜索（workspace-symbols）支持跨文件模糊查找；此外还有诊断检查、代码补全、参数提示和重命名预览等功能。

工具采用人性化的 1 索引行号系统，与主流编辑器显示保持一致。守护进程具备自动生命周期管理——首次查询时自动启动，空闲 5 分钟后自动退出，用户也可通过 lsp-query shutdown 手动终止。

显著优点

零依赖轻量设计：整个客户端仅使用 Python 标准库实现，约 700 行代码完成功能，无第三方包依赖，部署简洁可靠。

性能优化架构：后台守护进程模式避免重复初始化 Pyright 的开销，冷启动后后续查询响应时间约 200ms，远优于单次调用模式。

功能覆盖全面：完整实现 LSP 核心协议，从基础导航到高级重构场景，满足日常开发的绝大部分代码理解需求。

环境灵活适配：通过 LSP_WORKSPACE 环境变量支持任意 Python 项目，自动检测 git 根目录，适配多种工作流。

潜在缺点与局限性

语言单一性：目前仅支持 Python，且依赖 Pyright 作为语言服务器，对使用其他类型检查器（如 mypy）的项目可能产生诊断结果差异。

环境配置门槛：需要独立安装 pyright-langserver（npm 包）和 Python 3.10+，对非 Node.js 生态用户增加配置步骤。

诊断准确性受限：在未激活正确虚拟环境的场景下，会出现大量"缺失导入"误报，这些提示需要用户理解其环境依赖性。

状态同步问题：文件大幅变更或分支切换后，守护进程可能持有陈旧索引，需要手动重启（lsp-query shutdown）来刷新状态。

Unix 平台限定：使用 Unix socket 进行进程间通信，Windows 平台需借助 WSL 等兼容层运行。

适合的目标群体

该工具特别适合以下用户场景：

• 大型代码库探索者：需要快速理解陌生项目结构、追踪调用链路的开发者
• 终端优先用户：习惯在命令行工作、追求轻量工具集的工程师
• AI Agent 增强：为 LLM Agent 提供代码上下文检索能力，替代简单的 grep 搜索
• CI/预提交检查：在自动化流程中快速执行类型诊断和符号验证
• 远程开发环境：资源受限服务器上运行，避免完整 IDE 的内存开销

使用风险与注意事项

进程管理风险：守护进程使用 os.fork() 创建，在极少数系统上可能遇到信号处理或资源隔离问题。建议监控 ~/.cache/lsp-query/ 目录避免 socket 文件堆积。

安全边界说明：虽然 subprocess.Popen 用于启动 LSP 服务器，但命令参数完全硬编码，无用户注入漏洞。工具仅进行本地文件索引，不会上传代码至外部服务。

性能预期管理：首次查询的 1-2 秒冷启动时间在大型项目中可能延长，建议在批量操作前先执行预热查询。

版本兼容性：Pyright 的更新可能改变诊断行为或协议响应格式，建议锁定工作环境中的 pyright 版本以保证一致性。