# 职睿

**Repository Path**: bu-jianwu/zhirui

## Basic Information

- **Project Name**: 职睿
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 职睿 CareerWise · 一体式多智能体求职助手（LangGraph + FastAPI）

面向「求职者」的五智能体系统：一个总指挥 + 四个领域专家，支持 **就业规划咨询、面试题 PDF 生成
（可基于你的真实项目出题）、参考 GitHub 高星项目写工程级代码、上传简历 PDF 获得优化版简历**；
也可在对话中**直接发送图片**（简历截图 / JD / 面试题截图等，配置可选的多模态视觉模型后即可识别）；
另设 Harness **质检智能体**对专家产出做外部工具复核门禁。
整合了智能体主流技术：**LangGraph 图编排、RAG（向量库+关键词混合检索）、真实 MCP 工具协议、
工具调用、SQLite 会话记忆 + 向量跨会话长期记忆、SSE 流式输出、PDF 生成、受限文件系统工具**。

> 注意：本目录同时也是 MCP Server 所在仓库 —— 一个项目内同时演示了 **MCP Server 实现**
> 与 **MCP Client(Hub) 接入**。

---

## 一、四个智能体

| # | 智能体 | 角色 | 主要能力 / 工具 |
|---| --- | --- | --- |
| 1 | **总指挥 Orchestrator** | 与用户交流、判断意图、分派任务、整合汇报 | 三个委派工具（ReAct 图 + SQLite 多轮记忆） |
| 2 | **就业规划专家** | 行业/城市/薪资/新技术咨询，结论有依据 | `web_search`、`fetch_page`、RAG(职业库)、MCP(`market_overview`/`salary_reference`/`hot_skills`) |
| 3 | **面试辅导专家** | 查证后整理题目，生成可靠 PDF；可精读你的项目出定制题 | `web_search`、RAG(面试库)、MCP 题库、`generate_interview_pdf`、**项目只读工具**(`read_project_file` 等) |
| 4 | **写项目专家** | 需求分析→参考高星项目→写/改本地真实文件→自检交付 | 受限文件读写工具、语法自检、MCP `github_top_repos`、可选沙箱命令执行 |

### 面试 PDF 的“可靠性”设计
- 智能体提示词强制：题目优先来自 **题库/知识库/可核实网页**，每题必须给出
  **参考要点 + 难度 + 考察点 + 来源**，并附来源不明标注；
- 无可靠信息时要求明确说“未获取到/建议以官方为准”，禁止编造凑数；
- 生成前可交叉检索多来源；PDF 首页带“口径与免责声明”。

### 第三个智能体读取第四个智能体的项目
面试专家内置一套**只读**项目工具（`list_projects / list_project_files / read_project_file / search_project`），
当你说“结合我做的 XX 项目出面试题”时，它会精读你（由写项目专家产出）的真实代码，设计
架构 / 难点 / 扩展 / 性能 / 安全等「项目深挖题」——这是面试中最拉差距的一类问题。

---

## 二、架构图

```
用户 ── FastAPI(SSE) ──> 总指挥(Agent1 ReAct图, SQLite Checkpointer 多轮记忆)
                          │  委派(delegate tool)
        ┌─────────────────┼──────────────────┐
        ▼                 ▼                  ▼
  就业规划专家(2)     面试辅导专家(3)      写项目专家(4)
   [各自也是 ReAct 图 + 工具循环]
   工具:               工具:               工具:
   web_search         web_search          文件读写/改/删
   fetch_page         RAG(面试知识库)      search_in_files
   RAG(职业知识库)    generate_interview_pdf python_syntax_check
   MCP:               MCP: question_bank   MCP: github_top_repos
    market/salary/    【只读】读取写项目     (可选)沙箱命令执行
    hot_skills        专家产出的项目
                          │
                          └─> storage/pdfs/*.pdf
```

- **编排模式**：Supervisor / Orchestrator-Workers。总指挥是上层 ReAct 图，专家是下层 ReAct 图，
  层级清晰、易扩展。
- **工具来源**：原生 LangChain 工具（`@tool`/`StructuredTool`）+ **MCP Hub** 注入的 MCP 工具
  （在 `app/agents/*.py` 中按需过滤加载）。
- **状态记忆**：总指挥图挂 `AsyncSqliteSaver`，按 `thread_id` 存对话；
  会话明文另存 `storage/threads/*.jsonl` 供历史回放。

### 目录结构
```
├── main.py                     # FastAPI 入口（lifespan 自动摄入知识库）
├── app/
│   ├── config.py               # .env 配置（provider/embedding/存储路径）
│   ├── memory.py               # Async SQLite checkpointer + 会话记录
│   ├── llm/                    # 模型工厂（DeepSeek/OpenAI 兼容 + 多模态视觉识别）+ Mock
│   ├── vectorstore/            # 向量库抽象：Chroma(默认)/Weaviate(可选)/关键词兜底 + 摄入
│   ├── rag/                    # RAG 检索工具封装（kb_search_*）
│   ├── mcp/                    # MCP Server(就业/题库/GitHub) + Client Hub + servers.json
│   ├── tools/                  # web 搜索 / PDF / 工作区文件工具
│   ├── agents/                 # prompts + 四个智能体 + 委派编排
│   └── web/                    # 内置聊天页
├── data/                       # RAG 种子文档 + MCP 数据快照
├── scripts/                    # ingest_kb / run_mcp_server
├── storage/                    # 运行时产物（pdfs/projects/threads/chroma/*.db）
└── tests/                      # 离线冒烟测试（Mock 模型，无需 Key）
```

---

## 三、快速开始

### 1. 安装
```bash
python -m venv .venv
.venv\Scripts\activate            # Windows
pip install -r requirements.txt
pip install pytest                # 仅运行测试需要
```

### 2. 配置 `.env`（从 `.env.example` 复制）
```ini
LLM_PROVIDER=deepseek
LLM_API_KEY=sk-xxxx
# 也可整链切到阿里云百炼（一个 Key 全开：对话 + 发图识别 + RAG 向量），见 .env.example 顶部说明：
# LLM_PROVIDER=dashscope
# LLM_MODEL=qwen-plus
# EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# VISION_PROVIDER=dashscope
# 可选：对话里发送图片（DeepSeek 不支持图像，需另配一个 OpenAI 兼容的视觉模型）
# VISION_PROVIDER=zhipu            # 或 dashscope / openai，或用 VISION_BASE_URL+VISION_MODEL 自定义
# VISION_API_KEY=sk-xxx
# 可选：配置任一 OpenAI 兼容 embedding 以开启语义向量库（DeepSeek 无 embedding 接口）
# EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# EMBEDDING_API_KEY=sk-xxx
# EMBEDDING_MODEL=text-embedding-v3
# 可选：实时网页搜索
# TAVILY_API_KEY=tvly-xxx
```
> **没有 Key 也能体验**：`LLM_PROVIDER=mock` 会在无网/无 Key 时跑通整条链路
> （总指挥→专家→检索工具），用于验收部署是否正确。

### 3. 启动
```bash
.venv\Scripts\activate
uvicorn main:app --reload --port 8000
```
打开 http://127.0.0.1:8000 即内置聊天页。首次启动会自动把 `data/` 种子文档摄入向量库。

### 4. 常用 API
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/chat/stream` | SSE 流式对话 `{message, images?, thread_id}`（images 为可选图片 data URL） |
| POST | `/api/chat` | 一次性对话（同样支持 `images`） |
| GET | `/api/health` | 模型 / 向量后端 / 知识库状态 |
| GET/POST | `/api/kb/status`、`/api/kb/ingest` | 知识库状态 / 重新摄入 |
| GET | `/api/history/{thread_id}`、`/api/threads` | 历史会话 |
| GET | `/api/files/pdf/{name}`、`/api/files/projects/{name}/download` | 下载 PDF / 项目 zip |
| GET | `/api/agents` | 智能体清单 |

---

## 四、如何扩展

**加一个新的专家智能体**（3 步）：
1. 在 `app/agents/prompts.py` 写系统提示词；
2. 在 `app/agents/` 新建 `xxx.py`，实现 `build_xxx_agent_tools()` 与 `build_xxx_agent(model)`，
   参考 `career.py` 几十行的写法（可混用原生工具与 `available_mcp_tools()` 过滤出的 MCP 工具）；
3. 在 `app/agents/orchestrator.py` 的 `DELEGATES` 注册表里加一条即可，总指挥会自动获得委派能力。

**加一个 MCP Server**：在 `app/mcp/servers.json` 追加 `{name, module 或 command/args/env}`，
重启即自动连接并注入各智能体（内置 `career_assistant` 见 `app/mcp/server.py`，可作为样板）。

**换 LLM / embedding / 向量库**：改 `.env` 的 provider 与 base_url；换向量实现只需实现
`app/vectorstore/store.py` 中的 `_VectorStore` 接口并注册进工厂。

**改知识库内容**：往 `data/career`、`data/interview` 添加 `.md`，重启或调 `/api/kb/ingest`。

---

## 五、测试与安全说明
- `pytest tests/` 为**离线冒烟测试**：RAG 摄入与检索、PDF 生成、总指挥→专家→工具全链路（Mock 模型）。
- 写代码智能体的文件工具**限死在 `storage/projects` 内**（防目录穿越），删除/命令执行均有白名单；
  `SANDBOX_EXEC_ENABLED` 默认关闭 shell 执行。
- 面试专家只读项目文件，**无写权限**。
- 所有联网与数据结论都带「来源/日期/口径」标注，无法核实的信息明确提示，不在 PDF 里编造。

## 六、Roadmap 建议
- 语义向量库：按 `.env.example` 配置任一 OpenAI 兼容 embedding，重启即自动切 Chroma 语义检索；
- 更稳的实时搜索：接入 Tavily / Bing 等 key，或自行替换 `app/tools/web.py`；
- 生产化：多轮记忆换 Redis/Postgres checkpointer、加 LangSmith trace、用户画像持久化。