用途
cli-anything-safari 是一个用于在 macOS 上自动化真实 Safari 浏览器的命令行界面。它把 safari-mcp（一个 Node.js 的 MCP 服务器）封装成 Python Click CLI，因此可以按需调用 safari-mcp 提供的全部 84 个工具。因为 Safari 是原生浏览器，自动化过程中会保留登录状态。
该 CLI 的使用场景包括：智能体框架本身不支持 MCP 协议（如 Codex CLI、GitHub Copilot CLI、自定义脚本或较旧的框架）；需要在 bash 中脚本化浏览器自动化，例如结合 jq 处理输出；在 CI/CD 中运行可被 cron 调度的任务；以及从终端进行交互式调试。
如果智能体原生支持 MCP（如 Claude Code、Cursor、Cline 等），直接通过 MCP stdio 使用 safari-mcp 会更快，因为每次 CLI 调用都会启动一个新的子进程，存在额外的调用开销。
主要能力
CLI 的功能与 safari-mcp 保持对等：每个 Click 命令都由 safari-mcp 的工具 schema 自动生成（以 resources/tools.json 形式打包），全部 84 个工具都可以用 MCP 服务器所期望的参数名和类型调用。
顶层命令有 5 个： tool —— 调用 safari-mcp 的任意 84 个工具（动态、由 schema 驱动） tools —— 查看内置的工具注册表（list、describe、count） raw —— 逃生舱，用完整工具名加原始 JSON 参数调用工具 session —— 仅用于显示的内存会话状态（最近 URL、当前标签） repl —— 交互式 REPL（不带子命令时的默认行为）
可执行的典型操作涵盖：导航、快照（返回带 ref ID 的结构化文本）、按 ref/选择器/可见文本点击、填写表单、按方向与数量滚动、元素拖拽、截图、保存 PDF、执行 JavaScript、导航并读取、点击并读取、网络捕获与性能指标、Cookie 与本地存储读写、导出/导入存储、上传文件、剪贴板读写等。
安装与准备
前置条件： macOS（Safari MCP 仅支持 macOS） Safari（macOS 自带） Node.js 18+（可通过 brew install node 或从 nodejs.org 安装） Python 3.10+ 在 Safari 中启用 Apple 事件：Safari → 开发 → 允许 Apple 事件中的 JavaScript
安装命令： cd safari/agent-harness pip install -e .
首次调用工具时会下载 safari-mcp 的 npm 包（一次性，几 MB）。
使用方式
所有命令支持全局 --json 标志以获得结构化输出，默认是人类可读的缩进键值文本或项目符号列表。
示例： cli-anything-safari tools count cli-anything-safari tools list --filter click cli-anything-safari tools describe safari_scroll cli-anything-safari tool navigate --url https://example.com cli-anything-safari --json tool snapshot cli-anything-safari tool click --ref 0_5 cli-anything-safari tool click --selector "#submit" cli-anything-safari tool fill --selector "#email" --value "user@example.com" cli-anything-safari tool scroll --direction down --amount 500 cli-anything-safari tool save-pdf --path /tmp/page.pdf cli-anything-safari tool evaluate --script "document.title" cli-anything-safari --json tool navigate-and-read --url https://example.com
批量填表单可以传入 JSON 字符串： cli-anything-safari tool fill-form --fields '[{"selector": "#email", "value": "user@example.com"}, {"selector": "#password", "value": "hunter2"}]'
复杂嵌套参数可以使用 raw 逃生舱： cli-anything-safari raw safari_evaluate --json-args '{"code":"[...document.querySelectorAll("a")].map(a => a.href)"}'
不带子命令时进入交互式 REPL，REPL 横幅会打印该 SKILL.md 的绝对路径，方便智能体自行发现能力。
为智能体编写脚本时建议：始终使用 --json；检查返回码（0 表示成功，非零表示 URL 校验失败、MCP 调用失败或 JSON 参数无效）；从 stderr 读取错误信息，从 stdout 读取数据；文件相关工具的参数名并不一致，使用前先用 tools describe 确认。
适用场景与工具选择建议
优先使用 tool snapshot 而非 tool screenshot，因为带 ref ID 的结构化文本成本低得多，且携带点击所需的 ref。优先用 tool click --ref 而非 --selector，ref 在单次快照内稳定，选择器可能脆弱。tool navigate-and-read 可替代 navigate 加 read-page，tool click-and-read 可替代 click 加 read-page，各节省一次往返。只有当普通点击因 405/403（WAF 拦截、G2、Cloudflare）失败时，才使用 tool native-click，因为它会实际移动光标。
注意 ref 会过期：第一次快照的 ref 是 0_1、0_2、0_3……，第二次快照变成 1_1、1_2、1_3……，因此应在快照后尽快点击，不确定时重新快照。
Safari MCP 按会话跟踪标签所有权，会阻止对会话未打开的标签执行修改操作（navigate、click、fill）。要操作特定页面，应先用 tool new-tab --url ... 打开。
限制与注意事项
每次 CLI 调用都会启动新子进程，存在调用开销。CLI 只维护供 REPL 显示用的少量内存状态（last_url、current_tab_index），没有持久会话、撤销/重做或文档模型，每次调用状态都是全新的。Safari MCP 本身按调用无状态：每个工具命令会启动一个新的 npx safari-mcp 子进程执行后退出。
Safari MCP 实行单一活动会话，会杀掉超过 10 秒的旧 Node.js 进程。如果同时运行两个 CLI 实例，其中一个会杀掉另一个的后端。目前没有守护模式；对延迟敏感的工作流可从长生命周期 Python 脚本直接导入 cli_anything.safari.utils.safari_backend.call() 以避免每次调用重新生成子进程。
URL 校验：导航类工具（tool navigate、tool navigate-and-read、tool new-tab 以及 raw safari_navigate*）的 url 参数会经过 utils/security.py，拦截危险协议，包括 file、javascript、data、vbscript、about、chrome、safari、webkit、x-apple 及其他浏览器内部协议；可通过 CLI_ANYTHING_SAFARI_BLOCK_PRIVATE=1 选择屏蔽私有网络。
安全方面：tool evaluate 和 tool run-script 会在页面上下文执行任意 JavaScript，应像对待任何动态代码执行路径一样谨慎处理不可信输入；tool clipboard-read 与 tool clipboard-write 会触碰系统剪贴板，在用户活动会话中运行需谨慎。可通过 SAFARI_PROFILE 环境变量使用单独的 Safari 配置文件以隔离 Cookie、登录与历史。
常见错误：npx 未找到（需安装 Node.js 18+）、npm 上找不到 safari-mcp 包（检查网络）、非 macOS（该工具仅限 macOS）、AppleScript 被拒绝（需在 Safari 开发菜单启用「允许 Apple 事件中的 JavaScript」）、Blocked URL scheme（URL 校验按设计拒绝）。
其它说明
如果升级 safari-mcp，可用以下命令重新生成内置 schema： python scripts/extract_tools.py "$(npm root -g)/safari-mcp/index.js" cli_anything/safari/resources/tools.json 一致性测试 test_parity.py 固定了预期的工具数量，上游工具列表变化时需更新。
版本：1.0.0，对应 safari-mcp 2.7.8（84 个工具）。
完整文档见包内 cli_anything/safari/README.md，测试覆盖见 cli_anything/safari/tests/TEST.md，架构分析见 safari/agent-harness/SAFARI.md。