mpv/uosc Language Server

为 mpv 与 uosc 配置文件提供完整语言服务的 VS Code 扩展 + 独立 stdio LSP 服务器。

简介

mpv-uosc-lsp 基于真实的 Language Server Protocol 为三种 mpv 生态配置文件提供补全、悬停、诊断、格式化与跨文件理解：

语言服务器核心不依赖 VS Code API，是一个可被任意 LSP 客户端（Neovim、Zed 等）拉起的独立 stdio 进程；服务器从不执行配置内容、Lua 或 shell 命令，元数据随包内置，运行期不访问网络、不调用本机 mpv。

功能特性

mpv.conf

• 选项与 profile 补全、悬停说明，未知选项给出 mpv.unknown-option 诊断；
• 弃用选项提示：mpv.deprecated-option 诊断与迁移建议（覆盖手工维护条目与 mpv --list-options 生成的弃用别名，如 play-dir → play-direction）；
• profile 文档符号（[profile] 段落）与 profile 模板插入；
• 元数据覆盖层与版本选择：可从本机 mpv 生成选项/命令覆盖层，通过 mpvUosc.metadata.version（auto / builtin / 精确版本号）选择生效的元数据集；可选 mpvUosc.metadata.liveMpv 在激活时由客户端运行 mpv --no-config 采集最新元数据合并（服务器本身不执行任何命令）。

input.conf

• 按键、section、命令与引号参数的补全/诊断；支持 mpv 命令前缀（async / raw / repeatable 等，可叠加）；
• 修饰键链（大小写不敏感，Ctrl/ctrl/CTRL 均高亮）与按键名分别着色的语义/TextMate 高亮；
• 按键捕获面板：命令面板或 input.conf 编辑器右键菜单「mpv/uosc: 捕获按键并插入绑定」（mpvUosc.insertKeybinding）打开捕获面板——面板打开即就绪并列出全部已用绑定（可折叠「已使用的快捷键（N 个）」），直接按下组合键（无需先点击捕获区域），面板实时回显规范键名（与 mpv 归一化一致）；捕获后按规范键名显示该按键的现有绑定（无冲突提示，冲突逐条列出 文件名:行号 — key → command），插入前即可判断冲突；Enter 或点击「插入」确认后自动插入到活动 input.conf 光标处；若组合键被系统或其他软件拦截，可在面板内手动输入键名（OS 全局快捷键优先级高于任何应用，无法在扩展内绕过）；
• 按键规范化：按 mpv 语义（修饰键大小写与顺序不敏感、Shift+字母 折叠为大写字母、Shift+特殊键 保留）给出规范写法——修饰键顺序 Ctrl、Alt、Meta、Shift，首字母大写。非规范写法（如 ctrl+shift+a）触发 input.key-normalization 警告并附「规范化按键写法」快速修复，格式化器同样输出规范键名；
• 内置绑定代码片段 bind（key command）、binds（key {section} command）、bindc（key command ; command）。

uosc.conf

• uosc 配置项补全，布尔/枚举/数字值提示，语法诊断；
• uosc 上游同步：配置项元数据由上游默认配置自动生成，保持默认值与枚举提示最新。

跨文件理解

• 解析 include 与 profile 引用，支持在 include 图内对 include 路径和 profile= 引用进行定义跳转，并给出 mpv.include-missing / mpv.profile-unknown 诊断；
• include 图新鲜度：建图优先读取编辑器打开缓冲区（未保存的修改也生效），编辑打开的 included 文件即时失效根图并重发诊断，落盘变更由 workspace/didChangeWatchedFiles 捕获；
• 被 include 引用的文件即使未打开也会在其自身 URI 上收到诊断（语法错误等直接进入问题面板）；
• ~~home//~~/ include 先按根文档目录解析，未命中再按 mpv 优先级尝试候选配置目录（$MPV_HOME → $XDG_CONFIG_HOME/mpv 或 ~/.config/mpv，外加遗留 ~/.mpv；Windows 追加 %APPDATA%/mpv）。注意：mpv 本体按进程工作目录解析相对 include 路径，本服务器按「包含文件所在目录」解析（对编辑器场景更直观）；嵌套深度上限默认 8（mpvUosc.include.maxDepth 可调）与 mpv 一致；
• script 集成：识别 script-binding uosc/...（补全/悬停/跳转到 uosc 源码，未知绑定给出 input.unknown-script-binding 提示），并关联 script-opts-<script>-<key> 与 script-opts/<script>.conf（补全/悬停/跳转，未知选项给出 mpv.unknown-script-opt 提示）。第三方脚本自身的 Lua 代码不在分析范围内；
• 可配置文件识别：mpvUosc.recognition 支持自定义文件名、后缀扩展名、目录段匹配（如 ~/.config/mpv/ 下的 .conf）与 include 继承，让非标准命名的配置也获得完整 LSP 支持（详见文件识别）。

编辑辅助

• 格式化：mpv.conf/uosc.conf 输出规范 key=value（不改变注释、顺序、引号与换行风格），input.conf 绑定键输出规范写法，格式化幂等；总开关 mpvUosc.formatting.enabled 与分语言开关 mpvUosc.formatting.mpv|input|uosc；
• 快速修复 Code Action：相似拼写建议、布尔值切换、uosc 缺 = 修复、profile 模板插入、弃用选项迁移、按键写法规范化；
• 快捷键冲突视图：检测同一 input section 中重复的按键绑定，运行命令「mpv/uosc: 显示快捷键冲突视图」（mpvUosc.showKeybindingConflicts）在 Webview 中按 section 查看绑定与冲突高亮；
• 外部脚本 schema：第三方 mpv Lua 脚本（sponsorblock、autoload、thumbnail 等）的 script-opts 通过 mpvUosc.externalSchemas 注册 JSON schema 后获得补全、悬停与未知选项诊断（详见外部脚本 schema）。

安装

Marketplace / Open VSX

发布流程已就绪（tag 触发的自动发布工作流），首发后可在 Visual Studio Marketplace 与 Open VSX 搜索 mpv-uosc-lsp 安装。

从 GitHub Releases 手动安装

从 GitHub Releases 下载对应平台的 mpv-uosc-lsp-<version>.vsix，然后执行：

code --install-extension mpv-uosc-lsp-<version>.vsix

或在 VS Code 中选择「扩展: 从 VSIX 安装...」。

从源码构建

要求 Node.js ≥ 22.13：

git clone https://github.com/zerobiubiu/mpv-uosc-lsp.git
cd mpv-uosc-lsp
npm install && npm run build && npm run package
code --install-extension mpv-uosc-lsp-<version>.vsix

快速上手

1. 打开任意 mpv.conf / input.conf / uosc.conf（文件识别规则见 配置项），即可体验补全、悬停、诊断与「格式化文档」；
2. 命令面板中可用的两个命令：
   • 「mpv/uosc: 捕获按键并插入绑定」（mpvUosc.insertKeybinding）——打开按键捕获面板，按下组合键即可把规范键名绑定插入光标处（input.conf 编辑器右键菜单也有入口）；
   • 「mpv/uosc: 显示快捷键冲突视图」（mpvUosc.showKeybindingConflicts）——按 section 查看绑定与冲突。

独立 LSP 服务器

语言服务器核心不依赖 VS Code API。npm run build 额外产出独立入口 dist/standalone.js（自带 #!/usr/bin/env node shebang），是一个纯 stdio JSON-RPC 进程，可被任意 LSP 客户端拉起，服务器不需要工作区即可工作（元数据随包内置，运行期不访问网络、不调用本机 mpv）。

直接运行：

node dist/standalone.js --stdio

或在仓库根目录执行 npm link，将 package.json 中声明的 bin 注册为全局命令后即可全局调用：

npm link
mpv-uosc-lsp-lsp --stdio

各编辑器的接入示例：

• Neovim（nvim-lspconfig）
• Zed（settings.json 自定义 LSP）
• Zed 扩展包安装（语言检测 + 语法高亮 + LSP）

配置项

所有设置位于 mpvUosc.* 命名空间下：

文件识别（mpvUosc.recognition）

默认按文件名识别 mpv.conf / input.conf / uosc.conf。通过 mpvUosc.recognition 可扩展识别规则：

• filenames：按 basename（小写）匹配到对应 kind，例如把 include= 引用的 profiles.conf 识别为 mpv；
• extensions：按 basename 后缀（大小写不敏感）匹配到对应 kind，例如 {"mpv": [".mpv"]}，默认 {}；
• directories：URI 路径中完整匹配某个目录段（大小写不敏感）且文件以 .conf 结尾时，回退识别为 mpv——例如 ~/.config/mpv/ 下的任意 .conf；目录段要求精确相等，my-mpv-stuff 不会匹配 mpv。默认 mpv / .mpv（遗留配置目录，mpv 至今仍会读取）/ portable_config；
• includeInheritance：被 include= 引用的文件（出现在任一已打开 mpv 文档的 include 图中）自动继承父文档 kind，无需额外配置即可获得完整 LSP 支持。

已知盲区：$MPV_HOME 或 --config-dir 指向任意目录名时无法按目录段推断，请用 filenames/extensions 显式识别这类目录中的配置。

"mpvUosc.recognition": {
  "filenames": {
    "mpv": ["mpv.conf", "profiles.conf"],
    "input": ["input.conf"],
    "uosc": ["uosc.conf"]
  },
  "extensions": {},
  "directories": ["mpv", ".mpv", "portable_config"],
  "includeInheritance": true
}

外部脚本 schema（mpvUosc.externalSchemas）

第三方 mpv Lua 脚本（sponsorblock、autoload、thumbnail 等）有自己的 script-opts。通过 mpvUosc.externalSchemas 设置注册 JSON schema 文件后，这些脚本的 script-opts-<script>-<key> 也能获得补全、悬停与未知选项诊断。相对路径基于工作区根目录解析，绝对路径原样使用。schema 文件为单个对象或对象数组，每项形如 { script, options: [{ name, valueKind, description?, defaultValue? }] }，其中 valueKind 取 boolean / enum / number / string。例如：

[
  {
    "script": "sponsorblock",
    "options": [
      { "name": "server_address", "valueKind": "string", "description": "SponsorBlock 服务器地址", "defaultValue": "https://sponsor.ajay.app" },
      { "name": "skip_categories", "valueKind": "string", "description": "自动跳过的分类" }
    ]
  }
]

开发

要求 Node.js 22.13+ 与 VS Code 1.125+。

npm install
npm test
npm run check
npm run build
npm run package
npm run generate:metadata        # 从本机 mpv 重新生成选项/命令覆盖层（需要已安装 mpv）
npm run generate:uosc-metadata   # 从上游 uosc 默认配置重新生成 uosc 配置项元数据（需要网络）

注意：npm test 包含一个拉起 dist/server.js 的 stdio 协议集成测试，干净检出后需先 npm run build 再 npm test。

仓库还有元数据漂移检测 CI：定时比对本机 mpv 元数据产物，漂移时自动开 Issue（见 docs/03-metadata-drift.md）。

文档索引

更多设计与集成文档见 docs/README.md，包括设计规格、迭代历史、分发流程与各编辑器接入指南。

贡献

欢迎提交 Issue 与 Pull Request，开始之前请先阅读 CONTRIBUTING.md。

安全

发现安全漏洞请通过私密渠道报告，详见 SECURITY.md。

许可证

MIT