npx skills add https://github.com/lsp-client/lsp-skill --skill lsp-code-analysis要使用此技能,您必须遵循以下步骤:
lsp server start <project_path> 以启动 LSP 服务器并确认项目受支持。如果您不执行这些步骤,则不允许使用此技能。
本文档规定了 lsp-code-analysis 技能的操作要求和最佳实践。它通过语言服务器协议(LSP)为代码库导航、分析和重构提供了语义接口。
您可以使用 lsp CLI 工具进行语义代码导航和分析。对于大多数代码理解任务,应优先使用它,而不是 read 或 grep。
用途:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
指导原则:对于代码导航和分析,您应优先使用 LSP 命令。代理仅在语义分析不适用时(例如,搜索注释或字面字符串)才可以使用 read 或 grep。
| 任务 | 传统工具 | 推荐的 LSP 命令 |
|---|---|---|
| 查找定义 | grep, read | definition |
| 查找用法 | grep -r | reference |
| 理解文件 | read | outline |
| 查看文档/类型 | read | doc |
| 重构 | sed | 参见重构指南 |
所有命令都支持 -h 或 --help。
大多数命令通过 --scope 和 --find 选项使用统一的定位语法。
参数:<file_path>
选项:
--scope:将搜索范围缩小到符号体或行范围。--find:在范围内查找的文本模式。范围格式:
<line>:单行号(例如,42)。<start>,<end>:行范围(例如,10,20)。使用 0 作为结束表示直到文件末尾(例如,10,0)。<symbol_path>:带点的符号路径(例如,MyClass.my_method)。查找模式(--find):
--find 选项将目标缩小到选定范围内的文本模式:
--scope(行/范围/符号)确定。如果未给出 --scope,则整个文件是范围。<|>,以指定匹配项内感兴趣的确切位置(例如,在变量名、关键字或运算符上)。--find,命令将使用范围的起始位置(或工具特定的默认值)作为导航目标。光标标记(<|>):
<|> 标记指示符号解析的确切位置。它代表紧靠其右侧的字符。在查找模式中使用它来指向特定元素(例如,user.<|>name 以定位 name 属性)。
示例:
lsp doc foo.py --find "self.<|>" - 在整个文件中查找 self.,位置在点之后的字符(通常用于补全或成员访问)lsp doc foo.py --scope 42 --find "return <|>result" - 在第 42 行查找 return result,位置在 result 的 r 处lsp doc foo.py --scope 10,20 --find "if <|>condition" - 在第 10-20 行查找 if condition,位置在 condition 的 c 处lsp doc foo.py --scope MyClass.my_method --find "self.<|>" - 在 MyClass.my_method 内查找 self.,位置在点之后lsp doc foo.py --scope MyClass - 直接定位 MyClass 符号范围与查找的指导原则:
--scope <symbol_path>(例如,--scope MyClass,--scope MyClass.my_method)来定位类、函数或方法。这是定位符号最稳健且首选的方式。--find(通常与 --scope 结合使用)来定位变量或特定位置。当目标不是唯一命名的符号,或者您需要在代码块内精确定位特定用法时使用此方法。代理可以使用 lsp locate <file_path> --scope <scope> --find <find> 在运行其他命令之前验证目标是否存在于文件中并查看其上下文。
# 验证位置是否存在
lsp locate main.py --scope 42 --find "<|>process_data"
对于大型结果集(如 reference 或 search)使用分页。
--pagination-id <ID>:(必需)用于一致分页的唯一会话 ID。--max-items <N>:页面大小。--start-index <N>:偏移量(从 0 开始)。示例:
# 第 1 页
lsp search "User" --max-items 20 --pagination-id "task_123"
# 第 2 页
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"
指导原则:对于常见符号,使用具有唯一 ID 的分页功能以可管理的块获取结果。使用相同的 ID 递增 --start-index 进行浏览。
无需阅读实现即可获取分层符号结构。
# 获取主要符号(类、函数、方法)
lsp outline <file_path>
# 获取所有符号,包括变量和参数
lsp outline <file_path> --all
代理在读取文件之前应使用 outline,以避免不必要的上下文消耗。
导航到符号定义的位置。
# 跳转到 User.get_id 的定义位置
lsp definition models.py --scope User.get_id
# 查找导入的变量来自何处
lsp definition main.py --scope 42 --find "<|>config"
# 查找声明(例如,头文件、接口声明)
lsp definition models.py --scope 25 --mode declaration --find "<|>provider"
# 查找变量类型的类定义
lsp definition models.py --scope 30 --find "<|>user" --mode type_definition
查找符号被使用或实现的所有位置。
# 查找所有引用 logger 的地方
lsp reference main.py --scope MyClass.run --find "<|>logger"
# 查找接口/抽象类的所有具体实现
lsp reference api.py --scope "IDataProvider" --mode implementations
# 为每个引用获取更多周围的代码上下文
lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5
# 对于大型代码库限制结果数量
lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0
无需导航到源代码即可获取文档和类型信息。
# 获取第 42 行符号的文档字符串和类型信息
lsp doc main.py --scope 42
# 获取 process_data 函数的 API 文档
lsp doc models.py --scope process_data
当仅需要文档或类型信息时,代理应优先使用 doc 而不是 read。
当位置未知时,在整个工作区中搜索符号。
# 按名称搜索(默认为当前目录)
lsp search "MyClassName"
# 在特定项目中搜索
lsp search "UserModel" --project /path/to/project
# 按符号种类过滤(可以指定多次)
lsp search "init" --kinds function --kinds method
# 对于大型代码库限制结果数量并进行分页
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0
代理应使用 --kinds 来过滤结果并减少干扰。
获取包含某个位置的符号的完整源代码。
# 获取第 15 行函数/类的完整代码
lsp symbol main.py --scope 15
# 获取 UserClass 的完整实现
lsp symbol utils.py --scope UserClass
# 获取方法的完整实现
lsp symbol models.py --scope User.validate
响应包括:符号名称、种类(类/函数/方法)、范围以及完整的源代码。
代理应使用 symbol 来读取目标代码块,而不是对整个文件使用 read。
阅读重构指南了解重命名、提取和其他安全重构操作。
后台管理器会自动启动。手动控制是可选的。
# 列出正在运行的服务器
lsp server list
# 为项目启动服务器
lsp server start <path>
# 停止项目的服务器
lsp server stop <path>
# 关闭后台管理器
lsp server shutdown
探索新代码库的推荐顺序:
# 步骤 1:从 outline 开始 - 无需阅读实现即可获取文件结构
lsp outline <file_path>
# 步骤 2:检查签名 - 使用 doc 理解 API 契约
lsp doc <file_path> --scope <symbol_name>
# 步骤 3:导航依赖关系 - 跟随定义链
lsp definition <file_path> --scope <symbol_name>
# 步骤 4:映射用法 - 使用 reference 查找代码被调用的位置
lsp reference <file_path> --scope <symbol_name>
# 步骤 1:在整个工作区定位符号定义
lsp search "<symbol_name>"
# 步骤 2:验证实现细节
lsp definition <file_path> --scope <symbol_name>
# 步骤 3:跟踪所有调用者以理解调用上下文
lsp reference <file_path> --scope <symbol_name>
# 步骤 1:定位接口定义
lsp search "IUserService" --kinds interface
# 步骤 2:查找所有实现
lsp reference src/interfaces.py --scope IUserService --mode implementations
# 步骤 1:查找数据创建的位置
lsp search UserDTO --kinds class
# 步骤 2:查找使用它的位置
lsp reference models.py --scope UserDTO
# 步骤 3:检查转换
lsp doc transform.py --scope map_to_dto
# 步骤 1:获取类大纲
lsp outline models.py
# 步骤 2:查找子类(对基类的引用)
lsp reference models.py --scope BaseModel
# 步骤 3:检查类型定义
lsp definition models.py --scope BaseModel --mode type_definition
# 使用 outline 而不是读取整个文件
lsp outline large_file.py # 优于:read large_file.py
# 对嵌套结构使用符号路径(比行号更精确)
lsp definition models.py --scope User.Profile.validate
# 在大型代码库中限制结果数量
lsp search "User" --max-items 20
# 使用 doc 理解 API 而无需导航到源代码
lsp doc api.py --scope fetch_data # 无需跳转到定义即可获取文档/类型
# 如果命令失败,验证定位字符串
lsp locate main.py --scope 42 --find "<|>my_var"
针对专业场景,请参阅:
每周安装量
158
仓库
GitHub 星标数
82
首次出现
2026年1月22日
安全审计
安装于
opencode146
codex141
gemini-cli136
github-copilot133
amp124
kimi-cli118
To use this skill, you MUST follow these steps:
lsp server start <project_path> to start the LSP server and confirm the project is supported.IF YOU DO NOT PERFORM THESE STEPS, YOU ARE NOT ALLOWED TO USE THIS SKILL.
This document specifies the operational requirements and best practices for the lsp-code-analysis skill. It provides a semantic interface to codebase navigation, analysis and refactoring via the Language Server Protocol (LSP).
You are provided with lsp CLI tool for semantic code navigation and analysis. It SHOULD be preferred over read or grep for most code understanding tasks.
Usages:
Guideline : You SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use read or grep ONLY when semantic analysis is not applicable (e.g., searching for comments or literal strings).
| Task | Traditional Tool | Recommended LSP Command |
|---|---|---|
| Find Definition | grep, read | definition |
| Find Usages | grep -r | reference |
| Understand File | read | outline |
All commands support -h or --help.
Most commands use a unified locating syntax via the --scope and --find options.
Arguments : <file_path>
Options :
--scope: Narrow search to a symbol body or line range.--find: Text pattern to find within the scope.Scope Formats :
<line>: Single line number (e.g., 42).<start>,<end>: Line range (e.g., 10,20). Use 0 for end to mean till EOF (e.g., 10,0).<symbol_path>: Symbol path with dots (e.g., MyClass.my_method).Find Pattern (--find):
The --find option narrows the target to a text pattern within the selected scope :
--scope (line/range/symbol). If no --scope is given, the entire file is the scope.<|> inside the pattern to specify the exact position of interest within the match (for example, on a variable name, keyword, or operator).--find is omitted, the command uses the start of the scope (or a tool-specific default) as the navigation target.Cursor Marker (<|>):
The <|> marker indicates the exact position for symbol resolution. It represents the character immediately to its right. Use it within the find pattern to point to a specific element (e.g., user.<|>name to target the name property).
Examples :
lsp doc foo.py --find "self.<|>" - Find self. in entire file, position at the character after the dot (typically for completion or member access)lsp doc foo.py --scope 42 --find "return <|>result" - Find return result on line 42, position at r of resultlsp doc foo.py --scope 10,20 --find "if <|>condition" - Find if condition in lines 10-20, position at c of conditionGuideline for Scope vs. Find :
--scope <symbol_path> (e.g., --scope MyClass, --scope MyClass.my_method) to target classes, functions, or methods. This is the most robust and preferred way to target symbol.--find (often combined with --scope) to target variables or specific positions. Use this when the target is not a uniquely named symbol or when you need to pinpoint a specific usage within a code block.Agents MAY use lsp locate <file_path> --scope <scope> --find <find> to verify if the target exists in the file and view its context before running other commands.
# Verify location exists
lsp locate main.py --scope 42 --find "<|>process_data"
Use pagination for large result sets like reference or search.
--pagination-id <ID>: (Required) Unique session ID for consistent paging.--max-items <N>: Page size.--start-index <N>: Offset (0-based).Example :
# Page 1
lsp search "User" --max-items 20 --pagination-id "task_123"
# Page 2
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"
Guideline : Use pagination with a unique ID for common symbols to fetch results in manageable chunks. Increment --start-index using the same ID to browse.
Get hierarchical symbol structure without reading implementation.
# Get main symbols (classes, functions, methods)
lsp outline <file_path>
# Get all symbols including variables and parameters
lsp outline <file_path> --all
Agents SHOULD use outline before reading files to avoid unnecessary context consumption.
Navigate to where symbols are defined.
# Jump to where User.get_id is defined
lsp definition models.py --scope User.get_id
# Find where an imported variable comes from
lsp definition main.py --scope 42 --find "<|>config"
# Find declaration (e.g., header files, interface declarations)
lsp definition models.py --scope 25 --mode declaration --find "<|>provider"
# Find the class definition of a variable's type
lsp definition models.py --scope 30 --find "<|>user" --mode type_definition
Find where symbols are used or implemented.
# Find all places where logger is referenced
lsp reference main.py --scope MyClass.run --find "<|>logger"
# Find all concrete implementations of an interface/abstract class
lsp reference api.py --scope "IDataProvider" --mode implementations
# Get more surrounding code context for each reference
lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5
# Limit results for large codebases
lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0
Get documentation and type information without navigating to source.
# Get docstring and type info for symbol at line 42
lsp doc main.py --scope 42
# Get API documentation for process_data function
lsp doc models.py --scope process_data
Agents SHOULD prefer doc over read when only documentation or type information is needed.
Search for symbols across the workspace when location is unknown.
# Search by name (defaults to current directory)
lsp search "MyClassName"
# Search in specific project
lsp search "UserModel" --project /path/to/project
# Filter by symbol kind (can specify multiple times)
lsp search "init" --kinds function --kinds method
# Limit and paginate results for large codebases
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0
Agents SHOULD use --kinds to filter results and reduce noise.
Get the full source code of the symbol containing a location.
# Get complete code of the function/class at line 15
lsp symbol main.py --scope 15
# Get full UserClass implementation
lsp symbol utils.py --scope UserClass
# Get complete method implementation
lsp symbol models.py --scope User.validate
Response includes: symbol name, kind (class/function/method), range, and complete source code.
Agents SHOULD use symbol to read targeted code blocks instead of using read on entire files.
Read Refactoring Guide for rename, extract, and other safe refactoring operations.
The background manager starts automatically. Manual control is OPTIONAL.
# List running servers
lsp server list
# Start server for a project
lsp server start <path>
# Stop server for a project
lsp server stop <path>
# Shutdown the background manager
lsp server shutdown
The RECOMMENDED sequence for exploring new codebases:
# Step 1: Start with outline - Get file structure without reading implementation
lsp outline <file_path>
# Step 2: Inspect signatures - Use doc to understand API contracts
lsp doc <file_path> --scope <symbol_name>
# Step 3: Navigate dependencies - Follow definition chains
lsp definition <file_path> --scope <symbol_name>
# Step 4: Map usage - Find where code is called with reference
lsp reference <file_path> --scope <symbol_name>
# Step 1: Locate symbol definition workspace-wide
lsp search "<symbol_name>"
# Step 2: Verify implementation details
lsp definition <file_path> --scope <symbol_name>
# Step 3: Trace all callers to understand invocation context
lsp reference <file_path> --scope <symbol_name>
# Step 1: Locate interface definition
lsp search "IUserService" --kinds interface
# Step 2: Find all implementations
lsp reference src/interfaces.py --scope IUserService --mode implementations
# Step 1: Find where data is created
lsp search UserDTO --kinds class
# Step 2: Find where it's used
lsp reference models.py --scope UserDTO
# Step 3: Check transformations
lsp doc transform.py --scope map_to_dto
# Step 1: Get class outline
lsp outline models.py
# Step 2: Find subclasses (references to base)
lsp reference models.py --scope BaseModel
# Step 3: Check type definitions
lsp definition models.py --scope BaseModel --mode type_definition
# Use outline instead of reading entire files
lsp outline large_file.py # Better than: read large_file.py
# Use symbol paths for nested structures (more precise than line numbers)
lsp definition models.py --scope User.Profile.validate
# Limit results in large codebases
lsp search "User" --max-items 20
# Use doc to understand APIs without navigating to source
lsp doc api.py --scope fetch_data # Get docs/types without jumping to definition
# Verify locate strings if commands fail
lsp locate main.py --scope 42 --find "<|>my_var"
For specialized scenarios, see:
Weekly Installs
158
Repository
GitHub Stars
82
First Seen
Jan 22, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykWarn
Installed on
opencode146
codex141
gemini-cli136
github-copilot133
amp124
kimi-cli118
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
113,700 周安装
| View Docs/Types | read | doc |
| Refactor | sed | See Refactoring Guide |
lsp doc foo.py --scope MyClass.my_method --find "self.<|>" - Find self. within MyClass.my_method, position after the dotlsp doc foo.py --scope MyClass - Target the MyClass symbol directly