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

项目速览（TL;DR）

career-ops 是一个在本地人工智能编码命令行（AI coding CLI）中运行的开源求职工作流。它把职位采集、结构化评估、简历定制、申请跟踪、公司研究和流程校验组织为一套可执行的本地工具链，而不是面向海量职位自动投递。

• 仓库元信息：64,664 Star、12,650 Fork；这些数值会随 GitHub 状态变化。
• 主要语言：JavaScript；默认分支：main。
• 资料所示包版本：1.26.0；Node.js 要求为 >=18。
• 浏览器自动化依赖：Playwright 1.62.1，用于访问职位门户与公司招聘页面。
• 许可证：MIT，可用于商业场景，但分发时必须保留版权与许可声明。
• 支持的交互入口包括 Claude Code、Codex、OpenCode、Antigravity CLI、Qwen、Kimi、GitHub Copilot 和 Grok Build CLI；具体支持范围应以仓库最新文档为准。

根据 README，系统对职位执行五个加权维度的 A—F 分块评估，并给出 1.0 至 5.0 的结果；另有独立的 G 区块判断招聘信息可信度，但 G 区块不影响总分。README 明确建议不要申请低于 4.0/5 的职位，最终提交前仍需人工审阅。

定位与目标用户

该项目的定位是“求职决策与执行工作台”，重点在于从大量职位中筛选值得投入时间的少数目标，并围绕目标职位准备材料。它不是招聘网站，也不是托管式软件即服务（SaaS），核心流程运行在用户自己的开发环境或容器中。

“career-ops turns any AI coding CLI into a full job search command center.”

“This is NOT a spray-and-pray tool. career-ops is a filter.”

系统需要用户提供简历、职业经历、可验证成果、职位偏好、能力边界和希望规避的工作条件。README 将这一过程类比为新招聘人员的入职：初始评估质量不会理想，只有持续补充个人上下文，职位判断和简历适配才会逐步贴近真实目标。

其目标用户应具备基本的命令行和 Node.js 使用能力，并愿意检查模型生成的评估与文档。官方仓库未提供纯图形化安装器、托管账号体系或无需本地环境的完整网页版本信息，建议以最新 README 为准。

核心功能

career-ops 的功能不是彼此独立的生成器，而是围绕职位信息形成连续管线。输入可以是职位 URL 或职位描述，处理结果进入评估、材料生成和申请跟踪环节。

职位扫描与内容提取

根据 README，系统能够扫描 Greenhouse、Ashby、Lever 以及公司自己的招聘页面。触发入口包括 scan.mjs、scan-ats-full.mjs 和 browser-extract.mjs，其中 Playwright 负责浏览器访问与页面提取。

扫描环节的输入是职位页面、门户或预设种子，输出会交给后续评估流程。页面兼容列表、反机器人限制、登录态处理方式以及各门户字段映射，官方仓库给出的资料片段未完整说明，建议以最新 README 和脚本实现为准。

结构化职位评估

职位描述与用户职业资料会被交给模型进行推理式匹配，而非只做关键词计数。A—F 区块覆盖五个加权维度并汇总为 1.0 至 5.0 的分数；G 区块单独检查招聘信息可信度，不参与总分计算。

评估可以通过 AI 编码命令行执行，也可由 Gemini、OpenAI 兼容接口、Ollama 或 OpenRouter 相关脚本触发。各评分维度的具体权重、提示词全文和稳定性指标未出现在给定资料中，不能据此推定评分具有统计学或招聘合规意义。

职位定制简历与 PDF

系统以个人事实资料和目标职位描述为输入，生成针对该职位调整过的 ATS（Applicant Tracking System，申请人跟踪系统）简历，并可输出 PDF。相关脚本包括 generate-pdf.mjs、verify-cv-facts.mjs、cv-sync-check.mjs 和 Playwright 视觉测试。

这里的关键约束是“定制表达”而非编造经历。事实校验脚本提供了流程上的检查入口，但官方资料未声明它可以发现全部虚构内容，因此生成材料仍要由本人逐项核对。

申请跟踪与一致性检查

README 将申请记录描述为单一事实来源（single source of truth），并带有完整性检查。tracker.mjs、normalize-statuses.mjs、dedup-tracker.mjs、merge-tracker.mjs、reconcile-pipeline.mjs 和 verify-pipeline.mjs 构成跟踪与数据修复入口。

这些脚本分别面向状态规范化、记录去重、记录合并、管线对账和验证。跟踪数据的确切文件名、字段模式、事务机制和备份格式未在给定资料中出现，操作真实数据前应先检查脚本参数并保留本地副本。

公司研究与联系人定位

根据 README，系统不仅将候选人放入申请队列，还用于研究公司和查找合适的联系对象。输入来自公司及职位信息，输出用于辅助用户决定联系谁、以何种事实为沟通基础。

该能力涉及个人信息与外部站点使用边界，不能把“可访问”理解为“可任意收集或批量联系”。仓库资料未提供联系人数据来源、保留期限或数据主体请求流程，使用者必须自行建立合规规则。

系统架构与关键模块

从 README、package.json 和容器配置可以还原出四层结构：AI 编码命令行负责代理编排，Node.js 脚本承载业务步骤，Playwright 负责浏览器访问，Go 工具链用于可选的仪表盘终端界面。仓库以本地文件和脚本为中心，资料中没有独立后端服务或数据库端口配置。

README 还说明批处理可通过子代理并行评估十个以上职位。资料没有给出并发参数、资源上限、速率限制、基准测试或任务失败重试策略，因此不能把“支持并行”解释为确定的吞吐量承诺。

依赖与运行环境

本地运行的最低明确要求是 Node.js 18 或更高版本。直接安装会使用 npm，并在 postinstall 阶段尝试安装 Chromium 及其系统依赖。

• @google/generative-ai：版本约束为 ^0.24.1，用于 Gemini 集成。
• dotenv：版本约束为 ^17.0.0，用于读取环境变量文件。
• js-yaml：版本约束为 ^4.3.1，用于 YAML 数据处理。
• playwright：精确版本 1.62.1，并与 Docker 基础镜像中的浏览器版本对应。

Dockerfile 使用 mcr.microsoft.com/playwright:v1.62.1-jammy，并安装 Git、Tini、LaTeX 相关包与 Go 1.23.4。镜像支持 amd64 和 arm64；其他架构会在构建步骤中退出。

LaTeX 组件用于文档生成环境，Go 工具链用于 dashboard。仓库元信息将 JavaScript 标为主要语言，但容器提供了额外的 Go 和排版依赖，部署时不应只按单一 JavaScript 应用估算镜像体积。

快速开始

最小闭环可以按“安装、运行环境诊断、验证管线”执行。以下命令仅操作本地克隆目录，不包含账号登录、外部职位提交或批量访问。

安装

git clone https://github.com/santifer/career-ops.git
cd career-ops
git checkout main
npm install

npm install 会触发仓库定义的 postinstall，安装 Playwright Chromium 及依赖。若当前系统不适合安装浏览器依赖，可改用后文给出的 Docker Compose 方式。

运行与验证

# 运行仓库自带的环境诊断
npm run doctor

# 验证求职管线的数据与状态
npm run verify

上述两个脚本分别映射到 doctor.mjs 和 verify-pipeline.mjs。官方资料未提供成功输出样例、退出码约定和首次运行是否需要初始化数据的信息；如果命令要求补充文件，应以终端提示和最新 README 为准。

使用 Gemini 执行测试评估

cp .env.example .env
export GEMINI_API_KEY='<你的-GEMINI-API-KEY>'
node gemini-eval.mjs "JD text here"

<你的-GEMINI-API-KEY> 是占位符，必须替换为用户自己的测试密钥，不能提交到 Git。该调用形式来自 .env.example；职位描述示例使用仓库给出的 JD text here，没有触发职位申请。

配置说明

项目通过环境变量选择模型服务和可选插件，核心插件默认关闭。注释掉的字段并不代表程序已经设置默认值，下表会区分明确默认值、示例值与未提供值。

插件需要在 config/plugins.yml 中显式启用，环境变量注释说明其默认状态为关闭。该配置文件的字段结构未包含在给定资料中，不能补写启用语法，建议以仓库中的 plugins/README.md 和实际配置文件为准。

Docker 隔离运行

容器方案用于解决宿主机无法正常安装 Playwright Chromium 的情况，并把浏览器、Node.js 依赖、Go 和 LaTeX 工具集中在镜像环境中。Compose 不暴露网络端口，服务通过长时间运行的 tail -f /dev/null 保持可进入状态。

docker compose build
docker compose up -d

# 在运行中的容器内执行诊断与验证
docker compose exec career-ops npm run doctor
docker compose exec career-ops npm run verify

项目目录会绑定挂载到 /app，而 node_modules 保存在名为 career-ops-node-modules 的卷中，以避免宿主机与容器的二进制接口不一致。Compose 将共享内存设置为 1gb，用于避免 Chromium 受到默认 /dev/shm 容量限制。

API 密钥会从宿主机环境转发到容器，包括 GEMINI_API_KEY、ANTHROPIC_API_KEY 和 OPENAI_API_KEY。容器配置没有声明密钥管理服务、加密卷或只读文件系统，生产用途需要由部署者自行补充这些控制。

进阶用法

进阶操作应按数据管线分阶段执行，而不是直接将所有脚本串成无人值守投递流程。以下命令均来自 package.json，但具体参数和输入文件应在执行前查看对应脚本与最新文档。

扫描与提取

# 执行基础扫描
npm run scan

# 执行完整 ATS 扫描
npm run scan:full

# 仅使用仓库定义的 YC 种子
npm run scan:yc

# 提取浏览器页面内容
npm run extract

scan:seeds 使用资料中给出的 yc,a16z 种子，scan:yc 只使用 yc。种子清单的来源、更新频率和覆盖范围未在给定资料中说明。

OpenRouter 管线入口

export OPENROUTER_API_KEY='<你的-OPENROUTER-API-KEY>'

npm run or:scan
npm run or:eval
npm run or:pipeline

占位符必须替换为本人申请并有权使用的密钥。or:apply 也存在于脚本列表，但申请动作涉及向外部系统提交信息，不应在未检查目标职位、生成材料和最终字段前自动执行。

申请材料与质量控制

npm run cv:verify-facts
npm run sync-check
npm run test:cv-visual
npm run pdf

推荐先执行事实校验和同步检查，再做视觉测试与 PDF 生成。test:cv-visual:update 会更新视觉快照基线，只有确认排版变化符合预期后才应使用，否则会把错误输出固化为新的测试基线。

跟踪数据维护

npm run normalize
npm run dedup
npm run merge
npm run reconcile
npm run verify

这些入口适合在记录数量增加或状态来源不一致时执行。根据本文作者的经验判断，任何合并与去重操作都应先在版本控制分支或数据副本上运行；仓库资料没有声明自动回滚、事务隔离或冲突保留策略。

可观测性与运维

该仓库提供的是脚本级诊断、验证和摘要能力，而不是完整的集中式监控平台。运维重点是检查职位来源是否仍可访问、跟踪数据是否一致、文档是否通过事实与视觉校验，以及系统更新是否可回滚。

• npm run doctor：执行本地环境诊断。
• npm run liveness：运行 check-liveness.mjs，检查存活状态。
• npm run validate:portals 与 npm run verify:portals：检查职位门户配置或可用性。
• npm run freshness：执行表格新鲜度检查。
• npm run digest：生成周摘要。
• npm run patterns：分析申请数据中的模式。
• npm run rejection-latency：分析拒绝响应时延。
• npm run update:check、npm run update:test、npm run update 和 npm run rollback：覆盖更新检查、迁移测试、应用更新与回滚。

资料没有给出日志格式、指标名称、追踪协议、告警渠道、健康检查端口、数据保留期、恢复时间目标或服务级别协议。需要团队级运维时，应把脚本退出状态、结构化日志和数据备份纳入自己的运行平台，而不能假设仓库已提供相关承诺。

serve:dashboard 会执行 cd dashboard && go run . --path ..。Docker Compose 注释将其描述为交互式仪表盘终端用户界面（TUI），同时未暴露任何端口，因此不能据此宣称存在浏览器访问地址。

安全与合规边界

项目涉及网页自动化、职位数据采集、个人简历、联系人研究和第三方模型调用，使用边界必须由操作者明确控制。安全原则是只访问本人有权访问的页面，只处理具有合法依据的数据，并在提交申请前保留人工确认步骤。

• 站点授权：仅扫描公开职位页面或已获明确授权访问的账户内容，遵守目标站点条款、访问频率限制和适用法律。本文不提供绕过验证码、访问控制、反自动化机制或封禁策略的方法。
• 隐私数据：简历、邮箱、职业经历和申请状态属于敏感个人资料。向 Gemini、OpenRouter、OpenAI 兼容端点或其他模型服务发送前，应核对服务条款、数据保留设置和处理地域。
• 密钥管理：.env 不应提交到版本库，终端历史、容器环境和持续集成日志也不应输出密钥。资料未提供专用密钥保险库集成，部署者需要自行建立轮换与撤销流程。
• 联系人研究：只收集完成合法求职沟通所需的最少信息，不建立无关画像，不进行未经允许的批量营销或骚扰式联系。
• 材料真实性：模型生成内容不得添加不存在的任职经历、学历、技能、证书或量化成果。cv:verify-facts 是辅助检查，不替代本人确认。
• 自动提交：README 明确要求提交前审阅。即使脚本中存在申请入口，也不应将评分结果直接转换为无人监督的外部提交。

官方资料未提供 GDPR、CCPA、个人信息保护法、就业反歧视审计或数据处理协议方面的合规声明。组织使用时需要根据所在司法辖区、招聘平台协议和第三方模型服务条款完成独立评估。

许可证与商用条款

仓库采用 MIT License，版权声明为“Copyright (c) 2026 Santiago Fernández de Valderrama”。该许可证允许免费使用、复制、修改、合并、发布、分发、再许可和销售软件副本，因此可以用于商业项目。

条件是所有软件副本或软件的重要部分必须包含原版权声明和许可声明。许可证按“现状”提供，不附带明示或默示担保，作者或版权方不承担因软件或其使用产生的索赔、损害及其他责任。

README 还链接了单独的 TRADEMARK.md 商标政策。MIT 对软件代码的授权不自动等同于对项目名称、标识或品牌资产的无限授权；涉及品牌展示、再发行名称或对外背书时，应同时核对仓库商标政策，最终以仓库 LICENSE 和 TRADEMARK.md 为准。

局限性与已知限制

该系统的主要限制来自个人上下文质量、模型判断的不确定性、外部招聘页面变化和本地运行环境差异。README 已明确指出首次评估质量不会理想，因此不能把初始得分视为可靠的职业结论。

• 评分依赖用户提供的简历、职业故事、成果证据、偏好和排除条件；缺失信息会降低评估针对性。
• 职位匹配由模型推理完成，资料未提供黄金数据集结果、准确率、召回率、评分者一致性或偏差审计。
• Greenhouse、Ashby、Lever 和公司页面会变化；资料没有给出兼容性承诺或修复时限。
• README 提及十个以上职位的并行评估，但没有公布 CPU、内存、令牌消耗、运行时长或接口限流基准。
• Docker 镜像包含浏览器、Go 和 LaTeX 依赖，但官方资料没有提供镜像大小、签名、软件物料清单或漏洞扫描结果。
• 项目提供事实检查入口，但没有保证生成简历在事实、法律或招聘公平性层面完全正确。
• 资料没有说明跟踪数据的加密方式、备份策略、多用户并发、访问控制和审计记录。
• 官方仓库未提供 SLA、商业支持承诺或托管服务可用性信息，建议以最新 README 为准。

适合谁

适用判断应基于工作流、技术环境和数据控制要求，而不是仅看项目热度。满足以下三个以上信号时，投入配置和维护的收益更明确。

• 已经使用 Node.js 18 以上环境，并能阅读、运行和审查 JavaScript 脚本。
• 当前需要处理数十个以上候选职位，希望先建立统一评分标准，再把时间投入高分目标。
• 愿意维护结构化职业资料，并能为每条经历、成果和技能提供可验证依据。
• 希望数据主要保留在本地，同时能够自行评估第三方模型接口的数据处理条款。
• 已在使用 Claude Code、Codex、OpenCode、Antigravity、Qwen、Kimi、GitHub Copilot 或 Grok Build CLI，并希望把求职任务纳入代理式工作流。

不适合谁

以下情形与当前仓库提供的能力存在直接冲突，选择前应先确认能否接受额外开发和合规工作。若核心要求是无人维护的托管产品，该项目资料不足以证明能够满足。

• 要求完全无需命令行、Node.js、容器或配置文件的图形化使用体验。
• 目标是对大量职位执行无人监督的自动投递，并且不计划逐份检查职位、简历和申请字段。
• 组织要求现成的单点登录、角色权限、多租户隔离、集中审计和明确 SLA；官方仓库未提供这些信息。
• 不能把简历或职位描述发送给任何第三方模型端点，同时也没有可用的本地 Ollama 或兼容接口运行条件。
• 需要有统计验证的招聘决策模型、法律合规认证或可直接用于雇佣筛选的自动评分系统；该项目面向求职者筛选职位，不是招聘方决策系统。

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

排查应先区分环境安装、浏览器运行、模型认证和数据一致性四类问题。仓库提供了对应脚本入口，但给定资料没有列出完整错误码与报错文本。

npm install 在 Chromium 安装阶段失败怎么办

先确认 Node.js 版本满足 >=18，再运行 npm run doctor。如果宿主系统阻止 Playwright 安装器，使用仓库提供的 Dockerfile 与 Compose 配置；该镜像已经包含与 Playwright 1.62.1 对应的 Chromium。

容器内找不到浏览器怎么办

检查 PLAYWRIGHT_BROWSERS_PATH 是否为 /ms-playwright，并确认镜像基于 mcr.microsoft.com/playwright:v1.62.1-jammy 构建。不要把宿主机的 node_modules 覆盖到容器，Compose 已通过独立卷避免这种二进制接口冲突。

Gemini 评估提示认证失败怎么办

确认 GEMINI_API_KEY 已在当前进程或 .env 中设置，且没有保留示例占位符。模型名称可通过 GEMINI_MODEL 覆盖；仓库资料中的默认值是 gemini-3.6-flash，实际服务可用性应由接口响应确认。

如何使用其他 OpenAI 兼容服务

配置 OPENAI_API_KEY、OPENAI_BASE_URL 和 OPENAI_MODEL，再使用 openai-eval.mjs。资料列举的兼容端点包括 OpenAI、OpenRouter、Together、Groq、DeepSeek、智谱 GLM、LM Studio、llama.cpp、vLLM 和 Ollama 的 /v1 接口，但没有提供各服务的逐项兼容测试结果。

评分偏离个人判断怎么办

根据 README，应补充简历、职业故事、成果证据、工作偏好、优势和规避项，再重新评估。不要直接修改分数来掩盖上下文缺失，应保留职位原文与评分依据，检查具体维度为何产生偏差。

跟踪数据出现重复或状态不一致怎么办

在数据副本上依次检查 normalize、dedup、merge、reconcile 和 verify。脚本参数、覆盖行为和冲突处理方式未在资料中完整给出，因此执行前应读取对应 .mjs 文件，并将变更纳入 Git 审查。

仪表盘应访问哪个端口

给定 Compose 文件没有暴露端口，注释将仪表盘描述为 TUI。运行入口是 npm run serve:dashboard，官方仓库未提供网页端口信息，建议以最新 README 为准。

能否让系统自动替本人提交所有申请

不应把该项目用作无差别自动投递器。README 明确称其为筛选器，并要求提交前审阅；评分低于 4.0/5 的职位也被明确建议不要申请。

项目地址与资源

以下链接均来自仓库元信息、README 或项目资料，可用于核对最新版本、支持范围、案例和社区信息。版本、支持的命令行工具和配置项应以仓库默认分支中的最新文件为准。

• career-ops GitHub 仓库
• career-ops 官网与文档
• CareerOps Manifesto
• career-ops 最新发行版
• 支持的 AI 编码命令行列表
• career-ops 商标政策
• career-ops 使用案例
• 项目作者官方网站
• career-ops Discord 社区