go-version-manager

Go 版本管理器

更改依赖项前，先选择与项目兼容的 Go 工具链。优先使用机器上已有的 goenv 安装进行实际版本切换。若没有受支持的版本管理器，则改用显式二进制路径。

工作流

1. 阅读 go.mod，充分了解其中的 go、toolchain 和 replace 指令。
2. 运行 .agents/skills/go-version-manager/scripts/go-version-manager.sh requirement <project-dir>、manager 和 list。
3. 运行 .agents/skills/go-version-manager/scripts/go-version-manager.sh select <project-dir>，选择已安装的二进制文件。
4. 使用 <go-binary> version 和 <go-binary> env GOROOT GOTOOLCHAIN GOPATH GOMODCACHE GOCACHE 确认所选二进制文件。
5. 选择切换范围：
   • 对于单条命令，使用脚本的 exec 命令。使用 goenv 时，该命令只会为这条命令设置 GOENV_VERSION。
   • 对于当前终端，运行 shell-command 打印的命令（通常为 goenv shell <version>）。
   • 对于持久应用于仓库的选择，使用 switch-local；它会运行 goenv local <version> 并写入 .go-version，因此仅在用户授权修改仓库时执行。
   • 仅当用户明确要求更改整台机器的默认版本时，才更改 goenv global。
6. 执行任何模块命令后，检查 git diff -- go.mod go.sum。
7. 报告所选版本、运行的命令、依赖项变更和验证结果。

选择规则

• 优先选择与 toolchain goX.Y.Z 完全匹配的已安装版本。
• 否则，优先选择 go X.Y 次版本系列中已安装的最高补丁版本。
• 将 go 指令视为语言和工具链的最低要求，而非升级模块指令的许可。
• 仅当没有兼容的同次版本安装时，才使用较新的次版本；修改模块前说明风险。
• 对于常规 Go 安装，不要设置 GOROOT；所选 go 二进制文件会决定它。
• 除非用户明确要求，否则不要重写 /usr/local/go、系统符号链接、Shell 配置文件或全局 PATH。
• 优先使用已安装的 goenv 及其已安装版本。如果仓库已配置其他版本管理器（mise、asdf、g、gvm、Homebrew），则遵循现有配置。未经批准，不要引入第二个管理器。
• 不要自动安装缺失的 Go 版本。报告缺失的版本，并在下载或安装工具前征求同意。

模块安全

• 绝不要手动编辑 go.sum 来消除校验和缺失错误。
• 仅在使用所选的项目兼容工具链，且任务授权修改依赖文件时，才运行 go mod tidy。
• 如果只需获取现有依赖图，优先使用 go mod download 或错误信息中范围明确的 go get module@version；检查生成的差异。
• 不要为了弥补本机 Go 版本错误而升级软件包。
• 除非用户要求升级项目工具链，否则不要更改 go 或 toolchain 指令。
• 保留 go.mod 和 go.sum 中与任务无关的用户更改。

诊断常见故障

• package slices is not in GOROOT：当前 Go 二进制版本低于 Go 1.21。先切换工具链，再处理依赖项。
• missing go.sum entry：先使用正确的工具链，然后获取或整理模块依赖图；不要手动写入校验和。
• 缓存提示 operation not permitted：保留所选工具链，仅将可写缓存重定向到其他位置，例如 GOCACHE=<writable-temp-dir>。仅在必要时重定向 GOMODCACHE，因为这可能触发完整的依赖下载。
• Mock/测试二进制文件需要特殊标记或外部服务：区分编译与执行。如果包初始化导致无法在本地执行，可使用 go test -c -o <temp-file> <package> 进行仅编译验证。
• 某条命令意外更改了许多依赖项：停止操作，在继续前检查 go version、go env GOTOOLCHAIN、模块指令和差异。

验证阶梯

使用满足需求的最低级别，然后根据风险逐步升级：

1. <go> version 和 <go> env ...
2. <go> mod verify
3. 针对性运行 <go> test ./path/to/changed/package
4. 仅编译：<go> test -c -o <temp-file> ./package
5. 范围更广的 go test ./... 或项目构建命令

如果下载依赖项或在工作区之外写入文件需要审批，请提出申请，不要绕过沙箱或网络控制。

脚本

使用 .agents/skills/go-version-manager/scripts/go-version-manager.sh：

# Show go/toolchain requirements
.agents/skills/go-version-manager/scripts/go-version-manager.sh requirement /path/to/project

# List discovered Go binaries
.agents/skills/go-version-manager/scripts/go-version-manager.sh list

# Show which switching backend is available
.agents/skills/go-version-manager/scripts/go-version-manager.sh manager

# Print the selected Go binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh select /path/to/project

# Execute with the selected binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh exec /path/to/project -- test ./...

# Print the command that switches the current terminal
.agents/skills/go-version-manager/scripts/go-version-manager.sh shell-command /path/to/project

# Persist the selection for this repository (writes .go-version)
.agents/skills/go-version-manager/scripts/go-version-manager.sh switch-local /path/to/project

该脚本为只读脚本，只有 switch-local 会写入 .go-version，此外还会产生所提供的 Go 子命令通过 exec 导致的影响。