命令行参考
Sweepy 以单条命令 sweepy 的形式安装。输入该命令并按 Enter。需要超出默认行为时再加参数。每个配置文件、每次扫描、每份报告都从这里开始。
sweepy
Alex 每天早上用其中两条命令。先用 --run 以最近保存的配置文件扫描。运行异常时再用 --logs 查看发生了什么。
所有命令都要在 sweepy 文件夹中运行。如果上一步之后关闭了终端，请重新打开并先运行 cd sweepy。
命令参考
不带参数运行 sweepy 会打开向导的搜索启动台。下表按功能对每个参数分组。
在 sweepy 文件夹中运行一次 pip install -e .。下文都使用简写形式，因为该命令会注册它。如果 shell 找不到 sweepy，请重新打开终端，或改用 python swee.py。
扫描与配置文件
| 参数 | 作用 |
|---|---|
--run | 用最近保存的配置文件运行扫描。 |
--profile <path> | 按 YAML 配置文件运行扫描。 |
--setup | 打开搜索启动台，用于搜索和配置文件设置。 |
--non-interactive | 通过参数而非交互提示构建或更新配置文件。需与 --setup 搭配。 |
单次运行覆盖
| 参数 | 作用 |
|---|---|
--no-dedupe | 单次扫描中保留来自不同招聘网站的重复职位。 |
--include-seen | 同时报告此前扫描过的职位。 |
--reset-history | 清除该配置文件已报告的职位记录。 |
文档
| 参数 | 作用 |
|---|---|
--docx <path> | 将 DOCX 文件转换为 PDF，然后退出。 |
--convert <path> | 将受支持的文档转换为 PDF 并保存在源文件旁，然后退出。 |
职位搜索引擎
| 参数 | 作用 |
|---|---|
--list-engines | 列出所有引擎、各引擎读取的招聘网站及其安装状态。 |
--install-engines [names] | 下载全部可选引擎，或仅下载你指定的引擎。 |
--allow-engine-conflicts | 安装与其他已安装引擎版本锁定冲突的引擎，并跳过该锁定。需与 --install-engines 搭配。 |
更新与版本
| 参数 | 作用 |
|---|---|
--update | 拉取最新 Sweepy 代码并重新安装依赖。 |
--check-update | 报告是否存在更新的 Sweepy 版本。 |
--version | 显示引擎版本及其依赖。 |
日志
| 参数 | 作用 |
|---|---|
--debug | 在 logs/ 下开启调试日志。 |
--log-dir <dir> | 更改调试日志文件夹。 |
--logs | 打印最近的调试日志条目。 |
无交互设置取值
添加 --setup 时，这些参数用于填充配置文件。每个取值都需要对应的参数；除非配置文件已提供，--name、--titles、--location 和 --resume 仍为必需。
| 参数 | 作用 |
|---|---|
--sources <names> | 启用这些引擎，以逗号分隔。 |
--jobspy-sites <sites> | 设置 JobSpy 招聘网站，以逗号分隔。 |
--hirehunt-sources <sources> | 设置 HireHunt 来源，以逗号分隔。 |
--jobdrop-sites <sites> | 设置 JobDrop 招聘网站，以逗号分隔。 |
--openroles-companies <slugs> | 设置 OpenRoles 公司标识，以逗号分隔。 |
--apify-actor <actor> | 设置 Apify actor ID。 |
--timeout <seconds> | 设置每个来源的超时时间。 |
--cache-ttl <seconds> | 设置发现缓存的生存时间。 |
--no-cache | 禁用发现缓存。 |
--history-days <days> | 设置已报告职位再次出现前的天数。 |
--no-history | 每次运行都报告全部职位。 |
--job-tracking / --no-job-tracking | 开启或关闭 CSV 的求职跟踪列。 |
--name <name> | 设置配置文件中的姓名。 |
--titles <titles> | 设置目标职位名称，以逗号分隔。 |
--location <location> | 设置目标地点。 |
--resume <path> | 设置简历路径。 |
Sweepy 先处理 --logs、--version、--update、--check-update、--list-engines 和 --install-engines，然后转换文档。随后处理 --setup，最后执行扫描。每条命令只做一件事。
用 --run 运行最近的配置文件
保存一次配置文件，之后用一条短命令扫描。Sweepy 把你最近保存的配置文件记录在 profiles/.last_profile 中并复用。
sweepy --run
该命令按以下顺序确定配置文件：
profiles/.last_profile中的路径。profiles/中最新的配置文件。- 依次为
profiles/custom_profile.yaml、profiles/paralegal_nyc.yaml、config.sample.yaml。
以上都不存在时，Sweepy 报错并提示你使用 --setup。
用 --setup 构建配置文件
向导会打开搜索启动台，并为你写入 YAML 配置文件。
sweepy --setup
| 启动台板块 | 作用 |
|---|---|
| Launch Sweep | 用你打开的配置文件运行扫描。在打开配置文件之前，状态行会一直提示。 |
| Load Profile | 让你选择已保存的配置文件，用于下次扫描。 |
| Sweepy's Toolbox | 打开下方列出的工具箱条目。 |
| Build Profile | 用通俗问题收集信息，然后保存新的配置文件。 |
| Sweep Settings | 更改关键词权重、卡片上限、报告样式、历史记录行为以及 CSV 中的求职跟踪列。 |
| Exit Sweepy | 保存更改并返回 shell。 |
Sweepy 工具箱包含其余操作：
| 工具箱条目 | 作用 |
|---|---|
| Edit an existing profile | 从 profiles/ 加载配置文件并允许修改，包括求职跟踪列的开关。 |
| Manage job engines | 启用或停用引擎并编辑其设置。 |
| Download job engines | 确认后安装可选引擎。 |
| Add or edit aggregators | 切换职位源并管理自定义聚合器。 |
| Toggle debug logging | 切换配置文件的 debug 值。 |
| Show help | 打印向导的使用说明。 |
| Show recent logs | 打印最新的调试日志条目。 |
| Convert a document to PDF (bonus) | 转换 DOCX、DOC、TXT、MD 或 PDF 文件，然后返回工具箱。 |
| Update Sweepy | 拉取最新代码并重新安装依赖。 |
| Exit | 从工具箱关闭向导。 |
随时可以重新运行向导来新建或编辑配置文件。它从不删除旧配置文件。设置 Sweepy 页面逐步讲解每个问题。
将文档转换为 PDF（附加功能）
即使没有配置文件，Sweepy 工具箱也能转换文档。选择 Convert a document to PDF (bonus)，然后向 Sweepy 提供路径。
| 输入 | Sweepy 的处理 |
|---|---|
.docx | 用 python-docx 和 reportlab 重建干净文本，必要时回退到 Microsoft Word。 |
.doc | 通过 Microsoft Word 渲染，需要 docx2pdf 包。 |
.txt, .md | 按标题和项目符号渲染文本。 |
.pdf | 原样传递文件，或复制到你指定的输出路径。 |
路径无效时 Sweepy 打印警告并重新打开提示。输入有误则返回向导。
直接跳转到某个配置文件
加上 --profile 可跳过启动台，直接打开某个配置文件进行编辑：
sweepy --setup --profile profiles/paralegal_nyc.yaml
向导会用该文件的当前值填充复核界面。
无需交互提示构建配置文件
需要在每台机器上使用相同设置时，可脚本化生成配置文件。加上 --setup --non-interactive，并把每个取值作为参数传入：
sweepy --setup --non-interactive `
--name "Alex Rivera" `
--titles "Technical Writer,UX Writer" `
--location "New York, NY" `
--resume C:\Users\Alex\sweepy\resume.pdf `
--sources jobspy,openroles `
--openroles-companies figma,stripe,notion `
--timeout 120 --no-cache
写入文件前，Sweepy 会校验每个已启用的引擎。缺少取值（例如 OpenRoles 公司标识）时，它会打印 Error: 并以代码 1 退出。不指定 --profile 时，Sweepy 用你的姓名和第一个职位名称生成文件名，因此 Alex 的配置文件保存为 profiles/alex_rivera_technical_writer.yaml。要改为更新已有文件，请加上 --profile <path>。
Sweepy 更新
用以下命令拉取最新代码并重新安装依赖：
sweepy --update
Sweepy 获取 origin 远程仓库，快进当前分支，并运行 python -m pip install -r requirements.txt。当已跟踪文件存在未提交更改时，它拒绝执行，因此绝不会丢弃本地修改。若只想确认是否有更新，请使用只读检查：
sweepy --check-update
Sweepy 工具箱中的 Update Sweepy 执行同样的更新。
管理职位搜索引擎
列出所有引擎、各引擎读取的招聘网站及其安装状态：
sweepy --list-engines
下载可选引擎：
sweepy --install-engines all
在 JobSpy 持有冲突锁定的情况下，all 集合会跳过 JobDrop。用 --allow-engine-conflicts 单独安装 JobDrop：
sweepy --install-engines jobdrop --allow-engine-conflicts
安装引擎后它仍处于关闭状态。请在配置文件的 sources.enabled 中添加它，或在无交互设置时传入 --sources。安装失败时该命令以代码 1 退出。可选引擎 介绍每个引擎。
用 --profile 运行扫描
为每个城市或职位类型各保留一个配置文件，然后用 --profile 指向所需的那一个。其余工作由 Sweepy 完成。
sweepy --profile profiles/paralegal_nyc.yaml
请换成你自己的文件名。若希望 Sweepy 复用你最近保存的配置文件，请使用 --run。
为每个城市或职位类型保存一个配置文件。只需更换文件名即可在搜索之间切换。
覆盖单次运行
--run 和 --profile 接受三个覆盖项。每项只作用于该条命令，不改动配置文件。
sweepy --run --no-dedupe
sweepy --run --include-seen
sweepy --run --reset-history
两个招聘网站发布同一职位时，--no-dedupe 会保留每个网站的条目。扫描只报告新职位，配置文件中的 history.retention_days 默认把窗口设为四天。--include-seen 也会报告被隐藏的职位。单独运行 --reset-history 会清除该历史并直接退出，不执行扫描。
扫描过程中发生了什么
每次运行都按相同顺序执行同样的五个阶段。
| 阶段 | 发生的事情 |
|---|---|
| 1. 配置文件加载 | 读取 YAML 文件并检查设置。 |
| 2. 发现职位 | 在所有已启用平台上运行抓取器并收集职位。 |
| 3. 验证链接 | 移除失效链接并捕获 soft 404 重定向。检查无法验证的职位保留在本轮运行中。 |
| 4. 评分 | 解析 PDF 或 DOCX 简历以计算词条重合，并为每个职位撰写一条 Application Tip。 |
| 5. 生成报告 | 生成带日期标记的 PDF、CSV 和 JSON 文件。在导出格式中加入 png 可获得页面图片。 |
运行时终端以 [1/5] 至 [5/5] 打印各阶段。运行第一次扫描 展示完整输出。
用 --docx 将 DOCX 转换为 PDF
把一个 Word 文件传给 --docx。Sweepy 转换它、保存 PDF 并退出。
sweepy --docx path/to/resume.docx
Sweepy 随后提示输入 PDF 的目标位置。
Where should the PDF go? (leave blank to save next to the DOCX):
留空直接按 Enter，PDF 会以相同的主文件名保存在 DOCX 旁。也可改为输入完整路径，保存到其他位置。无论哪种方式，Sweepy 都会打印 PDF saved: 和最终位置。
Sweepy 先用 DOCX 文本重建 PDF。如果你的机器装有 Microsoft Word，Sweepy 会回退到 docx2pdf，使视觉还原更接近原稿。
用 --convert 转换任意文档
--convert 不提示输入，直接把 PDF 写在原文件旁。它支持 .docx、.doc、.txt、.md 或 .pdf 文件。
sweepy --convert path/to/resume.docx
PDF saved: C:\Users\Alex\sweepy\resume.pdf
输出沿用源文件名并替换扩展名，因此同一文件夹中的 notes.md 变为 notes.pdf。.pdf 源文件已在原处，Sweepy 会提示 This file is already a PDF: 并保持文件不变。
| 输入 | Sweepy 的处理 |
|---|---|
.docx | 用 python-docx 和 reportlab 重建干净文本，必要时回退到 Microsoft Word。 |
.doc | 通过 Microsoft Word 渲染，需要 docx2pdf 包。 |
.txt, .md | 按标题和项目符号渲染文本。 |
.pdf | 保持文件不变并报告其路径。 |
文件缺失或不受支持时会打印 Error: 并以代码 1 退出。因此该命令可安全用于脚本和定时任务。
PDF 生成后，把配置文件中的 resume.path 指向它，然后运行扫描。
用 --version 检查版本
用该命令确认引擎及其库已正确安装。
sweepy --version
Sweepy v3.0.0
Python 3.13.1 | pymupdf 1.28.2 | reportlab 5.0.1
Ready to sweep.
如果 pymupdf 或 reportlab 显示 MISSING，请重新安装依赖。安装 介绍该步骤。
开启调试日志
调试日志逐步记录引擎的操作。可通过参数、配置文件设置或环境变量开启。
| 方式 | 设置位置 | 持续时间 |
|---|---|---|
--debug 参数 | 加入终端命令。 | 仅该次运行有效。 |
debug: true | 加入 YAML 配置文件。 | 每次运行都生效，直到你移除。 |
SWEEPY_DEBUG=1 | 设为环境变量。 | 每次运行都生效，直到你关闭终端。 |
在任何扫描命令中加入该参数：
sweepy --debug --profile profiles/paralegal_nyc.yaml
或在配置文件中永久开启日志：
# Write a rotating debug log under logs/ on every run.
debug: true
或改为设置环境变量：
$env:SWEEPY_DEBUG = "1"
sweepy --profile profiles/paralegal_nyc.yaml
在 macOS 或 Linux 上，把第一行换成 export SWEEPY_DEBUG=1。
Sweepy 将日志写入应用文件夹内的 logs/。用 --log-dir 改写到其他位置：
sweepy --debug --log-dir C:\Users\Alex\sweepy-logs --profile profiles/paralegal_nyc.yaml
若要不必打开文件就读取最近条目，请运行：
sweepy --logs
在存在调试日志之前，--logs 命令会打印 No debug logs found. Run Sweepy with --debug to enable logging.。
定时每日运行
招聘团队整周都在发布新职位。每天早晨运行同一命令，你就能尽早捕获这些职位。
sweepy --profile profiles/paralegal_nyc.yaml
发现新职位的运行会写出报告文件。Sweepy 把配置文件、日期和时间写进每个报告文件名，例如 paralegal_nyc_2026-10-08-081500.pdf 和 paralegal_nyc_2026-10-08-081500.csv。Sweepy 按协调世界时读取时间，因此时间戳可能与本地时钟不同。时间戳避免一次运行覆盖另一次，results 因此保存完整的求职历史。
扫描只报告新职位，Sweepy 默认记住已报告的每个职位四天。某个早晨没有新职位时，该次运行打印 No new postings since your last sweep，且不写报告文件。发现的链接全部失效时也是如此。
在 Windows 上定时运行
- 从开始菜单打开任务计划程序。
- 选择创建基本任务，命名为
Sweepy morning sweep之类的名称。 - 选择每天，然后选择 8:00 AM 之类的开始时间。
- 操作选择启动程序。
- 将程序/脚本设为你的 Python 可执行文件。在 PowerShell 中运行
(Get-Command python).Source可打印该路径。 - 将添加参数设为
swee.py的完整路径加配置文件："C:\Users\Alex\sweepy\swee.py" --profile profiles\paralegal_nyc.yaml。 - 将起始于设为你的
sweepy文件夹。引擎从该文件夹读取profiles并写入results。
在 macOS 和 Linux 上定时运行
- 用
crontab -e打开 crontab。 - 添加一行，按机器时区每天 8:00 AM 运行扫描。
0 8 * * * cd /path/to/sweepy && python3 swee.py --profile profiles/paralegal_nyc.yaml
cd 部分很关键。引擎相对于启动目录读取 profiles 并写入 results。请使用安装了 Sweepy 依赖的那个 python3。用 python3 -c "import swee" 测试。
定时运行不会打开终端窗口，因此之前会话的 shell 设置不生效。先手动运行一次该命令，确认可用后再设置定时。