ai-job-search 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

ai-job-search 是一个基于 Claude Code 的本地求职申请工作流框架，使用者可以在自己的机器上完成职位抓取、职位匹配评估、简历定制、求职信撰写、面试准备和结果跟踪。项目主要使用 Python，并通过 Bun 运行部分职位搜索命令行工具。

根据仓库资料，项目当前默认分支为 master，许可证为 MIT，GitHub 页面显示 Star 数为 67356、Fork 数为 21355。README 将其定位为“运行在你自己机器上的求职搜索”，但个人资料会写入受版本控制的文件，因此仓库可见性和个人信息保护是部署前必须处理的问题。

定位与目标用户

这个项目适合希望把重复性求职工作组织成可复用流程的个人求职者。它不是独立的招聘网站，也不是由服务端托管全部资料的 SaaS 产品，而是把 Claude Code 作为命令执行和文本处理入口，将个人资料、职位信息与申请产物放在本地项目目录中管理。

README 明确说明，核心工作流中的个人画像、匹配评估以及“起草—审阅”式申请流程不受语言和国家限制；职位门户搜索技能则面向丹麦市场，资料中提到 Jobindex、Jobnet 和 Akademikernes Jobbank 等站点。迁移到其他国家时，重点是替换职位门户搜索技能，而不是重写整个申请流程。

“An AI-powered job application framework built on Claude Code. Fork it, fill in your profile, and let Claude evaluate job postings, tailor your CV, write cover letters, and prepare you for interviews.”
来源：README

核心功能

项目通过六个斜杠命令把求职过程拆分为连续步骤：/setup 建立个人资料，/scrape 搜索职位，/rank 对职位进行筛选，/apply 生成针对性的申请材料，/interview 准备面试，/outcome 记录结果。每个阶段都围绕结构化输入和文件产物展开，适合反复执行并保留历史记录。

个人资料初始化：/setup

/setup 用于从空项目建立求职者画像。README 指出，姓名、联系方式、工作经历和薪资期望等个人数据会被写入受 Git 跟踪的文件；因此该命令的输出不仅影响后续文本生成，也决定了仓库中哪些内容属于敏感个人信息。

触发条件是完成仓库准备并在 Claude Code 中执行该命令。输入是使用者提供的个人职业资料，输出是供职位评估、简历定制和求职信撰写使用的项目内资料；资料没有列出具体文件名、字段名或完整示例，具体格式应以当前版本 README 和项目文件为准。

职位搜索与抓取：/scrape

/scrape 负责从配置的职位门户发现新职位。仓库资料明确提到其内置搜索技能面向丹麦市场，并覆盖 Jobindex、Jobnet、Akademikernes Jobbank 等站点；资料没有提供抓取频率、并发参数、分页规则或站点访问限制，因此不能据此推断运行规模。

其输入通常来自职位搜索条件和门户技能，输出是后续排序与申请流程可使用的职位数据。由于职位门户技能位于 .agents/skills/*/cli/ 相关目录中，安装脚本会发现这些 CLI，而不是依赖一份固定的门户列表；这是 README 对安装器行为的明确说明。

职位排序：/rank

/rank 将已发现的职位按照个人背景和职位要求进行优先级筛选。README 将结构化评估标准列为项目编码的职业指导实践之一，但没有公开完整评分公式、权重、阈值或输出模式，因此不应把它解释为具有固定数学评分保证的排名系统。

该阶段的输入是职位描述和个人资料，输出是供申请阶段使用的候选职位集合或排序结果。实际排序依据取决于当前仓库中的提示词、技能文件和个人资料内容，修改这些文件可能改变评估结果。

申请材料生成：/apply

/apply 的职责是针对具体职位生成定制化简历和求职信。README 特别提到“起草—审阅”申请管线、面向未来的求职信框架，以及可选的薪资基准参考；简历通常需要通过 LaTeX 编译为 PDF，求职信使用 xelatex 编译。

输入包括个人资料和职位信息，输出包括定制化 CV、求职信及编译后的文档。pypdf 是可选依赖，用于 ATS 可解析性检查；如果缺少 pypdf，README 还说明 Poppler 的 pdftotext 可作为后备方案，若两者都缺少，则检查会退化为人工视觉关键词审阅。

面试准备：/interview

/interview 用于围绕目标职位准备面试。它建立在前面收集的职位信息、个人经历和申请材料之上，重点是把职位要求与候选人的经历联系起来；资料没有给出固定轮次模板、题库格式或自动评分接口。

因此，使用者应把该命令视为本地准备工作流，而不是面试结果预测器。生成内容仍需要由求职者核对事实，尤其是工作经历、技术能力、项目成果和薪资信息。

结果跟踪：/outcome

/outcome 用于记录职位申请之后的结果，使搜索、申请和反馈形成可追踪闭环。README 将其列为六个核心命令之一，但没有提供具体状态枚举、数据库结构、统计报表或同步服务说明。

这意味着结果数据的可用性取决于项目当前文件组织和使用者的记录习惯。对于需要团队协作、集中审计或跨设备同步的场景，仓库资料没有给出相应的服务端能力说明。

系统架构与关键模块

从公开资料看，项目采用“Claude Code 命令层 + 本地文件资料 + 门户 CLI + 文档编译工具”的组合结构。Claude Code 承担工作流编排和自然语言处理入口，Python 工具负责部分安装或辅助逻辑，Bun 负责职位门户 CLI 的运行，LaTeX 工具链负责将 CV 和求职信编译成文档。

Claude Code 工作流层

Claude Code 是该项目的核心执行入口，六个斜杠命令组成业务流程。命令本身不是独立的 Web API，README 没有公布 HTTP 端口、REST 接口或服务端部署方式，因此运行形态应理解为本地命令行交互。

Python 工具层

仓库中明确出现了 tools/install_portal_clis.py。该脚本会扫描 .agents/skills/*/cli/ 下的职位门户 CLI，并在每个 CLI 目录中执行 bun install；安装器使用发现机制，而不是只处理预先写死的门户名称。

Bun 与门户 CLI 层

Bun 是职位搜索 CLI 的运行工具。安装器会使用 --ignore-scripts，并跳过声明安装期生命周期脚本、trustedDependencies、workspaces，或目录旁存在 bunfig.toml、.npmrc 的 CLI，同时报告跳过原因。README 还指出，linkedin-search 和 freehire-search 没有运行时依赖，可以直接使用 plain Bun 运行。

LaTeX 文档生成层

CV 使用 lualatex 编译，求职信使用 xelatex，两者不能简单地用同一个引擎替代。README 说明，现代 MiKTeX 安装中使用 pdflatex 编译 CV 可能遇到 fontawesome5 字体扩展错误；求职信则依赖 cover.cls 和 fontspec，因此要求 xelatex。

依赖与运行环境

运行项目需要同时准备 Claude Code、Python、Bun 和 LaTeX；其中 pypdf 只用于可选的 ATS 文本解析检查。资料给出的 Python 要求是 3.10+，但没有给出 Claude Code、Bun、LaTeX 发行版或项目自身的具体版本号。

LaTeX 发行版可选 TeX Live、MacTeX、TinyTeX 或 MiKTeX。若使用 TinyTeX 或 BasicTeX 等精简安装，应按照仓库 SETUP.md 中列出的额外包进行补充；资料没有列出这些包的完整名称，因此这里不展开虚构的安装清单。

快速开始

最小流程是：取得代码，安装职位门户 CLI，启动 Claude Code 并执行 /setup。在执行任何会写入个人资料的命令之前，应确认当前仓库不会被公开发布。

安装：克隆项目并安装门户工具

gh repo fork ai-job-search-dev/ai-job-search --clone
cd ai-job-search
python3 tools/install_portal_clis.py

上述命令来自 README 的快速开始部分。Windows 环境下，README 给出的 Python 命令形式是 python tools\install_portal_clis.py。安装器会对发现的门户 CLI 执行依赖安装，并跳过具有指定风险特征的目录；可使用 --dry-run 查看将要安装的内容。

运行：建立个人资料并执行工作流

claude
/setup
/scrape
/rank
/apply
/interview
/outcome

这些斜杠命令对应 README 公开的六阶段工作流。首次运行建议先执行 /setup，完成个人资料后再搜索和筛选职位；申请材料、面试准备与结果记录应在具体职位上下文中执行。代码块中的 claude 表示启动 Claude Code CLI，资料没有提供额外启动参数。

验证：检查工具链和产物

python3 --version
bun --version
lualatex --version
xelatex --version
python3 -c "import pypdf; print(pypdf.__version__)"

前四条命令用于确认本地命令是否可调用，最后一条仅在已安装 pypdf 时执行。项目资料没有规定统一的测试命令、固定输出目录或验收脚本，因此文档是否生成、PDF 是否可提取文本，应结合当前仓库文件和实际命令输出核对。

配置说明

公开资料没有提供 .env.example、端口配置、API 环境变量、完整 config 文件或数据库连接参数。下面的表格只列出资料中明确出现的配置和运行入口；未提供的默认值保持留白说明，不对仓库内部未展示的字段作推断。

个人资料、职位搜索条件和申请内容的确切字段没有出现在所提供资料中。若需要修改职位门户、国家或语言，应先阅读当前仓库的技能文件与 SETUP.md，再按照项目已有结构扩展，而不是自行假定环境变量名称或接口签名。

进阶用法

进阶使用的核心是替换职位门户搜索技能，同时保留个人画像、评估、申请和面试准备的主流程。README 明确指出，职位门户技能面向丹麦市场，但整体模式设计为可换成本地求职网站。

增加或替换职位门户

README 提到可以通过 /add-portal 增加门户，或者从其他 fork 复制门户技能。安装脚本会发现新加入的 .agents/skills/*/cli/ 目录，因此新门户不需要被额外写入安装器的固定清单。

扩展时需要关注安装安全边界：如果新 CLI 声明安装期生命周期脚本、trustedDependencies、workspaces，或带有 bunfig.toml、.npmrc，安装器会跳过并报告。这个行为适合在本地先通过 --dry-run 审阅。

使用其他代理工具

README 的补充说明提到，使用 Codex、Antigravity 或 Gemini CLI 等其他代理工具时，应从 AGENTS.md 开始；门户搜索技能可以在那里直接使用，社区 fork 也存在对完整工作流的适配。资料没有说明这些工具的版本、兼容性矩阵或全部命令差异，因此迁移前应以对应分支和当前文件为准。

处理文档编译依赖

如果 CV 编译失败，应先确认调用的是 lualatex，求职信编译失败则确认 xelatex 和 fontspec 相关依赖存在。README 对精简 LaTeX 发行版的建议是安装 SETUP.md 中列出的额外包，不能用一个未验证的单一包名替代完整环境检查。

可观测性与运维

项目资料显示它是本地 CLI 工作流，而不是带有服务端监控面的常驻应用。README 只明确提供了 GitHub Actions CI 徽章、安装器的跳过报告和 --dry-run 预览能力，没有提供日志格式、指标名称、告警规则、健康检查端点或服务等级目标。

本地运维可以围绕三类结果进行核对：门户 CLI 是否完成安装、Claude Code 命令是否生成预期文件、LaTeX 和 PDF 文本检查是否成功。具体产物目录、日志目录、重试策略与备份方案未在资料中说明，建议以当前仓库的实际文件为准建立个人记录。

安装阶段的检查点

• 使用 python3 tools/install_portal_clis.py --dry-run 预览待安装 CLI。
• 检查被跳过的 CLI 及其原因，尤其关注安装脚本、trustedDependencies、workspaces 和旁路配置文件。
• 对新增门户先在本地测试，再纳入正式求职流程。

文档阶段的检查点

• 确认 CV 使用 lualatex，求职信使用 xelatex。
• 安装 pypdf 后执行 ATS 可解析性检查，或按 README 说明准备 Poppler 的 pdftotext 后备路径。
• 在提交申请前人工核对姓名、联系方式、经历、职位名称和薪资信息。

安全与合规边界

该项目处理职位抓取、个人履历、联系方式、薪资期望和申请材料，属于涉及隐私数据的自动化工作流。所有抓取和申请操作都应限于使用者有权访问的职位门户、个人账户和本地环境；本文不提供绕过登录、验证码、访问控制或网站限制的技巧。

仓库可见性与个人信息

README 明确警告：GitHub 不允许对公开仓库创建私有 fork，而 /setup 会把个人数据写入受跟踪文件。因此，如果仓库用于自己的求职而不是贡献代码，README 建议使用一个私有仓库，并将本项目作为 upstream；资料还指出，更新工作流可以保持一致。

个人资料、联系方式、雇佣历史和薪资期望不应直接发布到公开 fork。提交代码前应检查 Git 状态、差异和历史记录，删除不必要的敏感文件；仓库资料没有提供专门的密钥扫描或个人信息脱敏工具，因此这些检查需要由使用者负责。

第三方服务与授权

Claude Code 需要 Claude Pro、Max 或 Team 订阅，或者 Anthropic API credits；README 说明不存在免费层。发送给模型的职位描述和个人资料应依据所在地区、雇主要求、组织政策及相关服务条款进行判断，资料没有提供法律合规结论、数据驻留承诺或企业隐私协议。

README 还特别声明，该项目是独立开源项目，与 Anthropic 没有关联、背书、赞助或维护关系。项目没有关联加密货币、代币或付费赞助计划，任何声称存在此类项目的内容都不属于仓库授权范围。

许可证与商用条款

仓库提供的是 MIT License。根据仓库中的 LICENSE，许可授予获得软件的人使用、复制、修改、合并、发布、分发、再许可和销售软件副本的权利，但必须保留版权声明和许可证声明。

MIT License 同时以“按现状”提供软件，不提供适销性、特定用途适用性和不侵权保证，作者对软件使用产生的责任作了许可文本中的免责声明。是否满足特定地区的商业、隐私、劳动或招聘法规，应另行评估，不能仅凭 MIT License 得出合规结论。

本项目版权信息为 Copyright (c) 2026 Mads Lorentzen。再发布或制作衍生版本时，应保留许可证要求的版权和许可文本；具体分发方式与第三方依赖的额外条款应以仓库 LICENSE 及各依赖自身许可为准。

局限性与已知限制

项目的公开资料对工作流和安装方式说明较多，但没有提供固定版本矩阵、性能基准、并发能力、SLA、API 文档或统一测试验收标准。任何关于处理速度、职位数量、模型准确率或申请成功率的结论，均不能从现有资料推出。

• 职位门户技能针对丹麦市场，其他国家需要替换或新增本地门户技能。
• 职位抓取的频率、并发限制、分页行为和站点合规策略未提供。
• 个人资料会进入受 Git 跟踪文件，公开 fork 不适合直接保存真实求职资料。
• LaTeX 编译依赖发行版和额外包，精简安装需要依据 SETUP.md 补包。
• ATS 检查依赖可选的 pypdf，缺少相关工具时会退化为人工视觉关键词审阅。
• 结果跟踪的字段、统计能力、备份和多用户协作机制未在资料中公开。

README 记录了项目作者的个人经历：其在职位被裁撤后使用该框架进行求职，完成 69 份定制化申请、获得 20 次首次面试并最终签署一份合同。这个结果属于作者对个人使用过程的描述，不应解释为项目对其他使用者的效果保证。

适合谁

以下信号表明该项目与使用场景匹配度较高：

• 个人求职者愿意在本地维护自己的职业资料，并能审阅模型生成的申请内容。
• 求职过程包含大量相似但需要逐职位调整的简历、求职信和面试准备任务。
• 已有 Claude Code 使用条件，即 Claude Pro、Max、Team 订阅或 Anthropic API credits。
• 目标职位主要来自丹麦市场，或者团队具备能力根据本地门户改造搜索技能。
• 使用者能够安装 Python、Bun 和 LaTeX，并处理 PDF 编译与文本解析问题。

不适合谁

以下信号表示需要谨慎评估，或应先选择其他工作方式：

• 组织要求个人履历、薪资期望和申请文档不得离开受控系统，但当前方案需要与 Claude Code 工作流结合。
• 团队需要多用户权限、集中审计、服务端日志、统一仪表盘或明确 SLA，而资料没有提供这些能力。
• 目标市场的职位门户需要未授权抓取、绕过验证码或规避访问控制；该项目不应被用于这些场景。
• 使用者只需要人工申请少量职位，却不希望维护本地 CLI、Bun、LaTeX 和个人资料文件。
• 运行环境无法安装 lualatex、xelatex 或必要的字体与 LaTeX 包。

常见问题与排查（FAQ / Troubleshooting）

为什么不建议直接使用公开 fork 保存求职资料

因为 README 明确说明公开 fork 会保持公开，而 /setup 会把个人资料写入受 Git 跟踪的文件。用于个人求职时，应按照 README 的建议使用私有仓库并设置 upstream 关系。

安装器为什么跳过某个门户 CLI

安装器会跳过声明安装期生命周期脚本、trustedDependencies、workspaces，或存在 bunfig.toml、.npmrc 的 CLI。先运行带 --dry-run 的安装命令查看检测结果，并根据报告审阅该 CLI 的包配置。

CV 应该使用哪个 LaTeX 引擎

根据 README，CV 使用 lualatex，求职信使用 xelatex。如果使用 pdflatex 编译 CV，README 已提示现代 MiKTeX 安装可能出现 fontawesome5 字体扩展错误。

缺少 pypdf 是否无法申请

pypdf 是可选依赖，主要用于 /apply 的 ATS 可解析性检查。README 说明 Poppler 的 pdftotext 可以作为后备；如果两者都缺少，检查会降级为视觉关键词审阅，但资料没有说明该检查的详细输出格式。

能否使用其他代理工具

README 提到 Codex、Antigravity 和 Gemini CLI，并建议从 AGENTS.md 开始。其他代理工具的完整兼容性、版本要求和命令差异未提供，应以当前仓库文件和对应社区 fork 的说明为准。

项目有没有 Docker、端口或服务端部署方式

所提供资料没有出现 Docker 配置、服务端端口、HTTP API 或部署清单。官方仓库未提供该信息，建议以最新 README 为准。

项目地址与资源

以下链接均来自仓库资料或其 README 中出现的官方站点，适合用于代码、工具链和安装说明核对。

• ai-job-search GitHub 仓库
• Claude Code 官方页面
• Bun 官方网站
• TeX Live 官方网站
• MacTeX 官方页面
• TinyTeX 官方页面
• MiKTeX 官方网站
• 项目作者 Ko-fi 支持页面
• 项目作者 LinkedIn 页面