AI Agent 简历优化实战：Next.js + LangGraph.js 全栈落地

1. 为什么简历工具值得用 AI Agent 重做一遍

简历这个赛道看起来已经很拥挤了，各种在线简历生成器、模板站、排版工具一抓一大把。但真正动手做过简历产品的人都知道，这个领域有一个长期没被解决好的核心矛盾：用户不知道自己该写什么，更不知道自己写得对不对。传统简历工具解决的是"排版"问题，给你一个漂亮的模板，把内容填进去，导出 PDF，完事。可用户真正的痛点根本不在排版上，而在于"我这段经历该怎么描述才有说服力""我的技能栏是不是写得太虚了""这个岗位到底看重什么"。

这就是 AI Agent 切入的价值点。普通的 AI 简历工具，本质上是一次性的 prompt 调用：把简历内容丢给大模型，返回一段润色后的文字。这种做法的问题很明显——它没有记忆，没有多轮决策，没有工具调用能力，更没有对整份简历的全局把控。而 AI Agent 不一样，它可以拆解任务、分步骤执行、调用外部工具、根据中间结果调整策略。放到简历场景里，一个合格的 Agent 应该能做到：读取用户原始经历、分析目标岗位 JD、逐条优化描述、检查关键词覆盖度、给出量化建议、最后统一风格输出。

那技术选型为什么是 Next.js + LangGraph.js 这套组合？我踩过一些坑之后才想明白这件事。Next.js 负责的是产品层——页面渲染、API 路由、流式响应、部署一体化，这些它都很成熟。LangGraph.js 负责的是 Agent 编排层——状态管理、节点流转、条件分支、循环重试，这些恰恰是普通 LLM 调用链搞不定的。两者结合，前端到 Agent 逻辑全在 TypeScript 一个语言栈里，不用在 Python 后端和 JS 前端之间来回切，对独立开发者和小团队来说，维护成本能压到很低。

这篇文章适合谁看？如果你已经会用 Next.js 写页面，也对大模型 API 调用有基本概念，但一直不知道怎么把"AI 能力"真正做成一个能上线、能跑通完整业务流程的产品，那这篇就是写给你的。我会把整个简历 Agent 的落地过程拆开讲，包括状态图怎么设计、工具怎么接、流式输出怎么处理、以及那些文档里不会写的坑。

2. 把简历优化拆成 Agent 能执行的状态图

2.1 为什么不能用一个 prompt 搞定

先说一个我早期的错误做法。最开始我想得很简单：把用户的简历文本和目标岗位描述拼成一个超长 prompt，让模型一次性输出优化后的简历。跑了几次就发现三个致命问题。第一，输出不稳定，有时候只改了工作经历，有时候把教育背景也动了，用户根本不知道哪里变了。第二，没法处理长简历，一旦内容超过一定长度，模型会开始偷懒，后面的段落直接照抄。第三，没有中间校验，模型说"已优化"但实际可能漏掉了关键岗位关键词，用户拿到手还是过不了筛选。

这三个问题的本质是：简历优化不是一个单步任务，而是一个有依赖关系的多步流程。你得先理解岗位要什么，再对照简历找差距，然后逐块改写，最后做一致性检查。这种有顺序、有分支、有回退的流程，正是 LangGraph 的 StateGraph 擅长的事情。

2.2 状态图节点划分

我把整个简历 Agent 拆成了六个核心节点，每个节点职责单一，通过共享的 State 传递数据。这样设计的好处是每个节点可以单独测试、单独替换，出问题的时候能快速定位是哪一步挂了。

这里有个关键设计决策：rewriteSection 是循环执行的。因为一份简历通常有多个工作经历段落，如果放在一个节点里一次性处理，又会回到"模型偷懒"的老问题。所以我用 LangGraph 的条件边，让 rewriteSection 处理完一段后判断是否还有未处理段落，有就回到自己，没有就流向 checkCoverage。这种自循环结构用普通函数调用写起来很别扭，用状态图就很自然。

2.3 State 的字段设计

State 是整个 Agent 的血液，设计得好不好直接决定后面写起来顺不顺。我用的是 LangGraph 的 Annotation 方式定义 State，核心字段包括：原始简历文本、结构化简历对象、岗位关键词数组、当前处理段落索引、已改写段落集合、覆盖率报告、最终输出。这里要特别注意一点，不要把大段文本塞进 State 的多个字段里反复传递，能存引用就存引用，能存索引就存索引，否则内存占用和序列化开销会很难看。

还有一个容易忽略的点：State 里要留一个errors数组，记录每个节点执行过程中的异常。Agent 跑长流程的时候，某个节点失败是常态，如果没有错误收集机制，用户看到的就是一个莫名其妙的失败，而你排查起来也毫无头绪。

2.4 条件分支与重试逻辑

LangGraph 最强大的地方在于条件边。我在 gapAnalysis 之后加了一个判断：如果差距过大（比如关键词覆盖率低于 40%），就不直接进入改写，而是先返回一个"建议补充经历"的提示，让用户确认是否继续。这个分支看起来简单，但它避免了 Agent 在信息严重不足的情况下硬编内容，那种编出来的简历反而会害了用户。

重试逻辑我放在 rewriteSection 上。如果某段改写后长度异常（比如比原文短了一半以上），说明模型可能出问题了，这时候自动重试一次，重试还不行就标记该段为"需人工处理"。这种防御性设计在实际使用中救了我很多次，尤其是用户简历格式特别乱的时候。

3. Next.js 侧怎么承接 Agent 的流式输出

3.1 路由设计：一个 API 路由搞定还是拆多个

我一开始把整个 Agent 调用放在一个/api/optimize路由里，结果发现两个问题。一是超时，Agent 跑完整流程可能要几十秒，Vercel 的默认函数超时扛不住。二是没法给用户中间反馈，用户点了按钮之后就是干等，体验很差。

后来我改成两层结构：/api/optimize/start负责启动 Agent 并返回一个任务 ID，/api/optimize/stream负责用 SSE 推送执行进度。Agent 的执行放在一个独立的后台任务里，通过事件总线把每个节点的完成状态推给 stream 路由。这样即使用户刷新页面，重新连上 stream 也能继续看到进度。

这里有个 Next.js 的细节要注意：App Router 下的 Route Handler 默认是流式友好的，但你要手动设置Content-Type: text/event-stream和Cache-Control: no-cache，并且用ReadableStream包装返回。我见过不少人用NextResponse.json返回流式数据，那是行不通的。

3.2 前端状态管理：别用全局 store 硬扛

简历 Agent 的前端状态其实挺复杂的：当前执行到哪个节点、每个节点的输出是什么、用户有没有中途修改、最终结果是什么。我试过用 Zustand 做一个大 store，结果发现状态更新和流式事件对不上，经常出现 UI 显示滞后。

后来我换了个思路：把 Agent 执行状态和 UI 展示状态分开。Agent 状态用一个 reducer 管理，只处理来自 SSE 的事件；UI 状态用组件本地 state，只关心当前展示什么。两者通过一个中间层同步。这样职责清晰，调试起来也容易。具体来说，SSE 每收到一个node_complete事件，就往 reducer 里 dispatch 一次，reducer 更新对应节点的输出；UI 组件订阅 reducer 里自己关心的那部分数据。

3.3 流式渲染的体验细节

流式输出不只是技术问题，更是体验问题。我做了几个小优化，用户反馈明显变好。第一，每个节点开始时先显示一个骨架屏，让用户知道"正在分析岗位要求"，而不是一片空白。第二，节点完成后不要一次性把全部内容刷出来，而是用打字机效果逐字显示，虽然技术上多此一举，但用户感知上会觉得"AI 在认真工作"。第三，加一个进度条，把六个节点映射成六个阶段，用户能直观看到还剩多少。

提示：打字机效果不要用 setInterval 硬写，用 requestAnimationFrame 配合时间戳控制速度，否则在低端设备上会卡顿。

3.4 错误边界与降级

Agent 调用大模型 API 失败是家常便饭，网络抖动、限流、超时都可能发生。我在前端加了三层降级：第一层是自动重试，针对网络类错误重试两次；第二层是部分降级，如果某个节点失败但其他节点成功，就把成功的部分展示出来，失败的节点标记为"待重试"；第三层是完整降级，如果 Agent 完全跑不起来，就退回到一个简单的单次 prompt 调用，至少让用户能拿到一个基础结果。

这套降级逻辑写起来不复杂，但它是产品能不能上线的分水岭。我见过太多 AI 产品 demo 很惊艳，一上线就因为各种边界情况被用户骂。

4. LangGraph.js 里那些文档没讲清楚的坑

4.1 节点函数的返回值陷阱

LangGraph.js 的节点函数返回值会直接合并进 State，这个机制看起来简单，但有个坑：如果你返回的字段和 State 里已有的字段同名，是覆盖还是合并，取决于字段的 reducer 定义。默认是覆盖，但如果你用了Annotation并指定了 reducer，行为就不一样了。

我踩过一次：State 里有个rewrittenSections数组，我想让每次改写都追加进去，结果因为没定义 reducer，每次都被覆盖，最后只剩最后一段。正确做法是给这个字段定义一个 concat reducer：

import { Annotation } from "@langchain/langgraph"; const ResumeState = Annotation.Root({ rewrittenSections: Annotation<string[]>({ reducer: (current, update) => current.concat(update), default: () => [], }), currentIndex: Annotation<number>({ reducer: (_, update) => update, default: () => 0, }), });

这个细节文档里有提，但很容易一扫而过，等到发现数据丢了才回头找原因。

4.2 条件边的返回值必须是字符串

LangGraph.js 的条件边函数必须返回一个字符串，这个字符串对应目标节点的名称。我一开始想返回一个对象带上额外信息，结果直接报错。后来才明白，条件边只负责路由决策，要传数据得通过 State。

还有个细节：条件边返回的字符串如果拼错了节点名，不会报错，而是静默地结束流程。这个坑我找了半天，最后是靠加日志才定位到。所以建议在开发阶段给每个节点入口都打一条日志，确认流转路径符合预期。

4.3 循环终止条件要显式判断

前面说的 rewriteSection 自循环，如果不加终止条件就是死循环。我的做法是在 State 里维护一个processedIndices集合，每次进入节点先检查当前索引是否已处理，处理完把索引加进去，然后条件边判断processedIndices.size < totalSections决定是否继续循环。

这里有个性能考量：不要用数组的 includes 做存在性判断，段落多了之后 O(n) 查询会拖慢整体速度，用 Set 或者对象做映射。简历一般也就十几段，影响不大，但养成习惯总是好的。

4.4 中断与恢复

LangGraph 支持在节点之间中断，这对简历场景特别有用。比如 gapAnalysis 之后，我想让用户确认一下差距报告再继续，就可以用interruptBefore配置。用户确认后，用相同的 thread_id 恢复执行。

这个功能实现起来不难，但要注意：中断期间 State 是持久化的，如果你用的是内存存储，服务重启就丢了。生产环境一定要接一个持久化层，我用的是 Postgres 存 checkpoint，配合 LangGraph 的 checkpointer 接口，几十行代码就能搞定。

5. 简历场景专属的 Prompt 工程与工具设计

5.1 岗位关键词提取不能只靠模型

analyzeJD 这个节点，我一开始完全交给模型做，让它从 JD 里提取关键词。结果发现模型提取的关键词太泛，"沟通能力""团队协作"这种词每个岗位都有，没有区分度。后来我改成混合方案：先用规则提取 JD 里明确列出的技能词（比如"熟悉 React""掌握 Python"），再用模型补充隐含要求，最后用一个预置的岗位词典做归一化。

这个岗位词典是我自己维护的，把同义词合并，比如"React.js""ReactJS""React"统一成"React"。别小看这一步，它直接决定了后面覆盖率计算的准确性。词典不用很大，覆盖主流技术栈和常见职能词就够了，几百个条目。

5.2 改写指令要带约束

rewriteSection 的 prompt 是整个 Agent 里最关键的。我试过很多版本，最后稳定下来的结构是这样的：先给角色设定（资深 HR + 行业专家），再给改写原则（STAR 法则、量化优先、动词开头），然后给具体约束（保持原意、不编造数据、长度控制在原文 1.2 倍以内），最后才是待改写内容和差距报告。

这里有个经验：约束一定要具体到可验证。"保持原意"太虚，"不得新增原文中没有的公司名、项目名、数字"就具体多了。模型对具体约束的遵守度明显更高。

5.3 覆盖率校验的量化方法

checkCoverage 节点我做了一个简单的加权计算：每个关键词有权重（来自 JD 中的出现频率和位置），简历中命中该关键词就得对应分数，最后算总分除以总权重得到覆盖率。覆盖率低于 60% 就提示用户补充，60% 到 80% 之间给优化建议，80% 以上算通过。

这个阈值不是拍脑袋定的，我拿了几十份真实简历和对应 JD 做测试，发现 60% 以下基本过不了初筛，80% 以上通过率明显提升。当然不同行业标准不一样，技术岗对关键词更敏感，创意岗相对宽松，这个可以做成可配置的。

5.4 工具调用的边界

Agent 可以调用外部工具，但简历场景里工具不是越多越好。我只接了两个工具：一个是岗位词典查询，一个是行业薪资数据查询（用于给量化建议提供参考）。其他像网页搜索、文件解析这些，要么没必要，要么有隐私风险。

注意：简历包含大量个人敏感信息，任何外部工具调用都要评估数据泄露风险。我的原则是能不传出去就不传，必须传的做脱敏处理。

6. 上线前必须处理的性能与成本问题

6.1 Token 消耗的实测数据

一份中等长度的简历（约 800 字）加上一份 JD（约 500 字），跑完整 Agent 流程大概消耗 8000 到 12000 token。如果按主流模型的价格算，单次成本在几分钱到一毛钱之间。看起来不多，但如果日活上千，一个月就是几百块。

优化空间主要在两个地方。一是 parseResume 和 analyzeJD 可以并行执行，省一轮往返。二是 rewriteSection 循环时，差距报告不用每次都完整传入，只传当前段落相关的部分就行。我做了这两个优化之后，token 消耗降了大概 30%。

6.2 缓存策略

简历优化有个特点：同一个用户可能会针对不同岗位反复优化同一份简历。这时候 parseResume 的结果是可以复用的。我用简历内容的哈希值做 key，把结构化结果缓存起来，有效期设一天。这样用户换岗位重新优化时，能省掉解析那一步。

缓存层我用的是 Redis，但如果你部署在 Serverless 环境，用 Next.js 的 unstable_cache 也能凑合，只是控制粒度没那么细。

6.3 并发与限流

Agent 执行时间长，并发一高就容易把后端打爆。我在 API 路由层加了一个简单的令牌桶限流，每个用户每分钟最多发起 3 次优化请求。同时 Agent 执行用了队列，超过并发上限的请求排队等待，而不是直接拒绝。这样用户体验上只是慢一点，不会直接报错。

队列我用的是内存队列，因为单实例部署够用了。如果要多实例，得换成 Redis 队列或者云厂商的消息队列。

6.4 监控与可观测性

Agent 这种多步骤流程，没有监控就是睁眼瞎。我埋了几个关键指标：每个节点的平均耗时、失败率、token 消耗、覆盖率分布。这些数据用简单的日志加定时聚合就能拿到，不用上很重的 APM。

特别要监控的是节点耗时异常。如果某个节点突然变慢，很可能是模型 API 出问题了，或者是某类输入触发了模型的"思考陷阱"。我遇到过一次 rewriteSection 对某份简历卡了 40 秒，最后发现是那段经历里有个特殊符号导致模型反复解析。加了输入清洗之后就正常了。

7. 我踩过的三个真实坑与修复过程

7.1 中文简历的编码问题

第一个坑很隐蔽。用户上传的简历如果是从某些老系统导出的，可能带有 BOM 头或者特殊空白字符。这些字符在页面上看不出来，但传给模型之后会导致解析异常，模型会把整段内容当成乱码处理。

排查过程是这样的：我发现某些简历的 parseResume 结果为空，但原文看起来完全正常。把原文 hex dump 出来一看，开头有几个不可见字符。修复方法是在 parseResume 入口做一次清洗，去掉 BOM、零宽字符、连续空白，统一换行符。这几行代码加上之后，解析失败率从 5% 降到了接近 0。

7.2 流式输出的断线重连

第二个坑是 SSE 断线。用户网络不稳定的时候，SSE 连接会断，前端如果直接报错，用户就得重新跑一遍 Agent，体验极差。

我的修复方案是给每个 Agent 任务分配一个持久化的 task_id，前端断线后带着 task_id 重新连接，后端从 checkpoint 里恢复状态继续推送。这里的关键是事件要有序号，前端记录最后收到的事件序号，重连时告诉后端从哪个序号开始推，避免重复或遗漏。

7.3 模型输出的格式漂移

第三个坑最烦人。rewriteSection 要求输出 JSON 格式的改写结果，但模型有时候会输出带 markdown 代码块的 JSON，有时候会加一段解释文字再给 JSON。这种格式漂移导致解析失败。

我试过用 prompt 强调"只输出 JSON"，效果有限。最后用了组合方案：prompt 里给明确的 JSON schema 示例，解析时先用正则提取 JSON 部分，再用 zod 做校验，校验失败就触发重试。这套组合拳下来，解析成功率稳定在 99% 以上。

8. 从 Demo 到产品的最后一段路

8.1 用户引导比算法更重要

技术做完之后我发现，用户根本不知道怎么用。他们不知道要填目标岗位，不知道简历要写多详细，不知道优化结果怎么看。后来我加了一个三步引导：第一步让用户粘贴简历，第二步让用户粘贴 JD，第三步展示优化前后的对比。每一步都有示例和说明。

这个引导做完之后，完成率提升了差不多一倍。技术再好，用户不会用也是白搭。

8.2 结果的可解释性

用户拿到优化后的简历，最常问的问题是"为什么这么改"。如果只是给一个结果，用户会怀疑。所以我在每个改写段落旁边加了一个"修改说明"，用一两句话解释改了什么、为什么这么改。这个说明也是模型生成的，但 prompt 里要求它用大白话，不要用术语。

可解释性带来的信任感，是简历这种敏感场景里特别重要的东西。用户愿意把简历交给你处理，你得让他知道你没乱来。

8.3 数据隐私的底线

简历是高度敏感的个人数据，这一点怎么强调都不过分。我做了几件事：所有简历数据加密存储，用户可以选择用完即删，Agent 执行过程中的中间数据不落盘（除了必要的 checkpoint），日志里不记录简历原文。

还有一点，不要拿用户简历去训练模型，哪怕匿名化也不行。这个承诺要写在隐私政策里，并且真的做到。信任一旦失去，产品就完了。

8.4 后续可以扩展的方向

这套 Agent 架构其实可以复用到很多场景。比如面试准备，把简历和 JD 换成简历和目标公司，Agent 可以生成可能的面试问题。再比如职业规划，输入简历和期望方向，Agent 可以分析差距并给出学习路径。核心的状态图逻辑不用大改，换几个节点和 prompt 就行。

我在实际使用中最大的体会是，AI Agent 产品的竞争力不在模型本身，而在流程设计和工程细节。模型能力大家都能用，但怎么把模型能力组织成一个稳定、可解释、体验好的产品，这才是真正拉开差距的地方。LangGraph 给了一个很好的编排框架，Next.js 给了一个很好的产品框架，剩下的就是把这些细节一个个抠到位。