Claude Code 插件进阶（上）：代码智能插件实测，装之前怎么审，不工作怎么查

这篇教程解决三个问题：

Claude 改完代码，能不能像编辑器那样马上知道哪里类型不对？ 能，装一个代码智能插件。
装别人的插件之前，怎么知道它会在我机器上干什么？
插件装了没反应，从哪查起？

做一个插件分享给团队那篇讲的是怎么做插件。这篇站在用插件的人这边。

实测环境
日期	2026-10-12
版本	Claude Code 2.1.296，typescript-lsp 插件 1.0.0
系统	Ubuntu 24.04，Node.js 22
模型	Sonnet 5.5
连接方式	通过酷站AI 中转站，不是直连官方
示例	一个两个文件的 TypeScript 小项目

一、代码智能插件

它给 Claude 多了什么

没有它的时候，Claude 改完一个文件，并不知道自己有没有改出类型错误，要等你或它自己去跑一遍编译。找一个函数在哪被调用，靠的是文本搜索。

代码智能插件把一个语言服务器接给 Claude，就是编辑器里提供红色波浪线和“跳到定义”的那个东西。接上之后多了两样：

改完自动收到诊断。 Claude 每次编辑或写入一个文件，语言服务器报出的错误和警告会交到它手上：类型不对、少了 import、语法错误。
多一个 LSP 工具。 按符号去查定义、引用，不靠搜字符串。这个工具是只读的。

插件本身不带语言服务器。 它只告诉 Claude Code 用什么命令启动服务器、管哪些扩展名。服务器的程序要你自己装。

官方市场里现成的：

语言	插件	要装的程序
TypeScript 和 JavaScript	`typescript-lsp`	`typescript-language-server`
Python	`pyright-lsp`	`pyright-langserver`
Go	`gopls-lsp`	`gopls`
Rust	`rust-analyzer-lsp`	`rust-analyzer`
Java	`jdtls-lsp`	`jdtls`
C/C++	`clangd-lsp`	`clangd`
C#	`csharp-lsp`	`csharp-ls`
PHP	`php-lsp`	`intelephense`
Ruby	`ruby-lsp`	`ruby-lsp`
Kotlin、Swift、Lua、Liquid	`kotlin-lsp`、`swift-lsp`、`lua-lsp`、`liquid-lsp`	见各自的说明

安装

两步，顺序是先装程序、再装插件。

装语言服务器。 文档给 TypeScript 的命令是全局安装：

npm install -g typescript-language-server typescript

装完确认它在 PATH 上：which typescript-language-server。

本站的测试机不动系统目录，所以装在了示例目录里，启动 Claude Code 时把那个目录加到 PATH 前面：

PATH=~/demo/h7-lsp/tools/node_modules/.bin:$PATH claude

这种装法后面多踩了一个坑，下面会讲。

装插件。 会话里输入 /plugin install typescript-lsp@claude-plugins-official，或者在终端里：

claude plugin install typescript-lsp@claude-plugins-official --scope project

装完看一眼它里面有什么：

$ claude plugin details typescript-lsp
typescript-lsp 1.0.0
  Description: TypeScript/JavaScript language server for enhanced code intelligence

Component inventory
  Skills (0)
  Agents (0)
  Hooks (0)
  MCP servers (0)
  LSP servers (1)  typescript  (out-of-process tooling; no model context cost)

Projected token cost
  Always-on:   ~0 tok   added to every session

没有 skill、没有 hook，只声明了一个语言服务器。它不占上下文：服务器是在 Claude 之外运行的进程。

连踩三个坑

本站没有一次跑通。三个报错都是 LSP 工具返回给 Claude、再由 Claude 转述出来的。

坑一：程序不在 PATH 上。

Error performing workspaceSymbol: Command failed with ENOENT: typescript-language-server --stdio
Executable not found in $PATH: "typescript-language-server"

要留意的是，这时 LSP 工具照样出现在工具清单里（装插件前是 21 个工具，装完 22 个）。工具在，不代表服务器能启动。

坑二：项目里没有 TypeScript。

把程序放上 PATH 之后：

Could not find a valid TypeScript installation. Please ensure that the "typescript" dependency
is installed in the workspace or that a valid tsserver.path is specified.

语言服务器自己不带 TypeScript，它要在项目的 node_modules 里或者全局找一份。按文档全局安装的话两样都有了，不会碰到这一条。本站是装在别处的，项目里又没有，所以找不到。在项目里 npm install -D typescript 解决。

坑三：TypeScript 7 不行。

上面那条命令在测试当天装下来的是 7.0.2：

The TypeScript of the workspace (TypeScript 7.0.2 at ".../node_modules/typescript/lib") provides
no tsserver.js. No other valid TypeScript installation was found.

这个语言服务器要的是 tsserver.js，7.0.2 的包里没有这个文件。换成 5.x 就好了：

npm install -D typescript@5

本站装到的是 5.9.3，之后一切正常。如果你的项目已经升到了 TypeScript 7，这个插件目前配不上；本站没有去找替代的办法。

跑通之后：按符号找引用

让它“用 LSP 工具找出 lineTotal 的所有引用，不要用 grep”。它一共调了四次：

workspaceSymbol    query: "lineTotal"                按名字在整个项目里找符号
documentSymbol     src/price.ts                      列出这个文件里的符号
findReferences     src/price.ts 第 3 行第 17 列       从定义的位置找引用

结果是 2 处，都在 src/price.ts：第 3 行的定义，第 8 行的调用。和实际一致。

和文本搜索的差别在大项目里才明显：同名的函数、注释里出现的名字、字符串里的名字，文本搜索全都会搜出来，按符号找只给真正的引用。

跑通之后：诊断是“下一步”才到的

这是实测里最值得知道的一点。

先用非交互模式试：让它把一个函数的返回类型从 number 改成 string，函数体不动，然后问它有没有自动收到类型错误。没有。 四次都没有，包括服务器已经能正常工作的那一次。

换成交互会话，让它连着改两处：

● Update(src/price.ts)
  ⎿  Added 1 line, removed 1 line
      7 -export function orderTotal(items: Item[]): number {
      7 +export function orderTotal(items: Item[]): string {

● Step 1 is done, and the edit result came back with no diagnostics. Step 2: …

● Update(src/report.ts)
  ⎿  Added 1 line, removed 1 line
  ⎿  Found 1 new diagnostic issue in 1 file (ctrl+o to expand)

第一次编辑后没有诊断。第二次编辑后出现了那一行 Found 1 new diagnostic issue，而内容是关于第一次编辑的：

price.ts:
  ✘ [Line 8:3] Type 'number' is not assignable to type 'string'. [2322] (typescript)

Claude 自己也看出来了，原话是：“这是第一步造成的，不是第二步。第一步完成时我没有收到它，是在第二步之后才收到的。”

原因文档里有：语言服务器是在 Claude 第一次编辑这类文件时才启动的。启动、读项目、分析都要时间，结果赶不上当时那一次编辑，只能搭下一次工具调用的车回来。

所以：

只改一处就结束的任务，别指望它。 改完那一下很可能什么都没收到。
多步的任务里它才有用。 前面改出的错，后面几步之内会被送回来，Claude 接着就能修。
它不是编译器。 上面第二次编辑其实也引入了一个错误（string 上没有 toFixed），在会话结束之前没有被报出来。提交之前还是要跑一遍类型检查。

想自己看诊断的具体内容，在那一行上按 Ctrl+O。

另外几点（整理自文档）

推荐对话框。 如果机器上已经有某个语言服务器的程序、但没装对应的插件，Claude 编辑那种文件后可能弹出“LSP plugin recommendation”，问你要不要装。一个会话最多弹一次；连续五次不理它，以后就不再弹。
云端会话里没有。 Claude Code 在云端会话里不启动插件的语言服务器。
没有现成插件的语言，可以自己写一个只声明语言服务器的插件。

二、装别人的插件之前

先明白它能干什么

文档第一句话就很直接：你装的插件可以用你的用户权限在你的机器上执行任意代码。

一个插件里可能有这些东西：

组成	它会做什么
hooks	在 Claude Code 的各个时点运行 shell 命令
monitors	会话开始时自动在后台启动的 shell 命令
mod	在 Claude Code 进程里运行的 JavaScript，带着你的权限
MCP 服务器、语言服务器	Claude Code 替你启动的进程
`bin/` 目录	被加进 Bash 工具的 `PATH`，Claude 的命令可以直接运行里面的程序
skills、命令、子代理	以指令的形式进入 Claude 的上下文，影响它怎么用手上的工具

权限规则和沙箱管不到前四样。 文档写得很明确：权限规则和沙箱管的是 Claude 发起的工具调用，不是插件自己运行的代码。hooks、monitors、各种服务器进程，都是带着你的完整用户权限、在沙箱之外运行的。

还有一条容易忽略：自动更新。 市场开着自动更新的话，插件会在后台更新，你审过的那些文件可能已经变了。

市场的名字说明什么

市场分三档：官方、社区、第三方。官方和社区那几个名字（比如 claude-plugins-official）只认来自 github.com/anthropics/ 的仓库，别人冒充不了。同事或公司自己发布的市场都算第三方。

但文档提醒：市场的名字只说明目录是谁发布的，不说明里面每个插件干什么。哪个市场来的都要看。

先看你现在配了哪些市场、各自从哪来：

$ claude plugin marketplace list
Configured marketplaces:

  ❯ anthropic-plugin-directory
    Source: Built in (Anthropic Directory)

  ❯ claude-plugins-official
    Source: GitHub (anthropics/claude-plugins-official)

审一个插件的四步

一、在面板里看它声明了什么。 会话里 /plugin，选中那个插件，详情里有一节“Will install”，列出它的命令、子代理、skills、hooks、MCP 和语言服务器。

二、去看源码。 “Will install”只告诉你“有一个 hook”，不告诉你它运行什么。到插件的仓库里读这三处：

hooks/hooks.json：每个 hook 运行的命令；
.mcp.json：每个服务器的启动命令或地址；
bin/ 下的每一个文件。

三、不装，先让 Claude Code 读一遍。 把仓库克隆下来，用 --plugin-dir 指过去：

claude --plugin-dir <插件目录> plugin details <插件名>

本站拿之前做的示例插件试了：

express-kit 0.1.0
  Description: 团队在这个仓库上用的一套约定：提交说明的格式、测试评审员、改动记录

Component inventory
  Skills (1)  commit-message
  Agents (1)  test-reviewer
  Hooks (1)  PostToolUse  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~134 tok   added to every session

Per-component (rounded)
  component       always-on  on-invoke
  commit-message        ~70       ~270
  test-reviewer         ~60       ~160

这条命令不启动会话，只读文件。它列出了每个组件，hook 挂在哪个事件上，还估了这个插件要占多少上下文：每个会话固定多 134 个 token，skill 和子代理被用到时再各加一两百。

四、装完再看一次。 claude plugin details <插件名> 看的是装好的那一份，位置在 ~/.claude/plugins/cache/<市场>/<插件>/<版本>/。

不信任了，怎么清干净

claude plugin uninstall <插件> --scope <当初装的范围>

卸载之后有三样东西要留意：

缓存的文件还在。 文档说卸载后文件会在 ~/.claude/plugins/cache/ 下留 14 天，由后台清理。本站核对了：上一篇测完就卸载的 Claude Security 插件，它的 0.12.0 目录还在，760 KB。想立刻删干净，自己把那个目录删掉。
插件自己存的数据。 默认随卸载一起删。
市场。 连市场的主人也不信任了，就把市场也移除，从它装的所有插件会一并卸载。

三、插件不工作，从哪查

先看面板里的 Errors

/plugin 打开的面板有四个页签：

Plugins  Discover   Installed   Marketplaces   Errors

出了问题先翻到 Errors。文档说语言服务器的程序找不到时，这里会有一行 Executable not found in $PATH。

本站想复现这一条，没有成功：不带语言服务器启动，让 Claude 改了两个 .ts 文件，Errors 页显示的是 No plugin errors。回头看记录，那次 Claude 是用 shell 命令往文件末尾追加内容的，没有走编辑工具，语言服务器根本没被触发。同样的缺失，在让它直接调用 LSP 工具时是报了错的（上面的坑一）。

常见的几种

现象	原因和办法
输入 `/plugin` 得到 `/plugin isn't available in this environment`	你不在终端的交互会话里。非交互模式、Agent SDK、桌面应用和 VS Code 面板里都没有这个面板。改用终端里的 `claude plugin install <插件>@<市场>`
`Marketplace "claude-plugins-official" not found`	官方市场没注册上。`/plugin marketplace add anthropics/claude-plugins-official` 之后重试
装完提示 `Run /reload-plugins to apply.`	照做，或者重开会话
装了代码智能插件，但从来没见过诊断	按上面三个坑的顺序查：程序在不在 `PATH` 上，项目里有没有那门语言的工具链，版本对不对。直接让 Claude 调一次 `LSP` 工具，报错最清楚
按项目范围装了插件，别的工具说工作区不干净	安装会生成或修改 `.claude/settings.json`。提交它，或者加进 `.gitignore`。Claude Security 那篇里就是这个文件挡住了出补丁
语言服务器占内存太多、单仓库里误报	文档有专门的条目，见官方的插件排错页

官方的排错页是按“你看到的原话”组织的，从添加市场、安装、装了不工作到被组织策略拦住，分阶段列着。拿到报错原文去那页搜，比猜快。

终端里几条顺手的命令：

claude plugin list                  # 装了哪些、什么范围、启用没有
claude plugin details <插件>         # 里面有什么、占多少上下文
claude plugin marketplace list      # 市场从哪来
claude plugin validate <目录>        # 自己做的插件，结构对不对

通过中转站用，有什么不一样

这篇里的东西都在本机：语言服务器是本机进程，插件的安装和审查读的是本机文件。官方市场是从 GitHub 取的，和模型接口走哪里无关。本站没有碰到和中转站有关的问题。

这一趟花了多少

约 0.9 美元。八次非交互运行，每次 0.03 到 0.1 美元；两次交互会话合计约 0.25 美元。用的是 Sonnet 5.5。这是 Claude Code 按官方价格估算的数字，不是中转站实际扣的金额。

这次实测没有覆盖到的

只测了 TypeScript。 其他语言的插件装起来有什么坑，没有试。
语言服务器没有按文档的办法全局安装。 坑二是本站的装法带来的，全局安装不会遇到。
TypeScript 7 的项目怎么办，没有找到答案。
推荐对话框没有见到。
Errors 页签里出现真实报错的样子没有复现。
诊断“下一步才到”只观察了一次，延迟多久、会不会漏，没有系统地测。
审查部分的面板操作（Will install、打开主页）是文档的说法，本站实际运行的是终端里那几条命令。
组织层面的管控、mod 的信任问题没有涉及。