从零到上线
AI Chat 完整学习手册

interface ProviderAdapter {
    buildRequestBody(opts: BuildRequestOptions): Record<string, any>;
    parseChunk(parsed: any): ParsedChunk;
  }
  
  // 不同模式的温度 & max_tokens
  function modeParams(mode: ChatMode) {
    return {
      temperature: mode === 'fast' ? 0.7 : mode === 'think' ? 0.3 : 0.5,
      max_tokens:  mode === 'fast' ? 2048 : mode === 'think' ? 8192 : 16384,
    };
  }
  
  // DeepSeek 适配器 —— 思考模式自动切换 deepseek-reasoner
  const deepseekAdapter: ProviderAdapter = {
    buildRequestBody({ messages, mode, model, userModelId }) {
      const finalModelId = userModelId || (mode==='think' ? 'deepseek-reasoner' : model.model_id);
      return { model: finalModelId, messages, stream: true, ...modeParams(mode) };
    },
    parseChunk(parsed) {
      const delta = parsed.choices?.[0]?.delta || {};
      return { content: delta.content, reasoning: delta.reasoning_content, tokens: parsed.usage?.total_tokens };
    },
  };
  
  // 通用 OpenAI 兼容适配器（Moonshot / 豆包 / Qwen...）
  function getAdapter(provider: string): ProviderAdapter {
    const map = { deepseek: deepseekAdapter, minimax: minimaxAdapter, qwen: qwenAdapter, doubao: doubaoAdapter };
    return map[provider] ?? defaultAdapter;
  }

// ⚠️ flushHeaders() 必须在首次 write() 之前调用，否则响应头会混入 body
res.setHeader('Content-Type',     'text/event-stream');
res.setHeader('Cache-Control',     'no-cache');
res.setHeader('Connection',        'keep-alive');
res.setHeader('X-Accel-Buffering', 'no'); // 必须！关闭 Nginx 缓冲，否则所有内容攒到最后才一次性返回
res.flushHeaders(); // 立即将响应头推送给客户端，SSE 通道正式建立

// SSE 协议规范：event: xxx\ndata: JSON\n\n（末尾两个换行是必须的分隔符）
const writeEvent = (event: string, data: any) =>
  res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);

await aiService.streamChat({
  modelId, messages, mode,
  // 每收到一个文字 delta 就立即推给客户端，用户实时看到字符
  onChunk:     (chunk)     => writeEvent('chunk',     { content: chunk }),
  // DeepSeek R1 / think 模式的推理过程，前端单独展示为折叠面板
  onReasoning: (reasoning) => writeEvent('reasoning', { content: reasoning }),
  // 流结束：写 DB、扣 Token、关闭连接（顺序不能颠倒）
  onDone: (fullText, reasoningText, tokensUsed) => {
    chatService.addMessage(conversation_id, 'assistant', fullText, {
      reasoning_content: reasoningText || undefined,
      tokens_used: tokensUsed,
    });
    userService.deductTokens(userId, tokensUsed);
    writeEvent('done', { fullText, reasoningText, tokensUsed });
    res.end();
  },
  onError: (err) => { writeEvent('error', { message: err.message }); res.end(); },
});

// 用 fetch 而非 EventSource：支持 POST + 自定义 Header（Bearer Token）
const res = await fetch('/api/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
  body: JSON.stringify({ conversation_id, model_id, mode, message }),
});

const reader  = res.body!.getReader();
const decoder = new TextDecoder();
let buf = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  // 按 SSE 协议分隔符 \n\n 切割；最后一段可能不完整，留到下次循环拼接
  const parts = buf.split('\n\n');
  buf = parts.pop() ?? '';
  for (const part of parts) {
    const evt  = part.match(/^event: (\w+)/m)?.[1];
    const data = part.match(/^data: (.+)/m)?.[1];
    if (!evt || !data) continue;
    const { content } = JSON.parse(data);
    if (evt === 'chunk')     setReply(r     => r + content);
    if (evt === 'reasoning') setThinking(r  => r + content);
    if (evt === 'done')      setLoading(false);
    if (evt === 'error')     toast.error(content);
  }
}

// 内容类型分流：注入不同系统提示词
if (content_type === 'webdesign') {
  historyMessages.unshift({ role: 'system', content: getWebDesignSystemPrompt() });
} else if (content_type === 'career') {
  historyMessages.unshift({ role: 'system', content: getCareerSystemPrompt() });
}
// 网页设计模式强制 expert（max_tokens=16384，避免 HTML 被截断）
const effectiveMode = content_type === 'webdesign' ? 'expert' : mode;

// 限额配置：免费=0张、体验券=2张、源码版=4张
const planLimits: Record<string, number> = { experience: 2, source: 4 };
const imageLimit = planLimits[user.plan_type] ?? 0;

if (imageLimit === 0) {
  return { error: '\u56fe\u7247\u751f\u6210\u4e3a\u4ed8\u8d39\u529f\u80fd', need_upgrade: true };
}
// 生成成功后计数回写
const imageUrl = await aiService.generateImage(prompt);
userService.incrementImagesUsed(userId);
return { imageUrl, images_used: imagesUsed + 1 };

// 用户传入 Key 时，跳过 DB 读取，直接使用
if (!userApiKey) {
  model = getModelById(modelId);
  if (!model.api_key) {
    // DB 为空时，从环境变量坤底（DEEPSEEK_API_KEY 等）
    const envKey = getEnvApiKey(model.provider);
    if (envKey) model = { ...model, api_key: envKey };
  }
}
const apiKey  = userApiKey  || model?.api_key;
const baseUrl = userBaseUrl || model?.base_url || 'https://api.openai.com/v1';

// 扫描 fullContent 中所有 [IMAGE_N] 占位符（不依赖 Agent1 的规划）
const foundPlaceholders = new Set<number>();
const placeholderRe = /\[IMAGE_(\d+)\]/g;
let phMatch: RegExpExecArray | null;
while ((phMatch = placeholderRe.exec(fullContent)) !== null) {
  foundPlaceholders.add(parseInt(phMatch[1], 10));
}

// 并行生成所有图片
await Promise.all(sortedIndices.map(async (index) => {
  const prompt = effectiveImagePrompts[index] ?? `high quality illustration for: ${plan.summary}`;
  if (canGenerateImages) {
    writeEvent('image_start', { index, prompt });
    const url = await multimodalService.generateImage(prompt);
    imageResults.set(index, url);
    writeEvent('image', { index, url });
  }
}));

// 存库前替换占位符，周刷不再浮现占位符
let savedContent = fullContent;
imageResults.forEach((url, index) => {
  const replacement = url
    ? `![\u751f\u6210\u56fe\u7247${index + 1}](${url})`
    : `> \u26A0\uFE0F \u56fe\u7247${index + 1}\u751f\u6210\u5931\u8d25`;
  savedContent = savedContent.replace(`[IMAGE_${index}]`, replacement);
});
// 清除没有生成器对应的残留占位符
savedContent = savedContent.replace(/\[IMAGE_\d+\]/g, '');
chatService.addMessage(conversation_id, 'assistant', savedContent, { content_type: 'multimodal' });

// cleanMermaidArtifacts — 清除 DOM 污染
function cleanMermaidArtifacts(id?: string) {
  if (id) document.getElementById(id)?.remove();
  document.querySelectorAll('[id^="mermaid-"], .mermaid-error-icon, .mermaid > svg.error-icon')
    .forEach((el) => el.remove());
}

// 覆盖 parseError 防止默认渲染
try { (mermaid as any).parseError = () => {}; } catch { /* ignore */ }

// catch 块中清理并优化错误提示
} catch (err: any) {
  if (gen !== genRef.current) return;
  cleanMermaidArtifacts(id); // 删除 DOM 污染
  const raw = typeof err === 'string' ? err : (err?.message ?? String(err));
  const msg = raw.split('\n')
    .filter((l: string) => !/mermaid version/i.test(l)) // 过滤版本行
    .join(' ')
    .replace(/Syntax error in text/gi, '\u56fe\u8868\u8bed\u6cd5\u9519\u8bef')
    .slice(0, 120);
  setError(msg || 'Mermaid \u56fe\u8868\u6e32\u67d3\u5931\u8d25');
}

const humanKeywords = [
  '\u4eba\u5de5', '\u5ba2\u670d', '\u4eba\u5de5\u670d\u52a1', '\u8f6c\u4eba\u5de5', '\u4eba\u5de5\u5ba2\u670d',
  '\u8054\u7cfb\u5ba2\u670d', '\u9700\u8981\u4eba\u5de5', '\u627e\u5ba2\u670d', '\u627e\u4eba', '\u5de5\u4f5c\u4eba\u5458',
];
const negativeKeywords = [
  '\u4e0d\u6ee1\u610f', '\u6ca1\u7528', '\u5783\u573e', '\u5dee\u8bc4', '\u5931\u671b', '\u7cd5\u7cd5', '\u6295\u8bc9', '\u4e0d\u5bf9', '\u9519\u4e86',
  '\u8fd9\u4e0d\u662f\u6211\u60f3\u8981\u7684', '\u5b8c\u5168\u4e0d\u5bf9', '\u7b54\u975e\u6240\u95ee',
];

const needsHuman = humanKeywords.some((k) => t.includes(k));
const isNegative = negativeKeywords.some((k) => t.includes(k));
return {
  negative: isNegative || needsHuman,
  needsHuman,
  emotion: needsHuman ? 'needs_human' : isNegative ? 'negative' : 'neutral',
};

// onDone 回调中分析情绪
const allMsgs = chatService.getMessages(conversation_id);
const lastUserMsg = [...allMsgs].reverse().find((m) => m.role === 'user');
const emotion = analyzeEmotion(lastUserMsg?.content || '');

// 负面情绪或人工需求：自动建工单
if (emotion.negative) {
  ticketService.createTicket({
    userId, conversationId: conversation_id,
    lastUserMessage: lastUserMsg?.content?.slice(0, 500),
    emotion: emotion.emotion, needsHuman: emotion.needsHuman,
  });
}

// done 事件携带 needsHuman 字段
writeEvent('done', { fullText, reasoningText, tokensUsed, needsHuman: emotion.needsHuman });

// SSE done 事件 needsHuman=true 时插入 human_support 消息
if (evt === 'done' && data.needsHuman) {
  addMessage(conversation_id, {
    id: Date.now(),
    role: 'assistant',
    content: '__human_support__',
    content_type: 'human_support',
  });
}

// ChatMessages.tsx 中识别 special 类型
if (msg.content_type === 'human_support') {
  return <HumanSupportCard key={msg.id} />; // 微信二维码 + 关闭按钒
}