🌍 Web 全栈版 · Next.js + TypeScript

为什么切 Web 栈

Day 7 结束时的 Python 版能跑，但有三个明显的门槛：

1. 用户要装 Python 环境：venv + pip install + ARK_API_KEY 一堆步骤。
2. Streamlit 部署重：想给别人用只能自己跑云服务器，或者用 Streamlit Cloud（有额度限制）。
3. 没法逐字流式：Streamlit 的执行模型是"每次交互整个脚本从头跑"，答案只能等 tool loop 全跑完再一次性 render。

切 Next.js 一次性解决三件事：

• 用户打开 URL 就用，无需装环境
• Vercel 免费额度可上（当然要处理 SQLite 持久化，见 下一步）
• SSE 天然流式，一个字一个字往前端推

架构总览

┌────────────────────┐        ┌────────────────────────┐
│  app/page.tsx      │  SSE   │  app/api/chat/route.ts │
│  (Client React)    │◀───────│  (Streaming Response)  │
└────────────────────┘        └───────────┬────────────┘
                                          │
                                          ▼
                              ┌────────────────────────┐
                              │  lib/agent.ts          │
                              │  KnowledgeAgent        │
                              │  · runTurnStream()     │
                              │    async generator     │
                              └───┬──────────┬─────────┘
                                  │          │
                    ┌─────────────┘          └──────────┐
                    ▼                                    ▼
              ┌─────────┐                          ┌──────────┐
              │lib/tools│                          │lib/memory│
              │  7 tools│                          │  压缩逻辑│
              └────┬────┘                          └──────────┘
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
   ┌────────┐  ┌────────┐  ┌────────┐
   │ lib/kb │  │Tavily  │  │ lib/   │
   │ SQLite │  │(联网)  │  │embedding
   │+cosine │  │        │  │(火山方舟)
   └────────┘  └────────┘  └────────┘

关键设计：lib/agent.ts 只 yield 事件、不做任何 HTTP/UI；API route 把事件转成 SSE；React 消费 SSE 更新组件状态。引擎/表现层分离比 Day 6 更彻底，因为跨了进程边界。

技术选型对照 Python 版

向量库：ChromaDB → SQLite + 手写 cosine

Python 版用 ChromaDB —— 但它对 Web 部署不友好（要么起 Docker 服务，要么用 Chroma Cloud）。Web 版换成 SQLite + 手写 cosine 相似度。

存储 schema

CREATE TABLE chunks (
  id TEXT PRIMARY KEY,        -- "go-tips.md#0"
  file TEXT,
  chunk_idx INTEGER,
  text TEXT,
  embedding BLOB,             -- Float32Array 的字节序列
  tags TEXT
);

Cosine 就是三行数学

function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number {
  let dot = 0, na = 0, nb = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    na  += a[i] * a[i];
    nb  += b[i] * b[i];
  }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

Float32Array 的字节魔法

SQLite BLOB 只认字节。TypedArray 恰好有 .buffer 属性给你原始 ArrayBuffer：

// 存
function embeddingToBlob(v: number[]): Buffer {
  const arr = new Float32Array(v);
  return Buffer.from(arr.buffer);
}

// 取
function blobToEmbedding(buf: Buffer): Float32Array {
  return new Float32Array(
    buf.buffer,
    buf.byteOffset,
    buf.byteLength / Float32Array.BYTES_PER_ELEMENT,
  );
}

每个 float 4 字节；1024 维向量 = 4 KB。55 个 chunks 全放内存 = 220 KB，比一个头像还小。

流式对话：async generator + SSE

Web 版原生做了流式（Python 教程里只写了设计笔记，见 streaming-notes.md）。核心两个动作：

1) Agent 层：async generator yield 事件

async *runTurnStream(userInput: string): AsyncGenerator<TurnEvent> {
  this.memory.append({ role: "user", content: userInput });

  for (let round = 1; round <= this.maxRounds; round++) {
    const stream = await this.client.chat.completions.create({
      model: this.model,
      messages: this.memory.getMessages(),
      tools: TOOLS_SCHEMA,
      stream: true,
      stream_options: { include_usage: true },
    });

    // 累加器：拼出完整 assistant 消息
    let contentBuf = "", reasoningBuf = "";
    const toolCallsBuf: Record<number, {id, name, arguments}> = {};

    for await (const chunk of stream) {
      const delta = chunk.choices?.[0]?.delta;
      if (delta.content) {
        contentBuf += delta.content;
        yield { type: "answer_delta", text: delta.content };   // 一个字就吐一个字
      }
      if (delta.reasoning_content) {   // Doubao 特有
        reasoningBuf += delta.reasoning_content;
        yield { type: "thought_delta", text: delta.reasoning_content };
      }
      // tool_calls 按 index 归类累加
      for (const tc of delta.tool_calls ?? []) {
        const slot = (toolCallsBuf[tc.index] ??= {id: null, name: "", arguments: ""});
        if (tc.function?.arguments) slot.arguments += tc.function.arguments;
        // ...
      }
    }
    // 执行工具、yield tool_call_start / tool_call_result
  }
  yield { type: "turn_done", result };
}

2) API route：generator → SSE

const stream = new ReadableStream({
  async start(controller) {
    const encoder = new TextEncoder();
    for await (const event of agent.runTurnStream(message)) {
      controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
    }
    controller.close();
  },
});
return new Response(stream, {
  headers: {
    "Content-Type": "text/event-stream; charset=utf-8",
    "Cache-Control": "no-cache",
  },
});

3) 前端：fetch + ReadableStream 消费

const resp = await fetch("/api/chat", { method: "POST", body: ... });
const reader = resp.body!.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  // 按 \n\n 切分事件块，解析 data: 行
}

可中断 streaming：signal 一路穿透

用户等答案久了想停止 —— Stop 按钮不是"只停止 UI 渲染"，而是要把 abort 信号一路穿透到 OpenAI SDK 和 web_search fetch，同时回滚 memory 避免下一 turn 400。

信号链路

点击 ⏹ → controller.abort()
        │
        ▼
   fetch("/api/chat", { signal }) 被 abort
        │  (req.signal fire)
        ▼
   API route 拿到 req.signal
        │
        ▼
   agent.runTurnStream(msg, req.signal)
        │
   ┌────┴────┐
   ▼         ▼
OpenAI SDK   web_search fetch
create(..., {signal})   fetch(..., {signal: AbortSignal.any([...])})
   │         │
   ▼         ▼
抛 APIUserAbortError / AbortError
   │
   ▼
agent catch → memory.rollbackTo(baseline) → 重新抛
   │
   ▼
route catch → 判断是 abort → 发 {type:"aborted"} 而不是 error

1) 前端：AbortController 存 useRef

const abortRef = useRef<AbortController | null>(null);

async function submit() {
  const controller = new AbortController();
  abortRef.current = controller;
  let userAborted = false;
  try {
    const resp = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ message }),
      signal: controller.signal,   // 传给 fetch
    });
    // ...consume SSE...
    // 事件里如果拿到 {type:"aborted"} → userAborted = true
  } catch (e) {
    if ((e as Error).name === "AbortError") userAborted = true;
  } finally {
    abortRef.current = null;
  }
}

const stopGeneration = () => abortRef.current?.abort();

2) 后端：signal 穿透 + memory 回滚

// lib/agent.ts
async *runTurnStream(userInput: string, signal?: AbortSignal) {
  // 记录基线：abort 后回滚到这里
  const memoryBaseline = this.memory.size();
  this.memory.append({ role: "user", content: userInput });

  try {
    for (let round = 1; round <= this.maxRounds; round++) {
      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");

      const stream = await this.client.chat.completions.create(
        { model, messages, tools, stream: true, ... },
        { signal },   // ← OpenAI SDK 会把 signal 透传到底层 fetch
      );
      // ... consume stream, execute tools with { ...ctx, signal } ...
    }
  } catch (e) {
    const name = (e as Error).name;
    if (name === "AbortError" || name === "APIUserAbortError") {
      // 回滚：把这个 turn 加进去的所有消息撤掉。
      // 否则下一 turn 会有 "assistant.tool_calls 但没跟 tool response" → 400
      this.memory.rollbackTo(memoryBaseline);
    }
    throw e;
  }
}

3) web_search：AbortSignal.any 合并用户 abort + 15s 超时

// lib/tools.ts
const timeoutSignal = AbortSignal.timeout(15000);
const signal = ctx.signal
  ? AbortSignal.any([ctx.signal, timeoutSignal])   // Node 20+
  : timeoutSignal;

await fetch("https://api.tavily.com/search", {
  method: "POST",
  body: JSON.stringify({ query, ... }),
  signal,
});

要点汇总

跑起来

cd agents-web
cp .env.example .env.local
# 编辑 .env.local 填入 ARK_API_KEY / ARK_ENDPOINT_ID / ARK_EMBEDDING_ENDPOINT_ID

npm install
npm run dev
# 打开 http://localhost:3000
# 侧栏点 "🔄 仅重建索引" 建库（约 10 秒）
# 然后就能问了

预期体验：

• 问 "Go 错误处理" → 侧边显示"🔧 正在调用 search_notes"，然后答案一个字一个字冒出来
• 问 "Python 3.13 新特性" → 先 search_notes（相似度低）→ 再 web_search（如果配了 TAVILY_API_KEY）
• 历史消息里能展开每一轮的 Thought + tool 参数 + 返回
• 聊多轮后侧栏"对话记忆"进度条爬满 → 触发自动摘要压缩，主区显示蓝色提示卡

实际运行效果

问 "go 怎么处理错误的" 之后的实际截图：

能看到的能力（对照截图从上到下）：

• ✅ 逐字流式：答案 token-by-token 冒出来（截图是完成后的静态；实际交互时能看到光标闪烁）
• ✅ 可中断 streaming：流式期间"发送"按钮切换成红色"⏹ 停止"，点了立刻 abort —— 前端 AbortController → 后端 req.signal → OpenAI SDK 和 web_search fetch 一起断，memory 回滚到 turn 起点保证下一 turn 干净
• ✅ Markdown + 代码块保留：```go … ``` 三反引号包起来的代码块原样保留（当前用 whitespace-pre-wrap，未来可接 react-markdown 做真正的高亮）
• ✅ 引用溯源：答案末尾自动带 [来源: go-tips.md]
• ✅ 多轮工具调用可展开：这个例子 Agent 先 list_notes（第 1 轮）再 search_notes（第 2 轮），两轮都是可折叠卡片
• ✅ ReAct Thought 可见：第 1 轮展开里的蓝色框显示 Doubao 抓到的 reasoning_content —— 用户能看到"Agent 为什么调这个工具"
• ✅ Token 统计：底部 3 轮 · 2 次工具调用 · 11094 tokens
• ✅ 记忆进度条 > 80% 变橙：截图侧栏 3481 / 3000 字符，进度条橙色告警下一 turn 会触发压缩

🕳️ 踩坑

🚀 下一步方向

1. 🟢 换 Turso（libSQL 兼容 SQLite）：改一行 import Database from "@libsql/client"，直接上 Vercel
2. 🟢 可中断 streaming：AbortController 传给 fetch，前端"停止"按钮
3. 🟡 本地 LLM 后端：ARK_BASE_URL 换成 http://localhost:11434/v1（Ollama）
4. 🟡 多 Agent 编排：LangGraph.js，或者手写 handoff
5. 🔴 发布：域名 + Vercel + Turso + 用户认证（NextAuth），让别人真能用