sidmohan0/skills

Mac Context（视觉）

这是基础的感知技能。它让代理能够以最小副作用的方式观察本地 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=<path>。使用读取/视觉工具打开该路径，以解析不可脚本化的 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 脚本对应用进行操作。此技能仅感知；操作属于专门的、需要同意的技能。