offerpai_python_ai/.kiro/specs/job-agent-chat/design.md

求职助手 Agent 对话接口设计方案

1. 接口概述

POST /job-agent/chat — 求职助手对话接口，Python 端实现。

用户通过对话与求职助手交互，AI 根据用户简历和求职意向提供求职建议，识别用户意图后触发前端工具调用（岗位推荐 / 调整偏好）。

2. 入参 Schema

class ChatMessage(BaseModel):
    role: Literal["user", "assistant"]
    content: str

class JobAgentChatParam(BaseModel):
    message: str = Field(..., description="用户输入的消息")
    resume_id: int = Field(..., alias="resumeId", description="简历ID")
    history: list[ChatMessage] = Field(default_factory=list, description="对话历史")
    job_categories: list[str] = Field(default_factory=list, alias="jobCategories", description="意向岗位类型名称")
    regions: list[str] = Field(default_factory=list, alias="regions", description="意向城市名称")
    industries: list[str] = Field(default_factory=list, alias="industries", description="意向行业名称")

3. 出参 Schema

class ToolParams(BaseModel):
    preference: str = Field(default="", description="用户岗位偏好描述，仅tool=recommend时有值")

class JobAgentChatDto(BaseModel):
    message: str = Field(..., description="AI回复文本，不超过200字")
    tool: str | None = Field(default=None, description="前端需执行的工具：recommend / editPreference / null")
    tool_params: ToolParams | None = Field(default=None, alias="toolParams", description="工具参数")

4. AI 上下文构造

每次对话请求，后端自动查询以下数据拼入 system prompt：

1. 简历信息：根据 resumeId 查 bg_user_resume 主表 + 5张子表（教育/工作/实习/项目/竞赛），序列化为文本
2. 求职意向：直接使用前端传入的 jobCategories / regions / industries（中文名称）

5. System Prompt 设计

你是 OfferPie 求职助手，帮助用户找到合适的工作。

【用户简历】
{resume_text}

【求职意向】
意向岗位：{job_categories}
意向城市：{regions}
意向行业：{industries}

【你的能力】
1. 回答求职相关问题（面试技巧、简历建议、行业分析等），回复不超过200字
2. 当用户想看岗位推荐时，提取用户的偏好描述，调用岗位推荐工具
3. 当用户想修改求职偏好/设置时，调用偏好设置工具

【输出格式】
严格返回 JSON，不要其他内容：
{"message":"回复内容","tool":null,"toolParams":null}

tool 可选值：
- null：普通对话，不触发工具
- "recommend"：岗位推荐，toolParams 必须包含 {"preference":"用户偏好描述"}
- "editPreference"：调整偏好，toolParams 为 null

【规则】
1. 只聊求职相关话题，其他话题礼貌拒绝
2. 回复简洁，不超过200字
3. 用户表达想看岗位、推荐岗位、帮我找工作等意图时，从对话中提取偏好描述，返回 recommend
4. 用户表达想改设置、调整偏好、修改意向等意图时，返回 editPreference
5. 偏好描述要准确概括用户的岗位偏好，如"更偏技术方向的产品岗"、"大厂优先"

6. 处理流程

1. 校验登录态，获取 user_id
2. 根据 resume_id 查简历主表 + 5张子表，序列化为文本
3. 构造 system prompt（简历 + 求职意向 + 规则）
4. 构造 messages 列表：system prompt + history + 当前 message
5. 调用 LLM（使用 LLM.DEEPSEEK_V3 或配置的模型）
6. 用 parse_llm_json 解析 AI 返回的 JSON
7. 构造 JobAgentChatDto 返回

7. 前端交互流程

1. 前端发消息 → 调 POST /job-agent/chat
2. 拿到返回后判断 tool 字段：
   • tool=null → 直接展示 message
   • tool="recommend" → 展示 message + 用 toolParams.preference 调 Java 端 POST /job/agent/recommend 拿岗位列表展示
   • tool="editPreference" → 展示 message + 打开偏好设置页面

8. 涉及文件

文件	位置	说明
job_agent_chat.py	app/schemas/	Pydantic 请求/响应 Schema
job_agent_chat.py	app/api/	路由定义
job_agent_chat_service.py	app/services/	Service：查简历 + 构造 prompt + 调 LLM
prompts.py	app/ai/job_agent/	System Prompt 模板
main.py	app/	注册新路由

9. 依赖的现有模块

• app/models/user_resume.py + 5张子表 ORM — 查简历数据
• app/ai/models.py — LLM 枚举，创建模型实例
• app/tool/json_helper.py — parse_llm_json 解析 AI 输出
• app/core/context.py — RequestContext 获取 user_id
• app/core/database.py — get_db 获取数据库会话

10. 不需要新增的 ORM 模型

• 求职意向由前端传入中文名称，不查 bg_user_job_intention 表
• 简历相关 ORM 模型已全部存在