# agent学习

**Repository Path**: yushiyue/agent-learn

## Basic Information

- **Project Name**: agent学习
- **Description**: 零基础学习 agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 零基础 Agent 开发图文教程

> Node/TypeScript 主线 · Java(Spring AI) 对照 · 中转站 OpenAI 兼容 API · **VitePress 双轨文档** + 可运行代码

学完本教程，你将能够：

- 独立完成 Agent 开发全流程（Prompt → Tool → 记忆 → RAG → 多 Agent）
- 理解并使用 Vercel AI SDK / LangChain.js / LangGraph.js / Spring AI
- 交付可上线的客服 Agent 与垂直业务 Agent
- 应对常见 Agent 工程师面试题

如果你从未写过 Node.js 项目，也可以学习：先读 [零基础学习指南](docs/start/learning-guide.md)，再按 [第 0 章](docs/start/setup.md) 完成“安装 → 自检 → 第一个示例”，然后按 `examples/01~06` 的顺序前进。教程里的 **mock** 表示本地模拟，它能帮助你在没有 API Key 时理解流程；mock 跑通不等于真实模型连接已经成功。

---

## 阅读文档站（推荐）

```bash
pnpm install
pnpm docs:dev   # http://localhost:5174 （避免与客服前端 5173 冲突）
```

以上命令必须在含有本文件和根目录 `package.json` 的目录执行。若终端提示找不到 `package.json`，先用 `pwd` 查看当前位置，再 `cd` 到仓库根目录。

浏览器打开本地地址后，可走两条路径：

| 轨道 | 说明 | 入口 |
|------|------|------|
| 轨 A · 原理精讲 | Prompt / Tool / ReAct / RAG / 框架 / 工程化 / 面试 | `/start/setup` |
| 轨 B · 客服实战 | 一步一步拼出智能客服（对齐 `apps/customer-service-agent`） | `/lab/` |

构建静态站点：

```bash
pnpm docs:build
pnpm docs:preview
```

---

## 学习路线

```mermaid
flowchart LR
  base[环境+统一封装] --> principles[原理手写]
  principles --> frameworks[框架实战]
  frameworks --> rag[RAG]
  rag --> advanced[多Agent/MCP]
  advanced --> eng[工程化]
  eng --> lab[客服实战]
  lab --> more[SQL/导购]
  more --> interview[面试题]
```

| 部分 | 文档路径 | 示例代码 |
|------|----------|----------|
| 基建 | [docs/start/setup.md](docs/start/setup.md) | `packages/llm` |
| 原理 1–6 | [docs/principles/](docs/principles/) | `examples/01~06` |
| 框架 7–10 | [docs/frameworks/](docs/frameworks/) | `examples/07~09` + `java/` |
| RAG 11–13 | [docs/rag/](docs/rag/) | `examples/11~13` |
| 进阶 14–17 | [docs/advanced/](docs/advanced/) | `examples/14~17` |
| 工程 18–21 | [docs/engineering/](docs/engineering/) | `examples/18~21` |
| 客服实战 | [docs/lab/](docs/lab/) | `apps/customer-service-agent` |
| 其它实战 | [docs/projects/](docs/projects/) | `apps/vertical-agents` |
| 面试 | [docs/interview/](docs/interview/) | — |

---

## 快速开始

### 0. 先认识终端提示符

文档中的代码块只复制命令本身，不要复制 `$`、注释或终端输出。一行命令执行完、重新出现提示符后，再执行下一行。停止长期运行的服务使用 `Ctrl + C`。

### 1. 环境要求

- Node.js **>= 22.13**（推荐最新 22 LTS，仓库已提供 `.nvmrc`）
- pnpm 9+（本仓库锁定 `pnpm@10.5.2`）
- （可选）JDK 17+，用于 Java/Spring AI 对照章节

```bash
nvm use        # 或手动切换到 Node >= 22.13
node -v
pnpm -v
```

预期：`node -v` 显示 `v22.13.0` 或更高版本，`pnpm -v` 显示版本号。若 `nvm: command not found`，不代表仓库损坏，请按第 0 章选择 Node 安装方式。

### 2. 安装依赖

```bash
cp .env.example .env
# 编辑 .env：填入中转站 OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL

pnpm install
pnpm build
```

`pnpm install` 下载依赖，首次运行可能需要几分钟；`pnpm build` 编译 `packages/llm` 与 `packages/shared`。两条命令都应以 exit code 0 结束。

### 3. 先做连接自检（强烈推荐）

```bash
pnpm --filter @agent-tutorial/example-00-connection-check start
```

- 显示「对话可用」→ 可运行全部真实示例。
- 显示「对话不可用」→ 先按输出里的中文建议检查 Key、模型名和 URL。
- 即使模型暂不可用，带 mock 回退的示例仍可**离线演示**；日志出现“使用 mock”时，不能把它当成真实 API 验收结果。

### 4. 跑第一个示例

```bash
pnpm exec tsx examples/01-prompt-basics/index.ts
```

### 5. 启动客服 Agent（实战）

```bash
# 终端 1：后端（默认 8787）
pnpm --filter @agent-tutorial/customer-service-server dev

# 终端 2：Vue 前端
pnpm --filter @agent-tutorial/customer-service-web dev
# 或：pnpm dev:customer:web
```

前端入口：

- **工作台** `http://localhost:5173/`：左侧对话 + 右侧洞察
- **悬浮 Widget** `http://localhost:5173/embed`
- 文档站用 `pnpm docs:dev`（端口 **5174**），避免和客服前端抢 5173

---

## 仓库结构

```text
agent开发/
  packages/
    llm/          # 统一可切换模型客户端
    shared/       # 类型、日志、向量相似度、分块工具
  examples/       # 每章可运行示例
  apps/
    customer-service-agent/   # 客服 Agent（Node + Vue）
    vertical-agents/          # SQL Agent + 电商导购
  java/spring-ai-demo/        # Spring AI 对照工程
  docs/                       # VitePress 双轨教程
    .vitepress/               # 站点配置与主题
    lab/                      # 客服实战里程碑
    public/assets/            # 配图
```

## 换模型只改 .env

```env
OPENAI_BASE_URL=https://你的中转站/v1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o-mini
```

---

## License

MIT · 仅供学习