# Recruiter Navigator

<div align="center">

**招聘工具导航器 — 纯导航 + 极简启动的统一入口**

覆盖 **47 个招聘工具**，提供命令行和 Web 两种交互方式

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()

</div>

---

## 📖 目录

- [项目简介](#-项目简介)
- [核心功能](#-核心功能)
- [快速开始](#-快速开始)
- [命令详解](#-命令详解)
- [Web 界面](#-web-界面)
- [工具分类](#-工具分类)
- [自定义配置](#-自定义配置)
- [技术架构](#-技术架构)
- [开发指南](#-开发指南)
- [项目结构](#-项目结构)

---

## 🎯 项目简介

**Recruiter Navigator** 是一个招聘工具导航器，为 47 个招聘工具提供统一的导航入口和极简启动机制。

### 核心定位

- **纯导航**：不实现工具的具体功能，只提供导航和启动
- **统一入口**：一个命令访问所有招聘工具
- **双界面**：同时支持命令行（CLI）和 Web 可视化界面
- **工作流可视化**：展示工具间的上下游关系，构建完整招聘流程

### 覆盖场景

涵盖招聘全流程的 5 大领域：

| 领域 | 工具数 | 典型工具 |
|------|--------|----------|
| 🔍 人才搜索 | 13 | LinkedIn 搜索、脉脉搜索、GitHub 人才挖掘 |
| 📄 简历处理 | 12 | 简历解析、简历评估、候选人画像 |
| ✉️ 候选人触达 | 4 | 冷邮件生成、消息自动化、跟进管理 |
| 📊 数据管理 | 8 | 数据清洗、可视化分析、洞察报告 |
| 🔧 基础设施 | 10 | LLM 服务、浏览器自动化、Agent 框架 |

---

## ✨ 核心功能

### 1. 工具发现与浏览

- **列表展示**：表格形式展示所有工具
- **分类筛选**：按 5 大分类快速定位
- **关键词搜索**：支持工具名称、描述、标签搜索
- **详情查看**：查看工具完整文档、使用场景、快速开始

### 2. 一键启动

- **CLI 工具**：直接在终端执行命令
- **Web 应用**：自动启动服务并打开浏览器
- **交互式工具**：启动交互式会话

### 3. Web 可视化面板

- **招聘流程信息图**：可视化展示完整招聘流程和工具链
- **工具画廊**：卡片式展示所有工具
- **场景导航**：8 个典型招聘场景的完整工具链路
- **词云展示**：动态展示招聘场景关键词

### 4. 工作流可视化

- **上下游关系**：展示工具的前置和后续工具
- **拓扑图**：构建工具链的完整拓扑结构
- **场景推荐**：基于当前工具推荐下一步操作

### 5. 自定义配置

- **本地配置**：支持自定义工具注册表
- **配置覆盖**：使用自定义配置替代默认配置
- **灵活扩展**：添加新工具无需修改代码

---

## 🚀 快速开始

### 安装

```bash
pip install recruiter-navigator
```

### 基本使用

```bash
# 查看所有工具
recruiter list

# 按分类筛选
recruiter list --category search

# 关键词搜索
recruiter list --keyword linkedin

# 启动工具
recruiter use search-talent

# 启动 Web 面板
recruiter web
```

### Web 界面

启动 Web 服务后，访问 http://localhost:8080：

- **主页**：`/home` - 招聘流程信息图
- **工具列表**：`/` - 工具卡片画廊

---

## 📚 命令详解

### `recruiter list` - 列出工具

列出所有或筛选后的工具列表。

```bash
# 列出所有工具
recruiter list

# 按分类筛选
recruiter list --category search    # 人才搜索
recruiter list --category resume    # 简历处理
recruiter list --category outreach  # 候选人触达
recruiter list --category data      # 数据管理
recruiter list --category infra     # 基础设施

# 关键词搜索
recruiter list --keyword resume
recruiter list --keyword linkedin
recruiter list --keyword "cold email"

# 使用自定义配置
recruiter list --config ./my-registry.yaml
```

**输出示例**：

```
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                   ┃ Category   ┃ Description                      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ search-talent          │ search     │ LinkedIn 高级人才搜索工具         │
│ resume-oneclick        │ resume     │ 一键简历解析与结构化              │
│ cold-email-ai          │ outreach   │ AI 驱动的冷邮件生成器             │
│ ...                    │ ...        │ ...                              │
┗━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

---

### `recruiter use` - 启动工具

启动指定的工具。

```bash
# 基本用法
recruiter use <tool-name>

# 示例
recruiter use search-talent
recruiter use resume-oneclick
recruiter use cold-email-ai

# 传递参数给工具
recruiter use search-talent -- --location "Beijing" --keywords "Python"

# 使用自定义配置
recruiter use search-talent --config ./my-registry.yaml
```

**启动模式**：

- **CLI 模式**：在当前终端执行命令
- **Web 模式**：启动 Web 服务并自动打开浏览器
- **交互式模式**：启动交互式会话

---

### `recruiter web` - 启动 Web 面板

启动 FastAPI Web 可视化界面。

```bash
# 基本用法
recruiter web

# 指定端口
recruiter web --port 9000

# 自动打开浏览器
recruiter web --open

# 使用自定义配置
recruiter web --config ./my-registry.yaml

# 组合使用
recruiter web --port 9000 --open --config ./my-registry.yaml
```

**访问地址**：

- 主页（招聘流程信息图）：http://localhost:8080/home
- 工具画廊：http://localhost:8080/

---

### `recruiter init` - 初始化配置

将内置的 `registry.yaml` 复制到本地，用于自定义配置。

```bash
# 复制到当前目录
recruiter init

# 指定输出目录
recruiter init --output ~/my-tools

# 覆盖已存在文件
recruiter init --force

# 组合使用
recruiter init --output ~/my-tools --force
```

**输出示例**：

```
✅ 已创建配置文件: ./registry.yaml

📝 下一步:
  1. 编辑 registry.yaml 添加或修改工具
  2. 使用 recruiter list --config ./registry.yaml 查看自定义工具
  3. 使用 recruiter web --config ./registry.yaml 启动 Web 面板
```

---

## 🌐 Web 界面

### 页面路由

| 路径 | 说明 | 功能 |
|------|------|------|
| `/home` | 招聘流程信息图 | 核心功能页面，展示完整招聘流程 |
| `/` | 工具画廊 | 工具卡片列表，支持分类筛选和搜索 |
| `/api/tools` | 工具列表 API | 返回所有工具摘要（JSON） |
| `/api/tool/{name}` | 工具详情 API | 返回单个工具完整信息（JSON） |
| `/api/workflow-graph` | 工作流图 API | 返回工具链拓扑数据（JSON） |
| `/api/launch-guide/{name}` | 启动指引 API | 返回终端启动命令（JSON） |

### 招聘流程信息图（核心功能）

**6 个招聘阶段**：

1. 📋 **职位准备**：需求分析、JD 生成
2. 🔍 **人才搜索**：多平台搜索、人才发现
3. 📄 **简历处理**：解析、评估、画像构建
4. ✉️ **候选人触达**：邮件、消息、跟进
5. 📊 **数据分析**：可视化、洞察报告
6. 🔧 **基础设施**：LLM、浏览器、Agent

**8 个典型场景**：

1. LinkedIn 标准招聘流程
2. 脉脉 AI 自动化招聘
3. GitHub 开源人才定向招聘
4. 学术/专利人才挖掘
5. 简历批量处理与评估
6. 一站式多渠道触达
7. Agent 自动化全流程
8. 招聘数据可视化分析

**交互功能**：

- 点击阶段查看该阶段的所有工具
- 点击场景查看完整工具链路
- 词云动态展示场景关键词
- 工具卡片悬停显示详情

### 工具画廊

**功能特性**：

- 分类标签快速筛选
- 实时搜索过滤
- 工具卡片展示（名称、描述、分类、标签）
- 点击查看完整文档
- 一键复制启动命令

---

## 🗂️ 工具分类

### 🔍 人才搜索（Search）

多平台人才发现与搜索工具。

**工具列表**（13 个）：

- `search-talent`：LinkedIn 高级人才搜索
- `maimai-search`：脉脉人才搜索
- `liepin-search`：猎聘人才搜索
- `github-talent-scout`：GitHub 开源人才挖掘
- `scholar-talent-finder`：学术人才发现
- `patent-talent-miner`：专利人才挖掘
- ...

**典型场景**：

- LinkedIn 生态：search-talent → resume-oneclick
- 脉脉生态：maimai-search → maimai-auto-connect
- GitHub 生态：github-talent-scout → github-profile-analyzer

---

### 📄 简历处理（Resume）

简历解析、评估、画像构建工具。

**工具列表**（12 个）：

- `resume-oneclick`：一键简历解析
- `resume-batch-parser`：批量简历解析
- `resume-evaluator`：简历质量评估
- `candidate-profiler`：候选人画像构建
- `resume-filter`：简历智能筛选
- `jd-resume-matcher`：JD-简历匹配
- ...

**子分类**：

- 解析：resume-oneclick、resume-batch-parser
- 评估：resume-evaluator、jd-resume-matcher
- 画像：candidate-profiler
- 筛选：resume-filter
- 辅助：resume-summarizer

---

### ✉️ 候选人触达（Outreach）

冷邮件、消息自动化、跟进管理工具。

**工具列表**（4 个）：

- `cold-email-ai`：AI 冷邮件生成
- `outreach-automation`：触达自动化
- `follow-up-manager`：跟进管理
- `multi-channel-outreach`：多渠道一站式触达

**典型场景**：

- 邮件生成：cold-email-ai → follow-up-manager
- 消息发送：outreach-automation
- 一站式：multi-channel-outreach

---

### 📊 数据管理（Data）

数据清洗、可视化、洞察报告工具。

**工具列表**（8 个）：

- `data-cleaner`：招聘数据清洗
- `recruit-visualizer`：招聘数据可视化
- `talent-insight`：人才洞察报告
- `pipeline-tracker`：招聘漏斗追踪
- `report-generator`：招聘报告生成
- ...

**子分类**：

- 数据处理：data-cleaner
- 可视化：recruit-visualizer、pipeline-tracker
- 洞察：talent-insight、report-generator

---

### 🔧 基础设施（Infra）

LLM、浏览器、Agent 等底层支撑工具。

**工具列表**（10 个）：

- `llm-service`：LLM 服务接口
- `browser-automation`：浏览器自动化
- `recruit-agent`：招聘 Agent 框架
- `api-gateway`：API 网关
- `tool-orchestrator`：工具编排器
- ...

**子分类**：

- LLM：llm-service
- 浏览器：browser-automation
- Agent：recruit-agent
- API：api-gateway
- 工具：tool-orchestrator

---

## ⚙️ 自定义配置

### 创建本地配置

```bash
# 初始化配置文件
recruiter init

# 编辑配置文件
vim registry.yaml
```

### 配置文件结构

```yaml
tools:
  - name: my-custom-tool          # 工具包名（唯一标识）
    display_name: "My Custom Tool" # 显示名称
    description: "自定义工具描述"   # 一句话描述
    category: search               # 分类（search/resume/outreach/data/infra）
    pypi_url: "https://pypi.org/project/my-custom-tool/"
    launch:
      mode: cli                    # 启动模式（cli/web/interactive）
      command: "my-custom-tool"    # 终端命令
      web_port: 8080               # Web 端口（仅 web 模式需要）
    docs:
      readme: |                    # 完整介绍（Markdown）
        # My Custom Tool
        > 一句话描述
        
        ## 功能特性
        - 功能1
        - 功能2
        
        ## 使用方法
        ```bash
        my-custom-tool --help
        ```
      use_cases:                   # 使用场景
        - "场景1：xxx"
        - "场景2：xxx"
      workflow:                    # 工作流上下游
        prev_tools:                # 前置工具
          - search-talent
        next_tools:                # 后续工具
          - resume-oneclick
      quick_start:                 # 新手指引
        install: "pip install my-custom-tool"
        command_example: "my-custom-tool --help"
        expected_output: "显示帮助信息"
      tags:                        # 标签
        - "#自定义"
        - "#搜索"
```

### 使用自定义配置

```bash
# 列出工具
recruiter list --config ./registry.yaml

# 启动工具
recruiter use my-custom-tool --config ./registry.yaml

# 启动 Web 面板
recruiter web --config ./registry.yaml
```

---

## 🏗️ 技术架构

### 分层架构

```
┌─────────────────────────────────────┐
│         CLI 层 (cli/)               │  ← 用户交互
│  init / list / use / web            │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│       核心层 (core/)                 │  ← 业务逻辑
│  models / registry / launcher        │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│       数据层 (data/)                 │  ← 静态配置
│       registry.yaml                  │
└─────────────────────────────────────┘
```

### 核心模块

#### 1. Core 模块

**models.py** - 数据模型定义

- `Category`：工具分类枚举
- `LaunchMode`：启动模式枚举
- `Tool`：工具完整元数据
- `ToolSummary`：工具摘要
- `Registry`：工具注册表容器

**registry.py** - 工具注册表加载器

- `load_registry()`：加载并解析 registry.yaml
- `get_all_tools()`：获取所有工具
- `get_tool(name)`：按名称获取工具
- `get_tools_by_category(category)`：按分类筛选
- `search_tools(keyword)`：关键词搜索
- 使用 `@lru_cache` 缓存提升性能

**launcher.py** - 工具启动逻辑

- `launch_tool(tool, args)`：根据启动模式执行启动
- `_launch_cli()`：CLI 模式启动
- `_launch_web()`：Web 模式启动
- `_launch_interactive()`：交互式模式启动

#### 2. CLI 模块

**app.py** - Typer 主应用

- 注册 4 个子命令：init、list、use、web
- 使用 Rich 库提供美观输出

**init.py / list.py / use.py / web.py** - 各命令实现

#### 3. Web 模块

**app.py** - FastAPI 应用工厂

- 创建并配置 FastAPI 应用
- 挂载静态文件和模板引擎
- 注册路由模块

**routes/** - 路由模块

- `home.py`：招聘流程信息图
- `index.py`：工具画廊
- `detail.py`：工具详情 API

**templates/** - Jinja2 模板

- `base.html`：基础布局
- `home.html`：招聘流程信息图（核心页面）
- `index.html`：工具画廊

**static/css/** - 样式文件

- `base.css`：基础样式
- `common.css`：共享样式
- `home.css`：主页样式

### 技术栈

**命令行**：

- `typer[all]`：CLI 框架
- `rich`：终端美化输出

**数据处理**：

- `pydantic`：数据模型和验证
- `pyyaml`：YAML 解析

**Web 服务**：

- `fastapi`：Web 框架
- `uvicorn`：ASGI 服务器
- `jinja2`：模板引擎

**前端**：

- `alpine.js`：轻量级前端框架
- `tailwindcss`：样式框架

---

## 👨‍💻 开发指南

### 环境设置

```bash
# 克隆仓库
git clone https://github.com/yourusername/recruiter-navi.git
cd recruiter-navi

# 安装依赖
pip install -e ".[dev]"

# 或使用 hatch
pip install hatch
hatch env create
```

### 运行测试

```bash
# 使用 pytest
pytest tests/

# 使用 hatch
hatch run test
```

### 代码格式化

```bash
# 使用 ruff
ruff format .
ruff check .

# 使用 hatch
hatch run lint:fmt
hatch run lint:check
```

### 启动开发服务器

```bash
# 使用 uvicorn
uvicorn recruiter_navigator.web.app:create_app --factory --reload --port 8080

# 使用 hatch
hatch run serve
```

### 添加新工具

1. 编辑 `src/recruiter_navigator/data/registry.yaml`
2. 添加工具配置（参考现有工具格式）
3. 运行测试验证
4. 提交代码

---

## 📁 项目结构

```
recruiter-navi/
├── src/recruiter_navigator/
│   ├── __init__.py              # 包初始化
│   ├── cli/                     # 命令行接口
│   │   ├── __init__.py
│   │   ├── app.py               # 主命令注册
│   │   ├── init.py              # recruiter init
│   │   ├── list.py              # recruiter list
│   │   ├── use.py               # recruiter use
│   │   └── web.py               # recruiter web
│   ├── core/                    # 核心逻辑
│   │   ├── __init__.py
│   │   ├── models.py            # Pydantic 数据模型
│   │   ├── registry.py          # 注册表加载器
│   │   └── launcher.py          # 工具启动逻辑
│   ├── data/
│   │   ├── __init__.py
│   │   └── registry.yaml        # 内置工具注册表（80KB）
│   └── web/                     # Web 界面
│       ├── __init__.py
│       ├── app.py               # FastAPI 应用
│       ├── routes/              # 路由模块
│       │   ├── __init__.py
│       │   ├── home.py          # 招聘流程信息图
│       │   ├── index.py         # 工具画廊
│       │   └── detail.py        # 工具详情 API
│       ├── templates/           # Jinja2 模板
│       │   ├── base.html        # 基础布局
│       │   ├── home.html        # 主页（60KB）
│       │   └── index.html       # 工具列表（22KB）
│       └── static/              # 静态资源
│           └── css/
│               ├── base.css     # 基础样式
│               ├── common.css   # 共享样式
│               └── home.css     # 主页样式
├── tests/                       # 测试代码
│   ├── test_registry.py         # 注册表测试
│   └── test_web.py              # Web API 测试
├── docs/                        # 文档
│   ├── design_spec.md           # 设计规范
│   ├── guide-tools.md           # 工具指南
│   └── prd01.md                 # 产品需求文档
├── pyproject.toml               # 项目配置
└── README.md                    # 项目说明
```

---

## 📊 统计数据

- **总工具数**：47
- **分类分布**：
  - 人才搜索：13
  - 简历处理：12
  - 候选人触达：4
  - 数据管理：8
  - 基础设施：10
- **代码行数**：~3000 行（不含配置）
- **配置文件**：registry.yaml（80KB）
- **Web 模板**：home.html（60KB）+ index.html（22KB）

---

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 贡献方式

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范

- 使用 `ruff` 格式化代码
- 编写单元测试
- 更新相关文档
- 遵循 PEP 8 规范

---

## 📝 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

感谢所有招聘工具的开发者，为本项目提供了丰富的工具生态。



---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star！⭐**

Made with ❤️ by chandler

</div>