从零构建 AI Coding Agent

Appearance

这页解决什么问题 ​

实践篇的目标是帮助你把 AI Agent 的核心模式真正跑通，但在开始之前有一件事必须先说清楚：

  • 当前仓库首先是一个 VitePress 文档站点
  • 实践篇页面中的 bun run pxx-*.ts 更接近推荐的示例入口命名
  • 当前仓库已经提供 P1-P23 的根目录示例文件；实践篇当前章节都可以直接按推荐命令运行

如果你只是阅读原理，这一页可以快速浏览。

如果你打算边读边敲代码，这一页建议完整看完。

你会用到什么 ​

开始实践篇之前，建议至少准备好下面这些基础条件：

项建议值用途
Node.js20+兼容现代 ESM、VitePress、常见 Agent SDK
Bun1.1+文中运行命令默认使用 bun run / bun add
包管理器bun安装文档站点依赖，后续也可用于示例工程
OpenAI API Key必需涉及 openai 的章节都要用到
API Base URL可选当你使用代理、兼容网关或本地模型时需要配置
模型名建议预先确认避免在线运行或本地运行时直接填错
一个终端必需绝大多数示例都以命令行方式运行
一个浏览器在线运行时需要适合先验证核心链路是否能跑通

两种使用方式 ​

方式一：在线运行模式 ​

如果你还不想先折腾本地环境，只想先感受“这个示例到底会不会跑”，那在线运行模式更适合你。

它的核心思路很简单：在在线 Playground 或浏览器侧运行面板里，手动填写 3 个参数，再执行当前章节的示例代码。

配置项是否必填说明
API Key必填你的真实密钥，运行时用于鉴权
baseURL按需默认可指向官方 OpenAI，也可以替换成代理或兼容服务
model建议必填例如 gpt-4o、gpt-4o-mini、兼容服务自己的模型名

在线运行模式更适合这些场景：

  • 你想先快速体验 P1-P4 这种单文件、轻依赖的示例
  • 你还没决定要不要完整搭本地开发环境
  • 你想先验证自己的 baseURL / model / key 组合是否可用

在线运行模式也有明确边界：

  • 更适合 P1-P4、P10、P18 这类主链路清晰的轻量章节
  • 不适合 P14 这类需要双进程配合或额外服务的章节
  • 如果章节依赖文件输入、样本目录或多脚本联动，通常还是本地运行更稳

安全提醒：

  • 不要把真实 API Key 写进仓库、截图或公开分享
  • 如果在线运行平台会保存表单内容，优先确认它的存储策略
  • 演示结束后，建议清空页面中的敏感配置

方式二：本地运行模式 ​

如果你想跟着每一章把代码真正敲出来、修改、调试和扩展，本地运行仍然是实践篇的标准路径。

建议先准备示例运行环境，再进入各章节的 bun run pxx-*.ts 主线。

最小依赖通常包括：

bash
bun add openai

部分章节还会额外需要其他依赖。例如：

  • P14：MCP 协议接入 需要 @modelcontextprotocol/sdk
  • 涉及 HTTP 服务、Schema 校验、向量检索或文件处理的章节，可能还需要额外包

建议做法是：先读每章“前置准备”或“依赖安装”部分，再安装该章特有依赖，不要一开始把所有可能用到的库一次性全装上。

按当前仓库内已提供的 P1-P23 示例脚本，第三方依赖可以先这样分组：

分组覆盖章节说明
基础组P1-P23全部章节默认都要 openai
MCP 扩展组P14额外需要 @modelcontextprotocol/sdk

也就是说，如果你不打算先做 P14，当前只装 openai 就足够开始大部分实践章节。

如果你当前只是想本地阅读文档站点，不急着跑示例代码：

bash
bun install
bun dev

然后访问本地 VitePress 页面即可。

这个模式下，你不需要立刻安装 openai，也不需要配置 OPENAI_API_KEY。

运行参数配置 ​

只要代码里出现下面这种写法：

ts
import OpenAI from 'openai'

const client = new OpenAI()

就意味着运行时至少要拿到 API Key，而多数实践示例还支持额外传入 baseURL 与 model。

推荐你先统一理解这 3 个参数：

参数作用常见示例
OPENAI_API_KEY鉴权sk-...、代理平台密钥、本地模型占位值
OPENAI_BASE_URLAPI 入口地址https://api.openai.com/v1、代理网关、http://localhost:11434/v1
OPENAI_MODEL当前运行模型gpt-4o、gpt-4o-mini、llama3

本地运行时的推荐配置 ​

推荐在本地 shell 中先配置最小必需项：

bash
export OPENAI_API_KEY="你的真实 Key"

如果你不是直接使用官方 OpenAI，再补充：

bash
export OPENAI_BASE_URL="你的接口地址"
export OPENAI_MODEL="你的模型名"

如果你使用 zsh，可以把这行写入 ~/.zshrc 后重新加载：

bash
source ~/.zshrc

建议你先验证环境变量是否生效：

bash
echo $OPENAI_API_KEY

如果你还配置了其他参数，也建议一起确认：

bash
echo $OPENAI_BASE_URL
echo $OPENAI_MODEL

你应该能看到非空输出。不要把真实 Key 提交到仓库，也不要直接硬编码进示例源码。

在线运行时的推荐填写方式 ​

如果你使用浏览器中的在线 Playground，通常不需要写环境变量，而是直接把这 3 个值填进表单：

  • API Key 对应 OPENAI_API_KEY
  • baseURL 对应 OPENAI_BASE_URL
  • model 对应 OPENAI_MODEL

推荐顺序是：

  1. 先填 API Key
  2. 如果你用的是代理或兼容服务，再填 baseURL
  3. 最后填准确的 model 名称，避免把“平台名”误填成“模型名”

如果你第一次尝试在线运行，优先选 P1、P2、P3 这种输入输出简单、排查成本低的章节。

当前仓库状态说明 ​

为了避免预期错位，这里明确说明当前实践篇的运行边界：

  1. 实践文章里的代码片段已经覆盖主要实现逻辑，且当前 P1-P23 都已经落成仓库内可运行示例文件。
  2. 当前仓库已经提供 P1-P23 对应的根目录示例文件，其中 P14 包含 p14-mcp.ts 和 p14-mcp-server.ts 两个脚本。
  3. 如果你本地执行 bun run pxx-*.ts 时提示找不到文件，通常意味着分支版本较旧或当前工作区没有同步到最新内容，而不是文档仍要求你手动创建。
  4. RunCommand 组件会显示“是否已在仓库提供”的提示，但不会主动校验你的本地环境和 API Key 是否已经满足运行条件。

换句话说：当前实践篇已经覆盖 P1-P23 的现成可执行 demo。

推荐目录组织 ​

当前仓库为了让文档中的 bun run pxx-*.ts 命令可直接对齐，示例文件统一放在 practice/ 目录。

如果你准备在自己的项目里持续扩展这些示例，建议统一放在一个明确的目录里，不要和 VitePress 主题文件混在一起。

例如：

text
.
├── docs/
├── .vitepress/
├── examples/
│   ├── p01-minimal-agent.ts
│   ├── p02-multi-turn.ts
│   ├── p03-streaming.ts
│   └── ...
└── package.json

这样做有三个好处：

  • 文档代码和可执行示例分层清晰
  • 后续补测试、补 README、补样例输入更容易
  • 不会误把站点构建依赖和示例运行依赖混在一起

推荐运行流程 ​

建议你按下面顺序开始，而不是直接跳进后面的高级章节：

  1. 先决定你是走“在线运行模式”还是“本地运行模式”。
  2. 先读 P1，跑通最小示例，确认 API Key / baseURL / model 组合可用。
  3. 再进入 P2 到 P4，确认多轮、流式和错误处理都正常。
  4. 等 P1-P4 都稳定后，再进入 RAG、多 Agent、生产化章节。

这条路线的目的不是“保守”，而是避免你在 P14、P22 这类高复杂度章节里同时排查协议、环境、依赖和业务逻辑四类问题。

每章开始前的检查清单 ​

建议在每一章动手前，先过一遍下面这份清单：

检查项为什么要查
这章对应的示例文件是否已经在当前分支存在防止命令名与本地文件状态不一致
这章是否新增依赖防止 Cannot find package
这章是否需要额外资源例如图片、文档样本、diff 样本、测试输入
这章是否依赖前一章产物防止跳章导致上下文断裂
这章的预期输出是什么便于判断“没报错”是否真的等于“成功”

常见报错与排查 ​

1. Cannot find package 'openai' ​

说明依赖还没安装。

bash
bun add openai

2. OPENAI_API_KEY 未配置 ​

说明环境变量没有生效。先重新执行：

bash
export OPENAI_API_KEY="你的真实 Key"

然后用 echo $OPENAI_API_KEY 检查是否为空。

如果你走的是在线运行模式，则检查页面中的 API Key 输入框是否为空，或是否误填成了别的平台令牌。

3. baseURL 或 model 配错了 ​

常见现象包括：

  • 可以连上接口，但提示模型不存在
  • Key 看起来有效，但始终返回 404 / 400
  • 同一份代码在别的平台能跑，在当前平台跑不通

优先检查：

  • baseURL 是否已经带上正确的 /v1
  • model 填的是模型名，而不是平台名或部署名别称
  • 代理平台是否要求使用它自己的模型标识

4. bun run pxx-*.ts 找不到文件 ​

说明当前工作区缺少对应示例文件，优先检查当前分支是否同步到最新版本，或确认命令中的文件名是否与章节一致。

5. 章节代码能读懂，但拼起来跑不起来 ​

这通常不是模型问题，而是你遗漏了某一步：

  • 少了 import
  • 漏了类型定义
  • 漏了某一段辅助函数
  • 漏了环境变量或样本输入

建议做法：不要一次性复制整篇，按文章里的步骤一段一段组装，并在每一步完成后先跑通再继续。

推荐下一步 ​

准备完成后，建议按这个顺序进入实践篇：

如果你只是想快速复制某一章的运行命令，也可以直接查看 实践篇首页的运行索引。

如果你已经具备 Agent 开发经验，也可以直接从你关心的主题切入，但仍然建议先确认这页里的环境准备项已经满足。