Giao thức máy chủ ngôn ngữ (LSP)

Hermes chạy các máy chủ ngôn ngữ đầy đủ - pyright, gopls, máy phân tích rỉ sét, TypeScript-ngôn ngữ-server, clangd và ~20 thứ khác - làm nền các quy trình con và cung cấp chẩn đoán ngữ nghĩa của chúng vào phần ghi sau kiểm tra lint được sử dụng bởi write_file và `patch

. Khi đại lý chỉnh sửa một tập tin, nó sẽ thấy chính xác các lỗi mà bản chỉnh sửa đã đưa ra — không chỉ lỗi cú pháp, nhưng lỗi gõ, tên không xác định, thiếu nội dung nhập, và các vấn đề ngữ nghĩa trên toàn dự án mà máy chủ ngôn ngữ phát hiện.

Đây là kiến trúc tương tự mà các tác nhân mã hóa hàng đầu sử dụng. Hermes vận chuyển nó khép kín: không cần máy chủ soạn thảo, không cần plugin để cài đặt, không có daemon riêng để quản lý.

Khi LSP chạy

LSP được kiểm soát về phát hiện không gian làm việc git. Khi đại lý đang làm việc thư mục (hoặc tệp đang được chỉnh sửa) nằm trong kho git, LSP chạy ngược lại không gian làm việc đó. Khi không có trong repo git, LSP không hoạt động - hữu ích cho các cổng nhắn tin trong đó cwd là thư mục chính của người dùng và không có dự án nào để chẩn đoán.

Việc kiểm tra được phân lớp: kiểm tra cú pháp trong quá trình trước tiên (micro giây), sau đó chẩn đoán LSP thứ hai khi cú pháp rõ ràng. Bị bong tróc hoặc bị thiếu máy chủ ngôn ngữ không bao giờ có thể ngắt quá trình ghi - mọi đường dẫn lỗi LSP âm thầm quay trở lại kết quả chỉ có cú pháp.

Cụ thể, trên mỗi write_file hoặc patch thành công:

Hermes nắm bắt cơ sở chẩn đoán hiện tại cho tệp.
Thực hiện việc viết.
Truy vấn lại máy chủ ngôn ngữ, lọc ra các chẩn đoán đã có đã có trong đường cơ sở và chỉ hiển thị những cái mới.

Tác nhân thấy đầu ra như:

` { "bytes_written": 42, "dirs_created": false, "lint": {"status": "ok", "output": ""}, "lsp_diagnostics": "LSP diagnostics introduced by this edit:\n<diagnostics file="/path/to/foo.py"\nERROR [42:5] Cannot find name 'foo' [reportUndefinedVariable] (Pyright)\nERROR [50:1] Argument of type "str" is not assignable to "int" [reportArgumentType] (Pyright)\n</diagnostics" }

``Trường lint mang kết quả kiểm tra cú pháp (micro giây phân tích trong quá trình thông qua ast.parse

, `JSON.loads

, v.v.); cái Trường lsp_diagnostics mang chẩn đoán ngữ nghĩa từ máy chủ ngôn ngữ thực. Hai kênh, tín hiệu độc lập — tác nhân nhìn thấy một tệp cú pháp rõ ràng có các vấn đề về ngữ nghĩa như

`lint: ok

` plus a populated

`lsp_diagnostics

` .

Ngôn ngữ được hỗ trợ

Ngôn ngữ	Máy chủ	Tự động cài đặt
Python

pyright-langserver ` | npm | | TypeScript / JavaScript / JSX / TSX |

TypeScript-language-server ` | npm | | Vue |

@vue/language-server ` | npm | | Mảnh dẻ |

svelte-language-server ` | npm | | Astro |

@astrojs/language-server ` | npm | | Đi |

gopls | go install ` | | rỉ sét |

Rust-analyzer ` | hướng dẫn sử dụng (rỉ sét) | | C/C++ |

clangd ` | hướng dẫn sử dụng (LLVM) | | Bash / Zsh |

bash-language-server ` | npm | | YAML |

YAML-language-server ` | npm | | Lua |

lua-language-server ` | hướng dẫn sử dụng (bản phát hành GitHub) | | PHP |

intelephense ` | npm | | OCaml |

ocaml-lsp ` | hướng dẫn sử dụng (opam) | | Dockerfile |

Dockerfile-language-server-nodejs ` | npm | | địa hình |

terraform-ls ` | hướng dẫn sử dụng | | Phi tiêu |

dart language-server ` | hướng dẫn sử dụng (SDK phi tiêu) | | Haskell |

haskell-language-server ` | hướng dẫn sử dụng (ghcup) | | Julia |

julia

LanguageServer.jl | hướng dẫn sử dụng | | Clojure |

clojure-lsp ` | hướng dẫn sử dụng | | Nix |

nixd ` | hướng dẫn sử dụng | | Zig |

zls ` | hướng dẫn sử dụng | | Tia sáng |

gleam lsp ` | hướng dẫn sử dụng (cài đặt tia sáng) | | Thuốc tiên |

elixir-ls ` | hướng dẫn sử dụng | | Prisma |

prisma language-server ` | hướng dẫn sử dụng | | Kotlin |

kotlin-language-server ` | hướng dẫn sử dụng | | Java |

jdTLS ` | hướng dẫn sử dụng |

Đối với các mục "thủ công", hãy cài đặt máy chủ thông qua bất kỳ chuỗi công cụ nào người quản lý hiểu ngôn ngữ đó (Rustup, ghcup, opam, brew, …). Hermes tự động phát hiện mã nhị phân trên PATH hoặc trong

<Hermes_HOME/lsp/bin/

Một số máy chủ được cài đặt cùng với sự phụ thuộc ngang hàng mà npm sẽ không tự động kéo. Trường hợp hiện tại là `TypeScript-language-server

, yêu cầu SDK TypeScript có thể nhập từ cùng một Cây `node_modules

Hermes cài đặt cả hai gói cùng nhau khi bạn trước tiên hãy chạy Hermes lsp install TypeScript hoặc tự động cài đặt kích hoạt sử dụng.`##CLI

` Hermes lsp status # service state + per-server install status Hermes lsp list # registry, optionally --installed-only Hermes lsp install <id # eagerly install one server Hermes lsp install-all # try every server with a known recipe Hermes lsp restart # tear down running CLIents Hermes lsp which <id # print resolved binary path

` là điểm khởi đầu tốt nhất — nó cho thấy
các ngôn ngữ ngày nay sẽ nhận được chẩn đoán ngữ nghĩa và cần có
cài đặt nhị phân.

## Cấu hình

Các giá trị mặc định hoạt động cho các thiết lập thông thường; không có gì để đặt nếu nhị phân
đang ở trên PATH.

``` yaml

# config.yaml
lsp:
  # Master toggle. Disabling skips the entire subsystem — no servers
  # spawn, no background event loop runs.
  enabled: true

# How long to wait for diagnostics after each write.
  wait_mode: document      # "document" or "full"
  wait_timeout: 5.0

# How to handle missing server binaries.
  #   auto    — install via npm/pip/go install into &lt;Hermes_HOME/lsp/bin
  #   manual  — only use binaries already on PATH
  install_strategy: auto

# Per-server overrides (all optional).
  servers:
    pyright:
      disabled: false
      command: ["/abs/path/to/pyright-langserver", "--stdio"]
      env: &#123; PYRIGHT_LOG_LEVEL: "info" &#125;
      initialization_options:
        Python:
          analysis:
            typeCheckingMode: "strict"
    TypeScript:
      disabled: true       # skip TS even when its extensions match

`

### Khóa trên mỗi máy chủ* 
`disabled: true
` — hoàn toàn bỏ qua máy chủ này ngay cả khi nó
  phần mở rộng khớp với một tập tin.
* 
`command: [bin, ...args]

 - ghim đường dẫn nhị phân tùy chỉnh. Đường vòng
  tự động cài đặt.
* 
`env: \&#123;KEY: value&#125;

 - các biến env bổ sung được chuyển vào quy trình sinh ra.
* 
`initialization_options: \&#123;...&#125;

 - được sáp nhập vào LSP
  Tải trọng 
`initializationOptions
` được gửi trong 
`initialize

  bắt tay. Máy chủ cụ thể; tham khảo tài liệu của máy chủ ngôn ngữ.

## Vị trí lắp đặt

Khi 
`install_strategy: auto

, Hermes cài đặt các tệp nhị phân vào

&lt;Hermes_HOME/lsp/bin/

. Các gói npm được đưa vào

&lt;Hermes_HOME/lsp/node_modules/
` với các liên kết tượng trưng bin tăng một cấp.
Các tệp nhị phân của Go đến từ 
`go install
` với 
`GOBIN
` được chỉ vào
đạo diễn dàn dựng

Không có gì được cài đặt vào 

/usr/local/

, 

~/.local/
` hoặc bất kỳ thứ gì khác
vị trí được chia sẻ - thư mục dàn dựng hoàn toàn thuộc sở hữu của Hermes và được
bị xóa khi bạn đặt lại hồ sơ.

## Đặc tính hiệu suất

Máy chủ LSP **sinh ra lười biếng** trong lần sử dụng đầu tiên. Chỉnh sửa tệp Python
trong một dự án chưa từng thấy lưu lượng truy cập 

.py
` xuất hiện đúng; cái
sinh sản mất 1-3 giây đối với hầu hết các máy chủ (máy phân tích rỉ sét có thể mất hơn 10 giây
trong một dự án nguội). Các chỉnh sửa tiếp theo trong cùng một không gian làm việc được sử dụng lại
máy chủ đang chạy.

Lớp LSP thêm một vài mili giây để ghi sạch khi không
chẩn đoán được phát ra. Khi chẩn đoán được phát ra, thời gian chờ
ngân sách là 
`wait_timeout
` giây — thông thường máy chủ sẽ phản hồi trong
hàng chục mili giây đối với pyright/tsserver và một vài giây đối với
lập chỉ mục giữa máy phân tích rỉ sét.

Các máy chủ được duy trì hoạt động trong suốt quá trình của Hermes. có
không có thời gian chờ nhàn rỗi — chi phí khởi động lại chỉ mục của máy chủ
mỗi lần viết sẽ cao hơn nhiều so với việc giữ daemon.

## Vô hiệu hóa

Đặt 
`lsp.enabled: false
` trong 
`config.yaml
` để tắt toàn bộ
hệ thống con. Kiểm tra sau khi viết quay trở lại cú pháp trong quá trình
kiểm tra (
`ast.parse
` cho Python, 
`JSON.loads
` cho JSON, v.v.)
tàu không thay đổi so với các phiên bản trước đó.

Để tắt một ngôn ngữ mà không tắt toàn bộ lớp:

``` yaml
lsp:
  servers:
    Rust-analyzer:
      disabled: true

`

## Khắc phục sự cố`**
`Hermes lsp status
` hiển thị máy chủ là "thiếu"**

Tệp nhị phân không có trên PATH và không có trong 

&lt;Hermes_HOME/lsp/bin/

. Chạy
`Hermes lsp install &lt;server_id
` để thử cài đặt tự động hoặc
cài đặt nhị phân theo cách thủ công thông qua chuỗi công cụ thông thường của ngôn ngữ.

**Phần 
`Backend warnings
` trong 
`Hermes lsp status

`
**

Một số máy chủ gửi dưới dạng các trình bao bọc mỏng xung quanh CLI bên ngoài để thực tế
chẩn đoán - chúng sinh sản sạch sẽ và chấp nhận yêu cầu nhưng không bao giờ phát ra
lỗi khi thiếu nhị phân sidecar. Trường hợp phổ biến nhất là
`bash-language-server

, ủy quyền chẩn đoán cho 
`shellcheck

.
Khi 
`Hermes lsp status
` hiển thị phần 
`Backend warnings

, hãy cài đặt
công cụ được đặt tên thông qua trình quản lý gói hệ điều hành của bạn:

`
apt install shellcheck      # Debian / Ubuntu
brew install shellcheck     # macOS
scoop install shellcheck    # Windows

`
``Cảnh báo tương tự được ghi lại một lần tại thời điểm xuất hiện của máy chủ trong

~/.Hermes/logs/agent.log

.

**Máy chủ khởi động nhưng không bao giờ trả về kết quả chẩn đoán**

Kiểm tra 

~/.Hermes/logs/agent.log
` để biết các mục nhập 

[agent.lsp.CLIent]
` —
cả stderr từ máy chủ ngôn ngữ và lỗi giao thức đều xảy ra
ở đó. Một số máy chủ (đặc biệt là máy phân tích rỉ sét) cần hoàn thành quá trình
chỉ mục toàn dự án trước khi chúng đưa ra chẩn đoán cho mỗi tệp; cái đầu tiên
chỉnh sửa sau khi khởi động máy chủ có thể hoàn tất mà không có chẩn đoán, với
các chỉnh sửa tiếp theo sẽ chọn chúng.

**Máy chủ bị lỗi**

Một máy chủ bị lỗi sẽ được thêm vào tập hợp bị hỏng và sẽ không được thử lại trong
phần còn lại của phiên. Chạy 
`Hermes lsp restart
` để xóa bộ;
lần chỉnh sửa tiếp theo sẽ xuất hiện lại.

**Chỉnh sửa tệp bên ngoài bất kỳ repo git nào**

Theo thiết kế, LSP chỉ chạy bên trong kho git. Nếu dự án không
chưa được khởi tạo, hãy chạy 
`git init
` để bật chẩn đoán LSP. Nếu không thì
Áp dụng dự phòng chỉ theo cú pháp trong quá trình.

Khi LSP chạy​

Ngôn ngữ được hỗ trợ​

Khi LSP chạy

Ngôn ngữ được hỗ trợ