最近这段时间一直在折腾 AI Agent 的实际落地，前前后后试了好几个技术栈组合。这套Next.js + LangGraph.js 简历工具 AI Agent是我个人完整跑通、并且觉得最值得拿出来分享的一套方案。它解决的不是"做个聊天机器人"这种玩具问题，而是把一份简历从上传、解析、评估到给出可执行修改建议的完整流程，真正交给了 Agent 来驱动。
先说说为什么选这个方向。简历优化这个场景，看起来简单，其实特别适合 Agent 来干：输入是非结构化的文本，中间涉及多轮推理（哪里薄弱、为什么薄弱、怎么改），输出又需要结构化的评估和建议。单纯用提示词模板硬套，效果很不稳定；用普通后端流程写死，又没法处理各种意外情况。而用 LangGraph.js 把整个流程编排成有状态、可中断、可恢复的图，配合 Next.js 做交互层，体验和可维护性都能兼顾。
这篇文章我会从需求拆解、架构选型、状态图设计、核心实现、前端联调、再到实际踩坑记录，把整套落地过程完整讲一遍。代码和方案都是实际可复现的，适合已经熟悉 React/Next.js、想往 Agent 方向深入，或者正打算做类似"文档处理类 Agent"的朋友参考。
1. 简历工具为什么值得做成 Agent：普通表单和提示词模板的边界在哪里
在动手写代码之前，我花了不少时间想一个问题：简历优化这个需求，到底需不需要用 Agent？用传统方案行不行？这个想清楚了，后面才不会把架构做复杂。
传统方案无非两种。第一种是写一个表单页面，用户粘贴简历文本，后端用一个写死的 prompt 调一次大模型，返回一篇修改建议。这种方案的问题在于，简历内容差异极大——有人发来的是一段纯文本，有人是 PDF 里扒出来的乱格式，有人只有三五行工作经历，有人写了密密麻麻的十几页。一个固定 prompt 很难同时处理这些情况，结果是给资深工程师的建议和对应届生的建议几乎一样。第二种是用多轮对话的方式做，每次用户上传简历之后，让大模型"你问我答"地了解情况。但这又引入了另一个问题：普通对话没有强制结构，用户不问，模型就不会主动深入分析，最后产出的东西深度完全不可控。
Agent 的介入改变了这个局面。它的核心不是"多轮对话"，而是把一个复杂的任务拆成多个可以由模型自主决策的步骤，每一步都有明确的输入、输出和检查点。落到简历这个场景里就是：
- 第一步，把用户上传的原始文本清洗成结构化数据（基本信息、教育经历、工作经历、技能清单）；
- 第二步，基于岗位方向对结构化简历做逐项评估；
- 第三步，根据评估结果生成针对性的修改建议；
- 第四步，把这些内容组装成一份用户能直接看、直接用的报告。
这个流程里，每一步的结果都可能影响下一步的执行方式。比如第一步发现用户简历里完全没写技能清单，第二步评估的时候就不能判"技能缺失"然后给一句"建议补充技能"就完事，而应该结合用户的目标岗位方向，主动推荐该岗位的核心技能关键词。这种"根据中间结果动态调整后续动作"的能力，就是 Agent 相对普通表单流程最大的优势。
还有一个重要的点是用户要的不是一篇泛泛的建议，而是一份能照着改的清单。所以输出格式必须严格结构化。传统提示词模板虽然也能要求输出 JSON，但一旦某个环节需要重新处理，整个流程就要从头跑一遍。用了 Agent 编排之后，我可以随时把流程暂停在某个节点上，让用户补充信息，再从这个节点恢复执行，成本和体验完全不一样。
2. 技术选型与总体架构：为什么是 Next.js 和 LangGraph.js，它们各自扛什么职责
选 Next.js 做前端和 BFF（后端 for 前端）层，理由很直接：生态成熟、可以前后端一体部署，而且 API Route 处理流式响应非常顺手。LangGraph.js 则是整个 Agent 的运行时核心，它提供了一套将 Agent 状态机化的框架。
先看一个很多人会混淆的问题：既然 LangChain.js 也有 Agent 概念，为什么我还要上 LangGraph.js？我最初也是从 LangChain.js 的create_agent这类高层 API 开始试的，但很快就碰到了三个问题：
- 流程控制不够精细。LangChain.js 的高层 Agent API 更适合对话型交互，对于"解析-评估-生成建议"这种有固定流水线但中间又需要动态分支的场景，它给不了清晰的 DAG（有向无环图）控制；
- 状态管理是隐式的。我需要把每一步的中间结果（结构化简历、评分明细、用户补充信息）持久化下来，方便出错重试和断点续跑，LangChain.js 的默认实现里这块不够透明；
- 人工介入不方便。简历这个场景里，用户经常需要在流程进行中修改信息（比如纠正公司名称、补充一个项目经历），这意味着 Agent 要能"暂停等待用户输入"，而不是一条路跑到黑。LangGraph.js 的
interrupt机制正好干这个。
LangGraph.js 给的核心抽象就两个：StateGraph和State。State是一个全局共享的数据结构，每个节点执行完后可以更新它；StateGraph定义节点之间的连接关系和条件分支。你可以把它理解成一个带记忆的流水线：产品沿着传送带前进，每个工位（节点）读取产品当前状态、做加工、把加工结果写回产品，然后根据结果决定下一站去哪个工位。
整体架构上，我把它分成了三层：
| 层级 | 技术组件 | 职责 |
|---|---|---|
| 交互层 | Next.js App Router + React | 简历上传、流式展示评估过程、用户补充信息的弹窗交互 |
| 编排层 | LangGraph.js（运行在 API Route 内） | 状态图构建、节点执行、中断/恢复控制 |
| 模型层 | 大模型 API（兼容 OpenAI 协议）+ 结构化输出 | 文本解析、评分推理、建议生成 |
这里强调一点，LangGraph.js 本身是大模型无关的，你接哪家模型都行。我这里用的是兼容 OpenAI 协议的接口，因为这套协议是目前兼容性最好的。实际开发中，你的大模型 API 只需要两个能力：支持函数调用（或 JSON mode），支持流式输出。前者用于让模型的输出可以被程序安全解析，后者用于把中间过程实时推送给前端。
3. LangGraph.js 状态图设计：简历 Agent 的核心流程图与数据模型
这个部分是整个项目的灵魂。很多人用 LangGraph.js 失败，不是不会写代码，而是把状态图设计得太复杂或者太简单。太复杂导致链路调试困难，太简单又把 Agent 退化成了普通流水线。我的设计思路是：把一个简历评估拆成五个节点，每个节点只干一件大事，节点之间用清晰的 State 字段传递信息。
3.1 状态数据模型
先定义ResumeState。这个状态是整个图执行的"公共黑板"，所有节点都读写它：
type ResumeState = { // 用户输入的原始内容 rawText: string; // 用户指定的目标岗位方向，如 "前端工程师" targetRole: string; // 也可以让用户粘贴岗位 JD，作为评估依据 targetJD?: string; // 节点输出区 parsedResume: ParsedResume | null; // 节点1 输出 gapAnalysis: GapAnalysis | null; // 节点2 输出 scores: ScoreReport | null; // 节点3 输出 suggestions: SuggestionItem[] | null; // 节点4 输出 // 人工介入标记 userConfirmations: Record<string, unknown>; // 中断恢复时用的恢复数据 pendingUserInput?: { type: "confirm_company_name" | "select_role" | "supply_missing_skills"; context: unknown; }; };每个节点写完自己的结果就更新对应字段。后面的节点只需要读前面的字段，不需要关心它们是怎么生成的。这样设计的好处是图执行到一半挂了，我可以直接把整个ResumeState序列化保存下来，下次从断点恢复。
3.2 五个节点的职责划分
我用的是五个节点，按顺序分别是：
- 解析节点（parse_resume）：把用户上传的原始文本转成结构化对象。关键设计是输出必须符合严格的 JSON Schema，字段包括
personalInfo、education、workExperience[]、projects[]、skills[]等。如果文本里信息缺失，字段用空数组或 null 表示，不要凭空编造。 - 岗位对齐节点（align_role）：这一步很多人会忽略，但恰恰是简历评估质量的分水岭。它把目标岗位方向或者岗位 JD 转成一份"该岗位能力需求清单"（比如前端岗需要：React 生态、工程化、性能优化、跨端能力等）。这份清单是后续评分和建议的标尺。
- 差距分析节点（analyze_gap）：把结构化简历和岗位需求清单做比对，逐条判断匹配度，输出
GapAnalysis。内容包含每一项的匹配状态：match（匹配）、partial（部分匹配）、missing（缺失）、irrelevant（无关）。 - 评分节点（score_resume）：基于差距分析结果，从"技术深度、项目经验、技能匹配度、表达清晰度"四个维度打分，每个维度附一段 80 字以内的解释。分数不是凭空生成的，而是由差距分析里的具体条目推导出来的，这样用户追问分数原因时我们给得出解释。
- 生成建议节点（generate_suggestions）：根据评分和差距分析，输出优先级从高到低的修改建议。建议必须具体到"把你第 2 段的第一个项目描述改成这样：XXX"，而不是泛泛说"建议加强项目描述"。
3.3 边的设计与条件路由
连接这些节点的边也不是简单的一条直线。我加了两处条件路由：
- 解析节点 -> 岗位对齐节点：如果
parsedResume中关键字段全为空（比如用户只贴了三行字），则直接路由到一个人工介入节点，提示用户补充基本信息，而不是继续往下走。这个判断在真实场景里救了很多次——真有用户就贴一句"我是前端工程师，5年经验"就想让 AI 给出评估。 - 评分节点 -> 建议生成节点：如果评分结果里有任一维度低于阈值（比如低于 60 分），就额外调用一次模型对低分维度做深度分析，生成"专项改进建议"，挂载到对应的
suggestionItem里。这样避免所有建议都堆在一个大 JSON 里，内容层次更清晰。
下面用一个表格总结路由逻辑，方便你对照设计：
| 起点 | 终点 | 路由依据 |
|---|---|---|
parse_resume | align_role | parsedResume非空 |
parse_resume | human_interrupt | parsedResume关键字段为空 |
align_role | analyze_gap | 岗位需求清单生成成功 |
analyze_gap | score_resume | gapAnalysis条目数 > 0 |
score_resume | generate_suggestions | 无条件 |
score_resume | generate_suggestions | scores存在低分维度时，同时追加专项深挖节点 |
这里有个设计取舍：我没有把"人类介入"当做一个独立的 State 节点，而是通过interrupt()函数在任意节点内暂停执行，等外部程序补充状态后继续。这个后面在实现部分详细说。
4. 核心节点实现细节：结构化输出、评分规则与流式推送的代码落地
状态图设计好之后，真正写代码实现节点反而是最顺手的事。这一节我把几个关键节点的实现要点拆开讲，每个都有可复制的代码片段。
4.1 解析节点：用 JSON Schema 约束输出，别信自由文本
解析节点的核心是让大模型输出严格的、符合预期结构的 JSON。我推荐用StructuredOutputParser或者直接使用大模型的response_format: {type: "json_object"}。不过我更推荐在 LangGraph 里用输出校验函数做二次保险：模型返回 JSON 后，程序先校验必填字段，如果不合法就让模型基于错误信息重新生成一次。
const parseResumeNode: NodeFunction<ResumeState> = async (state) => { const { rawText, targetRole } = state; const prompt = ` 你是一个简历解析器。请从以下原始文本中提取结构化信息。 原始文本： --- ${rawText} --- 要求： 1. 只提取文本中真实存在的信息，不要编造。 2. 工作经历里的时间统一成 "YYYY.MM - YYYY.MM" 格式。 3. 如果某项信息缺失，使用空数组或 null。 4. 严格按照下面的 JSON 输出，不要输出其他内容。 { "personalInfo": { "name": string, "phone": string, "email": string }, "education": [{ "school": string, "degree": string, "major": string, "duration": string }], "workExperience": [{ "company": string, "title": string, "duration": string, "highlights": string[] }], "projects": [{ "name": string, "description": string, "techStack": string[], "highlights": string[] }], "skills": string[] } `; const parser = new StructuredOutputParser(JSONSchema); let result; try { result = await llm.invoke(prompt, { response_format: { type: "json_object" }, }); result = parser.parse(result); } catch (e) { // 解析失败，带着错误信息重试一次 result = await repairJsonWithError(prompt, e.message); } return { parsedResume: result }; };这里repairJsonWithError是一个很实用的工具函数：把模型上次的原始输出和校验报错一起丢回给模型，让它修正后重新输出。这个机制比单纯重试好用得多，因为模型往往只是小毛病（多了一个逗号、字段名拼错），看到具体错误提示之后很容易改对。
4.2 评分节点：四条评分维度如何从差距分析推导出来
评分节点如果直接用模型"打分"，很容易出现分数忽高忽低的情况。我的做法是：先让模型对每个维度做证据枚举，再基于证据给分数。打个比方，不是让考官直接给"面试表现 80 分"，而是让他先说"面试者项目经历深挖时条理清晰、能讲清难点，但系统设计环节没答上来"，然后据此打分。
const scoreResumeNode: NodeFunction<ResumeState> = async (state) => { const { parsedResume, gapAnalysis } = state; const prompt = ` 根据如下差距分析结果，为简历打分。 差距分析： ${JSON.stringify(gapAnalysis, null, 2)} 我只需要四个维度的分数，每个维度的评分说明必须先列出2-3条具体证据，再给出分数。 维度定义： - techDepth（技术深度）：项目是否涉及复杂业务、性能优化、架构设计 - projectMatch（项目匹配）：项目经验与目标岗位的相关度 - skillHit（技能匹配）：技能清单与岗位需求清单的覆盖率 - expression（表达清晰）：描述是否量化、是否突出个人贡献 输出格式： { "techDepth": { "score": 0-100, "evidence": string[], "comment": string }, "projectMatch": { "score": 0-100, "evidence": string[], "comment": string }, "skillHit": { "score": 0-100, "evidence": string[], "comment": string }, "expression": { "score": 0-100, "evidence": string[], "comment": string } } `; const result = await llm.invoke(prompt, { response_format: { type: "json_object" }, }); return { scores: result }; };注意我把evidence和comment放在同一个 JSON 对象里。前端展示时，证据可以折叠展示，评论直接显示在分数旁边。这样用户看到分数时不觉得是"黑箱打分"，而是"AI 给出了理由，我认可或反驳它再决定信不信"。
这里有个很重要的经验：不要让模型直接对原始简历打分，一定要先经过"差距分析"这一步。差距分析本质上是把复杂的评分任务拆成了一个个小的、可验证的判断（"这个人的技能清单里有没有 React？——有"）。这些判断合在一起，分数推导就变得稳定且可信。如果你让模型直接跳到最后一步，评分理由往往写得空泛，而且分数和具体建议会对不上。
4.3 流式推送：把每个节点的执行状态实时送到前端
LangGraph.js 对流式的支持做得不错，但我用的是更朴素的方法：在每个节点内部，通过回调把当前状态推给前端。这样我可以控制推送的粒度和格式，不让前端感知到 LangGraph 的存在。
const nodeWithStream = (nodeFn, stageLabel) => async (state) => { const start = Date.now(); const eventId = crypto.randomUUID(); // 通知前端当前阶段开始 await pushToSSE(eventId, { type: "stage_start", stage: stageLabel, state: extractPublicState(state), }); try { const updates = await nodeFn(state); await pushToSSE(eventId, { type: "stage_complete", stage: stageLabel, state: extractPublicState(updates), durationMs: Date.now() - start, }); return updates; } catch (e) { await pushToSSE(eventId, { type: "stage_error", stage: stageLabel, error: e.message, }); throw e; } };extractPublicState是为了避免把完整的、可能包含敏感信息的 state 推给前端，只挑几个必要字段推送。前端收到stage_start就显示"正在解析简历..."，收到stage_complete就更新对应板块的内容。
对于大模型生成建议这种耗时长的阶段，我还会在节点内部启用 token 级别的流式输出，把生成中的建议文本逐段推送到前端。这个实现看起来像这样：
const generateSuggestionsNode = async (state) => { const stream = await llm.stream(prompt); let accumulated = ""; for await (const chunk of stream) { accumulated += chunk.content; await pushToSSE(streamId, { type: "suggestion_delta", stage: "generate_suggestions", delta: chunk.content, }); } return { suggestions: parseAccumulated(accumulated) }; };这里和stage_complete事件有一个轻微的设计冲突，需要理清：suggestion_delta是给用户看的"正在生成"效果，而stage_complete是给前端逻辑用的"可以正式更新 UI 数据了"。两者不冲突，前端分别监听即可。
5. Next.js 侧接入：API Route、流式响应和"人工中断恢复"的实战处理
App Router 的 API Route 是 LangGraph.js 运行的地方。我用route.ts接收前端请求，创建图的执行实例，然后通过Response返回 SSE 流。
5.1 创建运行时和图实例
// app/api/analyze-resume/route.ts import { NextRequest } from "next/server"; import { runResumeAgentGraph } from "@/lib/agent/graph"; export async function POST(request: NextRequest) { const body = await request.json(); const { rawText, targetRole, targetJD } = body; // 校验输入 if (!rawText || rawText.length < 10) { return new Response( JSON.stringify({ error: "简历文本太短，请补充内容" }), { status: 400 } ); } const encoder = new TextEncoder(); // 使用 SSE 流式返回 const stream = new ReadableStream({ async start(controller) { // 收到前端断开信号时中止 Agent 执行 const abortController = new AbortController(); request.signal.addEventListener("abort", () => { abortController.abort(); }); const sendEvent = (event: unknown) => { controller.enqueue( encoder.encode(`data: ${JSON.stringify(event)}\n\n`) ); }; try { await runResumeAgentGraph({ rawText, targetRole, targetJD, onEvent: sendEvent, signal: abortController.signal, }); } catch (e) { sendEvent({ type: "fatal_error", error: (e as Error).message }); } finally { controller.close(); } }, }); return new Response(stream, { headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform", Connection: "keep-alive", }, }); }runResumeAgentGraph内部做的就是：初始化ResumeState，构建StateGraph，编译，然后调用graph.invoke(initialState, { onEvent })。把onEvent回调透传进图内节点，就实现了前面说的节点内部推送。
5.2 中断恢复：怎么让 Agent"停下来等用户"再继续跑
这是整套方案里最有 Agent 感的一个设计。用户上传的简历中经常有信息缺失的情况，比如没有目标岗位，或者公司名称被 OCR 识别得乱七八糟。此时如果流程继续往下跑，最后生成的报告质量一定很差。传统的做法是报错让用户重来。用 LangGraph.js 的interrupt()，流程会在特定位置暂停，等待外部数据补给后从暂停处继续。
我封装了一个工具函数：
import { interrupt } from "@langchain/langgraph"; export async function askUser( state: ResumeState, question: { id: string; type: "input" | "select" | "confirm"; question: string; options?: string[]; } ): Promise<Record<string, unknown>> { // 将 pendingUserInput 写入 state，前端能感知到 state.pendingUserInput = { type: question.id, context: question, }; const userResponse = await interrupt({ question, }); // 恢复后清空 pending 标记 state.pendingUserInput = undefined; return userResponse; }在前端，当收到stage_complete事件中带有pendingUserInput字段时，我会渲染一个中断弹窗，展示给用户的是类似这样的交互：
// 前端伪代码：处理中断弹窗 function InterruptModal({ pending, onResolve }) { if (pending.type === "select_role") { // 渲染岗位方向选择器 return <RoleSelector options={pending.options} onConfirm={onResolve} />; } if (pending.type === "confirm_company_name") { // 渲染文本确认框 return ( <TextConfirm original={pending.context.original} suggested={pending.context.suggested} onConfirm={(editable) => onResolve({ confirmedName: editable })} /> ); } }用户确认之后，前端把结果通过一个POST /api/agent/resume的resume请求发回后端。后端拿到回复之后，调用graph.invoke，带上Command(resume = userResponse)恢复执行。LangGraph.js 会从上次interrupt的位置继续往下跑，已经完成过的节点不会重复执行。
这里有个细节：中断恢复必须用一个新的图实例，但状态要从上次执行完的ResumeState里加载。所以我在数据库或记忆中保存了上次的执行状态快照。最简单的方式就是把ResumeState直接存在服务端 session 里，恢复时取出来塞回图里。如果你是部署在 Serverless 环境，可以考虑存 Redis，key 用本次任务的runId。
5.3 前端的事件协议设计
为了让前后端配合不出岔子，我设计了下面这套 SSE 事件协议。每个事件都带type，前端根据type分派处理：
| 事件 type | 触发时机 | 前端动作 |
|---|---|---|
stage_start | 节点刚开始 | 显示阶段状态栏，"正在解析..."、"正在评估..." |
stage_complete | 节点正常结束 | 更新对应板块的正式数据 |
stage_error | 节点抛错 | 显示错误提示，提供重试按钮 |
suggestion_delta | 建议文本流式生成中 | 实时追加显示生成中的建议 |
interrupt | 等待用户输入 | 弹窗展示待确认信息 |
run_complete | 全流程图执行完 | 展示最终报告，隐藏状态栏 |
run_idle | 图停了但没有走完 | 提示用户手动继续或放弃 |
前端的整体状态机很简单：running -> waiting_for_input -> resume_running -> done。收到interrupt时进入waiting_for_input，此时停止展示状态栏的"加载中"动画，改成弹窗交互。用户提交后置回resume_running，并把弹窗关闭，恢复状态栏。
6. 完整跑通之后的踩坑记录：LangGraph.js 版本差异、中断恢复丢失与流式乱序
代码写完之后，真正让我掉头发的不是架构设计，而是各种环境、版本和细节问题。这一节分享三个我觉得最有代表性的坑，以及完整的排查思路，希望能帮你少走点弯路。
6.1 坑一：LangGraph.js 不同小版本的事件序列差异
项目初期我用的@langchain/langgraph版本比较旧，graph.invoke结束后会默认吐出一个完整的事件数组。后来升级版本，发现 invoke 的返回结构变了，很多事件的type从"on_llm_end"变成了新的格式。最直观的现象是：前端突然收不到stage_start事件了，因为我在回调里判断了event.event === "on_node_start"，而新版本改成了event.name === "node_start"之类的字段。
排查路径是这样走的：
- 先在前端看网络面板，发现 SSE 流是通的，有数据返回，说明问题出在后端事件翻译层；
- 在后端打印
event结构，对比新旧版本的类型定义； - 发现旧代码里的事件名判断完全失效，需要改成读取统一的
event.meta字段； - 由于我们的事件协议是自己定义的（
stage_start等），所以最终修复方案是把 LangGraph 的原生事件彻底隐藏，不依赖它的具体格式，只用我们自己的节点包裹函数发事件。
这个坑给我最大的教训是：不要让业务代码直接依赖 LangGraph 原生事件的字段名，因为小版本升级就会破坏它们。正确做法是在节点内部显式发送自定义事件，原生事件只用来做执行流兜底。
6.2 坑二：中断恢复后状态丢失了一半
我用interrupt()做的用户确认功能，在上线初期碰到了一个问题：用户确认公司名称之后继续跑，后面的节点都正常，但最终报告里展示的解析结果，居然还是 OCR 纠正之前的旧数据。
一开始很迷惑：用户明明确认了新公司名，我也把Command(resume = { confirmedName: "某某科技有限公司" })传进去了。后来仔细排查才发现问题出在我的节点更新方式上。我写的恢复逻辑是：
const updatedState = await graph.invoke(initialState, { command: new Command(resume = { ... }), // 只更新了部分字段 });但 LangGraph.js 的Command恢复更新的是当前节点的返回字段，它是在当前状态快照的基础上合并的。而我后面节点读parsedResume时，用的还是旧状态里的对象引用，并没有把用户确认的新值回写到parsedResume.company。
修复方案是在askUser恢复之后，显式地修改状态：
const userResume = await askUser(state, question); if (question.type === "confirm_company") { const target = state.parsedResume.workExperience.find( (item) => item.company === question.context.original ); if (target) { target.company = userResume.confirmedName; } } return state;也就是说，中断之后的恢复逻辑不能只把用户输入塞进 Command 就完事，还要根据业务规则决定"这份输入到底更新状态里的哪个位置"。这个业务判断是模型做不了的，必须开发者自己写清楚。
6.3 坑三：多路流式输出导致前端 UI 顺序错乱
在建议生成阶段，我用了流式 token 推送，同时在评分节点也有一个"正在评分中"的动画提示。结果前端偶尔会出现"评分动画还在转，建议已经出来了"这种怪现象。排查之后发现是并发问题：评分节点和后续的建议节点在某种情况下会并行触发推送，而 SSE 是单通道的，前端收到的顺序就是交错的了。
这里我做了三个层面的修复：
- 在节点内部，明确把"业务完成事件"和"流式 token 事件"分成两个通道：前者用
stage_complete，后者统一用delta，前端严格按照type分派，不再混用一套事件名； - 前端对每个板块的 UI 状态只管"是否收到
stage_complete"，收到之前统一显示"分析中"，不再单独根据 token 流做动画； - 后端给每个事件打上
runId和stageId标记，前端收到事件后先校验这两个 id 是否匹配当前任务，不匹配直接丢弃。
这些修改之后，前端再也没出现过板块错乱的情况。我给的建议是：不要低估前端事件消费的复杂度，事件协议宁可多设计一些字段，也不要事后打补丁。
6.4 预算与耗时控制：简历报告的 token 消耗实测
最后说一个很多人忽略的工程问题：token 成本。一个简历从解析到生成最终建议，如果全程不节制，很容易一次消耗 3-5 万 token，接口耗时 30 秒以上。我对节点做了下面这些优化：
- 解析节点不要求模型输出格式化好的 markdown，只输出紧凑 JSON，省掉大量空白 token；
- 评分节点的输入是
gapAnalysis而不是原始简历，这样评分模型只需要看一份精简的中间结果，而不是啰嗦的原文； - 建议节点的 prompt 限定输出总长度（比如每条建议不超过 120 字），而且要求"直接给结论，不要铺垫"；
- 全局给大模型请求加
max_tokens，解析节点和建议节点分开设置，避免某个节点失控。
优化后，一次完整评估的 token 消耗压在了 1.2 万到 1.8 万之间，耗时控制在 15 到 25 秒，用户等待的体感也还行。如果你用的是按量计费的商业模型，这个成本控制是必须考虑的，不然功能做出来也没人用得起。
7. 内容扩展方向：从简历 Agent 到通用文档分析 Agent 的迁移思路
简历工具做完之后，我发现这套"解析-对齐-差距分析-评分-建议"的图结构，可以非常自然地迁移到其他文档处理场景。比如：
- 招聘 JD 与候选人履历匹配：把
parsedResume换成 JD 和候选人简历双端解析，gapAnalysis变成双向匹配报告； - 合同审查：解析节点提取合同关键条款，
align_role节点换成"业务需求规则库"，差距分析变成条款风险清单； - 学习计划生成：把用户输入换成"当前技术栈和目标岗位"，差距分析变成知识点补全计划。
核心的图结构不需要大改，主要调整的是三个节点：解析节点的 JSON Schema、对齐节点的参照物、建议节点的输出模板。这种"换数据不动架构"的迁移方式，让我觉得当初花时间优化状态图和事件协议是值得的。
如果你准备基于这套方案做自己的 Agent 工具，我个人建议先不要急着堆功能，而是把一条主流程做到 90 分的稳定度，再把中断恢复、流式展示、低成本运行这些"体感细节"补上。Agent 落地最难的不是模型能力，而是工程边界——你要非常清楚地知道每一步该做什么、什么情况下停下来问用户、什么情况下报错重试。把这个边界控制住了，后面的一切都顺。
最后再分享一个实际操作中的小技巧：在图的入口处一定要做输入长度校验，并且在每个节点里加一个简单的"输入状态是否合法"的判断函数。这个函数不需要太复杂，只要能在数据明显异常时抛出一个带具体原因的异常，就能避免很多因为用户粘贴格式千奇百怪而导致的流水线崩溃。简历工具这种面向真实用户的 Agent，用户不会按照你预设的格式输入，把容错做好，比把模型调对还重要。
