第37篇：LSP 诊断——代码语义检查

这篇讲的是：Hermes Agent 如何像一位“随队医生”一样，在你改完代码后立刻帮你查出隐藏的“内伤”——也就是语法之外的逻辑错误、类型错误和拼写错误。

为什么需要“语义检查”？

想象一下：你写了一段中文，错别字和标点错误（语法）很容易发现，但“把苹果放进冰箱”和“把冰箱放进苹果”这种逻辑问题，光靠眼睛可看不出来。代码也一样——语法检查只能发现“句子通不通”，而语义检查能发现“意思对不对”。

Hermes 内置了 20 多种语言服务器（比如 Python 的 Pyright、Go 的 gopls、Rust 的 rust-analyzer），它们像一群专业审稿人，在后台默默盯着你每次修改，然后告诉你：“你这里少了个定义”“那里类型对不上”。

第1步：确认你的项目在 Git 仓库里

LSP 只在 Git 工作区内生效。如果你的代码不在 Git 仓库里，这个功能就自动休眠——就像医生只在医院上班，不会跑到你家客厅来查房。

cd 你的项目目录
git init   # 如果还没初始化仓库

第2步：查看哪些语言已“配好医生”

运行这条命令，看看哪些语言的服务器已就绪：

hermes lsp status

它会列出每种语言的安装状态。没装的就用 hermes lsp install <语言id> 补上，比如：

hermes lsp install python   # 安装 Pyright
hermes lsp install go       # 安装 gopls

第3步：正常写代码，剩下的交给 Hermes

每次你用 write_file 或 patch 保存文件时，Hermes 会自动：

1. 先做语法检查（微秒级，几乎不耗时）
2. 再请语言服务器做语义检查（可能需要几秒）
3. 只报告“这次修改新引入的问题”，老问题不重复打扰你

你会在返回结果里看到类似这样的信息：

{
  "lint": {"status": "ok"},
  "lsp_diagnostics": "ERROR [42:5] Cannot find name 'foo' (Pyright)"
}

lint 是语法通道，lsp_diagnostics 是语义通道——语法没问题但语义有错时，你会看到 lint: ok 加上一堆诊断信息。

第4步：按需调整配置（可选）

默认配置对大多数人都够用。如果你想让 Python 检查更严格，可以在 config.yaml 里这样设置：

lsp:
  servers:
    pyright:
      initialization_options:
        python:
          analysis:
            typeCheckingMode: "strict"

改完配置记得重启服务：hermes lsp restart

常见问题

• 没装服务器会怎样？ 自动降级为纯语法检查，不会报错。
• 服务器启动慢？ 首次启动需要 1-10 秒，之后会常驻后台。
• PowerShell 用户？ 它比较特殊，需要手动下载模块包并设置路径，详见文档。

小结

LSP 诊断就像给代码加了一道“语义安检门”，让你在提交代码前就发现隐藏的“内伤”。语法检查保底，语义检查提升质量，两者配合，写代码更安心。

下篇预告：第38篇我们将聊聊 Hermes 的“记忆管理”——它如何记住你的项目偏好，越用越顺手。敬请期待！