Safari Control

## Changelog / 更新日志 ### Initial release / 首次发布 `safari-control` is now available on Clawhub. `safari-control` 现已发布到 Clawhub。 This first release brings full real-session Safari automation to macOS, built for workflows where the user's actual Safari state matters: logged-in sessions, cookies, open tabs, native Safari chrome, and live page content inside the real browser. 这是首个版本，提供面向 macOS 的真实 Safari 会话自动化能力，适用于用户真实 Safari 状态很重要的场景，例如登录态、Cookie、已打开标签页、Safari 原生界面元素，以及浏览器中的实时页面内容。 ### What’s included / 包含功能 - Real Safari session control 真实 Safari 会话控制 - Read the current tab, inspect windows and tabs, switch tabs, duplicate tabs, open new tabs or windows, close tabs or windows, and save or restore Safari session layouts 读取当前标签页、查看窗口和标签页、切换标签页、复制标签页、新建标签页或窗口、关闭标签页或窗口，以及保存和恢复 Safari 会话布局 - Native Safari UI automation Safari 原生界面自动化 - List Safari menu bar items and nested menu items 列出 Safari 菜单栏项目及其嵌套菜单项 - Click Safari menu commands 点击 Safari 菜单命令 - Inspect native Safari controls such as the smart search field, toolbar buttons, tab controls, and popup controls 检查 Safari 原生控件，例如智能搜索栏、工具栏按钮、标签页控件和弹出式控件 - Focus controls, press them, set values, open native menus, and invoke specific AX actions such as `AXConfirm` 聚焦控件、点击控件、设置值、打开原生菜单，并调用特定的辅助功能动作，例如 `AXConfirm` - Live page inspection and DOM automation 实时页面检查与 DOM 自动化 - Run JavaScript in Safari tabs 在 Safari 标签页中运行 JavaScript - Evaluate expressions as JSON-friendly output 将表达式求值为适合 JSON 的输出 - Read page text, HTML, links, tables, interactive elements, and form state 读取页面文本、HTML、链接、表格、可交互元素以及表单状态 - Query selectors, inspect elements, find visible text, and check element existence or counts 查询选择器、检查元素、查找可见文本，并检查元素是否存在及其数量 - Perform DOM actions including click, fill, focus, hover, scroll, drag, select, check, uncheck, upload, submit, keypress, shortcut dispatch, and custom event dispatch 执行 DOM 操作，包括点击、填写、聚焦、悬停、滚动、拖拽、选择、勾选、取消勾选、上传、提交、按键、快捷键派发以及自定义事件派发 - Real Safari wait and export workflows 真实 Safari 等待与导出工作流 - Wait for selectors, text, titles, URLs, JavaScript conditions, DOM mutations, element counts, and downloads 等待选择器、文本、标题、URL、JavaScript 条件、DOM 变化、元素数量以及下载完成 - Save HTML, extracted text, links, tables, snapshots, screenshots, and complete page bundles with manifests 保存 HTML、提取文本、链接、表格、快照、截图，以及带 manifest 的完整页面打包结果 - Packaging and release support 打包与发布支持 - Build standalone binaries 构建独立二进制 - Create release folders and zip archives 创建发布目录和 zip 压缩包 - Generate build and release manifests with checksums, git metadata, and environment metadata 生成带校验和、git 元数据和环境元数据的构建与发布 manifest ### v1 improvements included in this release / 本次 v1 发布包含的改进 - Structured JSON-based Safari session inspection for current tab, windows, and tabs 基于结构化 JSON 的 Safari 会话检查，覆盖当前标签页、窗口和标签页列表 - Rich native control metadata including `pressable`, `focusable`, `settable`, and `menuable` 更丰富的原生控件元数据，包括 `pressable`、`focusable`、`settable` 和 `menuable` - Configurable smart search confirmation modes with `ax`, `enter`, and `both` 可配置的智能搜索栏确认模式，支持 `ax`、`enter` 和 `both` - Post-action tab-state waiting for native URL open and native search flows 在原生打开 URL 和原生搜索流程中，支持动作完成后的标签页状态等待 - Agent-friendly workflow documentation organized by session, DOM, native UI, and export layers 面向 Agent 的工作流文档，按会话、DOM、原生 UI 和导出层进行组织 - Public-facing docs updated to use relative paths and English UI examples 对外文档已更新为相对路径，并使用英文界面示例 ### Important note about Safari settings / 关于 Safari 设置的重要说明 To unlock more advanced functionality, users may need to enable Safari capabilities such as: 要启用更高级的功能，用户可能需要在 Safari 中开启以下能力： - Allow Automation 允许自动化 - Allow JavaScript in the Smart Search field 允许在智能搜索栏中使用 JavaScript - Allow JavaScript from Apple Events 允许 Apple 事件中的 JavaScript These settings make more of `safari-control` available, especially for native Safari automation and script-driven workflows. They also increase risk, because automation and scripting gain more power over the user’s real Safari session. Users should enable them intentionally and only when they understand that tradeoff. 这些设置会让 `safari-control` 的更多功能可用，尤其是 Safari 原生自动化和脚本驱动工作流；但与此同时也会带来更高风险，因为自动化和脚本会获得对用户真实 Safari 会话更强的控制能力。用户应在理解这一权衡的前提下，主动决定是否开启。

## Changelog / 更新日志 ### Initial release / 首次发布 `safari-control` is now available on Clawhub. `safari-control` 现已发布到 Clawhub。 This first release brings full real-session Safari automation to macOS, built for workflows where the user's actual Safari state matters: logged-in sessions, cookies, open tabs, native Safari chrome, and live page content inside the real browser. 这是首个版本，提供面向 macOS 的真实 Safari 会话自动化能力，适用于用户真实 Safari 状态很重要的场景，例如登录态、Cookie、已打开标签页、Safari 原生界面元素，以及浏览器中的实时页面内容。 ### What’s included / 包含功能 - Real Safari session control 真实 Safari 会话控制 - Read the current tab, inspect windows and tabs, switch tabs, duplicate tabs, open new tabs or windows, close tabs or windows, and save or restore Safari session layouts 读取当前标签页、查看窗口和标签页、切换标签页、复制标签页、新建标签页或窗口、关闭标签页或窗口，以及保存和恢复 Safari 会话布局 - Native Safari UI automation Safari 原生界面自动化 - List Safari menu bar items and nested menu items 列出 Safari 菜单栏项目及其嵌套菜单项 - Click Safari menu commands 点击 Safari 菜单命令 - Inspect native Safari controls such as the smart search field, toolbar buttons, tab controls, and popup controls 检查 Safari 原生控件，例如智能搜索栏、工具栏按钮、标签页控件和弹出式控件 - Focus controls, press them, set values, open native menus, and invoke specific AX actions such as `AXConfirm` 聚焦控件、点击控件、设置值、打开原生菜单，并调用特定的辅助功能动作，例如 `AXConfirm` - Live page inspection and DOM automation 实时页面检查与 DOM 自动化 - Run JavaScript in Safari tabs 在 Safari 标签页中运行 JavaScript - Evaluate expressions as JSON-friendly output 将表达式求值为适合 JSON 的输出 - Read page text, HTML, links, tables, interactive elements, and form state 读取页面文本、HTML、链接、表格、可交互元素以及表单状态 - Query selectors, inspect elements, find visible text, and check element existence or counts 查询选择器、检查元素、查找可见文本，并检查元素是否存在及其数量 - Perform DOM actions including click, fill, focus, hover, scroll, drag, select, check, uncheck, upload, submit, keypress, shortcut dispatch, and custom event dispatch 执行 DOM 操作，包括点击、填写、聚焦、悬停、滚动、拖拽、选择、勾选、取消勾选、上传、提交、按键、快捷键派发以及自定义事件派发 - Real Safari wait and export workflows 真实 Safari 等待与导出工作流 - Wait for selectors, text, titles, URLs, JavaScript conditions, DOM mutations, element counts, and downloads 等待选择器、文本、标题、URL、JavaScript 条件、DOM 变化、元素数量以及下载完成 - Save HTML, extracted text, links, tables, snapshots, screenshots, and complete page bundles with manifests 保存 HTML、提取文本、链接、表格、快照、截图，以及带 manifest 的完整页面打包结果 - Packaging and release support 打包与发布支持 - Build standalone binaries 构建独立二进制 - Create release folders and zip archives 创建发布目录和 zip 压缩包 - Generate build and release manifests with checksums, git metadata, and environment metadata 生成带校验和、git 元数据和环境元数据的构建与发布 manifest ### v1 improvements included in this release / 本次 v1 发布包含的改进 - Structured JSON-based Safari session inspection for current tab, windows, and tabs 基于结构化 JSON 的 Safari 会话检查，覆盖当前标签页、窗口和标签页列表 - Rich native control metadata including `pressable`, `focusable`, `settable`, and `menuable` 更丰富的原生控件元数据，包括 `pressable`、`focusable`、`settable` 和 `menuable` - Configurable smart search confirmation modes with `ax`, `enter`, and `both` 可配置的智能搜索栏确认模式，支持 `ax`、`enter` 和 `both` - Post-action tab-state waiting for native URL open and native search flows 在原生打开 URL 和原生搜索流程中，支持动作完成后的标签页状态等待 - Agent-friendly workflow documentation organized by session, DOM, native UI, and export layers 面向 Agent 的工作流文档，按会话、DOM、原生 UI 和导出层进行组织 - Public-facing docs updated to use relative paths and English UI examples 对外文档已更新为相对路径，并使用英文界面示例 ### Important note about Safari settings / 关于 Safari 设置的重要说明 To unlock more advanced functionality, users may need to enable Safari capabilities such as: 要启用更高级的功能，用户可能需要在 Safari 中开启以下能力： - Allow Automation 允许自动化 - Allow JavaScript in the Smart Search field 允许在智能搜索栏中使用 JavaScript - Allow JavaScript from Apple Events 允许 Apple 事件中的 JavaScript These settings make more of `safari-control` available, especially for native Safari automation and script-driven workflows. They also increase risk, because automation and scripting gain more power over the user’s real Safari session. Users should enable them intentionally and only when they understand that tradeoff. 这些设置会让 `safari-control` 的更多功能可用，尤其是 Safari 原生自动化和脚本驱动工作流；但与此同时也会带来更高风险，因为自动化和脚本会获得对用户真实 Safari 会话更强的控制能力。用户应在理解这一权衡的前提下，主动决定是否开启。