Spaces:
Sleeping
Sleeping
📑 技术规格说明(SPR) — AI-powered Resume & Cover Letter Generator
1. 项目结构
apply-helper/
├── pyproject.toml # 项目依赖与配置
├── uv.lock # UV 依赖锁定文件
├── .env.example # 环境变量配置模板
├── src/ # 源代码根目录
│ ├── streamlit_app.py # Streamlit 前端主入口
│ ├── mock_data.py # 测试用模拟数据
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py
│ │ ├── analyse_service.py # JD/用户信息分析与总结
│ │ ├── generation_service.py # 简历与求职信生成
│ │ └── llm_service.py # LLM/LiteLLM 统一封装与调用
│ └── llm/ # LLM集成层
│ ├── __init__.py
│ ├── litellm_client.py # LiteLLM API 封装
│ └── prompt_templates.py # LLM Prompt 模板管理
├── docs/ # 文档目录
│ ├── prd.md # 产品需求文档
│ ├── spec.md # 技术规格说明(本文件)
│ ├── services.spec.md # 服务层规格说明
│ └── llm.spec.md # LLM集成规格说明
└── tests/ # 单元测试(待实现)
2. 主要 Python 文件与函数
2.1 src/streamlit_app.py — Streamlit 前端主入口
- 页面布局: 侧边栏输入控制,主区域双列预览(简历 + 求职信)
- 会话状态管理: 使用
st.session_state持久化分析结果、生成文档和错误状态 - 主要函数:
main():应用入口,负责页面配置、UI渲染与交互逻辑initialize_session_state():初始化会话状态变量handle_analyse(jd: str, user_info: str):分析按钮回调,包含输入验证、调用服务、异常处理handle_refine(feedback: str):优化按钮回调,基于反馈更新分析handle_mock_analyse():模拟分析按钮回调,加载预设测试数据
- 模拟数据功能: 三个按钮支持加载模拟JD、简历和完整分析结果
- 错误处理: 集中化错误显示,用户友好提示信息
2.2 LLM 集成层
src/services/llm_service.py — LLM服务包装层
- 核心功能: 提供LLM调用的统一接口,负责提示词模板格式化和LiteLLM调用
- 主要函数:
analyse_llm(jd: str, user_info: str) -> str: 工作分析,返回原始LLM响应字符串refine_llm(summary_json: str, feedback: str) -> str: 基于反馈优化分析,返回原始LLM响应generate_resume_llm(summary_json: str, user_info: str) -> str: 生成Markdown格式简历generate_cover_letter_llm(job_description: str, user_info: str) -> str: 生成德语求职信
src/llm/litellm_client.py — LiteLLM客户端集成
- 多Provider支持: 优先支持Azure OpenAI,备用支持标准OpenAI
- 自动配置: 基于环境变量自动检测和配置最优客户端
- 主要函数:
call_llm(prompt: str, model: str = None, max_tokens: int = 800, temperature: float = 1.0) -> strget_azure_client() -> dict: 配置Azure OpenAI客户端get_openai_client() -> dict: 配置标准OpenAI客户端- 包含连接测试和调试模式,支持litellm debug
src/llm/prompt_templates.py — 提示词模板管理
- 模板类型: analyse, refine, generate_resume, generate_cover_letter
- 函数:
get_template(name: str) -> str - 特点:
- 字典存储,包含详细的JSON输出格式要求
- ANALYSE_PROMPT: 德国科技市场专家角色,8-12个技能提取,4-6个匹配点分析
- GENERATE_COVER_LETTER_PROMPT: 德语商务求职信生成,符合德国商务信函规范
- 所有模板包含明确的输出格式要求和角色设定
核心处理逻辑
- 提示词管理: 从模板获取提示词,使用Python字符串format动态替换参数
- LLM调用: 通过LiteLLM统一接口调用不同provider的模型
- 错误处理: LiteLLM层处理API调用异常,服务层处理业务逻辑异常
- 响应处理: 返回原始字符串响应,由上层服务负责结构化解析
2.3 业务服务层
src/services/analyse_service.py — 分析服务
- 功能: 职位描述与用户背景的匹配分析,使用Pydantic数据模型
- 数据模型:
AnalysisResult(BaseModel)- 结构化分析结果- key_skills: List[str] - 关键技能列表
- match_points: List[str] - 匹配优势点
- gap_points: List[str] - 技能差距点
- suggestions: List[str] - 改进建议
- pitch: str - 价值主张
- 主要逻辑:
- 验证输入参数非空
- 委托LLM服务进行分析
_parse_analysis_response()- 复杂JSON解析逻辑,处理代码块包装analyse()- 初始分析,返回AnalysisResult对象refine()- 基于反馈优化分析,使用model_dump_json()序列化
src/services/generation_service.py — 文档生成服务
- 功能: 编排简历和求职信的生成
- 主要接口:
generate_resume(summary: AnalysisResult, user_info: str) -> str- 生成简历generate_cover_letter(job_description: str, user_info: str) -> str- 生成求职信generate_both(summary: AnalysisResult, user_info: str, job_description: str) -> Tuple[str, str]- 生成完整文档对
- 主要逻辑:
- 使用AnalysisResult对象和原始文本作为输入
- 调用LLM服务生成简历(Markdown)和求职信(德语文本)
- 支持动态导入处理,兼容模块和独立运行
- 返回生成的文档元组
2.4 模拟数据系统
src/mock_data.py — 测试数据管理
- MOCK_JD: 完整的高级软件工程师职位描述
- MOCK_RESUME: John Smith 的详细简历信息
- Analysis_Summary: 结构化分析结果(Dict格式)
- key_skills, match_points, gap_points, suggestions, pitch
- Resume: 生成的Markdown格式简历
- Cover_Letter: 生成的纯文本求职信
- 用途: 支持无需LLM调用的完整工作流测试
3. Streamlit UI 实现
3.1 页面布局
侧边栏(Sidebar):
- 模拟数据按钮: 三列布局 - "Load Mock JD", "Load Mock Resume", "Mock Analyse"
- 输入区域:
- Job Description 文本区域(高度150px)
- User Resume/Info 文本区域(高度200px)
- 控制按钮: "Analyse" 按钮(全宽)
- 优化区域:
- Feedback 文本区域(高度100px)
- "Refine" 按钮(全宽)
主区域(Main Area):
- 错误显示: 使用
st.error()显示异常信息 - 分析摘要: 使用
st.json()展示结构化分析结果 - 双列预览:
- 左列: Resume 预览(Markdown 渲染)
- 右列: Cover Letter 预览(纯文本显示)
- 错误显示: 使用
3.2 会话状态管理
状态变量:
summary- 分析摘要结果resume_md- 生成的简历Markdowncover_letter_txt- 生成的求职信文本error- 错误信息显示user_info_input- 用户输入缓存
3.3 交互流程
标准工作流:
- 输入JD和用户信息 → 点击"Analyse" → 显示分析和生成结果
- 输入反馈 → 点击"Refine" → 更新分析和重新生成
模拟数据工作流:
- 点击"Load Mock JD" → 自动填充职位描述
- 点击"Load Mock Resume" → 自动填充简历信息
- 点击"Mock Analyse" → 直接加载完整分析结果
错误处理:
- 输入验证: 检查空值,显示友好错误信息
- 异常捕获: 包装在try-catch中,显示具体错误消息
- 状态清理: 成功时清除error状态
4. 技术实现详情
4.1 依赖管理
核心依赖: streamlit (UI), litellm (LLM调用), python-dotenv (环境变量), weasyprint (PDF,未使用), pydantic (验证,未使用)
安装和运行:
pip install uv- 安装包管理器uv sync- 同步依赖cp .env.example .env- 配置环境变量uv run streamlit run src/streamlit_app.py- 启动应用
4.2 LLM集成配置
多Provider支持: 优先Azure OpenAI,备用标准OpenAI
Azure OpenAI配置: AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_MODEL, AZURE_OPENAI_API_VERSION(默认2024-12-01-preview)
OpenAI配置: OPENAI_API_KEY(使用gpt-3.5-turbo模型)
配置逻辑:
- 优先检测Azure配置,如果完整则使用Azure
- Azure不可用时回退到标准OpenAI
- 支持模型参数覆盖,但仅支持azure/前缀的模型
- 包含详细的配置验证和错误提示
4.3 开发和测试
模拟数据测试:
- 无需配置LLM即可测试完整UI流程
src/mock_data.py包含完整测试数据集- 点击"Mock Analyse"按钮即可加载预设结果
调试和测试模式:
python src/llm/litellm_client.py- 测试LLM连接和配置验证python src/services/analyse_service.py- 测试分析服务完整流程python src/services/generation_service.py- 测试文档生成流程- 包含litellm._turn_on_debug()调试支持
4.4 架构特点
模块化设计:
- 业务逻辑与UI分离
- LLM集成层独立封装
- 服务层薄包装,便于替换实现
扩展点:
- 添加新的LLM provider: 扩展
litellm_client.py中的客户端配置函数 - 添加PDF导出: 实现
pdf_service.py集成WeasyPrint - 添加新的生成模板: 在
prompt_templates.py中添加新模板常量 - 数据验证增强: 当前使用Pydantic AnalysisResult模型,可扩展更多验证模型
- 多语言支持: 扩展prompt_templates支持不同语言的求职信生成