typescript-lsp

TypeScript LSP 技能

目的

此技能提供 TypeScript Language Server Protocol 集成，用于探索和理解 TypeScript/JavaScript 代码库。

重要：处理 *.ts、*.tsx、*.js、*.jsx 文件时，优先使用 LSP 工具，而非 Grep/Glob。LSP 提供类型感知的结果，能够理解导入、导出和符号之间的关系。

使用这些工具来：

• 探索代码库——查找符号、了解模块结构、发现实现
• 查找引用——在整个代码库中进行类型感知搜索（查找符号时优于 grep）
• 了解类型——获取完整的类型签名、泛型和文档
• 编辑前验证——修改或删除导出内容前，检查所有用法
• 浏览代码——跳转到定义、查找实现

各工具的适用场景

工具	用途
Glob	按模式查找文件
Grep	搜索文本内容
lsp-find	搜索 TypeScript 符号
lsp-hover	获取类型信息和 TSDoc 文档
lsp-refs	查找符号的所有引用
lsp-analyze	批量分析文件结构

LSP 与 Grep/Glob 对比

任务	使用 LSP	使用 Grep/Glob
查找函数/类型的所有用法	✅ lsp-refs	❌ 会漏掉重新导出、别名
按名称搜索符号	✅ lsp-find	❌ 会匹配字符串、注释
获取类型签名和 TSDoc	✅ lsp-hover	❌ 无法实现
了解文件导出内容	✅ lsp-analyze --exports	❌ 无法解析重新导出
按模式查找文件	❌	✅ Glob
搜索非 TS 文件（md、json）	❌	✅ Grep
搜索注释/字符串中的文本	❌	✅ Grep

使用时机

探索代码（优先使用 LSP）：

• 运行 lsp-find，在工作区中搜索符号
• 运行 lsp-symbols，概览文件结构
• 运行 lsp-analyze --exports，查看模块提供的内容

编辑代码前：

• 运行 lsp-references，查找计划修改的符号的所有用法
• 运行 lsp-hover，验证当前类型签名

编写代码前：

• 运行 lsp-find，搜索相似模式或相关符号
• 对计划使用的 API 运行 lsp-hover

路径解析

所有脚本均接受三种文件路径：

• 绝对路径：/Users/name/project/src/file.ts
• 相对路径：./src/file.ts 或 ../other/file.ts
• 包导出路径：my-package/src/module.ts（通过 Bun.resolve() 解析）

建议使用包导出路径，以提高可移植性，并与包的 exports 字段保持一致。

脚本

单独脚本

lsp-hover

获取指定位置的类型信息。

bunx @plaited/development-skills lsp-hover <file> <line> <char>

参数：

• file：TypeScript/JavaScript 文件的路径
• line：行号（从 0 开始计数）
• char：字符位置（从 0 开始计数）

示例：

bunx @plaited/development-skills lsp-hover src/utils/parser.ts 42 10

lsp-symbols

列出文件中的所有符号。

bunx @plaited/development-skills lsp-symbols <file>

示例：

bunx @plaited/development-skills lsp-symbols src/utils/parser.ts

lsp-references

查找符号的所有引用。

bunx @plaited/development-skills lsp-refs <file> <line> <char>

示例：

bunx @plaited/development-skills lsp-refs src/utils/parser.ts 42 10

lsp-find

在工作区中搜索符号。

bunx @plaited/development-skills lsp-find <query> [context-file]

参数：

• query：符号名称或部分名称
• context-file：可选文件，用于打开项目上下文

示例：

bunx @plaited/development-skills lsp-find parseConfig
bunx @plaited/development-skills lsp-find validateInput src/lib/validator.ts

批处理脚本

lsp-analyze

在单个会话中执行多项分析，提高效率。

bunx @plaited/development-skills lsp-analyze <file> [options]

选项：

• --symbols, -s：列出所有符号
• --exports, -e：仅列出导出的符号
• --hover <line:char>：获取类型信息（可重复）
• --refs <line:char>：查找引用（可重复）
• --all：运行符号和导出分析

示例：

# Get file overview
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --all

# Check multiple positions
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --hover 50:10 --hover 75:5

# Before refactoring: find all references
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --refs 42:10

常见工作流

理解文件

# 1. Get exports overview
bunx @plaited/development-skills lsp-analyze path/to/file.ts --exports

# 2. For specific type info, hover on interesting symbols
bunx @plaited/development-skills lsp-hover path/to/file.ts <line> <char>

修改导出内容前

# 1. Find all references first
bunx @plaited/development-skills lsp-refs path/to/file.ts <line> <char>

# 2. Check what depends on it
# Review the output to understand impact

查找模式

# Search for similar implementations
bunx @plaited/development-skills lsp-find handleRequest
bunx @plaited/development-skills lsp-find parseConfig

实现前验证

# Before writing code that uses an API, verify its signature
bunx @plaited/development-skills lsp-hover path/to/api.ts <line> <char>

输出格式

所有脚本都将 JSON 输出到 stdout。错误信息输出到 stderr。

Hover 输出：

{
  "contents": {
    "kind": "markdown",
    "value": "```typescript\nconst parseConfig: (options: Options) => Config\n```"
  },
  "range": { "start": {...}, "end": {...} }
}

符号输出：

[
  {
    "name": "symbolName",
    "kind": 13,
    "range": { "start": {...}, "end": {...} }
  }
]

分析输出：

{
  "file": "path/to/file.ts",
  "exports": [
    { "name": "exportName", "kind": "Constant", "line": 139 }
  ]
}

性能

每次脚本调用都会：

1. 启动 TypeScript Language Server（约 300-500ms）
2. 初始化 LSP 连接
3. 打开文档
4. 执行查询
5. 关闭文档并停止

对于同一文件上的多个查询，请使用 lsp-analyze，在单个会话中批量执行操作。

相关技能

• code-documentation：用于文档的 TSDoc 标准