如何在Kate编辑器中正确启用YAML Language Server

问题背景 #

目前存在由Red Hat开发的yaml language server，需要在Kate Editor中接入该服务。Kate官方language server plugin文档给出的配置示例如下：

{
    "servers": {
        ...
        "python": {
            "command": ["python3", "-m", "pyls", "--check-parent-process"],
            "url": "https://github.com/palantir/python-language-server",
            "highlightingModeRegex": "^Python$"
        }
        ...
    }
}

• 当前Python语言服务器可开箱正常使用，可确认LSP插件本身不存在运行故障。

yaml language server官方给出的启动命令为：

docker run -it quay.io/redhat-developer/yaml-language-server:latest

• 在bash中手动执行该命令时，可观察到docker容器正常启动：

CONTAINER ID   IMAGE                                                  COMMAND                  CREATED          STATUS          PORTS     NAMES
fac9a04e2bf0   quay.io/redhat-developer/yaml-language-server:latest   "node ./out/server/s…"   12 seconds ago   Up 11 seconds             practical_euclid

已将当前用户加入docker用户组，可非root权限运行docker命令，Kate同样以当前用户身份运行，因此LSP插件也会以当前用户权限执行启动命令。

参照示例编写的Kate LSP插件yaml服务配置如下：

...
        "yaml": {
            "command": ["docker", "run", "-it", "quay.io/redhat-developer/yaml-language-server:latest"],
            "url": "https://github.com/redhat-developer/yaml-language-server",
            "highlightingModeRegex": "^YAML$"
        },
        ...

• 该配置经Kate配置编辑器校验为合法JSON格式，但在Kate中打开YAML文件时，收到如下日志提示：

10:24:14 LSP Client Log Started server yaml@/home/i314691: /usr/bin/docker run -it quay.io/redhat-developer/yaml-language-server:latest
10:24:14 LSP Client Warning Server terminated unexpectedly ... NOT Restarting [/usr/bin/docker run -it quay.io/redhat-developer/yaml-language-server:latest] [homepage: https://github.com/redhat-developer/yaml-language-server]

• 实际观测到docker容器会立刻终止，docker ps命令无法查询到已退出的容器，因此无法直接查看运行日志。Kate LSP插件文档提示可开启语言服务器的深度调试功能，因对Node.js相关知识了解有限，需要明确以下三类排查方法：
  • 运行Node.js应用的docker容器故障排查方法
  • yaml language server本身的运行问题排查方法
  • Kate与语言服务器之间的通信故障排查手段

当前使用的Kate编辑器版本信息如下：

||/ Name                 Version                             Architecture Description
+++-====================-===================================-============-============================================
ii  kate                 4:22.04.2-0ubuntu1~ubuntu22.04~ppa1 amd64        powerful text editor
ii  kate5-data           4:22.04.2-0ubuntu1~ubuntu22.04~ppa1 all          shared data files for Kate text editor
ii  ktexteditor-katepart 5.94.0-0ubuntu1~ubuntu22.04~ppa1    amd64        provide advanced plain text editing services

排查与修复步骤 #

1. 核心故障修复 #

当前配置失效的核心原因是docker run的-it参数使用错误：

• -it是-i（保持标准输入打开）+-t（分配伪终端TTY）的组合参数，Kate的LSP插件启动服务时不会为子进程分配交互式TTY，加了-t参数启动的容器检测不到TTY会直接立刻退出。
• LSP服务通过标准输入输出和编辑器通信，只需要保留-i参数即可，不需要分配TTY。

修正后的可用配置如下：

"yaml": {
    "command": ["docker", "run", "-i", "--rm", "quay.io/redhat-developer/yaml-language-server:latest", "--stdio"],
    "url": "https://github.com/redhat-developer/yaml-language-server",
    "highlightingModeRegex": "^YAML$"
}

新增参数说明：

• --rm：容器退出后自动删除，避免残留大量已退出的无用容器
• --stdio：显式指定yaml language server使用stdio模式通信，部分版本镜像默认不会自动启用该模式，显式指定可避免服务因未指定通信方式直接退出。

2. Docker容器（Node.js应用）通用排查方法 #

• 查看已退出容器日志：执行docker ps -a可列出所有状态的容器（包括已退出的），拿到对应容器ID后执行docker logs <容器ID>即可查看容器退出前的所有标准输出、错误输出，Node.js抛出的运行时异常会直接打印在日志中。
• 容器内手动调试：如果日志信息不足，可以覆盖容器入口点进入容器内部手动执行启动命令定位问题，执行命令：

  docker run --rm -it --entrypoint bash quay.io/redhat-developer/yaml-language-server:latest
  

  进入容器后手动执行服务启动命令node ./out/server/src/server.js --stdio，即可看到完整的Node.js运行报错，包括依赖缺失、权限错误、配置加载失败等问题。

3. YAML Language Server本身排查方法 #

• 脱离容器本地测试：先绕过Docker直接本地安装服务验证可用性，执行npm install -g yaml-language-server全局安装后，直接在终端执行yaml-language-server --stdio，如果进程不退出，输入任意字符后返回JSON格式的LSP错误报文，说明服务本身运行正常，问题出在Docker启动参数或Kate配置上。
• 验证启动参数：yaml language server支持多种通信模式，必须显式指定--stdio才能和Kate的LSP插件通过标准流通信，未指定该参数时服务启动后会因为找不到通信通道直接退出。

4. Kate LSP通信故障排查手段 #

• 开启LSP全量日志：在Kate的LSP插件设置中开启「显示LSP客户端日志面板」，打开YAML文件时日志面板会记录服务启动、初始化握手、报文交互的全量流程，可以直接定位故障是发生在服务启动阶段，还是LSP协议初始化阶段。
• 终端手动验证启动命令：将配置中的command完整复制到终端执行，比如修正后的命令docker run -i --rm quay.io/redhat-developer/yaml-language-server:latest --stdio，如果执行后进程持续驻留不退出，输入测试字符有对应输出，说明启动命令本身没有问题，故障出在Kate侧的配置匹配规则上，可检查highlightingModeRegex是否和Kate实际识别的YAML文件高亮模式完全匹配。

内容的提问来源于stack exchange，提问作者sumid