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

## 1. 接口概述

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

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

## 2. 入参 Schema

```python
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

```python
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 模型已全部存在