lsp-code-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LSP Code Analysis

LSP代码分析

IMPORTANT: PREREQUISITE

重要：前置条件

To use this skill, you MUST follow these steps:

Check for updates: Run the update script to ensure you are using the latest version of the tool.
Verify project support: Run
```
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.

要使用此技能，您必须遵循以下步骤：

检查更新：运行更新脚本以确保使用工具的最新版本。
验证项目支持：运行
```
lsp server start <project_path>
```
启动LSP服务器并确认项目受支持。

如果不执行这些步骤，您将无法使用该技能。

Abstract

摘要

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).

本文档规定了

lsp-code-analysis

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

Overview

概述

You are provided with

lsp

CLI tool for semantic code navigation and analysis. It SHOULD be preferred over

read

grep

for most code understanding tasks.

Usages:

Semantic navigation: Jump to definitions, find references, locate implementations - understands code structure, not just text patterns.
Language-aware: Distinguishes between variables, functions, classes, types - eliminates false positives from text search.
Cross-file intelligence: Trace dependencies, refactor safely across entire codebase - knows what imports what.
Type-aware: Get precise type information, signatures, documentation - without reading implementation code.

您将获得用于语义代码导航和分析的

lsp

CLI工具。对于大多数代码理解任务，应优先使用该工具而非

read

或

grep

。

用途：

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

Tool Selection

工具选择

Guideline: You SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use

read

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`
View Docs/Types	`read`	`doc`
Refactor	`sed`	See Refactoring Guide

指南：应优先使用LSP命令进行代码导航和分析。仅当语义分析不适用时（例如搜索注释或文字字符串），Agents才可使用

read

或

grep

。

任务	传统工具	推荐的LSP命令
查找定义	`grep` , `read`	`definition`
查找用法	`grep -r`	`reference`
理解文件内容	`read`	`outline`
查看文档/类型	`read`	`doc`
重构	`sed`	查看重构指南

Commands

命令

All commands support

-h

--help

所有命令均支持

-h

或

--help

参数。

Locating Symbols

定位符号

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:

The scope is determined by
```
--scope
```
(line/range/symbol). If no
```
--scope
```
is given, the entire file is the scope.
Pattern matching is whitespace-insensitive: differences in spaces, tabs, and newlines are ignored.
You MAY include the cursor marker
```
<|>
```
inside the pattern to specify the exact position of interest within the match (for example, on a variable name, keyword, or operator).
If
```
--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

result

lsp doc foo.py --scope 10,20 --find "if <|>condition"

- Find

if condition

in lines 10-20, position at

condition

lsp doc foo.py --scope MyClass.my_method --find "self.<|>"

- Find

self.

within

MyClass.my_method

, position after the dot

```
lsp doc foo.py --scope MyClass
```
- Target the
```
MyClass
```
symbol directly

Guideline for Scope vs. Find:

Use
```
--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.
Use
```
--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.

bash

undefined

大多数命令通过

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

的

字符处

lsp doc foo.py --scope 10,20 --find "if <|>condition"

- 在10-20行查找

if condition

，位置在

condition

的

字符处

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
```
结合）来定位变量或特定位置。当目标不是唯一命名的符号，或者您需要在代码块中精确定位特定用法时使用此选项。

Agents可以使用

lsp locate <file_path> --scope <scope> --find <find>

来验证目标是否存在于文件中，并在运行其他命令前查看其上下文。

bash

undefined

Verify location exists

验证位置是否存在

lsp locate main.py --scope 42 --find "<|>process_data"

undefined

lsp locate main.py --scope 42 --find "<|>process_data"

undefined

Pagination

分页

Use pagination for large result sets like

reference

search

```
--pagination-id <ID>
```
: (Required) Unique session ID for consistent paging.
```
--max-items <N>
```
: Page size.
```
--start-index <N>
```
: Offset (0-based).

Example:

bash

undefined

对于

reference

或

search

等大型结果集，使用分页功能。

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

示例：

bash

undefined

Page 1

第1页

lsp search "User" --max-items 20 --pagination-id "task_123"

Page 2

第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.

lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"


**指南**：对于常见符号，使用带唯一ID的分页功能以分块获取结果。使用相同ID递增`--start-index`来浏览后续页面。

Outline: File Structure

大纲：文件结构

Get hierarchical symbol structure without reading implementation.

bash

undefined

无需阅读实现代码即可获取分层符号结构。

bash

undefined

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.

lsp outline <file_path> --all


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

Definition: Navigate to Source

定义：跳转到源代码

Navigate to where symbols are defined.

bash

undefined

导航到符号的定义位置。

bash

undefined

Jump to where User.get_id is defined

跳转到User.get_id的定义位置

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

undefined

lsp definition models.py --scope 30 --find "<|>user" --mode type_definition

undefined

Reference: Find All Usages

引用：查找所有用法

Find where symbols are used or implemented.

bash

undefined

查找符号的使用或实现位置。

bash

undefined

Find all places where logger is referenced

查找logger被引用的所有位置

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

undefined

lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0

undefined

Doc: Get Documentation

文档：获取文档信息

Get documentation and type information without navigating to source.

bash

undefined

无需导航到源代码即可获取文档和类型信息。

bash

undefined

Get docstring and type info for symbol at line 42

获取第42行符号的文档字符串和类型信息

lsp doc main.py --scope 42

Get API documentation for process_data function

获取process_data函数的API文档

lsp doc models.py --scope process_data


Agents SHOULD prefer `doc` over `read` when only documentation or type information is needed.

lsp doc models.py --scope process_data


当仅需要文档或类型信息时，Agents应优先使用`doc`而非`read`。

Search: Global Symbol Search

搜索：全局符号搜索

Search for symbols across the workspace when location is unknown.

bash

undefined

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

bash

undefined

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.

lsp search "Config" --max-items 10 lsp search "User" --max-items 20 --start-index 0


Agents应使用`--kinds`来过滤结果，减少干扰。

Symbol: Get Complete Symbol Code

符号：获取完整符号代码

Get the full source code of the symbol containing a location.

bash

undefined

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

bash

undefined

Get complete code of the function/class at line 15

获取第15行的函数/类的完整代码

lsp symbol main.py --scope 15

Get full UserClass implementation

获取UserClass的完整实现

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.

lsp symbol models.py --scope User.validate


响应包括：符号名称、类型（类/函数/方法）、范围以及**完整源代码**。

Agents应使用`symbol`来读取目标代码块，而非使用`read`读取整个文件。

Refactoring Operations

重构操作

Read Refactoring Guide for rename, extract, and other safe refactoring operations.

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

Server: Manage Background Servers

服务器：管理后台服务器

The background manager starts automatically. Manual control is OPTIONAL.

bash

undefined

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

bash

undefined

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

undefined

lsp server shutdown

undefined

Best Practices

最佳实践

General Workflows

通用工作流

Understanding Unfamiliar Code

理解不熟悉的代码

The RECOMMENDED sequence for exploring new codebases:

bash

undefined

探索新代码库的推荐流程：

bash

undefined

Step 1: Start with outline - Get file structure without reading implementation

步骤1：从大纲开始 - 无需阅读实现即可获取文件结构

lsp outline <file_path>

Step 2: Inspect signatures - Use doc to understand API contracts

步骤2：检查签名 - 使用doc理解API契约

lsp doc <file_path> --scope <symbol_name>

Step 3: Navigate dependencies - Follow definition chains

步骤3：导航依赖关系 - 跟踪定义链

lsp definition <file_path> --scope <symbol_name>

Step 4: Map usage - Find where code is called with reference

步骤4：映射用法 - 使用reference查找代码的调用位置

lsp reference <file_path> --scope <symbol_name>

undefined

lsp reference <file_path> --scope <symbol_name>

undefined

Debugging Unknown Behavior

调试未知行为

bash

undefined

bash

undefined

Step 1: Locate symbol definition workspace-wide

步骤1：在工作区中定位符号定义

lsp search "<symbol_name>"

Step 2: Verify implementation details

步骤2：验证实现细节

lsp definition <file_path> --scope <symbol_name>

Step 3: Trace all callers to understand invocation context

步骤3：跟踪所有调用者以理解调用上下文

lsp reference <file_path> --scope <symbol_name>

undefined

lsp reference <file_path> --scope <symbol_name>

undefined

Finding Interface Implementations

查找接口实现

bash

undefined

bash

undefined

Step 1: Locate interface definition

步骤1：定位接口定义

lsp search "IUserService" --kinds interface

Step 2: Find all implementations

步骤2：查找所有实现

lsp reference src/interfaces.py --scope IUserService --mode implementations

undefined

lsp reference src/interfaces.py --scope IUserService --mode implementations

undefined

Tracing Data Flow

追踪数据流

bash

undefined

bash

undefined

Step 1: Find where data is created

步骤1：查找数据创建位置

lsp search UserDTO --kinds class

Step 2: Find where it's used

步骤2：查找数据使用位置

lsp reference models.py --scope UserDTO

Step 3: Check transformations

步骤3：检查转换逻辑

lsp doc transform.py --scope map_to_dto

undefined

lsp doc transform.py --scope map_to_dto

undefined

Understanding Type Hierarchies

理解类型层次结构

bash

undefined

bash

undefined

Step 1: Get class outline

步骤1：获取类大纲

lsp outline models.py

Step 2: Find subclasses (references to base)

步骤2：查找子类（对基类的引用）

lsp reference models.py --scope BaseModel

Step 3: Check type definitions

步骤3：检查类型定义

lsp definition models.py --scope BaseModel --mode type_definition

undefined

lsp definition models.py --scope BaseModel --mode type_definition

undefined

Performance Tips

性能提示

bash

undefined

bash

undefined

Use outline instead of reading entire files

使用outline代替读取整个文件

lsp outline large_file.py # Better than: read large_file.py

lsp outline large_file.py # 优于：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

使用doc理解API，无需导航到源代码

lsp doc api.py --scope fetch_data # Get docs/types without jumping to definition

lsp doc api.py --scope fetch_data # 获取文档/类型信息，无需跳转到定义

Verify locate strings if commands fail

如果命令失败，验证定位字符串

lsp locate main.py --scope 42 --find "<|>my_var"

undefined

lsp locate main.py --scope 42 --find "<|>my_var"

undefined

Domain-Specific Guides

特定领域指南

For specialized scenarios, see:

Monorepo: monorepo.md
Frontend: bp_frontend.md
Backend: bp_backend.md

针对特殊场景，请参阅：

单体仓库：monorepo.md
前端：bp_frontend.md
后端：bp_backend.md