用途
camoufox-setup 用于在当前机器上以幂等方式安装并验证 Camoufox 隐身浏览器工具链：先探测已存在的组件，再只安装缺失的部分。Camoufox 是一个基于 Firefox 的反检测分支，通过 Playwright 驱动；安装分为两步——安装 pip 包，再单独下载其打过补丁的浏览器二进制文件。
该技能仅限授权使用：用于自动化你拥有或获授权测试的站点，以及注重隐私的浏览。需遵守各站点的服务条款与 robots.txt；不得用于滥用、大规模抓取或规避你无权绕过的访问控制。
何时使用 / 何时不使用
适用场景：环境缺失或损坏时，例如 Camoufox 无法导入、camoufox fetch 失败、全新机器，或需要“准备好隐身环境”。
不适用场景：运行浏览任务或恢复会话——那属于 camoufox 技能。
工作流程
所有操作都通过捆绑脚本执行，它是确定性的关卡。
- 先探测（不做任何更改）。在改动任何东西之前查看已存在的内容：
python3 "${CLAUDE_SKILL_DIR}/scripts/setup_check.py"
阅读 STATUS <component>: OK|MISSING|WARN 各行以及最后的 RESULT:。camoufox_pkg 与 camoufox_browser 为必需项；playwright_cli 与 xvfb 为可选项，不会导致运行失败。
- 安装缺失项。仅当第 1 步报告 MISSING/失败时执行：
python3 "${CLAUDE_SKILL_DIR}/scripts/setup_check.py" --install
该命令会运行 pip install -U camoufox[geoip]，然后运行 python3 -m camoufox fetch，并且（若存在 npm）运行 npm i -g @playwright/cli@latest && playwright-cli install --skills。添加 --required-only 可跳过 playwright-cli 与 Xvfb。
- 验证。重新运行第 1 步；要求 RESULT: ok。报告解析出的包版本与浏览器安装路径。此处不要启动浏览器。
若某个必需步骤失败，阅读 FAIL 详情并修复根本原因（fetch 的网络/代理、磁盘空间、权限）——绝不要伪造成功。完整的故障排查与平台说明见 references/toolchain.md。
完成标准
setup_check.py 输出 STATUS camoufox_pkg: OK <ver>、STATUS camoufox_browser: OK <path> 以及 RESULT: ok（退出码 0）。你报告了版本与浏览器路径，且未做其他更改。
注意事项
- geoip 附加项对区域设置一致性并非可选。启动时 geoip=True 需要 [geoip] 附加项（一个 MaxMind 数据库，由 camoufox fetch 拉取）。安装普通 camoufox 后再传 geoip=True 会失败或泄漏不匹配的区域设置。始终安装 camoufox[geoip]。
- playwright-cli 通过启动而非附加来驱动 Camoufox（已测试）。其 attach --cdp 仅限 Chromium，attach --endpoint 在 Camoufox 服务器上会失败（无 contexts）。但将 Camoufox 的 launch_options() 传入 playwright-cli 的配置（browser.launchOptions），可让 playwright-cli open --browser firefox --config <f> 启动一个完全隐身的 Camoufox——已验证 navigator.webdriver 为 false 且伪造指纹完好。camoufox 技能的 pwcli_config.py 会生成该配置。进程内/服务器驱动仍使用 Playwright API（Camoufox(...) / firefox.connect）。详见 references/toolchain.md。
- headless="virtual" 需要 Xvfb（仅 Linux）。若缺少 Xvfb，安装脚本会发出警告；仅当你打算运行虚拟显示时才安装它（apt-get install -y xvfb 或你的包管理器）。macOS/Windows 忽略此项。
- Camoufox 自我标注为“开发中……可能不适合稳定的生产使用”。为可复现性固定一个通道（python3 -m camoufox set official/stable 然后 fetch），并在任何 Camoufox 或 Firefox 更新后重新运行 camoufox 技能内置的验证——隐身属性会随版本漂移。
- 清理/磁盘：浏览器二进制文件很大。若需要回收空间，可用 python3 -m camoufox remove 删除它。
参考资料
references/toolchain.md —— 安装矩阵、playwright-cli 边界、Xvfb、GeoIP、通道固定、清理，以及完整的授权使用政策。