career-ops 一键安装器（Scaffolder）深入解析：npx init 从零搭建 AI 求职工作区

career-ops 是一个跑在 AI 编程 CLI 里的开源 AI 求职系统：扫描职位门户、把职位评估成结构化的 A–H 报告并给出 1–5 综合评分、按职位定制简历并跟踪每一次申请。本仓库的 scaffolder/ 子项目把「安装整个工作区」压缩成一条 npx @santifer/career-ops init 命令。读完本文，你将理解该安装器的行为与默认值、它对多种 AI CLI 的适配机制（skill entrypoint 引导），以及安装完成后如何通过对话式 onboarding 完成首次配置、如何验证安装。

1. scaffolder 在仓库中的定位

在仓库根目录 scaffolder/README.md 中，scaffolder 被定义为一句话总结：career-ops 的一键安装器，即装即用（ready-to-use）。它并不是主程序本身，而是一个独立发布的 npm 脚手架包，职责是「克隆最新稳定版 + 安装依赖 + 引导 CLI skill 入口」，把用户引向完整的工作区。

从 scaffolder/package.json 可以看到它的发布形态：

{
  "name": "@santifer/career-ops",
  "version": "1.32.0",
  "description": "One-command installer for career-ops — the AI-powered job search pipeline built on Claude Code.",
  "bin": {
    "career-ops": "bin/cli.mjs"
  },
  "type": "module",
  "files": [
    "bin/cli.mjs",
    "bin/skill-entrypoints.mjs",
    "README.md"
  ],
  "engines": {
    "node": ">=18"
  },
  "keywords": ["career-ops", "claude-code", "job-search", "scaffold", "create", "cli"],
  "dependencies": {}
}

值得注意的实现事实：

• bin 字段声明了 career-ops 命令，入口为 bin/cli.mjs；npm 包发布时只带上 bin/cli.mjs、bin/skill-entrypoints.mjs 和 README 三个文件。
• dependencies 为空：安装器自身零运行时依赖，把重量级安装（Playwright、Chromium 等）留给克隆下来的主项目在其 postinstall 脚本里完成（见根目录 package.json 中的 "postinstall": "npx playwright install chromium ..."）。
• 版本与主仓库同步：scaffolder 的 1.32.0 与仓库根目录 VERSION 标注的 1.32.0 # x-release-please-version 一致，二者通过 release-please 协同发布。
• 包的关键字覆盖了它要服务的 CLI 生态：claude-code、opencode、codex、antigravity、qwen、kimi、copilot、grok 等（同时见根目录 package.json）。

2. 一条命令安装：行为与默认值

官方推荐且文档主推的安装方式只有一条命令：

npx @santifer/career-ops init

它等价于完整的带参形式：

npx @santifer/career-ops init [folder]   # 默认目录：./career-ops

2.1 这条命令做了什么

按 scaffolder/README.md 的描述，init 会建立一个开箱即用的工作区，共两步：

1. 把 career-ops 克隆到最新稳定发布版（clones career-ops at the latest stable release）；
2. 安装依赖（installs dependencies）。

安装目录默认是当前目录下的 ./career-ops；如果你想装到别处，把第二个参数 [folder] 换成目标目录名即可。

2.2 npx 的语义：一次运行，不全局安装

npx 随 Node.js 一起分发。npx @santifer/career-ops init 只临时拉取并运行一次安装器，不会全局安装任何东西——这与根目录 README 中文版 README.cn.md「快速开始」小节里的说明一致。运行时它从 npm 拉取的是 @santifer/career-ops 这个已发布包，因此即使本仓库后续有未发布的提交，npx 拿到的也始终是已发布的最新稳定版脚手架逻辑。

2.3 安装之后

装完后进入目录并打开你习惯的 AI 编码 CLI：

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

更完整的流程说明（含 Git 忽略规则、Codex codex exec 的批处理写法）见仓库的 docs/SETUP.md，那里是该文档中“更偏好手动 git clone 请查看 setup 指南”指向的详细安装手册。

3. 首次启动：对话式 onboarding，无需手动改配置

scaffolder 只负责「把代码拉到本地」，真正让工作区可用的第二步由主项目承担。根据 scaffolder/README.md 的核心说明：

在首次启动时，Agent 会通过聊天带你完成设置——你的简历、个人档案、目标职位——一切都可以用对话完成，无需手工配置任何东西。

这意味着 npm install 完成后第一次在你的 AI CLI 中打开目录，Agent（基于仓库根目录的 AGENTS.md 系列指令文件）会引导完成：

• 提供你的 CV；
• 填写个人信息（姓名、目标职位、薪资预期等）；
• 用预置的公司清单配置职位扫描器。

用户只需要回答提问即可，而不必手动编辑配置。这一点的实战含义是：第一轮对话质量决定后续评估质量——系统在还没有你的任何上下文时，第一次评估往往不会太好，喂给它越多信息（CV、职业故事、证明点、偏好、避开的公司类型），后续的 A–H 报告和简历定制才越准确（根目录 README.md「What Is This」一节对这一点有明确提示）。

4. AI 无关性设计：为什么它能跑在多款 CLI 上

scaffolder README 明确强调：career-ops 是 AI-agnostic（与 AI 厂商无关）的，Claude Code、Gemini、Codex、Qwen、OpenCode、GitHub Copilot CLI、Antigravity CLI、Grok Build CLI 都可以使用同一套工作区。

4.1 多 CLI 是如何被统一起来的

这套兼容性不是魔法，而是「每个 CLI 读各自入口文件，入口文件统一指向规范 AGENTS.md」的架构。仓库根目录 ARCHITECTURE.md 记录：每个 CLI 读取自己的入口文件（CLAUDE.md 完整版，以及指向 AGENTS.md 的薄封装 OPENCODE.md、CODEX.md、GEMINI.md），外加 .agents/skills/ 下的 skill entrypoint，遵循 open agent skill standard。支持矩阵与各 CLI 的调用方式见 docs/SUPPORTED_CLIS.md：

CLI	入口文件	交互式	无头 / 批处理
Claude Code	CLAUDE.md	claude（/career-ops）	claude -p "prompt"
Cursor	AGENTS.md	在 Cursor 中打开项目提问	.cursor/skills/career-ops/SKILL.md
Codex	CODEX.md	codex（纯文本提问）	codex exec "prompt"
OpenCode	OPENCODE.md	opencode（/career-ops）	opencode run "prompt"
Antigravity CLI	AGENTS.md	agy	agy -p "prompt"
Grok Build CLI	AGENTS.md	grok	grok -p "prompt"
Qwen / Kimi / GitHub Copilot CLI / Gemini	各自入口	各 CLI 原生交互	各 CLI 的 -p 无头参数

4.2 安装器为什么要在克隆后「补引导 skill 入口」

scaffolder README 里有一句容易被忽略却非常关键的设计说明：

The installer bootstraps CLI skill entrypoints after clone, so new CLIs (e.g. Grok) work even when npx pulled an older release tag.

翻译成实现语言：npm 发布包里的 bin/skill-entrypoints.mjs（scaffolder 的 files 清单中明确包含该文件）在克隆完成后会为各 CLI 补建 skill 入口文件。这样做的动机是：npx 拉取的脚手架版本可能晚于某个 CLI 生态的演进，比如仓库代码已经支持了较新的 Grok Build CLI，而 npx 缓存或发布的旧 tag 里还没带对应的入口——安装器在本地补上这些入口，就能让新 CLI 立刻可用，而不必等待脚手架重新发版。

仓库改动历史也印证了这条逻辑：CHANGELOG 中记录了 scaffolder 在无符号链接文件系统上「materialize」（实体化）Kimi skill 入口、测试需接受实体化 skill 入口而非仅符号链接、updater 在无 symlink 环境下实体化 skill 入口等修复（见 CHANGELOG.md）。也就是说，AGENTS.md 体系下的入口文件既有符号链接方案，也有直接实体文件的降级方案，scaffolder 必须同时处理这两种情况。

4.3 Codex 用户的特殊提醒

docs/SETUP.md 对 Codex 给出了补充：Codex 的交互会话中斜杠命令不保证可用，因此应把模式名直接写进 prompt。例如：

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：

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."

5. 手动安装的备选路线

如果你不想依赖 npx，scaffolder README 说明手动路线仍然完全有效：git clone 主仓库后进入目录执行 npm install，接着打开你的 AI CLI 走同样的首次启动引导，详细步骤见 docs/SETUP.md。docs/SETUP.md 还提示了这条路线适合的人群：想跟踪特定分支、想贡献代码、或想在安装依赖前先审计代码的人。

与一键命令相比，手动路线多出的一次性步骤是 PDF 渲染依赖：career-ops 用无头 Chromium 渲染 PDF，需按机器安装一次：

npx playwright install chromium

（自动化场景下，主项目根目录 package.json 的 postinstall 已经尝试执行 npx playwright install chromium --with-deps。）

另外，docs/SETUP.md 还提到无本地检出、纯云端运行的场景——Claude Code on the web：把仓库放进私有 GitHub 仓库（公开 fork 会暴露个人职业数据），在 web 会话中提交「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.」这类任务即可。需要注意的是云端工作区同样使用普通文件 cv.md、data/、reports/，且这些路径因含个人数据被刻意 git-ignored，web 会话结束即丢失，长线使用仍应走本地安装路线。

6. 环境要求：Node.js 18+ 与 git

scaffolder/README.md 给出的依赖只有两条：

• Node.js 18+
• git

这两条与 scaffolder/package.json 中 engines.node >= 18 互为印证。额外说明（来自 docs/SETUP.md）：

• npx 随 Node.js 附带，因此安装器拒绝在缺少二者时运行；也就是说有 Node 就有 npx，无需单独安装脚手架；
• 若使用 Gemini CLI 集成，需要 Node.js 20+；
• 可选：Go 1.21+（用于 dashboard TUI，对应根目录 package.json 的 npm run serve:dashboard 脚本，它实际执行 cd dashboard && go run .）。

7. 安装完成后如何验证

工作区就绪后，可以运行主项目自带的两个一致性检查来确认配置与管道完整：

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

（上述命令同样来自 docs/SETUP.md 的 Verify Setup 小节；对应根目录脚本见 package.json 的 sync-check、verify。若想大范围跑验证，仓库还提供 node test-all.mjs --quick，见 docs/SETUP.md 的贡献流程说明。）

8. 核心操作速查表

进入工作区并完成首次 onboarding 后，日常操作通过 /career-ops 斜杠命令或直接向 Agent 下达自然语言指令即可（下表摘录自 docs/SETUP.md）：

动作	方式
评估一份职位	粘贴 URL 或 JD 文本
搜索职位	/career-ops scan 或让 Agent 执行 scan
处理积压 URL	/career-ops pipeline 或让 Agent 执行 pipeline
生成 PDF	/career-ops pdf 或让 Agent 执行 pdf
起草申请邮件	/career-ops email——仅起草，绝不发送、提交或点击
批量评估	/career-ops batch，或 codex exec "Run career-ops batch mode ..."
查看跟踪状态	/career-ops tracker 或让 Agent 执行 tracker
填写申请表单	/career-ops apply 或让 Agent 执行 apply

9. 总结

把 scaffolder/README.md 与 scaffolder/package.json、docs/SETUP.md、docs/SUPPORTED_CLIS.md、ARCHITECTURE.md 合在一起看，scaffolder 的完整设计意图非常清晰：

1. 降低门槛：npx @santifer/career-ops init [folder]（默认 ./career-ops）一条命令完成「克隆最新稳定版 + 装依赖」，这是新手最快的上手路径；
2. 对话式配置：真正个性化设置不依赖手工编辑文件，首次启动时由 AI CLI 里的 Agent 通过与用户聊天完成 CV、个人档案与目标职位的录入；
3. CLI 无关：克隆后由 bin/skill-entrypoints.mjs 补建各 CLI 的 skill 入口，使 Grok 等新 CLI 在 npx 拉到旧 tag 时依然可用，底层是「各入口文件统一指向 AGENTS.md」的 open agent skill standard 架构；
4. 手动路线作为兜底：需要审计代码、跟踪特定分支或参与贡献时，git clone && npm install 依然完全可用。

如果你只想快速体验 career-ops，直接执行 npx @santifer/career-ops init，然后 cd career-ops && claude（或你惯用的 CLI），剩下的让首次对话引导你完成即可。