Máy chủ Intlayer LSP

Máy chủ Ngôn ngữ Intlayer (LSP) là một triển khai của Giao thức Máy chủ Ngôn ngữ (LSP) nhằm nâng cao IDE của bạn bằng trí thông minh nhận biết cấu trúc Intlayer. Hiện tại, máy chủ cung cấp tính năng Đi tới Định nghĩa (Go to Definition) cho các lệnh gọi khóa từ điển, cho phép bạn nhảy trực tiếp từ useIntlayer("my-key") trong thành phần của mình sang tệp .content.ts khai báo khóa đó.

Tại sao nên sử dụng LSP?

Khi bạn sử dụng Intlayer, kết nối giữa một lệnh gọi như useIntlayer("homepage") và khai báo của nó trong src/homepage.content.ts là ẩn định. Nếu không có công cụ, bạn phải tìm kiếm tệp theo cách thủ công. LSP làm cho liên kết đó trở nên rõ ràng:

Nhận thức của tác nhân AI

Các tác nhân lập trình AI (Cursor, Windsurf, GitHub Copilot, Claude Code, Codex) dựa vào máy chủ ngôn ngữ để giải quyết các ký hiệu và hiểu mối quan hệ chéo giữa các tệp. Khi Intlayer LSP đang chạy, các tác nhân có thể đi theo lệnh gọi useIntlayer("key") trở lại khai báo của nó, mang lại cho chúng ngữ cảnh chính xác về các khóa nội dung có sẵn, cấu trúc của từng từ điển và tệp nào cần đọc hoặc chỉnh sửa.

Đi tới Định nghĩa

Đặt con trỏ của bạn lên bất kỳ chuỗi khóa từ điển nào bên trong lệnh gọi getter được hỗ trợ và nhấn F12 (hoặc Cmd/Ctrl+Click). Trình soạn thảo sẽ mở tệp khai báo nội dung và đặt con trỏ vào dòng key:.

Hỗ trợ từ điển được gộp

Một khóa có thể được chia ra ở nhiều tệp nội dung khác nhau (Intlayer sẽ gộp chúng lại). Máy chủ trả về một vị trí (Location) trên mỗi tệp nguồn để bạn có thể điều hướng đến từng khai báo.

Hoạt động ở mọi nơi

Hỗ trợ tất cả các gói *-intlayer (next-intlayer, react-intlayer, vue-intlayer, svelte-intlayer, solid-intlayer, preact-intlayer, angular-intlayer, lit-intlayer, express-intlayer, hono-intlayer, fastify-intlayer, adonis-intlayer, intlayer).

Các lệnh gọi getter được hỗ trợ

Máy chủ phát hiện các lệnh gọi hàm sau và trích xuất đối số chuỗi ký tự đầu tiên làm khóa từ điển:

Các generic của TypeScript và các đối số bổ sung đều bị bỏ qua — chỉ chuỗi khóa mới quan trọng.

useDictionary và getDictionary nhận một đối tượng Dictionary đã được nhập làm đối số đầu tiên của chúng thay vì một khóa chuỗi, do đó chúng không được hưởng lợi từ tính năng Đi tới Định nghĩa và không được theo dõi bởi máy chủ.

Cài đặt

Máy chủ LSP được phân phối như một phần của @intlayer/lsp:

npm install --save-dev @intlayer/lsp

Gói này cung cấp tệp nhị phân intlayer-lsp, được trình soạn thảo sử dụng làm tệp thực thi của máy chủ.

Thiết lập như một Plugin Claude Code

Intlayer LSP có sẵn dưới dạng plugin Claude Code được lưu trữ trực tiếp trong kho lưu trữ GitHub của Intlayer. Việc cài đặt nó giúp Claude Code có nhận thức gốc về tính năng Đi tới Định nghĩa cho tất cả các lệnh gọi useIntlayer / getIntlayer của bạn.

1. Cài đặt tệp nhị phân máy chủ ngôn ngữ

npm install -g @intlayer/lsp

Thao tác này sẽ đặt tệp nhị phân intlayer-lsp vào biến môi trường PATH của bạn, đây là tệp được gọi bởi mục lspServers trong plugin.

2. Đăng ký thị trường Intlayer và cài đặt plugin

claude plugin marketplace add intlayer@github:aymericzip/intlayerclaude plugin install intlayer-lsp@intlayerclaude plugin enable intlayer-lsp@intlayer

Claude Code sẽ thêm "intlayer-lsp@intlayer": true vào danh sách enabledPlugins của bạn và tự động khởi động máy chủ ngôn ngữ trên các loại tệp được hỗ trợ (.ts, .tsx, .js, .jsx, .vue, .svelte).

3. Bật công cụ LSP (nếu chưa hoạt động)

Một số phiên bản Claude Code yêu cầu cờ tính năng LSP phải được đặt. Thêm nội dung sau vào tệp ~/.claude/settings.json của bạn nếu tính năng Đi tới Định nghĩa không hoạt động sau khi cài đặt:

{  "env": {    "ENABLE_LSP_TOOL": "1"  }}

Khởi động lại Claude Code — từ giờ nó sẽ sử dụng goToDefinition, findReferences và các thao tác LSP khác khi điều hướng cơ sở mã Intlayer của bạn thay vì sử dụng grep.

Thiết lập trong VS Code (thông qua tiện ích mở rộng — khuyến nghị)

Nếu bạn đã cài đặt tiện ích mở rộng Intlayer VS Code, máy chủ ngôn ngữ sẽ tự động bắt đầu. Không cần cấu hình thêm.

Xem tài liệu tiện ích mở rộng VS Code để biết cách cài đặt và các tính năng khác.

Thiết lập thủ công trong VS Code

Nếu bạn không sử dụng tiện ích mở rộng Intlayer, bạn có thể kết nối máy chủ ngôn ngữ theo cách thủ công bằng cách sử dụng một tiện ích mở rộng ứng dụng khách LSP chung như vscode-glspc hoặc bằng cách viết một tiện ích mở rộng nhỏ của riêng bạn. Phương pháp khuyến nghị là sử dụng tiện ích mở rộng Intlayer.

Để tham khảo, máy chủ được khởi chạy thông qua tệp nhị phân intlayer-lsp qua stdio:

{  "intlayer.languageServer.command": "npx",  "intlayer.languageServer.args": ["@intlayer/lsp"]}

Tiện ích mở rộng Intlayer đọc các cài đặt này để khởi chạy máy chủ. Nếu bạn chỉ dựa vào tiện ích mở rộng, không cần cài đặt thủ công.

Thiết lập trong Cursor

Cursor là một bản phân nhánh của VS Code với các tính năng AI tích hợp. Nó sử dụng cùng một hệ sinh thái tiện ích mở rộng, vì vậy tiện ích mở rộng Intlayer VS Code hoạt động mà không cần bất kỳ cấu hình bổ sung nào — hãy cài đặt nó một lần và Cursor sẽ tự động phát hiện.

Nếu bạn thích cấu hình thủ công, Cursor cũng đọc tệp .vscode/settings.json từ thư mục gốc của không gian làm việc, do đó đoạn mã VS Code ở trên sẽ áp dụng trực tiếp.

Thiết lập trong Windsurf

Windsurf (phát triển bởi Codeium) là một trình soạn thảo dựa trên VS Code khác. Cài đặt tiện ích mở rộng Intlayer từ VS Code Marketplace và máy chủ ngôn ngữ sẽ tự động được kích hoạt, giống hệt như trong VS Code và Cursor.

Để cấu hình thủ công, hãy tạo tệp .vscode/settings.json tại thư mục gốc của dự án:

{  "intlayer.languageServer.command": "npx",  "intlayer.languageServer.args": ["@intlayer/lsp"]}

Thiết lập trong Zed

Zed hỗ trợ LSP gốc thông qua cài đặt ngôn ngữ của nó. Thêm một mục trong cài đặt người dùng Zed của bạn (~/.config/zed/settings.json):

{  "lsp": {    "intlayer-lsp": {      "binary": {        "path": "npx",        "arguments": ["--yes", "@intlayer/lsp"]      }    }  },  "languages": {    "TypeScript": {      "language_servers": ["intlayer-lsp", "..."]    },    "TSX": {      "language_servers": ["intlayer-lsp", "..."]    },    "JavaScript": {      "language_servers": ["intlayer-lsp", "..."]    },    "Vue.js": {      "language_servers": ["intlayer-lsp", "..."]    },    "Svelte": {      "language_servers": ["intlayer-lsp", "..."]    }  }}

Dấu giữ chỗ "..." yêu cầu Zed giữ các máy chủ ngôn ngữ mặc định của nó cùng với máy chủ Intlayer.

Thiết lập cho CLI Tác nhân AI (Claude Code, Codex, v.v.)

Claude Code có hỗ trợ plugin LSP hạng nhất — hãy làm theo các bước thiết lập Plugin Claude Code ở trên để có được trải nghiệm Đi tới Định nghĩa đầy đủ trực tiếp trong các phiên terminal của bạn.

OpenAI Codex và các công cụ dựa trên terminal khác chưa hoạt động như máy chủ khách LSP — chúng đọc và ghi tệp trực tiếp thay vì duy trì một phiên máy chủ ngôn ngữ liên tục. Đối với những công cụ đó, giá trị của việc chạy LSP đến một cách gián tiếp: khi máy chủ hoạt động trong một trình soạn thảo đồng hành (VS Code, Cursor, Windsurf, ...), chỉ mục trực tiếp của trình soạn thảo sẽ có sẵn cho bất kỳ tác nhân AI nào có thể truy vấn nó thông qua ngữ cảnh do trình soạn thảo cung cấp (ví dụ: Cursor Composer, Windsurf Cascade, GitHub Copilot Chat).

Nếu bạn chỉ làm việc trong terminal mà không mở trình soạn thảo, bạn có thể khởi động máy chủ ngôn ngữ trong nền để nó sẵn sàng cho bất kỳ trình soạn thảo nào sau đó kết nối với cùng một không gian làm việc:

# Giữ cho máy chủ tiếp tục chạy trong nềnnpx @intlayer/lsp &

Thiết lập thủ công trong Neovim

Sử dụng nvim-lspconfig, đăng ký cấu hình máy chủ tùy chỉnh:

local lspconfig = require('lspconfig')local configs = require('lspconfig.configs')if not configs.intlayer_lsp then  configs.intlayer_lsp = {    default_config = {      -- Khởi chạy máy chủ bằng npx để bạn không cần cài đặt toàn cục      cmd = { 'npx', '--yes', '@intlayer/lsp' },      filetypes = {        'typescript',        'typescriptreact',        'javascript',        'javascriptreact',        'vue',        'svelte',      },      root_dir = lspconfig.util.root_pattern(        'intlayer.config.ts',        'intlayer.config.js',        'package.json'      ),    },  }endlspconfig.intlayer_lsp.setup({})

Sau khi khởi động lại Neovim, việc nhấn gd trên một khóa Intlayer sẽ kích hoạt Đi tới Định nghĩa.

Thiết lập thủ công trong các Trình soạn thảo khác

Bất kỳ trình soạn thảo nào hỗ trợ Giao thức Máy chủ Ngôn ngữ đều có thể sử dụng @intlayer/lsp. Máy chủ:

• Truyền tải – Node.js IPC / stdio (tiêu chuẩn)
• Tệp thực thi – npx @intlayer/lsp (hoặc tệp nhị phân intlayer-lsp được cài đặt cục bộ)
• Khả năng – definitionProvider: true, textDocumentSync: Incremental

Tham khảo tài liệu LSP của trình soạn thảo của bạn để biết định dạng cấu hình chính xác (ví dụ: languageserver.json cho coc.nvim, hoặc cài đặt ứng dụng khách LSP trong Helix).

Ví dụ: coc.nvim

{  "languageserver": {    "intlayer": {      "command": "npx",      "args": ["@intlayer/lsp"],      "filetypes": [        "typescript",        "typescriptreact",        "javascript",        "javascriptreact",        "vue",        "svelte"      ],      "rootPatterns": [        "intlayer.config.ts",        "intlayer.config.js",        "package.json"      ]    }  }}

Ví dụ: Helix

[[language]]name = "typescript"language-servers = ["intlayer-lsp", "typescript-language-server"][[language]]name = "tsx"language-servers = ["intlayer-lsp", "typescript-language-server"][language-server.intlayer-lsp]command = "npx"args = ["@intlayer/lsp"]

Cách hoạt động

Khi máy chủ khởi động, nó sẽ giải quyết cấu hình Intlayer từ thư mục gốc của không gian làm việc bằng cách sử dụng getConfiguration(). Điều này cung cấp cho nó các đường dẫn build và system cần thiết để tìm các từ điển được biên dịch.

Trên mỗi yêu cầu Đi tới Định nghĩa:

1. Máy chủ đọc toàn bộ văn bản của tài liệu đang mở.
2. Nó quét các lệnh gọi getter (useIntlayer, getIntlayer, v.v.) bằng cách sử dụng một biểu thức chính quy.
3. Nó kiểm tra xem vị trí con trỏ có nằm trong một trong những lệnh gọi đó hay không.
4. Nếu có, nó sẽ trích xuất khóa từ điển (nhóm chụp 3 của biểu thức chính quy) và gọi getUnmergedDictionaries() để xác định vị trí của từng tệp nội dung khai báo khóa đó.
5. Nó đọc từng tệp phù hợp và tìm dòng chính xác chứa key: "<key>" để định vị con trỏ một cách chính xác.
6. Nó trả về một mảng gồm các đối tượng Location — một đối tượng trên mỗi tệp nguồn.

Cấu hình được giải quyết một cách lazy và được lưu vào bộ nhớ cache cho mỗi phiên; nó sẽ được đặt lại trên mỗi yêu cầu initialize (ví dụ: khi bạn mở một thư mục không gian làm việc mới).

Khắc phục sự cố