altic-studio

Altic Studio

altic-studio 提供两种自动化模式：

1. AppleScript 模式，用于 macOS 应用和系统操作
2. MCP CDP 模式，用于控制 Google Chrome 浏览器
3. MCP 文件模式，用于安全地操作 Finder 和文件系统
4. MCP 剪贴板模式，用于文本、文件和图像的粘贴板操作
5. MCP 窗口／工作区模式，用于排列 macOS 应用和窗口

它还包含用于 macOS 活动显示屏截图、剪贴板文件／图像操作以及窗口／工作区管理的 Swift 实用脚本。

模式 A：AppleScript（macOS 应用）

• 始终通过 Bash 使用 osascript 执行 AppleScript。
• 始终从工作区根目录运行。
• 为脚本路径和参数加引号。
• 优先直接调用脚本；除非明确要求，否则不要通过 Python 包装器运行。

命令模板：

osascript "skills/altic-studio/scripts/<script>.applescript" [arg1] [arg2] ...

AppleScript 功能

Altic 的完整自动化功能由 skills/altic-studio/scripts 下的脚本提供：

• open-application.applescript - 参数：<app_name>
• send-message.applescript - 参数：<phone_or_handle> <message>
• messages-manager.applescript - 参数：<list_chats|send_file> ...
• read-recent-messages.applescript - 参数：<phone_or_handle> <count>
• fetch-all-contacts.applescript - 参数：无
• contacts-manager.applescript - 参数：<get|create|update> ...
• set-reminder.applescript - 参数：<text> <YYYY-MM-DD HH:MM> [list_name]
• reminders-manager.applescript - 参数：<list_lists|list|search|complete|delete|reschedule|update|show> ...
• create-note.applescript - 参数：<title> <body> [folder]
• search-for-note.applescript - 参数：<query> [max_results]
• notes-manager.applescript - 参数：<list_folders|list|get|append|update|delete|move> ...
• create-calendar-event.applescript - 参数：<title> <YYYY-MM-DD HH:MM> <duration_minutes> [calendar]
• list-all-calendar-events-for-day.applescript - 参数：<YYYY-MM-DD>
• calendar-manager.applescript - 参数：<list_calendars|list|search|update|delete|availability|create_recurring> ...
• open-safari-tab.applescript - 参数：[url]
• close-safari-tab.applescript - 参数：[tab_index|-1]
• get-safari-tabs.applescript - 参数：无
• switch-safari-tab.applescript - 参数：<tab_index>
• run-safari-javascript.applescript - 参数：<javascript_code>
• navigate-safari.applescript - 参数：<url>
• reload-safari-page.applescript - 参数：无
• safari-go-back.applescript - 参数：无
• safari-go-forward.applescript - 参数：无
• open-safari-window.applescript - 参数：[url]
• close-safari-window.applescript - 参数：无
• get-safari-page-info.applescript - 参数：无
• decrease-brightness.applescript - 参数：[amount_0_to_1]
• increase-brightness.applescript - 参数：[amount_0_to_1]
• turn-up-volume.applescript - 参数：[amount_0_to_100]
• turn-down-volume.applescript - 参数：[amount_0_to_100]
• capture-screenshot.applescript - 参数：[output_path] [full|interactive|window]
• capture-active-screen.swift - 参数：<output_path>（截取包含最前端应用的完整显示屏）
• clipboard.swift - 子命令：get-files、set-files <paths...>、save-image <output_path>、set-image <image_path>
• window-manager.swift - 子命令：get_frontmost_app、list_windows、focus_window、move_window、resize_window、center_window、tile_windows、minimize、hide_app、quit_app

Swift 命令模板（用于活动显示屏截图）：

swift "skills/altic-studio/scripts/capture-active-screen.swift" "/tmp/active-screen.png"

Swift 命令模板（用于窗口管理）：

swift "skills/altic-studio/scripts/window-manager.swift" "list_windows" '{"include_minimized":false}'

模式 B：提醒事项、日历和备忘录（MCP）

在结构化的“信息”“通讯录”“提醒事项”“日历”和“备忘录”工作流中使用 MCP 工具。这些较新的工具会返回包含 ok、action、data 和 error 的 JSON 信封。 删除工具默认使用 dry_run=true；只有在用户明确确认后才执行删除。

可用的信息工具：

• list_chats - 参数：[limit]
• send_file_message - 参数：<recipient> <path> [message] [recipient_type]

可用的通讯录工具：

• get_contact - 参数：<identifier>
• create_contact - 参数：<first_name> <last_name> [organization] [phone] [email] [note]
• update_contact - 参数：<identifier> [first_name] [last_name] [organization] [phone] [email] [note]

可用的提醒事项工具：

• list_reminder_lists - 参数：无
• list_reminders - 参数：[list_name] [include_completed]
• search_reminders - 参数：<query> [list_name] [include_completed]
• complete_reminder - 参数：<identifier> [list_name]
• delete_reminder - 参数：<identifier> [list_name] [dry_run]
• reschedule_reminder - 参数：<identifier> <YYYY-MM-DD HH:MM> [list_name]
• update_reminder - 参数：<identifier> [list_name] [name] [body] [datetime] [completed] [priority] [flagged]
• show_reminder - 参数：<identifier> [list_name]

可用的日历工具：

• list_calendars - 参数：无
• list_calendar_events - 参数：<start_date> <end_date> [calendar_name]
• search_calendar_events - 参数：<query> [start_date] [end_date] [calendar_name]
• update_calendar_event - 参数：<identifier> [title] [start_datetime] [duration_minutes] [calendar_name] [location] [notes_text]
• delete_calendar_event - 参数：<identifier> [start_date] [end_date] [calendar_name] [dry_run]
• check_calendar_availability - 参数：<start_datetime> <duration_minutes> [calendar_name]
• create_recurring_event - 参数：<title> <start_datetime> <duration_minutes> <frequency> [interval] [count] [until_date] [calendar_name] [location] [notes_text]

可用的备忘录工具：

• list_note_folders - 参数：无
• list_notes - 参数：[folder] [max_results]
• get_note - 参数：<identifier>
• append_to_note - 参数：<identifier> <body>
• update_note - 参数：<identifier> <body>
• delete_note - 参数：<identifier> [dry_run]
• move_note - 参数：<identifier> <folder>

工作流规则：

• 当目标不明确时，先调用 list/search 工具，再进行修改。
• 将 identifier 视为应用提供的 id 或精确匹配的标题/名称。
• 如果修改操作返回多个匹配项，请询问用户以消除歧义。
• 在用户明确确认前，破坏性操作必须保持在 dry-run 模式。
• 调用工具前验证日期：日期使用 YYYY-MM-DD，日期时间使用 YYYY-MM-DD HH:MM。
• 对于 send_file_message，继续现有群组对话时，在调用 list_chats 后优先使用 recipient_type="chat"；对于直接电话号码或电子邮件地址，使用 recipient_type="handle"。

模式 C：Chrome 浏览器控制（MCP CDP）

使用 MCP 工具执行确定性的 Chrome 自动化：

• chrome_open_session
• chrome_navigate
• chrome_wait_for
• chrome_click
• chrome_type
• chrome_extract
• chrome_screenshot
• chrome_close_session
• chrome_list_sessions
• capture_active_screen

执行流程：

1. 打开 Chrome 会话。
2. 导航并等待选择器稳定。
3. 使用点击和输入操作进行交互。
4. 使用提取操作验证状态。
5. 在检查点或失败时截取屏幕截图。
6. 关闭会话。

模式 D：文件查找与文件操作（MCP）

当用户要求查找、检查、复制、移动、重命名、显示或移入废纸篓中的文件时，请使用 MCP 文件工具，而不是 shell 命令。这些工具在查找和操作成功时会返回 JSON，失败时会返回 Error: ... 字符串。

可用工具：

• find_files - 参数：<query> [root] [max_results] [include_hidden] [kind]
• list_directory - 参数：<path> [include_hidden] [max_results]
• get_file_info - 参数：<path>
• copy_file - 参数：<source> <destination> [overwrite] [dry_run]
• copy_directory - 参数：<source> <destination> [overwrite] [dry_run]
• move_file - 参数：<source> <destination> [overwrite] [dry_run]
• rename_file - 参数：<path> <new_name> [overwrite] [dry_run]
• trash_file - 参数：<path> [dry_run]
• reveal_in_finder - 参数：<path>
• get_finder_selection - 参数：无

文件工作流规则：

• 如果用户提及已选中的文件、当前 Finder 窗口或“这个文件”，请先调用 get_finder_selection。
• 对于含义不明确的文件名，请调用 find_files，然后调用 get_file_info；如果仍有多个可能匹配项，请询问用户以消除歧义。
• 如果目标或目的地含义不明确，请优先在调用 copy_file、copy_directory、move_file、rename_file 或 trash_file 前使用 dry_run=true。
• 除非用户明确要求替换，否则不要覆盖；默认使用 overwrite=false。
• 使用 trash_file，不要永久删除文件。
• 如果用户希望在 Finder 中查看文件操作结果，请在操作后调用 reveal_in_finder。

模式 E：剪贴板操作（MCP）

当用户要求检查、复制、粘贴、清除或保存剪贴板内容时，请使用 MCP 剪贴板工具，而不是 shell 命令。这些工具会针对文本和文件操作返回 JSON，失败时返回 Error: ... 字符串；保存剪贴板图像时会返回图像内容。

可用工具：

• get_clipboard_text - 参数：[max_chars]
• set_clipboard_text - 参数：<text>
• clear_clipboard - 参数：无
• get_clipboard_files - 参数：无
• set_clipboard_files - 参数：<paths>
• save_clipboard_image - 参数：[output_path]
• set_clipboard_image - 参数：<path>

剪贴板工作流规则：

• 除非用户明确要求复制、设置、清除或替换剪贴板，否则在覆盖剪贴板内容前请先征求同意。
• 如果用户询问当前复制的文本，请先调用 get_clipboard_text。
• 如果用户说他们在 Finder 中复制了文件，或想把复制的文件粘贴到其他位置，请调用 get_clipboard_files。
• 如果用户希望检查、存储或转换当前剪贴板中的图像，请调用 save_clipboard_image。
• set_clipboard_files 只能使用现有路径；更改剪贴板前，请使用 find_files 消除含义不明确的文件名。
• set_clipboard_image 只能用于现有图像文件。

模式 F：窗口与工作区操作（MCP）

当用户要求整理工作区、聚焦应用或窗口、并排平铺应用、调整窗口大小、最小化窗口、隐藏应用、退出应用或检查最前方的应用时，请使用 MCP 窗口工具。操作成功时，这些工具会返回 JSON；失败时会返回 Error: ... 字符串。

可用工具：

• get_frontmost_app - 参数：无
• list_windows - 参数：[app_name] [include_minimized]
• focus_window - 参数：[app_name] [window_id] [window_index]
• move_window - 参数：<x> <y> [app_name] [window_id] [window_index] [display_index]
• resize_window - 参数：<width> <height> [app_name] [window_id] [window_index] [display_index]
• center_window - 参数：[app_name] [window_id] [window_index] [display_index] [width] [height]
• tile_windows - 参数：[layout=columns|rows|grid] [app_names] [display_index] [padding]
• minimize - 参数：[app_name] [window_id] [window_index]
• hide_app - 参数：<app_name>
• quit_app - 参数：<app_name>

窗口工作流规则：

• 如果目标应用有多个窗口或目标不明确，在移动、调整大小、最小化或聚焦之前，请先调用 list_windows。
• 面向用户的工作流优先使用 app_name；在调用 list_windows 后进行精确的后续操作时使用 window_id。
• 在特定显示器上排列窗口时使用 display_index；否则工具会选择包含目标窗口的显示器。
• 准备多应用任务时，使用带有明确 app_names 的 tile_windows。
• 除非用户明确要求关闭或退出应用，否则不要调用 quit_app。
• 如果窗口更改操作因辅助功能错误而失败，请告知用户为运行 MCP 服务的宿主应用授予辅助功能权限。

操作规则

• 运行提醒事项或日历脚本前，先验证日期／时间格式。
• 如果联系人查询返回多个选项，请先询问用户以消除歧义，再发送内容。
• 如果脚本输出表明存在权限问题，请准确说明需要启用哪些权限。
• 优先使用明确的 CSS 选择器，并在动态页面上点击或输入前调用 chrome_wait_for。
• 在 Chrome 中执行更改操作后，使用 chrome_extract 验证预期的页面状态。
• 对文件进行更改后，如果用户需要确认，请使用 get_file_info 或 list_directory 验证目标。
• 对剪贴板进行更改后，如果用户需要确认，请使用 get_clipboard_text、get_clipboard_files 或 save_clipboard_image 进行验证。
• 对窗口进行更改后，如果用户需要确认，请使用 list_windows 进行验证。

权限检查清单

• 联系人访问权限
• 日历访问权限
• 提醒事项访问权限
• 控制应用的自动化权限
• 系统控制和窗口管理的辅助功能权限
• 截屏和改进窗口发现功能的屏幕录制权限
• Safari 设置：允许通过 Apple Events 使用 JavaScript
• 为 CDP 工具安装 Google Chrome
• 读取 Messages 数据库的完整磁盘访问权限
• 显示、移至废纸篓或读取所选内容时，授予 Finder 自动化权限