boss-zhipin-helper

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。即使用户没有明说"帮我装"，只要场景对得上就用。 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 仍由用户点）： # 已 clone 仓库：直接跑本地脚本 bash .claude/skills/boss-zhipin-helper/scripts/fetch-latest-app.sh # 没有仓库（只装了这个单文件 skill / 纯对话场景）：从 GitHub 拉脚本再跑 # 先下载到本地再执行（不用 curl|bash，跑前可打开看一眼），脚本零依赖只要 curl 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 ★★★ 强推 https://platform.deepseek.com/api_keys 国内能直接访问，单次便宜（¥0.002），充值 5 块够用一阵 OpenAI ★★ https://platform.openai.com/api-keys 需要 VPN，新账号有免费额度，但需要外币卡 Claude ★★ https://console.anthropic.com/settings/keys 中文表达最自然，但价格高 对小白默认推 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，第一件事就是让他跑这个诊断脚本 ： # clone 过仓库的用户本地就有这个脚本（Path B 默认都 clone 了） bash .claude/skills/boss-zhipin-helper/scripts/check-env.sh # 万一手上没有仓库（单文件 skill 场景）：从 GitHub 拉再跑 # curl -fsSL https://raw.githubusercontent.com/longsizhuo/BossZhiPin_Job_Search/master/.claude/skills/boss-zhipin-helper/scripts/check-env.sh -o /tmp/check-env.sh && bash /tmp/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 # 装完之后**重启一下终端**或者跑 source ~/.zshrc（macOS）/ source ~/.bashrc（Linux） # 验证： which uv # 应该输出 ~/.local/bin/uv 之类 uv --version # 应该输出 uv 0.x.x 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 ~ 回到 home command 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 强推）。 # 编辑 .env（macOS） 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 简历放到 resume/ 目录下，命名 my_cover.pdf 重点提醒 ： 必须是 PDF 格式（脚本只解析 PDF），Word 文档要先导出 PDF 必须命名 my_cover.pdf （这是默认路径） 简历内容 最好是文字型 PDF，不是扫描件 / 图片型（脚本不带 OCR） 如果用户想用其他路径 → 在 .env 设 RESUME_PATH=/path/to/your/resume.pdf 验证 ： ls -la resume/my_cover.pdf # 应该看到文件存在且大小 > 0