不平 - 智能求职助手

人生之路总是坎坷，这也造就了我们不平凡的人生.

AI 求职助手是一个基于大语言模型 (LLM) 的智能求职辅助工具。覆盖从简历优化、岗位匹配、面试准备到职业发展的完整求职周期。

English version: README_EN.md

✨ 核心功能

🎯 已实现功能

• 📄 简历生成引擎

  • 普通简历生成（基于 YAML）
  • JD 定制简历生成（针对职位描述优化）
  • 单次 LLM 调用生成完整简历（~30 秒）
  • 支持 5 种专业样式模板
  • 详实量化内容，ATS 友好

• 📋 实时简历预览

  • 基于本地 YAML 的秒级预览（不调 LLM）
  • 切换样式/语言自动刷新
  • iframe 完整样式渲染

• ✏️ WYSIWYG 编辑器（iframe + designMode）

  • 所见即所得：编辑时与预览样式 100% 一致（颜色/字体/布局全部保留）
  • 18 个工具栏按钮：撤销/重做、3 级标题、粗体/斜体/下划线/删除线、有序/无序列表、引用、分隔线、链接、清除格式
  • 支持版式微调：可在编辑页调整行距和模块间距，并保存到最终 HTML/PDF
  • 使用原生 <iframe> + designMode="on"，样式隔离 0 依赖
  • 每 1.5s 自动保存到 localStorage（保留 5 个版本）
  • 支持 Ctrl+Z / Ctrl+Y / Ctrl+B / Ctrl+I / Ctrl+U 标准快捷键
  • 可编辑内容后导出 HTML

• 👀 可预览 + 可编辑

  • 实时预览：本地 YAML 渲染，秒级切换样式/语言（无需 LLM）
  • 历史预览：下拉选择任意历史简历加载到预览框
  • 一键切换：预览模式（只读 iframe）↔ 编辑模式（iframe WYSIWYG）
  • 生成完成自动加载最新内容到预览

• 📤 简历文档上传解析

  • 支持 PDF、Word (DOCX)、HTML、Markdown、YAML、LaTeX 等格式
  • 拖拽上传或点击选择，LLM 自动结构化提取，无需手动编辑
  • YAML/JSON 直接解析（零成本），其他格式走 LLM 智能识别
  • 解析结果自动填入 YAML 编辑器，用户审核后保存

• 📂 历史简历预览

  • 下拉式历史选择器
  • 一键加载任意历史简历到预览
  • 生成完成后自动加载最新内容到预览

• 📋 面试准备模块

  • 基于简历和 JD 自动生成面试准备报告
  • 包含：技术问题、行为面试 (STAR)、简历深挖、准备清单
  • 支持中英文双语
  • Markdown 报告导出

• 🎭 模拟面试模块

  • AI 扮演面试官，多轮对话模拟
  • 5 种面试官风格：友善型 / 专业型 / 压力型 / 学术型 / 闲聊型
  • 自动轮次控制：开场 → 项目 → 技术 → 行为 → 反问 → 结束
  • 结束生成多维度评估报告

• 🎨 三列布局

  • 左侧：API 配置 + 样式选择
  • 中间：简历预览（居中突出）
  • 右侧：职位描述

• 📊 生成进度条

  • 5 阶段可视化进度（解析 → LLM → CSS → Chrome → 保存）
  • 30-60s 生成期间实时反馈
  • 比单纯 spinner 体验更好

• 🔧 可隐藏侧边栏

  • 一键折叠/展开
  • 状态持久化到 localStorage
  • 移动端友好

• ⚙️ 配置与设置

  • API Key / Base URL 配置面板
  • 模型类型选择（anthropic / openai）
  • 简历语言选择（中文/英文）
  • 配置会写入 data_folder/secrets.yaml

• 📚 历史记录

  • 生成的简历历史列表
  • 一键下载 PDF
  • 预览历史简历

🚧 规划中功能

• 岗位匹配分析（从网络爬虫池）
• 申请跟踪管理
• 技能缺口分析
• 学习路径推荐

🛠️ 技术架构

📁 目录结构

Buping_Job_Seeker_Assistant/
├── pyproject.toml               # uv 项目配置 (替代 requirements.txt)
├── start-dev.bat                # Windows 一键启动
├── start-dev.sh                 # Linux/Mac 一键启动
├── main.py                      # CLI 入口 (保留)
├── config.py                    # 全局配置 (API Key 等)
│
├── backend/                     # FastAPI 后端
│   ├── app.py                   # FastAPI 入口
│   ├── dev_launcher.py          # 开发启动器 (同时启前后端)
│   └── api/
│       ├── router.py            # API 路由汇总
│       └── endpoints/
│           ├── resume.py        # 简历生成 API
│           ├── interview.py     # 面试准备 + 模拟面试 API
│           ├── settings.py      # 配置管理 API
│           └── history.py       # 历史记录 API
│
├── data_folder/                 # 用户数据 (实际数据，已脱敏)
│   ├── plain_text_resume.yaml   # 简历内容 (英文)
│   ├── plain_text_resume_zh.yaml # 简历内容 (中文)
│   ├── work_preferences.yaml    # 工作偏好
│   ├── work_preferences_zh.yaml
│   └── secrets.yaml             # API 密钥 (模板)
│
├── data_folder_example/         # 用户数据示例
│   ├── plain_text_resume.yaml   # 简历示例 (英文)
│   ├── resume_liam_murphy.txt
│   ├── work_preferences.yaml
│   └── secrets.yaml
│
├── frontend/                    # React + Vite 前端
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.ts
│   ├── index.html
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── api/client.ts        # API 调用封装
│       ├── i18n/index.ts        # 中英文国际化
│       ├── components/          # 通用组件
│       └── pages/               # 页面 (5 个)
│
├── src/                         # 业务逻辑 (保持不动)
├── data_folder/                 # 用户数据
└── assets/                      # 静态资源

🚀 快速开始

环境要求

一键启动

# 克隆仓库
git clone [email protected]:yi-wang-2/Buping_Job_Seeker_Assistant.git
cd Buping_Job_Seeker_Assistant

# 一键启动（自动安装依赖 + 启动前后端）
# Windows
.\start-dev.bat
# Linux/Mac
sh start-dev.sh

启动后访问：前端 http://127.0.0.1:5173 · 后端 http://127.0.0.1:8000

# 安装 Python 依赖
uv sync

# 安装前端依赖
cd frontend && npm install && cd ..

# 后端
uv run python -m uvicorn backend.app:app --host 127.0.0.1 --port 8000 --reload --reload-dir backend

# 前端 (另一个终端)
cd frontend && npm run dev

配置 API 密钥

启动后在前端「设置」页面配置 API Key，或编辑 data_folder/secrets.yaml：

llm_api_key: "your-api-key-here"
llm_base_url: "https://api.example.com/anthropic"
llm_model_type: "anthropic"
resume_language: "zh"
system_language: "zh"

优先级: 前端设置 → secrets.yaml → config.py

📥 导入基本信息（两种方式）

在使用本工具前，需要先准备你的简历数据。提供 手动填写 和 上传文档自动解析 两种方式：

方式一：手动填写 YAML 文件

直接编辑 data_folder/plain_text_resume.yaml（中文简历用 plain_text_resume_zh.yaml）：

personal_information:
  name: "Your"
  surname: "Name"
  email: "[email protected]"
  phone: "+1-555-123-4567"
  city: "San Francisco"
  country: "USA"
education_details:
  - education_level: "Bachelor's Degree"
    institution: "Stanford University"
    field_of_study: "Computer Science"
    year_of_completion: "2023"
experience_details:
  - position: "Senior Engineer"
    company: "Google"
    employment_period: "2020 - Present"
    key_responsibilities:
      - responsibility: "Led team of 5 engineers"
projects:
  - name: "Open Source Project"
    description: "Description of the project"

完整字段说明见 assets/resume_schema.yaml。

方式二：上传文档自动解析（推荐）

进入「设置」页面 → 「上传简历文档」区域，拖拽或点击上传任意格式的简历文件：

流程：

1. 上传文件（最大 5MB）
2. 系统自动解析（2-30 秒，PDF/Word 需调用 LLM）
3. 解析结果自动填入下方 YAML 编辑器
4. 检查修改 → 点击「保存简历内容」
5. 简历数据写入 data_folder/plain_text_resume*.yaml

小贴士：上传前请在设置页面填写 API Key（解析 PDF/DOCX 时需要 LLM 调用）；
YAML/JSON/TXT 文件无需 API Key 即可直接解析。

📖 使用说明

📄 生成简历

1. 在左侧导航点击「生成简历」
2. 配置 API Key、模型类型、简历语言
3. 选择简历样式模板（5 种可选）
4. 可选：粘贴职位描述生成定制简历
5. 点击「生成简历」，等待 ~30 秒
6. 下载 PDF

👀 实时预览 + ✏️ 在线编辑

简历生成后支持完整所见即所得的二次编辑流程：

1. 实时预览：左侧切换样式/语言时，预览自动刷新（不调 LLM，秒级响应）
2. 生成后自动预览：简历生成完毕，自动加载到预览框，无需手动操作
3. 历史预览：右上角下拉选择任意历史简历加载到预览
4. 切换编辑模式：点击「编辑模式」按钮，预览框变为 WYSIWYG 编辑器
5. 所见即所得编辑：在 iframe 中直接修改文字、格式、列表、链接——所见即所得
6. 版式微调：工具栏提供「行距」和「模块」滑块，可调整整体信息密度
7. 自动保存：修改后 1.5s 自动保存到 localStorage
8. 保存/重置：底部「保存」按钮提交修改，「重置」按钮放弃所有修改
9. 快捷键：支持 Ctrl+Z/Y（撤销/重做）、Ctrl+B/I/U（粗体/斜体/下划线）

技术说明：编辑器使用原生 <iframe> + document.designMode = "on" 实现，
与 WordPress 古腾堡、Notion 早期编辑器同源。样式 100% 保真，
删除了原 TipTap 依赖，bundle 体积减少 113KB。编辑后的内容会以完整 HTML 文档保存，
因此版式参数会同步影响后端 PDF 生成。

📋 面试准备

1. 点击「面试准备」
2. 粘贴目标职位描述 (JD)
3. 选择面试类型、设置问题数量
4. 点击「生成面试准备报告」
5. 查看 Markdown 报告并下载

🤖 模拟面试

1. 点击「模拟面试」
2. 配置公司、岗位、面试类型、面试官风格
3. 粘贴简历和 JD
4. 点击「开始面试」
5. 多轮对话，AI 面试官会追问
6. 点击「结束面试」生成评估报告

📚 历史记录

查看并下载之前生成的所有简历和报告。

⚙️ 设置

配置 API Key、模型、语言等，并可直接编辑简历 YAML 内容。

🎨 样式模板

📊 性能指标

🔧 问题排查

Q: 生成的简历内容太简单？
A: 在设置中增加 max_tokens 值（推荐 4096 或更高）。

Q: 401 认证错误？
A: 优先检查设置页或 data_folder/secrets.yaml 中的 API Key、Base URL、协议是否匹配。
系统会优先使用用户配置，其次才回退到 config.py 中的默认配置。

Q: PDF 生成失败？
A: 确保 Chrome 已安装且支持 headless 模式。Windows 上需要 Chrome 90+。

Q: CSS 文件读取错误 (GBK)？
A: 已在最新版修复，确保使用 encoding="utf-8"。

Q: 模拟面试无响应？
A: 检查 API Key 是否有效，查看终端日志。

Q: 编辑器看不到样式（颜色/字体/布局）？
A: 2026-06-19 起已改用 iframe + designMode 实现，编辑时样式 100% 与预览一致。
请确保 frontend/src/components/editor/EditableResumePreview.tsx 已更新到最新版本。

Q: PDF 在模块中间分页，或模块整体跳到下一页？
A: 当前 PDF 生成会保护二级小模块（如 .entry、技术栈、语言与其他、列表块）不被拆开；
一级 section 允许跨页，避免整个大模块跳页造成大面积空白。若单个小模块超过一页，Chrome 仍会强制分页。

Q: Modern Blue 超过两页？
A: Modern Blue 已压缩默认行距、模块间距、标题间距和打印样式。仍超页时，可在编辑模式用「行距」和「模块」滑块进一步压缩。

Q: 编辑时中文显示为乱码？
A: 旧版使用 PowerShell 写入时可能触发 GBK 编码，请用 UTF-8 (无 BOM) 重新写入文件：

[System.IO.File]::WriteAllText(
  "path/to/file.tsx",
    $content,
    [System.Text.UTF8Encoding]::new($false)
)

🤝 贡献指南

欢迎贡献！请遵循以下流程：

1. Fork 仓库
2. 创建功能分支 (git checkout -b feat/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送到分支 (git push origin feat/amazing-feature)
5. 创建 Pull Request

提交信息规范：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• test: 测试
• chore: 构建/工具

📜 License

MIT License

🔗 相关链接

🙏 致谢

本项目基于开源项目 Jobs_Applier_AI_Agent_AIHawk 开发，感谢原作者 feder-cr 的开源贡献。

在此基础上扩展了：

• 中文简历支持
• 模拟面试模块
• 面试准备模块
• API Key Fallback 机制
• 性能优化（LLM 调用合并）

Made with ❤️ by yi-wang-2