MeTTa-LSP

<img src="media/banner-top.png" width="100%" alt="" /> <div align="center"> <img src="media/metta-logo.png" alt="MeTTa" width="520" /> <h1>MeTTa LSP</h1> <img src="media/header-line.png" alt="" width="600" /> <p> <strong> 一个纯TypeScript语言服务器，VS Code扩展，CLI和MCP服务器 <a href="https://metta-lang.dev/">MeTTa</a>。 </strong> <br /> _{悬停提示 &nbsp;·&nbsp; 诊断信息 &nbsp;·&nbsp; 运行、跟踪和可视化 &nbsp;·&nbsp; 格式化 &nbsp;·&nbsp; 调试适配器 &nbsp;·&nbsp; 代理工具} </p> <p> <img src="https://img.shields.io/badge/VS%20Code-1.90%2B-0186DB?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code 1.90+" /> <img src="https://img.shields.io/badge/node-20.19%2B-083268?style=flat-square&logo=node.js&logoColor=white" alt="Node 20.19+" /> <img src="https://img.shields.io/badge/TypeScript-strict-0186DB?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript strict" /> <img src="https://img.shields.io/badge/MeTTa-@metta--ts%2Fcore-F3AD00?style=flat-square" alt="@metta-ts/core" /> <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-083268?style=flat-square" alt="Linux, macOS, and Windows" /> <img src="https://img.shields.io/badge/license-Apache--2.0-0186DB?style=flat-square" alt="Apache-2.0 License" /> </p> <p> <a href="https://mestto.github.io/MeTTa-LSP/"> <img src="https://img.shields.io/badge/文档-0186DB?style=for-the-badge&logo=gitbook&logoColor=white" alt="文档" /> </a> &nbsp; <a href="#quick-start"> <img src="https://img.shields.io/badge/快速开始-F3AD00?style=for-the-badge&logoColor=black" alt="快速开始" /> </a> &nbsp; <a href="https://github.com/MesTTo/MeTTa-LSP/issues/new?template=bug_report.yml"> <img src="https://img.shields.io/badge/报告问题-083268?style=for-the-badge&logo=github&logoColor=white" alt="报告问题" /> </a> &nbsp; <a href="https://github.com/MesTTo/MeTTa-LSP/issues/new?template=feature_request.yml"> <img src="https://img.shields.io/badge/请求功能-083268?style=for-the-badge&logo=github&logoColor=white" alt="请求功能" /> </a> </p> </div> <img src="media/divider-candy.png" width="100%" alt="" /> ## 什么是MeTTa LSP MeTTa LSP是一个通过多个工具暴露的分析器。相同的代码为VS Code扩展、stdio LSP服务器、命令行界面、MCP服务器、调试适配器、生成的文档和浏览器IDE提供支持。一个符号在悬停提示、诊断信息、跟踪输出、文档和代理工具调用中应该具有相同的含义。 浏览器IDE在Web Worker中运行相同的语言服务器。它提供了一个持久的多文件工作区、实时的诊断信息、补全、悬停提示、导航、重命名、格式化、文档符号和受限的求值，而无需后端服务。 运行时基于`@metta-ts/core`，因此服务器在Node上运行，无需WASM依赖。编辑器分析不会求值用户代码。显式的运行、跟踪、测试和可视化命令使用配置的运行时路径和受限的工作器（如果适用）。 扩展、CLI、stdio语言服务器、MCP服务器和文档工具链设计用于Linux、macOS和Windows。编辑器特定的设置有所不同，但每个客户端都启动相同的Node stdio服务器并读取相同的`metta.*`设置。 <img src="media/divider-candy.png" width="100%" alt="" /> ## 快速开始 从Marketplace安装VS Code扩展： ```sh code --install-extension MeTTaMesTTo.metta-ts-lsp ``` 您也可以安装下载的GitHub发布资产： ```sh code --install-extension metta-ts-lsp-0.11.1.vsix ``` 从此检出构建时，您需要CLI、MCP服务器或另一个编辑器： ```sh npm install npm run compile ``` 构建写入以下入口点： ```text dist/server/server.js stdio语言服务器 dist/cli/cli.js metta-lsp CLI dist/mcp/server.js MCP服务器 dist/debug/mettaDebugAdapter.js 调试适配器 ``` 尝试从检出使用CLI： ```sh npm --silent run cli -- check examples/04-diagnostics.metta npm --silent run cli -- trace examples/13-trace.metta "(sum-to 3)" --max 8 ``` 在本地打包扩展： ```sh npm run package code --install-extension metta-ts-lsp-*.vsix ``` 使用任何stdio LSP客户端： ```sh node /path/to/metta-ts-lsp/dist/server/server.js --stdio ``` <img src="media/divider-candy.png" width="100%" alt="" /> ## 功能 ### 编辑器智能 服务器为`.metta`文件实现了预期的LSP接口：悬停提示、补全、补全解析、签名帮助、诊断信息、文档符号、工作区符号、定义、引用、实现、类型定义、声明、重命名、准备重命名、文档高亮、链接编辑、文档链接、折叠范围、选择范围、语义标记、调用层次、插入提示、代码镜头、代码操作、组织导入、完整格式化、范围格式化和实时格式化。 VS Code扩展添加了状态栏控件、设置快速选择、运行和跟踪按钮、Test Explorer集成用于断言表单，以及用于使用调试适配器逐步调试的启动配置。 ### 诊断和lint 诊断信息涵盖语法错误、重复定义、未解析符号、未定义类型、未绑定空间、元数不匹配、字面类型不匹配、项目lint规则、TypeScript主机桥检查和引用的`.pl`桥文件的只读Prolog解析器诊断。 抑制是可见的。内联注释（如`; @suppress symbol.possibleTypo`）隐藏了一个诊断信息，并提供了显示被抑制内容的悬停提示。项目抑制存在于`lint.metta`中作为数据，使用与lint规则相同的结构化匹配器。 ### 运行、测试、跟踪、可视化 运行命令求值顶级bang查询并将MeTTa语法打印回输出通道或CLI。测试发现运行顶级断言表单。跟踪记录查询的每个减少步骤，而可视化写入交互式MeTTaGrapher HTML视图。 受限求值在具有燃料、超时、输出和堆栈限制的无状态工作器中运行。对于故意使用主机互操作的受信任程序，提供无限制运行。 ### 语法和语义颜色 TextMate语法处理注释、字符串、转义、数字、变量、文档原子、括号、运算符、声明和内置函数。语义标记在语法之上添加了控制流、绑定、模式匹配、模块、类型运算符、求值、引用控制、效果、算术、比较、逻辑、数学函数、集合函数、谓词、断言、声明、定义、返回类型、默认库符号、已弃用符号和未解析符号的含义。 VS Code主题可以直接样式化这些标记类型。当主题不这样做时，扩展将它们映射回熟悉的TextMate范围。 ### TypeScript、Python和Prolog接口 TypeScript主机桥读取`@metta-ts/hyperon`或类型化eDSL注册的接地操作。悬停提示和转到定义一个接地原子可以显示TypeScript签名、JSDoc、MeTTa类型视图和主机源。CLI公开了相同的数据，带有`host-type`。 TypeScript语言服务插件在`.ts`文件中的MeTTa字符串和模板中提供了MeTTa悬停提示、补全、签名帮助和诊断信息。Python互操作示例涵盖了`py-atom`、`py-call`和`py-eval`。Prolog诊断信息解析了引用的`.pl`文件，而不咨询或执行它们。 ### 搜索、重写和文档 结构化搜索命令将MeTTa表单视为数据。 `$X`捕获一个原子，而`$$$Rest`捕获一个序列。正则表达式约束可以细化`lint.metta`中的捕获，而`replace`可以预览或写入结构化重写。 文档生成器从工作区模块和主机操作构建MeTTa API参考。悬停提示、CLI输出、生成的参考页面和浏览器文档站点都共享相同的MeTTa文档渲染代码。 <img src="media/divider-candy.png" width="100%" alt="" /> ## 示例 打开`examples/`作为VS Code工作区，并按顺序遍历文件。每个文件都显示一个表面，并包含用于尝试编辑器操作或CLI命令的注释。完整的检查清单存在于[`examples/FEATURE-COVERAGE.md`](examples/FEATURE-COVERAGE.md)。 | 示例 | 表面 | | --- | --- | | [`01-hovers.metta`](examples/01-hovers.metta) | 内置函数和用户符号的悬停提示 | | [`02-running.metta`](examples/02-running.metta) | 运行、跟踪和可视化 | | [`04-diagnostics.metta`](examples/04-diagnostics.metta) | 诊断信息目录 | | [`05-lint-and-suppression/`](examples/05-lint-and-suppression/demo.metta) | Lint规则、修复和抑制 | | [`08-navigation.metta`](examples/08-navigation.metta) | 定义、引用、重命名和调用层次 | | [`09-formatting.metta`](examples/09-formatting.metta) | 完整、范围和实时格式化 | | [`10-testing.metta`](examples/10-testing.metta) | 断言测试和Test Explorer | | [`13-trace.metta`](examples/13-trace.metta) | 减少跟踪 | | [`14-editor-surfaces.metta`](examples/14-editor-surfaces.metta) | 语义颜色、符号、链接、折叠和选择范围 | | [`15-guarded-and-agent-surfaces.metta`](examples/15-guarded-and-agent-surfaces.metta) | 受限求值、CLI和MCP | | [`16-debugging.metta`](examples/16-debugging.metta) | 调试适配器 | | [`17-prolog-diagnostics/`](examples/17-prolog-diagnostics/main.metta) | Prolog解析器诊断信息 | | [`18-host-bridge/`](examples/18-host-bridge/main.metta) | TypeScript接地操作主机桥 | | [`19-typescript-plugin/`](examples/19-typescript-plugin/sample.ts) | MeTTa在TypeScript字符串中 | <img src="media/divider-candy.png" width="100%" alt="" /> ## 命令行 安装的命令是`metta-lsp`，它是脚本、CI、代理和本地shell的正常接口： ```sh metta-lsp check examples/04-diagnostics.metta metta-lsp trace examples/13-trace.metta "(sum-to 3)" --max 8 ``` 从未链接的检出，使用npm别名： ```sh npm --silent run cli -- check examples/04-diagnostics.metta ``` 要从检出全局安装命令，请运行： ```sh npm run compile npm link ``` | 命令 | 它做什么 | | --- | --- | | `capabilities` | 打印功能账本和表面覆盖。 | | `check <file> [--json] [--show-suppressed]` | 运行解析器、分析器、lint、桥和可选诊断。 | | `symbols <file> [--json]` | 打印文档大纲。 | | `hover <file> <line> <character> [--json]` | 在1-based编辑器位置显示悬停文本。 | | `def <file> <line> <character> [--json]` | 转到符号定义。 | | `host-type <file> <line> <character> [--json]` | 为接地原子显示TypeScript主机签名数据。 | | `explain <file> <line> <character> [--json]` | 将当前表单渲染为mixfix表示法。 | | `refs <file> <line> <character> [--json]` | 查找指定位置的符号引用。 | | `fmt <file> [--check]` | 格式化MeTTa文件或检查是否已格式化。 | | `lint <file> [--json] [--fix]` | 运行语法lint规则并可选地应用修复。 | | `search <file> "<pattern>" [--json]` | 运行结构化模式匹配器。 | | `replace <file> "<pattern>" "<template>" [--write]` | 预览或应用结构化重写。 | | `test <file> [--json] [--tap] [--junit]` | 在受限运行时运行顶级断言表单。 | | `run <file> [--unguarded]` | 求值顶级bang查询。仅在受信任的主机互操作中使用`--unguarded`。 | | `trace <file> "<query>" [--json] [--max N]` | 显示查询的每个减少步骤。 | | `visualise <file> "<query>" [--out file.html] [--block]` | 写入减少图HTML视图。 | | `doc [root] [--json] [--build] [--serve] [--open] [--port N] [--base PATH]` | 为工作区生成或提供MeTTa文档。 | | `repl [file]` | 启动交互式MeTTa REPL，可选地使用文件作为种子。 | | `lsp --stdio` | 启动stdio上的语言服务器。 | | `mcp --stdio` | 启动stdio上的MCP服务器。 | 大多数读取命令都接受 `--json` 以用于脚本和代理。 ### 抑制示例 ```metta ; @suppress symbol.possibleTypo !(cdr-atomm 2) ``` 项目抑制存在于 `lint.metta`中： ```metta (suppress (legacy $$$) symbol.possibleTypo) ``` 自定义规则可以添加正则表达式约束： ```metta (lint-rule capitalized-function-name (pattern (= ($Func $$$Args) $$$Body)) (metavariable-regex $Func "^[A-Z]") (message "函数 {$Func} 以大写字母开头") (severity warn)) ``` 检查文件并包括被抑制的诊断信息： ```sh metta-lsp check examples/05-lint-and-suppression/demo.metta --show-suppressed ``` ### 跟踪示例 ```metta (: sum-to (-> Number Number)) (= (sum-to $n) (if (== $n 0) 0 (+ $n (sum-to (- $n 1))))) ``` ```sh metta-lsp trace examples/13-trace.metta "(sum-to 3)" --max 8 ``` ```text 0 (sum-to 3) 1 (if (== 3 0) 0 (+ 3 (sum-to (- 3 1)))) 2 (if False 0 (+ 3 (sum-to (- 3 1)))) 3 (+ 3 (sum-to (- 3 1))) 4 (+ 3 (sum-to 2)) 5 (+ 3 (if (== 2 0) 0 (+ 2 (sum-to (- 2 1))))) 6 (+ 3 (if False 0 (+ 2 (sum-to (- 2 1))))) 7 (+ 3 (+ 2 (sum-to (- 2 1)))) 8 (+ 3 (+ 2 (sum-to 1))) ... 截断在8步 ``` <img src="media/divider-candy.png" width="100%" alt="" /> ## 代理设置 Claude Code、Codex和通用MCP客户端使用MCP服务器： ```sh npm run compile npm run setup:mcp -- --claude --codex ``` 设置脚本将`metta-lsp`注册为stdio MCP服务器，指向`dist/mcp/server.js`。代理可以调用粒度工具，如`lsp_diagnostics`、`lsp_hover`、`lsp_workspace_symbols`和`lsp_guarded_evaluate`，或操作调度`lsp`工具。 运行设置脚本而不带标志以打印代码片段： ```sh npm run setup:mcp ``` 克劳德代码： ```sh claude mcp add -s user metta-lsp -- node /path/to/metta-ts-lsp/dist/mcp/server.js ``` Codex，在`~/.codex/config.toml`中： ```toml [mcp_servers."metta-lsp"] command = "node" args = ["/path/to/metta-ts-lsp/dist/mcp/server.js"] startup_timeout_sec = 120.0 ``` 通用MCP客户端： ```json { "mcpServers": { "metta-lsp": { "command": "node", "args": ["/path/to/metta-ts-lsp/dist/mcp/server.js"] } } } ``` 代理响应默认情况下是紧凑的。符号、位置和调用层次结构结果按文件分组，并使用行数组： ```json { "fields": ["name", "kind", "line", "char"], "count": 2, "files": [{ "path": "math.metta", "rows": [["inc", "function", 3, 5]] }] } ``` 当代理需要原始LSP协议对象时，请传递 `"resultFormat": "lsp"`。 ### 欧米克劳 欧米克劳通过其MeTTa `getSkills`目录暴露工具，因此它使用技能覆盖层而不是MCP客户端配置： ```sh npm run compile npm run setup:omegaclaw -- /path/to/OmegaClaw-Core ``` 安装程序将MeTTa-LSP桥接文件复制到目标OmegaClaw-Core检出，添加可逆管理块，并写入收据。集成文件保留在此仓库中，用户可以将覆盖层应用于自己的OmegaClaw系统，而不仅仅是维护OmegaClaw分支。 使用以下命令删除覆盖层： ```sh npm run setup:omegaclaw -- /path/to/OmegaClaw-Core --uninstall ``` <img src="media/divider-candy.png" width="100%" alt="" /> ## 编辑器设置 VS Code用户安装扩展。其他编辑器启动同一个stdio服务器： ```sh node /path/to/metta-ts-lsp/dist/server/server.js --stdio ``` 在Neovim、Helix、Emacs、Sublime Text、Kate、Zed或其他支持stdio服务器的LSP客户端中使用该命令。设置位于 `metta` 部分。 常见设置： ```json { "metta.docs.baseUrl": "https://mestto.github.io/MeTTa-LSP/", "metta.inlayHints.enabled": true, "metta.pseudocode.enabled": false, "metta.diagnostics.semanticLint": false, "metta.workspace.maxFiles": 4000 } ``` 文档站点在[`docs-site/lsp/editors.md`](https://github.com/MesTTo/MeTTa-LSP/tree/main/docs-site/lsp/editors.md)有可复制的VS Code、Neovim、Helix、Emacs和Sublime Text设置代码片段。 <img src="media/divider-candy.png" width="100%" alt="" /> ## 文档 公共文档站点由`docs-site/`构建。它涵盖了LSP概述、CLI、MCP设置、编辑器设置、lint规则、抑制、结构化搜索和重写、mixfix伪代码、诊断信息、浏览器IDE、视觉编辑器、运行时游戏、内置函数参考和生成的MeTTa API页面。 生成参考页面： ```sh npm run docs:builtins npm run docs:metta ``` 在工作区根目录中使用CLI文档命令生成、构建或提供文档： ```sh metta-lsp doc examples --json metta-lsp doc examples --build metta-lsp doc examples --serve --open --port 5173 ``` <img src="media/divider-candy.png" width="100%" alt="" /> ## 开发 有用的检查： ```sh npm run typecheck npm run test npm run smoke:tool npm run smoke:all npm run verify:strict ``` `npm run smoke:tool`编译MCP服务器并运行检查的`examples/mcp-tool-smoke.jsonl`请求流。`npm run smoke:all`还检查解析器行为、受限安全性、DAP、Python互操作、DSL帮助程序、功能漂移、设置脚本和MCP烟雾流。 构建发布工件： ```sh npm run package ``` 通过GitHub Actions发布未来市场更新： ```sh git tag v0.11.2 git push origin v0.11.2 ``` `VS Code Marketplace`工作流构建VSIX，将其上传到标签的GitHub发布中，并将相同的包发布到Visual Studio Marketplace。添加存储库机密，命名为`VSCE_PAT`，一次使用具有`Manage`范围的Marketplace PAT。 检查Alloy模型： ```sh npm run alloy ``` <img src="media/divider-candy.png" width="100%" alt="" /> ## 许可证 Apache-2.0。参见 [LICENSE](https://github.com/MesTTo/MeTTa-LSP/blob/main/LICENSE)。