golang-gopls

角色： 你是一名 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）。

使用 gopls 的三种方式

这几种方式不能互换——根据你已知的信息和需要的结果来选择：

• gopls 自带的 MCP 服务（大多数任务的首选） — 专为 Agent 打造：工具接受名称、文件路径和模糊查询，而不是原始光标位置。每台机器只需注册一次：claude mcp add gopls -- gopls mcp。通过 stdio 无头运行，不需要连接编辑器，只能看到已保存到磁盘的文件——这是仅使用 Agent 的工作流的理想默认方式。所有工具请参见 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 工具符合 Agent 的思维方式（按名称/路径，而不是光标位置）；原生工具会自动提供免费的诊断信息；CLI 是文档明确记载的最后备用方案。尽可能配置所有可用方式，让任务选择工具——已有 line:col 的查询用 LSP 处理很方便，“X 在哪里”的查询用 go_search 处理很方便，快速的无人值守检查用 CLI 处理很方便。

能力 → CLI → MCP → 原生 LSP

每项能力对应的 CLI 命令、MCP 工具和原生 LSP 操作的完整映射： references/matrix.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。

高效工作流

这些 Read/Edit 工作流规定了可避免冗余查询和只完成一半的编辑的顺序——请将每一步都视为必需步骤，不要为了省一次往返而跳过。

• 会话开始 — 调用一次 go_workspace，检测这是否为 Go 工作区；如果是，立即接着运行基线检查 go_vulncheck，以发现工作区已有的漏洞。此步骤无条件执行，且独立于编辑工作流中依赖变更后的检查。

读取工作流（先理解，再动手）：

1. go_workspace — 查看布局（模块／工作区／GOPATH）；如果尚未运行，则与上述会话开始检查使用同一次调用。
2. go_search — 按名称模糊查找类型／函数／变量。
3. go_file_context — 首次读取任何 Go 文件后立即调用，查看它从所属包的其他部分引入了什么；如果该文件的依赖发生变化，则重新运行。
4. go_package_api — 查看第三方依赖或同级包的公共接口，而不必读取每个文件。

编辑工作流（持续迭代，直到诊断通过）：

1. 先读取（使用上述工作流）。
2. 修改任何定义前先运行 go_symbol_references — 判断影响范围，然后读取所有需要配套修改的引用文件。
3. 完成所有计划中的编辑，包括引用位置的编辑，然后再继续。
4. 对每个已修改文件运行 go_diagnostics — 每次修改后都必须运行，不是可选的清理步骤。
5. 修复报告的错误：应用任何建议的快速修复前先检查其差异，然后重新运行诊断，确认修复已生效。忽略与任务无关的提示／信息级诊断。诊断消息可能会转述周围的源代码，而非逐字引用。
6. 仅当 go.mod 中的依赖发生变化时，才对整个工作区运行 go_vulncheck — 在诊断通过后运行，不要提前运行。
7. 运行 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、godig、Context7 与 govulncheck 的区别

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）。
• 对于非 Go 文档或未被 pkg.go.dev 收录的 Go 模块，Context7 仍可作为后备方案。

完整的任务与工具对照表位于 samber/cc-skills-golang@golang-how-to 技能的“godig 与 gopls、Context7、govulncheck 的区别”一节。