Sweepy 开发者参考
Sweepy 是一个小型 Python 项目，引擎结构扁平。本页把每个流水线阶段对应到执行它的模块，便于你确定改动位置。
读者对象
如果你计划修改 Sweepy 代码或新增职位源，请阅读本页。评审者也可用它快速了解拉取请求。本页只涉及内部实现：模块、依赖和 Python 版本。
提示
若只想运行扫描，可跳过本页。请从安装开始。
流水线阶段与模块
swee.py 按顺序执行五个阶段。终端以 [1/5] 至 [5/5] 打印各阶段。
| 阶段 | 模块 | 作用 |
|---|---|---|
| 1. 加载配置文件 | engine/config.py | 加载并校验 YAML 配置文件。同一模块中的向导负责写入配置文件。 |
| 2. 发现职位 | engine/discovery.py | 通过 python-jobspy 查询聚合职位源，并对各平台分类。 |
| 2. 发现职位 | engine/sources/ | 从公开端点获取 Greenhouse、Ashby、Lever、Workable 和 Built In NYC 招聘网站。 |
| 2. 去重 | swee.py | 把聚合器与各源的结果合并为每个职位链接一张卡片。 |
| 3. 验证 URL | engine/validator.py | 用 HTTP HEAD 请求并在必要时回退到 GET 检查每个链接，剔除失效职位。 |
| 4. 简历评分 | engine/scorer.py | 提取职位与简历词条，按任职要求和关键词计算重合度，并标记需要书面应答的职位。 |
| 5. 分配简历轨道 | engine/enrich.py | 选择词条重合度最高的轨道，并赋予对应的徽标颜色。 |
| 5. 丰富卡片 | engine/enrich.py | 生成卡片摘要、薪资行和定制建议文本。 |
| 5. 默认卡片 PDF | engine/report.py | 渲染卡片版式，默认每页六张卡片，并返回页数。 |
| 5. 旧版表格 PDF | engine/pdf_builder.py | 当配置文件设置 report.style: legacy 时渲染表格版式。 |
| 5. 数据导出 | engine/exporter.py | 写出 CSV 和 JSON 文件，并可按需栅格化 PNG 页面图片。 |
| 5. 求职跟踪 | engine/tracking.py | 添加跟踪列，并读取此前的导出文件，使你填写的内容得以延续。 |
engine/session.py 保存有状态模型上下文协议（MCP）流程的卡片存储。它用线程安全的映射保存卡片，索引为每个职位链接的稳定哈希。
改动位置
| 你想改动 | 从何处入手 |
|---|---|
| 某个职位源或其端点 | engine/sources/，以及在 data/sources/ 中的种子列表 |
| 匹配的评分方式 | engine/scorer.py |
| 卡片显示的内容 | engine/enrich.py，然后是 engine/report.py |
| 链接的检查方式 | engine/validator.py |
| 某个命令行参数 | swee.py |
| 某个 MCP 工具 | server.py |
提示
server.py 导入的引擎模块与命令行工具相同。任何引擎改动后都要测试 MCP 路径，因为一处修复会影响两个入口。
模块参考
入口
| 模块 | 用途 |
|---|---|
swee.py | 五阶段流水线的主编排器及 argparse 命令行入口。 |
server.py | 模型上下文协议（stdio）服务器，向 AI 助手提供引擎工具。 |
引擎模块
| 模块 | 用途 |
|---|---|
engine/config.py | 交互式向导以及 YAML 加载与校验。 |
engine/discovery.py | python-jobspy 与确定性源的抓取编排、申请人跟踪系统（ATS）识别以及去重。 |
engine/validator.py | 链接可用性检查，含 soft-404 检测。无法验证的链接保留在本轮运行中。 |
engine/scorer.py | 简历词条提取、百分比匹配、标记以及按轨道评分。 |
engine/enrich.py | 卡片丰富，包括摘要、薪资、轨道分配和定制建议。 |
engine/session.py | 线程安全的卡片存储，为有状态 MCP 流程提供稳定 ID。 |
engine/report.py | 默认卡片版式 PDF。 |
engine/pdf_builder.py | 用于 report.style: legacy 的旧版表格版式 PDF。 |
engine/exporter.py | CSV 与 JSON 导出，以及报告 PDF 的 PNG 栅格化。 |
engine/tracking.py | 跟踪列，以及此前导出文件的延续读取。 |
engine/docx.py | 用 python-docx 和 reportlab 将 DOCX 转换为 PDF，并含 Microsoft Word 回退。 |
engine/documents.py | --convert 与 MCP 转换器的文档分派，涵盖 DOCX、DOC、文本、Markdown 和 PDF。 |
engine/logging.py | logs/ 下可选的调试日志。 |
engine/cache.py | 按查询和引擎集合索引的 SQLite 抓取缓存，生存时间为一小时。 |
engine/circuit_breaker.py | 统计连续源错误，并在冷却期内暂停调用。 |
engine/engine_defaults.py | 共享的默认网站列表与引擎设置，保持无导入以避免循环。 |
engine/engines.py | 可选 hirehunt、openroles、apify 和 jobdrop 引擎的适配器注册表与安装器。 |
engine/history.py | 已报告职位的持久记录。每日扫描只报告新职位。 |
engine/normalize.py | 将引擎原始行规范化为共享职位列。 |
engine/salary.py | 招聘网站未提供结构化薪资时，从职位文本提取薪资。 |
engine/sweep_config.py | 把共享引擎默认值应用到配置文件设置。 |
engine/updater.py | 针对代码检出目录的基于 Git 的更新检查与依赖重装。 |
确定性源
| 模块 | 用途 |
|---|---|
engine/sources/__init__.py | 抓取器导出以及从 data/sources/ 加载种子列表。 |
engine/sources/_common.py | HTTP 标头、标题预筛选和 HTML 转文本的共享辅助函数。 |
engine/sources/greenhouse.py | Greenhouse 招聘网站抓取器。 |
engine/sources/ashby.py | Ashby 招聘网站抓取器。 |
engine/sources/lever.py | Lever 职位抓取器。 |
engine/sources/workable.py | Workable 组件 API 抓取器。 |
engine/sources/builtinnyc.py | Built In NYC 分类抓取器。 |
引擎适配器
| 模块 | 用途 |
|---|---|
engine/adapters/__init__.py | 把每个引擎名称映射到其适配器的注册表。 |
engine/adapters/base.py | ScraperAdapter 基类、共享 User-Agent 标头以及结果结构辅助函数。 |
engine/adapters/jobspy_adapter.py | 面向 LinkedIn、Indeed、Glassdoor 和 ZipRecruiter 的 python-jobspy 聚合适配器。 |
engine/adapters/ats_adapter.py | 覆盖 engine/sources/ 中确定性 ATS 抓取器的适配器。 |
engine/adapters/hirehunt_adapter.py | 可选 hirehunt 引擎适配器。 |
engine/adapters/openroles_adapter.py | 可选 openroles 引擎适配器。 |
engine/adapters/apify_adapter.py | 可选 Apify actor 适配器。 |
engine/adapters/jobdrop_adapter.py | 可选 jobdrop 引擎适配器。 |
数据、脚本与测试
| 路径 | 用途 |
|---|---|
data/sources/*.txt | 招聘网站、公司、组织和分类的种子列表。 |
scripts/make_sample.py | 构建存放在 docs/ 中的示例报告。 |
tests/ | pytest 测试套件，每个领域一个文件：adapters、config、documents、docx、engines、enrich、history、logging 和 report。其余文件覆盖 salary、scorer、server、session、sources、swee、tracking、updater 和 validator。 |
备注
改动 discovery.py、exporter.py 或 pdf_builder.py 时，请新增专用测试文件，并放在 tests/ 中。
依赖
运行时包来自 requirements.txt。下列版本与该文件一致。
| 包 | 版本 | 为 Sweepy 提供的功能 |
|---|---|---|
reportlab | 5.0.1 | 生成带可点击链接的样式化 PDF 报告。 |
pymupdf | 1.28.2 | 从简历 PDF 提取文本并栅格化 PNG 导出。 |
python-docx | 1.2.0 | 读取 .docx 简历，并在没有 Word 的情况下把 DOCX 文本重建为 PDF。 |
requests | 2.32.5 | 访问 ATS 端点并检查每个职位链接是否有响应。 |
beautifulsoup4 | 4.15.0 | 解析 Greenhouse、Lever、Workable 和 Built In NYC 源的 HTML。 |
pyyaml | 6.0.3 | 读写 YAML 配置文件。 |
questionary | 2.1.1 | 驱动向导的交互式问题。 |
prompt-toolkit | 3.0.53 | 驱动向导的交互式文本输入。 |
python-jobspy | 1.2.0 | 无需 API 凭据抓取 LinkedIn、Indeed、Glassdoor 和 ZipRecruiter。 |
pandas | 2.2.3 | 组织职位数据并生成 CSV 与 JSON 导出文件。 |
mcp | 1.30.0 | 运行模型上下文协议服务器。 |
anyio | 4.12.1 | 运行异步 MCP 传输。 |
requirements.txt 还列出一个可选包。需要由 Word 生成 PDF 时，取消对 docx2pdf 的注释。
docx2pdf（0.5.2，可选）在 Windows 上通过 Microsoft Word 将 DOCX 渲染为 PDF。只要机器上存在 Microsoft Word，Sweepy 就会调用它。
备注
mcp 有意保持在 1.x。2.x SDK 只服务 2026-07-28 协议时代。先探测 server/discover、随后回退到 initialize 握手的客户端会收到 -32022 错误。VS Code Copilot 会走这条回退路径。
提示
pandas 有意保持在 2.x。Pandas 3.x 需要 Python 3.11 或更高版本，而 CI 矩阵仍在测试 Python 3.10。
开发包（requirements-dev.txt）
| 包 | 版本 | 作用 |
|---|---|---|
pytest | 9.1.1 | 运行 tests/ 中的测试套件。 |
pytest-cov | 7.1.0 | 报告 swee.py、server.py 和 engine/scorer.py 的覆盖率。 |
ruff | 0.17.0 | 检查代码并排序导入。 |
tomli | 2.2.1 | 为 Python 3.10 的测试运行提供 tomllib。 |
终端
pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q
环境要求与受支持的 Python 版本
| 项目 | 说明 |
|---|---|
| Python 下限 | Sweepy 需要 Python 3.10 或更高版本，所有模块都面向 3.10 语法。 |
| 测试范围 | .github/workflows/ci.yml 中的 CI 工作流在 Ubuntu 上运行 Python 3.10、3.11 和 3.12。 |
| Lint 目标 | pyproject.toml 设置 ruff 的 target-version = "py310"。仅适用于更高版本的写法会导致 lint 作业失败。 |
| 行长度 | Ruff 强制 100 字符行宽上限，并忽略 E501。 |
| CI 步骤 | 该作业安装两个依赖文件，并在 pytest 之前运行 ruff check .。 |
备注
pyproject.toml 声明 requires-python = ">=3.10"，因此 pip 在安装时拒绝更旧的解释器。CI 矩阵和 ruff 目标定义了测试范围。Python 3.13 实际可用，但仍在该范围之外。
Python 3.13
没有预编译 wheel 时，pymupdf 包可能从源码编译。安装依赖前，请先安装 Microsoft C++ Build Tools 并选择 “Desktop development with C++” 工作负载。
仓库结构
仓库结构
swee.py CLI 入口点与扫描编排器
server.py 基于 stdio 的 MCP 服务器
engine/ 流水线模块
engine/sources/ 确定性的 ATS 抓取器
engine/adapters/ 聚合器与可选引擎适配器
data/sources/ 各抓取器的种子列表
profiles/ YAML 搜索配置文件
results/ 生成的 PDF、CSV、JSON 和 PNG 文件
logs/ 可选的调试日志
styles/ 文档的 Vale 样式规则
tests/ pytest 测试套件
在 server.py 中更改工具签名时，请在同一次提交中更新 MCP 工具参考。