实战：从零构建一个 Mini Claude Code（TypeScript）

[minorcell]

收益

• 理解为什么 Agent 可以做事情，而 ChatBot 不能
• 听得懂 ReAct 与 Agent 基本架构
• 能跑通最小 TypeScript Agent
• 带走工程落地经验

目录

1. Agent 是怎么工作的？ — ChatBot vs Agent 的本质差异，三要素：上下文窗口、系统提示词、工具调用
2. ReAct：让模型"边想边做" — 观察 → 思考 → 行动的循环，控制流从人转移到模型
3. Agent 最小架构：ReAct + Tools + UI — 公式拆解，最小可行 Agent 长什么样
4. 最小 Agent 实现：天气查询（Bun + TypeScript） — 代码走读，40 行核心 Loop
5. Mini Claude Code 设计 — 拆解 Claude Code CLI，精选 5 工具，引入 Vercel AI SDK
6. 工程经验 — 上下文管理、安全防护、系统提示词架构

---

代码仓库：mini-claude-code

[minorcell]

Agent 是怎么工作的？

一些 Agents 的例子

• 春节期间的千问："帮我点一杯奶茶"；
• Manus："帮我做一个个人博客网站"；
• Claude Code CLI / Cursor IDE："帮我修复这个Bug..."；
• OpenClaw："帮我整理一下谷歌邮件"；
• ......

可以看到明显的几个点：

1. Agent 能做事情
2. Agent 能持续执行任务，直到完成目标
3. Agent 能和外部系统交互

为什么 Agent 可以做这些：

早期大模型产品，最经典的是 ChatGPT 的网页版本，用户输入提示词， ChatGPT 回复一段文字，这便是"ChatBot"，那时候它可以记住前后说了什么。

比较取巧的是，如果你告诉大模型，让他扮演什么角色、能干什么、不能干什么，它确实会这么做，比如：

• "你是一个小红书博主，你的核心工作是...."；
• "你是一个资深的Web前端高手, ....."。

后来，网页版的 ChatGPT 支持查询天气、支持网络搜索。比如："明日上海天气如何？"，它便会去查询上海的天气，然后告诉你它查到的结果，并且是这么回复（并不是天气查询接口原始JSON输出）："明天上海天气晴朗，气温约在16-23摄氏度，可以穿卫衣出行～"。

其实到这里就不在是简单的 Chatbot 了，就是"Agent"用技术术语来说，这三个要素构成了 LLM-based Agent 的最小 viable architecture（最小可行架构）：

用户感知	技术术语	技术本质
记住前后说了什么	上下文窗口 或 对话状态管理	维护一个消息数组，包含 system/user/assistant/tool 角色的历史消息，作为模型的输入上下文
扮演什么角色、能干什么	系统提示词 或 角色注入	在请求体最前端的 system 消息中定义行为边界、能力范围、输出格式约束，通过 Prompt Engineering 对齐模型行为
查询上海的天气	工具调用 或 外部能力扩展	模型生成结构化输出（JSON/XML）触发外部 API，将结果以 tool/function 角色回注上下文

怎么实现的？

比较成熟的一种方式是 ReAct。

时至今日，Agent 开发范式不止 ReAct 一种。Plan-and-Execute, Function/Tool Calling + Loop(ReAct Like) 等多种模式也有较多的应用。

ReAct：让模型"边想边做"

ReAct（Reasoning + Acting）是 Agent 架构的一种核心范式。它不再是大模型单次输入输出的"问答"，而是一个**"观察 → 思考 → 行动 → 再观察"**的循环过程。

想象你让 Manus "帮我做一个个人博客网站"，如果是传统 ChatBot，它会给你一段代码和教程，然后结束对话，你需要手动复制粘贴代码到本地测试，有问题之后还要把错误发给它，让它再次修复。但 ReAct 模式下，Agent 会这样执行：

[思考 Thought]  
用户需要一个博客网站，需求是：简洁风格、支持 Markdown、部署到线上。
我需要：1) 先创建项目结构 2) 编写 HTML/CSS  3) 添加交互逻辑  4) 部署到服务器。
第一步应该是初始化 Next.js 项目。

[行动 Action]  
执行 shell 命令：npx create-next-app@latest my-blog --typescript --tailwind

[观察 Observation]  
命令执行成功，项目目录已创建，但终端提示需要安装依赖。

[思考 Thought]  
依赖安装是下一步，然后我需要创建首页组件。等等，用户要求简洁风格，我应该先查看默认生成的文件结构，决定保留哪些。

[行动 Action]  
执行：cd my-blog && ls -la（查看目录结构）

...（循环继续，直到网站部署完成）

技术实现：控制流的转移

不难看出，ReAct 的关键在于**控制流（Control Flow）**从人类转移到了模型：

阶段	控制方	交互方式
ChatBot	人类	人问 → 模型答 → 人决定下一步
ReAct Agent	模型	模型观察 → 模型决策 → 模型自主执行 → 模型根据反馈调整

具体实现时，一个简单的 AGENT 系统提示词可能会包含这样的指令框架：

你是一个xxx的助手。
...
你可以使用以下工具：[文件操作、命令执行、网络搜索...]

每次回复必须遵循以下格式：
<observation>当前环境状态/工具返回结果</observation>
<thought>分析当前状况，决定下一步行动</thought>
<action>{"tool": "tool_name", "params": {...}}</action>

当模型输出 <action> 时，Agent 框架（如 Claude Code CLI 的运行时）会解析这段 JSON，实际调用对应的工具，然后将工具返回的结果以 <observation> 的形式重新注入上下文，再次请求模型，形成闭环。

为什么这能实现"持续执行"？

自我修正能力：如果某一步行动报错（比如代码编译失败），这个错误会作为新的 Observation 回到模型，模型会在 Thought 中分析错误原因，调整 Action（比如修改代码），而不是像 ChatBot 那样等待用户手动修复。

任务分解：面对"帮我修复这个 Bug"这样的复杂指令，模型会在 Thought 中自动拆解：先定位文件 → 阅读相关代码 → 理解逻辑 → 修改 → 测试验证，而不是一次性尝试解决（那样往往失败）。

状态持久：每一轮循环的 Observation 和 Thought 都追加到上下文中，Agent 不会"遗忘"已经完成的步骤（比如已经创建了哪个文件、修改了哪行代码），确保任务连续性。

这正是早期 ChatBot 与现在 Agent 的本质区别：前者是"一次性建议"，后者是"闭环执行"。

[minorcell]

Agent = ReAct + Tools + UI

或者更详细的来说是：Agent = ReAct(LLM + Context(System + User + LLM + Tool)) + Tools + UI

注解：
LLM: 大模型本身，作为整个 Agent 的"脑子"
System：系统提示词，通常包含基础提示词、人格设定、工具使用指南、MCP Tools、Skills 索引 等
Tool：内置工具（实质就是一些函数，函数中你可以自由定义逻辑）

如何理解：

• UI：无论什么 Agent 都需要一个用户交互界面，譬如：TUI、Web、手机APP...
• Tools: 要让 Agent 支持哪些功能，就需要对应的工具支持，这也要看宿主环境能提供什么（通常情况下，也不必担心，现在有 MCP 了）
• ReAct：如上文所说，它核心是个 Loop 循环。

一个最小可行的 Agent 便是如此。

[minorcell]

最小 Agent：天气查询（Bun + TypeScript）

借助上面的公式：UI + ReAct + Tools

• UI 演示方便，我们使用命令行交互
• Tools：获取当前时间、查询天气 两个最小集工具
• ReAct：检测到输出工具调用之后调用工具、检测到输出结果时，返回结果给用户。

项目文件：最小 Agent：天气查询（Bun + TypeScript）

[minorcell]

核心：Loop

来看这里的 40 行关键代码：

async function AgentLoop(question: string) {
  const systemPrompt = await Bun.file("prompt.md").text()

  const history: ChatMessage[] = [
    { role: "system", content: systemPrompt },
    { role: "user", content: question },
  ]

  for (let step = 0; step < 10; step++) {
    const assistantText = await callLLMs(history)
    console.log(`\n[LLM 第 ${step + 1} 轮输出]\n${assistantText}\n`)
    history.push({ role: "assistant", content: assistantText })

    const parsed = parseAssistant(assistantText)
    if (parsed.final) {
      return parsed.final
    }

    if (parsed.action) {
      const toolFn = TOOLKIT[parsed.action.tool as ToolName]
      let observation: string

      if (toolFn) {
        observation = await toolFn(parsed.action.input)
      } else {
        observation = `未知工具: ${parsed.action.tool}`
      }

      console.log(`<observation>${observation}</observation>\n`)

      history.push({
        role: "user",
        content: `<observation>${observation}</observation>`,
      })
      continue
    }

    break // 未产生 action 或 final
  }

  return "未能生成最终回答，请重试或调整问题。"
}

1. 加载系统提示词
2. 维护一个 historyMessage 作为 Agent 的历史上下文
3. 循环：调用大模型 -> 解析输出 -> 是最终消息 ? 作为结果返回并结束本轮对话 : 调用工具并回填结果再次调用大模型

这便是代码落地的、一个最小的 Agent 的核心内容。

[minorcell]

Mini Claude Code

先微拆 Claude Code CLI

Claude Code CLI 是个超成熟的 Code Agent 范例。要搞 Mini 版，我们就来简单拆一拆它的核心：

内置工具：

• 文件系统：Read File, Write File, Edit File, Search Files...
• Bash/Shell：最常用，查 Git、跑复杂命令、执行 Python/Node 代码
• 网络：WebFetch
• 上下文管理：Plan/Todo
• MCP Client
• 子 Agents：进程间交互

上下文：

• 压缩机制
• 会话历史：.claude/sessions/**.jsonl
• Skills 系统

TUI/CLI

• claude mcp ..., claude -c, claude -p, claude -dangerous 等用法
• 终端交互：slash 命令、IO 流等

Mini Claude Code 设计

工具设计

Mini 版工具精简到 4 个核心，够用不乱：

• Read / Write / Edit（文件三件套）
• Bash（Shell 执行）
• WebFetch（网络请求）

原则：工具别贪多。每多一个，模型负担就加重。Unix 哲学——一工具一事，但组合无限。

Agent 框架 / 库

之前天气 Demo 用原生 fetch 调用 LLM，手动 SSE 解析。零依赖好，但生产级有瓶颈：

1. 多模型适配麻烦：OpenAI/Anthropic/Gemini 协议不一样（delta.content vs delta.text）
2. 工具调用状态机手动管：tool_calls → execute → tool_results
3. 类型安全缺位：XML 结果 vs 工具参数无校验

所以，Mini 版用 Vercel AI SDK 做基建。不是框架党，而是借它的 Provider Gateway 和工具抽象，专注业务不纠结协议。

Vercel AI SDK 的用法请见：Vercel AI SDK 最小用法，详情参看官网 AI SDK

为啥不 Langchain / Langgraph？可以思考一下。

模型服务

演示用 七牛大模型推理服务，模型齐、顶尖无缝切。结合 ReAct 实战，快速迭代 Agent 循环。

相关代码实现：Mini Claude Code
相关设计文档：Mini Claude Code Design

[minorcell]

一些实际工程经验

没真正下场之前，我以为 Claude Code 这种东西"差不多就那样"。直到我在做 Memo Code 的过程中才意识到：从"能跑"到"能解决真实问题、能稳定投产"，中间的鸿沟还是软件工程。

下面这几条，基本都是踩坑踩出来的。

Agent 上下文工程

聊 agent / 大模型，绕不开上下文：越跑越长、越长越容易忘。通常要从两个入口拆开看：

1. 上下文太长了怎么办（模型有固定上下文长度）
2. 怎么从源头控制上下文不要暴涨

1）上下文太长：压缩 + 断环重启
通用解法是"压缩"。实现上可以很朴素：做 token 计数；当 session 中 context 的 token 占比超过阈值（比如 80%）时，中断当前 Loop，把历史上下文整体丢给模型，让它总结：

• 已经做了什么
• 还没做什么
• 当前状态 / 关键约束
• 后续注意事项（坑、边界条件、依赖）

然后新开一个会话（或滑动窗口），后续只发送：系统提示词 + 总结 + 新产生的内容。
这一步的关键不在"总结写得多漂亮"，而在于它要能支撑下一轮继续干活：信息结构要稳定、可复用、可增量更新。

2）防止上下文暴涨：从源头管住工具输出
真正让上下文爆炸的，很多时候不是用户对话，而是：

• 工具返回的超长结果（search / read / list）
• MCP 工具的"工作痕迹"（日志、堆栈、长 JSON）
• 不合理的提示词（把无关信息一次性塞满）

举个经典例子：TS 项目里的 node_modules，比宇宙还深还大。模型调用 search 去扫项目中的 js/ts 文件，如果 Search 工具没有合理的防护机制，工具返回可能直接无限长，一次下来就能把上下文撑爆。

所以工具设计本身非常重要，至少要有两道闸门：

• 黑白名单 / ignore 规则：禁止访问某些目录（建议复用 ignore 库，兼容 .gitignore）
• 工具结果拦截：当工具输出超过阈值，要么截断，要么直接返回一个明确的 system-hint，让模型知道"有内容，但被省略了"，避免它误以为自己看到了全量信息。

比如这种形式就很好（明确、可机器解析、可追踪）：

<system_hint type="tool_output_omitted" tool="${toolName}" reason="too_long" actual_chars="${actualChars}" max_chars="${maxChars}">
  Tool output too long, automatically omitted.
</system_hint>

Agent 安全问题

Agent 一旦"能动手"，安全问题就不是抽象讨论，而是迟早会发生的事故。

一些我觉得必须认真对待的点：

• 危险命令误执行：rm -rf . 是最经典的例子（早期 Gemini CLI 就踩过）。以及最近"小龙虾误删某高管历史邮件"的故事……这类事故的共同点是：不是模型一定会坏，而是系统缺少最后一道保险。
• 子进程泄漏 / 资源泄漏：agent 工作时会频繁启停子进程，处理不当就容易出现不可控的内存泄漏。我自己就遇到过：Codex 内存泄漏 54GB，电脑死机。这类问题通常不是"优化一下就好"，而是要把资源回收当作一等公民。
• 工具权限边界：--dangerous 确实能释放双手，但也会释放风险。到底是给"全程全权限"，还是"关键操作每次审批"，需要按场景权衡：频繁审批会拖慢体验，但无审批的代价可能是灾难级。

七牛 Agent 专用沙箱 或者 e2b , Docker 容器等做法是直接提供给 agent 一个单一环境，与用户环境隔离。

可以参考做法：Memo Code 安全设计：子进程、命令防护与权限审批的统一方案，这里不做过多赘述。

Agent 系统提示词

系统提示词怎么写的"内容套路"，市面上已经很多了。这里更想聊工程层面的格式与组装：什么样的提示词结构更利好大模型、也更利好长期维护。

很多人把系统提示词当成一个固定的 Markdown 文件来管，但在真实项目里，系统提示词往往要承载这些东西：

• 基础行为指令（核心身份、输出规范）
• 用户偏好设置（比如 SOUL.md）
• 项目级上下文（比如 AGENTS.md）
• 动态工具能力（内置工具 + MCP 工具清单/用法）
• Skills 技能（.agents/skills/skillname/SKILL.md)
• 运行时异常状态（截断提示、危险命令拦截、工具降级）

问题是：来源不同、格式不同、优先级不同，而且有些是运行时动态生成的。这就需要一套统一的拼装逻辑（比如分段、打标签、定义优先级、支持增量更新）。

没有最优解，我把自己在做 Memo Code 时的设计思路整理成了一篇文章：
Memo Code 系统提示词架构解析：从模板到上下文组装