career-ops 安装与本地运行指南：三种安装路径、首次引导与可选 Dashboard 构建

本文基于 career-ops 仓库的 SETUP.md 整理并扩展，覆盖前置条件、三种安装方式（npx 一键安装、浏览器版 Claude Code、手动 clone）、首次运行引导流程、可用命令速查、PDF 渲染依赖、环境校验手段（cv-sync-check.mjs / verify-pipeline.mjs）以及可选的 Go 语言 Dashboard TUI 构建。读完本文，你可以完成从零到可用的本地部署，理解各配置文件为何被 git-ignore，并知道如何自行验证环境完整性。

前置条件

安装前需要准备以下工具（以 SETUP.md 的 Prerequisites 一节为准）：

依赖	要求	说明
AI 编码 CLI	任选其一	Claude Code、Gemini CLI、Codex、Qwen Code、OpenCode、GitHub Copilot CLI、Antigravity CLI 或 Grok Build CLI，完整对照表见 SUPPORTED_CLIS.md
Node.js	18+	同时需要 git；npx 随 Node 附带，安装器在缺失时会拒绝运行。仓库 package.json 中 engines.node 声明为 >=18。注意：Gemini CLI 集成要求 Node.js 20+
Go	1.21+（可选）	仅用于构建 Dashboard TUI。注意：当前仓库 dashboard/go.mod 声明 go 1.25.0，dashboard/README.md 也要求 Go 1.24+，实际构建请以 go.mod 为准

career-ops 对 CLI 是"AI-agnostic"的：核心逻辑统一放在 AGENTS.md，各 CLI 通过仓库根目录的入口包装文件接入。从 SUPPORTED_CLIS.md 的对照表看，Claude Code 用 CLAUDE.md（该文件仅包含一行 @AGENTS.md 引用）、Codex 用 CODEX.md、OpenCode 用 OPENCODE.md、Gemini 用 GEMINI.md（遗留包装，已过渡到 Antigravity CLI），其余 CLI 直接读 AGENTS.md。

快速开始

推荐方式：一条命令安装

npx @santifer/career-ops init

npx 随 Node.js 附带，该命令只会把安装器运行一次而不会全局安装任何东西。它会做两件事：把最新 release 克隆到 ./career-ops 目录，并安装依赖。然后进入工作区并打开你的 AI CLI：

cd career-ops
claude   # 或 codex / qwen / opencode / agy / grok

首次启动时，career-ops 会以对话方式引导你完成设置——它会询问你的 CV、个人信息（姓名、目标岗位、薪资期望），并用预配置的公司列表配置职位扫描器。无需手动编辑任何文件，只要回答它的问题即可。之后粘贴一个职位 URL 或职位描述，它就会评估该职位、生成报告、产出定制 PDF，并记录到追踪表中。

Codex 用户的调用方式

Codex 中斜杠命令（slash command）不保证可用，因此如果 /career-ops 不可用，直接用自然语言指定相同的模式名即可：

Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123
Run the career-ops scan mode.
Run the career-ops pipeline mode.
Run the career-ops pdf mode.
Run the career-ops email mode for the latest evaluated role. Draft only; never sends, submits, or clicks.
Run the career-ops tracker mode.

对于一次性任务或批处理，使用 codex exec（完整指南见 docs/CODEX.md）：

codex exec "Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123"
codex exec "Run career-ops scan mode in this repo."
codex exec "Run career-ops pipeline mode for data/pipeline.md."
codex exec "Run career-ops pdf mode for the latest evaluated role."
codex exec "Run career-ops email mode for the latest evaluated role. Draft only; do not send, submit, or click anything."
codex exec "Run career-ops tracker mode and summarize the current statuses."

进阶：手动 clone

如果你希望自行克隆仓库——例如跟踪特定分支、贡献代码、或在安装依赖前审计代码——可以手动操作：

git clone https://github.com/career-ops-hq/career-ops.git
cd career-ops
npm install

随后在该目录打开你的 AI CLI，首次运行引导流程与其他安装方式完全一致。

仅浏览器方案：Claude Code on the web

Claude Code 的网页版可以无需本地检出地运行 career-ops（目前是针对符合条件 Claude 订阅计划的研究预览）。Web 会话会把一个 GitHub 仓库克隆到隔离的云 VM 中——注意它没有你本机的文件和本地配置。使用步骤：

1. 把 career-ops 放进一个你的账号可以访问的私有 GitHub 仓库。可以用 GitHub Importer 以 https://github.com/career-ops-hq/career-ops.git 为源导入。普通 fork 该公开仓库的结果仍然是公开的，因此不要用公开 fork 存放个人求职数据。

2. 打开 claude.ai/code，连接 GitHub，选择私有仓库和分支。首次运行用 Default 云环境即可。

3. 提交这个首个任务：

   Set up career-ops in this checkout. Run npm install, then start the first-run
   onboarding. Keep cv.md, data/, and reports/ out of Git.
   

云端检出中 career-ops 仍然使用普通的工作区文件（而非浏览器存储）：

路径（相对仓库根）	存放内容
cv.md	你的主简历
data/	追踪表及其他私有工作流状态
reports/	职位评估与生成的报告

一个必须理解的关键行为：cv.md、data/ 下的运行时内容以及 reports/ 下的 Markdown 文件被有意 git-ignore，因为它们包含个人数据。仓库根目录的 .gitignore 中可以看到对应规则：cv.md 直接忽略、data/* 整目录忽略（仅保留 .gitkeep 占位）、reports/*.md 忽略。这意味着 web 会话分支的常规 push 不会把这些数据持久化到 GitHub：新的云会话重新从仓库开始，拿不到上一个 VM 里被 ignore 的文件。因此建议把整个个人工作流保持在同一个会话内，并在其环境到期前把需要的产出转移到安全存储；永远不要强制添加这些路径（git add -f）。需要跨多个会话的持久工作区时，请使用下文推荐的本地安装方式。

可用命令速查

安装完成后，日常操作通过斜杠命令（或让 Agent 执行对应模式）完成。下表完整继承自 SETUP.md 的 Available Commands 一节：

操作	使用方式
评估一个职位	粘贴 URL 或 JD 文本
搜索职位	/career-ops scan 或让 Agent 运行 scan
处理待处理 URL	/career-ops pipeline 或让 Agent 运行 pipeline
生成 PDF	/career-ops pdf 或让 Agent 运行 pdf
起草申请邮件	/career-ops email 或让 Agent 运行 email；仅草稿，永不发送、提交或点击
批量评估	/career-ops batch 或 codex exec "Run career-ops batch mode ..."
查看追踪表状态	/career-ops tracker 或让 Agent 运行 tracker
填写申请表	/career-ops apply 或让 Agent 运行 apply

这些模式名对应 modes/ 目录下各自的 Markdown 提示词文件：如 scan.md（门户扫描）、pipeline.md（处理 data/pipeline.md URL 收件箱）、pdf.md（ATS 优化 PDF）、email.md（申请邮件草稿）、batch.md（无头 worker 批量处理）、tracker.md（追踪表总览）、apply.md（在线申请助手，只填表、永不提交）等，完整模式目录见 modes/README.md 的 Mode catalog 表。路由逻辑（哪个用户请求触发哪个模式）写在 AGENTS.md 的 Skill Modes 表中。

PDF 渲染：一次性安装

PDF 通过无头 Chromium 渲染，每台机器只需安装一次：

npx playwright install chromium

一个可以佐证的细节：package.json 的 postinstall 脚本已经内置了 npx playwright install chromium --with-deps，因此 npm install 成功后 Chromium 通常已就绪；如果 postinstall 被跳过或失败（常见于受限网络），上面的手动命令就是补救手段。PDF 生成本身由 generate-pdf.mjs 驱动，依赖 playwright（在 package.json 的 dependencies 中锁定为 1.62.1）。

验证安装

SETUP.md 给出的两条验证命令：

node cv-sync-check.mjs      # 检查配置
node verify-pipeline.mjs   # 检查管线完整性

结合仓库源码可以看清它们各自校验什么：

• cv-sync-check.mjs：校验 career-ops 设置的一致性，包括 4 项检查——cv.md 存在（且内容足够长，短于 100 字符会给出警告）、config/profile.yml 存在并包含 full_name、email、location 等必填字段（仍含示例数据 "Jane Smith" 会告警）、modes/_shared.md / modes/_writing.md / batch/batch-prompt.md 中是否存在硬编码指标数字、article-digest.md 的新鲜度。它通过 path-resolver.mjs 的 getCareerOpsRoot() 解析数据根目录，因此兼容自定义数据目录布局。
• verify-pipeline.mjs：管线完整性健康检查，当前实现包含 16 项校验，例如：所有状态必须属于 templates/states.yml 定义的规范状态（含西语别名归一化，如 entrevista → interview）、无重复公司+岗位、报告链接指向真实存在的文件、分数格式必须为 X.XX/5 或 N/A 或 DUP、行格式为合法管道分隔、batch/tracker-additions/ 下无未合并的 TSV、无被两个报告文件覆盖的同一公司+岗位、data/applications.md 与 data/active-interviews.md 状态同步、追踪表单元格中无不可见控制字符等。对全新安装（尚无 applications.md）它会友好退出："This is normal for a fresh setup."

此外还有一个文档未列入但仓库内置的更完整诊断入口 doctor.mjs：node doctor.mjs 会检查全部前置条件并输出通过/失败清单，支持 --json（机器可读的 onboarding 状态）、--strict（额外网络探测 portals.yml 中的每个条目）、--target <path>（诊断另一个 career-ops 检出）、--cli <name>（检查指定 CLI 的集成，可选值 claude, codex, opencode, antigravity, grok, qwen, kimi, copilot, gemini）。作为新手引导的入口点，它是排障时首选的第一站。

构建 Dashboard（可选）

career-ops 附带一个独立的 Go 语言终端 UI，用于浏览 pipeline：过滤标签页、排序模式、分组/平铺视图、懒加载报告预览和内联状态选择器。它由 Bubble Tea + Lipgloss 构建（见 dashboard/go.mod），与 Node 核心完全隔离——不依赖 Node 侧任何代码，只读取追踪表文件（数据加载器会依次尝试 {path}/applications.md 和 {path}/data/applications.md 两种布局，并支持 --path <dir> 参数指定 career-ops 目录）。

从仓库根构建：

npm run serve:dashboard     # 打开 TUI pipeline 查看器（等价于 cd dashboard && go run .）
npm run build:dashboard     # 可选：构建独立二进制

两个脚本都定义在 package.json 的 scripts 中。build:dashboard 走的是 build-dashboard.mjs 包装器而非直接 go build，原因是 go build -o career-dashboard . 在 Windows 上会生成无扩展名的可执行文件，该包装器负责选择平台正确的输出名（Windows 为 career-dashboard.exe，其他平台为 career-dashboard）。注意文档中的 Go 1.21+ 为最低门槛，当前 dashboard/go.mod 声明 go 1.25.0，实际构建请使用不低于此版本的环境。Go 测试与包同目录（*_test.go），Node 测试套件在 node test-all.mjs 中会构建 dashboard（--quick 模式下跳过）。

首次贡献

SETUP.md 的 "Contributing for the first time" 一节给出了一条低门槛贡献路径：小而聚焦的改动可直接提 PR（bug 修复、文档、翻译、新的零认证扫描器 provider），而新功能、新模式、新命令或架构变更应先开 issue。基本工作流：

1. Fork 仓库，从 main 创建分支；
2. 做一个聚焦的改动，并确保 cv.md、profile.yml、申请记录和报告等个人数据不进入提交；
3. 运行相关检查；做较全面验证时可用 node test-all.mjs --quick；
4. 提交并推送分支到你的 fork；
5. 向 career-ops-hq/career-ops 开 PR，说明改了什么、为什么改。

完整的贡献规范见 CONTRIBUTING.md。这里值得强调的是第 2 步：从 .gitignore 的注释可以看到，个人数据（cv.md、data/*、reports/*.md、config/profile.yml 等）之所以被忽略，正是为了保证"每个用户的检出里这些文件都不会被误提交"，贡献者无需为此做任何额外操作。

常见问题速查

症状	处理
npx init 拒绝运行	确认已安装 Node.js 18+ 与 git（npx 随 Node 附带）
使用 Gemini CLI 集成失败	需要 Node.js 20+，升级 Node 后重试
PDF 生成报找不到 Chromium	运行 npx playwright install chromium（见 PDF 渲染一节）
配置不确定是否完整	依次运行 node cv-sync-check.mjs、node verify-pipeline.mjs，必要时 node doctor.mjs
Dashboard 构建报 Go 版本错误	安装 Go 1.25+（以 dashboard/go.mod 为准）
web 会话数据"消失"	这是预期行为：cv.md/data//reports/ 被 git-ignore，不会随 push 持久化；把工作流留在一个会话内并及时导出产出

适用前提与限制：以上命令均假设你在 career-ops 仓库根目录（npx init 克隆出的 ./career-ops 目录或手动 clone 的检出）内执行；node test-all.mjs 为完整测试套件，日常安装无需运行。career-ops 的所有用户层文件（cv.md、config/profile.yml、portals.yml、data/* 等）均被 git-ignore 且永不被自动更新系统触碰（详见 DATA_CONTRACT.md 的两层数据契约），因此系统更新与你的个人数据是相互隔离的。