用途:对既有 Go 代码做安全、成规模的重构,在不改变可观察行为的前提下调整内部结构,使代码更易理解、更易修改。
核心循环:Understand(用 gopls 查引用、调用层级、包 API 评估影响面)→ Safety net(先补测试)→ 小步工具驱动转换 → Verify → 单一类别原子提交,循环重复。验证命令为 go build ./... && go vet ./... && go test ./...,并发改动加 -race,热路径用 benchstat 对比基准。
主要能力与模式:Plan 模式是任何编辑前的强制关卡,产出重构清单与顺序并经用户确认;Execute 模式为人机协同,每个原子改动一个分支、一个 PR;Simple-sweep 模式用于单次机械式全树转换;Review 模式检查重构 PR 的结构与行为分离。
规则要点:同一提交不得混合结构与行为变更;优先用 gopls Rename/Inline 而非 LLM 手改;跨多处重复改动应生成重写工具,按 gofmt -r → eg → gopatch → go/analysis 逐级升级;跨包移动类型先用类型别名;打破导入环优先用消费侧接口。重命名后须 grep 结构体标签与反射引用。跨包移动、导出 API 变更、删除、新主版本、无测试代码等操作前必须人工确认。
限制:gopls 只保证编译层面,不覆盖反射、struct tag、text/template;代码稳定无人再改、无测试的关键生产代码、时间紧或无明确目的时不宜重构。工具依赖:gopls(go install golang.org/x/tools/gopls@latest),可选 golangci-lint、benchstat、deadcode、eg、gopatch。