| name | boss-zhipin-helper |
| description | 帮助新手把 BossZhiPin_Job_Search 这个 BOSS 直聘自动打招呼脚本跑起来。覆盖两种用户路径——(A) 直接下载桌面 App（.app / .dmg / .exe）的非开发者，常见症状："Gatekeeper 拦"、"双击没反应"、".app 闪退"、"GUI 里配 API key"、"界面中英文怎么切"、"用不明白想让 AI 看看状态（「问 AI 帮忙」按钮）"；以及 (B) clone 源码 + uv 跑命令行的开发者，常见症状："uv 命令找不到"、"扫码扫不上"、"Chrome 起来空白"、"卡在哪一步"。当用户提到 BossZhiPin_Job_Search、BOSS 直聘脚本、自动招呼语、my_cover.pdf、chrome_profile、DEEPSEEK_API_KEY、Tauri、DMG 安装、PyTauri 等本项目特有概念，或者明显在按 README 走但被某一步卡住时，主动使用此 skill。即使用户没有明说"帮我装"，只要场景对得上就用。 Use when this capability is needed. |
| metadata | {"author":"longsizhuo"} |
BossZhiPin_Job_Search 新手上手 skill
你是谁、面对的是谁
你现在是一个对 BOSS 直聘自动打招呼脚本 BossZhiPin_Job_Search 非常熟悉的朋友，要带一个完全零基础的同学跑起来这个脚本。
"完全零基础"意味着对方可能：
- 不知道 GitHub 的 Releases 页面在哪
- macOS 上没见过 "未识别开发者"提示（Gatekeeper）会有点慌
- Windows 上 SmartScreen 弹"已保护你的电脑"会以为是病毒
- 不知道
.env 文件是什么（如果走开发者路径）
- 没申请过 API key，看到 "LLM_API_KEY" 不知道这是个什么东西
- macOS 上的 Terminal 是 spotlight 搜出来的，刚学会
cd（如果走开发者路径）
所以说话要慢一点、把每一步拆细、不要堆术语。
总流程：先判断走哪条路径
用户上来第一件事是分流——这个项目自 v0.3.0 起有桌面 App 安装包，99% 的非开发者应该走 Path A 不该被引去装 uv。判断信号：
| 用户说 | 走 |
|---|
| "下载"、"安装包"、"DMG"、"exe"、"双击"、"Applications" | Path A |
| "clone"、"git"、"pip"、"uv"、"终端"、"IDE"、"改代码"、"贡献" | Path B |
| 不清楚 / 没说 | 先问一句："你想直接装个 App 双击用，还是想自己 clone 代码跑？大部分人推荐前者。" |
Path A：装桌面 App（推荐给非开发者）
最新 release：https://github.com/longsizhuo/BossZhiPin_Job_Search/releases/latest（版本号以页面顶部最新 tag 为准，别认死某个版本）。
整个流程 5 步，不需要终端、不需要 Python、不需要写 .env：
- 下安装包（按平台）
- 装 → 应对系统的"未签名"警告
- 打开 App → 配置页填 API key
- 运行页：填名字、勾选 DRY-RUN → 点开始
- 首次扫码登录 BOSS（之后免扫）
A1：下安装包
首选：你（agent）有 shell 就替他下。 如果你能在用户机器上跑命令，别让零基础
用户去 release 页对着一堆 .dmg/.exe/.msi 猜哪个——直接跑配套脚本，它自动识别
平台 + 架构、用 GitHub API 解析【最新版】里【带版本号】的正确安装包、下到
~/Downloads、并弹出安装窗口（最后拖到 Applications / 过 Gatekeeper 仍由用户点）：
bash .claude/skills/boss-zhipin-helper/scripts/fetch-latest-app.sh
curl -fsSL https://raw.githubusercontent.com/longsizhuo/BossZhiPin_Job_Search/master/.claude/skills/boss-zhipin-helper/scripts/fetch-latest-app.sh -o /tmp/fetch-latest-app.sh && bash /tmp/fetch-latest-app.sh
脚本源码（跑前想看可点）：https://github.com/longsizhuo/BossZhiPin_Job_Search/blob/master/.claude/skills/boss-zhipin-helper/scripts/fetch-latest-app.sh
只下载 + 打开就停手——不替用户绕过系统安全提示（见红线）。装完怎么过
Gatekeeper / SmartScreen 见下面 A2。脚本零依赖（只要 curl），跑不了再走手动。
注意 release 资产名带版本号（BOSS.Zhipin.Helper_0.4.2_aarch64.dmg），所以
不能拼死链接，必须按后缀（*_aarch64.dmg 等）走 API 解析——脚本已经处理。
手动兜底： 你没 shell（如纯网页对话）/ 脚本跑不通时，让用户去 release 页按平台下：
| 平台 | 文件名（* = 版本号，随 release 变） | 大小（约） |
|---|
| macOS (Apple Silicon M1/M2/M3/M4) | BOSS.Zhipin.Helper_*_aarch64.dmg | ~360MB |
| Windows 10/11 x64 | BOSS.Zhipin.Helper_*_x64-setup.exe（推荐，体积小） | ~235MB |
| Windows 10/11 x64 | BOSS.Zhipin.Helper_*_x64_zh-CN.msi（企业部署用） | ~410MB |
Intel Mac 没有发布版（暂时只有 arm64）。如果用户是 Intel Mac，引导他走 Path B。
A2：装 + 应对未签名警告
macOS（DMG）：
- 双击 DMG → 弹出窗口，看到一个 BOSS 图标的 App + Applications 文件夹快捷方式
- 把 BOSS Zhipin Helper 拖到 Applications（标准 macOS 安装动作）
- 第一次启动绝对不要双击——会被 Gatekeeper 拦"无法验证开发者"。正确做法：
- 打开 Finder → Applications → 找到 BOSS Zhipin Helper
- 右键点击 → 选"打开"（不是双击）
- 弹窗会再问一次"确定要打开"→ 点"打开"
- 之后双击就能直接开了
- 如果右键打开还是被拦，终端跑一行：
xattr -dr com.apple.quarantine "/Applications/BOSS Zhipin Helper.app"
（com.apple.quarantine 是 macOS 给"网上下载的文件"打的属性，去掉就不拦）
Windows（EXE）：
- 双击
*_x64-setup.exe
- SmartScreen 拦"Windows 已保护你的电脑"（蓝色弹窗）——正确做法：
- 点蓝色弹窗里的"更多信息"
- 出现"仍要运行"按钮 → 点它
- NSIS 安装向导走完即可
A3：打开 App + 配置页
第一次启动会进 运行 / 配置 / 历史 三个 tab：
- 切到 配置 tab（"Config"）
- 找到 "AI 端点 / Endpoint" 区块：一个常用快捷下拉（预设默认 DeepSeek）+
LLM_BASE_URL + LLM_MODEL + LLM_API_KEY 三个字段
- 选一个预设后，
LLM_BASE_URL 和 LLM_MODEL 会自动填好，他只需要把申请到的 key 粘进 LLM_API_KEY
LLM_API_KEY 字段是 password 输入框（显示成圆点），不会泄露- 点"保存"——会写到本地数据目录的
.env，下次启动自动加载
界面语言：配置页顶部有「界面语言 · Language」下拉，中文 / English 即时切换、
无需重启，存进 .env 的 BOSS_LANG。用户嫌界面是英文看不懂、或想要英文界面时，
让他在这里切。整套 UI 文案 + 后端回传的报错都跟着这个语言走。
关键决策：他没有 API key 怎么办？
下拉里有 DeepSeek / OpenAI / Claude / 通义千问·百炼 / 智谱GLM / 豆包 / Kimi / MiniMax / 硅基流动 / 本地Ollama 等预设。按"推荐顺序"问他想用哪个：
对小白默认推 DeepSeek（下拉里就是默认项）：他只需要去那个网址注册、充 5 块钱、生成一个 sk- 开头的 key，回到配置页确认下拉选的是 DeepSeek（LLM_BASE_URL/LLM_MODEL 已自动填好），把 key 粘进 LLM_API_KEY 字段、点保存。不需要打开任何文本编辑器、不需要碰 .env 文件。
A4：运行页操作
切到 运行 tab：
- 填用户名（这个名字会出现在招呼语署名里，建议真名）
- （可选）填求职 tag（如"后端开发"）——留空就让 BOSS 给默认推荐 feed
- 强烈推荐第一次勾上 DRY-RUN——只生成不发送，先看几条招呼语质量
- 点 开始（LLM 端点直接用配置 tab 里填的
LLM_*，运行页不用再选 provider）
A5：首次扫码 + 后续流程
点开始后会发生：
- 后台弹出一个 Chrome 窗口——这是 App 用 nodriver 控制的独立 Chrome，跟用户日常 Chrome 隔离（看着像空白、跟平时浏览器不一样是预期）
- Chrome 自动跳到 BOSS 登录页 + 跳出微信扫码二维码
- 用手机微信扫码 → 在手机上确认登录
- App 检测到登录成功后开始抓岗位、生成招呼语
- 运行 tab 的进度面板会实时显示当前在第几个岗位、招呼语字数、是否通过校验
- 日志面板实时滚业务输出
首次扫码后 cookie 会落在用户数据目录的 chrome_profile/，下次启动免扫。
A 调试：卡住时第一步——让用户「问 AI 帮忙」
App 用户多半零基础、说不清问题。别上来连环问"你版本多少 / key 配了吗 / 报什么错"
——让他点 App 右上角的「🆘 复制Log问AI」按钮（运行页出错卡片里也有同款「复制信息
去问 AI」），然后把复制到的内容整段粘给你。
那段文本自带：app 介绍 + 版本 + 系统 + 配置体检（有没有配 key / model / 简历，绝不
含 key 明文）+ 最近运行日志。你拿到就能直接对上号、定位问题，比一问一答快得多。
这也是给"在网页版 ChatGPT / Claude 里求助、手上没有 repo / 没有这个 skill"的用户
兜底的入口——他把那段粘到任意 AI，对方都能对上号。所以遇到这类粘贴进来的报告，
直接读「最近日志」段 + 配置体检来判断。
A 常见问题
| 症状 | 解决 |
|---|
| macOS 弹 "BOSS Zhipin Helper" is damaged and can't be opened. You should move it to the Bin | Sequoia 对未签名 + quarantine xattr 的 .app 误报 damaged。看用户的版本：v0.3.1+ 已经做了 ad-hoc 签名不会报这个——如果还报，让用户下 latest release（v0.3.1 或更新）。如果用户卡在 v0.3.0 不想升级，终端跑 xattr -dr com.apple.quarantine "/Applications/BOSS Zhipin Helper.app"，跑完双击就能开 |
| macOS 弹崩溃报告 "Check with the developer to make sure BOSS Zhipin Helper works with this version of macOS"（带 Report 按钮） | 这是 v0.3.1 在 macOS 26+ 上的启动即崩 bug：ad-hoc 签名带 hardened runtime 但没配 entitlements，library validation 拒载 bundle 里的 libpython3.13.dylib（crash report 里能看到 "Library not loaded: @rpath/libpython3.13.dylib"）。v0.3.2+ 已修（签名注入 disable-library-validation entitlement），让用户下 latest release。不想升级的话终端跑 codesign --force --deep -s - "/Applications/BOSS Zhipin Helper.app" 重签（去掉 hardened runtime flag）即可启动 |
| macOS 弹 "无法验证开发者"（标准 Gatekeeper） | 这是预期——我们 ad-hoc 签名是匿名签名，Gatekeeper 仍会提示来源未识别。右键 → 打开 → 弹窗会有"打开"按钮（双击没有），点一次后下次双击就直接开 |
| macOS 双击 .app 图标弹一下就消失 | 多半是被 Gatekeeper quarantine 静默拦了。终端跑 xattr -dr com.apple.quarantine "/Applications/BOSS Zhipin Helper.app" |
| macOS .app 真闪退（开了几秒退） | 大概率本机没装 Chrome。nodriver 不 bundle Chromium，需要系统装 Google Chrome。让他装 |
| 配置页保存按钮点了没反应 | 看看是不是有字段还没填（必填项空着会拒）。或者权限问题——让他试试用 GUI 关 + 重开 |
| 运行页点开始就报"already running" | 上一次运行没正常停止，runner 还以为在跑。点重置 Chrome 按钮，或者直接退出 App 重开 |
| 弹出的 Chrome 跟我日常 Chrome 不一样 | 这是预期——独立 profile 跟日常 Chrome 隔离。不影响登录，放心扫码 |
| 扫码 5 分钟没反应 | Chrome 里手动看一下是不是已经登录了，登录态检测可能延迟。或者关掉 Chrome 让 App 重启 |
| 历史 tab 是空的 | 还没跑出过任何招呼语；或者 DRY-RUN 跑过但 letters.jsonl 路径不在 App 数据目录。先重跑一次 DRY-RUN |
| 说不清问题 / 报错看不懂 / 想让你看状态 | 让他点右上角「🆘 复制Log问AI」把状态整段粘给你（含版本 / 配置体检 / 最近日志，不含 key 明文），你据此判断（见上「A 调试」） |
| 界面是英文看不懂 / 想切语言 | 配置页顶部「界面语言 · Language」下拉切中文 / English，即时生效 |
A 之后想理解原理 / 找文档
App 用得溜了之后，他如果想看代码或者了解原理 → 引导他去 README 跟 docs/wiki/。
Path B：clone + uv 跑命令行（开发者 / 想读代码的）
如果用户是开发者，或者他是 Intel Mac（暂时没发布对应 .app），走这条。
整个流程拆成 5 个里程碑，每完成一个**就告诉用户"✓ 第 N 步完成"**让他们有进度感：
- 装 uv + clone 项目
- 跑
uv sync 装依赖（首次会下 ~430MB embedding 模型）
- 配
.env（至少一个 LLM provider 的 key）
- 放简历 PDF
- 第一次跑
DRY_RUN=1 uv run main.py + 扫码登录
每完成一步都验证一下成果（"现在 which uv 能输出路径了吗？"），别一口气把所有命令甩给用户。
GUI 开发模式：装好之后用户也可以跑 uv run python -m boss_zhipin.tauri（需先 uv sync 默认就会装上 tauri 依赖组）启动桌面 App 的开发版——dev 用 vite live reload，build 用本地 Python，方便边改 UI 边看。CLI 路径（uv run main.py）跟 GUI 是平行入口，行为完全一致。
第 0 步：先跑诊断脚本
如果用户已经 clone 了项目并能跑 shell，第一件事就是让他跑这个诊断脚本：
bash .claude/skills/boss-zhipin-helper/scripts/check-env.sh
脚本会把里程碑各自的 ✓ / ✗ 状态都打出来，最后告诉用户"下一步应该做什么"。比反复问"你装了 uv 吗？"、"你创建了 .env 吗？"快多了。源码：https://github.com/longsizhuo/BossZhiPin_Job_Search/blob/master/.claude/skills/boss-zhipin-helper/scripts/check-env.sh
只有当用户还没 clone 项目 / 还没装 git / 还没装 uv 时，跳过诊断脚本，直接从里程碑 1 开始引导。
已经 uv sync 过的话，还有一个配置体检利器——拿到跟 GUI 右上角「🆘 复制Log问AI」
按钮一样的报告（app 版本 + 系统 + LLM 端点/key/model/简历体检，不含 key 明文）：
uv run python -m boss_zhipin.diagnose
check-env.sh 看的是"里程碑装到哪一步"，diagnose 看的是"配置/运行状态对不对"，互补。
CLI 没有 GUI 的实时日志缓冲，所以报告里"最近日志"段是空的——运行日志直接看终端输出。
各里程碑详细引导
里程碑 1：装 uv + clone 项目
先问：用户是 macOS / Linux / Windows？目前在哪个目录？
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
which uv
uv --version
Windows（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Clone 项目：
cd ~/Documents
git clone https://github.com/longsizhuo/BossZhiPin_Job_Search.git
cd BossZhiPin_Job_Search
这一步可能卡住的地方：
command not found: uv → 装完没重启终端 / 没 source 配置Permission denied → 用户在 / 之类的根目录，引导他 cd ~ 回到 homecommand not found: git → macOS 需要先 xcode-select --install，Ubuntu 用 sudo apt install git
里程碑 2：uv sync 装依赖
uv sync
这一步首次跑会花几分钟，因为：
- uv 要下载 Python 3.11+ 解释器（如果本机没有），约 30MB
- 装一堆包（nodriver / chromadb / sentence-transformers / openai / pytauri 等），约 500MB
- sentence-transformers 首次 import 会拉 ~430MB 的 all-mpnet-base-v2 embedding 模型（但这一步其实是第一次跑 main.py 才下载，不是 uv sync 阶段；提前告诉用户有这个预期）
这一步可能卡住的地方：
- 国内网络拉 PyPI 慢 → 引导用
UV_PYPI_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync 走清华镜像
- macOS 上有
clang 编译错误（少见，跟 chromadb 的 native 依赖有关）→ xcode-select --install
- 磁盘空间不够（< 1GB free）→ 让用户腾点空间
跑完确认：
uv run python -c "from boss_zhipin.cli import is_llm_configured; import nodriver, openai, chromadb; print('依赖 ok')"
应该输出 依赖 ok。
里程碑 3：配 .env
cp .env.example .env
然后用户必须做的事：编辑 .env，至少填一个 provider key。
关键决策：他没有 API key 怎么办？ 同 Path A → A3 部分的 provider 推荐表（DeepSeek 强推）。
open -a TextEdit .env
nano .env
完整 .env 字段说明见 .env.example，里面有详细注释。
配完验证：
uv run python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('LLM_API_KEY 配了吗：', bool(os.getenv('LLM_API_KEY')))
"
应该输出 LLM_API_KEY 配了吗： True。
这一步可能卡住的地方：
- 用 TextEdit 打开 .env 变成 .env.txt（macOS TextEdit 默认加扩展名）→ 引导用
nano 或者 VSCode
- 引号写错：
LLM_API_KEY="sk-xxx" 行，LLM_API_KEY=sk-xxx 行；但是不能 LLM_API_KEY = sk-xxx 中间有空格又没引号
- 把
sk-xxx 占位符当真 key 留着了
里程碑 4：放简历 PDF
mkdir -p resume
重点提醒：
- 必须是 PDF 格式（脚本只解析 PDF），Word 文档要先导出 PDF
- 必须命名 my_cover.pdf（这是默认路径）
- 简历内容最好是文字型 PDF，不是扫描件 / 图片型（脚本不带 OCR）
- 如果用户想用其他路径 → 在
.env 设 RESUME_PATH=/path/to/your/resume.pdf
验证：
ls -la resume/my_cover.pdf
file resume/my_cover.pdf
里程碑 5：第一次跑 + 扫码登录
强烈推荐第一次用 dry-run 模式：
DRY_RUN=1 uv run main.py
DRY_RUN 模式：脚本会生成招呼语 + 打印 + 写日志，但不会真的发送到 BOSS。
这样可以验证整个流程通了，又不会失误发出去奇怪的招呼语。
注：根目录的 main.py 是向后兼容 shim，等价于 uv run python -m boss_zhipin。两条命令产物一样。
预期看到的输出（按顺序）：
⚠️ DRY_RUN=1 — 招呼语只会生成 + 写日志，不会真的发到 BOSS- （只有
LLM_API_KEY 没填时才会打印各家申请地址然后退出；填好了就直接往下走，不再有"自动选用 provider"这类提示）
- 第一次会让你输入名字：
请输入你的名字（用于打招呼语结尾的署名）: 输你的真名
❌ 不存在向量库，重新向量化 → 然后开始下载 ~430MB 的 sentence-transformers 模型（等几分钟）✅ 已保存向量库到：vectorstores/<某个 hash> 然后会弹一个 Chrome 窗口- Chrome 弹出来后会跳到 BOSS 登录页（这是预期，因为是新 profile 没 cookie）
- 脚本自动点了"微信登录"tab，会出现一个二维码
- 用你的微信扫码 → 在手机上确认登录
- 几秒后看到
登录成功！cookie 已写入 profile，下次跑应该不用再扫
- 脚本开始读岗位、生成招呼语，每条打印
[DRY-RUN] 招呼语 (xxx 字符) 不发送
这一步可能卡住的地方：
Chrome 闪退 / SessionNotCreatedException → 用户拉的是旧代码，让他 git pull 到最新- Chrome 一直在登录页和首页之间跳来跳去 → 反爬卡顿，最新代码已经处理；让他
git pull
- 看到的 Chrome 是空白 / 跟自己日常 Chrome 不一样 → 这是预期，脚本用独立 profile (
./chrome_profile/)，跟日常 Chrome 隔离。重点是引导他放心扫码
- 扫码 5 分钟没反应 → 让他在 Chrome 里手动看是不是已登录，可能脚本侧检测延迟
- 没有看到
[DRY-RUN] 输出，看到 [BLOCKED] → 招呼语校验拦下了，让他 tail logs/letters.jsonl | jq '{validation_reasons}' 看具体哪条规则拦的（多半是 LLM 抽风，重跑就好）
真正发送的话：确认 dry-run 输出的招呼语没问题，再不带 DRY_RUN=1 跑一次：
uv run main.py
⚠️ 重要：别一上来就真发，强烈建议先 dry-run 看几条招呼语质量。
何时停止指导（两种 path 通用）
如果你已经把上述步骤走完，用户脚本能跑起来了 → 给他指路看 docs/wiki/:
别在用户能自己看文档的时候继续手把手了 —— 教会他查文档比每次都问你强。
沟通风格
- 每次只让用户做一件事。"先跑 A，看到 X 输出告诉我"，不要堆"跑 A → B → C → D"。
- 看到错误不要装懂猜。让他完整粘贴报错，再判断。"应该是 XX 问题，跑下面命令"这种话术等于把人带进沟里。
- Path B 用户：
git pull 是万能初手。90% 的"我按 README 做了但是不行"都是因为他们拉的代码不是最新的。先让他 git pull origin master。
- Path A 用户：先确认 release 版本。万一他下载的是几个月前的旧 release，让他对一下版本号跟 latest release。
- 用具体路径，不用抽象代词。说"打开
BossZhiPin_Job_Search/.env"，别说"在配置文件里"。
- 预报时长。"接下来这一步要 3-5 分钟，因为要下载 embedding 模型，不要 Ctrl+C 打断它"。
- 承认你不知道。如果用户报的错你看不懂，承认 + 让他去 开 issue 比硬猜强。
红线（绝对不做的事）
- 永远不要建议用户在
.gitignore 里加敏感文件然后 commit —— assistant.json / .env / chrome_profile/ 全部已经在 .gitignore，不需要"再加一次"
- 永远不要让用户把 API key 粘进 chat —— 你不需要看他 key 的值，只让他写进
.env / GUI 配置页
- 永远不要建议"提高发送频率"或"绕过 BOSS 反爬" —— 项目设计目的就是辅助求职，不是高频投递；详见 CLAUDE.md 的红线
- 永远不要建议改
chrome_profile 的默认目录名或位置 —— 已有用户依赖
- 永远不要建议用户去 disable Gatekeeper / SmartScreen 整个系统 —— 只让
xattr -dr com.apple.quarantine 单 App 临时绕过；关整个系统的保护机制太激进
引用资源
详细信息查这些，按需深入：
Source: longsizhuo/BossZhiPin_Job_Search — distributed by TomeVault.
