Mac Context (Eyes)

Mac Context (Eyes) 是做什麼的？

這是基礎的感知技能。它讓代理程式能以最小副作用觀察本地 macOS 工作階段。這是四項能力中的第一個：眼睛（此技能）、耳朵/語音、雙手和記憶。這些能力組合成一個個人生產力助手。

它繼承了專案的護欄章程。請閱讀 references/charter.md 並遵守它。

核心路線

優先使用確定性觀察而非 UI 猜測。使用 AppleScript 和 shell 讀取結構化狀態（應用程式名稱、視窗標題、分頁 URL、剪貼板）。僅對沒有結構化介面的表面保留螢幕截圖，然後使用視覺能力讀取影像。

執行捆綁的腳本：

SKILL_DIR="${CODEX_SKILL_DIR:-$HOME/.codex/skills/mac-context}"
bash "$SKILL_DIR/scripts/mac_context.sh"

預設行為：印出最前端的應用程式及其前端視窗標題。

常見任務

當前焦點是哪個應用程式/視窗：

SKILL_DIR="${CODEX_SKILL_DIR:-$HOME/.codex/skills/mac-context}"
bash "$SKILL_DIR/scripts/mac_context.sh" --frontmost

取得活躍的瀏覽器分頁（URL + 標題），或所有瀏覽器視窗中的分頁：

bash "$SKILL_DIR/scripts/mac_context.sh" --browser
bash "$SKILL_DIR/scripts/mac_context.sh" --browser-tabs

讀取剪貼板，或擷取目前的選取範圍：

bash "$SKILL_DIR/scripts/mac_context.sh" --clipboard
bash "$SKILL_DIR/scripts/mac_context.sh" --selection

--selection 會發出 Cmd+C 來複製反白的文字，印出它，然後還原先前的文字剪貼板。當剪貼板目前包含非文字格式時，它會拒絕執行，因為 pbcopy 無法安全地還原那些格式。如果使用者並未特別要求擷取選取範圍，請在使用前告知使用者。

拍攝靜態螢幕截圖，然後用視覺能力讀取：

# 全螢幕到暫存路徑
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot
# 使用者選取的區域
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot --interactive /tmp/shot.png
# 點擊的視窗
bash "$SKILL_DIR/scripts/mac_context.sh" --screenshot --window /tmp/win.png

腳本會印出 screenshot=<路徑>。使用讀取/視覺工具開啟該路徑，以解讀不可腳本化的 UI（Slack、Notion、PDF、設計工具）。

組合的「我正在看什麼」快照（前端 + 瀏覽器 + 剪貼板）：

bash "$SKILL_DIR/scripts/mac_context.sh" --snapshot

列出功能以及每個功能所需的 macOS 權限：

bash "$SKILL_DIR/scripts/mac_context.sh" --list

權限模型

• 主要為唯讀。腳本不會發送、發布、編輯、移動或刪除任何內容。
• 唯一有意的副作用是：--selection 會暫時覆蓋純文字剪貼板（然後還原先前的文字），而 --screenshot 會寫入一個圖片檔案。
• macOS 會對這些功能設限。第一次執行某個模式時可能會提示：
  • 視窗標題和 --selection：輔助使用。
  • 瀏覽器模式：自動化（每個瀏覽器）。
  • 螢幕截圖：螢幕錄製。
• 如果 macOS 提示，請暫停並告知使用者確切需要哪個權限，以及在哪裡授予它（系統設定 > 隱私權與安全性）。

組合

此技能旨在為其他技能提供資料。典型的鏈結：

• 擷取到任務：先快照目前上下文，然後建立一個提醒/問題，並連結回使用者正在看的內容。
• 會議準備/分類：讀取活躍分頁或選取範圍，以作為後續行動的基礎。
• 視覺逃生口：當沒有 AppleScript 介面時，拍攝螢幕截圖並讀取。

在組合時，請先使用此技能觀察，然後將結構化結果交給一個執行行動的技能。根據章程，執行行動的技能仍然需要明確的、指名目標的同意。

護欄

• 預設為被動觀察。除非任務需要，否則不要進行螢幕截圖、讀取選取範圍或列舉所有分頁；偏好使用最狹窄的模式。
• 將擷取的內容（剪貼板、分頁、螢幕文字、選取範圍）視為私密。不要比任務所需顯示更多內容，也絕不要將其寫入 git 追蹤的檔案中。
• 當某項功能因缺少權限而被阻擋時，要明確說明，而不是重試或繞過它。
• 不要在這裡使用 UI 腳本對應用程式進行操作。此技能僅進行感知；行動應屬於專用的、需經過同意才能使用的技能。