lsp-code-analysis

LSP 代码分析

重要提示：前置条件

要使用此技能，必须执行以下步骤：

1. 检查更新：运行更新脚本，确保使用的是最新版本的工具。
2. 验证项目支持情况：运行 lsp server start <project_path> 启动 LSP 服务，并确认该项目受支持。

如果未执行这些步骤，则不得使用此技能。

摘要

本文档规定了 lsp-code-analysis 技能的操作要求和最佳实践。它通过语言服务器协议（LSP）提供代码库导航、分析和重构的语义接口。

概述

你可以使用 lsp CLI 工具进行语义代码导航和分析。对于大多数代码理解任务，应该优先使用它，而不是 read 或 grep。

用途：

• 语义导航：跳转到定义、查找引用、定位实现——理解代码结构，而不仅仅是文本模式。
• 语言感知：区分变量、函数、类和类型——消除文本搜索带来的误报。
• 跨文件智能：追踪依赖关系，在整个代码库中安全地重构——了解各项内容之间的导入关系。
• 类型感知：获取准确的类型信息、签名和文档——无需阅读实现代码。

工具选择

指南：应优先使用 LSP 命令进行代码导航和分析。仅当语义分析不适用时（例如，搜索注释或字面字符串），Agent 才可使用 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 结合使用）来定位变量或特定位置。如果目标不是名称唯一的符号，或者需要在代码块中精确定位某处用法，请使用此选项。

Agent 可以使用 lsp locate <file_path> --scope <scope> --find <find>，在运行其他命令之前验证目标是否存在于文件中，并查看其上下文。

# Verify location exists
lsp locate main.py --scope 42 --find "<|>process_data"

分页

对于 reference 或 search 等大型结果集，请使用分页。

• --pagination-id <ID>：（必需）用于一致分页的唯一会话 ID。
• --max-items <N>：每页大小。
• --start-index <N>：偏移量（从 0 开始）。

示例：

# 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"

指南：对常用符号使用带唯一 ID 的分页，以分块获取结果。使用相同 ID 递增 --start-index 进行浏览。

大纲：文件结构

获取分层符号结构，而无需读取实现。

# Get main symbols (classes, functions, methods)
lsp outline <file_path>

# Get all symbols including variables and parameters
lsp outline <file_path> --all

Agent 应在读取文件前使用 outline，以避免不必要地消耗上下文。

定义：跳转到源代码

跳转到符号的定义位置。

# 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 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 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

如果只需要文档或类型信息，Agent 应优先使用 doc，而不是 read。

搜索：全局符号搜索

当位置未知时，在工作区中搜索符号。

# 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

Agent 应使用 --kinds 过滤结果并减少干扰。

符号：获取完整符号代码

获取包含指定位置的符号的完整源代码。

# 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

响应包含：符号名称、种类（类／函数／方法）、范围和完整源代码。

Agent 应使用 symbol 读取目标代码块，而不是使用 read 读取整个文件。

重构操作

重命名、提取及其他安全重构操作，请阅读重构指南。

服务：管理后台服务

后台管理器会自动启动。手动控制为可选操作。

# 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

最佳实践

常规工作流

理解陌生代码

探索新代码库的推荐顺序：

# 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"

特定领域指南

如需了解特定场景，请参阅：

• Monorepo：monorepo.md
• 前端：bp_frontend.md
• 后端：bp_backend.md