🐱 JobHunter Cat · 找工作喵

A desktop AI agent that searches, evaluates and applies for jobs — then learns from the results.

一只住在你桌面上的 AI 求职 Agent。

Not just auto-apply. A personal job-search agent that remembers what worked.

不只是自动投递，而是会记住什么对你有效的个人求职 Agent。

🇨🇳 中文（当前）· 🇬🇧 English

简历 → 求职策略 → 搜索岗位 → AI 匹配 → 自动投递 → HR 监控 → 结果分析 → 下一轮策略优化

---

⚡ Quick Start · 5 分钟跑起来

只想先跑起来？看这一节就够。想了解它为什么这么设计 → 跳过，从下一节读起。

环境

项	要求
系统	Windows 10/11
Python	3.10–3.13（必须带 tkinter）
Node.js	20+
浏览器	Chrome（需手动登录 BOSS 直聘）
LLM	任意 OpenAI 兼容端点（base_url / model / api_key）

1. 克隆

git clone https://github.com/hlan98/JobHunterCat.git jobhuntercat
cd jobhuntercat

2. 安装依赖

python -m pip install -r requirements.txt   # 用 python -m pip，避免 pip 不在 PATH
cd desktop && npm install && cd ..          # Electron 桌宠依赖（装在 desktop/ 下）

若这一步失败（git clone 超时 / npm 或 pip 拉不动），说明当前网络访问
GitHub、npm registry 或 PyPI 受限 —— 请改用你所在网络可访问的代理或镜像源，再重试。

3. 配置

mkdir run
cp memory/templates/config.example.json run/config.json

编辑 run/config.json，至少填三项：

• llm —— API 端点、模型名、密钥
• target_city —— 投递城市（支持 63 个，见 支持城市列表）
• resume_send_name —— 你在 BOSS 上已上传的附件简历文件名

4. 登录 BOSS

用 Chrome 打开 BOSS 直聘，手动登录。

5. 启动

双击 desktop\启动找工作喵.bat，或在 desktop/ 下执行 npm start。

⚠️ 这是真实求职环境。 Agent 会真的发送打招呼、简历和回复，不是模拟。
详细风险说明见下一节。

---

想了解它为什么这么设计？继续往下看 ↓

---

⚠️ 先说清楚：它会真的给 HR 发消息

这不是演示程序。打招呼、发简历、回复都是真实动作，发出去就收不回来。

但它只在两种情况下主动开口：HR 要简历（自动发简历）、HR 拒绝（自动回致谢）。
约面试、谈薪资这类需要你判断的对话，它只提醒、不代答 —— 详见「HR 消息监控」。

请务必：

1. 投递前确认简历、关键词、薪资、城市都是你要的

   ⚠️ 本项目没有演练模式，也没有只读试跑 ——
   界面上的「开始投递」点了就是真实投递，没有「先试一下」的选项。

2. 用你自己的账号，自己承担平台规则风险

关于封号：截至 2026-09-24，连续 5 天高强度使用（每天 5 小时以上）未出现封号。
程序内置了控频机制（达标岗位中随机跳过一部分，实测约 26% 的跳过属于此类），
但这不构成任何保证 —— 平台规则随时可能变化，请自行评估并承担风险。

项目不接管账号密码 —— 它接管的是你已经手动登录好的浏览器。

---

🤔 为什么需要它

很多 AI 求职工具解决的问题是：

帮你找到岗位，然后帮你投出去。

找工作喵想解决的是另一个问题：

投完以后发生了什么？

很多自动投递工具会告诉你投了多少，但不一定把这些结果进一步用于下一轮求职决策。

以一次真实使用为例（2026-09-18 ~ 09-24，连续 7 天，数字取自程序自己的动作账本）：

口径说明：上图的 3,135 是动作次数，不是岗位数。同一个岗位在不同关键词、不同轮次下
会被反复扫到，所以次数大于实际岗位数 —— 按「岗位名 + 公司」去重后，跳过涉及的岗位约 985 个。
141 次打招呼 / 14 份简历 / 13 家有回音同样是动作计数，不是岗位数。

这 3,135 次里有 2,980 次是主动跳过（95.1%）：

跳过原因	次数	占比
匹配分不够	1,475	49.5%
控频随机跳过	776	26.0%
薪资不符	391	13.1%
命中排除词（JD / 岗位名 / 标题）	338	11.3%

95% 的扫描最终被筛掉 —— 这说明当前的筛选机制对投递数量做了明显控制。
至于这些筛选是否真的提高了有效投递率（而不是把好岗位也误杀了），
还需要更多真实数据才能判断，这也是本项目正在公开验证的假设之一。

而这些跳过与投递都不是白记的 —— 它们会沉淀成关键词有效性
（下表来自岗位记忆的关键词维度统计，按关键词去重，与上面的动作次数口径不同）：

关键词	扫描	投递
用户运营	52	20
运营经理	70	18
海外运营	64	16
内容运营	27	16
海外社媒运营	43	0

同样一批岗位，用户运营 投出去 20 个，海外社媒运营 扫了 43 个一个没投 ——
下一轮就该考虑把它换掉。这就是「记住什么对你有效」的具体样子。

第二轮时，AI 会发现：

• 哪些关键词扫出来的岗位回复率更高
• 哪些岗位匹配分不低，但实际没什么反馈
• 哪些方向连续多轮没有有效回复

于是下一轮不是简单重复搜索，而是把历史结果当作新的决策依据。

---

🐱 Why JobHunter Cat? · 为什么是找工作喵？

Most job-search automation focuses on one action:
大多数求职自动化只解决一个动作：

Find a job → Apply

找到岗位 → 投出去

JobHunter Cat explores a longer loop:
找工作喵探索的是一个更长的闭环：

Understand → Plan → Search → Match → Apply → Observe → Remember → Adapt

理解 → 规划 → 搜索 → 匹配 → 投递 → 观察 → 记忆 → 调整

The desktop cat is the interface. The Agent does the work.
The Job Memory keeps the context. The Strategy Engine turns past results into future decisions.

桌面猫是交互入口，Agent 在背后干活；求职记忆保留上下文，策略引擎把过去的结果变成下一个决策。

---

🧠 Personal Job Memory · 求职记忆

桌面猫是交互入口，求职记忆才是我们正在重点探索的核心能力。

它会持续记录你的求职过程：简历与职业经历、求职方向、城市与薪资偏好、岗位搜索记录、匹配结果、投递记录、HR 回复、面试邀请、拒绝结果，以及不同关键词的历史表现。

The goal is not simply to remember what happened,
but to use what happened to inform the next decision.

目标不只是"记住发生过什么"，而是用发生过的事去影响下一个决策。

---

🔬 我们正在研究什么

如果 AI 记住一个人的真实求职结果，
它能不能逐渐做出比固定规则更好的求职决策？

这是一个公开的、进行中的实验。

我们不假设"记住历史结果"一定会让求职效果变好 —— 我们希望通过真实使用数据去验证它。

正在探索：

• 求职方向与 HR 回复率之间的关系
• 匹配分数与真实 HR 反馈之间的关系
• 不同关键词的有效性差异
• 哪些岗位特征更容易产生面试机会
• 什么时候该扩大搜索范围，什么时候该调整方向
• 如何避免因为样本不足而过早改变策略

We prefer to document what actually works
rather than present planned features as completed features.

---

✅ 现在能做什么

以下是已经实现的（不把规划当成已完成）：

简历理解

• PDF / DOCX / TXT / Markdown 简历解析（Word 会读表格；图片走本地 OCR）
• 基于 LLM 的职业信息提取：求职方向、城市、薪资偏好
• 校验后才写入：识别结果不像简历时会终止，不污染配置

岗位匹配

• 完整读取 JD
• 规则分 + LLM 语义补分
• 输出匹配分、命中依据、缺失能力
• 14 天去重：已评估岗位直接使用缓存分，不重复消耗 LLM token

投递执行

• 浏览器自动化（DrissionPage 接管 CDP）
• 自动打招呼、投递账本
• 投递前验证登录态，未登录会停下等你扫码
• 提醒你选择在线附件简历，未选完不开始投递
• 请求节奏控制：达标岗位中随机跳过一部分以降低风控风险；失败会回滚状态
• ⚠️ 当前版本没有演练模式：real 参数恒为 True，点「开始投递」即真实发送

HR 消息监控

每轮关键词扫完自动跑一轮监听。只有两种信号会真的发出去，其余一律交给你：

HR 发来	爬爬的动作
要简历	✅ 自动同意 → 选你指定的在线附件简历 → 发送
拒绝	✅ 自动回一句致谢（话术由你配置，每会话只发一次）
约面试	⚠️ 不回复，提醒你接管
普通提问 / 闲聊	⚠️ 不回复，只提醒你去看
平台自动回复模板	⏭️ 不回复（对方并没有真的说话）

没有把握的一律不擅自回复。 面试时间、薪资谈判、反问 HR 这类需要你判断的对话，
它只提醒、不代答 —— 不会替你答应任何事，也不会自己编内容回 HR。

防重复：同一会话的简历只发一次、致谢只发一次。

拟人节奏

不需要你调任何延时参数 —— 每个关键环节的停顿由程序自己生成。

固定间隔的规律性太明显，所以停顿不取均匀随机，而是用偏态分布：
多数间隔偏短，偶发一次长停顿，更接近真人翻页、阅读的节奏。

环节	停顿
读取职位详情页（看 JD 再决定）	1.2~3.0 秒，偏中短（多数岗位快速扫一眼）
翻到下一个职位前	2.56 秒为主，约 6% 概率出现 610 秒长停顿
扫到不合适的岗位	0.5~1.0 秒，略作停顿
聊天监听中的每次点击 / 读取	0.8~4.0 秒，按动作细分多档

共 30+ 处停顿点，覆盖投递链路与聊天监听两条主线。
参数全部内置在程序里，配置文件里没有任何延时项 —— 不需要你调。

求职记忆

• 投递结果与 HR 回复历史
• 搜索 / 投递统计
• 每轮结束自动总结，并按关键词有效性给出调整建议
• 历史结果回灌下一轮方案

桌面 Agent

• 常驻桌面宠物（Electron 透明窗）
• 说人话指挥：「把薪资放宽到 15-25K」「删掉抖音运营这个关键词」
• 看板：进度条、投放明细、分析报告
• 关键动作写账本，全程可观测

---

⚠️ 当前限制

诚实说明当前边界：

限制	说明
只支持 BOSS 直聘	其它平台适配器未实现
一次投递只能一个城市	多城市需分多次跑
需自己保持浏览器登录	登录态过期需手动重新扫码
不做验证码识别	遇验证码会停下等你处理
城市码表 63 个	未覆盖全部地级市；填表外城市会明确报错而非静默换城市
图片简历需额外依赖	缺 rapidocr-onnxruntime 时图片简历不可用，PDF/docx 不受影响
匹配分未经统计校准	分数是启发式的，不等于"真实成功率"
策略优化仍是实验性的	已有 7 天真实数据（1,346 条评估记录 / 141 次打招呼 / 13 家有回音），但样本仍不足以做统计结论
自动化需持续维护	页面结构变化会导致选择器失效

数字口径说明：本文出现的数字来自两个不同的统计口径，不是同一个分母 ——
前文「为什么需要它」的 3,135 是动作账本里的动作次数（跳过 / 打招呼 / 发简历合计）；
这里的 1,346 是岗位记忆里的评估记录条数（同一岗位在不同关键词、不同轮次会各记一条，
按「岗位名 + 公司」去重后是 524 个岗位）。两者不能相除，也不能直接比较。

---

🏗 Architecture

Agent 是核心，桌面猫是交互入口，Job Memory 是长期状态，Browser Automation 是执行能力。

分层与事件协议详见 docs/ARCHITECTURE.md。

---

🗺 Roadmap

不设时间表，只说明正在探索的方向。

Now

• BOSS 工作流稳定性
• Personal Job Memory
• 结果驱动的策略实验
• 测试覆盖率

Next

• 用真实结果校准匹配分
• 职业画像提取
• 更好的策略推荐
• 更健壮的浏览器恢复

Exploring

• 更多求职平台
• 英文界面（英文 README 已提供）
• 社区 skill
• Agent 评估框架

---

🚀 安装与运行

环境要求

项	要求
系统	Windows 10/11
Python	3.10–3.13（必须带 tkinter）
Node.js	20+
浏览器	Chrome（自己启动并手动登录 BOSS 直聘）
LLM	任意 OpenAI 兼容端点

关于 Python 版本：写 3.10–3.13 而不是 3.8+，是因为实测过 ——
3.8/3.9 上部分依赖已不再提供支持；3.13 上本地 OCR（rapidocr-onnxruntime）装不上，
已在 requirements.txt 里加了 python_version < "3.13" 标记，会自动跳过并回落到视觉 LLM，
不影响其余功能。

安装

git clone https://github.com/hlan98/JobHunterCat.git jobhuntercat
cd jobhuntercat

python -m pip install -r requirements.txt   # Python 依赖（推荐 python -m pip 写法）
cd desktop && npm install && cd ..          # 桌面壳依赖（node_modules 装在 desktop/ 下）

若下载依赖失败，说明当前网络访问 GitHub / npm registry / PyPI 受限 ——
请改用你所在网络可访问的代理或镜像源，再重试同一步。这属于网络环境问题，不是项目缺陷。

配置

mkdir run
cp memory/templates/config.example.json run/config.json

编辑 run/config.json，至少填三项：

• llm —— API 端点、模型名、密钥
• target_city —— 投递城市（支持 63 个，见 支持城市列表；城市码定义在 agent/main.py 的 CITY_CODES）
• resume_send_name —— 你在 BOSS 上已上传的附件简历文件名

启动

# 双击（注意：是 desktop\ 下那个 —— node_modules 装在 desktop/）
desktop\启动找工作喵.bat

# 或命令行
cd desktop && npm start

# ⚠️ scripts\启动找工作喵.bat 只是转发入口（它内部会调用 desktop\ 那个），
#    如果你改过目录结构，请以 desktop\ 下的为准。

首次启动前，请先自己打开 Chrome 并登录 BOSS 直聘（程序会接管 9222 调试端口）。

首次运行：猫会拦住你做两件事

这不是可选步骤 —— 没完成就不会开始投递：

1. 验证登录态 —— 未登录会打开登录页停下来等你扫码；运行中丢失也会检测
2. 选择在线附件简历 —— 猫不会自己上传本地 PDF，让你从 BOSS 上已有的附件简历里选一份；没选完就点「开始投递」会直接停止

---

🔧 常见问题（Troubleshooting）

Chrome 连不上 / 9222 端口没开

程序通过 Chrome 调试端口（默认 9222）接管浏览器。

• 确认你是以可远程调试的方式启动的 Chrome，并已手动登录 BOSS 直聘。
• 端口被占用：换端口需同步改 run/config.json 里的调试端口配置。

LLM 连不上

检查 run/config.json 的 llm 段：

• base_url（API Base）是否正确
• api_key 是否填好、是否过期
• model 名是否对得上
• 网络能否直达该端点（部分 Key 需特定 header 或代理）

pip 找不到 / 装不上

不要直接用 pip，改成：

python -m pip install -r requirements.txt

若仍提示找不到 python，先确认 Python 已加入 PATH，或改用完整安装路径。

npm install 失败

• 确认 Node.js >= 20（node -v 自查）。
• 卡在下载 electron / ffmpeg-static 等二进制（国内网络常见）：这是网络环境限制，请换用你所在网络可访问的镜像或代理后重试，与项目无关。
• 失败后先 cd desktop && rm -rf node_modules 再重装，避免半成品缓存。

BOSS 页面元素变化，选择器失效

BOSS 直聘前端会更新，可能导致浏览器自动化选择器失效。

• 先升级到最新版仓库代码。
• 仍不行请提交 Issue，并附上 run/logs/ 下的报错日志。

Agent 启动后不工作 / 不投递

按顺序排查：

1. Chrome 是否已登录 BOSS
2. Chrome 调试端口（9222）是否可用
3. run/config.json 是否填好 llm / target_city / resume_send_name
4. LLM 是否能正常调用（看日志有无 4xx / 5xx）
5. 首次运行是否完成了「验证登录态」和「选择在线附件简历」两步（没完成不会投递）

猫在，但对话框不说话 / 主进程 spawn 失败

这是 Python 桥接没起来。程序会自动探测解释器（顺序：MIAO_PYTHON > 随包 > .venv > PATH），需满足：Python 3.10–3.13 且 tkinter 可用。

python -c "import tkinter"

报错则需重装带 tkinter 的 Python。

---

🧪 测试

python -m unittest discover -s tests -t .

当前：49 项全部通过。

改动 DOM 读取逻辑时，请额外做假 DOM 双版本对照验证
（修复前必须失败、修复后必须全过），否则无法确认修复真的生效。

---

🤝 谁能来贡献

你不需要什么都会。当前最需要这些方向：

方向	可以改进什么
🧠 Agent / LLM	岗位匹配、策略规划、记忆与评估
🌐 Browser Automation	平台适配、稳定性、去重、错误恢复
🖥 Desktop	宠物交互、UI、动画、通知
📊 Data / Research	求职结果分析、匹配分校准、策略优化
🌍 Localization	英文界面与文档、其它求职平台、其它国家与求职流程
🧪 Testing	不同简历、不同行业、不同求职策略的测试

适合新手的入口：补充简历格式支持、改进岗位标题归一化、加新的猫动画、改进报错文案、补充测试覆盖。

---

📚 文档

文档	看什么
docs/CURRENT_STATUS.md	当前能跑什么、模块职责、正在开发什么
docs/ARCHITECTURE.md	分层结构、事件链路、数据流
docs/DECISIONS.md	关键设计决策与取舍（12 条 ADR）
docs/CODE_PROVENANCE.md	各文件代码来源与修改范围
docs/PRIVACY.md	会读什么、写什么、哪些绝不能提交
AGENTS.md	给 AI 编码助手的仓库约定

---

📜 License / 许可

本仓库不同文件适用不同许可证 —— 注意这不是「MIT / PolyForm 任选其一」的双许可模式，
而是按文件边界划分，使用者没有选择权。分三类：

类别	路径	许可处理
① 纯原创	agent/main.py、agent/pet_bridge.py、desktop/、memory/、assets/、scripts/、docs/	PolyForm Noncommercial 1.0.0
② 来源于原项目	examples/	MIT
③ 混合文件	boss/、agent/shared.py、agent/ledger.py、agent/doctor.py、agent/skill_entry.py、tests/	见下方说明

③ 混合文件

这些文件是在原 MIT 代码基础上继续修改形成的混合文件 —— 同一个文件里既有原 MIT 代码，也有后续新增的代码。

为保留原 MIT 代码所享有的许可权利，本项目目前对这些混合文件采取保守处置：整体按 MIT 许可进行分发，不对其追加商业限制。

这是一项项目级的许可处理方式，
并不表示其中每一行代码都可以追溯到上游 MIT 原始版本。

混合文件的代码来源与修改范围已单独进行基线比对，详见 docs/CODE_PROVENANCE.md。

原创部分（PolyForm Noncommercial 1.0.0）

• ✅ 个人使用、学习、研究、自用 —— 免费
• ✅ 非营利机构（学校、慈善、公共研究、政府）—— 免费
• ❌ 商业用途（含公司内部使用、SaaS、二次销售、商业产品集成）—— 需获得授权

商用授权请联系：Leo He

• 邮箱：[email protected]
• QQ：104495956
• GitHub：@hlan98

⚠️ 由于 MIT 部分不可追加限制，本仓库整体不能一概视为"禁止商用" —— 限制只作用于表中标注的原创部分。

许可边界声明见 NOTICE；MIT 全文见 LICENSES/MIT-job-hunter-skill.txt。

语言说明：本仓库另有英文版 README_EN.md；如两版表述不一致，以本中文版为准。
Language: an English version is available at README_EN.md; where the two differ, the Chinese version governs.

⚠️ 以上为事实声明，不构成法律意见。混合文件的授权问题涉及衍生作品认定、
贡献者权利等具体法律问题，如有需要请咨询专业人士。

---

🙏 致谢

• 起源于一个 MIT 许可的 job-hunter-skill 项目；具体代码来源与演变记录见 docs/CODE_PROVENANCE.md
• 桌面壳基于 Electron
• 浏览器自动化基于 DrissionPage

---

免责声明

本项目仅供个人求职使用。使用者需自行承担：

• 因自动化操作导致的平台账号风险
• 向 HR 发出的任何消息的后果
• 所在地区的法律法规合规责任

作者不对使用本工具产生的任何后果负责。