checking-files-with-lsp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Checking Files With LSP

使用LSP检查文件

Overview

概述

When you need to validate, check, or understand a file's structure or code quality, use language servers and linters to do it systematically. This skill provides a reliable workflow: detect the file type, search mise for available LSP/linter tools, intelligently choose one, and run the check.

Core principle: Let the appropriate tool for the language do the validation work, not manual inspection. Automate tool discovery and selection.

当你需要验证、检查或理解文件的结构或代码质量时，请使用语言服务器（Language Server）和代码检查工具（linter）来系统地完成这项工作。本技能提供了一套可靠的工作流程：检测文件类型，在mise中搜索可用的LSP/代码检查工具，智能选择合适的工具，然后执行检查。

核心原则：让对应语言的专用工具来执行验证工作，而非人工检查。自动完成工具的发现与选择。

When to Use

使用场景

Use this skill when:

Checking code files for syntax errors, type issues, or style problems
Validating configuration files (YAML, TOML, JSON, KDL, etc.)
Understanding code structure or quality of unfamiliar files
Verifying Markdown files for formatting/link issues
Need to quickly understand what problems exist in a file

Don't use when:

Just reading a file to understand its contents (no validation needed)
Running full test suites (that's testing, not validation)
Analyzing code behavior (that's debugging, not validation)

在以下场景使用本技能：

检查代码文件的语法错误、类型问题或风格问题
验证配置文件（YAML、TOML、JSON、KDL等）
理解陌生文件的代码结构或质量
验证Markdown文件的格式/链接问题
需要快速了解文件中存在的问题

请勿在以下场景使用：

仅读取文件以理解其内容（无需验证）
运行完整的测试套件（这属于测试范畴，而非验证）
分析代码行为（这属于调试范畴，而非验证）

The Workflow

工作流程

Step 1: Detect File Type

步骤1：检测文件类型

Determine the language/type from file extension:

.lua     → lua
.ts/.tsx → typescript
.py      → python
.go      → go
.rs      → rust
.md      → markdown
.json    → json
.yaml    → yaml
.toml    → toml
.kdl     → kdl

If extension is unclear or missing, inspect file shebang or content patterns.

通过文件扩展名判断语言/类型：

.lua     → lua
.ts/.tsx → typescript
.py      → python
.go      → go
.rs      → rust
.md      → markdown
.json    → json
.yaml    → yaml
.toml    → toml
.kdl     → kdl

如果扩展名不明确或缺失，检查文件的shebang（脚本头）或内容模式。

Step 2: Search Mise for LSP/Linters

步骤2：在Mise中搜索LSP/代码检查工具

Run:

mise search <filetype>

This returns all available language servers, linters, and formatters for that language.

Example outputs:

mise search lua
lua-language-server    (most popular)
stylua                 (formatter)

mise search python
pyright
pylance
python-language-server
black
ruff

执行命令：

mise search <filetype>

该命令会返回该语言所有可用的语言服务器、代码检查工具和格式化工具。

示例输出：

mise search lua
lua-language-server    (最受欢迎)
stylua                 (格式化工具)

mise search python
pyright
pylance
python-language-server
black
ruff

Step 3: Make Smart Selection

步骤3：智能选择工具

Prioritize by tool type: Language Server (LSP) > Linter > Formatter

LSPs provide the most comprehensive validation. Linters catch style/quality issues. Formatters are secondary for validation purposes.

If ONE obvious choice exists:

Auto-select it (e.g., only lua-language-server for Lua)
Verify installation:
```
mise list | grep <tool>
```
(if not listed, install it)
Install:
```
mise install lua-language-server
```
Run it on the file

If MULTIPLE choices exist:

Filter by priority: Show LSPs first, linters second, skip formatters
Rank by popularity: Most-used tools first (measured by GitHub stars, then npm/PyPI downloads as tiebreaker)
Show ranked list to user (with tool type and brief descriptions)
Let user pick by number/letter
Verify and install selected tool
Run it on the file

If NO tools found:

Inform user explicitly: "No LSP/linter available in mise for [filetype]"
Suggest alternatives in order:
1. Check online package managers (npm, PyPI, cargo, etc.) if not in mise
2. Look for generic validators (jq for JSON, yamllint for YAML, etc.)
3. Basic syntax checking (built-in language checkers)
4. Manual validation with structured guidance
Offer: "Would you like me to help install from another source?"

按工具类型优先级排序： 语言服务器（LSP）> 代码检查工具（Linter）> 格式化工具（Formatter）

LSP提供最全面的验证功能，代码检查工具捕获风格/质量问题，格式化工具在验证场景中属于次要选择。

如果有明确的唯一选择：

自动选择该工具（例如，Lua语言仅选择lua-language-server）
验证安装情况：
```
mise list | grep <tool>
```
（如果未列出，则进行安装）
安装命令：
```
mise install lua-language-server
```
在目标文件上运行该工具

如果有多个选择：

按优先级筛选：先显示LSP，再显示代码检查工具，跳过格式化工具
按流行度排序：优先选择使用最多的工具（以GitHub星标数为衡量标准，若星标数相同则以npm/PyPI下载量为决胜条件）
向用户展示排序后的列表（包含工具类型和简要说明）
让用户通过编号/字母选择
验证并安装所选工具
在目标文件上运行该工具

如果未找到任何工具：

明确告知用户： "在mise中未找到适用于[filetype]的LSP/代码检查工具"
按顺序推荐替代方案：
1. 检查在线包管理器（npm、PyPI、cargo等），如果该工具不在mise中
2. 寻找通用验证工具（如用于JSON的jq，用于YAML的yamllint等）
3. 基础语法检查（语言内置的语法检查器）
4. 提供结构化指导的人工验证
询问用户："是否需要我协助从其他来源安装工具？"

Step 4: Run Validation

步骤4：执行验证

Execute the selected tool against the file and return results: errors, warnings, style issues, and suggestions.

在目标文件上运行所选工具，并返回结果：错误、警告、风格问题和改进建议。

Quick Reference

快速参考

Task	Action
Detect file type	Use file extension as primary signal
Find tools	`mise search <filetype>`
Install obvious choice	`mise install <tool>` (auto-selected)
Show options	Present ranked list for user choice
Run validation	Execute tool with file path

任务	操作
检测文件类型	以文件扩展名作为主要判断依据
查找工具	`mise search <filetype>`
安装明确选择的工具	`mise install <tool>` （自动选择）
展示可选工具	向用户展示排序后的列表
执行验证	使用文件路径执行工具

Common Mistakes

常见错误

Mistake: Skip file type detection

Wrong: "It's a code file, any language server works"
Right: File type determines which LSP applies. Wrong LSP = wrong errors

Mistake: Pick random LSP when multiple exist

Wrong: "I'll just try the first one" or "They're all the same"
Right: Different LSPs check different aspects. Use ranking: most popular > less common. Filter by type: LSP > Linter > Formatter
No exceptions: You must present options to user when multiple exist, not guess

Mistake: Assume LSP is installed

Wrong: "Let me just run lua-language-server..."
Right: Always verify with
```
mise search
```
first. Check
```
mise list
```
before installing. Install if needed

Mistake: Don't check system requirements

Wrong: "Install the LSP and it'll work"
Right: Some LSPs need runtime dependencies (Python, Node, etc.). Test LSP runs before reporting results

Mistake: When LSP unavailable, give up

Wrong: "No tool for this language, can't validate"
Right: Explore alternatives in order: online package managers → generic validators → syntax checking → manual guidance

Mistake: Mixing tool categories

Wrong: Showing formatters and linters equally for validation
Right: Prioritize LSP > Linter > Formatter. Use tool type as first filter

错误：跳过文件类型检测

错误做法："这是一个代码文件，任何语言服务器都能用"
正确做法：文件类型决定了适用的LSP。错误的LSP会导致错误的检测结果

错误：存在多个LSP时随机选择

错误做法："我就试试第一个"或"它们都一样"
正确做法：不同的LSP检查的内容不同。按排序规则选择：最受欢迎 > 较不常用。按类型筛选：LSP > 代码检查工具 > 格式化工具
无例外情况： 当存在多个选项时，必须向用户展示选项，而非自行猜测

错误：假设LSP已安装

错误做法："我直接运行lua-language-server就行..."
正确做法：始终先通过
```
mise search
```
确认。在安装前检查
```
mise list
```
。若未安装则进行安装

错误：不检查系统要求

错误做法："安装LSP后就能用了"
正确做法：部分LSP需要运行时依赖（如Python、Node等）。在报告结果前先测试LSP能否正常运行

错误：LSP不可用时直接放弃

错误做法："该语言没有可用工具，无法验证"
正确做法：按顺序探索替代方案：在线包管理器 → 通用验证工具 → 语法检查 → 人工指导

错误：混淆工具类别

错误做法：在验证场景中同等展示格式化工具和代码检查工具
正确做法：按优先级排序：LSP > 代码检查工具 > 格式化工具。将工具类型作为首要筛选条件

Fallback Validation Options

备用验证方案

When LSP/linter not available in mise:

Check online package managers (npm, PyPI, cargo, etc.) if not in mise
Look for generic validators - JSON validators, YAML checkers work across projects
Basic syntax checking - Some languages have built-in syntax checkers
Manual validation - Provide structured review guidance
Suggest installation - "Would you like me to help install from another source?"

当mise中没有可用的LSP/代码检查工具时：

检查在线包管理器（npm、PyPI、cargo等），如果该工具不在mise中
寻找通用验证工具——JSON验证器、YAML检查器可跨项目使用
基础语法检查——部分语言内置了语法检查器
人工验证——提供结构化的审核指导
建议安装——"是否需要我协助从其他来源安装工具？"

Implementation Steps

实施步骤

When helping a user check a file:

Ask or determine: "What file are we checking?"
Detect the file type from extension
Run:
```
mise search <filetype>
```
Decide: obvious choice or show ranked options?
Verify installation:
```
mise list | grep <tool>
```
(check if already installed)
Install if needed:
```
mise install <selected-tool>
```
Test tool runs: Verify LSP/linter executes without errors
Run: Execute tool against file with appropriate flags
Report: Show user the validation results
Offer next steps: "Fix these issues?" or "Run checks again?"

当帮助用户检查文件时：

询问或确认："我们要检查哪个文件？"
通过扩展名检测文件类型
执行命令：
```
mise search <filetype>
```
判断：是有明确选择还是需要展示排序后的选项？
验证安装情况：
```
mise list | grep <tool>
```
（检查是否已安装）
若需要则安装：
```
mise install <selected-tool>
```
测试工具运行：验证LSP/代码检查工具能否正常执行
执行：使用合适的参数在目标文件上运行工具
报告：向用户展示验证结果
提供后续选项："需要修复这些问题吗？"或"再次运行检查？"

Troubleshooting

故障排除

Tool installs but won't run:

Some LSPs need runtime dependencies (Python for some tools, Node for others)
Check LSP documentation for runtime requirements
Example:
```
python-language-server
```
needs Python installed
Verify with:
```
mise exec <tool> -- <tool> --version
```

Mise search returns no results:

Language might not be in mise database
Try alternative package managers: npm (JavaScript), PyPI (Python), cargo (Rust)
Or use generic validators: jq (JSON), yamllint (YAML)

LSP finds errors but tool isn't right for the job:

Wrong tool selected (formatter instead of LSP)
Go back to Step 3, filter by type priority (LSP > Linter)
Ask user to pick a different option from the list

File has unusual extension:

Use file content inspection (shebang, headers) as fallback
Example: Executable shell scripts often lack
```
.sh
```
extension
Check content to confirm type before searching mise

工具已安装但无法运行：

部分LSP需要运行时依赖（如部分工具需要Python，其他需要Node等）
查看LSP的文档以确认运行时要求
示例：
```
python-language-server
```
需要安装Python
使用命令验证：
```
mise exec <tool> -- <tool> --version
```

Mise搜索无结果：

该语言可能不在mise的数据库中
尝试使用其他包管理器：npm（JavaScript）、PyPI（Python）、cargo（Rust）
或使用通用验证工具：jq（JSON）、yamllint（YAML）

LSP检测到错误但工具不适合当前任务：

选择了错误的工具（比如用了格式化工具而非LSP）
返回步骤3，按类型优先级筛选（LSP > 代码检查工具）
让用户从列表中选择其他选项

文件扩展名不常见：

将文件内容检查（shebang、文件头）作为备用方案
示例：可执行的Shell脚本通常没有
```
.sh
```
扩展名
在搜索mise前先检查内容以确认文件类型

Real-World Impact

实际价值

Fast validation: No manual code review for common issues
Consistent checking: Same tool, same criteria, every time
Discovery: Find issues you'd miss with manual inspection
Automation: Can be integrated into workflows, CI/CD, pre-commit hooks
Language agnostic: Same pattern works for any language with an LSP available

快速验证：无需人工检查常见问题
检查一致性：每次使用相同工具、相同标准
问题发现：找出人工检查容易遗漏的问题
自动化：可集成到工作流、CI/CD、提交前钩子（pre-commit hooks）中
语言无关：只要有可用的LSP，这套流程适用于任何语言