agent-lsp

English · 简体中文 · Русский · हिन्दी · العربية

面向 AI Agent 的代码智能基础设施。 65 个工具、32 种经 CI 验证的语言、24 个 Agent 工作流。单个 Go 二进制文件。

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp init

这是什么？

agent-lsp 是一个 MCP 服务，可将现有 LSP 服务（gopls、rust-analyzer、jdtls 等）编排为适用于 Agent 的工作流。

它不是 LSP 服务——而是一个编排层，用于管理语言服务，并通过 MCP 工具提供批量操作、推测式编辑和多步骤工作流。

架构：

• 语言服务（gopls、rust-analyzer 等）→ 提供代码智能
• agent-lsp（MCP 服务）→ 编排工作流，维持运行时热启动
• AI Agent → 通过 MCP 协议使用

为什么选择 agent-lsp？

持久的预热运行时
语言服务器会在 Agent 会话之间持续建立索引。首次会话：为工作区建立索引（典型项目约需 10 秒）。后续会话：即时可用。每次请求都无需承受冷启动开销。

批量操作
blast_radius → 一次调用即可返回所有导出项和所有调用方（区分测试与非测试代码）。如果没有编排，则需要依次调用 LSP 20 多次。

试探性编辑
simulate_edit → 在内存中预览更改，检查诊断差异，然后应用或丢弃。在修改磁盘文件前先测试编辑。

工作流编排
24 个技能，可将 LSP 操作串联成完整流程：

• /lsp-refactor → 影响分析 → 预览 → 应用 → 验证构建 → 运行测试
• /lsp-safe-edit → 预览 → 诊断差异 → 确认安全后应用
• /lsp-verify → LSP 诊断 → 构建 → 测试套件

单个会话支持多种语言
一个 agent-lsp 进程会将 .go 路由至 gopls，将 .ts 路由至 tsserver，将 .py 路由至 pyright。切换项目无需重新配置。会话会在不同文件和代码仓库之间持续保留。

提示

优化 Token 的输出： 工具响应采用 GCF 编码，而非 JSON。根据工具不同，Token 数量可减少 30-84%（启用会话去重时最高可减少 92.7%）。所有前沿模型的 LLM 理解率均为 100%；在复杂代码图中达到 91.2%，而 JSON 平均为 54.1%。各工具的实测节省量请见下文。

各组件如何协同工作： LSP（Language Server Protocol，语言服务器协议）是编辑器获取代码智能功能的方式：代码补全、诊断、跳转到定义。MCP（Model Context Protocol，模型上下文协议）是 Claude Code 等 AI 工具发现并调用外部工具的标准方式。agent-lsp 将两者连接起来：让 AI Agent 能够使用语言服务器提供的智能功能。

适用场景

• 构建 Agent 化代码生成系统
• 自动化大型代码库中的重构
• 需要以编程方式获取代码智能的 CI 工具
• 任何依次调用 LSP 过慢或过于复杂的工作流

Agent 的评价

我们让 AI Agent 针对 10 项编码任务（查找调用方、安全重命名、预览编辑、检测死代码）评估 agent-lsp，并撰写真实评价。四种不同的模型，四份独立的评估，结论一致：

Claude (Opus 4.6)：“对于涉及重构、影响分析或安全编辑的任何工作流，我都会推荐 agent-lsp。最出色的工具是 blast_radius（一次调用即可分析影响范围，并区分测试与非测试代码；用 grep 复现需要 5-10 条命令）、go_to_implementation（经过类型检查的接口实现关系，grep 根本无法做到），以及模拟会话工作流（无需接触磁盘即可进行试探性类型检查，而 grep/read 都无法做到这一点）。”

Cursor (auto)：“对于大型重构和代码导航，我会推荐 agent-lsp，因为重命名、引用、实现、调用层级和模拟工具能减少大量脆弱的 grep/手动编辑工作，让更改更安全。”

GPT-5.5 (via Codex)：“对于符号感知类工作，我会推荐 agent-lsp：查找引用和实现、预览重命名、查看诊断以及分析大型文件结构，都比 grep/read 循环快得多，也不容易出错。”

Gemini 2.5 Pro (via Gemini CLI)：“我会强烈推荐 agent-lsp，因为它提供了标准文本搜索工具无法企及的语义理解能力。它能够高置信度地重命名、查找接口实现，并在不写入磁盘的情况下预览编辑对诊断的影响，从而显著降低引入回归问题的风险。”

经过测试，而非凭空假设

其他 MCP-LSP 实现都在配置文件中列出支持的语言。它们没有一个会在 CI 中运行实际的语言服务器来验证其是否正常工作。

每次推送时，agent-lsp CI 都会针对真实的代码样例库运行 32 个真实语言服务器：Go、Python、TypeScript、Rust、Java、C、C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Zig、Lua、Elixir、Gleam、Clojure、Dart、Terraform、Nix、Prisma、SQL、MongoDB、MQL 等。我们说“兼容 gopls”时，这是经过验证的自动化结论，而非一厢情愿。

推测执行

在写入磁盘之前，先在内存中模拟更改。其他 MCP-LSP 实现都不具备此功能。

preview_edit 可预览任意编辑对诊断的影响。在文件被修改之前，你就能准确看到哪些内容会出问题。simulate_chain 会评估一系列相互依赖的编辑（重命名函数、更新所有调用方、更改返回类型），并报告哪个步骤最先引入错误。

8 个推测执行工具。完整工作流请参阅 docs/guide/speculative-execution.md。

节省 Token

在相同任务中，结构化 LSP 响应比 grep/read 少用 5-34 倍 Token。在 HashiCorp Consul（319K 行代码）上，影响范围分析使用 grep 时为 17.7MB，使用 LSP 时为 841KB，工具调用次数也从 5,534 次降至 119 次。代码库越大，节省越多。五个代码库的完整实验请参阅 docs/guide/token-savings.md。

Token 优化输出（GCF）

工具响应采用 GCF（Graph Compact Format） 编码，而非 JSON。GCF 消除了字段名称重复、标识符重复以及每条记录的结构开销。

分组/嵌套响应（例如某个符号下的调用方、带相关信息的诊断）也会转换为表格格式；对于这类结构，相比 JSON 可节省约 14%（详情）。

GCF 默认启用。要恢复为 JSON：

export AGENT_LSP_OUTPUT_FORMAT=json

基准测试：go run scripts/gcf-benchmark.go。架构详情请参阅 docs/guide/gcf-integration.md。

GCF： gcformat.com · 规范 · Go · Python · TypeScript · 演练场

编排为何重要

AI Agent 会做出错误的代码更改，因为它们看不到全貌：谁调用了这个函数、重命名后会有什么影响、构建是否仍能通过。语言服务器掌握着这些答案，但原始 LSP 工具需要 20 次以上的连续调用和复杂的编排逻辑。

agent-lsp 通过将正确的多步骤操作整合为单次调用和技能来解决这一问题。blast_radius 一次调用即可完成 Agent 原本需要 20 次以上调用才能完成的工作。/lsp-refactor 会将影响分析 → 预览 → 应用 → 验证 → 测试串联起来，无需针对每条提示词进行编排。

持久守护进程模式

Python 和 TypeScript 项目需要数分钟的后台索引时间，find_references 才能正常工作。agent-lsp 会自动启动一个持久守护进程代理，在会话之间持续运行，使工作区保持已索引状态。首次会话：守护进程启动并建立索引（FastAPI 约需 10 秒）。后续会话：立即连接到已预热的守护进程。空闲 30 分钟后自动退出。Go、Rust 等索引速度快的语言则完全绕过此模式（零开销）。

阶段强制执行

技能会告知 Agent 正确的操作顺序。阶段强制执行让运行时阻止违规操作，而不是相信 Agent 会遵循指示。

当 Agent 激活一项技能时，系统会根据当前阶段的权限检查每次工具调用。在影响范围分析期间调用 apply_edit 不会悄悄继续，而是会返回错误，并提供具体的恢复指导（“请先完成 blast_radius 阶段，可用工具：[blast_radius, find_references]”）。当 Agent 调用后续阶段的工具时，阶段会自动推进。

没有其他 MCP 工具提供方会在运行时强制执行工作流顺序。请参阅 docs/guide/phase-enforcement.md。

并发分析

检查器包含 4 项并发检查，适用于 4 类并发模型中的 25 种语言（goroutine、线程、async、actor）：

• 未恢复的并发入口：未进行恢复处理的 goroutine／线程／任务
• 未检查的共享状态：对 sync.Map、ConcurrentHashMap 进行裸类型断言
• 通道从未关闭：已创建但从未关闭的通道／队列（会导致 goroutine 泄漏）
• 共享字段缺少同步：从并发上下文访问字段时未进行同步

如果父类型有互斥锁，blast_radius 会为符号添加 sync_guarded: true 标注。使用 cross_concurrent: true 的 find_callers 会追踪跨越 goroutine／线程边界的调用链。/lsp-concurrency-audit 技能会针对任意类型生成字段级安全报告。

自动诊断

符号编辑工具（replace_symbol_body、insert_after_symbol、insert_before_symbol、safe_delete_symbol）会自动返回 errors_after 和 warnings_after 计数。无需单独调用 get_diagnostics，Agent 就能立即知道编辑是否导致了问题。

safe_apply_edit 会在一次调用中结合预览和应用：先试探性预览，只有在 net_delta == 0（没有新增错误）时才会将更改应用到磁盘。只需调用一次工具，而不是三次。

兼容

请参阅 docs/getting-started/mcp-clients.md 获取可直接复制粘贴的配置。

技能

原始工具会被忽略，技能则会被使用。每项技能都规定了正确的工具调用顺序，让工作流能够实际运行，无需为每个提示词编写编排指令。技能可作为 AgentSkills 斜杠命令使用，也可通过 prompts/list / prompts/get 作为 MCP 提示词提供给任何 MCP 客户端。

完整说明和使用指南请参阅 docs/guide/skills.md。

更改任何内容之前

安全编辑

开始使用

了解不熟悉的代码

编辑之后

生成代码

完整工作流

Docker

Stdio 模式（MCP 客户端直接启动容器）：

# Go
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:go go:gopls

# TypeScript
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:typescript typescript:typescript-language-server,--stdio

# Python
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:python python:pyright-langserver,--stdio

HTTP 模式（持久服务，远程客户端通过 HTTP+SSE 连接）：

docker run --rm \
  -p 8080:8080 \
  -v /your/project:/workspace \
  -e AGENT_LSP_TOKEN=your-secret-token \
  ghcr.io/blackwell-systems/agent-lsp:go \
  --http --port 8080 go:gopls

镜像默认以非 root 用户（uid 65532）运行。通过环境变量设置 AGENT_LSP_TOKEN，切勿在命令行中使用 --token。镜像也镜像到了 Docker Hub（blackwellsystems/agent-lsp）。完整标签列表、HTTP 模式设置和安全强化选项请参阅 DOCKER.md。

设置

步骤 1：安装 agent-lsp

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh

brew install blackwell-systems/tap/agent-lsp

# PowerShell (no admin required)
iwr -useb https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.ps1 | iex

# Scoop
scoop bucket add blackwell-systems https://github.com/blackwell-systems/agent-lsp
scoop install blackwell-systems/agent-lsp

# Winget
winget install BlackwellSystems.agent-lsp

# pip
pip install agent-lsp

# npm
npm install -g @blackwell-systems/agent-lsp

# Go install
go install github.com/blackwell-systems/agent-lsp/cmd/agent-lsp@latest

为你的技术栈安装相应的服务器。常见的有：

完整的 32 种受支持语言列表见 docs/reference/language-support.md。

步骤 3：验证设置

agent-lsp doctor

探测每个已配置的语言服务器并报告其功能。继续之前，请修复所有故障。安装命令和特定服务器的说明，请参阅语言支持。

步骤 4：配置你的 AI 工具

agent-lsp init

检测 PATH 中的语言服务器，询问你使用哪种 AI 工具，写入正确的 MCP 配置，并为你的 AI 提供方安装技能感知规则（Claude Code 使用 CLAUDE.md，Cursor 使用 .cursor/rules/，Cline 使用 .clinerules，Windsurf 使用 .windsurfrules，Gemini CLI 使用 GEMINI.md，Pi 使用 AGENTS.md）。用于 CI 或脚本化场景：agent-lsp init --non-interactive。

对于 Pi，请选择项目（9）或全局（10）目标。Pi 没有内置 MCP 支持；init 会写入共享的标准 MCP 文件，供 pi-mcp-adapter 包读取——项目 .mcp.json（与 Claude Code 使用的文件相同，因此一份配置即可供两者使用）或全局 ~/.config/mcp/mcp.json。技能感知规则会写入 AGENTS.md（项目）或 ~/.pi/agent/AGENTS.md（全局）。使用 pi install npm:pi-mcp-adapter 安装一次适配器即可。

一条命令完成全部设置

添加 --with-skills，同时安装内置技能文件（无需克隆仓库）：

agent-lsp init --with-skills

技能会写入与所选目标对应的位置：只有 Pi 项目目标（9）使用与工具无关的 .agents/skills/ 目录（可随仓库一同版本管理）；Pi 全局目标（10）使用 ~/.pi/agent/skills/；Claude Code 目标（1/2）使用 ~/.claude/skills/；Cursor（4）使用 ~/.cursor/skills/；Gemini CLI（7）使用 ~/.config/gemini-cli/skills/。对于没有经验证的技能目录的提供方，系统会跳过安装，并提示使用 skills/install.sh --dest。重新运行会覆盖受管理的技能文件，使其与已安装的二进制文件保持同步。agent-lsp uninstall 会将其移除。

生成的配置如下：

{
  "mcpServers": {
    "lsp": {
      "type": "stdio",
      "command": "agent-lsp",
      "args": [
        "go:gopls",
        "typescript:typescript-language-server,--stdio",
        "python:pyright-langserver,--stdio"
      ]
    }
  }
}

每个参数的格式为 language:server-binary（服务器参数以逗号分隔）。

步骤 5：安装技能

git clone https://github.com/blackwell-systems/agent-lsp.git /tmp/agent-lsp-skills
cd /tmp/agent-lsp-skills/skills && ./install.sh --copy

也可以完全跳过克隆：agent-lsp init --with-skills 会将相同的内置技能安装到与你所选目标对应的位置。

技能是复制到 AI 工具配置中的提示词文件。--copy 表示之后可以安全删除克隆的仓库。脚本默认使用 ~/.claude/skills/；对于其他 Agent，请传入 --dest，例如 Pi 使用 --dest ~/.pi/agent/skills。它还会在现有指令文件（~/.claude/CLAUDE.md、项目 AGENTS.md、~/.pi/agent/AGENTS.md、GEMINI.md）中追加受管理的技能表。

技能也可作为 MCP 提示词使用：任何 MCP 客户端都可以通过 prompts/list 发现这些技能，并通过 prompts/get 获取完整的工作流说明，无需手动安装。install.sh 路径适用于兼容 AgentSkills 的客户端（Claude Code 斜杠命令、Pi /skill:name 命令）。

步骤 6：允许工具权限（Claude Code）

对于 Claude Code，将 mcp__lsp__* 添加到权限允许列表，这样所有 65 个工具都无需逐个批准即可使用：

// ~/.claude/settings.json
{
  "permissions": {
    "allow": ["mcp__lsp__*"]
  }
}

如果不这样做，Claude Code 会在每次调用工具时请求权限。其他 MCP 客户端处理权限的方式各不相同；请查阅客户端文档。

Skills 是编码可靠流程的多工具工作流：编辑前检查影响范围、写入前预览、变更后运行测试。完整列表请参见 docs/guide/skills.md。

步骤 7：开始工作

AI Agent 会自动调用工具。首次调用会初始化工作区：

start_lsp(root_dir="/your/project")

这是 Agent 执行的操作，无需你输入。之后即可使用 65 个工具中的任意一个。会话会保持热启动；切换文件时无需重启。

agent-lsp 的独特之处

使用场景

• 多项目会话：将 AI 指向 ~/code/，无需重新配置即可跨项目工作
• 多语言开发：在一个会话中处理 Go 后端、TypeScript 前端和 Python 脚本
• 大型单体仓库：一个服务处理所有语言，并按文件扩展名路由
• 代码迁移：借助完整的跨仓库引用跟踪，在多个仓库间重构
• CI 流水线：根据真实语言服务器行为进行验证
• 小众语言技术栈：Gleam、Elixir、Prisma、Zig、Clojure、Nix、Dart、Scala、MongoDB，均经 CI 验证

多语言支持

支持 32 种语言，每次 CI 运行都会针对真实语言服务器进行端到端 CI 验证。其他 MCP-LSP 实现都不会在 CI 中测试任何一种语言。

Go、Python、TypeScript、Rust、Java、C、C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Zig、Lua、Elixir、Gleam、Clojure、Dart、Terraform、Nix、Prisma、SQL、MongoDB、JavaScript、YAML、JSON、Dockerfile、CSS、HTML、MQL。

完整的覆盖矩阵请参见 docs/reference/language-support.md。

工具

65 个工具，涵盖导航、分析、重构、符号编辑、组合式探索、安全编辑、推测执行和会话生命周期。所有工具均经 CI 验证。

完整参考（含参数和示例）请参见 docs/reference/tools.md。

延伸阅读

文档

• 工具参考：完整的工具参考，含参数和示例
• Skills 参考：skills 参考、工作流、使用场景和组合方式
• 语言支持：语言覆盖矩阵
• 架构：系统设计和内部实现
• 推测执行：先模拟再应用的工作流
• LSP 一致性：LSP 3.17 规范覆盖情况
• Docker：Docker 标签、compose 和卷缓存

贡献

• CI 说明：CI 特殊情况和测试框架详情
• 分发方式：安装渠道和发布流水线

开发

git clone https://github.com/blackwell-systems/agent-lsp.git
cd agent-lsp && go build ./...
go test ./...                   # unit tests
go test ./... -tags integration # integration tests (requires language servers)

库的使用方式

pkg/lsp、pkg/session 和 pkg/types 包提供稳定的 Go API，可直接使用 agent-lsp 的 LSP 客户端，无需运行 MCP 服务。

import "github.com/blackwell-systems/agent-lsp/pkg/lsp"

client := lsp.NewLSPClient("gopls", []string{})
client.Initialize(ctx, "/path/to/workspace")
defer client.Shutdown(ctx)

locs, err := client.GetDefinition(ctx, fileURI, lsp.Position{Line: 10, Character: 4})

完整的包 API 请参阅 docs/architecture/architecture.md。

许可证

MIT