构建可扩展 AI Agent 系统的三次演进

prisma/schema.prisma          # 新建 Discussion 表src/ai/tools/discussionChat.ts  # 新工具src/ai/tools/saveDiscussion.ts   # 保存工具src/app/(study)/agents/studyAgent.ts     # 添加工具到 Agentsrc/app/(study)/agents/fastInsightAgent.ts  # 再添加一次src/app/(study)/agents/productRnDAgent.ts   # 再添加一次... 还有 6 个文件

// studyAgentRequest.ts (493 行)export async function studyAgentRequest(context) {  const result = await streamText({    model: llm("claude-sonnet-4"),    system: studySystem(),    messages,    tools: {      webSearch,      interview,      scoutTask,      saveAnalyst,      generateReport      // ... 15 个工具    },    onStepFinish: async (step) => {      // 保存消息      // 跟踪 token      // 发送通知      // ... 120 行逻辑    }  });}// fastInsightAgentRequest.ts (416 行)// 95% 相同的代码// productRnDAgentRequest.ts (302 行)// 95% 相同的代码

class ResearchSession {  state: 'IDLE' | 'PLANNING' | 'RESEARCHING' | 'REPORTING';  data: {    interviews: Interview[];    findings: Finding[];    reports: Report[];  };  transition(event: Event) {    switch (this.state) {      case 'IDLE':        if (event.type === 'START') this.state = 'PLANNING';        break;      case 'PLANNING':        if (event.type === 'PLAN_COMPLETE') this.state = 'RESEARCHING';        break;      // ... 更多状态转换    }  }}

const messages = [  { role: 'user', content: '想了解年轻人对咖啡的偏好' },  { role: 'assistant', content: '我可以帮你做一个用户研究...' },  { role: 'assistant', toolCalls: [{ name: 'scoutTask', args: {...} }] },  { role: 'tool', content: '观察到了 5 个用户群体...' },  { role: 'assistant', content: '基于观察，我建议访谈 18-25 岁咖啡爱好者...' },  { role: 'assistant', toolCalls: [{ name: 'interviewChat', args: {...} }] },  // ...];

// ❌ 传统：显式状态管理interface ResearchState {  stage: 'planning' | 'researching' | 'reporting';  completedInterviews: number;  pendingTasks: Task[];}// 需要同步：状态和对话历史可能不一致

// ✅ AI-native：对话即状态const messages = [...conversationHistory];// AI 自己从历史推断状态，无需显式同步const result = await streamText({  messages,  // AI 知道该做什么});

// Plan Mode：理解意图"用户说：想了解年轻人对咖啡的偏好"  → 分析：需要定性研究  → 决策：用群体讨论方法  → 输出：完整的研究计划// Study Agent：执行计划"收到研究计划"  → 调用 discussionChat  → 分析讨论结果  → 生成洞察报告

// 精确匹配相关记忆const query_embedding = await embed(user_message);const relevant_memories = await vectorDB.search(query_embedding, top_k=5);

// 简单透明const memory = await readFile(`memories/${userId}.md`);const messages = [  { role: 'user', content: `<UserMemory>\n${memory}\n</UserMemory>` },  ...conversationMessages];

// 地方 1：analyst 表const analyst = await prisma.analyst.findUnique({  where: { id }});console.log(analyst.studySummary);  // "研究总结..."// 地方 2：interviews 表const interviews = await prisma.interview.findMany({  where: { analystId: id }});console.log(interviews.map(i => i.conclusion));  // ["访谈1结论", "访谈2结论"]// 地方 3：messages 表const messages = await prisma.chatMessage.findMany({  where: { userChatId }});// webSearch 结果在这里

async function generateReport(analystId) {  const analyst = await prisma.analyst.findUnique({    where: { id: analystId },    include: { interviews: true }  // JOIN！  });  const messages = await prisma.chatMessage.findMany({    where: { userChatId: analyst.studyUserChatId }  });  // 拼接数据  const reportData = {    summary: analyst.studySummary,              // 来自 analyst 表    interviewInsights: analyst.interviews.map(...),  // 来自 interviews 表    webResearch: extractFromMessages(messages)    // 来自 messages 表  };}

// interviewChat：内容在 DB，返回引用{  toolName: 'interviewChat',  output: { interviewId: 123 }  // 需要再查询 DB}// scoutTaskChat：内容在返回值{  toolName: 'scoutTaskChat',  output: {    plainText: "观察结果...",  // 直接返回内容    insights: [...]  }}

// ✅ 新架构：统一输出格式interface ResearchToolResult {  plainText: string;  // 人类可读的总结，必需  [key: string]: any; // 可选的结构化数据}// interviewChat 也返回 plainText{  toolName: 'interviewChat',  output: {    plainText: "访谈总结：用户张三表示...",  // ← 完整内容在这里    interviewId: 123  // 可选：DB 引用  }}

// 不预先保存，用时再生成if (!analyst.studyLog) {  const messages = await loadMessages(studyUserChatId);  const studyLog = await generateStudyLog(messages);  // ← 从消息生成  await prisma.analyst.update({    where: { id },    data: { studyLog }  });}

删除文件：- src/ai/tools/saveInterview.ts- src/ai/tools/saveDiscussion.ts- src/ai/tools/saveScoutTask.ts- src/ai/tools/savePersona.ts- src/ai/tools/saveWebSearch.ts简化文件（28 个）：- Agent 配置不再需要保存工具- generateReport 不需要多表 JOIN

添加 discussionChat：1. 创建 Discussion 表2. 写 discussionChat 工具3. 写 saveDiscussion 工具4. 在 3 个 Agent 中添加这两个工具5. 写 discussion 查询逻辑6. 修改 generateReport 查询总计：12 个文件，2-3 天

添加 discussionChat：1. 写 discussionChat 工具（返回 plainText）2. 在 Agent 配置中添加工具3. generateReport 自动支持（从消息读取）总计：3 个文件，2-3 小时

AI: "你想研究哪个年龄段？"User: "18-25岁吧"AI: "你想用什么方法？访谈还是问卷？"User: "访谈"AI: "需要多少人？"User: "10个左右"

$ wc -l src/app/(study)/agents/*AgentRequest.ts493 studyAgentRequest.ts416 fastInsightAgentRequest.ts302 productRnDAgentRequest.ts

// src/app/(study)/agents/configs/planModeAgentConfig.tsexport async function createPlanModeAgentConfig() {  return {    model: "claude-sonnet-4-5",    systemPrompt: planModeSystem({ locale }),    tools: {      requestInteraction,  // 和用户交互      makeStudyPlan,       // 展示完整计划，一键确认    },    maxSteps: 5,  // 最多 5 步完成意图澄清  };}

// src/app/(study)/agents/baseAgentRequest.ts (577 行)interface AgentRequestConfig<TOOLS extends ToolSet> {  model: LLMModelName;  systemPrompt: string;  tools: TOOLS;  maxSteps?: number;  specialHandlers?: {    // 动态控制哪些工具可用    customPrepareStep?: (options) => {      messages,      activeTools?: (keyof TOOLS)[]    };    // 自定义后处理逻辑    customOnStepFinish?: (step, context) => Promise<void>;  };}async function executeBaseAgentRequest<TOOLS>(  baseContext: BaseAgentContext,  config: AgentRequestConfig<TOOLS>,  streamWriter: UIMessageStreamWriter) {  // Phase 1: Initialization  // Phase 2: Prepare Messages  // Phase 3: Universal Attachment Processing  // Phase 4: Universal MCP and Team System Prompt  // Phase 5: Load Memory and Inject into Context  // Phase 6: Main Streaming Loop  // Phase 7: Universal Notifications}

// src/app/(study)/api/chat/route.tsif (!analyst.kind) {  // Plan Mode - 意图澄清  const config = await createPlanModeAgentConfig(agentContext);  await executeBaseAgentRequest(agentContext, config, streamWriter);} else if (analyst.kind === AnalystKind.productRnD) {  // Product R&D Agent  const config = await createProductRnDAgentConfig(agentContext);  await executeBaseAgentRequest(agentContext, config, streamWriter);} else {  // Study Agent（综合研究、快速洞察、测试、创意等）  const config = await createStudyAgentConfig(agentContext);  await executeBaseAgentRequest(agentContext, config, streamWriter);}

// src/app/(study)/agents/configs/studyAgentConfig.tsexport async function createStudyAgentConfig(params) {  return {    model: "claude-sonnet-4",    systemPrompt: studySystem({ locale }),    tools: buildStudyTools(params),  // ← 这个 Agent 需要的工具    specialHandlers: {      // 自定义工具控制      customPrepareStep: async ({ messages }) => {        const toolUseCount = calculateToolUsage(messages);        let activeTools = undefined;        // 报告生成后，限制可用工具        if ((toolUseCount[ToolName.generateReport] ?? 0) > 0) {          activeTools = [            ToolName.generateReport,            ToolName.reasoningThinking,            ToolName.toolCallError,          ];        }        return { messages, activeTools };      },      // 自定义后处理      customOnStepFinish: async (step) => {        // 保存研究意图后，自动生成标题        const saveAnalystTool = findTool(step, ToolName.saveAnalyst);        if (saveAnalystTool) {          await generateChatTitle(studyUserChatId);        }      },    },  };}

删除：- studyAgentRequest.ts (493 行)- fastInsightAgentRequest.ts (416 行)- productRnDAgentRequest.ts (302 行)合计：-1,211 行新增：+ baseAgentRequest.ts (577 行)+ planModeAgentConfig.ts (120 行)+ studyAgentConfig.ts (180 行)+ productRnDAgentConfig.ts (80 行)合计：+957 行净减少：-254 行

添加 MCP 集成：1. 修改 studyAgentRequest.ts2. 修改 fastInsightAgentRequest.ts3. 修改 productRnDAgentRequest.ts4. 测试三个 Agent时间：2-3 天

添加 MCP 集成：1. 修改 baseAgentRequest.ts2. 所有 Agent 自动获得新能力时间：2-3 小时

用户："想了解年轻人对咖啡的偏好"AI："你想研究哪个年龄段？"用户："18-25 岁"AI："你想用什么方法？"用户："访谈吧"AI："需要多少人？"...（3-5 轮对话）

用户："想了解年轻人对咖啡的偏好"AI 展示完整计划：┌─────────────────────────────────────┐│ 【研究计划】                        ││ 目标：理解 18-25 岁年轻人咖啡偏好   ││ 方法：群体讨论（5-8 人）            ││ 预计时长：40 分钟                   ││ 输出：消费者洞察报告                ││                                     ││ [确认开始] [修改计划]               │└─────────────────────────────────────┘

const result = await streamText({  messages: currentConversation,  // ← 只有当前对话  // 没有历史对话的上下文});

model Memory {  id      Int  @id @default(autoincrement())  userId  Int? // 用户级记忆  teamId  Int? // 团队级记忆  version Int  // 版本管理  // 双层架构  core    String @default("") @db.Text  // 核心记忆（Markdown）  working Json   @default("[]")         // 工作记忆（JSON，待整合）  changeNotes String @db.Text  // 本次更新说明  @@unique([userId, version])  @@index([userId, version(sort: Desc)])}

# 用户信息- 行业：消费品行业产品经理- 关注：年轻消费者偏好、新兴趋势# 研究风格- 偏好定性研究（访谈、讨论）- 重视真实用户声音，而非数据统计

[  { "info": "用户最近关注咖啡赛道", "source": "chat_123" },  { "info": "偏好群体讨论方法", "source": "chat_124" }]

// src/app/(memory)/actions.tsasync function updateMemory({ userId, conversationContext }) {  let memory = await loadLatestMemory(userId);  // Step 1: 超过阈值时重组（Claude Sonnet 4.5）  if (memory.core.length > 8000 || memory.working.length > 20) {    memory = await reorganizeMemory(memory, conversationContext);  }  // Step 2: 提取新信息（Claude Haiku 4.5）  const newInfo = await extractMemoryUpdate(memory.core, conversationContext);  if (newInfo) {    // Step 3: 插入新信息到指定位置    await insertMemoryInfo(memory, newInfo);  }}

// src/app/(study)/agents/baseAgentRequest.ts// Phase 5: Load Memoryconst memory = await loadUserMemory(userId);if (memory?.core) {  // 注入到对话开头  modelMessages = [    {      role: 'user',      content: `<UserMemory>\n${memory.core}\n</UserMemory>`    },    ...modelMessages  ];}// Phase 6: Streamingconst result = await streamText({  messages: modelMessages,  // ← 包含用户记忆  // ...});// Phase 7: 非阻塞更新记忆waitUntil(  updateMemory({ userId, conversationContext: messages }));

第 1 次对话：User: "想做个咖啡研究"AI: "你从事什么行业？"User: "消费品行业"AI: "你关注哪些维度？"...第 2 次对话（一周后）：User: "想做个茶饮研究"AI: "你从事什么行业？"  # ← 又问了一遍

第 1 次对话：User: "想做个咖啡研究"AI: "你从事什么行业？"User: "消费品行业产品经理"# AI 记住了第 2 次对话（一周后）：User: "想做个茶饮研究"AI: "基于你作为消费品行业产品经理的背景，我建议..."  # ← 记住了！

Memory Update（每次对话）：- Model: Claude Haiku 4.5- Tokens: ~5K- Cost: ~$0.001Memory Reorganize（每 20 次对话）：- Model: Claude Sonnet 4.5- Tokens: ~15K- Cost: ~$0.02平均成本：~$0.002/次对话

Memory 加载：+50ms（非阻塞）Memory 更新：后台运行，不影响响应

重复代码：Before: 1,211 行（三个 Agent wrapper）After: 0 行减少：100%总代码行数：Before: 1,211 行（重复）+ 其他After: 577 行（base）+ 380 行（configs）= 957 行净减少：254 行（21%）Cyclomatic Complexity（代码复杂度指标）：Before: avg 12.3After: avg 6.7降低：45%

Token 消耗（有 prompt cache）：- studyLog 生成: ~2K tokens (~$0.002)- Memory 更新: ~5K tokens (~$0.005)- 平均每次对话：+$0.007响应时间：- Memory 加载: +50ms（非阻塞）- Plan Mode: +2s（一次性）- studyLog 生成：后台，不影响响应

意图澄清：Before: 平均 3.2 轮对话After: 1 次展示计划 + 1 次确认提升：3x 效率AI "记忆"：Before: 每次对话问重复问题After: 自动加载用户偏好提升：个性化体验研究启动时间：Before: ~5 分钟（多轮澄清）After: ~1 分钟（一键确认）提升：5x 效率

// 完全类型安全的工具处理const tool = step.toolResults.find(  t => !t.dynamic && t.toolName === ToolName.generateReport) as StaticToolResult<Pick<StudyToolSet, ToolName.generateReport>>;if (tool?.output) {  const token = tool.output.reportToken;  // ← TypeScript 知道这个字段存在}

// baseAgentRequest.tsif (webhookUrl) {  await sendWebhook(webhookUrl, step);}