← 返回首页SmartResume

About This Project

智简 技术介绍

项目定位

SmartResume 是一个面向求职与职业决策场景的 Web 应用，当前包含两个核心模块：

  • 简历诊断与优化
  • CareerCompass 生涯路线规划

项目目标不是只做“把简历排版得更好看”，而是把“信息提取、问题诊断、内容优化、结果导出、职业决策辅助、Agent 交互”串成一个完整流程。

核心能力

1. 简历诊断与优化

  • 支持粘贴简历文本，或上传 PDF / Word 简历进行解析
  • 对简历进行多维度诊断，包括内容完整性、关键词匹配、ATS 可读性、表达力度等
  • 可结合目标 JD 做岗位匹配分析，识别缺失关键词与内容短板
  • 基于原始简历内容生成优化版简历，并尽量保留原始信息结构与事实
  • 支持 Cover Letter、面试问题预测、历史记录与 PDF 导出
  • 内置简历 Agent，可在编辑器中提出修改建议，并在用户确认后写入简历数据

2. CareerCompass 生涯路线规划

  • 通过结构化表单采集用户的经历证据、当前投入、理想生活、现实约束与背景信息
  • 对用户经历做证据评分，而不是只依赖人格测试或专业标签
  • 输出路线预测、关键张力、环境适配、岗位路径建议与简历策略
  • 在信息不足时进入探索模式，避免强行给出低可信度结论
  • 内置生涯 Agent，可评估填写质量、调用知识库、运行路线预测，并把结果同步给简历 Agent 使用

技术架构

前端

  • Next.js 16 App Router
  • React 19
  • TypeScript
  • Tailwind CSS 4
  • Zustand
  • CopilotKit React Core

前端采用 App Router 组织页面与接口路由。首页主流程使用客户端状态驱动的单页体验，职业规划模块通过独立路由承载更完整的多步骤流程。两个 Agent 都基于 CopilotKit 的 headless chat、readable context 与 action 工具机制实现，但分别绑定在不同业务页面。

服务端能力

  • Next Route Handlers
  • CopilotKit Runtime
  • OpenAI SDK 兼容调用
  • AI SDK OpenAI provider
  • Zod 参数校验
  • Puppeteer / Puppeteer-Core PDF 导出

服务端主要承担以下职责：

  • 接收简历诊断、优化、求职信生成、面试问题预测等请求
  • 为 CopilotKit 提供统一运行时入口 /api/copilotkit
  • 拼装提示词并调用大模型
  • 对模型返回结果做结构化校验、归一化与二次处理
  • 为 Agent 工具提供规则计算、知识库检索与业务 API 封装
  • 将最终简历页面导出为可下载 PDF

两个 Agent 的技术实现

1. 公共运行时：CopilotKit Runtime

两个 Agent 共用根布局里的 CopilotKitProvider：

  • 前端入口：src/components/CopilotKitProvider.tsx
  • Runtime 地址：/api/copilotkit
  • 服务端入口：src/app/api/copilotkit/route.ts

服务端使用 CopilotRuntime 和 OpenAIAdapter 接入模型。模型供应商由环境变量 LLM_PROVIDER 决定：

  • LLM_PROVIDER=1：默认走 DeepSeek 兼容 OpenAI 接口
  • LLM_PROVIDER=2：走智谱 GLM 兼容 OpenAI 接口

OpenAIAdapter 默认可能走 Responses API，而 DeepSeek 不支持该接口，所以项目覆盖了 serviceAdapter.getLanguageModel，强制使用 Chat Completions 形式的 provider.chat(model)。这是 CopilotKit 能兼容 DeepSeek / GLM 的关键处理。

2. 简历 Agent：小简智能助手

简历 Agent 位于：

  • src/components/chat/AgentChat.tsx
  • 挂载位置：src/components/editor/ResumeEditor.tsx

它的定位是“简历编辑与求职准备 Agent”。它不是只聊天，而是能读取当前简历、调用工具、提出修改 diff，并在用户确认后把改动写回编辑器状态。

上下文注入

简历 Agent 通过 useCopilotReadable 注入以下上下文：

  • Agent 身份：小简智能助手
  • 当前结构化简历数据 resumeData
  • 当前目标 JD jdText
  • 最近一次诊断结果 diagnosis
  • CareerCompass 生涯规划结果 smartresume-career-strategy

其中 resumeData 是结构化对象，不是纯文本。Agent 能直接看到姓名、联系方式、个人简介、工作经历、项目经历、教育背景、技能和奖项等字段，因此可以基于当前编辑器状态给出更精确的建议。

工具注册

简历 Agent 使用 useCopilotAction 注册多类工具：

  • analyze_resume：调用 /api/analyze 做简历诊断
  • rewrite_section：调用 /api/generate-resume 对指定区块生成改写建议
  • update_field：提出字段更新建议，如姓名、标题、简介、联系方式
  • remove_item：提出删除某条经历、项目、技能或奖项的建议
  • match_jd：分析简历和 JD 的匹配度
  • generate_cover_letter：调用求职信生成接口
  • predict_interview_questions：调用面试问题预测接口
  • change_template：建议切换简历模板
  • export_pdf：建议导出 PDF
  • add_missing_keywords：根据 JD 补充缺失关键词
  • career_analyze：结合简历判断职业方向
  • prepare_interview：基于简历与 JD 做面试准备
  • optimize_for_jd：针对目标 JD 生成定向优化建议
  • apply_career_strategy：把 CareerCompass 的简历策略应用到当前简历

修改确认机制

简历 Agent 不会直接改简历。它会先通过 proposeChange 生成待确认的修改卡片，核心修改类型包括：

  • rewrite_section
  • update_field
  • remove_item
  • change_template
  • export_pdf

用户点击确认后，AgentChat 才会通过 onToolAction 把动作传给 ResumeEditor。ResumeEditor 内部的 handleAgentToolAction 再按 action 类型更新对应字段或数组条目。

这种设计把“AI 建议”和“真实写入”分开，避免模型一次工具调用就直接覆盖用户简历。

3. 生涯 Agent：小简生涯助手

生涯 Agent 位于：

  • src/components/career/CareerAgentChat.tsx
  • 挂载位置：src/app/career/page.tsx

它的定位是“CareerCompass 表单填写与路线预测 Agent”。它负责帮助用户判断信息是否足够、经历证据是否有说服力、当前投入和理想生活之间是否有张力，并可直接触发完整路线预测。

上下文注入

生涯 Agent 通过 useCopilotReadable 注入以下上下文：

  • Agent 身份：小简生涯助手
  • 当前 CareerCompass 表单数据 formData
  • 当前填写步骤 currentStep
  • 表单完整度摘要
  • 最近一次路线预测结果 forecastResult

表单完整度不是只看是否提交，而是按模块计算：

  • 经历与证据
  • 当前投入
  • 理想生活
  • 现实约束
  • 专业背景

Agent 因此可以判断用户是缺少核心经历证据，还是只缺少补充背景信息。

工具注册

生涯 Agent 使用 useCopilotAction 注册以下工具：

  • career_score_evidence：对经历证据做五维度规则评分
  • career_detect_tensions：检测当前投入与理想生活之间的结构性张力
  • career_search_knowledge：检索岗位画像、行业趋势、方法论和用户案例知识库
  • career_forecast：调用 /api/career/forecast 运行完整生涯路线预测
  • career_generate_life_resume：调用 /api/career/life-resume 生成人生简历叙事
  • career_check_completeness：检查当前表单完整度并给出补填建议

其中前三个工具通过聚合接口 /api/career/agent-tools 承载：

  • knowledge_search：本地知识库文本检索
  • score_evidence：规则化经历证据评分
  • detect_tensions：规则化张力检测

完整路线预测和人生简历生成则分别走独立业务接口：

  • /api/career/forecast
  • /api/career/life-resume

路线预测回写

当生涯 Agent 调用 career_forecast 成功后，会触发 onForecastResult(res)。该回调在 career/page.tsx 中把预测结果写入 CareerCompass store，并进一步触发生命叙事生成。

同时，页面会把关键策略保存到 localStorage：

  • key：smartresume-career-strategy
  • 内容：推荐路线、全部路线、简历策略、岗位路径、关键张力、是否进入探索模式等

这一步是两个 Agent 协作的核心桥梁。

4. 双 Agent 协作方式

两个 Agent 没有直接互相调用，而是通过“结构化结果共享”协作：

  1. 用户在 CareerCompass 中填写表单
  2. 生涯 Agent 或用户触发 career_forecast
  3. Career 页面把预测结果保存为 smartresume-career-strategy
  4. 用户回到简历编辑器
  5. 简历 Agent 读取 smartresume-career-strategy
  6. 用户触发 apply_career_strategy
  7. 简历 Agent 根据生涯路线、岗位路径和简历策略生成待确认的简历改动

这种设计的优点是：

  • 两个 Agent 职责清晰
  • 生涯分析结果不会强行覆盖简历
  • 简历 Agent 能利用生涯 Agent 的结论做更有方向的优化
  • 即使用户刷新页面，关键策略仍可通过本地存储恢复

数据流设计

简历诊断链路

  1. 用户输入简历文本，或上传 PDF / Word 文件
  2. 前端完成文件解析与基础清洗
  3. /api/analyze 调用诊断逻辑与模型分析
  4. 服务端合并规则评分与模型评分，返回统一诊断结果
  5. 前端展示问题分析、优化建议与岗位匹配结果

简历优化链路

  1. 用户基于诊断结果发起优化
  2. /api/generate-resume 结合原始简历、建议与模板风格生成结构化简历数据
  3. 前端进入预览或编辑态
  4. 简历 Agent 可在编辑器中继续提出 diff 式修改建议
  5. /api/export-pdf 将最终 HTML 导出为 PDF

生涯路线规划链路

  1. 用户逐步填写 CareerCompass 表单
  2. 本地状态与草稿会被持久化保存
  3. 生涯 Agent 可检查完整度、评分经历、检索知识库或触发路线预测
  4. /api/career/forecast 输出路线预测与决策报告
  5. /api/career/life-resume 异步补充“人生简历”叙事结果
  6. 关键结果写入 smartresume-career-strategy，供简历 Agent 后续读取

关键实现点

1. 输入兼容

  • pdfjs-dist 用于前端 PDF 文本提取
  • mammoth 用于 Word 文档原始文本提取
  • 图片上传会在前端压缩后再进入简历模板流程

这样做的好处是：用户不需要先把简历手动转成纯文本，输入门槛更低。

2. 规则与模型混合诊断

简历诊断并不是完全依赖大模型自由输出，而是采用“规则诊断 + 模型补充”的混合方式：

  • 规则层负责基础结构判断与可控评分
  • 模型层负责补充语义分析、改写建议与 JD 匹配说明
  • 最终结果会做归一化、去重、字段修正与事实约束

这种设计比纯提示词生成更稳定，也更容易控制误判和幻觉。

3. 模板化简历生成

项目内置多套简历模板，不同模板对应不同视觉风格与信息布局。优化后的简历并不是一段纯文本，而是结构化数据驱动的页面渲染结果，因此：

  • 更容易切换模板
  • 更容易继续编辑
  • 更适合导出高质量 PDF

4. 本地持久化

部分用户输入和操作历史保存在本地，包括：

  • 草稿简历内容
  • JD 输入
  • 上传照片
  • 历史诊断记录
  • 深色模式偏好
  • CareerCompass 草稿
  • CareerCompass 预测后的简历策略

这样即使刷新页面，也能尽量保持上下文连续性。

目录说明

  • src/app/：页面与 API 路由
  • src/components/：界面组件
  • src/components/chat/：简历 Agent 与修改确认卡片
  • src/components/career/：CareerCompass 页面组件与生涯 Agent
  • src/hooks/：核心状态编排逻辑
  • src/lib/：规则、工具函数、存储与模型调用封装
  • src/templates/：简历模板构建逻辑
  • src/data/ 与 src/knowledge/：静态数据与知识库
  • docs/：项目说明与补充文档

适用场景

  • 求职者快速检查简历质量
  • 针对特定岗位做定向优化
  • 生成可投递的 PDF 简历
  • 辅助梳理职业方向与阶段性路线选择
  • 在 Agent 的辅助下边分析边修改简历

当前设计取舍

  • 首页主流程偏客户端状态驱动，交互更顺滑，但页面逻辑集中度较高
  • 文档解析与简历优化链路强调“保留原始事实”，因此生成策略会偏保守
  • 生涯规划模块强调可解释性，因此引入了较多结构化字段与规则层
  • 两个 Agent 通过本地结构化结果协作，部署简单，但还不是服务端多 Agent 编排
  • 简历 Agent 采用“建议先确认再写入”的机制，操作更稳，但交互步骤会比直接修改多

后续可扩展方向

  • 增加更细粒度的模板配置能力
  • 引入用户账户体系与云端历史记录
  • 将 smartresume-career-strategy 从本地存储升级为用户级服务端记忆
  • 为两个 Agent 增加更严格的工具参数校验与审计日志
  • 为职业规划模块增加更多数据来源与验证机制
  • 补充更完整的自动化测试与监控链路