起因

最近 Claude Code 很火，作为一个终端 AI 编程助手，它能直接在命令行里帮你写代码、改 Bug、执行命令。

用了一段时间后，我产生了一个想法：这玩意儿的核心原理是什么？我能不能自己写一个？

于是花了几周时间，用 Go 语言从零实现了一个 Mini 版本，取名 MiniCode。

写完之后发现，这个过程涉及的知识点挺多的，而且网上很少有人系统讲过。所以我把整个过程整理成了一个 30 天教程，从最基础的 API 调用，到流式输出、工具系统、TUI 界面，一步步带你搞懂 AI Agent 的核心原理。

项目地址： https://github.com/JiayuXu0/MiniCode 欢迎大家Star，感谢感谢

---

先说结论：AI Agent 没那么神秘

很多文章把 AI Agent 讲得很玄乎，什么"自主决策"、“任务规划”、“记忆系统”，听起来像是在造 AGI。

但实际上，核心原理很简单：

就是一个循环：LLM 决定要不要用工具，用了就把结果塞回去，再让 LLM 判断，直到它觉得可以回答了为止。

Claude Code 的"智能"，本质上是：

1. 强大的底座模型（Claude 4）
2. 精心设计的工具集（20+ 个工具）
3. 巧妙的 Prompt 工程

模型能力我们比不了，但工具系统和架构设计，完全可以学。

---

为什么用 Go 而不是 Python？

网上 99% 的 AI Agent 教程都是 Python + LangChain。我选择 Go 有几个原因：

1. 性能

Go 编译成原生二进制，启动快、内存小。Python 光是 import 那一堆依赖就要好几秒。

2. 部署简单

一个二进制文件，复制到服务器就能跑。不用装 Python、不用搞虚拟环境、不用 pip install 半天。

3. 并发处理

流式输出需要同时处理：接收 API 响应、更新 UI、响应用户输入。Go 的 goroutine 天然适合这种场景，比 Python 的 async/await 写起来舒服。

4. 类型安全

工具的输入输出都有明确的类型定义，编译时就能发现错误。不像 Python，跑到一半才告诉你 KeyError。

---

技术栈选择

组件	选择	理由
AI SDK	Fantasy	Charmbracelet 出品，比 LangChain 轻量 10 倍
TUI 框架	Bubble Tea	Elm 架构，状态管理清晰
LLM	智谱 GLM-4	国产模型，有免费额度，API 兼容 OpenAI

Fantasy 是我这次发现的宝藏库。它是 Charmbracelet（就是做 Bubble Tea 那家）出的 AI SDK，特点是：

• 统一接口，支持 OpenAI/Anthropic/Google 等主流 Provider
• 原生支持流式输出
• 工具系统设计得很优雅
• 没有 LangChain 那种过度抽象

---

核心实现：工具系统

Claude Code 最核心的能力是工具调用。比如你说"帮我找一下所有 Go 文件"，它会：

1. 理解你的意图
2. 调用 glob 工具搜索文件
3. 拿到结果后组织语言回复你

在 Fantasy 里，定义一个工具非常简单：

// 定义输入结构
type GlobInput struct {
    Pattern string `json:"pattern" description:"The glob pattern (e.g., **/*.go)"`
    Path    string `json:"path,omitempty" description:"Search directory"`
}

// 实现工具函数
func Glob(ctx context.Context, input GlobInput, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
    matches, err := doublestar.FilepathGlob(filepath.Join(input.Path, input.Pattern))
    if err != nil {
        return fantasy.NewTextErrorResponse(err.Error()), nil
    }
    return fantasy.NewTextResponse(fmt.Sprintf("Found %d files:\n%s", len(matches), strings.Join(matches, "\n"))), nil
}

// 注册工具
tool := fantasy.NewAgentTool("glob", "Search files by pattern", Glob)

几个关键点：

1. description tag 会发送给 LLM，让它知道这个参数是干什么的
2. 返回 TextErrorResponse 表示工具执行失败，LLM 会知道需要换个方式
3. Fantasy 会自动把结构体转成 JSON Schema

目前 MiniCode 实现了 6 个工具：

工具	功能
glob	文件搜索（支持 ** 递归）
view	查看文件内容（带行号）
grep	内容搜索（正则匹配）
bash	执行命令
write	写入文件
edit	编辑文件（字符串替换）

---

流式输出：打字机效果

非流式输出的体验很差——发送问题后，要等好几秒才能看到回复，不知道 AI 在干嘛。

流式输出可以实时显示 AI 的思考过程：

result, err := agent.Stream(ctx, fantasy.AgentStreamCall{
    Messages: history,
    Prompt:   input,
    
    OnTextDelta: func(id, text string) error {
        // 每收到一个文本片段就更新 UI
        program.Send(streamTextMsg{delta: text})
        return nil
    },
    
    OnToolCall: func(tc fantasy.ToolCallContent) error {
        // 工具调用开始，显示 loading 状态
        program.Send(streamToolCallMsg{name: tc.ToolName})
        return nil
    },
    
    OnToolResult: func(tr fantasy.ToolResultContent) error {
        // 工具执行完成，显示结果
        program.Send(streamToolResultMsg{result: tr.Result})
        return nil
    },
})

这里有个坑：回调函数是在独立 goroutine 里执行的，不能直接修改 UI 状态，否则会有竞态条件。

解决方案是通过 program.Send() 发送消息到主循环，让 Bubble Tea 的 Update 函数统一处理。

---

TUI 架构：Elm 模式

Bubble Tea 采用 Elm 架构，核心是三个函数：

• Model: 应用状态
• Update: 根据消息更新状态
• View: 根据状态渲染 UI

这种架构的好处是状态管理非常清晰。所有状态修改都在 Update 里，View 是纯函数，不会有奇怪的副作用。

MiniCode 的 Model 结构：

type Model struct {
    textarea    textarea.Model    // 输入框
    viewport    viewport.Model    // 消息显示区
    history     []fantasy.Message // 对话历史
    agent       fantasy.Agent     // AI Agent
    streaming   bool              // 是否正在流式输出
    streamParts []streamPart      // 流式内容缓存
    cancelFunc  context.CancelFunc // 取消函数
}

---

教程目录

整个项目我整理成了 30 天的教程，目前已完成 Day 1-4：

Day	主题	内容
Day 1	创建第一个 AI Agent	Fantasy SDK 基础、Provider、Agent
Day 2	给 Agent 添加工具	Tool 系统、Glob 实现、AgentResult 结构
Day 3	构建交互式 TUI	Bubble Tea、Elm 架构、多轮对话
Day 4	实现流式输出	Streaming API、跨 goroutine 通信、取消机制
Day 5+	更多工具和高级特性	持续更新中…

每篇教程都有完整的代码和详细的原理讲解，不是那种"Hello World 跑通就完事"的水文。

---

写在最后

做这个项目的初衷，是想搞清楚 Claude Code 到底是怎么工作的。写完之后发现，AI Agent 的核心原理并不复杂，难的是工程细节和产品打磨。

目前已经完成了 Day 1-4 的教程，实现了基础功能：流式输出、工具调用、多轮对话、TUI 界面。接下来我会每天连载更新，把 30 天的内容全部写完。

后续更新计划：

• Day 5-10：完善工具集（文件读写、代码编辑、命令执行）
• Day 11-20：Agent 循环与上下文管理
• Day 21-30：子 Agent、记忆系统、生产级部署

说实话，写教程比写代码累多了——代码跑通就行，教程要把每个细节讲清楚。所以恳请大家：

• 点个 Star ⭐️ —— 这是我持续更新最大的动力
• Watch 项目 —— 第一时间收到更新通知
• 关注我 —— 后续会在知乎同步发布每天的教程

一个人写容易摸鱼，有人看着就不一样了 😂

GitHub： https://github.com/JiayuXu0/MiniCode

如果在学习过程中遇到问题，欢迎提 Issue，我会尽量回复。也欢迎提 PR，一起完善这个项目。

让我们一起，30 天搞懂 AI Agent！