ghuntley/how-to-build-a-coding-agent

ghuntley/how-to-build-a-coding-agent – 构建本地 Claude 驱动型编码助手的实战工作坊

这是什么 – 一个逐步教程（附带可直接运行的 Go 源文件），展示如何将 Anthropic 的 Claude 模型转变为本地的“编码助手”。该仓库通过六个逐步进化的版本，每次添加一个新工具（文件读取、目录列出、shell 执行、文件编辑、代码搜索），并演示经典的 代理-工具 循环。

为何重要 – 它提供了一个具体、动手实践的范例，展示了新兴模式：大型语言模型保持轻量，而繁重的任务（文件系统访问、命令执行、grep 风格搜索）由显式、沙箱化的工具来完成。读者可以直观看到完整的架构、基于 Go 的工具注册表，以及如何将 Claude 的 JSON 结构化工具调用连接到真实函数。

---

主要特性（如 README 所述）

特性	你将获得
Claude 集成	简单的 Go 客户端，将用户消息发送到 Anthropic API 并接收响应。
渐进式代理	六个可直接运行的程序（chat.go、read.go、list_files.go、bash_tool.go、edit_tool.go、code_search_tool.go），每个都添加一项新功能。
工具系统	统一的工具定义（名称、描述、输入模式、Go 函数），Claude 可通过其工具使用协议调用。
文件操作	安全地读取任意文件、列出目录内容、编辑或创建文件。
Shell 命令执行	有限地运行 bash 命令，并将 stdout/stderr 返回给 Claude。
代码搜索	使用 ripgrep 在代码库中进行基于模式的搜索。
详细日志	--verbose 标志可显示完整的事件循环、工具分发和错误详情。
示例数据	小型演示文件（fizzbuzz.js、riddle.txt、AGENT.md），可立即尝试工具。
开发环境	可选的 devenv 配置，可自动部署 Go、Node、Python、Rust、.NET 及常见开发工具。

---

架构概览（来自 README）

1. 用户输入 → 通过 Anthropic 客户端发送给 Claude。
2. Claude 直接回复或返回 工具请求（例如 read_file）。
3. 代理在 注册表 中查找请求的工具，执行 Go 函数，捕获结果或错误。
4. 结果反馈给 Claude，Claude 可生成最终答案或请求更多工具。
5. 此循环重复，直到 Claude 返回纯文本响应。

README 中的图示展示了两个视角：

• 应用演进 – 每个后续程序如何添加新工具。
• 事件循环 – 消息、工具分发和结果处理的运行时流程。

---

快速上手（按 README 操作）

1. 前置条件
   • Go 1.24.2 或更高版本（或使用提供的 devenv 设置）。
   • Anthropic API 密钥（export ANTHROPIC_API_KEY=…）。
2. 设置
   • 推荐：运行 devenv shell 加载环境。
   • 或手动在克隆后运行 go mod tidy。
3. 运行第一个版本

   go run chat.go          # 基础 Claude 聊天
   go run read.go          # 添加文件读取工具
   go run list_files.go    # 添加目录列出功能
   go run bash_tool.go     # 添加 shell 命令工具
   go run edit_tool.go     # 添加文件编辑工具
   go run code_search_tool.go  # 添加基于 ripgrep 的搜索
   

   • 使用 --verbose 查看详细日志。
   • 尝试 README 中展示的示例提示（如“读取 fizzbuzz.js”、“运行 git status”）。
4. 故障排除 – 检查 API 密钥、运行 go mod tidy、使用 --verbose、验证文件权限。

---

技术栈

• 语言 – Go（利用 Go 结构体生成 JSON 模式）。
• LLM – 通过其公开 API 访问 Anthropic Claude。
• 工具 – 使用 ripgrep 实现快速代码搜索，使用标准 OS shell 执行命令。
• 可选开发环境 – devenv（提供多语言运行时和工具）。

---

适合谁使用

• 对 LLM 驱动的代理 感兴趣，并希望安全地暴露系统能力的开发者。
• 希望获得 Claude 工具使用集成具体示例的 Go 程序员。
• 寻找现成、渐进式教程的教育者或工作坊组织者。

---

作者建议的下一步

• 添加自定义工具（如 HTTP API 调用器、网页爬虫）。
• 将工具串联以实现更复杂的流程。
• 实现跨会话的持久化记忆。
• 构建 Web UI 前端。
• 尝试其他 LLM 提供商。

---

总结 – 该仓库是使用 Claude 和 Go 构建本地 AI 编码助手的实用、动手实践指南，以清晰、渐进的方式展示了现代代理-工具模式。