checking-files-with-lsp

使用 LSP 检查文件

概述

需要验证、检查或了解文件的结构或代码质量时，请使用语言服务器和代码检查器，以系统化地完成任务。本技能提供了一套可靠的工作流：检测文件类型、在 mise 中搜索可用的 LSP/代码检查工具、智能选择工具并运行检查。

核心原则： 让适用于该语言的工具完成验证工作，而不是手动检查。自动化工具的发现与选择过程。

适用场景

在以下情况下使用本技能：

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

在以下情况下不要使用：

• 只是阅读文件以了解其内容（无需验证）
• 运行完整测试套件（这是测试，而不是验证）
• 分析代码行为（这是调试，而不是验证）

工作流

步骤 1：检测文件类型

根据文件扩展名确定语言/类型：

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

如果扩展名不明确或缺失，请检查文件的 shebang 或内容特征。

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

运行：mise search <filetype>

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

示例输出：

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

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

步骤 3：智能选择

按工具类型优先选择： 语言服务器（LSP）> 代码检查器 > 格式化工具

LSP 提供最全面的验证。代码检查器可发现风格/质量问题。对于验证而言，格式化工具优先级较低。

如果只有一个明显的选择：

• 自动选择（例如，Lua 只有 lua-language-server）
• 确认是否已安装：mise list | grep <tool>（如果未列出，则安装）
• 安装：mise install lua-language-server
• 对文件运行该工具

如果有多个选择：

• 按优先级筛选：先显示 LSP，再显示代码检查器，跳过格式化工具
• 按受欢迎程度排序：最常用的工具排在前面（依据 GitHub 星标数量；如需进一步区分，则参考 npm/PyPI 下载量）
• 向用户显示排序后的列表（注明工具类型并简要说明）
• 让用户按编号/字母选择
• 确认并安装所选工具
• 对文件运行该工具

如果没有找到工具：

• 明确告知用户：“mise 中没有适用于 [filetype] 的 LSP/代码检查器”
• 按顺序提供替代方案：
  1. 如果 mise 中没有，可检查在线包管理器（npm、PyPI、cargo 等）
  2. 查找通用验证工具（用于 JSON 的 jq、用于 YAML 的 yamllint 等）
  3. 进行基本语法检查（使用语言内置检查器）
  4. 在结构化指导下手动验证
• 询问：“需要我帮你从其他来源安装吗？”

步骤 4：运行验证

对文件执行所选工具，并返回结果：错误、警告、风格问题和建议。

快速参考

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

常见错误

错误：跳过文件类型检测

• 错误做法：“这是代码文件，任何语言服务器都能用”
• 正确做法：文件类型决定适用哪种 LSP。LSP 不匹配 = 错误提示不准确

错误：有多个 LSP 时随便选一个

• 错误做法：“我就试第一个吧”或“它们都一样”
• 正确做法：不同的 LSP 会检查不同方面。按受欢迎程度排序：最受欢迎的 > 不太常见的。按类型筛选：LSP > 代码检查工具 > 格式化工具
• 没有例外： 有多个选项时，必须向用户列出选项，不能自行猜测

错误：假设已安装 LSP

• 错误做法：“我直接运行 lua-language-server……”
• 正确做法：始终先用 mise search 确认。安装前检查 mise list。如有需要则安装

错误：不检查系统要求

• 错误做法：“安装 LSP 就能用”
• 正确做法：有些 LSP 需要运行时依赖（Python、Node 等）。报告结果前，先测试 LSP 能否运行

错误：LSP 不可用时就放弃

• 错误做法：“没有适用于这种语言的工具，无法验证”
• 正确做法：按顺序探索替代方案：在线包管理器 → 通用验证工具 → 语法检查 → 手动指导

错误：混淆工具类别

• 错误做法：验证时把格式化工具和代码检查工具同等对待
• 正确做法：优先级为 LSP > 代码检查工具 > 格式化工具。首先按工具类型筛选

备用验证选项

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

1. 如果 mise 中没有，检查在线包管理器（npm、PyPI、cargo 等）
2. 查找通用验证工具——JSON 验证器、YAML 检查器可用于各种项目
3. 基本语法检查——有些语言内置了语法检查器
4. 手动验证——提供结构化的审查指导
5. 建议安装——“你希望我帮你从其他来源安装吗？”

实施步骤

帮助用户检查文件时：

1. 询问或确定：“我们要检查什么文件？”
2. 根据扩展名检测文件类型
3. 运行：mise search <filetype>
4. 判断：选项是否显而易见，还是需要展示排序后的选项？
5. 确认是否已安装：mise list | grep <tool>（检查是否已安装）
6. 如有需要则安装：mise install <selected-tool>
7. 测试工具能否运行：确认 LSP/代码检查工具运行时没有错误
8. 运行：使用适当的标志对文件执行工具
9. 报告：向用户展示验证结果
10. 提供后续步骤：“要修复这些问题吗？”或“要重新运行检查吗？”

故障排除

工具安装成功但无法运行：

• 有些 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 前检查文件内容以确认类型

实际影响

• 快速验证：常见问题无需手动代码审查
• 检查一致：每次都使用相同的工具和标准
• 发现问题：找出手动检查时会遗漏的问题
• 自动化：可集成到工作流、CI/CD、提交前钩子中
• 语言无关：只要有可用的 LSP，同一模式就适用于任何语言