go-surgeon：为 LLM 代理打造的 Go 语言 AST 精准代码编辑工具

go-surgeon 是一款专为 AI 代理设计的 Go 语言代码编辑工具，基于抽象语法树（AST）提供确定性的字节级代码修改能力，彻底解决 LLM 在编辑 Go 代码时的缩进幻觉和语法错误问题。

当大语言模型（LLM）尝试修改现有代码时，通常依赖于通用的文本替换工具，如 diff 代码块或正则表达式。这些方法在理论上简单直接，但在实践中却存在诸多隐患：

• 缩进幻觉：LLM 经常在代码块的缩进层级上产生错误，导致语法无效
• 上下文丢失：标准文本替换可能意外破坏周围的注释、文档字符串或格式化
• 无限循环：当修改引入语法错误时，代理可能陷入反复修复的死循环
• 上下文窗口浪费：为了理解代码结构，代理往往需要加载数千行代码到上下文窗口

对于 Go 语言这种对格式和语法极其敏感的语言，这些问题尤为突出。

go-surgeon 从根本上改变了 LLM 与 Go 代码交互的方式。它不再依赖脆弱的文本替换，而是基于 Go 的**抽象语法树（AST）**提供确定性的字节级操作接口。

零缩进错误：通过精确定位 AST 中的字节偏移，代理只需提供原始代码块，工具自动处理缩进和导入。内置的 goimports 集成确保每次修改后代码格式正确、依赖完整。

完美上下文保留：与标准 AST 变异不同，go-surgeon 的字节范围引擎保留所有周围注释，并同步更新 Godoc 文档块，确保代码的可维护性不受影响。

最大化上下文窗口效率：工具充当 CLI 版本的 LSP（语言服务器协议），代理可以通过 graph 和 symbol 命令查询函数签名、文档和代码体，而无需将整个大文件加载到上下文窗口。

大幅降低回合数：通过原子级更新复杂方法、接口或结构体，一次操作完成原本需要多轮交互的修改任务。

graph 命令提供项目结构的全景视图：

• 列出所有 Go 包的导入路径
• 通过 --symbols --dir 参数展示子树中所有导出的类型、函数和方法
• 上下文窗口管理标志（--depth、--focus、--exclude、--token-budget）让代理能够渐进式深入探索，而不超出令牌预算

symbol 命令支持精确的代码片段提取：

• 提取函数签名、文档或完整代码体
• 智能压缩：自动去除空行以节省 LLM 令牌
• 支持 Receiver.Method 精确查找，快速定位目标

go-surgeon 提供一系列专门的子命令进行代码修改：

• add-func：添加新函数
• update-func：更新现有函数
• delete-func：删除函数
• add-struct：添加结构体
• add-interface：添加接口

每个子命令都接受通过 stdin 传入的原始 Go 源代码，并通过 --flags 传递元数据。每次变异后自动运行 goimports，确保代码格式和导入正确。

接口模拟生成：mock 命令可以一步创建或更新接口及其函数字段模拟实现，自动保持同步。

接口实现：implement 命令自动为结构体生成满足任意接口（标准库、第三方或项目本地）所需的缺失方法存根，扫描整个包以防止跨文件重复。

外部接口模拟：external-mock 命令允许为不拥有的接口生成函数字段模拟，而无需修改接口文件本身。