Deixis

Deixis

Deixis 是一个模型上下文协议（MCP）服务，为编码 Agent 提供对语言服务器协议（LSP）操作的类型化访问。它会管理为单个项目显式配置的语言服务器，并开放其语义能力，而不会额外引入文件系统、Shell、编辑器、索引或记忆层。

警告

Deixis 处于预 Alpha 阶段。其语义工具和受保护的重命名工作流可以使用，但目前尚不提供稳定性保证。

功能

默认情况下，已配置的 Deixis 会话会开放 15 个只读 MCP 工具。 使用 --allow-mutation 启动时，会增加 apply_rename，使工具总数达到 16 个。

工具	用途
deixis_server_status	列出已连接的服务，或查看某个服务的详细信息。
hover	返回零起始 UTF-8 位置上的悬停标记。
signature_help	返回调用签名和结构化参数详情。
definition	查找定义。
declaration	查找声明。
type_definition	查找类型定义。
implementation	查找实现。
references	查找引用，并明确指定是否包含声明。
incoming_calls	查找调用者及其调用位置。
outgoing_calls	查找被调用者及其调用位置。
diagnostics	请求拉取式诊断，或返回缓存的推送式诊断。
document_symbols	在需要符号结构时查看文件大纲。
workspace_symbols	搜索已连接的服务，或搜索某个明确指定的服务。
prepare_rename	检查某个位置上的符号是否可以重命名。
preview_rename	验证编辑并返回差异，以及一次性预览 ID。
apply_rename	应用一个确切的预览（需要 --allow-mutation）。

Deixis 会协商使用 UTF-8、UTF-16 和 UTF-32 位置，在针对文件的请求前从磁盘同步文档，确保每项操作都符合语言服务器声明的能力，并在结果中保留源服务器的来源信息。多个语言服务器可以服务于同一个不可变项目根目录。

可恢复的 LSP 取消会在有限的就绪等待后最多重试三次。重试共用原始请求超时时间，并会在 MCP 调用方取消时停止。如果重试次数用尽，错误会报告尝试次数并保留语言服务器的错误详情。

在索引期间遇到空结果，以及遇到 ContentModified 错误时，导航、悬停、签名帮助、引用、符号和调用层级准备操作也会在相同的超时时间和三次重试限制内重试。得到空结果后，Deixis 会等待服务就绪，直至请求截止时间，而不是在索引仍在继续时消耗重试次数。若服务仍处于忙碌状态，则会返回 request_timeout 错误（默认 30 秒）。 每次重试遇到 ContentModified 错误时，都会等待服务就绪，最长 5 秒。 针对文件的重试会在复用位置前确认已同步的文档及其磁盘内容均未更改。若请求期间服务始终处于就绪或状态未知，则非空结果和空结果都会立即返回。 对于目标符号导航，请直接使用 definition、type_definition、implementation 和 references。仅当需要文件大纲（例如查看文件中的类型、函数和嵌套成员）时，才使用 document_symbols。它不是默认导航步骤，也不是执行其他查询的前提条件。这些说明也包含在 MCP 初始化说明和工具描述中。

不带参数调用 deixis_server_status 会按字典顺序列出已连接的服务，并统计其余已配置的服务：

attached: python, rust
not attached: 3

空列表显示为 attached: none；即使数量为零，也会显示计数。结构化输出包含 attached（已配置名称的数组）和 notAttached（数量）。Deixis 至少与某个服务当前进程同步过一份文档后，该服务才算已连接。尚未启动或已启动但没有同步文档的服务计为未连接。传入 server 可获取该服务详细的生命周期和能力快照；start: true 也要求明确指定服务名称。

references、incoming_calls、outgoing_calls、document_symbols 和 workspace_symbols 均接受可选的 limit（默认值为 100，最大值为 500）和 offset（默认值为 0）。每页的紧凑 JSON 结果数组上限也为 64 KiB。结构化的 pagination 对象会报告 returned、total、truncated，并在还有更多结果时报告 nextOffset。使用该偏移量和相同的查询参数继续查询。每次调用都会重新运行查询，因此文件编辑、索引进度或已连接服务的变化都可能导致分页结果发生变化。文本响应会概述当前页。

每个嵌套的文档符号都会计入限制。符号在每页中保留层级关系；index 和 parentIndex 用于标识跨页关系，而 childCount 则报告直接子项的完整数量。单个条目若大到无法放入一页，则会被省略，其索引会列在 pagination.omitted 中，并将 truncated 设为 true。分页会跳过这些条目继续前进。计数和字节数限制适用于 Deixis 返回的规范化结果；语言服务器仍会计算完整响应。

请参阅 DESIGN.md，了解协议和架构；请参阅 TODO.md，了解计划中的工作。

安装

语言服务器是独立程序；请安装已配置的语言服务器，并确保 MCP 宿主的环境可以访问它们。

预编译二进制文件

最新的 GitHub 发布版本提供适用于 x86-64 和 ARM64 Linux、Intel 和 Apple 芯片 macOS，以及 x86-64 Windows 的压缩包。Linux 发布版本同时包含 glibc 和静态 musl 构建。

在 Linux 或 macOS 上自动安装相应的发布版本：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jolars/deixis/releases/latest/download/deixis-installer.sh | sh

或者在 Windows 上使用 PowerShell：

powershell -ExecutionPolicy Bypass -c "irm https://github.com/jolars/deixis/releases/latest/download/deixis-installer.ps1 | iex"

安装程序会将 deixis 放入 Cargo 的二进制目录。每个发布版本还包含 SHA-256 校验和及 GitHub 构建证明。使用以下命令验证下载的压缩包：

gh attestation verify deixis-aarch64-apple-darwin.tar.xz --repo jolars/deixis

Nix

安装默认的 flake 软件包：

nix profile install github:jolars/deixis

或者直接运行，无需安装：

nix run github:jolars/deixis -- --root /path/to/project --config /path/to/config.toml

Cargo

需要 Rust 1.98.0 或更高版本：

cargo install deixis --locked

crates.io 软件包属于 MCP Registry 身份标识 mcp-name: io.github.jolars/deixis。

如需改为构建本地检出版本：

git clone https://github.com/jolars/deixis.git
cd deixis
cargo build --release --locked

生成的二进制文件为 target/release/deixis（Windows 上为 deixis.exe）。

配置语言服务器

从经过测试的示例配置开始，或定义单个服务器：

[servers.rust]
command = "rust-analyzer"
file_extensions = { ".rs" = "rust" }

使用 --config 显式传入文件，或将其安装为用户配置：

平台	未设置 XDG_CONFIG_HOME 时的默认路径
Linux 和其他 Unix	~/.config/deixis/config.toml
macOS	~/Library/Application Support/deixis/config.toml
Windows	%APPDATA%\deixis\config.toml

在所有平台上，只要设置了 $XDG_CONFIG_HOME，$XDG_CONFIG_HOME/deixis/config.toml 就会优先使用。显式指定的 --config 优先于用户配置。Deixis 不会在项目目录树中查找配置。

配置采用严格校验：未知字段、空命令、无效路由和取值为零的限制都会导致启动失败并报错。配置参考记录了每个字段、默认值、路由规则和进程限制。

连接 MCP 客户端

Deixis 是一个本地 stdio 服务。MCP 宿主必须直接启动二进制文件；不要用 shell 命令包装它。使用 --root 指定项目，或者在项目目录中启动 Deixis。根目录默认为当前工作目录，并在启动时规范化一次。

Codex

从命令行添加 Deixis：

codex mcp add deixis --env RUST_LOG=deixis=info -- /absolute/path/to/deixis --root /absolute/path/to/project --config /absolute/path/to/config.toml

也可以添加项目级 .codex/config.toml：

[mcp_servers.deixis]
command = "/absolute/path/to/deixis"
args = [
  "--root",
  "/absolute/path/to/project",
  "--config",
  "/absolute/path/to/config.toml",
]
tool_timeout_sec = 70

[mcp_servers.deixis.env]
RUST_LOG = "deixis=info"

宿主工具的 70 秒超时可满足默认的 30 秒 LSP 启动和请求限制，适用于首次工具调用时延迟启动服务器的情况。Codex 的 startup_timeout_sec 针对的是 Deixis MCP 握手，而不是下游语言服务器。有关宿主端所有选项，请参阅最新的 Codex MCP 文档。

基于 JSON 的 MCP 宿主

对于使用 mcpServers JSON 对象的宿主，请使用对应的 stdio 条目。有关配置文件位置，请查阅宿主文档。

{
  "mcpServers": {
    "deixis": {
      "command": "/absolute/path/to/deixis",
      "args": [
        "--root",
        "/absolute/path/to/project",
        "--config",
        "/absolute/path/to/config.toml"
      ],
      "env": {
        "RUST_LOG": "deixis=info"
      }
    }
  }
}

如果宿主无法继承交互式 shell 的 PATH，请使用绝对路径。配置的语言服务器命令也必须能在宿主环境中解析。

Home Manager

该 flake 提供 homeManagerModules.default。非空的类型化服务器目录会安装 Deixis、写入其用户配置，并在 programs.mcp.servers 中注册一条不绑定根目录的命令：

添加 flake 输入：

inputs.deixis = {
  url = "github:jolars/deixis";
  inputs.nixpkgs.follows = "nixpkgs";
};

然后导入并配置 Home Manager 模块：

{ inputs, ... }:

{
  imports = [ inputs.deixis.homeManagerModules.default ];

  programs.deixis = {
    enable = true;
    servers = {
      rust = {
        command = "rust-analyzer";
        fileExtensions.".rs" = "rust";
      };
      typescript = {
        command = "typescript-language-server";
        args = [ "--stdio" ];
        fileExtensions.".ts" = "typescript";
      };
    };
  };
}

生成的命令不固定根目录，因此每个 MCP 进程都会绑定到自己的工作目录。若要安装现有 TOML 文件，请设置 programs.deixis.configFile，而不要设置 servers。这两个选项不能同时使用。

操作

语言服务器仅在工具调用选择它们时启动。文件范围工具接受相对于项目的路径或位于根目录内的绝对 path，以及可选的已配置 server 名称。基于位置的工具还接受：

{ "line": 12, "character": 8 }

这两个值均从零开始；character 是 UTF-8 字节偏移量。如果多个服务器与某个文件匹配，请提供 server，或确保配置路由唯一。 signature_help 会返回服务器提供的所有签名及其结构化参数标签和文档。为保持 Agent 上下文简洁，其文本回退内容仅包含当前活动签名；如果服务器未选定签名，则包含第一个签名。

incoming_calls 和 outgoing_calls 接受 path、UTF-8 position 和可选的 server。它们会在内部准备调用层级，然后展开该位置返回的所有符号。calls 中的每个条目包含 from（调用方）、to（被调用方）和 fromRanges（from.uri 中的调用位置，使用 from.positionEncoding）。两个符号都包含其名称、种类、URI、范围、服务器和位置编码，以及服务器提供的任何详细信息或不透明数据。可读的项目文件使用 UTF-8；其他目标保留服务器编码。这些工具需要已协商的调用层级支持。准备、展开和重试共用一个请求超时时间。分页适用于所有返回的调用，每对调用方和被调用方计为一项。

如果未指定 server，workspace_symbols 会将请求分发给已连接且具备相应能力的服务器，不会启动其他服务器，并按稳定的服务器名称顺序合并结果。提供 server 可单独查询该服务器，并在必要时启动它。

成功调用会返回结构化 JSON 和简洁的文本回退内容。工具调用失败时，会返回带有稳定结构化错误代码的 isError: true。语义结果为 null 或为空时，也可能报告 readiness 和 resultStability；transient 结果表示语言服务器已表明仍在处理。

符号重命名特意设计为两步变更。默认情况下，可使用 prepare_rename 和 preview_rename 进行只读检查，但不会公布 apply_rename，也无法调用它。在配置 MCP 主机时，将 --allow-mutation 添加到 Deixis 命令中，以启用应用操作。然后使用文件、UTF-8 位置和 newName 调用 preview_rename；检查其按文件划分的结构化编辑和统一差异；再将其不透明的 previewId 传递给 apply_rename。预览不会修改文件。该 ID 仅授权执行完全匹配的预览，十分钟后过期，并会在首次应用尝试时被消耗，包括尝试失败的情况。再次应用必须创建新的预览。

重命名仅接受对不可变项目根目录内现有 UTF-8 文件的文本编辑。它会拒绝创建文件、删除文件、重命名操作、变更注释、外部路径、重叠编辑和过期的文件内容。应用操作会在提交任何文件之前暂存所有替换内容；如果提交失败，则会尝试恢复所有原始文件。这是在进程内进行的事务，并不保证断电后仍能完成；Deixis 不承诺在进程或机器崩溃后进行恢复。服务器发起的 workspace/applyEdit 请求仍会被拒绝，因为它们不包含明确的预览授权。

日志记录

Deixis 将 stdout 保留给 MCP 帧。其日志以及所有子进程的 stderr 都会写入 stderr。日志级别默认设为 deixis=info；在 MCP 主机的环境中设置 RUST_LOG 可更改过滤器：

RUST_LOG=deixis=debug

子进程和 LSP 日志事件会附带服务器名称。常规 info 日志不包含源代码内容或协议正文。有关启动、路由、超时、诊断和关闭故障，请参阅故障排除。

开发

此仓库固定使用 Rust 1.98.0。进入 devenv shell 后，会提供完整的工具链并安装 pre-commit 钩子：

devenv shell
task check

可选的兼容性测试套件使用 flake.lock 固定的版本，测试 TypeScript Language Server、Pyright、gopls、clangd 和 Deno：

task compatibility

如果不使用 Nix，请安装这五个服务，然后运行：

cargo test --test real_language_servers -- --ignored --test-threads=1

可使用 DEIXIS_TYPESCRIPT_LANGUAGE_SERVER、DEIXIS_PYRIGHT_LANGSERVER、DEIXIS_GOPLS、DEIXIS_CLANGD 和 DEIXIS_DENO 覆盖可执行文件路径。

Agent 基准测试会运行成对的 Codex 试验，分别测试 Deixis 可用或不可用，以及使用中性指令或 LSP 指向性指令的情况。测试会在隔离的 Git 工作树中记录任务成功情况、模型令牌数、耗时、MCP 调用、补丁和原始事件流。

完整的开发门禁要求请参阅 CONTRIBUTING.md。

许可证

您可以选择依据 Apache License, Version 2.0 或 MIT License 获得许可。