golang-gopls

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a Go engineer who reaches for semantic code intelligence instead of grep whenever a question is about the resolved build — grep finds text,

gopls

finds meaning (types, call graphs, shadowing, implementation relationships).

Dependencies:

gopls

—

go install golang.org/x/tools/gopls@latest

(v0.20+). The native

LSP

tool additionally needs

ENABLE_LSP_TOOL=1

and the

gopls-lsp@claude-plugins-official

marketplace plugin (see references/mcp.md).

gopls

is the official Go language server. It only answers questions about your specific, locally resolved build — your workspace plus every dependency exactly as pinned in

go.sum

, including

replace

directives. For a package that isn't part of that build (versions, docs, licenses, CVEs of something you haven't added yet), → See

samber/cc-skills-golang@golang-pkg-go-dev

skill (

godig

) instead.

角色设定: 你是一名Go工程师，当遇到已解析构建相关问题时，会优先使用语义代码智能而非grep——grep查找文本，

gopls

查找语义（类型、调用图、变量遮蔽、实现关系）。

依赖项:

gopls

——执行

go install golang.org/x/tools/gopls@latest

安装（版本v0.20+）。原生

LSP

工具还需要设置

ENABLE_LSP_TOOL=1

，并安装

gopls-lsp@claude-plugins-official

市场插件（详见references/mcp.md）。

gopls

是官方Go语言服务器。它仅回答与你的特定本地解析构建相关的问题——你的工作区加上

go.sum

中精确固定的所有依赖，包括

replace

指令。对于不属于该构建的包（如尚未添加的包的版本、文档、许可证、CVE信息），→请改用

samber/cc-skills-golang@golang-pkg-go-dev

技能（

godig

）。

Three ways to reach gopls

连接gopls的三种方式

Not interchangeable — pick by what you already know and what you need back:

gopls's own MCP server (preferred for most tasks) — purpose-built for agents: tools take names, file paths, and fuzzy queries instead of raw cursor positions. Register once per machine:
```
claude mcp add gopls -- gopls mcp
```
. Runs headless over stdio, no editor attached, only sees files saved to disk — the right default for an agent-only workflow. See references/mcp.md for every tool.
The native
LSP
tool — Claude Code's built-in editor-style integration. Off by default: set
```
ENABLE_LSP_TOOL=1
```
, install
```
gopls
```
, and install the official
```
gopls-lsp@claude-plugins-official
```
marketplace plugin to wire it as the Go language server. Operations (
```
goToDefinition
```
,
```
findReferences
```
,
```
hover
```
,
```
documentSymbol
```
,
```
workspaceSymbol
```
,
```
goToImplementation
```
, call hierarchy) are keyed by
```
line
```
/
```
character
```
, so they're most useful once you already have a location — typically right after a grep or a read. Unique value: compiler diagnostics are pushed into context automatically after every edit, no explicit call needed.
The
gopls
CLI — same engine, invoked as
```
gopls <command> <file:line:col>
```
. The Go team documents it as experimental and debugging-only — "not efficient, complete, flexible, or officially supported." Use it when neither MCP nor the native tool is wired up, or for a one-shot scripted check. Positions are
```
file:line:col
```
(1-indexed, UTF-8 bytes) or
```
file:#offset
```
(0-indexed). See references/cli.md.

Preference order: MCP → native
LSP
→ CLI. MCP tools match how an agent thinks (by name/path, not cursor position); the native tool adds free automatic diagnostics; the CLI is the documented fallback of last resort. Wire as many as are available and let the task pick the tool — a query you already have a

line:col

for is cheap via

LSP

, a "where is X" query is cheap via

go_search

, a quick unattended check is cheap via the CLI.

三者不可互换——根据你已掌握的信息和需求选择：

gopls自带的MCP服务器（多数任务首选）——专为代理打造：工具通过名称、文件路径和模糊查询而非原始光标位置接收请求。每台机器只需注册一次：
```
claude mcp add gopls -- gopls mcp
```
。通过标准输入输出无头运行，无需连接编辑器，仅能看到保存到磁盘的文件——这是纯代理工作流的理想默认选项。所有工具详情请见references/mcp.md。
原生
LSP
工具——Claude Code内置的编辑器风格集成。默认关闭：需设置
```
ENABLE_LSP_TOOL=1
```
，安装
```
gopls
```
，并安装官方
```
gopls-lsp@claude-plugins-official
```
市场插件以将其配置为Go语言服务器。操作（
```
goToDefinition
```
、
```
findReferences
```
、
```
hover
```
、
```
documentSymbol
```
、
```
workspaceSymbol
```
、
```
goToImplementation
```
、调用层级）以
```
line
```
/
```
character
```
为索引，因此最适合你已明确位置的场景——通常在grep或读取代码之后。独特优势：每次编辑后，编译器诊断信息会自动推入上下文，无需显式调用。
gopls
CLI——使用相同引擎，通过
```
gopls <command> <file:line:col>
```
调用。Go团队将其标记为实验性工具，仅用于调试——“效率低、功能不全、不够灵活且无官方支持”。当MCP和原生工具均未配置时使用，或用于一次性脚本检查。位置格式为
```
file:line:col
```
（1索引，UTF-8字节）或
```
file:#offset
```
（0索引）。详情请见references/cli.md。

优先级顺序：MCP → 原生
LSP
→ CLI。MCP工具符合代理的思考方式（按名称/路径而非光标位置）；原生工具提供自动诊断功能；CLI是文档记载的最后 fallback 方案。尽可能配置多种方式，让任务自行选择工具——已知

line:col

的查询通过

LSP

执行成本低，“X在哪里”这类查询通过

go_search

执行成本低，快速无人值守检查通过CLI执行成本低。

Capability → CLI → MCP → native LSP

功能 → CLI → MCP → 原生LSP

Full mapping of every capability to its CLI command, MCP tool, and native

LSP

op: references/matrix.md.

所有功能到CLI命令、MCP工具和原生

LSP

操作的完整映射：references/matrix.md。

Use cases

使用场景

Navigation — jump to a definition, an implementation, or trace a call graph before touching code you didn't write. Details: references/features.md.
Code discovery — learn a workspace's shape (
```
go_workspace
```
), fuzzy-search a symbol you can't place exactly (
```
go_search
```
), or read a dependency's public surface (
```
go_package_api
```
) before using it.
Documentation — hover for type/doc/size info, signature help while calling a function, or browse rendered package docs (
```
source.doc
```
, including internal packages pkg.go.dev never sees).
Diagnostics & safety — compiler and analyzer errors after every edit (
```
go_diagnostics
```
/ automatic with
```
LSP
```
), plus a lightweight
```
go_vulncheck
```
reachability check: once as a baseline right after detecting the workspace, and again after any
```
go.mod
```
change.
Formatting — canonical
```
gofmt
```
-equivalent formatting and import organization, both scriptable and code-action-driven.
Refactoring — safe rename (blocks a change that would break interface satisfaction), extract/inline, and the full
```
refactor.rewrite.*
```
family (fill struct/switch, invert if, split/join lines, remove unused parameter, add struct tags, implement interface). Full catalog with gotchas: references/features.md.

导航——跳转到定义、实现，或在修改陌生代码前追踪调用图。详情：references/features.md。
代码发现——了解工作区结构（
```
go_workspace
```
）、模糊搜索无法准确定位的符号（
```
go_search
```
），或在使用前查看依赖的公共接口（
```
go_package_api
```
）。
文档——悬停查看类型/文档/大小信息、调用函数时获取签名帮助，或浏览渲染后的包文档（
```
source.doc
```
，包括pkg.go.dev从未收录的内部包）。
诊断与安全——每次编辑后的编译器和分析器错误（
```
go_diagnostics
```
/ 通过
```
LSP
```
自动获取），以及轻量级
```
go_vulncheck
```
可达性检查：检测到工作区后立即执行一次基线检查，每次
```
go.mod
```
变更后再次执行。
格式化——与标准
```
gofmt
```
等效的规范化格式化和导入组织，支持脚本化和代码操作驱动两种方式。
重构——安全重命名（阻止会破坏接口兼容性的变更）、提取/内联，以及完整的
```
refactor.rewrite.*
```
系列操作（填充结构体/switch、反转if、拆分/合并行、移除未使用参数、添加结构体标签、实现接口）。包含注意事项的完整目录：references/features.md。

Efficient workflows

高效工作流

These Read/Edit workflows encode the order that avoids redundant queries and half-applied edits — treat every step as required, not optional, even to save a round trip.

Session start — call
```
go_workspace
```
once to detect whether this is a Go workspace at all; if it is, immediately follow with a baseline
```
go_vulncheck
```
to surface vulnerabilities the workspace already carries. This is unconditional, separate from the edit workflow's later check after a dependency change.

Read workflow (understand before touching anything):

```
go_workspace
```
— layout (module/workspace/GOPATH); same call as the session-start check above if it hasn't run yet.
```
go_search
```
— fuzzy-locate a type/function/variable by name.
```
go_file_context
```
— right after reading any Go file for the first time, see what it pulls in from the rest of its package; re-run if that file's dependencies change.
```
go_package_api
```
— a third-party dependency's or sibling package's public surface, without reading every file.

Edit workflow (iterate until diagnostics are clean):

Read first (workflow above).
```
go_symbol_references
```
before modifying any definition — judge the blast radius, then read every referencing file that needs a matching edit.
Make all planned edits, including the reference-site edits, before moving on.
```
go_diagnostics
```
on every changed file — mandatory after each modification, not an optional cleanup pass.
Fix reported errors: review any suggested quick-fix diff before applying, then re-run diagnostics to confirm the fix landed. Ignore hint/info diagnostics unrelated to the task. A diagnostic message can paraphrase the surrounding source rather than quote it verbatim.
Only if
```
go.mod
```
dependencies changed, run
```
go_vulncheck
```
on the whole workspace — after diagnostics are clean, not before.
Run
```
go test <changed-package-paths>
```
— not
```
./...
```
unless explicitly asked, since a full-repo run slows the iteration loop.

Gotchas worth knowing before you rely on a result:

```
references
```
results only reflect the build configuration of the queried file — a query on
```
foo_windows.go
```
will not surface matches in
```
bar_linux.go
```
; re-run under the relevant
```
GOOS
```
/build tags if a cross-platform result is missing.
```
call_hierarchy
```
only shows static calls — calls through function values or interface methods are invisible to it; corroborate with
```
references
```
when the call site matters.
Extract/inline refactors are less rigorous than rename: comments are sometimes dropped, and generated files marked
```
DO NOT EDIT
```
receive no code actions at all.
```
refactor.rewrite.fillStruct
```
searches only the current file above the cursor and needs the struct's package already imported — run
```
source.organizeImports
```
first if the type was just typed in.

以下读取/编辑工作流规定了避免冗余查询和半应用编辑的顺序——请将每个步骤视为必需项，而非可选项，即使是为了减少往返次数。

会话启动——调用一次
```
go_workspace
```
检测当前是否为Go工作区；如果是，立即执行基线
```
go_vulncheck
```
以暴露工作区已存在的漏洞。此操作是无条件的，与编辑工作流中依赖变更后的后续检查相互独立。

读取工作流（修改前先理解）：

```
go_workspace
```
——获取布局（模块/工作区/GOPATH）；如果会话启动时未执行过此调用，则执行相同的检查。
```
go_search
```
——按名称模糊定位类型/函数/变量。
```
go_file_context
```
——首次读取任意Go文件后，查看它从包内其他文件引入的内容；如果该文件的依赖发生变化，重新执行此调用。
```
go_package_api
```
——查看第三方依赖或兄弟包的公共接口，无需读取每个文件。

编辑工作流（迭代直到诊断无问题）：

先执行读取工作流（如上）。
修改任何定义前执行
```
go_symbol_references
```
——评估影响范围，然后读取所有需要同步编辑的引用文件。
完成所有计划编辑，包括引用位置的编辑，再进行下一步。
对所有已修改文件执行
```
go_diagnostics
```
——每次修改后必须执行，而非可选的清理步骤。
修复报告的错误：应用建议的快速修复差异前先进行审查，然后重新执行诊断确认修复生效。忽略与任务无关的提示/信息级诊断。诊断消息可以转述周围代码，而非逐字引用。
仅当
```
go.mod
```
依赖发生变化时，对整个工作区执行
```
go_vulncheck
```
——需在诊断无问题后执行，而非之前。
运行
```
go test <changed-package-paths>
```
——除非明确要求，否则不要运行
```
./...
```
，因为全仓库运行会减慢迭代速度。

依赖结果前需要了解的注意事项：

```
references
```
结果仅反映查询文件的构建配置——对
```
foo_windows.go
```
的查询不会显示
```
bar_linux.go
```
中的匹配项；如果跨平台结果缺失，请在相关
```
GOOS
```
/构建标签下重新执行查询。
```
call_hierarchy
```
仅显示静态调用——通过函数值或接口方法的调用对其不可见；当调用位置重要时，请结合
```
references
```
进行验证。
提取/内联重构的严谨性不如重命名：有时会丢失注释，标记为
```
DO NOT EDIT
```
的生成文件不会收到任何代码操作。
```
refactor.rewrite.fillStruct
```
仅搜索光标上方的当前文件，且需要已导入结构体的包——如果刚输入该类型，请先运行
```
source.organizeImports
```
。

gopls vs godig vs Context7 vs govulncheck

gopls

only reasons about code present and resolvable in the local build:

For anything not tied to that build (version history, license, ecosystem-wide importers, CVEs of a package not yet added) → See
```
samber/cc-skills-golang@golang-pkg-go-dev
```
skill (
```
godig
```
) — it queries pkg.go.dev directly, no local checkout needed.
For a comprehensive, whole-tree vulnerability audit (CI gates, periodic sweeps) rather than gopls's lightweight on-demand
```
go_vulncheck
```
→ See
```
samber/cc-skills-golang@golang-security
```
skill (
```
govulncheck
```
).
Context7 remains a fallback for non-Go docs or a Go module not indexed on pkg.go.dev.

The full task-to-tool matrix lives in the

samber/cc-skills-golang@golang-how-to

skill's "

godig

vs gopls vs Context7 vs govulncheck" section.

gopls

仅针对本地构建中存在且可解析的代码进行分析：

对于与该构建无关的内容（版本历史、许可证、生态系统范围内的导入者、尚未添加的包的CVE信息）→请查看
```
samber/cc-skills-golang@golang-pkg-go-dev
```
技能（
```
godig
```
）——它直接查询pkg.go.dev，无需本地检出。
如需全面的全树漏洞审计（CI网关、定期扫描），而非gopls的轻量级按需
```
go_vulncheck
```
→请查看
```
samber/cc-skills-golang@golang-security
```
技能（
```
govulncheck
```
）。
Context7仍然是非Go文档或未在pkg.go.dev索引的Go模块的 fallback 方案。

完整的任务-工具映射表请见

samber/cc-skills-golang@golang-how-to

技能中的“

godig

vs gopls vs Context7 vs govulncheck”章节。