前端视角：AI Agent 工作流实战指南

这两年最火的技能不是写代码，而是「让 AI 帮你写代码」。本文从前端视角出发，用大白话讲透 AI Agent 工作流、Prompt Engineering、RAG 等核心技术，并提供可落地的代码实战。

开始之前：准备你的 AI API Key

推荐方案：DeepSeek（本文主推）

DeepSeek 注册步骤（2分钟搞定）

1. 访问 https://platform.deepseek.com/
2. 注册账号（支持手机号/邮箱）
3. 进入控制台 → API Keys → 创建新密钥
4. 复制 API Key（格式：sk-xxxxxxxxxxxxxxxx）
5. 保存到环境变量：DEEPSEEK_API_KEY=你的密钥

备选方案：2025年主流 AI 模型对比

模型	免费额度	注册门槛	付费价格（2025年最新）	推荐指数
DeepSeek V3 （推荐）	✓ 500万tokens	✓ 手机号/邮箱	¥2/M（输入）¥8/M（输出）	★★★★★
智谱GLM-4-Flash （免费）	完全免费！	✓ 手机号	完全免费	★★★★★
智谱GLM-4-Plus	✓ 赠送1亿免费tokens	✓ 手机号	¥5/M（降价90%）	★★★★
Google Gemini 1.5 Flash	✓ 1500次/天	✓ Google账号	免费层充足，付费低价	★★★★
通义千问 Max	✓ 100万tokens/月	✓ 阿里云账号	¥0.4-2/M（输入）¥0.8-8/M（输出）	★★★★
OpenAI GPT-5 mini	△ $5（3个月）	✗ 需国外手机号	$0.25/M（输入）$2/M（输出）≈¥1.8/¥14.4	★★★
OpenAI GPT-5 标准版	△ $5（3个月）	✗ 需国外手机号	$1.25/M（输入）$10/M（输出）≈¥9/¥72	★★★
Claude Haiku 4.5	△ $5（1个月）	✗ 需国外手机号	$1/M（输入）$5/M（输出）≈¥7.2/¥36	★★★
Claude 4.5 Sonnet	△ $5（1个月）	✗ 需国外手机号	$3/M（输入）$15/M（输出）≈¥21.6/¥108	★★（能力强但贵）

AI 工作流是什么？5分钟看懂

大白话：传统开发是你写死逻辑（if-else），AI 工作流是 AI 根据需求自己决定怎么做。

传统 API 调用 vs AI Agent

对比维度	传统 API 调用	AI Agent 工作流
逻辑	开发者写死（if-else）	AI 自主决策
灵活性	新需求需改代码	改 Prompt 就行
复杂度	逻辑越多代码越复杂	AI 自动组合工具
成本	开发成本高	Token 成本（按量付费）

真实业务场景

核心概念速通（不讲废话）

Prompt Engineering：让 AI 听话的艺术

大白话：就像跟实习生说话，你说得越清楚，他干得越好。

System Prompt（角色设定）

const systemPrompt = `你是一名资深前端工程师，擅长 React 和 TypeScript。
你的回答需要：
1. 直接给出可运行的代码（不要伪代码）
2. 包含 TypeScript 类型定义
3. 遵循 React 最佳实践
4. 代码要有注释

用户提问风格随意，你要理解意图并给出专业回答。`;

const userMessage = "帮我写个 React 表单组件，要有验证";

const response = await openai.chat.completions.create({
  model: "deepseek-chat", // DeepSeek 主力模型
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: userMessage }
  ]
});

Few-Shot Learning（给例子）

// ✗ 效果差：只给需求
const prompt = "把这段文字总结成标题";

// ✓ 效果好：给例子
const prompt = `请把文字总结成标题，参考以下示例：

示例1：
输入：前端性能优化需要关注 LCP、FID、CLS 三大指标...
输出：前端性能优化三大核心指标详解

示例2：
输入：React Hooks 让函数组件也能拥有状态和生命周期...
输出：React Hooks 完全指南

现在请处理：
输入：${userInput}
输出：`;

Chain of Thought（让 AI 思考）

// ✗ 直接让 AI 回答（容易出错）
const prompt = "2025年距离2000年多少天？";

// ✓ 让 AI 一步步思考
const prompt = `请一步步计算：2025年距离2000年多少天？

思考步骤：
1. 先算年份差
2. 再算闰年数量
3. 计算总天数

请按步骤输出你的思考过程。`;

Function Calling：让 AI 调用你的函数

大白话：就像给 AI 一个工具箱，它根据需要自己挑工具用。

// 1. 定义可供 AI 调用的函数
const functions = [
  {
    name: "get_weather",
    description: "获取指定城市的天气信息",
    parameters: {
      type: "object",
      properties: {
        city: {
          type: "string",
          description: "城市名称，如：北京、上海"
        }
      },
      required: ["city"]
    }
  },
  {
    name: "calculate",
    description: "执行数学计算",
    parameters: {
      type: "object",
      properties: {
        expression: {
          type: "string",
          description: "数学表达式，如：(100 + 50) * 2"
        }
      },
      required: ["expression"]
    }
  }
];

// 2. 调用 AI
const response = await openai.chat.completions.create({
  model: "deepseek-chat", // DeepSeek 主力模型
  messages: [{ role: "user", content: "北京今天天气怎么样？" }],
  functions: functions,
  function_call: "auto" // 让 AI 自动决定是否调用函数
});

// 3. 检查 AI 是否要调用函数
const message = response.choices[0].message;
if (message.function_call) {
  const functionName = message.function_call.name;
  const args = JSON.parse(message.function_call.arguments);

  // 4. 执行实际函数
  let result;
  if (functionName === "get_weather") {
    result = await getWeatherAPI(args.city);
  }

  // 5. 把结果返回给 AI
  const finalResponse = await openai.chat.completions.create({
    model: "deepseek-chat", // DeepSeek 主力模型
    messages: [
      { role: "user", content: "北京今天天气怎么样？" },
      message, // AI 的函数调用请求
      { role: "function", name: functionName, content: JSON.stringify(result) }
    ]
  });

  console.log(finalResponse.choices[0].message.content);
  // 输出：北京今天晴天，气温25度
}

RAG（检索增强生成）：让 AI 学会你的私有数据

大白话：AI 原本不知道你公司的业务，通过 RAG 让它先搜索相关文档，再回答。

RAG 实现流程

import { OpenAI } from 'openai';
import { ChromaClient } from 'chromadb';

// 1. 初始化向量数据库
const chroma = new ChromaClient();
const collection = await chroma.createCollection({ name: "docs" });

// 2. 把文档存入向量数据库
const documents = [
  "我们的退款政策：7天内无理由退款",
  "发货时间：工作日下单当天发货，周末顺延",
  "客服电话：400-123-4567，工作时间9:00-18:00"
];

await collection.add({
  documents: documents,
  ids: ["1", "2", "3"]
});

// 3. 用户提问时，先检索相关文档
const userQuestion = "你们多久发货？";

const results = await collection.query({
  queryTexts: [userQuestion],
  nResults: 2 // 取最相关的2条
});

// 4. 把检索到的文档注入 Prompt
const context = results.documents[0].join("\n");
const prompt = `基于以下信息回答用户问题：

信息：
${context}

用户问题：${userQuestion}

请用简洁的语言回答。`;

const response = await openai.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: prompt }]
});

console.log(response.choices[0].message.content);
// 输出：工作日下单当天发货，周末顺延到下周一发货。

前端如何集成 AI（代码实战）

基础：调用 DeepSeek API

// 安装依赖
// npm install openai

import OpenAI from 'openai';

// 配置 DeepSeek
const openai = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY, // 你的 DeepSeek API Key
  baseURL: "https://api.deepseek.com/v1" // DeepSeek API 地址
});

async function chat(message: string): Promise<string> {
  try {
    const response = await openai.chat.completions.create({
      model: "deepseek-chat", // DeepSeek 主力模型
      messages: [
        { role: "system", content: "你是一个友好的助手" },
        { role: "user", content: message }
      ],
      temperature: 0.7, // 创造性（0-2，越高越随机）
      max_tokens: 500   // 最大输出长度
    });

    return response.choices[0].message.content || "无回复";
  } catch (error) {
    console.error("AI 调用失败", error);
    throw error;
  }
}

// 使用
const answer = await chat("什么是闭包？");
console.log(answer);

进阶：流式输出（SSE）

为什么需要流式输出？ AI 生成内容慢，流式输出可以边生成边显示，提升用户体验。

// 前端 React 示例
import { useState } from 'react';

function ChatComponent() {
  const [messages, setMessages] = useState<string[]>([]);
  const [currentReply, setCurrentReply] = useState("");
  const [loading, setLoading] = useState(false);

  async function sendMessage(userInput: string) {
    setLoading(true);
    setCurrentReply("");

    // 调用后端 SSE 接口
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: userInput })
    });

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader!.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.trim() !== '');

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') {
            setLoading(false);
            setMessages(prev => [...prev, currentReply]);
            setCurrentReply("");
            return;
          }

          try {
            const parsed = JSON.parse(data);
            const content = parsed.choices[0]?.delta?.content || '';
            setCurrentReply(prev => prev + content);
          } catch (e) {
            console.error('解析失败', e);
          }
        }
      }
    }
  }

  return (
    <div>
      <div>
        {messages.map((msg, i) => (
          <div key={i}>{msg}</div>
        ))}
        {currentReply && <div>{currentReply}</div>}
        {loading && <span>AI 正在思考...</span>}
      </div>
      <button onClick={() => sendMessage("介绍一下 TypeScript")}>
        发送
      </button>
    </div>
  );
}

// 后端 Node.js 示例（Express）
import express from 'express';
import OpenAI from 'openai';

const app = express();
const openai = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1"
});

app.post('/api/chat', async (req, res) => {
  const { message } = req.body;

  // 设置 SSE 响应头
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  try {
    const stream = await openai.chat.completions.create({
      model: "deepseek-chat",
      messages: [{ role: "user", content: message }],
      stream: true // 关键：开启流式输出
    });

    for await (const chunk of stream) {
      const content = chunk.choices[0]?.delta?.content || '';
      if (content) {
        // 发送 SSE 格式数据
        res.write(`data: ${JSON.stringify(chunk)}\n\n`);
      }
    }

    res.write('data: [DONE]\n\n');
    res.end();
  } catch (error) {
    res.write(`data: ${JSON.stringify({ error: error.message })}\n\n`);
    res.end();
  }
});

app.listen(3000);

错误处理与重试

async function chatWithRetry(
  message: string,
  maxRetries = 3
): Promise<string> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await openai.chat.completions.create({
        model: "deepseek-chat",
        messages: [{ role: "user", content: message }],
        timeout: 30000 // 30秒超时
      });

      return response.choices[0].message.content || "无回复";
    } catch (error: any) {
      console.error(`第 ${i + 1} 次尝试失败`, error.message);

      // 速率限制，等待后重试
      if (error.status === 429) {
        const waitTime = Math.pow(2, i) * 1000; // 指数退避
        console.log(`速率限制，等待 ${waitTime}ms 后重试`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      // Token 超限，缩短输入
      if (error.status === 400 && error.message.includes('maximum context')) {
        throw new Error('输入内容过长，请缩短后重试');
      }

      // 最后一次重试失败，抛出错误
      if (i === maxRetries - 1) {
        throw error;
      }
    }
  }

  throw new Error('重试次数已用尽');
}

Token 计数与成本控制

import { encoding_for_model } from 'tiktoken';

// 计算 Token 数量
function countTokens(text: string, model: string = "gpt-3.5-turbo"): number {
  const encoder = encoding_for_model(model as any);
  const tokens = encoder.encode(text);
  encoder.free();
  return tokens.length;
}

// 预估成本
function estimateCost(inputText: string, outputText: string): number {
  const inputTokens = countTokens(inputText);
  const outputTokens = countTokens(outputText);

  // DeepSeek V3 价格（2025年2月起）
  const inputPrice = 0.002 / 1000;   // ¥0.002/1K tokens = ¥2/1M tokens
  const outputPrice = 0.008 / 1000;  // ¥0.008/1K tokens = ¥8/1M tokens

  return inputTokens * inputPrice + outputTokens * outputPrice;
}

// 使用
const input = "请介绍一下 TypeScript";
const output = await chat(input);
const cost = estimateCost(input, output);

console.log(`输入: ${countTokens(input)} tokens`);
console.log(`输出: ${countTokens(output)} tokens`);
console.log(`成本: $${cost.toFixed(6)}`);

切换到其他模型（2025年最新）

前面所有代码都基于 DeepSeek V3，如果你想切换到其他模型，只需改 3 个地方：

切换到 OpenAI GPT-5 系列（2025年8月发布）

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY, // ← 改1：换API Key
  baseURL: "https://api.openai.com/v1" // ← 改2：换地址
});

const response = await openai.chat.completions.create({
  model: "gpt-5-mini", // ← 改3：换模型名
  // 或 "gpt-5" (标准版) / "gpt-5-nano" (极速版)
  messages: [{ role: "user", content: "你好" }]
});

// 其他代码完全不变！

切换到 Claude 4.5 系列

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await anthropic.messages.create({
  model: "claude-haiku-4-5", // ← 或 "claude-4-5-sonnet"
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }]
});

切换到智谱GLM-4系列 ★完全免费

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.ZHIPU_API_KEY,
  baseURL: "https://open.bigmodel.cn/api/paas/v4/"
});

const response = await openai.chat.completions.create({
  model: "glm-4-flash", // ← 完全免费！
  // 或 "glm-4-plus" (¥5/M) / "glm-4-air" (¥1/M)
  messages: [{ role: "user", content: "你好" }]
});

切换到 Google Gemini 1.5（兼容OpenAI API）

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
  model: "gemini-1.5-flash", // ← 或 "gemini-1.5-pro"
  messages: [{ role: "user", content: "你好" }]
});

切换到通义千问

const openai = new OpenAI({
  apiKey: process.env.QWEN_API_KEY,
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
});

const response = await openai.chat.completions.create({
  model: "qwen-plus", // 或 "qwen-turbo" / "qwen-max"
  messages: [{ role: "user", content: "你好" }]
});

2025年主流模型对比总结

模型	价格（输入/输出）	免费额度	优势	劣势	推荐度
智谱GLM-4-Flash	完全免费	无限制	完全免费、性能优秀	无	★★★★★
DeepSeek V3	¥2/¥8M	500万tokens	超大免费额度、性价比极高	2025年2月涨价（仍很便宜）	★★★★★
Google Gemini 1.5 Flash	低价（见官网）	1500次/天	免费额度充足、兼容OpenAI	需要Google账号	★★★★
通义千问	¥0.4-2/¥0.8-8M	100万/月	中文理解好、阿里云集成	高级型号价格与DeepSeek相当	★★★★
智谱GLM-4-Plus	¥5M	1亿tokens	降价90%、性能强	无	★★★★
GPT-5 mini	$0.25/$2M≈¥1.8/¥14.4	$5（3个月）	性价比不错、GPT-5家族	注册难、门槛高	★★★
Claude Haiku 4.5	$1/$5M≈¥7.2/¥36	$5（1个月）	性能追平Sonnet、速度翻倍	注册难、价格较高	★★★
GPT-5 标准版	$1.25/$10M≈¥9/¥72	$5（3个月）	能力顶尖、上下文400K	价格高、门槛高	★★
Claude 4.5 Sonnet	$3/$15M≈¥21.6/¥108	$5（1个月）	编程能力直逼GPT-5	价格极高	★★（土豪专属）

Prompt Engineering 实战技巧

System Prompt 设计模板

// 模板 1：专业助手
const systemPrompt = `你是一名 ${角色}，具备以下特点：
- 专业能力：${技能列表}
- 回答风格：${风格描述}
- 输出格式：${格式要求}

限制条件：
- ${限制1}
- ${限制2}

示例：
输入：${示例输入}
输出：${示例输出}`;

// 实际应用：前端代码审查助手
const codeReviewPrompt = `你是一名资深前端工程师，具备以下特点：
- 专业能力：精通 React、TypeScript、性能优化、安全最佳实践
- 回答风格：严谨、直接指出问题、给出具体改进方案
- 输出格式：Markdown，包含问题等级（严重/警告/建议）

限制条件：
- 只关注代码质量，不讨论业务逻辑
- 必须给出可执行的代码示例
- 不要说"可能"、"也许"等模糊词汇

示例：
输入：
```tsx
function UserList() {
  const [users, setUsers] = useState([]);
  useEffect(() => {
    fetch('/api/users').then(res => setUsers(res.json()));
  }, []);
  return <div>{users.map(u => <div>{u.name}</div>)}</div>
}
```

输出：
## 严重问题
1. **缺少 key 属性**：列表渲染必须加 key
2. **Promise 处理错误**：fetch 返回的是 Promise，需要 await

## 修复代码
```tsx
function UserList() {
  const [users, setUsers] = useState<User[]>([]);

  useEffect(() => {
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data))
      .catch(err => console.error(err));
  }, []);

  return (
    <div>
      {users.map(u => <div key={u.id}>{u.name}</div>)}
    </div>
  );
}
```
`;

常见 Prompt 陷阱

陷阱	✗ 错误示例	✓ 正确示例
指令模糊	"帮我优化这段代码"	"这段代码存在性能问题，请： 1. 找出不必要的重渲染 2. 给出 useMemo/useCallback 优化方案"
缺少上下文	"这个组件有 bug"	"这是一个 React 表单组件，用户输入后点提交没反应，控制台也没报错，代码如下..."
期望不明确	"写个登录功能"	"写一个 React 登录表单组件，要求： 1. 使用 react-hook-form 2. 表单验证（邮箱格式、密码长度） 3. 提交时调用 /api/login"
没给例子	"把这些数据格式化"	"把数组转成对象，参考格式： 输入：[{id:1, name:'a'}] 输出：{1: {name:'a'}}"

高级技巧：Prompt 分层

// 对于复杂任务，分成多个步骤
async function complexTask(userInput: string) {
  // 步骤 1：理解需求
  const step1 = await openai.chat.completions.create({
    model: "deepseek-chat", // DeepSeek 主力模型
    messages: [{
      role: "user",
      content: `用户需求：${userInput}

请分析用户真正想要什么，输出JSON格式：
{
  "intent": "用户意图",
  "entities": ["关键实体"],
  "complexity": "简单|中等|复杂"
}`
    }]
  });

  const analysis = JSON.parse(step1.choices[0].message.content || "{}");

  // 步骤 2：根据复杂度选择策略
  if (analysis.complexity === "简单") {
    return await simpleTask(userInput);
  } else {
    // 步骤 3：复杂任务拆解
    const step3 = await openai.chat.completions.create({
      model: "deepseek-chat", // DeepSeek 主力模型
      messages: [{
        role: "user",
        content: `任务：${userInput}

请把这个任务拆解成 3-5 个子任务，输出 JSON 数组：
[
  { "step": 1, "task": "子任务描述", "依赖": [] },
  { "step": 2, "task": "子任务描述", "依赖": [1] }
]`
      }]
    });

    const subtasks = JSON.parse(step3.choices[0].message.content || "[]");

    // 步骤 4：依次执行子任务
    const results = [];
    for (const subtask of subtasks) {
      const result = await executeSubtask(subtask, results);
      results.push(result);
    }

    return results;
  }
}

业务案例

案例 1：智能客服机器人（带上下文记忆）

interface Message {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

class ChatBot {
  private conversationHistory: Message[] = [];
  private maxHistory = 10; // 最多保留 10 轮对话

  // 配置 DeepSeek
  private openai = new OpenAI({
    apiKey: process.env.DEEPSEEK_API_KEY,
    baseURL: "https://api.deepseek.com/v1"
  });

  constructor() {
    // 初始化系统提示
    this.conversationHistory.push({
      role: 'system',
      content: `你是智能客服助手，可以：
1. 查询订单状态（调用 get_order_status 函数）
2. 处理退款申请（调用 process_refund 函数）
3. 解答常见问题

回答要求：
- 友好、耐心
- 如果不确定，引导用户联系人工客服
- 不要编造信息`
    });
  }

  async chat(userMessage: string): Promise<string> {
    // 添加用户消息
    this.conversationHistory.push({
      role: 'user',
      content: userMessage
    });

    // 调用 AI
    const response = await this.openai.chat.completions.create({
      model: "deepseek-chat",
      messages: this.conversationHistory,
      functions: [
        {
          name: "get_order_status",
          description: "查询订单状态",
          parameters: {
            type: "object",
            properties: {
              order_id: { type: "string", description: "订单号" }
            },
            required: ["order_id"]
          }
        },
        {
          name: "process_refund",
          description: "处理退款申请",
          parameters: {
            type: "object",
            properties: {
              order_id: { type: "string" },
              reason: { type: "string", description: "退款原因" }
            },
            required: ["order_id", "reason"]
          }
        }
      ],
      function_call: "auto"
    });

    const message = response.choices[0].message;

    // 如果 AI 要调用函数
    if (message.function_call) {
      const functionName = message.function_call.name;
      const args = JSON.parse(message.function_call.arguments);

      let result;
      if (functionName === "get_order_status") {
        result = await this.getOrderStatus(args.order_id);
      } else if (functionName === "process_refund") {
        result = await this.processRefund(args.order_id, args.reason);
      }

      // 把函数执行结果返回给 AI
      this.conversationHistory.push(message);
      this.conversationHistory.push({
        role: 'function' as any,
        name: functionName,
        content: JSON.stringify(result)
      } as any);

      // AI 根据函数结果生成最终回复
      const finalResponse = await this.openai.chat.completions.create({
        model: "deepseek-chat",
        messages: this.conversationHistory
      });

      const reply = finalResponse.choices[0].message.content || "";
      this.conversationHistory.push({
        role: 'assistant',
        content: reply
      });

      // 限制历史长度
      if (this.conversationHistory.length > this.maxHistory * 2) {
        this.conversationHistory = [
          this.conversationHistory[0], // 保留 system prompt
          ...this.conversationHistory.slice(-this.maxHistory * 2)
        ];
      }

      return reply;
    }

    // 普通回复
    const reply = message.content || "";
    this.conversationHistory.push({
      role: 'assistant',
      content: reply
    });

    return reply;
  }

  private async getOrderStatus(orderId: string) {
    // 模拟调用订单 API
    return {
      order_id: orderId,
      status: "已发货",
      tracking_number: "SF1234567890"
    };
  }

  private async processRefund(orderId: string, reason: string) {
    // 模拟退款处理
    return {
      success: true,
      refund_id: "RF" + Date.now(),
      message: "退款申请已提交，预计3-5个工作日到账"
    };
  }
}

// 使用
const bot = new ChatBot();
console.log(await bot.chat("我的订单 12345 到哪了？"));
// AI 会自动调用 get_order_status，然后回复：
// "您的订单已发货，快递单号是 SF1234567890"

console.log(await bot.chat("帮我退款，质量有问题"));
// AI 会询问订单号，或者根据上下文记住是 12345
// 然后调用 process_refund，回复退款进度

案例 2：Markdown 文档问答助手（RAG）

import fs from 'fs';
import OpenAI from 'openai';
import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { MemoryVectorStore } from 'langchain/vectorstores/memory';

class DocQA {
  private vectorStore: MemoryVectorStore | null = null;
  private openai = new OpenAI({
    apiKey: process.env.DEEPSEEK_API_KEY,
    baseURL: "https://api.deepseek.com/v1"
  });

  // 初始化：加载文档
  async loadDocuments(markdownFiles: string[]) {
    // 1. 读取所有 Markdown 文件
    const documents = markdownFiles.map(file => ({
      pageContent: fs.readFileSync(file, 'utf-8'),
      metadata: { source: file }
    }));

    // 2. 文档分块（避免单个文档太长）
    const splitter = new RecursiveCharacterTextSplitter({
      chunkSize: 1000,      // 每块最多 1000 字符
      chunkOverlap: 200     // 块之间重叠 200 字符（保持上下文）
    });

    const chunks = await splitter.splitDocuments(documents);

    // 3. 向量化并存储
    const embeddings = new OpenAIEmbeddings({
      openAIApiKey: process.env.OPENAI_API_KEY
    });

    this.vectorStore = await MemoryVectorStore.fromDocuments(
      chunks,
      embeddings
    );

    console.log(`已加载 ${chunks.length} 个文档块`);
  }

  // 问答
  async ask(question: string): Promise<string> {
    if (!this.vectorStore) {
      throw new Error('请先加载文档');
    }

    // 1. 检索相关文档（Top 3）
    const relevantDocs = await this.vectorStore.similaritySearch(question, 3);

    // 2. 构建 Prompt
    const context = relevantDocs
      .map(doc => doc.pageContent)
      .join('\n\n---\n\n');

    const prompt = `基于以下文档内容回答用户问题。
如果文档中没有相关信息，明确告诉用户"文档中未找到相关内容"。

文档内容：
${context}

用户问题：${question}

回答：`;

    // 3. 调用 AI 生成答案
    const response = await this.openai.chat.completions.create({
      model: "deepseek-chat",
      messages: [{ role: "user", content: prompt }],
      temperature: 0.3 // 降低创造性，提高准确性
    });

    return response.choices[0].message.content || "无法生成答案";
  }
}

// 使用
const qa = new DocQA();
await qa.loadDocuments([
  './docs/deployment.md',
  './docs/api-reference.md',
  './docs/troubleshooting.md'
]);

console.log(await qa.ask("如何部署到生产环境？"));
// AI 会检索 deployment.md，然后总结出部署步骤

console.log(await qa.ask("API 速率限制是多少？"));
// AI 会检索 api-reference.md，找到速率限制说明

开源工具链推荐

核心库选择：openai（强烈推荐）

// 安装
// npm install openai

import OpenAI from 'openai';

// 使用 DeepSeek
const deepseek = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1"
});

// 使用 OpenAI
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.openai.com/v1"
});

// 使用通义千问
const qwen = new OpenAI({
  apiKey: process.env.QWEN_API_KEY,
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
});

// API 调用完全一样！
const response = await deepseek.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "你好" }]
});

备选库：Vercel AI SDK（仅限 OpenAI 官方）

对比维度	openai 库	Vercel AI SDK
模型支持	✓ 所有（DeepSeek/OpenAI/通义千问等）	✗ 仅官方（OpenAI/Claude/Cohere）
React 集成	△ 需要自己写 SSE 解析	✓ useChat hook 开箱即用
灵活性	✓ 完全控制	△ 封装较死
推荐场景	✓ 所有场景（尤其是用 DeepSeek）	△ 仅用 OpenAI 官方且追求快速开发

如果你坚持用 Vercel AI SDK（仅限 OpenAI）

// 安装
// npm install ai

// app/api/chat/route.ts（Next.js App Router）
import { OpenAIStream, StreamingTextResponse } from 'ai';
import { Configuration, OpenAIApi } from 'openai-edge';

const config = new Configuration({
  apiKey: process.env.OPENAI_API_KEY // △ 只能用 OpenAI 官方
});
const openai = new OpenAIApi(config);

export async function POST(req: Request) {
  const { messages } = await req.json();

  const response = await openai.createChatCompletion({
    model: 'gpt-3.5-turbo',
    stream: true,
    messages
  });

  const stream = OpenAIStream(response);
  return new StreamingTextResponse(stream);
}

// 前端组件
import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">发送</button>
      </form>
    </div>
  );
}

其他工具链

工具	定位	优势	适用场景
openai（推荐）	AI API 调用库	支持所有模型、灵活	所有场景（本文主推）
LangChain.js	AI 应用开发框架	功能全面、RAG 支持好	复杂 AI 应用（RAG、Agent）
Flowise	可视化 AI 工作流	拖拽式搭建、开源免费	非开发人员快速搭建
Dify	开源 AI 应用平台	包含 Prompt 管理、数据集	企业级 AI 应用开发
LlamaIndex	数据框架	专注 RAG、文档索引	文档问答、知识库

性能优化与成本控制

Prompt 压缩技巧

// ✗ 冗长的 Prompt（浪费 Token）
const badPrompt = `
您好，我是一名前端工程师，目前在做一个 React 项目。
我遇到了一个问题，就是当用户点击按钮的时候，页面没有反应。
我不知道是什么原因导致的，能否帮我分析一下可能的原因？
下面是我的代码：
${code}
`;

// ✓ 精简的 Prompt（节省 30-50% Token）
const goodPrompt = `React 按钮点击无反应，代码如下：
${code}

请分析原因。`;

缓存策略

import Redis from 'ioredis';

const redis = new Redis();

async function chatWithCache(message: string): Promise<string> {
  // 1. 生成缓存 key（基于消息内容）
  const cacheKey = `ai:chat:${hashString(message)}`;

  // 2. 检查缓存
  const cached = await redis.get(cacheKey);
  if (cached) {
    console.log('从缓存返回');
    return cached;
  }

  // 3. 调用 AI
  const response = await openai.chat.completions.create({
    model: "deepseek-chat",
    messages: [{ role: "user", content: message }]
  });

  const reply = response.choices[0].message.content || "";

  // 4. 缓存结果（过期时间 1 小时）
  await redis.setex(cacheKey, 3600, reply);

  return reply;
}

function hashString(str: string): string {
  // 简单的哈希函数
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) - hash) + str.charCodeAt(i);
    hash |= 0;
  }
  return hash.toString(36);
}

模型选型与成本对比（2025年最新）

模型	输入价格	输出价格	免费额度	性价比	适用场景
DeepSeek V3 ★	¥2/M	¥8/M	✓ 500万tokens	极致性价比	所有场景
智谱GLM-4-Plus	¥5/M	¥5/M	✓ 1亿tokens	高性价比	企业项目
通义千问 Max	¥0.4-2/M	¥0.8-8/M	✓ 100万/月	高性价比	中文场景、阿里云用户
Gemini 1.5 Flash	低价（见官网）	低价（见官网）	✓ 1500次/天	高性价比	个人项目、测试
GPT-5 mini	$0.25/M≈¥1.8	$2/M≈¥14.4	△ $5（3个月）	中等	一般对话、轻量任务
Claude Haiku 4.5	$1/M≈¥7.2	$5/M≈¥36	△ $5（1个月）	中等	编程任务
GPT-5 标准版	$1.25/M≈¥9	$10/M≈¥72	△ $5（3个月）	较低	复杂推理、高质量要求
Claude 4.5 Sonnet	$3/M≈¥21.6	$15/M≈¥108	△ $5（1个月）	低	顶级编程、长文本

最佳实践清单

总结

AI 工作流不是未来，而是现在。掌握这些技能可以让你：

1. 10 倍提效：AI 帮你写代码、审查代码、生成文档
2. 差异化竞争：同样是前端，你会 AI 应用开发
3. 业务价值：快速搭建 AI 功能（客服、助手、问答）